@worca/app 1.5.0-rc.3 → 1.6.0-rc.1

package/src/broker/ui/page.mjs

@@ -0,0 +1,202 @@
+// The key page's script (src/broker/ui-server.mjs serves it). No framework, no
+// third-party code: everything on this page talks only to this origin.
+const $ = (sel) => document.querySelector(sel);
+let csrf = '';
+let me = null;
+
+const STATE_TEXT = { set: 'Set', missing: 'Not set', invalid: 'Rejected', keyless: 'No key needed', operator: 'Provided by the team' };
+
+function el(tag, attrs = {}, ...kids) {
+  const n = document.createElement(tag);
+  for (const [k, v] of Object.entries(attrs)) {
+    if (v === null || v === undefined || v === false) continue;
+    if (k === 'class') n.className = v;
+    else if (k.startsWith('on')) n.addEventListener(k.slice(2), v);
+    else n.setAttribute(k, v === true ? '' : v);
+  }
+  for (const k of kids.flat()) if (k !== null && k !== undefined && k !== false) n.append(k);
+  return n;
+}
+
+const usd = (n) => `$${(Number(n) || 0).toFixed(2)}`;
+const when = (iso) => {
+  if (!iso) return '';
+  const d = new Date(iso);
+  const mins = Math.round((Date.now() - d.getTime()) / 60000);
+  if (mins < 1) return 'just now';
+  if (mins < 60) return `${mins} minute${mins === 1 ? '' : 's'} ago`;
+  if (mins < 48 * 60) return `${Math.round(mins / 60)} hours ago`;
+  return d.toISOString().slice(0, 10);
+};
+
+async function api(method, path, body) {
+  const res = await fetch(path, {
+    method,
+    headers: { 'content-type': 'application/json', 'x-worca-csrf': csrf },
+    body: body === undefined ? undefined : JSON.stringify(body),
+    credentials: 'same-origin',
+  });
+  let data = {};
+  try { data = await res.json(); } catch { /* empty */ }
+  if (!res.ok) throw new Error(data.error || `HTTP ${res.status}`);
+  return data;
+}
+
+function showError(text) {
+  const e = $('#error');
+  e.textContent = text || '';
+  e.hidden = !text;
+}
+
+function slotCard(slot) {
+  const card = el('article', { class: 'slot', id: `slot-${slot.id}` });
+  const msg = el('p', { class: 'msg', hidden: true, role: 'status' });
+  const say = (text, ok) => { msg.textContent = text; msg.className = `msg ${ok ? 'ok' : 'err'}`; msg.hidden = !text; };
+  const kindText = slot.kind === 'subscription' ? ' · Claude subscription' : '';
+  const chipText = (slot.state === 'set' && slot.suffix ? `Set ••••${slot.suffix}` : STATE_TEXT[slot.state] || slot.state) + (slot.state === 'set' ? kindText : '');
+  // GitHub ("push as me"): a GitHub sign-in, or a pasted fine-grained token, both.
+  const pasteToo = slot.id === 'github' || slot.protocol === 'github';
+
+  const metaParts = [];
+  if (slot.updatedAt) metaParts.push(`added ${when(slot.updatedAt)}`);
+  if (slot.lastUsedAt) metaParts.push(`used ${when(slot.lastUsedAt)}`);
+  if (slot.state === 'invalid' && slot.verifyError) metaParts.push(`last check: ${slot.verifyError}`);
+  if (slot.state === 'missing' && slot.credential === 'per-person') metaParts.push('Runs on these models are refused until you add a key');
+
+  card.append(el('div', { class: 'slot-top' },
+    el('div', {}, el('h2', {}, slot.label), metaParts.length ? el('p', { class: 'meta' }, metaParts.join(' · ')) : null),
+    el('span', { class: `chip ${slot.state}` }, chipText)));
+
+  if (slot.credential === 'per-person' && slot.signIn === 'github-device') {
+    card.append(githubSignIn(slot, say));
+    if (slot.protocol === 'github') {
+      card.append(el('p', { class: 'meta' }, "worca's pushes and pull requests for runs you start go out as you. Nothing here is ever given to an agent."));
+    }
+  }
+  if (slot.credential === 'per-person' && (slot.signIn !== 'github-device' || pasteToo)) {
+    const input = el('input', { type: 'password', id: `key-${slot.id}`, autocomplete: 'off', spellcheck: 'false', placeholder: slot.keyHint ? `Paste your key (${slot.keyHint})` : 'Paste your key', 'aria-label': `${slot.label}` });
+    const form = el('div', { class: 'row', hidden: slot.state === 'set' || (pasteToo && slot.state !== 'invalid') });
+    const save = el('button', { class: 'primary', type: 'button' }, 'Save');
+    save.addEventListener('click', async () => {
+      if (!input.value.trim()) { say('Paste the key first.', false); return; }
+      save.disabled = true; say('Checking the key with the provider…', true);
+      try {
+        await api('PUT', `/api/slots/${slot.id}`, { secret: input.value });
+        input.value = '';
+        await load(slot.protocol === 'github' ? 'Saved. GitHub accepted the token.' : `Saved. The provider accepted your ${slot.label}.`, slot.id);
+      } catch (err) { say(err.message, false); save.disabled = false; }
+    });
+    form.append(el('div', { class: 'grow' }, input), save);
+    if (slot.state === 'set') {
+      form.append(el('button', { type: 'button', onclick: () => { form.hidden = true; actions.hidden = false; say('', true); } }, 'Cancel'));
+    }
+
+    const actions = el('div', { class: 'row', hidden: slot.state !== 'set' && slot.state !== 'invalid' });
+    const test = el('button', { type: 'button' }, 'Test');
+    test.addEventListener('click', async () => {
+      test.disabled = true; say('Testing…', true);
+      try { await api('POST', `/api/slots/${slot.id}/test`); say('The provider accepted the key.', true); }
+      catch (err) { say(err.message, false); }
+      test.disabled = false;
+    });
+    const replace = el('button', { type: 'button', onclick: () => { form.hidden = false; actions.hidden = true; input.focus(); } }, pasteToo ? 'Paste a token instead' : 'Replace');
+    const del = el('button', { type: 'button', class: 'danger' }, 'Delete');
+    const confirmRow = el('div', { class: 'row', hidden: true },
+      el('span', { class: 'grow' }, `Delete your ${slot.label}? Runs using it will pause until you add another.`),
+      el('button', { type: 'button', class: 'danger', onclick: async () => {
+        try { await api('DELETE', `/api/slots/${slot.id}`); await load(`Deleted your ${slot.label}.`, slot.id); }
+        catch (err) { say(err.message, false); }
+      } }, 'Delete key'),
+      el('button', { type: 'button', onclick: () => { confirmRow.hidden = true; actions.hidden = false; } }, 'Keep it'));
+    del.addEventListener('click', () => { confirmRow.hidden = false; actions.hidden = true; say('', true); });
+    // GitHub: the sign-in box above already has "Sign in again" and "Sign out"; here only
+    // pasting a token is offered (always shown when nothing is set yet).
+    if (pasteToo) {
+      actions.append(replace);
+      actions.hidden = false;
+    } else actions.append(test, replace, del);
+    if (slot.state === 'invalid') form.hidden = false;
+    card.append(form, actions, confirmRow);
+
+    if (slot.kind === 'subscription' && slot.state === 'set') {
+      card.append(el('p', { class: 'usage' }, "Runs on your Claude plan: no per-call cost, and your plan's usage limits apply. Only agents that run under your own user use it."));
+    } else if (!pasteToo && (slot.state === 'set' || slot.state === 'invalid')) {
+      const u = me.usage?.[slot.id] || { todayUsd: 0, monthUsd: 0 };
+      card.append(el('p', { class: 'usage' }, `Today ${usd(u.todayUsd)} · This month ${usd(u.monthUsd)}`));
+      const dIn = el('input', { type: 'number', min: '0', step: '1', id: `daily-${slot.id}`, value: slot.dailyUsd ?? '', placeholder: me.defaults?.dailyUsd != null ? String(me.defaults.dailyUsd) : 'none' });
+      const mIn = el('input', { type: 'number', min: '0', step: '1', id: `monthly-${slot.id}`, value: slot.monthlyUsd ?? '', placeholder: me.defaults?.monthlyUsd != null ? String(me.defaults.monthlyUsd) : 'none' });
+      const saveCaps = el('button', { type: 'button' }, 'Save caps');
+      saveCaps.addEventListener('click', async () => {
+        try { await api('PUT', `/api/budget/${slot.id}`, { dailyUsd: dIn.value, monthlyUsd: mIn.value }); say('Spending caps saved.', true); }
+        catch (err) { say(err.message, false); }
+      });
+      card.append(el('div', { class: 'caps' },
+        el('label', { for: `daily-${slot.id}` }, 'Daily cap $', dIn),
+        el('label', { for: `monthly-${slot.id}` }, 'Monthly cap $', mIn),
+        saveCaps));
+    }
+  }
+  card.append(msg);
+  return { card, say };
+}
+
+/** Copilot: GitHub's device sign-in, run by the broker. The page only shows the code. */
+function githubSignIn(slot, say) {
+  const box = el('div', {});
+  const signedIn = slot.state === 'set' || slot.state === 'invalid';
+  const start = el('button', { type: 'button', class: signedIn ? '' : 'primary' }, signedIn ? 'Sign in again' : 'Sign in with GitHub');
+  const codeRow = el('div', { class: 'row', hidden: true });
+  const actions = el('div', { class: 'row' }, start);
+  if (signedIn) {
+    const del = el('button', { type: 'button', class: 'danger' }, 'Sign out');
+    del.addEventListener('click', async () => {
+      try { await api('DELETE', `/api/slots/${slot.id}`); await load('Signed out of GitHub Copilot.', slot.id); }
+      catch (err) { say(err.message, false); }
+    });
+    actions.append(del);
+  }
+  let timer = null;
+  start.addEventListener('click', async () => {
+    start.disabled = true; say('', true);
+    let flow;
+    try { flow = await api('POST', `/api/slots/${slot.id}/device`); }
+    catch (err) { say(err.message, false); start.disabled = false; return; }
+    const link = el('a', { href: flow.verificationUri, target: '_blank', rel: 'noopener' }, flow.verificationUri);
+    codeRow.replaceChildren(el('span', { class: 'grow' }, 'Enter ', el('strong', { class: 'code' }, flow.userCode), ' at ', link, ', then come back here.'));
+    codeRow.hidden = false;
+    let wait = Math.max(2, flow.interval || 5) * 1000;
+    const poll = async () => {
+      try {
+        const r = await api('POST', `/api/slots/${slot.id}/device/poll`);
+        if (r.pending) { if (r.slowDown) wait += 5000; timer = setTimeout(poll, wait); return; }
+        await load('Signed in. GitHub Copilot works for your runs now.', slot.id);
+      } catch (err) { codeRow.hidden = true; start.disabled = false; say(err.message, false); }
+    };
+    timer = setTimeout(poll, wait);
+  });
+  window.addEventListener('beforeunload', () => clearTimeout(timer));
+  box.append(actions, codeRow);
+  return box;
+}
+
+async function load(notice = '', focusSlot = null) {
+  try {
+    const res = await fetch('/api/me', { credentials: 'same-origin' });
+    if (!res.ok) throw new Error(res.status === 401 ? 'Your sign-in has expired. Reload the page to sign in again.' : `Could not load your credentials (HTTP ${res.status}).`);
+    me = await res.json();
+  } catch (err) { showError(err.message); return; }
+  showError('');
+  csrf = me.csrf;
+  $('#who').textContent = `Signed in as ${me.email}`;
+  const back = $('#back');
+  if (me.returnUrl) { back.href = me.returnUrl; back.hidden = false; }
+  const list = $('#slots');
+  list.replaceChildren();
+  for (const slot of me.slots) {
+    const { card, say } = slotCard(slot);
+    list.append(card);
+    if (notice && slot.id === focusSlot) say(notice, true);
+  }
+}
+
+load();

