@stonyx/oauth 0.1.1-beta.164 → 0.1.1-beta.166

package/README.md

@@ -116,6 +116,74 @@ providers: {
 }
 ```
 
+## Login CSRF protection — the `oauth_state` cookie
+
+### Breaking changes
+
+**As of the fix for [#36](https://github.com/abofs/stonyx-oauth/issues/36).** Two separate breaks — an integration can hit either one independently.
+
+**1. The login flow now requires a cookie jar.** A client that cannot hold a cookie between `/auth/login/:provider` and `/auth/callback/:provider` can no longer complete a login. That is the point of the change — see [Migration](#migration-from-a-cookie-less-client) below.
+
+**2. The JS API changed shape.** This one is invisible to anyone who only reads the cookie disclosure above. If you import the module's default export and call it directly — wrapping it, monkeypatching it, or driving it in tests — three things changed:
+
+| | Before | After |
+|---|--------|-------|
+| `getAuthorizationUrl(provider)` | returns the authorization URL as a `string` | returns `{ url, stateToken, bindingValue }` |
+| `handleCallback(provider, code, state)` | three arguments | requires a fourth, `bindingValues: readonly string[]` — every value the caller presented under the `oauth_state` cookie name |
+| `pendingStates` values | `number` (a creation timestamp) | `{ bindingHash, createdAt }` |
+
+None of these throws at import time, and a `typeof … === 'function'` surface check passes on all three: the arity and the return type change, not the presence. Callers must be updated by inspection.
+
+The HTTP contract is otherwise unchanged — the [route table](#routes) is the same, no config key was added or changed, and both routes still `302` on their success paths. One status is new: `/auth/login/:provider` returns `500` when the binding cookie cannot be set, which it never did before (see below).
+
+`GET /auth/login/:provider` issues an `oauth_state` cookie carrying a per-flow binding value, and keeps only its SHA-256 server-side. `GET /auth/callback/:provider` accepts an OAuth2 `state` only from a caller that also presents the matching cookie value.
+
+Without it, `state` was verified by membership in a server-side map plus an age bound, and nothing else. There was no value the browser that started the flow carried that another browser did not, so an attacker could start a login, harvest their own `state` and `code`, deliver them to a victim over a plain link, and log that victim into the *attacker's* account (RFC 6749 §10.12, RFC 9700). The victim's own account and data are not exposed; what is at risk is whatever they author afterwards, believing the session is theirs.
+
+### Cookie attributes
+
+| Attribute | Value | Why |
+|-----------|-------|-----|
+| Name | `oauth_state` | Issued at login, cleared on a successful callback. The *state* is single-use; the cookie name is fixed, so it is not — see [Concurrent logins](#concurrent-logins-in-the-same-browser) |
+| `HttpOnly` | always | 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. `Strict` withholds the cookie on exactly that request and breaks every login |
+| `Path` | `/` | Routing is case-insensitive; RFC 6265 `Path` matching is not. A narrower path silently drops the cookie on a case-varied callback |
+| `Secure` | when the provider's `redirectUri` is not `http:` | Derived from your configured redirect URI, so plaintext local development works and a TLS deployment behind a terminating proxy still gets `Secure` |
+| `Max-Age` | 600 seconds | Matches the server-side state TTL |
+
+If the runtime cannot set the cookie, `/auth/login/:provider` returns `500` and issues no state, rather than issuing one that cannot be bound.
+
+### Requirements for consumers
+
+- **Start the login as a top-level navigation** (`window.location = '/auth/login/discord'`, or a plain link). This is the documented pattern and it avoids CORS entirely.
+- **Serve login and callback from the same host.** The cookie is host-scoped and carries no `Domain` attribute. A **different port on the same host is fine** — port is not part of cookie scope (RFC 6265 §8.5) — but a different *hostname* is not: the cookie is never sent and the login fails. Both routes are mounted on the same `AuthRequest`, so this only bites when something in front of the app splits them across hostnames (a proxy split, or `app.example.com` for login and `example.com` for the callback).
+- **Keep your configured `redirectUri` on the same scheme the login endpoint is served over.** `Secure` is derived from `redirectUri`, so an `https` `redirectUri` behind a plaintext login endpoint issues a `Secure` cookie that the browser silently discards. Every login then fails the binding check **with no server-side signal** — the callback simply reports `error=auth_failed` if `frontendCallbackUrl` is configured, or a bare `500` if it is not. Check this first if logins start failing after a TLS or proxy change.
+- An XHR-initiated login will not work: `@stonyx/rest-server` never passes `credentials: true` to CORS, so the browser will neither store nor send the cookie on a cross-origin XHR. Narrowing `REST_CORS_ORIGIN` from its `*` default does not change this.
+
+### Migration from a cookie-less client
+
+Scripted and server-to-server logins break. If you drive the flow yourself, carry the `Set-Cookie` from the login response back as a `Cookie` header on the callback:
+
+```javascript
+const login = await fetch(`${host}/auth/login/discord`, { redirect: 'manual' });
+const cookie = login.headers.getSetCookie().map(header => header.split(';')[0]).join('; ');
+const state = new URL(login.headers.get('location')).searchParams.get('state');
+
+// ...provider redirects back with `code`...
+await fetch(`${host}/auth/callback/discord?code=${code}&state=${state}`, {
+  redirect: 'manual',
+  headers: { cookie },
+});
+```
+
+In a browser, `fetch` needs `credentials: 'include'` for a cross-origin request — but see the CORS caveat above; a top-level navigation is the supported path.
+
+### Concurrent logins in the same browser
+
+The cookie name is fixed and its `Path` is `/`, so a second login started in the same browser overwrites the first tab's binding value. The first tab's callback then presents the second tab's value and fails the binding check — redirecting with `error=auth_failed` if `frontendCallbackUrl` is configured, or returning `500` if it is not.
+
+This fails closed — no session is minted for the wrong flow, and it is not a way past the binding — but it is an availability regression against the previous behaviour, where two concurrent logins both completed. A user who opens two login tabs has to finish in the one they started last, or retry.
+
 ## Session Management
 
 Sessions are stored in-memory using a `Map`. Sessions are lost on server restart.

package/dist/auth-request.d.ts

@@ -1,18 +1,51 @@
 import { Request } from '@stonyx/rest-server';
+interface AuthorizationRequest {
+    url: string;
+    stateToken: string;
+    bindingValue: string;
+}
 interface OAuthInstance {
     frontendCallbackUrl?: string;
+    stateTtl: number;
     getSession(sessionId: string): unknown;
-    getAuthorizationUrl(providerName: string): string;
-    handleCallback(providerName: string, code: string, stateToken: string): Promise<{
+    getAuthorizationUrl(providerName: string): AuthorizationRequest;
+    discardState(stateToken: string): void;
+    redirectUriFor(providerName: string): string | undefined;
+    handleCallback(providerName: string, code: string, stateToken: string, bindingValues: readonly string[]): Promise<{
         sessionId: string;
         expiresAt: number;
     }>;
     logout(sessionId: string): void;
 }
+export 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.pipe.headers`
+ * is unreachable once `state.redirect` is set (`request.ts` returns on the
+ * redirect first), so setting a cookie means reaching for `req.res`.
+ *
+ * This is a deliberate, sanctioned interim reach-around, not an accident:
+ * `abofs/stonyx-rest-server#45` is the reopened successor issue that adds a
+ * first-class header/cookie affordance to migrate onto, and it is sequenced
+ * after this fix. `setBindingCookie` fails closed if the affordance is not
+ * there, which is what contains the dependency.
+ */
+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>;
+    res?: ResponseLike;
 }
 interface RouteState {
     redirect?: string;
@@ -23,13 +56,42 @@ 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;
         };
     };
