@uuaid/pillar 0.2.0-alpha.10 → 0.2.0-alpha.12

package/src/net/carrier-server.mjs

@@ -36,9 +36,11 @@ import { createHash } from "node:crypto";
 import Database from "better-sqlite3";
 import { open as openEnvelope } from "./envelope.mjs";
 import { Keychain } from "../identity/keychain.mjs";
+import { verifyTierGrant } from "../identity/tier.mjs";
 
 const MAX_WAIT_S = 30;
-const MAX_BODY = 512 * 1024; // 512 KiB per envelope
+const MAX_BODY = 512 * 1024; // 512 KiB per envelope (community tier)
+const MAX_BODY_STREAM = 2 * 1024 * 1024 + 8192; // absolute read cap: max tier body + grant/header slack
 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
@@ -51,7 +53,7 @@ const MAX_DB_BYTES = 256 * 1024 * 1024;    // F2: SQLite size backpressure (503
 const RATE_MAP_HARD_CAP = 10_000;          // F2: bound memory under key spray
 
 export class CarrierServer {
-  constructor({ dbPath = "carrier.db", ttlDays = 14, cryptoInventory } = {}) {
+  constructor({ dbPath = "carrier.db", ttlDays = 14, cryptoInventory, trustedTierIssuers = [] } = {}) {
     this.db = new Database(dbPath);
     this.db.pragma("journal_mode = WAL");
     this.db.exec(`
@@ -73,6 +75,37 @@ export class CarrierServer {
     this.rateMap = new Map(); // F2: "<kind>:<key>" -> [ms timestamps]
     this.activeWaits = 0;     // F2: long-polls currently sleeping
     this._closed = false;
+    // Tier grants: issuer pubkeys (hex) this carrier honors. Empty = every
+    // sender gets community-tier budgets (pre-tier behavior, default).
+    this.trustedTierIssuers = trustedTierIssuers;
+    this._grantCache = new Map(); // sender uuaid -> { grant, cachedAt }
+  }
+
+  /**
+   * Tier resolution for a POST: verify an optional x-pillar-tier-grant header
+   * (base64 JSON, issued by makeTierGrant). A valid grant FOR THE CLAIMED
+   * SENDER raises that sender's rate/size budget. Invalid/foreign grants are
+   * ignored (fall back to community) — never a hard reject, so a bad grant
+   * cannot break plain delivery.
+   */
+  _resolveTier(req, sender) {
+    const fallback = { tier: "community", envelopesPerMin: MAX_ENVELOPES_PER_MIN, maxBodyBytes: MAX_BODY };
+    if (!this.trustedTierIssuers.length) return fallback;
+    const hdr = req?.headers?.["x-pillar-tier-grant"];
+    if (!hdr) return fallback;
+    let grant;
+    try { grant = JSON.parse(Buffer.from(String(hdr), "base64").toString("utf-8")); }
+    catch (_e) { return fallback; }
+    if (grant?.uuaid !== sender) return fallback; // grant must name the claimed sender
+    const cached = this._grantCache.get(sender);
+    if (cached && cached.sig === grant.sig && Date.now() - cached.at < 60_000) return cached.resolved;
+    const v = verifyTierGrant(grant, this.trustedTierIssuers);
+    const resolved = v.ok
+      ? { tier: grant.tier, envelopesPerMin: grant.envelopesPerMin, maxBodyBytes: grant.maxBodyBytes }
+      : fallback;
+    if (this._grantCache.size > 4096) this._grantCache.clear(); // bounded
+    this._grantCache.set(sender, { sig: grant.sig, at: Date.now(), resolved });
+    return resolved;
   }
 
   /** F2: best-effort client identity, nginx-aware (XFF set by proxy). */
@@ -127,7 +160,7 @@ export class CarrierServer {
       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; }
+        if (size > MAX_BODY_STREAM) { reject(new Error("body too large")); req.destroy(); return; }
         chunks.push(c);
       });
       req.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
@@ -135,7 +168,7 @@ export class CarrierServer {
     });
   }
 
-  _handlePost(envelope, ip = "unknown") {
+  _handlePost(envelope, ip = "unknown", req = null, rawBytes = 0) {
     const verdict = openEnvelope(envelope, { cryptoInventory: this.cryptoInventory });
     if (!verdict.ok) {
       // F2: cap rejected sends per client (flood the verifier → 429).
@@ -147,8 +180,13 @@ export class CarrierServer {
     if (typeof envelope.recipient !== "string" || !envelope.recipient.startsWith("uuaid:")) {
       return { code: 400, body: { accepted: false, reason: "bad-recipient" } };
     }
+    // Tier: a verified grant raises this sender's budgets; default community.
+    const tier = this._resolveTier(req, envelope.sender);
+    if (rawBytes > tier.maxBodyBytes) {
+      return { code: 413, body: { accepted: false, reason: "body-too-large", maxBodyBytes: tier.maxBodyBytes, tier: tier.tier } };
+    }
     // F2: per-sender ingest budget — a sender uuaid cannot flood its carrier.
-    if (!this._rateAllow(`s:${envelope.sender}`, MAX_ENVELOPES_PER_MIN)) {
+    if (!this._rateAllow(`s:${envelope.sender}`, tier.envelopesPerMin)) {
       return { code: 429, body: { accepted: false, reason: "rate-limited" } };
     }
     // F2: per-client budget on ACCEPTED sends — closes the unlimited
@@ -255,7 +293,7 @@ export class CarrierServer {
           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));
+          const { code, body } = this._handlePost(envelope, this._clientIp(req), req, Buffer.byteLength(raw));
           return this._json(res, code, body);
         }
         const inboxMatch = /^\/v1\/inbox\/([^/]+)$/.exec(url.pathname);

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

@@ -22,6 +22,7 @@ import { createTransport, PILLAR_PROTOCOL, uuaidToDhtKey, peerIdFromEd25519Hex }
 import { seal, open, decrypt, envelopeSha, ENVELOPE_VERSION } from "./net/envelope.mjs";
 import { Mailbox } from "./mailbox/mailbox.mjs";
 import { CarrierClient } from "./net/carrier-client.mjs";
+import { Observability } from "./observability.mjs";
 
 const VALUE_STORE_PREFIX = "/uuaid/1.0";
 
@@ -37,6 +38,9 @@ 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
   }) {
     if (!keychain?._identity) throw new Error("Pillar: keychain must be loaded before construction");
     this.keychain = keychain;
@@ -47,11 +51,13 @@ 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._envelopeHandlers = new Set();
     this._openStreams = new Map(); // peerIdString -> pushable
   }
@@ -235,7 +241,11 @@ export class Pillar {
    * 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");
+    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,6 +261,7 @@ 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`);
     }
 
@@ -260,9 +271,15 @@ export class Pillar {
     // 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 +287,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 };
   }
 
   /**
@@ -309,6 +337,9 @@ export class Pillar {
         results.push({ member, ok: false, error: e.message });
       }
     }
+    this.metrics.inc("sendGroup");
+    const failed = results.filter((r) => !r.ok).length;
+    if (failed) this.metrics.inc("sendGroup.failed", failed);
     return { group, results };
   }
 
@@ -328,8 +359,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;
   }
@@ -358,6 +392,7 @@ export class Pillar {
           this.mailbox.setCarrierCursor?.(base, seq);
           since = Math.max(since, seq);
           total++;
+          this.metrics.inc(`carrier.drain.${base}`);
         }
       }
     }
@@ -451,15 +486,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
@@ -468,16 +508,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);
+      }
     }
   }
 }