Files
archie/docs/prds/binding-secret-encryption.md
T
sam 9864766804 docs: describe the PostgreSQL-only stores, state_dir and the import-only db_path
Architecture, deployment, installer, skill and PRD text now name the Postgres
State Store, the offline recovery commands on database_url, state_dir for host
state, and db_path as the legacy-file locator for archie-state-store import.
Finalised PRDs, CHANGELOG, docs/news and docs/archive are unchanged records.
2026-09-24 14:51:48 +10:00

116 lines
5.5 KiB
Markdown

# Binding secret at-rest encryption -- decision
**Status:** Approved
**Date:** 2026-09-02
**Beads issue:** `archie-core-t2db.7` (P2), parent `archie-core-t2db`
## Problem
> Storage superseded: every store now lives in PostgreSQL behind
> `internal/domain/storecontract`, implemented in `internal/infrastructure/postgres`
> (`docs/prds/state-store-contract.md`). SQLite names below describe the
> original design.
`binding.Binding.Secret` (the per-source HMAC shared secret) is persisted as
plaintext in the `bindings.secret TEXT` column. Anyone with read access to the
SQLite file -- the same access level as `captured_events.body` and `tasks.body`
-- sees sender-side shared secrets. A leaked database file leaks secrets even
when the filesystem ACLs were correct at rest.
## Decision
Encrypt the `secret` column at rest with **AES-256-GCM** (stdlib
`crypto/aes` + `crypto/cipher`, no new dependency), transparently inside the
store: encrypt on write, decrypt on read. The store is the data boundary; its
consumers (dispatch loop, HMAC verification) receive the plaintext secret
exactly as and the webui already blanks `Secret` on every response.
### Cipher parameters
- **AEAD:** AES-256-GCM, 12-byte random nonce (`crypto/rand`), tag appended.
- **Key length:** 32 bytes, derived as `SHA-256(resolved_material)`. Kept as
SHA-256 (no Argon2id) because the source is a **32-byte high-entropy** value
resolved through the secret registry, so re-deriving to 32 bytes merely
re-shapes entropy rather than defending a weak passphrase.
- **AAD:** a static domain separator, `[]byte("arcie-binding-secret")`, so a
ciphertext cannot be relocated to a different field/column and still
authenticate. AAD is intentionally **not** row-bound: binding secrets are
random HMAC keys and are never used as lookup keys, so cross-row swap is not
a meaningful attack here.
### Envelope format
```
arcie-binding:v1:<keyFingerprint>:<base64url(nonce || ciphertext || tag)>
```
- `arcie-binding` -- domain marker
- `v1` -- format version (future cipher/KDF change is a new version, old rows
stay readable)
- `<keyFingerprint>` -- `hex(SHA-256(material))[:16]`, the identity of the key
that sealed the row, enabling rotation without a one-shot rewrite
- payload -- `base64url` of `nonce ‖ GCM.Seal(plaintext, aad)`
### Key source (confirmed with maintainer)
Resolved through the existing secret registry (`internal/secret`), the
established `SecretRef` pattern already used for `forge.webhook_secret`:
```toml
[bindings]
encryption_key = { engine = "env", key = "ARCHIE_BINDING_KEY" }
# Rotation: after swapping encryption_key to a new value, retain the previous
# material so rows sealed under the old key still decrypt.
previous_encryption_keys = [ { engine = "env", key = "ARCHIE_BINDING_KEY_OLD" } ]
```
The active key encrypts new writes; `previous_encryption_keys` are retained for
decrypt-only. Key identity is intrinsic to the material (the fingerprint), so
no manual key IDs are configured.
### Rotation story
Rotate by changing `encryption_key`, moving the old material into
`previous_encryption_keys`. Rows sealed under the old key still decrypt via
their embedded fingerprint; new writes use the new active key. Once no
remaining row references an old fingerprint, remove it from the config. Losing
a fingerprint's material before all its rows are rewritten makes those rows
unreadable -- the same operational rule as any key rotation, and the reason the
old material must be retained.
## Non-goals / deferred
- **`captured_events.body` redaction hardening** was completed alongside this
work (not deferred): `webhookguard.RedactPayload` now redacts an expanded set
of secret key markers (compound names like `access_token`, `client_secret`,
`signing_key`, `x_api_key`, …) as well as unambiguous value shapes (compact
JWTs, PEM private-key blocks) under any key. `gateway.sensitiveParameterKey`
was broadened identically to preserve the documented agreement. It remains
best-effort per `docs/prds/webhook-intake-security.md` point 5 -- a sender
that picks a name the heuristic misses is still captured.
- **Key re-derivation on config reload** is a startup concern: the store holds
the cipher for its lifetime, so a reload that changes `[bindings]` keys
requires a daemon restart to take effect. Documented, accepted.
## Wiring
- `internal/config`: add `BindingsConfig` (`encryption_key SecretRef`,
`previous_encryption_keys []SecretRef`) on `Config.Bindings`.
- `internal/app/archied/bootstrap.go` `openStores`: resolve both refs through
the already-built `secrets` registry, pass the material to `store.Open` via a
new option `store.WithBindingCipher(cipher)`.
- `internal/infrastructure/bindingcipher`: the `BindingCipher` interface and
concrete AES-GCM impl, consumed by the event-capture store; a `bindingCipher` field on `Store`, and the `Open`
option. **Nil cipher = plaintext**, so existing call sites and tests change
nothing and legacy deployments keep current behaviour until they set a key.
## Back-compat & tests
- `store.Open` gains the option variadically; all current call sites compile
unchanged.
- Existing plaintext rows are unaffected until a cipher is configured; rows
written before a cipher is installed remain plaintext and read as plaintext.
- Tests: cipher round-trip (Encrypt/Decrypt), wrong-key and tampered-ciphertext
integrity failure, envelope parse errors, and a store round-trip that asserts
the persisted column is NOT the plaintext while `GetBinding` returns it.