Operator vault
Operator vault
The secrets that run an app live in files: .env on the laptop, the
production env on the server. Lose the laptop or the server and they are
gone, and some cannot be made again: every signed-in session and every
value encrypted with BETTER_AUTH_SECRET depends on that one string.
The vault is an encrypted copy of those files, committed to the repo. One key opens it, and that key is the only thing kept outside.
It came from RunMist, which has run it since 2026-11-13.
What it is
vault/.env.operator: every secret file, encrypted. Committed..vault.keys: the key that opens it. Gitignored. Keep it in a password manager; without it the vault is noise.scripts/security/vault/manifest.ts: the one list of files in the vault.scripts/security/vault.sh: the commands, also asmake vault.*.
Encryption is dotenvx: each file is
base64'd into one variable and the variable is encrypted with a public
key. .vault.keys holds the private key.
.vault.keys is not the app's .env.keys. Nothing that can read the
app's env (the server, a CI job) can open the vault.
Setup, once per repo
- Install dotenvx: https://dotenvx.com/docs/install.
- Edit
scripts/security/vault/manifest.ts: add the production env as the server has it (see "Sources"). make vault.encrypt. The first run makes.vault.keys.- Put
.vault.keysin your password manager. Do this before the commit. - Commit
vault/.
After that, run make vault.encrypt and commit whenever a secret changes.
make vault.status says when that is.
Commands
| Command | What it does |
|---|---|
make vault.encrypt | Collects every file in the manifest and rewrites vault/.env.operator. Rewrites nothing when no file changed. Keeps the vault's copy of a file it cannot read, so an unreachable server never empties the vault. Drops entries removed from the manifest. |
make vault.status | One line per file: same, newer than the vault (run encrypt), drifted, missing. Then the vault's age and any secret past its rotation age. |
make vault.verify | The same, and fails unless every file matches. |
make vault.install | Puts each local file back at its real path with its mode. Asks before it replaces a file that differs. For a new laptop. Server files are never installed. |
make vault.decrypt | Restores every file into .vault/ (gitignored, 0700) without touching the real paths. |
bash scripts/security/vault.sh cat <name> | Prints one file. Writes nothing to disk. |
make vault.bitwarden | Writes .vault/bitwarden/vault-bitwarden.json, one secure note per file, for Bitwarden's importer (Tools, Import data, "Bitwarden (json)"). The file is plaintext: run make vault.bitwarden.clean after the import. |
Sources
Each manifest entry names where the file is:
| Source | Meaning |
|---|---|
repo:.env | A file in this checkout. |
~/.ssh/id_deploy | A file in your home directory. |
ssh:prod:/home/deploy/myapp/shared/env/.env.production | A file on a server. prod is a host from ~/.ssh/config; the vault runs ssh prod cat <path>. |
The server's production env is the copy that counts, so add it:
{
name: 'prod.env.production',
source: 'ssh:prod:/home/deploy/myapp/shared/env/.env.production',
mode: 0o600,
tool: 'the running app (canonical production env)'
}
For a credential, record what it may do and when it was last rotated.
make vault.status then warns when it is due:
{
name: 'npmrc',
source: '~/.npmrc',
mode: 0o600,
tool: 'npm, bun',
scope: 'publish to the @myorg scope',
rotated: '2026-11-17',
rotateDays: 90
}
After a rotation
Change the secret where it lives, then make vault.encrypt, commit
vault/, and set the entry's rotated date.
To replace the vault key itself: move .vault.keys aside, run
make vault.encrypt from the real files, and store the new key.
What keeps it honest
scripts/security/vault/vault.test.ts runs in make ci. Once
vault/.env.operator exists it fails if any value in it is not
ciphertext, or if it holds a variable the manifest does not list.
make check-secrets scans it like every other tracked file.
Limits
- Anyone with
.vault.keysand the repo reads everything. One key, one place, and that place is a password manager, not a second laptop file. - A commit keeps old ciphertext in git history. A secret that leaked must be rotated; removing it from the vault does not help.
- The vault is a backup, not the way the app gets its env. Deployment is unchanged.