design: the secret store

Written from the conversation of 2026-08-12. Nothing implemented; every claim
about the current tree was checked on that date.

The short version: secrets stay in Postgres, the keys move out of .env into a
small SQLite store, and rotation becomes an operation instead of data loss.

What is actually wrong today is narrower than "secrets in .env" and worth stating
precisely, because the separation that exists is correct and must survive a
refactor: secrets live in Postgres and the key that opens them does not. The
problem is blast radius across processes — Bun auto-loads .env, so
VAULT_STORE_KEY sits in the environment of all twenty pm2 processes, and
officer-music holds the key that decrypts wallet seed envelopes for no reason.

The document records the decisions and, more usefully, what was ruled out:

  Keys cannot go in Postgres. A dump would carry the ciphertext and the thing
  that opens it. Encrypting the key with a second key only moves the question —
  one secret has to be readable without any other, and the only decision is where
  it lives.

  The store is not encrypted at rest, and this was tested rather than assumed:
  stock SQLite silently ignores unknown pragmas, so `PRAGMA key` succeeds,
  encrypts nothing, and the value is readable with `strings`. bun:sqlite ships
  stock SQLite 3.53.0. Whole-file encryption needs SQLCipher, which is a second
  native dependency, and this project already knows what one of those costs.

  SQLite rather than a flat file for rotation, not secrecy: rotation needs key
  VERSIONS, since an interrupted rotation needs the old key and the new one to
  both exist.

  The file must not live in $OFFICER_ROOT/data/ — that is what people back up,
  and a key store in the same tarball as a database dump rebuilds the problem.

It also records the core/plugin split the design assumes: light plus
officer-headscale is the core, because CLAUDE.md rests the security model on the
tailnet and a model that rests on the tailnet cannot treat administering it as
optional. Vaultwarden and the wallet become plugins. Moving headscale into light
removes it from the app store automatically, since catalogue.test.ts asserts the
catalogue equals full minus light.

Five open questions are left open rather than guessed at.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

CLAUDE.md

@@ -387,6 +387,9 @@ explaining why it was safe.
   mounted and what it knows, the URL-vs-channel split for panel-to-panel communication, and the
   persistence key families. Read before building a panel app. Its defect list is
   `docs/workspace-panel-todo.md`.
+- `docs/secret-store.md` — **design, not built**: moving the encryption and signing keys out of `.env`
+  into a SQLite store, why they cannot live in Postgres, and key rotation. Also records the core/plugin
+  split it assumes — light plus `officer-headscale` is the core; Vaultwarden and the wallet are plugins
 - `docs/sidecar-topology.md` — where the sidecar architecture is going, and what was considered and dropped
 - `docs/working-on-officer.md` — how to run, restart and check your work on this machine
 - `docs/wallet-key-custody.md` — what the platform can and cannot see of the wallet