@stonyx/oauth 0.1.1-alpha.21 → 0.1.1-alpha.23

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';
@@ -6,37 +7,53 @@ 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']);
 
+/** 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;
 }
 
-interface ProviderConfig {
-  module?: string;
-  [key: string]: unknown;
+/**
+ * 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 AuthorizationRequest {
-  /** Provider authorization URL to redirect the client to. */
+export interface IssuedState {
+  /** Sent to the provider as the OAuth2 `state` parameter. */
   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`.
-   */
+  /** 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;
+}
+
 export default class OAuth {
   static instance: OAuth | null;
 
   providers = new Map<string, ProviderEntry>();
-  stateStore = new StateStore();
+  pendingStates = new Map<string, PendingState>();
+  stateTtl = STATE_TTL_MS;
   sessionManager!: SessionManager;
   frontendCallbackUrl?: string;
 
@@ -78,33 +95,126 @@ export default class OAuth {
     return provider;
   }
 
-  getAuthorizationUrl(providerName: string): AuthorizationRequest {
+  /**
+   * 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');
+  }
+
+  /** 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;
+  }
+
+  /**
+   * 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, bindingValue } = this.stateStore.issue(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), bindingValue };
+    return { url: flow.buildAuthorizationUrl(stateToken), stateToken, bindingValue };
   }
 
   /**
-   * `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.
+   * Withdraws a state that was issued but could not be handed to a client.
    *
-   * 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.
+   * 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.
    */
-  async handleCallback(
-    providerName: string,
-    code: string,
-    stateToken: string,
-    bindingValues: readonly string[],
-  ) {
-    this.stateStore.consume(stateToken, providerName, bindingValues);
+  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);
+
+    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);
@@ -113,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,10 +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: 'hex'): string;
+    digest(encoding: string): string;
   }
 
-  export function randomUUID(): string;
-  export function randomBytes(size: number): { toString(encoding: 'base64url' | 'hex'): string };
+  export function randomBytes(size: number): BinaryLike;
   export function createHash(algorithm: string): Hash;
 }

package/dist/constants.d.ts

@@ -1,33 +0,0 @@
-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

@@ -1,42 +0,0 @@
-// 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/state-store.d.ts

@@ -1,116 +0,0 @@
-/**
- * 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

@@ -1,144 +0,0 @@
-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/src/constants.ts

@@ -1,46 +0,0 @@
-// 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.
- */