package/src/broker/ui-server.mjs

@@ -0,0 +1,217 @@
+// src/broker/ui-server.mjs
+// The key page (plans/credential-broker-design.html §5.6, §7.1): each person saves,
+// tests and deletes their own credentials here, at the broker's own hostname, behind
+// its own Access application. The broker checks the identity itself and never trusts
+// worca for it. Keys can be written, never read back.
+import { readFileSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { createAccessVerifier } from '../core/cf-access.mjs';
+import { safeEqual, normalizeBillTo } from './tokens.mjs';
+import { startOfUtcDay, startOfUtcMonth } from './limits.mjs';
+import { startDeviceFlow, pollDeviceFlow, githubSecretOf } from './copilot.mjs';
+
+const UI_DIR = fileURLToPath(new URL('./ui/', import.meta.url));
+const STATIC = Object.freeze({
+  '/': { file: 'page.html', type: 'text/html; charset=utf-8' },
+  '/page.mjs': { file: 'page.mjs', type: 'text/javascript; charset=utf-8' },
+  '/page.css': { file: 'page.css', type: 'text/css; charset=utf-8' },
+});
+export const CSP = "default-src 'none'; script-src 'self'; style-src 'self'; img-src 'self' data:; connect-src 'self'; form-action 'self'; base-uri 'none'; frame-ancestors 'none'";
+const CSRF_COOKIE = 'wb_csrf';
+
+export function securityHeaders() {
+  return {
+    'content-security-policy': CSP,
+    'x-frame-options': 'DENY',
+    'x-content-type-options': 'nosniff',
+    'referrer-policy': 'no-referrer',
+    'cache-control': 'no-store',
+    'cross-origin-opener-policy': 'same-origin',
+    'cross-origin-resource-policy': 'same-origin',
+  };
+}
+
+function send(res, status, body, type = 'application/json', extra = {}) {
+  const s = typeof body === 'string' ? body : JSON.stringify(body);
+  res.writeHead(status, { ...securityHeaders(), 'content-type': type, 'content-length': Buffer.byteLength(s), ...extra });
+  res.end(s);
+}
+
+function cookies(req) {
+  const out = {};
+  for (const part of String(req.headers.cookie || '').split(';')) {
+    const i = part.indexOf('=');
+    if (i > 0) out[part.slice(0, i).trim()] = part.slice(i + 1).trim();
+  }
+  return out;
+}
+
+function readJson(req, limit = 16 << 10) {
+  return new Promise((resolveP, rejectP) => {
+    const parts = []; let n = 0;
+    req.on('data', (c) => { n += c.length; if (n > limit) { rejectP(new Error('too large')); req.destroy(); return; } parts.push(c); });
+    req.on('end', () => { try { resolveP(n ? JSON.parse(Buffer.concat(parts).toString('utf8')) : {}); } catch { rejectP(new Error('bad json')); } });
+    req.on('error', rejectP);
+  });
+}
+
+/** The identity resolver for the key page: Access JWT, a trusted header, or none. */
+export function createIdentity(config, { fetchImpl } = {}) {
+  const id = config.identity;
+  if (id?.kind === 'access') {
+    const verify = createAccessVerifier({ teamDomain: id.teamDomain, aud: id.aud, ...(fetchImpl ? { fetchImpl } : {}) });
+    return async (req) => {
+      const token = req.headers['cf-access-jwt-assertion'];
+      if (typeof token !== 'string' || !token) return null;
+      const who = await verify(token);
+      return who?.email ? normalizeBillTo(who.email) : null;
+    };
+  }
+  if (id?.kind === 'header') {
+    return async (req) => {
+      const v = req.headers[id.header];
+      return normalizeBillTo(Array.isArray(v) ? v[0] : v);
+    };
+  }
+  return async () => null;
+}
+
+/**
+ * @param {{config:object, service:object, store:object, identity?:(req)=>Promise<string|null>, now?:()=>number, log?:Function}} o
+ * @returns {(req, res) => void}
+ */
+export function createUiHandler({ config, service, store, identity = createIdentity(config), now = Date.now, log = () => {} }) {
+  const staticCache = new Map();
+  const readStatic = (entry) => {
+    if (!staticCache.has(entry.file)) staticCache.set(entry.file, readFileSync(UI_DIR + entry.file, 'utf8'));
+    return staticCache.get(entry.file);
+  };
+  const secureCookie = String(config.publicUrl || '').startsWith('https:') ? '; Secure' : '';
+  const deviceFlows = new Map();   // "<email>|<slot>" -> {deviceCode, expiresAt}: in memory, per sign-in attempt
+
+  function usageFor(email) {
+    const t = now();
+    const out = {};
+    for (const s of service.slots) {
+      out[s.id] = { todayUsd: store.spentSince(email, s.id, startOfUtcDay(t)), monthUsd: store.spentSince(email, s.id, startOfUtcMonth(t)) };
+    }
+    return out;
+  }
+
+  /** A state-changing request must come from the key page itself. */
+  function csrfOk(req) {
+    const origin = String(req.headers.origin || '');
+    if (!config.publicUrl || origin !== config.publicUrl) return false;
+    const c = cookies(req)[CSRF_COOKIE];
+    const h = req.headers['x-worca-csrf'];
+    return !!c && typeof h === 'string' && safeEqual(c, h);
+  }
+
+  async function handle(req, res) {
+    const url = new URL(req.url || '/', 'http://keys');
+    const p = url.pathname;
+    if (req.method === 'GET' && p === '/healthz') { send(res, 200, { ok: true, version: config.version || null, mode: config.mode }); return; }
+
+    let email;
+    try { email = await identity(req); }
+    catch { send(res, 503, { error: 'cannot verify the sign-in token right now' }); return; }
+    if (!email) { send(res, 401, { error: 'unauthorized: sign in through the identity proxy' }); return; }
+
+    if (req.method === 'GET' && STATIC[p]) { send(res, 200, readStatic(STATIC[p]), STATIC[p].type); return; }
+
+    if (req.method === 'GET' && p === '/api/me') {
+      let csrf = cookies(req)[CSRF_COOKIE];
+      if (!csrf || !/^[A-Za-z0-9_-]{43}$/.test(csrf)) csrf = randomBytes(32).toString('base64url');
+      send(res, 200, {
+        email, returnUrl: config.returnUrl, csrf,
+        slots: service.slotStatus(email), usage: usageFor(email),
+        defaults: { dailyUsd: config.defaultDailyUsd, monthlyUsd: config.defaultMonthlyUsd },
+      }, 'application/json', { 'set-cookie': `${CSRF_COOKIE}=${csrf}; Path=/; HttpOnly; SameSite=Strict${secureCookie}` });
+      return;
+    }
+
+    const m = /^\/api\/(slots|budget)\/([a-z][a-z0-9-]{1,31})(\/test|\/device|\/device\/poll)?$/.exec(p);
+    if (!m) { send(res, 404, { error: 'not found' }); return; }
+    if (!csrfOk(req)) { send(res, 403, { error: 'refused: this request did not come from the key page' }); return; }
+    const [, kind, slotId, sub] = m;
+    const test = sub === '/test';
+    if (!service.slotById.has(slotId)) { send(res, 404, { error: 'unknown slot' }); return; }
+
+    // GitHub device sign-in (Copilot): the broker runs the flow and keeps the resulting
+    // GitHub token sealed; neither the page nor worca ever holds it.
+    if (kind === 'slots' && (sub === '/device' || sub === '/device/poll') && req.method === 'POST') {
+      const slot = service.slotById.get(slotId);
+      if (slot.signIn !== 'github-device') { send(res, 404, { error: 'this credential has no sign-in flow' }); return; }
+      const key = `${email}|${slotId}`;
+      if (sub === '/device') {
+        try {
+          const f = await startDeviceFlow({ fetchImpl: service.fetchImpl, ...(slot.deviceBaseUrl ? { baseUrl: slot.deviceBaseUrl } : {}), ...(slot.clientId ? { clientId: slot.clientId, scope: slot.scope } : {}) });
+          deviceFlows.set(key, { deviceCode: f.deviceCode, expiresAt: now() + f.expiresIn * 1000 });
+          send(res, 200, { userCode: f.userCode, verificationUri: f.verificationUri, interval: f.interval, expiresIn: f.expiresIn });
+        } catch (err) { send(res, 502, { error: err.message }); }
+        return;
+      }
+      const flow = deviceFlows.get(key);
+      if (!flow || flow.expiresAt < now()) { deviceFlows.delete(key); send(res, 410, { error: 'the sign-in code expired: start again' }); return; }
+      let r;
+      try { r = await pollDeviceFlow(flow.deviceCode, { fetchImpl: service.fetchImpl, ...(slot.deviceBaseUrl ? { baseUrl: slot.deviceBaseUrl } : {}), ...(slot.clientId ? { clientId: slot.clientId } : {}) }); }
+      catch (err) { send(res, 502, { error: err.message }); return; }
+      if (r.pending) { send(res, 200, { pending: true, slowDown: !!r.slowDown }); return; }
+      deviceFlows.delete(key);
+      if (r.error) { send(res, 422, { error: `GitHub sign-in failed: ${r.error}` }); return; }
+      // A GitHub App user token comes with a refresh token: stored together, renewed by the broker.
+      const saved = await service.saveCredential(email, slotId, slot.auth === 'github-user' ? githubSecretOf(r, now()) : r.token);
+      if (!saved.ok) { send(res, saved.status || 422, { error: saved.error }); return; }
+      send(res, 200, { state: 'set', suffix: saved.suffix, kind: saved.kind });
+      return;
+    }
+
+    if (kind === 'slots' && req.method === 'PUT' && !test) {
+      let body;
+      try { body = await readJson(req); } catch { send(res, 400, { error: 'body must be JSON' }); return; }
+      const r = await service.saveCredential(email, slotId, body.secret);
+      if (!r.ok) { send(res, r.status || 422, { error: r.error }); return; }
+      send(res, 200, { state: 'set', suffix: r.suffix, kind: r.kind });
+      return;
+    }
+    if (kind === 'slots' && req.method === 'POST' && test) {
+      const r = await service.testCredential(email, slotId);
+      send(res, r.ok ? 200 : (r.status || 422), r.ok ? { ok: true } : { ok: false, error: r.error });
+      return;
+    }
+    if (kind === 'slots' && req.method === 'DELETE' && !test) {
+      service.deleteCredential(email, slotId);
+      send(res, 200, { state: 'missing' });
+      return;
+    }
+    if (kind === 'budget' && req.method === 'PUT' && !test) {
+      let body;
+      try { body = await readJson(req); } catch { send(res, 400, { error: 'body must be JSON' }); return; }
+      const cap = (v, dflt, name) => {
+        if (v === null || v === undefined || v === '') return { v: null };
+        const n = Number(v);
+        if (!Number.isFinite(n) || n < 0) return { err: `${name} must be a number of dollars` };
+        if (dflt != null && n > dflt) return { err: `${name} can't be above the team limit of $${dflt}` };
+        return { v: n };
+      };
+      const d = cap(body.dailyUsd, config.defaultDailyUsd, 'Daily cap');
+      const mo = cap(body.monthlyUsd, config.defaultMonthlyUsd, 'Monthly cap');
+      if (d.err || mo.err) { send(res, 422, { error: d.err || mo.err }); return; }
+      const n = store.setCaps(email, slotId, { dailyUsd: d.v, monthlyUsd: mo.v });
+      if (!n) { send(res, 404, { error: 'save a key first' }); return; }
+      service.limits.invalidate(email, slotId);
+      send(res, 200, { dailyUsd: d.v, monthlyUsd: mo.v });
+      return;
+    }
+    send(res, 405, { error: 'method not allowed' });
+  }
+
+  return (req, res) => {
+    handle(req, res).catch((err) => {
+      log(`key page error: ${err && err.message}`);
+      if (!res.headersSent) send(res, 500, { error: 'internal error' });
+      else res.destroy();
+    });
+  };
+}

package/src/broker/usage.mjs

@@ -0,0 +1,108 @@
+// src/broker/usage.mjs
+// Usage of one proxied request (plans/credential-broker-design.html §6.1). A tap
+// sees the response body as it streams past, WITHOUT buffering it, and pulls the
+// token counts out of Anthropic SSE / JSON and OpenAI final chunks. When the
+// upstream reports its own USD figure (OpenRouter's `usage.cost`) that figure wins;
+// otherwise the usage is priced from the shared list-price table. Pure.
+import { listPriceFor } from '../core/list-prices.mjs';
+
+const MAX_LINE = 1 << 20;   // an SSE line longer than this is skipped, never buffered further
+const MAX_JSON = 4 << 20;   // a non-streamed JSON body larger than this is not parsed for usage
+
+export function emptyUsage() {
+  return { model: null, inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, reportedUsd: null };
+}
+
+function applyAnthropic(u, obj) {
+  if (!obj || typeof obj !== 'object') return;
+  const msg = obj.type === 'message_start' ? obj.message : (obj.type === 'message' ? obj : null);
+  if (msg) {
+    if (msg.model) u.model = msg.model;
+    const us = msg.usage || {};
+    if (Number.isFinite(us.input_tokens)) u.inputTokens = us.input_tokens;
+    if (Number.isFinite(us.output_tokens)) u.outputTokens = us.output_tokens;
+    if (Number.isFinite(us.cache_read_input_tokens)) u.cacheReadTokens = us.cache_read_input_tokens;
+    if (Number.isFinite(us.cache_creation_input_tokens)) u.cacheWriteTokens = us.cache_creation_input_tokens;
+  }
+  if (obj.type === 'message_delta' && obj.usage) {
+    // Cumulative counts: the last delta wins.
+    if (Number.isFinite(obj.usage.output_tokens)) u.outputTokens = obj.usage.output_tokens;
+    if (Number.isFinite(obj.usage.input_tokens)) u.inputTokens = obj.usage.input_tokens;
+    if (Number.isFinite(obj.usage.cache_read_input_tokens)) u.cacheReadTokens = obj.usage.cache_read_input_tokens;
+    if (Number.isFinite(obj.usage.cache_creation_input_tokens)) u.cacheWriteTokens = obj.usage.cache_creation_input_tokens;
+  }
+}
+
+function applyOpenAI(u, obj) {
+  if (!obj || typeof obj !== 'object') return;
+  if (obj.model) u.model = obj.model;
+  const us = obj.usage || (obj.response && obj.response.usage);
+  if (!us || typeof us !== 'object') return;
+  const input = us.prompt_tokens ?? us.input_tokens;
+  const output = us.completion_tokens ?? us.output_tokens;
+  if (Number.isFinite(input)) u.inputTokens = input;
+  if (Number.isFinite(output)) u.outputTokens = output;
+  const cached = us.prompt_tokens_details?.cached_tokens ?? us.input_tokens_details?.cached_tokens;
+  if (Number.isFinite(cached)) u.cacheReadTokens = cached;
+  if (Number.isFinite(us.cost)) u.reportedUsd = us.cost;
+}
+
+/**
+ * A usage tap for one response.
+ * @param {'anthropic'|'openai'} protocol
+ * @param {string|null} contentType  the response's content-type
+ * @returns {{write:(chunk:Buffer|string)=>void, end:()=>ReturnType<typeof emptyUsage>}}
+ */
+export function createUsageTap(protocol, contentType) {
+  const u = emptyUsage();
+  const apply = protocol === 'openai' ? applyOpenAI : applyAnthropic;
+  const sse = /text\/event-stream/i.test(String(contentType || ''));
+  let buf = '';
+  let jsonParts = [];
+  let jsonLen = 0;
+  let skipping = false;
+
+  const onLine = (line) => {
+    if (!line.startsWith('data:')) return;
+    const data = line.slice(5).trim();
+    if (!data || data === '[DONE]') return;
+    try { apply(u, JSON.parse(data)); } catch { /* not JSON: ignore */ }
+  };
+
+  return {
+    write(chunk) {
+      const s = typeof chunk === 'string' ? chunk : chunk.toString('utf8');
+      if (!sse) {
+        if (jsonLen <= MAX_JSON) { jsonParts.push(s); jsonLen += s.length; }
+        return;
+      }
+      buf += s;
+      let i;
+      while ((i = buf.indexOf('\n')) >= 0) {
+        const line = buf.slice(0, i).replace(/\r$/, '');
+        buf = buf.slice(i + 1);
+        if (skipping) { skipping = false; continue; }
+        onLine(line);
+      }
+      if (buf.length > MAX_LINE) { buf = ''; skipping = true; }
+    },
+    end() {
+      if (sse) { if (buf && !skipping) onLine(buf.replace(/\r$/, '')); }
+      else if (jsonLen && jsonLen <= MAX_JSON) {
+        try { apply(u, JSON.parse(jsonParts.join(''))); } catch { /* not JSON */ }
+      }
+      jsonParts = [];
+      return u;
+    },
+  };
+}
+
+/** USD for a usage record: the upstream's own figure, else list price, else 0. */
+export function priceUsage(u, rates = listPriceFor(u.model)) {
+  if (Number.isFinite(u.reportedUsd)) return u.reportedUsd;
+  if (!rates) return 0;
+  return ((u.inputTokens || 0) * (rates.input || 0)
+    + (u.outputTokens || 0) * (rates.output || 0)
+    + (u.cacheReadTokens || 0) * (rates.cacheRead || 0)
+    + (u.cacheWriteTokens || 0) * (rates.cacheWrite || 0)) / 1e6;
+}

package/src/broker/vault.mjs

@@ -0,0 +1,37 @@
+// src/broker/vault.mjs
+// Credentials at rest (plans/credential-broker-design.html §6.5): AES-256-GCM with
+// the operator's vault key, the (person, slot) pair bound in as additional data so a
+// row copied to another person or slot fails to open. Pure apart from the key given.
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from 'node:crypto';
+
+/** Short fingerprint of a vault key: tells the broker a row was sealed with another key. */
+export function keyId(key) {
+  return createHash('sha256').update(key).digest('hex').slice(0, 8);
+}
+
+function aadFor(billTo, slot) {
+  return Buffer.from(`${billTo}\n${slot}`, 'utf8');
+}
+
+/** @returns {{ciphertext: Buffer, iv: Buffer, tag: Buffer, keyId: string}} */
+export function seal(key, plaintext, { billTo, slot }) {
+  const iv = randomBytes(12);
+  const c = createCipheriv('aes-256-gcm', key, iv);
+  c.setAAD(aadFor(billTo, slot));
+  const ciphertext = Buffer.concat([c.update(String(plaintext), 'utf8'), c.final()]);
+  return { ciphertext, iv, tag: c.getAuthTag(), keyId: keyId(key) };
+}
+
+/** The plaintext, or throws (wrong key, tampered row, or row of another person/slot). */
+export function open(key, { ciphertext, iv, tag }, { billTo, slot }) {
+  const d = createDecipheriv('aes-256-gcm', key, Buffer.from(iv));
+  d.setAAD(aadFor(billTo, slot));
+  d.setAuthTag(Buffer.from(tag));
+  return Buffer.concat([d.update(Buffer.from(ciphertext)), d.final()]).toString('utf8');
+}
+
+/** The last 4 characters, shown as ••••xxxx. Never more. */
+export function suffixOf(secret) {
+  const s = String(secret || '');
+  return s.length > 8 ? s.slice(-4) : '';
+}