@stonyx/oauth 0.1.1-alpha.3 → 0.1.1-alpha.30

package/dist/ticket-store.js

@@ -0,0 +1,106 @@
+import { randomBytes } from 'node:crypto';
+/**
+ * Lifetime of an exchange ticket.
+ *
+ * Sized for one redirect plus one page load, and deliberately two orders of
+ * magnitude tighter than the 10-minute state TTL: the ticket is a bearer value
+ * travelling in a URL, and the whole point of #45 is that a bearer value in a
+ * URL must not be long-lived — in the fragment, so it reaches no server, but
+ * still into browser history and readable by scripts on the landing page.
+ */
+export const TICKET_TTL_MS = 60 * 1000;
+/** Entropy of a ticket, in bytes. */
+export const TICKET_BYTES = 32;
+/**
+ * Single-use, short-lived tickets that stand in for a session id on the wire.
+ *
+ * The callback redirect hands the browser a ticket instead of the session id
+ * (#45), in the URL *fragment*, which no user agent transmits to any server.
+ * The ticket authenticates nothing — `GET /auth` reads the `session-id` header
+ * and knows only about `SessionManager` — so a ticket observed in history or
+ * by a script reading `location.hash` is worth something only inside the
+ * sub-second window before the landing page redeems it, and nothing at all
+ * afterwards.
+ *
+ * Known residual, stated rather than papered over: a ticket observed *within*
+ * that window is redeemable by the observer, because nothing here binds a
+ * ticket to the client that started the flow. Closing it means binding the way
+ * #36 bound the state, and that binding has to travel on a cookie the
+ * cross-origin exchange cannot carry.
+ *
+ * The blocker is `abofs/stonyx-rest-server#63`: `@stonyx/rest-server` calls
+ * `cors({ origin, methods })` and has no `credentials` support at all. It is
+ * *not* `abofs/stonyx-rest-server#45` — that issue is the response-header half
+ * and is already worked around in `auth-request.ts`, which sets and clears the
+ * binding cookie on a redirect by reaching through `req.res`. Closing #45
+ * would not make this residual closeable. It is a reduction, not an
+ * elimination.
+ *
+ * Like `OAuth.pendingStates`, an abandoned ticket is never collected. That is
+ * a pre-existing pattern in this module, not something this store introduces,
+ * and it is bounded here by a 60-second TTL rather than a 10-minute one.
+ * Tracked, with both maps named, at `abofs/stonyx-oauth#43`.
+ *
+ * ---
+ *
+ * **Why this is a second store rather than a reuse of `OAuth.pendingStates`.**
+ *
+ * The duplication is real and is not an oversight: `pendingStates` is also a
+ * single-use, TTL-bounded, consume-on-recognition map keyed by a
+ * `randomBytes`-minted opaque token, with the same delete-before-TTL-check
+ * ordering and the same never-collected caveat. The shared shape could be
+ * extracted into one primitive, and the two constants homes (`STATE_TTL_MS`
+ * and `BINDING_VALUE_BYTES` in `main.ts`, `TICKET_TTL_MS` and `TICKET_BYTES`
+ * here) could then live together.
+ *
+ * It is deliberately not done in the change that fixes #45. Widening a
+ * security fix into a refactor of the CSRF store means the #36 binding
+ * mechanism — whose invariants are load-bearing and separately guarded — moves
+ * in the same commit as the fix, for no security gain in either. The two also
+ * do not have the same invariants: `pendingStates` is a security control fed
+ * by an unauthenticated `GET`, holding a *digest* of a client secret, with a
+ * 10-minute budget sized for a provider round trip; this is a delivery
+ * convenience reachable only after a successfully bound callback, holding a
+ * value it hands back, with a 60-second budget sized for a page load.
+ * Collapsing them would couple the control to the convenience.
+ *
+ * The extraction is tracked at `abofs/stonyx-oauth#58`.
+ */
+export default class TicketStore {
+    tickets = new Map();
+    ttl = TICKET_TTL_MS;
+    /**
+     * Mints a ticket for a freshly created session.
+     *
+     * The ticket is independent entropy, never a transform of the session id:
+     * anything derived from the credential is the credential.
+     */
+    issue(sessionId, expiresAt) {
+        const ticket = randomBytes(TICKET_BYTES).toString('base64url');
+        this.tickets.set(ticket, { sessionId, expiresAt, createdAt: Date.now() });
+        return ticket;
+    }
+    /**
+     * Spends a ticket, if it is live.
+     *
+     * Consumed on recognition, *before* the TTL check, for the same reason
+     * `OAuth.handleCallback` consumes a pending state before validating its
+     * binding: every ticket gets exactly one attempt whatever the outcome, so
+     * this endpoint is never a repeatable oracle. Deleting after the TTL check
+     * instead would leave an expired ticket in the map answering `400` forever
+     * while a live one answers `200` — an unauthenticated distinguisher.
+     *
+     * Returns `null` for unknown, spent and expired tickets alike. The caller
+     * maps all three to the same `400`; telling them apart is information the
+     * holder of a ticket they did not mint has no business having.
+     */
+    redeem(ticket) {
+        const record = ticket ? this.tickets.get(ticket) : undefined;
+        if (!record)
+            return null;
+        this.tickets.delete(ticket);
+        if (Date.now() - record.createdAt > this.ttl)
+            return null;
+        return { sessionId: record.sessionId, expiresAt: record.expiresAt };
+    }
+}

