@stonyx/oauth 0.1.1-beta.126 → 0.1.1-beta.127

package/dist/constants.d.ts

@@ -0,0 +1,33 @@
+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;
+/**
+ * There is deliberately no cap on how many values carrying `STATE_COOKIE_NAME`
+ * a callback will try.
+ *
+ * A client can hold more than one cookie of the same name — a sibling subdomain
+ * can set one on the parent domain — and the browser sends every applicable
+ * cookie in one header, so all of them must be tried or a planted cookie denies
+ * login by sorting ahead of the real one (RFC 6265 section 5.4).
+ *
+ * A cap of 8 was tried and withdrawn: it *reinstated* that denial above its own
+ * threshold. Measured on the pre-change tree, 7 shadow cookies still minted a
+ * session and 8 failed permanently — the same outcome as the original defect,
+ * with the attacker's cost raised from one planted cookie to eight. That is
+ * reachable: RFC 6265 section 5.4 orders by path length then creation time, so
+ * a 4-label API host with a foothold beneath it gets 3 settable parent domains
+ * x 3 usable paths = 9 candidates ahead of the real one.
+ *
+ * What the cap was defending is already bounded, structurally and for free.
+ * Node caps the whole header block at `http.maxHeaderSize`, 16 KB by default,
+ * and the shortest segment that can reach the hash is `stonyx_oauth_state=x` at
+ * 20 bytes, so a request cannot present more than 779 hashable candidates.
+ * Parsing and SHA-256-hashing all 779 costs 0.32 ms median / 0.81 ms worst of 9
+ * runs (Node 24.13.0, Apple silicon). Paying a permanent, unauthenticated
+ * denial of login to avoid a third of a millisecond is the wrong trade, so the
+ * bound is left where it already was: the header size limit.
+ */

package/dist/constants.js

@@ -0,0 +1,42 @@
+// 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;
+/**
+ * There is deliberately no cap on how many values carrying `STATE_COOKIE_NAME`
+ * a callback will try.
+ *
+ * A client can hold more than one cookie of the same name — a sibling subdomain
+ * can set one on the parent domain — and the browser sends every applicable
+ * cookie in one header, so all of them must be tried or a planted cookie denies
+ * login by sorting ahead of the real one (RFC 6265 section 5.4).
+ *
+ * A cap of 8 was tried and withdrawn: it *reinstated* that denial above its own
+ * threshold. Measured on the pre-change tree, 7 shadow cookies still minted a
+ * session and 8 failed permanently — the same outcome as the original defect,
+ * with the attacker's cost raised from one planted cookie to eight. That is
+ * reachable: RFC 6265 section 5.4 orders by path length then creation time, so
+ * a 4-label API host with a foothold beneath it gets 3 settable parent domains
+ * x 3 usable paths = 9 candidates ahead of the real one.
+ *
+ * What the cap was defending is already bounded, structurally and for free.
+ * Node caps the whole header block at `http.maxHeaderSize`, 16 KB by default,
+ * and the shortest segment that can reach the hash is `stonyx_oauth_state=x` at
+ * 20 bytes, so a request cannot present more than 779 hashable candidates.
+ * Parsing and SHA-256-hashing all 779 costs 0.32 ms median / 0.81 ms worst of 9
+ * runs (Node 24.13.0, Apple silicon). Paying a permanent, unauthenticated
+ * denial of login to avoid a third of a millisecond is the wrong trade, so the
+ * bound is left where it already was: the header size limit.
+ */

package/dist/main.d.ts

@@ -1,21 +1,44 @@
 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;
+    /**
+     * `bindingValues` 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 an array, not a single value, because a client can hold more than one
+     * cookie of the binding cookie's name and every one of them has to be tried —
+     * see `StateStore.anyCandidateMatches`. A caller driving the flow itself
+     * passes `[bindingValue]`; the route handler passes through every value the
+     * client presented, which may be none.
+     */
+    handleCallback(providerName: string, code: string, stateToken: string, bindingValues: readonly string[]): Promise<import("./session-manager.js").SessionResult>;
     getSession(sessionId: string): unknown;
     logout(sessionId: string): void;
 }

package/dist/main.js

@@ -6,11 +6,12 @@ import RestServer from '@stonyx/rest-server';
 import TokenManager from './token-manager.js';
 import SessionManager from './session-manager.js';
 import AuthRequest from './auth-request.js';