+    /**
+     * Whether the binding cookie is issued with `Secure`.
+     *
+     * Derived from the scheme of the provider's configured `redirectUri`, which
+     * is the deployment's own statement of the origin this cookie has to survive
+     * a round trip to.
+     *
+     * Not `req.secure`: express derives that from the socket unless `trust proxy`
+     * is on, and `@stonyx/rest-server` leaves it off by default, so in the
+     * standard production topology — TLS terminated at a proxy, plaintext to the
+     * origin — `req.secure` is `false` on every request to an HTTPS site and the
+     * cookie would ship without `Secure` while the deployment looks correct. Not
+     * the `Host` header either: that is attacker-controllable on any non-browser
+     * client. And not hardcoded `true`, which breaks plaintext local development.
+     *
+     * An unparseable or absent redirect URI fails secure.
+     */
+    isSecureContext(providerName: string): boolean;
+    cookieOptions(providerName: string): Omit<CookieOptions, 'maxAge'>;
+    setBindingCookie(req: RouteRequest, providerName: string, bindingValue: string): boolean;
+    /**
+     * Every value the client presented under the binding cookie's name.
+     *
+     * Not the first one, and not capped — see `OAuth.anyCandidateMatches` for why
+     * either would hand an attacker a permanent, unauthenticated denial of login
+     * for any victim they can plant a same-named cookie on.
+     */
+    readBindingCookies(req: RouteRequest): string[];
+    clearBindingCookie(req: RouteRequest, providerName: string): void;
 }
 export {};

package/dist/auth-request.js

@@ -1,4 +1,24 @@
 import { Request } from '@stonyx/rest-server';
