offrouter-core 0.1.0 → 0.2.0

package/src/auth/oauth-pkce.ts

@@ -10,6 +10,8 @@
 import { randomBytes } from "node:crypto";
 import type { SecretStore } from "../secrets.js";
 import { Redacted } from "./credential-chain.js";
+import { setOAuthTokens } from "./keychain.js";
+import { startCallbackServer } from "./oauth-server.js";
 
 // ---------------------------------------------------------------------------
 // PKCE code generation
@@ -312,15 +314,22 @@ export async function exchangeCodeForTokens(
     );
   }
 
-  // Store tokens in secret store
+  // Store tokens in secret store (structured)
   if (options.store) {
-    await options.store.set(`${provider}_access_token`, json.access_token);
-    if (json.refresh_token) {
-      await options.store.set(
-        `${provider}_refresh_token`,
-        json.refresh_token,
-      );
-    }
+    const obtainedAt = Date.now();
+    await setOAuthTokens(
+      provider,
+      {
+        accessToken: json.access_token,
+        refreshToken: json.refresh_token,
+        expiresAt: json.expires_in
+          ? obtainedAt + json.expires_in * 1000
+          : undefined,
+        scope: json.scope,
+        obtainedAt,
+      },
+      options.store,
+    );
   }
 
   return {
@@ -333,6 +342,149 @@ export async function exchangeCodeForTokens(
   };
 }
 
