offrouter-core 0.1.0 → 0.2.1

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

@@ -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(

package/src/config.ts

@@ -111,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 = {
@@ -368,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 ?? []),

package/src/index.ts

@@ -119,6 +119,13 @@ export type {
 } from "./audit.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,
@@ -198,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";
@@ -215,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/usage-file.test.ts

@@ -0,0 +1,243 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { mkdir, mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  DEFAULT_NEAR_LIMIT_THRESHOLD,
+  FileUsageStore,
+  InMemoryUsageStore,
+  type UsageStore,
+} from "./usage-file.js";
+
+const tempDirs: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(
+    tempDirs.splice(0).map((dir) => rm(dir, { recursive: true, force: true })),
+  );
+},);
+
+async function makeTempDir(): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), "offrouter-usage-file-"));
+  tempDirs.push(dir);
+  return dir;
+}
+
+async function makeFileStore(
+  filePath?: string,
+): Promise<{ dir: string; path: string; store: FileUsageStore }> {
+  const dir = await makeTempDir();
+  const path = filePath ?? join(dir, "state", "usage.json");
+  const store = new FileUsageStore({ filePath: path });
+  return { dir, path, store };
+}
+
+describe("FileUsageStore", () => {
+  it("satisfies the UsageStore interface contract", () => {
+    const store: UsageStore = new FileUsageStore({
+      filePath: "/tmp/offrouter-usage-store-interface.json",
+    });
+    expect(typeof store.recordUsage).toBe("function");
+    expect(typeof store.isNearLimit).toBe("function");
+    expect(typeof store.record).toBe("function");
+  });
+
+  it("persists account usage across store instances sharing the same file", async () => {
+    const { path, store } = await makeFileStore();
+    await store.recordUsage("anthropic", "anthropic-1", {
+      used: 42,
+      limit: 100,
+    });
+
+    const reloaded = new FileUsageStore({ filePath: path });
+    const snap = await reloaded.getAccountUsage("anthropic", "anthropic-1");
+    expect(snap?.used).toBe(42);
+    expect(snap?.limit).toBe(100);
+    expect(snap?.remaining).toBe(58);
+
+    // A fresh instance also sees near-limit state.
+    expect(await reloaded.isNearLimit("anthropic", "anthropic-1")).toBe(false);
+  });
+
+  it("marks an account near-limit at 85% consumed (threshold 0.2)", async () => {
+    const { store } = await makeFileStore();
+    const snap = await store.recordUsage("anthropic", "anthropic-1", {
+      used: 85,
+      limit: 100,
+    });
+    expect(snap.remaining).toBe(15);
+    expect(snap.percentRemaining).toBe(15);
+    expect(snap.nearLimit).toBe(true);
+    expect(snap.subscriptionStatus).toBe("near-limit");
+    expect(await store.isNearLimit("anthropic", "anthropic-1")).toBe(true);
+  });
+
+  it("does not mark an account near-limit at 50% consumed", async () => {
+    const { store } = await makeFileStore();
+    const snap = await store.recordUsage("anthropic", "anthropic-1", {
+      used: 50,
+      limit: 100,
+    });
+    expect(snap.nearLimit).toBe(false);
+    expect(snap.subscriptionStatus).toBe("active");
+    expect(await store.isNearLimit("anthropic", "anthropic-1")).toBe(false);
+  });
+
+  it("respects a custom near-limit threshold", async () => {
+    const { store } = await makeFileStore();
+    await store.recordUsage("anthropic", "anthropic-1", {
+      used: 85,
+      limit: 100,
+    });
+    // 15% remaining: near-limit at 0.2 default, not at stricter 0.1.
+    expect(await store.isNearLimit("anthropic", "anthropic-1")).toBe(true);
+    expect(await store.isNearLimit("anthropic", "anthropic-1", 0.1)).toBe(false);
+  });
+
+  it("marks an account exhausted at 100% consumed with dead health", async () => {
+    const { store } = await makeFileStore();
+    const snap = await store.recordUsage("anthropic", "anthropic-1", {
+      used: 100,
+      limit: 100,
+    });
+    expect(snap.subscriptionStatus).toBe("exhausted");
+    expect(snap.nearLimit).toBe(false);
+    expect(snap.health).toBe("dead");
+  });
+
+  it("writes the usage file with mode 0600 on POSIX", async () => {
+    if (process.platform === "win32") {
+      return;
+    }
+    const { path, store } = await makeFileStore();
+    await store.recordUsage("anthropic", "anthropic-1", {
+      used: 1,
+      limit: 100,
+    });
+
+    const info = await stat(path);
+    expect(info.mode & 0o777).toBe(0o600);
+  });
+
+  it("falls back to an empty state on a corrupt file instead of crashing", async () => {
+    const dir = await makeTempDir();
+    const path = join(dir, "state", "usage.json");
+    await mkdir(join(dir, "state"), { recursive: true });
+    await writeFile(path, "{not valid json at all", "utf8");
+
+    const store = new FileUsageStore({ filePath: path });
+    // Reads do not throw; state is empty.
+    const snap = await store.getAccountUsage("anthropic", "anthropic-1");
+    expect(snap).toBeUndefined();
+    expect(await store.listAccountUsage()).toEqual([]);
+
+    // A subsequent write replaces the corrupt file with a valid document.
+    await store.recordUsage("anthropic", "anthropic-1", {
+      used: 90,
+      limit: 100,
+    });
+    const raw = JSON.parse(await readFile(path, "utf8")) as {
+      version: number;
+      accounts: Record<string, unknown>;
+    };
+    expect(raw.version).toBe(1);
+    expect(Object.keys(raw.accounts)).toEqual(["anthropic:anthropic-1"]);
+  });
+
+  it("concurrent writes from two stores on the same file do not corrupt it", async () => {
+    const dir = await makeTempDir();
+    const path = join(dir, "state", "usage.json");
+    const s1 = new FileUsageStore({ filePath: path });
+    const s2 = new FileUsageStore({ filePath: path });
+
+    await Promise.all([
+      s1.recordUsage("anthropic", "anthropic-1", { used: 80, limit: 100 }),
+      s2.recordUsage("openai", "openai-1", { used: 90, limit: 100 }),
+    ]);
+
+    // The file is always valid JSON with the expected schema.
+    const raw = JSON.parse(await readFile(path, "utf8")) as {
+      version: number;
+      accounts: Record<string, { providerId: string }>;
+    };
+    expect(raw.version).toBe(1);
+    // Last-writer-wins is acceptable; corruption (invalid JSON) is not.
+    for (const doc of Object.values(raw.accounts)) {
+      expect(typeof doc.providerId).toBe("string");
+    }
+  });
+
+  it("writes on every mutation so a new process sees the latest usage", async () => {
+    const { path, store } = await makeFileStore();
+    await store.recordUsage("anthropic", "anthropic-1", {
+      used: 10,
+      limit: 100,
+    });
+    await store.recordUsage("anthropic", "anthropic-1", {
+      used: 88,
+      limit: 100,
+    });
+
+    const reloaded = new FileUsageStore({ filePath: path });
+    const snap = await reloaded.getAccountUsage("anthropic", "anthropic-1");
+    expect(snap?.used).toBe(88);
+    expect(snap?.nearLimit).toBe(true);
+  });
+
+  it("delegates provider health/quota logic to an in-memory store", async () => {
+    const { store } = await makeFileStore();
+    await store.setSubscriptionQuota("claude", {
+      limit: 10,
+      used: 9,
+      status: "active",
+    });
+    const snap = await store.getProvider("claude");
+    expect(snap?.subscriptionQuotaRemaining).toBe(1);
+    expect(snap?.health).toBe("healthy");
+  });
+
+  it("returns near-limit accounts across the persisted set", async () => {
+    const { store } = await makeFileStore();
+    await store.recordUsage("anthropic", "anthropic-1", {
+      used: 85,
+      limit: 100,
+    });
+    await store.recordUsage("anthropic", "anthropic-2", {
+      used: 10,
+      limit: 100,
+    });
+    const near = await store.getNearLimitAccounts();
+    expect(near).toHaveLength(1);
+    expect(near[0]?.accountId).toBe("anthropic-1");
+  });
+
+  it("toJSON exposes diagnostics without throwing", async () => {
+    const { store } = await makeFileStore();
+    await store.recordUsage("anthropic", "anthropic-1", {
+      used: 85,
+      limit: 100,
+    });
+    const json = store.toJSON();
+    expect(json).toMatchObject({ kind: "file-usage" });
+    expect(JSON.stringify(json)).not.toContain("anthropic-1");
+  });
+
+  it("uses the default near-limit threshold constant", () => {
+    expect(DEFAULT_NEAR_LIMIT_THRESHOLD).toBe(0.2);
+  });
+
+  it("accepts an injected in-memory delegate for provider state", async () => {
+    const dir = await makeTempDir();
+    const path = join(dir, "state", "usage.json");
+    const delegate = new InMemoryUsageStore();
+    const wired = new FileUsageStore({ filePath: path, delegate });
+    await wired.setSubscriptionQuota("claude", {
+      limit: 5,
+      used: 1,
+      status: "active",
+    });
+    // Provider state lives on the injected delegate.
+    const snap = await delegate.getProvider("claude");
+    expect(snap?.subscriptionQuotaRemaining).toBe(4);
+  });
+});