offrouter-core 0.1.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "offrouter-core",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -15,7 +15,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "smol-toml": "0.0.0",
-    "zod": "0.0.0"
+    "smol-toml": "^1.7.0",
+    "zod": "^3.23.0"
   }
 }

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