@stonyx/oauth 0.1.1-beta.185 → 0.1.1-beta.187

package/README.md

@@ -47,6 +47,9 @@ By default no providers are enabled. Add providers as keys in the `providers` ob
 |--------|---------|-------------|
 | `providers` | `{}` | Map of provider name to config |
 | `sessionDuration` | `86400` | Session TTL in seconds (default: 24h) |
+| `frontendCallbackUrl` | `null` | Where `GET /auth/callback/:provider` sends the browser after a successful login. **Setting this changes the callback's response shape**: unset, the callback returns `{ sessionId, expiresAt }` as a JSON body; set, it issues a `302` to this URL carrying a single-use exchange ticket in the fragment, which the landing page redeems at `POST /auth/session`. See [Session delivery](#session-delivery--the-exchange-ticket). |
+
+`TICKET_TTL_MS` (60s, the exchange ticket's lifetime) and `STATE_TTL_MS` (600s, the `oauth_state` lifetime) are module constants with no config key today. If your landing page cannot reach its earliest hook inside 60 seconds on a cold boot, the exchange returns `400` and the login dies — see [stonyx-oauth#59](https://github.com/abofs/stonyx-oauth/issues/59).
 
 ## Routes
 
@@ -56,7 +59,8 @@ The module self-registers the following routes on the rest server:
 |--------|-------|-------------|
 | `GET` | `/auth` | Validate session — send `session-id` header, returns user or 401 |
 | `GET` | `/auth/login/:provider` | Redirects to provider's OAuth2 authorization page |
-| `GET` | `/auth/callback/:provider` | OAuth2 callback — exchanges code for tokens, creates session |
+| `GET` | `/auth/callback/:provider` | OAuth2 callback — exchanges code for tokens, creates session, redirects with a single-use `ticket` in the URL **fragment** |
+| `POST` | `/auth/session` | Redeems the `ticket` for the session id — `application/json`, `{ "ticket": "..." }` |
 | `GET` | `/auth/logout` | Destroys session (send `session-id` header) |
 
 ## Officially Supported Providers
@@ -118,7 +122,7 @@ providers: {
 
 ## Login CSRF protection — the `oauth_state` cookie
 
-### Breaking changes
+### Breaking changes (#36)
 
 **As of the fix for [#36](https://github.com/abofs/stonyx-oauth/issues/36).** Two separate breaks — an integration can hit either one independently.
 
@@ -176,6 +180,8 @@ await fetch(`${host}/auth/callback/discord?code=${code}&state=${state}`, {
 });
 ```
 
+That callback now answers `302` with an exchange ticket in the `Location` fragment rather than a session id. A scripted client continues by reading the ticket out of the fragment and redeeming it — see [Migration](#migration) under Session delivery for the exchange step. A server-to-server client can do this perfectly well; the "cannot complete a login at all" row in the #45 break table is about clients that cannot issue a cross-origin `POST` from a browser, not about scripted ones.
+
 In a browser, `fetch` needs `credentials: 'include'` for a cross-origin request — but see the CORS caveat above; a top-level navigation is the supported path.
 
 ### Concurrent logins in the same browser
@@ -184,11 +190,124 @@ The cookie name is fixed and its `Path` is `/`, so a second login started in the
 
 This fails closed — no session is minted for the wrong flow, and it is not a way past the binding — but it is an availability regression against the previous behaviour, where two concurrent logins both completed. A user who opens two login tabs has to finish in the one they started last, or retry.
 
+## Session delivery — the exchange ticket
+
+### Breaking changes (#45)
+
+**As of the fix for [#45](https://github.com/abofs/stonyx-oauth/issues/45).** This is a break in the **HTTP contract**, not in the JS API.
+
+`GET /auth/callback/:provider` no longer redirects with `?sessionId=`. It redirects with a single-use, 60-second ticket in the URL **fragment**, which is exchanged for the session id over a JSON `POST`:
+
+```
+GET  /auth/callback/:provider  ->  302 <frontendCallbackUrl>#ticket=<opaque>&expiresAt=<ts>
+POST /auth/session             <-  {"ticket":"<opaque>"}     Content-Type: application/json
+                               ->  200 {"sessionId":"<uuid>","expiresAt":<ts>}
+                                   Cache-Control: no-store
+                               ->  400 on an unknown, spent, expired or unparseable ticket
+```
+
+The success redirect carries **no query string at all**. Read the ticket from `location.hash`, not `location.search`. The failure redirect is unchanged and still uses the query (`?error=auth_failed`) — an error code is not a credential.
+
+**Who this breaks, and how:**
+
+| Party | What breaks |
+|---|---|
+| **Any client reading `?sessionId=` off the callback redirect** | Gets `undefined`. The redirect no longer carries a session id under any name, in the query or the fragment. |
+| **Any client reading the callback redirect's query at all** | Gets an empty query on success. Both the ticket and `expiresAt` are in the fragment. A server-side reader **cannot** see either — that is the point, and it is why a browser-side handler is required. |
+| **Any client that cannot issue a cross-origin `POST`** | Cannot complete a login at all. The exchange is the only way to obtain a session id when `frontendCallbackUrl` is configured. |
+| **Form-encoded callers** | `@stonyx/rest-server` installs `express.json()` only, so a form-encoded body arrives unparsed and the exchange returns `400`. The request **must** be `application/json`. |
+| [`abofs/stonyx-dashboard`](https://github.com/abofs/stonyx-dashboard) | `demo-app/routes/auth/discord-callback.js` reads `?sessionId=`. Tracked at [stonyx-dashboard#103](https://github.com/abofs/stonyx-dashboard/issues/103), which must land before that consumer bumps. |
+| `lynxury/backend` | `test/integration/05-oauth-bypass-test.js` reads `?sessionId=` from the callback redirect. Reds when it bumps off `@stonyx/oauth@0.1.1-beta.157`. |
+| `lynxury/dashboard` | Bumps its `@stonyx/dashboard` commit pin after #103 lands. |
+
+### Deployment prerequisites — the server's own CORS configuration
+
+This is the half that breaks on the **server** rather than in the consumer's code, and it fails as a browser console CORS error against a server that logs nothing.
+
+Before #45 this module served only `GET`. A deployment that had hardened `REST_CORS_METHODS=GET` was correct and lost nothing. After #45 that same deployment has **no working login at all**: the browser refuses the preflight for `POST /auth/session` and never sends the exchange, and with the session id no longer in the URL there is no fallback path.
+
+| Setting | Required value | Why |
+|---|---|---|
+| `REST_CORS_METHODS` | must include `POST` | Default is `GET,POST,PATCH,PUT,DELETE`, which is fine. A narrowed value that omits `POST` kills every login. `@stonyx/rest-server` answers the preflight in middleware before routing, so the server returns `204` either way — the failure is visible only in `Access-Control-Allow-Methods`. |
+| `REST_CORS_ORIGIN` | the frontend origin | Default is `*`. `POST /auth/session` hands out a session id, so under `*` any origin holding a ticket can redeem it and read the result from script. Pin it to the origin serving your `frontendCallbackUrl`. |
+
+`test/integration/oauth-test.ts` AC5 asserts both the preflight's `access-control-allow-methods` and the real cross-origin `POST`, so a regression here reds rather than passing silently.
+
+**Unaffected.** The `session-id` **header** contract is unchanged: `GET /auth` and `GET /auth/logout` still authenticate from it, and everything in the [`oauth_state` binding](#login-csrf-protection--the-oauth_state-cookie) is untouched. What changed is how the session id is *delivered once*, not how it is *used afterwards*. The JS API is unchanged — `handleCallback` still returns `{ sessionId, expiresAt }`, and a deployment with **no** `frontendCallbackUrl` configured still gets the session object as the callback's response body, because that is a direct response rather than a value written into a URL.
+
+### Why
+
+The session id is the bearer credential — `GET /auth` authenticates from exactly that value. Delivering it as a query parameter wrote a live 24-hour credential into:
+
+- browser history and the address bar,
+- the `Referer` header on any outbound link from the landing page,
+- proxy, CDN and server access logs,
+- `location.search`, readable by every script on the landing page.
+
+Putting the ticket in the **fragment** rather than the query removes the middle two outright, for every deployment, with no configuration. A fragment is never transmitted to any server by any user agent: it does not appear in the frontend's own access logs, in any reverse proxy or CDN in front of the landing page, or in `Referer` under any referrer policy.
+
+What the fragment does **not** remove is browser history and readability by page scripts (`location.hash` instead of `location.search`). Those are the app's own to close and nothing in front of the app can close them — no proxy can unwrite a URL the app chose. They are why the ticket is still single-use and 60-second rather than a long-lived value, and why the migration below scrubs it with `history.replaceState`.
+
+### Ticket properties
+
+| Property | Value | Why |
+|---|---|---|
+| Lifetime | **60 seconds** | One redirect plus one page load. Two orders of magnitude tighter than the 600s state TTL, because unlike the state this value travels in a URL — in the fragment, so not to any server, but still into history and into page scripts. |
+| Uses | **exactly one** | Consumed on recognition, before the TTL is checked, so every ticket gets one attempt whatever the outcome and the route is not a repeatable oracle. |
+| Entropy | 32 random bytes, base64url | Independent of the session id, never derived from it. |
+| Authenticates | **nothing** | `GET /auth` validates against the session store, which has never heard of the ticket. A ticket in a `session-id` header is a `401`. |
+| Failure modes | one indistinguishable `400` | Unknown, spent, expired and unparseable are not told apart. |
+| Server-side storage | **keyed by the ticket digest** | The store is keyed by the SHA-256 of the ticket, never by the ticket, so the map holds no redeemable *ticket*: a reader of the map gets a digest, and a digest cannot be presented to the exchange. **It does still hold the live `sessionId` in plaintext, in the record value**, so the map is sensitive and must not be dumped or logged. Note this is the mirror image of the `oauth_state` binding rather than the same shape: `pendingStates` is keyed by the plaintext state and keeps the digest (`bindingHash`) in the value, so that record unlocks nothing on its own; here the digest is the key and the value is a live credential. Both share the discipline of never storing the client-presented secret in the clear. No constant-time compare is needed: lookup is a hash probe on a 256-bit key, not a secret-dependent byte comparison. |
+| Exchange response | `Cache-Control: no-store` | The `200` body is the session id. A `POST` is not cacheable without explicit freshness, so this is defence in depth — no intermediary or service worker retains the credential. |
+
+### Known residual risk
+
+**This is a reduction, not an elimination.** A ticket observed in the sub-second window *before* the landing page redeems it is redeemable by the observer. What the change buys is the difference between a live 24-hour credential permanently written into history and a one-shot token that is already spent by the time the page renders.
+
+Closing the window means binding the ticket to the client that started the flow, the way [#36](https://github.com/abofs/stonyx-oauth/issues/36) bound the `state`. That binding has to travel on a cookie, and the exchange is cross-origin, so the cookie cannot be sent without `credentials: 'include'`.
+
+The blocker is [**`abofs/stonyx-rest-server#63`**](https://github.com/abofs/stonyx-rest-server/issues/63) — `@stonyx/rest-server` calls `cors({ origin, methods })` and has no `credentials` support at all: no `credentials: true`, no `REST_CORS_CREDENTIALS`. A cookie-bound exchange is impossible until that lands, and it will also require pinning `REST_CORS_ORIGIN`, since `*` with credentials is spec-forbidden.
+
+It is **not** blocked on [`abofs/stonyx-rest-server#45`](https://github.com/abofs/stonyx-rest-server/issues/45) (*"no supported way for a route handler to set a response header"*). That gap is real but is an ergonomics dependency, and it is already worked around in this very file — `setBindingCookie`/`clearBindingCookie` set and clear cookies on a redirect today by reaching through `req.res`. Closing #45 would not make this residual closeable. **That risk belongs to the rest-server layer.** Revisit when #63 lands.
+
+An abandoned ticket is never garbage-collected, the same pre-existing limitation `pendingStates` has. It is bounded by a 60-second TTL rather than a 600-second one. Both maps are tracked at [stonyx-oauth#43](https://github.com/abofs/stonyx-oauth/issues/43), which names each site so a fix cannot sweep one and leave the other.
+
+### Migration
+
+Read the `ticket`, exchange it, and scrub the URL:
+
+```javascript
+// On the landing page at your `frontendCallbackUrl`, before first paint.
+// The ticket is in the fragment, not the query — `location.hash`, not
+// `location.search`. `.slice(1)` drops the leading `#`.
+const params = new URLSearchParams(location.hash.slice(1));
+const ticket = params.get('ticket');
+
+const response = await fetch(`${host}/auth/session`, {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },  // form-encoded will 400
+  body: JSON.stringify({ ticket }),
+});
+
+if (!response.ok) throw new Error('login failed');  // unknown, spent or expired
+
+const { sessionId, expiresAt } = await response.json();
+
+// The ticket is spent, but do not leave it in the address bar or in history.
+// The fragment kept it away from every server; `replaceState` is what keeps it
+// out of this browser's history and away from later scripts on the page.
+history.replaceState({}, '', location.pathname);
+```
+
+Then send `sessionId` as a `session-id` header exactly as before.
+
+Exchange promptly — the ticket is valid for 60 seconds. Do it in the earliest hook your framework offers (`beforeModel` in Ember, a loader in Remix or React Router), not after the page has rendered.
+
 ## Session Management
 
 Sessions are stored in-memory using a `Map`. Sessions are lost on server restart.
 
-Clients should store the `sessionId` returned from the callback and send it as a `session-id` header on subsequent requests.
+Clients obtain the `sessionId` by redeeming the callback's exchange ticket at `POST /auth/session` — see [Session delivery](#session-delivery--the-exchange-ticket) — and send it as a `session-id` header on subsequent requests. It is never delivered in a URL.
 
 ## License
 

package/dist/auth-request.d.ts

@@ -15,6 +15,14 @@ interface OAuthInstance {
         sessionId: string;
         expiresAt: number;
     }>;
+    issueExchangeTicket(session: {
+        sessionId: string;
+        expiresAt: number;
+    }): string;
+    redeemExchangeTicket(ticket: string): {
+        sessionId: string;
+        expiresAt: number;
+    } | null;
     logout(sessionId: string): void;
 }
 export interface CookieOptions {
@@ -40,11 +48,25 @@ export interface CookieOptions {
 interface ResponseLike {
     cookie(name: string, value: string, options: CookieOptions): unknown;
     clearCookie(name: string, options: Omit<CookieOptions, 'maxAge'>): unknown;
+    /**
+     * Optional: every call site guards on it. `@stonyx/rest-server` hands the
+     * express response through untyped, and a test double need not implement the
+     * whole surface.
+     */
+    setHeader?(name: string, value: string): unknown;
 }
 interface RouteRequest {
     headers: Record<string, string | undefined>;
     params: Record<string, string>;
     query: Record<string, string>;
+    /**
+     * Parsed by `express.json()`, which `@stonyx/rest-server` installs globally.
+     *
+     * Optional and typed loosely because it is whatever an unauthenticated
+     * caller sent: a form-encoded body arrives as `null` and a bodyless request
+     * as `undefined`, so every read of it has to survive both.
+     */
+    body?: unknown;
     res?: ResponseLike;
 }
 interface RouteState {
@@ -63,6 +85,34 @@ export default class AuthRequest extends Request {
             } | 500 | 400 | undefined>;
             '/logout': ({ headers }: RouteRequest) => void;
         };
+        post: {
+            /**
+             * Redeems the exchange ticket from the callback redirect (#45).
+             *
+             * `POST` and not `GET` because a `GET` would put the ticket back in a
+             * URL — in the caller's history, in access logs — which is the defect
+             * this route exists to close.
+             *
+             * `application/json` and not form-encoded: `@stonyx/rest-server`
+             * installs `express.json()` only, so a form-encoded body arrives as
+             * `null` and the ticket is unreadable. Measured, not assumed.
+             *
+             * Unknown, spent and expired tickets are one indistinguishable `400`.
+             *
+             * `Cache-Control: no-store` because the `200` body is the session id —
+             * the bearer credential itself. A `POST` response is not cacheable
+             * without explicit freshness, so this is defence in depth rather than a
+             * live defect: it is there so that no intermediary, service worker or
+             * future `GET` variant of this route can retain the credential. Set
+             * through `req.res`, the same reach-through the binding-cookie helpers
+             * use, because `@stonyx/rest-server` has no supported way for a handler
+             * to set a response header (`abofs/stonyx-rest-server#45`).
+             */
+            '/session': (req: RouteRequest) => 400 | {
+                sessionId: string;
+                expiresAt: number;
+            };
+        };
     };
     /**
      * Whether the binding cookie is issued with `Secure`.

package/dist/auth-request.js

@@ -79,13 +79,37 @@ export default class AuthRequest extends Request {
                     // server-side, and their real callback then fails.
                     this.clearBindingCookie(req, providerName);
                     if (this.oauth.frontendCallbackUrl) {
+                        // The session id is the bearer credential (`GET /auth` above
+                        // authenticates from exactly this value), so it must not be
+                        // written into a URL: URLs land in browser history, in `Referer`
+                        // on any outbound link, in proxy and CDN access logs, and in
+                        // `location.search` for every script on the landing page. What
+                        // goes in the URL instead is a single-use 60-second ticket that
+                        // authenticates nothing, redeemed at `POST /auth/session` (#45).
+                        //
+                        // The ticket rides in the *fragment*, not the query. A fragment is
+                        // never transmitted to any server by any user agent: it is absent
+                        // from the frontend's own access logs, from every reverse proxy
+                        // and CDN in front of the landing page, and from `Referer` under
+                        // every referrer policy. That removes two of the four leak vectors
+                        // #45 names outright, for one character. What it does not remove
+                        // is browser history and readability by page scripts — those are
+                        // why the ticket is still single-use and 60-second, and why the
+                        // documented migration scrubs it with `history.replaceState`.
+                        //
+                        // `expiresAt` rides along in the same fragment rather than staying
+                        // in the query, so the consumer has one place to read from.
+                        // It is not a credential and nothing authenticates from it.
                         const params = new URLSearchParams({
-                            sessionId: session.sessionId,
+                            ticket: this.oauth.issueExchangeTicket(session),
                             expiresAt: String(session.expiresAt),
                         });
-                        state.redirect = `${this.oauth.frontendCallbackUrl}?${params}`;
+                        state.redirect = `${this.oauth.frontendCallbackUrl}#${params}`;
                         return;
                     }
+                    // No `frontendCallbackUrl` configured: the session is the response
+                    // body of a direct request, not a value handed to a browser through
+                    // a URL, so there is nothing here for #45 to fix.
                     return session;
                 }
                 catch {
@@ -101,7 +125,43 @@ export default class AuthRequest extends Request {
                 if (sessionId)
                     this.oauth.logout(sessionId);
             },
-        }
+        },
+        post: {
+            /**
+             * Redeems the exchange ticket from the callback redirect (#45).
+             *
+             * `POST` and not `GET` because a `GET` would put the ticket back in a
+             * URL — in the caller's history, in access logs — which is the defect
+             * this route exists to close.
+             *
+             * `application/json` and not form-encoded: `@stonyx/rest-server`
+             * installs `express.json()` only, so a form-encoded body arrives as
+             * `null` and the ticket is unreadable. Measured, not assumed.
+             *
+             * Unknown, spent and expired tickets are one indistinguishable `400`.
+             *
+             * `Cache-Control: no-store` because the `200` body is the session id —
+             * the bearer credential itself. A `POST` response is not cacheable
+             * without explicit freshness, so this is defence in depth rather than a
+             * live defect: it is there so that no intermediary, service worker or
+             * future `GET` variant of this route can retain the credential. Set
+             * through `req.res`, the same reach-through the binding-cookie helpers
+             * use, because `@stonyx/rest-server` has no supported way for a handler
+             * to set a response header (`abofs/stonyx-rest-server#45`).
+             */
+            '/session': (req) => {
+                const { body, res } = req;
+                if (typeof res?.setHeader === 'function')
+                    res.setHeader('Cache-Control', 'no-store');
+                const ticket = body?.ticket;
+                if (typeof ticket !== 'string' || !ticket)
+                    return 400;
+                const session = this.oauth.redeemExchangeTicket(ticket);
+                if (!session)
+                    return 400;
+                return { sessionId: session.sessionId, expiresAt: session.expiresAt };
+            },
+        },
     };
     /**
      * Whether the binding cookie is issued with `Secure`.

package/dist/main.d.ts

@@ -1,5 +1,8 @@
 import TokenManager from './token-manager.js';
 import SessionManager from './session-manager.js';
+import TicketStore from './ticket-store.js';
+import type { RedeemedTicket } from './ticket-store.js';
+import type { SessionResult } from './session-manager.js';
 import type OAuthFlow from './oauth-flow.js';
 /** Lifetime of a pending state, and the binding cookie's `Max-Age`. */
 export declare const STATE_TTL_MS: number;