+import log from 'stonyx/log';
+/**
+ * The cookie carrying the client-held half of the OAuth2 `state` binding (#36).
+ *
+ * The attributes below are load-bearing, not cosmetic:
+ *
+ *   - `SameSite=Lax` — the callback is a cross-site, top-level GET navigation
+ *     initiated by the provider. `Strict` withholds the cookie on exactly that
+ *     request, breaking 100% of logins while passing every CSRF test; `None`
+ *     requires `Secure` and widens exposure for no benefit.
+ *   - `Path=/` — routing is case-insensitive today
+ *     (`abofs/stonyx-rest-server#47`: `GET /AUTH/login/discord` redirects) but
+ *     RFC 6265 section 5.1.4 `Path` matching is case-sensitive, so a narrow
+ *     `/auth` silently drops the cookie on a case-varied callback and breaks
+ *     login.
+ *   - `HttpOnly` — script must not be able to read or forge the binding value.
+ */
+const STATE_COOKIE_NAME = 'oauth_state';
+const STATE_COOKIE_PATH = '/';
+const STATE_COOKIE_SAME_SITE = 'lax';
 export default class AuthRequest extends Request {
     oauth;
     constructor(oauth) {
@@ -18,13 +38,21 @@ 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 it is withdrawn rather
+                // than issued unbindable.
+                if (!this.setBindingCookie(req, providerName, authorization.bindingValue)) {
+                    this.oauth.discardState(authorization.stateToken);
+                    return 500;
+                }
+                state.redirect = authorization.url;
             },
             '/callback/:provider': async (req, state) => {
                 const { provider: providerName } = req.params;
@@ -39,7 +67,17 @@ 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, this.readBindingCookies(req));
+                    // Cleared only here, on the success path, which is the only path that
+                    // is certain to have consumed a state belonging to *this* client.
+                    //
+                    // Clearing on failure instead looks harmless and is not: `code` is
+                    // attacker-supplied and unvalidated, so a bare `?code=1` — no
+                    // knowledge of anyone's state — would delete the binding cookie of a
+                    // client still sitting on the provider's consent screen, leaving
+                    // their pending state untouched so nothing is detectable
+                    // server-side, and their real callback then fails.
+                    this.clearBindingCookie(req, providerName);
                     if (this.oauth.frontendCallbackUrl) {
                         const params = new URLSearchParams({
                             sessionId: session.sessionId,
@@ -65,4 +103,85 @@ export default class AuthRequest extends Request {
             },
         }
     };
+    /**
+     * Whether the binding cookie is issued with `Secure`.
+     *
+     * Derived from the scheme of the provider's configured `redirectUri`, which
+     * is the deployment's own statement of the origin this cookie has to survive
+     * a round trip to.
+     *
+     * Not `req.secure`: express derives that from the socket unless `trust proxy`
+     * is on, and `@stonyx/rest-server` leaves it off by default, so in the
+     * standard production topology — TLS terminated at a proxy, plaintext to the
+     * origin — `req.secure` is `false` on every request to an HTTPS site and the
+     * cookie would ship without `Secure` while the deployment looks correct. Not
+     * the `Host` header either: that is attacker-controllable on any non-browser
+     * client. And not hardcoded `true`, which breaks plaintext local development.
+     *
+     * An unparseable or absent redirect URI fails secure.
+     */
+    isSecureContext(providerName) {
+        const redirectUri = this.oauth.redirectUriFor(providerName);
+        if (!redirectUri)
+            return true;
+        try {
+            return new URL(redirectUri).protocol !== 'http:';
+        }
+        catch {
+            return true;
+        }
+    }
+    cookieOptions(providerName) {
+        return {
+            httpOnly: true,
+            sameSite: STATE_COOKIE_SAME_SITE,
+            path: STATE_COOKIE_PATH,
+            secure: this.isSecureContext(providerName),
+        };
+    }
+    setBindingCookie(req, providerName, 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(providerName),
+            maxAge: this.oauth.stateTtl,
+        });
+        return true;
+    }
+    /**
+     * Every value the client presented under the binding cookie's name.
+     *
+     * Not the first one, and not capped — see `OAuth.anyCandidateMatches` for why
+     * either would hand an attacker a permanent, unauthenticated denial of login
+     * for any victim they can plant a same-named cookie on.
+     */
+    readBindingCookies(req) {
+        const header = req.headers.cookie;
+        if (!header)
+            return [];
+        const values = [];
+        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 decoding 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.
+            values.push(part.slice(separator + 1).trim());
+        }
+        return values;
+    }
+    clearBindingCookie(req, providerName) {
+        const { res } = req;
+        if (typeof res?.clearCookie !== 'function')
+            return;
+        res.clearCookie(STATE_COOKIE_NAME, this.cookieOptions(providerName));
+    }
 }

package/dist/main.d.ts

@@ -1,21 +1,105 @@
 import TokenManager from './token-manager.js';
 import SessionManager from './session-manager.js';
 import type OAuthFlow from './oauth-flow.js';
