@stonyx/oauth 0.1.1-alpha.31 → 0.1.1-alpha.33

package/README.md

@@ -202,6 +202,7 @@ This fails closed — no session is minted for the wrong flow, and it is not a w
 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
 ```
 
@@ -256,6 +257,8 @@ What the fragment does **not** remove is browser history and readability by page
 | 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 | **SHA-256 digest only** | The store is keyed by the digest of the ticket, never by the ticket, so a heap dump or an accidental log of the map yields a useless digest rather than a live redeemable credential. Same discipline as the `oauth_state` binding, which stores `bindingHash` and never the binding value. 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
 

package/dist/auth-request.d.ts

@@ -48,6 +48,12 @@ 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>;
@@ -92,8 +98,17 @@ export default class AuthRequest extends Request {
              * `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': ({ body }: RouteRequest) => 400 | {
+            '/session': (req: RouteRequest) => 400 | {
                 sessionId: string;
                 expiresAt: number;
             };

package/dist/auth-request.js

@@ -139,8 +139,20 @@ export default class AuthRequest extends Request {
              * `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': ({ body }) => {
+            '/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;

package/dist/ticket-store.d.ts

@@ -75,8 +75,24 @@ export interface RedeemedTicket {
  * 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.
+     *
+     * Same discipline as `OAuth.pendingStates`, which holds `bindingHash` and
+     * never the binding value: a ticket is a client-presented secret looked up
+     * server-side, so a heap dump, a debug serialisation or an accidental log of
+     * this map should yield a useless digest rather than a live redeemable
+     * credential. The two secret stores in this module now agree.
+     *
+     * 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 this store keeps on the heap. */
+    static hash(ticket: string): string;
     /**
      * Mints a ticket for a freshly created session.
      *

package/dist/ticket-store.js

@@ -1,4 +1,4 @@
-import { randomBytes } from 'node:crypto';
+import { createHash, randomBytes } from 'node:crypto';
 /**
  * Lifetime of an exchange ticket.
  *
@@ -67,8 +67,26 @@ export const TICKET_BYTES = 32;
  * 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.
+     *
+     * Same discipline as `OAuth.pendingStates`, which holds `bindingHash` and
+     * never the binding value: a ticket is a client-presented secret looked up
+     * server-side, so a heap dump, a debug serialisation or an accidental log of
+     * this map should yield a useless digest rather than a live redeemable
+     * credential. The two secret stores in this module now agree.
+     *
+     * 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 this store keeps on the heap. */
+    static hash(ticket) {
+        return createHash('sha256').update(ticket).digest('hex');
+    }
     /**
      * Mints a ticket for a freshly created session.
      *
@@ -77,7 +95,7 @@ export default class TicketStore {
      */
     issue(sessionId, expiresAt) {
         const ticket = randomBytes(TICKET_BYTES).toString('base64url');
-        this.tickets.set(ticket, { sessionId, expiresAt, createdAt: Date.now() });
+        this.tickets.set(TicketStore.hash(ticket), { sessionId, expiresAt, createdAt: Date.now() });
         return ticket;
     }
     /**
@@ -95,10 +113,11 @@ export default class TicketStore {
      * holder of a ticket they did not mint has no business having.
      */
     redeem(ticket) {
-        const record = ticket ? this.tickets.get(ticket) : undefined;
+        const key = ticket ? TicketStore.hash(ticket) : null;
+        const record = key ? this.tickets.get(key) : undefined;
         if (!record)
             return null;
-        this.tickets.delete(ticket);
+        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-alpha.31",
+  "version": "0.1.1-alpha.33",
   "description": "OAuth2 authentication module for the Stonyx framework",
   "repository": {
     "type": "git",

package/src/auth-request.ts

@@ -69,6 +69,12 @@ 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 {
@@ -226,8 +232,20 @@ export default class AuthRequest extends Request {
        * `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': ({ body }: RouteRequest) => {
+      '/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;
 

package/src/ticket-store.ts

@@ -1,4 +1,4 @@
-import { randomBytes } from 'node:crypto';
+import { createHash, randomBytes } from 'node:crypto';
 
 /**
  * Lifetime of an exchange ticket.
@@ -81,9 +81,28 @@ export interface RedeemedTicket {
  * 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.
+   *
+   * Same discipline as `OAuth.pendingStates`, which holds `bindingHash` and
+   * never the binding value: a ticket is a client-presented secret looked up
+   * server-side, so a heap dump, a debug serialisation or an accidental log of
+   * this map should yield a useless digest rather than a live redeemable
+   * credential. The two secret stores in this module now agree.
+   *
+   * 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 this store keeps on the heap. */
+  static hash(ticket: string): string {
+    return createHash('sha256').update(ticket).digest('hex');
+  }
+
   /**
    * Mints a ticket for a freshly created session.
    *
@@ -92,7 +111,7 @@ export default class TicketStore {
    */
   issue(sessionId: string, expiresAt: number): string {
     const ticket = randomBytes(TICKET_BYTES).toString('base64url');
-    this.tickets.set(ticket, { sessionId, expiresAt, createdAt: Date.now() });
+    this.tickets.set(TicketStore.hash(ticket), { sessionId, expiresAt, createdAt: Date.now() });
     return ticket;
   }
 
@@ -111,10 +130,11 @@ export default class TicketStore {
    * 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;
+    const key = ticket ? TicketStore.hash(ticket) : null;
+    const record = key ? this.tickets.get(key) : undefined;
     if (!record) return null;
 
-    this.tickets.delete(ticket);
+    this.tickets.delete(key!);
 
     if (Date.now() - record.createdAt > this.ttl) return null;