@stonyx/oauth 0.1.1-alpha.17 → 0.1.1-alpha.19

package/README.md

@@ -86,20 +86,74 @@ issue time, and sends the plaintext to the client as a cookie:
 | `HttpOnly` | set | script must not be able to read or forge the binding value |
 | `SameSite` | `Lax` | **required.** The callback is a cross-site, top-level `GET` navigation from the provider. `SameSite=Strict` withholds the cookie on exactly that request and breaks login outright; `SameSite=None` requires `Secure` and widens exposure for no benefit |
 | `Path` | `/auth` | the cookie is only ever read by the callback route |
-| `Secure` | set on every host except loopback (`localhost`, `127.0.0.0/8`, `::1`, `0.0.0.0`) | deriving it from `req.secure` would omit it in the standard production topology: behind a TLS-terminating proxy Express reports the request as plaintext unless `trust proxy` is enabled, and `@stonyx/rest-server` leaves that off by default. A non-loopback plaintext deployment therefore cannot store this cookie — that failure is loud and deliberate, in preference to a silently insecure production cookie |
+| `Secure` | set on every host except loopback | deriving it from `req.secure` would omit it in the standard production topology: behind a TLS-terminating proxy Express reports the request as plaintext unless `trust proxy` is enabled, and `@stonyx/rest-server` leaves that off by default. A non-loopback plaintext deployment therefore cannot store this cookie — that failure is loud and deliberate, in preference to a silently insecure production cookie. The exemption rule is exact; see below |
 | `Max-Age` | 600 (10 minutes) | matches the pending state's lifetime |
 
+#### Which hosts are exempt from `Secure`
+
+The exemption is decided by parsing the `Host` header and testing the result for
+membership. It is never a prefix or suffix match on the raw header value,
+because `Host` is attacker-controllable from any non-browser client.
+
+Exempt, and nothing else:
+
+- `localhost` (case-insensitive)
+- any address in `127.0.0.0/8` — a dotted quad of **four** decimal octets whose
+  first is `127`, so `127.0.0.2` is exempt and `127.evil.com` is not. The
+  resolver shorthands `127.1` and `127.0.0` are *not* exempt: accepting a
+  variable number of octets is how a membership test decays back into a prefix
+  match. Use the full form
+- `::1` (and its expanded form), and the IPv4-mapped loopback spellings
+  `::ffff:127.0.0.1` and `::ffff:7f00:1`
+- the wildcard bind addresses `0.0.0.0` and `::`
+
+Everything else gets `Secure`, including:
+
+- **`*.localhost`.** A `.localhost` suffix was exempt in an earlier draft of
+  this module and is not any more: a split-horizon vhost under that zone would
+  have shipped the binding value in cleartext. Develop against `localhost` or
+  `127.0.0.1`, which reach the same server.
+- any `Host` that is not a well-formed `host[:port]` — a non-numeric port, a
+  userinfo segment (`localhost:80@evil.com`), a comma-joined multi-value, or a
+  character a registered name may not contain
+- a request carrying **more than one `Host` header**. Node collapses repeats
+  into the first value, so an upstream component that prepends rather than
+  replaces a `Host:` line could otherwise downgrade the cookie on a response to
+  someone else. RFC 9112 section 3.2 makes such a request invalid; this module
+  treats it as unattributable.
+- a request carrying **no `Host` header** at all
+
+`X-Forwarded-Host` is deliberately **not** consulted.
+
 `GET /auth/callback/:provider` accepts the callback only when all of the
 following hold, and mints no session otherwise:
 
 - the `state` is one this server issued and has not already been used
 - it was issued for **this** provider
 - it was issued less than 10 minutes ago
-- the request carries the binding cookie whose value hashes to the stored digest
+- the request carries a binding cookie whose value hashes to the stored digest
+
+A client can hold more than one cookie of that name — a sibling subdomain can
+set one on the parent domain, and the browser sends every applicable cookie in
+a single header. **Every** value carrying the name is tried, up to eight, and
+the callback is accepted if any of them matches. Reading only the first would
+let anyone who can plant a cookie on the victim's domain deny them login
+permanently: RFC 6265 section 5.4 sorts a planted cookie ahead of the real one
+on equal paths, and the state is burned on every recognised callback, so
+retrying does not help. Trying all of them concedes nothing, because the
+attacker would still have to present the victim's own binding value.
 
 The state and the cookie are both single-use: the pending record is consumed on
