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

package/README.md

@@ -11,7 +11,7 @@ OAuth2 authentication module for the Stonyx framework. Provides a generic OAuth2
 Add as a devDependency to your Stonyx project:
 
 ```bash
-pnpm add @stonyx/oauth
+npm install @stonyx/oauth
 ```
 
 Requires `@stonyx/rest-server` as a peer dependency.
@@ -55,167 +55,10 @@ The module self-registers the following routes on the rest server:
 | Method | Route | Description |
 |--------|-------|-------------|
 | `GET` | `/auth` | Validate session — send `session-id` header, returns user or 401 |
-| `GET` | `/auth/login/:provider` | Redirects to provider's OAuth2 authorization page, and sets the state binding cookie |
-| `GET` | `/auth/callback/:provider` | OAuth2 callback — verifies the state binding, exchanges code for tokens, creates session |
+| `GET` | `/auth/login/:provider` | Redirects to provider's OAuth2 authorization page |
+| `GET` | `/auth/callback/:provider` | OAuth2 callback — exchanges code for tokens, creates session |
 | `GET` | `/auth/logout` | Destroys session (send `session-id` header) |
 
-### Starting the flow
-
-Send the browser to `/auth/login/:provider` as a **top-level navigation**:
-
-```javascript
-window.location.href = 'https://api.example.com/auth/login/discord';
-```
-
-Do not start the flow with `fetch()` or `XMLHttpRequest`. The login response
-sets the state binding cookie described below, and the browser must be holding
-that cookie when the provider redirects it back to `/auth/callback/:provider`.
-
-## State Binding (CSRF Protection)
-
-The OAuth2 `state` parameter only protects against login CSRF if it is bound to
-the client that started the flow. This module binds it with a cookie.
-
-On `GET /auth/login/:provider` the module issues a random 32-byte binding value,
-stores only a SHA-256 digest of it server-side alongside the provider name and
-issue time, and sends the plaintext to the client as a cookie:
-
-| Attribute | Value | Why |
-|-----------|-------|-----|
-| Name | `stonyx_oauth_state` | |
-| `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 | 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 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 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:
-
-- **The cookie cannot be set at all.** `GET /auth/login/:provider` responds
-  `500` rather than issuing a state it cannot bind, and logs
-  `OAuth: unable to set the state binding cookie; login rejected`. This is a
-  framework-wiring condition — the response object the module reaches for is
-  not there — not a network or proxy one.
-- **`Set-Cookie` is stripped in transit** by a reverse proxy or CDN.
-  `GET /auth/login/:provider` **succeeds and redirects normally**; the module
-  never learns the header was dropped. The failure surfaces one hop later, at
-  `GET /auth/callback/:provider`, as `?error=auth_failed` on
-  `frontendCallbackUrl` (or a bare `500` when it is unset), with
-  `OAuth: callback rejected — Missing state binding value` in the log. First
-  thing to check: does the login response reach the browser carrying
-  `Set-Cookie: stonyx_oauth_state`.
-
-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. 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
-back and forward produces a second `auth_failed`. The user must restart at
-`GET /auth/login/:provider`. Only one login can be in flight per browser at a
-time, for the same reason — the binding cookie has one fixed name, so starting
-a second login overwrites the first flow's binding value and the earlier flow
-will fail at its callback.
-
-### Custom flow drivers
-
-Consumers that drive the flow themselves instead of using the routes above must
-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]);
-```
-
-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
-> required fourth argument, the client's binding values, as an array.
-> Applications using the self-registering `/auth` routes need no changes.
-
 ## Officially Supported Providers
 
 ### Discord
