Skip to content

feat(stack-auth): verify CTS access tokens against the issuer's JWKS - #1691

Draft
cipherstash-agent wants to merge 3 commits into
mainfrom
claude/project-thread-im7wrp
Draft

cipherstash-agent wants to merge 3 commits into
mainfrom
claude/project-thread-im7wrp

Conversation

@cipherstash-agent

@cipherstash-agent cipherstash-agent commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Requested by CipherStash · project thread

Summary

Today every stack-auth strategy trusts whatever token CTS's authorize endpoint returns. If someone controls the auth URL (an injected CS_CTS_HOST, a compromised dependency, a poisoned token store), they can hand the client a token with any scopes and a services claim that sends key requests to a rogue ZeroKMS.

This PR adds a token verifier to stack-auth. Call verify_tokens() on a strategy builder, and every token is checked before get_token returns it:

  • the token must be signed with RS256 (none and HMAC are refused) by a key from <issuer>/.well-known/jwks.json;
  • iss must be the trusted issuer;
  • exp must not have passed (60 seconds of leeway, the same as ZeroKMS);
  • aud must contain the audience the strategy requested, when it requested one.

The trusted issuer is pinned separately from the auth URL. It is the CTS that service discovery names for the workspace's region (https://<region>.aws.cts.cipherstashmanaged.net/). base_url() and CS_CTS_HOST change where tokens are requested, never which issuer is trusted. Use trusted_issuer(url) to trust a different CTS, such as staging.

