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

package/src/main.ts

@@ -0,0 +1,259 @@
+import { createHash, randomBytes, randomUUID } from 'node:crypto';
+import config from 'stonyx/config';
+import log from 'stonyx/log';
+import { waitForModule } from 'stonyx';
+import { setup, emit } from '@stonyx/events';
+import RestServer from '@stonyx/rest-server';
+import TokenManager from './token-manager.js';
+import SessionManager from './session-manager.js';
+import TicketStore from './ticket-store.js';
+import AuthRequest from './auth-request.js';
+import type { RedeemedTicket } from './ticket-store.js';
+import type { SessionResult } from './session-manager.js';
+import type OAuthFlow from './oauth-flow.js';
+
+setup(['authenticate']);
+
+/** Lifetime of a pending state, and the binding cookie's `Max-Age`. */
+export const STATE_TTL_MS = 10 * 60 * 1000;
+
+/** Entropy of the client-held binding value, in bytes. */
+export const BINDING_VALUE_BYTES = 32;
+
+interface ProviderEntry {
+  flow: OAuthFlow;
+  tokenManager: TokenManager;
+}
+
+/**
+ * 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;
+  /** 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;
+}
+
+interface ProviderConfig {
+  module?: string;
+  [key: string]: unknown;
+}
+
+export default class OAuth {
+  static instance: OAuth | null;
+
+  providers = new Map<string, ProviderEntry>();
+  pendingStates = new Map<string, PendingState>();
+  stateTtl = STATE_TTL_MS;
+  sessionManager!: SessionManager;
+  ticketStore = new TicketStore();
+  frontendCallbackUrl?: string;
+
+  constructor() {
+    if (OAuth.instance) return OAuth.instance;
+    OAuth.instance = this;
+  }
+
+  async init(): Promise<void> {
+    // Self-register so log.oauth works even when @stonyx/oauth is in the
+    // consumer's `dependencies` (stonyx loader only merges devDependencies).
+    const { logColor = 'magenta', logMethod = 'oauth' } = config.oauth;
+    log.defineType(logMethod, logColor);
+
+    const oauthConfig = config.oauth;
+    const { providers, sessionDuration, frontendCallbackUrl } = oauthConfig;
+    this.frontendCallbackUrl = frontendCallbackUrl;
+
+    for (const [name, providerConfig] of Object.entries(providers)) {
+      const modulePath = providerConfig.module
+        ? `${config.rootPath}/${providerConfig.module}`
+        : `./providers/${name}.js`;
+      const { default: Provider } = await import(modulePath);
+      const flow: OAuthFlow = new Provider(providerConfig);
+      this.providers.set(name, { flow, tokenManager: new TokenManager(flow) });
+    }
+
+    this.sessionManager = new SessionManager(sessionDuration);
+
+    await waitForModule('rest-server');
+    RestServer.instance.mountRoute(AuthRequest, { name: 'auth', options: this });
+
+    log.oauth?.('OAuth module initialized');
+  }
+
+  getProvider(name: string): ProviderEntry {
+    const provider = this.providers.get(name);
+    if (!provider) throw new Error(`OAuth provider "${name}" is not configured`);
+    return provider;
+  }
+
+  /**
+   * 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 {
+    return createHash('sha256').update(value).digest('hex');
+  }
+
+  /** Length-independent, content-constant-time comparison of two digests. */
+  static digestsMatch(a: string, b: string): boolean {
+    if (a.length !== b.length) return false;
+
+    let difference = 0;
+    for (let index = 0; index < a.length; index++) {
+      difference |= a.charCodeAt(index) ^ b.charCodeAt(index);
+    }
+
+    return difference === 0;
+  }
+
+  /**
+   * 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 {
+    return candidates.reduce(
+      (matched, candidate) => OAuth.digestsMatch(OAuth.hash(candidate), bindingHash) || matched,
+      false,
+    );
+  }
+
+  /**
+   * 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 {
+    const { flow } = this.getProvider(providerName);
+    const stateToken = randomUUID();
+    const bindingValue = randomBytes(BINDING_VALUE_BYTES).toString('base64url');
+
+    this.pendingStates.set(stateToken, {
+      bindingHash: OAuth.hash(bindingValue),
+      createdAt: Date.now(),
+    });
+
+    return { url: flow.buildAuthorizationUrl(stateToken), stateToken, bindingValue };
+  }
+
+  /**
+   * 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 {
+    this.pendingStates.delete(stateToken);
+  }
+
+  /**
+   * Validates and consumes a pending state, then completes the flow.
+   *
+   * `bindingValues` is every value the client presented under the binding
+   * cookie's name — see `anyCandidateMatches`.
+   */
+  async handleCallback(providerName: string, code: string, stateToken: string, bindingValues: readonly string[]) {
+    const record = stateToken ? this.pendingStates.get(stateToken) : undefined;
+    if (!record) throw new Error('Invalid or missing state token');
+
+    // Consumed on recognition, before the TTL and binding checks, so every
+    // state gets exactly one attempt whatever the outcome. Checking the
+    // binding first would leave the record in place on a mismatch and turn
+    // this endpoint into a repeatable, unauthenticated oracle against the
+    // binding value for the state's full lifetime.
+    this.pendingStates.delete(stateToken);
+
+    if (Date.now() - record.createdAt > this.stateTtl) {
+      throw new Error('State token has expired');
+    }
+
+    // No "absent means skip". An empty candidate list is a rejection, which is
+    // what makes an attacker-delivered link fail for a victim who never
+    // started the flow and therefore holds no binding cookie.
+    const candidates = bindingValues.filter(value => value.length > 0);
+    if (candidates.length === 0) throw new Error('Missing state binding value');
+
+    if (!OAuth.anyCandidateMatches(candidates, record.bindingHash)) {
+      throw new Error('State token is not bound to this client');
+    }
+
+    // Everything below burns a live authorization code, so the binding is
+    // settled before `exchangeCode` is ever reached.
+    const { flow, tokenManager } = this.getProvider(providerName);
+    const tokens = await tokenManager.getTokens(code);
+    const rawUser = await flow.fetchUserInfo(tokens.accessToken);
+    const user = flow.normalizeUser(rawUser);
+    await emit('authenticate', user);
+    return this.sessionManager.create(user, tokens);
+  }
+
+  /** The provider's configured redirect URI, used to decide the cookie's `Secure`. */
+  redirectUriFor(providerName: string): string | undefined {
+    return this.providers.get(providerName)?.flow.redirectUri;
+  }
+
+  /**
+   * Mints the value the callback redirect is allowed to put in a URL (#45).
+   *
+   * The session id never travels in the redirect. What travels is a ticket
+   * that is single-use, expires in 60 seconds, and authenticates nothing on
+   * its own — `GET /auth` validates against `sessionManager`, which has never
+   * heard of it.
+   */
+  issueExchangeTicket(session: SessionResult): string {
+    return this.ticketStore.issue(session.sessionId, session.expiresAt);
+  }
+
+  /** Spends a ticket for the session id it stands for, or `null`. */
+  redeemExchangeTicket(ticket: string): RedeemedTicket | null {
+    return this.ticketStore.redeem(ticket);
+  }
+
+  getSession(sessionId: string) {
+    return this.sessionManager.validate(sessionId);
+  }
+
+  logout(sessionId: string): void {
+    this.sessionManager.destroy(sessionId);
+  }
+}

