@stonyx/oauth 0.1.1-alpha.32 → 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/package.json

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