packages/session that parses key sets, mints and verifies every token class, and builds the public JWKS. It is one of
the Tuturuuu session slices.
Entry points and the boundary
@tuturuuu/session/verifystays free of signing. It never imports./tokens, and the boundary test keeps rejecting ECDSAsignandgetRandomValuesin the graphs of./verify,./cookieand the expiry module.@tuturuuu/session/tokensis a new entry point. It signs only with aCryptoKeyits caller passes in, and drawsjtibytes from an injectedRandomSource, so it calls no global random function. The boundary test scopes its no-signing rule by entry point instead of scanning every export, and asserts that no entry other than./tokensreaches./tokens.verifyIdentityAssertionkeeps its name, option names and failure-reason union, and becomes the identity case ofverifyToken. Itskeysoption changes type to the key lookup below, so the production identity path checks class and lifetimes. The existing negative tests run through the fenced test adapter.- Key lookup. One lookup,
get(kid): Promise<{ key, class, notBefore, notAfter } | null | 'unavailable'>, servesverifyToken,verifyIdentityAssertionand slice 2b’s step-up verification. Key acceptance runs after the payload is parsed, so the class,iat >= notBeforeandnow < notAfterare checked against the token. An adapter from a bareCryptoKeyexists only inside the fenced test issuer, takes explicit finite lifetimes with no open default, and a boundary assertion keeps it unreachable from every other entry point. - Durations in this page are seconds: a day is 86,400, 7 days 604,800 and
90 days 7,776,000. They are not the core’s millisecond
DAY_MS, and every comparison uses a seconds clock.
Key sets
TTR_TOKEN_SIGNING_KEYS (signer) and the internal key set given to verifiers
share one JSON shape, parsed by parseKeySet(json, { mode, now }) with the
core’s parseStrictJson. In signer mode it also takes the signer’s
observation rows and emergencyKids, and computes each key’s mintableAt:
-
Document and entry failures. A document that is not strict JSON in the
KeySetshape fails as a whole and its key source returnsunavailable, which fails closed askeys_unavailable. Inside a valid document, an entry that breaks a rule below is disabled alone; the rest of the set, anddeniedKids, still apply. If the disabled entry is a signed class’sactivekey, that class stops minting. - One key, one class. A key belongs to exactly one class. The key source for a class returns only that class’s keys.
-
Threat model. Key-set configuration is trusted input. Anyone who can
write
TTR_TOKEN_SIGNING_KEYSalready holds the private keys, sodeniedKidsin that same document cannot stop them; that case is covered by secret custody and by the separately deployed verifier configuration. The 7-day pre-publication rule from the parent design is a propagation rule, enforced only by the honest signer, so verifiers never depend on it. It gives every verifier a window to load a key before tokens signed with it appear; a verifier still without the key after the window fails closed withunknown_key. Early signatures by someone who already holds a private key are an accepted residual, not something this rule prevents. -
Observation port.
KeyObservationStoreis an injected port, so 2a stays pure and is tested with a fake. It offers an insert-only get-or-create of a(class, kid, thumbprint)row time-stamped by the store’s own clock, and one transaction that marks the first row of a class as its bootstrap key. The thumbprint is SHA-256 over the RFC 7638 canonical JSON ofcrv,kty,xandyonly, encoded as base64url without padding. Akidwhose thumbprint differs from its row is a different key with its own row. The Durable Object adapter, who may administer it, and cache durability belong to slice 4. -
Verifier registry. Each class has a closed list of verifier
deployments, owned by that class’s verifier owner and never by the identity
that writes
TTR_TOKEN_SIGNING_KEYS:- identity: the gateway’s effective mount inventory (its mounted paths and mount bindings, merged with the live bindings), owned by the gateway release;
- realtime, s2s, access and step-up: their verifier Workers, each listed by its owning release.
-
Census. The host refreshes the reports and a public fetch of
/.well-known/jwks.jsonin the background and hands the pure module the last successful census with its time.mintTokennever fetches. A census older than 300 seconds, the same bound as the public JWKS cache andkiddenial, fails closed; a failed refresh keeps the last success only until that cap. -
Publication evidence.
publicationHolds(entry, { registry, census, now })is true only when:- the class’s
registryis non-empty andcensusis at most 300 seconds old; - the census holds exactly one report for every registered deployment and none for anything else (a missing, extra or duplicate report fails);
- each report is the public key bundle that deployment actually loaded, and
the census’s JWKS is the public fetch of
/.well-known/jwks.json, neverjwksDocument()’s own return value; - for each of them, the reducer parses the key, recomputes its thumbprint
from
crv,kty,xandywith the function above, ignores any thumbprint field on the document, and finds the same(kid, thumbprint).
publicationHoldsis true, and the row’s store time is itspublishedAt. The document’spublishedAtfield is untrusted and never an input tomintableAt; the only rule on it is that a value later thannowdisables the entry. How slice 4 collects the reports is part of its design. - the class’s
-
Minting time.
mintableAtismax(notBefore, publishedAt + 7 days)for an ordinary key. The class’s bootstrap key and an armed emergency key skip only the 7 days. Every mint, for every key, also requirespublicationHoldsagainst the last census, so a deployment added or rolled back after the row was written stops minting, at the latest at the next refresh, until it holds the key again. -
Store errors. The signer caches only rows the store has committed, never
a local election, and a store error fails closed for any key whose committed
row is not cached. That is the pure module’s rule. Slice 4 must persist
committed rows across isolates and keep minting from that persisted cache
when the store errors, so a store outage during a deploy cannot stop
authentication; only a key with no persisted row stays blocked. The adapter
stamps
publishedAtfrom the store’s clock: no caller supplies it, and the identity that writesTTR_TOKEN_SIGNING_KEYScannot insert or backdate rows. -
Emergency keys. Only the signer reads
TTR_TOKEN_EMERGENCY_KIDS, a separate configuration with at most onekidper class, owned by a different deploy identity from the one that writesTTR_TOKEN_SIGNING_KEYS. An armedkidskips only the 7-day wait, and only when it is already its class’s singleactivekey inside the signing window. A listedkidthat is unknown,next, retired, of the wrong class or a second one for its class is ignored alone. Verifiers are unaffected, because they never apply the delay. -
Conflicts. Two
activekeys in one class, or two entries with onekid, disable all of the conflicting entries, and that class stops minting. AretiredAton an entry whose status is notretireddisables the entry, so a half-applied retirement cannot keep a key signing. -
Windows. A key signs for at most 90 days after its
notBefore. A non-retired key’snotAfteris exactlynotBefore + 90 days + maxLifetime(class) + 1 day, wheremaxLifetimeis the class’s largest cap (600 s for realtime); one second off disables the entry. Aretiredkey hasretiredAt, and itsnotAfterismin(notBefore + 90 days + maxLifetime(class) + 1 day, retiredAt + maxLifetime(class) + 1 day), so retiring a key never lengthens its verification window; any other value disables the entry. -
Emergency rotation.
deniedKidsin the verifier configuration is the emergency stop. An armed emergency key skips only the 7-day wait: it signs as soon as every registered deployment and the served JWKS report it. -
Signer mode is configured with the classes it signs, all read from
TTR_TOKEN_SIGNING_KEYS. Each signed class has at most oneactiveand at most onenextkey carrying aprivateJwkwhose public half matchespublicJwk; aprivateJwkon aretiredkey disables that entry.mintTokenuses only the class’sactivekey whilemintableAt <= now < min(notBefore + 90 days, notAfter), never anextkey, and refuses that class alone when no such key exists. -
Verifier mode disables any entry carrying a
privateJwk. A class may have no usable active key; its non-deniednextandretiredkeys still verify under the rules below, so a lapsed active key never takes valid retired keys with it. Verifiers read only their configured key set; they have no store dependency at parse time or on the token path, and a cold start needs only that configuration. -
Key acceptance. A verifier accepts a key for a token only when the class
matches, the
kidis not denied,now < notAfter, andiat >= notBefore. Anextkey is accepted under the same rule, which is what lets a signer promote it without a verifier configuration push. -
Denial. A
kidindeniedKidsis removed before any other rule runs. A denied, expired, not-yet-valid or unknownkidresolves tounknown_key, the same reason a key source returningnullgives today.
Public JWKS
jwksDocument(set, now) returns next, active and retired keys before
their notAfter, minus deniedKids. Each JWK carries kty, crv, x, y,
kid, use: "sig", alg: "ES256", ttr:class, nbf (the key’s
notBefore) and exp (its notAfter). A JWKS-fed verifier rejects a key
whose ttr:class, nbf or exp is missing, or whose class differs from the
class it verifies, and applies the key acceptance rule above with nbf and
exp. exp is only the bound a stale cache can never extend past; it is not
a denial channel. JWKS consumers refetch under the parent’s
Cache-Control: public, max-age=300 and drop any kid no longer listed, which
is how a denied key stops verifying within 5 minutes.
Claim profiles
Every class uses the identity verifier’s encoding rules: the token is at most 4 KiB; three canonical base64url segments; header members exactlyalg,
typ and kid; strict JSON with duplicate members rejected, __proto__ parsed as an
ordinary member (and then rejected as unknown by the closed member set), and
canonical numbers; aud a single string; iat <= now + 5, exp > iat
and now < exp.
verifyToken(class, token, { issuer, environment, audience, keys, now, ...classOptions })
pins alg: ES256 and the class’s typ, rejects every member outside the
class’s closed set, including unknown nested members, and applies key
acceptance. It rejects an iss, env or aud that differs from the
configured value with the identity reasons issuer, environment and
audience, and checks that the configured audience has the class’s shape.
Class options supply the other expected values: realtime takes the expected
topic, access takes the scope and client registries, and s2s takes the
service registry. mintToken checks the same registries. For s2s it takes
caller, the minting Worker’s own service identity supplied by its host, and
signs only when sub and azp both equal caller.
mintToken(class, claims, { keySet, observations, emergencyKids, census, caller, random, now })
takes the parsed signer key set, selects the class’s mintable active entry
itself, and refuses when there is none; callers never pass a bare key. It
applies the same profile and member types before signing and refuses a
violation instead of signing it.
Member types for every class: jti is 16 bytes in canonical base64url; a
user sub is a canonical lowercase UUID; sid and gen follow the identity
profile.
ws is required. An empty array grants no workspace access; there is no
omitted or wildcard form. The ttr+access lifetime follows the parent token
table; the rollout page’s open question on that lifetime stays open, and the
cap is one constant that a decision would change.
What 2a does not close
2a makes every verifier reject denied and expired keys the same way. The rest of G5, which is the risk decision on the ordinary-read bound, uncached checks for mutations and issuance with their outage behavior, and the end-to-end emergencykid denial test, belongs to slice 4.
Tests
Mint and verify every class. Prove cross-class rejection in both directions for every pair, including s2s against step-up. Reject denied, expired, not-yet-valid and wrong-class keys through both the internal key set and the JWKS, including a JWK with nottr:class, nbf or exp, and a cached JWK
past its exp. Pin the wait: accept at publishedAt + 604800, reject at
publishedAt + 604799. Reject publication for an empty registry, an empty report list, a census
older than 300 seconds, two of three registered deployments, and when only jwksDocument() output
contains the key. Prove a retired identity key past its notAfter and a key
of another class both fail through verifyIdentityAssertion itself. On the
signer, refuse to mint before 7 days of publication,
including with a backdated notBefore or publishedAt or a reused kid
with a new thumbprint, and before both the JWKS and the internal verifier set
contain the key, using the served document rather than jwksDocument()
output and every deployed verifier set; skip only the 7 days for the
bootstrap key and an armed emergency active key, still after both
observations; ignore an armed next key; keep minting with cached committed
rows during a store outage, and stop on a cold start. A verifier set without
a kid returns unknown_key for a token signed after the 7 days. Two active
keys, a duplicated kid and a stray retiredAt disable the entries named
above, and a notAfter one second off the formula is rejected. Reject a wrong
iss, env, aud and realtime topic in both directions, an unregistered
scope, client or service, an s2s token whose sub and azp differ or name
a service other than caller, and a
malformed jti or sub. Verify that a retired key past its notAfter
fails through the production identity entry point. A bad entry, or a bad
emergency list entry, disables only itself. Refuse to mint with a next key or past 90 days. Accept a next key only for
iat >= nbf. Keep verifying a retired key after the active key lapses.
Reject realtime tickets over the cap for their topic kind, an access token
without ws, and every unknown member. Run the identity verifier’s existing
encoding negatives against every class.