offrouter-core 0.0.0 → 0.2.0

package/src/auth/oauth-server.ts

@@ -0,0 +1,296 @@
+/**
+ * Local OAuth callback server for OffRouter's live PKCE login flow.
+ *
+ * Binds to 127.0.0.1 ONLY (never 0.0.0.0) so the provider can redirect back
+ * to this machine without exposing the callback to the network. The server
+ * captures the authorization `code` + `state` from the redirect and hands them
+ * to the caller; it never touches tokens, secrets, or the network beyond the
+ * single loopback HTTP socket.
+ */
+import { createServer, type Server, type IncomingMessage, type ServerResponse } from "node:http";
+import { URL } from "node:url";
+
+/** Loopback-only hostname. Hardcoded to prevent accidental 0.0.0.0 binds. */
+const LOOPBACK_HOST = "127.0.0.1";
+
+/** Path the provider redirects to (http://127.0.0.1:PORT/callback). */
+const CALLBACK_PATH = "/callback";
+
+export interface CallbackServerOptions {
+  /**
+   * State value expected from the provider. Validated in waitForCode against
+   * the state returned by the redirect; a mismatch rejects the promise.
+   * May also be supplied per-call to waitForCode.
+   */
+  expectedState?: string;
+}
+
+export interface WaitForCodeOptions {
+  /** Overrides the server-level expectedState for this call. */
+  expectedState?: string;
+  /** How long to wait for a callback before rejecting (default 5 minutes). */
+  timeoutMs?: number;
+  /** Optional abort signal to cancel the wait early. */
+  signal?: AbortSignal;
+}
+
+export interface CallbackCode {
+  code: string;
+  state: string;
+}
+
+export interface CallbackServerHandle {
+  /** Full redirect_uri to register with the provider (http://127.0.0.1:PORT/callback). */
+  url: string;
+  /** Actual bound port (useful when 0 was requested). */
+  port: number;
+  /** Resolve with {code, state} on a valid callback; reject on timeout/state mismatch. */
+  waitForCode(options?: WaitForCodeOptions): Promise<CallbackCode>;
+  /** Stop listening and free the port. Idempotent. */
+  close(): Promise<void>;
+}
+
+/**
+ * Start a loopback HTTP server that captures an OAuth authorization code.
+ * Pass port 0 to let the OS choose a free port (read handle.port afterwards).
+ */
+export function startCallbackServer(
+  port: number,
+  options: CallbackServerOptions = {},
+): Promise<CallbackServerHandle> {
+  return new Promise((resolve, reject) => {
+    const serverLevelState = options.expectedState;
+
+    // Deferred for the first valid callback (has a `code` param).
+    let captured: CallbackCode | null = null;
+    const waiters: Array<{
+      resolve: (value: CallbackCode) => void;
+      reject: (error: Error) => void;
+    }> = [];
+
+    const httpServer: Server = createServer(
+      (req: IncomingMessage, res: ServerResponse) => {
+        handleCallback(req, res);
+      },
+    );
+
+    function handleCallback(req: IncomingMessage, res: ServerResponse): void {
+      // Only respond to GET on the callback path; everything else 404s.
+      if (req.method !== "GET") {
+        res.writeHead(405, { "content-type": "text/plain; charset=utf-8" });
+        res.end("Method Not Allowed");
+        return;
+      }
+
+      let parsedUrl: URL;
+      try {
+        parsedUrl = new URL(req.url ?? "/", `http://${LOOPBACK_HOST}`);
+      } catch {
+        res.writeHead(400, { "content-type": "text/plain; charset=utf-8" });
+        res.end("Bad Request");
+        return;
+      }
+
+      const pathname = parsedUrl.pathname;
+      const code = parsedUrl.searchParams.get("code");
+      const state = parsedUrl.searchParams.get("state");
+      const error = parsedUrl.searchParams.get("error");
+
+      // OAuth error from the provider (e.g. user denied consent).
+      if (error) {
+        res.writeHead(400, { "content-type": "text/html; charset=utf-8" });
+        res.end(authorizationDeniedPage(error));
+        return;
+      }
+
+      if (pathname !== CALLBACK_PATH) {
+        res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+        res.end("Not Found");
+        return;
+      }
+
+      // Missing code -> provider returned nothing usable.
+      if (!code) {
+        res.writeHead(400, { "content-type": "text/html; charset=utf-8" });
+        res.end(missingCodePage());
+        return;
+      }
+
+      // Capture the first valid callback exactly once.
+      const callback: CallbackCode = { code, state: state ?? "" };
+      if (!captured) {
+        captured = callback;
+        // Resolve any pending waiters that accept this callback.
+        const pending = waiters.splice(0, waiters.length);
+        for (const w of pending) {
+          w.resolve(callback);
+        }
+      }
+
+      // Always show the user a friendly page; security validation happens in
+      // waitForCode (state may not be known at request time).
+      res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+      res.end(successPage());
+    }
+
+    httpServer.on("error", (err: NodeJS.ErrnoException) => {
+      reject(
+        new Error(
+          `Failed to start OAuth callback server on 127.0.0.1:${port}: ${err.message}`,
+          { cause: err },
+        ),
+      );
+    });
+
+    httpServer.listen(port, LOOPBACK_HOST, () => {
+      const address = httpServer.address();
+      const boundPort =
+        address && typeof address === "object" ? address.port : port;
+      const redirectUrl = `http://${LOOPBACK_HOST}:${boundPort}${CALLBACK_PATH}`;
+
+      const handle: CallbackServerHandle = {
+        url: redirectUrl,
+        port: boundPort,
+        waitForCode(waitOpts: WaitForCodeOptions = {}): Promise<CallbackCode> {
+          const expected =
+            waitOpts.expectedState !== undefined
+              ? waitOpts.expectedState
+              : serverLevelState;
+          const timeoutMs = waitOpts.timeoutMs ?? 5 * 60 * 1000;
+
+          return new Promise<CallbackCode>((resolveWait, rejectWait) => {
+            let settled = false;
+
+            const settle = (
+              outcome: CallbackCode | Error,
+              isReject: boolean,
+            ): void => {
+              if (settled) return;
+              settled = true;
+              clearTimeout(timer);
+              waitOpts.signal?.removeEventListener("abort", onAbort);
+              if (isReject) {
+                rejectWait(outcome as Error);
+              } else {
+                resolveWait(outcome as CallbackCode);
+              }
+            };
+
+            const onAbort = (): void => {
+              settle(
+                new Error("OAuth callback wait was aborted."),
+                true,
+              );
+            };
+
+            const timer = setTimeout(() => {
+              settle(new Error("OAuth login timed out waiting for callback."), true);
+            }, timeoutMs);
+
+            if (waitOpts.signal?.aborted) {
+              settle(new Error("OAuth callback wait was aborted."), true);
+              return;
+            }
+            waitOpts.signal?.addEventListener("abort", onAbort);
+
+            const resolveWith = (callback: CallbackCode): void => {
+              if (expected !== undefined && callback.state !== expected) {
+                settle(
+                  new Error(
+                    `OAuth state mismatch: expected "${redactState(expected)}" ` +
+                      `but received "${redactState(callback.state)}". ` +
+                      `This may indicate a CSRF attempt or a stale login tab.`,
+                  ),
+                  true,
+                );
+                return;
+              }
+              settle(callback, false);
+            };
+
+            if (captured) {
+              resolveWith(captured);
+              return;
+            }
+
+            waiters.push({ resolve: resolveWith, reject: rejectWait });
+          });
+        },
+        close(): Promise<void> {
+          return new Promise<void>((resolveClose) => {
+            httpServer.close(() => resolveClose());
+            // close() waits for in-flight connections; closeAllConnections is
+            // available on Node 18+ and speeds shutdown without dropping the
+            // response the user's browser is mid-receiving.
+            // (Not called here to keep the success page delivery intact.)
+          });
+        },
+      };
+
+      resolve(handle);
+    });
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Static HTML pages (ASCII-only, no secret material)
+// ---------------------------------------------------------------------------
+
+function successPage(): string {
+  return [
+    "<!doctype html>",
+    "<html lang=\"en\">",
+    "<head><meta charset=\"utf-8\"><title>OffRouter login</title></head>",
+    "<body>",
+    "<h1>OffRouter login authorized</h1>",
+    "<p>You can close this tab and return to your terminal.</p>",
+    "</body>",
+    "</html>",
+    "",
+  ].join("\n");
+}
+
+function authorizationDeniedPage(error: string): string {
+  const safe = escapeHtml(error);
+  return [
+    "<!doctype html>",
+    "<html lang=\"en\">",
+    "<head><meta charset=\"utf-8\"><title>OffRouter login</title></head>",
+    "<body>",
+    "<h1>OffRouter login not completed</h1>",
+    `<p>The provider reported: ${safe}</p>`,
+    "<p>You can close this tab and try again from your terminal.</p>",
+    "</body>",
+    "</html>",
+    "",
+  ].join("\n");
+}
+
+function missingCodePage(): string {
+  return [
+    "<!doctype html>",
+    "<html lang=\"en\">",
+    "<head><meta charset=\"utf-8\"><title>OffRouter login</title></head>",
+    "<body>",
+    "<h1>OffRouter login incomplete</h1>",
+    "<p>The callback did not include an authorization code.</p>",
+    "</body>",
+    "</html>",
+    "",
+  ].join("\n");
+}
+
+function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
+/** Truncate a state token for error messages so it is never echoed in full. */
+function redactState(state: string): string {
+  if (state.length <= 8) return "***";
+  return `${state.slice(0, 4)}...${state.slice(-4)}`;
+}

package/src/config.test.ts

@@ -157,7 +157,7 @@ enabled = true
     expect(config.policyDefaults.subscriptionFirst).toBe(true);
     expect(config.policyDefaults.allowApiKeyFallback).toBe(true);
     expect(config.providers).toEqual({
-      claude: { id: "claude", enabled: true },
+      claude: { id: "claude", enabled: true, accounts: [{ id: "claude" }] },
     });
 
     const allowed = evaluatePolicy(
@@ -168,6 +168,22 @@ enabled = true
     expect(allowed.allowed).toHaveLength(1);
   });
 
+  it("parses policy.near_limit_threshold into policy.nearLimitThreshold", async () => {
+    const home = await trackDir(makeHome);
+    await writeFile(
+      join(home, "config.toml"),
+      `allowlisted_profiles = ["claude-personal"]
+
+[policy]
+near_limit_threshold = 0.15
+`,
+      "utf8",
+    );
+
+    const config = await loadConfig({ env: { OFFROUTER_HOME: home } });
+    expect(config.policy.nearLimitThreshold).toBe(0.15);
+  });
+
   it("loads named profile overlays from profiles/*.toml", async () => {
     const home = await trackDir(makeHome);
     await writeFile(
@@ -323,7 +339,7 @@ enabled = true
       "project-enabled",
     ]);
     expect(trusted.providers).toEqual({
-      "project-agent": { id: "project-agent", enabled: true },
+      "project-agent": { id: "project-agent", enabled: true, accounts: [{ id: "project-agent" }] },
     });
     expect(trusted.sources).toContain(
       join(project, ".offrouter", "config.toml"),
@@ -412,4 +428,52 @@ weird_flag = 1
     expect(config.sources).toEqual([]);
     expect(config.warnings).toEqual([]);
   });
+
+  describe("multi-account provider config", () => {
+    it("parses TOML with explicit accounts array", async () => {
+      const home = await trackDir(makeHome);
+      await writeFile(
+        join(home, "config.toml"),
+        `
+allowlisted_profiles = ["claude-personal"]
+
+[[providers.anthropic.accounts]]
+id = "anthropic-1"
+label = "Work Account"
+
+[[providers.anthropic.accounts]]
+id = "anthropic-2"
+label = "Personal Account"
+`,
+        "utf8",
+      );
+
+      const config = await loadConfig({ env: { OFFROUTER_HOME: home } });
+      expect(config.providers.anthropic).toBeDefined();
+      expect(config.providers.anthropic.accounts).toEqual([
+        { id: "anthropic-1", label: "Work Account" },
+        { id: "anthropic-2", label: "Personal Account" },
+      ]);
+      expect(config.providers.anthropic.enabled).toBe(true);
+    });
+
+    it("creates implicit account when no accounts array is present", async () => {
+      const home = await trackDir(makeHome);
+      await writeFile(
+        join(home, "config.toml"),
+        `
+allowlisted_profiles = ["codex-personal"]
+
+[providers.openai]
+enabled = true
+`,
+        "utf8",
+      );
+
+      const config = await loadConfig({ env: { OFFROUTER_HOME: home } });
+      expect(config.providers.openai).toBeDefined();
+      expect(config.providers.openai.accounts).toEqual([{ id: "openai" }]);
+      expect(config.providers.openai.enabled).toBe(true);
+    });
+  });
 });

