Go to file
Hongming Wang b625445357 docs: reframe secret encryption as KMS envelopes (with static-key fallback)
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>
2026-05-04 04:46:02 -07:00
.github/workflows chore(ci): enroll in org-wide secret-scan reusable workflow (Molecule-AI/molecule-core#2109 rollout) 2026-04-26 16:12:33 -07:00
app feat(docs): align doc.moleculesai.app chrome with landing's warm-paper design 2026-04-30 22:42:42 -07:00
audio merge: PR #58 2026-04-21 03:00:15 +00:00
content docs: reframe secret encryption as KMS envelopes (with static-key fallback) 2026-05-04 04:46:02 -07:00
docs/marketing devrel: add failed workspace EC2 console output demo script (#68) 2026-04-21 03:40:33 +00:00
lib fix: restore build infrastructure deleted by bad PR #59 merge 2026-04-22 14:03:24 -07:00
marketing/demos/snapshot-scrub docs(marketing): snapshot secret scrubber working demo (PR #977) (#63) 2026-04-21 03:01:07 +00:00
.gitignore fix: restore build infrastructure deleted by bad PR #59 merge 2026-04-22 14:03:24 -07:00
mdx-components.tsx fix: restore build infrastructure deleted by bad PR #59 merge 2026-04-22 14:03:24 -07:00
next.config.mjs fix: restore build infrastructure deleted by bad PR #59 merge 2026-04-22 14:03:24 -07:00
package-lock.json fix: restore build infrastructure deleted by bad PR #59 merge 2026-04-22 14:03:24 -07:00
package.json fix: restore build infrastructure deleted by bad PR #59 merge 2026-04-22 14:03:24 -07:00
postcss.config.mjs fix: restore build infrastructure deleted by bad PR #59 merge 2026-04-22 14:03:24 -07:00
source.config.ts fix: restore build infrastructure deleted by bad PR #59 merge 2026-04-22 14:03:24 -07:00
tsconfig.json fix: restore build infrastructure deleted by bad PR #59 merge 2026-04-22 14:03:24 -07:00