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>
[Molecule-Platform-Evolvement-Manager]
PR #59 (commit dae42e2) was merged ~2 weeks ago with a bad diff that
deleted all Next.js/Fumadocs build files (package.json, app/, lib/,
source.config.ts, tsconfig.json, etc.) and most MDX content pages.
This broke the Vercel build, taking doc.moleculesai.app offline.
Root cause: the PR branch was likely rebased or reset to a state that
only contained the marketing/ subtree, so the merge diff showed
deletions for every other file.
This commit:
1. Restores all build infrastructure from the last good commit (86fa0e9)
2. Restores 25 deleted MDX content pages (concepts, quickstart, etc.)
3. Adds frontmatter (title) to 55 .md files added post-bad-merge that
were missing the required YAML frontmatter for Fumadocs
4. Removes duplicate quickstart.mdx (superseded by quickstart.md)
5. Adds CI workflow (.github/workflows/ci.yml) to catch build failures
on PRs before merge — this would have prevented the outage
Build verified: 99 static pages generated successfully.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
