@stonyx/oauth 0.1.1-beta.2 → 0.1.1-beta.200

package/src/auth-request.ts

@@ -0,0 +1,348 @@
+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;
+  /**
+   * Optional: every call site guards on it. `@stonyx/rest-server` hands the
+   * express response through untyped, and a test double need not implement the
+   * whole surface.
+   */
+  setHeader?(name: string, value: string): 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`.
+       *
+       * `Cache-Control: no-store` because the `200` body is the session id —
+       * the bearer credential itself. A `POST` response is not cacheable
+       * without explicit freshness, so this is defence in depth rather than a
+       * live defect: it is there so that no intermediary, service worker or
+       * future `GET` variant of this route can retain the credential. Set
+       * through `req.res`, the same reach-through the binding-cookie helpers
+       * use, because `@stonyx/rest-server` has no supported way for a handler
+       * to set a response header (`abofs/stonyx-rest-server#45`).
+       */
+      '/session': (req: RouteRequest) => {
+        const { body, res } = req;
+        if (typeof res?.setHeader === 'function') res.setHeader('Cache-Control', 'no-store');
+
+        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));
+  }
+}

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
   }
 }