@stonyx/oauth 0.1.1-alpha.14 → 0.1.1-alpha.16

package/README.md

@@ -55,10 +55,74 @@ The module self-registers the following routes on the rest server:
 | Method | Route | Description |
 |--------|-------|-------------|
 | `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/login/:provider` | Redirects to provider's OAuth2 authorization page, and sets the state binding cookie |
+| `GET` | `/auth/callback/:provider` | OAuth2 callback — verifies the state binding, exchanges code for tokens, creates session |
 | `GET` | `/auth/logout` | Destroys session (send `session-id` header) |
 
+### Starting the flow
+
+Send the browser to `/auth/login/:provider` as a **top-level navigation**:
+
+```javascript
+window.location.href = 'https://api.example.com/auth/login/discord';
+```
+
+Do not start the flow with `fetch()` or `XMLHttpRequest`. The login response
+sets the state binding cookie described below, and the browser must be holding
+that cookie when the provider redirects it back to `/auth/callback/:provider`.
+
+## State Binding (CSRF Protection)
+
+The OAuth2 `state` parameter only protects against login CSRF if it is bound to
+the client that started the flow. This module binds it with a cookie.
+
+On `GET /auth/login/:provider` the module issues a random 32-byte binding value,
+stores only a SHA-256 digest of it server-side alongside the provider name and
+issue time, and sends the plaintext to the client as a cookie:
+
+| Attribute | Value | Why |
+|-----------|-------|-----|
+| Name | `stonyx_oauth_state` | |
+| `HttpOnly` | set | script must not be able to read or forge the binding value |
+| `SameSite` | `Lax` | **required.** The callback is a cross-site, top-level `GET` navigation from the provider. `SameSite=Strict` withholds the cookie on exactly that request and breaks login outright; `SameSite=None` requires `Secure` and widens exposure for no benefit |
+| `Path` | `/auth` | the cookie is only ever read by the callback route |
+| `Secure` | set when the request arrived over HTTPS | |
+| `Max-Age` | 600 (10 minutes) | matches the pending state's lifetime |
+
+`GET /auth/callback/:provider` accepts the callback only when all of the
+following hold, and mints no session otherwise:
+
+- the `state` is one this server issued and has not already been used
+- it was issued for **this** provider
+- it was issued less than 10 minutes ago
+- the request carries the binding cookie whose value hashes to the stored digest
+
+The state and the cookie are both single-use: the pending record is consumed on
+any callback that presents a recognised `state` — successful or not — and the
+callback response clears the cookie.
+
+If the cookie cannot be set, `GET /auth/login/:provider` responds `500` rather
+than issuing a state it cannot bind. A reverse proxy or CDN that strips
+`Set-Cookie` from redirect responses will therefore break login rather than
+silently degrade it.
+
+### Custom flow drivers
+
+Consumers that drive the flow themselves instead of using the routes above must
+carry the binding value between the two calls:
+
+```javascript
+const { url, bindingValue } = oauth.getAuthorizationUrl('discord');
+// hand bindingValue to the client, then on the callback:
+const session = await oauth.handleCallback('discord', code, state, bindingValue);
+```
+
+> **Changed in the release that fixes [#36](https://github.com/abofs/stonyx-oauth/issues/36):**
+> `getAuthorizationUrl(provider)` returned a URL string and now returns
+> `{ url, bindingValue }`; `handleCallback(provider, code, state)` takes a
+> fourth argument, the client's binding value. Applications using the
+> self-registering `/auth` routes need no changes.
+
 ## Officially Supported Providers
 
 ### Discord
@@ -119,6 +183,8 @@ providers: {
 ## Session Management
 
 Sessions are stored in-memory using a `Map`. Sessions are lost on server restart.
+Pending OAuth states are held in-memory too, so a restart mid-login, or more
+than one instance behind a load balancer, will reject the callback.
 
 Clients should store the `sessionId` returned from the callback and send it as a `session-id` header on subsequent requests.
 

package/dist/auth-request.d.ts

@@ -1,18 +1,44 @@
 import { Request } from '@stonyx/rest-server';
+interface AuthorizationRequest {
+    url: string;
+    bindingValue: string;
+}
 interface OAuthInstance {
     frontendCallbackUrl?: string;
     getSession(sessionId: string): unknown;
-    getAuthorizationUrl(providerName: string): string;
-    handleCallback(providerName: string, code: string, stateToken: string): Promise<{
+    getAuthorizationUrl(providerName: string): AuthorizationRequest;
+    handleCallback(providerName: string, code: string, stateToken: string, bindingValue?: string): Promise<{
         sessionId: string;
         expiresAt: number;
     }>;
     logout(sessionId: string): void;
 }
+interface CookieOptions {
+    httpOnly: boolean;
+    sameSite: string;
+    path: string;
+    secure: boolean;
+    maxAge?: number;
+}
+/**
+ * The response object Express hangs off the request.
+ *
+ * `@stonyx/rest-server` hands handlers `(req, state)` only, and `state` has no
+ * affordance for response headers, so setting a cookie means reaching for
+ * `req.res`. This is a deliberate, temporary escape hatch — tracked by
+ * `abofs/stonyx-rest-server#45`, which adds a first-class header affordance to
+ * migrate onto.
+ */
+interface ResponseLike {
+    cookie(name: string, value: string, options: CookieOptions): unknown;
+    clearCookie(name: string, options: Omit<CookieOptions, 'maxAge'>): unknown;
+}
 interface RouteRequest {
     headers: Record<string, string | undefined>;
     params: Record<string, string>;
     query: Record<string, string>;
+    secure?: boolean;
+    res?: ResponseLike;
 }
 interface RouteState {
     redirect?: string;
@@ -23,13 +49,17 @@ export default class AuthRequest extends Request {
     handlers: {
         get: {
             '/': ({ headers }: RouteRequest) => {};
-            '/login/:provider': (req: RouteRequest, state: RouteState) => 404 | undefined;
+            '/login/:provider': (req: RouteRequest, state: RouteState) => 404 | 500 | undefined;
             '/callback/:provider': (req: RouteRequest, state: RouteState) => Promise<{
                 sessionId: string;
                 expiresAt: number;
-            } | 400 | 500 | undefined>;
+            } | 500 | 400 | undefined>;
             '/logout': ({ headers }: RouteRequest) => void;
         };
     };
+    cookieOptions(req: RouteRequest): Omit<CookieOptions, 'maxAge'>;
+    setBindingCookie(req: RouteRequest, bindingValue: string): boolean;
+    readBindingCookie(req: RouteRequest): string | undefined;
+    clearBindingCookie(req: RouteRequest): void;
 }
 export {};

package/dist/auth-request.js

@@ -1,4 +1,6 @@
 import { Request } from '@stonyx/rest-server';
+import log from 'stonyx/log';
+import { STATE_COOKIE_NAME, STATE_COOKIE_PATH, STATE_COOKIE_SAME_SITE, STATE_TTL_MS, } from './constants.js';
 export default class AuthRequest extends Request {
     oauth;
     constructor(oauth) {
@@ -18,17 +20,26 @@ export default class AuthRequest extends Request {
             },
             '/login/:provider': (req, state) => {
                 const { provider: providerName } = req.params;
+                let authorization;
                 try {
-                    const url = this.oauth.getAuthorizationUrl(providerName);
-                    state.redirect = url;
+                    authorization = this.oauth.getAuthorizationUrl(providerName);
                 }
                 catch {
                     return 404;
                 }
+                // Fail closed: a state we cannot bind to this client is exactly the
+                // defect this mechanism exists to prevent, so never issue one.
+                if (!this.setBindingCookie(req, authorization.bindingValue))
+                    return 500;
+                state.redirect = authorization.url;
             },
             '/callback/:provider': async (req, state) => {
                 const { provider: providerName } = req.params;
                 const { code, state: stateToken, error } = req.query;
+                // The binding value is single-use: whatever the outcome below, this
+                // callback is the end of that cookie's life.
+                const bindingValue = this.readBindingCookie(req);
+                this.clearBindingCookie(req);
                 if (error) {
                     if (this.oauth.frontendCallbackUrl) {
                         state.redirect = `${this.oauth.frontendCallbackUrl}?error=${encodeURIComponent(error)}`;
@@ -39,7 +50,7 @@ export default class AuthRequest extends Request {
                 if (!code)
                     return 400;
                 try {
-                    const session = await this.oauth.handleCallback(providerName, code, stateToken);
+                    const session = await this.oauth.handleCallback(providerName, code, stateToken, bindingValue);
                     if (this.oauth.frontendCallbackUrl) {
                         const params = new URLSearchParams({
                             sessionId: session.sessionId,
@@ -65,4 +76,47 @@ export default class AuthRequest extends Request {
             },
         }
     };
+    cookieOptions(req) {
+        return {
+            httpOnly: true,
+            // Load-bearing: the callback is a cross-site top-level GET navigation
+            // from the provider. `Strict` withholds the cookie on exactly that
+            // request and breaks login outright.
+            sameSite: STATE_COOKIE_SAME_SITE,
+            path: STATE_COOKIE_PATH,
+            secure: req.secure === true,
+        };
+    }
+    setBindingCookie(req, bindingValue) {
+        const { res } = req;
+        if (typeof res?.cookie !== 'function') {
+            log.error('OAuth: unable to set the state binding cookie; login rejected');
+            return false;
+        }
+        res.cookie(STATE_COOKIE_NAME, bindingValue, {
+            ...this.cookieOptions(req),
+            maxAge: STATE_TTL_MS,
+        });
+        return true;
+    }
+    readBindingCookie(req) {
+        const header = req.headers.cookie;
+        if (!header)
+            return undefined;
+        for (const part of header.split(';')) {
+            const separator = part.indexOf('=');
+            if (separator === -1)
+                continue;
+            if (part.slice(0, separator).trim() !== STATE_COOKIE_NAME)
+                continue;
+            return decodeURIComponent(part.slice(separator + 1).trim());
+        }
+        return undefined;
+    }
+    clearBindingCookie(req) {
+        const { res } = req;
+        if (typeof res?.clearCookie !== 'function')
+            return;
+        res.clearCookie(STATE_COOKIE_NAME, this.cookieOptions(req));
+    }
 }

package/dist/constants.d.ts

@@ -0,0 +1,7 @@
+export declare const STATE_COOKIE_NAME = "stonyx_oauth_state";
+export declare const STATE_COOKIE_PATH = "/auth";
+export declare const STATE_COOKIE_SAME_SITE = "lax";
+/** Lifetime of a pending state record, and the binding cookie's Max-Age. */
+export declare const STATE_TTL_MS: number;
+/** Entropy of the client-held binding value, in bytes. */
+export declare const BINDING_VALUE_BYTES = 32;

package/dist/constants.js

@@ -0,0 +1,16 @@
+// Shared constants for the OAuth state/client-binding mechanism (#36).
+//
+// The binding cookie attributes are load-bearing, not cosmetic:
+//   - `SameSite=Lax` — the OAuth callback is a cross-site, top-level GET
+//     navigation initiated by the provider. `Strict` withholds the cookie on
+//     exactly that request and breaks login; `None` requires `Secure` and
+//     widens exposure for no benefit. `Lax` is the only correct value.
+//   - `Path=/auth` — the cookie is only ever read by the callback route.
+//   - `HttpOnly` — script must not be able to read or forge the binding value.
+export const STATE_COOKIE_NAME = 'stonyx_oauth_state';
+export const STATE_COOKIE_PATH = '/auth';
+export const STATE_COOKIE_SAME_SITE = 'lax';
+/** Lifetime of a pending state record, and the binding cookie's Max-Age. */
+export const STATE_TTL_MS = 10 * 60 * 1000;
+/** Entropy of the client-held binding value, in bytes. */
+export const BINDING_VALUE_BYTES = 32;

package/dist/main.d.ts

@@ -1,21 +1,32 @@
 import TokenManager from './token-manager.js';
 import SessionManager from './session-manager.js';
+import StateStore from './state-store.js';
 import type OAuthFlow from './oauth-flow.js';
 interface ProviderEntry {
     flow: OAuthFlow;
     tokenManager: TokenManager;
 }
+export interface AuthorizationRequest {
+    /** Provider authorization URL to redirect the client to. */
+    url: string;
+    /**
+     * Client-held half of the state binding (#36). The caller must hand this to
+     * the client that started the flow — the auth routes set it as an HttpOnly
+     * cookie — and present it back to `handleCallback`.
+     */
+    bindingValue: string;
+}
 export default class OAuth {
     static instance: OAuth | null;
     providers: Map<string, ProviderEntry>;
-    pendingStates: Map<string, number>;
+    stateStore: StateStore;
     sessionManager: SessionManager;
     frontendCallbackUrl?: string;
     constructor();
     init(): Promise<void>;
     getProvider(name: string): ProviderEntry;
-    getAuthorizationUrl(providerName: string): string;
-    handleCallback(providerName: string, code: string, stateToken: string): Promise<import("./session-manager.js").SessionResult>;
+    getAuthorizationUrl(providerName: string): AuthorizationRequest;
+    handleCallback(providerName: string, code: string, stateToken: string, bindingValue?: string): Promise<import("./session-manager.js").SessionResult>;
     getSession(sessionId: string): unknown;
     logout(sessionId: string): void;
 }

package/dist/main.js

@@ -6,11 +6,12 @@ import RestServer from '@stonyx/rest-server';
 import TokenManager from './token-manager.js';
 import SessionManager from './session-manager.js';
 import AuthRequest from './auth-request.js';
+import StateStore from './state-store.js';
 setup(['authenticate']);
 export default class OAuth {
     static instance;
     providers = new Map();
-    pendingStates = new Map();
+    stateStore = new StateStore();
     sessionManager;
     frontendCallbackUrl;
     constructor() {
@@ -19,6 +20,10 @@ export default class OAuth {
         OAuth.instance = this;
     }
     async init() {
+        // Self-register so log.oauth works even when @stonyx/oauth is in the
+        // consumer's `dependencies` (stonyx loader only merges devDependencies).
+        const { logColor = 'magenta', logMethod = 'oauth' } = config.oauth;
+        log.defineType(logMethod, logColor);
         const oauthConfig = config.oauth;
         const { providers, sessionDuration, frontendCallbackUrl } = oauthConfig;
         this.frontendCallbackUrl = frontendCallbackUrl;
@@ -43,22 +48,11 @@ export default class OAuth {
     }
     getAuthorizationUrl(providerName) {
         const { flow } = this.getProvider(providerName);
-        const stateToken = crypto.randomUUID();
-        this.pendingStates.set(stateToken, Date.now());
-        return flow.buildAuthorizationUrl(stateToken);
+        const { stateToken, bindingValue } = this.stateStore.issue(providerName);
+        return { url: flow.buildAuthorizationUrl(stateToken), bindingValue };
     }
-    async handleCallback(providerName, code, stateToken) {
-        if (!stateToken || !this.pendingStates.has(stateToken)) {
-            throw new Error('Invalid or missing state token');
-        }
-        const stateCreatedAt = this.pendingStates.get(stateToken);
-        if (stateCreatedAt === undefined)
-            throw new Error('State token not found in pending states');
-        this.pendingStates.delete(stateToken);
-        const TEN_MINUTES = 10 * 60 * 1000;
-        if (Date.now() - stateCreatedAt > TEN_MINUTES) {
-            throw new Error('State token has expired');
-        }
+    async handleCallback(providerName, code, stateToken, bindingValue) {
+        this.stateStore.consume(stateToken, providerName, bindingValue);
         const { flow, tokenManager } = this.getProvider(providerName);
         const tokens = await tokenManager.getTokens(code);
         const rawUser = await flow.fetchUserInfo(tokens.accessToken);

package/dist/state-store.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Server-side record for an OAuth flow that is in progress.
+ *
+ * Deliberately holds a *digest* of the binding value rather than the value
+ * itself: a callback is only accepted when the caller presents the plaintext
+ * that hashes to `bindingHash`, so the record on its own unlocks nothing.
+ */
+export interface PendingState {
+    provider: string;
+    bindingHash: string;
+    createdAt: number;
+}
+export interface IssuedState {
+    /** Sent to the provider as the OAuth2 `state` parameter. */
+    stateToken: string;
+    /** Held by the client that started the flow (a cookie), never by the provider. */
+    bindingValue: string;
+}
+/**
+ * Issues and validates OAuth2 `state` tokens bound to the client that started
+ * the flow (#36).
+ *
+ * Presence-plus-age on a process-global map is replay-window limiting, not the
+ * CSRF binding `state` exists to provide (RFC 6749 section 10.12): any state
+ * issued to any visitor validated for any callback, so an attacker could
+ * harvest their own state and code and deliver them to a victim, logging the
+ * victim in as the attacker. A state is now only accepted when the caller also
+ * presents the matching client-held binding value, and only at the provider it
+ * was issued for.
+ */
+export default class StateStore {
+    pending: Map<string, PendingState>;
+    ttl: number;
+    constructor(ttl?: number);
+    static hash(value: string): string;
+    /** Length-independent, content-constant-time comparison of two digests. */
+    static digestsMatch(a: string, b: string): boolean;
+    issue(provider: string): IssuedState;
+    /**
+     * Validates and consumes a pending state. Throws on every rejection path.
+     *
+     * The record is removed as soon as the state is recognised — before the
+     * binding is checked — so a state cannot survive a failed attempt and be
+     * used as a target for guessing the binding value.
+     */
+    consume(stateToken: string | undefined, provider: string, bindingValue: string | undefined): void;
+}

package/dist/state-store.js

@@ -0,0 +1,68 @@
+import { createHash, randomBytes, randomUUID } from 'node:crypto';
+import { BINDING_VALUE_BYTES, STATE_TTL_MS } from './constants.js';
+/**
+ * Issues and validates OAuth2 `state` tokens bound to the client that started
+ * the flow (#36).
+ *
+ * Presence-plus-age on a process-global map is replay-window limiting, not the
+ * CSRF binding `state` exists to provide (RFC 6749 section 10.12): any state
+ * issued to any visitor validated for any callback, so an attacker could
+ * harvest their own state and code and deliver them to a victim, logging the
+ * victim in as the attacker. A state is now only accepted when the caller also
+ * presents the matching client-held binding value, and only at the provider it
+ * was issued for.
+ */
+export default class StateStore {
+    pending = new Map();
+    ttl;
+    constructor(ttl = STATE_TTL_MS) {
+        this.ttl = ttl;
+    }
+    static hash(value) {
+        return createHash('sha256').update(value).digest('hex');
+    }
+    /** Length-independent, content-constant-time comparison of two digests. */
+    static digestsMatch(a, b) {
+        if (a.length !== b.length)
+            return false;
+        let difference = 0;
+        for (let index = 0; index < a.length; index++) {
+            difference |= a.charCodeAt(index) ^ b.charCodeAt(index);
+        }
+        return difference === 0;
+    }
+    issue(provider) {
+        const stateToken = randomUUID();
+        const bindingValue = randomBytes(BINDING_VALUE_BYTES).toString('base64url');
+        this.pending.set(stateToken, {
+            provider,
+            bindingHash: StateStore.hash(bindingValue),
+            createdAt: Date.now(),
+        });
+        return { stateToken, bindingValue };
+    }
+    /**
+     * Validates and consumes a pending state. Throws on every rejection path.
+     *
+     * The record is removed as soon as the state is recognised — before the
+     * binding is checked — so a state cannot survive a failed attempt and be
+     * used as a target for guessing the binding value.
+     */
+    consume(stateToken, provider, bindingValue) {
+        if (!stateToken)
+            throw new Error('Invalid or missing state token');
+        const record = this.pending.get(stateToken);
+        if (!record)
+            throw new Error('Invalid or missing state token');
+        this.pending.delete(stateToken);
+        if (Date.now() - record.createdAt > this.ttl)
+            throw new Error('State token has expired');
+        if (record.provider !== provider)
+            throw new Error('State token was not issued for this provider');
+        if (!bindingValue)
+            throw new Error('Missing state binding value');
+        if (!StateStore.digestsMatch(StateStore.hash(bindingValue), record.bindingHash)) {
+            throw new Error('State token is not bound to this client');
+        }
+    }
+}

package/package.json

@@ -4,7 +4,7 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.1.1-alpha.14",
+  "version": "0.1.1-alpha.16",
   "description": "OAuth2 authentication module for the Stonyx framework",
   "repository": {
     "type": "git",
@@ -17,6 +17,10 @@
       "types": "./dist/main.d.ts",
       "default": "./dist/main.js"
     },
+    "./constants": {
+      "types": "./dist/constants.d.ts",
+      "default": "./dist/constants.js"
+    },
     "./oauth-flow": {
       "types": "./dist/oauth-flow.d.ts",
       "default": "./dist/oauth-flow.js"
@@ -54,16 +58,16 @@
     "provenance": true
   },
   "dependencies": {
-    "@stonyx/events": "0.1.1-beta.47",
-    "stonyx": "0.2.3-beta.63"
+    "@stonyx/events": "0.1.1-beta.52",
+    "stonyx": "0.2.3-beta.76"
   },
   "peerDependencies": {
     "@stonyx/rest-server": ">=0.2.1-beta.11"
   },
   "devDependencies": {
-    "@stonyx/rest-server": "0.2.1-beta.59",
-    "@stonyx/utils": "0.2.3-beta.23",
-    "@stonyx/logs": "1.0.1-beta.16",
+    "@stonyx/rest-server": "0.2.1-beta.80",
+    "@stonyx/utils": "0.2.3-beta.26",
+    "@stonyx/logs": "1.0.1-beta.19",
     "@types/qunit": "^2.19.13",
     "@types/sinon": "^21.0.1",
     "qunit": "^2.24.1",

package/src/auth-request.ts

@@ -1,17 +1,58 @@
 import { Request } from '@stonyx/rest-server';
+import log from 'stonyx/log';
+import {
+  STATE_COOKIE_NAME,
+  STATE_COOKIE_PATH,
+  STATE_COOKIE_SAME_SITE,
+  STATE_TTL_MS,
+} from './constants.js';
+
+interface AuthorizationRequest {
+  url: string;
+  bindingValue: string;
+}
 
 interface OAuthInstance {
   frontendCallbackUrl?: string;
   getSession(sessionId: string): unknown;
-  getAuthorizationUrl(providerName: string): string;
-  handleCallback(providerName: string, code: string, stateToken: string): Promise<{ sessionId: string; expiresAt: number }>;
+  getAuthorizationUrl(providerName: string): AuthorizationRequest;
+  handleCallback(
+    providerName: string,
+    code: string,
+    stateToken: string,
+    bindingValue?: string,
+  ): Promise<{ sessionId: string; expiresAt: number }>;
   logout(sessionId: string): void;
 }
 
+interface CookieOptions {
+  httpOnly: boolean;
+  sameSite: string;
+  path: string;
+  secure: boolean;
+  maxAge?: number;
+}
+
+/**
+ * The response object Express hangs off the request.
+ *
+ * `@stonyx/rest-server` hands handlers `(req, state)` only, and `state` has no
+ * affordance for response headers, so setting a cookie means reaching for
+ * `req.res`. This is a deliberate, temporary escape hatch — tracked by
+ * `abofs/stonyx-rest-server#45`, which adds a first-class header affordance to
+ * migrate onto.
+ */
+interface ResponseLike {
+  cookie(name: string, value: string, options: CookieOptions): unknown;
+  clearCookie(name: string, options: Omit<CookieOptions, 'maxAge'>): unknown;
+}
+
 interface RouteRequest {
   headers: Record<string, string | undefined>;
   params: Record<string, string>;
   query: Record<string, string>;
+  secure?: boolean;
+  res?: ResponseLike;
 }
 
 interface RouteState {
@@ -41,18 +82,29 @@ export default class AuthRequest extends Request {
       '/login/:provider': (req: RouteRequest, state: RouteState) => {
         const { provider: providerName } = req.params;
 
+        let authorization: AuthorizationRequest;
         try {
-          const url = this.oauth.getAuthorizationUrl(providerName);
-          state.redirect = url;
+          authorization = this.oauth.getAuthorizationUrl(providerName);
         } catch {
           return 404;
         }
+
+        // Fail closed: a state we cannot bind to this client is exactly the
+        // defect this mechanism exists to prevent, so never issue one.
+        if (!this.setBindingCookie(req, authorization.bindingValue)) return 500;
+
+        state.redirect = authorization.url;
       },
 
       '/callback/:provider': async (req: RouteRequest, state: RouteState) => {
         const { provider: providerName } = req.params;
         const { code, state: stateToken, error } = req.query;
 
+        // The binding value is single-use: whatever the outcome below, this
+        // callback is the end of that cookie's life.
+        const bindingValue = this.readBindingCookie(req);
+        this.clearBindingCookie(req);
+
         if (error) {
           if (this.oauth.frontendCallbackUrl) {
             state.redirect = `${this.oauth.frontendCallbackUrl}?error=${encodeURIComponent(error)}`;
@@ -64,7 +116,7 @@ export default class AuthRequest extends Request {
         if (!code) return 400;
 
         try {
-          const session = await this.oauth.handleCallback(providerName, code, stateToken);
+          const session = await this.oauth.handleCallback(providerName, code, stateToken, bindingValue);
 
           if (this.oauth.frontendCallbackUrl) {
             const params = new URLSearchParams({
@@ -91,4 +143,54 @@ export default class AuthRequest extends Request {
       },
     }
   };
+
+  cookieOptions(req: RouteRequest): Omit<CookieOptions, 'maxAge'> {
+    return {
+      httpOnly: true,
+      // Load-bearing: the callback is a cross-site top-level GET navigation
+      // from the provider. `Strict` withholds the cookie on exactly that
+      // request and breaks login outright.
+      sameSite: STATE_COOKIE_SAME_SITE,
+      path: STATE_COOKIE_PATH,
+      secure: req.secure === true,
+    };
+  }
+
+  setBindingCookie(req: RouteRequest, bindingValue: string): boolean {
+    const { res } = req;
+
+    if (typeof res?.cookie !== 'function') {
+      log.error('OAuth: unable to set the state binding cookie; login rejected');
+      return false;
+    }
+
+    res.cookie(STATE_COOKIE_NAME, bindingValue, {
+      ...this.cookieOptions(req),
+      maxAge: STATE_TTL_MS,
+    });
+
+    return true;
+  }
+
+  readBindingCookie(req: RouteRequest): string | undefined {
+    const header = req.headers.cookie;
+    if (!header) return undefined;
+
+    for (const part of header.split(';')) {
+      const separator = part.indexOf('=');
+      if (separator === -1) continue;
+      if (part.slice(0, separator).trim() !== STATE_COOKIE_NAME) continue;
+
+      return decodeURIComponent(part.slice(separator + 1).trim());
+    }
+
+    return undefined;
+  }
+
+  clearBindingCookie(req: RouteRequest): void {
+    const { res } = req;
+    if (typeof res?.clearCookie !== 'function') return;
+
+    res.clearCookie(STATE_COOKIE_NAME, this.cookieOptions(req));
+  }
 }

package/src/constants.ts

@@ -0,0 +1,19 @@
+// Shared constants for the OAuth state/client-binding mechanism (#36).
+//
+// The binding cookie attributes are load-bearing, not cosmetic:
+//   - `SameSite=Lax` — the OAuth callback is a cross-site, top-level GET
+//     navigation initiated by the provider. `Strict` withholds the cookie on
+//     exactly that request and breaks login; `None` requires `Secure` and
+//     widens exposure for no benefit. `Lax` is the only correct value.
+//   - `Path=/auth` — the cookie is only ever read by the callback route.
+//   - `HttpOnly` — script must not be able to read or forge the binding value.
+
+export const STATE_COOKIE_NAME = 'stonyx_oauth_state';
+export const STATE_COOKIE_PATH = '/auth';
+export const STATE_COOKIE_SAME_SITE = 'lax';
+
+/** Lifetime of a pending state record, and the binding cookie's Max-Age. */
+export const STATE_TTL_MS = 10 * 60 * 1000;
+
+/** Entropy of the client-held binding value, in bytes. */
+export const BINDING_VALUE_BYTES = 32;

package/src/main.ts

@@ -6,6 +6,7 @@ import RestServer from '@stonyx/rest-server';
 import TokenManager from './token-manager.js';
 import SessionManager from './session-manager.js';
 import AuthRequest from './auth-request.js';
+import StateStore from './state-store.js';
 import type OAuthFlow from './oauth-flow.js';
 
 setup(['authenticate']);
@@ -20,11 +21,22 @@ interface ProviderConfig {
   [key: string]: unknown;
 }
 
+export interface AuthorizationRequest {
+  /** Provider authorization URL to redirect the client to. */
+  url: string;
+  /**
+   * Client-held half of the state binding (#36). The caller must hand this to
+   * the client that started the flow — the auth routes set it as an HttpOnly
+   * cookie — and present it back to `handleCallback`.
+   */
+  bindingValue: string;
+}
+
 export default class OAuth {
   static instance: OAuth | null;
 
   providers = new Map<string, ProviderEntry>();
-  pendingStates = new Map<string, number>();
+  stateStore = new StateStore();
   sessionManager!: SessionManager;
   frontendCallbackUrl?: string;
 
@@ -34,6 +46,11 @@ export default class OAuth {
   }
 
   async init(): Promise<void> {
+    // Self-register so log.oauth works even when @stonyx/oauth is in the
+    // consumer's `dependencies` (stonyx loader only merges devDependencies).
+    const { logColor = 'magenta', logMethod = 'oauth' } = config.oauth;
+    log.defineType(logMethod, logColor);
+
     const oauthConfig = config.oauth;
     const { providers, sessionDuration, frontendCallbackUrl } = oauthConfig;
     this.frontendCallbackUrl = frontendCallbackUrl;
@@ -61,26 +78,15 @@ export default class OAuth {
     return provider;
   }
 
-  getAuthorizationUrl(providerName: string): string {
+  getAuthorizationUrl(providerName: string): AuthorizationRequest {
     const { flow } = this.getProvider(providerName);
-    const stateToken = crypto.randomUUID();
-    this.pendingStates.set(stateToken, Date.now());
-    return flow.buildAuthorizationUrl(stateToken);
-  }
+    const { stateToken, bindingValue } = this.stateStore.issue(providerName);
 
-  async handleCallback(providerName: string, code: string, stateToken: string) {
-    if (!stateToken || !this.pendingStates.has(stateToken)) {
-      throw new Error('Invalid or missing state token');
-    }
-
-    const stateCreatedAt = this.pendingStates.get(stateToken);
-    if (stateCreatedAt === undefined) throw new Error('State token not found in pending states');
-    this.pendingStates.delete(stateToken);
+    return { url: flow.buildAuthorizationUrl(stateToken), bindingValue };
+  }
 
-    const TEN_MINUTES = 10 * 60 * 1000;
-    if (Date.now() - stateCreatedAt > TEN_MINUTES) {
-      throw new Error('State token has expired');
-    }
+  async handleCallback(providerName: string, code: string, stateToken: string, bindingValue?: string) {
+    this.stateStore.consume(stateToken, providerName, bindingValue);
 
     const { flow, tokenManager } = this.getProvider(providerName);
     const tokens = await tokenManager.getTokens(code);

package/src/state-store.ts

@@ -0,0 +1,95 @@
+import { createHash, randomBytes, randomUUID } from 'node:crypto';
+import { BINDING_VALUE_BYTES, STATE_TTL_MS } from './constants.js';
+
+/**
+ * Server-side record for an OAuth flow that is in progress.
+ *
+ * Deliberately holds a *digest* of the binding value rather than the value
+ * itself: a callback is only accepted when the caller presents the plaintext
+ * that hashes to `bindingHash`, so the record on its own unlocks nothing.
+ */
+export interface PendingState {
+  provider: string;
+  bindingHash: string;
+  createdAt: number;
+}
+
+export interface IssuedState {
+  /** Sent to the provider as the OAuth2 `state` parameter. */
+  stateToken: string;
+  /** Held by the client that started the flow (a cookie), never by the provider. */
+  bindingValue: string;
+}
+
+/**
+ * Issues and validates OAuth2 `state` tokens bound to the client that started
+ * the flow (#36).
+ *
+ * Presence-plus-age on a process-global map is replay-window limiting, not the
+ * CSRF binding `state` exists to provide (RFC 6749 section 10.12): any state
+ * issued to any visitor validated for any callback, so an attacker could
+ * harvest their own state and code and deliver them to a victim, logging the
+ * victim in as the attacker. A state is now only accepted when the caller also
+ * presents the matching client-held binding value, and only at the provider it
+ * was issued for.
+ */
+export default class StateStore {
+  pending = new Map<string, PendingState>();
+  ttl: number;
+
+  constructor(ttl: number = STATE_TTL_MS) {
+    this.ttl = ttl;
+  }
+
+  static hash(value: string): string {
+    return createHash('sha256').update(value).digest('hex');
+  }
+
+  /** Length-independent, content-constant-time comparison of two digests. */
+  static digestsMatch(a: string, b: string): boolean {
+    if (a.length !== b.length) return false;
+
+    let difference = 0;
+    for (let index = 0; index < a.length; index++) {
+      difference |= a.charCodeAt(index) ^ b.charCodeAt(index);
+    }
+
+    return difference === 0;
+  }
+
+  issue(provider: string): IssuedState {
+    const stateToken = randomUUID();
+    const bindingValue = randomBytes(BINDING_VALUE_BYTES).toString('base64url');
+
+    this.pending.set(stateToken, {
+      provider,
+      bindingHash: StateStore.hash(bindingValue),
+      createdAt: Date.now(),
+    });
+
+    return { stateToken, bindingValue };
+  }
+
+  /**
+   * Validates and consumes a pending state. Throws on every rejection path.
+   *
+   * The record is removed as soon as the state is recognised — before the
+   * binding is checked — so a state cannot survive a failed attempt and be
+   * used as a target for guessing the binding value.
+   */
+  consume(stateToken: string | undefined, provider: string, bindingValue: string | undefined): void {
+    if (!stateToken) throw new Error('Invalid or missing state token');
+
+    const record = this.pending.get(stateToken);
+    if (!record) throw new Error('Invalid or missing state token');
+    this.pending.delete(stateToken);
+
+    if (Date.now() - record.createdAt > this.ttl) throw new Error('State token has expired');
+    if (record.provider !== provider) throw new Error('State token was not issued for this provider');
+    if (!bindingValue) throw new Error('Missing state binding value');
+
+    if (!StateStore.digestsMatch(StateStore.hash(bindingValue), record.bindingHash)) {
+      throw new Error('State token is not bound to this client');
+    }
+  }
+}

package/src/types/node.d.ts

@@ -1,3 +1,10 @@
 declare module 'node:crypto' {
+  interface Hash {
+    update(data: string): Hash;
+    digest(encoding: 'hex'): string;
+  }
+
   export function randomUUID(): string;
+  export function randomBytes(size: number): { toString(encoding: 'base64url' | 'hex'): string };
+  export function createHash(algorithm: string): Hash;
 }

package/src/types/stonyx.d.ts

@@ -3,6 +3,8 @@ declare module 'stonyx/config' {
     providers: Record<string, { module?: string; [key: string]: unknown }>;
     sessionDuration: number;
     frontendCallbackUrl?: string;
+    logColor?: string;
+    logMethod?: string;
   }
   interface Config {
     oauth: OAuthConfig;
@@ -14,7 +16,13 @@ declare module 'stonyx/config' {
 }
 
 declare module 'stonyx/log' {
-  const log: Record<string, ((...args: unknown[]) => void) | undefined>;
+  interface Log {
+    oauth(message: string): void;
+    error(message: string): void;
+    defineType(type: string, setting: string, options?: Record<string, unknown> | null): void;
+    [key: string]: unknown;
+  }
+  const log: Log;
   export default log;
 }