+import StateStore from './state-store.js';
 setup(['authenticate']);
 export default class OAuth {
     static instance;
     providers = new Map();
-    pendingStates = new Map();
+    stateStore = new StateStore();
     sessionManager;
     frontendCallbackUrl;
     constructor() {
@@ -47,22 +48,23 @@ 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');
-        }
+    /**
+     * `bindingValues` 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 an array, not a single value, because a client can hold more than one
+     * cookie of the binding cookie's name and every one of them has to be tried —
+     * see `StateStore.anyCandidateMatches`. A caller driving the flow itself
+     * passes `[bindingValue]`; the route handler passes through every value the
+     * client presented, which may be none.
+     */
+    async handleCallback(providerName, code, stateToken, bindingValues) {
+        this.stateStore.consume(stateToken, providerName, bindingValues);
         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,116 @@
+/**
+ * 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;
+}
+/**
+ * The five reasons a callback is rejected, as fixed strings.
+ *
+ * Named rather than inlined so that collapsing two of them into one is a
+ * visible edit: distinguishing them in the server log is the whole point of
+ * logging a reason, and an operator telling an expired state from a
+ * cross-provider replay depends on them staying distinct.
+ */
+export declare const STATE_REJECTION: {
+    readonly unknownState: "Invalid or missing state token";
+    readonly expired: "State token has expired";
+    readonly wrongProvider: "State token was not issued for this provider";
+    readonly missingBinding: "Missing state binding value";
+    readonly unboundClient: "State token is not bound to this client";
+};
+/**
+ * A callback rejected by `StateStore.consume`.
+ *
+ * Carries two things the route layer cannot otherwise recover: that the
+ * rejection came from state validation rather than from anything downstream of
+ * it, and whether a pending record was actually consumed.
+ */
+export declare class StateRejection extends Error {
+    /** True when this attempt recognised a pending record and burned it. */
+    consumed: boolean;
+    constructor(reason: string, consumed: boolean);
+}
+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. `consumed` on the rejection says whether this
+     * call actually burned a record, so a caller can distinguish "nothing of the
+     * victim's was touched" from "one attempt was spent".
+     *
+     * `bindingValues` is every value the client presented under the binding
+     * cookie's name, not just the first — see `anyCandidateMatches`.
+     */
+    consume(stateToken: string | undefined, provider: string, bindingValues: readonly string[]): void;
+    /**
+     * Whether *any* presented value is the binding value for this record.
+     *
+     * Every candidate is tried, and the callback is accepted if one matches.
+     * Returning on the first value carrying the cookie name instead made 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. The
+     * record is consumed on recognition, so a state still gets exactly one
+     * attempt however many candidates were presented, and the candidate count is
+     * bounded by Node's header size limit rather than by a cap here — a cap
+     * truncates the list from the wrong end and reinstates the denial this method
+     * exists to close. See `constants.ts`.
+     *
+     * The loop does not short-circuit, so the work is a function of how many
+     * values were presented and not of which one matched.
+     */
+    anyCandidateMatches(candidates: readonly string[], record: PendingState): boolean;
+}

package/dist/state-store.js

@@ -0,0 +1,144 @@
+import { createHash, randomBytes, randomUUID } from 'node:crypto';
+import { BINDING_VALUE_BYTES, STATE_TTL_MS } from './constants.js';
+/**
+ * The five reasons a callback is rejected, as fixed strings.
+ *
+ * Named rather than inlined so that collapsing two of them into one is a
+ * visible edit: distinguishing them in the server log is the whole point of
+ * logging a reason, and an operator telling an expired state from a
+ * cross-provider replay depends on them staying distinct.
+ */
+export const STATE_REJECTION = {
+    unknownState: 'Invalid or missing state token',
+    expired: 'State token has expired',
+    wrongProvider: 'State token was not issued for this provider',
+    missingBinding: 'Missing state binding value',
+    unboundClient: 'State token is not bound to this client',
+};
+/**
+ * A callback rejected by `StateStore.consume`.
+ *
+ * Carries two things the route layer cannot otherwise recover: that the
+ * rejection came from state validation rather than from anything downstream of
+ * it, and whether a pending record was actually consumed.
+ */
+export class StateRejection extends Error {
+    /** True when this attempt recognised a pending record and burned it. */
+    consumed;
+    constructor(reason, consumed) {
+        super(reason);
+        this.name = 'StateRejection';
+        this.consumed = consumed;
+    }
+}
+/**
+ * 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. `consumed` on the rejection says whether this
+     * call actually burned a record, so a caller can distinguish "nothing of the
+     * victim's was touched" from "one attempt was spent".
+     *
+     * `bindingValues` is every value the client presented under the binding
+     * cookie's name, not just the first — see `anyCandidateMatches`.
+     */
+    consume(stateToken, provider, bindingValues) {
+        if (!stateToken)
+            throw new StateRejection(STATE_REJECTION.unknownState, false);
+        const record = this.pending.get(stateToken);
+        if (!record)
+            throw new StateRejection(STATE_REJECTION.unknownState, false);
+        this.pending.delete(stateToken);
+        if (Date.now() - record.createdAt > this.ttl)
+            throw new StateRejection(STATE_REJECTION.expired, true);
+        if (record.provider !== provider)
+            throw new StateRejection(STATE_REJECTION.wrongProvider, true);
+        const candidates = bindingValues.filter(value => value.length > 0);
+        if (candidates.length === 0)
+            throw new StateRejection(STATE_REJECTION.missingBinding, true);
+        if (!this.anyCandidateMatches(candidates, record)) {
+            throw new StateRejection(STATE_REJECTION.unboundClient, true);
+        }
+    }
+    /**
+     * Whether *any* presented value is the binding value for this record.
+     *
+     * Every candidate is tried, and the callback is accepted if one matches.
+     * Returning on the first value carrying the cookie name instead made 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. The
+     * record is consumed on recognition, so a state still gets exactly one
+     * attempt however many candidates were presented, and the candidate count is
+     * bounded by Node's header size limit rather than by a cap here — a cap
+     * truncates the list from the wrong end and reinstates the denial this method
+     * exists to close. See `constants.ts`.
+     *
+     * The loop does not short-circuit, so the work is a function of how many
+     * values were presented and not of which one matched.
+     */
+    anyCandidateMatches(candidates, record) {
+        return candidates.reduce((matched, candidate) => StateStore.digestsMatch(StateStore.hash(candidate), record.bindingHash) || matched, false);
+    }
+}

package/package.json

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