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

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/state-store.ts

@@ -0,0 +1,179 @@
+import { createHash, randomBytes, randomUUID } from 'node:crypto';
+import { BINDING_VALUE_BYTES, STATE_TTL_MS } from './constants.js';
+
+/**
+ * Server-side record for an OAuth flow that is in progress.
+ *
+ * Deliberately 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 {
+  provider: string;
+  bindingHash: string;
+  createdAt: number;
+}
+
+/**
+ * The five reasons a callback is rejected, as fixed strings.
+ *
+ * Named rather than inlined so that collapsing two of them into one is a
+ * visible edit: distinguishing them in the server log is the whole point of
+ * logging a reason, and an operator telling an expired state from a
+ * cross-provider replay depends on them staying distinct.
+ */
+export const STATE_REJECTION = {
+  unknownState: 'Invalid or missing state token',
+  expired: 'State token has expired',
+  wrongProvider: 'State token was not issued for this provider',
+  missingBinding: 'Missing state binding value',
+  unboundClient: 'State token is not bound to this client',
+} as const;
+
+/**
+ * A callback rejected by `StateStore.consume`.
+ *
+ * Carries two things the route layer cannot otherwise recover: that the
+ * rejection came from state validation rather than from anything downstream of
+ * it, and whether a pending record was actually consumed.
+ */
+export class StateRejection extends Error {
+  /** True when this attempt recognised a pending record and burned it. */
+  consumed: boolean;
+
+  constructor(reason: string, consumed: boolean) {
+    super(reason);
+    this.name = 'StateRejection';
+    this.consumed = consumed;
+  }
+}
+
+export interface IssuedState {
+  /** Sent to the provider as the OAuth2 `state` parameter. */
+  stateToken: string;
+  /** Held by the client that started the flow (a cookie), never by the provider. */
+  bindingValue: string;
+}
+
+/**
+ * Issues and validates OAuth2 `state` tokens bound to the client that started
+ * the flow (#36).
+ *
+ * Presence-plus-age on a process-global map is replay-window limiting, not the
+ * CSRF binding `state` exists to provide (RFC 6749 section 10.12): any state
+ * issued to any visitor validated for any callback, so an attacker could
+ * harvest their own state and code and deliver them to a victim, logging the
+ * victim in as the attacker. A state is now only accepted when the caller also
+ * presents the matching client-held binding value, and only at the provider it
+ * was issued for.
+ */
+export default class StateStore {
+  pending = new Map<string, PendingState>();
+  ttl: number;
+
+  constructor(ttl: number = STATE_TTL_MS) {
+    this.ttl = ttl;
+  }
+
+  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;
+  }
+
+  issue(provider: string): IssuedState {
+    const stateToken = randomUUID();
+    const bindingValue = randomBytes(BINDING_VALUE_BYTES).toString('base64url');
+
+    this.pending.set(stateToken, {
+      provider,
+      bindingHash: StateStore.hash(bindingValue),
+      createdAt: Date.now(),
+    });
+
+    return { stateToken, bindingValue };
+  }
+
+  /**
+   * Validates and consumes a pending state. Throws on every rejection path.
+   *
+   * 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. `consumed` on the rejection says whether this
+   * call actually burned a record, so a caller can distinguish "nothing of the
+   * victim's was touched" from "one attempt was spent".
+   *
+   * `bindingValues` is every value the client presented under the binding
+   * cookie's name, not just the first — see `anyCandidateMatches`.
+   */
+  consume(stateToken: string | undefined, provider: string, bindingValues: readonly string[]): void {
+    if (!stateToken) throw new StateRejection(STATE_REJECTION.unknownState, false);
+
+    const record = this.pending.get(stateToken);
+    if (!record) throw new StateRejection(STATE_REJECTION.unknownState, false);
+    this.pending.delete(stateToken);
+
+    if (Date.now() - record.createdAt > this.ttl) throw new StateRejection(STATE_REJECTION.expired, true);
+    if (record.provider !== provider) throw new StateRejection(STATE_REJECTION.wrongProvider, true);
+
+    const candidates = bindingValues.filter(value => value.length > 0);
+    if (candidates.length === 0) throw new StateRejection(STATE_REJECTION.missingBinding, true);
+
+    if (!this.anyCandidateMatches(candidates, record)) {
+      throw new StateRejection(STATE_REJECTION.unboundClient, true);
+    }
+  }
+
+  /**
+   * Whether *any* presented value is the binding value for this record.
+   *
+   * Every candidate is tried, and the callback is accepted if one matches.
+   * Returning on the first value carrying the cookie name instead made 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. The
+   * record is consumed on recognition, so a state still gets exactly one
+   * attempt however many candidates were presented, and the candidate count is
+   * bounded by Node's header size limit rather than by a cap here — a cap
+   * truncates the list from the wrong end and reinstates the denial this method
+   * exists to close. See `constants.ts`.
+   *
+   * The loop does not short-circuit, so the work is a function of how many
+   * values were presented and not of which one matched.
+   */
+  anyCandidateMatches(candidates: readonly string[], record: PendingState): boolean {
+    return candidates.reduce(
+      (matched, candidate) => StateStore.digestsMatch(StateStore.hash(candidate), record.bindingHash) || matched,
+      false,
+    );
+  }
+}

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,10 @@
+declare module 'node:crypto' {
+  interface Hash {
+    update(data: string): Hash;
+    digest(encoding: 'hex'): string;
+  }
+
+  export function randomUUID(): string;
+  export function randomBytes(size: number): { toString(encoding: 'base64url' | 'hex'): string };
+  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;
+}

package/.github/workflows/ci.yml

