@uuaid/pillar 0.2.0-alpha.10

package/src/bridges/zestro.mjs

@@ -0,0 +1,155 @@
+/**
+ * Zestro WebSocket bridge.
+ *
+ * Wire protocol — verified against the OFFICIAL client contract
+ * (Zestro app.asar: dist/cli/maestro-client.ts, sourcesContent from
+ * maestro-cli.js.map) and the app's own server/renderer handlers:
+ *   ws://127.0.0.1:53522/<token>/ws
+ *   -> { type: "send_command", requestId: "req_...", sessionId: <agentId>,
+ *        command: <str>, inputMode: "ai", tabId?: <uuid>, force?: true }
+ *   <- { type: "command_result", success, sessionId, tabId?, requestId }  // echoes requestId
+ *   <- { type: "error", message, sessionId }                              // NO requestId echo
+ *
+ * Correlation is on `requestId`, NOT `id` — the server echoes only
+ * `requestId`, so a client correlating on `id` can never match a reply.
+ *
+ * Semantics (verified in app code, all four layers):
+ * - command_result arrives IMMEDIATELY after the renderer receives the
+ *   command — it means "consumed by the renderer / spawn initiated", NOT
+ *   "the agent's turn completed". The turn answer returns out-of-band.
+ * - A busy target session WITHOUT force is rejected by the server
+ *   ({type:"error"}), and the renderer has TWO more busy drops of its own.
+ *   Errors carry no requestId, so they must be handled single-flight.
+ * - force=true on a BUSY tab spawns a SECOND agent process resuming the
+ *   same session transcript (handle-spawn.js: no live-process guard,
+ *   --resume <agentSessionId>). Concurrent, not queued. Opt-in only.
+ *
+ * Token lives in ~/Library/Application Support/zestro/cli-server.json.
+ * Agent id for ZZ was verified to be 7fbce535-3a2f-4e6b-96e6-64926403efa5.
+ */
+import { WebSocket } from "ws";
+
+/** Server rejected the command (busy session, bad payload, ...). */
+export class ZestroServerError extends Error {
+  constructor(message, code = "ZESTRO_SERVER_ERROR") {
+    super(message);
+    this.name = "ZestroServerError";
+    this.code = code;
+  }
+}
+
+export class ZestroBridge {
+  constructor({ url, token, sessionId, tabId, timeoutMs = 30000, force = false }) {
+    if (!url || !token || !sessionId) {
+      throw new Error("ZestroBridge requires { url, token, sessionId }");
+    }
+    // Accept either the token-embedded URL or the base URL.
+    if (!url.includes("/ws")) {
+      if (!url.endsWith("/")) url += "/";
+      url = `${url}${token}/ws`;
+    }
+    this.url = url;
+    this.sessionId = sessionId;
+    this.tabId = tabId ?? null;
+    this.timeoutMs = timeoutMs;
+    this.force = force;
+    this._ws = null;
+    this._pending = new Map();
+  }
+
+  connect() {
+    return new Promise((resolve, reject) => {
+      const ws = new WebSocket(this.url);
+      ws.on("open", () => { this._ws = ws; resolve(); });
+      ws.on("error", (e) => { if (!this._ws) reject(e); });
+      ws.on("close", () => {
+        for (const p of this._pending.values()) p.reject(new Error("bridge closed"));
+        this._pending.clear();
+        this._ws = null;
+      });
+      ws.on("message", (buf) => {
+        let msg;
+        try { msg = JSON.parse(buf.toString()); } catch { return; }
+
+        // `echo` = the app did not recognize the message type (older build).
+        if (msg.type === "echo") {
+          const original = msg.data ?? {};
+          const reqId = original.requestId ?? msg.originalRequestId;
+          if (reqId && this._pending.has(reqId)) {
+            this._settle(reqId, p => p.reject(new ZestroServerError(
+              `Zestro app does not support '${original.type ?? "unknown"}' (older build?)`,
+              "ZESTRO_UNSUPPORTED"
+            )));
+          }
+          return;
+        }
+
+        // Exact correlation: server echoes requestId on command_result.
+        if (msg.requestId && this._pending.has(msg.requestId)) {
+          this._settle(msg.requestId, p => p.resolve(msg));
+          return;
+        }
+
+        // Single-flight: server `error` replies carry NO requestId (verified:
+        // sendError sends {type:'error', message, ...extra}). The bridge keeps
+        // at most one request in flight, so route orphan replies to it.
+        if (msg.type === "error") {
+          const message = msg.message ?? "zestro server error";
+          const code = /busy/i.test(message) ? "SESSION_BUSY" : "ZESTRO_SERVER_ERROR";
+          this._settleOldest(p => p.reject(new ZestroServerError(message, code)));
+          return;
+        }
+        if (msg.type === "command_result") {
+          this._settleOldest(p => p.resolve(msg));
+        }
+      });
+    });
+  }
+
+  _settle(requestId, fn) {
+    const p = this._pending.get(requestId);
+    if (p) {
+      this._pending.delete(requestId);
+      fn(p);
+    }
+  }
+
+  _settleOldest(fn) {
+    const first = this._pending.entries().next();
+    if (!first.done) {
+      const [requestId, p] = first.value;
+      this._pending.delete(requestId);
+      fn(p);
+    }
+  }
+
+  sendCommand({ command, inputMode = "ai", force } = {}) {
+    if (!this._ws || this._ws.readyState !== WebSocket.OPEN) {
+      return Promise.reject(new Error("zestro bridge not connected"));
+    }
+    const requestId = `req_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this._pending.delete(requestId);
+        reject(new Error(`zestro send_command ${requestId} timed out after ${this.timeoutMs}ms`));
+      }, this.timeoutMs);
+      this._pending.set(requestId, {
+        resolve: (msg) => { clearTimeout(timer); resolve(msg); },
+        reject:  (e)   => { clearTimeout(timer); reject(e); },
+      });
+      this._ws.send(JSON.stringify({
+        type: "send_command",
+        requestId,
+        sessionId: this.sessionId,
+        command,
+        inputMode,
+        ...(this.tabId ? { tabId: this.tabId } : {}),
+        ...((force ?? this.force) ? { force: true } : {}),
+      }));
+    });
+  }
+
+  close() {
+    if (this._ws) { try { this._ws.close(); } catch (_e) {} this._ws = null; }
+  }
+}

package/src/crypto/e2e.mjs

@@ -0,0 +1,97 @@
+/**
+ * End-to-end payload encryption — FUNDAMENTAL, not optional.
+ *
+ * Every envelope's payload is sealed to the recipient's key.  There is no
+ * plaintext mode.  A carrier (or any relay) sees only ciphertext.
+ *
+ * Construction (sealed box over the agent's existing Ed25519 identity):
+ *   1. Recipient's Ed25519 public key  --birational map-->  X25519 public key
+ *      (libsodium crypto_sign_ed25519_pk_to_curve25519 equivalent;
+ *       @noble/curves ed25519.utils.toMontgomery)
+ *   2. Sender mints an EPHEMERAL X25519 keypair per envelope (forward secrecy
+ *      per message: compromising the sender's long-term key never decrypts
+ *      past traffic; compromising the recipient's does — that's the classic
+ *      sealed-box tradeoff, addressed by key rotation policy, not this layer).
+ *   3. shared = X25519(ephemeralPriv, recipientX25519Pub)
+ *   4. key = HKDF-SHA256(shared, salt = epk || recipientX25519Pub,
+ *                        info = "uuaid-pillar-e2e/1")  -> 32 bytes
+ *   5. AES-256-GCM(key, iv = random 12 bytes) over JCS(payload)
+ *      AAD = envelope id  (binds ciphertext to THIS envelope; a ciphertext
+ *      transplanted into another envelope fails the GCM tag).
+ *
+ * Identity binding: callers MUST verify sha256(recipientEdPub) derives the
+ * recipient's UUAID local-id before sealing (seal() in envelope.mjs does it).
+ */
+import { createHash, createCipheriv, createDecipheriv, hkdfSync, randomBytes } from "node:crypto";
+import { ed25519, x25519 } from "@noble/curves/ed25519.js";
+import { jcs } from "../identity/jcs.mjs";
+
+export const E2E_ALG = "x25519-hkdf-sha256-aes256gcm";
+const HKDF_INFO = "uuaid-pillar-e2e/1";
+
+/** Convert an Ed25519 public key (hex) to its X25519 (Montgomery) form. */
+export function edPubToX25519(edPubHex) {
+  return Buffer.from(ed25519.utils.toMontgomery(Buffer.from(edPubHex, "hex")));
+}
+
+/** Convert an Ed25519 seed (32 raw private bytes) to an X25519 secret. */
+export function edSeedToX25519(seed32) {
+  return Buffer.from(ed25519.utils.toMontgomerySecret(seed32));
+}
+
+function deriveKey(shared, epk, recipientXPub) {
+  const salt = Buffer.concat([epk, recipientXPub]);
+  return Buffer.from(hkdfSync("sha256", shared, salt, HKDF_INFO, 32));
+}
+
+/**
+ * Seal a payload object to a recipient's Ed25519 public key.
+ * Returns the `enc` block for the envelope.
+ */
+export function sealPayload(recipientEdPubHex, payload, { aad }) {
+  if (!aad) throw new Error("sealPayload: aad (envelope id) required");
+  const recipientXPub = edPubToX25519(recipientEdPubHex);
+  const ephemeralSecret = randomBytes(32);
+  const epk = Buffer.from(x25519.getPublicKey(ephemeralSecret));
+  const shared = Buffer.from(x25519.getSharedSecret(ephemeralSecret, recipientXPub));
+  const key = deriveKey(shared, epk, recipientXPub);
+  const iv = randomBytes(12);
+  const cipher = createCipheriv("aes-256-gcm", key, iv);
+  cipher.setAAD(Buffer.from(aad, "utf-8"));
+  const plaintext = Buffer.from(jcs(payload), "utf-8");
+  const ct = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return {
+    alg: E2E_ALG,
+    epk: epk.toString("hex"),
+    iv: iv.toString("hex"),
+    ct: Buffer.concat([ct, tag]).toString("hex"), // tag appended, last 16 bytes
+  };
+}
+
+/**
+ * Open a sealed payload with the recipient's Ed25519 seed (32 bytes).
+ * Throws on any integrity failure (wrong key, tamper, transplanted aad).
+ */
+export function openPayload(recipientSeed32, enc, { aad }) {
+  if (!enc || enc.alg !== E2E_ALG) throw new Error(`openPayload: unsupported alg ${enc?.alg}`);
+  if (!aad) throw new Error("openPayload: aad (envelope id) required");
+  const xSecret = edSeedToX25519(recipientSeed32);
+  const recipientXPub = Buffer.from(x25519.getPublicKey(xSecret));
+  const epk = Buffer.from(enc.epk, "hex");
+  const shared = Buffer.from(x25519.getSharedSecret(xSecret, epk));
+  const key = deriveKey(shared, epk, recipientXPub);
+  const raw = Buffer.from(enc.ct, "hex");
+  const ct = raw.subarray(0, raw.length - 16);
+  const tag = raw.subarray(raw.length - 16);
+  const decipher = createDecipheriv("aes-256-gcm", key, Buffer.from(enc.iv, "hex"));
+  decipher.setAAD(Buffer.from(aad, "utf-8"));
+  decipher.setAuthTag(tag);
+  const plaintext = Buffer.concat([decipher.update(ct), decipher.final()]);
+  return JSON.parse(plaintext.toString("utf-8"));
+}
+
+/** sha256 helper for identity binding checks. */
+export function sha256Hex(buf) {
+  return createHash("sha256").update(buf).digest("hex");
+}

package/src/identity/jcs.mjs

@@ -0,0 +1,35 @@
+/**
+ * RFC 8785 JCS canonicalization.  Same implementation as the pillar-core reference,
+ * kept independent so the pillar-node package has no upward dependency.
+ *
+ * Numbers: integers only (safe for the wire we design; enforce it).  Floats
+ * throw because deterministic ECMA-262 number serialization requires more code
+ * than we want in a reference impl and this package's message payloads never
+ * legitimately contain non-integer numbers.
+ */
+export function jcs(value) {
+  return _ser(value);
+}
+
+function _ser(v) {
+  if (v === null) return "null";
+  if (v === true) return "true";
+  if (v === false) return "false";
+  if (typeof v === "string") return JSON.stringify(v);
+  if (typeof v === "number") {
+    if (!Number.isFinite(v)) throw new Error("JCS: NaN/Infinity not permitted");
+    if (Number.isInteger(v)) return String(v);
+    throw new Error("JCS: non-integer numbers not permitted; use string decimal encoding");
+  }
+  if (typeof v === "bigint") return v.toString();
+  if (Array.isArray(v)) return "[" + v.map(_ser).join(",") + "]";
+  if (typeof v === "object") {
+    // UTF-16 code unit sort — the RFC 8785 requirement.
+    const keys = Object.keys(v).sort((a, b) => {
+      const ab = Buffer.from(a, "utf16le"), bb = Buffer.from(b, "utf16le");
+      return Buffer.compare(ab, bb);
+    });
+    return "{" + keys.map(k => JSON.stringify(k) + ":" + _ser(v[k])).join(",") + "}";
+  }
+  throw new Error("JCS: unsupported type " + typeof v);
+}

package/src/identity/keychain.mjs

@@ -0,0 +1,140 @@
+/**
+ * Keychain — persistent identity for a pillar peer.
+ *
+ * Every agent has exactly one identity: an Ed25519 keypair.  The private key
+ * is stored encrypted at rest with a password derived from the OS keyring
+ * (Windows Credential Manager / macOS Keychain / GNOME libsecret) if
+ * available, or a user-supplied passphrase otherwise.
+ *
+ * The keychain is deliberately simple: one keypair, one UUAID, one file.
+ * Rotation is a new keypair + a new signed profile in the DHT.
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync, chmodSync } from "node:fs";
+import { dirname } from "node:path";
+import { randomBytes, createHash, generateKeyPairSync, sign, verify, createPublicKey, createPrivateKey, hkdfSync, createCipheriv, createDecipheriv } from "node:crypto";
+
+const KEYCHAIN_VERSION = 1;
+
+export class Keychain {
+  constructor(path) {
+    this.path = path;
+    this._identity = null; // { uuaid, publicKeyHex, privateKey (KeyObject), createdAt }
+  }
+
+  exists() {
+    return existsSync(this.path);
+  }
+
+  /**
+   * Generate a fresh identity.  Never overwrites.
+   *
+   * uuaidNamespace: default "foundation" per IAASO-1001 today; will support
+   * federated forms once federation profile ratifies.
+   * objectType: default "agent"; overridable to "service" etc.
+   * localId: default random UUIDv4-like; caller may supply.
+   */
+  static generate({ uuaidNamespace = "foundation", objectType = "agent", localId = null } = {}) {
+    const { publicKey, privateKey } = generateKeyPairSync("ed25519");
+    const pubDer = publicKey.export({ type: "spki", format: "der" });
+    const rawPub = pubDer.slice(pubDer.length - 32);
+    const localIdActual = localId ?? Keychain._localIdFromKey(rawPub);
+    const uuaid = `uuaid:${uuaidNamespace}:${objectType}:${localIdActual}`;
+    return {
+      uuaid,
+      publicKey,
+      privateKey,
+      publicKeyHex: Buffer.from(rawPub).toString("hex"),
+      createdAt: new Date().toISOString(),
+    };
+  }
+
+  static _localIdFromKey(rawPub) {
+    // Derive a stable, publishable local id from the public key.  This makes
+    // the UUAID self-authenticating: given the UUAID, anyone can independently
+    // check that the public key hashes to the expected local-id.
+    const h = createHash("sha256").update(rawPub).digest();
+    // First 16 bytes -> UUID-style dash format for readability.
+    const b = h.slice(0, 16);
+    const hex = Buffer.from(b).toString("hex");
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+  }
+
+  /**
+   * Load an identity from disk.
+   */
+  load({ passphrase } = {}) {
+    if (!this.exists()) throw new Error("keychain not initialized; run `pillar init` first");
+    const blob = JSON.parse(readFileSync(this.path, "utf-8"));
+    if (blob.version !== KEYCHAIN_VERSION) throw new Error(`unsupported keychain version ${blob.version}`);
+    const salt = Buffer.from(blob.salt, "hex");
+    const key = hkdfSync("sha256", Buffer.from(passphrase ?? "", "utf-8"), salt, "uuaid-pillar-keychain-v1", 32);
+    const iv = Buffer.from(blob.iv, "hex");
+    const ct = Buffer.from(blob.ciphertext, "base64");
+    const tag = Buffer.from(blob.tag, "hex");
+    const decipher = createDecipheriv("aes-256-gcm", Buffer.from(key), iv);
+    decipher.setAuthTag(tag);
+    const plain = Buffer.concat([decipher.update(ct), decipher.final()]);
+    const seed = plain; // 32-byte raw ed25519 seed
+    const pkcs8Prefix = Buffer.from("302e020100300506032b657004220420", "hex");
+    const privateKey = createPrivateKey({ key: Buffer.concat([pkcs8Prefix, seed]), format: "der", type: "pkcs8" });
+    const publicKey = createPublicKey(privateKey);
+    const pubDer = publicKey.export({ type: "spki", format: "der" });
+    const rawPub = pubDer.slice(pubDer.length - 32);
+    const publicKeyHex = Buffer.from(rawPub).toString("hex");
+    // Sanity: derived UUAID must match stored UUAID.
+    const derivedLocalId = Keychain._localIdFromKey(rawPub);
+    const parts = blob.uuaid.split(":");
+    if (parts.length < 4 || parts[3] !== derivedLocalId) {
+      throw new Error("keychain integrity failure: UUAID does not match keypair");
+    }
+    this._identity = { uuaid: blob.uuaid, publicKey, privateKey, publicKeyHex, createdAt: blob.createdAt };
+    return this._identity;
+  }
+
+  /**
+   * Save identity to disk, encrypted with the passphrase.
+   */
+  save(identity, { passphrase } = {}) {
+    const seedDer = identity.privateKey.export({ type: "pkcs8", format: "der" });
+    const seed = seedDer.slice(seedDer.length - 32);
+    const salt = randomBytes(16);
+    const key = hkdfSync("sha256", Buffer.from(passphrase ?? "", "utf-8"), salt, "uuaid-pillar-keychain-v1", 32);
+    const iv = randomBytes(12);
+    const cipher = createCipheriv("aes-256-gcm", Buffer.from(key), iv);
+    const ct = Buffer.concat([cipher.update(seed), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    const blob = {
+      version: KEYCHAIN_VERSION,
+      uuaid: identity.uuaid,
+      createdAt: identity.createdAt,
+      salt: salt.toString("hex"),
+      iv: iv.toString("hex"),
+      ciphertext: ct.toString("base64"),
+      tag: tag.toString("hex"),
+      // Public material is stored in the clear so `pillar profile` doesn't need a passphrase.
+      publicKeyHex: identity.publicKeyHex,
+    };
+    mkdirSync(dirname(this.path), { recursive: true });
+    writeFileSync(this.path, JSON.stringify(blob, null, 2));
+    chmodSync(this.path, 0o600);
+    this._identity = identity;
+  }
+
+  publicView() {
+    if (!this.exists()) return null;
+    const blob = JSON.parse(readFileSync(this.path, "utf-8"));
+    return { uuaid: blob.uuaid, publicKeyHex: blob.publicKeyHex, createdAt: blob.createdAt };
+  }
+
+  sign(data) {
+    if (!this._identity) throw new Error("identity not loaded");
+    return sign(null, Buffer.isBuffer(data) ? data : Buffer.from(data, "utf-8"), this._identity.privateKey);
+  }
+
+  static verifyDetached(publicKeyHex, data, signatureBytes) {
+    const spkiPrefix = Buffer.from("302a300506032b6570032100", "hex");
+    const der = Buffer.concat([spkiPrefix, Buffer.from(publicKeyHex, "hex")]);
+    const pub = createPublicKey({ key: der, format: "der", type: "spki" });
+    return verify(null, Buffer.isBuffer(data) ? data : Buffer.from(data, "utf-8"), pub, signatureBytes);
+  }
+}

package/src/index.mjs

@@ -0,0 +1,18 @@
+/**
+ * @uuaid/pillar — v0.2.0-alpha.0
+ *
+ * IAASO-3050 reference: every agent runs its own PDP pillar, discovers peers
+ * via a Kademlia DHT, exchanges cryptographically signed messages over libp2p.
+ *
+ * Entry point.  Not intended for import in browsers today — browser build
+ * lives at @uuaid/pillar-browser (later).
+ */
+export { Keychain } from "./identity/keychain.mjs";
+export { jcs } from "./identity/jcs.mjs";
+export { seal, open, decrypt, envelopeSha, keychainSeed, ENVELOPE_VERSION, E2E_ALG } from "./net/envelope.mjs";
+export { sealPayload, openPayload, edPubToX25519, edSeedToX25519 } from "./crypto/e2e.mjs";
+export { Mailbox } from "./mailbox/mailbox.mjs";
+export { Pillar } from "./pillar.mjs";
+export { createTransport, PILLAR_PROTOCOL, uuaidToDhtKey, peerIdFromEd25519Hex } from "./net/transport.mjs";
+export { CarrierClient } from "./net/carrier-client.mjs";
+export { CarrierServer } from "./net/carrier-server.mjs";

package/src/mailbox/mailbox.mjs

@@ -0,0 +1,194 @@
+/**
+ * Mailbox — per-agent SQLite outbox + inbox with per-log chain hashes.
+ *
+ * Every agent owns its own state.  This is the local truth.  Peers observe
+ * envelopes in flight, but the sender's outbox chain and the recipient's
+ * inbox chain are the authoritative record from each party's perspective.
+ * Disagreements are provable via chain-hash comparison.
+ *
+ * Two tables:
+ *   outbox: envelopes this agent has sent.  Chain-hashed.
+ *   inbox : envelopes this agent has received.  Chain-hashed independently.
+ *
+ * A "chained hash" over a log is:
+ *   chain[0] = sha256("uuaid-pillar-mailbox-v1|" + envelope_sha256[0])
+ *   chain[n] = sha256(chain[n-1] + envelope_sha256[n])
+ * Where envelope_sha256[i] = sha256(JCS(envelope[i])).
+ */
+import Database from "better-sqlite3";
+import { createHash } from "node:crypto";
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { jcs } from "../identity/jcs.mjs";
+
+const SCHEMA = `
+create table if not exists outbox (
+  seq             integer primary key autoincrement,
+  envelope_id     text not null unique,
+  envelope_sha256 text not null,
+  recipient       text not null,
+  created_at      text not null,
+  envelope_json   text not null,
+  chain_hash      text not null,
+  status          text not null default 'pending',
+  delivered_at    text,
+  ack_sha256      text
+);
+create index if not exists outbox_recipient on outbox (recipient);
+create index if not exists outbox_status on outbox (status);
+
+create table if not exists inbox (
+  seq             integer primary key autoincrement,
+  envelope_id     text not null unique,
+  envelope_sha256 text not null,
+  sender          text not null,
+  received_at     text not null,
+  envelope_json   text not null,
+  chain_hash      text not null,
+  read_at         text
+);
+create index if not exists inbox_sender on inbox (sender);
+
+create table if not exists carrier_cursors (
+  carrier text primary key,
+  seq     integer not null
+);
+
+create table if not exists chain_state (
+  log_name        text primary key,
+  chain_head      text not null
+);
+`;
+
+const CHAIN_SEED = "uuaid-pillar-mailbox-v1|";
+
+export class Mailbox {
+  constructor(path) {
+    mkdirSync(dirname(path), { recursive: true });
+    this.db = new Database(path);
+    this.db.pragma("journal_mode = WAL");
+    this.db.pragma("synchronous = NORMAL");
+    this.db.exec(SCHEMA);
+  }
+
+  close() { try { this.db.close(); } catch (_e) {} }
+
+  /** Carrier polling cursors: carrier URL -> highest seq we have consumed. */
+  getCarrierCursors() {
+    const rows = this.db.prepare("select carrier, seq from carrier_cursors").all();
+    return Object.fromEntries(rows.map(r => [r.carrier, r.seq]));
+  }
+
+  setCarrierCursor(carrier, seq) {
+    this.db.prepare(
+      "insert into carrier_cursors (carrier, seq) values (?, ?) on conflict(carrier) do update set seq = max(seq, excluded.seq)"
+    ).run(carrier, seq);
+  }
+
+  _getHead(logName) {
+    const row = this.db.prepare("select chain_head from chain_state where log_name = ?").get(logName);
+    return row?.chain_head ?? null;
+  }
+  _setHead(logName, hash) {
+    this.db.prepare("insert into chain_state (log_name, chain_head) values (?, ?) on conflict (log_name) do update set chain_head = excluded.chain_head").run(logName, hash);
+  }
+
+  static envelopeSha(envelope) {
+    return createHash("sha256").update(jcs(envelope)).digest("hex");
+  }
+
+  /**
+   * Append an outgoing envelope.  Envelope must be a JS object that is JCS-canonicalizable
+   * and MUST include at least `id`, `recipient`, `createdAt`.  Chain hash is computed
+   * atomically with the insert; concurrent appends are serialized via the SQLite transaction.
+   */
+  appendOutbound(envelope) {
+    return this.db.transaction(() => {
+      const envSha = Mailbox.envelopeSha(envelope);
+      const prev = this._getHead("outbox");
+      const chainInput = prev == null ? CHAIN_SEED + envSha : prev + envSha;
+      const chain = createHash("sha256").update(chainInput).digest("hex");
+      this.db.prepare(`
+        insert into outbox (envelope_id, envelope_sha256, recipient, created_at, envelope_json, chain_hash, status)
+        values (?, ?, ?, ?, ?, ?, 'pending')
+      `).run(envelope.id, envSha, envelope.recipient, envelope.createdAt, JSON.stringify(envelope), chain);
+      this._setHead("outbox", chain);
+      return { envelopeId: envelope.id, envelopeSha256: envSha, chainHash: chain };
+    })();
+  }
+
+  /**
+   * Append an incoming envelope.  Same shape.  MUST be idempotent on envelope.id;
+   * a duplicate delivery does NOT re-append and does NOT advance the chain.
+   */
+  appendInbound(envelope) {
+    return this.db.transaction(() => {
+      const existing = this.db.prepare("select envelope_id, envelope_sha256 from inbox where envelope_id = ?").get(envelope.id);
+      if (existing) {
+        return { duplicate: true, envelopeId: envelope.id, envelopeSha256: existing.envelope_sha256 };
+      }
+      const envSha = Mailbox.envelopeSha(envelope);
+      const prev = this._getHead("inbox");
+      const chainInput = prev == null ? CHAIN_SEED + envSha : prev + envSha;
+      const chain = createHash("sha256").update(chainInput).digest("hex");
+      this.db.prepare(`
+        insert into inbox (envelope_id, envelope_sha256, sender, received_at, envelope_json, chain_hash)
+        values (?, ?, ?, ?, ?, ?)
+      `).run(envelope.id, envSha, envelope.sender ?? envelope.from ?? "unknown", new Date().toISOString(), JSON.stringify(envelope), chain);
+      this._setHead("inbox", chain);
+      return { duplicate: false, envelopeId: envelope.id, envelopeSha256: envSha, chainHash: chain };
+    })();
+  }
+
+  markOutboundDelivered(envelopeId, ackSha256) {
+    this.db.prepare("update outbox set status = 'delivered', delivered_at = ?, ack_sha256 = ? where envelope_id = ?")
+      .run(new Date().toISOString(), ackSha256 ?? null, envelopeId);
+  }
+
+  outboxTip() { return this._getHead("outbox") ?? "0".repeat(64); }
+  inboxTip()  { return this._getHead("inbox")  ?? "0".repeat(64); }
+
+  outboxSince(seq = 0, limit = 100) {
+    return this.db.prepare("select * from outbox where seq > ? order by seq asc limit ?").all(seq, limit);
+  }
+  inboxSince(seq = 0, limit = 100) {
+    return this.db.prepare("select * from inbox where seq > ? order by seq asc limit ?").all(seq, limit);
+  }
+
+  /** Envelopes never shown to the operator (read_at null). Oldest first. */
+  inboxUnread(limit = 100) {
+    return this.db.prepare("select * from inbox where read_at is null order by seq asc limit ?").all(limit);
+  }
+
+  markInboxRead(envelopeId) {
+    this.db.prepare("update inbox set read_at = ? where envelope_id = ? and read_at is null")
+      .run(new Date().toISOString(), envelopeId);
+  }
+
+  /**
+   * Recompute the outbox chain from scratch and compare to stored chain_hash column.
+   * Returns { ok, badSeq? }.  Used by adversarial tests + operator-driven audits.
+   */
+  auditOutbox() {
+    const rows = this.db.prepare("select seq, envelope_sha256, chain_hash from outbox order by seq asc").all();
+    let prev = null;
+    for (const r of rows) {
+      const chainInput = prev == null ? CHAIN_SEED + r.envelope_sha256 : prev + r.envelope_sha256;
+      const expected = createHash("sha256").update(chainInput).digest("hex");
+      if (expected !== r.chain_hash) return { ok: false, badSeq: r.seq };
+      prev = r.chain_hash;
+    }
+    return { ok: true };
+  }
+  auditInbox() {
+    const rows = this.db.prepare("select seq, envelope_sha256, chain_hash from inbox order by seq asc").all();
+    let prev = null;
+    for (const r of rows) {
+      const chainInput = prev == null ? CHAIN_SEED + r.envelope_sha256 : prev + r.envelope_sha256;
+      const expected = createHash("sha256").update(chainInput).digest("hex");
+      if (expected !== r.chain_hash) return { ok: false, badSeq: r.seq };
+      prev = r.chain_hash;
+    }
+    return { ok: true };
+  }
+}