@uuaid/agent-commons 0.0.0-stage → 0.2.0-alpha.2

package/src/vendor/pillar/identity/keychain.mjs

@@ -0,0 +1,192 @@
+/**
+ * Keychain — persistent identity for a pillar peer.
+ *
+ * Every agent has exactly one identity: an Ed25519 keypair.  The private key
+ * is stored encrypted at rest with a password derived from the OS keyring
+ * (Windows Credential Manager / macOS Keychain / GNOME libsecret) if
+ * available, or a user-supplied passphrase otherwise.
+ *
+ * The keychain is deliberately simple: one keypair, one UUAID, one file.
+ * Rotation is a new keypair + a new signed profile in the DHT.
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync, chmodSync } from "node:fs";
+import { dirname } from "node:path";
+import { randomBytes, createHash, generateKeyPairSync, sign, verify, createPublicKey, createPrivateKey, hkdfSync, createCipheriv, createDecipheriv } from "node:crypto";
+import { ed25519 } from "@noble/curves/ed25519.js";
+
+const KEYCHAIN_VERSION = 1;
+
+/**
+ * RFC 8032 / FIPS 186-5 rule for an Ed25519 public key: the canonical encoding
+ * of a point that is not of small order and lies in the prime-order subgroup.
+ *
+ * OpenSSL's Ed25519 verify (node `crypto.verify`) does not check this: it uses
+ * the non-cofactored equation, and 5 of the 8 small-order points verify as
+ * keys. With the identity point as the key, R = identity and S = 0 verifies on
+ * every message, so anyone could forge a signature "from" that key's uuaid
+ * (found 2026-10-06). The same rule as `isStrictEd25519PublicKey` in
+ * @uuaid/pillar-client.
+ *
+ * The answer depends on the key alone, so it is cached (bounded).
+ */
+const STRICT_KEY_CACHE_MAX = 4096;
+const strictKeyCache = new Map();
+
+export function isStrictEd25519PublicKey(publicKeyHex) {
+  if (typeof publicKeyHex !== "string" || !/^[0-9a-f]{64}$/i.test(publicKeyHex)) return false;
+  const hex = publicKeyHex.toLowerCase();
+  const cached = strictKeyCache.get(hex);
+  if (cached !== undefined) return cached;
+  let ok = false;
+  try {
+    const point = ed25519.Point.fromHex(hex, false);
+    ok = point.toHex() === hex && !point.isSmallOrder() && point.isTorsionFree();
+  } catch (_e) {
+    ok = false;
+  }
+  if (strictKeyCache.size >= STRICT_KEY_CACHE_MAX) strictKeyCache.delete(strictKeyCache.keys().next().value);
+  strictKeyCache.set(hex, ok);
+  return ok;
+}
+
+/**
+ * Derive a stable, publishable local id from a raw Ed25519 public key.  This
+ * makes the UUAID self-authenticating: given the UUAID, anyone can
+ * independently check that the public key hashes to the expected local-id.
+ *
+ * Public because consumers verifying a UUAID against a public key need it
+ * without reaching into `Keychain._localIdFromKey`.
+ */
+export function localIdFromKey(rawPub) {
+  const h = createHash("sha256").update(rawPub).digest();
+  // First 16 bytes -> UUID-style dash format for readability.
+  const b = h.slice(0, 16);
+  const hex = Buffer.from(b).toString("hex");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}
+
+export class Keychain {
+  constructor(path) {
+    this.path = path;
+    this._identity = null; // { uuaid, publicKeyHex, privateKey (KeyObject), createdAt }
+  }
+
+  exists() {
+    return existsSync(this.path);
+  }
+
+  /**
+   * Generate a fresh identity.  Never overwrites.
+   *
+   * uuaidNamespace: default "foundation" per IAASO-1001 today; will support
+   * federated forms once federation profile ratifies.
+   * objectType: default "agent"; overridable to "service" etc.
+   * localId: default random UUIDv4-like; caller may supply.
+   */
+  static generate({ uuaidNamespace = "foundation", objectType = "agent", localId = null } = {}) {
+    const { publicKey, privateKey } = generateKeyPairSync("ed25519");
+    const pubDer = publicKey.export({ type: "spki", format: "der" });
+    const rawPub = pubDer.slice(pubDer.length - 32);
+    const localIdActual = localId ?? Keychain._localIdFromKey(rawPub);
+    const uuaid = `uuaid:${uuaidNamespace}:${objectType}:${localIdActual}`;
+    return {
+      uuaid,
+      publicKey,
+      privateKey,
+      publicKeyHex: Buffer.from(rawPub).toString("hex"),
+      createdAt: new Date().toISOString(),
+    };
+  }
+
+  /**
+   * Derive the local-id from a raw Ed25519 public key.
+   *
+   * Kept on the class for the call sites that already reach for it; the
+   * implementation is the module-level `localIdFromKey`, which is the public
+   * export.
+   */
+  static localIdFromKey = localIdFromKey;
+
+  /** @deprecated Alias kept for compatibility — use `localIdFromKey`. */
+  static _localIdFromKey = localIdFromKey;
+
+  /**
+   * Load an identity from disk.
+   */
+  load({ passphrase } = {}) {
+    if (!this.exists()) throw new Error("keychain not initialized; run `pillar init` first");
+    const blob = JSON.parse(readFileSync(this.path, "utf-8"));
+    if (blob.version !== KEYCHAIN_VERSION) throw new Error(`unsupported keychain version ${blob.version}`);
+    const salt = Buffer.from(blob.salt, "hex");
+    const key = hkdfSync("sha256", Buffer.from(passphrase ?? "", "utf-8"), salt, "uuaid-pillar-keychain-v1", 32);
+    const iv = Buffer.from(blob.iv, "hex");
+    const ct = Buffer.from(blob.ciphertext, "base64");
+    const tag = Buffer.from(blob.tag, "hex");
+    const decipher = createDecipheriv("aes-256-gcm", Buffer.from(key), iv);
+    decipher.setAuthTag(tag);
+    const plain = Buffer.concat([decipher.update(ct), decipher.final()]);
+    const seed = plain; // 32-byte raw ed25519 seed
+    const pkcs8Prefix = Buffer.from("302e020100300506032b657004220420", "hex");
+    const privateKey = createPrivateKey({ key: Buffer.concat([pkcs8Prefix, seed]), format: "der", type: "pkcs8" });
+    const publicKey = createPublicKey(privateKey);
+    const pubDer = publicKey.export({ type: "spki", format: "der" });
+    const rawPub = pubDer.slice(pubDer.length - 32);
+    const publicKeyHex = Buffer.from(rawPub).toString("hex");
+    // Sanity: derived UUAID must match stored UUAID.
+    const derivedLocalId = Keychain._localIdFromKey(rawPub);
+    const parts = blob.uuaid.split(":");
+    if (parts.length < 4 || parts[3] !== derivedLocalId) {
+      throw new Error("keychain integrity failure: UUAID does not match keypair");
+    }
+    this._identity = { uuaid: blob.uuaid, publicKey, privateKey, publicKeyHex, createdAt: blob.createdAt };
+    return this._identity;
+  }
+
+  /**
+   * Save identity to disk, encrypted with the passphrase.
+   */
+  save(identity, { passphrase } = {}) {
+    const seedDer = identity.privateKey.export({ type: "pkcs8", format: "der" });
+    const seed = seedDer.slice(seedDer.length - 32);
+    const salt = randomBytes(16);
+    const key = hkdfSync("sha256", Buffer.from(passphrase ?? "", "utf-8"), salt, "uuaid-pillar-keychain-v1", 32);
+    const iv = randomBytes(12);
+    const cipher = createCipheriv("aes-256-gcm", Buffer.from(key), iv);
+    const ct = Buffer.concat([cipher.update(seed), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    const blob = {
+      version: KEYCHAIN_VERSION,
+      uuaid: identity.uuaid,
+      createdAt: identity.createdAt,
+      salt: salt.toString("hex"),
+      iv: iv.toString("hex"),
+      ciphertext: ct.toString("base64"),
+      tag: tag.toString("hex"),
+      // Public material is stored in the clear so `pillar profile` doesn't need a passphrase.
+      publicKeyHex: identity.publicKeyHex,
+    };
+    mkdirSync(dirname(this.path), { recursive: true });
+    writeFileSync(this.path, JSON.stringify(blob, null, 2));
+    chmodSync(this.path, 0o600);
+    this._identity = identity;
+  }
+
+  publicView() {
+    if (!this.exists()) return null;
+    const blob = JSON.parse(readFileSync(this.path, "utf-8"));
+    return { uuaid: blob.uuaid, publicKeyHex: blob.publicKeyHex, createdAt: blob.createdAt };
+  }
+
+  sign(data) {
+    if (!this._identity) throw new Error("identity not loaded");
+    return sign(null, Buffer.isBuffer(data) ? data : Buffer.from(data, "utf-8"), this._identity.privateKey);
+  }
+
+  static verifyDetached(publicKeyHex, data, signatureBytes) {
+    if (!isStrictEd25519PublicKey(publicKeyHex)) return false; // @rule keychain.strict-key
+    const spkiPrefix = Buffer.from("302a300506032b6570032100", "hex");
+    const der = Buffer.concat([spkiPrefix, Buffer.from(publicKeyHex, "hex")]);
+    const pub = createPublicKey({ key: der, format: "der", type: "spki" });
+    return verify(null, Buffer.isBuffer(data) ? data : Buffer.from(data, "utf-8"), pub, signatureBytes);
+  }
+}

package/src/vendor/pillar/identity/tier.mjs

@@ -0,0 +1,130 @@
+/**
+ * Tier grants — carrier-side volume/size flexibility for qualified identities.
+ *
+ * Foundations, orgs, and enterprise supporters that pass the UUAID
+ * qualification process receive a SIGNED TIER GRANT: a portable JSON object,
+ * Ed25519-signed by a trusted issuer (the UUAID Foundation identity, or any
+ * issuer a carrier operator chooses to trust).  Carriers verify the signature
+ * and expiry locally — no registry lookup, no account, consistent with the
+ * self-authenticating design.  The wire API is unchanged: a grant only
+ * raises the holder's rate/size budgets at carriers that trust the issuer.
+ *
+ * Qualification has two routes. The original is off-wire: the foundation's
+ * review process decides WHO gets a grant. The second is earned on-wire —
+ * operators who keep a public seed alive are promoted by the seed registry
+ * (net/seed-registry.mjs) and issued a grant automatically, no review. This
+ * module only makes grants unforgeable and portable; it does not care which
+ * route produced one.
+ *
+ * Grant shape (JCS-signed over every field except `sig`):
+ *   { v: 1, uuaid, tier, envelopesPerMin, maxBodyBytes, expires, issuer, sig }
+ *   ...plus optional { priority: true, seedTier, seedUrl } on earned grants.
+ *
+ * `priority` is the wire half of priority delivery: a carrier that trusts the
+ * issuer admits the holder from a reserved lane when it is otherwise shedding
+ * load. It is inside the signed body, so it cannot be added to a grant after
+ * issue. Older carriers that predate the field verify such a grant unchanged
+ * (JCS covers whatever keys are present) and simply ignore the privilege.
+ */
+import { createHash } from "node:crypto";
+import { jcs } from "./jcs.mjs";
+import { Keychain } from "./keychain.mjs";
+
+/** Tier ladder. community = the unauthenticated default (F2 hardening values).
+ *
+ *  Greek-order names (Doric, Ionic, Corinthian) are ALIASES for the lower
+ *  three rungs of the canonical ladder. They were added 2026-09-19 so that
+ *  grants may carry a feature-tier name — Doric = pillar core only,
+ *  Ionic = + plinth mix hops, Corinthian = + full optional stack — while
+ *  the carrier still enforces a single budget table. A grant with
+ *  `tier: "Doric"` and a grant with `tier: "community"` resolve to the same
+ *  rate/size budget; carriers verify by `TIER_DEFAULTS[grant.tier]` and
+ *  never see the difference.
+ *
+ *  Aliasing is additive — the canonical five names still work, no carrier
+ *  upgrade required. Enterprise and foundation keep their original names
+ *  (no alias needed; they are not feature-presence markers).
+ *
+ *  Adding a new alias is a one-line change here: spread the budget object
+ *  under the new key. No other file needs to know.
+ */
+const _CANONICAL_TIERS = {
+  community:  { envelopesPerMin: 120,  maxBodyBytes: 512 * 1024 },
+  supporter:  { envelopesPerMin: 300,  maxBodyBytes: 1024 * 1024 },
+  org:        { envelopesPerMin: 600,  maxBodyBytes: 2 * 1024 * 1024 },
+  enterprise: { envelopesPerMin: 1200, maxBodyBytes: 2 * 1024 * 1024 },
+  foundation: { envelopesPerMin: 3000, maxBodyBytes: 2 * 1024 * 1024 },
+};
+
+export const TIER_DEFAULTS = {
+  ..._CANONICAL_TIERS,
+  Doric:      _CANONICAL_TIERS.community,    // alias of community
+  Ionic:      _CANONICAL_TIERS.supporter,    // alias of supporter
+  Corinthian: _CANONICAL_TIERS.org,          // alias of org
+};
+
+/** Hard ceiling any grant can reach — also the carrier's raw-body stream cap. */
+export const ABSOLUTE_MAX_BODY = 2 * 1024 * 1024;
+export const ABSOLUTE_MAX_RATE = 6000;
+
+function signable(grant) {
+  const { sig, ...rest } = grant;
+  return jcs(rest);
+}
+
+/**
+ * Issue a grant, signed by the loaded keychain (the issuer identity).
+ * Rates/sizes default from the tier ladder; explicit overrides are clamped
+ * to the absolute ceilings.
+ */
+export function makeTierGrant(keychain, { uuaid, tier, envelopesPerMin, maxBodyBytes, expires, priority, seedTier, seedUrl }) {
+  if (!TIER_DEFAULTS[tier]) throw new Error(`unknown tier "${tier}" (${Object.keys(TIER_DEFAULTS).join("|")})`);
+  if (!uuaid?.startsWith("uuaid:")) throw new Error("grant subject must be a uuaid:...");
+  if (!expires || !Number.isFinite(Date.parse(expires))) throw new Error("expires must be an ISO date");
+  const grant = {
+    v: 1,
+    uuaid,
+    tier,
+    envelopesPerMin: Math.min(envelopesPerMin ?? TIER_DEFAULTS[tier].envelopesPerMin, ABSOLUTE_MAX_RATE),
+    maxBodyBytes: Math.min(maxBodyBytes ?? TIER_DEFAULTS[tier].maxBodyBytes, ABSOLUTE_MAX_BODY),
+    expires,
+    issuer: keychain._identity.publicKeyHex,
+    // Optional fields are omitted rather than set false/null so that a plain
+    // grant's signed body stays byte-identical to what pre-priority issuers
+    // produced.
+    ...(priority ? { priority: true } : {}),
+    ...(seedTier ? { seedTier } : {}),
+    ...(seedUrl ? { seedUrl } : {}),
+  };
+  grant.sig = keychain.sign(Buffer.from(signable(grant), "utf-8")).toString("hex");
+  return grant;
+}
+
+/**
+ * Verify a grant against a set of trusted issuer pubkeys (hex).
+ * Returns { ok: true, grant } or { ok: false, reason }.
+ */
+export function verifyTierGrant(grant, trustedIssuers, now = Date.now()) {
+  if (grant?.v !== 1) return { ok: false, reason: "bad-version" };
+  if (!TIER_DEFAULTS[grant.tier]) return { ok: false, reason: "unknown-tier" };
+  if (!trustedIssuers?.includes(grant.issuer)) return { ok: false, reason: "untrusted-issuer" };
+  const exp = Date.parse(grant.expires);
+  if (!Number.isFinite(exp) || exp < now) return { ok: false, reason: "expired" };
+  if (!(grant.envelopesPerMin <= ABSOLUTE_MAX_RATE) || !(grant.maxBodyBytes <= ABSOLUTE_MAX_BODY)) {
+    return { ok: false, reason: "over-ceiling" };
+  }
+  // Fail closed on a malformed privilege: `priority` is either absent or the
+  // boolean true. Anything else (a truthy string, 1, an object) is a grant we
+  // do not understand, and understanding it wrongly grants a reserved lane.
+  if ("priority" in grant && grant.priority !== true) return { ok: false, reason: "bad-priority" };
+  let verified = false;
+  try {
+    verified = Keychain.verifyDetached(grant.issuer, Buffer.from(signable(grant), "utf-8"), Buffer.from(grant.sig, "hex"));
+  } catch (_e) { return { ok: false, reason: "verify-threw" }; }
+  if (!verified) return { ok: false, reason: "bad-signature" };
+  return { ok: true, grant };
+}
+
+export function grantFingerprint(grant) {
+  return createHash("sha256").update(signable(grant)).digest("hex").slice(0, 16);
+}

package/src/vendor/pillar/net/carrier-client.mjs

@@ -0,0 +1,197 @@
+/**
+ * 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.
+ */
+import { envelopeBodyBytes, preflightBodyBytes } from "../blob/blob.mjs";
+import { seedTier } from "./seed-tier.mjs";
+import { carrierFix, REFUSAL_FIXES } from "./refusals.mjs";
+
+/**
+ * Rank carriers by how proven they are, best first. Unknown carriers rank as
+ * `probation` — the primary carrier from a directory has no seed tier and
+ * should not be assumed better than a seed that earned one, nor worse.
+ * Array.prototype.sort is stable, so a client given no tier information at
+ * all keeps its list in exactly the order it was constructed with.
+ */
+function byTier(tiers) {
+  return (a, b) => seedTier(tiers[a] ?? "probation").listRank - seedTier(tiers[b] ?? "probation").listRank;
+}
+
+export class CarrierClient {
+  /**
+   * @param {{keychain: import('../identity/keychain.mjs').Keychain, carriers: string[]}} opts
+   *   carriers: base URLs, e.g. ["https://pillar.uuaid.org"]
+   */
+  /**
+   * @param {object} opts
+   *   carrierTiers  optional { "<url>": "<seed tier>" } from a directory's
+   *                 seeds[]. Drives which carrier's receipt is authoritative
+   *                 and which one is polled first — see `deliver`.
+   */
+  constructor({ keychain, carriers, tierGrant = null, carrierTiers = {} }) {
+    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;
+    // Normalise tier keys the same way as carrier URLs so a trailing slash on
+    // one side does not silently drop a seed to `probation`.
+    this.carrierTiers = Object.fromEntries(
+      Object.entries(carrierTiers).map(([u, t]) => [String(u).replace(/\/+$/, ""), t]),
+    );
+    this.carriers = carriers.map(u => u.replace(/\/+$/, "")).sort(byTier(this.carrierTiers));
+    // Tier label for the local preflight: a signed grant raises it; default
+    // stays community (matches the carrier's unauthenticated tier).
+    this.tier = tierGrant?.tier ?? "community";
+    this.maxBodyBytes = Number.isInteger(tierGrant?.maxBodyBytes) ? tierGrant.maxBodyBytes : null;
+    // Optional signed tier grant (tier.mjs) — sent as a header on deliver so
+    // qualifying senders get raised budgets at carriers that trust the issuer.
+    this.tierGrantB64 = tierGrant
+      ? Buffer.from(JSON.stringify(tierGrant), "utf-8").toString("base64")
+      : null;
+    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 receipt from the
+   * most PROVEN accepting carrier as the primary ({ carrier, seq, sha,
+   * duplicate }) plus `all` with every carrier's outcome ({ carrier, ok,
+   * seq?, sha?, duplicate?, error?, status?, reason?, fix? }).
+   *
+   * When every carrier refuses, the thrown error carries `code` (the most
+   * proven carrier's `reason`, else carrier-unreachable / carrier-bad-response),
+   * `fix`, `status`, `carrier` and `refusals` (= `all`).
+   *
+   * Which receipt is primary matters because callers quote its seq back as a
+   * cursor and cite its carrier in receipts: it should name a seed that will
+   * still be there. With no tier information every carrier ranks equally and
+   * the first-in-list receipt wins, exactly as before.
+   */
+  async deliver(envelope, { timeoutMs = 10000 } = {}) {
+    // Preflight against the carrier limits BEFORE any network call: the
+    // tier inline limit first, then the 2 MiB direct hard cap — no tier
+    // grant can raise the hard cap.  Typed failure, not a carrier 413.
+    const pf = preflightBodyBytes(envelopeBodyBytes(envelope), { tier: this.tier, maxBodyBytes: this.maxBodyBytes });
+    if (!pf.ok) {
+      const e = new Error(`carrier preflight: body ${pf.bytes}B exceeds ${pf.source} limit ${pf.limit}B — use the blob transport`);
+      e.code = pf.source === "direct-cap" ? "blob-too-large" : "over-tier-limit";
+      e.limit = pf.limit; e.source = pf.source;
+      e.fix = REFUSAL_FIXES["over-tier-limit"];
+      throw e;
+    }
+    const attempt = async (base) => {
+      try {
+        const res = await fetch(`${base}/v1/envelopes`, {
+          method: "POST",
+          headers: {
+            "content-type": "application/json",
+            ...(this.tierGrantB64 ? { "x-pillar-tier-grant": this.tierGrantB64 } : {}),
+          },
+          body: JSON.stringify(envelope),
+          signal: AbortSignal.timeout(timeoutMs),
+        });
+        const raw = await res.text();
+        let body = {};
+        try { body = raw ? JSON.parse(raw) : {}; } catch (_error) {}
+        if (res.status === 202 && body.accepted) {
+          return { carrier: base, ok: true, seq: body.seq, sha: body.sha, duplicate: !!body.duplicate };
+        }
+        const reason = typeof body.reason === "string" && body.reason ? body.reason
+          : typeof body.error === "string" && body.error ? body.error : null;
+        return {
+          carrier: base, ok: false, status: res.status,
+          error: `${res.status} ${body.reason ?? body.error ?? (raw ? "non-json-response" : "empty-response")}`,
+          ...(reason ? { reason, fix: (typeof body.fix === "string" && body.fix) || carrierFix(reason) } : {}),
+        };
+      } 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) {
+      const e = new Error(`carrier deliver failed on all carriers: ${all.map(r => `${r.carrier}: ${r.error}`).join("; ")}`);
+      // `all` is in rank order, so this is the most proven carrier's answer.
+      const primary = all.find(r => r.reason) ?? all.find(r => r.status) ?? null;
+      e.code = primary?.reason ?? (primary ? "carrier-bad-response" : "carrier-unreachable");
+      e.fix = primary?.fix ?? carrierFix(e.code);
+      if (primary) { e.status = primary.status; e.carrier = primary.carrier; }
+      e.refusals = all;
+      throw e;
+    }
+    const ranked = accepted.slice().sort((a, b) => byTier(this.carrierTiers)(a.carrier, b.carrier));
+    const { carrier, seq, sha, duplicate } = ranked[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(() => ({}));
+      const e = new Error(`inbox fetch ${base}: ${res.status} ${body.error ?? ""}`);
+      e.code = typeof body.error === "string" && body.error ? body.error : "carrier-bad-response";
+      e.fix = (typeof body.fix === "string" && body.fix) || carrierFix(e.code);
+      e.status = res.status; e.carrier = base;
+      throw e;
+    }
+    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.
+   * onError(error, { carrier }) — the carrier context is passed so callers
+   * can attribute failures per carrier in metrics.
+   */
+  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}`), { carrier: base }); }
+          }
+        } catch (e) {
+          onError?.(e, { carrier: base });
+          // 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),
+    };
+  }
+}