shraga 0.1.112 → 0.1.114

package/src/server/security/guard.ts

@@ -0,0 +1,337 @@
+// Guard: abuse limits in front of every turn — BEFORE any LLM spend.
+//
+// Order: blocklist (policy manual blocklist + persisted auto-blocks) → rate (principal, ip, channel buckets) → proceed.
+// Plus a global ceiling on concurrent agent turns for principals below `ceilingBelowRank`.
+//
+// SHADOW: unless `enforce()` (SECURITY_ENFORCE=true) every verdict is `{ ok: true, wouldDeny }` — computed and audited,
+// never denied. Auto-blocks are still recorded (TTL-bound) so the Console shows what enforcement would do.
+//
+// Memory is bounded: buckets, hit windows and blocks are LRU maps capped at `maxKeys` — a spray of distinct
+// principals/IPs evicts the least-recently-used entry instead of growing the heap.
+//
+// Persistence: auto-blocks → data/security/blocks.json (atomic tmp+rename). Only an ACTIVE instance writes; a PASSIVE
+// standby keeps blocks in memory and `activate()` re-loads from disk on promotion (same model as runtime/policy).
+import { BlockList, isIP } from 'node:net';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { dataPath } from '../paths.ts';
+import type { AuditEvent } from './audit.ts';
+import type { Principal } from './principal.ts';
+import { enforcing } from './enforce.ts';
+
+export interface GuardDenial { ok: false; status: 429 | 403; retryAfter?: number; reason: string }
+export type GuardVerdict = { ok: true; wouldDeny?: GuardDenial } | GuardDenial;
+export interface GuardInput { principal: Principal; ip?: string; channel?: string; rank: number; rate: string }
+export type TurnAdmission = { ok: true; release: () => void; wouldDeny?: GuardDenial } | GuardDenial;
+export interface BlockRecord { until: number; reason: string; at: number }
+
+const UNITS: Record<string, number> = { s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000 };
+
+/** `"N/h"`, `"N/m"`, `"N/s"`, `"N/d"`; bare `"N"` = per hour; `"0"` = deny all. null = unparseable. */
+export function parseRate(rate: string): { cap: number; periodMs: number } | null {
+  const m = /^(\d+)(?:\/([smhd]))?$/.exec(String(rate ?? '').trim());
+  return m ? { cap: Number(m[1]), periodMs: UNITS[m[2] ?? 'h'] } : null;
+}
+
+/** `TRUSTED_PROXIES` → BlockList. Comma/space separated IPs or CIDRs; unset/empty = trust none. */
+export function parseTrustedProxies(spec: string | undefined, log: Pick<Console, 'warn'> = console): BlockList {
+  const list = new BlockList();
+  for (const raw of String(spec ?? '').split(/[\s,]+/).filter(Boolean)) {
+    const [addr, bits] = raw.split('/');
+    const ip = normalizeIp(addr), type = ip && isIP(ip) === 6 ? 'ipv6' : 'ipv4';
+    if (!ip) { log.warn(`[guard] TRUSTED_PROXIES: ignoring invalid entry "${raw}"`); continue; }
+    if (bits === undefined) list.addAddress(ip, type);
+    else if (/^\d+$/.test(bits) && Number(bits) <= (type === 'ipv6' ? 128 : 32)) list.addSubnet(ip, Number(bits), type);
+    else log.warn(`[guard] TRUSTED_PROXIES: ignoring invalid prefix "${raw}"`);
+  }
+  return list;
+}
+
+/** Strip `::ffff:` IPv4-mapped prefix and zone ids; undefined if not an IP. */
+export function normalizeIp(v: string | undefined): string | undefined {
+  let s = String(v ?? '').trim();
+  if (s.startsWith('[') && s.includes(']')) s = s.slice(1, s.indexOf(']'));
+  s = s.replace(/%.*$/, '');
+  if (/^::ffff:\d+\.\d+\.\d+\.\d+$/i.test(s)) s = s.slice(7);
+  return isIP(s) ? s : undefined;
+}
+
+const isTrusted = (list: BlockList, ip: string) => list.check(ip, isIP(ip) === 6 ? 'ipv6' : 'ipv4');
+const isLoopback = (ip: string) => /^127\./.test(ip) || ip === '::1';
+
+/**
+ * Client IP: the direct peer, unless the peer is a trusted proxy — then walk `x-forwarded-for` right→left and take the
+ * first hop that is NOT trusted. Headers from an untrusted peer are ignored (spoofable). A malformed hop stops the walk
+ * at the last trusted hop. Returns undefined when nothing usable is known.
+ */
+export function clientIp(peer: string | undefined, xff: string | string[] | undefined, trusted: BlockList): string | undefined {
+  let ip = normalizeIp(peer);
+  if (!ip || !isTrusted(trusted, ip)) return ip;
+  const hops = (Array.isArray(xff) ? xff.join(',') : String(xff ?? '')).split(',').map(h => h.trim()).filter(Boolean);
+  for (let i = hops.length - 1; i >= 0; i--) {
+    const hop = normalizeIp(hops[i]);
+    if (!hop) return ip;
+    ip = hop;
+    if (!isTrusted(trusted, hop)) return hop;
+  }
+  return ip;
+}
+
+/** Insertion-ordered Map used as an LRU: get() refreshes, set() evicts the oldest past `max`. */
+class Lru<V> {
+  public readonly map = new Map<string, V>();
+  public constructor(private max: () => number) {}
+  public get(k: string): V | undefined {
+    const v = this.map.get(k);
+    if (v !== undefined) { this.map.delete(k); this.map.set(k, v); }
+    return v;
+  }
+  public set(k: string, v: V): void {
+    this.map.delete(k); this.map.set(k, v);
+    while (this.map.size > this.max()) this.map.delete(this.map.keys().next().value!);
+  }
+  public get size(): number { return this.map.size; }
+}
+
+export class GuardLimits {
+  /** Per client IP (only when an IP is known and not loopback). */
+  ip: string = '600/h';
+  /** Per channel name (e.g. `slack`, `api`, `ws`); channels not listed are unlimited. */
+  channel: Record<string, string> = {};
+  /** Max concurrent agent turns across principals ranked below `ceilingBelowRank`. */
+  maxConcurrentTurns: number = 8;
+  ceilingBelowRank: number = 50;
+  /** Auto-block a principal/IP after this many rate-limit hits within `blockWindowMs`… */
+  blockAfter: number = 20;
+  blockWindowMs: number = 10 * 60_000;
+  /** …for this long. */
+  blockTtlMs: number = 60 * 60_000;
+  /** Principals at/above this rank (owner, operator) are rate-limited but never auto-blocked or denied by IP-keyed state. */
+  autoBlockExemptRank: number = 80;
+  /** Cap per in-memory map (buckets, hit windows, blocks). */
+  maxKeys: number = 10_000;
+}
+
+export class GuardOptions {
+  clock: () => number = Date.now;
+  log: Pick<Console, 'info' | 'warn' | 'error'> = console;
+  limits: Partial<GuardLimits> = {};
+  blocksPath: string = dataPath('security', 'blocks.json');
+  /** Writes (blocks.json) only while true. */
+  isActive: () => boolean = () => true;
+  /** False = shadow: compute + audit, never deny. */
+  enforce: () => boolean = enforcing; // the ONE flag that also governs profile enforcement (enforce.ts)
+  /** Audit sink; `dedupeKey` = at most once per window (SecurityRuntime.record semantics). */
+  audit: (event: AuditEvent, dedupeKey?: string) => void = () => {};
+  /** Manual blocklist match (Policy.blocked). */
+  blocklist: (p: Principal) => { reason?: string; until: number | null } | undefined = () => undefined;
+  trustedProxies: BlockList = parseTrustedProxies(process.env.TRUSTED_PROXIES);
+}
+
+interface Bucket { tokens: number; at: number; rate: string }
+
+export class Guard {
+  public options: GuardOptions;
+  public readonly limits: GuardLimits;
+  private buckets: Lru<Bucket>;
+  /** Rate-limit hit times per key, with the authenticated principal id (undefined = anonymous) for shared-IP detection. */
+  private hits: Lru<Array<{ t: number; p?: string }>>;
+  private blocks: Lru<BlockRecord>;
+  private activeTurns = 0;
+
+  public constructor(options?: Partial<GuardOptions>) {
+    this.options = { ...new GuardOptions(), ...options };
+    this.limits = { ...new GuardLimits(), ...this.options.limits };
+    const max = () => this.limits.maxKeys;
+    this.buckets = new Lru(max); this.hits = new Lru(max); this.blocks = new Lru(max);
+    this.load();
+  }
+
+  /** Client IP of an HTTP request / WS upgrade (see clientIp). */
+  public ipOf(req: { socket?: { remoteAddress?: string }; headers: Record<string, string | string[] | undefined> }): string | undefined {
+    return clientIp(req.socket?.remoteAddress, req.headers['x-forwarded-for'], this.options.trustedProxies);
+  }
+
+  public get turnsInFlight(): number { return this.activeTurns; }
+
+  /** Active auto-blocks (for the Console). */
+  public list(): Array<BlockRecord & { key: string }> {
+    const now = this.options.clock();
+    return [...this.blocks.map].filter(([, b]) => b.until > now).map(([key, b]) => ({ key, ...b }));
+  }
+
+  /** Clear an auto-block (Owner Console) and its hit window; persists. False when no such block exists. */
+  public unblock(key: string): boolean {
+    if (!this.blocks.map.delete(key)) return false;
+    this.hits.map.delete(key);
+    this.save();
+    return true;
+  }
+
+  /** blocklist → auto-blocks → rate. Consumes one token from each applicable bucket only when all pass. */
+  public check(input: GuardInput): GuardVerdict {
+    const denial = this.evaluate(input);
+    if (!denial) return { ok: true };
+    return this.options.enforce() ? denial : { ok: true, wouldDeny: denial };
+  }
+
+  /** Concurrency slot for rank < ceilingBelowRank. Returns an idempotent release, or null when the ceiling is reached. */
+  public acquireTurn(rank: number): (() => void) | null {
+    if (rank >= this.limits.ceilingBelowRank) return () => {};
+    if (this.activeTurns >= this.limits.maxConcurrentTurns) return null;
+    this.activeTurns++;
+    let done = false;
+    return () => { if (!done) { done = true; this.activeTurns--; } };
+  }
+
+  /** Run `fn` holding a turn slot; the slot is released however `fn` exits. Throws when the ceiling is reached. */
+  public async withTurn<T>(rank: number, fn: () => T | Promise<T>): Promise<T> {
+    const release = this.acquireTurn(rank);
+    if (!release) throw new Error('guard: concurrent turn ceiling reached');
+    try { return await fn(); } finally { release(); }
+  }
+
+  /** check + acquireTurn, shadow-aware. On ok the caller MUST call `release` when the turn ends (try/finally). */
+  public admit(input: GuardInput): TurnAdmission {
+    const v = this.check(input);
+    if (!v.ok) return v;
+    const release = this.acquireTurn(input.rank);
+    if (release) return v.wouldDeny ? { ok: true, release, wouldDeny: v.wouldDeny } : { ok: true, release };
+    const denial: GuardDenial = { ok: false, status: 429, retryAfter: 5, reason: 'turn-ceiling' };
+    const enforced = this.options.enforce();
+    this.audit({ type: 'guard.limit', principal: input.principal.id, reason: 'turn-ceiling', meta: { key: 'global:turns', max: this.limits.maxConcurrentTurns, rank: input.rank, enforced } }, 'guard.limit|global:turns');
+    return enforced ? denial : { ok: true, release: () => {}, wouldDeny: v.wouldDeny ?? denial };
+  }
+
+  /** Passive → active promotion: merge disk state (the previous active's blocks) and persist. */
+  public activate(): void {
+    const mem = [...this.blocks.map];
+    this.load();
+    for (const [k, b] of mem) { const d = this.blocks.get(k); if (!d || d.until < b.until) this.blocks.set(k, b); }
+    this.save();
+  }
+
+  // ── internals ─────────────────────────────────────────────────────────────
+
+  private evaluate(input: GuardInput): GuardDenial | undefined {
+    const { principal, channel, rank } = input;
+    const now = this.options.clock(), enforced = this.options.enforce();
+    const ip = input.ip && !isLoopback(input.ip) ? input.ip : undefined;
+    const pKey = `principal:${principal.id}`, ipKey = ip ? `ip:${ip}` : undefined;
+    const meta = (extra: Record<string, unknown>) => ({ ...(ip ? { ip } : {}), ...(channel ? { channel } : {}), rank, enforced, ...extra });
+
+    const manual = this.safe(() => this.options.blocklist(principal), undefined);
+    if (manual) {
+      this.audit({ type: 'guard.block', principal: principal.id, reason: manual.reason ?? 'blocklist', meta: meta({ source: 'policy' }) }, `guard.block|policy|${principal.id}`);
+      const retryAfter = manual.until ? Math.max(1, Math.ceil(manual.until - now / 1000)) : undefined;
+      return { ok: false, status: 403, reason: 'blocked', ...(retryAfter ? { retryAfter } : {}) };
+    }
+    // IP-keyed state never denies an exempt rank: a shared IP (NAT, same-host proxy) blocked by a guest must not lock out an owner/operator.
+    const exempt = rank >= this.limits.autoBlockExemptRank;
+    for (const key of [pKey, exempt ? undefined : ipKey]) {
+      const b = key ? this.activeBlock(key, now) : undefined;
+      if (!b) continue;
+      this.audit({ type: 'guard.block', principal: principal.id, target: key, reason: b.reason, meta: meta({ source: 'auto' }) }, `guard.block|auto|${key}`);
+      return { ok: false, status: 403, reason: 'blocked', retryAfter: Math.max(1, Math.ceil((b.until - now) / 1000)) };
+    }
+
+    const wants: Array<[key: string, rate: string, blockable: boolean]> = [[pKey, input.rate, !exempt]];
+    if (ipKey && !exempt) wants.push([ipKey, this.limits.ip, true]);
+    const chRate = channel ? this.limits.channel[channel] : undefined;
+    if (chRate !== undefined) wants.push([`channel:${channel}`, chRate, false]);
+
+    const pending: Array<[string, Bucket]> = [];
+    for (const [key, rate, blockable] of wants) {
+      const r = parseRate(rate);
+      if (!r || r.cap === 0) {
+        // Policy denial ("0" = no access) or a bad rate string — not an abuse signal, so no auto-block.
+        if (!r) this.options.log.error(`[guard] invalid rate "${rate}" for ${key} — denying`);
+        this.audit({ type: 'guard.limit', principal: principal.id, target: key, reason: r ? 'rate-zero' : 'rate-invalid', meta: meta({ rate }) }, `guard.limit|${key}|zero`);
+        return { ok: false, status: 403, reason: r ? 'rate-zero' : 'rate-invalid' };
+      }
+      const prev = this.buckets.get(key);
+      const b: Bucket = prev && prev.rate === rate
+        ? { rate, at: now, tokens: Math.min(r.cap, prev.tokens + (Math.max(0, now - prev.at) * r.cap) / r.periodMs) } // clock stepped back → no refill, never a drain
+        : { rate, at: now, tokens: r.cap };
+      if (b.tokens < 1) {
+        const retryAfter = Math.max(1, Math.ceil(((1 - b.tokens) * r.periodMs) / r.cap / 1000));
+        this.buckets.set(key, b);
+        this.audit({ type: 'guard.limit', principal: principal.id, target: key, reason: 'rate', meta: meta({ rate, retryAfter }) }, `guard.limit|${key}`);
+        if (blockable) this.recordHit(key, principal, now, meta({}));
+        return { ok: false, status: 429, retryAfter, reason: 'rate' };
+      }
+      pending.push([key, b]);
+    }
+    for (const [key, b] of pending) { b.tokens -= 1; this.buckets.set(key, b); }
+    return undefined;
+  }
+
+  private recordHit(key: string, principal: Principal, now: number, meta: Record<string, unknown>): void {
+    const { blockAfter, blockWindowMs, blockTtlMs } = this.limits;
+    const window = (this.hits.get(key) ?? []).filter(h => now - h.t < blockWindowMs);
+    window.push({ t: now, p: principal.kind === 'anonymous' ? undefined : principal.id });
+    if (window.length < blockAfter) return void this.hits.set(key, window.slice(-blockAfter));
+    // An IP whose hits come from >1 authenticated principal is shared (NAT/proxy): throttle, never block it.
+    if (key.startsWith('ip:') && new Set(window.map(h => h.p).filter(Boolean)).size > 1) return void this.hits.set(key, window.slice(-blockAfter));
+    this.hits.map.delete(key);
+    const principalId = principal.id;
+    const rec: BlockRecord = { until: now + blockTtlMs, reason: `auto: ${window.length} limit hits in ${Math.round(blockWindowMs / 1000)}s`, at: now };
+    this.blocks.set(key, rec);
+    this.options.log.warn(`[guard] auto-blocked ${key} until ${new Date(rec.until).toISOString()} (${rec.reason})`);
+    this.audit({ type: 'guard.block', principal: principalId, target: key, reason: rec.reason, meta: { ...meta, source: 'auto', created: true, until: rec.until } });
+    this.save();
+  }
+
+  private activeBlock(key: string, now: number): BlockRecord | undefined {
+    const b = this.blocks.map.get(key);
+    if (!b) return undefined;
+    if (b.until > now) return b;
+    this.blocks.map.delete(key);
+    this.save();
+    return undefined;
+  }
+
+  private audit(event: AuditEvent, dedupeKey?: string): void {
+    this.safe(() => this.options.audit(event, dedupeKey), undefined);
+  }
+
+  private safe<T>(fn: () => T, fallback: T): T {
+    try { return fn(); } catch (e: any) { this.options.log.error(`[guard] hook threw: ${e?.message ?? e}`); return fallback; }
+  }
+
+  private active(): boolean { return this.safe(() => this.options.isActive(), false); }
+
+  /** Read blocks.json, dropping expired/malformed entries (persisting the prune when active). Never throws. */
+  private load(): void {
+    const p = this.options.blocksPath, now = this.options.clock();
+    if (!existsSync(p)) return;
+    let pruned = 0;
+    try {
+      const raw = JSON.parse(readFileSync(p, 'utf8'))?.blocks ?? {};
+      for (const [key, b] of Object.entries<any>(raw)) {
+        if (typeof b?.until === 'number' && b.until > now && typeof key === 'string') this.blocks.set(key, { until: b.until, reason: String(b.reason ?? 'auto'), at: Number(b.at) || now });
+        else pruned++;
+      }
+    } catch (e: any) { this.options.log.error(`[guard] ${p} unreadable — starting with no auto-blocks: ${e.message}`); return; }
+    if (pruned) { this.options.log.info(`[guard] pruned ${pruned} expired block(s) from ${p}`); this.save(); }
+  }
+
+  /** Atomic write of the active blocks. Active instance only. Never throws. */
+  private save(): void {
+    if (!this.active()) return;
+    const p = this.options.blocksPath, now = this.options.clock();
+    const blocks = Object.fromEntries([...this.blocks.map].filter(([, b]) => b.until > now));
+    try {
+      mkdirSync(path.dirname(p), { recursive: true });
+      const tmp = `${p}.${process.pid}.tmp`;
+      writeFileSync(tmp, JSON.stringify({ version: 1, blocks }, null, 2) + '\n', { mode: 0o600 });
+      renameSync(tmp, p);
+    } catch (e: any) { this.options.log.error(`[guard] persisting ${p} failed: ${e.message}`); }
+  }
+}
+
+/** Write a denial to an HTTP response (status + Retry-After). */
+export function writeDenial(res: { status(code: number): { json(body: unknown): unknown }; setHeader(k: string, v: string): unknown }, d: GuardDenial): void {
+  if (d.retryAfter) res.setHeader('Retry-After', String(d.retryAfter));
+  res.status(d.status).json({ error: d.status === 403 ? 'Forbidden' : 'Too many requests', reason: d.reason, ...(d.retryAfter ? { retryAfter: d.retryAfter } : {}) });
+}

