@uuaid/pillar 0.2.0-alpha.6

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@uuaid/pillar",
+  "version": "0.2.0-alpha.6",
+  "description": "IAASO-3050 reference implementation. Every agent runs its own PDP pillar, discovers peers via a Kademlia DHT, and exchanges cryptographically signed + Noise-encrypted messages over libp2p. One command to install and join the network.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "src/index.mjs",
+  "bin": {
+    "pillar": "bin/pillar.mjs",
+    "pillar-carrier": "bin/carrier.mjs",
+    "pillar-ask": "bin/pillar-ask.mjs",
+    "pillar-responder": "bin/pillar-responder.mjs",
+    "pillar-seed": "bin/pillar-seed.mjs"
+  },
+  "exports": {
+    ".": "./src/index.mjs"
+  },
+  "files": [
+    "src",
+    "bin",
+    "README.md",
+    "INTERACTION-CONVENTION.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test --test-reporter spec test/unit/*.test.mjs",
+    "test:int": "node --test --test-reporter spec test/integration/*.test.mjs",
+    "test:chaos": "node --test --test-reporter spec test/chaos/*.test.mjs",
+    "test:all": "node --test --test-reporter spec test/unit/*.test.mjs test/integration/*.test.mjs test/chaos/*.test.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@chainsafe/libp2p-noise": "^17.0.0",
+    "@chainsafe/libp2p-yamux": "^8.0.1",
+    "@libp2p/autonat": "^3.0.26",
+    "@libp2p/bootstrap": "^12.0.29",
+    "@libp2p/circuit-relay-v2": "^4.2.11",
+    "@libp2p/crypto": "^5.1.22",
+    "@libp2p/dcutr": "^3.0.26",
+    "@libp2p/identify": "^4.1.12",
+    "@libp2p/kad-dht": "^16.4.3",
+    "@libp2p/peer-id": "^6.0.14",
+    "@libp2p/ping": "^3.1.11",
+    "@libp2p/tcp": "^11.0.26",
+    "@libp2p/webrtc": "^6.0.29",
+    "@libp2p/websockets": "^10.1.19",
+    "@multiformats/multiaddr": "^13.0.3",
+    "@noble/curves": "^2.3.0",
+    "better-sqlite3": "^11.10.0",
+    "it-pipe": "^3.0.1",
+    "it-pushable": "^3.2.4",
+    "libp2p": "^3.3.8",
+    "multiformats": "^14.0.5",
+    "uint8arrays": "^5.1.1",
+    "ws": "^8.21.3"
+  }
+}

package/src/address-book.mjs

@@ -0,0 +1,42 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+
+/**
+ * Load a fleet.json address book into a Pillar instance.
+ *
+ * Shape: { "fleet": { "<role>": { uuaid, addrs?, peerId?, publicKey } } }.
+ * `pillar init --directory` writes one from the directory's agents[] so a
+ * fresh agent can `ask`/`send` with no manual key plumbing.
+ */
+export function loadFleetAddressBook(fleetPath, pillar) {
+  if (!fleetPath || !existsSync(fleetPath)) return 0;
+  const fleet = JSON.parse(readFileSync(fleetPath, "utf-8")).fleet ?? {};
+  // Warm handoff: fleet.json addrs come from a short-lived `pillar id` probe
+  // on /tcp/0, so a running daemon's REAL addr differs. Each daemon writes
+  // <home>/runtime.json on boot; prefer that addr when fresh.
+  const fleetRoot = dirname(fleetPath);
+  let n = 0;
+  for (const [role, id] of Object.entries(fleet)) {
+    if (!id.uuaid) continue;
+    if (id.uuaid === pillar.uuaid) continue; // don't self-register
+    let multiaddr = id.addrs?.[0];
+    let peerId = id.peerId;
+    const rtPath = join(fleetRoot, role, "runtime.json");
+    if (existsSync(rtPath)) {
+      try {
+        const rt = JSON.parse(readFileSync(rtPath, "utf-8"));
+        if (rt.uuaid === id.uuaid && rt.addrs?.[0]) {
+          multiaddr = rt.addrs[0];
+          peerId = rt.peerId ?? peerId;
+        }
+      } catch (_e) {}
+    }
+    pillar.registerAddress(id.uuaid, {
+      peerId,
+      multiaddr,
+      publicKey: id.publicKey, // REQUIRED for E2E sends
+    });
+    n++;
+  }
+  return n;
+}

package/src/bridges/zestro.mjs

@@ -0,0 +1,83 @@
+/**
+ * Zestro WebSocket bridge.
+ *
+ * Wire protocol (from ZZ's Mac audit):
+ *   ws://127.0.0.1:53522/<token>/ws
+ *   -> { type: "send_command", id: <uuid>, sessionId: <agentId>, command: <str>, inputMode: "ai" }
+ *   <- { type: "command_result", id: <uuid>, ... }
+ *
+ * Token lives in ~/Library/Application Support/zestro/cli-server.json.
+ * Agent id for ZZ was verified to be 7fbce535-3a2f-4e6b-96e6-64926403efa5.
+ *
+ * Correlation on `id` so multiple concurrent sends don't race.
+ */
+import { WebSocket } from "ws";
+import { randomUUID } from "node:crypto";
+
+export class ZestroBridge {
+  constructor({ url, token, sessionId, timeoutMs = 30000 }) {
+    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.timeoutMs = timeoutMs;
+    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; }
+        if (msg.type === "command_result" && msg.id && this._pending.has(msg.id)) {
+          const p = this._pending.get(msg.id);
+          this._pending.delete(msg.id);
+          p.resolve(msg);
+        }
+      });
+    });
+  }
+
+  sendCommand({ command, inputMode = "ai" }) {
+    if (!this._ws || this._ws.readyState !== WebSocket.OPEN) {
+      return Promise.reject(new Error("zestro bridge not connected"));
+    }
+    const id = randomUUID();
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this._pending.delete(id);
+        reject(new Error(`zestro send_command ${id} timed out after ${this.timeoutMs}ms`));
+      }, this.timeoutMs);
+      this._pending.set(id, {
+        resolve: (msg) => { clearTimeout(timer); resolve(msg); },
+        reject:  (e)   => { clearTimeout(timer); reject(e); },
+      });
+      this._ws.send(JSON.stringify({
+        type: "send_command",
+        id,
+        sessionId: this.sessionId,
+        command,
+        inputMode,
+      }));
+    });
+  }
+
+  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,184 @@
+/**
+ * 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);
+  }
+
+  /**
+   * 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 };
+  }
+}