@uuaid/pillar 0.2.0-alpha.8 → 2.0.1

package/src/observability.mjs

@@ -0,0 +1,141 @@
+/**
+ * Observability — metrics/analytics for the Pillar communication system.
+ *
+ * Zero-dependency, in-memory counters / gauges / histograms with an optional
+ * append-only JSONL sink (same pattern as the escrow journal).  Every Pillar
+ * and EscrowService owns one instance; when none is passed in, a default is
+ * created internally so instrumentation sites never null-check.
+ *
+ *   inc("sent.via.carrier")            counters — labels compose into dotted
+ *                                      keys at the CALL SITE, e.g.
+ *                                      `inc(\`received.kind.${kind}\`)`
+ *   setGauge("escrow.offers.open", 3)  gauges — last write wins
+ *   observe("send.latencyMs", ms)      histograms — fixed latency buckets
+ *
+ * Sink: journal({event, ...}) appends an event line; flush() appends a full
+ * state snapshot.  An external analytics pipeline can tail the file without
+ * a live process.  summary() renders the one-glance human view.
+ *
+ * Keys are sanitized (lowercased, non-alphanumerics folded to "-") so
+ * attacker-influenced strings (envelope kinds, error reasons) can never
+ * fabricate keys or escape the dotted namespace.
+ */
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+
+// Fixed latency buckets (ms) — covers fast local sends (<10 ms) up to slow
+// carrier round-trips (>10 s).  Values above the top bucket still count into
+// n/sum/max; percentiles interpolate within the top bucket's upper bound.
+export const LATENCY_BUCKETS = [10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10000];
+
+const MAX_KEY = 64;
+
+export function slugKey(key) {
+  return String(key)
+    .toLowerCase()
+    .replace(/[^a-z0-9.-]+/g, "-")
+    .replace(/^-+|-+$/g, "") // a trailing "!!!" run must not leave a dangling dash
+    .slice(0, MAX_KEY);
+}
+
+function newHistogram() {
+  return { n: 0, sum: 0, min: Infinity, max: -Infinity, buckets: new Array(LATENCY_BUCKETS.length).fill(0) };
+}
+
+function percentile(h, p) {
+  if (h.n === 0) return 0;
+  const target = h.n * p;
+  let acc = 0;
+  let lower = 0;
+  for (let i = 0; i < LATENCY_BUCKETS.length; i++) {
+    acc += h.buckets[i];
+    if (acc >= target) {
+      const upper = LATENCY_BUCKETS[i];
+      const inBucket = h.buckets[i];
+      const frac = inBucket === 0 ? 0 : (target - (acc - inBucket)) / inBucket;
+      return Math.round(lower + frac * (upper - lower));
+    }
+    lower = LATENCY_BUCKETS[i];
+  }
+  return h.max;
+}
+
+export class Observability {
+  constructor({ sinkPath = null } = {}) {
+    this.sinkPath = sinkPath;
+    this.counters = new Map();
+    this.gauges = new Map();
+    this.histograms = new Map();
+    this.startedAt = new Date().toISOString();
+  }
+
+  /* ------------------------------------------------ write paths -------- */
+
+  inc(key, n = 1) {
+    const k = slugKey(key);
+    this.counters.set(k, (this.counters.get(k) ?? 0) + n);
+    return this.counters.get(k);
+  }
+
+  setGauge(key, value) {
+    this.gauges.set(slugKey(key), value);
+  }
+
+  observe(key, ms) {
+    const k = slugKey(key);
+    let h = this.histograms.get(k);
+    if (!h) { h = newHistogram(); this.histograms.set(k, h); }
+    const v = Number(ms);
+    if (!Number.isFinite(v)) return;
+    h.n += 1;
+    h.sum += v;
+    if (v < h.min) h.min = v;
+    if (v > h.max) h.max = v;
+    const idx = LATENCY_BUCKETS.findIndex((b) => v <= b);
+    h.buckets[idx < 0 ? LATENCY_BUCKETS.length - 1 : idx] += 1;
+  }
+
+  /** Append an event line to the sink (no-op without a sinkPath). */
+  journal({ event, ...fields }) {
+    if (!this.sinkPath) return;
+    mkdirSync(dirname(this.sinkPath), { recursive: true });
+    appendFileSync(this.sinkPath, JSON.stringify({ at: new Date().toISOString(), event, ...fields }) + "\n");
+  }
+
+  /** Append a full state snapshot line to the sink (no-op without a sinkPath). */
+  flush() {
+    if (!this.sinkPath) return;
+    mkdirSync(dirname(this.sinkPath), { recursive: true });
+    appendFileSync(this.sinkPath, JSON.stringify({ type: "snapshot", ...this.snapshot() }) + "\n");
+  }
+
+  /* ------------------------------------------------ read paths --------- */
+
+  snapshot() {
+    const histograms = {};
+    for (const [k, h] of this.histograms) {
+      histograms[k] = { n: h.n, sum: h.sum, min: h.min, max: h.max, p50: percentile(h, 0.5), p95: percentile(h, 0.95) };
+    }
+    return {
+      at: new Date().toISOString(),
+      startedAt: this.startedAt,
+      counters: Object.fromEntries(this.counters),
+      gauges: Object.fromEntries(this.gauges),
+      histograms,
+    };
+  }
+
+  /** One-glance human view for CLI / dashboards. */
+  summary() {
+    const s = this.snapshot();
+    const lines = [
+      `pillar metrics (since ${s.startedAt}) — ${this.counters.size} counters, ${this.gauges.size} gauges, ${this.histograms.size} histograms`,
+    ];
+    for (const [k, v] of Object.entries(s.counters).sort()) lines.push(`  ${k.padEnd(48)} ${v}`);
+    for (const [k, v] of Object.entries(s.gauges).sort()) lines.push(`  ${k.padEnd(48)} = ${v}`);
+    for (const [k, h] of Object.entries(s.histograms).sort()) {
+      lines.push(`  ${k.padEnd(48)} n=${h.n} min=${h.min}ms p50=${h.p50}ms p95=${h.p95}ms max=${h.max}ms`);
+    }
+    return lines.join("\n");
+  }
+}

