@uuaid/pillar 0.2.0-alpha.10

package/src/net/carrier-client.mjs

@@ -0,0 +1,118 @@
+/**
+ * Carrier client — lets a pillar deliver + receive envelopes through one or
+ * more carrier servers using only outbound HTTP(S).
+ *
+ * This is the universal transport: works from sandboxes, NATed laptops,
+ * serverless, anywhere.  No listening socket required.
+ */
+
+export class CarrierClient {
+  /**
+   * @param {{keychain: import('../identity/keychain.mjs').Keychain, carriers: string[]}} opts
+   *   carriers: base URLs, e.g. ["https://pillar.uuaid.org"]
+   */
+  constructor({ keychain, carriers }) {
+    if (!keychain?._identity) throw new Error("CarrierClient needs a loaded keychain");
+    if (!carriers?.length) throw new Error("CarrierClient needs at least one carrier URL");
+    this.keychain = keychain;
+    this.carriers = carriers.map(u => u.replace(/\/+$/, ""));
+    this._stopPolling = false;
+  }
+
+  get uuaid() { return this.keychain._identity.uuaid; }
+  get publicKeyHex() { return this.keychain._identity.publicKeyHex; }
+
+  /**
+   * Deliver an envelope to ALL carriers in parallel — p2p seed replication:
+   * the message lands on every configured seed (like a file seeded on many
+   * peers), so it survives any single carrier dying before the recipient
+   * polls.  Duplicate copies are harmless: the recipient mailbox dedups on
+   * envelope.id and re-fires no handlers.
+   *
+   * Resolves once every carrier has answered.  Succeeds if at least one
+   * accepted; throws if every carrier rejects.  Returns the first-in-list
+   * accepting receipt as the primary ({ carrier, seq, sha, duplicate }) plus
+   * `all` with every carrier's outcome ({ carrier, ok, seq?, sha?,
+   * duplicate?, error? }).
+   */
+  async deliver(envelope, { timeoutMs = 10000 } = {}) {
+    const attempt = async (base) => {
+      try {
+        const res = await fetch(`${base}/v1/envelopes`, {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify(envelope),
+          signal: AbortSignal.timeout(timeoutMs),
+        });
+        const body = await res.json();
+        if (res.status === 202 && body.accepted) {
+          return { carrier: base, ok: true, seq: body.seq, sha: body.sha, duplicate: !!body.duplicate };
+        }
+        return { carrier: base, ok: false, error: `${res.status} ${body.reason ?? body.error ?? ""}` };
+      } catch (e) {
+        return { carrier: base, ok: false, error: e.message };
+      }
+    };
+    const all = await Promise.allSettled(this.carriers.map(attempt)).then(rs =>
+      rs.map(r => r.status === "fulfilled" ? r.value : { carrier: "?", ok: false, error: String(r.reason) }));
+    const accepted = all.filter(r => r.ok);
+    if (!accepted.length) {
+      throw new Error(`carrier deliver failed on all carriers: ${all.map(r => `${r.carrier}: ${r.error}`).join("; ")}`);
+    }
+    const { carrier, seq, sha, duplicate } = accepted[0];
+    return { carrier, seq, sha, duplicate, all };
+  }
+
+  /**
+   * Fetch envelopes addressed to us with seq > since from a specific carrier.
+   * Signed request; carrier verifies our key before serving.
+   */
+  async fetchInbox(base, { since = 0, waitS = 0, timeoutMs = 40000 } = {}) {
+    const path = `GET /v1/inbox/${this.uuaid}?since=${since}`;
+    const ts = String(Date.now());
+    const sig = this.keychain.sign(Buffer.from(`${path}\n${ts}`, "utf-8")).toString("hex");
+    const res = await fetch(`${base}/v1/inbox/${encodeURIComponent(this.uuaid)}?since=${since}&wait=${waitS}`, {
+      headers: {
+        "x-pillar-pubkey": this.publicKeyHex,
+        "x-pillar-ts": ts,
+        "x-pillar-sig": sig,
+      },
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (res.status !== 200) {
+      const body = await res.json().catch(() => ({}));
+      throw new Error(`inbox fetch ${base}: ${res.status} ${body.error ?? ""}`);
+    }
+    return res.json(); // { envelopes: [{seq, envelope}], now }
+  }
+
+  /**
+   * Long-poll every carrier in parallel forever, invoking onEnvelope for each
+   * new envelope.  Tracks per-carrier cursor.  Returns a stop() function.
+   */
+  startPolling({ onEnvelope, cursors = {}, waitS = 25, onError }) {
+    this._stopPolling = false;
+    const state = { cursors: { ...cursors } };
+    const loops = this.carriers.map(async (base) => {
+      while (!this._stopPolling) {
+        try {
+          const r = await this.fetchInbox(base, { since: state.cursors[base] ?? 0, waitS });
+          for (const { seq, envelope } of r.envelopes) {
+            state.cursors[base] = Math.max(state.cursors[base] ?? 0, seq);
+            try { await onEnvelope(envelope, { carrier: base, seq }); }
+            catch (e) { onError?.(new Error(`onEnvelope threw: ${e.message}`)); }
+          }
+        } catch (e) {
+          onError?.(e);
+          // Back off on error so a dead carrier doesn't spin the CPU.
+          await new Promise(r2 => setTimeout(r2, 2000));
+        }
+      }
+    });
+    return {
+      stop: () => { this._stopPolling = true; },
+      cursors: () => ({ ...state.cursors }),
+      done: Promise.allSettled(loops),
+    };
+  }
+}

package/src/net/carrier-server.mjs

@@ -0,0 +1,301 @@
+/**
+ * Carrier server — the universal store-and-forward relay.
+ *
+ * An always-on node (e.g. a DO droplet) that lets ANY two agents exchange
+ * signed envelopes even when NEITHER can accept an inbound connection.
+ * The only capability a participant needs is outbound HTTPS.
+ *
+ * Protocol (/carrier/v1):
+ *
+ *   POST /v1/envelopes
+ *     body: envelope JSON (sealed by sender's pillar)
+ *     - carrier verifies the transport signature before accepting (fail closed)
+ *     - idempotent on envelope.id
+ *     -> 202 { accepted: true, seq, sha }
+ *
+ *   GET /v1/inbox/<uuaid>?since=<seq>&wait=<seconds>
+ *     headers:
+ *       x-pillar-pubkey: <ed25519 pubkey hex>
+ *       x-pillar-ts:     <unix ms>  (rejected if clock skew > 5 min)
+ *       x-pillar-sig:    hex(sign("GET /v1/inbox/<uuaid>?since=<seq>" + "\n" + ts))
+ *     - carrier derives UUAID from pubkey; must equal <uuaid>  (self-authenticating,
+ *       zero registration)
+ *     - long-polls up to `wait` seconds (max 30)
+ *     -> 200 { envelopes: [{seq, envelope}], now }
+ *
+ *   GET /v1/health
+ *     -> 200 { ok, uptime, stored }
+ *
+ * Durability: SQLite (WAL).  Envelopes are retained until TTL (default 14 days).
+ * The carrier CANNOT read payloads it relays beyond what the envelope exposes,
+ * and CANNOT forge envelopes (no keys).  It can only: deliver, delay, or drop —
+ * and drops are detectable by sequence gaps + sender outbox audit.
+ */
+import { createServer } from "node:http";
+import { createHash } from "node:crypto";
+import Database from "better-sqlite3";
+import { open as openEnvelope } from "./envelope.mjs";
+import { Keychain } from "../identity/keychain.mjs";
+
+const MAX_WAIT_S = 30;
+const MAX_BODY = 512 * 1024; // 512 KiB per envelope
+const MAX_SKEW_MS = 5 * 60 * 1000;
+// Hardening (RedTeam F2/F3):
+const MAX_ENVELOPE_AGE_MS = 24 * 3600_000; // F3: ingest freshness — reject skewed createdAt
+const RATE_WINDOW_MS = 60_000;             // F2: sliding window for all rate limits
+const MAX_ENVELOPES_PER_MIN = 120;         // F2: per claimed-sender ingest budget
+const MAX_GOOD_PER_MIN = 300;              // F2: per client-IP budget for accepted sends
+const MAX_INVALID_PER_MIN = 60;            // F2: per client-IP budget for rejected sends
+const MAX_CONCURRENT_WAITS = 64;           // F2: inbox long-poll concurrency cap
+const MAX_DB_BYTES = 256 * 1024 * 1024;    // F2: SQLite size backpressure (503 when full)
+const RATE_MAP_HARD_CAP = 10_000;          // F2: bound memory under key spray
+
+export class CarrierServer {
+  constructor({ dbPath = "carrier.db", ttlDays = 14, cryptoInventory } = {}) {
+    this.db = new Database(dbPath);
+    this.db.pragma("journal_mode = WAL");
+    this.db.exec(`
+      create table if not exists envelopes (
+        seq         integer primary key autoincrement,
+        envelope_id text not null unique,
+        recipient   text not null,
+        sender      text not null,
+        sha         text not null,
+        body        text not null,
+        created_at  text not null default (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
+      );
+      create index if not exists idx_envelopes_recipient on envelopes(recipient, seq);
+    `);
+    this.ttlDays = ttlDays;
+    this.cryptoInventory = cryptoInventory ?? { ed25519: "active" };
+    this.startedAt = Date.now();
+    this.server = null;
+    this.rateMap = new Map(); // F2: "<kind>:<key>" -> [ms timestamps]
+    this.activeWaits = 0;     // F2: long-polls currently sleeping
+    this._closed = false;
+  }
+
+  /** F2: best-effort client identity, nginx-aware (XFF set by proxy). */
+  _clientIp(req) {
+    const fwd = req.headers["x-forwarded-for"];
+    if (fwd) return String(fwd).split(",")[0].trim();
+    return req.socket.remoteAddress ?? "unknown";
+  }
+
+  /** F2: sliding-window allow. Returns false when over budget. */
+  _rateAllow(key, limit) {
+    const now = Date.now();
+    let arr = this.rateMap.get(key);
+    if (!arr) {
+      if (this.rateMap.size >= RATE_MAP_HARD_CAP) {
+        for (const [k, v] of this.rateMap) {
+          while (v.length && v[0] < now - RATE_WINDOW_MS) v.shift();
+          if (v.length === 0) this.rateMap.delete(k);
+        }
+        if (this.rateMap.size >= RATE_MAP_HARD_CAP) {
+          this.rateMap.delete(this.rateMap.keys().next().value); // shed oldest
+        }
+      }
+      arr = [];
+      this.rateMap.set(key, arr);
+    }
+    const cutoff = now - RATE_WINDOW_MS;
+    while (arr.length && arr[0] < cutoff) arr.shift();
+    if (arr.length >= limit) return false;
+    arr.push(now);
+    return true;
+  }
+
+  /** Remove envelopes older than TTL.  Call periodically. */
+  vacuum() {
+    const cutoff = new Date(Date.now() - this.ttlDays * 86400_000).toISOString();
+    const r = this.db.prepare("delete from envelopes where created_at < ?").run(cutoff);
+    return r.changes;
+  }
+
+  _json(res, code, obj) {
+    // No-op on a dead socket: close() destroys connections, and a long-poll
+    // handler whose timer fires afterwards must not throw on write.
+    if (res.destroyed || res.writableEnded) return;
+    const body = JSON.stringify(obj);
+    res.writeHead(code, { "content-type": "application/json", "content-length": Buffer.byteLength(body) });
+    res.end(body);
+  }
+
+  async _readBody(req) {
+    return new Promise((resolve, reject) => {
+      let size = 0; const chunks = [];
+      req.on("data", (c) => {
+        size += c.length;
+        if (size > MAX_BODY) { reject(new Error("body too large")); req.destroy(); return; }
+        chunks.push(c);
+      });
+      req.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
+      req.on("error", reject);
+    });
+  }
+
+  _handlePost(envelope, ip = "unknown") {
+    const verdict = openEnvelope(envelope, { cryptoInventory: this.cryptoInventory });
+    if (!verdict.ok) {
+      // F2: cap rejected sends per client (flood the verifier → 429).
+      if (!this._rateAllow(`bad:${ip}`, MAX_INVALID_PER_MIN)) {
+        return { code: 429, body: { accepted: false, reason: "rate-limited" } };
+      }
+      return { code: 400, body: { accepted: false, reason: verdict.reason } };
+    }
+    if (typeof envelope.recipient !== "string" || !envelope.recipient.startsWith("uuaid:")) {
+      return { code: 400, body: { accepted: false, reason: "bad-recipient" } };
+    }
+    // F2: per-sender ingest budget — a sender uuaid cannot flood its carrier.
+    if (!this._rateAllow(`s:${envelope.sender}`, MAX_ENVELOPES_PER_MIN)) {
+      return { code: 429, body: { accepted: false, reason: "rate-limited" } };
+    }
+    // F2: per-client budget on ACCEPTED sends — closes the unlimited
+    // fresh-keypair spray (each new key gets a fresh sender budget).
+    if (!this._rateAllow(`g:${ip}`, MAX_GOOD_PER_MIN)) {
+      return { code: 429, body: { accepted: false, reason: "rate-limited" } };
+    }
+    // F3: freshness — reject envelopes whose createdAt is missing or skewed
+    // > MAX_ENVELOPE_AGE_MS (covers both stale replay and future-dated).
+    const createdMs = Date.parse(envelope.createdAt);
+    if (!Number.isFinite(createdMs) || Math.abs(Date.now() - createdMs) > MAX_ENVELOPE_AGE_MS) {
+      return { code: 400, body: { accepted: false, reason: "stale-envelope" } };
+    }
+    // F2: backpressure — refuse ingest when the store is near-full instead of
+    // failing at disk-full mid-write.
+    const pages = this.db.pragma("page_count", { simple: true });
+    const pageBytes = this.db.pragma("page_size", { simple: true });
+    if (pages * pageBytes > MAX_DB_BYTES) {
+      return { code: 503, body: { accepted: false, reason: "carrier-full" } };
+    }
+    const sha = createHash("sha256").update(JSON.stringify(envelope)).digest("hex");
+    try {
+      const r = this.db.prepare(
+        "insert into envelopes (envelope_id, recipient, sender, sha, body) values (?,?,?,?,?)"
+      ).run(envelope.id, envelope.recipient, envelope.sender, sha, JSON.stringify(envelope));
+      return { code: 202, body: { accepted: true, seq: Number(r.lastInsertRowid), sha } };
+    } catch (e) {
+      if (/UNIQUE constraint/.test(e.message)) {
+        const row = this.db.prepare("select seq, sha from envelopes where envelope_id = ?").get(envelope.id);
+        return { code: 202, body: { accepted: true, duplicate: true, seq: row.seq, sha: row.sha } };
+      }
+      throw e;
+    }
+  }
+
+  _verifyInboxAuth(req, uuaid, sincePath) {
+    const pubkey = req.headers["x-pillar-pubkey"];
+    const ts = req.headers["x-pillar-ts"];
+    const sig = req.headers["x-pillar-sig"];
+    if (!pubkey || !ts || !sig) return { ok: false, reason: "missing-auth-headers" };
+    if (!/^[0-9a-f]{64}$/i.test(pubkey)) return { ok: false, reason: "bad-pubkey" };
+    if (!/^[0-9a-f]{128}$/i.test(sig)) return { ok: false, reason: "bad-sig-encoding" };
+    const tsNum = Number(ts);
+    if (!Number.isFinite(tsNum) || Math.abs(Date.now() - tsNum) > MAX_SKEW_MS) {
+      return { ok: false, reason: "clock-skew" };
+    }
+    // Self-authenticating: UUAID must derive from the presented pubkey.
+    const localId = Keychain._localIdFromKey(Buffer.from(pubkey, "hex"));
+    const derived = `uuaid:foundation:agent:${localId}`;
+    if (derived !== uuaid) return { ok: false, reason: "uuaid-pubkey-mismatch" };
+    const message = Buffer.from(`${sincePath}\n${ts}`, "utf-8");
+    let verified = false;
+    try { verified = Keychain.verifyDetached(pubkey, message, Buffer.from(sig, "hex")); }
+    catch (_e) { return { ok: false, reason: "verify-threw" }; }
+    if (!verified) return { ok: false, reason: "bad-signature" };
+    return { ok: true };
+  }
+
+  async _handleInbox(req, res, uuaid, url) {
+    const since = Number(url.searchParams.get("since") ?? 0);
+    const wait = Math.min(Number(url.searchParams.get("wait") ?? 0), MAX_WAIT_S);
+    const sincePath = `GET /v1/inbox/${uuaid}?since=${since}`;
+    const auth = this._verifyInboxAuth(req, uuaid, sincePath);
+    if (!auth.ok) return this._json(res, 401, { error: auth.reason });
+
+    // F2: cap concurrent long-polls so sleeping connections cannot pin the
+    // event loop / fd table.
+    if (wait > 0 && this.activeWaits >= MAX_CONCURRENT_WAITS) {
+      return this._json(res, 503, { error: "busy" });
+    }
+    if (wait > 0) this.activeWaits++;
+
+    const fetchRows = () => {
+      // closed → the DB is gone; a long-poll timer armed before close() can
+      // fire afterwards. Never touch a closed connection.
+      if (this._closed) return [];
+      return this.db.prepare(
+        "select seq, body from envelopes where recipient = ? and seq > ? order by seq asc limit 200"
+      ).all(uuaid, since);
+    };
+
+    try {
+      let rows = fetchRows();
+      const deadline = Date.now() + wait * 1000;
+      while (rows.length === 0 && Date.now() < deadline && !this._closed) {
+        await new Promise(r => setTimeout(r, 400));
+        rows = fetchRows();
+      }
+      this._json(res, 200, {
+        envelopes: rows.map(r => ({ seq: r.seq, envelope: JSON.parse(r.body) })),
+        now: Date.now(),
+      });
+    } finally {
+      if (wait > 0) this.activeWaits--;
+    }
+  }
+
+  listen(port = 0, host = "127.0.0.1") {
+    this.server = createServer(async (req, res) => {
+      try {
+        const url = new URL(req.url, `http://${req.headers.host ?? "localhost"}`);
+        if (req.method === "POST" && url.pathname === "/v1/envelopes") {
+          const raw = await this._readBody(req);
+          let envelope;
+          try { envelope = JSON.parse(raw); }
+          catch { return this._json(res, 400, { accepted: false, reason: "bad-json" }); }
+          const { code, body } = this._handlePost(envelope, this._clientIp(req));
+          return this._json(res, code, body);
+        }
+        const inboxMatch = /^\/v1\/inbox\/([^/]+)$/.exec(url.pathname);
+        if (req.method === "GET" && inboxMatch) {
+          const uuaid = decodeURIComponent(inboxMatch[1]);
+          if (!uuaid.startsWith("uuaid:")) return this._json(res, 404, { error: "not-found" });
+          return await this._handleInbox(req, res, uuaid, url);
+        }
+        if (req.method === "GET" && url.pathname === "/v1/health") {
+          const stored = this.db.prepare("select count(*) as n from envelopes").get().n;
+          return this._json(res, 200, { ok: true, uptimeMs: Date.now() - this.startedAt, stored });
+        }
+        this._json(res, 404, { error: "not-found" });
+      } catch (e) {
+        // F4: never leak internal error details (paths, stack, SQL text).
+        console.error(`[carrier] 500: ${e.message}`);
+        this._json(res, 500, { error: "internal-error" });
+      }
+    });
+    return new Promise((resolve) => {
+      this.server.listen(port, host, () => resolve(this.server.address()));
+    });
+  }
+
+  async close() {
+    this._closed = true;
+    if (this.server) {
+      // close() must not wait for in-flight connections: a client long-polling
+      // this carrier re-issues requests on its keep-alive socket, so
+      // http.Server.close() would never resolve. Stop accepting first, then
+      // destroy every socket (Node >= 18.2; no-op below, covered by the race).
+      const closed = new Promise(r => this.server.close(r));
+      this.server.closeIdleConnections?.();
+      this.server.closeAllConnections?.();
+      // Belt-and-braces: never let a shutdown path hang on a pinned socket.
+      const deadline = new Promise(r => { const t = setTimeout(r, 3000); t.unref?.(); });
+      await Promise.race([closed, deadline]);
+    }
+    // Idempotent: the second close in test teardown (and any double-shutdown
+    // path) must be a no-op, not a throw.
+    if (this.db.open) this.db.close();
+  }
+}

package/src/net/envelope.mjs

@@ -0,0 +1,175 @@
+/**
+ * Envelope v2 — the wire format for pillar-to-pillar messages.
+ *
+ * ENCRYPTION IS FUNDAMENTAL.  There is no plaintext payload mode.  Every
+ * envelope's payload is sealed to the recipient's key before the envelope
+ * is signed.  Anyone can VERIFY an envelope (transport signature is public);
+ * only the recipient can READ it.
+ *
+ * Envelope v2 = {
+ *   version:   "uuaid-pillar-envelope/2",
+ *   id:        "env-...",
+ *   sender:    "uuaid:...",
+ *   recipient: "uuaid:...",
+ *   kind:      "message" | "work-order" | ...   (routing hint, NOT secret)
+ *   createdAt: ISO 8601,
+ *   enc: { alg: "x25519-hkdf-sha256-aes256gcm", epk, iv, ct },   // sealed payload
+ *   transportSignature: { alg: "ed25519", keyId, publicKey, signature, created },
+ * }
+ *
+ * The transport signature covers everything (including the ciphertext), so
+ * tamper detection works WITHOUT decrypting — carriers verify-then-store.
+ * The GCM AAD binds the ciphertext to the envelope id, so a valid ciphertext
+ * cannot be transplanted into a different envelope even by the sender.
+ *
+ * seal() enforces identity binding: recipient UUAID local-id must equal
+ * sha256(recipientPublicKey) — you cannot encrypt to a key that doesn't own
+ * the UUAID you're addressing.
+ */
+import { createHash, randomBytes } from "node:crypto";
+import { jcs } from "../identity/jcs.mjs";
+import { Keychain } from "../identity/keychain.mjs";
+import { sealPayload, openPayload, E2E_ALG } from "../crypto/e2e.mjs";
+
+export const ENVELOPE_VERSION = "uuaid-pillar-envelope/2";
+export { E2E_ALG };
+
+/**
+ * Build, encrypt, and sign an envelope.
+ *
+ * keychain: a loaded Keychain (has .sign()).
+ * body: {
+ *   recipient:           "uuaid:..."          REQUIRED
+ *   recipientPublicKey:  ed25519 pubkey hex   REQUIRED (E2E is not optional)
+ *   kind, payload, id, createdAt              optional
+ * }
+ */
+export function seal(keychain, body) {
+  const identity = keychain._identity;
+  if (!identity) throw new Error("keychain not loaded");
+  const sender = body.sender ?? identity.uuaid;
+  if (sender !== identity.uuaid) {
+    throw new Error(`envelope.sender ${sender} does not match keychain identity ${identity.uuaid}`);
+  }
+  if (!body.recipient || typeof body.recipient !== "string") {
+    throw new Error("seal: recipient required");
+  }
+  if (!body.recipientPublicKey || !/^[0-9a-f]{64}$/i.test(body.recipientPublicKey)) {
+    throw new Error("seal: recipientPublicKey (ed25519 hex) is REQUIRED — encryption is not optional");
+  }
+  // Identity binding: the key must own the UUAID.
+  const expectedLocalId = Keychain._localIdFromKey(Buffer.from(body.recipientPublicKey, "hex"));
+  const recipientLocalId = body.recipient.split(":")[3];
+  if (recipientLocalId !== expectedLocalId) {
+    throw new Error(`seal: recipientPublicKey does not derive recipient UUAID (key owns ...${expectedLocalId.slice(0, 13)}, envelope addressed to ...${String(recipientLocalId).slice(0, 13)})`);
+  }
+
+  const id = body.id ?? mkEnvelopeId();
+  const enc = sealPayload(body.recipientPublicKey, body.payload ?? {}, { aad: id });
+
+  const envelope = {
+    version: ENVELOPE_VERSION,
+    id,
+    sender,
+    recipient: body.recipient,
+    kind: body.kind ?? "message",
+    enc,
+    createdAt: body.createdAt ?? new Date().toISOString(),
+  };
+  const canonical = jcs(envelope);
+  const sigBytes = keychain.sign(Buffer.from(canonical, "utf-8"));
+  envelope.transportSignature = {
+    alg: "ed25519",
+    keyId: identity.uuaid,
+    publicKey: identity.publicKeyHex,
+    signature: sigBytes.toString("hex"),
+    created: envelope.createdAt,
+  };
+  return envelope;
+}
+
+/**
+ * Verify an envelope's transport signature and structure.  Does NOT decrypt.
+ * Anyone (carriers, relays, auditors) can call this.
+ * Returns { ok: true } or { ok: false, reason }.
+ */
+export function open(envelope, { cryptoInventory } = {}) {
+  if (!envelope || typeof envelope !== "object" || Array.isArray(envelope)) return { ok: false, reason: "not-object" };
+  if (envelope.version !== ENVELOPE_VERSION) return { ok: false, reason: `bad-version ${envelope.version}` };
+  const sig = envelope.transportSignature;
+  if (!sig || typeof sig !== "object" || sig.alg !== "ed25519") return { ok: false, reason: "missing-or-bad-alg" };
+  if (cryptoInventory && cryptoInventory[sig.alg] !== "active") {
+    return { ok: false, reason: `alg-not-active:${sig.alg}` };
+  }
+  if (sig.keyId !== envelope.sender) return { ok: false, reason: "keyId-sender-mismatch" };
+  if (typeof sig.publicKey !== "string" || !/^[0-9a-f]{64}$/i.test(sig.publicKey)) return { ok: false, reason: "bad-publicKey" };
+  if (typeof sig.signature !== "string" || !/^[0-9a-f]{128}$/i.test(sig.signature)) return { ok: false, reason: "bad-signature-encoding" };
+  // Structural checks on the encryption block — an envelope without one is invalid.
+  const enc = envelope.enc;
+  if (!enc || typeof enc !== "object") return { ok: false, reason: "missing-enc" };
+  if (enc.alg !== E2E_ALG) return { ok: false, reason: `enc-alg-not-supported:${enc.alg}` };
+  if (cryptoInventory && cryptoInventory[enc.alg] && cryptoInventory[enc.alg] !== "active") {
+    return { ok: false, reason: `enc-alg-not-active:${enc.alg}` };
+  }
+  if (typeof enc.epk !== "string" || !/^[0-9a-f]{64}$/i.test(enc.epk)) return { ok: false, reason: "bad-epk" };
+  if (typeof enc.iv !== "string" || !/^[0-9a-f]{24}$/i.test(enc.iv)) return { ok: false, reason: "bad-iv" };
+  if (typeof enc.ct !== "string" || !/^[0-9a-f]{32,}$/i.test(enc.ct)) return { ok: false, reason: "bad-ct" };
+  // Verify the signature over the envelope WITHOUT the signature block.
+  const { transportSignature: _sig, ...withoutSig } = envelope;
+  let canonical;
+  try { canonical = jcs(withoutSig); } catch (_e) { return { ok: false, reason: "bad-canonical" }; }
+  let okSig;
+  try {
+    okSig = Keychain.verifyDetached(sig.publicKey, Buffer.from(canonical, "utf-8"), Buffer.from(sig.signature, "hex"));
+  } catch (_e) {
+    return { ok: false, reason: "verify-threw" };
+  }
+  if (!okSig) return { ok: false, reason: "bad-signature" };
+  // Sender binding (self-authenticating identity): the sender UUAID's
+  // local-id MUST derive from the signing key — the sender-side mirror of
+  // seal()'s recipient binding.  Without this, anyone can sign an envelope
+  // with their own key while claiming another agent's sender UUAID.
+  const expectedSenderLocalId = Keychain._localIdFromKey(Buffer.from(sig.publicKey, "hex"));
+  if (expectedSenderLocalId !== String(envelope.sender).split(":")[3]) {
+    return { ok: false, reason: "publicKey-sender-mismatch" };
+  }
+  return { ok: true };
+}
+
+/**
+ * Decrypt an envelope's payload.  Only the recipient can do this.
+ * keychain must be the recipient's loaded keychain.
+ * Throws on wrong recipient, wrong key, tamper, or AAD mismatch.
+ */
+export function decrypt(keychain, envelope) {
+  const identity = keychain._identity;
+  if (!identity) throw new Error("decrypt: keychain not loaded");
+  if (envelope.recipient !== identity.uuaid) {
+    throw new Error(`decrypt: envelope addressed to ${envelope.recipient}, not us (${identity.uuaid})`);
+  }
+  const seed = keychainSeed(keychain);
+  return openPayload(seed, envelope.enc, { aad: envelope.id });
+}
+
+/** Extract the 32-byte Ed25519 seed from a loaded keychain. */
+export function keychainSeed(keychain) {
+  const der = keychain._identity.privateKey.export({ type: "pkcs8", format: "der" });
+  return Buffer.from(der.subarray(der.length - 32));
+}
+
+/**
+ * Envelope id: 16 random bytes hex + a small timestamp prefix for
+ * human-readable sort.  Not sensitive; not secret.  Used as GCM AAD.
+ */
+export function mkEnvelopeId() {
+  const now = Date.now().toString(36);
+  const rnd = randomBytes(8).toString("hex");
+  return `env-${now}-${rnd}`;
+}
+
+/**
+ * Content-hash of an envelope, computable by anyone.
+ */
+export function envelopeSha(envelope) {
+  return createHash("sha256").update(jcs(envelope)).digest("hex");
+}