offrouter-core 0.2.0 → 0.2.2

package/src/auth/oauth-pkce.ts

@@ -1,571 +0,0 @@
-/**
- * OAuth PKCE flow for OffRouter.
- *
- * Supports Anthropic and OpenAI/Codex only (opt-in, bring-your-own-client-id).
- * Gemini/xAI/Z.ai are API-key only and do NOT implement OAuth.
- *
- * Never auto-triggers OAuth. Requires explicit user configuration.
- * Tokens are stored in the SecretStore (keychain or file fallback).
- */
-import { randomBytes } from "node:crypto";
-import type { SecretStore } from "../secrets.js";
-import { Redacted } from "./credential-chain.js";
-import { setOAuthTokens } from "./keychain.js";
-import { startCallbackServer } from "./oauth-server.js";
-
-// ---------------------------------------------------------------------------
-// PKCE code generation
-// ---------------------------------------------------------------------------
-
-const VERIFIER_CHARS =
-  "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~";
-
-/**
- * Generate a random code verifier for PKCE (RFC 7636).
- * Length is between 43 and 128 characters.
- */
-export function generateCodeVerifier(): string {
-  const length = 64 + (randomBytes(1)[0]! % 32); // 64-95 chars
-  const bytes = randomBytes(length);
-  let verifier = "";
-  for (let i = 0; i < length; i++) {
-    verifier += VERIFIER_CHARS[bytes[i]! % VERIFIER_CHARS.length];
-  }
-  return verifier;
-}
-
-/**
- * Generate a S256 code challenge from a verifier (RFC 7636).
- * Uses Web Crypto API (available in Node >= 22, Workers, browsers).
- */
-export async function generateCodeChallenge(
-  verifier: string,
-): Promise<string> {
-  const encoder = new TextEncoder();
-  const data = encoder.encode(verifier);
-  const digest = await crypto.subtle.digest("SHA-256", data);
-  const base64 = btoa(
-    String.fromCharCode(...new Uint8Array(digest)),
-  );
-  return base64
-    .replace(/\+/g, "-")
-    .replace(/\//g, "_")
-    .replace(/=+$/, "");
-}
-
-// ---------------------------------------------------------------------------
-// OAuth provider configs
-// ---------------------------------------------------------------------------
-
-export interface OAuthProviderConfig {
-  authorizeUrl: string;
-  tokenUrl: string;
-  scopes: string[];
-  defaultClientId?: string;
-  clientIdEnvVar?: string;
-}
-
-/**
- * OAuth PKCE configurations for supported providers.
- * Only Anthropic and OpenAI/Codex are supported.
- * Gemini/xAI/Z.ai are API-key only.
- */
-export const PKCE_CONFIGS: Record<string, OAuthProviderConfig> = {
-  anthropic: {
-    authorizeUrl: "https://console.anthropic.com/oauth/authorize",
-    tokenUrl: "https://console.anthropic.com/oauth/token",
-    scopes: ["api", "offline_access"],
-    clientIdEnvVar: "OFFROUTER_ANTHROPIC_CLIENT_ID",
-    // No default client id; users must bring their own.
-  },
-  openai: {
-    authorizeUrl: "https://auth.openai.com/oauth/authorize",
-    tokenUrl: "https://auth.openai.com/oauth/token",
-    scopes: ["offline_access"],
-    clientIdEnvVar: "OFFROUTER_OPENAI_CLIENT_ID",
-    // Note: reuses Codex client id; documented as fragile.
-  },
-};
-
-/**
- * Returns true if the provider supports OAuth (opt-in).
- */
-export function isOAuthProvider(providerId: string): boolean {
-  return providerId in PKCE_CONFIGS;
-}
-
-// ---------------------------------------------------------------------------
-// OAuth session store (in-memory, out-of-band — NOT embedded in state)
-// ---------------------------------------------------------------------------
-
-/** Time-to-live for a stored OAuth session (10 minutes). */
-const SESSION_TTL_MS = 10 * 60 * 1000;
-
-/**
- * In-memory session data associated with a PKCE nonce.
- * Never serialised into the caller-visible state string.
- */
-export interface OAuthSession {
-  codeVerifier: string;
-  redirectUri: string;
-  createdAt: number;
-}
-
-/** Module-level session store: nonce → session. */
-const sessions = new Map<string, OAuthSession>();
-
-/**
- * Retrieve and delete a session by nonce (one-shot consume).
- * Returns null if the nonce is unknown, already consumed, or expired.
- */
-export function consumeOAuthSession(nonce: string): OAuthSession | null {
-  const session = sessions.get(nonce);
-  if (!session) return null;
-  sessions.delete(nonce);
-  if (Date.now() - session.createdAt > SESSION_TTL_MS) {
-    return null; // expired
-  }
-  return session;
-}
-
-/**
- * Cancel / discard a session without consuming it.
- */
-export function cancelOAuthSession(nonce: string): void {
-  sessions.delete(nonce);
-}
-
-// ---------------------------------------------------------------------------
-// OAuth flow state
-// ---------------------------------------------------------------------------
-
-export interface OAuthFlowState {
-  provider: string;
-  nonce: string;
-}
-
-export interface OAuthFlowResult {
-  authorizeUrl: string;
-  state: string;
-}
-
-export interface OAuthTokenResponse {
-  accessToken: Redacted<string>;
-  refreshToken?: Redacted<string>;
-  expiresIn?: number;
-  scope?: string;
-}
-
-export interface OAuthStartOptions {
-  redirectUri: string;
-  /** Override client ID (default from env or PKCE_CONFIGS). */
-  clientId?: string;
-}
-
-export interface OAuthTokenOptions {
-  store: SecretStore;
-  fetch?: typeof globalThis.fetch;
-}
-
-/**
- * Create an OAuth state string that encodes provider metadata.
- * Used to validate the callback matches the initiated flow.
- */
-export function createOAuthState(provider: string): string {
-  const nonce = randomBytes(16).toString("hex");
-  return JSON.stringify({ provider, nonce });
-}
-
-/**
- * Start an OAuth PKCE flow for the given provider.
- * Returns the authorization URL and state for redirect.
- * Never auto-triggers; requires explicit user configuration.
- */
-export async function startOAuthFlow(
-  provider: string,
-  options: OAuthStartOptions,
-): Promise<OAuthFlowResult> {
-  const config = PKCE_CONFIGS[provider];
-  if (!config) {
-    throw new Error(
-      `OAuth not supported for provider: ${provider}. ` +
-        `OAuth is only available for anthropic and openai providers.`,
-    );
-  }
-
-  const clientId =
-    options.clientId ??
-    (config.clientIdEnvVar ? process.env[config.clientIdEnvVar] : undefined);
-
-  if (!clientId) {
-    throw new Error(
-      `Client ID required for ${provider} OAuth. ` +
-        `Set the ${config.clientIdEnvVar ?? "client id"} environment variable ` +
-        `or pass it explicitly.`,
-    );
-  }
-
-  const codeVerifier = generateCodeVerifier();
-  const codeChallenge = await generateCodeChallenge(codeVerifier);
-  const state = createOAuthState(provider);
-
-  const params = new URLSearchParams({
-    response_type: "code",
-    client_id: clientId,
-    redirect_uri: options.redirectUri,
-    code_challenge: codeChallenge,
-    code_challenge_method: "S256",
-    state,
-    scope: config.scopes.join(" "),
-  });
-
-  const authorizeUrl = `${config.authorizeUrl}?${params.toString()}`;
-
-  // Store the verifier OOB so it never appears in the caller-visible state
-  const parsed = JSON.parse(state) as { provider: string; nonce: string };
-  sessions.set(parsed.nonce, {
-    codeVerifier,
-    redirectUri: options.redirectUri,
-    createdAt: Date.now(),
-  });
-
-  return {
-    authorizeUrl,
-    state, // clean — provider + nonce only, no secrets
-  };
-}
-
-/**
- * Exchange an authorization code for tokens.
- * Called after the user completes the OAuth flow in their browser.
- */
-export async function exchangeCodeForTokens(
-  provider: string,
-  code: string,
-  statePayload: string,
-  options: OAuthTokenOptions,
-): Promise<OAuthTokenResponse> {
-  const config = PKCE_CONFIGS[provider];
-  if (!config) {
-    throw new Error(`OAuth not supported for provider: ${provider}`);
-  }
-
-  let stateData: { provider?: string; nonce?: string };
-  try {
-    stateData = JSON.parse(statePayload) as typeof stateData;
-  } catch {
-    throw new Error("Invalid OAuth state payload");
-  }
-
-  if (!stateData.nonce) {
-    throw new Error("Missing nonce in OAuth state");
-  }
-
-  const session = consumeOAuthSession(stateData.nonce);
-  if (!session) {
-    throw new Error(
-      "OAuth session expired, already consumed, or not found. Please restart the OAuth flow.",
-    );
-  }
-
-  if (!session.codeVerifier) {
-    throw new Error("Missing code verifier in OAuth session");
-  }
-
-  const clientId =
-    config.clientIdEnvVar
-      ? (process.env[config.clientIdEnvVar] ?? "")
-      : "";
-
-  const tokenParams = new URLSearchParams({
-    grant_type: "authorization_code",
-    code,
-    redirect_uri: session.redirectUri ?? "http://127.0.0.1:8765/callback",
-    client_id: clientId,
-    code_verifier: session.codeVerifier,
-  });
-
-  const fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
-  const response = await fetchImpl(config.tokenUrl, {
-    method: "POST",
-    headers: {
-      "content-type": "application/x-www-form-urlencoded",
-    },
-    body: tokenParams.toString(),
-  });
-
-  if (!response.ok) {
-    const body = await response.text().catch(() => "");
-    throw new Error(
-      `Token exchange failed for ${provider}: HTTP ${response.status} ${body}`,
-    );
-  }
-
-  const json = (await response.json()) as {
-    access_token?: string;
-    refresh_token?: string;
-    expires_in?: number;
-    scope?: string;
-  };
-
-  if (!json.access_token) {
-    throw new Error(
-      `Token exchange for ${provider} returned no access_token`,
-    );
-  }
-
-  // Store tokens in secret store (structured)
-  if (options.store) {
-    const obtainedAt = Date.now();
-    await setOAuthTokens(
-      provider,
-      {
-        accessToken: json.access_token,
-        refreshToken: json.refresh_token,
-        expiresAt: json.expires_in
-          ? obtainedAt + json.expires_in * 1000
-          : undefined,
-        scope: json.scope,
-        obtainedAt,
-      },
-      options.store,
-    );
-  }
-
-  return {
-    accessToken: new Redacted(json.access_token),
-    refreshToken: json.refresh_token
-      ? new Redacted(json.refresh_token)
-      : undefined,
-    expiresIn: json.expires_in,
-    scope: json.scope,
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Login orchestration (callback server + browser + token exchange)
-// ---------------------------------------------------------------------------
-
-/** Default loopback ports for supported providers. */
-const DEFAULT_CALLBACK_PORTS: Record<string, number> = {
-  anthropic: 1456,
-  openai: 1455,
-};
-
-/**
- * Return the default callback port for a provider, or 0 (OS-assigned).
- */
-export function defaultCallbackPort(provider: string): number {
-  return DEFAULT_CALLBACK_PORTS[provider] ?? 0;
-}
-
-/**
- * Resolve the client id for a provider from process env (or a provided env
- * override). Returns undefined if the env var is not set.
- */
-export function resolveClientId(
-  provider: string,
-  env: NodeJS.ProcessEnv = process.env,
-): string | undefined {
-  const config = PKCE_CONFIGS[provider];
-  if (!config?.clientIdEnvVar) return undefined;
-  return env[config.clientIdEnvVar] ?? undefined;
-}
-
-export interface RunOAuthLoginOptions {
-  provider: string;
-  store: SecretStore;
-  /** Override client id (else resolved from env / PKCE_CONFIGS). */
-  clientId?: string;
-  /** Loopback port (defaults to provider default or 0). */
-  port?: number;
-  /** Wait timeout in ms (default 5 min). */
-  timeoutMs?: number;
-  /** Called with the authorize URL once built (test/display). */
-  onAuthorizeUrl?: (url: string) => void;
-  /** Best-effort browser open (non-throwing). */
-  openBrowser?: (url: string) => Promise<boolean> | boolean;
-  /** Injectable fetch (tests). */
-  fetch?: typeof globalThis.fetch;
-  /** Optional abort signal. */
-  signal?: AbortSignal;
-}
-
-export interface RunOAuthLoginResult {
-  provider: string;
-  redirectUri: string;
-  expiresAt?: number;
-  scope?: string;
-}
-
-/**
- * Run the full OAuth PKCE login flow:
- * 1. Start a local callback server on 127.0.0.1
- * 2. Build the authorize URL with PKCE challenge + state
- * 3. Notify caller (onAuthorizeUrl) and attempt browser open
- * 4. Wait for the provider callback (code + state)
- * 5. Exchange code for tokens
- * 6. Store structured tokens in the secret store
- * 7. Clean up the server
- */
-export async function runOAuthLogin(
-  opts: RunOAuthLoginOptions,
-): Promise<RunOAuthLoginResult> {
-  const config = PKCE_CONFIGS[opts.provider];
-  if (!config) {
-    throw new Error(
-      `OAuth not supported for provider: ${opts.provider}. ` +
-        `OAuth is only available for anthropic and openai providers.`,
-    );
-  }
-
-  const clientId =
-    opts.clientId ?? resolveClientId(opts.provider) ?? undefined;
-  if (!clientId) {
-    const envHint =
-      config.clientIdEnvVar
-        ? `Set the ${config.clientIdEnvVar} environment variable or pass it explicitly.`
-        : "A client id is required for this provider.";
-    throw new Error(
-      `Client ID required for ${opts.provider} OAuth. ${envHint}`,
-    );
-  }
-
-  // 1. Start callback server
-  const port = opts.port ?? defaultCallbackPort(opts.provider);
-  const server = await startCallbackServer(port);
-
-  try {
-    const redirectUri = server.url;
-
-    // 2. Build the authorize URL with PKCE
-    const flow = await startOAuthFlow(opts.provider, {
-      redirectUri,
-      clientId,
-    });
-
-    // 3. Notify and attempt to open browser
-    opts.onAuthorizeUrl?.(flow.authorizeUrl);
-    if (opts.openBrowser) {
-      try {
-        await opts.openBrowser(flow.authorizeUrl);
-      } catch {
-        // Best-effort only.
-      }
-    }
-
-    // 4. Wait for callback (validates expected state)
-    const { code } = await server.waitForCode({
-      expectedState: flow.state,
-      timeoutMs: opts.timeoutMs,
-      signal: opts.signal,
-    });
-
-    // 5. Exchange code for tokens (also stores them)
-    const tokens = await exchangeCodeForTokens(opts.provider, code, flow.state, {
-      store: opts.store,
-      fetch: opts.fetch,
-    });
-
-    // 6. Tokens are already stored by exchangeCodeForTokens.
-    //    Compute expiresAt from expiresIn for the result.
-    const expiresAt = tokens.expiresIn
-      ? Date.now() + tokens.expiresIn * 1000
-      : undefined;
-
-    return {
-      provider: opts.provider,
-      redirectUri,
-      expiresAt,
-      scope: tokens.scope,
-    };
-  } finally {
-    // 7. Clean up
-    await server.close();
-  }
-}
-
-/**
- * Refresh an OAuth token using a refresh token.
- * Updates the stored tokens on success.
- */
-export async function refreshTokens(
-  provider: string,
-  refreshToken: string,
-  store: SecretStore,
-  options?: { fetch?: typeof globalThis.fetch },
-): Promise<OAuthTokenResponse> {
-  const config = PKCE_CONFIGS[provider];
-  if (!config) {
-    throw new Error(`OAuth not supported for provider: ${provider}`);
-  }
-
-  if (!store) {
-    throw new Error("SecretStore is required for token refresh");
-  }
-
-  const clientId =
-    config.clientIdEnvVar
-      ? (process.env[config.clientIdEnvVar] ?? "")
-      : "";
-
-  const params = new URLSearchParams({
-    grant_type: "refresh_token",
-    refresh_token: refreshToken,
-    client_id: clientId,
-  });
-
-  const fetchImpl = options?.fetch ?? globalThis.fetch.bind(globalThis);
-  const response = await fetchImpl(config.tokenUrl, {
-    method: "POST",
-    headers: {
-      "content-type": "application/x-www-form-urlencoded",
-    },
-    body: params.toString(),
-  });
-
-  if (!response.ok) {
-    const body = await response.text().catch(() => "");
-    throw new Error(
-      `Token refresh failed for ${provider}: HTTP ${response.status} ${body}`,
-    );
-  }
-
-  const json = (await response.json()) as {
-    access_token?: string;
-    refresh_token?: string;
-    expires_in?: number;
-    scope?: string;
-  };
-
-  if (!json.access_token) {
-    throw new Error(
-      `Token refresh for ${provider} returned no access_token`,
-    );
-  }
-
-  // Update stored tokens (structured)
-  const obtainedAt = Date.now();
-  await setOAuthTokens(
-    provider,
-    {
-      accessToken: json.access_token,
-      refreshToken: json.refresh_token,
-      expiresAt: json.expires_in
-        ? obtainedAt + json.expires_in * 1000
-        : undefined,
-      scope: json.scope,
-      obtainedAt,
-    },
-    store,
-  );
-
-  return {
-    accessToken: new Redacted(json.access_token),
-    refreshToken: json.refresh_token
-      ? new Redacted(json.refresh_token)
-      : undefined,
-    expiresIn: json.expires_in,
-    scope: json.scope,
-  };
-}

package/src/auth/oauth-server.test.ts

@@ -1,83 +0,0 @@
-/**
- * Tests for the local OAuth callback server.
- * No real OAuth: we hit the callback URL directly over HTTP.
- */
-import { describe, expect, it } from "vitest";
-import { startCallbackServer } from "./oauth-server.js";
-
-describe("startCallbackServer", () => {
-  it("binds to 127.0.0.1 and exposes a localhost redirect URL", async () => {
-    const server = await startCallbackServer(0);
-    try {
-      expect(server.url).toContain("127.0.0.1");
-      expect(server.url).toMatch(/^http:\/\/127\.0\.0\.1:\d+\/callback$/);
-      expect(server.port).toBeGreaterThan(0);
-    } finally {
-      await server.close();
-    }
-  });
-
-  it("captures the authorization code from a matching callback", async () => {
-    const server = await startCallbackServer(0);
-    try {
-      const waitPromise = server.waitForCode({
-        expectedState: "state-abc",
-        timeoutMs: 2000,
-      });
-      const res = await fetch(`${server.url}?code=AUTHCODE123&state=state-abc`);
-      expect(res.status).toBe(200);
-      const body = await res.text();
-      expect(body).toMatch(/success|complete|authorized/i);
-
-      const result = await waitPromise;
-      expect(result.code).toBe("AUTHCODE123");
-      expect(result.state).toBe("state-abc");
-    } finally {
-      await server.close();
-    }
-  });
-
-  it("rejects a callback with a mismatched state", async () => {
-    const server = await startCallbackServer(0);
-    try {
-      const waitPromise = server.waitForCode({
-        expectedState: "expected-state",
-        timeoutMs: 2000,
-      });
-      // Attach the rejection handler before triggering the callback so the
-      // rejection is never momentarily unhandled.
-      const assertion = expect(waitPromise).rejects.toThrow(/state/i);
-      await fetch(`${server.url}?code=CODE&state=wrong-state`);
-      await assertion;
-    } finally {
-      await server.close();
-    }
-  });
-
-  it("rejects when no callback arrives before the timeout", async () => {
-    const server = await startCallbackServer(0);
-    try {
-      await expect(
-        server.waitForCode({ timeoutMs: 50 }),
-      ).rejects.toThrow(/timed out|timeout/i);
-    } finally {
-      await server.close();
-    }
-  });
-
-  it("returns an error page for callbacks missing the code", async () => {
-    const server = await startCallbackServer(0);
-    try {
-      const res = await fetch(`${server.url}?state=only-state`);
-      expect(res.status).toBe(400);
-    } finally {
-      await server.close();
-    }
-  });
-
-  it("close is idempotent and releases the port", async () => {
-    const server = await startCallbackServer(0);
-    await server.close();
-    await expect(server.close()).resolves.toBeUndefined();
-  });
-});