@worca/app 1.5.0 → 1.6.0-rc.2

package/src/broker/slots.mjs

@@ -0,0 +1,180 @@
+// src/broker/slots.mjs
+// Credential slots (plans/credential-broker-design.html §5.3, §6.3): one kind of
+// credential with ONE pinned destination. A request names a slot, never a host, so
+// nothing on worca's side (the catalog, an Ask proposal, an agent's env) can send a
+// key anywhere else (guarantee K2). Pure.
+
+export const PROTOCOLS = Object.freeze(['anthropic', 'openai', 'github']);
+export const AUTH_STYLES = Object.freeze(['x-api-key', 'bearer', 'copilot', 'github-user', 'none']);
+const HEADER_NAME_RE = /^[a-z0-9-]{1,64}$/;
+/** Request headers Copilot's gateway needs beyond the common allowlist (the editor identity). */
+const COPILOT_HEADERS = Object.freeze([
+  'copilot-integration-id', 'editor-version', 'editor-plugin-version', 'openai-intent',
+  'x-github-api-version', 'x-request-id', 'x-initiator', 'copilot-vision-request',
+]);
+export const CREDENTIAL_KINDS = Object.freeze(['per-person', 'operator', 'none']);
+const SLOT_ID_RE = /^[a-z][a-z0-9-]{1,31}$/;
+
+const ANTHROPIC_PATHS = Object.freeze([
+  ['POST', '/v1/messages'],
+  ['POST', '/v1/messages/count_tokens'],
+  ['GET', '/v1/models'],
+]);
+const OPENAI_PATHS = Object.freeze([
+  ['POST', '/v1/chat/completions'],
+  ['POST', '/v1/responses'],
+  ['GET', '/v1/models'],
+]);
+
+/**
+ * The built-in slots. `local` exists only when the operator names its upstream; `github`
+ * ("push as me") only when the operator configured a GitHub App or OAuth App for it.
+ */
+export function builtinSlots({ localUrl = null, github = null } = {}) {
+  const slots = [
+    {
+      // An API key (sk-ant-api…) or a Claude subscription token from `claude setup-token`
+      // (sk-ant-oat…): the broker tells them apart and sends each the way it must be sent.
+      id: 'anthropic', label: 'Anthropic API key or Claude subscription', protocol: 'anthropic',
+      upstream: 'https://api.anthropic.com', auth: 'x-api-key', credential: 'per-person',
+      paths: ANTHROPIC_PATHS, verify: { method: 'GET', path: '/v1/models' },
+      keyHint: 'sk-ant-api… or, from `claude setup-token`, sk-ant-oat…',
+    },
+    {
+      id: 'openai', label: 'OpenAI API key', protocol: 'openai',
+      upstream: 'https://api.openai.com', auth: 'bearer', credential: 'per-person',
+      paths: OPENAI_PATHS, verify: { method: 'GET', path: '/v1/models' },
+      keyHint: 'sk-…',
+    },
+    {
+      id: 'openrouter', label: 'OpenRouter API key', protocol: 'openai',
+      upstream: 'https://openrouter.ai', auth: 'bearer', credential: 'per-person',
+      paths: Object.freeze([['POST', '/api/v1/chat/completions'], ['GET', '/api/v1/models'], ['GET', '/api/v1/key']]),
+      verify: { method: 'GET', path: '/api/v1/key' },
+      keyHint: 'sk-or-…',
+    },
+    {
+      // The upstream is where the token exchange says Copilot's API lives (always a
+      // *.githubcopilot.com host, src/broker/copilot.mjs); this is only the fallback.
+      id: 'copilot', label: 'GitHub Copilot', protocol: 'openai',
+      upstream: 'https://api.githubcopilot.com', auth: 'copilot', credential: 'per-person',
+      paths: Object.freeze([['POST', '/chat/completions'], ['POST', '/responses'], ['POST', '/v1/messages'], ['GET', '/models']]),
+      headers: COPILOT_HEADERS, verify: { exchange: true }, keyHint: '', signIn: 'github-device',
+    },
+  ];
+  if (github && github.clientId) {
+    // Never proxied (no paths): worca asks the broker for a short-lived token for ONE
+    // git or gh call of the acting person (/internal/github-token), and makes the call.
+    slots.push({
+      id: 'github', label: 'GitHub (push as me)', protocol: 'github',
+      upstream: 'https://api.github.com', auth: 'github-user', credential: 'per-person',
+      paths: Object.freeze([]), verify: { github: true }, keyHint: 'or paste a fine-grained token (github_pat_…)',
+      signIn: 'github-device', clientId: github.clientId, scope: github.scope,
+    });
+  }
+  if (localUrl) {
+    slots.push({
+      id: 'local', label: 'Local models', protocol: 'anthropic',
+      upstream: localUrl, auth: 'none', credential: 'none',
+      paths: ANTHROPIC_PATHS, verify: null, keyHint: '',
+    });
+  }
+  return slots;
+}
+
+function isPrivateHost(host) {
+  const h = String(host || '').toLowerCase().replace(/^\[|\]$/g, '');
+  if (h === 'localhost' || h === '::1' || h === 'host.docker.internal' || h.endsWith('.internal') || h.endsWith('.local')) return true;
+  if (/^(fc|fd)[0-9a-f]{2}:/i.test(h)) return true;
+  const m = /^(\d+)\.(\d+)\.\d+\.\d+$/.exec(h);
+  if (!m) return !h.includes('.');          // a bare service name on a private network ("ollama")
+  const [a, b] = [Number(m[1]), Number(m[2])];
+  return a === 127 || a === 10 || (a === 192 && b === 168) || (a === 172 && b >= 16 && b <= 31);
+}
+
+/** An upstream must be an origin: https anywhere, http only on a private network. */
+export function upstreamIssue(v) {
+  let u;
+  try { u = new URL(String(v || '').trim()); } catch { return 'upstream is not a URL'; }
+  if (u.username || u.password) return 'upstream must not carry credentials';
+  if (u.pathname !== '/' || u.search || u.hash) return 'upstream must be an origin only (scheme://host[:port])';
+  if (u.protocol === 'https:') return null;
+  if (u.protocol === 'http:' && isPrivateHost(u.hostname)) return null;
+  return 'upstream must be https (http only for a private or loopback host)';
+}
+
+function normPaths(paths, where) {
+  if (!Array.isArray(paths) || !paths.length) throw new Error(`${where}: paths must be a non-empty array of [METHOD, "/path"]`);
+  return Object.freeze(paths.map((p) => {
+    const [method, path] = Array.isArray(p) ? p : [p?.method, p?.path];
+    const m = String(method || '').toUpperCase();
+    if (!['GET', 'POST'].includes(m)) throw new Error(`${where}: method must be GET or POST`);
+    if (typeof path !== 'string' || !path.startsWith('/') || pathIssue(path)) throw new Error(`${where}: bad path ${JSON.stringify(path)}`);
+    return Object.freeze([m, path]);
+  }));
+}
+
+/**
+ * Merge the operator's slots file over the built-ins: an entry with a built-in id
+ * overrides it field by field, a new id adds a slot. Throws with a message naming
+ * the entry.
+ */
+export function mergeSlots(builtins, extra) {
+  const byId = new Map(builtins.map((s) => [s.id, { ...s }]));
+  if (extra !== undefined && extra !== null) {
+    if (!Array.isArray(extra)) throw new Error('the slots file must hold a JSON array');
+    for (const [i, e] of extra.entries()) {
+      const where = `slots[${i}]`;
+      if (!e || typeof e !== 'object') throw new Error(`${where} must be an object`);
+      if (!SLOT_ID_RE.test(String(e.id || ''))) throw new Error(`${where}: id must match ${SLOT_ID_RE}`);
+      const base = byId.get(e.id) || {};
+      const s = { ...base, ...e };
+      if (!PROTOCOLS.includes(s.protocol)) throw new Error(`${where}: protocol must be one of ${PROTOCOLS.join(', ')}`);
+      if (!AUTH_STYLES.includes(s.auth)) throw new Error(`${where}: auth must be one of ${AUTH_STYLES.join(', ')}`);
+      if (!CREDENTIAL_KINDS.includes(s.credential)) throw new Error(`${where}: credential must be one of ${CREDENTIAL_KINDS.join(', ')}`);
+      const issue = upstreamIssue(s.upstream);
+      if (issue) throw new Error(`${where}: ${issue}`);
+      s.upstream = new URL(s.upstream).origin;
+      // A GitHub ("push as me") slot is never proxied: it keeps no paths.
+      s.paths = s.auth === 'github-user' ? Object.freeze([]) : normPaths(s.paths || (s.protocol === 'openai' ? OPENAI_PATHS : ANTHROPIC_PATHS), where);
+      s.label = typeof s.label === 'string' && s.label.trim() ? s.label.trim() : s.id;
+      if (s.verify && (typeof s.verify !== 'object' || (!s.verify.path && !s.verify.exchange && !s.verify.github))) throw new Error(`${where}: verify must be {method, path}`);
+      if (s.headers !== undefined) {
+        if (!Array.isArray(s.headers) || !s.headers.every((x) => HEADER_NAME_RE.test(String(x).toLowerCase()))) throw new Error(`${where}: headers must be a list of header names`);
+        if (s.headers.some((x) => /^(authorization|x-api-key|cookie|host|proxy-.*)$/i.test(x))) throw new Error(`${where}: headers may not include credential or routing headers`);
+        s.headers = Object.freeze(s.headers.map((x) => String(x).toLowerCase()));
+      }
+      for (const k of ['exchangeUrl', 'deviceBaseUrl']) {
+        if ((s.auth !== 'copilot' && s.auth !== 'github-user') || s[k] === undefined) continue;
+        let origin;
+        try { origin = new URL(s[k]).origin; } catch { throw new Error(`${where}: ${k} is not a URL`); }
+        const issue = upstreamIssue(origin);
+        if (issue) throw new Error(`${where}: ${k}: ${issue}`);
+      }
+      byId.set(s.id, s);
+    }
+  }
+  return [...byId.values()].map((s) => Object.freeze(s));
+}
+
+/**
+ * Why a request path is unsafe to forward, or null. Rejects anything a
+ * normalising upstream could read as a different path: dot segments, empty
+ * segments, encoded slashes/backslashes/dots, backslashes and control chars.
+ */
+export function pathIssue(path) {
+  const p = String(path);
+  if (!p.startsWith('/')) return 'path must start with /';
+  if (/[\u0000-\u001f\u007f\\]/.test(p)) return 'path has control characters or backslashes';
+  if (/%(2f|5c|2e|00)/i.test(p)) return 'path has encoded separators';
+  if (p.includes('//')) return 'path has empty segments';
+  if (p.split('/').some((seg) => seg === '.' || seg === '..')) return 'path has dot segments';
+  return null;
+}
+
+/** Whether `method path` (path WITHOUT the query) is on the slot's allowlist. */
+export function isAllowedPath(slot, method, path) {
+  if (pathIssue(path)) return false;
+  const m = String(method || '').toUpperCase();
+  return slot.paths.some(([pm, pp]) => pm === m && pp === path);
+}

