offrouter-core 0.0.0

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

@@ -0,0 +1,184 @@
+/**
+ * Tests for OAuth PKCE flow helpers.
+ */
+import { describe, expect, it } from "vitest";
+import {
+  generateCodeVerifier,
+  generateCodeChallenge,
+  PKCE_CONFIGS,
+  createOAuthState,
+  isOAuthProvider,
+} from "./oauth-pkce.js";
+
+describe("PKCE code verifier and challenge", () => {
+  it("generates a code verifier of correct length", () => {
+    const verifier = generateCodeVerifier();
+    expect(verifier).toBeTruthy();
+    expect(verifier.length).toBeGreaterThanOrEqual(43);
+    expect(verifier.length).toBeLessThanOrEqual(128);
+  });
+
+  it("generates a non-empty code challenge from verifier", async () => {
+    const verifier = generateCodeVerifier();
+    const challenge = await generateCodeChallenge(verifier);
+    expect(challenge).toBeTruthy();
+    expect(typeof challenge).toBe("string");
+  });
+
+  it("generates unique verifiers on each call", () => {
+    const v1 = generateCodeVerifier();
+    const v2 = generateCodeVerifier();
+    expect(v1).not.toBe(v2);
+  });
+});
+
+describe("PKCE_CONFIGS", () => {
+  it("has config for anthropic", () => {
+    const config = PKCE_CONFIGS["anthropic"];
+    expect(config).toBeDefined();
+    expect(config.authorizeUrl).toContain("console.anthropic.com");
+    expect(config.scopes).toContain("offline_access");
+  });
+
+  it("has config for openai", () => {
+    const config = PKCE_CONFIGS["openai"];
+    expect(config).toBeDefined();
+    expect(config.authorizeUrl).toContain("auth.openai.com");
+    expect(config.scopes).toContain("offline_access");
+  });
+
+  it("has no config for gemini", () => {
+    expect(PKCE_CONFIGS["gemini"]).toBeUndefined();
+  });
+
+  it("has no config for xai", () => {
+    expect(PKCE_CONFIGS["xai"]).toBeUndefined();
+  });
+});
+
+describe("createOAuthState", () => {
+  it("creates a state string with metadata", () => {
+    const state = createOAuthState("anthropic");
+    const parsed = JSON.parse(state);
+    expect(parsed.provider).toBe("anthropic");
+    expect(parsed.nonce).toBeTruthy();
+    expect(typeof parsed.nonce).toBe("string");
+  });
+});
+
+describe("isOAuthProvider", () => {
+  it("returns true for anthropic", () => {
+    expect(isOAuthProvider("anthropic")).toBe(true);
+  });
+
+  it("returns true for openai", () => {
+    expect(isOAuthProvider("openai")).toBe(true);
+  });
+
+  it("returns false for gemini", () => {
+    expect(isOAuthProvider("gemini")).toBe(false);
+  });
+
+  it("returns false for xai", () => {
+    expect(isOAuthProvider("xai")).toBe(false);
+  });
+});
+
+describe("startOAuthFlow", () => {
+  it("returns an authorization URL for anthropic", async () => {
+    const { startOAuthFlow } = await import("./oauth-pkce.js");
+    const result = await startOAuthFlow("anthropic", {
+      redirectUri: "http://127.0.0.1:8765/callback",
+      clientId: "test-client-id-anthropic",
+    });
+    expect(result).toBeDefined();
+    expect(result.authorizeUrl).toContain("console.anthropic.com/oauth/authorize");
+    expect(result.authorizeUrl).toContain("response_type=code");
+    expect(result.authorizeUrl).toContain("code_challenge_method=S256");
+    expect(result.state).toBeTruthy();
+  });
+
+  it("returns an authorization URL for openai", async () => {
+    const { startOAuthFlow } = await import("./oauth-pkce.js");
+    const result = await startOAuthFlow("openai", {
+      redirectUri: "http://127.0.0.1:8765/callback",
+      clientId: "test-client-id-openai",
+    });
+    expect(result).toBeDefined();
+    expect(result.authorizeUrl).toContain("auth.openai.com/oauth/authorize");
+    expect(result.authorizeUrl).toContain("response_type=code");
+  });
+
+  it("throws for unsupported provider", async () => {
+    const { startOAuthFlow } = await import("./oauth-pkce.js");
+    await expect(
+      startOAuthFlow("gemini", {
+        redirectUri: "http://127.0.0.1:8765/callback",
+      }),
+    ).rejects.toThrow("OAuth not supported for provider: gemini");
+  });
+});
+
+describe("OAuth session store", () => {
+  it("state string does NOT contain codeVerifier or redirectUri", async () => {
+    const { startOAuthFlow } = await import("./oauth-pkce.js");
+    const result = await startOAuthFlow("anthropic", {
+      redirectUri: "http://127.0.0.1:8765/callback",
+      clientId: "test-client-id-anthropic",
+    });
+    const parsed = JSON.parse(result.state);
+    expect(parsed).not.toHaveProperty("codeVerifier");
+    expect(parsed).not.toHaveProperty("redirectUri");
+    expect(parsed).toHaveProperty("provider", "anthropic");
+    expect(parsed).toHaveProperty("nonce");
+  });
+
+  it("consumeOAuthSession is one-shot: second call returns null", async () => {
+    const { startOAuthFlow, consumeOAuthSession } = await import(
+      "./oauth-pkce.js"
+    );
+    const result = await startOAuthFlow("anthropic", {
+      redirectUri: "http://127.0.0.1:8765/callback",
+      clientId: "test-client-id-anthropic",
+    });
+    const parsed = JSON.parse(result.state);
+
+    const first = consumeOAuthSession(parsed.nonce);
+    expect(first).not.toBeNull();
+    expect(first!.codeVerifier).toBeTruthy();
+    expect(first!.redirectUri).toBe("http://127.0.0.1:8765/callback");
+
+    const second = consumeOAuthSession(parsed.nonce);
+    expect(second).toBeNull();
+  });
+
+  it("cancelOAuthSession removes the session", async () => {
+    const { startOAuthFlow, cancelOAuthSession, consumeOAuthSession } =
+      await import("./oauth-pkce.js");
+    const result = await startOAuthFlow("anthropic", {
+      redirectUri: "http://127.0.0.1:8765/callback",
+      clientId: "test-client-id-anthropic",
+    });
+    const parsed = JSON.parse(result.state);
+
+    cancelOAuthSession(parsed.nonce);
+    const session = consumeOAuthSession(parsed.nonce);
+    expect(session).toBeNull();
+  });
+
+  it("consumeOAuthSession returns null for unknown nonce", async () => {
+    const { consumeOAuthSession } = await import("./oauth-pkce.js");
+    const result = consumeOAuthSession("nonexistent-nonce");
+    expect(result).toBeNull();
+  });
+});
+
+describe("refreshTokens", () => {
+  it("throws when no store is provided", async () => {
+    const { refreshTokens } = await import("./oauth-pkce.js");
+    await expect(
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      refreshTokens("anthropic", "old-refresh-token", undefined as any),
+    ).rejects.toThrow("SecretStore is required");
+  });
+});

package/src/auth/oauth-pkce.ts

@@ -0,0 +1,409 @@
+/**
+ * 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";
+
+// ---------------------------------------------------------------------------
+// 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
+  if (options.store) {
+    await options.store.set(`${provider}_access_token`, json.access_token);
+    if (json.refresh_token) {
+      await options.store.set(
+        `${provider}_refresh_token`,
+        json.refresh_token,
+      );
+    }
+  }
+
+  return {
+    accessToken: new Redacted(json.access_token),
+    refreshToken: json.refresh_token
+      ? new Redacted(json.refresh_token)
+      : undefined,
+    expiresIn: json.expires_in,
+    scope: json.scope,
+  };
+}
+
+/**
+ * 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
+  await store.set(`${provider}_access_token`, json.access_token);
+  if (json.refresh_token) {
+    await store.set(`${provider}_refresh_token`, json.refresh_token);
+  }
+
+  return {
+    accessToken: new Redacted(json.access_token),
+    refreshToken: json.refresh_token
+      ? new Redacted(json.refresh_token)
+      : undefined,
+    expiresIn: json.expires_in,
+    scope: json.scope,
+  };
+}