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

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
-npm install @stonyx/oauth
+pnpm add @stonyx/oauth
 ```
 
 Requires `@stonyx/rest-server` as a peer dependency.
@@ -86,7 +86,7 @@ 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 when the request arrived over HTTPS | |
+| `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 |
 | `Max-Age` | 600 (10 minutes) | matches the pending state's lifetime |
 
 `GET /auth/callback/:provider` accepts the callback only when all of the
@@ -101,10 +101,35 @@ 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.
 
-If the cookie cannot be set, `GET /auth/login/:provider` responds `500` rather
-than issuing a state it cannot bind. A reverse proxy or CDN that strips
-`Set-Cookie` from redirect responses will therefore break login rather than
-silently degrade it.
+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. The client-facing `auth_failed` stays deliberately opaque.
+
+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
 
@@ -184,7 +209,11 @@ providers: {
 
 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.
+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

@@ -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): Promise<{
+    handleCallback(providerName: string, code: string, stateToken: string, bindingValue: string | undefined): Promise<{
         sessionId: string;
         expiresAt: number;
     }>;
@@ -58,6 +58,23 @@ export default class AuthRequest extends Request {
         };
     };
     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.
+     */
+    isSecureContext(req: RouteRequest): boolean;
     setBindingCookie(req: RouteRequest, bindingValue: string): boolean;
     readBindingCookie(req: RouteRequest): string | undefined;
     clearBindingCookie(req: RouteRequest): void;

package/dist/auth-request.js

@@ -1,6 +1,11 @@
 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';
