@cohortapp/agent-sdk 2.3.0

package/lib/org/ui-parity.test.mjs

@@ -0,0 +1,348 @@
+/**
+ * ui-parity.test.mjs — Agent UI-parity helpers (full human-action mirror).
+ *
+ * The 328 wrappers in ui-parity.mjs are each a one-liner over call() from
+ * client.mjs, so client.test.mjs already proves the transport contract (headers,
+ * idempotency, fail-open, frame normalisation). Here we just prove a representative
+ * slice across families ROUTES to the correct method name, POSTs the params body,
+ * and returns the res frame — using the same injected fetchImpl (no network).
+ *
+ * Run: node --test lib/org/ui-parity.test.mjs
+ */
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  charterUpdateClauses,
+  charterGet,
+  memberCreate,
+  channelCreate,
+  sopCreate,
+  decisionSign,
+  taskUpdate,
+  settingsMintApiKey,
+  filePin,
+  emailSend,
+  emailMarkRead,
+  emailInbox,
+  emailMessage,
+  emailThread,
+  artifactCreate,
+  artifactAct,
+  artifactPatch,
+  artifactGet,
+  artifactList,
+  artifactCatalog,
+} from "./ui-parity.mjs";
+import { PROTOCOL_VERSION } from "./protocol.mjs";
+
+const BASE = "https://org.cohortapp.com";
+const TOKEN = "tok-abc";
+
+// Ambient COHORT_* tokens would leak into header assertions; clear them.
+delete process.env.COHORT_API_TOKEN;
+delete process.env.COHORT_TOKEN;
+
+/** A fake fetch that records calls and returns a canned res frame. */
+function fakeFetch(responder) {
+  const calls = [];
+  const impl = async (url, init) => {
+    calls.push({ url, init, headers: (init && init.headers) || {} });
+    const r = responder ? responder(url, init, calls.length - 1) : null;
+    const status = r && typeof r.status === "number" ? r.status : 200;
+    const ok = r && typeof r.ok === "boolean" ? r.ok : status >= 200 && status < 300;
+    const body = r ? r.body : { ok: true, result: null };
+    return {
+      ok,
+      status,
+      headers: { get: (k) => (r && r.respHeaders ? r.respHeaders[k.toLowerCase()] : undefined) },
+      json: async () => body,
+    };
+  };
+  impl.calls = calls;
+  return impl;
+}
+
+// --- representative wrappers route to the right /v1 method -------------------
+
+test("ui-parity helpers route to their /v1 methods (one per family)", async () => {
+  const seen = [];
+  const f = fakeFetch((url) => { seen.push(url); return { body: { ok: true, result: null } }; });
+  const o = { base: BASE, token: TOKEN, idempotencyKey: "k", fetchImpl: f };
+  await charterUpdateClauses({ channelId: "c", clauses: [] }, o);
+  await charterGet({ memberId: "m" }, o);
+  await memberCreate({ kind: "AI", displayName: "Robin", roleTitle: "Eng", roleLevel: 4, teamId: "t" }, o);
+  await channelCreate({ slug: "ops", name: "Ops", kind: "TEAM" }, o);
+  await sopCreate({ channelId: "c", title: "Runbook" }, o);
+  await decisionSign({ decisionId: "d", memberSlug: "robin" }, o);
+  await taskUpdate({ taskId: "tk", priority: "P1" }, o);
+  await settingsMintApiKey({ name: "ci" }, o);
+  await filePin({ channelId: "c", name: "f.pdf", dataUrl: "data:," }, o);
+  assert.deepEqual(seen, [
+    `${BASE}/api/v1/charter.updateClauses`,
+    `${BASE}/api/v1/charter.get`,
+    `${BASE}/api/v1/member.create`,
+    `${BASE}/api/v1/channel.create`,
+    `${BASE}/api/v1/sop.create`,
+    `${BASE}/api/v1/decision.sign`,
+    `${BASE}/api/v1/board.updateTask`,
+    `${BASE}/api/v1/settings.mintApiKey`,
+    `${BASE}/api/v1/file.pin`,
+  ]);
+});
+
+test("ui-parity wrapper POSTs params + Bearer + x-org-protocol, returns the frame", async () => {
+  const f = fakeFetch(() => ({ body: { ok: true, result: { id: "ch-1" } } }));
+  const frame = await channelCreate(
+    { slug: "ops", name: "Ops", kind: "TEAM" },
+    { base: BASE, token: TOKEN, idempotencyKey: "chan-ops", fetchImpl: f },
+  );
+  assert.deepEqual(frame, { ok: true, result: { id: "ch-1" } });
+  assert.equal(f.calls[0].init.method, "POST");
+  assert.equal(f.calls[0].url, `${BASE}/api/v1/channel.create`);
+  assert.equal(f.calls[0].headers.authorization, `Bearer ${TOKEN}`);
+  assert.equal(f.calls[0].headers["x-org-protocol"], String(PROTOCOL_VERSION));
+  assert.deepEqual(JSON.parse(f.calls[0].init.body), { slug: "ops", name: "Ops", kind: "TEAM" });
+});
+
+test("idempotent wrapper forwards a caller-supplied x-idempotency-key", async () => {
+  // member.create is idempotent but carries no natural id at creation time, so the
+  // caller SHOULD supply a stable key — verify it reaches the wire.
+  const f = fakeFetch(() => ({ body: { ok: true, result: null } }));
+  await memberCreate(
+    { kind: "AI", displayName: "Robin", roleTitle: "Eng", roleLevel: 4, teamId: "t" },
+    { base: BASE, token: TOKEN, idempotencyKey: "seed-robin", fetchImpl: f },
+  );
+  assert.equal(f.calls[0].headers["x-idempotency-key"], "seed-robin");
+});
+
+test("read-style method (charter.get) is a POST RPC, sends NO idempotency key", async () => {
+  const f = fakeFetch(() => ({ body: { ok: true, result: { memberId: "m" } } }));
+  const frame = await charterGet({ memberId: "m" }, { base: BASE, token: TOKEN, fetchImpl: f });
+  assert.equal(f.calls[0].init.method, "POST");
+  assert.equal(f.calls[0].headers["x-idempotency-key"], undefined);
+  assert.equal(frame.result.memberId, "m");
+});
+
+test("ui-parity wrappers fail open on transport throw (no throw, INTERNAL frame)", async () => {
+  const thrower = fakeFetch(() => { throw new Error("network"); });
+  const o = { base: BASE, token: TOKEN, fetchImpl: thrower };
+  for (const frame of [
+    await taskUpdate({ taskId: "tk" }, o),
+    await decisionSign({ decisionId: "d", memberSlug: "x" }, o),
+    await filePin({ channelId: "c", name: "f", dataUrl: "data:," }, o),
+  ]) {
+    assert.equal(frame.ok, false);
+    assert.equal(frame.error.code, "INTERNAL");
+  }
+});
+
+test("ui-parity wrapper surfaces a server error frame verbatim (FORBIDDEN_SCOPE 403)", async () => {
+  const f = fakeFetch(() => ({ ok: false, status: 403, body: { ok: false, error: { code: "FORBIDDEN_SCOPE", message: "admin only" } } }));
+  const frame = await settingsMintApiKey({ name: "ci" }, { base: BASE, token: TOKEN, idempotencyKey: "k", fetchImpl: f });
+  assert.equal(frame.ok, false);
+  assert.equal(frame.error.code, "FORBIDDEN_SCOPE");
+});
+
+// --- email family (companion spec §8 / §9.1) --------------------------------
+
+test("email wrappers route to their /v1 email.* methods and POST the params", async () => {
+  const seen = [];
+  const f = fakeFetch((url) => { seen.push(url); return { body: { ok: true, result: null } }; });
+  const o = { base: BASE, token: TOKEN, idempotencyKey: "k", fetchImpl: f };
+  await emailSend({ threadId: "t1", text: "re: hi", idempotencyId: "biz-1" }, o);
+  await emailMarkRead({ messageId: "m1" }, o);
+  await emailInbox({ unreadOnly: true, limit: 50 }, o);
+  await emailMessage({ id: "m1" }, o);
+  await emailThread({ threadId: "t1" }, o);
+  assert.deepEqual(seen, [
+    `${BASE}/api/v1/email.send`,
+    `${BASE}/api/v1/email.markRead`,
+    `${BASE}/api/v1/email.inbox`,
+    `${BASE}/api/v1/email.message`,
+    `${BASE}/api/v1/email.thread`,
+  ]);
+});
+
+test("email mutating wrappers carry x-idempotency-key; reads do not", async () => {
+  const f = fakeFetch(() => ({ body: { ok: true, result: null } }));
+  await emailSend({ threadId: "t1", text: "x", idempotencyId: "biz-1" }, { base: BASE, token: TOKEN, idempotencyKey: "send-1", fetchImpl: f });
+  assert.equal(f.calls[0].headers["x-idempotency-key"], "send-1");
+  await emailInbox({ limit: 1 }, { base: BASE, token: TOKEN, fetchImpl: f });
+  assert.equal(f.calls[1].headers["x-idempotency-key"], undefined, "sideEffecting:false reads send no key");
+  assert.equal(f.calls[1].init.method, "POST", "email reads are POST METHODS, not GET reads");
+});
+
+test("emailSend surfaces the approval_required result as a NORMAL frame", async () => {
+  const approval = { actionClass: "external_comms", payloadHash: "abc", intent: { to: ["x@y.z"] } };
+  const f = fakeFetch(() => ({ body: { ok: true, result: { status: "approval_required", approval, firstContactRecipients: ["x@y.z"] } } }));
+  const frame = await emailSend({ to: ["x@y.z"], subject: "s", text: "b", idempotencyId: "biz-2" }, { base: BASE, token: TOKEN, idempotencyKey: "k2", fetchImpl: f });
+  assert.equal(frame.ok, true, "approval_required is a result, not an error");
+  assert.equal(frame.result.status, "approval_required");
+  assert.deepEqual(frame.result.approval, approval);
+});
+
+// --- artifact family (GU program 2026-07) -----------------------------------
+
+test("artifact wrappers route to their /v1 artifact.* methods and POST the params", async () => {
+  const seen = [];
+  const f = fakeFetch((url) => { seen.push(url); return { body: { ok: true, result: null } }; });
+  const o = { base: BASE, token: TOKEN, fetchImpl: f };
+  const envelope = { genui: "v2", artifact: { class: "ops.status", version: 1, state: "complete", source: { kind: "native" } }, actions: [], root: { type: "card", tone: "neutral", blocks: [] } };
+  await artifactCreate({ channelId: "c1", envelope, clientMsgId: "cm-1" }, o);
+  await artifactAct({ artifactId: "a1", action: "approve", idempotencyKey: "k-1" }, o);
+  await artifactPatch({ artifactId: "a1", toState: "complete", envelope }, o);
+  await artifactGet({ artifactId: "a1" }, o);
+  await artifactList({ channelId: "c1", state: "complete" }, o);
+  await artifactCatalog({}, o);
+  assert.deepEqual(seen, [
+    `${BASE}/api/v1/artifact.create`,
+    `${BASE}/api/v1/artifact.act`,
+    `${BASE}/api/v1/artifact.patch`,
+    `${BASE}/api/v1/artifact.get`,
+    `${BASE}/api/v1/artifact.list`,
+    `${BASE}/api/v1/artifact.catalog`,
+  ]);
+  assert.deepEqual(JSON.parse(f.calls[0].init.body).envelope, envelope, "envelope POSTed verbatim");
+});
+
+test("artifact writes are dispatcher-neutral: business ids in the BODY, no x-idempotency-key header", async () => {
+  // sideEffecting:false at the dispatcher (the hq artifact service self-appends
+  // its ledger) → call() attaches no header even when o.idempotencyKey is set;
+  // dedup rides params.clientMsgId / params.idempotencyKey instead.
+  const f = fakeFetch(() => ({ body: { ok: true, result: { artifactId: "a1", messageId: "m1" } } }));
+  await artifactCreate({ channelId: "c1", envelope: { genui: "v1", root: {} }, clientMsgId: "cm-9" }, { base: BASE, token: TOKEN, idempotencyKey: "ignored", fetchImpl: f });
+  assert.equal(f.calls[0].headers["x-idempotency-key"], undefined);
+  assert.equal(JSON.parse(f.calls[0].init.body).clientMsgId, "cm-9");
+  const held = fakeFetch(() => ({ body: { ok: true, result: { held: true, approvalId: "ap-1" } } }));
+  const frame = await artifactAct({ artifactId: "a1", action: "pay", idempotencyKey: "pay-a1" }, { base: BASE, token: TOKEN, fetchImpl: held });
+  assert.equal(held.calls[0].headers["x-idempotency-key"], undefined);
+  assert.equal(JSON.parse(held.calls[0].init.body).idempotencyKey, "pay-a1");
+  assert.equal(frame.ok, true, "approval-held is a result, not an error");
+  assert.equal(frame.result.held, true);
+});
+
+// --- agent desks (books / calendar / crm / files / email Inbox app / meetings) --
+
+test("desk wrappers route to their /v1 methods and POST the params", async () => {
+  const {
+    emailMailboxes, emailThreads, emailTriage, emailDraftSend,
+    filesList, filesDocWriteRevision,
+    calendarFindATime, calendarRsvp,
+    crmListDeals, crmMoveStage,
+    booksReports, booksInvoiceDraft, booksAsk,
+    meetingsRecapFile,
+  } = await import("./ui-parity.mjs");
+  const seen = [];
+  const f = fakeFetch((url) => { seen.push(url); return { body: { ok: true, result: null } }; });
+  const o = { base: BASE, token: TOKEN, idempotencyKey: "k", fetchImpl: f };
+  await emailMailboxes({}, o);
+  await emailThreads({ mailboxId: "mb1", folder: "inbox" }, o);
+  await emailTriage({ threadId: "t1", priority: "P1" }, o);
+  await emailDraftSend({ mailboxId: "mb1", to: ["a@b.co"], bodyText: "hi" }, o);
+  await filesList({ q: "plan" }, o);
+  await filesDocWriteRevision({ fileId: "f1", html: "<p>x</p>" }, o);
+  await calendarFindATime({ attendeeMemberIds: ["m1"], durationMinutes: 30, fromDay: "2026-07-27" }, o);
+  await calendarRsvp({ eventId: "e1", rsvp: "ACCEPTED" }, o);
+  await crmListDeals({ openOnly: true }, o);
+  await crmMoveStage({ dealId: "d1", stage: "PROPOSAL" }, o);
+  await booksReports({ report: "pl" }, o);
+  await booksInvoiceDraft({ payeeName: "Acme", description: "Retainer", totalCents: 120000 }, o);
+  await booksAsk({ question: "What is overdue?" }, o);
+  await meetingsRecapFile({ meetingId: "mt1", recap: { bullets: ["done"] } }, o);
+  assert.deepEqual(seen, [
+    `${BASE}/api/v1/email.mailboxes`,
+    `${BASE}/api/v1/email.threads`,
+    `${BASE}/api/v1/email.triage`,
+    `${BASE}/api/v1/email.draftSend`,
+    `${BASE}/api/v1/files.list`,
+    `${BASE}/api/v1/files.docWriteRevision`,
+    `${BASE}/api/v1/calendar.findATime`,
+    `${BASE}/api/v1/calendar.rsvp`,
+    `${BASE}/api/v1/crm.listDeals`,
+    `${BASE}/api/v1/crm.moveStage`,
+    `${BASE}/api/v1/books.reports`,
+    `${BASE}/api/v1/books.invoiceDraft`,
+    `${BASE}/api/v1/books.ask`,
+    `${BASE}/api/v1/meetings.recapFile`,
+  ]);
+});
+
+// --- directory desk (2026-07) -----------------------------------------------
+
+test("directory wrappers route to their /v1 methods and POST the params", async () => {
+  const {
+    directorySearch, directoryListPeople, directoryGetPerson, directoryAsk,
+    directoryAddChannel, directoryProposeCapture, directoryProposeMerge,
+    directoryRequestAwareness, directoryCreateList,
+  } = await import("./ui-parity.mjs");
+  const seen = [];
+  const f = fakeFetch((url) => { seen.push(url); return { body: { ok: true, result: null } }; });
+  const o = { base: BASE, token: TOKEN, idempotencyKey: "k", fetchImpl: f };
+  await directorySearch({ q: "hartmann" }, o);
+  await directoryListPeople({ relationship: "client", sort: "touch" }, o);
+  await directoryGetPerson({ contactId: "c1" }, o);
+  await directoryAsk({ question: "Who owns Fieldstone?" }, o);
+  await directoryAddChannel({ subjectType: "PERSON", subjectId: "c1", type: "EMAIL", value: "a@b.co", verifiedFrom: "SIGNATURE" }, o);
+  await directoryProposeCapture({ kind: "PERSON", payload: { person: { displayName: "Lena" } }, source: "MAIL", sourceFingerprint: "sig:1" }, o);
+  await directoryProposeMerge({ aRef: "contact:c1", bRef: "contact:c2" }, o);
+  await directoryRequestAwareness({ contactId: "c9", reason: "renewal paper" }, o);
+  await directoryCreateList({ name: "Fieldstone renewal" }, o);
+  assert.deepEqual(seen, [
+    `${BASE}/api/v1/directory.search`,
+    `${BASE}/api/v1/directory.listPeople`,
+    `${BASE}/api/v1/directory.getPerson`,
+    `${BASE}/api/v1/directory.ask`,
+    `${BASE}/api/v1/directory.addChannel`,
+    `${BASE}/api/v1/directory.proposeCapture`,
+    `${BASE}/api/v1/directory.proposeMerge`,
+    `${BASE}/api/v1/directory.requestAwareness`,
+    `${BASE}/api/v1/directory.createList`,
+  ]);
+  assert.equal(JSON.parse(f.calls[5].init.body).sourceFingerprint, "sig:1", "the dedup key rides the body");
+});
+
+test("directory reads are POST RPCs with no idempotency key; idempotent writes forward the caller's", async () => {
+  const { directoryListPeople, directoryCreatePerson } = await import("./ui-parity.mjs");
+  const f = fakeFetch(() => ({ body: { ok: true, result: { people: [] } } }));
+  await directoryListPeople({ scope: "external" }, { base: BASE, token: TOKEN, fetchImpl: f });
+  assert.equal(f.calls[0].init.method, "POST", "directory reads are POST METHODS, not GET reads");
+  assert.equal(f.calls[0].headers["x-idempotency-key"], undefined);
+  await directoryCreatePerson({ displayName: "Lena Hartmann" }, { base: BASE, token: TOKEN, idempotencyKey: "seed-lena", fetchImpl: f });
+  assert.equal(f.calls[1].headers["x-idempotency-key"], "seed-lena");
+});
+
+test("a human-gated directory verb surfaces the server's refusal verbatim, never a throw", async () => {
+  // executeMerge / setAwareness / archive* are human-gated in the hq domain
+  // (DECISIONS D-7). An agent seat gets a FORBIDDEN_SCOPE frame — that refusal is
+  // correct behaviour and must reach the caller intact.
+  const { directoryExecuteMerge } = await import("./ui-parity.mjs");
+  const f = fakeFetch(() => ({ ok: false, status: 403, body: { ok: false, error: { code: "FORBIDDEN_SCOPE", message: "a human resolves merges" } } }));
+  const frame = await directoryExecuteMerge({ candidateId: "m1", survivorRef: "contact:c1" }, { base: BASE, token: TOKEN, fetchImpl: f });
+  assert.equal(frame.ok, false);
+  assert.equal(frame.error.code, "FORBIDDEN_SCOPE");
+  assert.match(frame.error.message, /human/);
+});
+
+test("every desk protocol method has exactly one ui-parity wrapper (196 desks / 328 total)", async () => {
+  const fs = await import("node:fs");
+  const path = await import("node:path");
+  const url = await import("node:url");
+  const here = path.dirname(url.fileURLToPath(import.meta.url));
+  const src = fs.readFileSync(path.join(here, "ui-parity.mjs"), "utf8");
+  const called = [...src.matchAll(/return call\("([a-z]+\.[A-Za-z]+)"/g)].map((x) => x[1]);
+  // 2026-08 mobile-parity delta: +16 desk methods (email 5, files 9,
+  // calendar.ask, crm.ask) → 312 → 328.
+  assert.equal(called.length, 328, "one call() site per wrapper");
+  assert.equal(new Set(called).size, called.length, "no duplicate method bindings");
+  const p = await import("./protocol.mjs");
+  const deskFams = new Set(["books", "calendar", "crm", "directory", "files"]);
+  const deskMethods = Object.entries(p.METHODS)
+    .filter(([n, d]) => deskFams.has(d.family) || n.startsWith("email.") || n === "meetings.recapFile")
+    .map(([n]) => n);
+  const bound = new Set(called);
+  const missing = deskMethods.filter((m) => !bound.has(m));
+  assert.deepEqual(missing, [], "every desk method is wrapped");
+});

package/lib/org/verify.mjs

@@ -0,0 +1,176 @@
+/**
+ * lib/org/verify.mjs — the detective layer (SPEC-org-server §G3).
+ *
+ * The org server is a convenient coordinator, NOT a trusted authority. The
+ * threat model: a compromised or malicious server may *withhold* state or *lie*,
+ * but it must never be able to forge state the agent *accepts* as authoritative.
+ * So every authoritative read is independently re-checked here:
+ *
+ *   - verifySnapshot(snapshot, trustedSignersPem[]) — the server signs the
+ *     canonicalized snapshot with its org-signing key; we verify that signature
+ *     against a PINNED allow-list of public keys baked into the agent's config.
+ *     The signer list is NEVER taken from the snapshot itself (that would let
+ *     the server name its own key) — it is supplied by the caller from pinned
+ *     trust. An unsigned, wrong-signer, or tampered snapshot is rejected.
+ *
+ *   - verifyEvents(events, startPrev) — re-derives the append-only hash chain via
+ *     protocol.verifyChain (the SAME computeRowHash the server wrote with), so a
+ *     rewritten or reordered log is caught at the first broken link.
+ *
+ * Helpers return a `{ok, reason}` quarantine verdict rather than throwing: a
+ * compromised server can DoS us (we refuse its state) but cannot crash us or
+ * slip forged state past. The caller quarantines and falls back to last-good /
+ * file-backed state on `ok:false`.
+ *
+ * Pure: node:crypto via keys.mjs + protocol.mjs. No I/O, no network.
+ *
+ * @module lib/org/verify
+ */
+
+"use strict";
+
+import { canonicalize, verifyChain } from "./protocol.mjs";
+import { verifySignature } from "./keys.mjs";
+
+/**
+ * Build the canonical signing material for a snapshot: the snapshot payload with
+ * its own signature envelope stripped (the server signs the body, not the
+ * signature). We delete `sig`/`signature`/`signer` before canonicalizing so the
+ * bytes match what the server signed.
+ * @param {object} snapshot
+ * @returns {string}
+ */
+function snapshotSigningMaterial(snapshot) {
+  const { sig, signature, signer, ...body } = snapshot || {};
+  void sig; void signature; void signer; // signature envelope is excluded from material
+  return canonicalize(body);
+}
+
+/**
+ * Verify a server snapshot against a PINNED list of trusted signer public keys.
+ *
+ * The snapshot carries a detached signature in `sig` (base64) — and optionally a
+ * `signer` hint — over the canonicalized snapshot body (envelope fields removed).
+ * We try every pinned signer and accept iff one verifies. The pinned list is the
+ * root of trust; an empty list means "nothing is trusted" → reject.
+ *
+ * @param {object} snapshot the server snapshot payload (must contain `sig`)
+ * @param {string[]} trustedSignersPem PINNED SPKI public-key PEMs (from config)
+ * @returns {{ok:true, signer:string}|{ok:false, reason:string}}
+ */
+export function verifySnapshot(snapshot, trustedSignersPem) {
+  if (!snapshot || typeof snapshot !== "object") {
+    return { ok: false, reason: "snapshot not an object" };
+  }
+  const sig = snapshot.sig || snapshot.signature;
+  if (!sig || typeof sig !== "string") {
+    return { ok: false, reason: "snapshot missing signature" };
+  }
+  const signers = Array.isArray(trustedSignersPem) ? trustedSignersPem.filter(Boolean) : [];
+  if (signers.length === 0) {
+    return { ok: false, reason: "no pinned signers (default-deny)" };
+  }
+  const material = Buffer.from(snapshotSigningMaterial(snapshot));
+  for (const pem of signers) {
+    if (verifySignature(pem, material, sig)) {
+      return { ok: true, signer: pem };
+    }
+  }
+  return { ok: false, reason: "signature not from any pinned signer" };
+}
+
+// ---------------------------------------------------------------------------
+// SSH allowed-signers → SPKI PEM (the SPEC-format trust root loader)
+// ---------------------------------------------------------------------------
+
+/** Fixed DER prefix for an Ed25519 SubjectPublicKeyInfo (12 bytes, then 32 raw). */
+const ED25519_SPKI_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
+
+/**
+ * Convert an OpenSSH ed25519 public key (the base64 blob from a `ssh-ed25519
+ * AAAA… [comment]` one-liner, OR the whole one-liner) into a SubjectPublicKeyInfo
+ * PEM that node:crypto / the verify layer can pin. The trust root SPEC uses the
+ * OpenSSH allowed-signers format (`principal namespaces? ssh-ed25519 base64key`),
+ * so we accept either the bare base64 blob or a full allowed-signers / authorized
+ * line and pull the `ssh-ed25519` token out.
+ *
+ * The OpenSSH wire blob is `string("ssh-ed25519") string(<32-byte raw key>)`; the
+ * SPKI DER is the fixed Ed25519 prefix followed by the same 32 raw bytes — so the
+ * conversion is a parse + re-wrap (round-trips exactly with the SPKI PEM
+ * node:crypto exports for the same key). Returns null on any malformed input
+ * (the detective layer treats "can't parse" as "don't trust"). Pure, never throws.
+ *
+ * @param {string} input a base64 ssh-ed25519 blob or a full allowed-signers line
+ * @returns {string|null} SPKI PEM, or null
+ */
+export function sshEd25519ToSpkiPem(input) {
+  try {
+    if (!input || typeof input !== "string") return null;
+    let b64 = input.trim();
+    if (/\s/.test(b64)) {
+      // A full line (allowed-signers or authorized_keys): take the field that
+      // follows the `ssh-ed25519` token, else the longest base64-looking token.
+      const toks = b64.split(/\s+/);
+      const idx = toks.indexOf("ssh-ed25519");
+      b64 = idx >= 0 && toks[idx + 1] ? toks[idx + 1]
+        : toks.filter((t) => /^[A-Za-z0-9+/=]+$/.test(t) && t.length >= 64).sort((a, b) => b.length - a.length)[0] || "";
+    }
+    if (!b64) return null;
+    const blob = Buffer.from(b64, "base64");
+    // Parse the SSH wire format: 4-byte BE length-prefixed strings.
+    let off = 0;
+    const readStr = () => {
+      if (off + 4 > blob.length) throw new Error("truncated");
+      const n = blob.readUInt32BE(off); off += 4;
+      if (off + n > blob.length) throw new Error("truncated");
+      const s = blob.subarray(off, off + n); off += n;
+      return s;
+    };
+    const algo = readStr().toString("utf8");
+    const raw = readStr();
+    if (algo !== "ssh-ed25519" || raw.length !== 32) return null;
+    const der = Buffer.concat([ED25519_SPKI_PREFIX, raw]);
+    const body = der.toString("base64").replace(/(.{64})/g, "$1\n").replace(/\n$/, "");
+    return `-----BEGIN PUBLIC KEY-----\n${body}\n-----END PUBLIC KEY-----\n`;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Verify a contiguous slice of the event chain. Delegates to the protocol's
+ * `verifyChain` (which uses the load-bearing computeRowHash). Returns a
+ * quarantine verdict instead of the raw break object.
+ *
+ * @param {Array<object>} events ordered by seq ascending
+ * @param {string} [startPrev=""] row_hash of the event BEFORE events[0]
+ * @returns {{ok:true}|{ok:false, reason:string, index:number}}
+ */
+export function verifyEvents(events, startPrev = "") {
+  if (!Array.isArray(events)) {
+    return { ok: false, reason: "events not an array", index: -1 };
+  }
+  const broken = verifyChain(events, startPrev);
+  if (broken) {
+    return { ok: false, reason: broken.reason, index: broken.index };
+  }
+  return { ok: true };
+}
+
+/**
+ * Quarantine wrapper: run a verifier and normalise any thrown error into a
+ * `{ok:false, reason}` verdict, so a malformed payload from a hostile server can
+ * never crash the caller. Accepts a thunk that returns a `{ok,...}` verdict.
+ *
+ * @param {() => ({ok:boolean, reason?:string})} fn
+ * @returns {{ok:boolean, reason?:string}}
+ */
+export function quarantine(fn) {
+  try {
+    const v = fn();
+    if (v && typeof v.ok === "boolean") return v;
+    return { ok: false, reason: "verifier returned no verdict" };
+  } catch (err) {
+    return { ok: false, reason: `verify threw: ${err && err.message ? err.message : String(err)}` };
+  }
+}