@@ -276,12 +119,6 @@ providers: {
 ## Session Management
 
 Sessions are stored in-memory using a `Map`. Sessions are lost on server restart.
-Pending OAuth states are held in-memory too, so a restart mid-login, or more
-than one instance behind a load balancer, will reject the callback. Pending
-records are removed when a callback consumes them, not swept on a timer — the
-ten-minute age bound is only evaluated when a matching callback arrives, so an
-abandoned flow's record persists until the process restarts. See
-[#38](https://github.com/abofs/stonyx-oauth/issues/38).
 
 Clients should store the `sessionId` returned from the callback and send it as a `session-id` header on subsequent requests.
 

package/dist/auth-request.d.ts

@@ -1,51 +1,18 @@
 import { Request } from '@stonyx/rest-server';
-interface AuthorizationRequest {
-    url: string;
-    bindingValue: string;
-}
 interface OAuthInstance {
     frontendCallbackUrl?: string;
     getSession(sessionId: string): unknown;
-    getAuthorizationUrl(providerName: string): AuthorizationRequest;
-    handleCallback(providerName: string, code: string, stateToken: string, bindingValues: readonly string[]): Promise<{
+    getAuthorizationUrl(providerName: string): string;
+    handleCallback(providerName: string, code: string, stateToken: string): Promise<{
         sessionId: string;
         expiresAt: number;
     }>;
     logout(sessionId: string): void;
 }
-interface CookieOptions {
-    httpOnly: boolean;
-    sameSite: string;
-    path: string;
-    secure: boolean;
-    maxAge?: number;
-}
-/**
- * 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.
- */
-interface ResponseLike {
-    cookie(name: string, value: string, options: CookieOptions): unknown;
-    clearCookie(name: string, options: Omit<CookieOptions, 'maxAge'>): unknown;
-}
 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;
 }
 interface RouteState {
     redirect?: string;
@@ -56,92 +23,13 @@ export default class AuthRequest extends Request {
     handlers: {
         get: {
             '/': ({ headers }: RouteRequest) => {};
-            '/login/:provider': (req: RouteRequest, state: RouteState) => 404 | 500 | undefined;
+            '/login/:provider': (req: RouteRequest, state: RouteState) => 404 | undefined;
             '/callback/:provider': (req: RouteRequest, state: RouteState) => Promise<{
                 sessionId: string;
                 expiresAt: number;
-            } | 500 | 400 | undefined>;
+            } | 400 | 500 | undefined>;
             '/logout': ({ headers }: RouteRequest) => void;
         };
     };
-    cookieOptions(req: RouteRequest): Omit<CookieOptions, 'maxAge'>;
-    /**
-     * 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.
-     *
-     * 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;
-    /**
-     * 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;
-    /**
-     * 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.
-     */
-    readBindingCookies(req: RouteRequest): string[];
-    clearBindingCookie(req: RouteRequest): void;
 }
 export {};

package/dist/auth-request.js

@@ -1,52 +1,4 @@
 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';
-/**
- * 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 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) {
@@ -66,23 +18,17 @@ export default class AuthRequest extends Request {
             },
             '/login/:provider': (req, state) => {
                 const { provider: providerName } = req.params;
-                let authorization;
                 try {
-                    authorization = this.oauth.getAuthorizationUrl(providerName);
+                    const url = this.oauth.getAuthorizationUrl(providerName);
+                    state.redirect = url;
                 }
                 catch {
                     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;
-                state.redirect = authorization.url;
             },
             '/callback/:provider': async (req, state) => {
                 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)}`;
@@ -93,10 +39,7 @@ 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);
                     if (this.oauth.frontendCallbackUrl) {
                         const params = new URLSearchParams({
                             sessionId: session.sessionId,
@@ -107,52 +50,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;
@@ -167,176 +65,4 @@ export default class AuthRequest extends Request {
             },
         }
     };
-    cookieOptions(req) {
-        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.
-     *
-     * 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) {
-        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) {
-        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) {
-        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;
-        if (typeof res?.cookie !== 'function') {
-            log.error('OAuth: unable to set the state binding cookie; login rejected');
-            return false;
-        }
-        res.cookie(STATE_COOKIE_NAME, bindingValue, {
-            ...this.cookieOptions(req),
-            maxAge: STATE_TTL_MS,
-        });
-        return true;
-    }
-    /**
-     * 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.
-     */
-    readBindingCookies(req) {
-        const header = req.headers.cookie;
-        if (!header)
-            return [];
-        const values = [];
-        for (const part of header.split(';')) {
-            const separator = part.indexOf('=');
-            if (separator === -1)
-                continue;
-            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
-            // `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.
-            values.push(part.slice(separator + 1).trim());
-        }
-        return values;
-    }
-    clearBindingCookie(req) {
-        const { res } = req;
-        if (typeof res?.clearCookie !== 'function')
-            return;
-        res.clearCookie(STATE_COOKIE_NAME, this.cookieOptions(req));
-    }
 }