package/src/pillar.mjs

@@ -19,9 +19,14 @@ 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 { seal, open, decrypt, envelopeSha, mkEnvelopeId, ENVELOPE_VERSION } from "./net/envelope.mjs";
 import { Mailbox } from "./mailbox/mailbox.mjs";
 import { CarrierClient } from "./net/carrier-client.mjs";
+import { Observability } from "./observability.mjs";
+import {
+  BLOB_KIND, MAX_INLINE_BODY_BYTES, BlobError, BlobSizeError, envelopeBodyBytes, preflightBodyBytes,
+  prepareBlobSend, fetchAndDecryptBlob, prepareBrokerBlobSend, fetchBrokerBlob,
+} from "./blob/blob.mjs";
 
 const VALUE_STORE_PREFIX = "/uuaid/1.0";
 
@@ -37,6 +42,13 @@ export class Pillar {
     carriers = [],
     enableLibp2p = true,
     cryptoInventory = { ed25519: "active", "ml-dsa-65": "reserved", "slh-dsa-128s": "reserved" },
+    trust = null, // { policy, allow, block } from loadTrustPolicy(); null = open
+    tierGrant = null, // signed grant object (tier.mjs) sent with carrier delivers
+    metrics = null, // Observability instance; a default is created internally
+    blobStore = null, // BlobStore (src/blob/store.mjs) for the blob transport
+    blobBroker = null, // challenge broker for blob reserve/finalize/redeem
+    blobClient = null, // PillarBlobHttpClient for the production S3 broker path
+    senderKeyCheck = null, // registry gate for senders not derived from their key: (uuaid, pubkeyHex) => status
   }) {
     if (!keychain?._identity) throw new Error("Pillar: keychain must be loaded before construction");
     this.keychain = keychain;
@@ -47,11 +59,19 @@ export class Pillar {
     this.dhtClientMode = dhtClientMode;
     this.dhtPeerInfoMapper = dhtPeerInfoMapper;
     this.carriers = carriers;
-    this.carrierClient = carriers.length ? new CarrierClient({ keychain, carriers }) : null;
+    this.carrierClient = carriers.length ? new CarrierClient({ keychain, carriers, tierGrant }) : null;
     this._carrierPoller = null;
     this.enableLibp2p = enableLibp2p;
     this.cryptoInventory = cryptoInventory;
     this.node = null;
+    this.trust = trust;
+    this.metrics = metrics ?? new Observability();
+    this.blobStore = blobStore;
+    this.blobBroker = blobBroker;
+    this.blobClient = blobClient;
+    this.blobTier = tierGrant?.tier ?? "community";
+    this.blobMaxBodyBytes = Number.isInteger(tierGrant?.maxBodyBytes) ? tierGrant.maxBodyBytes : null;
+    this.senderKeyCheck = senderKeyCheck;
     this._envelopeHandlers = new Set();
     this._openStreams = new Map(); // peerIdString -> pushable
   }
@@ -234,8 +254,12 @@ export class Pillar {
    * 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");
+  async send({ recipient, recipientPublicKey, kind = "message", payload = {}, envelopeId = null, resolveTimeoutMs = 5000 }) {
+    if (!this.node && !this.carrierClient) {
+      this.metrics.inc("send.error.not-started");
+      throw new Error("pillar not started");
+    }
+    const t0 = Date.now();
 
     const book = this.addressBook?.get(recipient);
 
@@ -251,18 +275,30 @@ export class Pillar {
       } catch (_e) { /* fall through to the error below */ }
     }
     if (!pubkey) {
+      this.metrics.inc("send.error.no-public-key");
       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 envelope = seal(this.keychain, { recipient, recipientPublicKey: pubkey, kind, payload, id: envelopeId ?? undefined });
+    const hardCap = preflightBodyBytes(envelopeBodyBytes(envelope), { maxBodyBytes: MAX_INLINE_BODY_BYTES });
+    if (!hardCap.ok) {
+      this.metrics.inc("send.error.direct-cap");
+      throw new BlobSizeError(`envelope ${hardCap.bytes}B exceeds the ${MAX_INLINE_BODY_BYTES}B hard cap`, { size: hardCap.bytes, max: MAX_INLINE_BODY_BYTES });
+    }
     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) };
+        const delivery = await this._deliverToPeer(envelope, book.peerId, book.multiaddr);
+        this.metrics.inc("send.via.direct");
+        this.metrics.observe("send.latencyMs.via.direct", Date.now() - t0);
+        return { envelope, persisted, via: "direct", delivery };
       } catch (e) {
-        if (!this.carrierClient) throw e; // else fall through to carrier
+        if (!this.carrierClient) {
+          this.metrics.inc("send.error.direct-delivery-failed");
+          throw e;
+        } // else fall through to carrier
       }
     }
 
