0021. Encryption of stored secrets and hashing of credentials
- Status: Accepted
- Date: 2026-11-08
Context
Section titled “Context”Projects store secrets: inbound source secrets, outbound webhook signing secrets (cl_whsec_), and destination credentials. ADR 0007 forbids them in logs and responses; they must also be useless if the database is copied.
Decision
Section titled “Decision”- Stored secrets are encrypted with AES-256-GCM through the
SecretCipherport. The key comes fromSecretProvider(SECRET_KEK_<kid>), and the ciphertext is prefixed with itskid. - The additional authenticated data is
(project_id, purpose, record_id), so a ciphertext cannot be moved to another project or record. - Key rotation re-encrypts in the background.
- Outbound webhook signing secrets (
cl_whsec_) are needed in plaintext to sign, so they are encrypted like the other stored secrets, never hashed. - API keys (
cl_sk_,cl_rk_,cl_pk_) and OTP codes are stored only as hashes (ADR 0025, ADR 0026). - Cloudflare Secrets Store is not used while it is in beta.
Amendment (2026-11-20, pending ADR 0051, Proposed): MCP OAuth tokens and codes are stored only as hashes, except that a refresh rotation’s response (the new access and refresh tokens) is kept encrypted with the auth secret on the rotated row from rotation until it is cleared, after the 10-second reuse window, on the chain’s next refresh or by the daily cron. It is protected like sessions.token (ADR 0040): reading the table alone gives nothing usable without the auth secret. D1 Time Travel and backups keep the encrypted value for their own retention.
Consequences
Section titled “Consequences”- Secrets are decrypted only inside the command or adapter that needs them and never returned by the API or MCP.