package/dist/token-manager.d.ts

@@ -0,0 +1,15 @@
+import type OAuthFlow from './oauth-flow.js';
+import type { TokenResult } from './oauth-flow.js';
+export interface TokenData extends TokenResult {
+    expiresAt: number;
+}
+export default class TokenManager {
+    flow: OAuthFlow;
+    constructor(flow: OAuthFlow);
+    getTokens(code: string): Promise<TokenData>;
+    refresh(refreshToken: string): Promise<TokenData>;
+    revoke(accessToken: string): Promise<void>;
+    isExpired(tokenData: {
+        expiresAt?: number;
+    } | null | undefined): boolean;
+}

package/dist/token-manager.js

@@ -0,0 +1,24 @@
+export default class TokenManager {
+    flow;
+    constructor(flow) {
+        this.flow = flow;
+    }
+    async getTokens(code) {
+        const tokens = await this.flow.exchangeCode(code);
+        tokens.expiresAt = Date.now() + (tokens.expiresIn * 1000);
+        return tokens;
+    }
+    async refresh(refreshToken) {
+        const tokens = await this.flow.refreshAccessToken(refreshToken);
+        tokens.expiresAt = Date.now() + (tokens.expiresIn * 1000);
+        return tokens;
+    }
+    async revoke(accessToken) {
+        return this.flow.revokeToken(accessToken);
+    }
+    isExpired(tokenData) {
+        if (!tokenData?.expiresAt)
+            return true;
+        return Date.now() >= tokenData.expiresAt;
+    }
+}

package/package.json

@@ -4,16 +4,39 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.1.1-alpha.3",
+  "version": "0.1.1-alpha.30",
   "description": "OAuth2 authentication module for the Stonyx framework",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/abofs/stonyx-oauth.git"
   },
-  "main": "src/main.js",
+  "main": "dist/main.js",
   "type": "module",
   "exports": {
-    ".": "./src/main.js"
+    ".": {
+      "types": "./dist/main.d.ts",
+      "default": "./dist/main.js"
+    },
+    "./oauth-flow": {
+      "types": "./dist/oauth-flow.d.ts",
+      "default": "./dist/oauth-flow.js"
+    },
+    "./auth-request": {
+      "types": "./dist/auth-request.d.ts",
+      "default": "./dist/auth-request.js"
+    },
+    "./session-manager": {
+      "types": "./dist/session-manager.d.ts",
+      "default": "./dist/session-manager.js"
+    },
+    "./token-manager": {
+      "types": "./dist/token-manager.d.ts",
+      "default": "./dist/token-manager.js"
+    },
+    "./providers/discord": {
+      "types": "./dist/providers/discord.d.ts",
+      "default": "./dist/providers/discord.js"
+    }
   },
   "author": "Stone Costa",
   "license": "Apache-2.0",
