Skip to content

0021. Encryption of stored secrets and hashing of credentials

  • Status: Accepted
  • Date: 2026-11-08

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.

  • Stored secrets are encrypted with AES-256-GCM through the SecretCipher port. The key comes from SecretProvider (SECRET_KEK_<kid>), and the ciphertext is prefixed with its kid.
  • 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.

  • Secrets are decrypted only inside the command or adapter that needs them and never returned by the API or MCP.