Verification is opt-in in this PR. CTS signs with RS256, its issuer is the regional URL above, and its keys are at /.well-known/jwks.json. The terraform provider's validator and CTS's route list say so, and a new step in the live job of tests-golang.yml confirms it by verifying a real CTS token (issued by https://us-east-2.aws.cts.cipherstashmanaged.net/). Turning verification on by default is a small follow-up.

Changes

  • packages/stack-auth/src/token_verifier.rs (new):
    • Fetches and caches the JWKS for an hour. A rotated key is fetched early, but at most one fetch a minute, whether fetches succeed or fail.
    • During a JWKS outage, keys already in the cache keep verifying.
    • Refused tokens get one opaque AuthError::InvalidToken. The reason is logged at warn, and nothing from the token is logged.
    • JWKS fetch failures are Request / Server errors.
  • RSA verification uses aws-lc-rs natively. On wasm32, where aws-lc-rs does not build (and the WASI gate forbids aws-lc-sys), it uses RustCrypto rsa. Only public-key operations are used, so RUSTSEC-2023-0071 does not apply. The host tests run both backends against the same vectors. vitaminc has no RSA verification.
  • verify_tokens() / trusted_issuer() are added to the AccessKeyStrategy, OidcFederationStrategy, DeviceSessionStrategy and AutoStrategy builders.
    • A saved device session is verified against the CTS for the region saved with it, not against its own iss.
  • transport::get for the JWKS request. The Go host transport already honours the request method.
  • examples/verify_tokens.rs:
    • built in tests-crates.yml;
    • run against real CTS in the live job of tests-golang.yml.
  • README.md: new "Verifying tokens" section. Comments in oidc_refresher.rs and oidc_federation_strategy.rs now make clear that the token the client can't verify is the provider's JWT.
  • Updated the Cargo.lock files of the root workspace, both Go guests and the three fuzz crates. The changes only add rsa and its dependencies.
  • .cargo/mutants.toml: added an exclusion for the wasm32-only dispatch, and moved the line anchor of the existing wasm32 detect_inner exclusion.
  • Changeset: @cipherstash/auth patch. Its behaviour is unchanged, since the option is not exposed in JS yet.

Verification

  • cargo test -p stack-auth --all-features: 367 passed. --no-default-features: passed. Doctests passed.
  • cargo clippy -p stack-auth --all-targets --all-features -D warnings and RUSTDOCFLAGS=-D warnings cargo doc (both feature shapes): clean.
  • WASI gate: cargo check --target wasm32-wasip1 -p stack-auth --no-default-features, with no aws-lc-sys, reqwest or js-sys in the tree. wasm32-unknown-unknown check for stack-auth-wasm. Both Go guests pass cargo check --locked --target wasm32-wasip1.
  • Mutation testing (cargo mutants --in-diff): all mutants on the changed lines are caught or excluded. Each check was also confirmed by mutating it by hand.
  • pnpm run test:scripts: 1431 passed.
  • The live check against real CTS passed in this PR's tests-golang.yml live job: it verified a token for workspace 35PWGD4AWHAVOBG4 issued by https://us-east-2.aws.cts.cipherstashmanaged.net/.

Related

Review notes

  • Follow-ups, deliberately not in this PR:
    • turn verification on by default;
    • expose it in the @cipherstash/auth JS API and the Go auth package;
    • decide on a default audience for the OIDC and device-session strategies. Their aud is unchecked today because the client does not know CTS's default.
  • ServiceToken's accessors still decode claims without verifying them. They can be trusted only on tokens from a strategy with verification on.

Generated by Claude Code

🤖 Generated with Claude Code

https://claude.ai/code/session_012Jmn7r23UyoxCG5saYMrgG

Strategies trusted whatever token `authorize` returned. Whoever controls
the auth URL (an injected CS_CTS_HOST, a compromised dependency, a
poisoned token store) could hand the client a token with any scopes and a
`services` claim pointing key requests at a rogue ZeroKMS.

`verify_tokens()` on the access-key, OIDC federation, device-session and
auto strategy builders now checks every token before `get_token` returns
it: RS256 signature under a key from `<issuer>/.well-known/jwks.json`,
`iss`, `exp` (60s leeway) and, when an audience was requested, `aud`. The
trusted issuer is the CTS that service discovery names for the region,
pinned separately from `base_url` and CS_CTS_HOST; `trusted_issuer(url)`
pins another. The JWKS is cached for an hour and refetched early for an
unknown `kid` at most once a minute.

RSA verification uses aws-lc-rs natively and RustCrypto's `rsa` on
wasm32, where aws-lc-rs does not build; the host tests run both backends
against the same vectors. Verification is opt-in until the live check
added to tests-golang.yml confirms CTS matches these assumptions.

Refs CIP-5080

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012Jmn7r23UyoxCG5saYMrgG
…through an outage

A failed fetch never moved the refetch clock, so a JWKS outage turned
every get_token into a request to CTS. Attempts are now limited to one a
minute whether they succeed or fail, and a key already cached still
verifies when a refresh fails. An unreadable JWKS is a request error,
not the token's. The refused-algorithm log no longer quotes the token's
alg, the unverified header and claims are named as such, and the OIDC
comments the ticket cites now say it is the provider's JWT that the
client cannot verify.

Refs CIP-5080

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012Jmn7r23UyoxCG5saYMrgG
Kills the surviving mutants in the token verifier: an hour-literal cache
test, one JWK filter at a time, a 4096-bit key on both RS256 backends,
and distinct refusal reasons. The wasm32 RS256 dispatch is excluded as
unreachable in the host build, and the wasm32 detect_inner exclusion
follows its new line.

Refs CIP-5080

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012Jmn7r23UyoxCG5saYMrgG
@coderabbitai

coderabbitai Bot commented Nov 16, 2026

Copy link
Copy Markdown
Contributor

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

  • Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

@changeset-bot

changeset-bot Bot commented Nov 16, 2026

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 5390894

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 19 packages
Name Type
@cipherstash/auth Patch
stash Patch
@cipherstash/stack Patch
@cipherstash/wizard Patch
@cipherstash/ffi-integration-tests Patch
@cipherstash/basic-example Patch
@cipherstash/e2e Patch
@cipherstash/bench Patch
@cipherstash/stack-drizzle Patch
@cipherstash/stack-prisma Patch
@cipherstash/stack-supabase Patch
@cipherstash/test-kit Patch
@cipherstash/prisma-example Patch
@cipherstash/auth-darwin-arm64 Patch
@cipherstash/auth-darwin-x64 Patch
@cipherstash/auth-linux-arm64-gnu Patch
@cipherstash/auth-linux-x64-gnu Patch
@cipherstash/auth-linux-x64-musl Patch
@cipherstash/auth-win32-x64-msvc Patch

Not sure what this means? Click here to learn what changesets are.

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

@github-actions

Copy link
Copy Markdown
Contributor

Mutation testing (cargo-mutants, --in-diff, stack-auth + stack-encrypt)

caught missed unviable timeout
41 0 47 0

Every mutant in the changed lines was caught by a test.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants