@blackbelt-technology/pi-agent-dashboard 0.5.0 → 0.5.2

package/packages/server/src/model-proxy/__tests__/api-key-store.test.ts

@@ -0,0 +1,142 @@
+import { describe, it, expect } from "vitest";
+import {
+  hashKey,
+  verifyKey,
+  generateKey,
+  findApiKey,
+  recordKeyUsage,
+  keyHasScope,
+  type FindResult,
+} from "../api-key-store.js";
+import type { ProxyApiKey, ModelProxyConfig } from "@blackbelt-technology/pi-dashboard-shared/config.js";
+
+function makeConfig(apiKeys: ProxyApiKey[]): ModelProxyConfig {
+  return {
+    enabled: true,
+    maxConcurrentStreams: 16,
+    perKeyConcurrentStreams: 4,
+    logRequests: false,
+    apiKeys,
+  };
+}
+
+function makeKey(overrides: Partial<ProxyApiKey> & { cleartext: string }): { entry: ProxyApiKey; cleartext: string } {
+  const { cleartext, ...rest } = overrides;
+  return {
+    cleartext,
+    entry: {
+      id: "k1",
+      label: "test",
+      hash: hashKey(cleartext),
+      createdAt: 1000,
+      ...rest,
+    },
+  };
+}
+
+describe("hashKey / verifyKey", () => {
+  it("hashKey produces consistent sha256 hex", () => {
+    const h = hashKey("pi-proxy-abc123");
+    expect(h).toHaveLength(64); // sha256 hex
+    expect(h).toBe(hashKey("pi-proxy-abc123"));
+  });
+
+  it("verifyKey returns true for matching key", () => {
+    const key = "pi-proxy-test";
+    expect(verifyKey(key, hashKey(key))).toBe(true);
+  });
+
+  it("verifyKey returns false for wrong key", () => {
+    expect(verifyKey("wrong", hashKey("right"))).toBe(false);
+  });
+});
+
+describe("generateKey", () => {
+  it("returns pi-proxy- prefixed key", () => {
+    const key = generateKey();
+    expect(key).toMatch(/^pi-proxy-[A-Za-z0-9_-]{48}$/);
+  });
+
+  it("generates unique keys", () => {
+    const keys = new Set(Array.from({ length: 10 }, generateKey));
+    expect(keys.size).toBe(10);
+  });
+});
+
+describe("findApiKey", () => {
+  it("returns valid entry on match", () => {
+    const { entry, cleartext } = makeKey({ cleartext: generateKey() });
+    const config = makeConfig([entry]);
+    const result = findApiKey(cleartext, config);
+    expect(result.kind).toBe("valid");
+    expect((result as Extract<FindResult, { kind: "valid" }>).entry.id).toBe("k1");
+  });
+
+  it("returns miss on no match", () => {
+    const config = makeConfig([]);
+    expect(findApiKey("pi-proxy-unknown", config).kind).toBe("miss");
+  });
+
+  it("returns revoked for revoked key", () => {
+    const { entry, cleartext } = makeKey({ cleartext: generateKey(), revokedAt: Date.now() });
+    const config = makeConfig([entry]);
+    expect(findApiKey(cleartext, config).kind).toBe("revoked");
+  });
+
+  it("returns expired for expired key", () => {
+    const { entry, cleartext } = makeKey({ cleartext: generateKey(), expiresAt: Date.now() - 1000 });
+    const config = makeConfig([entry]);
+    expect(findApiKey(cleartext, config).kind).toBe("expired");
+  });
+
+  it("returns valid for non-expired key", () => {
+    const { entry, cleartext } = makeKey({ cleartext: generateKey(), expiresAt: Date.now() + 60_000 });
+    const config = makeConfig([entry]);
+    expect(findApiKey(cleartext, config).kind).toBe("valid");
+  });
+});
+
+describe("recordKeyUsage", () => {
+  it("updates lastUsedAt on first use", () => {
+    const { entry } = makeKey({ cleartext: generateKey() });
+    const now = Date.now();
+    const { updated, apiKeys } = recordKeyUsage(entry.id, [entry], now);
+    expect(updated).toBe(true);
+    expect(apiKeys[0].lastUsedAt).toBe(now);
+  });
+
+  it("debounces within 60s", () => {
+    const { entry } = makeKey({ cleartext: generateKey(), lastUsedAt: 1000 });
+    const { updated } = recordKeyUsage(entry.id, [entry], 1000 + 30_000);
+    expect(updated).toBe(false);
+  });
+
+  it("updates after debounce window", () => {
+    const { entry } = makeKey({ cleartext: generateKey(), lastUsedAt: 1000 });
+    const now = 1000 + 61_000;
+    const { updated, apiKeys } = recordKeyUsage(entry.id, [entry], now);
+    expect(updated).toBe(true);
+    expect(apiKeys[0].lastUsedAt).toBe(now);
+  });
+});
+
+describe("keyHasScope", () => {
+  it("\"all\" matches any scope", () => {
+    const { entry } = makeKey({ cleartext: generateKey(), scopes: ["all"] });
+    expect(keyHasScope(entry, "models:list")).toBe(true);
+    expect(keyHasScope(entry, "chat")).toBe(true);
+    expect(keyHasScope(entry, "messages")).toBe(true);
+  });
+
+  it("specific scope matches only that scope", () => {
+    const { entry } = makeKey({ cleartext: generateKey(), scopes: ["models:list"] });
+    expect(keyHasScope(entry, "models:list")).toBe(true);
+    expect(keyHasScope(entry, "chat")).toBe(false);
+  });
+
+  it("default scopes (undefined) acts as [\"all\"]", () => {
+    const { entry } = makeKey({ cleartext: generateKey() });
+    delete (entry as any).scopes;
+    expect(keyHasScope(entry, "chat")).toBe(true);
+  });
+});