package/src/server/security/owner-only.ts

@@ -0,0 +1,34 @@
+// Owner gate for admin actions. `isOwner` is set by requireAuth from the OWNERS env (owners.ts), so this
+// must run AFTER requireAuth. Real enforcement (not shadow): only for system-scope mutations.
+import type { Request, Response, RequestHandler } from 'express';
+import { security } from './runtime.ts';
+
+/** True if the caller is an owner; otherwise responds 403 with `message` and returns false. */
+export function ownerOnly(req: Request, res: Response, message = 'Only an owner can do this'): boolean {
+  if ((req as any).user?.isOwner) return true;
+  res.status(403).json({ error: message });
+  return false;
+}
+
+/** 403 + `auth.deny` audit unless the caller's principal kind is one of `kinds`. */
+function kindGate(kinds: string[], error: string): RequestHandler {
+  return (req, res, next) => {
+    const kind = (req as any).user?.principal?.kind ?? 'unknown';
+    if (kinds.includes(kind)) return next();
+    console.warn(`[owner-only] ${req.method} ${req.path} refused: ${kind} credential`);
+    security()?.authDeny(`http:${req.path}`, `non-interactive:${kind}`, req.ip);
+    res.status(403).json({ error });
+  };
+}
+
+/** Middleware form of ownerOnly, for policy/config/skills/MCP routes. The agent subprocess carries an owner-signed
+ *  internal token (INTERNAL_API_TOKEN), so an internal principal is never owner HERE — otherwise a prompt-injected turn
+ *  could rewrite its own policy. Owner = interactive login or an uncapped owner API key (CLI terminal). Inline
+ *  `ownerOnly` callers (self-upgrade, schedules, modules) keep accepting the internal token. */
+export function requireOwner(message?: string): RequestHandler {
+  const notInternal = kindGate(['user', 'apikey'], 'Owner access requires an interactive login or an owner API key — not the agent\'s internal token');
+  return (req, res, next) => { if (ownerOnly(req, res, message)) notInternal(req, res, next); };
+}
+
+/** Security-console writes: an interactive login only (no API key, no internal token) — same rule as minting a key. */
+export const requireInteractive = (): RequestHandler => kindGate(['user'], 'This change requires an interactive login');

