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

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';
@@ -6,12 +7,16 @@ 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']);
+/** 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();
-    stateStore = new StateStore();
+    pendingStates = new Map();
+    stateTtl = STATE_TTL_MS;
     sessionManager;
     frontendCallbackUrl;
     constructor() {
@@ -46,25 +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, bindingValue } = this.stateStore.issue(providerName);
-        return { url: flow.buildAuthorizationUrl(stateToken), bindingValue };
+        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 };
     }
     /**
-     * `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.
+     */
+    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) {
-        this.stateStore.consume(stateToken, providerName, bindingValues);
+        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);
@@ -72,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-alpha.21",
+  "version": "0.1.1-alpha.23",
   "description": "OAuth2 authentication module for the Stonyx framework",
   "repository": {
     "type": "git",
@@ -55,15 +55,15 @@
   },
   "dependencies": {
     "@stonyx/events": "0.1.1-beta.52",
-    "stonyx": "0.2.3-beta.77"
+    "stonyx": "0.2.3-beta.81"
   },
   "peerDependencies": {
     "@stonyx/rest-server": ">=0.2.1-beta.11"
   },
   "devDependencies": {
-    "@stonyx/rest-server": "0.2.1-beta.83",
+    "@stonyx/rest-server": "0.2.1-beta.98",
     "@stonyx/utils": "0.2.3-beta.26",
-    "@stonyx/logs": "1.0.1-beta.19",
+    "@stonyx/logs": "1.0.1-beta.20",
     "@types/qunit": "^2.19.13",
     "@types/sinon": "^21.0.1",
     "qunit": "^2.24.1",

package/src/auth-request.ts

@@ -1,71 +1,39 @@
 import { Request } from '@stonyx/rest-server';
 import log from 'stonyx/log';
-import { StateRejection } from './state-store.js';
-import {
-  STATE_COOKIE_NAME,
-  STATE_COOKIE_PATH,
-  STATE_COOKIE_SAME_SITE,
-  STATE_TTL_MS,
-} from './constants.js';
-
-interface AuthorizationRequest {
-  url: string;
-  bindingValue: string;
-}
 
 /**
- * Hosts treated as a development origin by exact match, and — together with
- * `127.0.0.0/8` and the IPv4-mapped IPv6 spellings of it — the only ones exempt
- * from `Secure` on the binding cookie. See `AuthRequest.isSecureContext`.
+ * The cookie carrying the client-held half of the OAuth2 `state` binding (#36).
  *
- * `0.0.0.0` and `::` are the wildcard bind addresses a developer reaches a
- * local server on; `127.0.0.1` is covered by the `127.0.0.0/8` test rather than
- * listed here, so the two are not silently redundant.
- */
-const LOOPBACK_HOSTS = new Set(['localhost', '::1', '0:0:0:0:0:0:0:1', '0.0.0.0', '::']);
-
-/** `host` values whose port component is anything but a decimal port are rejected. */
-const PORT_PATTERN = /^\d{1,5}$/;
-
-/**
- * The characters RFC 1123 permits in a registered hostname, plus `.`.
+ * The attributes below are load-bearing, not cosmetic:
  *
- * Anything else — `@`, `,`, whitespace, `/` — means the value is not a bare
- * hostname, and the caller fails secure rather than guessing. This is what
- * rejects `localhost:80@evil.com` and a comma-joined multi-value `Host`.
- */
-const HOSTNAME_PATTERN = /^[A-Za-z0-9._-]+$/;
-
-/** A dotted-quad whose first octet is 127, i.e. real `127.0.0.0/8` membership. */
-function isLoopbackIpv4(hostname: string): boolean {
-  const octets = hostname.split('.');
-  if (octets.length !== 4) return false;
-  if (!octets.every(octet => /^\d{1,3}$/.test(octet) && Number(octet) <= 255)) return false;
-
-  return Number(octets[0]) === 127;
-}
-
-/**
- * IPv4-mapped IPv6 loopback, in both spellings a dual-stack listener produces:
- * `::ffff:127.0.0.1` and `::ffff:7f00:1`.
+ *   - `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.
  */
-function isLoopbackIpv6(hostname: string): boolean {
-  const mapped = /^::ffff:(.+)$/.exec(hostname);
-  if (!mapped) return false;
+const STATE_COOKIE_NAME = 'oauth_state';
+const STATE_COOKIE_PATH = '/';
+const STATE_COOKIE_SAME_SITE = 'lax';
 
-  const rest = mapped[1];
-  if (isLoopbackIpv4(rest)) return true;
-
-  const hextets = /^([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(rest);
-  if (!hextets) return false;
-
-  return parseInt(hextets[1], 16) >>> 8 === 127;
+interface AuthorizationRequest {
+  url: string;
+  stateToken: string;
+  bindingValue: string;
 }
 
 interface OAuthInstance {
   frontendCallbackUrl?: string;
+  stateTtl: number;
   getSession(sessionId: string): unknown;
   getAuthorizationUrl(providerName: string): AuthorizationRequest;
+  discardState(stateToken: string): void;
+  redirectUriFor(providerName: string): string | undefined;
   handleCallback(
     providerName: string,
     code: string,
@@ -84,13 +52,17 @@ interface CookieOptions {
 }
 
 /**
- * The response object Express hangs off the request.
+ * The response object express hangs off the request.
  *
- * `@stonyx/rest-server` hands handlers `(req, state)` only, and `state` has no
- * affordance for response headers, so setting a cookie means reaching for
- * `req.res`. This is a deliberate, temporary escape hatch — tracked by
- * `abofs/stonyx-rest-server#45`, which adds a first-class header affordance to
- * migrate onto.
+ * `@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;
@@ -99,16 +71,8 @@ interface ResponseLike {
 
 interface RouteRequest {
   headers: Record<string, string | undefined>;
-  /**
-   * Node's flat `[name, value, name, value, ...]` header list, when the runtime
-   * supplies it. Read only to detect a *duplicate* `Host`: Node collapses
-   * repeats into the first value, so `req.headers.host` alone cannot tell an
-   * unambiguous origin from a smuggled one.
-   */
-  rawHeaders?: string[];
   params: Record<string, string>;
   query: Record<string, string>;
-  secure?: boolean;
   res?: ResponseLike;
 }
 
@@ -146,9 +110,13 @@ export default class AuthRequest extends Request {
           return 404;
         }
 
-        // Fail closed: a state we cannot bind to this client is exactly the
-        // defect this mechanism exists to prevent, so never issue one.
-        if (!this.setBindingCookie(req, authorization.bindingValue)) return 500;
+        // 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;
       },
@@ -157,8 +125,6 @@ export default class AuthRequest extends Request {
         const { provider: providerName } = req.params;
         const { code, state: stateToken, error } = req.query;
 
-        const bindingValues = this.readBindingCookies(req);
-
         if (error) {
           if (this.oauth.frontendCallbackUrl) {
             state.redirect = `${this.oauth.frontendCallbackUrl}?error=${encodeURIComponent(error)}`;
@@ -170,11 +136,23 @@ export default class AuthRequest extends Request {
         if (!code) return 400;
 
         try {
-          const session = await this.oauth.handleCallback(providerName, code, stateToken, bindingValues);
-
-          // The binding value is single-use and the state has now been
-          // consumed, so this is the end of that cookie's life.
-          this.clearBindingCookie(req);
+          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({
@@ -186,53 +164,7 @@ export default class AuthRequest extends Request {
           }
 
           return session;
-        } catch (rejection) {
-          // Clear only when this request actually spent the cookie.
-          //
-          // Moving the clear below the `error` and `!code` returns was not
-          // enough: it still ran unconditionally for any request carrying a
-          // `code`, and `code` is attacker-supplied and unvalidated. So
-          // `?code=1` — one query parameter, no knowledge of the victim's state
-          // — deleted the binding cookie of a client still at the provider's
-          // consent screen, leaving their pending state untouched so nothing
-          // was detectable server-side, and their real callback then failed.
-          //
-          // `StateRejection.consumed` is the only thing that distinguishes
-          // "nothing of this client's was touched" from "one attempt was
-          // spent". Anything that is not a `StateRejection` was thrown below
-          // the state check, which means the record was already burned.
-          if (!(rejection instanceof StateRejection) || rejection.consumed) {
-            this.clearBindingCookie(req);
-          }
-
-          // `StateStore.consume` distinguishes five rejection reasons that
-          // otherwise collapse into one opaque outcome with no server-side
-          // signal at all. The client-facing `auth_failed` stays opaque; the
-          // server has no reason to be.
-          //
-          // Only a `StateRejection`'s message is logged, and those are the
-          // fixed strings in `STATE_REJECTION`. The `try` above spans far more
-          // than `consume` — `getProvider`, `TokenManager.getTokens` ->
-          // `flow.exchangeCode`, `flow.fetchUserInfo`, `flow.normalizeUser`,
-          // `emit('authenticate')`, `sessionManager.create` — and three of
-          // those are consumer-overridable through the documented
-          // `providers.<name>.module` extension point. A provider that puts
-          // request context in its error, which is ordinary practice, would
-          // otherwise land its `clientSecret` and the caller-supplied `code` in
-          // the log verbatim; `@stonyx/logs` appends content raw when
-          // `logToFile` is enabled, so an echoed `code` is also a CRLF
-          // log-forging primitive for an unauthenticated caller. Before this
-          // module logged anything, all of that was swallowed.
-          //
-          // Anything below the state check therefore gets a fixed
-          // discriminator, and the detail is left to whatever the provider
-          // itself logs.
-          if (rejection instanceof StateRejection) {
-            log.error(`OAuth: callback rejected — ${rejection.message}`);
-          } else {
-            log.error('OAuth: callback failed after state validation');
-          }
-
+        } catch {
           if (this.oauth.frontendCallbackUrl) {
             state.redirect = `${this.oauth.frontendCallbackUrl}?error=auth_failed`;
             return;
@@ -248,128 +180,44 @@ export default class AuthRequest extends Request {
     }
   };
 
-  cookieOptions(req: RouteRequest): Omit<CookieOptions, 'maxAge'> {
-    return {
-      httpOnly: true,
-      // Load-bearing: the callback is a cross-site top-level GET navigation
-      // from the provider. `Strict` withholds the cookie on exactly that
-      // request and breaks login outright.
-      sameSite: STATE_COOKIE_SAME_SITE,
-      path: STATE_COOKIE_PATH,
-      secure: this.isSecureContext(req),
-    };
-  }
-
   /**
    * Whether the binding cookie is issued with `Secure`.
    *
-   * Not `req.secure`. Express derives that from the socket unless `trust proxy`
-   * is enabled, and `@stonyx/rest-server` leaves it off by default
-   * (`trustProxy: REST_TRUST_PROXY === 'true'`). In the standard production
-   * topology — TLS terminated at a proxy, plaintext to the origin — `req.secure`
-   * is therefore `false` on every request to an HTTPS site, and the binding
-   * cookie would ship without `Secure` while the deployment looks correct.
+   * 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.
    *
-   * So `Secure` is set unconditionally except on a loopback host. Guessing
-   * wrong there breaks a non-loopback plaintext development setup, which fails
-   * at the first login and is loud. The alternative fails silently, in
-   * production, on the one attribute protecting the value this whole mechanism
-   * is built around.
-   *
-   * The exemption is decided by *parsing* the `Host` header and testing the
-   * result for membership, never by matching a prefix or a suffix on the raw
-   * value — `Host` is attacker-controllable on any non-browser client, and a
-   * security predicate written as a substring match drifts. Every shape that
-   * cannot be parsed as a bare `host[:port]`, and every request with more than
-   * one `Host`, fails secure.
-   */
-  isSecureContext(req: RouteRequest): boolean {
-    if (req.secure === true) return true;
-    if (AuthRequest.hasAmbiguousHost(req)) return true;
-
-    const host = req.headers.host;
-    if (!host) return true;
-
-    const hostname = AuthRequest.parseHostname(host);
-    if (hostname === undefined) return true;
-
-    return !AuthRequest.isLoopbackHost(hostname);
-  }
-
-  /**
-   * True when the request carried more than one `Host` header.
-   *
-   * Node keeps the first and discards the rest, so a component that *prepends*
-   * a `Host:` line — request smuggling, or a proxy that appends rather than
-   * replaces — can make `req.headers.host` read `localhost` on a request whose
-   * real origin is public. RFC 9112 section 3.2 makes such a request invalid;
-   * this treats it as unattributable and fails secure rather than trusting it.
-   */
-  static hasAmbiguousHost(req: RouteRequest): boolean {
-    const raw = req.rawHeaders;
-    if (!Array.isArray(raw)) return false;
-
-    let seen = 0;
-    for (let index = 0; index < raw.length; index += 2) {
-      if (typeof raw[index] === 'string' && raw[index].toLowerCase() === 'host') seen++;
-    }
-
-    return seen > 1;
-  }
-
-  /**
-   * The hostname component of a `Host` header, lowercased, or `undefined` when
-   * the value is not a well-formed `host[:port]`.
+   * 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.
    *
-   * `host.split(':')[0]` is not enough: it truncates at the *first* colon, so
-   * `localhost:80@evil.com` reduces to `localhost`. The port is therefore
-   * required to be decimal, and the hostname to contain only characters a
-   * registered name may contain.
+   * An unparseable or absent redirect URI fails secure.
    */
-  static parseHostname(host: string): string | undefined {
-    if (host.startsWith('[')) {
-      const close = host.indexOf(']');
-      if (close === -1) return undefined;
-
-      const port = host.slice(close + 1);
-      if (port !== '' && !(port.startsWith(':') && PORT_PATTERN.test(port.slice(1)))) return undefined;
-
-      const literal = host.slice(1, close);
-      if (!/^[0-9A-Fa-f:.]+$/.test(literal)) return undefined;
-
-      return literal.toLowerCase();
+  isSecureContext(providerName: string): boolean {
+    const redirectUri = this.oauth.redirectUriFor(providerName);
+    if (!redirectUri) return true;
+
+    try {
+      return new URL(redirectUri).protocol !== 'http:';
+    } catch {
+      return true;
     }
-
-    const colon = host.indexOf(':');
-    if (colon === -1) return HOSTNAME_PATTERN.test(host) ? host.toLowerCase() : undefined;
-
-    if (!PORT_PATTERN.test(host.slice(colon + 1))) return undefined;
-
-    const name = host.slice(0, colon);
-
-    return HOSTNAME_PATTERN.test(name) ? name.toLowerCase() : undefined;
   }
 
-  /**
-   * Whether a parsed hostname is a loopback development origin.
-   *
-   * Membership tests, never prefix or suffix tests. `startsWith('127.')`
-   * matched `127.evil.com`, a perfectly registerable name (RFC 1123 permits a
-   * leading digit in a label), and `endsWith('.localhost')` exempted an entire
-   * suffix — so a `.localhost` split-horizon vhost shipped the binding value in
-   * cleartext. The `.localhost` exemption is withdrawn rather than tightened:
-   * the README documented `127.0.0.0/8`, `localhost`, `::1` and `0.0.0.0` and
-   * never documented it, and a developer on `app.localhost` reaches the same
-   * server on `localhost` or `127.0.0.1`.
-   */
-  static isLoopbackHost(hostname: string): boolean {
-    if (LOOPBACK_HOSTS.has(hostname)) return true;
-    if (isLoopbackIpv4(hostname)) return true;
-
-    return isLoopbackIpv6(hostname);
+  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, bindingValue: string): boolean {
+  setBindingCookie(req: RouteRequest, providerName: string, bindingValue: string): boolean {
     const { res } = req;
 
     if (typeof res?.cookie !== 'function') {
@@ -378,8 +226,8 @@ export default class AuthRequest extends Request {
     }
 
     res.cookie(STATE_COOKIE_NAME, bindingValue, {
-      ...this.cookieOptions(req),
-      maxAge: STATE_TTL_MS,
+      ...this.cookieOptions(providerName),
+      maxAge: this.oauth.stateTtl,
     });
 
     return true;
@@ -388,20 +236,9 @@ export default class AuthRequest extends Request {
   /**
    * Every value the client presented under the binding cookie's name.
    *
-   * Not the first one. A browser sends every applicable cookie in a single
-   * header, and a sibling subdomain can set a same-named cookie on the parent
-   * domain that RFC 6265 section 5.4 orders *ahead* of the real one — so
-   * returning on the first name match handed an attacker a permanent,
-   * unauthenticated denial of login for any victim they could plant a cookie
-   * on. `Secure`, `HttpOnly` and `SameSite` do not constrain that: the attacker
-   * is writing, not reading.
-   *
-   * Every value is returned, with no cap. A cap here does not bound an attack,
-   * it *is* one: truncating the list reinstates exactly the 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 — at most 779
-   * hashable candidates, 0.32 ms to parse and hash all of them. See
-   * `constants.ts` for the measurement.
+   * 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;
@@ -415,20 +252,20 @@ export default class AuthRequest extends Request {
       if (part.slice(0, separator).trim() !== STATE_COOKIE_NAME) continue;
 
       // Not decoded. The binding value is base64url, whose alphabet
-      // `encodeURIComponent` never escapes, so a decode buys nothing — and
+      // `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 with a stack trace.
+      // callback into a 500.
       values.push(part.slice(separator + 1).trim());
     }
 
     return values;
   }
 
-  clearBindingCookie(req: RouteRequest): void {
+  clearBindingCookie(req: RouteRequest, providerName: string): void {
     const { res } = req;
     if (typeof res?.clearCookie !== 'function') return;
 
-    res.clearCookie(STATE_COOKIE_NAME, this.cookieOptions(req));
+    res.clearCookie(STATE_COOKIE_NAME, this.cookieOptions(providerName));
   }
 }