@@ -1,16 +0,0 @@
-name: CI
-
-on:
-  pull_request:
-    branches: [dev, main]
-
-concurrency:
-  group: ci-${{ github.head_ref || github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  contents: read
-
-jobs:
-  test:
-    uses: abofs/stonyx-workflows/.github/workflows/ci.yml@main

package/.github/workflows/publish.yml

@@ -1,51 +0,0 @@
-name: Publish to NPM
-
-on:
-  repository_dispatch:
-    types: [cascade-publish]
-  workflow_dispatch:
-    inputs:
-      version-type:
-        description: 'Version type'
-        required: true
-        type: choice
-        options:
-          - patch
-          - minor
-          - major
-      custom-version:
-        description: 'Custom version (optional, overrides version-type)'
-        required: false
-        type: string
-  pull_request:
-    types: [opened, synchronize, reopened]
-    branches: [main]
-  push:
-    branches: [main]
-
-concurrency:
-  group: ${{ github.event_name == 'repository_dispatch' && 'cascade-update' || format('publish-{0}', github.ref) }}
-  cancel-in-progress: false
-
-permissions:
-  contents: write
-  id-token: write
-  pull-requests: write
-
-jobs:
-  publish:
-    if: "!contains(github.event.head_commit.message, '[skip ci]')"
-    uses: abofs/stonyx-workflows/.github/workflows/npm-publish.yml@main
-    with:
-      version-type: ${{ github.event.inputs.version-type }}
-      custom-version: ${{ github.event.inputs.custom-version }}
-      cascade-source: ${{ github.event.client_payload.source_package || '' }}
-    secrets: inherit
-
-  cascade:
-    needs: publish
-    uses: abofs/stonyx-workflows/.github/workflows/cascade.yml@main
-    with:
-      package-name: ${{ needs.publish.outputs.package-name }}
-      published-version: ${{ needs.publish.outputs.published-version }}
-    secrets: inherit

package/src/auth-request.js

@@ -1,74 +0,0 @@
-import { Request } from '@stonyx/rest-server';
-
-export default class AuthRequest extends Request {
-  constructor(oauth) {
-    super();
-    this.oauth = oauth;
-  }
-
-  handlers = {
-    get: {
-      '/': ({ headers }) => {
-        const sessionId = headers['session-id'];
-        if (!sessionId) return 401;
-
-        const user = this.oauth.getSession(sessionId);
-        if (!user) return 401;
-
-        return user;
-      },
-
-      '/login/:provider': (req, state) => {
-        const { provider: providerName } = req.params;
-
-        try {
-          const url = this.oauth.getAuthorizationUrl(providerName);
-          state.redirect = url;
-        } catch {
-          return 404;
-        }
-      },
-
-      '/callback/:provider': async (req, state) => {
-        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);
-
-          if (this.oauth.frontendCallbackUrl) {
-            const params = new URLSearchParams({
-              sessionId: session.sessionId,
-              expiresAt: session.expiresAt,
-            });
-            state.redirect = `${this.oauth.frontendCallbackUrl}?${params}`;
-            return;
-          }
-
-          return session;
-        } catch {
-          if (this.oauth.frontendCallbackUrl) {
-            state.redirect = `${this.oauth.frontendCallbackUrl}?error=auth_failed`;
-            return;
-          }
-          return 500;
-        }
-      },
-
-      '/logout': ({ headers }) => {
-        const sessionId = headers['session-id'];
-        if (sessionId) this.oauth.logout(sessionId);
-      },
-    }
-  };
-}

package/src/main.js

@@ -1,83 +0,0 @@
-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 AuthRequest from './auth-request.js';
-
-setup(['authenticate']);
-
-export default class OAuth {
-  providers = new Map();
-  pendingStates = new Map();
-
-  constructor() {
-    if (OAuth.instance) return OAuth.instance;
-    OAuth.instance = this;
-  }
-
-  async init() {
-    const { providers, sessionDuration, frontendCallbackUrl } = config.oauth;
-    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 = 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) {
-    const provider = this.providers.get(name);
-    if (!provider) throw new Error(`OAuth provider "${name}" is not configured`);
-    return provider;
-  }
-
-  getAuthorizationUrl(providerName) {
-    const { flow } = this.getProvider(providerName);
-    const stateToken = crypto.randomUUID();
-    this.pendingStates.set(stateToken, Date.now());
-    return flow.buildAuthorizationUrl(stateToken);
-  }
-
-  async handleCallback(providerName, code, stateToken) {
-    if (!stateToken || !this.pendingStates.has(stateToken)) {
-      throw new Error('Invalid or missing state token');
-    }
-
-    const stateCreatedAt = this.pendingStates.get(stateToken);
-    this.pendingStates.delete(stateToken);
-
-    const TEN_MINUTES = 10 * 60 * 1000;
-    if (Date.now() - stateCreatedAt > TEN_MINUTES) {
-      throw new Error('State token has expired');
-    }
-
-    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);
-  }
-
-  getSession(sessionId) {
-    return this.sessionManager.validate(sessionId);
-  }
-
-  logout(sessionId) {
-    this.sessionManager.destroy(sessionId);
-  }
-}

package/src/token-manager.js

@@ -1,26 +0,0 @@
-export default class TokenManager {
-  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/test/config/environment.js

@@ -1,18 +0,0 @@
-export default {
-  restServer: {
-    dir: './test/sample/requests',
-  },
-  oauth: {
-    providers: {
-      mock: {
-        clientId: 'test-client-id',
-        clientSecret: 'test-client-secret',
-        redirectUri: 'http://localhost:2666/auth/callback/mock',
-        scopes: ['identify'],
-        module: './test/sample/providers/mock.js',
-      }
-    },
-    sessionDuration: 3600,
-    frontendCallbackUrl: 'http://localhost:4200/auth/callback',
-  }
-};