-any callback that presents a recognised `state` — successful or not — and the
-callback response clears the cookie.
+any callback that presents a recognised `state` — successful or not — and that
+same response clears the cookie, scoped to `Path=/auth` so the deletion actually
+reaches the cookie that was set.
+
+A callback that consumes **nothing** — an unrecognised or absent `state`, a
+provider `error`, a missing `code` — leaves the cookie alone. That is not
+tidiness: `/auth/callback/:provider?code=1` is a request any attacker can induce
+as a top-level navigation while a victim is still at the provider's consent
+screen, and clearing on it would delete the victim's binding cookie without
+touching anything the server could later notice.
 
 Two distinct failure modes surface on two different routes. They are unrelated,
 and the route is the fastest way to tell them apart:
@@ -121,7 +175,17 @@ and the route is the fastest way to tell them apart:
 Every callback rejection is logged server-side with its reason
 (`OAuth: callback rejected — ...`), which distinguishes an unknown state, a
 wrong provider, an expired state, a missing binding value and a wrong binding
-value. The client-facing `auth_failed` stays deliberately opaque.
+value. Those five strings are this module's own; nothing caller-controlled
+appears in them. The client-facing `auth_failed` stays deliberately opaque.
+
+A failure thrown **below** the state check — by `getProvider`, by a provider's
+`exchangeCode`, `fetchUserInfo` or `normalizeUser`, by an `authenticate`
+subscriber, or by session creation — logs the fixed line
+`OAuth: callback failed after state validation` and **nothing from the error
+itself**. Custom providers are consumer code, and a provider error that carries
+request context would otherwise put a `clientSecret` or the caller-supplied
+`code` into your logs verbatim. If you need that detail, log it inside your
+provider, where you control what goes in it.
 
 A failed callback **cannot be retried**: the pending record is consumed on any
 callback presenting a recognised `state`, so refreshing the error page or going
@@ -139,14 +203,18 @@ carry the binding value between the two calls:
 ```javascript
 const { url, bindingValue } = oauth.getAuthorizationUrl('discord');
 // hand bindingValue to the client, then on the callback:
-const session = await oauth.handleCallback('discord', code, state, bindingValue);
+const session = await oauth.handleCallback('discord', code, state, [bindingValue]);
 ```
 