+/**
+ * Hosts treated as a development origin, and the only ones exempt from
+ * `Secure` on the binding cookie. See `AuthRequest.isSecureContext`.
+ */
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '::1', '0.0.0.0']);
 export default class AuthRequest extends Request {
     oauth;
     constructor(oauth) {
@@ -36,10 +41,7 @@ export default class AuthRequest extends Request {
             '/callback/:provider': async (req, state) => {
                 const { provider: providerName } = req.params;
                 const { code, state: stateToken, error } = req.query;
-                // The binding value is single-use: whatever the outcome below, this
-                // callback is the end of that cookie's life.
                 const bindingValue = this.readBindingCookie(req);
-                this.clearBindingCookie(req);
                 if (error) {
                     if (this.oauth.frontendCallbackUrl) {
                         state.redirect = `${this.oauth.frontendCallbackUrl}?error=${encodeURIComponent(error)}`;
@@ -49,6 +51,13 @@ 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);
                     if (this.oauth.frontendCallbackUrl) {
@@ -61,7 +70,14 @@ export default class AuthRequest extends Request {
                     }
                     return session;
                 }
-                catch {
+                catch (rejection) {
+                    // `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}`);
                     if (this.oauth.frontendCallbackUrl) {
                         state.redirect = `${this.oauth.frontendCallbackUrl}?error=auth_failed`;
                         return;
@@ -84,9 +100,43 @@ export default class AuthRequest extends Request {
             // request and breaks login outright.
             sameSite: STATE_COOKIE_SAME_SITE,
             path: STATE_COOKIE_PATH,
-            secure: req.secure === true,
+            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.
+     */
+    isSecureContext(req) {
+        if (req.secure === true)
+            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'))
+            return false;
+        return true;
+    }
     setBindingCookie(req, bindingValue) {
         const { res } = req;
         if (typeof res?.cookie !== 'function') {
@@ -109,7 +159,12 @@ export default class AuthRequest extends Request {
                 continue;
             if (part.slice(0, separator).trim() !== STATE_COOKIE_NAME)
                 continue;
-            return decodeURIComponent(part.slice(separator + 1).trim());
+            // 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.
+            return part.slice(separator + 1).trim();
         }
         return undefined;
     }

package/dist/main.d.ts

@@ -26,7 +26,15 @@ export default class OAuth {
     init(): Promise<void>;
     getProvider(name: string): ProviderEntry;
     getAuthorizationUrl(providerName: string): AuthorizationRequest;
-    handleCallback(providerName: string, code: string, stateToken: string, bindingValue?: string): Promise<import("./session-manager.js").SessionResult>;
+    /**
+     * `bindingValue` 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.
+     */
+    handleCallback(providerName: string, code: string, stateToken: string, bindingValue: string | undefined): Promise<import("./session-manager.js").SessionResult>;
     getSession(sessionId: string): unknown;
     logout(sessionId: string): void;
 }

package/dist/main.js

@@ -51,6 +51,14 @@ export default class OAuth {
         const { stateToken, bindingValue } = this.stateStore.issue(providerName);
         return { url: flow.buildAuthorizationUrl(stateToken), bindingValue };
     }
+    /**
+     * `bindingValue` 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.
+     */
     async handleCallback(providerName, code, stateToken, bindingValue) {
         this.stateStore.consume(stateToken, providerName, bindingValue);
         const { flow, tokenManager } = this.getProvider(providerName);

package/dist/state-store.d.ts

@@ -39,9 +39,22 @@ export default class StateStore {
     /**
      * Validates and consumes a pending state. Throws on every rejection path.
      *
-     * The record is removed as soon as the state is recognised — before the
-     * binding is checked — so a state cannot survive a failed attempt and be
-     * used as a target for guessing the binding value.
+     * The record is removed as soon as the state is recognised — before the TTL,
+     * provider and binding checks — so every state gets exactly one attempt
+     * whatever the outcome.
+     *
+     * That uniformity is the justification, not brute-force resistance:
+     * guessing `BINDING_VALUE_BYTES` of CSPRNG output is infeasible whether or
+     * not the record survives. What retaining it would buy an attacker is a
+     * repeatable, unauthenticated oracle on this endpoint for the state's full
+     * lifetime — and the safety of that would then rest entirely on an entropy
+     * constant a future change can lower. One attempt per state is a structural
+     * property; entropy arithmetic is not.
+     *
+     * 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.
      */
     consume(stateToken: string | undefined, provider: string, bindingValue: string | undefined): void;
 }

package/dist/state-store.js

@@ -44,9 +44,22 @@ export default class StateStore {
     /**
      * Validates and consumes a pending state. Throws on every rejection path.
      *
-     * The record is removed as soon as the state is recognised — before the
-     * binding is checked — so a state cannot survive a failed attempt and be
-     * used as a target for guessing the binding value.
+     * The record is removed as soon as the state is recognised — before the TTL,
+     * provider and binding checks — so every state gets exactly one attempt
+     * whatever the outcome.
+     *
+     * That uniformity is the justification, not brute-force resistance:
+     * guessing `BINDING_VALUE_BYTES` of CSPRNG output is infeasible whether or
+     * not the record survives. What retaining it would buy an attacker is a
+     * repeatable, unauthenticated oracle on this endpoint for the state's full
+     * lifetime — and the safety of that would then rest entirely on an entropy
+     * constant a future change can lower. One attempt per state is a structural
+     * property; entropy arithmetic is not.
+     *
+     * 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.
      */
     consume(stateToken, provider, bindingValue) {
         if (!stateToken)

package/package.json

@@ -4,7 +4,7 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.1.1-alpha.16",
+  "version": "0.1.1-alpha.17",
   "description": "OAuth2 authentication module for the Stonyx framework",
   "repository": {
     "type": "git",
@@ -17,10 +17,6 @@
       "types": "./dist/main.d.ts",
       "default": "./dist/main.js"
     },
-    "./constants": {
-      "types": "./dist/constants.d.ts",
-      "default": "./dist/constants.js"
-    },
     "./oauth-flow": {
       "types": "./dist/oauth-flow.d.ts",
       "default": "./dist/oauth-flow.js"
@@ -65,7 +61,7 @@
     "@stonyx/rest-server": ">=0.2.1-beta.11"
   },
   "devDependencies": {
-    "@stonyx/rest-server": "0.2.1-beta.80",
+    "@stonyx/rest-server": "0.2.1-beta.81",
     "@stonyx/utils": "0.2.3-beta.26",
     "@stonyx/logs": "1.0.1-beta.19",
     "@types/qunit": "^2.19.13",

package/src/auth-request.ts

@@ -12,6 +12,12 @@ interface AuthorizationRequest {
   bindingValue: string;
 }
 
+/**
+ * Hosts treated as a development origin, and the only ones exempt from
+ * `Secure` on the binding cookie. See `AuthRequest.isSecureContext`.
+ */
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '::1', '0.0.0.0']);
+
 interface OAuthInstance {
   frontendCallbackUrl?: string;
   getSession(sessionId: string): unknown;
@@ -20,7 +26,7 @@ interface OAuthInstance {
     providerName: string,
     code: string,
     stateToken: string,
-    bindingValue?: string,
+    bindingValue: string | undefined,
   ): Promise<{ sessionId: string; expiresAt: number }>;
   logout(sessionId: string): void;
 }
@@ -100,10 +106,7 @@ export default class AuthRequest extends Request {
         const { provider: providerName } = req.params;
         const { code, state: stateToken, error } = req.query;
 
-        // The binding value is single-use: whatever the outcome below, this
-        // callback is the end of that cookie's life.
         const bindingValue = this.readBindingCookie(req);
-        this.clearBindingCookie(req);
 
         if (error) {
           if (this.oauth.frontendCallbackUrl) {
@@ -115,6 +118,14 @@ 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);
 
@@ -128,7 +139,15 @@ export default class AuthRequest extends Request {
           }
 
           return session;
-        } catch {
+        } catch (rejection) {
+          // `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}`);
+
           if (this.oauth.frontendCallbackUrl) {
             state.redirect = `${this.oauth.frontendCallbackUrl}?error=auth_failed`;
             return;
@@ -152,10 +171,45 @@ export default class AuthRequest extends Request {
       // request and breaks login outright.
       sameSite: STATE_COOKIE_SAME_SITE,
       path: STATE_COOKIE_PATH,
-      secure: req.secure === true,
+      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.
+   */
+  isSecureContext(req: RouteRequest): boolean {
+    if (req.secure === true) 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')) return false;
+
+    return true;
+  }
+
   setBindingCookie(req: RouteRequest, bindingValue: string): boolean {
     const { res } = req;
 
@@ -181,7 +235,12 @@ export default class AuthRequest extends Request {
       if (separator === -1) continue;
       if (part.slice(0, separator).trim() !== STATE_COOKIE_NAME) continue;
 
-      return decodeURIComponent(part.slice(separator + 1).trim());
+      // 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.
+      return part.slice(separator + 1).trim();
     }
 
     return undefined;

package/src/main.ts

@@ -85,7 +85,20 @@ export default class OAuth {
     return { url: flow.buildAuthorizationUrl(stateToken), bindingValue };
   }
 
-  async handleCallback(providerName: string, code: string, stateToken: string, bindingValue?: string) {
+  /**
+   * `bindingValue` 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.
+   */
+  async handleCallback(
+    providerName: string,
+    code: string,
+    stateToken: string,
+    bindingValue: string | undefined,
+  ) {
     this.stateStore.consume(stateToken, providerName, bindingValue);
 
     const { flow, tokenManager } = this.getProvider(providerName);

package/src/state-store.ts

@@ -73,9 +73,22 @@ export default class StateStore {
   /**
    * Validates and consumes a pending state. Throws on every rejection path.
    *
-   * The record is removed as soon as the state is recognised — before the
-   * binding is checked — so a state cannot survive a failed attempt and be
-   * used as a target for guessing the binding value.
+   * The record is removed as soon as the state is recognised — before the TTL,
+   * provider and binding checks — so every state gets exactly one attempt
+   * whatever the outcome.
+   *
+   * That uniformity is the justification, not brute-force resistance:
+   * guessing `BINDING_VALUE_BYTES` of CSPRNG output is infeasible whether or
+   * not the record survives. What retaining it would buy an attacker is a
+   * repeatable, unauthenticated oracle on this endpoint for the state's full
+   * lifetime — and the safety of that would then rest entirely on an entropy
+   * constant a future change can lower. One attempt per state is a structural
+   * property; entropy arithmetic is not.
+   *
+   * 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.
    */
   consume(stateToken: string | undefined, provider: string, bindingValue: string | undefined): void {
     if (!stateToken) throw new Error('Invalid or missing state token');