@@ -21,6 +44,7 @@
     "Stone Costa <stone.costa@synamicd.com>"
   ],
   "files": [
+    "dist",
     "src",
     "config",
     "README.md"
@@ -30,19 +54,26 @@
     "provenance": true
   },
   "dependencies": {
-    "stonyx": "0.2.3-beta.11",
-    "@stonyx/events": "0.1.1-beta.9"
+    "@stonyx/events": "0.1.1-beta.54",
+    "stonyx": "0.2.3-beta.82"
   },
   "peerDependencies": {
     "@stonyx/rest-server": ">=0.2.1-beta.11"
   },
   "devDependencies": {
-    "@stonyx/rest-server": "0.2.1-beta.30",
-    "@stonyx/utils": "0.2.3-beta.7",
+    "@stonyx/rest-server": "0.2.1-beta.100",
+    "@stonyx/utils": "0.2.3-beta.26",
+    "@stonyx/logs": "1.0.1-beta.20",
+    "@types/qunit": "^2.19.13",
+    "@types/sinon": "^21.0.1",
     "qunit": "^2.24.1",
-    "sinon": "^21.0.0"
+    "sinon": "^21.0.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.8.3"
   },
   "scripts": {
-    "test": "stonyx test"
+    "build": "tsc",
+    "build:test": "tsc -p tsconfig.test.json",
+    "test": "pnpm build && NODE_ENV=test node --import tsx/esm --import ./test/setup.ts node_modules/qunit/bin/qunit.js 'test/**/*-test.ts'"
   }
 }

package/src/auth-request.ts