package/packages/server/src/model-proxy/__tests__/auth-json-contention.test.ts

@@ -0,0 +1,98 @@
+/**
+ * Acceptance test for the single-writer auth.json contract (task 2.12).
+ *
+ * Simulates concurrent credential writes from:
+ *   (a) InternalAuthStorage (dashboard side) via writeCredential
+ *   (b) A stub bridge-side AuthStorage.refresh (simulated via writeCredential
+ *       from a separate "context")
+ *
+ * Asserts:
+ *   - File remains valid JSON after concurrent writes
+ *   - Both writes' fields survive (last-writer-wins for overlapping provider;
+ *     non-overlapping providers preserved)
+ *
+ * Cap: 5s timeout.
+ */
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { writeCredential, readAuthJson } from "../../provider-auth-storage.js";
+
+const AUTH_DIR = path.join(os.homedir(), ".pi", "agent");
+const AUTH_PATH = path.join(AUTH_DIR, "auth.json");
+
+let backup: string | null = null;
+beforeEach(() => {
+  fs.mkdirSync(AUTH_DIR, { recursive: true });
+  try { backup = fs.readFileSync(AUTH_PATH, "utf-8"); } catch { backup = null; }
+});
+
+afterEach(() => {
+  try {
+    if (backup !== null) fs.writeFileSync(AUTH_PATH, backup);
+    else fs.rmSync(AUTH_PATH, { force: true });
+  } catch {}
+});
+
+describe("auth.json single-writer contract (task 2.12)", () => {
+  it("sequential writes produce valid JSON with all fields", () => {
+    // Write provider A from "dashboard" side
+    writeCredential("anthropic", { type: "oauth", refresh: "r1", access: "a1", expires: Date.now() + 3600_000 });
+    // Write provider B from "bridge" side (simulated as a second writeCredential)
+    writeCredential("openai", { type: "api_key", key: "sk-test" });
+
+    const data = readAuthJson();
+    expect(data["anthropic"]).toBeDefined();
+    expect(data["openai"]).toBeDefined();
+    expect(data["anthropic"].type).toBe("oauth");
+    expect(data["openai"].type).toBe("api_key");
+  });
+
+  it("concurrent writes from two 'processes' leave valid JSON", async () => {
+    // Pre-populate with initial state
+    writeCredential("anthropic", { type: "oauth", refresh: "r0", access: "a0", expires: Date.now() + 100 });
+    writeCredential("openai", { type: "api_key", key: "sk-old" });
+
+    // Simulate two concurrent writes
+    const write1 = new Promise<void>((resolve) => {
+      setTimeout(() => {
+        writeCredential("anthropic", { type: "oauth", refresh: "r1", access: "a1", expires: Date.now() + 3600_000 });
+        resolve();
+      }, 0);
+    });
+
+    const write2 = new Promise<void>((resolve) => {
+      setTimeout(() => {
+        writeCredential("openai", { type: "api_key", key: "sk-new" });
+        resolve();
+      }, 0);
+    });
+
+    await Promise.all([write1, write2]);
+
+    // File must still be valid JSON
+    const raw = fs.readFileSync(AUTH_PATH, "utf-8");
+    let data: any;
+    expect(() => { data = JSON.parse(raw); }).not.toThrow();
+
+    // Non-overlapping providers both survived (one or both may be latest version)
+    expect(data["anthropic"]).toBeDefined();
+    expect(data["openai"]).toBeDefined();
+  }, 5000);
+
+  it("overlapping provider write: last writer wins, other provider preserved", () => {
+    // Initial state
+    writeCredential("anthropic", { type: "oauth", refresh: "r0", access: "a0", expires: 1 });
+    writeCredential("gemini", { type: "api_key", key: "gk-original" });
+
+    // Refresh anthropic (simulates InternalAuthStorage OAuth refresh)
+    writeCredential("anthropic", { type: "oauth", refresh: "r1", access: "a1", expires: Date.now() + 3600_000 });
+
+    const data = readAuthJson();
+    // anthropic updated
+    expect((data["anthropic"] as any).refresh).toBe("r1");
+    // gemini unchanged
+    expect((data["gemini"] as any).key).toBe("gk-original");
+  });
+});

