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

package/dist/auth-request.js

@@ -1,52 +1,24 @@
 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`.
+ * The cookie carrying the client-held half of the OAuth2 `state` binding (#36).
  *
- * `0.0.0.0` and `::` are the wildcard bind addresses a developer reaches a
- * local server on; `127.0.0.1` is covered by the `127.0.0.0/8` test rather than
- * listed here, so the two are not silently redundant.
- */
-const LOOPBACK_HOSTS = new Set(['localhost', '::1', '0:0:0:0:0:0:0:1', '0.0.0.0', '::']);
-/** `host` values whose port component is anything but a decimal port are rejected. */
-const PORT_PATTERN = /^\d{1,5}$/;
-/**
- * The characters RFC 1123 permits in a registered hostname, plus `.`.
+ * The attributes below are load-bearing, not cosmetic:
  *
- * Anything else — `@`, `,`, whitespace, `/` — means the value is not a bare
- * hostname, and the caller fails secure rather than guessing. This is what
- * rejects `localhost:80@evil.com` and a comma-joined multi-value `Host`.
- */
-const HOSTNAME_PATTERN = /^[A-Za-z0-9._-]+$/;
-/** A dotted-quad whose first octet is 127, i.e. real `127.0.0.0/8` membership. */
-function isLoopbackIpv4(hostname) {
-    const octets = hostname.split('.');
-    if (octets.length !== 4)
-        return false;
-    if (!octets.every(octet => /^\d{1,3}$/.test(octet) && Number(octet) <= 255))
-        return false;
-    return Number(octets[0]) === 127;
-}
-/**
- * IPv4-mapped IPv6 loopback, in both spellings a dual-stack listener produces:
- * `::ffff:127.0.0.1` and `::ffff:7f00:1`.
+ *   - `SameSite=Lax` — the callback is a cross-site, top-level GET navigation
+ *     initiated by the provider. `Strict` withholds the cookie on exactly that
+ *     request, breaking 100% of logins while passing every CSRF test; `None`
+ *     requires `Secure` and widens exposure for no benefit.
+ *   - `Path=/` — routing is case-insensitive today
+ *     (`abofs/stonyx-rest-server#47`: `GET /AUTH/login/discord` redirects) but
+ *     RFC 6265 section 5.1.4 `Path` matching is case-sensitive, so a narrow
+ *     `/auth` silently drops the cookie on a case-varied callback and breaks
+ *     login.
+ *   - `HttpOnly` — script must not be able to read or forge the binding value.
  */