package/src/config.ts

@@ -20,6 +20,7 @@ export interface PolicyDefaults {
 export interface ConfiguredProvider {
   id: string;
   enabled: boolean;
+  accounts: ConfiguredAccount[];
 }
 
 /** Named profile overlay loaded from profiles/*.toml. */
@@ -30,6 +31,12 @@ export interface ConfiguredProfile {
   subscriptionFirst?: boolean;
 }
 
+/** Single configured account within a provider. */
+export interface ConfiguredAccount {
+  id: string;
+  label?: string;
+}
+
 export interface ConfigWarning {
   filePath: string;
   path: string;
@@ -94,6 +101,9 @@ function allowedFromZodShape(shape: z.ZodRawShape): AllowedShape {
 
 const ProviderConfigShape = {
   enabled: z.boolean().optional(),
+  accounts: z
+    .array(z.object({ id: z.string().min(1), label: z.string().optional() }).strict())
+    .optional(),
 } satisfies z.ZodRawShape;
 
 const PolicySectionShape = {
@@ -101,6 +111,7 @@ const PolicySectionShape = {
   allow_api_key_fallback: z.boolean().optional(),
   allow_third_party_subscription_adapters: z.boolean().optional(),
   denied_providers: z.array(z.string().min(1)).optional(),
+  near_limit_threshold: z.number().min(0).max(1).optional(),
 } satisfies z.ZodRawShape;
 
 const RootConfigShape = {
@@ -122,7 +133,10 @@ const ProfileFileShape = {
 const RootConfigSchema = z.object(RootConfigShape).strict();
 const ProfileFileSchema = z.object(ProfileFileShape).strict();
 
-const PROVIDER_ALLOWED: AllowedShape = allowedFromZodShape(ProviderConfigShape);
+const PROVIDER_ALLOWED: AllowedShape = {
+  ...allowedFromZodShape(ProviderConfigShape),
+  accounts: "leaf",
+};
 const ROOT_ALLOWED: AllowedShape = {
   ...allowedFromZodShape(RootConfigShape),
   policy: allowedFromZodShape(PolicySectionShape),
@@ -355,6 +369,9 @@ function mergeRootInto(
       target.policy.allowThirdPartySubscriptionAdapters =
         root.policy.allow_third_party_subscription_adapters;
     }
+    if (root.policy.near_limit_threshold !== undefined) {
+      target.policy.nearLimitThreshold = root.policy.near_limit_threshold;
+    }
     if (root.policy.denied_providers) {
       target.policy.deniedProviders = uniqueStrings([
         ...(target.policy.deniedProviders ?? []),
@@ -365,9 +382,13 @@ function mergeRootInto(
 
   if (root.providers) {
     for (const [id, provider] of Object.entries(root.providers)) {
+      const accounts: ConfiguredAccount[] = provider.accounts
+        ? provider.accounts.map((a: { id: string; label?: string }) => ({ id: a.id, label: a.label }))
+        : [{ id }];
       target.providers[id] = {
         id,
         enabled: provider.enabled ?? true,
+        accounts,
       };
     }
   }

package/src/index.ts

@@ -83,6 +83,7 @@ export {
   resolveOffRouterHome,
 } from "./config.js";
 export type {
+  ConfiguredAccount,
   ConfiguredProfile,
   ConfiguredProvider,
   ConfigWarning,
@@ -117,8 +118,16 @@ export type {
   MarkCancelledOptions,
 } from "./audit.js";
 
-export { InMemoryStateStore, InMemoryUsageStore } from "./usage.js";
+export { DEFAULT_NEAR_LIMIT_THRESHOLD, InMemoryStateStore, InMemoryUsageStore } from "./usage.js";
+export {
+  FileUsageStore,
+} from "./usage-file.js";
+export type {
+  FileUsageStoreFileSystem,
+  FileUsageStoreOptions,
+} from "./usage-file.js";
 export type {
+  AccountUsageSnapshot,
   InMemoryUsageStoreOptions,
   PaidFallbackExplanation,
   ProviderUsageSnapshot,
@@ -196,14 +205,21 @@ export type {
 // Auth module (credential chain, OAuth PKCE, keychain helpers)
 export {
   Redacted,
+  defaultCallbackPort,
+  deleteOAuthTokens,
   exchangeCodeForTokens,
   generateCodeChallenge,
   generateCodeVerifier,
+  getOAuthTokens,
   getProviderToken,
   isOAuthProvider,
+  isOAuthTokenExpired,
   PKCE_CONFIGS,
   refreshTokens,
+  resolveClientId,
   resolveCredential,
+  runOAuthLogin,
+  setOAuthTokens,
   setProviderToken,
   startOAuthFlow,
 } from "./auth/index.js";
@@ -213,10 +229,13 @@ export type {
   OAuthFlowResult,
   OAuthFlowState,
   OAuthProviderConfig,
+  OAuthStoredTokens,
   OAuthStartOptions,
   OAuthTokenOptions,
   OAuthTokenResponse,
   ResolveCredentialOptions,
+  RunOAuthLoginOptions,
+  RunOAuthLoginResult,
 } from "./auth/index.js";
 
 // OpenAI Responses-compatible local proxy

package/src/policy.ts

@@ -25,6 +25,8 @@ export interface PolicyConfig {
   allowThirdPartySubscriptionAdapters?: boolean;
   /** Optional explicit provider deny list by providerId. */
   deniedProviders?: string[];
+  /** Fraction of subscription quota remaining at/under which an account is "near-limit". Default 0.2. */
+  nearLimitThreshold?: number;
 }
 
 const HEALTHY_SUBSCRIPTION_STATUSES: ReadonlySet<SubscriptionStatus> = new Set([

package/src/providers/adapter.ts

@@ -209,6 +209,7 @@ export interface AuthStatus {
   subscriptionStatus?: SubscriptionStatus;
   limitsDiscoverable: boolean;
   health: ProviderHealth;
+  accountId?: string;
   detail?: string;
   /**
    * Which credential source satisfied auth (if any).
@@ -231,6 +232,7 @@ export interface LimitSnapshot {
   limit?: number;
   resetAt?: string;
   unit?: string;
+  accountId?: string;
   metadata?: Record<string, string | number | boolean | null>;
 }
 
@@ -320,5 +322,7 @@ export function capabilityToCandidate(
     contextWindowTokens: capability.contextWindowTokens,
     maxOutputTokens: capability.maxOutputTokens,
     estimatedCostUsd: extras.estimatedCostUsd ?? capability.estimatedCostUsd,
+    accountId: extras.accountId,
+    subscriptionQuotaPercentRemaining: extras.subscriptionQuotaPercentRemaining,
   };
 }

package/src/router.test.ts

@@ -559,4 +559,141 @@ describe("routeRequest", () => {
       expect(decision.auditSummary).not.toContain("raw user text");
     }
   });
+
+  describe("multi-account routing", () => {
+    it("selects first healthy subscription when two accounts have same rank", () => {
+      const decision = routeRequest(
+        baseRequest({
+          constraints: { subscriptionFirst: true, allowApiKeyFallback: false },
+        }),
+        [
+          candidate({
+            providerId: "anthropic",
+            modelId: "sonnet",
+            authTier: "subscription",
+            subscriptionStatus: "active",
+            health: "healthy",
+            accountId: "anthropic-1",
+            estimatedCostUsd: 0,
+          }),
+          candidate({
+            providerId: "anthropic",
+            modelId: "sonnet",
+            authTier: "subscription",
+            subscriptionStatus: "active",
+            health: "healthy",
+            accountId: "anthropic-2",
+            estimatedCostUsd: 0,
+          }),
+        ],
+        personalConfig,
+      );
+
+      expect(decision.blocked).toBeFalsy();
+      // Same rankKey, stable sort by input order: first candidate wins
+      expect(decision.route?.accountId).toBe("anthropic-1");
+    });
+
+    it("skips exhausted account and picks the next healthy one", () => {
+      const decision = routeRequest(
+        baseRequest({
+          constraints: { subscriptionFirst: true, allowApiKeyFallback: true },
+        }),
+        [
+          candidate({
+            providerId: "anthropic",
+            modelId: "sonnet",
+            authTier: "subscription",
+            subscriptionStatus: "exhausted",
+            health: "healthy",
+            accountId: "anthropic-1",
+            estimatedCostUsd: 0,
+          }),
+          candidate({
+            providerId: "anthropic",
+            modelId: "sonnet",
+            authTier: "subscription",
+            subscriptionStatus: "active",
+            health: "healthy",
+            accountId: "anthropic-2",
+            estimatedCostUsd: 0,
+          }),
+        ],
+        personalConfig,
+      );
+
+      expect(decision.blocked).toBeFalsy();
+      expect(decision.route?.accountId).toBe("anthropic-2");
+    });
+
+    it("prefers healthy active account over near-limit account", () => {
+      const decision = routeRequest(
+        baseRequest({
+          constraints: { subscriptionFirst: true, allowApiKeyFallback: false },
+        }),
+        [
+          candidate({
+            providerId: "anthropic",
+            modelId: "sonnet",
+            authTier: "subscription",
+            subscriptionStatus: "near-limit",
+            subscriptionQuotaPercentRemaining: 15,
+            health: "healthy",
+            accountId: "anthropic-1",
+            estimatedCostUsd: 0,
+          }),
+          candidate({
+            providerId: "anthropic",
+            modelId: "sonnet",
+            authTier: "subscription",
+            subscriptionStatus: "active",
+            health: "healthy",
+            accountId: "anthropic-2",
+            estimatedCostUsd: 0,
+          }),
+        ],
+        personalConfig,
+      );
+
+      expect(decision.blocked).toBeFalsy();
+      expect(decision.route?.accountId).toBe("anthropic-2");
+      expect(decision.nearLimitWarning).toBeUndefined();
+    });
+
+    it("selects near-limit subscription when no healthy alternative exists and warns", () => {
+      const decision = routeRequest(
+        baseRequest({
+          constraints: { subscriptionFirst: true, allowApiKeyFallback: true },
+        }),
+        [
+          candidate({
+            providerId: "anthropic",
+            modelId: "sonnet",
+            authTier: "subscription",
+            subscriptionStatus: "near-limit",
+            subscriptionQuotaPercentRemaining: 15,
+            health: "healthy",
+            accountId: "anthropic-1",
+            estimatedCostUsd: 0,
+          }),
+          candidate({
+            providerId: "openrouter",
+            modelId: "fast",
+            authTier: "api-key",
+            authScope: "third-party",
+            estimatedCostUsd: 0.01,
+          }),
+        ],
+        personalConfig,
+      );
+
+      expect(decision.blocked).toBeFalsy();
+      expect(decision.route?.accountId).toBe("anthropic-1");
+      expect(decision.nearLimitWarning).toBeTruthy();
+      expect(decision.nearLimitWarning).toContain("near its limit");
+      expect(decision.explanation).toContain("near its limit");
+      expect(decision.route?.provider).toBe("anthropic");
+      expect(decision.route?.model).toBe("sonnet");
+    });
+  });
 });