package/packages/server/src/model-proxy/__tests__/concurrency.test.ts

@@ -0,0 +1,107 @@
+import { describe, it, expect } from "vitest";
+import { ConcurrencyTracker, ConcurrencyError } from "../concurrency.js";
+import type { ModelProxyConfig } from "@blackbelt-technology/pi-dashboard-shared/config.js";
+
+function makeConfig(overrides?: Partial<ModelProxyConfig>): ModelProxyConfig {
+  return {
+    enabled: true,
+    maxConcurrentStreams: 2,
+    perKeyConcurrentStreams: 1,
+    logRequests: false,
+    apiKeys: [],
+    ...overrides,
+  };
+}
+
+describe("ConcurrencyTracker", () => {
+  it("acquires and releases normally", () => {
+    const t = new ConcurrencyTracker();
+    const config = makeConfig();
+    const release = t.acquire({ apiKeyId: "k1", provider: "openai" }, config);
+    expect(typeof release).toBe("function");
+    release();
+  });
+
+  it("server cap exhausts → SERVER_FULL", () => {
+    const t = new ConcurrencyTracker();
+    const config = makeConfig({ maxConcurrentStreams: 2, perKeyConcurrentStreams: 10 });
+    t.acquire({ apiKeyId: "k1", provider: "a" }, config);
+    t.acquire({ apiKeyId: "k2", provider: "b" }, config);
+    expect(() => t.acquire({ apiKeyId: "k3", provider: "c" }, config)).toThrow(ConcurrencyError);
+    try {
+      t.acquire({ apiKeyId: "k3", provider: "c" }, config);
+    } catch (e) {
+      expect((e as ConcurrencyError).code).toBe("SERVER_FULL");
+    }
+  });
+
+  it("per-key cap exhausts → KEY_FULL", () => {
+    const t = new ConcurrencyTracker();
+    const config = makeConfig({ maxConcurrentStreams: 10, perKeyConcurrentStreams: 1 });
+    t.acquire({ apiKeyId: "k1", provider: "a" }, config);
+    expect(() => t.acquire({ apiKeyId: "k1", provider: "b" }, config)).toThrow(ConcurrencyError);
+    try {
+      t.acquire({ apiKeyId: "k1", provider: "b" }, config);
+    } catch (e) {
+      expect((e as ConcurrencyError).code).toBe("KEY_FULL");
+    }
+  });
+
+  it("per-provider cap exhausts → PROVIDER_FULL", () => {
+    const t = new ConcurrencyTracker();
+    const config = makeConfig({
+      maxConcurrentStreams: 10,
+      perKeyConcurrentStreams: 10,
+      perProviderCaps: { openai: 1 },
+    });
+    t.acquire({ apiKeyId: "k1", provider: "openai" }, config);
+    expect(() => t.acquire({ apiKeyId: "k2", provider: "openai" }, config)).toThrow(ConcurrencyError);
+    try {
+      t.acquire({ apiKeyId: "k2", provider: "openai" }, config);
+    } catch (e) {
+      expect((e as ConcurrencyError).code).toBe("PROVIDER_FULL");
+    }
+  });
+
+  it("release decrements all counters", () => {
+    const t = new ConcurrencyTracker();
+    const config = makeConfig({ maxConcurrentStreams: 1, perKeyConcurrentStreams: 1 });
+    const release = t.acquire({ apiKeyId: "k1", provider: "a" }, config);
+    release();
+    // Should be able to acquire again
+    const release2 = t.acquire({ apiKeyId: "k1", provider: "a" }, config);
+    release2();
+  });
+
+  it("double release is safe", () => {
+    const t = new ConcurrencyTracker();
+    const config = makeConfig();
+    const release = t.acquire({ apiKeyId: "k1", provider: "a" }, config);
+    release();
+    release(); // no-op
+  });
+
+  it("concurrent acquire/release under Promise.all", async () => {
+    const t = new ConcurrencyTracker();
+    const config = makeConfig({ maxConcurrentStreams: 100, perKeyConcurrentStreams: 100, perProviderCaps: { a: 100 } });
+    const releases: (() => void)[] = [];
+
+    // Acquire many concurrently
+    await Promise.all(
+      Array.from({ length: 50 }, (_, i) => {
+        return new Promise<void>((resolve) => {
+          const release = t.acquire({ apiKeyId: `k${i}`, provider: "a" }, config);
+          releases.push(release);
+          resolve();
+        });
+      }),
+    );
+
+    // Release all
+    releases.forEach((r) => r());
+
+    // Should be able to acquire again
+    const release = t.acquire({ apiKeyId: "k0", provider: "a" }, config);
+    release();
+  });
+});

