DMNO Encrypted Vaults
Install
Install the package:
npm add @dmno/encrypted-vault-plugin
pnpm add @dmno/encrypted-vault-plugin
yarn add @dmno/encrypted-vault-plugin
Initialize the plugin
Initialize the plugin in the root, or service if not shared. Note the vault/prod
alias, which we can refer to in other services or in the CLI. This is useful if you have multiple vaults.
Also, note the configPath
function. This is a helper function that will look up the value of the key that contains the key used to encrypt/decrypt the vault. This is useful for keeping the key out of the codebase. It will need to live in your .env.local
file, or in an environment variable.
import { defineDmnoService, configPath } from 'dmno';import { EncryptedVaultDmnoPlugin, EncryptedVaultTypes } from '@dmno/encrypted-vault-plugin';
const MyProdVault = new EncryptedVaultDmnoPlugin('vault', { key: configPath('DMNO_VAULT_KEY'),});
export default defineDmnoService({ schema: { DMNO_VAULT_KEY: { extends: EncryptedVaultTypes.encryptionKey, // NOTE - the type itself is already marked as secret }, },});
If your plugin was initiatized in root and you need to use in a child service, inject the already configured plugin:
import { EncryptedVaultDmnoPlugin } from '@dmno/encrypted-vault-plugin';
const MyVault = EncryptedVaultDmnoPlugin.injectInstance('vault/prod'); // same "instance name" it was created with
Initialize the vault and key
npm exec -- dmno plugin -p vault -- setup
pnpm exec dmno plugin -p vault -- setup
yarn exec -- dmno plugin -p vault -- setup
This will:
- detect if the vault is configured but has no key value
- detect if vault file is empty/exists
- create new a key if needed
Add vault items to your schema
{ // simple case example SUPER_SECRET_ITEM: { value: MyProdVault.item(), }, ITEM_WITH_PROD_ONLY_SECRET: { value: toggleByNodeEnv({ _default: 'not-a-secret', staging: NonProdVault.item(), // reference to another vault production: MyProdVault.item(), }) },}
Fill the vault with your secrets
Add encrypted values to the vault:
npm exec -- dmno plugin -p vault -- add
pnpm exec dmno plugin -p vault -- add
yarn exec -- dmno plugin -p vault -- add
Rotate the vault key
npm exec -- dmno plugin -p vault -- rotate-key
pnpm exec dmno plugin -p vault -- rotate-key
yarn exec -- dmno plugin -p vault -- rotate-key
This will:
- generate a new key, and share it, similar to the initial setup
- re-encrypts all the values in the vault with the new key
Accessing an existing vault
If you’re joining a project that already has a vault set up, you’ll will need to get the key from a coworker.
Plugin CLI reference
Reference
Description: Runs CLI commands related to a specific plugin instance
Options
-s, --service [service]
which service to load
-p, --plugin <plugin>
which plugin instance to interact with
Example(s)
# set up a new encrypted vaultdmno plugin -p vault -- setup
# Update or insert an item to te vaultdmno plugin -p vault -- upsert
# add an item to the vaultdmno plugin -p vault -- add
# update an item in the vaultdmno plugin -p vault -- update
# delete an item from the vaultdmno plugin -p vault -- delete
# delete an item from the vaultdmno plugin -p vault -- delete
![a CLI showing the dmno plugin command](/_astro/plugin.D-so-2-A_2aC12N.webp)