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 as make 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

  1. Install dotenvx: https://dotenvx.com/docs/install.
  2. Edit scripts/security/vault/manifest.ts: add the production env as the server has it (see "Sources").
  3. make vault.encrypt. The first run makes .vault.keys.
  4. Put .vault.keys in your password manager. Do this before the commit.
  5. Commit vault/.

After that, run make vault.encrypt and commit whenever a secret changes. make vault.status says when that is.

Commands

CommandWhat it does
make vault.encryptCollects 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.statusOne 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.verifyThe same, and fails unless every file matches.
make vault.installPuts 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.decryptRestores 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.bitwardenWrites .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:

SourceMeaning
repo:.envA file in this checkout.
~/.ssh/id_deployA file in your home directory.
ssh:prod:/home/deploy/myapp/shared/env/.env.productionA 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.keys and 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.