@@ -34,6 +37,7 @@ export default class OAuth {
     pendingStates: Map<string, PendingState>;
     stateTtl: number;
     sessionManager: SessionManager;
+    ticketStore: TicketStore;
     frontendCallbackUrl?: string;
     constructor();
     init(): Promise<void>;
@@ -97,9 +101,20 @@ export default class OAuth {
      * `bindingValues` is every value the client presented under the binding
      * cookie's name — see `anyCandidateMatches`.
      */
-    handleCallback(providerName: string, code: string, stateToken: string, bindingValues: readonly string[]): Promise<import("./session-manager.js").SessionResult>;
+    handleCallback(providerName: string, code: string, stateToken: string, bindingValues: readonly string[]): Promise<SessionResult>;
     /** The provider's configured redirect URI, used to decide the cookie's `Secure`. */
     redirectUriFor(providerName: string): string | undefined;
+    /**
+     * Mints the value the callback redirect is allowed to put in a URL (#45).
+     *
+     * The session id never travels in the redirect. What travels is a ticket
+     * that is single-use, expires in 60 seconds, and authenticates nothing on
+     * its own — `GET /auth` validates against `sessionManager`, which has never
+     * heard of it.
+     */
+    issueExchangeTicket(session: SessionResult): string;
+    /** Spends a ticket for the session id it stands for, or `null`. */
+    redeemExchangeTicket(ticket: string): RedeemedTicket | null;
     getSession(sessionId: string): unknown;
     logout(sessionId: string): void;
 }

package/dist/main.js

@@ -6,6 +6,7 @@ import { setup, emit } from '@stonyx/events';
 import RestServer from '@stonyx/rest-server';
 import TokenManager from './token-manager.js';
 import SessionManager from './session-manager.js';
+import TicketStore from './ticket-store.js';
 import AuthRequest from './auth-request.js';
 setup(['authenticate']);
 /** Lifetime of a pending state, and the binding cookie's `Max-Age`. */
@@ -18,6 +19,7 @@ export default class OAuth {
     pendingStates = new Map();
     stateTtl = STATE_TTL_MS;
     sessionManager;
+    ticketStore = new TicketStore();
     frontendCallbackUrl;
     constructor() {
         if (OAuth.instance)
@@ -168,6 +170,21 @@ export default class OAuth {
     redirectUriFor(providerName) {
         return this.providers.get(providerName)?.flow.redirectUri;
     }
+    /**
+     * Mints the value the callback redirect is allowed to put in a URL (#45).
+     *
+     * The session id never travels in the redirect. What travels is a ticket
+     * that is single-use, expires in 60 seconds, and authenticates nothing on
+     * its own — `GET /auth` validates against `sessionManager`, which has never
+     * heard of it.
+     */
+    issueExchangeTicket(session) {
+        return this.ticketStore.issue(session.sessionId, session.expiresAt);
+    }
+    /** Spends a ticket for the session id it stands for, or `null`. */
+    redeemExchangeTicket(ticket) {
+        return this.ticketStore.redeem(ticket);
+    }
     getSession(sessionId) {
         return this.sessionManager.validate(sessionId);
     }

package/dist/ticket-store.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Lifetime of an exchange ticket.
+ *
+ * Sized for one redirect plus one page load, and deliberately two orders of
+ * magnitude tighter than the 10-minute state TTL: the ticket is a bearer value
+ * travelling in a URL, and the whole point of #45 is that a bearer value in a
+ * URL must not be long-lived — in the fragment, so it reaches no server, but
+ * still into browser history and readable by scripts on the landing page.
+ */
+export declare const TICKET_TTL_MS: number;
+/** Entropy of a ticket, in bytes. */
+export declare const TICKET_BYTES = 32;
+interface TicketRecord {
+    sessionId: string;
+    expiresAt: number;
+    createdAt: number;
+}
+export interface RedeemedTicket {
+    sessionId: string;
+    expiresAt: number;
+}
+/**
+ * Single-use, short-lived tickets that stand in for a session id on the wire.
+ *
+ * The callback redirect hands the browser a ticket instead of the session id
+ * (#45), in the URL *fragment*, which no user agent transmits to any server.
+ * The ticket authenticates nothing — `GET /auth` reads the `session-id` header
+ * and knows only about `SessionManager` — so a ticket observed in history or
+ * by a script reading `location.hash` is worth something only inside the
+ * sub-second window before the landing page redeems it, and nothing at all
+ * afterwards.
+ *
+ * Known residual, stated rather than papered over: a ticket observed *within*
+ * that window is redeemable by the observer, because nothing here binds a
+ * ticket to the client that started the flow. Closing it means binding the way
+ * #36 bound the state, and that binding has to travel on a cookie the
+ * cross-origin exchange cannot carry.
+ *
+ * The blocker is `abofs/stonyx-rest-server#63`: `@stonyx/rest-server` calls
+ * `cors({ origin, methods })` and has no `credentials` support at all. It is
+ * *not* `abofs/stonyx-rest-server#45` — that issue is the response-header half
+ * and is already worked around in `auth-request.ts`, which sets and clears the
+ * binding cookie on a redirect by reaching through `req.res`. Closing #45
+ * would not make this residual closeable. It is a reduction, not an
+ * elimination.
+ *
+ * Like `OAuth.pendingStates`, an abandoned ticket is never collected. That is
+ * a pre-existing pattern in this module, not something this store introduces,
+ * and it is bounded here by a 60-second TTL rather than a 10-minute one.
+ * Tracked, with both maps named, at `abofs/stonyx-oauth#43`.
+ *
+ * ---
+ *
+ * **Why this is a second store rather than a reuse of `OAuth.pendingStates`.**
+ *
+ * The duplication is real and is not an oversight: `pendingStates` is also a
+ * single-use, TTL-bounded, consume-on-recognition map keyed by a
+ * `randomBytes`-minted opaque token, with the same delete-before-TTL-check
+ * ordering and the same never-collected caveat. The shared shape could be
+ * extracted into one primitive, and the two constants homes (`STATE_TTL_MS`
+ * and `BINDING_VALUE_BYTES` in `main.ts`, `TICKET_TTL_MS` and `TICKET_BYTES`
+ * here) could then live together.
+ *
+ * It is deliberately not done in the change that fixes #45. Widening a
+ * security fix into a refactor of the CSRF store means the #36 binding
+ * mechanism — whose invariants are load-bearing and separately guarded — moves
+ * in the same commit as the fix, for no security gain in either. The two also
+ * do not have the same invariants: `pendingStates` is a security control fed
+ * by an unauthenticated `GET`, holding a *digest* of a client secret, with a
+ * 10-minute budget sized for a provider round trip; this is a delivery
+ * convenience reachable only after a successfully bound callback, holding a
+ * value it hands back, with a 60-second budget sized for a page load.
+ * Collapsing them would couple the control to the convenience.
+ *
+ * The extraction is tracked at `abofs/stonyx-oauth#58`.
+ */
+export default class TicketStore {
+    /**
+     * Live tickets, keyed by the **SHA-256 of the ticket**, never by the ticket.
+     *
+     * Keying by the digest means the map holds no redeemable *ticket*: a ticket
+     * is a client-presented secret looked up server-side, so what a reader of
+     * this map gets is a digest, and a digest cannot be presented to `redeem`.
+     *
+     * That does not make the map safe to expose. The record *value* holds a
+     * plaintext, live `sessionId` — the 24-hour bearer credential this store
+     * exists to keep out of URLs — so a heap dump, a debug serialisation or an
+     * accidental log of this map yields live session ids. The map is sensitive
+     * on that basis and must not be dumped or logged. Whether the stored
+     * `sessionId` should itself be protected is a separate question, and is not
+     * settled here.
+     *
+     * This is the mirror image of `OAuth.pendingStates`, not the same shape:
+     * there the *key* is the plaintext state token and the digest
+     * (`bindingHash`) sits in the value, so that record unlocks nothing on its
+     * own; here the digest is the key and the value is a live credential. What
+     * the two stores share is the discipline of never keeping a
+     * client-presented secret in the clear — neither the ticket nor the binding
+     * value is on the heap — but they place the digest on opposite sides of the
+     * entry.
+     *
+     * No constant-time comparison is needed and none is used: lookup is a hash
+     * probe on a 256-bit high-entropy key, not a secret-dependent byte
+     * comparison, so there is no early-exit timing signal to exploit. That is
+     * the same reason `redeem` can stay an ordinary `Map.get`.
+     */
+    tickets: Map<string, TicketRecord>;
+    ttl: number;
+    /** SHA-256 of a ticket, hex — the only form of the *ticket* this store keeps. */
+    static hash(ticket: string): string;
+    /**
+     * Mints a ticket for a freshly created session.
+     *
+     * The ticket is independent entropy, never a transform of the session id:
+     * anything derived from the credential is the credential.
+     */
+    issue(sessionId: string, expiresAt: number): string;
+    /**
+     * Spends a ticket, if it is live.
+     *
+     * Consumed on recognition, *before* the TTL check, for the same reason
+     * `OAuth.handleCallback` consumes a pending state before validating its
+     * binding: every ticket gets exactly one attempt whatever the outcome, so
+     * this endpoint is never a repeatable oracle. Deleting after the TTL check
+     * instead would leave an expired ticket in the map answering `400` forever
+     * while a live one answers `200` — an unauthenticated distinguisher.
+     *
+     * Returns `null` for unknown, spent and expired tickets alike. The caller
+     * maps all three to the same `400`; telling them apart is information the
+     * holder of a ticket they did not mint has no business having.
+     */
+    redeem(ticket: string): RedeemedTicket | null;
+}
+export {};

package/dist/ticket-store.js

@@ -0,0 +1,140 @@
+import { createHash, randomBytes } from 'node:crypto';
+/**
+ * Lifetime of an exchange ticket.
+ *
+ * Sized for one redirect plus one page load, and deliberately two orders of
+ * magnitude tighter than the 10-minute state TTL: the ticket is a bearer value
+ * travelling in a URL, and the whole point of #45 is that a bearer value in a
+ * URL must not be long-lived — in the fragment, so it reaches no server, but
+ * still into browser history and readable by scripts on the landing page.
+ */
+export const TICKET_TTL_MS = 60 * 1000;
+/** Entropy of a ticket, in bytes. */
+export const TICKET_BYTES = 32;
+/**
+ * Single-use, short-lived tickets that stand in for a session id on the wire.
+ *
+ * The callback redirect hands the browser a ticket instead of the session id
+ * (#45), in the URL *fragment*, which no user agent transmits to any server.
+ * The ticket authenticates nothing — `GET /auth` reads the `session-id` header
+ * and knows only about `SessionManager` — so a ticket observed in history or
+ * by a script reading `location.hash` is worth something only inside the
+ * sub-second window before the landing page redeems it, and nothing at all
+ * afterwards.
+ *
+ * Known residual, stated rather than papered over: a ticket observed *within*
+ * that window is redeemable by the observer, because nothing here binds a
+ * ticket to the client that started the flow. Closing it means binding the way
+ * #36 bound the state, and that binding has to travel on a cookie the
+ * cross-origin exchange cannot carry.
+ *
+ * The blocker is `abofs/stonyx-rest-server#63`: `@stonyx/rest-server` calls
+ * `cors({ origin, methods })` and has no `credentials` support at all. It is
+ * *not* `abofs/stonyx-rest-server#45` — that issue is the response-header half
+ * and is already worked around in `auth-request.ts`, which sets and clears the
+ * binding cookie on a redirect by reaching through `req.res`. Closing #45
+ * would not make this residual closeable. It is a reduction, not an
+ * elimination.
+ *
+ * Like `OAuth.pendingStates`, an abandoned ticket is never collected. That is
+ * a pre-existing pattern in this module, not something this store introduces,
+ * and it is bounded here by a 60-second TTL rather than a 10-minute one.
+ * Tracked, with both maps named, at `abofs/stonyx-oauth#43`.
+ *
+ * ---
+ *
+ * **Why this is a second store rather than a reuse of `OAuth.pendingStates`.**
+ *
+ * The duplication is real and is not an oversight: `pendingStates` is also a
+ * single-use, TTL-bounded, consume-on-recognition map keyed by a
+ * `randomBytes`-minted opaque token, with the same delete-before-TTL-check
+ * ordering and the same never-collected caveat. The shared shape could be
+ * extracted into one primitive, and the two constants homes (`STATE_TTL_MS`
+ * and `BINDING_VALUE_BYTES` in `main.ts`, `TICKET_TTL_MS` and `TICKET_BYTES`
+ * here) could then live together.
+ *
+ * It is deliberately not done in the change that fixes #45. Widening a
+ * security fix into a refactor of the CSRF store means the #36 binding
+ * mechanism — whose invariants are load-bearing and separately guarded — moves
+ * in the same commit as the fix, for no security gain in either. The two also
+ * do not have the same invariants: `pendingStates` is a security control fed
+ * by an unauthenticated `GET`, holding a *digest* of a client secret, with a
+ * 10-minute budget sized for a provider round trip; this is a delivery
+ * convenience reachable only after a successfully bound callback, holding a
+ * value it hands back, with a 60-second budget sized for a page load.
+ * Collapsing them would couple the control to the convenience.
+ *
+ * The extraction is tracked at `abofs/stonyx-oauth#58`.
+ */
+export default class TicketStore {
+    /**
+     * Live tickets, keyed by the **SHA-256 of the ticket**, never by the ticket.
+     *
+     * Keying by the digest means the map holds no redeemable *ticket*: a ticket
+     * is a client-presented secret looked up server-side, so what a reader of
+     * this map gets is a digest, and a digest cannot be presented to `redeem`.
+     *
+     * That does not make the map safe to expose. The record *value* holds a
+     * plaintext, live `sessionId` — the 24-hour bearer credential this store
+     * exists to keep out of URLs — so a heap dump, a debug serialisation or an
+     * accidental log of this map yields live session ids. The map is sensitive
+     * on that basis and must not be dumped or logged. Whether the stored
+     * `sessionId` should itself be protected is a separate question, and is not
+     * settled here.
+     *
+     * This is the mirror image of `OAuth.pendingStates`, not the same shape:
+     * there the *key* is the plaintext state token and the digest
+     * (`bindingHash`) sits in the value, so that record unlocks nothing on its
+     * own; here the digest is the key and the value is a live credential. What
+     * the two stores share is the discipline of never keeping a
+     * client-presented secret in the clear — neither the ticket nor the binding
+     * value is on the heap — but they place the digest on opposite sides of the
+     * entry.
+     *
+     * No constant-time comparison is needed and none is used: lookup is a hash
+     * probe on a 256-bit high-entropy key, not a secret-dependent byte
+     * comparison, so there is no early-exit timing signal to exploit. That is
+     * the same reason `redeem` can stay an ordinary `Map.get`.
+     */
+    tickets = new Map();
+    ttl = TICKET_TTL_MS;
+    /** SHA-256 of a ticket, hex — the only form of the *ticket* this store keeps. */
+    static hash(ticket) {
+        return createHash('sha256').update(ticket).digest('hex');
+    }
+    /**
+     * Mints a ticket for a freshly created session.
+     *
+     * The ticket is independent entropy, never a transform of the session id:
+     * anything derived from the credential is the credential.
+     */
+    issue(sessionId, expiresAt) {
+        const ticket = randomBytes(TICKET_BYTES).toString('base64url');
+        this.tickets.set(TicketStore.hash(ticket), { sessionId, expiresAt, createdAt: Date.now() });
+        return ticket;
+    }
+    /**
+     * Spends a ticket, if it is live.
+     *
+     * Consumed on recognition, *before* the TTL check, for the same reason
+     * `OAuth.handleCallback` consumes a pending state before validating its
+     * binding: every ticket gets exactly one attempt whatever the outcome, so
+     * this endpoint is never a repeatable oracle. Deleting after the TTL check
+     * instead would leave an expired ticket in the map answering `400` forever
+     * while a live one answers `200` — an unauthenticated distinguisher.
+     *
+     * Returns `null` for unknown, spent and expired tickets alike. The caller
+     * maps all three to the same `400`; telling them apart is information the
+     * holder of a ticket they did not mint has no business having.
+     */
+    redeem(ticket) {
+        const key = ticket ? TicketStore.hash(ticket) : null;
+        const record = key ? this.tickets.get(key) : undefined;
+        if (!record)
+            return null;
+        this.tickets.delete(key);
+        if (Date.now() - record.createdAt > this.ttl)
+            return null;
+        return { sessionId: record.sessionId, expiresAt: record.expiresAt };
+    }
+}

package/package.json

@@ -4,7 +4,7 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.1.1-beta.185",
+  "version": "0.1.1-beta.187",
   "description": "OAuth2 authentication module for the Stonyx framework",
   "repository": {
     "type": "git",
@@ -61,7 +61,7 @@
     "@stonyx/rest-server": ">=0.2.1-beta.11"
   },
   "devDependencies": {
-    "@stonyx/rest-server": "0.2.1-beta.122",
+    "@stonyx/rest-server": "0.2.1-beta.123",
     "@stonyx/utils": "0.2.3-beta.27",
     "@stonyx/logs": "1.0.1-beta.21",
     "@types/qunit": "^2.19.13",

package/src/auth-request.ts

@@ -40,6 +40,8 @@ interface OAuthInstance {
     stateToken: string,
     bindingValues: readonly string[],
   ): Promise<{ sessionId: string; expiresAt: number }>;
+  issueExchangeTicket(session: { sessionId: string; expiresAt: number }): string;
+  redeemExchangeTicket(ticket: string): { sessionId: string; expiresAt: number } | null;
   logout(sessionId: string): void;
 }
 
@@ -67,12 +69,26 @@ export interface CookieOptions {
 interface ResponseLike {
   cookie(name: string, value: string, options: CookieOptions): unknown;
   clearCookie(name: string, options: Omit<CookieOptions, 'maxAge'>): unknown;
+  /**
+   * Optional: every call site guards on it. `@stonyx/rest-server` hands the
+   * express response through untyped, and a test double need not implement the
+   * whole surface.
+   */
+  setHeader?(name: string, value: string): unknown;
 }
 
 interface RouteRequest {
   headers: Record<string, string | undefined>;
   params: Record<string, string>;
   query: Record<string, string>;
+  /**
+   * Parsed by `express.json()`, which `@stonyx/rest-server` installs globally.
+   *
+   * Optional and typed loosely because it is whatever an unauthenticated
+   * caller sent: a form-encoded body arrives as `null` and a bodyless request
+   * as `undefined`, so every read of it has to survive both.
+   */
+  body?: unknown;
   res?: ResponseLike;
 }
 
@@ -155,14 +171,38 @@ export default class AuthRequest extends Request {
           this.clearBindingCookie(req, providerName);
 
           if (this.oauth.frontendCallbackUrl) {
+            // The session id is the bearer credential (`GET /auth` above
+            // authenticates from exactly this value), so it must not be
+            // written into a URL: URLs land in browser history, in `Referer`
+            // on any outbound link, in proxy and CDN access logs, and in
+            // `location.search` for every script on the landing page. What
+            // goes in the URL instead is a single-use 60-second ticket that
+            // authenticates nothing, redeemed at `POST /auth/session` (#45).
+            //
+            // The ticket rides in the *fragment*, not the query. A fragment is
+            // never transmitted to any server by any user agent: it is absent
+            // from the frontend's own access logs, from every reverse proxy
+            // and CDN in front of the landing page, and from `Referer` under
+            // every referrer policy. That removes two of the four leak vectors
+            // #45 names outright, for one character. What it does not remove
+            // is browser history and readability by page scripts — those are
+            // why the ticket is still single-use and 60-second, and why the
+            // documented migration scrubs it with `history.replaceState`.
+            //
+            // `expiresAt` rides along in the same fragment rather than staying
+            // in the query, so the consumer has one place to read from.
+            // It is not a credential and nothing authenticates from it.
             const params = new URLSearchParams({
-              sessionId: session.sessionId,
+              ticket: this.oauth.issueExchangeTicket(session),
               expiresAt: String(session.expiresAt),
             });
-            state.redirect = `${this.oauth.frontendCallbackUrl}?${params}`;
+            state.redirect = `${this.oauth.frontendCallbackUrl}#${params}`;
             return;
           }
 
+          // No `frontendCallbackUrl` configured: the session is the response
+          // body of a direct request, not a value handed to a browser through
+          // a URL, so there is nothing here for #45 to fix.
           return session;
         } catch {
           if (this.oauth.frontendCallbackUrl) {
@@ -177,7 +217,44 @@ export default class AuthRequest extends Request {
         const sessionId = headers['session-id'];
         if (sessionId) this.oauth.logout(sessionId);
       },
-    }
+    },
+
+    post: {
+      /**
+       * Redeems the exchange ticket from the callback redirect (#45).
+       *
+       * `POST` and not `GET` because a `GET` would put the ticket back in a
+       * URL — in the caller's history, in access logs — which is the defect
+       * this route exists to close.
+       *
+       * `application/json` and not form-encoded: `@stonyx/rest-server`
+       * installs `express.json()` only, so a form-encoded body arrives as
+       * `null` and the ticket is unreadable. Measured, not assumed.
+       *
+       * Unknown, spent and expired tickets are one indistinguishable `400`.
+       *
+       * `Cache-Control: no-store` because the `200` body is the session id —
+       * the bearer credential itself. A `POST` response is not cacheable
+       * without explicit freshness, so this is defence in depth rather than a
+       * live defect: it is there so that no intermediary, service worker or
+       * future `GET` variant of this route can retain the credential. Set
+       * through `req.res`, the same reach-through the binding-cookie helpers
+       * use, because `@stonyx/rest-server` has no supported way for a handler
+       * to set a response header (`abofs/stonyx-rest-server#45`).
+       */
+      '/session': (req: RouteRequest) => {
+        const { body, res } = req;
+        if (typeof res?.setHeader === 'function') res.setHeader('Cache-Control', 'no-store');
+
+        const ticket = (body as { ticket?: unknown } | null | undefined)?.ticket;
+        if (typeof ticket !== 'string' || !ticket) return 400;
+
+        const session = this.oauth.redeemExchangeTicket(ticket);
+        if (!session) return 400;
+
+        return { sessionId: session.sessionId, expiresAt: session.expiresAt };
+      },
+    },
   };
 
   /**

package/src/main.ts

@@ -6,7 +6,10 @@ import { setup, emit } from '@stonyx/events';
 import RestServer from '@stonyx/rest-server';
 import TokenManager from './token-manager.js';
 import SessionManager from './session-manager.js';
+import TicketStore from './ticket-store.js';
 import AuthRequest from './auth-request.js';
+import type { RedeemedTicket } from './ticket-store.js';
+import type { SessionResult } from './session-manager.js';
 import type OAuthFlow from './oauth-flow.js';
 
 setup(['authenticate']);
@@ -55,6 +58,7 @@ export default class OAuth {
   pendingStates = new Map<string, PendingState>();
   stateTtl = STATE_TTL_MS;
   sessionManager!: SessionManager;
+  ticketStore = new TicketStore();
   frontendCallbackUrl?: string;
 
   constructor() {
@@ -228,6 +232,23 @@ export default class OAuth {
     return this.providers.get(providerName)?.flow.redirectUri;
   }
 
+  /**
+   * Mints the value the callback redirect is allowed to put in a URL (#45).
+   *
+   * The session id never travels in the redirect. What travels is a ticket
+   * that is single-use, expires in 60 seconds, and authenticates nothing on
+   * its own — `GET /auth` validates against `sessionManager`, which has never
+   * heard of it.
+   */
+  issueExchangeTicket(session: SessionResult): string {
+    return this.ticketStore.issue(session.sessionId, session.expiresAt);
+  }
+
+  /** Spends a ticket for the session id it stands for, or `null`. */
+  redeemExchangeTicket(ticket: string): RedeemedTicket | null {
+    return this.ticketStore.redeem(ticket);
+  }
+
   getSession(sessionId: string) {
     return this.sessionManager.validate(sessionId);
   }

package/src/ticket-store.ts

@@ -0,0 +1,158 @@
+import { createHash, randomBytes } from 'node:crypto';
+
+/**
+ * Lifetime of an exchange ticket.
+ *
+ * Sized for one redirect plus one page load, and deliberately two orders of
+ * magnitude tighter than the 10-minute state TTL: the ticket is a bearer value
+ * travelling in a URL, and the whole point of #45 is that a bearer value in a
+ * URL must not be long-lived — in the fragment, so it reaches no server, but
+ * still into browser history and readable by scripts on the landing page.
+ */
+export const TICKET_TTL_MS = 60 * 1000;
+
+/** Entropy of a ticket, in bytes. */
+export const TICKET_BYTES = 32;
+
+interface TicketRecord {
+  sessionId: string;
+  expiresAt: number;
+  createdAt: number;
+}
+
+export interface RedeemedTicket {
+  sessionId: string;
+  expiresAt: number;
+}
+
+/**
+ * Single-use, short-lived tickets that stand in for a session id on the wire.
+ *
+ * The callback redirect hands the browser a ticket instead of the session id
+ * (#45), in the URL *fragment*, which no user agent transmits to any server.
+ * The ticket authenticates nothing — `GET /auth` reads the `session-id` header
+ * and knows only about `SessionManager` — so a ticket observed in history or
+ * by a script reading `location.hash` is worth something only inside the
+ * sub-second window before the landing page redeems it, and nothing at all
+ * afterwards.
+ *
+ * Known residual, stated rather than papered over: a ticket observed *within*
+ * that window is redeemable by the observer, because nothing here binds a
+ * ticket to the client that started the flow. Closing it means binding the way
+ * #36 bound the state, and that binding has to travel on a cookie the
+ * cross-origin exchange cannot carry.
+ *
+ * The blocker is `abofs/stonyx-rest-server#63`: `@stonyx/rest-server` calls
+ * `cors({ origin, methods })` and has no `credentials` support at all. It is
+ * *not* `abofs/stonyx-rest-server#45` — that issue is the response-header half
+ * and is already worked around in `auth-request.ts`, which sets and clears the
+ * binding cookie on a redirect by reaching through `req.res`. Closing #45
+ * would not make this residual closeable. It is a reduction, not an
+ * elimination.
+ *
+ * Like `OAuth.pendingStates`, an abandoned ticket is never collected. That is
+ * a pre-existing pattern in this module, not something this store introduces,
+ * and it is bounded here by a 60-second TTL rather than a 10-minute one.
+ * Tracked, with both maps named, at `abofs/stonyx-oauth#43`.
+ *
+ * ---
+ *
+ * **Why this is a second store rather than a reuse of `OAuth.pendingStates`.**
+ *
+ * The duplication is real and is not an oversight: `pendingStates` is also a
+ * single-use, TTL-bounded, consume-on-recognition map keyed by a
+ * `randomBytes`-minted opaque token, with the same delete-before-TTL-check
+ * ordering and the same never-collected caveat. The shared shape could be
+ * extracted into one primitive, and the two constants homes (`STATE_TTL_MS`
+ * and `BINDING_VALUE_BYTES` in `main.ts`, `TICKET_TTL_MS` and `TICKET_BYTES`
+ * here) could then live together.
+ *
+ * It is deliberately not done in the change that fixes #45. Widening a
+ * security fix into a refactor of the CSRF store means the #36 binding
+ * mechanism — whose invariants are load-bearing and separately guarded — moves
+ * in the same commit as the fix, for no security gain in either. The two also
+ * do not have the same invariants: `pendingStates` is a security control fed
+ * by an unauthenticated `GET`, holding a *digest* of a client secret, with a
+ * 10-minute budget sized for a provider round trip; this is a delivery
+ * convenience reachable only after a successfully bound callback, holding a
+ * value it hands back, with a 60-second budget sized for a page load.
+ * Collapsing them would couple the control to the convenience.
+ *
+ * The extraction is tracked at `abofs/stonyx-oauth#58`.
+ */
+export default class TicketStore {
+  /**
+   * Live tickets, keyed by the **SHA-256 of the ticket**, never by the ticket.
+   *
+   * Keying by the digest means the map holds no redeemable *ticket*: a ticket
+   * is a client-presented secret looked up server-side, so what a reader of
+   * this map gets is a digest, and a digest cannot be presented to `redeem`.
+   *
+   * That does not make the map safe to expose. The record *value* holds a
+   * plaintext, live `sessionId` — the 24-hour bearer credential this store
+   * exists to keep out of URLs — so a heap dump, a debug serialisation or an
+   * accidental log of this map yields live session ids. The map is sensitive
+   * on that basis and must not be dumped or logged. Whether the stored
+   * `sessionId` should itself be protected is a separate question, and is not
+   * settled here.
+   *
+   * This is the mirror image of `OAuth.pendingStates`, not the same shape:
+   * there the *key* is the plaintext state token and the digest
+   * (`bindingHash`) sits in the value, so that record unlocks nothing on its
+   * own; here the digest is the key and the value is a live credential. What
+   * the two stores share is the discipline of never keeping a
+   * client-presented secret in the clear — neither the ticket nor the binding
+   * value is on the heap — but they place the digest on opposite sides of the
+   * entry.
+   *
+   * No constant-time comparison is needed and none is used: lookup is a hash
+   * probe on a 256-bit high-entropy key, not a secret-dependent byte
+   * comparison, so there is no early-exit timing signal to exploit. That is
+   * the same reason `redeem` can stay an ordinary `Map.get`.
+   */
+  tickets = new Map<string, TicketRecord>();
+  ttl = TICKET_TTL_MS;
+
+  /** SHA-256 of a ticket, hex — the only form of the *ticket* this store keeps. */
+  static hash(ticket: string): string {
+    return createHash('sha256').update(ticket).digest('hex');
+  }
+
+  /**
+   * Mints a ticket for a freshly created session.
+   *
+   * The ticket is independent entropy, never a transform of the session id:
+   * anything derived from the credential is the credential.
+   */
+  issue(sessionId: string, expiresAt: number): string {
+    const ticket = randomBytes(TICKET_BYTES).toString('base64url');
+    this.tickets.set(TicketStore.hash(ticket), { sessionId, expiresAt, createdAt: Date.now() });
+    return ticket;
+  }
+
+  /**
+   * Spends a ticket, if it is live.
+   *
+   * Consumed on recognition, *before* the TTL check, for the same reason
+   * `OAuth.handleCallback` consumes a pending state before validating its
+   * binding: every ticket gets exactly one attempt whatever the outcome, so
+   * this endpoint is never a repeatable oracle. Deleting after the TTL check
+   * instead would leave an expired ticket in the map answering `400` forever
+   * while a live one answers `200` — an unauthenticated distinguisher.
+   *
+   * Returns `null` for unknown, spent and expired tickets alike. The caller
+   * maps all three to the same `400`; telling them apart is information the
+   * holder of a ticket they did not mint has no business having.
+   */
+  redeem(ticket: string): RedeemedTicket | null {
+    const key = ticket ? TicketStore.hash(ticket) : null;
+    const record = key ? this.tickets.get(key) : undefined;
+    if (!record) return null;
+
+    this.tickets.delete(key!);
+
+    if (Date.now() - record.createdAt > this.ttl) return null;
+
+    return { sessionId: record.sessionId, expiresAt: record.expiresAt };
+  }
+}