chore(ci): gate the build on deprecated and non-existent API in docs#61
Merged
Conversation
…abase docs The v2 docs branch will host the Supabase page at /docs/integrations/supabase but isn't published yet. Add a temporary (307) redirect from that future URL to the current Supabase overview page (/stack/cipherstash/supabase) so external links resolve until v2 ships, at which point this entry should be removed.
…ons-supabase chore(redirects): temp redirect /integrations/supabase → current Supabase docs
… build The EQL reference generator fetches the latest release's API.md at build time and passes lowercase-led tags (e.g. `<tt>`) through as real HTML. MDX requires every tag to be balanced, so a mangled SQL-comment source that emits an unclosed `<tt>` fails the whole Vercel build — which is exactly what eql-3.0.0-alpha.3 did (index.mdx:2153, `Expected a closing tag for <tt>`). `<tt>` is Doxygen's teletype tag; MDX doesn't need it. Strip `<tt>`/`</tt>` (non-code text only) before escaping, so malformed upstream docs degrade gracefully instead of taking the deploy down. Verified: regenerated content/stack/reference/eql/index.mdx from the live eql-3.0.0-alpha.3 release and `next build` compiles all 329 pages.
fix(eql-docs): strip Doxygen <tt> tags so a stray one can't break the build
The live docs teach `new LockContext().identify(jwt)`. Per-operation CTS
tokens were removed in protect-ffi 0.25, so `identify()` is deprecated: it
still compiles and logs a warning, but the token it fetches is no longer
used by encryption operations. Readers copying these examples get code that
appears to bind an identity and does not.
Correct usage authenticates the client as the end user with
OidcFederationStrategy (config.authStrategy), then names the claim to bind:
const client = await Encryption({
schemas: [users],
config: { authStrategy: OidcFederationStrategy.create(crn, () => getJwt()) },
})
await client.encrypt(v, opts).withLockContext({ identityClaim: ["sub"] })
Two pages also used `client.withLockContext({ identityToken })`, a call shape
that never existed in any release.
Verified against the shipped type definitions of @cipherstash/stack 0.19.0
and @cipherstash/auth 0.42.0.
docs: update identity-aware encryption to the strategy-based API
Follow-up to #57, from review feedback on the v2 port (#56). The client setup blocks configure `authStrategy`, but the examples below them import an already-built client, so a reader skimming the encrypt and decrypt snippets sees `.withLockContext()` with no strategy in view and could reasonably conclude the claim binding stands alone. - Warn that OidcFederationStrategy is the only strategy supporting lock contexts. AccessKeyStrategy authenticates as the service, so there is no end-user identity for ZeroKMS to resolve the claim against. - State that the examples depend on the authStrategy-configured client. - Explain that `_` in the dashboard OIDC providers URL is the selected workspace. Dropped the "AccessKeyStrategy is also re-exported" aside from identity.mdx: naming it in a lock-context section was what invited the confusion.
…arifications docs: clarify that lock contexts require OidcFederationStrategy
Brings the identity-API fixes (#57, #59) and the EQL docs build fix (#58) into the v2 branch. Without this, merging v2 to main at launch would revert them: v2's copy of content/stack still taught LockContext.identify(), which is deprecated and no longer affects encryption. One conflict, in scripts/generate-eql-docs.ts. Both branches carry the same `<tt>`-stripping fix; they differ only in whether the .replace chain is wrapped in parentheses. Kept v2's formatting.
A page fixed on one branch gets silently reintroduced by a port from the other. That is how `LockContext.identify()` survived being fixed on main and came back through a comparison-page port (#43), and how v2's legacy tree kept teaching it after main was fixed (#60). `validate-content` scans content/docs and content/stack for API that is deprecated (LockContext.identify), never existed (withLockContext with an identityToken option), or was removed in EQL 3.0.0 (eql_v2_encrypted, add_search_config, the cs_*_v1 config functions), plus stale `protect` and `@cipherstash/cli` branding. Rules are scoped: EQL v3 rules apply only to content/docs, since the legacy tree documents EQL v2 by design. Generated output is skipped; those examples come from the SDK's own doc comments and get fixed upstream. A line is exempt when it also says the API is retired, so deprecation callouts and migration notes can still name the old API in order to warn readers off it. Naming a dead symbol without saying it is dead is the bug. Verified against both real regressions: it flags PR #43's original aws-kms snippet and main's pre-#57 `identityToken` form, and passes on the current tree.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
This was referenced Jul 9, 2026
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Stacked on #60 (merge
mainintov2). Review that first; this PR's diff againstv2will show #60's changes until it lands.Why
Twice today the same class of bug bit us:
aws-kms.mdxinto the v2 tree carryingnew LockContext().identify(userJwt)— reintroducing onv2exactly what docs: update identity-aware encryption to the strategy-based API #57 removed frommain.v2's wholecontent/stackstill teaching the deprecated flow, which would have reverted docs: update identity-aware encryption to the strategy-based API #57 at the launch merge.Neither was caught by anything. Two long-lived content branches plus a fast-moving SDK means a fix on one branch is not a fix, and code review is the only thing standing between a stale port and production.
What it does
bun run validate-content, wired intoprebuild, scanscontent/docsandcontent/stackfor API that is:lockcontext-identify.identify(— deprecated inprotect-ffi0.25; the token it fetches no longer affects encryptionidentity-token-optionwithLockContext({ identityToken })— never existed in any releasebare-lockcontext-constructornew LockContext()— only useful with the deprecated floweql-v2-encrypted-typeeql_v2_encrypted— removed in EQL 3.0.0eql-v2-schema-functionseql_v2.*()callseql-v2-config-tablecs_add_column_v1,cs_match_v1,cs_ste_vec_v2,add_search_config, …protect-brandingProtectClientConfig,@cipherstash/cliEach failure prints the file, line, offending text, and the fix.
Two design decisions
Rules are scoped. The EQL v3 rules apply only to
content/docs. The legacy tree documents EQL v2 throughout by design, andcontent/docs/reference/eql/v2/is a deliberately retained v2 reference. Both would otherwise drown the output.A line is exempt when it says the API is retired. The exemption matches
deprecated | removed | no longer | are gone | never existed, so deprecation callouts and migration notes can name the old API in order to warn readers off it. Naming a dead symbol without saying it's dead is the bug; that's the line the check draws.This also means the check is line-local and greppable rather than an AST pass. It's a tripwire, not a type checker. The real fix for snippet correctness is snippet type-checking against the published packages, which is still open as part of the correctness-CI work.
Verification
Not just "it passes". I replayed both regressions:
Both flagged. And it passes on the current tree:
bun run buildpasses with the guard running inprebuild, 714 pages.biome checkclean.Note
This deliberately pulls the deprecated-API subset of the correctness-CI work forward, ahead of snippet type-checking. It's ~150 lines and it protects the v2 branch for the rest of the migration, which has 58 pages still to port.