package/packages/server/src/model-proxy/__tests__/failed-auth-backoff.test.ts

@@ -0,0 +1,46 @@
+import { describe, it, expect } from "vitest";
+import { FailedAuthBackoff } from "../failed-auth-backoff.js";
+
+describe("FailedAuthBackoff", () => {
+  it("starts at 10ms on first failure", () => {
+    const b = new FailedAuthBackoff();
+    const delay = b.record("1.2.3.4");
+    expect(delay).toBe(10);
+  });
+
+  it("doubles on each failure", () => {
+    const b = new FailedAuthBackoff();
+    expect(b.record("1.2.3.4")).toBe(10);
+    expect(b.record("1.2.3.4")).toBe(20);
+    expect(b.record("1.2.3.4")).toBe(40);
+    expect(b.record("1.2.3.4")).toBe(80);
+  });
+
+  it("caps at 10s", () => {
+    const b = new FailedAuthBackoff();
+    for (let i = 0; i < 20; i++) b.record("1.2.3.4");
+    expect(b.getDelayMs("1.2.3.4")).toBe(10_000);
+  });
+
+  it("resets on success", () => {
+    const b = new FailedAuthBackoff();
+    b.record("1.2.3.4");
+    b.record("1.2.3.4");
+    b.reset("1.2.3.4");
+    expect(b.getDelayMs("1.2.3.4")).toBe(0);
+  });
+
+  it("isolates different IPs", () => {
+    const b = new FailedAuthBackoff();
+    b.record("1.1.1.1");
+    b.record("1.1.1.1");
+    b.record("2.2.2.2");
+    expect(b.getDelayMs("1.1.1.1")).toBe(20);
+    expect(b.getDelayMs("2.2.2.2")).toBe(10);
+  });
+
+  it("getDelayMs returns 0 for unknown IP", () => {
+    const b = new FailedAuthBackoff();
+    expect(b.getDelayMs("unknown")).toBe(0);
+  });
+});

