docs(security): correct the ZeroKMS key exchange and caching claims

[coderdan]

A materially wrong security claim is live. reference/security-architecture.mdx is the page we point vendor security reviewers at, and it currently tells them the client key is transmitted to CipherStash:

"The SDK sends a key derivation request to ZeroKMS with the client key component."
"ZeroKMS combines the authority key and client key to produce a key seed."

That inverts the property the architecture exists to provide. If it were true, the dual-party split would be theatre: both halves would meet on CipherStash's side.

What actually happens

Adjudicated with @coderdan:

1. The application requests a key seed by sending a key ID. The request carries no key material of yours, only the ID. The ID is what gives each data key its unique identity, so a value can be decrypted later by asking for the seed for the same ID.
2. ZeroKMS applies proxy symmetric re-encryption to the authority key alone and returns the seed. It never receives the client key.
3. Your application processes the seed with the client key, then an HMAC-based KDF expands the result into a per-value data key.

Only the seed crosses the boundary, and it crosses inward. Nothing crosses outward: not the client key, not the processed seed, not the data key.

Two other wrong claims on the same page

Caching. It 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. What's true: no data key is ever cached; Proxy caches keyset-scoped cipher objects. The page now states both, and explains why they differ.

Root keys and wrapping. kms/index.mdx said "Root keys are stored in AWS KMS. ZeroKMS handles key derivation and wrapping", contradicting the same page's "no wrapped-key storage". Both are partly right: AWS KMS protects the authority key at rest, and no per-value data key is ever wrapped or stored. kms/keysets.mdx likewise described a per-keyset "root key" from which ZeroKMS derives data keys; keysets scope the authority key.

AES naming

Standardised on AES-256-GCM-SIV. The corpus was split 6/3 against plain AES-256-GCM, and two of the wrong ones were compliance pages, where naming the wrong cipher mode is worse than sloppy.

before:  6x AES-GCM-SIV,  3x AES-256-GCM
after:   9x AES-256-GCM-SIV

Files (7)

reference/security-architecture.mdx (key derivation, trust model, both data-flow paths, caching section), cipherstash/kms/index.mdx, cipherstash/kms/keysets.mdx, plus AES naming in cipherstash/proxy/getting-started.mdx, deploy/troubleshooting.mdx, reference/comparisons/fhe.mdx, reference/use-cases/compliance.mdx.

Checks

• bun run build passes, 589 pages.
• grep for the old claims returns nothing outside generated TypeDoc.

Follow-up

The v2 branch carries the reconciled version of this page at /security/cryptography (#62). Once both land, main -> v2 needs another sync, or the launch merge reverts this. That recurring problem is tracked separately; a sync policy is still undecided.

Not fixed here: SOC 2 / SOC2 splits 9/6 across the corpus. Cosmetic, and worth doing in one pass with the rest of the consistency sweep.

[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:12am