thinkpool-pair 0.7.160 → 0.7.161

package/account.mjs

@@ -16,6 +16,7 @@ import os from 'node:os'
 import { saveAuth, loadAuth, loadDirs, bindDir, loadServed, rememberServed, loadDefaultDir, saveDefaultDir, claudeRecentProjectDir } from './auth-store.mjs'
 import { isSafeToRestart } from './update-gate.mjs'
 import { makeThrottledTrack } from './presence.mjs'
+import { publicKeyB64, announceProviders, listProviders, addProvider, removeProvider, unseal } from './providers.mjs'
 import { supervisorServes, shouldCooldownOnExit, roomInCooldown } from './serve-consent.mjs'
 import { resolveServeDir } from './serve-dir.mjs'
 import { pairKeyFor, pairTopic, CROSSROOM_BUS } from './cross-terminal.mjs'
@@ -369,7 +370,56 @@ export async function runAccount(SUPABASE_URL, SUPABASE_ANON) {
   // service (always-on, survives reboot) vs a foreground `npx` run that dies with its
   // terminal. THINKPOOL_PAIR_AUTOUPDATE=1 is set ONLY by the install-service plist/unit
   // (service.mjs), so it's the reliable proxy for "running as the managed service".
-  const pushPresence = () => trackPresence({ name: machine, version: VERSION, rooms: [...children.keys()], refused: [...refused].map(([code, reason]) => ({ code, reason })), service: process.env.THINKPOOL_PAIR_AUTOUPDATE === '1', ts: Date.now() })
+  // providerPubKey: the bridge's RSA-OAEP public key (SPKI base64), generated +
+  // persisted 0600 on first read. The dashboard imports it to SEAL a provider's API
+  // key so it reaches the bridge without ever crossing the wire in the clear. Computed
+  // ONCE (the keypair is stable across restarts). `providers` is the name-only registry
+  // (id+name+model, NEVER the key or baseUrl) so the dashboard can list what's available
+  // to spawn against — re-read each announce so an add/remove reflects immediately.
+  // Both are additive; older clients ignore them (feature: multi-provider BYOK, slice 1).
+  const PROVIDER_PUBKEY = publicKeyB64()
+  const pushPresence = () => trackPresence({ name: machine, version: VERSION, rooms: [...children.keys()], refused: [...refused].map(([code, reason]) => ({ code, reason })), service: process.env.THINKPOOL_PAIR_AUTOUPDATE === '1', providerPubKey: PROVIDER_PUBKEY, providers: announceProviders(), ts: Date.now() })
+
+  // ── Provider registry — the multi-BYOK wire contract (slice 1). ─────────────
+  // AUTH: the account channel `tpacct:<uid>` is created WITHOUT config.private:true,
+  // so it is a PUBLIC realtime channel — NOT RLS-gated (the existing shutdown/restart
+  // handlers ride the same public channel; accepted for those, NOT for key management).
+  // Every provider event therefore carries the sender's `jwt` (session access token);
+  // we verify getUser(jwt).id === the owner uid before ANY registry mutation or read.
+  // Only the owner manages their own keys on their own machine — a partner is refused.
+  const OWNER_UID = session.user.id
+  const isOwner = async (jwt) => {
+    if (!jwt || typeof jwt !== 'string') return false
+    try { const { data } = await sb.auth.getUser(jwt); return !!data?.user && data.user.id === OWNER_UID } catch { return false }
+  }
+  const provReply = (event, payload) => { try { acct.send({ type: 'broadcast', event, payload }) } catch { /* channel down */ } }
+  // provider-add {sealed, nonce, jwt} → decrypt, validate, append, re-announce.
+  acct.on('broadcast', { event: 'provider-add' }, async ({ payload }) => {
+    const nonce = payload?.nonce
+    if (!(await isOwner(payload?.jwt))) return provReply('provider-add-res', { nonce, ok: false, error: 'unauthorized' })
+    let fields
+    // Decrypt failures answer ok:false WITHOUT logging the ciphertext or plaintext
+    // (security invariant d) — a bare boolean, never the sealed blob or the key.
+    try { fields = unseal(payload?.sealed) } catch { return provReply('provider-add-res', { nonce, ok: false, error: 'could not decrypt the sealed payload' }) }
+    const r = addProvider(fields)
+    if (r.ok) { pushPresence(); process.stderr.write(`\n  ◆ provider added (${String(fields?.name || '').slice(0, 40)}) — re-announced.\n`) }
+    provReply('provider-add-res', { nonce, ok: r.ok, error: r.ok ? undefined : r.error, id: r.ok ? r.id : undefined })
+  })
+  // provider-remove {id, nonce, jwt} → remove (built-in refuses), re-announce.
+  acct.on('broadcast', { event: 'provider-remove' }, async ({ payload }) => {
+    const nonce = payload?.nonce
+    if (!(await isOwner(payload?.jwt))) return provReply('provider-remove-res', { nonce, ok: false, error: 'unauthorized' })
+    const r = removeProvider(payload?.id)
+    if (r.ok) { pushPresence(); process.stderr.write('\n  ◆ provider removed — re-announced.\n') }
+    provReply('provider-remove-res', { nonce, ok: r.ok, error: r.ok ? undefined : r.error })
+  })
+  // providers-list-req {nonce, jwt} → the masked list (keyHint = last 4 chars only).
+  acct.on('broadcast', { event: 'providers-list-req' }, async ({ payload }) => {
+    const nonce = payload?.nonce
+    if (!(await isOwner(payload?.jwt))) return provReply('providers-list-res', { nonce, ok: false, error: 'unauthorized', providers: [] })
+    provReply('providers-list-res', { nonce, ok: true, providers: listProviders() })
+  })
+
   // Re-track on EVERY (re)subscribe, not just the first: a realtime reconnect
   // (network blip, or a token swap mid-flight) rejoins the channel and must
   // re-announce, or the dashboard would read "no bridge" until the next restart.

package/bridge.mjs

@@ -38,6 +38,10 @@ import { createRequire } from 'node:module'
 import { randomUUID } from 'node:crypto'
 import { createClient } from '@supabase/supabase-js'
 import { serveDecision, amGrantee, standDownOnPeerAnnounce, standDownOnGrantChange, fetchServeRow, refusalMessage, gateFailAction, GRANT_RECLAIM_EXIT } from './serve-consent.mjs'
+// resolveProviderEnv(id) → {ANTHROPIC_BASE_URL,ANTHROPIC_AUTH_TOKEN,ANTHROPIC_MODEL} for a
+// registered custom provider, or null for the built-in/unknown (leave the default env intact).
+// Multi-provider BYOK slice 1: a lane spawned with a `provider` id runs on that endpoint.
+import { resolveProviderEnv } from './providers.mjs'
 import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk'
 import { z } from 'zod'
 import { startClaudeSession } from './claude-session.mjs'
@@ -1412,12 +1416,12 @@ function worktreeSnapshot(cwd) {
 // relay STRUCTURED events. onEvent → broadcast `code-event` + print locally +
 // persist to the host file; tool calls round-trip through the perm card; the
 // rolling log replays to joiners and survives bridge restarts (session-store).
-function openStructured({ id, model, resume, log, commands, mode, spawnedBy, rolePrompt, flowSessionId, flowTaskKey, cwd, reviewSliceRoots, openedAt, defer }) {
+function openStructured({ id, model, resume, log, commands, mode, spawnedBy, rolePrompt, flowSessionId, flowTaskKey, cwd, reviewSliceRoots, openedAt, defer, provider }) {
   if (sessions.has(id)) return
   // spawnedBy: set when this lane was Dispatched (spawn_terminal). Restored from the
   // session store so the Ensemble flag survives a bridge restart (else a respin
   // stripped it and the lane reverted to a plain tab — the t6 "no chip" bug).
-  const entry = { cmd: 'claude', kind: 'structured', log: Array.isArray(log) ? log.slice(-STRUCTURED_LOG_MAX) : [], pending: new Map(), session: null, recovered: false, commands: Array.isArray(commands) ? commands : undefined, mode, model: model || null, spawnedBy: spawnedBy || undefined, flowSessionId: flowSessionId || null, flowTaskKey: flowTaskKey || null, cwd: cwd || null,
+  const entry = { cmd: 'claude', kind: 'structured', log: Array.isArray(log) ? log.slice(-STRUCTURED_LOG_MAX) : [], pending: new Map(), session: null, recovered: false, commands: Array.isArray(commands) ? commands : undefined, mode, model: model || null, provider: provider || null, spawnedBy: spawnedBy || undefined, flowSessionId: flowSessionId || null, flowTaskKey: flowTaskKey || null, cwd: cwd || null,
     // Stable creation order — persisted so a bridge restart restores tabs in the SAME
     // order (not readdir/filesystem order). Legacy recs (no openedAt) derive it from the
     // first transcript event ts, so even the first post-fix restart is ordered right.
@@ -1595,7 +1599,7 @@ function openStructured({ id, model, resume, log, commands, mode, spawnedBy, rol
   // restart. Without this, sessionData omitted it → on restart the resumed session
   // re-launched on the host default (Opus) regardless of the last switch, and the
   // switch looked like it "never changed the model" (Max 2026-07-02). Restored below.
-  const sessionData = () => ({ sessionId: entry.session?.sessionId || resume || null, log: entry.log, commands: entry.commands, mode: entry.mode, model: entry.model || null, spawnedBy: entry.spawnedBy, flowSessionId: entry.flowSessionId, flowTaskKey: entry.flowTaskKey, cwd: entry.cwd, rolePrompt: entry.rolePrompt, flowReviewTarget: entry.flowReviewTarget || null, revertTarget: entry.revertTarget || null, reviewSliceRoots: entry.reviewSliceRoots || [], openedAt: entry.openedAt || null })
+  const sessionData = () => ({ sessionId: entry.session?.sessionId || resume || null, log: entry.log, commands: entry.commands, mode: entry.mode, model: entry.model || null, provider: entry.provider || null, spawnedBy: entry.spawnedBy, flowSessionId: entry.flowSessionId, flowTaskKey: entry.flowTaskKey, cwd: entry.cwd, rolePrompt: entry.rolePrompt, flowReviewTarget: entry.flowReviewTarget || null, revertTarget: entry.revertTarget || null, reviewSliceRoots: entry.reviewSliceRoots || [], openedAt: entry.openedAt || null })
   const persist = () => saveSession(room, id, sessionData())
   // Synchronous flush of this session's record. Used on open (so a brand-new session
   // has a file under its id BEFORE its first event — surviving a restart inside the
@@ -1761,6 +1765,7 @@ function openStructured({ id, model, resume, log, commands, mode, spawnedBy, rol
           name: z.string().max(80).optional().describe('a short label for the new lane so the room (and you) can find it, e.g. "Research: topologies"'),
           task: z.string().optional().describe('an initial task to hand the new lane immediately; omit to open it idle'),
           model: z.string().optional().describe('optional model for the lane, e.g. opus / sonnet / haiku'),
+          provider: z.string().optional().describe('optional registered LLM provider id to run this lane on (from the account\'s provider registry); omit for the default Claude/Anthropic path'),
           mode: z.enum(['default', 'acceptEdits', 'bypassPermissions', 'plan']).optional().describe('permission mode for the new lane; defaults to inheriting YOUR current mode. Raising a lane to bypassPermissions from a non-bypass lane asks the room to confirm once.'),
         },
         async (args) => {
@@ -1791,7 +1796,7 @@ function openStructured({ id, model, resume, log, commands, mode, spawnedBy, rol
           // plan-mode lane would stall on ExitPlanMode cards. An explicit args.mode still wins;
           // otherwise inherit, but fall plan → default (an autonomous worker doesn't plan-gate).
           const childMode = args?.mode || (entry.mode === 'plan' ? 'default' : entry.mode)
-          openStructured({ id: newId, model: args?.model, mode: childMode })
+          openStructured({ id: newId, model: args?.model, provider: args?.provider, mode: childMode })
           const ne = sessions.get(newId)
           if (!ne) { if (args?.name) { delete termNames[newId]; saveNames(room, termNames) } return okText('Could not open a new lane — the terminal cap may have just been reached. Close one and retry.') }
           ne.spawnedBy = id   // ownership: only the spawner may close_terminal it
@@ -1975,7 +1980,12 @@ function openStructured({ id, model, resume, log, commands, mode, spawnedBy, rol
     // Tier 3 — the SENDER-side gate for post_to_session (the receipt card lives in
     // the target room). roomHop/crossRoomPostCount reset on a real human turn (code-turn).
     crossRoomPostGate: () => crossRoomPostDecision({ roomHop: entry.roomHop || 0, postCount: entry.crossRoomPostCount || 0, disabled: process.env.TP_PAIRBUS_OFF === '1' }),
-    env: { ...process.env, ...buildConductorEnv({ flowSessionId, mode }), TP_MOCKUP_OUTBOX: mockupOutbox },
+    // Per-lane provider (multi-BYOK slice 1): a lane opened with a registered `provider`
+    // id runs on THAT Anthropic-compatible endpoint. resolveProviderEnv → {ANTHROPIC_BASE_URL,
+    // ANTHROPIC_AUTH_TOKEN, ANTHROPIC_MODEL}, spread AFTER process.env so it overrides the
+    // per-machine default (provider.mjs/applyProviderEnv). null for built-in/unknown → the
+    // default Claude env is left exactly as-is (unchanged path).
+    env: { ...process.env, ...buildConductorEnv({ flowSessionId, mode }), ...(resolveProviderEnv(provider) || {}), TP_MOCKUP_OUTBOX: mockupOutbox },
     onEvent: (evt) => {
       // Self-heal a stale resume — the saved SDK session expired. Reopen fresh,
       // keeping the transcript (scrollback survives; live context is gone).
@@ -2320,7 +2330,7 @@ channel
       // previous terminal's model (and the first uses the provider default). Falls
       // through to the SDK default when absent. Stamped on the entry so the announce
       // carries it at open (chip shows the model immediately, not the branch).
-      openStructured({ id: payload.id, mode: payload.mode, model: payload.model || undefined })
+      openStructured({ id: payload.id, mode: payload.mode, model: payload.model || undefined, provider: payload.provider || undefined })
       process.stderr.write(`\n  ◆ web opened a structured "${payload.cmd}" session (${payload.mode || 'default'}${payload.model ? `, model ${payload.model}` : ''}).\n`)
       return
     }
@@ -2428,7 +2438,7 @@ channel
   // ── structured-session control (Phase 2) ──
   .on('broadcast', { event: 'code-open' }, ({ payload }) => {
     if (payload?.host && payload.host !== name) return
-    openStructured({ id: payload?.id || randomUUID(), model: payload?.model, resume: payload?.resume, mode: payload?.mode })
+    openStructured({ id: payload?.id || randomUUID(), model: payload?.model, provider: payload?.provider, resume: payload?.resume, mode: payload?.mode })
   })
   .on('broadcast', { event: 'code-turn' }, async ({ payload }) => {
     const s = payload?.term && sessions.get(payload.term)
@@ -2611,7 +2621,7 @@ channel
             // FL-M6 — restore the flow context (id/role/cwd) so an in-flight flow survives a
             // bridge restart: the conductor keeps its subagent-block + plan interception, and
             // lanes keep their worktree cwd + the ability to mark done.
-            openStructured({ id: rec.id, model: rec.model || undefined, resume: canResume(rec) ? rec.sessionId : undefined, log: rec.log, commands: rec.commands, mode: rec.mode, spawnedBy: rec.spawnedBy, flowSessionId: rec.flowSessionId, flowTaskKey: rec.flowTaskKey, cwd: rec.cwd, rolePrompt: rec.rolePrompt, reviewSliceRoots: rec.reviewSliceRoots, openedAt: rec.openedAt,
+            openStructured({ id: rec.id, model: rec.model || undefined, provider: rec.provider || undefined, resume: canResume(rec) ? rec.sessionId : undefined, log: rec.log, commands: rec.commands, mode: rec.mode, spawnedBy: rec.spawnedBy, flowSessionId: rec.flowSessionId, flowTaskKey: rec.flowTaskKey, cwd: rec.cwd, rolePrompt: rec.rolePrompt, reviewSliceRoots: rec.reviewSliceRoots, openedAt: rec.openedAt,
               // Lazy-boot restored terminals that were IDLE + not part of a flow: their transcript
               // shows immediately; the query boots on first turn. Mid-turn + flow terminals boot now
               // (mid-turn needs auto-resume; flow needs its lane live).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thinkpool-pair",
-  "version": "0.7.160",
+  "version": "0.7.161",
   "description": "Share a local coding-agent CLI (Claude Code, Codex, Gemini, Aider, …) into a ThinkPool Code room, live.",
   "type": "module",
   "bin": {
@@ -37,6 +37,7 @@
     "account.mjs",
     "auth-store.mjs",
     "provider.mjs",
+    "providers.mjs",
     "README.md"
   ],
   "scripts": {

package/providers.mjs

@@ -0,0 +1,232 @@
+/* ─────────────────────────────────────────────────────────────
+   providers.mjs — the bridge's LLM-provider REGISTRY (multi-BYOK).
+
+   Slice 1 of the multi-provider BYOK feature (spec:
+   docs/specs/2026-07-05-llm-provider-registry.md). Lets a user register
+   extra Anthropic-compatible providers (name + base url + model + API
+   key) on their OWN bridge; a Code lane can then spawn against any
+   registered provider by id. Keys live ONLY on the bridge host — they are
+   never broadcast, never written to the DB, never in an announce.
+
+   This module owns:
+     • providers.json   — the registry ({id,name,baseUrl,model,key,addedAt}[]), 0600
+     • bridge-key.json  — the bridge's RSA keypair, 0600 (host-only)
+     • seal/unseal      — the hybrid envelope the dashboard uses to hand the
+                          bridge a key WITHOUT it ever crossing the wire in the
+                          clear (RSA-OAEP wraps an AES-256-GCM session key).
+     • env resolution   — {ANTHROPIC_BASE_URL,ANTHROPIC_AUTH_TOKEN,ANTHROPIC_MODEL}
+                          for a chosen provider id, matching provider.mjs conventions.
+
+   The built-in `anthropic` provider (the host's regular Claude login) is
+   IMPLICIT: never stored, never removable, always present. A lane with no
+   provider id runs the default Claude path unchanged.
+
+   ── Why HYBRID sealing, not raw RSA ──────────────────────────────────
+   RSA-OAEP-2048/SHA-256 caps plaintext at 190 bytes. A real payload —
+   {name,baseUrl,model,key} with e.g. an OpenAI `sk-proj-…` key (~164 chars)
+   plus JSON overhead — blows past that and RSA encrypt throws. So `sealed`
+   is a hybrid envelope: RSA-OAEP wraps a fresh 32-byte AES key, AES-256-GCM
+   encrypts the payload. Both ends are WebCrypto-native (browser dashboard
+   seals, Node bridge unseals). Envelope shape (base64 of UTF8 JSON):
+     { v:1, ek:base64(RSA-OAEP(aesKeyRaw)), iv:base64(12B), ct:base64(gcmCiphertext||16B-tag) }
+   WebCrypto's subtle.encrypt returns ciphertext||tag concatenated; Node's
+   createDecipheriv wants the tag separately, so unseal splits the last 16.
+
+   ── Auth (see account.mjs handlers) ─────────────────────────────────
+   The account channel `tpacct:<uid>` is a PUBLIC realtime channel (no
+   config.private:true), so it is NOT RLS-gated — the sender is verified at
+   the application layer (getUser(jwt).id === owner uid) before any registry
+   mutation. This module stays transport-agnostic; the caller does auth.
+   ───────────────────────────────────────────────────────────── */
+import os from 'node:os'
+import fs from 'node:fs'
+import path from 'node:path'
+import crypto from 'node:crypto'
+
+const DIR       = path.join(os.homedir(), '.thinkpool-pair')
+const REG_FILE  = path.join(DIR, 'providers.json')
+const KEY_FILE  = path.join(DIR, 'bridge-key.json')
+
+// The built-in provider id — always present, never stored, never removable.
+export const BUILTIN_ID = 'anthropic'
+
+function ensureDir() { try { fs.mkdirSync(DIR, { recursive: true, mode: 0o700 }) } catch { /* noop */ } }
+
+// ── registry load / save ───────────────────────────────────────────────
+/** @returns {Array<{id:string,name:string,baseUrl:string,model?:string,key:string,addedAt:number}>} */
+export function loadProviders() {
+  try {
+    const arr = JSON.parse(fs.readFileSync(REG_FILE, 'utf8'))
+    return Array.isArray(arr) ? arr.filter((p) => p && p.id && p.id !== BUILTIN_ID) : []
+  } catch { return [] }
+}
+
+function saveProviders(arr) {
+  ensureDir()
+  fs.writeFileSync(REG_FILE, JSON.stringify(arr, null, 2), { mode: 0o600 })
+  // Writing with { mode } only applies on CREATE; harden an existing file too.
+  try { fs.chmodSync(REG_FILE, 0o600) } catch { /* noop */ }
+}
+
+// ── keypair ─────────────────────────────────────────────────────────────
+// Generate an RSA-OAEP-2048 keypair on first run, persist 0600, return the
+// public key as SPKI base64 (what the dashboard imports) + the private key
+// object (for unseal). Idempotent: a persisted key is reused.
+let _keyCache = null
+export function ensureKeypair() {
+  if (_keyCache) return _keyCache
+  ensureDir()
+  try {
+    const saved = JSON.parse(fs.readFileSync(KEY_FILE, 'utf8'))
+    if (saved?.publicKeyB64 && saved?.privateKeyPem) {
+      _keyCache = {
+        publicKeyB64: saved.publicKeyB64,
+        privateKey: crypto.createPrivateKey({ key: saved.privateKeyPem, format: 'pem' }),
+      }
+      return _keyCache
+    }
+  } catch { /* generate below */ }
+
+  const { publicKey, privateKey } = crypto.generateKeyPairSync('rsa', { modulusLength: 2048 })
+  const publicKeyB64 = publicKey.export({ type: 'spki', format: 'der' }).toString('base64')
+  const privateKeyPem = privateKey.export({ type: 'pkcs8', format: 'pem' })
+  fs.writeFileSync(KEY_FILE, JSON.stringify({ publicKeyB64, privateKeyPem, createdAt: Date.now() }, null, 2), { mode: 0o600 })
+  try { fs.chmodSync(KEY_FILE, 0o600) } catch { /* noop */ }
+  _keyCache = { publicKeyB64, privateKey }
+  return _keyCache
+}
+
+/** SPKI base64 public key for the announce (`providerPubKey`). */
+export function publicKeyB64() { return ensureKeypair().publicKeyB64 }
+
+// ── seal / unseal (hybrid RSA-OAEP + AES-256-GCM) ───────────────────────
+// seal() is here so the UNIT can drive both ends node-side; the real seal
+// happens in the browser dashboard via WebCrypto against the same envelope.
+/** @param {object} payload  @param {string=} pubKeyB64  → base64(envelope JSON) */
+export function seal(payload, pubKeyB64) {
+  const spkiB64 = pubKeyB64 || publicKeyB64()
+  const publicKey = crypto.createPublicKey({ key: Buffer.from(spkiB64, 'base64'), format: 'der', type: 'spki' })
+  const aesKey = crypto.randomBytes(32)
+  const iv = crypto.randomBytes(12)
+  const cipher = crypto.createCipheriv('aes-256-gcm', aesKey, iv)
+  const enc = Buffer.concat([cipher.update(JSON.stringify(payload), 'utf8'), cipher.final()])
+  const tag = cipher.getAuthTag()
+  const ek = crypto.publicEncrypt(
+    { key: publicKey, padding: crypto.constants.RSA_PKCS1_OAEP_PADDING, oaepHash: 'sha256' },
+    aesKey,
+  )
+  const envelope = {
+    v: 1,
+    ek: ek.toString('base64'),
+    iv: iv.toString('base64'),
+    ct: Buffer.concat([enc, tag]).toString('base64'),   // ct||tag, matches WebCrypto
+  }
+  return Buffer.from(JSON.stringify(envelope), 'utf8').toString('base64')
+}
+
+/**
+ * Decrypt a sealed envelope with the bridge private key. Returns the parsed
+ * payload object, or throws. Callers MUST catch and answer ok:false WITHOUT
+ * logging the ciphertext or plaintext (security invariant d).
+ * @param {string} sealedB64  base64(envelope JSON)
+ */
+export function unseal(sealedB64) {
+  const { privateKey } = ensureKeypair()
+  const env = JSON.parse(Buffer.from(String(sealedB64 || ''), 'base64').toString('utf8'))
+  if (!env || env.v !== 1 || !env.ek || !env.iv || !env.ct) throw new Error('bad envelope')
+  const aesKey = crypto.privateDecrypt(
+    { key: privateKey, padding: crypto.constants.RSA_PKCS1_OAEP_PADDING, oaepHash: 'sha256' },
+    Buffer.from(env.ek, 'base64'),
+  )
+  const iv = Buffer.from(env.iv, 'base64')
+  const ctTag = Buffer.from(env.ct, 'base64')
+  if (ctTag.length < 16) throw new Error('bad ciphertext')
+  const tag = ctTag.subarray(ctTag.length - 16)
+  const ct = ctTag.subarray(0, ctTag.length - 16)
+  const decipher = crypto.createDecipheriv('aes-256-gcm', aesKey, iv)
+  decipher.setAuthTag(tag)
+  const dec = Buffer.concat([decipher.update(ct), decipher.final()])
+  return JSON.parse(dec.toString('utf8'))
+}
+
+// ── CRUD ────────────────────────────────────────────────────────────────
+function validate({ name, baseUrl, key }) {
+  if (!name || typeof name !== 'string' || !name.trim()) return 'name is required'
+  if (!key || typeof key !== 'string' || !key.trim()) return 'key is required'
+  let u
+  try { u = new URL(String(baseUrl)) } catch { return 'baseUrl must be a valid https url' }
+  if (u.protocol !== 'https:') return 'baseUrl must be https'
+  return null
+}
+
+/**
+ * Append a provider. `fields` = {name, baseUrl, model?, key} (already unsealed).
+ * @returns {{ok:true,id:string} | {ok:false,error:string}}
+ */
+export function addProvider(fields) {
+  const err = validate(fields || {})
+  if (err) return { ok: false, error: err }
+  const arr = loadProviders()
+  const id = crypto.randomUUID()
+  arr.push({
+    id,
+    name: String(fields.name).trim(),
+    baseUrl: String(fields.baseUrl).trim(),
+    model: fields.model ? String(fields.model).trim() : undefined,
+    key: String(fields.key).trim(),
+    addedAt: Date.now(),
+  })
+  saveProviders(arr)
+  return { ok: true, id }
+}
+
+/**
+ * Remove a provider by id. The built-in `anthropic` refuses.
+ * @returns {{ok:true} | {ok:false,error:string}}
+ */
+export function removeProvider(id) {
+  if (!id || id === BUILTIN_ID) return { ok: false, error: 'the built-in Anthropic provider cannot be removed' }
+  const arr = loadProviders()
+  const next = arr.filter((p) => p.id !== id)
+  if (next.length === arr.length) return { ok: false, error: 'no such provider' }
+  saveProviders(next)
+  return { ok: true }
+}
+
+// ── read-only projections (never expose the raw key) ────────────────────
+/** Masked list for the dashboard: keyHint = last 4 chars only. Built-in first. */
+export function listProviders() {
+  const custom = loadProviders().map((p) => ({
+    id: p.id,
+    name: p.name,
+    model: p.model || null,
+    keyHint: keyHint(p.key),
+  }))
+  return [{ id: BUILTIN_ID, name: 'Anthropic (Claude)', model: null, keyHint: null }, ...custom]
+}
+
+/** Name-only projection for the announce/presence payload — NO key, NO baseUrl. */
+export function announceProviders() {
+  const custom = loadProviders().map((p) => ({ id: p.id, name: p.name, model: p.model || null }))
+  return [{ id: BUILTIN_ID, name: 'Anthropic (Claude)', model: null }, ...custom]
+}
+
+function keyHint(key) {
+  const k = String(key || '')
+  return k.length <= 4 ? k : k.slice(-4)
+}
+
+/**
+ * Resolve the spawn env for a provider id, matching provider.mjs conventions
+ * exactly (ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN / ANTHROPIC_MODEL).
+ * Built-in / unknown id → null (the caller leaves the default Claude env intact).
+ * @returns {{ANTHROPIC_BASE_URL:string,ANTHROPIC_AUTH_TOKEN:string,ANTHROPIC_MODEL?:string} | null}
+ */
+export function resolveProviderEnv(id) {
+  if (!id || id === BUILTIN_ID) return null
+  const p = loadProviders().find((x) => x.id === id)
+  if (!p) return null
+  const env = { ANTHROPIC_BASE_URL: p.baseUrl, ANTHROPIC_AUTH_TOKEN: p.key }
+  if (p.model) env.ANTHROPIC_MODEL = p.model
+  return env
+}