@stonyx/oauth 0.1.1-beta.17 → 0.1.1-beta.170

package/dist/oauth-flow.d.ts

@@ -0,0 +1,30 @@
+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 {
+    clientId: string;
+    clientSecret: string;
+    redirectUri: string;
+    scopes: string[];
+    authorizationUrl: string;
+    tokenUrl: string;
+    userInfoUrl: string;
+    constructor({ clientId, clientSecret, redirectUri, scopes, authorizationUrl, tokenUrl, userInfoUrl }: OAuthConfig);
+    buildAuthorizationUrl(stateToken: string): string;
+    exchangeCode(code: string): Promise<TokenResult>;
+    refreshAccessToken(refreshToken: string): Promise<TokenResult>;
+    fetchUserInfo(accessToken: string): Promise<unknown>;
+    normalizeUser(rawUser: unknown): unknown;
+    revokeToken(_accessToken: string): Promise<void>;
+}

package/dist/oauth-flow.js

@@ -0,0 +1,83 @@
+export default class OAuthFlow {
+    clientId;
+    clientSecret;
+    redirectUri;
+    scopes;
+    authorizationUrl;
+    tokenUrl;
+    userInfoUrl;
+    constructor({ clientId, clientSecret, redirectUri, scopes, authorizationUrl, tokenUrl, userInfoUrl }) {
+        this.clientId = clientId;
+        this.clientSecret = clientSecret;
+        this.redirectUri = redirectUri;
+        this.scopes = scopes || [];
+        this.authorizationUrl = authorizationUrl;
+        this.tokenUrl = tokenUrl;
+        this.userInfoUrl = userInfoUrl;
+    }
+    buildAuthorizationUrl(stateToken) {
+        const params = new URLSearchParams({
+            client_id: this.clientId,
+            redirect_uri: this.redirectUri,
+            response_type: 'code',
+            scope: this.scopes.join(' '),
+            state: stateToken,
+        });
+        return `${this.authorizationUrl}?${params.toString()}`;
+    }
+    async exchangeCode(code) {
+        const response = await fetch(this.tokenUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                client_id: this.clientId,
+                client_secret: this.clientSecret,
+                grant_type: 'authorization_code',
+                code,
+                redirect_uri: this.redirectUri,
+            }),
+        });
+        if (!response.ok)
+            throw new Error(`Token exchange failed: ${response.status}`);
+        const data = await response.json();
+        return {
+            accessToken: data.access_token,
+            refreshToken: data.refresh_token || null,
+            expiresIn: data.expires_in,
+        };
+    }
+    async refreshAccessToken(refreshToken) {
+        const response = await fetch(this.tokenUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                client_id: this.clientId,
+                client_secret: this.clientSecret,
+                grant_type: 'refresh_token',
+                refresh_token: refreshToken,
+            }),
+        });
+        if (!response.ok)
+            throw new Error(`Token refresh failed: ${response.status}`);
+        const data = await response.json();
+        return {
+            accessToken: data.access_token,
+            refreshToken: data.refresh_token || refreshToken,
+            expiresIn: data.expires_in,
+        };
+    }
+    async fetchUserInfo(accessToken) {
+        const response = await fetch(this.userInfoUrl, {
+            headers: { Authorization: `Bearer ${accessToken}` },
+        });
+        if (!response.ok)
+            throw new Error(`User info fetch failed: ${response.status}`);
+        return response.json();
+    }
+    normalizeUser(rawUser) {
+        return { raw: rawUser };
+    }
+    async revokeToken(_accessToken) {
+        // Optional — providers override if supported
+    }
+}

package/dist/providers/discord.d.ts

@@ -0,0 +1,30 @@
+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: DiscordProviderConfig);
+    exchangeCode(code: string): Promise<TokenResult>;
+    normalizeUser(rawUser: DiscordUser): NormalizedDiscordUser;
+}
+export {};

package/dist/providers/discord.js