package/packages/server/src/model-proxy/__tests__/recursion-guard.test.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect } from "vitest";
+import { isSelfPointing, collectDashboardOrigins } from "../recursion-guard.js";
+
+const origins = [
+  "localhost:8000",
+  "127.0.0.1:8000",
+  "[::1]:8000",
+  "192.168.1.10:8000",
+  "abcdef.share.zrok.io",
+];
+
+describe("isSelfPointing", () => {
+  it("catches localhost variants", () => {
+    expect(isSelfPointing("http://localhost:8000/v1", origins)).toBe(true);
+    expect(isSelfPointing("http://127.0.0.1:8000/v1", origins)).toBe(true);
+    expect(isSelfPointing("http://[::1]:8000/v1", origins)).toBe(true);
+  });
+
+  it("catches LAN IP self", () => {
+    expect(isSelfPointing("http://192.168.1.10:8000/v1", origins)).toBe(true);
+  });
+
+  it("catches tunnel hostname self", () => {
+    expect(isSelfPointing("https://abcdef.share.zrok.io/v1", origins)).toBe(true);
+  });
+
+  it("passes legitimate external URL", () => {
+    expect(isSelfPointing("https://api.openai.com/v1", origins)).toBe(false);
+  });
+
+  it("handles case insensitivity", () => {
+    expect(isSelfPointing("http://LOCALHOST:8000/v1", origins)).toBe(true);
+  });
+
+  it("handles different port", () => {
+    expect(isSelfPointing("http://localhost:9999/v1", origins)).toBe(false);
+  });
+
+  it("handles malformed URL gracefully", () => {
+    expect(isSelfPointing("not-a-url", origins)).toBe(false);
+  });
+
+  it("handles HTTPS with default port", () => {
+    const httpsOrigins = ["abcdef.share.zrok.io"];
+    expect(isSelfPointing("https://abcdef.share.zrok.io/v1", httpsOrigins)).toBe(true);
+  });
+});
+
+describe("collectDashboardOrigins", () => {
+  it("includes localhost variants", () => {
+    const origins = collectDashboardOrigins(8000);
+    expect(origins).toContain("localhost:8000");
+    expect(origins).toContain("127.0.0.1:8000");
+    expect(origins).toContain("[::1]:8000");
+  });
+
+  it("includes tunnel hostname when provided", () => {
+    const origins = collectDashboardOrigins(8000, { tunnelHostname: "my.tunnel.io" });
+    expect(origins).toContain("my.tunnel.io");
+  });
+});

package/packages/server/src/model-proxy/__tests__/streamer.test.ts

