FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

docs(v2): port comparisons (FHE/KMS/HSM/Vault) into /concepts/compare by coderdan · Pull Request #43 · cipherstash/docs · GitHub

/ docs Public

docs(v2): port comparisons (FHE/KMS/HSM/Vault) into /concepts/compare - #43

Merged
coderdan merged 6 commits into
v2from
docs/v2-comparisons
Jul 30, 2026
ConversationCommits (6)ChecksFiles changed
Merged

docs(v2): port comparisons (FHE/KMS/HSM/Vault) into /concepts/compare#43
coderdan merged 6 commits into
v2from
docs/v2-comparisons

Conversation

coderdan commented Jul 5, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Ports and refreshes the comparison section under /concepts/compare, against the current v2 branch.

Pages

  • CipherStash vs AWS KMS
  • CipherStash vs HashiCorp Vault
  • ZeroKMS vs hardware security modules
  • CipherStash vs homomorphic encryption

The Comparisons item is a menu-only folder in the sidebar; the four comparisons are its children.

Updates from the original draft

  • rewrites the Vault comparison for the current plural datakeys batch endpoint, removing the obsolete claim that envelope-mode data-key generation cannot be batched
  • removes unverified AWS KMS latency, throughput, pricing-plan, and product claims while retaining the architectural comparison
  • aligns the FHE page with EQL v3 capabilities and the current published EQL benchmark page
  • keeps the public TFHE/ORE primitive benchmark, with an explicit microbenchmark caveat
  • replaces the unfinished HSM draft and all of its TODOs with a scoped custody, operations, and complementary-deployment comparison
  • updates internal links, terminology, and navigation for the current V2 IA

Validation

  • bun run types:check
  • bun run lint
  • content, Mermaid, link, and redirect validators
  • Next.js production build

Supersedes the older comparison drafts from #31 and #34.

vercel Bot commented Jul 5, 2026 •
edited
Loading

Copy link
Copy Markdown

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

Project Deployment Actions Updated (UTC)
public-docs Ready Preview Jul 30, 2026 3:36pm

This was referenced Jul 5, 2026
Closed
Closed
coderdan changed the title docs(v2): port KMS/HSM/Vault comparisons into the /compare section docs(v2): port comparisons (FHE/KMS/HSM/Vault) into the /compare section Jul 5, 2026
coderdan force-pushed the docs/v2-comparisons branch from 1c38305 to eea1c10 Compare July 6, 2026 13:48
coderdan changed the title docs(v2): port comparisons (FHE/KMS/HSM/Vault) into the /compare section docs(v2): port comparisons (FHE/KMS/HSM/Vault) into /concepts/compare Jul 7, 2026
coderdan added 3 commits July 8, 2026 17:05
docs(v2): port KMS/HSM/Vault comparisons into the /compare IA section
118259b 
Ports the comparison content from PR #31 (AWS KMS merge + ZeroKMS vs HSM)
and PR #34 (HashiCorp Vault) out of the legacy content/stack tree and into
the new IA `/compare` section:

- content/docs/compare/aws-kms.mdx        (from #31)
- content/docs/compare/zerokms-vs-hsm.mdx (from #31; retains its WIP TODOs)
- content/docs/compare/hashicorp-vault.mdx (from #34)
- public/images/hsm.png                    (from #31)

Each page gains v2 facets (type: concept, components, audience, reviewBy —
the claims-page review date rather than verifiedAgainst). Intra-comparison
links are rewritten to `/compare/*`; all other cross-links keep pointing at
the still-served legacy `/stack/...` pages (which hold the real content
until their sections migrate). The dead `/stack/cipherstash/secrets` link on
the Vault page (no secrets page exists in this repo) is delinked.

The comparisons overview and nav (index.mdx, meta.json) list the three
ported pages. The FHE comparison stays in the legacy tree for now — it is
written against EQL v2 (eql_v2_encrypted, BLAKE3) and needs a v3 content
refresh before porting, tracked separately in IA.md (/compare/fhe port).

Supersedes #31 and #34 for the v2 branch.

Claude-Session: https://claude.ai/code/session_01CqDNqLSEEkCi7xAJFq7HJA
docs(v2): port the FHE comparison to /compare, rewritten for EQL v3
b5bc0f5 
Completes the /compare section: content/docs/compare/fhe.mdx, updated from
EQL v2 to EQL v3 and wired into the overview cards and nav.

- Types/operators: eql_v2_encrypted -> the eql_v3 domain-variant model
  (text_eq / int8_ord / text_match / text_search), typed-operand casts, and
  encrypted text match via bloom-filter `@>` (LIKE is blocked on ciphertext,
  now stated explicitly).
- Scheme portfolio + leakage rewritten around the v3 terms (hm / ob / bf) and
  the new order-preserving encryption (OPE) fast path; dropped the unverified
  BLAKE3 primitive claim.
- New "Real-world performance on EQL v3" section with v3 database-level numbers
  (0.12 ms exact equality ~1.3x plaintext; OPE range 0.12 ms ~1.2x plaintext;
  ORE range 4x faster than v2; bloom match 100-400x vs no index -- 1M rows,
  M1 Max, PG 17), from cipherstash/benches PR #23. Kept the primitive-level
  TFHE-vs-ORE table (tfhe-ore-bench). A public citation for the v3 DB figures
  is flagged with a TODO pending publication.
- Links repointed to the v3 EQL reference (/reference/eql, core-concepts);
  cross-links to un-ported pages keep pointing at the served legacy /stack tree.

Based on the v3 EQL reference; source of truth for terminology and terms is
content/docs/reference/eql/core-concepts.

Claude-Session: https://claude.ai/code/session_01CqDNqLSEEkCi7xAJFq7HJA
docs(v2): relocate comparisons under /concepts/compare per revised IA
6db2352 
The revised IA folds Comparisons into Concepts (no top-level /compare tab).
The rebase already moved these pages into content/docs/concepts/compare/;
this adjusts their in-file content to match:

- repoint /compare/* cross-links and index Cards to /concepts/compare/*
- components facet [zerokms] -> [platform] (zerokms collapsed into platform
  in the components enum)

fhe.mdx keeps [encryption, eql]. The zerokms-vs-hsm page is retained.
coderdan force-pushed the docs/v2-comparisons branch from eea1c10 to 6db2352 Compare July 8, 2026 07:05
docs(compare): update the aws-kms identity example to the strategy-ba…
abc761d 
…sed API

The ported snippet used new LockContext().identify(userJwt), deprecated in
protect-ffi 0.25, and passed the resulting Result straight to
withLockContext() instead of unwrapping .data. main fixed this in #57; this
carries the fix across so merging the port doesn't reintroduce it.

coderdan commented Jul 9, 2026

Copy link
Copy Markdown
Contributor Author

Pushed abc761d to this branch.

The aws-kms.mdx identity example was ported before #57 landed on main, so it carried two problems:

const lockContext = await new LockContext().identify(userJwt);   // deprecated
await client.encrypt(...).withLockContext(lockContext);          // Result, not LockContext

identify() is deprecated (per-operation CTS tokens were removed in protect-ffi 0.25 — it compiles, warns, and no longer affects encryption). And identify() returns Result<LockContext, EncryptionError>, so passing it straight to .withLockContext() skips the .data unwrap.

Merging as-is would have reintroduced into the v2 tree exactly what #57 removed from main. The snippet now matches: OidcFederationStrategy via config.authStrategy, then .withLockContext({ identityClaim: ["sub"] }).

aws-kms.mdx was the only comparison page with TypeScript examples; fhe, zerokms-vs-hsm, and hashicorp-vault are prose and SQL only. Build passes, 664 pages.

Heads up that this branch is 33 commits behind v2 — worth a rebase before merge.

This was referenced Jul 9, 2026
Merged
Merged

coderdan commented Jul 14, 2026

Copy link
Copy Markdown
Contributor Author

Reviewed against shipped Stack 1.0-rc.0 / EQL 3.0. No changes needed for correctness — the pages already match what shipped:

  • fhe.mdx — the fast-path claim "~0.12 ms exact match and order-preserving range" is correct (_ord is the OPE default in 3.0). The FHE-vs-ORE primitive numbers (~755 ns, ~200,000×, 5–6 orders of magnitude) are unaffected by the OPE default flip, since they measure the ORE primitive itself, which still ships as _ord_ore.
  • aws-kms.mdx — the SDK examples import @cipherstash/stack and @cipherstash/stack/schema with the fluent builder (encryptedColumn().freeTextSearch().equality().orderAndRange()). All of that still ships in 1.0-rc.0 (./schema export present; the three fluent methods present), so no import breakage. No deprecated identity API.
  • hashicorp-vault.mdx / zerokms-vs-hsm.mdx — conceptual, no SDK imports, no version-specific claims.

Two optional (non-blocking) items, your call:

  1. aws-kms.mdx demonstrates the v2 fluent schema builder, while the integration pages now lead with the v3 concrete-type style (types.TextEq(...)). Both ship, but it reads as inconsistent. Want it modernized to v3?
  2. There's an unresolved {/* TODO */} on aws-kms.mdx asking to replace the ~16×/~85× KMS figures with a public-facing citation (currently sourced from cipherstash/benches kms-app/REPORT.md). I left it rather than fabricate a citation.

coderdan mentioned this pull request Jul 14, 2026
Merged
coderdan merged commit 9ac42fd into v2 Jul 30, 2026
3 checks passed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
Show hidden characters
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

Back | FazBrowse Home | New Git URL