+// ---------------------------------------------------------------------------
+// Login orchestration (callback server + browser + token exchange)
+// ---------------------------------------------------------------------------
+
+/** Default loopback ports for supported providers. */
+const DEFAULT_CALLBACK_PORTS: Record<string, number> = {
+  anthropic: 1456,
+  openai: 1455,
+};
+
+/**
+ * Return the default callback port for a provider, or 0 (OS-assigned).
+ */
+export function defaultCallbackPort(provider: string): number {
+  return DEFAULT_CALLBACK_PORTS[provider] ?? 0;
+}
+
+/**
+ * Resolve the client id for a provider from process env (or a provided env
+ * override). Returns undefined if the env var is not set.
+ */
+export function resolveClientId(
+  provider: string,
+  env: NodeJS.ProcessEnv = process.env,
+): string | undefined {
+  const config = PKCE_CONFIGS[provider];
+  if (!config?.clientIdEnvVar) return undefined;
+  return env[config.clientIdEnvVar] ?? undefined;
+}
+
+export interface RunOAuthLoginOptions {
+  provider: string;
+  store: SecretStore;
+  /** Override client id (else resolved from env / PKCE_CONFIGS). */
+  clientId?: string;
+  /** Loopback port (defaults to provider default or 0). */
+  port?: number;
+  /** Wait timeout in ms (default 5 min). */
+  timeoutMs?: number;
+  /** Called with the authorize URL once built (test/display). */
+  onAuthorizeUrl?: (url: string) => void;
+  /** Best-effort browser open (non-throwing). */
+  openBrowser?: (url: string) => Promise<boolean> | boolean;
+  /** Injectable fetch (tests). */
+  fetch?: typeof globalThis.fetch;
+  /** Optional abort signal. */
+  signal?: AbortSignal;
+}
+
+export interface RunOAuthLoginResult {
+  provider: string;
+  redirectUri: string;
+  expiresAt?: number;
+  scope?: string;
+}
+
+/**
+ * Run the full OAuth PKCE login flow:
+ * 1. Start a local callback server on 127.0.0.1
+ * 2. Build the authorize URL with PKCE challenge + state
+ * 3. Notify caller (onAuthorizeUrl) and attempt browser open
+ * 4. Wait for the provider callback (code + state)
+ * 5. Exchange code for tokens
+ * 6. Store structured tokens in the secret store
+ * 7. Clean up the server
+ */
+export async function runOAuthLogin(
+  opts: RunOAuthLoginOptions,
+): Promise<RunOAuthLoginResult> {
+  const config = PKCE_CONFIGS[opts.provider];
+  if (!config) {
+    throw new Error(
+      `OAuth not supported for provider: ${opts.provider}. ` +
+        `OAuth is only available for anthropic and openai providers.`,
+    );
+  }
+
+  const clientId =
+    opts.clientId ?? resolveClientId(opts.provider) ?? undefined;
+  if (!clientId) {
+    const envHint =
+      config.clientIdEnvVar
+        ? `Set the ${config.clientIdEnvVar} environment variable or pass it explicitly.`
+        : "A client id is required for this provider.";
+    throw new Error(
+      `Client ID required for ${opts.provider} OAuth. ${envHint}`,
+    );
+  }
+
+  // 1. Start callback server
+  const port = opts.port ?? defaultCallbackPort(opts.provider);
+  const server = await startCallbackServer(port);
+
+  try {
+    const redirectUri = server.url;
+
+    // 2. Build the authorize URL with PKCE
+    const flow = await startOAuthFlow(opts.provider, {
+      redirectUri,
+      clientId,
+    });
+
+    // 3. Notify and attempt to open browser
+    opts.onAuthorizeUrl?.(flow.authorizeUrl);
+    if (opts.openBrowser) {
+      try {
+        await opts.openBrowser(flow.authorizeUrl);
+      } catch {
+        // Best-effort only.
+      }
+    }
+
+    // 4. Wait for callback (validates expected state)
+    const { code } = await server.waitForCode({
+      expectedState: flow.state,
+      timeoutMs: opts.timeoutMs,
+      signal: opts.signal,
+    });
+
+    // 5. Exchange code for tokens (also stores them)
+    const tokens = await exchangeCodeForTokens(opts.provider, code, flow.state, {
+      store: opts.store,
+      fetch: opts.fetch,
+    });
+
+    // 6. Tokens are already stored by exchangeCodeForTokens.
+    //    Compute expiresAt from expiresIn for the result.
+    const expiresAt = tokens.expiresIn
+      ? Date.now() + tokens.expiresIn * 1000
+      : undefined;
+
+    return {
+      provider: opts.provider,
+      redirectUri,
+      expiresAt,
+      scope: tokens.scope,
+    };
+  } finally {
+    // 7. Clean up
+    await server.close();
+  }
+}
+
 /**
  * Refresh an OAuth token using a refresh token.
  * Updates the stored tokens on success.
@@ -392,11 +544,21 @@ export async function refreshTokens(
     );
   }
 
-  // Update stored tokens
-  await store.set(`${provider}_access_token`, json.access_token);
-  if (json.refresh_token) {
-    await store.set(`${provider}_refresh_token`, json.refresh_token);
-  }
+  // Update stored tokens (structured)
+  const obtainedAt = Date.now();
+  await setOAuthTokens(
+    provider,
+    {
+      accessToken: json.access_token,
+      refreshToken: json.refresh_token,
+      expiresAt: json.expires_in
+        ? obtainedAt + json.expires_in * 1000
+        : undefined,
+      scope: json.scope,
+      obtainedAt,
+    },
+    store,
+  );
 
   return {
     accessToken: new Redacted(json.access_token),

package/src/auth/oauth-server.test.ts

@@ -0,0 +1,83 @@
+/**
+ * Tests for the local OAuth callback server.
+ * No real OAuth: we hit the callback URL directly over HTTP.
+ */
+import { describe, expect, it } from "vitest";
+import { startCallbackServer } from "./oauth-server.js";
+
+describe("startCallbackServer", () => {
+  it("binds to 127.0.0.1 and exposes a localhost redirect URL", async () => {
+    const server = await startCallbackServer(0);
+    try {
+      expect(server.url).toContain("127.0.0.1");
+      expect(server.url).toMatch(/^http:\/\/127\.0\.0\.1:\d+\/callback$/);
+      expect(server.port).toBeGreaterThan(0);
+    } finally {
+      await server.close();
+    }
+  });
+
+  it("captures the authorization code from a matching callback", async () => {
+    const server = await startCallbackServer(0);
+    try {
+      const waitPromise = server.waitForCode({
+        expectedState: "state-abc",
+        timeoutMs: 2000,
+      });
+      const res = await fetch(`${server.url}?code=AUTHCODE123&state=state-abc`);
+      expect(res.status).toBe(200);
+      const body = await res.text();
+      expect(body).toMatch(/success|complete|authorized/i);
+
+      const result = await waitPromise;
+      expect(result.code).toBe("AUTHCODE123");
+      expect(result.state).toBe("state-abc");
+    } finally {
+      await server.close();
+    }
+  });
+
+  it("rejects a callback with a mismatched state", async () => {
+    const server = await startCallbackServer(0);
+    try {
+      const waitPromise = server.waitForCode({
+        expectedState: "expected-state",
+        timeoutMs: 2000,
+      });
+      // Attach the rejection handler before triggering the callback so the
+      // rejection is never momentarily unhandled.
+      const assertion = expect(waitPromise).rejects.toThrow(/state/i);
+      await fetch(`${server.url}?code=CODE&state=wrong-state`);
+      await assertion;
+    } finally {
+      await server.close();
+    }
+  });
+
+  it("rejects when no callback arrives before the timeout", async () => {
+    const server = await startCallbackServer(0);
+    try {
+      await expect(
+        server.waitForCode({ timeoutMs: 50 }),
+      ).rejects.toThrow(/timed out|timeout/i);
+    } finally {
+      await server.close();
+    }
+  });
+
+  it("returns an error page for callbacks missing the code", async () => {
+    const server = await startCallbackServer(0);
+    try {
+      const res = await fetch(`${server.url}?state=only-state`);
+      expect(res.status).toBe(400);
+    } finally {
+      await server.close();
+    }
+  });
+
+  it("close is idempotent and releases the port", async () => {
+    const server = await startCallbackServer(0);
+    await server.close();
+    await expect(server.close()).resolves.toBeUndefined();
+  });
+});

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