docs(security): write the canonical ZeroKMS cryptography page

[coderdan]

/security/architecture, the page that picks one ZeroKMS story. Everything else in the security section is blocked on this.

The three accounts turned out to be one

I expected to have to discard two descriptions. Instead, each was a different layer of the same mechanism, stated as if it were the whole thing. Adjudicated with @coderdan:

Old claim	Where	Resolution
"HMAC-based key derivation scheme"	security-architecture.mdx	True of layer 2: the SDK expands the key seed into a per-value data key, client-side
"Proxy symmetric re-encryption (patent pending)"	kms/index.mdx	True of layer 1: ZeroKMS combines the authority key with the client key component to produce the seed, server-side
"Root keys stored in AWS KMS. ZeroKMS handles key derivation and wrapping"	kms/index.mdx	True of the authority key at rest. AWS KMS protects it; no per-value data key is ever wrapped or stored
"No caching needed" / "never cached"	security-architecture.mdx	Too broad, and now corrected

So the page separates the layers explicitly, with a diagram, and says why naming only one of them is incomplete.

The caching claim was wrong and is now stated plainly

security-architecture.mdx said data keys are "never stored, cached, or transmitted" and that there is "no caching needed". Meanwhile Proxy ships cipher_cache_size=64, cipher_cache_ttl_seconds=3600, and a cipherstash_proxy_keyset_cipher_cache_hits_total metric. A reviewer who reads both pages catches us.

What's actually true: Proxy caches keyset-scoped cipher objects; no data key is ever cached. The page carries a table making the distinction, and an info callout saying the earlier claim was too broad. Caching a keyset cipher isn't caching a data key: the cipher still needs the client key to derive anything, and per-value keys are still derived per value.

This is the kind of thing a CISO finds, so we should find it first.

Also

• Standardises on AES-256-GCM-SIV. The corpus was split 6/3 between AES-GCM-SIV and AES-256-GCM (plain GCM would have overclaimed nothing and underclaimed nonce-misuse resistance).
• Rewrites security/index.mdx from a stub into a real section door, since the CISO audience is meant to read this section end to end.
• Does not restate the index-term leakage model. That belongs to /concepts/searchable-encryption (still a stub, task pending). This page gives a one-paragraph summary and links, per the anti-drift rule. It does say plainly that HMAC leaks frequency and ORE leaks order.

Checks

• bun run build passes, 716 pages. /security/architecture prerenders.
• validate-content passes.
• All internal links resolve.
• No em-dashes.

Follow-ups this unblocks and creates

Unblocks /security/{zerokms,cts,stack-sdk,proxy} and /security/threat-scenarios, which must link here rather than restate.

Creates cleanup on the legacy tree, which is still live at /stack: kms/index.mdx, kms/keysets.mdx, and reference/security-architecture.mdx still carry the unreconciled claims, and three pages still say AES-256-GCM. Two of those are compliance pages. Tracked separately.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
public-docs	Ready	Preview, Comment	Jul 9, 2026 8:15am

[coderdan]

Pushed 005d22c with two follow-ups from review.

Renamed /security/architecture -> /security/cryptography (H1, nav item, and slug). Also repointed the /stack/reference/security-architecture redirect at the new destination, and ticked the item in IA.md. validate-redirects still passes at 194 pages.

Section index nav item now reads "Overview". It was "Architecture & security", duplicating the folder label directly above it.

That one needed a small mechanism. Fumadocs derives both the sidebar label and the H1 from a page's title, so renaming the frontmatter would have changed the H1 too. I added a navTitle field to the v2 frontmatter schema, applied in getV2PageTree alongside the existing flattenEmptyFolders transform. It overrides the sidebar label only; URL and H1 are untouched.

Verified against the built HTML:

/docs/security               -> 'Overview'
/docs/security/cryptography  -> 'Cryptography'
/docs/security/compliance    -> 'Compliance'

H1 on /security:              Architecture & security
H1 on /security/cryptography: Cryptography

navTitle is reusable: every other section index has the same duplication (/reference sits under a "Reference" folder and is itself labelled "Reference", and so on). Worth applying across the board when the index pages get filled in.