@@ -270,16 +306,27 @@ export class Pillar {
     if (this.carrierClient) {
       const receipt = await this.carrierClient.deliver(envelope);
       this.mailbox.markOutboundDelivered(envelope.id, envelopeSha(envelope));
+      this.metrics.inc("send.via.carrier");
+      this.metrics.observe("send.latencyMs.via.carrier", Date.now() - t0);
       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 (!this.node) {
+      this.metrics.inc("send.error.no-route");
+      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}`); }
+      catch (e) {
+        this.metrics.inc("send.error.resolve-failed");
+        throw new Error(`send: cannot resolve ${recipient}: ${e.message}`);
+      }
     }
-    return { envelope, persisted, via: "dht", delivery: await this._deliverToPeer(envelope, dhtAdvert.peerId, dhtAdvert.addrs?.[0]) };
+    const delivery = await this._deliverToPeer(envelope, dhtAdvert.peerId, dhtAdvert.addrs?.[0]);
+    this.metrics.inc("send.via.dht");
+    this.metrics.observe("send.latencyMs.via.dht", Date.now() - t0);
+    return { envelope, persisted, via: "dht", delivery };
   }
 
   /**
@@ -292,26 +339,90 @@ export class Pillar {
    * 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? }] }.
+   * Returns { group, results: [{ member, ok, via?, envelopeId?, error?, code?, fix? }] }.
    */
   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 };
+    // _group goes last so a payload can never override the group it travels in.
+    const wrapped = { ...payload, _group: { name: group, members } };
     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 });
+        results.push({ member, ok: false, error: e.message, ...(typeof e.code === "string" ? { code: e.code } : {}), ...(typeof e.fix === "string" ? { fix: e.fix } : {}) });
       }
     }
+    this.metrics.inc("sendGroup");
+    const failed = results.filter((r) => !r.ok).length;
+    if (failed) this.metrics.inc("sendGroup.failed", failed);
     return { group, results };
   }
 
+  /**
+   * Blob send — the oversized-payload path.  Explicit flow (blob.mjs header):
+   * broker reserve -> local AES-256-GCM encrypt (fresh DEK + nonce, AAD bound
+   * to this envelope) -> store upload -> broker finalize -> seal a kind
+   * "blob-ref" envelope carrying the signed ref (DEK inside the sealed
+   * payload, never in metadata) -> deliver.
+   *
+   * Preflight is exact: the placeholder-free body is measured against the
+   * tier inline limit and the 2 MiB direct hard cap BEFORE any store or
+   * broker call.  The envelope id is generated first so the GCM AAD can bind
+   * the ciphertext to it.
+   */
+  async sendBlob({ recipient, recipientPublicKey, kind = BLOB_KIND, data, ttlMs, resolveTimeoutMs = 5000 }) {
+    if (!this.blobClient && !this.blobStore) throw new BlobError("no-store", "sendBlob: configure blobClient or blobStore on the Pillar");
+    const buf = Buffer.isBuffer(data) ? data : Buffer.from(data);
+    // Reserve an envelope id so the blob ciphertext is AAD-bound to it.
+    const envelopeId = mkEnvelopeId();
+    const placeholder = { blobRef: { v: 1, envelopeId } };
+    // Seal a disposable probe before any broker/S3 side effect. Besides sizing,
+    // this enforces recipient UUAID ↔ public-key binding up front.
+    const probe = seal(this.keychain, { recipient, recipientPublicKey, kind, payload: placeholder, id: envelopeId });
+    const pf = preflightBodyBytes(envelopeBodyBytes(probe), { tier: this.blobTier, maxBodyBytes: this.blobMaxBodyBytes });
+    if (!pf.ok) {
+      this.metrics.inc(`sendBlob.preflight.${pf.source}`);
+      throw new BlobError("blob-too-large", `sendBlob: placeholder body ${pf.bytes}B exceeds ${pf.source} limit ${pf.limit}B`);
+    }
+    const prepared = this.blobClient
+      ? await prepareBrokerBlobSend(this.keychain, { data: buf, envelopeId, recipient, ttlMs, client: this.blobClient })
+      : await prepareBlobSend(this.keychain, {
+        data: buf, envelopeId, recipient, ttlMs,
+        store: this.blobStore, broker: this.blobBroker,
+      });
+    const r = await this.send({
+      recipient, recipientPublicKey, kind,
+      payload: { blobRef: prepared.ref }, envelopeId, resolveTimeoutMs,
+    });
+    this.metrics.inc("sendBlob.ok");
+    return { ...r, blob: { object: prepared.object, hash: prepared.hash, size: prepared.size, metadata: prepared.metadata } };
+  }
+
+  /**
+   * Redeem a blob-ref from an inbound payload — fetch + hash-check +
+   * single-use broker redemption + AES-256-GCM decrypt with the ref's DEK.
+   * The sender key gate (derived from its key, else a registry badge) runs
+   * BEFORE the broker redemption burns.  Returns { data, object, hash, size }.
+   */
+  async receiveBlob(payload, { envelopeId = null, now = Date.now() } = {}) {
+    const ref = payload?.blobRef;
+    if (!ref) throw new BlobError("blob-ref-invalid", "receiveBlob: payload carries no blobRef");
+    if (!this.blobClient && !this.blobStore) throw new BlobError("no-store", "receiveBlob: configure blobClient or blobStore on the Pillar");
+    const r = this.blobClient
+      ? await fetchBrokerBlob({ ref, envelopeId, recipient: this.uuaid, now, client: this.blobClient })
+      : await fetchAndDecryptBlob({
+        ref, store: this.blobStore, envelopeId, now,
+        broker: this.blobBroker, senderKeyCheck: this.senderKeyCheck,
+      });
+    this.metrics.inc("receiveBlob.ok");
+    return r;
+  }
+
   /**
    * Start pulling our inbox from every configured carrier.  Received envelopes
    * flow through the same verification + mailbox + handler pipeline as
@@ -328,8 +439,11 @@ export class Pillar {
       onEnvelope: async (envelope, { carrier, seq }) => {
         await this._receive(JSON.stringify(envelope), null);
         this.mailbox.setCarrierCursor?.(carrier, seq);
+        this.metrics.inc(`carrier.poll.${carrier}`);
+      },
+      onError: (_e, meta) => {
+        this.metrics.inc(`carrier.poll.error.${meta?.carrier ?? "unknown"}`);
       },
-      onError: (_e) => { /* transient poll errors are expected; backoff is in client */ },
     });
     return this._carrierPoller;
   }
@@ -338,7 +452,38 @@ export class Pillar {
     if (this._carrierPoller) { this._carrierPoller.stop(); this._carrierPoller = null; }
   }
 
+  /**
+   * One-shot inbox pull: fetch every pending envelope from every carrier
+   * (no long-poll) through the same verification + mailbox + handler
+   * pipeline, then return.  Complements startCarrierPolling for CLI /
+   * cron-style "check my mail now" callers.  Returns envelopes fetched.
+   */
+  async drainCarrierInbox() {
+    if (!this.carrierClient) return 0;
+    let total = 0;
+    const cursors = this.mailbox.getCarrierCursors?.() ?? {};
+    for (const base of this.carriers) {
+      let since = cursors[base] ?? 0;
+      for (;;) { // carrier pages at 200/fetch — loop until an empty page
+        const r = await this.carrierClient.fetchInbox(base, { since, waitS: 0 });
+        if (!r.envelopes.length) break;
+        for (const { seq, envelope } of r.envelopes) {
+          await this._receive(JSON.stringify(envelope), null);
+          this.mailbox.setCarrierCursor?.(base, seq);
+          since = Math.max(since, seq);
+          total++;
+          this.metrics.inc(`carrier.drain.${base}`);
+        }
+      }
+    }
+    return total;
+  }
+
   async _deliverToPeer(envelope, peerIdStr, multiaddrStr) {
+    const bytes = envelopeBodyBytes(envelope);
+    if (bytes > MAX_INLINE_BODY_BYTES) {
+      throw new BlobSizeError(`direct envelope ${bytes}B exceeds the ${MAX_INLINE_BODY_BYTES}B hard cap`, { size: bytes, max: MAX_INLINE_BODY_BYTES });
+    }
     const { peerIdFromString } = await import("@libp2p/peer-id");
     const { multiaddr } = await import("@multiformats/multiaddr");
     const peerId = peerIdFromString(peerIdStr);
@@ -383,6 +528,10 @@ export class Pillar {
     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 });
+    const bytes = envelopeBodyBytes(envelope);
+    if (bytes > MAX_INLINE_BODY_BYTES) {
+      throw new BlobSizeError(`direct envelope ${bytes}B exceeds the ${MAX_INLINE_BODY_BYTES}B hard cap`, { size: bytes, max: MAX_INLINE_BODY_BYTES });
+    }
     this.mailbox.appendOutbound(envelope);
     const { peerIdFromString } = await import("@libp2p/peer-id");
     const { multiaddr } = await import("@multiformats/multiaddr");
@@ -404,8 +553,14 @@ export class Pillar {
   async _handleStream(stream, connection) {
     try {
       let buf = "";
+      let receivedBytes = 0;
       for await (const chunk of stream) {
         const bytes = chunk?.subarray ? chunk.subarray() : chunk;
+        receivedBytes += bytes.byteLength ?? bytes.length;
+        if (receivedBytes > MAX_INLINE_BODY_BYTES + 1) {
+          this.metrics.inc("received.rejected.direct-cap");
+          throw new BlobSizeError(`incoming direct envelope exceeds the ${MAX_INLINE_BODY_BYTES}B hard cap`, { size: receivedBytes, max: MAX_INLINE_BODY_BYTES });
+        }
         buf += u8ToString(bytes);
         const newlineIdx = buf.indexOf("\n");
         if (newlineIdx < 0) continue;
@@ -425,15 +580,20 @@ export class Pillar {
   async _receive(rawLine, connection) {
     let envelope;
     try { envelope = JSON.parse(rawLine); }
-    catch (_e) { return; }
+    catch (_e) {
+      this.metrics.inc("received.unparsable");
+      return;
+    }
     const verdict = open(envelope, { cryptoInventory: this.cryptoInventory });
     if (!verdict.ok) {
+      this.metrics.inc(`received.rejected.${verdict.reason}`);
       // 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.
+      this.metrics.inc("received.wrong-recipient");
       return;
     }
     // E2E: decrypt the sealed payload.  Ciphertext-at-rest: the mailbox stores
@@ -442,16 +602,45 @@ export class Pillar {
     try {
       payload = decrypt(this.keychain, envelope);
     } catch (e) {
+      this.metrics.inc("received.decrypt-failed");
       // 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
+    if (persisted.duplicate) {
+      this.metrics.inc("received.duplicate");
+      return; // replay: do not re-fire handlers
+    }
+    this.metrics.inc(`received.kind.${envelope.kind}`);
+    // Trust gate (recipient consent): quarantine-not-drop. The envelope is
+    // already persisted (chain-hashed evidence); a gated sender just never
+    // reaches handlers. An ack/reply passes the gate ONLY if its inReplyTo
+    // names an envelope in OUR outbox — a genuine receipt for our own send.
+    // (kind alone is spoofable; the outbox check is not.)
+    if (this.trust) {
+      const isReceipt = (envelope.kind === "ack" || envelope.kind === "reply") &&
+        typeof payload?.inReplyTo === "string" && this.mailbox.hasOutbound(payload.inReplyTo);
+      if (!isReceipt) {
+        const { evaluateTrust } = await import("./identity/trust.mjs");
+        const known = new Set(this.addressBook?.keys() ?? []);
+        const verdict = evaluateTrust(this.trust, envelope.sender, known);
+        if (!verdict.deliver) {
+          this.mailbox.markQuarantined(envelope.id, verdict.reason);
+          this.metrics.inc(`received.quarantined.${verdict.reason}`);
+          // eslint-disable-next-line no-console
+          console.warn(`pillar: quarantined ${envelope.id} from ${envelope.sender} (${verdict.reason})`);
+          return;
+        }
+      }
+    }
     const view = { ...envelope, payload };
     for (const h of this._envelopeHandlers) {
       try { await h(view, persisted); }
-      catch (e) { console.error("pillar: envelope handler threw", e); }
+      catch (e) {
+        this.metrics.inc("received.handler-error");
+        console.error("pillar: envelope handler threw", e);
+      }
     }
   }
 }