-function isLoopbackIpv6(hostname) {
-    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;
-}
+const STATE_COOKIE_NAME = 'oauth_state';
+const STATE_COOKIE_PATH = '/';
+const STATE_COOKIE_SAME_SITE = 'lax';
 export default class AuthRequest extends Request {
     oauth;
     constructor(oauth) {
@@ -73,16 +45,18 @@ export default class AuthRequest extends Request {
                 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))
+                // Fail closed. A state we cannot bind to this client is exactly the
+                // defect this mechanism exists to prevent, so it is withdrawn rather
+                // than issued unbindable.
+                if (!this.setBindingCookie(req, providerName, authorization.bindingValue)) {
+                    this.oauth.discardState(authorization.stateToken);
                     return 500;
+                }
                 state.redirect = authorization.url;
             },
             '/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 +67,17 @@ export default class AuthRequest extends Request {
                 if (!code)
                     return 400;
                 try {
-                    const session = await this.oauth.handleCallback(providerName, code, stateToken, bindingValues);
-                    // The binding value is single-use and the state has now been
-                    // consumed, so this is the end of that cookie's life.
-                    this.clearBindingCookie(req);
+                    const session = await this.oauth.handleCallback(providerName, code, stateToken, this.readBindingCookies(req));
+                    // Cleared only here, on the success path, which is the only path that
+                    // is certain to have consumed a state belonging to *this* client.
+                    //
+                    // Clearing on failure instead looks harmless and is not: `code` is
+                    // attacker-supplied and unvalidated, so a bare `?code=1` — no
+                    // knowledge of anyone's state — would delete the binding cookie of a
+                    // client still sitting on the provider's consent screen, leaving
+                    // their pending state untouched so nothing is detectable
+                    // server-side, and their real callback then fails.
+                    this.clearBindingCookie(req, providerName);
                     if (this.oauth.frontendCallbackUrl) {
                         const params = new URLSearchParams({
                             sessionId: session.sessionId,
@@ -107,52 +88,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,151 +103,60 @@ 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.
+     * Derived from the scheme of the provider's configured `redirectUri`, which
+     * is the deployment's own statement of the origin this cookie has to survive
+     * a round trip to.
      *
-     * So `Secure` is set unconditionally except on a loopback host. Guessing
-     * wrong there breaks a non-loopback plaintext development setup, which fails
-     * at the first login and is loud. The alternative fails silently, in
-     * production, on the one attribute protecting the value this whole mechanism
-     * is built around.
+     * Not `req.secure`: express derives that from the socket unless `trust proxy`
+     * is on, and `@stonyx/rest-server` leaves it off by default, so in the
+     * standard production topology — TLS terminated at a proxy, plaintext to the
+     * origin — `req.secure` is `false` on every request to an HTTPS site and the
+     * cookie would ship without `Secure` while the deployment looks correct. Not
+     * the `Host` header either: that is attacker-controllable on any non-browser
+     * client. And not hardcoded `true`, which breaks plaintext local development.
      *
-     * 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.
+     * An unparseable or absent redirect URI fails secure.
      */
-    isSecureContext(req) {
-        if (req.secure === true)
-            return true;
-        if (AuthRequest.hasAmbiguousHost(req))
+    isSecureContext(providerName) {
+        const redirectUri = this.oauth.redirectUriFor(providerName);
+        if (!redirectUri)
             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++;
+        try {
+            return new URL(redirectUri).protocol !== 'http:';
         }
-        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();
+        catch {
+            return true;
         }
-        const colon = host.indexOf(':');
-        if (colon === -1)
-            return HOSTNAME_PATTERN.test(host) ? host.toLowerCase() : undefined;
-        if (!PORT_PATTERN.test(host.slice(colon + 1)))
-            return undefined;
-        const name = host.slice(0, colon);
-        return HOSTNAME_PATTERN.test(name) ? name.toLowerCase() : undefined;
     }
-    /**
-     * Whether a parsed hostname is a loopback development origin.
-     *
-     * Membership tests, never prefix or suffix tests. `startsWith('127.')`
-     * matched `127.evil.com`, a perfectly registerable name (RFC 1123 permits a
-     * leading digit in a label), and `endsWith('.localhost')` exempted an entire
-     * suffix — so a `.localhost` split-horizon vhost shipped the binding value in
-     * cleartext. The `.localhost` exemption is withdrawn rather than tightened:
-     * the README documented `127.0.0.0/8`, `localhost`, `::1` and `0.0.0.0` and
-     * never documented it, and a developer on `app.localhost` reaches the same
-     * server on `localhost` or `127.0.0.1`.
-     */
-    static isLoopbackHost(hostname) {
-        if (LOOPBACK_HOSTS.has(hostname))
-            return true;
-        if (isLoopbackIpv4(hostname))
-            return true;
-        return isLoopbackIpv6(hostname);
+    cookieOptions(providerName) {
+        return {
+            httpOnly: true,
+            sameSite: STATE_COOKIE_SAME_SITE,
+            path: STATE_COOKIE_PATH,
+            secure: this.isSecureContext(providerName),
+        };
     }
-    setBindingCookie(req, bindingValue) {
+    setBindingCookie(req, providerName, 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,
+            ...this.cookieOptions(providerName),
+            maxAge: this.oauth.stateTtl,
         });
         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.
+     * Not the first one, and not capped — see `OAuth.anyCandidateMatches` for why
+     * either would hand an attacker a permanent, unauthenticated denial of login
+     * for any victim they can plant a same-named cookie on.
      */
     readBindingCookies(req) {
         const header = req.headers.cookie;
@@ -325,18 +170,18 @@ export default class AuthRequest extends Request {
             if (part.slice(0, separator).trim() !== STATE_COOKIE_NAME)
                 continue;
             // Not decoded. The binding value is base64url, whose alphabet
-            // `encodeURIComponent` never escapes, so a decode buys nothing — and
+            // `encodeURIComponent` never escapes, so decoding buys nothing — and
             // `decodeURIComponent` throws `URIError` on malformed input, which any
             // unauthenticated caller can supply, turning the first line of the
-            // callback into a 500 with a stack trace.
+            // callback into a 500.
             values.push(part.slice(separator + 1).trim());
         }
         return values;
     }
-    clearBindingCookie(req) {
+    clearBindingCookie(req, providerName) {
         const { res } = req;
         if (typeof res?.clearCookie !== 'function')
             return;
-        res.clearCookie(STATE_COOKIE_NAME, this.cookieOptions(req));
+        res.clearCookie(STATE_COOKIE_NAME, this.cookieOptions(providerName));
     }
 }

package/dist/main.d.ts

@@ -1,44 +1,105 @@
 import TokenManager from './token-manager.js';
 import SessionManager from './session-manager.js';
-import StateStore from './state-store.js';
 import type OAuthFlow from './oauth-flow.js';
+/** Lifetime of a pending state, and the binding cookie's `Max-Age`. */
+export declare const STATE_TTL_MS: number;
+/** Entropy of the client-held binding value, in bytes. */
+export declare const BINDING_VALUE_BYTES = 32;
 interface ProviderEntry {
     flow: OAuthFlow;
     tokenManager: TokenManager;
 }
-export interface AuthorizationRequest {
-    /** Provider authorization URL to redirect the client to. */
+/**
+ * A flow that is in progress.
+ *
+ * Holds a *digest* of the binding value rather than the value itself: a
+ * callback is only accepted when the caller presents the plaintext that hashes
+ * to `bindingHash`, so the record on its own unlocks nothing.
+ */
+export interface PendingState {
+    bindingHash: string;
+    createdAt: number;
+}
+export interface IssuedState {
+    /** Sent to the provider as the OAuth2 `state` parameter. */
     url: string;
-    /**
-     * Client-held half of the state binding (#36). The caller must hand this to
-     * the client that started the flow — the auth routes set it as an HttpOnly
-     * cookie — and present it back to `handleCallback`.
-     */
+    /** Retained so a login that cannot be bound can withdraw its own state. */
+    stateToken: string;
+    /** Held by the client that started the flow, never by the provider. */
     bindingValue: string;
 }
 export default class OAuth {
     static instance: OAuth | null;
     providers: Map<string, ProviderEntry>;
-    stateStore: StateStore;
+    pendingStates: Map<string, PendingState>;
+    stateTtl: number;
     sessionManager: SessionManager;
     frontendCallbackUrl?: string;
     constructor();
     init(): Promise<void>;
     getProvider(name: string): ProviderEntry;
-    getAuthorizationUrl(providerName: string): AuthorizationRequest;
     /**
-     * `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.
+     * SHA-256 of a binding value, hex encoded.
+     *
+     * The pending record stores the digest so that read access to the map does
+     * not hand over the value a callback must present.
+     */
+    static hash(value: string): string;
+    /** Length-independent, content-constant-time comparison of two digests. */
+    static digestsMatch(a: string, b: string): boolean;
+    /**
+     * Whether *any* presented value is the binding value for this record.
+     *
+     * Every candidate is tried, and the callback is accepted if one matches.
+     * Stopping at the first value carrying the cookie's name instead makes a
+     * planted cookie a permanent, unauthenticated denial of login: RFC 6265
+     * section 5.4 orders the `Cookie` header by path length then creation time,
+     * so an attacker with content control on a sibling subdomain sets a
+     * same-named cookie once and every subsequent callback for that victim reads
+     * theirs, fails the binding check, and burns the state on the way out. The
+     * victim cannot recover by retrying.
+     *
+     * Accepting any match gives an attacker nothing: they would have to present
+     * the victim's own binding value, which is the property being checked. And
+     * the candidate list is deliberately uncapped — a cap does not bound an
+     * attack, it *is* one, reinstating that denial above its own threshold
+     * because the planted cookies are the ones that sort first. The work is
+     * already bounded by Node's 16 KB header limit.
+     *
+     * The reduce does not short-circuit, so the work is a function of how many
+     * values were presented and not of which one matched.
+     */
+    static anyCandidateMatches(candidates: readonly string[], bindingHash: string): boolean;
+    /**
+     * Starts a flow: an OAuth2 `state` for the provider, and a binding value for
+     * the client that asked for it.
+     *
+     * `state` on its own is replay-window limiting, not the CSRF binding it
+     * exists to provide (RFC 6749 section 10.12, RFC 9700): before this, any
+     * state issued to any visitor validated for any callback, so an attacker
+     * could harvest their own state and code, deliver them to a victim over a
+     * plain link, and log the victim into the attacker's account. The binding
+     * value is the thing the victim's browser carries and the attacker's does
+     * not (#36).
+     */
+    getAuthorizationUrl(providerName: string): IssuedState;
+    /**
+     * Withdraws a state that was issued but could not be handed to a client.
+     *
+     * Used by the login route when the binding cookie cannot be set: a state the
+     * client cannot be bound to is exactly the defect this mechanism exists to
+     * prevent, so it must not outlive the request that failed to bind it.
+     */
+    discardState(stateToken: string): void;
+    /**
+     * Validates and consumes a pending state, then completes the flow.
      *
-     * 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.
+     * `bindingValues` is every value the client presented under the binding
+     * cookie's name — see `anyCandidateMatches`.
      */
     handleCallback(providerName: string, code: string, stateToken: string, bindingValues: readonly string[]): Promise<import("./session-manager.js").SessionResult>;
+    /** The provider's configured redirect URI, used to decide the cookie's `Secure`. */
+    redirectUriFor(providerName: string): string | undefined;
     getSession(sessionId: string): unknown;
     logout(sessionId: string): void;
 }