+/** Lifetime of a pending state, 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;
 interface ProviderEntry {
     flow: OAuthFlow;
     tokenManager: TokenManager;
 }
+/**
+ * A flow that is in progress.
+ *
+ * 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 {
+    bindingHash: string;
+    createdAt: number;
+}
+export interface IssuedState {
+    /** Sent to the provider as the OAuth2 `state` parameter. */
+    url: string;
+    /** Retained so a login that cannot be bound can withdraw its own state. */
+    stateToken: string;
+    /** Held by the client that started the flow, never by the provider. */
+    bindingValue: string;
+}
 export default class OAuth {
     static instance: OAuth | null;
     providers: Map<string, ProviderEntry>;
-    pendingStates: Map<string, number>;
+    pendingStates: Map<string, PendingState>;
+    stateTtl: number;
     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>;
+    /**
+     * SHA-256 of a binding value, hex encoded.
+     *
+     * The pending record stores the digest so that read access to the map does
+     * not hand over the value a callback must present.
+     */
+    static hash(value: string): string;
+    /** Length-independent, content-constant-time comparison of two digests. */
+    static digestsMatch(a: string, b: string): boolean;
+    /**
+     * Whether *any* presented value is the binding value for this record.
+     *
+     * Every candidate is tried, and the callback is accepted if one matches.
+     * Stopping at the first value carrying the cookie's name instead makes a
+     * planted cookie a permanent, unauthenticated denial of login: RFC 6265
+     * section 5.4 orders the `Cookie` header by path length then creation time,
+     * so an attacker with content control on a sibling subdomain sets a
+     * same-named cookie once and every subsequent callback for that victim reads
+     * theirs, fails the binding check, and burns the state on the way out. The
+     * victim cannot recover by retrying.
+     *
+     * Accepting any match gives an attacker nothing: they would have to present
+     * the victim's own binding value, which is the property being checked. And
+     * the candidate list is deliberately uncapped — a cap does not bound an
+     * attack, it *is* one, reinstating that denial above its own threshold
+     * because the planted cookies are the ones that sort first. The work is
+     * already bounded by Node's 16 KB header limit.
+     *
+     * The reduce does not short-circuit, so the work is a function of how many
+     * values were presented and not of which one matched.
+     */
+    static anyCandidateMatches(candidates: readonly string[], bindingHash: string): boolean;
+    /**
+     * Starts a flow: an OAuth2 `state` for the provider, and a binding value for
+     * the client that asked for it.
+     *
+     * `state` on its own is replay-window limiting, not the CSRF binding it
+     * exists to provide (RFC 6749 section 10.12, RFC 9700): before this, any
+     * state issued to any visitor validated for any callback, so an attacker
+     * could harvest their own state and code, deliver them to a victim over a
+     * plain link, and log the victim into the attacker's account. The binding
+     * value is the thing the victim's browser carries and the attacker's does
+     * not (#36).
+     */
+    getAuthorizationUrl(providerName: string): IssuedState;
+    /**
+     * Withdraws a state that was issued but could not be handed to a client.
+     *
+     * Used by the login route when the binding cookie cannot be set: a state the
+     * client cannot be bound to is exactly the defect this mechanism exists to
+     * prevent, so it must not outlive the request that failed to bind it.
+     */
+    discardState(stateToken: string): void;
+    /**
+     * Validates and consumes a pending state, then completes the flow.
+     *
+     * `bindingValues` is every value the client presented under the binding
+     * cookie's name — see `anyCandidateMatches`.
+     */
+    handleCallback(providerName: string, code: string, stateToken: string, bindingValues: readonly string[]): Promise<import("./session-manager.js").SessionResult>;
+    /** The provider's configured redirect URI, used to decide the cookie's `Secure`. */
+    redirectUriFor(providerName: string): string | undefined;
     getSession(sessionId: string): unknown;
     logout(sessionId: string): void;
 }

package/dist/main.js

@@ -1,3 +1,4 @@
+import { createHash, randomBytes, randomUUID } from 'node:crypto';
 import config from 'stonyx/config';
 import log from 'stonyx/log';
 import { waitForModule } from 'stonyx';
@@ -7,10 +8,15 @@ import TokenManager from './token-manager.js';
 import SessionManager from './session-manager.js';
 import AuthRequest from './auth-request.js';
 setup(['authenticate']);
