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

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
@@ -273,15 +116,54 @@ providers: {
 }
 ```
 
+## Login CSRF protection — the `oauth_state` cookie
+
+**Breaking, as of the fix for [#36](https://github.com/abofs/stonyx-oauth/issues/36): the login flow now requires a cookie jar.** A client that cannot hold a cookie between `/auth/login/:provider` and `/auth/callback/:provider` can no longer complete a login. That is the point of the change — see [Migration](#migration-from-a-cookie-less-client) below.
+
+`GET /auth/login/:provider` issues a single-use `oauth_state` cookie and keeps only its SHA-256 server-side. `GET /auth/callback/:provider` accepts an OAuth2 `state` only from a caller that also presents the matching cookie value.
+
+Without it, `state` was verified by membership in a server-side map plus an age bound, and nothing else. There was no value the browser that started the flow carried that another browser did not, so an attacker could start a login, harvest their own `state` and `code`, deliver them to a victim over a plain link, and log that victim into the *attacker's* account (RFC 6749 §10.12, RFC 9700). The victim's own account and data are not exposed; what is at risk is whatever they author afterwards, believing the session is theirs.
+
+### Cookie attributes
+
+| Attribute | Value | Why |
+|-----------|-------|-----|
+| Name | `oauth_state` | Single-use; issued at login, cleared on a successful callback |
+| `HttpOnly` | always | 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. `Strict` withholds the cookie on exactly that request and breaks every login |
+| `Path` | `/` | Routing is case-insensitive; RFC 6265 `Path` matching is not. A narrower path silently drops the cookie on a case-varied callback |
+| `Secure` | when the provider's `redirectUri` is not `http:` | Derived from your configured redirect URI, so plaintext local development works and a TLS deployment behind a terminating proxy still gets `Secure` |
+| `Max-Age` | 600 seconds | Matches the server-side state TTL |
+
+If the runtime cannot set the cookie, `/auth/login/:provider` returns `500` and issues no state, rather than issuing one that cannot be bound.
+
+### Requirements for consumers
+
+- **Start the login as a top-level navigation** (`window.location = '/auth/login/discord'`, or a plain link). This is the documented pattern and it avoids CORS entirely.
+- **Serve login and callback from the same origin.** A cookie set on the login origin is not sent to a different callback origin, and the login fails.
+- An XHR-initiated login will not work: `@stonyx/rest-server` sets `origin: '*'` without `credentials: true`, so the browser will neither store nor send the cookie on a cross-origin XHR.
+
+### Migration from a cookie-less client
+
+Scripted and server-to-server logins break. If you drive the flow yourself, carry the `Set-Cookie` from the login response back as a `Cookie` header on the callback:
+
+```javascript
+const login = await fetch(`${host}/auth/login/discord`, { redirect: 'manual' });
+const cookie = login.headers.getSetCookie().map(header => header.split(';')[0]).join('; ');
+const state = new URL(login.headers.get('location')).searchParams.get('state');
+
+// ...provider redirects back with `code`...
+await fetch(`${host}/auth/callback/discord?code=${code}&state=${state}`, {
+  redirect: 'manual',
+  headers: { cookie },
+});
+```
+
+In a browser, `fetch` needs `credentials: 'include'` for a cross-origin request — but see the CORS caveat above; a top-level navigation is the supported path.
+
 ## 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,12 +1,16 @@
 import { Request } from '@stonyx/rest-server';
 interface AuthorizationRequest {
     url: string;
+    stateToken: string;
     bindingValue: string;
 }
 interface OAuthInstance {
     frontendCallbackUrl?: string;
+    stateTtl: number;
     getSession(sessionId: string): unknown;
     getAuthorizationUrl(providerName: string): AuthorizationRequest;
+    discardState(stateToken: string): void;
+    redirectUriFor(providerName: string): string | undefined;
     handleCallback(providerName: string, code: string, stateToken: string, bindingValues: readonly string[]): Promise<{
         sessionId: string;
         expiresAt: number;
@@ -21,13 +25,17 @@ interface CookieOptions {
     maxAge?: number;
 }
 /**
- * The response object Express hangs off the request.
+ * The response object express hangs off the request.
  *
- * `@stonyx/rest-server` hands handlers `(req, state)` only, and `state` has no
- * affordance for response headers, so setting a cookie means reaching for
- * `req.res`. This is a deliberate, temporary escape hatch — tracked by
- * `abofs/stonyx-rest-server#45`, which adds a first-class header affordance to
- * migrate onto.
+ * `@stonyx/rest-server` hands handlers `(req, state)` only, and `state.pipe.headers`
+ * is unreachable once `state.redirect` is set (`request.ts` returns on the
+ * redirect first), so setting a cookie means reaching for `req.res`.
+ *
+ * This is a deliberate, sanctioned interim reach-around, not an accident:
+ * `abofs/stonyx-rest-server#45` is the reopened successor issue that adds a
+ * first-class header/cookie affordance to migrate onto, and it is sequenced
+ * after this fix. `setBindingCookie` fails closed if the affordance is not
+ * there, which is what contains the dependency.
  */
 interface ResponseLike {
     cookie(name: string, value: string, options: CookieOptions): unknown;
@@ -35,16 +43,8 @@ interface ResponseLike {
 }
 interface RouteRequest {
     headers: Record<string, string | undefined>;
-    /**
-     * Node's flat `[name, value, name, value, ...]` header list, when the runtime
-     * supplies it. Read only to detect a *duplicate* `Host`: Node collapses
-     * repeats into the first value, so `req.headers.host` alone cannot tell an
-     * unambiguous origin from a smuggled one.
-     */
-    rawHeaders?: string[];
     params: Record<string, string>;
     query: Record<string, string>;
-    secure?: boolean;
     res?: ResponseLike;
 }
 interface RouteState {
@@ -64,84 +64,34 @@ export default class AuthRequest extends Request {
             '/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.
+     * 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: 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;
+    isSecureContext(providerName: string): boolean;
+    cookieOptions(providerName: string): Omit<CookieOptions, 'maxAge'>;
+    setBindingCookie(req: RouteRequest, providerName: string, 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.
+     * Not the first one, and not capped — see `OAuth.anyCandidateMatches` for why
+     * either would hand an attacker a permanent, unauthenticated denial of login
+     * for any victim they can plant a same-named cookie on.
      */
     readBindingCookies(req: RouteRequest): string[];
-    clearBindingCookie(req: RouteRequest): void;
+    clearBindingCookie(req: RouteRequest, providerName: string): void;
 }
 export {};