@uuaid/pillar 0.2.0-alpha.6

package/src/net/transport.mjs

@@ -0,0 +1,109 @@
+/**
+ * Transport — libp2p node that speaks the UUAID pillar protocol.
+ *
+ * Design:
+ *   - The pillar's Ed25519 identity IS the libp2p PeerId (same private key).
+ *     One identity, one keypair, one signature primitive across every layer.
+ *   - Kad-DHT is used for two things:
+ *       1. Peer routing (find PeerId -> multiaddrs)
+ *       2. Content routing (publish a UUAID -> hash mapping so anyone can
+ *          resolve a UUAID to a live PeerId without a central directory)
+ *   - Custom protocol /uuaid/pillar/1.0.0: framed newline-delimited JSON
+ *     envelopes.  Noise encryption is handled by libp2p; the envelope
+ *     signature is our IAASO-1201 attestation.
+ *
+ * Two roles:
+ *   - Peer   : ordinary agent.  Dials others; listens for direct dials.
+ *   - Relay  : a Peer that ALSO runs circuitRelayServer, letting NATed
+ *              peers use it as a Circuit Relay v2 rendezvous.  Optional
+ *              opt-in — every Peer can be a Relay; not every Peer needs to be.
+ */
+import { createLibp2p } from "libp2p";
+import { tcp } from "@libp2p/tcp";
+import { webSockets } from "@libp2p/websockets";
+import { noise } from "@chainsafe/libp2p-noise";
+import { yamux } from "@chainsafe/libp2p-yamux";
+import { identify, identifyPush } from "@libp2p/identify";
+import { kadDHT, removePrivateAddressesMapper, passthroughMapper } from "@libp2p/kad-dht";
+import { bootstrap } from "@libp2p/bootstrap";
+import { circuitRelayTransport, circuitRelayServer } from "@libp2p/circuit-relay-v2";
+import { dcutr } from "@libp2p/dcutr";
+import { autoNAT } from "@libp2p/autonat";
+import { ping } from "@libp2p/ping";
+import { privateKeyFromRaw, publicKeyFromRaw } from "@libp2p/crypto/keys";
+import { peerIdFromPublicKey } from "@libp2p/peer-id";
+import { createHash } from "node:crypto";
+
+export const PILLAR_PROTOCOL = "/uuaid/pillar/1.0.0";
+export const DHT_PROTOCOL_PREFIX = "/uuaid";
+
+/**
+ * Build a libp2p node bound to the pillar's Ed25519 identity.
+ *
+ * @param {{seedHex: string, listenAddrs?: string[], bootstrapPeers?: string[], enableRelay?: boolean, dhtClientMode?: boolean}} opts
+ */
+export async function createTransport({
+  seedHex,
+  listenAddrs = ["/ip4/0.0.0.0/tcp/0", "/ip4/0.0.0.0/tcp/0/ws"],
+  bootstrapPeers = [],
+  enableRelay = false,
+  dhtClientMode = true,
+  dhtPeerInfoMapper,
+}) {
+  const seed = Buffer.from(seedHex, "hex");
+  if (seed.length !== 32) throw new Error("seedHex must be 32 raw bytes hex");
+  const privateKey = privateKeyFromRaw(seed);
+
+  const services = {
+    identify: identify(),
+    identifyPush: identifyPush(),
+    ping: ping(),
+    dht: kadDHT({
+      protocol: `${DHT_PROTOCOL_PREFIX}/kad/1.0.0`,
+      clientMode: dhtClientMode,
+      // Default filters loopback/RFC1918 addrs; tests and dev fleets override with passthrough.
+      peerInfoMapper: dhtPeerInfoMapper ?? removePrivateAddressesMapper,
+    }),
+    autoNAT: autoNAT(),
+    dcutr: dcutr(),
+  };
+  if (enableRelay) {
+    services.relay = circuitRelayServer({
+      reservations: { maxReservations: 128, defaultDurationLimit: 5 * 60 * 1000 },
+    });
+  }
+
+  const cfg = {
+    privateKey,
+    addresses: { listen: listenAddrs },
+    transports: [tcp(), webSockets(), circuitRelayTransport()],
+    connectionEncrypters: [noise()],
+    streamMuxers: [yamux()],
+    services,
+  };
+  if (bootstrapPeers.length > 0) {
+    cfg.peerDiscovery = [bootstrap({ list: bootstrapPeers })];
+  }
+
+  const node = await createLibp2p(cfg);
+  return node;
+}
+
+/**
+ * Map a UUAID string to the DHT key we advertise under.  The DHT key is
+ * a raw sha256 of the UUAID string — content-addressed, stable, and
+ * doesn't leak PII beyond what the UUAID already does.
+ */
+export function uuaidToDhtKey(uuaid) {
+  return createHash("sha256").update(uuaid, "utf-8").digest();
+}
+
+/**
+ * Convert a raw Ed25519 public key hex to a libp2p PeerId.  This is how
+ * a peer given only a UUAID's public key can dial that peer.
+ */
+export function peerIdFromEd25519Hex(publicKeyHex) {
+  const raw = Buffer.from(publicKeyHex, "hex");
+  const pub = publicKeyFromRaw(raw);
+  return peerIdFromPublicKey(pub);
+}