@@ -0,0 +1,330 @@
+import { Request } from '@stonyx/rest-server';
+import log from 'stonyx/log';
+
+/**
+ * The cookie carrying the client-held half of the OAuth2 `state` binding (#36).
+ *
+ * The attributes below are load-bearing, not cosmetic:
+ *
+ *   - `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.
+ */
+const STATE_COOKIE_NAME = 'oauth_state';
+const STATE_COOKIE_PATH = '/';
+const STATE_COOKIE_SAME_SITE = 'lax';
+
+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 }>;
+  issueExchangeTicket(session: { sessionId: string; expiresAt: number }): string;
+  redeemExchangeTicket(ticket: string): { sessionId: string; expiresAt: number } | null;
+  logout(sessionId: string): void;
+}
+
+export 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.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;
+  clearCookie(name: string, options: Omit<CookieOptions, 'maxAge'>): unknown;
+}
+
+interface RouteRequest {
+  headers: Record<string, string | undefined>;
+  params: Record<string, string>;
+  query: Record<string, string>;
+  /**
+   * Parsed by `express.json()`, which `@stonyx/rest-server` installs globally.
+   *
+   * Optional and typed loosely because it is whatever an unauthenticated
+   * caller sent: a form-encoded body arrives as `null` and a bodyless request
+   * as `undefined`, so every read of it has to survive both.
+   */
+  body?: unknown;
+  res?: ResponseLike;
+}
+
+interface RouteState {
+  redirect?: string;
+}
+
+export default class AuthRequest extends Request {
+  oauth: OAuthInstance;
+
+  constructor(oauth: OAuthInstance) {
+    super();
+    this.oauth = oauth;
+  }
+
+  handlers = {
+    get: {
+      '/': ({ headers }: RouteRequest) => {
+        const sessionId = headers['session-id'];
+        if (!sessionId) return 401;
+
+        const user = this.oauth.getSession(sessionId);
+        if (!user) return 401;
+
+        return user;
+      },
+
+      '/login/:provider': (req: RouteRequest, state: RouteState) => {
+        const { provider: providerName } = req.params;
+
+        let authorization: AuthorizationRequest;
+        try {
+          authorization = this.oauth.getAuthorizationUrl(providerName);
+        } catch {
+          return 404;
+        }
+
+        // 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: RouteRequest, state: RouteState) => {
+        const { provider: providerName } = req.params;
+        const { code, state: stateToken, error } = req.query;
+
+        if (error) {
+          if (this.oauth.frontendCallbackUrl) {
+            state.redirect = `${this.oauth.frontendCallbackUrl}?error=${encodeURIComponent(error)}`;
+            return;
+          }
+          return 400;
+        }
+
+        if (!code) return 400;
+
+        try {
+          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) {
+            // The session id is the bearer credential (`GET /auth` above
+            // authenticates from exactly this value), so it must not be
+            // written into a URL: URLs land in browser history, in `Referer`
+            // on any outbound link, in proxy and CDN access logs, and in
+            // `location.search` for every script on the landing page. What
+            // goes in the URL instead is a single-use 60-second ticket that
+            // authenticates nothing, redeemed at `POST /auth/session` (#45).
+            //
+            // The ticket rides in the *fragment*, not the query. A fragment is
+            // never transmitted to any server by any user agent: it is absent
+            // from the frontend's own access logs, from every reverse proxy
+            // and CDN in front of the landing page, and from `Referer` under
+            // every referrer policy. That removes two of the four leak vectors
+            // #45 names outright, for one character. What it does not remove
+            // is browser history and readability by page scripts — those are
+            // why the ticket is still single-use and 60-second, and why the
+            // documented migration scrubs it with `history.replaceState`.
+            //
+            // `expiresAt` rides along in the same fragment rather than staying
+            // in the query, so the consumer has one place to read from.
+            // It is not a credential and nothing authenticates from it.
+            const params = new URLSearchParams({
+              ticket: this.oauth.issueExchangeTicket(session),
+              expiresAt: String(session.expiresAt),
+            });
+            state.redirect = `${this.oauth.frontendCallbackUrl}#${params}`;
+            return;
+          }
+
+          // No `frontendCallbackUrl` configured: the session is the response
+          // body of a direct request, not a value handed to a browser through
+          // a URL, so there is nothing here for #45 to fix.
+          return session;
+        } catch {
+          if (this.oauth.frontendCallbackUrl) {
+            state.redirect = `${this.oauth.frontendCallbackUrl}?error=auth_failed`;
+            return;
+          }
+          return 500;
+        }
+      },
+
+      '/logout': ({ headers }: RouteRequest) => {
+        const sessionId = headers['session-id'];
+        if (sessionId) this.oauth.logout(sessionId);
+      },
+    },
+
+    post: {
+      /**
+       * Redeems the exchange ticket from the callback redirect (#45).
+       *
+       * `POST` and not `GET` because a `GET` would put the ticket back in a
+       * URL — in the caller's history, in access logs — which is the defect
+       * this route exists to close.
+       *
+       * `application/json` and not form-encoded: `@stonyx/rest-server`
+       * installs `express.json()` only, so a form-encoded body arrives as
+       * `null` and the ticket is unreadable. Measured, not assumed.
+       *
+       * Unknown, spent and expired tickets are one indistinguishable `400`.
+       */
+      '/session': ({ body }: RouteRequest) => {
+        const ticket = (body as { ticket?: unknown } | null | undefined)?.ticket;
+        if (typeof ticket !== 'string' || !ticket) return 400;
+
+        const session = this.oauth.redeemExchangeTicket(ticket);
+        if (!session) return 400;
+
+        return { sessionId: session.sessionId, expiresAt: session.expiresAt };
+      },
+    },
+  };
+
+  /**
+   * Whether the binding cookie is issued with `Secure`.
+   *
+   * 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.
+   *
+   * 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.
+   *
+   * An unparseable or absent redirect URI fails secure.
+   */
+  isSecureContext(providerName: string): boolean {
+    const redirectUri = this.oauth.redirectUriFor(providerName);
+    if (!redirectUri) return true;
+
+    try {
+      return new URL(redirectUri).protocol !== 'http:';
+    } catch {
+      return true;
+    }
+  }
+
+  cookieOptions(providerName: string): Omit<CookieOptions, 'maxAge'> {
+    return {
+      httpOnly: true,
+      sameSite: STATE_COOKIE_SAME_SITE,
+      path: STATE_COOKIE_PATH,
+      secure: this.isSecureContext(providerName),
+    };
+  }
+
+  setBindingCookie(req: RouteRequest, providerName: string, bindingValue: string): boolean {
+    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(providerName),
+      maxAge: this.oauth.stateTtl,
+    });
+
+    return true;
+  }
+
+  /**
+   * Every value the client presented under the binding cookie's name.
+   *
+   * 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[] {
+    const header = req.headers.cookie;
+    if (!header) return [];
+
+    const values: string[] = [];
+
+    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 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.
+      values.push(part.slice(separator + 1).trim());
+    }
+
+    return values;
+  }
+
+  clearBindingCookie(req: RouteRequest, providerName: string): void {
+    const { res } = req;
+    if (typeof res?.clearCookie !== 'function') return;
+
+    res.clearCookie(STATE_COOKIE_NAME, this.cookieOptions(providerName));
+  }
+}