offrouter-core 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "offrouter-core",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/src/auth/credential-chain.test.ts

@@ -199,4 +199,128 @@ describe("credentialSource type narrowing", () => {
     const s: CredentialSource = { type: "oauth", provider: "anthropic" };
     expect(s.type).toBe("oauth");
   });
+});
+
+describe("oauth credential source", () => {
+  function storeWithOAuth(
+    accessToken: string,
+    refreshToken?: string,
+    expiresAt?: number,
+  ): SecretStore {
+    const tokens = {
+      accessToken,
+      refreshToken,
+      expiresAt,
+      obtainedAt: 1_000,
+    };
+    return {
+      get: vi.fn(async (id: string) =>
+        id === "anthropic:oauth" ? JSON.stringify(tokens) : undefined,
+      ),
+      set: vi.fn(),
+      delete: vi.fn(),
+      listProviders: vi.fn(async () => ["anthropic:oauth"]),
+      redact: vi.fn((v: string) => v),
+      toJSON: vi.fn(() => ({})),
+    };
+  }
+
+  it("resolves a stored (non-expired) OAuth token", async () => {
+    const store = storeWithOAuth(
+      "ant-oauth-token",
+      "ant-refresh",
+      Date.now() + 3600_000,
+    );
+    const sources: CredentialSource[] = [
+      { type: "oauth", provider: "anthropic" },
+    ];
+    const result = await resolveCredential(sources, { store });
+    expect(result).not.toBeNull();
+    expect(result!.value.rawValue).toBe("ant-oauth-token");
+    expect(result!.source).toBe("oauth");
+  });
+
+  it("returns null when no OAuth tokens are stored", async () => {
+    const store = stubStore({});
+    const sources: CredentialSource[] = [
+      { type: "oauth", provider: "anthropic" },
+    ];
+    const result = await resolveCredential(sources, { store });
+    expect(result).toBeNull();
+  });
+
+  it("returns null for an expired token without a refresh callback", async () => {
+    const store = storeWithOAuth(
+      "ant-oauth-expired",
+      "ant-refresh",
+      Date.now() - 1000,
+    );
+    const sources: CredentialSource[] = [
+      { type: "oauth", provider: "anthropic" },
+    ];
+    const result = await resolveCredential(sources, { store });
+    expect(result).toBeNull();
+  });
+
+  it("calls refreshOAuthToken for expired tokens when callback is provided", async () => {
+    const store = storeWithOAuth(
+      "ant-oauth-expired",
+      "ant-refresh",
+      Date.now() - 1000,
+    );
+    const refreshCallback = vi.fn(async (provider: string) => {
+      expect(provider).toBe("anthropic");
+      return "ant-oauth-refreshed";
+    });
+    const sources: CredentialSource[] = [
+      { type: "oauth", provider: "anthropic" },
+    ];
+    const result = await resolveCredential(sources, {
+      store,
+      refreshOAuthToken: refreshCallback,
+    });
+    expect(result).not.toBeNull();
+    expect(result!.value.rawValue).toBe("ant-oauth-refreshed");
+    expect(result!.source).toBe("oauth");
+    expect(refreshCallback).toHaveBeenCalledWith("anthropic");
+  });
+
+  it("falls through when refreshOAuthToken returns null", async () => {
+    const store = storeWithOAuth(
+      "ant-oauth-expired",
+      "ant-refresh",
+      Date.now() - 1000,
+    );
+    const refreshCallback = vi.fn(async () => null);
+    const sources: CredentialSource[] = [
+      { type: "oauth", provider: "anthropic" },
+      { type: "keychain", providerId: "fallback" },
+    ];
+    // No fallback token stored, so overall null.
+    const result = await resolveCredential(sources, {
+      store,
+      refreshOAuthToken: refreshCallback,
+    });
+    expect(result).toBeNull();
+    expect(refreshCallback).toHaveBeenCalledWith("anthropic");
+  });
+
+  it("falls through when refreshOAuthToken throws", async () => {
+    const store = storeWithOAuth(
+      "ant-oauth-expired",
+      "ant-refresh",
+      Date.now() - 1000,
+    );
+    const refreshCallback = vi.fn(async () => {
+      throw new Error("network error");
+    });
+    const sources: CredentialSource[] = [
+      { type: "oauth", provider: "anthropic" },
+    ];
+    const result = await resolveCredential(sources, {
+      store,
+      refreshOAuthToken: refreshCallback,
+    });
+    expect(result).toBeNull();
+  });
 });

