RedactPayload only redacted values under a fixed set of sensitive key names, so a sender that names a secret field something else leaked it into captured_events.body. Harden the heuristic: - broaden the key-name markers (compound names like access_token, client_secret, signing_key, x_api_key, webhook_secret, refresh_token) and keep gateway.sensitiveParameterKey identical to preserve the documented agreement between the two redaction paths. - add value-shape detection: a compact JWT or a PEM private-key block is redacted under any key, catching the 'sender named the field something the heuristic misses' gap. - keep it conservative so schema-by-example field mapping still works: only unambiguous shapes (eyJ-prefixed JWTs, PEM key blocks) are redacted by value, never ordinary content. Best-effort per docs/prds/webhook-intake-security.md point 5. Refs archie-core-t2db (captured_events.body redaction)
5.2 KiB
Binding secret at-rest encryption -- decision
Status: Decided, to be implemented
Date: 2026-09-02
Beads issue: archie-core-t2db.7 (P2), parent archie-core-t2db
Problem
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 today, 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 markerv1-- 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 --
base64urlofnonce ‖ 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:
[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.bodyredaction hardening was completed alongside this work (not deferred):webhookguard.RedactPayloadnow redacts an expanded set of secret key markers (compound names likeaccess_token,client_secret,signing_key,x_api_key, …) as well as unambiguous value shapes (compact JWTs, PEM private-key blocks) under any key.gateway.sensitiveParameterKeywas broadened identically to preserve the documented agreement. It remains best-effort perdocs/prds/webhook-intake-security.mdpoint 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: addBindingsConfig(encryption_key SecretRef,previous_encryption_keys []SecretRef) onConfig.Bindings.internal/app/archied/bootstrap.goopenStores: resolve both refs through the already-builtsecretsregistry, pass the material tostore.Openvia a new optionstore.WithBindingCipher(cipher).internal/store: add aBindingCipherinterface (concrete AES-GCM impl inbinding_cipher.go), abindingCipherfield onStore, and theOpenoption. 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.Opengains 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
GetBindingreturns it.