offrouter-core 0.0.0

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

@@ -0,0 +1,202 @@
+/**
+ * Tests for credential-chain resolver.
+ */
+import { describe, expect, it, vi } from "vitest";
+import {
+  Redacted,
+  resolveCredential,
+  type CredentialSource,
+} from "./credential-chain.js";
+import type { SecretStore } from "../secrets.js";
+
+function stubStore(entries: Record<string, string>): SecretStore {
+  return {
+    get: vi.fn(async (id: string) => entries[id]),
+    set: vi.fn(),
+    delete: vi.fn(),
+    listProviders: vi.fn(async () => Object.keys(entries)),
+    redact: vi.fn((v: string) => v),
+    toJSON: vi.fn(() => ({})),
+  };
+}
+
+describe("Redacted", () => {
+  it("wraps a value and hides it in toJSON", () => {
+    const r = new Redacted("sk-ant-test123");
+    expect(r.rawValue).toBe("sk-ant-test123");
+    expect(r.toJSON()).toBe("[REDACTED]");
+    expect(JSON.stringify(r)).toBe('"[REDACTED]"');
+    expect(String(r)).toBe("[REDACTED]");
+  });
+
+  it("returns a non-empty rawValue", () => {
+    const r = new Redacted("some-token");
+    expect(r.rawValue).toBe("some-token");
+    expect(r.rawValue.length).toBeGreaterThan(0);
+  });
+});
+
+describe("resolveCredential", () => {
+  it("returns null for empty sources array", async () => {
+    const result = await resolveCredential([], { store: stubStore({}) });
+    expect(result).toBeNull();
+  });
+
+  describe("env source", () => {
+    it("returns value from process.env", async () => {
+      const prev = process.env["OFFROUTER_TEST_KEY"];
+      process.env["OFFROUTER_TEST_KEY"] = "env-value";
+      try {
+        const sources: CredentialSource[] = [
+          { type: "env", name: "OFFROUTER_TEST_KEY" },
+        ];
+        const result = await resolveCredential(sources, { store: stubStore({}) });
+        expect(result).not.toBeNull();
+        expect(result!.value.rawValue).toBe("env-value");
+        expect(result!.source).toBe("env");
+      } finally {
+        if (prev === undefined) {
+          delete process.env["OFFROUTER_TEST_KEY"];
+        } else {
+          process.env["OFFROUTER_TEST_KEY"] = prev;
+        }
+      }
+    });
+
+    it("skips env when variable is undefined", async () => {
+      const sources: CredentialSource[] = [
+        { type: "env", name: "OFFROUTER_DOES_NOT_EXIST_XYZ" },
+      ];
+      const result = await resolveCredential(sources, { store: stubStore({}) });
+      expect(result).toBeNull();
+    });
+  });
+
+  describe("keychain source", () => {
+    it("returns value from secret store", async () => {
+      const store = stubStore({ "anthropic": "sk-ant-keychain-test" });
+      const sources: CredentialSource[] = [
+        { type: "keychain", providerId: "anthropic" },
+      ];
+      const result = await resolveCredential(sources, { store });
+      expect(result).not.toBeNull();
+      expect(result!.value.rawValue).toBe("sk-ant-keychain-test");
+      expect(result!.source).toBe("keychain");
+    });
+
+    it("skips keychain when store returns undefined", async () => {
+      const store = stubStore({});
+      const sources: CredentialSource[] = [
+        { type: "keychain", providerId: "unknown" },
+      ];
+      const result = await resolveCredential(sources, { store });
+      expect(result).toBeNull();
+    });
+  });
+
+  describe("chain order", () => {
+    it("returns first non-empty source (env beats keychain)", async () => {
+      process.env["ANTHROPIC_API_KEY"] = "from-env";
+      try {
+        const store = stubStore({ "anthropic": "from-keychain" });
+        const sources: CredentialSource[] = [
+          { type: "env", name: "ANTHROPIC_API_KEY" },
+          { type: "keychain", providerId: "anthropic" },
+        ];
+        const result = await resolveCredential(sources, { store });
+        expect(result).not.toBeNull();
+        expect(result!.value.rawValue).toBe("from-env");
+        expect(result!.source).toBe("env");
+      } finally {
+        delete process.env["ANTHROPIC_API_KEY"];
+      }
+    });
+
+    it("falls through to keychain when env is missing", async () => {
+      const store = stubStore({ "openai": "sk-from-keychain" });
+      const sources: CredentialSource[] = [
+        { type: "env", name: "OPENAI_API_KEY_MISSING" },
+        { type: "keychain", providerId: "openai" },
+      ];
+      const result = await resolveCredential(sources, { store });
+      expect(result).not.toBeNull();
+      expect(result!.value.rawValue).toBe("sk-from-keychain");
+      expect(result!.source).toBe("keychain");
+    });
+
+    it("returns null when all sources fail", async () => {
+      const store = stubStore({});
+      const sources: CredentialSource[] = [
+        { type: "env", name: "MISSING_VAR_1" },
+        { type: "env", name: "MISSING_VAR_2" },
+        { type: "keychain", providerId: "nonexistent" },
+      ];
+      const result = await resolveCredential(sources, { store });
+      expect(result).toBeNull();
+    });
+  });
+
+  describe("config source (trusted config)", () => {
+    it("returns value from trusted config provider apiKey", async () => {
+      const store = stubStore({});
+      const sources: CredentialSource[] = [
+        { type: "config", key: "providers.anthropic.apiKey" },
+      ];
+      const result = await resolveCredential(sources, {
+        store,
+        config: { providers: { anthropic: { apiKey: "sk-ant-config" } } } as Record<string, unknown>,
+      });
+      expect(result).not.toBeNull();
+      expect(result!.value.rawValue).toBe("sk-ant-config");
+      expect(result!.source).toBe("config");
+    });
+
+    it("returns null when config is not provided", async () => {
+      const store = stubStore({});
+      const sources: CredentialSource[] = [
+        { type: "config", key: "providers.anthropic.apiKey" },
+      ];
+      const result = await resolveCredential(sources, { store });
+      expect(result).toBeNull();
+    });
+
+    it("handles dot-notation path", async () => {
+      const store = stubStore({});
+      const sources: CredentialSource[] = [
+        { type: "config", key: "providers.openai.apiKey" },
+      ];
+      const result = await resolveCredential(sources, {
+        store,
+        config: {
+          providers: {
+            openai: { enabled: true },
+            anthropic: { apiKey: "wrong-key" },
+          },
+        } as Record<string, unknown>,
+      });
+      expect(result).toBeNull();
+    });
+  });
+});
+
+describe("credentialSource type narrowing", () => {
+  it("env source type is correct literal", () => {
+    const s: CredentialSource = { type: "env", name: "API_KEY" };
+    expect(s.type).toBe("env");
+  });
+
+  it("keychain source type is correct literal", () => {
+    const s: CredentialSource = { type: "keychain", providerId: "anthropic" };
+    expect(s.type).toBe("keychain");
+  });
+
+  it("config source type is correct literal", () => {
+    const s: CredentialSource = { type: "config", key: "providers.anthropic.apiKey" };
+    expect(s.type).toBe("config");
+  });
+
+  it("oauth source type is correct literal", () => {
+    const s: CredentialSource = { type: "oauth", provider: "anthropic" };
+    expect(s.type).toBe("oauth");
+  });
+});