package/src/auth/credential-chain.ts

@@ -7,7 +7,11 @@
  */
 
 import type { SecretStore } from "../secrets.js";
-import { accountStorageKey } from "./keychain.js";
+import {
+  accountStorageKey,
+  getOAuthTokens,
+  isOAuthTokenExpired,
+} from "./keychain.js";
 
 // ---------------------------------------------------------------------------
 // Redacted wrapper
@@ -80,6 +84,18 @@ export interface ResolveCredentialOptions {
    * user's OffRouter home directory.
    */
   config?: Record<string, unknown>;
+  /**
+   * Injectable fetch for any network calls during credential resolution
+   * (e.g. OAuth token refresh). Defaults to globalThis.fetch.
+   */
+  fetch?: typeof globalThis.fetch;
+  /**
+   * Optional OAuth token refresher. Given a provider id, refreshes the stored
+   * OAuth token (if possible) and returns the new access token, or null if
+   * refresh is not possible. When omitted, expired OAuth tokens resolve as
+   * null (no silent refresh during credential resolution).
+   */
+  refreshOAuthToken?: (provider: string) => Promise<string | null>;
 }
 
 /**
@@ -118,9 +134,14 @@ async function trySource(
       return tryKeychain(source.providerId, opts.store, source.accountId);
     }
     case "oauth": {
-      // OAuth is never auto-triggered during credential resolution.
-      // It requires explicit configuration and a separate flow.
-      return null;
+      // Resolve stored OAuth tokens. This does NOT trigger a login flow;
+      // it resolves tokens already obtained via the `login` command.
+      // If the token is expired and a refresher is wired, try refreshing.
+      return tryOAuth(
+        source.provider,
+        opts.store,
+        opts.refreshOAuthToken,
+      );
     }
   }
 }
@@ -181,4 +202,34 @@ async function tryKeychain(
     // KeychainUnavailableError or other errors: treat as missing.
   }
   return null;
+}
+
+/**
+ * Resolve a credential from stored OAuth tokens (no new login flow).
+ * Returns the access token if valid, triggers refresh if expired + wired,
+ * or returns null if no tokens exist or refresh fails.
+ */
+async function tryOAuth(
+  providerId: string,
+  store: SecretStore,
+  refresh?: (provider: string) => Promise<string | null>,
+): Promise<string | null> {
+  try {
+    const tokens = await getOAuthTokens(providerId, store);
+    if (!tokens) return null;
+
+    if (!isOAuthTokenExpired(tokens)) {
+      return tokens.accessToken;
+    }
+
+    // Expired: try refresh if a refresher is wired.
+    if (!refresh) return null;
+    try {
+      return await refresh(providerId);
+    } catch {
+      return null;
+    }
+  } catch {
+    return null;
+  }
 }

package/src/auth/index.ts

@@ -11,15 +11,26 @@ export type {
   ResolveCredentialOptions,
 } from "./credential-chain.js";
 
-export { getProviderToken, setProviderToken } from "./keychain.js";
+export {
+  deleteOAuthTokens,
+  getOAuthTokens,
+  getProviderToken,
+  isOAuthTokenExpired,
+  setOAuthTokens,
+  setProviderToken,
+} from "./keychain.js";
+export type { OAuthStoredTokens } from "./keychain.js";
 
 export {
+  defaultCallbackPort,
   exchangeCodeForTokens,
   generateCodeChallenge,
   generateCodeVerifier,
   isOAuthProvider,
   PKCE_CONFIGS,
   refreshTokens,
+  resolveClientId,
+  runOAuthLogin,
   startOAuthFlow,
 } from "./oauth-pkce.js";
 export type {
@@ -29,4 +40,6 @@ export type {
   OAuthStartOptions,
   OAuthTokenOptions,
   OAuthTokenResponse,
+  RunOAuthLoginOptions,
+  RunOAuthLoginResult,
 } from "./oauth-pkce.js";

package/src/auth/keychain.test.ts

@@ -2,7 +2,15 @@
  * Tests for keychain-backed token helpers.
  */
 import { describe, expect, it } from "vitest";
-import { getProviderToken, setProviderToken } from "./keychain.js";
+import {
+  deleteOAuthTokens,
+  getOAuthTokens,
+  getProviderToken,
+  isOAuthTokenExpired,
+  setOAuthTokens,
+  setProviderToken,
+  type OAuthStoredTokens,
+} from "./keychain.js";
 import { FileSecretStore } from "../secrets.js";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -109,4 +117,149 @@ describe("multi-account tokens", () => {
       rmSync(dir, { recursive: true, force: true });
     }
   });