+/** Lifetime of a pending state, 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;
 export default class OAuth {
     static instance;
     providers = new Map();
     pendingStates = new Map();
+    stateTtl = STATE_TTL_MS;
     sessionManager;
     frontendCallbackUrl;
     constructor() {
@@ -45,24 +51,112 @@ export default class OAuth {
             throw new Error(`OAuth provider "${name}" is not configured`);
         return provider;
     }
+    /**
+     * SHA-256 of a binding value, hex encoded.
+     *
+     * The pending record stores the digest so that read access to the map does
+     * not hand over the value a callback must present.
+     */
+    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;
+    }
+    /**
+     * Whether *any* presented value is the binding value for this record.
+     *
+     * Every candidate is tried, and the callback is accepted if one matches.
+     * Stopping at the first value carrying the cookie's name instead makes a
+     * planted cookie a permanent, unauthenticated denial of login: RFC 6265
+     * section 5.4 orders the `Cookie` header by path length then creation time,
+     * so an attacker with content control on a sibling subdomain sets a
+     * same-named cookie once and every subsequent callback for that victim reads
+     * theirs, fails the binding check, and burns the state on the way out. The
+     * victim cannot recover by retrying.
+     *
+     * Accepting any match gives an attacker nothing: they would have to present
+     * the victim's own binding value, which is the property being checked. And
+     * the candidate list is deliberately uncapped — a cap does not bound an
+     * attack, it *is* one, reinstating that denial above its own threshold
+     * because the planted cookies are the ones that sort first. The work is
+     * already bounded by Node's 16 KB header limit.
+     *
+     * The reduce does not short-circuit, so the work is a function of how many
+     * values were presented and not of which one matched.
+     */
+    static anyCandidateMatches(candidates, bindingHash) {
+        return candidates.reduce((matched, candidate) => OAuth.digestsMatch(OAuth.hash(candidate), bindingHash) || matched, false);
+    }
+    /**
+     * Starts a flow: an OAuth2 `state` for the provider, and a binding value for
+     * the client that asked for it.
+     *
+     * `state` on its own is replay-window limiting, not the CSRF binding it
+     * exists to provide (RFC 6749 section 10.12, RFC 9700): before this, any
+     * state issued to any visitor validated for any callback, so an attacker
+     * could harvest their own state and code, deliver them to a victim over a
+     * plain link, and log the victim into the attacker's account. The binding
+     * value is the thing the victim's browser carries and the attacker's does
+     * not (#36).
+     */
     getAuthorizationUrl(providerName) {
         const { flow } = this.getProvider(providerName);
-        const stateToken = crypto.randomUUID();
-        this.pendingStates.set(stateToken, Date.now());
-        return flow.buildAuthorizationUrl(stateToken);
+        const stateToken = randomUUID();
+        const bindingValue = randomBytes(BINDING_VALUE_BYTES).toString('base64url');
+        this.pendingStates.set(stateToken, {
+            bindingHash: OAuth.hash(bindingValue),
+            createdAt: Date.now(),
+        });
+        return { url: flow.buildAuthorizationUrl(stateToken), stateToken, bindingValue };
     }
