chore(docs): refactor (#23)

README.md

@@ -1,53 +1,24 @@
 # vault-plugin-secrets-vercel
 
 Vault Secrets Plugin for Vercel allows you to dynamically generate Vercel API tokens through Vault.
-Useful for CI/CD as you can generate short-lived deployment tokens and let them revoke once you are done.
+Useful for CI/CD as you can generate short-lived deployment tokens through Vault and manage developer access that way.
+Vault revokes the tokens automatically upon expiration, which is user-configurable.
 
-Currently supports personal Vercel accounts. Additional features, such as token-specific fine-grained permissions
-are not supported by the plugin - simply because I have no Pro/Enterprise plan to develop it against with.
+## Scope
 
-## Run it locally
+Currently this project is scoped for personal (or "Hobby") Vercel accounts.
 
-Run a local development setup with the following commands:
+Any Pro/Enterprise plan features, such as these, are scoped out:
 
-```
-$ make build
-$ make start
-$ make enable
-```
+- Team-specific tokens
+- Token-specific scope or permissions
 
-This sets up a local Vault installation in development mode and enables the plugin.
+Access to Pro/Enterprise plan or contributions are welcome, of course!
 
-Go to the [Vercel tokens page](https://vercel.com/account/tokens) and generate an admin token. Then configure the plugin:
+## Getting started
 
-```
-$ vault write vercel-secrets/config api_key=<your-api-key-here>
-```
+Get started by following the documentation:
 
-You can also define a maximum TTL for the secrets by defining an additional parameter `max_ttl=<seconds>`. By default it is 10 minutes. TTLs can be defined on a per-token basis, but they will need to be lower than or equal to the max.
-
-## Generate tokens
-
-Generate a new Vault plugin managed Vercel token:
-
-```
-$ vault read vercel-secrets/token
-Key                Value
----                -----
-lease_id           vercel-secrets/token/<lease-id>
-lease_duration     10m
-lease_renewable    false
-bearer_token       xyzabbacdc
-token_id           bababababa
-```
-
-You can set a custom lease duration with the parameter `ttl=<seconds>`.
-
-Vault will automatically revoke & delete the API key after the lease duration.
-The generated token also has an expiration time equal to the lease duration on Vercel side.
-
-## Running it on production
-
-Please don't - yet!
-
-If you do, please refer to the documentation on deployment model for plugins [from the official HashiCorp Vault tutorials](https://developer.hashicorp.com/vault/tutorials/app-integration/plugin-backends#setup-vault).
+- [Running the plugin locally](./docs/development.md)
+- [Configuring and generating tokens with the plugin](./docs/configuration.md)
+- [Installing the plugin to an existing Vault installation](./docs/install.md)

docs/configuration.md

@@ -0,0 +1,55 @@
+# Configuring the plugin
+
+Once you have the plugin enabled, you'll have to configure it. Ensure you have Vault CLI installed and that you have proper access to the Vault instance.
+
+Go to the [Vercel tokens page](https://vercel.com/account/tokens) and generate a new token. This is the token the plugin will use to dynamically create other (short-lived) tokens. Set the key as follows:
+
+```
+$ vault write vercel-secrets/config api_key=<your-api-key-here>
+```
+
+Optional parameters are:
+
+- `max_ttl=<seconds>`: Maximum TTL for the tokens generated by the plugin. TTLs can be defined on a per-token basis, but they will need to be lower than or equal to the maximum. Default is 10 minutes.
+
+## Generate tokens
+
+Now you can start generating ephemeral tokens. Run the following command to generate a new Vault plugin managed Vercel token:
+
+```
+$ vault read vercel-secrets/token
+Key                Value
+---                -----
+lease_id           vercel-secrets/token/<lease-id>
+lease_duration     10m
+lease_renewable    false
+bearer_token       xyzabbacdc
+token_id           bababababa
+```
+
+Optional parameters are:
+
+- `ttl=<seconds>`: Custom lease duration. Has to be lower than or equal to `max_ttl` configured to the plugin backend.
+
+## Revoke tokens
+
+Vault will *automatically* revoke & delete the API key after the lease duration.
+
+The token also has an expiration time equal to the lease duration on Vercel side. Should anything happen to Vault, the token will expire as configured. However, it will remain on Vercel and has to be manually cleaned up.
+
+## Information about the plugin
+
+You can print informational details about the plugin by querying the info endpoint:
+
+```
+$ vault read vercel-secrets/info
+Key                    Value
+---                    -----
+build_commit           d912476
+build_commit_branch    docs/verify-signed-build
+build_commit_date      d912476
+build_date             Fri Jul 07 22:07:50 EEST 2023
+build_dirty            true
+build_tag              v0.2.3
+build_version          v0.2.3
+```

docs/development.md

@@ -0,0 +1,19 @@
+# Development setup
+
+**NOTE: This setup is purely for local development, demonstration or testing.**
+
+## Run it locally
+
+Run a local development setup with the following commands:
+
+```
+$ make build
+$ make start
+$ make enable
+```
+
+This creates a local Vault installation in development mode and enables the plugin.
+
+## Configuring the plugin
+
+Follow [the configuration guide](configuration.md).

docs/install.md

@@ -0,0 +1,73 @@
+# Installing vault-plugin-secrets-vercel
+
+**NOTE: This project is under active development and has not been production battle-tested yet - treat it as such and contributions welcome.**
+
+Install the plugin with the following instructions to an existing Vault installation. For a more detailed explanation, please refer to [the official HashiCorp Vault documentation on plugin backends](https://developer.hashicorp.com/vault/tutorials/app-integration/plugin-backends#setup-vault).
+
+For local development or testing, please refer to [the development setup guide](development.md).
+
+## Downloading the plugin
+
+Grab the latest release from [the releases page](https://github.com/thevilledev/vault-plugin-secrets-vercel/releases) that matches
+your operating system and architecture.
+
+### Verifying the plugin build
+
+All builds have a matching SHA256 checksum. These are signed and the matching public key can be found from [signing-key-public.asc](/signing-key-public.asc).
+
+You can validate these builds by doing the following:
+
+- Download the release files `vault-plugin-secrets-vercel_<version>_SHA256SUMS` and `vault-plugin-secrets-vercel_<version>_SHA256SUMS.sig` to the same directory.
+- Download the signing key [signing-key-public.asc](/signing-key-public.asc).
+- Import the signing key with `gpg --import signing-key-public.asc`
+- Verify checksums with `gpg --verify vault-plugin-secrets-vercel_<version>_SHA256SUMS.sig`
+
+You have now verified that the checksums are signed by the project keys.
+
+Next, generate a SHA256 checksum for the build you downloaded, for example:
+
+```
+$ sha256sum vault-plugin-secrets-vercel_v0.2.3_Darwin_arm64.tar.gz
+cdadd3ec3115995625541dd4222ae4986bfdc2531b2f442ead3f8d385f87df88  vault-plugin-secrets-vercel_v0.2.3_Darwin_arm64.tar.gz
+```
+
+And finally, check that it matches the SHA256SUMS file:
+
+```
+$ grep 'vault-plugin-secrets-vercel_v0.2.3_Darwin_arm64.tar.gz' vault-plugin-secrets-vercel_v0.2.3_SHA256SUMS
+cdadd3ec3115995625541dd4222ae4986bfdc2531b2f442ead3f8d385f87df88  vault-plugin-secrets-vercel_v0.2.3_Darwin_arm64.tar.gz
+```
+
+All good!
+
+## Registering the plugin
+
+Un-tar the installation package and move the plugin binary to the `plugin_directory` of your Vault installation. For example:
+
+```
+$ mv vault-plugin-secrets-vercel /etc/vault/vault_plugins/
+```
+
+Calculate the SHA256 checksum of the plugin binary.
+
+```
+$ SHA256=$(sha256sum /etc/vault/vault_plugins/vault-plugin-secrets-vercel | cut -d ' ' -f1)
+```
+
+And register the plugin into the Vault plugin catalog. This assumes you have Vault CLI access properly configured.
+
+```
+$ vault plugin register -sha256=$SHA256 secret vault-plugin-secrets-vercel
+```
+
+## Enabling the plugin
+
+To enable the plugin, run:
+
+```
+$ vault secrets enable -path=vercel-secrets vault-plugin-secrets-vercel
+```
+
+## Configuring the plugin
+
+Follow [the configuration guide](configuration.md).

signing-key-public.asc

@@ -0,0 +1,14 @@
+-----BEGIN PGP PUBLIC KEY BLOCK-----
+
+mDMEZKhDlBYJKwYBBAHaRw8BAQdAJR7nRRjl/q5kyrZvbzLW52+ykBrYQl/FgqwI
+Cnhzb1S0NVZhdWx0IFBsdWdpbiBTZWNyZXRzIFZlcmNlbCA8dmlsbGUrdnBzdkB2
+ZXNpbGVodG8uZmk+iJMEExYKADsWIQRVWaxdrDVOp0IMNgAw3ij+yy/4VwUCZKhD
+lAIbAwULCQgHAgIiAgYVCgkICwIEFgIDAQIeBwIXgAAKCRAw3ij+yy/4VxOUAQDC
+RGP483q/guX9Qh0xom5QKnbTgZPwq2CNKiEGg1f1mgD+Mer5CPx4IIkjLW4+gJby
+P+NlTt5/wZSQV/hQYKIuKw24OARkqEOUEgorBgEEAZdVAQUBAQdAH6ATUqlwhBTW
+S7VfZfkxm+mciqf5GayM7K2+4PTKIxUDAQgHiHgEGBYKACAWIQRVWaxdrDVOp0IM
+NgAw3ij+yy/4VwUCZKhDlAIbDAAKCRAw3ij+yy/4VxEdAQD/aNq7QKsGgHB3K8R1
+jI/n7Iz2ZPSi1nGORj5Nj973MQD/bUu5jZhgbwFBX9HhKMNmu6Ga6nSYBy9LKRTl
+fEZ7jwM=
+=/Uh6
+-----END PGP PUBLIC KEY BLOCK-----