feat: surface a CipherStash usage-limit refusal with a code and a remedy - #894

Summary

CipherStash meters usage per organisation. When one goes over its allowance, the CipherStash Token Service — the component that issues the short-lived token behind every encrypt and decrypt — stops issuing tokens and answers 402 Payment Required.

Until now that reached a caller as an untyped error carrying one sentence of prose. Nothing in it said which organisation was affected, where to fix it, or that the condition was permanent, so a client retrying on failure — the sensible default — would retry forever against something only a human with a billing page can clear.

A refusal now arrives as a typed, branchable thing: authCode says what it is, message says what to do, and url says where. Two codes mean "stop": USAGE_LIMIT_EXCEEDED (over the allowance, upgrade the plan) and ORG_NOT_PROVISIONED (not registered for billing at all, which needs support, not a purchase). Telling the second to upgrade sends the user somewhere that cannot help them, which is why they are separate codes rather than one.

Changes

@cipherstash/protect-ffi — the Rust/JavaScript boundary

• A thrown error now sets authCode, help and url alongside the existing code, on both bindings and on each item of a partial bulk decrypt. getAuthErrorCode() reads it back; ProtectAuthErrorCode types it.
• authCode is a separate field from code because the two sets have different owners. code is this package's own closed set, pinned by a test against the Rust source. The auth set belongs to the upstream stack-auth crate and grows on its own release schedule, so ProtectAuthErrorCode is deliberately open — compare with ===, do not switch exhaustively over it.
• A failure raised by a caller-supplied config.authStrategy has its own type, help and url relayed verbatim rather than rebuilt from the pinned crate's enum, which maps only ten of twenty-one codes and would replace a strategy's own remedy with someone else's.
• Client crates move to 0.42.3 (cipherstash-client, cts-common, stack-auth, stack-profile — they release together). That release is where the whole taxonomy comes from.

@cipherstash/stack

• Every failure that came from the token service carries authCode, with the remedy folded into message and the link on url.
• The remedy text is upstream's. stack-auth 0.42.3 attaches a help and a url to both terminal refusals, so this package prefers those and keeps its own copy only as a fallback for the one path that cannot receive them. A config.authStrategy supplying its own help is honoured rather than overridden.
• Diagnostics (code, authCode, help, url) are attached by one shared helper rather than enumerated at each of twenty failure mappers. Enumeration is how two of the four went missing before: help reached a caller only as prose and url by no path at all.
• LockContext.identify() is fixed. It calls the token service directly, so a 402 was not an exception — it fell through to a body with no token and reported "the response did not contain an access token, please contact support", which is the misleading message this PR exists to remove.

stash (CLI)

• auth login and env print the remedy, and no longer answer a billing refusal with "run stash auth login and try again" — a fresh login cannot mint a credential being withheld on billing grounds.
• env reports the terminal refusals under their own --json codes rather than session_invalid or not_logged_in. code is the only machine-readable field on that stream, so reporting a stale session sends an automated caller round a re-login loop it cannot win.
• The --json error envelope gains an optional hint, previously printed only on the interactive path — absent for exactly the automated consumers --json exists for.

@cipherstash/nextjs

• getCtsToken() reported a failure as Failed to fetch CTS token: and nothing else: it read statusText, which is empty over HTTP/2, and discarded the body along with any code in it. It now names the status, quotes what the service said, and surfaces authCode.

Skills and changesets — stash-auth (canonical for auth), stash-cli and stash-encryption updated; four changesets.

One detail worth knowing: how a refusal is read off the wire

Three places read a 402 themselves — the Rust client, LockContext.identify(), and the Next.js helper. They now follow the same rules, because three readers disagreeing about one response is a bug waiting to happen:

• The status decides, not the body. The OAuth token endpoints must report a usage refusal as access_denied to stay standards-compliant, so the body alone cannot say what it is.
• A 402 carrying a refusal is JSON, with the code in a cs_code field. Every other failure from that endpoint is plain text, so the body is read as text exactly once and parsed defensively — calling .json() on a 401 throws a parse error that replaces the real failure.
• A 402 that is not valid CipherStash JSON is declined, not classified. That is a proxy, WAF or gateway answering in front of the service, and reporting it as a billing problem sends the user to a billing page for something a retry would have cleared.

Verification

CI on this branch: 25 checks pass, 0 fail (10 skip — they are gated on packages/eql/, which this branch does not touch).

Locally, against a protect-ffi binding compiled fresh at 0.42.3:

• @cipherstash/stack — 1220/1220, including the 159 live tests that talk to real CipherStash infrastructure with credentials. That live run is what clears the other half of 0.42.3: it also makes ZeroKMS require an org_id claim on every token, and real encrypt/decrypt/keyset/audit round-trips pass.
• Rust — 332 tests, cargo fmt --check clean.
• @cipherstash/protect-ffi (JS) — 105.
• @cipherstash/nextjs — 24.
• stash — the auth and env suites, 107.
• Repo guards — the remedy-copy sync check and the parked-changeset check, 10.
• pnpm run code:check exits 0.

Stated rather than omitted: the full stash suite fails 21 tests locally, all of them resolving @cipherstash/eql/sql. That is a build output this working copy does not have; the identical failure reproduces on main, and CI builds it, which is why CI is green. It is unrelated to this change.

Related

Refs cipherstash/cipherstash-suite#2120 — the server-side half, which defines the taxonomy and the response bodies this PR reads.

Review notes

Start at packages/stack/src/encryption/helpers/auth-failure.ts (what the remedy is and where it comes from) and packages/stack/src/identity/index.ts (how a 402 is classified). The three commits are split by layer — boundary, SDK, consumers — and each stands on its own; reviewing in order should read as one argument.

Not live yet, and no follow-up needed here. Two of the four surfaces reach the token service through the npm package @cipherstash/auth rather than the Rust client: a config.authStrategy you construct yourself, and the stash CLI. Its latest release predates the taxonomy, so those paths still see a generic server error until it ships. The code is already correct for that release and starts reporting the codes the moment it lands. Everything going through the Rust client is live today.

Deliberately deferred:

• packages/wizard has two sites that still read only failure.error.message and drop help. Same one-line defect, different published package; left out to keep this reviewable.
• stash auth login reports USAGE_LIMIT_EXCEEDED on --json where stash env reports usage_limit_exceeded. Real inconsistency, but login's code for an auth failure has always been the raw type, which predates this work and covers every code rather than these two. Collapsing the spellings changes an existing machine-readable contract and belongs in its own change.
• Two things worth asking upstream for: the crate knows which failures are retryable but does not expose it across the boundary, so the CLI still hardcodes which codes are terminal; and the upstream help for USAGE_LIMIT_EXCEEDED ends "then retry", which reads as the wrong signal without the upgrade clause in front of it.