docs: refresh root README around the three Stack pillars by coderdan · Pull Request #526 · cipherstash/stack

coderdan · 2026-06-28T11:19:58Z

What

A conversion-focused rewrite of the root README.md, benchmarked against 8 company-backed, high-star OSS READMEs (Supabase, Clerk, Infisical, Vault, Trigger.dev, Prisma, Drizzle, React Email).

The README now:

Leads with the differentiator — searchable encryption ("search encrypted data without decrypting it") plus a zero-knowledge trust line, instead of a single-bullet "What is the stack?".
Account-first quick start — step 1 is create a free account, then npx stash init, then a snippet that shows encrypt → search without decrypting → decrypt.
Covers all three pillars early: 🔐 searchable encryption, 🔗 ORM & database integrations (Supabase / Drizzle / Prisma Next / DynamoDB, as a status matrix), 👤 identity-aware encryption.
Adds a "How it works" trust section with an embedded architecture diagram and a link to the security architecture docs — the trust signal the security-category leaders leave out of their READMEs.
Reference-style links — all URLs are centralised at the bottom of the file; CipherStash links carry ?utm_source=github&utm_medium=stack_readme for attribution.

Also in this PR:

Marks @cipherstash/protect (Protect.js) as legacy with a warning banner at the top of its README.
Architecture diagram embedded — four SVG variants under docs/images/ (desktop/mobile × light/dark), selected by a single <picture> element that switches on both prefers-color-scheme and max-width (viewport). The desktop-light <img> is the universal fallback for npm and older renderers.
docs/plans/readme-visual-assets.md — specs for the visual assets, including a ship-today Mermaid version of the diagram.

Auth section — reflects #497 (`OidcFederationStrategy`), now merged

The identity-aware encryption pillar uses the strategy-based API from #497 (now merged): client-level OidcFederationStrategy (config.strategy, re-exported from @cipherstash/stack) + .withLockContext({ identityClaim }), replacing the deprecated new LockContext() → identify() → .withLockContext(lc) ceremony. This makes every OIDC provider (Clerk, Supabase, Auth0, Okta) first-class.

✅ Signature verified against the merged code — OidcFederationStrategy.create(workspaceCrn, () => getJwt()) (2-arg form, getJwt returns a Promise<jwt>), matching packages/stack/__tests__/lock-context.test.ts. The branch has been rebased onto main (post-#497).

Follow-ups

Before merge: restore absolute image URLs. The architecture-diagram <picture> paths are temporarily relative (docs/images/…) so they preview on this branch — they must be switched back to https://raw.githubusercontent.com/cipherstash/stack/main/docs/images/… before merge, or they break on the npm package page. (TODO noted inline in the README and in the spec doc.)
npm deprecate @cipherstash/protect — being handled separately (npm not authed in the build env).
Produce the remaining visual asset: the type-safety autocomplete GIF (architecture diagram is done).

Notes for reviewers

Render the README on the branch to check the badge row, tables, reference links, and the architecture diagram (light/dark + desktop/mobile) all resolve.
Confirm the UTM scope (currently on all cipherstash.com links) matches what analytics expects — easy to dial back since they're all in one block.

changeset-bot · 2026-06-28T11:20:02Z

⚠️ No Changeset found

Latest commit: 0d318de

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

coderabbitai · 2026-06-28T11:20:06Z

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 5d989611-9043-43cc-afc0-0764e8bc02d5

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch docs/readme-refresh

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

- Lead with a searchable-encryption value prop and zero-knowledge trust line - Account-first quick start; show encrypt + search-without-decrypt + decrypt - Cover all three pillars early: searchable encryption, ORM integrations (Supabase/Drizzle/Prisma Next/DynamoDB), identity-aware encryption - Add a 'How it works' section linking the security architecture docs - Use reference-style links with all URLs centralised at the bottom (CipherStash links carry README UTM params) - Mark @cipherstash/protect (Protect.js) as legacy in its README - Spec the architecture diagram + type-safety GIF in docs/plans

Reflects the auth changes in #497: replace the deprecated LockContext.identify() ceremony with client-level OidcFederationStrategy + .withLockContext({ identityClaim }), which makes every OIDC provider (Clerk, Supabase, Auth0, Okta) first-class.

Add the four architecture SVG variants (desktop/mobile x light/dark) and embed them in the How it works section via a single <picture> element. Sources select on both prefers-color-scheme and max-width:600px; the desktop-light <img> is the universal fallback for npm and older renderers.

Temporary: switch the architecture <picture> srcset/src to relative paths so they render on the PR branch. Must be restored to absolute raw.githubusercontent.com/.../main/ URLs before merge (relative paths break on the npm package page). TODO noted inline and in the visual-assets spec.

- Lead with three short searchable-encryption examples (Supabase, Prisma Next, Drizzle) and a Quick starts table - EQL v3 framing: CREATE TABLE with domain types replaces per-column SEM config; auth gains device auth; keysets replace BYOK under Advanced features - Add performance table (benches-attributed), FAQ from the Supabase listing, and a Start free CTA; drop the Protect.js migration section - Spec a purpose-built flat-latency chart as Asset 3 in the visual assets plan

- Drizzle example uses the types namespace (types.TextMatch) instead of the SEM-style options object, matching the v3 authoring surface - Add docs/plans/readme-go-live-checklist.md consolidating every doc-driven claim to confirm before merging to main, referenced from a comment at the top of the README

Make the "only raw pg needs a client-side schema" claim concrete with an encryptedTable + types example mirroring the CREATE TABLE domain types above it; sharpen the matching go-live checklist item.

og:image via repo Settings → Social preview (1280×640 dark-brand card, export kept in-repo), About description doubling as og:description; add the upload/verify step to the go-live checklist.

coderdan added 2 commits July 3, 2026 09:57

coderdan force-pushed the docs/readme-refresh branch from 20e13ae to 88c9aec Compare July 2, 2026 23:58

coderdan added 6 commits July 3, 2026 12:21

docs(readme): show eql/v3 types schema for the raw-pg path

b41c47b

Make the "only raw pg needs a client-side schema" claim concrete with an encryptedTable + types example mirroring the CREATE TABLE domain types above it; sharpen the matching go-live checklist item.

docs(plans): spec repo social preview card as Asset 4

0d318de

og:image via repo Settings → Social preview (1280×640 dark-brand card, export kept in-repo), About description doubling as og:description; add the upload/verify step to the go-live checklist.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: refresh root README around the three Stack pillars#526

docs: refresh root README around the three Stack pillars#526
coderdan wants to merge 8 commits into
mainfrom
docs/readme-refresh

coderdan commented Jun 28, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented Jun 28, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Jun 28, 2026 •

edited

Loading

Review skipped

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

coderdan commented Jun 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Auth section — reflects #497 (OidcFederationStrategy), now merged

Follow-ups

Notes for reviewers

Uh oh!

changeset-bot Bot commented Jun 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

coderabbitai Bot commented Jun 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

coderdan commented Jun 28, 2026 •

edited

Loading

Auth section — reflects #497 (`OidcFederationStrategy`), now merged

changeset-bot Bot commented Jun 28, 2026 •

edited

Loading

coderabbitai Bot commented Jun 28, 2026 •

edited

Loading