+});
+
+describe("OAuth token storage", () => {
+  function freshStore() {
+    const dir = mkdtempSync(join(tmpdir(), "offrouter-oauth-test-"));
+    const store = new FileSecretStore({ filePath: join(dir, "secrets.json") });
+    return { store, dir };
+  }
+
+  it("getOAuthTokens returns undefined when nothing is stored", async () => {
+    const { store, dir } = freshStore();
+    try {
+      const result = await getOAuthTokens("anthropic", store);
+      expect(result).toBeUndefined();
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("stores and retrieves structured OAuth tokens", async () => {
+    const { store, dir } = freshStore();
+    try {
+      const tokens: OAuthStoredTokens = {
+        accessToken: "access-abc",
+        refreshToken: "refresh-xyz",
+        expiresAt: 9_999_999_999_000,
+        scope: "api offline_access",
+        obtainedAt: 1_000,
+      };
+      await setOAuthTokens("anthropic", tokens, store);
+      const result = await getOAuthTokens("anthropic", store);
+      expect(result).toEqual(tokens);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("stores tokens under a separate key from plain API-key tokens", async () => {
+    const { store, dir } = freshStore();
+    try {
+      await setProviderToken("anthropic", "sk-ant-apikey", store);
+      await setOAuthTokens(
+        "anthropic",
+        { accessToken: "access-oauth", obtainedAt: 1 },
+        store,
+      );
+      const apiToken = await getProviderToken("anthropic", store);
+      const oauthTokens = await getOAuthTokens("anthropic", store);
+      expect(apiToken!.rawValue).toBe("sk-ant-apikey");
+      expect(oauthTokens!.accessToken).toBe("access-oauth");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("deleteOAuthTokens removes only the OAuth entry", async () => {
+    const { store, dir } = freshStore();
+    try {
+      await setOAuthTokens(
+        "openai",
+        { accessToken: "a", obtainedAt: 1 },
+        store,
+      );
+      await setProviderToken("openai", "sk-openai", store);
+      await deleteOAuthTokens("openai", store);
+      expect(await getOAuthTokens("openai", store)).toBeUndefined();
+      expect((await getProviderToken("openai", store))!.rawValue).toBe(
+        "sk-openai",
+      );
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("supports per-account OAuth token storage", async () => {
+    const { store, dir } = freshStore();
+    try {
+      await setOAuthTokens(
+        "anthropic",
+        { accessToken: "default", obtainedAt: 1 },
+        store,
+      );
+      await setOAuthTokens(
+        "anthropic",
+        { accessToken: "acct2", obtainedAt: 1 },
+        store,
+        "anthropic-2",
+      );
+      const def = await getOAuthTokens("anthropic", store);
+      const acct2 = await getOAuthTokens("anthropic", store, "anthropic-2");
+      expect(def!.accessToken).toBe("default");
+      expect(acct2!.accessToken).toBe("acct2");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("returns undefined for corrupt stored JSON", async () => {
+    const { store, dir } = freshStore();
+    try {
+      await store.set("anthropic:oauth", "{not json");
+      const result = await getOAuthTokens("anthropic", store);
+      expect(result).toBeUndefined();
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("isOAuthTokenExpired", () => {
+  it("treats tokens without expiresAt as not expired", () => {
+    expect(
+      isOAuthTokenExpired({ accessToken: "a", obtainedAt: 1 }),
+    ).toBe(false);
+  });
+
+  it("treats future expiry as valid", () => {
+    expect(
+      isOAuthTokenExpired(
+        { accessToken: "a", expiresAt: 10_000, obtainedAt: 1 },
+        5_000,
+        1_000,
+      ),
+    ).toBe(false);
+  });
+
+  it("treats tokens within the skew window as expired", () => {
+    // now=5000, skew=1000 => anything expiring <= 6000 is expired
+    expect(
+      isOAuthTokenExpired(
+        { accessToken: "a", expiresAt: 6_000, obtainedAt: 1 },
+        5_000,
+        1_000,
+      ),
+    ).toBe(true);
+  });
+
+  it("treats past expiry as expired", () => {
+    expect(
+      isOAuthTokenExpired(
+        { accessToken: "a", expiresAt: 1_000, obtainedAt: 0 },
+        5_000,
+      ),
+    ).toBe(true);
+  });
 });

package/src/auth/keychain.ts

@@ -54,4 +54,115 @@ export async function setProviderToken(
 ): Promise<void> {
   const key = accountStorageKey(providerId, accountId);
   await store.set(key, token);
+}
+
+// ---------------------------------------------------------------------------
+// OAuth token storage (structured, separate from API-key tokens)
+// ---------------------------------------------------------------------------
+
+/** Suffix that namespaces structured OAuth token blobs in the secret store. */
+const OAUTH_SUFFIX = ":oauth";
+
+/**
+ * Structured OAuth token material stored under "${providerId}[:account]:oauth".
+ * accessToken is the bearer used for provider calls; refreshToken drives
+ * silent refresh; expiresAt/obtainedAt are epoch milliseconds. Stored as JSON
+ * so the whole token set moves atomically and stays separate from API keys.
+ */
+export interface OAuthStoredTokens {
+  accessToken: string;
+  refreshToken?: string;
+  expiresAt?: number;
+  scope?: string;
+  obtainedAt: number;
+}
+
+/** Compute the secret-store key for a provider+account OAuth token set. */
+export function oauthStorageKey(
+  providerId: string,
+  accountId?: string,
+): string {
+  return `${accountStorageKey(providerId, accountId)}${OAUTH_SUFFIX}`;
+}
+
+/**
+ * Store structured OAuth tokens (access, optional refresh, expiry, scope).
+ */
+export async function setOAuthTokens(
+  providerId: string,
+  tokens: OAuthStoredTokens,
+  store: SecretStore,
+  accountId?: string,
+): Promise<void> {
+  const key = oauthStorageKey(providerId, accountId);
+  await store.set(key, JSON.stringify(tokens));
+}
+
+/**
+ * Retrieve structured OAuth tokens. Returns undefined if nothing is stored,
+ * the store is unavailable, or the stored payload is corrupt.
+ */
+export async function getOAuthTokens(
+  providerId: string,
+  store: SecretStore,
+  accountId?: string,
+): Promise<OAuthStoredTokens | undefined> {
+  try {
+    const key = oauthStorageKey(providerId, accountId);
+    const raw = await store.get(key);
+    if (typeof raw !== "string" || raw.length === 0) {
+      return undefined;
+    }
+    const parsed = JSON.parse(raw) as Partial<OAuthStoredTokens>;
+    if (
+      typeof parsed.accessToken !== "string" ||
+      parsed.accessToken.length === 0
+    ) {
+      return undefined;
+    }
+    return {
+      accessToken: parsed.accessToken,
+      refreshToken:
+        typeof parsed.refreshToken === "string" && parsed.refreshToken.length > 0
+          ? parsed.refreshToken
+          : undefined,
+      expiresAt:
+        typeof parsed.expiresAt === "number" ? parsed.expiresAt : undefined,
+      scope: typeof parsed.scope === "string" ? parsed.scope : undefined,
+      obtainedAt:
+        typeof parsed.obtainedAt === "number" ? parsed.obtainedAt : Date.now(),
+    };
+  } catch {
+    // Corrupt payload or unavailable store: treat as missing.
+    return undefined;
+  }
+}
+
+/** Remove stored OAuth tokens for a provider+account. */
+export async function deleteOAuthTokens(
+  providerId: string,
+  store: SecretStore,
+  accountId?: string,
+): Promise<void> {
+  try {
+    const key = oauthStorageKey(providerId, accountId);
+    await store.delete(key);
+  } catch {
+    // Unavailable store: nothing to delete.
+  }
+}
+
+/**
+ * Returns true when the access token is expired or within the skew window.
+ * Tokens without an expiresAt are treated as not expired (no expiry known).
+ */
+export function isOAuthTokenExpired(
+  tokens: OAuthStoredTokens,
+  now: number = Date.now(),
+  skewMs = 60_000,
+): boolean {
+  if (typeof tokens.expiresAt !== "number") {
+    return false;
+  }
+  return now + skewMs >= tokens.expiresAt;
 }

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 });
+    }
+  });
+});