@stonyx/oauth 0.1.1-alpha.15 → 0.1.1-alpha.17

package/README.md

@@ -11,7 +11,7 @@ OAuth2 authentication module for the Stonyx framework. Provides a generic OAuth2
 Add as a devDependency to your Stonyx project:
 
 ```bash
-npm install @stonyx/oauth
+pnpm add @stonyx/oauth
 ```
 
 Requires `@stonyx/rest-server` as a peer dependency.
@@ -55,10 +55,99 @@ 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 on every host except loopback (`localhost`, `127.0.0.0/8`, `::1`, `0.0.0.0`) | deriving it from `req.secure` would omit it in the standard production topology: behind a TLS-terminating proxy Express reports the request as plaintext unless `trust proxy` is enabled, and `@stonyx/rest-server` leaves that off by default. A non-loopback plaintext deployment therefore cannot store this cookie — that failure is loud and deliberate, in preference to a silently insecure production cookie |
+| `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.
+
+Two distinct failure modes surface on two different routes. They are unrelated,
+and the route is the fastest way to tell them apart:
+
+- **The cookie cannot be set at all.** `GET /auth/login/:provider` responds
+  `500` rather than issuing a state it cannot bind, and logs
+  `OAuth: unable to set the state binding cookie; login rejected`. This is a
+  framework-wiring condition — the response object the module reaches for is
+  not there — not a network or proxy one.
+- **`Set-Cookie` is stripped in transit** by a reverse proxy or CDN.
+  `GET /auth/login/:provider` **succeeds and redirects normally**; the module
+  never learns the header was dropped. The failure surfaces one hop later, at
+  `GET /auth/callback/:provider`, as `?error=auth_failed` on
+  `frontendCallbackUrl` (or a bare `500` when it is unset), with
+  `OAuth: callback rejected — Missing state binding value` in the log. First
+  thing to check: does the login response reach the browser carrying
+  `Set-Cookie: stonyx_oauth_state`.
+
+Every callback rejection is logged server-side with its reason
+(`OAuth: callback rejected — ...`), which distinguishes an unknown state, a
+wrong provider, an expired state, a missing binding value and a wrong binding
+value. The client-facing `auth_failed` stays deliberately opaque.
+
+A failed callback **cannot be retried**: the pending record is consumed on any
+callback presenting a recognised `state`, so refreshing the error page or going
+back and forward produces a second `auth_failed`. The user must restart at
+`GET /auth/login/:provider`. Only one login can be in flight per browser at a
+time, for the same reason — the binding cookie has one fixed name, so starting
+a second login overwrites the first flow's binding value and the earlier flow
+will fail at its callback.
+
+### 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 +208,12 @@ 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. Pending
+records are removed when a callback consumes them, not swept on a timer — the
+ten-minute age bound is only evaluated when a matching callback arrives, so an
+abandoned flow's record persists until the process restarts. See
+[#38](https://github.com/abofs/stonyx-oauth/issues/38).
 
 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 | undefined): 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,34 @@ 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'>;
+    /**
+     * Whether the binding cookie is issued with `Secure`.
+     *
+     * Not `req.secure`. Express derives that from the socket unless `trust proxy`
+     * is enabled, and `@stonyx/rest-server` leaves it off by default
+     * (`trustProxy: REST_TRUST_PROXY === 'true'`). In the standard production
+     * topology — TLS terminated at a proxy, plaintext to the origin — `req.secure`
+     * is therefore `false` on every request to an HTTPS site, and the binding
+     * cookie would ship without `Secure` while the deployment looks correct.
+     *
+     * So `Secure` is set unconditionally except on a loopback host. Guessing
+     * wrong there breaks a non-loopback plaintext development setup, which fails
+     * at the first login and is loud. The alternative fails silently, in
+     * production, on the one attribute protecting the value this whole mechanism
+     * is built around.
+     */
+    isSecureContext(req: RouteRequest): boolean;
+    setBindingCookie(req: RouteRequest, bindingValue: string): boolean;
+    readBindingCookie(req: RouteRequest): string | undefined;
+    clearBindingCookie(req: RouteRequest): void;
 }
 export {};

package/dist/auth-request.js

@@ -1,4 +1,11 @@
 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';
+/**
+ * Hosts treated as a development origin, and the only ones exempt from
+ * `Secure` on the binding cookie. See `AuthRequest.isSecureContext`.
+ */
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '::1', '0.0.0.0']);
 export default class AuthRequest extends Request {
     oauth;
     constructor(oauth) {
@@ -18,17 +25,23 @@ 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;
+                const bindingValue = this.readBindingCookie(req);
                 if (error) {
                     if (this.oauth.frontendCallbackUrl) {
                         state.redirect = `${this.oauth.frontendCallbackUrl}?error=${encodeURIComponent(error)}`;
@@ -38,8 +51,15 @@ export default class AuthRequest extends Request {
                 }
                 if (!code)
                     return 400;
+                // The binding value is single-use, so this callback is the end of that
+                // cookie's life — but only from here down, where the state is actually
+                // consumed. Clearing above the two early returns denied login to a
+                // client still at the provider's consent screen, via an
+                // attacker-induced navigation to `?error=...` that needs no knowledge
+                // of the victim's state at all.
+                this.clearBindingCookie(req);
                 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,
@@ -50,7 +70,14 @@ export default class AuthRequest extends Request {
                     }
                     return session;
                 }
-                catch {
+                catch (rejection) {
+                    // `StateStore.consume` distinguishes five rejection reasons that
+                    // otherwise collapse into one opaque outcome with no server-side
+                    // signal at all. The client-facing `auth_failed` stays opaque; the
+                    // server has no reason to be. The messages are fixed strings, so
+                    // nothing caller-controlled reaches the log.
+                    const reason = rejection instanceof Error ? rejection.message : String(rejection);
+                    log.error(`OAuth: callback rejected — ${reason}`);
                     if (this.oauth.frontendCallbackUrl) {
                         state.redirect = `${this.oauth.frontendCallbackUrl}?error=auth_failed`;
                         return;
@@ -65,4 +92,86 @@ 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: this.isSecureContext(req),
+        };
+    }
+    /**
+     * Whether the binding cookie is issued with `Secure`.
+     *
+     * Not `req.secure`. Express derives that from the socket unless `trust proxy`
+     * is enabled, and `@stonyx/rest-server` leaves it off by default
+     * (`trustProxy: REST_TRUST_PROXY === 'true'`). In the standard production
+     * topology — TLS terminated at a proxy, plaintext to the origin — `req.secure`
+     * is therefore `false` on every request to an HTTPS site, and the binding
+     * cookie would ship without `Secure` while the deployment looks correct.
+     *
+     * So `Secure` is set unconditionally except on a loopback host. Guessing
+     * wrong there breaks a non-loopback plaintext development setup, which fails
+     * at the first login and is loud. The alternative fails silently, in
+     * production, on the one attribute protecting the value this whole mechanism
+     * is built around.
+     */
+    isSecureContext(req) {
+        if (req.secure === true)
+            return true;
+        const host = req.headers.host;
+        if (!host)
+            return true;
+        // `[::1]:2666` -> `::1`; `localhost:2666` -> `localhost`.
+        const hostname = (host.startsWith('[')
+            ? host.slice(1, host.indexOf(']'))
+            : host.split(':')[0]).toLowerCase();
+        if (LOOPBACK_HOSTS.has(hostname))
+            return false;
+        if (hostname.startsWith('127.'))
+            return false;
+        if (hostname === 'localhost' || hostname.endsWith('.localhost'))
+            return false;
+        return 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;
+            // Not decoded. The binding value is base64url, whose alphabet
+            // `encodeURIComponent` never escapes, so a decode buys nothing — and
+            // `decodeURIComponent` throws `URIError` on malformed input, which any
+            // unauthenticated caller can supply, turning the first line of the
+            // callback into a 500 with a stack trace.
+            return 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,40 @@
 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;
+    /**
+     * `bindingValue` is required, not optional (#36). An optional parameter lets
+     * an existing three-argument call site keep compiling and then fail at
+     * runtime on the first real login; a compile error is the loudest disclosure
+     * channel available for this break. It is typed as possibly-undefined
+     * because the route handler passes through whatever the client presented,
+     * and `StateStore.consume` rejects falsy explicitly.
+     */
+    handleCallback(providerName: string, code: string, stateToken: string, bindingValue: string | undefined): 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() {
@@ -47,22 +48,19 @@ 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');
-        }
+    /**
+     * `bindingValue` is required, not optional (#36). An optional parameter lets
+     * an existing three-argument call site keep compiling and then fail at
+     * runtime on the first real login; a compile error is the loudest disclosure
+     * channel available for this break. It is typed as possibly-undefined
+     * because the route handler passes through whatever the client presented,
+     * and `StateStore.consume` rejects falsy explicitly.
+     */
+    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,60 @@
+/**
+ * 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 TTL,
+     * provider and binding checks — so every state gets exactly one attempt
+     * whatever the outcome.
+     *
+     * That uniformity is the justification, not brute-force resistance:
+     * guessing `BINDING_VALUE_BYTES` of CSPRNG output is infeasible whether or
+     * not the record survives. What retaining it would buy an attacker is a
+     * repeatable, unauthenticated oracle on this endpoint for the state's full
+     * lifetime — and the safety of that would then rest entirely on an entropy
+     * constant a future change can lower. One attempt per state is a structural
+     * property; entropy arithmetic is not.
+     *
+     * The trade is real: an attacker who already knows a victim's state can burn
+     * it, and the victim must restart at `/auth/login/:provider`. That vector is
+     * accepted deliberately — it requires the victim's `randomUUID` state, and
+     * it is self-healing on retry.
+     */
+    consume(stateToken: string | undefined, provider: string, bindingValue: string | undefined): void;
+}

package/dist/state-store.js

@@ -0,0 +1,81 @@
+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 TTL,
+     * provider and binding checks — so every state gets exactly one attempt
+     * whatever the outcome.
+     *
+     * That uniformity is the justification, not brute-force resistance:
+     * guessing `BINDING_VALUE_BYTES` of CSPRNG output is infeasible whether or
+     * not the record survives. What retaining it would buy an attacker is a
+     * repeatable, unauthenticated oracle on this endpoint for the state's full
+     * lifetime — and the safety of that would then rest entirely on an entropy
+     * constant a future change can lower. One attempt per state is a structural
+     * property; entropy arithmetic is not.
+     *
+     * The trade is real: an attacker who already knows a victim's state can burn
+     * it, and the victim must restart at `/auth/login/:provider`. That vector is
+     * accepted deliberately — it requires the victim's `randomUUID` state, and
+     * it is self-healing on retry.
+     */
+    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.15",
+  "version": "0.1.1-alpha.17",
   "description": "OAuth2 authentication module for the Stonyx framework",
   "repository": {
     "type": "git",
@@ -54,16 +54,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.60",
-    "@stonyx/utils": "0.2.3-beta.23",
-    "@stonyx/logs": "1.0.1-beta.16",
+    "@stonyx/rest-server": "0.2.1-beta.81",
+    "@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,64 @@
 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;
+}
+
+/**
+ * Hosts treated as a development origin, and the only ones exempt from
+ * `Secure` on the binding cookie. See `AuthRequest.isSecureContext`.
+ */
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '::1', '0.0.0.0']);
 
 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 | undefined,
+  ): 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 +88,26 @@ 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;
 
+        const bindingValue = this.readBindingCookie(req);
+
         if (error) {
           if (this.oauth.frontendCallbackUrl) {
             state.redirect = `${this.oauth.frontendCallbackUrl}?error=${encodeURIComponent(error)}`;
@@ -63,8 +118,16 @@ export default class AuthRequest extends Request {
 
         if (!code) return 400;
 
+        // The binding value is single-use, so this callback is the end of that
+        // cookie's life — but only from here down, where the state is actually
+        // consumed. Clearing above the two early returns denied login to a
+        // client still at the provider's consent screen, via an
+        // attacker-induced navigation to `?error=...` that needs no knowledge
+        // of the victim's state at all.
+        this.clearBindingCookie(req);
+
         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({
@@ -76,7 +139,15 @@ export default class AuthRequest extends Request {
           }
 
           return session;
-        } catch {
+        } catch (rejection) {
+          // `StateStore.consume` distinguishes five rejection reasons that
+          // otherwise collapse into one opaque outcome with no server-side
+          // signal at all. The client-facing `auth_failed` stays opaque; the
+          // server has no reason to be. The messages are fixed strings, so
+          // nothing caller-controlled reaches the log.
+          const reason = rejection instanceof Error ? rejection.message : String(rejection);
+          log.error(`OAuth: callback rejected — ${reason}`);
+
           if (this.oauth.frontendCallbackUrl) {
             state.redirect = `${this.oauth.frontendCallbackUrl}?error=auth_failed`;
             return;
@@ -91,4 +162,94 @@ 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: this.isSecureContext(req),
+    };
+  }
+
+  /**
+   * Whether the binding cookie is issued with `Secure`.
+   *
+   * Not `req.secure`. Express derives that from the socket unless `trust proxy`
+   * is enabled, and `@stonyx/rest-server` leaves it off by default
+   * (`trustProxy: REST_TRUST_PROXY === 'true'`). In the standard production
+   * topology — TLS terminated at a proxy, plaintext to the origin — `req.secure`
+   * is therefore `false` on every request to an HTTPS site, and the binding
+   * cookie would ship without `Secure` while the deployment looks correct.
+   *
+   * So `Secure` is set unconditionally except on a loopback host. Guessing
+   * wrong there breaks a non-loopback plaintext development setup, which fails
+   * at the first login and is loud. The alternative fails silently, in
+   * production, on the one attribute protecting the value this whole mechanism
+   * is built around.
+   */
+  isSecureContext(req: RouteRequest): boolean {
+    if (req.secure === true) return true;
+
+    const host = req.headers.host;
+    if (!host) return true;
+
+    // `[::1]:2666` -> `::1`; `localhost:2666` -> `localhost`.
+    const hostname = (host.startsWith('[')
+      ? host.slice(1, host.indexOf(']'))
+      : host.split(':')[0]
+    ).toLowerCase();
+
+    if (LOOPBACK_HOSTS.has(hostname)) return false;
+    if (hostname.startsWith('127.')) return false;
+    if (hostname === 'localhost' || hostname.endsWith('.localhost')) return false;
+
+    return 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;
+
+      // Not decoded. The binding value is base64url, whose alphabet
+      // `encodeURIComponent` never escapes, so a decode buys nothing — and
+      // `decodeURIComponent` throws `URIError` on malformed input, which any
+      // unauthenticated caller can supply, turning the first line of the
+      // callback into a 500 with a stack trace.
+      return 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;
 
@@ -66,26 +78,28 @@ 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');
-    }
+  /**
+   * `bindingValue` is required, not optional (#36). An optional parameter lets
+   * an existing three-argument call site keep compiling and then fail at
+   * runtime on the first real login; a compile error is the loudest disclosure
+   * channel available for this break. It is typed as possibly-undefined
+   * because the route handler passes through whatever the client presented,
+   * and `StateStore.consume` rejects falsy explicitly.
+   */
+  async handleCallback(
+    providerName: string,
+    code: string,
+    stateToken: string,
+    bindingValue: string | undefined,
+  ) {
+    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,108 @@
+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 TTL,
+   * provider and binding checks — so every state gets exactly one attempt
+   * whatever the outcome.
+   *
+   * That uniformity is the justification, not brute-force resistance:
+   * guessing `BINDING_VALUE_BYTES` of CSPRNG output is infeasible whether or
+   * not the record survives. What retaining it would buy an attacker is a
+   * repeatable, unauthenticated oracle on this endpoint for the state's full
+   * lifetime — and the safety of that would then rest entirely on an entropy
+   * constant a future change can lower. One attempt per state is a structural
+   * property; entropy arithmetic is not.
+   *
+   * The trade is real: an attacker who already knows a victim's state can burn
+   * it, and the victim must restart at `/auth/login/:provider`. That vector is
+   * accepted deliberately — it requires the victim's `randomUUID` state, and
+   * it is self-healing on retry.
+   */
+  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

@@ -18,6 +18,7 @@ declare module 'stonyx/config' {
 declare module 'stonyx/log' {
   interface Log {
     oauth(message: string): void;
+    error(message: string): void;
     defineType(type: string, setting: string, options?: Record<string, unknown> | null): void;
     [key: string]: unknown;
   }