offrouter-core 0.1.0 → 0.2.1

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

@@ -1,14 +1,22 @@
 /**
  * Tests for OAuth PKCE flow helpers.
  */
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";
 import {
   generateCodeVerifier,
   generateCodeChallenge,
   PKCE_CONFIGS,
   createOAuthState,
   isOAuthProvider,
+  defaultCallbackPort,
+  resolveClientId,
+  runOAuthLogin,
 } from "./oauth-pkce.js";
+import { FileSecretStore } from "../secrets.js";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { mkdtempSync, rmSync } from "node:fs";
+import { getOAuthTokens } from "./keychain.js";
 
 describe("PKCE code verifier and challenge", () => {
   it("generates a code verifier of correct length", () => {
@@ -181,4 +189,141 @@ describe("refreshTokens", () => {
       refreshTokens("anthropic", "old-refresh-token", undefined as any),
     ).rejects.toThrow("SecretStore is required");
   });
-});
+});
+
+describe("defaultCallbackPort", () => {
+  it("returns 1456 for anthropic", () => {
+    expect(defaultCallbackPort("anthropic")).toBe(1456);
+  });
+
+  it("returns 1455 for openai", () => {
+    expect(defaultCallbackPort("openai")).toBe(1455);
+  });
+});
+
+describe("resolveClientId", () => {
+  it("reads from the right env var for anthropic", () => {
+    const id = resolveClientId("anthropic", {
+      OFFROUTER_ANTHROPIC_CLIENT_ID: "ant-id-from-env",
+    } as NodeJS.ProcessEnv);
+    expect(id).toBe("ant-id-from-env");
+  });
+
+  it("reads from the right env var for openai", () => {
+    const id = resolveClientId("openai", {
+      OFFROUTER_OPENAI_CLIENT_ID: "oa-id-from-env",
+    } as NodeJS.ProcessEnv);
+    expect(id).toBe("oa-id-from-env");
+  });
+
+  it("returns undefined when env var is not set", () => {
+    expect(resolveClientId("anthropic", {} as NodeJS.ProcessEnv)).toBeUndefined();
+  });
+});
+
+describe("runOAuthLogin", () => {
+  it("stores structured OAuth tokens in the keychain after the full flow", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "offrouter-run-oauth-"));
+    try {
+      const store = new FileSecretStore({ filePath: join(dir, "secrets.json") });
+      const openBrowser = vi.fn();
+      let capturedAuthorizeUrl = "";
+
+      // Mock fetch: return a fake token response on the token exchange.
+      const mockFetch = vi.fn(async (_url: string, init?: RequestInit) => {
+        const body = typeof init?.body === "string" ? init.body : "";
+        if (body.includes("grant_type=authorization_code")) {
+          return new Response(
+            JSON.stringify({
+              access_token: "ant-access-token-mock",
+              refresh_token: "ant-refresh-token-mock",
+              expires_in: 3600,
+              scope: "api offline_access",
+            }),
+            {
+              status: 200,
+              headers: { "content-type": "application/json" },
+            },
+          );
+        }
+        return new Response("ok", { status: 200 });
+      });
+
+      // Start login; it will block on waitForCode.
+      const loginPromise = runOAuthLogin({
+        provider: "anthropic",
+        store,
+        clientId: "test-client-id",
+        port: 0,
+        timeoutMs: 5000,
+        openBrowser,
+        onAuthorizeUrl: (url) => { capturedAuthorizeUrl = url; },
+        fetch: mockFetch as unknown as typeof globalThis.fetch,
+      });
+
+      // Wait until the authorize URL is emitted (server is ready).
+      await vi.waitFor(() => {
+        expect(capturedAuthorizeUrl).toBeTruthy();
+      }, { timeout: 2000, interval: 50 });
+
+      // Parse url to get redirect_uri and state.
+      const parsed = new URL(capturedAuthorizeUrl);
+      const state = parsed.searchParams.get("state");
+      const redirectUri = parsed.searchParams.get("redirect_uri");
+      expect(state).toBeTruthy();
+      expect(redirectUri).toMatch(/^http:\/\/127\.0\.0\.1:\d+\/callback$/);
+
+      // Emulate the provider callback.
+      const cbRes = await fetch(
+        `${redirectUri}?code=TESTCODE&state=${encodeURIComponent(state!)}`,
+        { redirect: "manual" },
+      );
+      expect(cbRes.status).toBe(200);
+      const body = await cbRes.text();
+      expect(body).toMatch(/success|complete|authorized/i);
+
+      // Await the login result.
+      const result = await loginPromise;
+      expect(result.provider).toBe("anthropic");
+      expect(result.redirectUri).toBe(redirectUri);
+      expect(result.expiresAt).toBeGreaterThan(Date.now());
+
+      // Verify tokens stored in keychain.
+      const stored = await getOAuthTokens("anthropic", store);
+      expect(stored).toBeDefined();
+      expect(stored!.accessToken).toBe("ant-access-token-mock");
+      expect(stored!.refreshToken).toBe("ant-refresh-token-mock");
+      expect(stored!.expiresAt).toBeGreaterThan(Date.now());
+      expect(stored!.scope).toBe("api offline_access");
+
+      // Verify openBrowser was called.
+      expect(openBrowser).toHaveBeenCalledWith(capturedAuthorizeUrl);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("throws for unsupported provider", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "offrouter-oauth-bad-"));
+    try {
+      const store = new FileSecretStore({ filePath: join(dir, "secrets.json") });
+      await expect(
+        runOAuthLogin({ provider: "gemini", store }),
+      ).rejects.toThrow(/not supported/i);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("throws if client id cannot be resolved", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "offrouter-oauth-noid-"));
+    try {
+      const store = new FileSecretStore({ filePath: join(dir, "secrets.json") });
+      await expect(
+        runOAuthLogin({ provider: "anthropic", store, port: 0 }),
+      ).rejects.toThrow(/client id required|client.*id/i);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/auth/oauth-pkce.ts

@@ -10,6 +10,8 @@
 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
@@ -312,15 +314,22 @@ export async function exchangeCodeForTokens(
     );
   }
 
-  // Store tokens in secret store
+  // Store tokens in secret store (structured)
   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,
-      );
-    }
+    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 {
@@ -333,6 +342,149 @@ export async function exchangeCodeForTokens(
   };
 }
 
+// ---------------------------------------------------------------------------
+// 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.
@@ -392,11 +544,21 @@ export async function refreshTokens(
     );
   }
 
-  // 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);
-  }
+  // 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),

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

@@ -0,0 +1,83 @@
+/**
+ * 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();
+  });
+});