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.
116 lines
5.5 KiB
Markdown
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.
|