package/src/pillar.mjs

@@ -0,0 +1,457 @@
+/**
+ * Pillar — top-level orchestrator.
+ *
+ * Wires:
+ *   - Keychain: identity, signing key
+ *   - Mailbox: durable local outbox + inbox with chain-hash audit
+ *   - Transport: libp2p node with DHT + /uuaid/pillar/1.0.0 protocol
+ *
+ * Public surface:
+ *   const pillar = new Pillar({ keychain, mailboxPath, listenAddrs, bootstrapPeers, enableRelay });
+ *   await pillar.start();
+ *   await pillar.publishSelf();                 // advertise our UUAID -> PeerId in the DHT
+ *   pillar.onEnvelope((env) => { ... });        // subscribe to received envelopes
+ *   await pillar.send({ recipient, kind, payload });
+ *   await pillar.stop();
+ */
+import { fromString as u8FromString, toString as u8ToString } from "uint8arrays";
+import { CID } from "multiformats/cid";
+import * as raw from "multiformats/codecs/raw";
+import { sha256 } from "multiformats/hashes/sha2";
+import { createTransport, PILLAR_PROTOCOL, uuaidToDhtKey, peerIdFromEd25519Hex } from "./net/transport.mjs";
+import { seal, open, decrypt, envelopeSha, ENVELOPE_VERSION } from "./net/envelope.mjs";
+import { Mailbox } from "./mailbox/mailbox.mjs";
+import { CarrierClient } from "./net/carrier-client.mjs";
+
+const VALUE_STORE_PREFIX = "/uuaid/1.0";
+
+export class Pillar {
+  constructor({
+    keychain,
+    mailboxPath,
+    listenAddrs,
+    bootstrapPeers,
+    enableRelay,
+    dhtClientMode = true,
+    dhtPeerInfoMapper,
+    carriers = [],
+    enableLibp2p = true,
+    cryptoInventory = { ed25519: "active", "ml-dsa-65": "reserved", "slh-dsa-128s": "reserved" },
+  }) {
+    if (!keychain?._identity) throw new Error("Pillar: keychain must be loaded before construction");
+    this.keychain = keychain;
+    this.mailbox = new Mailbox(mailboxPath);
+    this.listenAddrs = listenAddrs;
+    this.bootstrapPeers = bootstrapPeers;
+    this.enableRelay = enableRelay;
+    this.dhtClientMode = dhtClientMode;
+    this.dhtPeerInfoMapper = dhtPeerInfoMapper;
+    this.carriers = carriers;
+    this.carrierClient = carriers.length ? new CarrierClient({ keychain, carriers }) : null;
+    this._carrierPoller = null;
+    this.enableLibp2p = enableLibp2p;
+    this.cryptoInventory = cryptoInventory;
+    this.node = null;
+    this._envelopeHandlers = new Set();
+    this._openStreams = new Map(); // peerIdString -> pushable
+  }
+
+  get uuaid() { return this.keychain._identity.uuaid; }
+  get publicKeyHex() { return this.keychain._identity.publicKeyHex; }
+
+  async start() {
+    // Carrier-only mode: no listening socket, no libp2p.  This is what runs
+    // in sandboxes / serverless / anywhere that cannot open inbound ports and
+    // doesn't need direct dials.
+    if (!this.enableLibp2p) return this;
+    // Rebuild seed from the loaded keychain identity so libp2p PeerId derives
+    // from the same private key that the keychain uses for envelope signing.
+    const seedDer = this.keychain._identity.privateKey.export({ type: "pkcs8", format: "der" });
+    const seed = seedDer.slice(seedDer.length - 32);
+    this.node = await createTransport({
+      seedHex: Buffer.from(seed).toString("hex"),
+      listenAddrs: this.listenAddrs,
+      bootstrapPeers: this.bootstrapPeers,
+      enableRelay: this.enableRelay,
+      dhtClientMode: this.dhtClientMode,
+      dhtPeerInfoMapper: this.dhtPeerInfoMapper,
+    });
+    await this.node.start();
+    await this.node.handle(PILLAR_PROTOCOL, this._handleStream.bind(this));
+    // Eagerly dial each bootstrap peer so kad-dht's routing table can
+    // populate.  The @libp2p/bootstrap discovery service by itself does not
+    // trigger dials in every libp2p config, so we do it explicitly.
+    if (this.bootstrapPeers && this.bootstrapPeers.length > 0) {
+      const { multiaddr } = await import("@multiformats/multiaddr");
+      await Promise.allSettled(
+        this.bootstrapPeers.map(async (ma) => {
+          try { await this.node.dial(multiaddr(ma)); }
+          catch (e) { /* one bad bootstrap shouldn't kill startup */ }
+        }),
+      );
+    }
+    return this;
+  }
+
+  /**
+   * Wait until the DHT routing table has at least `minPeers` entries.
+   * kad-dht will not answer put/get queries until it has peers in the
+   * routing table (not just the peer store).  In client mode we usually
+   * only need 1 (a bootstrap server).  Callers should await this before
+   * publishSelf() or resolveUuaid() when the mesh has just started.
+   */
+  async awaitDhtReady({ minPeers = 1, timeoutMs = 15000, intervalMs = 200 } = {}) {
+    if (!this.node) throw new Error("pillar not started");
+    const dht = this.node.services.dht;
+    if (!dht) throw new Error("dht service not enabled");
+    const t0 = Date.now();
+    // Trigger a self findPeer against every connected peer.  A successful kad
+    // response causes kad-dht to add that peer to the routing table.  If we
+    // are talking to a server-mode peer, that's all we need.
+    // Doing findPeer(peerId) both (a) populates OUR routing table when the
+    // response comes back and (b) causes the remote server-mode peer to add
+    // US to ITS routing table.  Without this second-order effect, DHT put/get
+    // never propagates because the bootstrap can't route back to the client.
+    const trySeedRoutingTable = async () => {
+      for (const peerId of this.node.getPeers()) {
+        try {
+          for await (const _evt of dht.findPeer(peerId, { signal: AbortSignal.timeout(2000) })) { /* drain */ }
+        } catch (_e) { /* peer may be client-mode, that's ok */ }
+        // Also query for ourselves via this peer — this is the standard
+        // "self-query" that Kademlia uses on join, and it announces us to the
+        // peer's routing table.
+        try {
+          for await (const _evt of dht.getClosestPeers(this.node.peerId.toMultihash().bytes, { signal: AbortSignal.timeout(2000) })) { /* drain */ }
+        } catch (_e) {}
+      }
+    };
+    while (Date.now() - t0 < timeoutMs) {
+      const size = dht.routingTable?.size ?? 0;
+      if (size >= minPeers) return { size, waitedMs: Date.now() - t0 };
+      await trySeedRoutingTable();
+      await new Promise(r => setTimeout(r, intervalMs));
+    }
+    throw new Error(`awaitDhtReady: routing table did not reach ${minPeers} peers within ${timeoutMs}ms`);
+  }
+
+  async stop() {
+    this.stopCarrierPolling();
+    if (!this.node) { this.mailbox.close(); return; }
+    for (const push of this._openStreams.values()) { try { push.end(); } catch (_e) {} }
+    this._openStreams.clear();
+    try { await this.node.stop(); } catch (_e) {}
+    this.node = null;
+    this.mailbox.close();
+  }
+
+  /**
+   * Convert a UUAID string to a stable CID.  We use `raw` codec + sha256(uuaid)
+   * so the CID is content-addressed on the UUAID itself.
+   */
+  async _uuaidCid(uuaid) {
+    const digest = await sha256.digest(u8FromString(uuaid));
+    return CID.createV1(raw.code, digest);
+  }
+
+  /**
+   * Advertise (UUAID -> our PeerId) in the DHT via provider records.
+   *
+   * Uses `contentRouting.provide(cid)`, which stores a provider record
+   * (peerId + multiaddrs) at the closest peers to `cid`.  This is the
+   * BitTorrent-style discovery: peers looking for `cid` learn who has it
+   * and can dial them directly.  Unlike `contentRouting.put/get`, provider
+   * records do not require validator registration.
+   */
+  async publishSelf() {
+    if (!this.node) throw new Error("pillar not started");
+    const cid = await this._uuaidCid(this.uuaid);
+    await this.node.contentRouting.provide(cid);
+    return {
+      uuaid: this.uuaid,
+      peerId: this.node.peerId.toString(),
+      publicKey: this.publicKeyHex,
+      addrs: this.node.getMultiaddrs().map(a => a.toString()),
+      cid: cid.toString(),
+    };
+  }
+
+  /**
+   * Resolve a UUAID -> live peer via DHT provider lookup.
+   *
+   * Iterates `findProviders(cid)` until we find a provider whose PeerId
+   * matches the hash of a public key we can verify.  Verification is done
+   * by dialing the peer, letting Noise/libp2p authenticate the PeerId, then
+   * reading the peer's public key from libp2p's peer store.
+   *
+   * Returns { uuaid, peerId, publicKeyHex, addrs }.
+   * Throws if no provider is found within `timeoutMs`.
+   */
+  async resolveUuaid(uuaid, { timeoutMs = 15000 } = {}) {
+    if (!this.node) throw new Error("pillar not started");
+    const { peerIdFromCID } = await import("@libp2p/peer-id");
+    const cid = await this._uuaidCid(uuaid);
+    const signal = AbortSignal.timeout(timeoutMs);
+    for await (const provider of this.node.contentRouting.findProviders(cid, { signal })) {
+      // Provider record gives us peerId + addrs.  libp2p's PeerId is a hash
+      // of the peer's public key; when we later dial, Noise will authenticate
+      // that the peer actually holds the private key.  So the trust chain is:
+      //   UUAID (sha256(pubkey) local-id)  ==  publicKey the peer proves via Noise.
+      const providerPubKey = provider.id.publicKey;
+      if (!providerPubKey) continue; // shouldn't happen for Ed25519 PeerIds but be safe
+      const publicKeyHex = Buffer.from(providerPubKey.raw).toString("hex");
+      // Recompute the UUAID that this key would mint.
+      const { Keychain } = await import("./identity/keychain.mjs");
+      const localId = Keychain._localIdFromKey(Buffer.from(publicKeyHex, "hex"));
+      const expectedUuaid = `uuaid:foundation:agent:${localId}`;
+      if (expectedUuaid !== uuaid) continue; // provider is squatting on someone else's key
+      // Remember addrs so future dials succeed even if the provider drops off DHT.
+      if (provider.multiaddrs?.length) {
+        try { await this.node.peerStore.patch(provider.id, { multiaddrs: provider.multiaddrs }); } catch (_e) {}
+      }
+      return {
+        uuaid,
+        peerId: provider.id.toString(),
+        publicKeyHex,
+        addrs: (provider.multiaddrs ?? []).map(a => a.toString()),
+      };
+    }
+    throw new Error(`resolveUuaid(${uuaid}): no matching provider found within ${timeoutMs}ms`);
+  }
+
+  onEnvelope(handler) {
+    this._envelopeHandlers.add(handler);
+    return () => this._envelopeHandlers.delete(handler);
+  }
+
+  /**
+   * Send a signed envelope.  Resolution order:
+   *   1. Address book: if `this.addressBook.get(recipient)` returns {peerId, multiaddr},
+   *      dial directly (out-of-band trust; used by the fleet runner).
+   *   2. DHT: resolveUuaid(recipient) via provider records.
+   *
+   * The DHT path is FUNCTIONAL for large public meshes but has known slow
+   * convergence on tiny 3-peer loopback tests in libp2p 3.x kad-dht.  For
+   * fleet deployment we bypass DHT via the address book which is populated
+   * once at fleet-up time.
+   */
+  async send({ recipient, recipientPublicKey, kind = "message", payload = {}, resolveTimeoutMs = 5000 }) {
+    if (!this.node && !this.carrierClient) throw new Error("pillar not started");
+
+    const book = this.addressBook?.get(recipient);
+
+    // E2E: we MUST have the recipient's public key before anything leaves
+    // this process.  Sources, in order: explicit param, address book, DHT
+    // provider record (which carries the pubkey inside the PeerId).
+    let pubkey = recipientPublicKey ?? book?.publicKey;
+    let dhtAdvert = null;
+    if (!pubkey && this.node) {
+      try {
+        dhtAdvert = await this.resolveUuaid(recipient, { timeoutMs: resolveTimeoutMs });
+        pubkey = dhtAdvert.publicKeyHex;
+      } catch (_e) { /* fall through to the error below */ }
+    }
+    if (!pubkey) {
+      throw new Error(`send: no public key known for ${recipient} — encryption is mandatory; register the peer (address book / fleet.json) or pass recipientPublicKey`);
+    }
+
+    const envelope = seal(this.keychain, { recipient, recipientPublicKey: pubkey, kind, payload });
+    const persisted = this.mailbox.appendOutbound(envelope);
+
+    // 1. Address book path: direct libp2p dial (lowest latency, no third party).
+    if (this.node && book?.peerId && book?.multiaddr) {
+      try {
+        return { envelope, persisted, via: "direct", delivery: await this._deliverToPeer(envelope, book.peerId, book.multiaddr) };
+      } catch (e) {
+        if (!this.carrierClient) throw e; // else fall through to carrier
+      }
+    }
+
+    // 2. Carrier path: universal store-and-forward.
+    if (this.carrierClient) {
+      const receipt = await this.carrierClient.deliver(envelope);
+      this.mailbox.markOutboundDelivered(envelope.id, envelopeSha(envelope));
+      return { envelope, persisted, via: "carrier", delivery: receipt };
+    }
+
+    // 3. DHT path.
+    if (!this.node) throw new Error(`send: cannot resolve ${recipient}: no carrier configured and libp2p not started`);
+    if (!dhtAdvert) {
+      try { dhtAdvert = await this.resolveUuaid(recipient, { timeoutMs: resolveTimeoutMs }); }
+      catch (e) { throw new Error(`send: cannot resolve ${recipient}: ${e.message}`); }
+    }
+    return { envelope, persisted, via: "dht", delivery: await this._deliverToPeer(envelope, dhtAdvert.peerId, dhtAdvert.addrs?.[0]) };
+  }
+
+  /**
+   * Group send — fan-out to every member with per-member E2E sealing.
+   *
+   * There is deliberately NO group key: each member gets their own sealed
+   * envelope (same guarantees as 1:1 send), so membership changes never
+   * require rekeying and the carrier still can't read anything.  The group
+   * context travels INSIDE the sealed payload as `_group: { name, members }`
+   * so every recipient can reply to the whole group without extra lookups.
+   *
+   * Failures are isolated: one undeliverable member never blocks the rest.
+   * Returns { group, results: [{ member, ok, via?, envelopeId?, error? }] }.
+   */
+  async sendGroup({ group, members, kind = "message", payload = {}, resolveTimeoutMs = 5000 }) {
+    if (!Array.isArray(members) || members.length === 0) {
+      throw new Error(`sendGroup: group "${group}" has no members`);
+    }
+    const others = members.filter(m => m !== this.uuaid);
+    const wrapped = { _group: { name: group, members }, ...payload };
+    const results = [];
+    for (const member of others) {
+      try {
+        const r = await this.send({ recipient: member, kind, payload: wrapped, resolveTimeoutMs });
+        results.push({ member, ok: true, via: r.via, envelopeId: r.envelope.id });
+      } catch (e) {
+        results.push({ member, ok: false, error: e.message });
+      }
+    }
+    return { group, results };
+  }
+
+  /**
+   * Start pulling our inbox from every configured carrier.  Received envelopes
+   * flow through the same verification + mailbox + handler pipeline as
+   * libp2p-received envelopes.  Cursors persist in the mailbox DB so restarts
+   * do not re-deliver.
+   */
+  startCarrierPolling({ waitS = 25 } = {}) {
+    if (!this.carrierClient) throw new Error("no carriers configured");
+    if (this._carrierPoller) return this._carrierPoller;
+    const cursors = this.mailbox.getCarrierCursors?.() ?? {};
+    this._carrierPoller = this.carrierClient.startPolling({
+      cursors,
+      waitS,
+      onEnvelope: async (envelope, { carrier, seq }) => {
+        await this._receive(JSON.stringify(envelope), null);
+        this.mailbox.setCarrierCursor?.(carrier, seq);
+      },
+      onError: (_e) => { /* transient poll errors are expected; backoff is in client */ },
+    });
+    return this._carrierPoller;
+  }
+
+  stopCarrierPolling() {
+    if (this._carrierPoller) { this._carrierPoller.stop(); this._carrierPoller = null; }
+  }
+
+  async _deliverToPeer(envelope, peerIdStr, multiaddrStr) {
+    const { peerIdFromString } = await import("@libp2p/peer-id");
+    const { multiaddr } = await import("@multiformats/multiaddr");
+    const peerId = peerIdFromString(peerIdStr);
+    if (multiaddrStr) {
+      try { await this.node.peerStore.patch(peerId, { multiaddrs: [multiaddr(multiaddrStr)] }); } catch (_e) {}
+    }
+    const stream = await this.node.dialProtocol(peerId, PILLAR_PROTOCOL);
+    const line = JSON.stringify(envelope) + "\n";
+    stream.send(u8FromString(line));
+    await stream.close();
+    this.mailbox.markOutboundDelivered(envelope.id, envelopeSha(envelope));
+    return { peerId: peerIdStr };
+  }
+
+  /**
+   * In-memory address book: uuaid -> { peerId?, multiaddr?, publicKey }.
+   * publicKey (ed25519 hex) is what makes E2E possible without DHT.
+   * Identity binding (pubkey must derive the UUAID) is enforced in seal().
+   */
+  registerAddress(uuaid, { peerId, multiaddr, publicKey }) {
+    if (!this.addressBook) this.addressBook = new Map();
+    const prev = this.addressBook.get(uuaid) ?? {};
+    this.addressBook.set(uuaid, {
+      peerId: peerId ?? prev.peerId,
+      multiaddr: multiaddr ?? prev.multiaddr,
+      publicKey: publicKey ?? prev.publicKey,
+    });
+  }
+
+  /** Register just a peer's public key (enough for carrier-path E2E sends). */
+  registerKey(uuaid, publicKeyHex) {
+    this.registerAddress(uuaid, { publicKey: publicKeyHex });
+  }
+
+  /**
+   * Direct-dial helper for tests: given a peer's UUAID + its libp2p multiaddr,
+   * we bypass DHT lookup.  Also useful when a caller already has the peer's
+   * connection info out of band.
+   */
+  async sendDirect({ recipient, recipientPublicKey, recipientPeerIdStr, recipientMultiaddr, kind = "message", payload = {} }) {
+    if (!this.node) throw new Error("pillar not started");
+    const pubkey = recipientPublicKey ?? this.addressBook?.get(recipient)?.publicKey;
+    if (!pubkey) throw new Error(`sendDirect: no public key for ${recipient} — encryption is mandatory`);
+    const envelope = seal(this.keychain, { recipient, recipientPublicKey: pubkey, kind, payload });
+    this.mailbox.appendOutbound(envelope);
+    const { peerIdFromString } = await import("@libp2p/peer-id");
+    const { multiaddr } = await import("@multiformats/multiaddr");
+    const peerId = peerIdFromString(recipientPeerIdStr);
+    const ma = multiaddr(recipientMultiaddr);
+    await this.node.peerStore.patch(peerId, { multiaddrs: [ma] });
+    const stream = await this.node.dialProtocol(peerId, PILLAR_PROTOCOL);
+    const line = JSON.stringify(envelope) + "\n";
+    stream.send(u8FromString(line));
+    await stream.close();
+    this.mailbox.markOutboundDelivered(envelope.id, envelopeSha(envelope));
+    return envelope;
+  }
+
+  /**
+   * libp2p stream handler for incoming envelopes.
+   * Wire format: one envelope per stream, JSON + newline.
+   */
+  async _handleStream(stream, connection) {
+    try {
+      let buf = "";
+      for await (const chunk of stream) {
+        const bytes = chunk?.subarray ? chunk.subarray() : chunk;
+        buf += u8ToString(bytes);
+        const newlineIdx = buf.indexOf("\n");
+        if (newlineIdx < 0) continue;
+        const line = buf.slice(0, newlineIdx);
+        buf = buf.slice(newlineIdx + 1);
+        await this._receive(line, connection);
+        break; // one envelope per stream for v0.2
+      }
+    } catch (e) {
+      // eslint-disable-next-line no-console
+      console.error("pillar: stream error", e?.message ?? e);
+    } finally {
+      try { await stream.close(); } catch (_e) {}
+    }
+  }
+
+  async _receive(rawLine, connection) {
+    let envelope;
+    try { envelope = JSON.parse(rawLine); }
+    catch (_e) { return; }
+    const verdict = open(envelope, { cryptoInventory: this.cryptoInventory });
+    if (!verdict.ok) {
+      // eslint-disable-next-line no-console
+      console.warn("pillar: rejected envelope from", connection?.remotePeer?.toString(), verdict.reason);
+      return;
+    }
+    if (envelope.recipient !== this.uuaid) {
+      // Not for us.  Store-and-forward would go here in v0.3.
+      return;
+    }
+    // E2E: decrypt the sealed payload.  Ciphertext-at-rest: the mailbox stores
+    // the envelope as received (encrypted); only the handler view is plaintext.
+    let payload;
+    try {
+      payload = decrypt(this.keychain, envelope);
+    } catch (e) {
+      // eslint-disable-next-line no-console
+      console.warn("pillar: envelope decrypt failed (dropping)", envelope.id, e.message);
+      return;
+    }
+    const persisted = this.mailbox.appendInbound(envelope);
+    if (persisted.duplicate) return; // replay: do not re-fire handlers
+    const view = { ...envelope, payload };
+    for (const h of this._envelopeHandlers) {
+      try { await h(view, persisted); }
+      catch (e) { console.error("pillar: envelope handler threw", e); }
+    }
+  }
+}