package/src/broker/store.mjs

@@ -0,0 +1,171 @@
+// src/broker/store.mjs
+// The broker's own SQLite database (plans/credential-broker-design.html §6.5):
+// sealed credentials, spawn tokens (hashes only) and usage rows. node:sqlite,
+// synchronous, loaded lazily like src/core/db.mjs. A path of ':memory:' keeps
+// everything in memory (single mode without a data dir, and tests).
+import { createRequire } from 'node:module';
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+const _require = createRequire(import.meta.url);
+
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS credentials (
+  bill_to TEXT NOT NULL, slot TEXT NOT NULL,
+  ciphertext BLOB NOT NULL, iv BLOB NOT NULL, tag BLOB NOT NULL,
+  key_id TEXT NOT NULL, suffix TEXT NOT NULL,
+  created_at TEXT NOT NULL, updated_at TEXT NOT NULL,
+  last_used_at TEXT, verified_at TEXT, verify_error TEXT,
+  daily_usd REAL, monthly_usd REAL,
+  PRIMARY KEY (bill_to, slot));
+CREATE TABLE IF NOT EXISTS tokens (
+  hash TEXT PRIMARY KEY,
+  spawn_id TEXT NOT NULL UNIQUE, run_id TEXT, thread_id TEXT, kind TEXT NOT NULL,
+  bill_to TEXT NOT NULL, slots TEXT NOT NULL, issuer TEXT NOT NULL,
+  created_at TEXT NOT NULL, expires_at TEXT NOT NULL, revoked_at TEXT,
+  budget_usd REAL, spent_usd REAL NOT NULL DEFAULT 0);
+CREATE TABLE IF NOT EXISTS usage (
+  id INTEGER PRIMARY KEY, at TEXT NOT NULL, bill_to TEXT NOT NULL, slot TEXT NOT NULL,
+  spawn_id TEXT, run_id TEXT, model TEXT, status INTEGER,
+  input_tokens INTEGER, output_tokens INTEGER, cache_read_tokens INTEGER, cache_write_tokens INTEGER,
+  usd REAL, ms INTEGER);
+CREATE INDEX IF NOT EXISTS usage_bill_to_at ON usage (bill_to, at);
+CREATE INDEX IF NOT EXISTS usage_run ON usage (run_id);
+CREATE INDEX IF NOT EXISTS tokens_issuer ON tokens (issuer);
+`;
+
+const iso = (ms) => new Date(ms).toISOString();
+
+export function openStore(path = ':memory:') {
+  const { DatabaseSync } = _require('node:sqlite');
+  if (path !== ':memory:') mkdirSync(dirname(path), { recursive: true });
+  const db = new DatabaseSync(path);
+  db.exec('PRAGMA journal_mode = WAL; PRAGMA busy_timeout = 5000;');
+  db.exec(SCHEMA);
+  // Columns added after the first release, on existing databases too:
+  //   credentials.kind   'api-key' | 'subscription' | 'github' (shown without decrypting)
+  //   tokens.isolated    the spawn runs under its person's own agent user (a subscription
+  //                      is only ever used by such a spawn in multi mode)
+  //   usage.plan         'subscription' for calls on a Claude plan (no per-call price)
+  const cols = (t) => new Set(db.prepare(`PRAGMA table_info(${t})`).all().map((r) => r.name));
+  if (!cols('credentials').has('kind')) db.exec('ALTER TABLE credentials ADD COLUMN kind TEXT');
+  if (!cols('tokens').has('isolated')) db.exec('ALTER TABLE tokens ADD COLUMN isolated INTEGER NOT NULL DEFAULT 0');
+  if (!cols('usage').has('plan')) db.exec('ALTER TABLE usage ADD COLUMN plan TEXT');
+  const q = (sql) => db.prepare(sql);
+
+  const s = {
+    db,
+    close() { try { db.close(); } catch { /* already closed */ } },
+
+    // ── credentials ──
+    putCredential({ billTo, slot, sealed, suffix, kind = null, verifiedAt = null, now = Date.now() }) {
+      q(`INSERT INTO credentials (bill_to, slot, ciphertext, iv, tag, key_id, suffix, kind, created_at, updated_at, verified_at, verify_error)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL)
+         ON CONFLICT (bill_to, slot) DO UPDATE SET ciphertext = excluded.ciphertext, iv = excluded.iv, tag = excluded.tag,
+           key_id = excluded.key_id, suffix = excluded.suffix, kind = excluded.kind, updated_at = excluded.updated_at,
+           verified_at = excluded.verified_at, verify_error = NULL`)
+        .run(billTo, slot, sealed.ciphertext, sealed.iv, sealed.tag, sealed.keyId, suffix, kind, iso(now), iso(now), verifiedAt ? iso(verifiedAt) : null);
+    },
+    getCredential(billTo, slot) {
+      return q('SELECT * FROM credentials WHERE bill_to = ? AND slot = ?').get(billTo, slot) || null;
+    },
+    listCredentials(billTo) {
+      return q('SELECT bill_to, slot, suffix, kind, key_id, created_at, updated_at, last_used_at, verified_at, verify_error, daily_usd, monthly_usd FROM credentials WHERE bill_to = ? ORDER BY slot').all(billTo);
+    },
+    allCredentials() {
+      return q('SELECT * FROM credentials').all();
+    },
+    resealCredential(billTo, slot, sealed) {
+      q('UPDATE credentials SET ciphertext = ?, iv = ?, tag = ?, key_id = ? WHERE bill_to = ? AND slot = ?')
+        .run(sealed.ciphertext, sealed.iv, sealed.tag, sealed.keyId, billTo, slot);
+    },
+    deleteCredential(billTo, slot) {
+      return q('DELETE FROM credentials WHERE bill_to = ? AND slot = ?').run(billTo, slot).changes;
+    },
+    markUsed(billTo, slot, now = Date.now()) {
+      q('UPDATE credentials SET last_used_at = ? WHERE bill_to = ? AND slot = ?').run(iso(now), billTo, slot);
+    },
+    setVerify(billTo, slot, { ok, error = null, now = Date.now() }) {
+      q('UPDATE credentials SET verified_at = ?, verify_error = ? WHERE bill_to = ? AND slot = ?')
+        .run(iso(now), ok ? null : String(error || 'rejected').slice(0, 300), billTo, slot);
+    },
+    setCaps(billTo, slot, { dailyUsd = null, monthlyUsd = null }) {
+      return q('UPDATE credentials SET daily_usd = ?, monthly_usd = ? WHERE bill_to = ? AND slot = ?')
+        .run(dailyUsd, monthlyUsd, billTo, slot).changes;
+    },
+
+    // ── tokens ──
+    insertToken(row) {
+      q(`INSERT INTO tokens (hash, spawn_id, run_id, thread_id, kind, bill_to, slots, issuer, created_at, expires_at, budget_usd, isolated)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+        .run(row.hash, row.spawnId, row.runId ?? null, row.threadId ?? null, row.kind, row.billTo,
+          JSON.stringify(row.slots), row.issuer, iso(row.createdAt), iso(row.expiresAt), row.budgetUsd ?? null, row.isolated ? 1 : 0);
+    },
+    tokenByHash(hash) {
+      return q('SELECT * FROM tokens WHERE hash = ?').get(hash) || null;
+    },
+    tokenBySpawn(spawnId) {
+      return q('SELECT * FROM tokens WHERE spawn_id = ?').get(spawnId) || null;
+    },
+    revokeSpawn(spawnId, now = Date.now()) {
+      return q('UPDATE tokens SET revoked_at = ? WHERE spawn_id = ? AND revoked_at IS NULL').run(iso(now), spawnId).changes;
+    },
+    revokeWhere({ issuer, runId, billTo, exceptIssuer }, now = Date.now()) {
+      const where = []; const args = [];
+      if (issuer) { where.push('issuer = ?'); args.push(issuer); }
+      if (exceptIssuer) { where.push('issuer <> ?'); args.push(exceptIssuer); }
+      if (runId) { where.push('run_id = ?'); args.push(runId); }
+      if (billTo) { where.push('bill_to = ?'); args.push(billTo); }
+      if (!where.length) return 0;
+      return q(`UPDATE tokens SET revoked_at = ? WHERE revoked_at IS NULL AND ${where.join(' AND ')}`).run(iso(now), ...args).changes;
+    },
+    addSpend(hash, usd) {
+      if (!(usd > 0)) return;
+      q('UPDATE tokens SET spent_usd = spent_usd + ? WHERE hash = ?').run(usd, hash);
+    },
+    deleteExpiredTokens(now = Date.now()) {
+      // Keep revoked/expired rows for a day so a late request still gets "expired or revoked".
+      return q('DELETE FROM tokens WHERE expires_at < ?').run(iso(now - 86_400_000)).changes;
+    },
+
+    // ── usage ──
+    insertUsage(u) {
+      q(`INSERT INTO usage (at, bill_to, slot, spawn_id, run_id, model, status, input_tokens, output_tokens, cache_read_tokens, cache_write_tokens, usd, ms, plan)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+        .run(iso(u.at ?? Date.now()), u.billTo, u.slot, u.spawnId ?? null, u.runId ?? null, u.model ?? null, u.status ?? null,
+          u.inputTokens ?? 0, u.outputTokens ?? 0, u.cacheReadTokens ?? 0, u.cacheWriteTokens ?? 0, u.usd ?? 0, u.ms ?? null, u.plan ?? null);
+    },
+    spentSince(billTo, slot, sinceMs) {
+      const r = q('SELECT COALESCE(SUM(usd), 0) AS usd FROM usage WHERE bill_to = ? AND slot = ? AND at >= ?').get(billTo, slot, iso(sinceMs));
+      return Number(r?.usd || 0);
+    },
+    queryUsage({ since = null, billTo = null, runId = null, spawnId = null, limit = 1000 } = {}) {
+      const where = []; const args = [];
+      if (since) { where.push('at >= ?'); args.push(since); }
+      if (billTo) { where.push('bill_to = ?'); args.push(billTo); }
+      if (runId) { where.push('run_id = ?'); args.push(runId); }
+      if (spawnId) { where.push('spawn_id = ?'); args.push(spawnId); }
+      const lim = Math.max(1, Math.min(10_000, Number(limit) || 1000));
+      return q(`SELECT at, bill_to AS billTo, slot, spawn_id AS spawnId, run_id AS runId, model, status,
+          input_tokens AS inputTokens, output_tokens AS outputTokens, cache_read_tokens AS cacheReadTokens,
+          cache_write_tokens AS cacheWriteTokens, usd, ms
+        FROM usage ${where.length ? `WHERE ${where.join(' AND ')}` : ''} ORDER BY id DESC LIMIT ${lim}`).all(...args);
+    },
+    /** Spend and volume per person and slot in [since, until): the Stats "By person" card. */
+    summarizeUsage({ since = null, until = null } = {}) {
+      const where = []; const args = [];
+      if (since) { where.push('at >= ?'); args.push(since); }
+      if (until) { where.push('at < ?'); args.push(until); }
+      return q(`SELECT bill_to AS billTo, slot, COALESCE(plan, 'api') AS plan, COUNT(*) AS requests, COALESCE(SUM(usd), 0) AS usd,
+          COALESCE(SUM(input_tokens), 0) AS inputTokens, COALESCE(SUM(output_tokens), 0) AS outputTokens,
+          COALESCE(SUM(cache_read_tokens), 0) AS cacheReadTokens, COALESCE(SUM(cache_write_tokens), 0) AS cacheWriteTokens,
+          COUNT(DISTINCT run_id) AS runs, MAX(at) AS lastAt
+        FROM usage ${where.length ? `WHERE ${where.join(' AND ')}` : ''}
+        GROUP BY bill_to, slot, COALESCE(plan, 'api') ORDER BY usd DESC`).all(...args);
+    },
+    deleteOldUsage(now = Date.now()) {
+      return q('DELETE FROM usage WHERE at < ?').run(iso(now - 400 * 86_400_000)).changes;
+    },
+  };
+  return s;
+}

package/src/broker/tokens.mjs

@@ -0,0 +1,116 @@
+// src/broker/tokens.mjs
+// Per-spawn tokens (plans/credential-broker-design.html §5.4). A token is
+// `wbt_` + 43 base64url chars (32 random bytes). The broker stores only its
+// SHA-256, so a copy of the database cannot be replayed. The `wbt_` prefix exists so
+// worca can redact a token wherever agent output is stored or shown.
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+
+export const TOKEN_PREFIX = 'wbt_';
+export const TOKEN_RE = /^wbt_[A-Za-z0-9_-]{43}$/;
+export const SPAWN_KINDS = Object.freeze(['phase', 'ask', 'aux', 'test']);
+/** Default and maximum lifetime per spawn kind, before the operator's global cap. */
+export const KIND_TTL_MS = Object.freeze({ aux: 10 * 60_000, test: 10 * 60_000, ask: 2 * 3_600_000, phase: 24 * 3_600_000 });
+const ID_RE = /^[A-Za-z0-9._:-]{1,128}$/;
+const EMAIL_RE = /^[^\s@<>]{1,200}(@[^\s@<>]{1,200})?$/;
+
+export function hashToken(token) {
+  return createHash('sha256').update(String(token)).digest('hex');
+}
+
+/** Constant-time string comparison (both sides hashed first so lengths match). */
+export function safeEqual(a, b) {
+  const ha = createHash('sha256').update(String(a ?? '')).digest();
+  const hb = createHash('sha256').update(String(b ?? '')).digest();
+  return timingSafeEqual(ha, hb) && String(a ?? '').length === String(b ?? '').length;
+}
+
+/** Normalise a person id: lower-cased email, or 'local'. null when unusable. */
+export function normalizeBillTo(v) {
+  const s = typeof v === 'string' ? v.trim().toLowerCase() : '';
+  return s && EMAIL_RE.test(s) ? s : null;
+}
+
+/**
+ * Validate a mint request body. Returns {req} or {error}.
+ * @param {object} body {billTo, slots, spawnId, runId?, threadId?, kind, ttlSec?, budgetUsd?, issuer}
+ */
+export function parseMintRequest(body, { slotIds, maxTtlMs }) {
+  const b = body && typeof body === 'object' ? body : {};
+  const billTo = normalizeBillTo(b.billTo);
+  if (!billTo) return { error: 'billTo must be an email or "local"' };
+  if (!Array.isArray(b.slots) || !b.slots.length || !b.slots.every((s) => slotIds.includes(s))) {
+    return { error: `slots must be a non-empty list of known slots (${slotIds.join(', ')})` };
+  }
+  if (!ID_RE.test(String(b.spawnId || ''))) return { error: 'spawnId is required ([A-Za-z0-9._:-], at most 128)' };
+  if (!ID_RE.test(String(b.issuer || ''))) return { error: 'issuer is required' };
+  for (const k of ['runId', 'threadId']) {
+    if (b[k] != null && !ID_RE.test(String(b[k]))) return { error: `${k} has unsupported characters` };
+  }
+  const kind = SPAWN_KINDS.includes(b.kind) ? b.kind : null;
+  if (!kind) return { error: `kind must be one of ${SPAWN_KINDS.join(', ')}` };
+  const kindMax = KIND_TTL_MS[kind];
+  let ttlMs = kindMax;
+  if (b.ttlSec != null) {
+    const n = Number(b.ttlSec);
+    if (!Number.isFinite(n) || n <= 0) return { error: 'ttlSec must be a positive number' };
+    ttlMs = Math.min(n * 1000, kindMax);
+  }
+  ttlMs = Math.min(ttlMs, maxTtlMs);
+  let budgetUsd = null;
+  if (b.budgetUsd != null) {
+    const n = Number(b.budgetUsd);
+    if (!Number.isFinite(n) || n < 0) return { error: 'budgetUsd must be a number >= 0' };
+    budgetUsd = n;
+  }
+  return {
+    req: {
+      billTo, slots: [...new Set(b.slots)], spawnId: String(b.spawnId), issuer: String(b.issuer),
+      runId: b.runId != null ? String(b.runId) : null, threadId: b.threadId != null ? String(b.threadId) : null,
+      kind, ttlMs, budgetUsd,
+      // worca says so when the spawn runs under its person's own agent user (agent-pool.mjs):
+      // only then may a personal Claude subscription be used for it in multi mode.
+      isolated: b.isolated === true,
+    },
+  };
+}
+
+/** Mint and store a token. Returns {token, expiresAt}. A reused spawnId revokes the old token first. */
+export function mintToken(store, req, now = Date.now()) {
+  const old = store.tokenBySpawn(req.spawnId);
+  if (old) {
+    store.revokeSpawn(req.spawnId, now);
+    store.db.prepare('DELETE FROM tokens WHERE spawn_id = ?').run(req.spawnId);
+  }
+  const token = TOKEN_PREFIX + randomBytes(32).toString('base64url');
+  const expiresAt = now + req.ttlMs;
+  store.insertToken({ ...req, hash: hashToken(token), createdAt: now, expiresAt });
+  return { token, expiresAt: new Date(expiresAt).toISOString() };
+}
+
+/**
+ * Look a presented token up. Returns {row} for a live token, or {error} naming why
+ * it is refused ('missing' | 'malformed' | 'unknown' | 'revoked' | 'expired').
+ */
+export function resolveToken(store, token, now = Date.now()) {
+  if (!token) return { error: 'missing' };
+  if (!TOKEN_RE.test(token)) return { error: 'malformed' };
+  const row = store.tokenByHash(hashToken(token));
+  if (!row) return { error: 'unknown' };
+  if (row.revoked_at) return { error: 'revoked' };
+  if (Date.parse(row.expires_at) <= now) return { error: 'expired' };
+  let slots = [];
+  try { slots = JSON.parse(row.slots); } catch { slots = []; }
+  return { row: { ...row, slots } };
+}
+
+/** The token a request carries: `x-api-key`, or `Authorization: Bearer`. */
+export function tokenFromHeaders(headers) {
+  const k = headers['x-api-key'];
+  if (typeof k === 'string' && k.trim()) return k.trim();
+  const a = headers.authorization;
+  if (typeof a === 'string') {
+    const m = /^Bearer\s+(\S+)\s*$/i.exec(a);
+    if (m) return m[1];
+  }
+  return null;
+}

package/src/broker/ui/page.css

@@ -0,0 +1,54 @@
+:root{
+  color-scheme:light dark;
+  --bg:light-dark(#F1F1EF,#161614);
+  --panel:light-dark(#FFFFFF,#222220);
+  --field:light-dark(#F6F6F4,#2C2C29);
+  --ink:light-dark(#19191B,#ECECE8);
+  --ink-2:light-dark(#5C5C63,#B4B4AE);
+  --line:light-dark(#E3E3E0,#3A3A36);
+  --accent:light-dark(#2B6A8C,#86C4E3);
+  --on-accent:light-dark(#FFFFFF,#161614);
+  --ok-bg:light-dark(#E2F3DF,#1C2F1D); --ok:light-dark(#2F7A38,#8FD48F);
+  --err-bg:light-dark(#FBE3E0,#34201D); --err:light-dark(#C5483A,#F08C7E);
+  --na-bg:light-dark(#ECECEA,#30302D); --na:light-dark(#5C5C63,#B4B4AE);
+  --info-bg:light-dark(#DEEFF7,#1A2A33); --info:light-dark(#3782A8,#86C4E3);
+}
+*{box-sizing:border-box}
+/* The page toggles rows with the hidden attribute; author display rules (.row) must not win. */
+[hidden]{display:none!important}
+body{margin:0;background:var(--bg);color:var(--ink);font:15px/1.55 system-ui,-apple-system,"Segoe UI",Roboto,sans-serif;padding-inline:16px}
+.page{max-width:760px;margin:0 auto;padding-block:40px 64px}
+.head{display:flex;justify-content:space-between;align-items:flex-start;gap:16px;flex-wrap:wrap}
+h1{font-size:24px;line-height:1.2;margin:0 0 4px}
+.who{margin:0;color:var(--ink-2);font-size:14px}
+.back{color:var(--accent);font-size:14px}
+.intro{color:var(--ink-2);font-size:14px;max-width:62ch;margin:14px 0 20px}
+.banner{padding:10px 14px;border-radius:8px;font-size:14px;margin:0 0 16px}
+.banner.err{background:var(--err-bg);color:var(--err)}
+.slots{display:grid;gap:18px}
+.slot{background:var(--panel);border:1px solid var(--line);border-radius:10px;padding:16px}
+.slot-top{display:grid;grid-template-columns:minmax(0,1fr) auto;gap:8px 16px;align-items:center}
+.slot h2{font-size:16px;margin:0}
+.meta{font-size:13px;color:var(--ink-2);margin:2px 0 0}
+.chip{display:inline-block;font-size:12px;font-weight:600;padding:4px 9px;border-radius:999px;white-space:nowrap}
+.chip.set{background:var(--ok-bg);color:var(--ok)}
+.chip.missing{background:var(--na-bg);color:var(--na)}
+.chip.invalid{background:var(--err-bg);color:var(--err)}
+.chip.keyless,.chip.operator{background:var(--info-bg);color:var(--info)}
+.row{display:flex;flex-wrap:wrap;gap:8px;align-items:center;margin-top:12px}
+.row .grow{flex:1 1 240px;min-width:0}
+input{font:inherit;color:var(--ink);background:var(--field);border:1px solid var(--line);border-radius:6px;padding:0 10px;height:34px;width:100%}
+input:focus-visible,button:focus-visible,a:focus-visible{outline:2px solid var(--accent);outline-offset:2px}
+button{font:inherit;font-size:13px;font-weight:500;height:34px;padding:0 12px;border-radius:6px;border:1px solid var(--line);background:var(--panel);color:var(--ink);cursor:pointer}
+button.primary{background:var(--accent);border-color:var(--accent);color:var(--on-accent)}
+button.danger{color:var(--err)}
+button:disabled{opacity:.6;cursor:default}
+.msg{font-size:13px;margin:8px 0 0}
+.msg.ok{color:var(--ok)}
+.msg.err{color:var(--err)}
+.caps{display:flex;flex-wrap:wrap;gap:8px 16px;align-items:center;font-size:13px;color:var(--ink-2);margin-top:12px}
+.caps label{display:flex;gap:6px;align-items:center}
+.caps input{width:90px}
+.code{font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:15px;letter-spacing:.08em}
+.usage{font-size:13px;color:var(--ink-2);margin:10px 0 0;font-variant-numeric:tabular-nums}
+@media (max-width:520px){.slot-top{grid-template-columns:minmax(0,1fr)}}

package/src/broker/ui/page.html

@@ -0,0 +1,25 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Your model credentials · worca</title>
+<link rel="icon" href="data:,">
+<link rel="stylesheet" href="/page.css">
+<script type="module" src="/page.mjs"></script>
+</head>
+<body>
+<main class="page">
+  <header class="head">
+    <div>
+      <h1>Your model credentials</h1>
+      <p class="who" id="who">Loading…</p>
+    </div>
+    <a class="back" id="back" href="#" hidden>Back to worca</a>
+  </header>
+  <p class="intro">Your keys are stored encrypted by the credential broker and are never shown again, to anyone. Runs, chats and code on this worca are still visible to your teammates.</p>
+  <p class="banner err" id="error" role="alert" hidden></p>
+  <section class="slots" id="slots" aria-live="polite"></section>
+</main>
+</body>
+</html>