@@ -0,0 +1,139 @@
+/**
+ * Tests for streamer.ts: streamCompletion wraps pi-ai's streamSimple.
+ *
+ * Uses faux registry + streamSimple mocks — no real pi-ai required.
+ *
+ * See change: add-dashboard-model-proxy, tasks 6.2 + 6.3.
+ */
+import { describe, it, expect, vi } from "vitest";
+import { streamCompletion } from "../streamer.js";
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+function makeModel(id = "test-model") {
+  return { id, provider: "test-provider" };
+}
+
+function makeRegistry(apiKey = "sk-test", headers = {} as Record<string, string>) {
+  return {
+    getApiKeyAndHeaders: vi.fn().mockResolvedValue({ apiKey, headers }),
+  };
+}
+
+async function* fakeStream(events: any[]): AsyncIterable<any> {
+  for (const e of events) yield e;
+}
+
+// ── Tests ──────────────────────────────────────────────────────────────────
+
+describe("streamCompletion", () => {
+  it("calls streamSimple with resolved credentials", async () => {
+    const model = makeModel();
+    const registry = makeRegistry("sk-abc", { "x-foo": "bar" });
+    const streamSimple = vi.fn().mockReturnValue(fakeStream([{ type: "start" }]));
+
+    await streamCompletion({ model, messages: [{ role: "user", content: "hi" }] }, streamSimple as any, registry);
+
+    expect(registry.getApiKeyAndHeaders).toHaveBeenCalledWith(model);
+    expect(streamSimple).toHaveBeenCalledOnce();
+    const [, , optionsArg] = streamSimple.mock.calls[0];
+    expect(optionsArg.apiKey).toBe("sk-abc");
+    expect(optionsArg.headers).toEqual({ "x-foo": "bar" });
+  });
+
+  it("passes model, messages, and optional fields through to streamSimple", async () => {
+    const model = makeModel();
+    const registry = makeRegistry();
+    const streamSimple = vi.fn().mockReturnValue(fakeStream([]));
+
+    const messages = [{ role: "user", content: "hello" }];
+    const tools = [{ name: "search" }];
+    const signal = new AbortController().signal;
+
+    await streamCompletion({ model, messages, system: "Be helpful", tools, maxTokens: 100, temperature: 0.7, signal }, streamSimple as any, registry);
+
+    const [modelArg, contextArg, optionsArg] = streamSimple.mock.calls[0];
+    expect(modelArg).toEqual(model);
+    expect(contextArg.messages).toEqual(messages);
+    expect(contextArg.systemPrompt).toBe("Be helpful");
+    expect(contextArg.tools).toEqual(tools);
+    expect(optionsArg.maxTokens).toBe(100);
+    expect(optionsArg.temperature).toBe(0.7);
+    expect(optionsArg.signal).toBe(signal);
+  });
+
+  it("omits systemPrompt when not provided", async () => {
+    const model = makeModel();
+    const registry = makeRegistry();
+    const streamSimple = vi.fn().mockReturnValue(fakeStream([]));
+
+    await streamCompletion({ model, messages: [] }, streamSimple as any, registry);
+
+    const [, contextArg] = streamSimple.mock.calls[0];
+    expect("systemPrompt" in contextArg).toBe(false);
+  });
+
+  it("yields events from the underlying stream", async () => {
+    const model = makeModel();
+    const registry = makeRegistry();
+    const events = [
+      { type: "start" },
+      { type: "text_delta", delta: "hello" },
+      { type: "done", message: { stopReason: "stop", usage: { input: 5, output: 3 }, content: [] } },
+    ];
+    const streamSimple = vi.fn().mockReturnValue(fakeStream(events));
+
+    const iterable = await streamCompletion({ model, messages: [] }, streamSimple as any, registry);
+    const collected: any[] = [];
+    for await (const event of iterable) collected.push(event);
+
+    expect(collected).toHaveLength(3);
+    expect(collected[0].type).toBe("start");
+    expect(collected[1].delta).toBe("hello");
+    expect(collected[2].type).toBe("done");
+  });
+
+  it("AbortSignal abort terminates iteration promptly (task 6.3)", async () => {
+    const model = makeModel();
+    const registry = makeRegistry();
+    const controller = new AbortController();
+
+    let yieldCount = 0;
+    async function* slowStream(): AsyncIterable<any> {
+      try {
+        while (true) {
+          if (controller.signal.aborted) return;
+          yield { type: "text_delta", delta: "chunk" };
+          yieldCount++;
+          if (yieldCount === 1) {
+            controller.abort(); // abort after first event
+          }
+          // Small delay so abort check catches up
+          await new Promise((r) => setTimeout(r, 5));
+        }
+      } finally {
+        // generator cleans up
+      }
+    }
+
+    const streamSimple = vi.fn().mockReturnValue(slowStream());
+
+    const iterable = await streamCompletion(
+      { model, messages: [], signal: controller.signal },
+      streamSimple as any,
+      registry,
+    );
+
+    const start = Date.now();
+    const collected: any[] = [];
+    for await (const event of iterable) {
+      collected.push(event);
+    }
+    const elapsed = Date.now() - start;
+
+    // Terminates promptly — well under 100ms after abort
+    expect(elapsed).toBeLessThan(200);
+    // Only events before abort emitted
+    expect(collected.length).toBeLessThanOrEqual(2);
+  });
+});

