ada-agent 0.6.1 → 0.8.0

package/src/selfcheck.ts

@@ -293,6 +293,159 @@ async function main(): Promise<void> {
     assert.equal(route("anything-else"), "openrouter", "unmatched → openrouter");
   }
 
+  // --- enterprise control plane: seats, policy, metering, audit (temp data dir, no HTTP) ---
+  {
+    const dir = join(tmpdir(), `ada-ent-${Date.now()}`);
+    const ent = await import("./server/enterprise.ts");
+    process.env.ADA_DATA_DIR = dir;
+    try {
+      assert.equal(ent.enterpriseMode(dir), false, "no seats + no admin key → enterprise mode off");
+      const key = ent.createSeat("alice", "admin", dir);
+      assert.ok(key.startsWith("ada_sk_") && key.length > 40, "seat keys are long and prefixed");
+      assert.equal(ent.enterpriseMode(dir), true, "a seat activates enterprise mode");
+      assert.deepEqual(ent.identifySeat(key, dir), { user: "alice", role: "admin" }, "seat key resolves to its identity");
+      assert.equal(ent.identifySeat("ada_sk_wrong", dir), null, "unknown key → null");
+      // The auth-bypass the review caught: Object.prototype keys must NOT authenticate.
+      for (const evil of ["toString", "constructor", "__proto__", "valueOf", "hasOwnProperty"]) {
+        assert.equal(ent.identifySeat(evil, dir), null, `prototype key "${evil}" must not authenticate`);
+      }
+      assert.equal(ent.listSeats(dir)[0]!.keyPrefix.length, 14, "listing exposes only a key prefix");
+      assert.equal(ent.disableSeat(key.slice(0, 8), dir), null, "too-short prefix refused");
+      assert.equal(ent.disableSeat(key.slice(0, 14), dir), "alice", "disable by unique prefix");
+      assert.equal(ent.identifySeat(key, dir), null, "disabled seat no longer authenticates");
+
+      assert.ok(ent.modelAllowed("claude-opus-4-8", {}), "empty policy allows everything");
+      const pol = { models: ["@cf/*", "claude-*"] };
+      assert.ok(ent.modelAllowed("@cf/moonshotai/kimi-k2.7-code", pol), "wildcard allowlist matches");
+      assert.ok(!ent.modelAllowed("gpt-5", pol), "non-listed model denied");
+
+      ent.appendUsage({ ts: Date.now(), user: "alice", model: "m1", provider: "p", promptTokens: 100, completionTokens: 20 }, dir);
+      ent.appendUsage({ ts: Date.now(), user: "alice", model: "m1", provider: "p", promptTokens: 50, completionTokens: 10 }, dir);
+      ent.appendUsage({ ts: Date.now() - 90 * 86_400_000, user: "old", model: "m1", provider: "p", promptTokens: 999, completionTokens: 999 }, dir);
+      const sum = ent.usageSummary(30, dir);
+      assert.equal(sum.byUser.alice!.requests, 2, "usage aggregates per user");
+      assert.equal(sum.totals.promptTokens, 150, "old rows fall outside the window");
+
+      assert.ok(ent.auditTail(10, dir).some((e) => e.event === "seat_created"), "audit log records seat creation");
+
+      const sse = 'data: {"choices":[]}\n\ndata: {"choices":[],"usage":{"prompt_tokens":11,"completion_tokens":7,"completion_tokens_details":{"reasoning_tokens":2}}}\n\ndata: [DONE]\n\n';
+      assert.deepEqual(ent.extractLastUsage(sse), { promptTokens: 11, completionTokens: 7 }, "usage extracted from SSE tail (nested details ok)");
+      assert.equal(ent.extractLastUsage("no usage here"), null, "no usage → null");
+      // A trailing "usage": null must not hide the real one earlier in the stream.
+      assert.deepEqual(ent.extractLastUsage('{"usage":{"prompt_tokens":5,"completion_tokens":3}}\n{"usage":null}'), { promptTokens: 5, completionTokens: 3 }, "trailing usage:null skipped, real one found");
+
+      // policy validation rejects malformed shapes, accepts good ones
+      assert.ok("error" in ent.validatePolicy({ models: [1, 2] }), "non-string models rejected");
+      assert.ok("error" in ent.validatePolicy({ permissions: [{ tool: "x" }] }), "permission without action rejected");
+      assert.ok("policy" in ent.validatePolicy({ models: ["@cf/*"], permissions: [{ tool: "bash", action: "deny" }] }), "valid policy accepted");
+
+      // corrupt users.json → CorruptStore (fail-closed), NOT an empty map that unlocks the backend
+      writeFileSync(join(dir, "users.json"), "{ this is not json");
+      assert.throws(() => ent.loadSeats(dir), (e: unknown) => e instanceof ent.CorruptStore, "corrupt users.json throws CorruptStore");
+      assert.equal(ent.enterpriseMode(dir), true, "corrupt store → still enterprise (locked), never open");
+    } finally {
+      delete process.env.ADA_DATA_DIR;
+      rmSync(dir, { recursive: true, force: true });
+    }
+  }
+
+  // --- OIDC SSO (Stage 2): JIT seat invariants + hermetic RS256 id-token verification ---
+  {
+    const dir = join(tmpdir(), `ada-oidc-${Date.now()}`);
+    const ent = await import("./server/enterprise.ts");
+    const oidc = await import("./server/oidc.ts");
+    const { generateKeyPairSync, sign } = await import("node:crypto");
+    const savedEnv = { ...process.env };
+    const iss = "https://idp.example.com";
+    process.env.ADA_DATA_DIR = dir;
+    process.env.ADA_OIDC_ISSUER = iss;
+    process.env.ADA_OIDC_CLIENT_ID = "ada-client";
+    process.env.ADA_OIDC_ALLOWED_GROUPS = "engineering";
+    process.env.ADA_OIDC_ADMIN_GROUP = "admins";
+    try {
+      // JIT seat provisioning invariants (the load-bearing new behavior).
+      const ext = `${iss}#sub-123`;
+      const k1 = ent.upsertSeatForSSO(ext, iss, "sso-user", "dev", dir);
+      assert.ok(k1 && k1.startsWith("ada_sk_") && k1.length > 40, "OIDC JIT mints a valid seat key");
+      assert.equal(ent.upsertSeatForSSO(ext, iss, "sso-user", "dev", dir), k1, "same iss#sub reuses one seat (no key rotation)");
+      assert.equal(ent.upsertSeatForSSO(ext, iss, "sso-user", "admin", dir), k1, "existing seat is NOT auto-escalated to admin on login");
+      assert.deepEqual(ent.identifySeat(k1!, dir), { user: "sso-user", role: "dev" }, "SSO seat key authenticates like any seat");
+      assert.equal(ent.disableSeatByExternalId(ext, dir), "sso-user", "disable-by-externalId offboards");
+      assert.equal(ent.upsertSeatForSSO(ext, iss, "sso-user", "dev", dir), null, "disabled externalId denies re-login (fail-closed deprovision, no resurrect)");
+      assert.equal(ent.identifySeat(k1!, dir), null, "disabled SSO seat no longer authenticates");
+      assert.equal(ent.seatByExternalId("__proto__", dir), null, "externalId scan is prototype-safe");
+      // admin→dev downgrade when the admin group drops off a later login.
+      const ext2 = `${iss}#boss`;
+      const kb = ent.upsertSeatForSSO(ext2, iss, "boss", "admin", dir);
+      assert.equal(ent.identifySeat(kb!, dir)!.role, "admin", "admin seat provisioned");
+      assert.equal(ent.upsertSeatForSSO(ext2, iss, "boss", "dev", dir), kb, "downgrade reuses the same key");
+      assert.equal(ent.identifySeat(kb!, dir)!.role, "dev", "admin→dev downgrade on group removal");
+
+      // group/domain gate.
+      assert.ok(oidc.isProvisionAllowed({ iss, sub: "s", name: "n", groups: ["engineering"] }), "allowed group provisions");
+      assert.ok(!oidc.isProvisionAllowed({ iss, sub: "s", name: "n", groups: ["other"], email: "x@evil.com" }), "non-allowed group/domain refused");
+      assert.equal(oidc.mapIdentityToSeatFields({ iss, sub: "z", name: "z", groups: ["admins"] }).role, "admin", "admin group → admin role");
+
+      // Hermetic RS256 verification: sign a token locally, verify via an injected JWKS key.
+      const { publicKey, privateKey } = generateKeyPairSync("rsa", { modulusLength: 2048 });
+      const pubJwk = { ...(publicKey.export({ format: "jwk" }) as Record<string, unknown>), kid: "test", kty: "RSA" };
+      const getKey = (kid: string) => (kid === "test" ? pubJwk : null);
+      const now = 1_800_000_000_000;
+      const sec = Math.floor(now / 1000);
+      const b64u = (o: unknown): string => Buffer.from(typeof o === "string" ? o : JSON.stringify(o)).toString("base64url");
+      const mkToken = (payload: Record<string, unknown>, alg = "RS256"): string => {
+        const head = b64u({ alg, kid: "test", typ: "JWT" });
+        const body = b64u(payload);
+        if (alg === "none") return `${head}.${body}.`;
+        return `${head}.${body}.${sign("RSA-SHA256", Buffer.from(`${head}.${body}`), privateKey).toString("base64url")}`;
+      };
+      const good = { iss, aud: "ada-client", sub: "sub-123", exp: sec + 3600, iat: sec, groups: ["engineering"], email: "dev@corp.com" };
+      const id = await oidc.verifyOidcToken(mkToken(good), { getKey, now });
+      assert.ok(id && id.sub === "sub-123" && id.iss === iss, "valid RS256 id_token verifies");
+      const validTok = mkToken(good);
+      assert.equal(await oidc.verifyOidcToken(`${validTok.slice(0, -4)}AAAA`, { getKey, now }), null, "tampered signature → null");
+      assert.equal(await oidc.verifyOidcToken(mkToken({ ...good, aud: "someone-else" }), { getKey, now }), null, "wrong audience → null");
+      assert.equal(await oidc.verifyOidcToken(mkToken(good, "none"), { getKey, now }), null, "alg=none → null (no key confusion)");
+      assert.equal(await oidc.verifyOidcToken(mkToken({ ...good, exp: sec - 7200 }), { getKey, now }), null, "expired token → null");
+      // email is trusted only when the IdP marks it verified (domain-provisioning fail-open fix).
+      const idU = await oidc.verifyOidcToken(mkToken({ ...good, email: "x@corp.com", email_verified: false }), { getKey, now });
+      assert.ok(idU && idU.email === undefined, "unverified email dropped from identity");
+      const idV = await oidc.verifyOidcToken(mkToken({ ...good, email: "x@corp.com", email_verified: true }), { getKey, now });
+      assert.equal(idV!.email, "x@corp.com", "verified email kept");
+
+      // SSRF guard classifies against a parsed IP (net.isIP), not a string prefix.
+      for (const bad of ["https://[::1]/keys", "https://[fe80::1]/keys", "https://[fc00::1]/keys", "https://[::ffff:127.0.0.1]/keys", "https://127.0.0.1/keys", "https://10.1.2.3/keys", "http://idp.okta.com/keys"]) {
+        assert.throws(() => oidc.assertSafeJwksUri(bad), `jwks_uri rejected: ${bad}`);
+      }
+      for (const ok of ["https://fcm.googleapis.com/keys", "https://fd-idp.corp.com/keys", "https://your-tenant.okta.com/oauth2/v1/keys"]) {
+        assert.doesNotThrow(() => oidc.assertSafeJwksUri(ok), `jwks_uri allowed: ${ok}`);
+      }
+    } finally {
+      for (const k of ["ADA_DATA_DIR", "ADA_OIDC_ISSUER", "ADA_OIDC_CLIENT_ID", "ADA_OIDC_ALLOWED_GROUPS", "ADA_OIDC_ADMIN_GROUP"]) {
+        if (savedEnv[k] === undefined) delete process.env[k];
+        else process.env[k] = savedEnv[k];
+      }
+      rmSync(dir, { recursive: true, force: true });
+    }
+  }
+
+  // --- org policy merge: restrictive wins, org can tighten but never loosen ---
+  {
+    const { permissionFor, setActiveAgentPermissions, setOrgPermissions } = await import("./client/settings.ts");
+    setActiveAgentPermissions([{ tool: "bash", action: "allow" }]);
+    setOrgPermissions([{ tool: "bash", action: "deny" }]);
+    assert.equal(permissionFor("bash", "x"), "deny", "org deny beats local allow");
+    setOrgPermissions([{ tool: "bash", action: "ask" }]);
+    assert.equal(permissionFor("bash", "x"), "ask", "org ask upgrades local allow");
+    setActiveAgentPermissions([{ tool: "bash", action: "deny" }]);
+    setOrgPermissions([{ tool: "bash", action: "allow" }]);
+    assert.equal(permissionFor("bash", "x"), "deny", "org allow cannot loosen a local deny");
+    setActiveAgentPermissions([]);
+    assert.equal(permissionFor("bash", "x"), null, "org allow cannot loosen the default gating");
+    setOrgPermissions(null);
+    setActiveAgentPermissions(null);
+  }
+
   // --- @codebase semantic search: pure parts (no network / no embedding model needed) ---
   {
     const { chunkText, cosine, walkFiles } = await import("./client/embed-index.ts");

package/src/server/enterprise.ts

@@ -0,0 +1,408 @@
+// Enterprise control plane: seats (per-user client keys), org policy, usage metering, audit log.
+// One deployment = one org (it's self-hosted; multi-org is the SaaS upgrade path, not v1).
+//
+// Enterprise mode ACTIVATES when a seat exists or ADA_ADMIN_KEY is set — with neither, the backend
+// behaves exactly as before (dev-open / ADA_CLIENT_KEYS / login). Bootstrap:
+//
+//   ADA_ADMIN_KEY=<random> ada-server
+//   curl -X POST -H "Authorization: Bearer $ADA_ADMIN_KEY" localhost:8787/v1/users -d '{"name":"alice"}'
+//
+// Security posture (hardened after an adversarial review):
+//   - lookups are own-property + format-guarded (no prototype-key auth bypass);
+//   - writes are atomic (tmp + rename); a corrupt/unreadable store fails CLOSED (never dev-open);
+//   - key comparisons are timing-safe.
+// ponytail: file-backed under ~/.ada/server — fine to ~50 seats. Postgres + rotating usage logs are
+// the upgrade path when an org outgrows files (usageSummary/auditTail read whole files: OK to
+// low-millions of rows, then rotate).
+
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+// Resolved once: an empty ADA_DATA_DIR means "unset", and a relative path can't scatter the auth
+// store across working directories (which would itself be a fail-open).
+const DATA_DIR = resolve(process.env.ADA_DATA_DIR || join(homedir(), ".ada", "server"));
+function dataDir(): string {
+  return DATA_DIR;
+}
+
+/** Thrown when a store file exists but can't be read/parsed — callers must fail CLOSED, never open. */
+export class CorruptStore extends Error {}
+
+export interface Seat {
+  name: string;
+  role: "admin" | "dev";
+  created: string;
+  disabled?: boolean;
+  externalId?: string; // OIDC SSO: issuer-scoped stable id (`iss#sub`) — non-secret, the deprovision target
+  iss?: string; // OIDC issuer the seat was provisioned from (so an issuer change is detectable)
+}
+export interface PolicyRule {
+  tool?: string;
+  pattern?: string;
+  action: "allow" | "ask" | "deny";
+}
+export interface Policy {
+  models?: string[];
+  permissions?: PolicyRule[];
+}
+export interface UsageRow {
+  ts: number;
+  user: string;
+  model: string;
+  provider: string;
+  promptTokens: number;
+  completionTokens: number;
+}
+export interface Identity {
+  user: string;
+  role: "admin" | "dev";
+}
+
+const usersFile = (dir: string): string => join(dir, "users.json");
+const policyFile = (dir: string): string => join(dir, "policy.json");
+const usageFile = (dir: string): string => join(dir, "usage.jsonl");
+const auditFile = (dir: string): string => join(dir, "audit.jsonl");
+
+function atomicWrite(file: string, data: string): void {
+  mkdirSync(join(file, ".."), { recursive: true });
+  const tmp = `${file}.tmp.${process.pid}`;
+  writeFileSync(tmp, data);
+  renameSync(tmp, file); // atomic on the same filesystem — a crash can't leave a torn file
+}
+
+function errno(e: unknown): string | undefined {
+  return (e as NodeJS.ErrnoException).code;
+}
+
+/** Seats keyed by full key. Missing file → empty (prototype-free) map. Any OTHER read/parse error
+ *  → CorruptStore (callers fail closed — a torn users.json must not silently disable auth). */
+export function loadSeats(dir = dataDir()): Record<string, Seat> {
+  const map: Record<string, Seat> = Object.create(null); // no Object.prototype — belt-and-suspenders with the own-property check
+  let text: string;
+  try {
+    text = readFileSync(usersFile(dir), "utf8");
+  } catch (e) {
+    if (errno(e) === "ENOENT") return map;
+    throw new CorruptStore(`users.json unreadable: ${e instanceof Error ? e.message : e}`);
+  }
+  try {
+    const parsed = (JSON.parse(text) as { users?: Record<string, Seat> }).users ?? {};
+    for (const [k, v] of Object.entries(parsed)) map[k] = v;
+    return map;
+  } catch (e) {
+    throw new CorruptStore(`users.json corrupt: ${e instanceof Error ? e.message : e}`);
+  }
+}
+
+function saveSeats(seats: Record<string, Seat>, dir = dataDir()): void {
+  atomicWrite(usersFile(dir), JSON.stringify({ users: seats }, null, 2));
+}
+
+/** Enterprise mode = admin key set, or seats exist. A corrupt seat store counts as enterprise
+ *  (locked), never as "no seats" — fail closed. */
+export function enterpriseMode(dir = dataDir()): boolean {
+  if (process.env.ADA_ADMIN_KEY) return true;
+  try {
+    return Object.keys(loadSeats(dir)).length > 0;
+  } catch {
+    return true;
+  }
+}
+
+function timingEqual(a: string, b: string): boolean {
+  const ab = Buffer.from(a);
+  const bb = Buffer.from(b);
+  return ab.length === bb.length && timingSafeEqual(ab, bb);
+}
+
+/** Resolve a bearer token to a seat identity (or the bootstrap admin). Null = not a seat. Throws
+ *  CorruptStore if the seat store can't be read (caller returns 503, never dev-open). */
+export function identifySeat(token: string, dir = dataDir()): Identity | null {
+  const admin = process.env.ADA_ADMIN_KEY;
+  if (admin && timingEqual(token, admin)) return { user: "admin", role: "admin" };
+  if (!token.startsWith("ada_sk_")) return null; // format guard — "toString"/"__proto__"/… never reach the map
+  const seats = loadSeats(dir); // may throw CorruptStore
+  if (!Object.prototype.hasOwnProperty.call(seats, token)) return null; // own-property only
+  const seat = seats[token]!;
+  return seat.disabled ? null : { user: seat.name, role: seat.role };
+}
+
+/** Create a seat; returns its full key (shown once — only a prefix is ever listed again). */
+export function createSeat(name: string, role: "admin" | "dev" = "dev", dir = dataDir()): string {
+  const key = `ada_sk_${randomBytes(24).toString("hex")}`;
+  const seats = loadSeats(dir);
+  seats[key] = { name, role, created: new Date().toISOString() };
+  saveSeats(seats, dir);
+  appendAudit({ ts: Date.now(), user: "-", event: "seat_created", detail: `${name} (${role})` }, dir);
+  return key;
+}
+
+/** Find a seat by its OIDC externalId (`iss#sub`). Scans the (small) seat map by VALUE — externalId
+ *  is compared, never used as a lookup key, so it's inherently prototype-safe. Inherits CorruptStore
+ *  from loadSeats (callers fail closed). */
+export function seatByExternalId(externalId: string, dir = dataDir()): { key: string; seat: Seat } | null {
+  const seats = loadSeats(dir);
+  for (const key of Object.keys(seats)) {
+    const seat = seats[key]!;
+    if (seat.externalId === externalId) return { key, seat };
+  }
+  return null;
+}
+
+/** JIT-provision (or reuse) a seat for a verified OIDC identity. Returns the seat's `ada_sk_` key, or
+ *  null if the seat exists but is DISABLED (a deprovisioned user must not be resurrected by re-login).
+ *  - existing enabled seat → reuse its key (NO rotation); if it was admin and the login no longer
+ *    carries the admin group, downgrade admin→dev (privilege revocation). Never auto-ESCALATE here.
+ *  - new identity → mint one key, stamp externalId+iss, one `seat_created` audit row. */
+export function upsertSeatForSSO(externalId: string, iss: string, name: string, role: "admin" | "dev", dir = dataDir()): string | null {
+  const seats = loadSeats(dir);
+  let foundKey: string | null = null;
+  for (const key of Object.keys(seats)) {
+    if (seats[key]!.externalId === externalId) {
+      foundKey = key;
+      break;
+    }
+  }
+  if (foundKey) {
+    const seat = seats[foundKey]!;
+    if (seat.disabled) return null; // deprovisioned — do NOT resurrect
+    if (seat.role === "admin" && role === "dev") {
+      seat.role = "dev";
+      saveSeats(seats, dir);
+      appendAudit({ ts: Date.now(), user: name, event: "role_changed", detail: `${name} admin→dev (SSO group removed)` }, dir);
+    }
+    return foundKey;
+  }
+  const key = `ada_sk_${randomBytes(24).toString("hex")}`;
+  seats[key] = { name, role, created: new Date().toISOString(), externalId, iss };
+  saveSeats(seats, dir);
+  appendAudit({ ts: Date.now(), user: name, event: "seat_created", detail: `${name} (${role}) via OIDC ${externalId}` }, dir);
+  return key;
+}
+
+/** Immediate offboarding: disable the seat for an OIDC externalId. The admin endpoint (and, later,
+ *  SCIM DELETE) call this — the next identifySeat for that key returns null (401). */
+export function disableSeatByExternalId(externalId: string, dir = dataDir()): string | null {
+  const seats = loadSeats(dir);
+  for (const key of Object.keys(seats)) {
+    const seat = seats[key]!;
+    if (seat.externalId === externalId) {
+      if (seat.disabled) return seat.name; // idempotent
+      seat.disabled = true;
+      saveSeats(seats, dir);
+      appendAudit({ ts: Date.now(), user: seat.name, event: "seat_disabled", detail: `${seat.name} (SSO ${externalId})` }, dir);
+      return seat.name;
+    }
+  }
+  return null;
+}
+
+/** Disable (not delete — the audit trail keeps the history) the seat whose key starts with prefix. */
+export function disableSeat(prefix: string, dir = dataDir()): string | null {
+  if (prefix.length < 12) return null; // too short to be safely unique
+  const seats = loadSeats(dir);
+  const keys = Object.keys(seats).filter((k) => k.startsWith(prefix));
+  if (keys.length !== 1) return null;
+  seats[keys[0]!]!.disabled = true;
+  saveSeats(seats, dir);
+  appendAudit({ ts: Date.now(), user: "-", event: "seat_disabled", detail: seats[keys[0]!]!.name }, dir);
+  return seats[keys[0]!]!.name;
+}
+
+/** Key prefixes + metadata for listing — full keys are never returned after creation. Display-only,
+ *  so a corrupt store yields [] rather than crashing the banner. */
+export function listSeats(dir = dataDir()): Array<Seat & { keyPrefix: string }> {
+  try {
+    return Object.entries(loadSeats(dir)).map(([k, s]) => ({ ...s, keyPrefix: k.slice(0, 14) }));
+  } catch {
+    return [];
+  }
+}
+
+let lastGoodPolicy: Policy | null = null;
+/** Missing file → {} (no policy = allow all, legitimate). A corrupt EXISTING file → last-known-good
+ *  if we have one, else CorruptStore (fail closed — a security control must not degrade to allow-all). */
+export function loadPolicy(dir = dataDir()): Policy {
+  let text: string;
+  try {
+    text = readFileSync(policyFile(dir), "utf8");
+  } catch (e) {
+    if (errno(e) === "ENOENT") return {};
+    if (lastGoodPolicy) return lastGoodPolicy;
+    throw new CorruptStore(`policy.json unreadable: ${e instanceof Error ? e.message : e}`);
+  }
+  try {
+    lastGoodPolicy = JSON.parse(text) as Policy;
+    return lastGoodPolicy;
+  } catch (e) {
+    if (lastGoodPolicy) return lastGoodPolicy;
+    throw new CorruptStore(`policy.json corrupt: ${e instanceof Error ? e.message : e}`);
+  }
+}
+
+export function savePolicy(p: Policy, dir = dataDir()): void {
+  atomicWrite(policyFile(dir), JSON.stringify(p, null, 2));
+  lastGoodPolicy = p;
+  appendAudit({ ts: Date.now(), user: "-", event: "policy_updated", detail: JSON.stringify(p).slice(0, 300) }, dir);
+}
+
+/** Validate a policy shape from the wire. Returns the typed policy or an error message. */
+export function validatePolicy(raw: unknown): { policy: Policy } | { error: string } {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return { error: "policy must be a JSON object" };
+  const r = raw as Record<string, unknown>;
+  const out: Policy = {};
+  if (r.models !== undefined) {
+    if (!Array.isArray(r.models) || r.models.some((m) => typeof m !== "string" || !m.trim())) return { error: "models must be an array of non-empty strings" };
+    out.models = r.models as string[];
+  }
+  if (r.permissions !== undefined) {
+    if (!Array.isArray(r.permissions)) return { error: "permissions must be an array" };
+    for (const p of r.permissions) {
+      const rule = p as Record<string, unknown>;
+      if (!rule || typeof rule !== "object" || !["allow", "ask", "deny"].includes(rule.action as string)) return { error: "each permission needs action: allow|ask|deny" };
+      if (rule.tool !== undefined && typeof rule.tool !== "string") return { error: "permission.tool must be a string" };
+      if (rule.pattern !== undefined && typeof rule.pattern !== "string") return { error: "permission.pattern must be a string" };
+    }
+    out.permissions = r.permissions as PolicyRule[];
+  }
+  return { policy: out };
+}
+
+function globMatch(pattern: string, s: string): boolean {
+  const re = new RegExp(`^${pattern.split("*").map((p) => p.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join(".*")}$`, "i");
+  return re.test(s);
+}
+
+/** Is this model allowed by org policy? No/empty allowlist = everything allowed. */
+export function modelAllowed(model: string, policy: Policy): boolean {
+  if (!Array.isArray(policy.models) || !policy.models.length) return true;
+  return policy.models.some((p) => globMatch(p, model));
+}
+
+export function appendUsage(row: UsageRow, dir = dataDir()): void {
+  try {
+    mkdirSync(dir, { recursive: true });
+    appendFileSync(usageFile(dir), `${JSON.stringify(row)}\n`);
+  } catch {
+    /* metering is best-effort; never fail a request over it */
+  }
+}
+
+export interface AuditRow {
+  ts: number;
+  user: string;
+  event: string;
+  detail: string;
+}
+
+export function appendAudit(row: AuditRow, dir = dataDir()): void {
+  try {
+    mkdirSync(dir, { recursive: true });
+    appendFileSync(auditFile(dir), `${JSON.stringify(row)}\n`);
+  } catch {
+    /* best-effort */
+  }
+}
+
+export function auditTail(limit = 200, dir = dataDir()): AuditRow[] {
+  let lines: string[];
+  try {
+    lines = readFileSync(auditFile(dir), "utf8").split("\n").filter(Boolean);
+  } catch {
+    return [];
+  }
+  const out: AuditRow[] = [];
+  for (const l of lines.slice(-limit)) {
+    try {
+      out.push(JSON.parse(l) as AuditRow); // skip a torn last line instead of losing the whole view
+    } catch {
+      /* skip corrupt line */
+    }
+  }
+  return out;
+}
+
+interface Bucket {
+  requests: number;
+  promptTokens: number;
+  completionTokens: number;
+}
+export interface UsageSummary {
+  since: number;
+  totals: Bucket;
+  byUser: Record<string, Bucket>;
+  byModel: Record<string, Bucket>;
+}
+
+export function usageSummary(days = 30, dir = dataDir()): UsageSummary {
+  const since = Date.now() - days * 86_400_000;
+  const zero = (): Bucket => ({ requests: 0, promptTokens: 0, completionTokens: 0 });
+  const out: UsageSummary = { since, totals: zero(), byUser: Object.create(null), byModel: Object.create(null) };
+  let lines: string[] = [];
+  try {
+    lines = readFileSync(usageFile(dir), "utf8").split("\n").filter(Boolean);
+  } catch {
+    return out;
+  }
+  for (const l of lines) {
+    let r: UsageRow;
+    try {
+      r = JSON.parse(l) as UsageRow;
+    } catch {
+      continue;
+    }
+    if (r.ts < since) continue;
+    for (const b of [out.totals, (out.byUser[r.user] ??= zero()), (out.byModel[r.model] ??= zero())]) {
+      b.requests++;
+      b.promptTokens += r.promptTokens || 0;
+      b.completionTokens += r.completionTokens || 0;
+    }
+  }
+  return out;
+}
+
+function matchBraces(text: string, start: number): string | null {
+  let depth = 0;
+  let inStr = false;
+  let esc = false;
+  for (let i = start; i < text.length; i++) {
+    const c = text[i];
+    if (inStr) {
+      if (esc) esc = false;
+      else if (c === "\\") esc = true;
+      else if (c === '"') inStr = false;
+    } else if (c === '"') inStr = true;
+    else if (c === "{") depth++;
+    else if (c === "}" && --depth === 0) return text.slice(start, i + 1);
+  }
+  return null;
+}
+
+/** Pull the LAST real `"usage": { … }` object out of streamed/response text. Skips a trailing
+ *  `"usage": null` and keeps scanning backwards, so a null in a late frame doesn't hide a real one. */
+export function extractLastUsage(text: string): { promptTokens: number; completionTokens: number } | null {
+  let at = text.lastIndexOf('"usage"');
+  while (at >= 0) {
+    const brace = text.indexOf("{", at + 7);
+    const colon = text.indexOf(":", at + 7);
+    if (brace >= 0 && colon >= 0 && text.slice(colon + 1, brace).trim() === "") {
+      const obj = matchBraces(text, brace);
+      if (obj) {
+        try {
+          const u = JSON.parse(obj) as { prompt_tokens?: number; completion_tokens?: number };
+          if (u.prompt_tokens != null || u.completion_tokens != null) return { promptTokens: u.prompt_tokens ?? 0, completionTokens: u.completion_tokens ?? 0 };
+        } catch {
+          /* malformed — keep looking backwards */
+        }
+      }
+    }
+    at = text.lastIndexOf('"usage"', at - 1);
+  }
+  return null;
+}
+
+export function storeExists(dir = dataDir()): boolean {
+  return existsSync(usersFile(dir)) || existsSync(policyFile(dir));
+}