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

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.
- */

package/src/state-store.ts

@@ -1,179 +0,0 @@
-import { createHash, randomBytes, randomUUID } from 'node:crypto';
-import { BINDING_VALUE_BYTES, STATE_TTL_MS } from './constants.js';
-
-/**
- * Server-side record for an OAuth flow that is in progress.
- *
- * Deliberately holds a *digest* of the binding value rather than the value
- * itself: a callback is only accepted when the caller presents the plaintext
- * that hashes to `bindingHash`, so the record on its own unlocks nothing.
- */
-export interface PendingState {
-  provider: string;
-  bindingHash: string;
-  createdAt: number;
-}
-
-/**
- * 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',
-} as const;
-
-/**
- * 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: boolean;
-
-  constructor(reason: string, consumed: boolean) {
-    super(reason);
-    this.name = 'StateRejection';
-    this.consumed = consumed;
-  }
-}
-
-export interface IssuedState {
-  /** Sent to the provider as the OAuth2 `state` parameter. */
-  stateToken: string;
-  /** Held by the client that started the flow (a cookie), never by the provider. */
-  bindingValue: string;
-}
-
-/**
- * Issues and validates OAuth2 `state` tokens bound to the client that started
- * the flow (#36).
- *
- * Presence-plus-age on a process-global map is replay-window limiting, not the
- * CSRF binding `state` exists to provide (RFC 6749 section 10.12): any state
- * issued to any visitor validated for any callback, so an attacker could
- * harvest their own state and code and deliver them to a victim, logging the
- * victim in as the attacker. A state is now only accepted when the caller also
- * presents the matching client-held binding value, and only at the provider it
- * was issued for.
- */
-export default class StateStore {
-  pending = new Map<string, PendingState>();
-  ttl: number;
-
-  constructor(ttl: number = STATE_TTL_MS) {
-    this.ttl = ttl;
-  }
-
-  static hash(value: string): string {
-    return createHash('sha256').update(value).digest('hex');
-  }
-
-  /** Length-independent, content-constant-time comparison of two digests. */
-  static digestsMatch(a: string, b: string): boolean {
-    if (a.length !== b.length) return false;
-
-    let difference = 0;
-    for (let index = 0; index < a.length; index++) {
-      difference |= a.charCodeAt(index) ^ b.charCodeAt(index);
-    }
-
-    return difference === 0;
-  }
-
-  issue(provider: string): IssuedState {
-    const stateToken = randomUUID();
-    const bindingValue = randomBytes(BINDING_VALUE_BYTES).toString('base64url');
-
-    this.pending.set(stateToken, {
-      provider,
-      bindingHash: StateStore.hash(bindingValue),
-      createdAt: Date.now(),
-    });
-
-    return { stateToken, bindingValue };
-  }
-
-  /**
-   * Validates and consumes a pending state. Throws on every rejection path.
-   *
-   * The record is removed as soon as the state is recognised — before the TTL,
-   * provider and binding checks — so every state gets exactly one attempt
-   * whatever the outcome.
-   *
-   * That uniformity is the justification, not brute-force resistance:
-   * guessing `BINDING_VALUE_BYTES` of CSPRNG output is infeasible whether or
-   * not the record survives. What retaining it would buy an attacker is a
-   * repeatable, unauthenticated oracle on this endpoint for the state's full
-   * lifetime — and the safety of that would then rest entirely on an entropy
-   * constant a future change can lower. One attempt per state is a structural
-   * property; entropy arithmetic is not.
-   *
-   * The trade is real: an attacker who already knows a victim's state can burn
-   * it, and the victim must restart at `/auth/login/:provider`. That vector is
-   * accepted deliberately — it requires the victim's `randomUUID` state, and
-   * it is self-healing on retry. `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 {
-    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: readonly string[], record: PendingState): boolean {
-    return candidates.reduce(
-      (matched, candidate) => StateStore.digestsMatch(StateStore.hash(candidate), record.bindingHash) || matched,
-      false,
-    );
-  }
-}