The platform's actual crypto model is two-mode envelope encryption
(workspace-server/internal/crypto/envelope.go):
- KMS mode (production): KMS_KEY_ARN selects an AWS KMS CMK; each
Encrypt() calls GenerateDataKey for a fresh per-secret DEK, seals
the payload with AES-256-GCM, stores the KMS-encrypted DEK +
ciphertext together. CMK rotation is a no-op for existing blobs.
- Static mode (dev / self-host): SECRETS_ENCRYPTION_KEY is a single
long-lived 32-byte AES-256 key. Cannot rotate without a data
migration.
Both modes coexist during cutover (v2 prefix byte tags KMS blobs).
The platform refuses to start with neither configured rather than
silently storing plaintext.
Previous docs framed this as "AES-256-GCM at the application layer"
and named only SECRETS_ENCRYPTION_KEY, which under-described the
production path and made the KMS migration invisible to readers.
Files updated:
- content/docs/architecture.mdx — env table adds KMS_KEY_ARN, clarifies
SECRETS_ENCRYPTION_KEY as static-mode/self-host
- content/docs/self-hosting.mdx — env table + Secrets Encryption section
rewritten to cover both modes; cites envelope.go
- content/docs/security/owasp-agentic-top-10.mdx — A02 control
description now lists envelope encryption with KMS as production path
- content/docs/development/constraints-and-rules.md — Rule 11 reframes
storage model as envelope encryption (KMS prod, static dev)
- content/docs/architecture/database-schema.md — workspace_secrets
description updated to mention envelope encryption + v2 prefix +
source file pointer
- content/docs/architecture/molecule-technical-doc.md — five touchpoints
(capability bullet, schema table, codebase tree, env table now
includes KMS_KEY_ARN, recent-features global API keys row)
No infra/runtime/Nemotron claims touched.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
b625445357