package/src/auth/credential-chain.ts

@@ -0,0 +1,181 @@
+/**
+ * Credential-chain resolution for OffRouter.
+ *
+ * Tries each source in order: env -> config -> keychain -> (oauth, opt-in).
+ * Never logs secret values. Uses Redacted<T> wrapper for safe output.
+ * Never scrapes other CLI credential stores.
+ */
+
+import type { SecretStore } from "../secrets.js";
+
+// ---------------------------------------------------------------------------
+// Redacted wrapper
+// ---------------------------------------------------------------------------
+
+/**
+ * Wrapper that hides secret material from JSON serialization and string
+ * conversion. The raw value is accessible via `.rawValue` for use in
+ * Authorization headers, never for logging.
+ */
+export class Redacted<T extends string = string> {
+  readonly #value: T;
+
+  constructor(value: T) {
+    this.#value = value;
+  }
+
+  /** Access the raw secret value. Use only for provider API calls. */
+  get rawValue(): T {
+    return this.#value;
+  }
+
+  /** Returns a constant redacted string for JSON serialization. */
+  toJSON(): string {
+    return "[REDACTED]";
+  }
+
+  /** Returns a constant redacted string for debugging. */
+  toString(): string {
+    return "[REDACTED]";
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Credential source types
+// ---------------------------------------------------------------------------
+
+/**
+ * A single credential source in the chain.
+ * Each source is tried in order; the first non-empty value wins.
+ */
+export type CredentialSource =
+  | { type: "env"; name: string }
+  | { type: "config"; key: string }
+  | { type: "keychain"; providerId: string }
+  | { type: "oauth"; provider: string };
+
+/**
+ * Result of a successful credential resolution.
+ */
+export interface CredentialResult {
+  /**
+   * The resolved credential value, wrapped in Redacted so it cannot be
+   * accidentally logged or serialized.
+   */
+  value: Redacted<string>;
+  /** Which source type produced the value. */
+  source: "env" | "config" | "keychain" | "oauth";
+}
+
+/**
+ * Options for resolveCredential.
+ */
+export interface ResolveCredentialOptions {
+  /** Secret store for keychain lookups. */
+  store: SecretStore;
+  /**
+   * Optional trusted config object. When provided, config sources can read
+   * provider-level apiKey values. Only use with trusted config from the
+   * user's OffRouter home directory.
+   */
+  config?: Record<string, unknown>;
+}
+
+/**
+ * Resolve a credential by trying each source in order.
+ * Returns the first non-empty value, or null if all sources are empty.
+ */
+export async function resolveCredential(
+  sources: CredentialSource[],
+  opts: ResolveCredentialOptions,
+): Promise<CredentialResult | null> {
+  for (const source of sources) {
+    const value = await trySource(source, opts);
+    if (value !== null) {
+      return { value: new Redacted(value), source: source.type };
+    }
+  }
+  return null;
+}
+
+/**
+ * Try a single credential source.
+ * Returns the raw secret string or null if not found.
+ */
+async function trySource(
+  source: CredentialSource,
+  opts: ResolveCredentialOptions,
+): Promise<string | null> {
+  switch (source.type) {
+    case "env": {
+      return tryEnv(source.name);
+    }
+    case "config": {
+      return tryConfig(source.key, opts.config);
+    }
+    case "keychain": {
+      return tryKeychain(source.providerId, opts.store);
+    }
+    case "oauth": {
+      // OAuth is never auto-triggered during credential resolution.
+      // It requires explicit configuration and a separate flow.
+      return null;
+    }
+  }
+}
+
+/**
+ * Read a value from environment variables.
+ */
+function tryEnv(name: string): string | null {
+  const value = process.env[name];
+  if (typeof value === "string" && value.trim().length > 0) {
+    return value.trim();
+  }
+  return null;
+}
+
+/**
+ * Read a value from trusted config using dot-notation path.
+ * Only reads from config if provided (trusted source).
+ * Path format: "providers.{providerId}.apiKey"
+ */
+function tryConfig(key: string, config?: Record<string, unknown>): string | null {
+  if (!config) {
+    return null;
+  }
+  const parts = key.split(".");
+  let current: unknown = config;
+  for (const part of parts) {
+    if (typeof current !== "object" || current === null) {
+      return null;
+    }
+    const obj = current as Record<string, unknown>;
+    if (!(part in obj)) {
+      return null;
+    }
+    current = obj[part];
+  }
+  if (typeof current === "string" && current.trim().length > 0) {
+    return current.trim();
+  }
+  return null;
+}
+
+/**
+ * Read a value from the secret store (keychain-backed).
+ */
+async function tryKeychain(
+  providerId: string,
+  store: SecretStore,
+): Promise<string | null> {
+  try {
+    const value = await store.get(providerId);
+    if (typeof value === "string" && value.trim().length > 0) {
+      return value.trim();
+    }
+  } catch {
+    // KeychainUnavailableError or other errors: treat as missing.
+  }
+  return null;
+}

package/src/auth/index.ts

@@ -0,0 +1,32 @@
+/**
+ * Auth module barrel export for OffRouter.
+ */
+export {
+  Redacted,
+  resolveCredential,
+} from "./credential-chain.js";
+export type {
+  CredentialResult,
+  CredentialSource,
+  ResolveCredentialOptions,
+} from "./credential-chain.js";
+
+export { getProviderToken, setProviderToken } from "./keychain.js";
+
+export {
+  exchangeCodeForTokens,
+  generateCodeChallenge,
+  generateCodeVerifier,
+  isOAuthProvider,
+  PKCE_CONFIGS,
+  refreshTokens,
+  startOAuthFlow,
+} from "./oauth-pkce.js";
+export type {
+  OAuthFlowResult,
+  OAuthFlowState,
+  OAuthProviderConfig,
+  OAuthStartOptions,
+  OAuthTokenOptions,
+  OAuthTokenResponse,
+} from "./oauth-pkce.js";

package/src/auth/keychain.test.ts

@@ -0,0 +1,75 @@
+/**
+ * Tests for keychain-backed token helpers.
+ */
+import { describe, expect, it } from "vitest";
+import { getProviderToken, setProviderToken } from "./keychain.js";
+import { FileSecretStore } from "../secrets.js";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { mkdtempSync, rmSync } from "node:fs";
+
+describe("getProviderToken", () => {
+  it("returns undefined when no token is stored", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "offrouter-keychain-test-"));
+    try {
+      const store = new FileSecretStore({ filePath: join(dir, "secrets.json") });
+      const result = await getProviderToken("anthropic", store);
+      expect(result).toBeUndefined();
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("returns the token when stored", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "offrouter-keychain-test-"));
+    try {
+      const store = new FileSecretStore({ filePath: join(dir, "secrets.json") });
+      await store.set("anthropic", "sk-ant-stored-value");
+      const result = await getProviderToken("anthropic", store);
+      expect(result).not.toBeUndefined();
+      expect(result!.rawValue).toBe("sk-ant-stored-value");
+      expect(JSON.stringify(result)).toBe('"[REDACTED]"');
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("returns undefined for nonexistent provider", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "offrouter-keychain-test-"));
+    try {
+      const store = new FileSecretStore({ filePath: join(dir, "secrets.json") });
+      const result = await getProviderToken("nonexistent", store);
+      expect(result).toBeUndefined();
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("setProviderToken", () => {
+  it("stores a token and retrieves it", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "offrouter-keychain-test-"));
+    try {
+      const store = new FileSecretStore({ filePath: join(dir, "secrets.json") });
+      await setProviderToken("openai", "sk-openai-test", store);
+      const token = await getProviderToken("openai", store);
+      expect(token).not.toBeUndefined();
+      expect(token!.rawValue).toBe("sk-openai-test");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("overwrites existing token", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "offrouter-keychain-test-"));
+    try {
+      const store = new FileSecretStore({ filePath: join(dir, "secrets.json") });
+      await setProviderToken("test", "first-value", store);
+      await setProviderToken("test", "second-value", store);
+      const token = await getProviderToken("test", store);
+      expect(token!.rawValue).toBe("second-value");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/auth/keychain.ts

@@ -0,0 +1,39 @@
+/**
+ * Keychain-backed token helpers for OffRouter.
+ *
+ * Provides getProviderToken/setProviderToken that use the SecretStore
+ * abstraction (file or OS keychain). Never scrapes other CLI credential stores.
+ */
+import type { SecretStore } from "../secrets.js";
+import { Redacted } from "./credential-chain.js";
+
+/**
+ * Retrieve a provider token from the secret store.
+ * Returns undefined if no token is stored or the store is unavailable.
+ */
+export async function getProviderToken(
+  providerId: string,
+  store: SecretStore,
+): Promise<Redacted<string> | undefined> {
+  try {
+    const value = await store.get(providerId);
+    if (typeof value === "string" && value.length > 0) {
+      return new Redacted(value);
+    }
+  } catch {
+    // KeychainUnavailableError or other errors: treat as missing.
+  }
+  return undefined;
+}
+
+/**
+ * Store a provider token in the secret store.
+ * Throws if the store is unavailable (e.g., KeychainUnavailableError).
+ */
+export async function setProviderToken(
+  providerId: string,
+  token: string,
+  store: SecretStore,
+): Promise<void> {
+  await store.set(providerId, token);
+}