@@ -0,0 +1,43 @@
+import OAuthFlow from '../oauth-flow.js';
+export default class DiscordProvider extends OAuthFlow {
+    constructor(config) {
+        super({
+            ...config,
+            authorizationUrl: 'https://discord.com/oauth2/authorize',
+            tokenUrl: 'https://discord.com/api/oauth2/token',
+            userInfoUrl: 'https://discord.com/api/users/@me',
+        });
+    }
+    async exchangeCode(code) {
+        const response = await fetch(this.tokenUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: new URLSearchParams({
+                client_id: this.clientId,
+                client_secret: this.clientSecret,
+                grant_type: 'authorization_code',
+                code,
+                redirect_uri: this.redirectUri,
+            }),
+        });
+        if (!response.ok)
+            throw new Error(`Token exchange failed: ${response.status}`);
+        const data = await response.json();
+        return {
+            accessToken: data.access_token,
+            refreshToken: data.refresh_token || null,
+            expiresIn: data.expires_in,
+        };
+    }
+    normalizeUser(rawUser) {
+        const { id, username, global_name, avatar, email } = rawUser;
+        return {
+            id,
+            username,
+            displayName: global_name || username,
+            avatar: avatar ? `https://cdn.discordapp.com/avatars/${id}/${avatar}.png` : null,
+            email: email || null,
+            raw: rawUser,
+        };
+    }
+}

package/dist/session-manager.d.ts

@@ -0,0 +1,20 @@
+interface SessionData {
+    user: unknown;
+    tokens: unknown;
+    expiresAt: number;
+}
+export interface SessionResult {
+    sessionId: string;
+    user: unknown;
+    expiresAt: number;
+}
+export default class SessionManager {
+    sessions: Map<string, SessionData>;
+    duration: number;
+    constructor(duration: number);
+    create(user: unknown, tokens: unknown): SessionResult;
+    get(sessionId: string): SessionData | null;
+    destroy(sessionId: string): void;
+    validate(sessionId: string): unknown;
+}
+export {};

package/dist/session-manager.js

@@ -0,0 +1,30 @@
+import { randomUUID } from 'node:crypto';
+export default class SessionManager {
+    sessions = new Map();
+    duration;
+    constructor(duration) {
+        this.duration = duration;
+    }
+    create(user, tokens) {
+        const sessionId = randomUUID();
+        const expiresAt = Date.now() + (this.duration * 1000);
+        this.sessions.set(sessionId, { user, tokens, expiresAt });
+        return { sessionId, user, expiresAt };
+    }
+    get(sessionId) {
+        return this.sessions.get(sessionId) || null;
+    }
+    destroy(sessionId) {
+        this.sessions.delete(sessionId);
+    }
+    validate(sessionId) {
+        const session = this.get(sessionId);
+        if (!session)
+            return null;
+        if (Date.now() >= session.expiresAt) {
+            this.destroy(sessionId);
+            return null;
+        }
+        return session.user;
+    }
+}

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,40 +4,76 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.1.1-beta.17",
+  "version": "0.1.1-beta.170",
   "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",
   "contributors": [
     "Stone Costa <stone.costa@synamicd.com>"
   ],
+  "files": [
+    "dist",
+    "src",
+    "config",
+    "README.md"
+  ],
   "publishConfig": {
     "access": "public",
     "provenance": true
   },
   "dependencies": {
-    "stonyx": "0.2.3-beta.6",
-    "@stonyx/events": "0.1.1-beta.7"
+    "@stonyx/events": "0.1.1-beta.54",
+    "stonyx": "0.2.3-beta.83"
   },
   "peerDependencies": {
     "@stonyx/rest-server": ">=0.2.1-beta.11"
   },
   "devDependencies": {
-    "@stonyx/rest-server": "0.2.1-beta.19",
-    "@stonyx/utils": "0.2.3-beta.5",
+    "@stonyx/rest-server": "0.2.1-beta.101",
+    "@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,271 @@
+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 }>;
+  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>;
+  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) {
+            const params = new URLSearchParams({
+              sessionId: session.sessionId,
+              expiresAt: String(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 }: RouteRequest) => {
+        const sessionId = headers['session-id'];
+        if (sessionId) this.oauth.logout(sessionId);
+      },
+    }
+  };
+
+  /**
+   * 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));
+  }
+}