package/src/{oauth-flow.js → oauth-flow.ts}

@@ -1,5 +1,29 @@
+export interface OAuthConfig {
+  clientId: string;
+  clientSecret: string;
+  redirectUri: string;
+  scopes?: string[];
+  authorizationUrl: string;
+  tokenUrl: string;
+  userInfoUrl: string;
+}
+
+export interface TokenResult {
+  accessToken: string;
+  refreshToken: string | null;
+  expiresIn: number;
+}
+
 export default class OAuthFlow {
-  constructor({ clientId, clientSecret, redirectUri, scopes, authorizationUrl, tokenUrl, userInfoUrl }) {
+  clientId: string;
+  clientSecret: string;
+  redirectUri: string;
+  scopes: string[];
+  authorizationUrl: string;
+  tokenUrl: string;
+  userInfoUrl: string;
+
+  constructor({ clientId, clientSecret, redirectUri, scopes, authorizationUrl, tokenUrl, userInfoUrl }: OAuthConfig) {
     this.clientId = clientId;
     this.clientSecret = clientSecret;
     this.redirectUri = redirectUri;
@@ -9,7 +33,7 @@ export default class OAuthFlow {
     this.userInfoUrl = userInfoUrl;
   }
 
-  buildAuthorizationUrl(stateToken) {
+  buildAuthorizationUrl(stateToken: string): string {
     const params = new URLSearchParams({
       client_id: this.clientId,
       redirect_uri: this.redirectUri,
@@ -21,7 +45,7 @@ export default class OAuthFlow {
     return `${this.authorizationUrl}?${params.toString()}`;
   }
 
-  async exchangeCode(code) {
+  async exchangeCode(code: string): Promise<TokenResult> {
     const response = await fetch(this.tokenUrl, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
@@ -45,7 +69,7 @@ export default class OAuthFlow {
     };
   }
 
-  async refreshAccessToken(refreshToken) {
+  async refreshAccessToken(refreshToken: string): Promise<TokenResult> {
     const response = await fetch(this.tokenUrl, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
@@ -68,7 +92,7 @@ export default class OAuthFlow {
     };
   }
 
-  async fetchUserInfo(accessToken) {
+  async fetchUserInfo(accessToken: string): Promise<unknown> {
     const response = await fetch(this.userInfoUrl, {
       headers: { Authorization: `Bearer ${accessToken}` },
     });
@@ -78,11 +102,11 @@ export default class OAuthFlow {
     return response.json();
   }
 
-  normalizeUser(rawUser) {
+  normalizeUser(rawUser: unknown): unknown {
     return { raw: rawUser };
   }
 
-  async revokeToken(_accessToken) {
+  async revokeToken(_accessToken: string): Promise<void> {
     // Optional — providers override if supported
   }
 }

package/src/providers/{discord.js → discord.ts}

@@ -1,7 +1,33 @@
 import OAuthFlow from '../oauth-flow.js';
+import type { TokenResult } from '../oauth-flow.js';
+
+interface DiscordProviderConfig {
+  clientId: string;
+  clientSecret: string;
+  redirectUri: string;
+  scopes?: string[];
+  [key: string]: unknown;
+}
+
+interface DiscordUser {
+  id: string;
+  username: string;
+  global_name?: string;
+  avatar: string | null;
+  email?: string | null;
+}
+
+interface NormalizedDiscordUser {
+  id: string;
+  username: string;
+  displayName: string;
+  avatar: string | null;
+  email: string | null;
+  raw: DiscordUser;
+}
 
 export default class DiscordProvider extends OAuthFlow {
-  constructor(config) {
+  constructor(config: DiscordProviderConfig) {
     super({
       ...config,
       authorizationUrl: 'https://discord.com/oauth2/authorize',
@@ -10,7 +36,7 @@ export default class DiscordProvider extends OAuthFlow {
     });
   }
 
-  async exchangeCode(code) {
+  async exchangeCode(code: string): Promise<TokenResult> {
     const response = await fetch(this.tokenUrl, {
       method: 'POST',
       headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
@@ -34,7 +60,7 @@ export default class DiscordProvider extends OAuthFlow {
     };
   }
 
-  normalizeUser(rawUser) {
+  override normalizeUser(rawUser: DiscordUser): NormalizedDiscordUser {
     const { id, username, global_name, avatar, email } = rawUser;
 
     return {

package/src/{session-manager.js → session-manager.ts}

@@ -1,13 +1,26 @@
 import { randomUUID } from 'node:crypto';
 
+interface SessionData {
+  user: unknown;
+  tokens: unknown;
+  expiresAt: number;
+}
+
+export interface SessionResult {
+  sessionId: string;
+  user: unknown;
+  expiresAt: number;
+}
+
 export default class SessionManager {
-  sessions = new Map();
+  sessions = new Map<string, SessionData>();
+  duration: number;
 
-  constructor(duration) {
+  constructor(duration: number) {
     this.duration = duration;
   }
 
-  create(user, tokens) {
+  create(user: unknown, tokens: unknown): SessionResult {
     const sessionId = randomUUID();
     const expiresAt = Date.now() + (this.duration * 1000);
 
@@ -16,15 +29,15 @@ export default class SessionManager {
     return { sessionId, user, expiresAt };
   }
 
-  get(sessionId) {
+  get(sessionId: string): SessionData | null {
     return this.sessions.get(sessionId) || null;
   }
 
-  destroy(sessionId) {
+  destroy(sessionId: string): void {
     this.sessions.delete(sessionId);
   }
 
-  validate(sessionId) {
+  validate(sessionId: string): unknown {
     const session = this.get(sessionId);
     if (!session) return null;
 

package/src/ticket-store.ts

@@ -0,0 +1,123 @@
+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;
+
+interface TicketRecord {
+  sessionId: string;
+  expiresAt: number;
+  createdAt: number;
+}
+
+export interface RedeemedTicket {
+  sessionId: string;
+  expiresAt: number;
+}
+
+/**
+ * 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<string, TicketRecord>();
+  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: string, expiresAt: number): string {
+    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: string): RedeemedTicket | null {
+    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/src/token-manager.ts

@@ -0,0 +1,35 @@
+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) {
+    this.flow = flow;
+  }
+
+  async getTokens(code: string): Promise<TokenData> {
+    const tokens = await this.flow.exchangeCode(code) as TokenData;
+    tokens.expiresAt = Date.now() + (tokens.expiresIn * 1000);
+    return tokens;
+  }
+
+  async refresh(refreshToken: string): Promise<TokenData> {
+    const tokens = await this.flow.refreshAccessToken(refreshToken) as TokenData;
+    tokens.expiresAt = Date.now() + (tokens.expiresIn * 1000);
+    return tokens;
+  }
+
+  async revoke(accessToken: string): Promise<void> {
+    return this.flow.revokeToken(accessToken);
+  }
+
+  isExpired(tokenData: { expiresAt?: number } | null | undefined): boolean {
+    if (!tokenData?.expiresAt) return true;
+    return Date.now() >= tokenData.expiresAt;
+  }
+}

package/src/types/node.d.ts

@@ -0,0 +1,19 @@
+declare module 'node:crypto' {
+  export function randomUUID(): string;
+
+  /**
+   * Structural stand-ins: this repo declares its own node shims rather than
+   * depending on `@types/node`, so only the surface actually used is typed.
+   */
+  interface BinaryLike {
+    toString(encoding: string): string;
+  }
+
+  interface Hash {
+    update(data: string): Hash;
+    digest(encoding: string): string;
+  }
+
+  export function randomBytes(size: number): BinaryLike;
+  export function createHash(algorithm: string): Hash;
+}

package/src/types/stonyx-events.d.ts

@@ -0,0 +1,4 @@
+declare module '@stonyx/events' {
+  export function setup(events: string[]): void;
+  export function emit(event: string, ...args: unknown[]): Promise<void>;
+}

package/src/types/stonyx-rest-server.d.ts

@@ -0,0 +1,11 @@
+declare module '@stonyx/rest-server' {
+  export class Request {
+    constructor();
+  }
+
+  export default class RestServer {
+    static instance: RestServer;
+    static close(): void;
+    mountRoute(RequestClass: unknown, options: { name: string; options?: unknown }): void;
+  }
+}

package/src/types/stonyx.d.ts

@@ -0,0 +1,38 @@
+declare module 'stonyx/config' {
+  interface OAuthConfig {
+    providers: Record<string, { module?: string; [key: string]: unknown }>;
+    sessionDuration: number;
+    frontendCallbackUrl?: string;
+    logColor?: string;
+    logMethod?: string;
+  }
+  interface Config {
+    oauth: OAuthConfig;
+    rootPath: string;
+    [key: string]: unknown;
+  }
+  const config: Config;
+  export default config;
+}
+
+declare module 'stonyx/log' {
+  interface Log {
+    oauth(message: string): void;
+    error(message: string): void;
+    defineType(type: string, setting: string, options?: Record<string, unknown> | null): void;
+    [key: string]: unknown;
+  }
+  const log: Log;
+  export default log;
+}
+
+declare module 'stonyx' {
+  export function waitForModule(name: string): Promise<void>;
+}
+
+declare module 'stonyx/test-helpers' {
+  export function setupIntegrationTests(hooks: {
+    before(fn: () => void | Promise<void>): void;
+    after(fn: () => void | Promise<void>): void;
+  }): void;
+}