+The fourth argument is an **array** — every value the client presented under the
+binding cookie's name. A driver that holds exactly one value passes
+`[bindingValue]`; one that holds none passes `[]`.
+
 > **Changed in the release that fixes [#36](https://github.com/abofs/stonyx-oauth/issues/36):**
 > `getAuthorizationUrl(provider)` returned a URL string and now returns
 > `{ url, bindingValue }`; `handleCallback(provider, code, state)` takes a
-> fourth argument, the client's binding value. Applications using the
-> self-registering `/auth` routes need no changes.
+> required fourth argument, the client's binding values, as an array.
+> Applications using the self-registering `/auth` routes need no changes.
 
 ## Officially Supported Providers
 

package/dist/auth-request.d.ts

@@ -7,7 +7,7 @@ interface OAuthInstance {
     frontendCallbackUrl?: string;
     getSession(sessionId: string): unknown;
     getAuthorizationUrl(providerName: string): AuthorizationRequest;
-    handleCallback(providerName: string, code: string, stateToken: string, bindingValue: string | undefined): Promise<{
+    handleCallback(providerName: string, code: string, stateToken: string, bindingValues: readonly string[]): Promise<{
         sessionId: string;
         expiresAt: number;
     }>;
@@ -35,6 +35,13 @@ 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;
@@ -73,10 +80,64 @@ export default class AuthRequest extends Request {
      * 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;
+    /**
+     * 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;
+    /**
+     * The hostname component of a `Host` header, lowercased, or `undefined` when
+     * the value is not a well-formed `host[:port]`.
+     *
+     * `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.
+     */
+    static parseHostname(host: string): string | 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;
     setBindingCookie(req: RouteRequest, bindingValue: string): boolean;
-    readBindingCookie(req: RouteRequest): string | undefined;
+    /**
+     * 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.
+     *
+     * Bounded at `MAX_BINDING_COOKIE_CANDIDATES`, so the work an unauthenticated
+     * caller can ask for is capped whatever the header contains.
+     */
+    readBindingCookies(req: RouteRequest): string[];
     clearBindingCookie(req: RouteRequest): void;
 }
 export {};

package/dist/auth-request.js

@@ -1,11 +1,52 @@
 import { Request } from '@stonyx/rest-server';
 import log from 'stonyx/log';
-import { STATE_COOKIE_NAME, STATE_COOKIE_PATH, STATE_COOKIE_SAME_SITE, STATE_TTL_MS, } from './constants.js';
+import { StateRejection } from './state-store.js';
+import { MAX_BINDING_COOKIE_CANDIDATES, STATE_COOKIE_NAME, STATE_COOKIE_PATH, STATE_COOKIE_SAME_SITE, STATE_TTL_MS, } from './constants.js';
 /**
- * Hosts treated as a development origin, and the only ones exempt from
- * `Secure` on the binding cookie. See `AuthRequest.isSecureContext`.
+ * 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`.
+ *
+ * `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', '127.0.0.1', '::1', '0.0.0.0']);
+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 `.`.
+ *
+ * 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) {
+    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`.
+ */
+function isLoopbackIpv6(hostname) {
+    const mapped = /^::ffff:(.+)$/.exec(hostname);
+    if (!mapped)
+        return false;
+    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;
+}
 export default class AuthRequest extends Request {
     oauth;
     constructor(oauth) {
@@ -41,7 +82,7 @@ export default class AuthRequest extends Request {
             '/callback/:provider': async (req, state) => {
                 const { provider: providerName } = req.params;
                 const { code, state: stateToken, error } = req.query;
-                const bindingValue = this.readBindingCookie(req);
+                const bindingValues = this.readBindingCookies(req);
                 if (error) {
                     if (this.oauth.frontendCallbackUrl) {
                         state.redirect = `${this.oauth.frontendCallbackUrl}?error=${encodeURIComponent(error)}`;
@@ -51,15 +92,11 @@ export default class AuthRequest extends Request {
                 }
                 if (!code)
                     return 400;
-                // The binding value is single-use, so this callback is the end of that
-                // cookie's life — but only from here down, where the state is actually
-                // consumed. Clearing above the two early returns denied login to a
-                // client still at the provider's consent screen, via an
-                // attacker-induced navigation to `?error=...` that needs no knowledge
-                // of the victim's state at all.
-                this.clearBindingCookie(req);
                 try {
-                    const session = await this.oauth.handleCallback(providerName, code, stateToken, bindingValue);
+                    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);
                     if (this.oauth.frontendCallbackUrl) {
                         const params = new URLSearchParams({
                             sessionId: session.sessionId,
@@ -71,13 +108,51 @@ 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. The messages are fixed strings, so
-                    // nothing caller-controlled reaches the log.
-                    const reason = rejection instanceof Error ? rejection.message : String(rejection);
-                    log.error(`OAuth: callback rejected — ${reason}`);
+                    // 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');
+                    }
                     if (this.oauth.frontendCallbackUrl) {
                         state.redirect = `${this.oauth.frontendCallbackUrl}?error=auth_failed`;
                         return;
@@ -118,24 +193,95 @@ export default class AuthRequest extends Request {
      * 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) {
         if (req.secure === true)
             return true;
+        if (AuthRequest.hasAmbiguousHost(req))
+            return true;
         const host = req.headers.host;
         if (!host)
             return true;
-        // `[::1]:2666` -> `::1`; `localhost:2666` -> `localhost`.
-        const hostname = (host.startsWith('[')
-            ? host.slice(1, host.indexOf(']'))
-            : host.split(':')[0]).toLowerCase();
-        if (LOOPBACK_HOSTS.has(hostname))
-            return false;
-        if (hostname.startsWith('127.'))
-            return false;
-        if (hostname === 'localhost' || hostname.endsWith('.localhost'))
+        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) {
+        const raw = req.rawHeaders;
+        if (!Array.isArray(raw))
             return false;
-        return true;
+        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]`.
+     *
+     * `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.
+     */
+    static parseHostname(host) {
+        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();
+        }
+        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) {
+        if (LOOPBACK_HOSTS.has(hostname))
+            return true;
+        if (isLoopbackIpv4(hostname))
+            return true;
+        return isLoopbackIpv6(hostname);
     }
     setBindingCookie(req, bindingValue) {
         const { res } = req;
@@ -149,11 +295,28 @@ export default class AuthRequest extends Request {
         });
         return true;
     }
-    readBindingCookie(req) {
+    /**
+     * 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.
+     *
+     * Bounded at `MAX_BINDING_COOKIE_CANDIDATES`, so the work an unauthenticated
+     * caller can ask for is capped whatever the header contains.
+     */
+    readBindingCookies(req) {
         const header = req.headers.cookie;
         if (!header)
-            return undefined;
+            return [];
+        const values = [];
         for (const part of header.split(';')) {
+            if (values.length >= MAX_BINDING_COOKIE_CANDIDATES)
+                break;
             const separator = part.indexOf('=');
             if (separator === -1)
                 continue;
@@ -164,9 +327,9 @@ export default class AuthRequest extends Request {
             // `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.
-            return part.slice(separator + 1).trim();
+            values.push(part.slice(separator + 1).trim());
         }
-        return undefined;
+        return values;
     }
     clearBindingCookie(req) {
         const { res } = req;

package/dist/constants.d.ts

@@ -5,3 +5,15 @@ export declare const STATE_COOKIE_SAME_SITE = "lax";
 export declare const STATE_TTL_MS: number;
 /** Entropy of the client-held binding value, in bytes. */
 export declare const BINDING_VALUE_BYTES = 32;
+/**
+ * Most values carrying `STATE_COOKIE_NAME` that a single 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. All of them are tried, so a planted cookie
+ * cannot deny login by sorting ahead of the real one; the cap bounds the work
+ * an unauthenticated caller can ask for. It is not a brute-force control: the
+ * pending record is consumed on recognition, so a state gets one attempt
+ * whatever the cap.
+ */
+export declare const MAX_BINDING_COOKIE_CANDIDATES = 8;

package/dist/constants.js

@@ -14,3 +14,15 @@ export const STATE_COOKIE_SAME_SITE = 'lax';
 export const STATE_TTL_MS = 10 * 60 * 1000;
 /** Entropy of the client-held binding value, in bytes. */
 export const BINDING_VALUE_BYTES = 32;
+/**
+ * Most values carrying `STATE_COOKIE_NAME` that a single 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. All of them are tried, so a planted cookie
+ * cannot deny login by sorting ahead of the real one; the cap bounds the work
+ * an unauthenticated caller can ask for. It is not a brute-force control: the
+ * pending record is consumed on recognition, so a state gets one attempt
+ * whatever the cap.
+ */
+export const MAX_BINDING_COOKIE_CANDIDATES = 8;

package/dist/main.d.ts

@@ -27,14 +27,18 @@ export default class OAuth {
     getProvider(name: string): ProviderEntry;
     getAuthorizationUrl(providerName: string): AuthorizationRequest;
     /**
-     * `bindingValue` is required, not optional (#36). An optional parameter lets
+     * `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 typed as possibly-undefined
-     * because the route handler passes through whatever the client presented,
-     * and `StateStore.consume` rejects falsy explicitly.
+     * 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, bindingValue: string | undefined): Promise<import("./session-manager.js").SessionResult>;
+    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

@@ -52,15 +52,19 @@ export default class OAuth {
         return { url: flow.buildAuthorizationUrl(stateToken), bindingValue };
     }
     /**
-     * `bindingValue` is required, not optional (#36). An optional parameter lets
+     * `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 typed as possibly-undefined
-     * because the route handler passes through whatever the client presented,
-     * and `StateStore.consume` rejects falsy explicitly.
+     * 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, bindingValue) {
-        this.stateStore.consume(stateToken, providerName, bindingValue);
+    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

@@ -10,6 +10,33 @@ export interface PendingState {
     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;
@@ -54,7 +81,34 @@ export default class StateStore {
      * 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.
+     * 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
+     * candidate list is bounded by `MAX_BINDING_COOKIE_CANDIDATES` at the point
+     * it is parsed, and the record is consumed on recognition, so a state still
+     * gets exactly one attempt.
+     *
+     * The loop does not short-circuit, so the work is a function of how many
+     * values were presented and not of which one matched.
      */
-    consume(stateToken: string | undefined, provider: string, bindingValue: string | undefined): void;
+    anyCandidateMatches(candidates: readonly string[], record: PendingState): boolean;
 }

package/dist/state-store.js

@@ -1,5 +1,36 @@
 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).
@@ -59,23 +90,53 @@ export default class StateStore {
      * 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.
+     * 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, bindingValue) {
+    consume(stateToken, provider, bindingValues) {
         if (!stateToken)
-            throw new Error('Invalid or missing state token');
+            throw new StateRejection(STATE_REJECTION.unknownState, false);
         const record = this.pending.get(stateToken);
         if (!record)
-            throw new Error('Invalid or missing state token');
+            throw new StateRejection(STATE_REJECTION.unknownState, false);
         this.pending.delete(stateToken);
         if (Date.now() - record.createdAt > this.ttl)
-            throw new Error('State token has expired');
+            throw new StateRejection(STATE_REJECTION.expired, true);
         if (record.provider !== provider)
-            throw new Error('State token was not issued for this provider');
-        if (!bindingValue)
-            throw new Error('Missing state binding value');
-        if (!StateStore.digestsMatch(StateStore.hash(bindingValue), record.bindingHash)) {
-            throw new Error('State token is not bound to this client');
+            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
+     * candidate list is bounded by `MAX_BINDING_COOKIE_CANDIDATES` at the point
+     * it is parsed, and the record is consumed on recognition, so a state still
+     * gets exactly one attempt.
+     *
+     * 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-alpha.17",
+  "version": "0.1.1-alpha.19",
   "description": "OAuth2 authentication module for the Stonyx framework",
   "repository": {
     "type": "git",

package/src/auth-request.ts

@@ -1,6 +1,8 @@
 import { Request } from '@stonyx/rest-server';
 import log from 'stonyx/log';
+import { StateRejection } from './state-store.js';
 import {
+  MAX_BINDING_COOKIE_CANDIDATES,
   STATE_COOKIE_NAME,
   STATE_COOKIE_PATH,
   STATE_COOKIE_SAME_SITE,
@@ -13,10 +15,53 @@ interface AuthorizationRequest {
 }
 
 /**
- * Hosts treated as a development origin, and the only ones exempt from
- * `Secure` on the binding cookie. See `AuthRequest.isSecureContext`.
+ * 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`.
+ *
+ * `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 `.`.
+ *
+ * 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 LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '::1', '0.0.0.0']);
+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`.
+ */
+function isLoopbackIpv6(hostname: string): boolean {
+  const mapped = /^::ffff:(.+)$/.exec(hostname);
+  if (!mapped) return false;
+
+  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 OAuthInstance {
   frontendCallbackUrl?: string;
@@ -26,7 +71,7 @@ interface OAuthInstance {
     providerName: string,
     code: string,
     stateToken: string,
-    bindingValue: string | undefined,
+    bindingValues: readonly string[],
   ): Promise<{ sessionId: string; expiresAt: number }>;
   logout(sessionId: string): void;
 }
@@ -55,6 +100,13 @@ 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;
@@ -106,7 +158,7 @@ export default class AuthRequest extends Request {
         const { provider: providerName } = req.params;
         const { code, state: stateToken, error } = req.query;
 
-        const bindingValue = this.readBindingCookie(req);
+        const bindingValues = this.readBindingCookies(req);
 
         if (error) {
           if (this.oauth.frontendCallbackUrl) {
@@ -118,16 +170,12 @@ export default class AuthRequest extends Request {
 
         if (!code) return 400;
 
-        // The binding value is single-use, so this callback is the end of that
-        // cookie's life — but only from here down, where the state is actually
-        // consumed. Clearing above the two early returns denied login to a
-        // client still at the provider's consent screen, via an
-        // attacker-induced navigation to `?error=...` that needs no knowledge
-        // of the victim's state at all.
-        this.clearBindingCookie(req);
-
         try {
-          const session = await this.oauth.handleCallback(providerName, code, stateToken, bindingValue);
+          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);
 
           if (this.oauth.frontendCallbackUrl) {
             const params = new URLSearchParams({
@@ -140,13 +188,51 @@ 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. The messages are fixed strings, so
-          // nothing caller-controlled reaches the log.
-          const reason = rejection instanceof Error ? rejection.message : String(rejection);
-          log.error(`OAuth: callback rejected — ${reason}`);
+          // 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');
+          }
 
           if (this.oauth.frontendCallbackUrl) {
             state.redirect = `${this.oauth.frontendCallbackUrl}?error=auth_failed`;
@@ -190,24 +276,98 @@ export default class AuthRequest extends Request {
    * 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;
 
-    // `[::1]:2666` -> `::1`; `localhost:2666` -> `localhost`.
-    const hostname = (host.startsWith('[')
-      ? host.slice(1, host.indexOf(']'))
-      : host.split(':')[0]
-    ).toLowerCase();
+    const hostname = AuthRequest.parseHostname(host);
+    if (hostname === undefined) return true;
 
-    if (LOOPBACK_HOSTS.has(hostname)) return false;
-    if (hostname.startsWith('127.')) return false;
-    if (hostname === 'localhost' || hostname.endsWith('.localhost')) return false;
+    return !AuthRequest.isLoopbackHost(hostname);
+  }
 
-    return true;
+  /**
+   * 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]`.
+   *
+   * `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.
+   */
+  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();
+    }
+
+    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);
   }
 
   setBindingCookie(req: RouteRequest, bindingValue: string): boolean {
@@ -226,11 +386,29 @@ export default class AuthRequest extends Request {
     return true;
   }
 
-  readBindingCookie(req: RouteRequest): string | undefined {
+  /**
+   * 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.
+   *
+   * Bounded at `MAX_BINDING_COOKIE_CANDIDATES`, so the work an unauthenticated
+   * caller can ask for is capped whatever the header contains.
+   */
+  readBindingCookies(req: RouteRequest): string[] {
     const header = req.headers.cookie;
-    if (!header) return undefined;
+    if (!header) return [];
+
+    const values: string[] = [];
 
     for (const part of header.split(';')) {
+      if (values.length >= MAX_BINDING_COOKIE_CANDIDATES) break;
+
       const separator = part.indexOf('=');
       if (separator === -1) continue;
       if (part.slice(0, separator).trim() !== STATE_COOKIE_NAME) continue;
@@ -240,10 +418,10 @@ export default class AuthRequest extends Request {
       // `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.
-      return part.slice(separator + 1).trim();
+      values.push(part.slice(separator + 1).trim());
     }
 
-    return undefined;
+    return values;
   }
 
   clearBindingCookie(req: RouteRequest): void {

package/src/constants.ts

@@ -17,3 +17,16 @@ export const STATE_TTL_MS = 10 * 60 * 1000;
 
 /** Entropy of the client-held binding value, in bytes. */
 export const BINDING_VALUE_BYTES = 32;
+
+/**
+ * Most values carrying `STATE_COOKIE_NAME` that a single 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. All of them are tried, so a planted cookie
+ * cannot deny login by sorting ahead of the real one; the cap bounds the work
+ * an unauthenticated caller can ask for. It is not a brute-force control: the
+ * pending record is consumed on recognition, so a state gets one attempt
+ * whatever the cap.
+ */
+export const MAX_BINDING_COOKIE_CANDIDATES = 8;

package/src/main.ts

@@ -86,20 +86,24 @@ export default class OAuth {
   }
 
   /**
-   * `bindingValue` is required, not optional (#36). An optional parameter lets
+   * `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 typed as possibly-undefined
-   * because the route handler passes through whatever the client presented,
-   * and `StateStore.consume` rejects falsy explicitly.
+   * 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: string,
     code: string,
     stateToken: string,
-    bindingValue: string | undefined,
+    bindingValues: readonly string[],
   ) {
-    this.stateStore.consume(stateToken, providerName, bindingValue);
+    this.stateStore.consume(stateToken, providerName, bindingValues);
 
     const { flow, tokenManager } = this.getProvider(providerName);
     const tokens = await tokenManager.getTokens(code);

package/src/state-store.ts

@@ -14,6 +14,40 @@ export interface PendingState {
   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;
@@ -88,21 +122,56 @@ export default class StateStore {
    * 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.
+   * 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, bindingValue: string | undefined): void {
-    if (!stateToken) throw new Error('Invalid or missing state token');
+  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 Error('Invalid or missing state token');
+    if (!record) throw new StateRejection(STATE_REJECTION.unknownState, false);
     this.pending.delete(stateToken);
 
-    if (Date.now() - record.createdAt > this.ttl) throw new Error('State token has expired');
-    if (record.provider !== provider) throw new Error('State token was not issued for this provider');
-    if (!bindingValue) throw new Error('Missing state binding value');
+    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 (!StateStore.digestsMatch(StateStore.hash(bindingValue), record.bindingHash)) {
-      throw new Error('State token is not bound to this client');
+    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
+   * candidate list is bounded by `MAX_BINDING_COOKIE_CANDIDATES` at the point
+   * it is parsed, and the record is consumed on recognition, so a state still
+   * gets exactly one attempt.
+   *
+   * 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,
+    );
+  }
 }