package/packages/server/src/model-proxy/api-key-store.ts

@@ -0,0 +1,87 @@
+/**
+ * Pure helpers for proxy API key management: hash, verify, generate, lookup.
+ *
+ * Keys use the format `pi-proxy-<48 base64url chars>` (288 bits of entropy).
+ * Storage uses sha256 hex hashes — cleartext is never persisted.
+ *
+ * See change: add-dashboard-model-proxy.
+ */
+import crypto from "node:crypto";
+import type { ProxyApiKey, ModelProxyConfig } from "@blackbelt-technology/pi-dashboard-shared/config.js";
+
+// ── Core helpers ────────────────────────────────────────────────────────────
+
+export function hashKey(key: string): string {
+  return crypto.createHash("sha256").update(key).digest("hex");
+}
+
+export function verifyKey(key: string, hash: string): boolean {
+  return crypto.timingSafeEqual(
+    Buffer.from(hashKey(key), "hex"),
+    Buffer.from(hash, "hex"),
+  );
+}
+
+export function generateKey(): string {
+  const bytes = crypto.randomBytes(36); // 36 bytes → 48 base64url chars
+  return `pi-proxy-${bytes.toString("base64url")}`;
+}
+
+// ── Lookup helpers ──────────────────────────────────────────────────────────
+
+export type FindResult =
+  | { kind: "valid"; entry: ProxyApiKey }
+  | { kind: "revoked" }
+  | { kind: "expired" }
+  | { kind: "miss" };
+
+/**
+ * Look up an API key in the config. Returns discriminated result.
+ * Checks revoked/expired status before returning valid.
+ */
+export function findApiKey(token: string, config: ModelProxyConfig): FindResult {
+  const tokenHash = hashKey(token);
+  for (const entry of config.apiKeys) {
+    if (entry.hash !== tokenHash) continue;
+    // Constant-time verify to prevent timing attacks
+    if (!verifyKey(token, entry.hash)) continue;
+    if (entry.revokedAt != null) return { kind: "revoked" };
+    if (entry.expiresAt != null && entry.expiresAt <= Date.now()) return { kind: "expired" };
+    return { kind: "valid", entry };
+  }
+  return { kind: "miss" };
+}
+
+/** Debounce window for lastUsedAt updates (60s). */
+const LAST_USED_DEBOUNCE_MS = 60_000;
+
+/**
+ * Update lastUsedAt on a key entry. Returns mutated apiKeys array (caller persists).
+ * Debounces: skips update if last use was within 60s.
+ */
+export function recordKeyUsage(
+  id: string,
+  apiKeys: ProxyApiKey[],
+  now = Date.now(),
+): { updated: boolean; apiKeys: ProxyApiKey[] } {
+  const result = apiKeys.map((k) => {
+    if (k.id !== id) return k;
+    if (k.lastUsedAt && now - k.lastUsedAt < LAST_USED_DEBOUNCE_MS) return k;
+    return { ...k, lastUsedAt: now };
+  });
+  const changed = result.some((k, i) => k !== apiKeys[i]);
+  return { updated: changed, apiKeys: result };
+}
+
+// ── Scope helpers ───────────────────────────────────────────────────────────
+
+export type ProxyScope = "models:list" | "chat" | "messages";
+
+/**
+ * Check if a key entry has the required scope.
+ * `"all"` in scopes matches any required scope.
+ */
+export function keyHasScope(entry: ProxyApiKey, requiredScope: ProxyScope): boolean {
+  const scopes = entry.scopes ?? ["all"];
+  return scopes.includes("all") || scopes.includes(requiredScope);
+}