@stonyx/oauth 0.1.1-alpha.26 → 0.1.1-alpha.27

package/README.md

@@ -56,7 +56,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` |
+| `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
@@ -184,11 +185,95 @@ 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
+
+**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=`, 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>}
+                               ->  400 on an unknown, spent, expired or unparseable ticket
+```
+
+**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. |
+| **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. |
+
+**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.
+
+The first and last of 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. `Referrer-Policy` and log scrubbing belong to the frontend and to infrastructure respectively, and this change does not attempt them.
+
+### 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. |
+| 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. |
+
+### 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'` — which needs [`abofs/stonyx-rest-server#45`](https://github.com/abofs/stonyx-rest-server/issues/45) plus a CORS change, since `origin` defaults to `*` and `*` with credentials is spec-forbidden. **That risk belongs to the rest-server layer.** Revisit when it 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.
+
+### Migration
+
+Read the `ticket`, exchange it, and scrub the URL:
+
+```javascript
+// On the landing page at your `frontendCallbackUrl`, before first paint.
+const params = new URLSearchParams(location.search);
+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.
+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 {
@@ -45,6 +53,14 @@ 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 +79,25 @@ 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`.
+             */
+            '/session': ({ body }: RouteRequest) => 400 | {
+                sessionId: string;
+                expiresAt: number;
+            };
+        };
     };
     /**
      * Whether the binding cookie is issued with `Secure`.

package/dist/auth-request.js

@@ -79,13 +79,26 @@ 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).
+                        //
+                        // `expiresAt` stays: 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}`;
                         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 +114,31 @@ 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`.
+             */
+            '/session': ({ body }) => {
+                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,67 @@
+/**
+ * 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.
+ */
+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). The ticket authenticates nothing — `GET /auth` reads the `session-id`
+ * header and knows only about `SessionManager` — so a ticket observed in
+ * history, in a `Referer`, or by a script reading `location.search` 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. Closing it means binding the
+ * ticket to the client the way #36 bound the state, and that binding has to
+ * travel on a cookie the cross-origin exchange cannot carry today — see
+ * `abofs/stonyx-rest-server#45`. 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.
+ */
+export default class TicketStore {
+    tickets: Map<string, TicketRecord>;
+    ttl: number;
+    /**
+     * 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,70 @@
+import { 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.
+ */
+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). The ticket authenticates nothing — `GET /auth` reads the `session-id`
+ * header and knows only about `SessionManager` — so a ticket observed in
+ * history, in a `Referer`, or by a script reading `location.search` 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. Closing it means binding the
+ * ticket to the client the way #36 bound the state, and that binding has to
+ * travel on a cookie the cross-origin exchange cannot carry today — see
+ * `abofs/stonyx-rest-server#45`. 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.
+ */
+export default class TicketStore {
+    tickets = new Map();
+    ttl = TICKET_TTL_MS;
+    /**
+     * 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(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 record = ticket ? this.tickets.get(ticket) : undefined;
+        if (!record)
+            return null;
+        this.tickets.delete(ticket);
+        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-alpha.26",
+  "version": "0.1.1-alpha.27",
   "description": "OAuth2 authentication module for the Stonyx framework",
   "repository": {
     "type": "git",

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;
 }
 
@@ -73,6 +75,14 @@ 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 +165,27 @@ 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).
+            //
+            // `expiresAt` stays: 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}`;
             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 +200,32 @@ 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`.
+       */
+      '/session': ({ body }: RouteRequest) => {
+        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,87 @@
+import { 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.
+ */
+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). The ticket authenticates nothing — `GET /auth` reads the `session-id`
+ * header and knows only about `SessionManager` — so a ticket observed in
+ * history, in a `Referer`, or by a script reading `location.search` 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. Closing it means binding the
+ * ticket to the client the way #36 bound the state, and that binding has to
+ * travel on a cookie the cross-origin exchange cannot carry today — see
+ * `abofs/stonyx-rest-server#45`. 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.
+ */
+export default class TicketStore {
+  tickets = new Map<string, TicketRecord>();
+  ttl = TICKET_TTL_MS;
+
+  /**
+   * 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(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 record = ticket ? this.tickets.get(ticket) : undefined;
+    if (!record) return null;
+
+    this.tickets.delete(ticket);
+
+    if (Date.now() - record.createdAt > this.ttl) return null;
+
+    return { sessionId: record.sessionId, expiresAt: record.expiresAt };
+  }
+}