@stonyx/oauth 0.1.1-alpha.32 → 0.1.1-alpha.34

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 | **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
 

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

@@ -78,11 +78,26 @@ 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.
+     * 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
@@ -91,7 +106,7 @@ export default class TicketStore {
      */
     tickets: Map<string, TicketRecord>;
     ttl: number;
-    /** SHA-256 of a ticket, hex — the only form this store keeps on the heap. */
+    /** 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.

package/dist/ticket-store.js

@@ -70,11 +70,26 @@ 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.
+     * 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
@@ -83,7 +98,7 @@ export default class TicketStore {
      */
     tickets = new Map();
     ttl = TICKET_TTL_MS;
-    /** SHA-256 of a ticket, hex — the only form this store keeps on the heap. */
+    /** 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');
     }

package/package.json

@@ -4,7 +4,7 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.1.1-alpha.32",
+  "version": "0.1.1-alpha.34",
   "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

@@ -84,11 +84,26 @@ 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.
+   * 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
@@ -98,7 +113,7 @@ export default class TicketStore {
   tickets = new Map<string, TicketRecord>();
   ttl = TICKET_TTL_MS;
 
-  /** SHA-256 of a ticket, hex — the only form this store keeps on the heap. */
+  /** 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');
   }