package/src/server/security/owner-routes.ts

@@ -0,0 +1,285 @@
+// Owner-only admin API (`/api/owner/*`). Each route runs requireAuth + requireOwner itself — never router-wide, so
+// mounting this router can't gate unrelated requests. Consumer: the Owner Console (client/components/owner/).
+// Policy writes: validated by Policy's own validatePolicy, saved via policy.save() (provenance holds), audited as
+// `policy.change` with the changed paths only (never values). Every write on a PASSIVE standby → 409.
+import { createHash } from 'node:crypto';
+import { Router, type Request, type Response } from 'express';
+import { requireAuth, type AuthUser } from '../auth.ts';
+import { apiKeyRouter } from '../api-key-routes.ts';
+import { apiKeyPrincipal } from '../api-keys.ts';
+import { getOwners } from '../owners.ts';
+import { canonical, type AuditEventType } from './audit.ts';
+import { matches, validatePolicy, type BindingMatch, type PolicyFile } from './policy.ts';
+import { anonymous, fromAuthUser, fromEmailSender, fromInternal, fromSlack, type Principal } from './principal.ts';
+import { requireInteractive, requireOwner } from './owner-only.ts';
+import { revocablePrincipalId, revokeTokens } from './revocation.ts';
+import { resolvePrincipal, security, type SecurityRuntime } from './runtime.ts';
+
+/** Reads: owner via interactive login or uncapped owner API key (never the agent's internal token). */
+const gate = [requireAuth, requireOwner()];
+/** Writes: interactive login only. */
+const writeGate = [...gate, requireInteractive()];
+/** The raw INTERNAL_API_TOKEN's principal (auth.ts) — no issued-at, so tokensValidAfter can never reject it. */
+const LEGACY_INTERNAL_ID = 'internal:agent-internal';
+const userOf = (req: Request) => (req as any).user as AuthUser;
+/** OWNERS as the principals a block could hit: each owner's login and verified email channel. */
+const ownerPrincipals = () => getOwners().flatMap(e => [fromAuthUser({ uid: e, email: e }), fromEmailSender(e, true)]);
+
+const fail = (res: Response, e: any, status = 400) => {
+  console.warn(`[owner-routes] ${e?.message ?? e}`);
+  res.status(status).json({ error: e?.message ?? String(e) });
+};
+
+const isObj = (v: unknown): v is Record<string, any> => !!v && typeof v === 'object' && !Array.isArray(v);
+const str = (v: unknown) => (typeof v === 'string' && v.trim() ? v.trim() : undefined);
+
+/** Opaque version of a policy document. A PUT carrying a stale version is refused, so a Console tab opened earlier
+ *  can't silently undo a revoke/block made meanwhile. */
+export const policyVersion = (p: PolicyFile) => createHash('sha256').update(canonical(p)).digest('hex').slice(0, 16);
+
+/** Paths that differ, two levels deep (`profiles.standard`, `bindings.2`, `default`) — names only, never values. */
+export function policyDiff(a: object, b: object, max = 30): string[] {
+  const keys = (x: object, y: object) => [...new Set([...Object.keys(x), ...Object.keys(y)])];
+  const out: string[] = [];
+  for (const k of keys(a, b)) {
+    const x = (a as any)[k], y = (b as any)[k];
+    if (canonical(x) === canonical(y)) continue;
+    if (x && y && typeof x === 'object' && typeof y === 'object') {
+      for (const s of keys(x, y)) if (canonical(x[s]) !== canonical(y[s])) out.push(`${k}.${s}`);
+    } else out.push(k);
+  }
+  return out.length > max ? [...out.slice(0, max), `+${out.length - max} more`] : out;
+}
+
+/** The runtime, or an error response: 503 when uninitialized; 409 for a write on a PASSIVE standby. */
+function runtimeOr(res: Response, write = false): SecurityRuntime | undefined {
+  const sec = security();
+  if (!sec) return void res.status(503).json({ error: 'Security runtime not initialized' });
+  if (write) {
+    let active = false;
+    try { active = sec.options.isActive(); } catch (e: any) { console.warn(`[owner-routes] isActive threw — treating as PASSIVE: ${e?.message ?? e}`); }
+    if (!active) return void res.status(409).json({ error: 'Read-only on a PASSIVE standby — use the active instance' });
+  }
+  return sec;
+}
+
+/** Incremental edits (blocklist) start from the current document — refused in fail-closed mode, where saving would
+ *  replace the broken-but-fixable file with the owners-only fallback. A whole-document PUT is the fix path. */
+function requireValidPolicy(res: Response, sec: SecurityRuntime): boolean {
+  if (sec.policy.valid) return true;
+  res.status(409).json({ error: 'Policy is invalid (fail-closed) — fix it with a full policy save first' });
+  return false;
+}
+
+/** validatePolicy → policy.save() → `policy.change` audit. Responds with the error itself; true on success. */
+function commit(req: Request, res: Response, sec: SecurityRuntime, next: PolicyFile, op: string): boolean {
+  const errors = validatePolicy(next);
+  if (errors.length) {
+    console.warn(`[owner-routes] ${op} refused: ${errors.join('; ')}`);
+    res.status(400).json({ error: `Invalid policy: ${errors.join('; ')}`, errors });
+    return false;
+  }
+  const prev = sec.policy.current;
+  try { sec.policy.save(next); } catch (e: any) { fail(res, e, 500); return false; }
+  sec.record({ type: 'policy.change', principal: userOf(req).principal.id, target: op, meta: { changed: policyDiff(prev, sec.policy.current) } });
+  return true;
+}
+
+const KINDS = ['user', 'email', 'slack', 'apikey', 'internal', 'anonymous'];
+
+/** A principal built by the SAME builders the channels use, from `{ kind, id?, email?, verified?, lane?, role?, attrs? }`.
+ *  `role` (apikey only) = the key's role cap; for an apikey, `email` is the creator. */
+export function principalFromDescriptor(d: any): Principal {
+  const kind = d?.kind, email = str(d?.email), id = str(d?.id);
+  const attrs: Record<string, unknown> = isObj(d?.attrs) ? { ...d.attrs } : {};
+  const lane = str(d?.lane) ?? str(attrs.lane), who = id ?? email;
+  if (!KINDS.includes(kind)) throw new Error(`kind must be one of ${KINDS.join(', ')}`);
+  if (kind !== 'anonymous' && !who) throw new Error('id or email is required');
+  let p: Principal;
+  switch (kind) {
+    case 'user': p = fromAuthUser({ uid: who!, email }); break;
+    case 'email': p = fromEmailSender(who!, d?.verified === true); break;
+    case 'slack': p = fromSlack(who!, { email }); break;
+    case 'apikey': p = apiKeyPrincipal({ id: id ?? 'console-test', uid: str(attrs.uid) ?? who!, email: email ?? '', role: str(d?.role) ?? str(attrs.role) }); break;
+    case 'internal': p = fromInternal({ uid: who!, email, lane }); break;
+    default: p = anonymous();
+  }
+  if (typeof d?.verified === 'boolean') p.verified = d.verified;
+  Object.assign(p.attrs, attrs, lane ? { lane } : {});
+  return p;
+}
+
+const DENY_TYPES = new Set<string>(['auth.deny', 'tool.deny', 'guard.block', 'guard.limit']);
+/** Events whose `role` is the ACTING principal's role. Others carry a different subject's role (key.create: the key's cap). */
+const OWN_ROLE_TYPES = new Set<string>(['role.resolve', 'turn.start', 'turn.end', 'tool.allow', 'tool.deny', 'escalate']);
+const PRINCIPAL_SCAN_CAP = 50_000;
+export interface PrincipalRow { id: string; kind: string; lastRole?: string; lastSeen: string; turns: number; denies: number }
+
+/** Principals in the audit since `sinceMs`, most recently seen first. Denies include shadow (would-deny) verdicts. */
+export function recentPrincipals(sec: SecurityRuntime, sinceMs: number, limit: number): { principals: PrincipalRow[]; truncated: boolean } {
+  const rows = new Map<string, PrincipalRow>();
+  let cursor: string | undefined, scanned = 0;
+  do {
+    const page = sec.audit.query({ from: sinceMs, limit: 1000, cursor });
+    for (const r of page.items) {
+      scanned++;
+      if (!r.principal) continue;
+      let row = rows.get(r.principal);
+      if (!row) rows.set(r.principal, row = { id: r.principal, kind: r.principal.split(':')[0], lastSeen: r.ts, turns: 0, denies: 0 });
+      if (!row.lastRole && r.role && OWN_ROLE_TYPES.has(r.type)) row.lastRole = r.role;
+      if (r.type === 'turn.start') row.turns++;
+      else if (DENY_TYPES.has(r.type)) row.denies++;
+    }
+    cursor = page.nextCursor;
+  } while (cursor && scanned < PRINCIPAL_SCAN_CAP);
+  return { principals: [...rows.values()].slice(0, limit), truncated: !!cursor };
+}
+
+const clampInt = (v: unknown, def: number, min: number, max: number) => Math.max(min, Math.min(max, Math.floor(Number(v)) || def));
+const when = (v: unknown): Date | undefined => {
+  const s = str(v);
+  if (!s) return undefined;
+  const d = new Date(/^\d+$/.test(s) ? Number(s) : s);
+  if (Number.isNaN(d.getTime())) throw new Error(`invalid date "${s}"`);
+  return d;
+};
+
+export const ownerRouter = Router();
+
+// ── Tokens + API keys ─────────────────────────────────────────────────────────
+
+/** Invalidate every token issued to a principal until now. Body: { principalId: "user:<email|uid>" | "internal:<uid>" }. */
+ownerRouter.post('/api/owner/tokens/revoke', ...writeGate, (req, res) => {
+  const { principalId } = (req.body ?? {}) as { principalId?: unknown };
+  const id = typeof principalId === 'string' ? revocablePrincipalId(principalId) : null;
+  if (!id) {
+    return void res.status(400).json({
+      error: 'principalId must be "user:<email|uid>" or "internal:<uid>" (the token kinds revocation checks). '
+        + 'To revoke an API key, DELETE /api/owner/api-keys/:id.',
+    });
+  }
+  if (id === LEGACY_INTERNAL_ID) {
+    return void res.status(400).json({
+      error: `${LEGACY_INTERNAL_ID} is the legacy shared internal token, which carries no issue time — it can only be `
+        + 'rotated by changing INTERNAL_API_TOKEN and restarting.',
+    });
+  }
+  try {
+    const validAfter = revokeTokens(id, userOf(req).principal.id);
+    res.json({ ok: true, principalId: id, validAfter });
+  } catch (e: any) { fail(res, e, 409); }
+});
+
+ownerRouter.use(apiKeyRouter({ base: '/api/owner/api-keys', gate, writeGate: [requireInteractive()], asOwner: true }));
+
+// ── Policy ────────────────────────────────────────────────────────────────────
+
+ownerRouter.get('/api/owner/policy', ...gate, (_req, res) => {
+  const sec = runtimeOr(res);
+  if (!sec) return;
+  const policy = sec.policy.current;
+  // ownerIds: a UI hint (hide Block on owner rows); the block route enforces it.
+  res.json({ policy, version: policyVersion(policy), valid: sec.policy.valid, ownerIds: ownerPrincipals().map(p => p.id) });
+});
+
+/** Body: { policy, version } — the whole document; `version` (from GET, required) guards against overwriting a newer
+ *  save. `tokensValidAfter` and `blocklist` always come from the CURRENT policy — they change only via their own routes,
+ *  so a PUT can't un-revoke or un-block. */
+ownerRouter.put('/api/owner/policy', ...writeGate, (req, res) => {
+  const sec = runtimeOr(res, true);
+  if (!sec) return;
+  const { policy, version } = (req.body ?? {}) as { policy?: unknown; version?: unknown };
+  if (!isObj(policy)) return void res.status(400).json({ error: 'Body must be { policy, version }' });
+  const current = sec.policy.current;
+  if (version !== policyVersion(current)) {
+    return void res.status(409).json({ error: version === undefined ? 'version is required — GET the policy first' : 'The policy changed since you loaded it — reload and re-apply your edit' });
+  }
+  const next = { ...policy, tokensValidAfter: current.tokensValidAfter, blocklist: current.blocklist } as PolicyFile;
+  if (commit(req, res, sec, next, 'policy')) res.json({ ok: true, version: policyVersion(sec.policy.current), valid: sec.policy.valid });
+});
+
+/** Resolve a descriptor exactly as a turn would (resolvePrincipal — decide()'s path), without auditing `role.resolve`. */
+ownerRouter.post('/api/owner/policy/test', ...gate, (req, res) => {
+  const sec = runtimeOr(res);
+  if (!sec) return;
+  let p: Principal;
+  try { p = principalFromDescriptor(req.body); } catch (e: any) { return fail(res, e); }
+  const r = resolvePrincipal(sec.policy, p);
+  res.json({ principal: p.id, role: r.role, rank: r.rank, profile: r.profileName, capabilities: r.profile, blocked: sec.policy.blocked(p) ?? null });
+});
+
+// ── Principals ────────────────────────────────────────────────────────────────
+
+/** Query: days (1–90, default 7), limit (1–500, default 200). */
+ownerRouter.get('/api/owner/principals', ...gate, (req, res) => {
+  const sec = runtimeOr(res);
+  if (!sec) return;
+  const days = clampInt(req.query.days, 7, 1, 90), limit = clampInt(req.query.limit, 200, 1, 500);
+  try { res.json({ days, ...recentPrincipals(sec, Date.now() - days * 86_400_000, limit) }); } catch (e: any) { fail(res, e, 500); }
+});
+
+// ── Blocklist ─────────────────────────────────────────────────────────────────
+
+/** Manual entries (policy blocklist, `until` epoch SECONDS) + guard auto-blocks (`until` epoch MS). */
+ownerRouter.get('/api/owner/blocks', ...gate, (_req, res) => {
+  const sec = runtimeOr(res);
+  if (!sec) return;
+  res.json({ manual: sec.policy.current.blocklist.map((b, index) => ({ index, ...b })), auto: sec.guard.list() });
+});
+
+/** Body: { match, until?: epoch seconds | null, reason? } — a manual block. */
+ownerRouter.post('/api/owner/blocks', ...writeGate, (req, res) => {
+  const sec = runtimeOr(res, true);
+  if (!sec || !requireValidPolicy(res, sec)) return;
+  const { match, until = null, reason } = (req.body ?? {}) as { match?: unknown; until?: unknown; reason?: unknown };
+  const owner = isObj(match) && ownerPrincipals().find(p => matches(match as BindingMatch, p));
+  if (owner) return void res.status(400).json({ error: `This block would match the owner ${owner.email ?? owner.id} — owners can't be blocked (change OWNERS instead)` });
+  if (until !== null && (typeof until !== 'number' || until >= 1e11)) return void res.status(400).json({ error: 'until must be epoch SECONDS or null' });
+  if (typeof until === 'number' && until <= Date.now() / 1000) return void res.status(400).json({ error: 'until is in the past' });
+  const next = sec.policy.current;
+  next.blocklist = [...next.blocklist, { match: match as BindingMatch, until, ...(str(reason) ? { reason: str(reason) } : {}) }];
+  if (commit(req, res, sec, next, 'blocklist.add')) res.json({ ok: true, index: next.blocklist.length - 1 });
+});
+
+/** Body: { source: "manual", index, match } (match must still equal the entry at index) | { source: "auto", key }. */
+ownerRouter.delete('/api/owner/blocks', ...writeGate, (req, res) => {
+  const sec = runtimeOr(res, true);
+  if (!sec) return;
+  const b = (req.body ?? {}) as { source?: unknown; index?: unknown; match?: unknown; key?: unknown };
+  if (b.source === 'auto') {
+    if (typeof b.key !== 'string' || !sec.guard.unblock(b.key)) return void res.status(404).json({ error: 'No such auto-block' });
+    sec.record({ type: 'policy.change', principal: userOf(req).principal.id, target: `auto-block:${b.key}`, meta: { op: 'auto-block.clear' } });
+    return void res.json({ ok: true });
+  }
+  if (b.source !== 'manual') return void res.status(400).json({ error: 'source must be "manual" or "auto"' });
+  if (!requireValidPolicy(res, sec)) return;
+  const next = sec.policy.current;
+  const entry = typeof b.index === 'number' && Number.isInteger(b.index) ? next.blocklist[b.index] : undefined;
+  if (!entry) return void res.status(404).json({ error: 'No such manual block' });
+  if (canonical(entry.match) !== canonical(b.match)) return void res.status(409).json({ error: 'The blocklist changed since you loaded it — reload' });
+  next.blocklist = next.blocklist.filter((_, i) => i !== b.index);
+  if (commit(req, res, sec, next, 'blocklist.remove')) res.json({ ok: true });
+});
+
+// The console deliberately exposes no conversation-delete route: the audit log is append-only, and removing a
+// conversation is a manual, on-box operation. The `session.delete` audit type stays for those out-of-band removals.
+
+// ── Audit ─────────────────────────────────────────────────────────────────────
+
+/** Query: from, to (ISO or epoch ms), type (comma list), principal, limit (1–500, default 100), cursor. Newest first. */
+ownerRouter.get('/api/owner/audit', ...gate, (req, res) => {
+  const sec = runtimeOr(res);
+  if (!sec) return;
+  try {
+    const type = str(req.query.type)?.split(',').map(s => s.trim()).filter(Boolean) as AuditEventType[] | undefined;
+    res.json(sec.audit.query({
+      from: when(req.query.from), to: when(req.query.to), type, principal: str(req.query.principal),
+      limit: clampInt(req.query.limit, 100, 1, 500), cursor: str(req.query.cursor),
+    }));
+  } catch (e: any) { fail(res, e, /cursor|date/.test(e?.message ?? '') ? 400 : 500); }
+});
+
+ownerRouter.get('/api/owner/audit/verify', ...gate, (_req, res) => {
+  const sec = runtimeOr(res);
+  if (sec) res.json(sec.audit.verify());
+});