-    async handleCallback(providerName, code, stateToken) {
-        if (!stateToken || !this.pendingStates.has(stateToken)) {
+    /**
+     * Withdraws a state that was issued but could not be handed to a client.
+     *
+     * Used by the login route when the binding cookie cannot be set: a state the
+     * client cannot be bound to is exactly the defect this mechanism exists to
+     * prevent, so it must not outlive the request that failed to bind it.
+     */
+    discardState(stateToken) {
+        this.pendingStates.delete(stateToken);
+    }
+    /**
+     * Validates and consumes a pending state, then completes the flow.
+     *
+     * `bindingValues` is every value the client presented under the binding
+     * cookie's name — see `anyCandidateMatches`.
+     */
+    async handleCallback(providerName, code, stateToken, bindingValues) {
+        const record = stateToken ? this.pendingStates.get(stateToken) : undefined;
+        if (!record)
             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');
+        // Consumed on recognition, before the TTL and binding checks, so every
+        // state gets exactly one attempt whatever the outcome. Checking the
+        // binding first would leave the record in place on a mismatch and turn
+        // this endpoint into a repeatable, unauthenticated oracle against the
+        // binding value for the state's full lifetime.
         this.pendingStates.delete(stateToken);
-        const TEN_MINUTES = 10 * 60 * 1000;
-        if (Date.now() - stateCreatedAt > TEN_MINUTES) {
+        if (Date.now() - record.createdAt > this.stateTtl) {
             throw new Error('State token has expired');
         }
+        // No "absent means skip". An empty candidate list is a rejection, which is
+        // what makes an attacker-delivered link fail for a victim who never
+        // started the flow and therefore holds no binding cookie.
+        const candidates = bindingValues.filter(value => value.length > 0);
+        if (candidates.length === 0)
+            throw new Error('Missing state binding value');
+        if (!OAuth.anyCandidateMatches(candidates, record.bindingHash)) {
+            throw new Error('State token is not bound to this client');
+        }
+        // Everything below burns a live authorization code, so the binding is
+        // settled before `exchangeCode` is ever reached.
         const { flow, tokenManager } = this.getProvider(providerName);
         const tokens = await tokenManager.getTokens(code);
         const rawUser = await flow.fetchUserInfo(tokens.accessToken);
@@ -70,6 +164,10 @@ export default class OAuth {
         await emit('authenticate', user);
         return this.sessionManager.create(user, tokens);
     }
+    /** The provider's configured redirect URI, used to decide the cookie's `Secure`. */
+    redirectUriFor(providerName) {
+        return this.providers.get(providerName)?.flow.redirectUri;
+    }
     getSession(sessionId) {
         return this.sessionManager.validate(sessionId);
     }

package/package.json

@@ -4,7 +4,7 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.1.1-beta.164",
+  "version": "0.1.1-beta.166",
   "description": "OAuth2 authentication module for the Stonyx framework",
   "repository": {
     "type": "git",

package/src/auth-request.ts

@@ -1,17 +1,79 @@
 import { Request } from '@stonyx/rest-server';
+import log from 'stonyx/log';
+
+/**
+ * The cookie carrying the client-held half of the OAuth2 `state` binding (#36).
+ *
+ * The attributes below are load-bearing, not cosmetic:
+ *
+ *   - `SameSite=Lax` — the callback is a cross-site, top-level GET navigation
+ *     initiated by the provider. `Strict` withholds the cookie on exactly that
+ *     request, breaking 100% of logins while passing every CSRF test; `None`
+ *     requires `Secure` and widens exposure for no benefit.
+ *   - `Path=/` — routing is case-insensitive today
+ *     (`abofs/stonyx-rest-server#47`: `GET /AUTH/login/discord` redirects) but
+ *     RFC 6265 section 5.1.4 `Path` matching is case-sensitive, so a narrow
+ *     `/auth` silently drops the cookie on a case-varied callback and breaks
+ *     login.
+ *   - `HttpOnly` — script must not be able to read or forge the binding value.
+ */
+const STATE_COOKIE_NAME = 'oauth_state';
+const STATE_COOKIE_PATH = '/';
+const STATE_COOKIE_SAME_SITE = 'lax';
+
+interface AuthorizationRequest {
+  url: string;
+  stateToken: string;
+  bindingValue: string;
+}
 
 interface OAuthInstance {
   frontendCallbackUrl?: string;
+  stateTtl: number;
   getSession(sessionId: string): unknown;
-  getAuthorizationUrl(providerName: string): string;
-  handleCallback(providerName: string, code: string, stateToken: string): Promise<{ sessionId: string; expiresAt: number }>;
+  getAuthorizationUrl(providerName: string): AuthorizationRequest;
+  discardState(stateToken: string): void;
+  redirectUriFor(providerName: string): string | undefined;
+  handleCallback(
+    providerName: string,
+    code: string,
+    stateToken: string,
+    bindingValues: readonly string[],
+  ): Promise<{ sessionId: string; expiresAt: number }>;
   logout(sessionId: string): void;
 }
 
+export 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.pipe.headers`
+ * is unreachable once `state.redirect` is set (`request.ts` returns on the
+ * redirect first), so setting a cookie means reaching for `req.res`.
+ *
+ * This is a deliberate, sanctioned interim reach-around, not an accident:
+ * `abofs/stonyx-rest-server#45` is the reopened successor issue that adds a
+ * first-class header/cookie affordance to migrate onto, and it is sequenced
+ * after this fix. `setBindingCookie` fails closed if the affordance is not
+ * there, which is what contains the dependency.
+ */
+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>;
+  res?: ResponseLike;
 }
 
 interface RouteState {
@@ -41,12 +103,22 @@ 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 it is withdrawn rather
+        // than issued unbindable.
+        if (!this.setBindingCookie(req, providerName, authorization.bindingValue)) {
+          this.oauth.discardState(authorization.stateToken);
+          return 500;
+        }
+
+        state.redirect = authorization.url;
       },
 
       '/callback/:provider': async (req: RouteRequest, state: RouteState) => {
@@ -64,7 +136,23 @@ 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,
+            this.readBindingCookies(req),
+          );
+
+          // Cleared only here, on the success path, which is the only path that
+          // is certain to have consumed a state belonging to *this* client.
+          //
+          // Clearing on failure instead looks harmless and is not: `code` is
+          // attacker-supplied and unvalidated, so a bare `?code=1` — no
+          // knowledge of anyone's state — would delete the binding cookie of a
+          // client still sitting on the provider's consent screen, leaving
+          // their pending state untouched so nothing is detectable
+          // server-side, and their real callback then fails.
+          this.clearBindingCookie(req, providerName);
 
           if (this.oauth.frontendCallbackUrl) {
             const params = new URLSearchParams({
@@ -91,4 +179,93 @@ export default class AuthRequest extends Request {
       },
     }
   };
+
+  /**
+   * Whether the binding cookie is issued with `Secure`.
+   *
+   * Derived from the scheme of the provider's configured `redirectUri`, which
+   * is the deployment's own statement of the origin this cookie has to survive
+   * a round trip to.
+   *
+   * Not `req.secure`: express derives that from the socket unless `trust proxy`
+   * is on, and `@stonyx/rest-server` leaves it off by default, so in the
+   * standard production topology — TLS terminated at a proxy, plaintext to the
+   * origin — `req.secure` is `false` on every request to an HTTPS site and the
+   * cookie would ship without `Secure` while the deployment looks correct. Not
+   * the `Host` header either: that is attacker-controllable on any non-browser
+   * client. And not hardcoded `true`, which breaks plaintext local development.
+   *
+   * An unparseable or absent redirect URI fails secure.
+   */
+  isSecureContext(providerName: string): boolean {
+    const redirectUri = this.oauth.redirectUriFor(providerName);
+    if (!redirectUri) return true;
+
+    try {
+      return new URL(redirectUri).protocol !== 'http:';
+    } catch {
+      return true;
+    }
+  }
+
+  cookieOptions(providerName: string): Omit<CookieOptions, 'maxAge'> {
+    return {
+      httpOnly: true,
+      sameSite: STATE_COOKIE_SAME_SITE,
+      path: STATE_COOKIE_PATH,
+      secure: this.isSecureContext(providerName),
+    };
+  }
+
+  setBindingCookie(req: RouteRequest, providerName: string, 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(providerName),
+      maxAge: this.oauth.stateTtl,
+    });
+
+    return true;
+  }
+
+  /**
+   * Every value the client presented under the binding cookie's name.
+   *
+   * Not the first one, and not capped — see `OAuth.anyCandidateMatches` for why
+   * either would hand an attacker a permanent, unauthenticated denial of login
+   * for any victim they can plant a same-named cookie on.
+   */
+  readBindingCookies(req: RouteRequest): string[] {
+    const header = req.headers.cookie;
+    if (!header) return [];
+
+    const values: string[] = [];
+
+    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 decoding 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.
+      values.push(part.slice(separator + 1).trim());
+    }
+
+    return values;
+  }
+
+  clearBindingCookie(req: RouteRequest, providerName: string): void {
+    const { res } = req;
+    if (typeof res?.clearCookie !== 'function') return;
+
+    res.clearCookie(STATE_COOKIE_NAME, this.cookieOptions(providerName));
+  }
 }

package/src/main.ts

@@ -1,3 +1,4 @@
+import { createHash, randomBytes, randomUUID } from 'node:crypto';
 import config from 'stonyx/config';
 import log from 'stonyx/log';
 import { waitForModule } from 'stonyx';
@@ -10,11 +11,38 @@ import type OAuthFlow from './oauth-flow.js';
 
 setup(['authenticate']);
 
+/** Lifetime of a pending state, 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;
+
 interface ProviderEntry {
   flow: OAuthFlow;
   tokenManager: TokenManager;
 }
 
+/**
+ * A flow that is in progress.
+ *
+ * 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 {
+  bindingHash: string;
+  createdAt: number;
+}
+
+export interface IssuedState {
+  /** Sent to the provider as the OAuth2 `state` parameter. */
+  url: string;
+  /** Retained so a login that cannot be bound can withdraw its own state. */
+  stateToken: string;
+  /** Held by the client that started the flow, never by the provider. */
+  bindingValue: string;
+}
+
 interface ProviderConfig {
   module?: string;
   [key: string]: unknown;
@@ -24,7 +52,8 @@ export default class OAuth {
   static instance: OAuth | null;
 
   providers = new Map<string, ProviderEntry>();
-  pendingStates = new Map<string, number>();
+  pendingStates = new Map<string, PendingState>();
+  stateTtl = STATE_TTL_MS;
   sessionManager!: SessionManager;
   frontendCallbackUrl?: string;
 
@@ -66,27 +95,126 @@ export default class OAuth {
     return provider;
   }
 
-  getAuthorizationUrl(providerName: string): string {
-    const { flow } = this.getProvider(providerName);
-    const stateToken = crypto.randomUUID();
-    this.pendingStates.set(stateToken, Date.now());
-    return flow.buildAuthorizationUrl(stateToken);
+  /**
+   * SHA-256 of a binding value, hex encoded.
+   *
+   * The pending record stores the digest so that read access to the map does
+   * not hand over the value a callback must present.
+   */
+  static hash(value: string): string {
+    return createHash('sha256').update(value).digest('hex');
   }
 
-  async handleCallback(providerName: string, code: string, stateToken: string) {
-    if (!stateToken || !this.pendingStates.has(stateToken)) {
-      throw new Error('Invalid or missing state token');
+  /** 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);
     }
 
-    const stateCreatedAt = this.pendingStates.get(stateToken);
-    if (stateCreatedAt === undefined) throw new Error('State token not found in pending states');
+    return difference === 0;
+  }
+
+  /**
+   * Whether *any* presented value is the binding value for this record.
+   *
+   * Every candidate is tried, and the callback is accepted if one matches.
+   * Stopping at the first value carrying the cookie's name instead makes a
+   * planted cookie a permanent, unauthenticated denial of login: RFC 6265
+   * section 5.4 orders the `Cookie` header by path length then creation time,
+   * so an attacker with content control on a sibling subdomain sets a
+   * same-named cookie once and every subsequent callback for that victim reads
+   * theirs, fails the binding check, and burns the state on the way out. The
+   * victim cannot recover by retrying.
+   *
+   * Accepting any match gives an attacker nothing: they would have to present
+   * the victim's own binding value, which is the property being checked. And
+   * the candidate list is deliberately uncapped — a cap does not bound an
+   * attack, it *is* one, reinstating that denial above its own threshold
+   * because the planted cookies are the ones that sort first. The work is
+   * already bounded by Node's 16 KB header limit.
+   *
+   * The reduce does not short-circuit, so the work is a function of how many
+   * values were presented and not of which one matched.
+   */
+  static anyCandidateMatches(candidates: readonly string[], bindingHash: string): boolean {
+    return candidates.reduce(
+      (matched, candidate) => OAuth.digestsMatch(OAuth.hash(candidate), bindingHash) || matched,
+      false,
+    );
+  }
+
+  /**
+   * Starts a flow: an OAuth2 `state` for the provider, and a binding value for
+   * the client that asked for it.
+   *
+   * `state` on its own is replay-window limiting, not the CSRF binding it
+   * exists to provide (RFC 6749 section 10.12, RFC 9700): before this, any
+   * state issued to any visitor validated for any callback, so an attacker
+   * could harvest their own state and code, deliver them to a victim over a
+   * plain link, and log the victim into the attacker's account. The binding
+   * value is the thing the victim's browser carries and the attacker's does
+   * not (#36).
+   */
+  getAuthorizationUrl(providerName: string): IssuedState {
+    const { flow } = this.getProvider(providerName);
+    const stateToken = randomUUID();
+    const bindingValue = randomBytes(BINDING_VALUE_BYTES).toString('base64url');
+
+    this.pendingStates.set(stateToken, {
+      bindingHash: OAuth.hash(bindingValue),
+      createdAt: Date.now(),
+    });
+
+    return { url: flow.buildAuthorizationUrl(stateToken), stateToken, bindingValue };
+  }
+
+  /**
+   * Withdraws a state that was issued but could not be handed to a client.
+   *
+   * Used by the login route when the binding cookie cannot be set: a state the
+   * client cannot be bound to is exactly the defect this mechanism exists to
+   * prevent, so it must not outlive the request that failed to bind it.
+   */
+  discardState(stateToken: string): void {
+    this.pendingStates.delete(stateToken);
+  }
+
+  /**
+   * Validates and consumes a pending state, then completes the flow.
+   *
+   * `bindingValues` is every value the client presented under the binding
+   * cookie's name — see `anyCandidateMatches`.
+   */
+  async handleCallback(providerName: string, code: string, stateToken: string, bindingValues: readonly string[]) {
+    const record = stateToken ? this.pendingStates.get(stateToken) : undefined;
+    if (!record) throw new Error('Invalid or missing state token');
+
+    // Consumed on recognition, before the TTL and binding checks, so every
+    // state gets exactly one attempt whatever the outcome. Checking the
+    // binding first would leave the record in place on a mismatch and turn
+    // this endpoint into a repeatable, unauthenticated oracle against the
+    // binding value for the state's full lifetime.
     this.pendingStates.delete(stateToken);
 
-    const TEN_MINUTES = 10 * 60 * 1000;
-    if (Date.now() - stateCreatedAt > TEN_MINUTES) {
+    if (Date.now() - record.createdAt > this.stateTtl) {
       throw new Error('State token has expired');
     }
 
+    // No "absent means skip". An empty candidate list is a rejection, which is
+    // what makes an attacker-delivered link fail for a victim who never
+    // started the flow and therefore holds no binding cookie.
+    const candidates = bindingValues.filter(value => value.length > 0);
+    if (candidates.length === 0) throw new Error('Missing state binding value');
+
+    if (!OAuth.anyCandidateMatches(candidates, record.bindingHash)) {
+      throw new Error('State token is not bound to this client');
+    }
+
+    // Everything below burns a live authorization code, so the binding is
+    // settled before `exchangeCode` is ever reached.
     const { flow, tokenManager } = this.getProvider(providerName);
     const tokens = await tokenManager.getTokens(code);
     const rawUser = await flow.fetchUserInfo(tokens.accessToken);
@@ -95,6 +223,11 @@ export default class OAuth {
     return this.sessionManager.create(user, tokens);
   }
 
+  /** The provider's configured redirect URI, used to decide the cookie's `Secure`. */
+  redirectUriFor(providerName: string): string | undefined {
+    return this.providers.get(providerName)?.flow.redirectUri;
+  }
+
   getSession(sessionId: string) {
     return this.sessionManager.validate(sessionId);
   }

package/src/types/node.d.ts

@@ -1,3 +1,19 @@
 declare module 'node:crypto' {
   export function randomUUID(): string;
+
+  /**
+   * Structural stand-ins: this repo declares its own node shims rather than
+   * depending on `@types/node`, so only the surface actually used is typed.
+   */
+  interface BinaryLike {
+    toString(encoding: string): string;
+  }
+
+  interface Hash {
+    update(data: string): Hash;
+    digest(encoding: string): string;
+  }
+
+  export function randomBytes(size: number): BinaryLike;
+  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;
   }