@uuaid/pillar 0.2.0-alpha.9 → 2.0.2

package/src/index.mjs

@@ -1,18 +1,44 @@
 /**
  * @uuaid/pillar — v0.2.0-alpha.0
  *
- * IAASO-3050 reference: every agent runs its own PDP pillar, discovers peers
+ * Every agent runs its own PDP pillar, discovers peers
  * via a Kademlia DHT, exchanges cryptographically signed messages over libp2p.
  *
  * Entry point.  Not intended for import in browsers today — browser build
  * lives at @uuaid/pillar-browser (later).
  */
-export { Keychain } from "./identity/keychain.mjs";
+export { Keychain, localIdFromKey } from "./identity/keychain.mjs";
 export { jcs } from "./identity/jcs.mjs";
 export { seal, open, decrypt, envelopeSha, keychainSeed, ENVELOPE_VERSION, E2E_ALG } from "./net/envelope.mjs";
+export { DELEGATION_VERSION, verifyDelegationDoc, delegationCoversKind } from "./net/delegation.mjs";
 export { sealPayload, openPayload, edPubToX25519, edSeedToX25519 } from "./crypto/e2e.mjs";
 export { Mailbox } from "./mailbox/mailbox.mjs";
 export { Pillar } from "./pillar.mjs";
 export { createTransport, PILLAR_PROTOCOL, uuaidToDhtKey, peerIdFromEd25519Hex } from "./net/transport.mjs";
 export { CarrierClient } from "./net/carrier-client.mjs";
 export { CarrierServer } from "./net/carrier-server.mjs";
+// Seeds: the ladder that turns sustained relay service into earned tier
+// grants + priority delivery, and the registry that observes and publishes it.
+export {
+  SEED_TIERS, SEED_TIER_NAMES, GRANT_TTL_DAYS, DEMOTE_AFTER_FAILURES,
+  seedTier, seedTierAtLeast, uptimeOf, evaluateSeedTier,
+} from "./net/seed-tier.mjs";
+export { SeedRegistry, checkSeedUrl, verifySeedInfo, PROBE_WINDOW } from "./net/seed-registry.mjs";
+// Blob transport (client/core half): oversized payloads ride an ephemeral
+// encrypted object store; only a <=4KiB signed ref travels in the envelope.
+export {
+  BLOB_REF_V, BLOB_KIND, MAX_BLOB_REF_BYTES, MAX_INLINE_BODY_BYTES,
+  MAX_BLOB_OBJECT_BYTES, MAX_BLOB_PLAINTEXT_BYTES,
+  DEFAULT_BLOB_TTL_MS, DEFAULT_DIRECT_THRESHOLD_BYTES,
+  BlobError, BlobSizeError, BlobExpiryError, BlobNotFoundError, BlobUploadError,
+  BlobFetchError, BlobIntegrityError, BlobRefError, BlobBrokerError, BlobSenderKeyError,
+  blobAad, encryptBlob, decryptBlob, contentHash, mkObjectName,
+  signBlobRef, verifyBlobRefSig, blobRefMetadata, blobRefSecret, refSerializedBytes,
+  makeBlobRef, validateBlobRef, envelopeBodyBytes, preflightBodyBytes, chooseTransport,
+  prepareBlobSend, fetchAndDecryptBlob, prepareBrokerBlobSend, fetchBrokerBlob,
+  SELF_CERTIFIED_KEY_ID, isSelfCertifiedUuaid, selfCertifiedUuaidFor, senderSelfCertified,
+} from "./blob/blob.mjs";
+export { MemoryBlobStore, FsBlobStore } from "./blob/store.mjs";
+export { PillarBlobHttpClient, PILLAR_BLOB_AUDIENCE } from "./blob/http.mjs";
+// Refusals in agent language: carrier reason -> one-line fix, `<code>: <fix>`.
+export { REFUSAL_FIXES, carrierFix, withCarrierFix, refusalLine, refusalFields } from "./net/refusals.mjs";

package/src/mailbox/mailbox.mjs

@@ -69,6 +69,12 @@ export class Mailbox {
     this.db.pragma("journal_mode = WAL");
     this.db.pragma("synchronous = NORMAL");
     this.db.exec(SCHEMA);
+    // v2 migration: quarantine marker (trust-policy gate). Nullable text =
+    // reason; null = normal mail. Chain hashes are unaffected (metadata only).
+    const cols = this.db.pragma("table_info(inbox)").map(c => c.name);
+    if (!cols.includes("quarantined")) {
+      this.db.exec("alter table inbox add column quarantined text");
+    }
   }
 
   close() { try { this.db.close(); } catch (_e) {} }
@@ -140,6 +146,21 @@ export class Mailbox {
     })();
   }
 
+  /** True if we sent this envelope (trust gate: is a receipt answering OUR send?). */
+  hasOutbound(envelopeId) {
+    return !!this.db.prepare("select 1 from outbox where envelope_id = ?").get(envelopeId);
+  }
+
+  /** Full outbox row by envelope id (VDA message-delivery instrument). */
+  getOutbound(envelopeId) {
+    return this.db.prepare("select * from outbox where envelope_id = ?").get(envelopeId) ?? null;
+  }
+
+  /** Full inbox row by envelope id (VDA message-delivery instrument). */
+  getInbound(envelopeId) {
+    return this.db.prepare("select * from inbox where envelope_id = ?").get(envelopeId) ?? null;
+  }
+
   markOutboundDelivered(envelopeId, ackSha256) {
     this.db.prepare("update outbox set status = 'delivered', delivered_at = ?, ack_sha256 = ? where envelope_id = ?")
       .run(new Date().toISOString(), ackSha256 ?? null, envelopeId);
@@ -155,9 +176,19 @@ export class Mailbox {
     return this.db.prepare("select * from inbox where seq > ? order by seq asc limit ?").all(seq, limit);
   }
 
-  /** Envelopes never shown to the operator (read_at null). Oldest first. */
+  /** Envelopes never shown to the operator (read_at null, not quarantined). Oldest first. */
   inboxUnread(limit = 100) {
-    return this.db.prepare("select * from inbox where read_at is null order by seq asc limit ?").all(limit);
+    return this.db.prepare("select * from inbox where read_at is null and quarantined is null order by seq asc limit ?").all(limit);
+  }
+
+  /** Trust-gated envelopes: stored as evidence, never surfaced to handlers. */
+  inboxQuarantined(limit = 100) {
+    return this.db.prepare("select * from inbox where quarantined is not null order by seq asc limit ?").all(limit);
+  }
+
+  markQuarantined(envelopeId, reason) {
+    this.db.prepare("update inbox set quarantined = ? where envelope_id = ?")
+      .run(String(reason).slice(0, 100), envelopeId);
   }
 
   markInboxRead(envelopeId) {

package/src/net/carrier-client.mjs

@@ -5,17 +5,51 @@
  * 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"]
    */
-  constructor({ keychain, carriers }) {
+  /**
+   * @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;
-    this.carriers = carriers.map(u => u.replace(/\/+$/, ""));
+    // 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;
   }
 
@@ -30,25 +64,56 @@ export class CarrierClient {
    * envelope.id and re-fires no handlers.
    *
    * Resolves once every carrier has answered.  Succeeds if at least one
-   * accepted; throws if every carrier rejects.  Returns the first-in-list
-   * accepting receipt as the primary ({ carrier, seq, sha, duplicate }) plus
-   * `all` with every carrier's outcome ({ carrier, ok, seq?, sha?,
-   * duplicate?, error? }).
+   * 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" },
+          headers: {
+            "content-type": "application/json",
+            ...(this.tierGrantB64 ? { "x-pillar-tier-grant": this.tierGrantB64 } : {}),
+          },
           body: JSON.stringify(envelope),
           signal: AbortSignal.timeout(timeoutMs),
         });
-        const body = await res.json();
+        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 };
         }
-        return { carrier: base, ok: false, error: `${res.status} ${body.reason ?? body.error ?? ""}` };
+        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 };
       }
@@ -57,9 +122,17 @@ export class CarrierClient {
       rs.map(r => r.status === "fulfilled" ? r.value : { carrier: "?", ok: false, error: String(r.reason) }));
     const accepted = all.filter(r => r.ok);
     if (!accepted.length) {
-      throw new Error(`carrier deliver failed on all carriers: ${all.map(r => `${r.carrier}: ${r.error}`).join("; ")}`);
+      const 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 { carrier, seq, sha, duplicate } = accepted[0];
+    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 };
   }
 
@@ -81,7 +154,11 @@ export class CarrierClient {
     });
     if (res.status !== 200) {
       const body = await res.json().catch(() => ({}));
-      throw new Error(`inbox fetch ${base}: ${res.status} ${body.error ?? ""}`);
+      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 }
   }
@@ -89,6 +166,8 @@ export class CarrierClient {
   /**
    * 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;
@@ -100,10 +179,10 @@ export class CarrierClient {
           for (const { seq, envelope } of r.envelopes) {
             state.cursors[base] = Math.max(state.cursors[base] ?? 0, seq);
             try { await onEnvelope(envelope, { carrier: base, seq }); }
-            catch (e) { onError?.(new Error(`onEnvelope threw: ${e.message}`)); }
+            catch (e) { onError?.(new Error(`onEnvelope threw: ${e.message}`), { carrier: base }); }
           }
         } catch (e) {
-          onError?.(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));
         }

package/src/net/carrier-server.mjs

@@ -18,14 +18,33 @@
  *       x-pillar-pubkey: <ed25519 pubkey hex>
  *       x-pillar-ts:     <unix ms>  (rejected if clock skew > 5 min)
  *       x-pillar-sig:    hex(sign("GET /v1/inbox/<uuaid>?since=<seq>" + "\n" + ts))
+ *       x-pillar-delegation: (optional) JSON delegation document letting a
+ *         delegate key read <uuaid>'s inbox; must be signed by <uuaid> and
+ *         cover kind "inbox" (or "*")
  *     - carrier derives UUAID from pubkey; must equal <uuaid>  (self-authenticating,
- *       zero registration)
+ *       zero registration) unless a valid inbox delegation is presented
  *     - long-polls up to `wait` seconds (max 30)
  *     -> 200 { envelopes: [{seq, envelope}], now }
  *
  *   GET /v1/health
  *     -> 200 { ok, uptime, stored }
  *
+ *   GET /v1/seed-info
+ *     -> 200 { v, url, uuaid, publicKey, startedAt, firstSeen, stats, now, sig }
+ *     Present only when the server was constructed with a keychain + publicUrl
+ *     (i.e. it is running as a public seed, not a private relay). The
+ *     signature binds this URL to the operator's key, which is what the seed
+ *     registry checks at enrollment before listing the URL as a seed.
+ *
+ * PRIORITY ADMISSION
+ *
+ * Load shedding is not uniform. A sender presenting a valid tier grant with
+ * `priority: true` — issued to durable seed operators by the seed registry —
+ * is admitted from reserved headroom that community traffic cannot touch:
+ * the last slice of the store, its own per-IP budget, and reserved long-poll
+ * slots. Under no load the two lanes are indistinguishable; the privilege
+ * only becomes visible at the moment the carrier starts saying no.
+ *
  * Durability: SQLite (WAL).  Envelopes are retained until TTL (default 14 days).
  * The carrier CANNOT read payloads it relays beyond what the envelope exposes,
  * and CANNOT forge envelopes (no keys).  It can only: deliver, delay, or drop —
@@ -36,10 +55,16 @@ import { createHash } from "node:crypto";
 import Database from "better-sqlite3";
 import { open as openEnvelope } from "./envelope.mjs";
 import { Keychain } from "../identity/keychain.mjs";
+import { jcs } from "../identity/jcs.mjs";
+import { verifyTierGrant } from "../identity/tier.mjs";
+import { verifyDelegationDoc, delegationCoversKind } from "./delegation.mjs";
+import { withCarrierFix } from "./refusals.mjs"; // additive `fix` on refusals; reason/error/status unchanged
 
 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;
+const MAX_DELEGATION_HEADER = 8192; // x-pillar-delegation size cap (bytes)
 // Hardening (RedTeam F2/F3):
 const MAX_ENVELOPE_AGE_MS = 24 * 3600_000; // F3: ingest freshness — reject skewed createdAt
 const RATE_WINDOW_MS = 60_000;             // F2: sliding window for all rate limits
@@ -49,9 +74,16 @@ const MAX_INVALID_PER_MIN = 60;            // F2: per client-IP budget for rejec
 const MAX_CONCURRENT_WAITS = 64;           // F2: inbox long-poll concurrency cap
 const MAX_DB_BYTES = 256 * 1024 * 1024;    // F2: SQLite size backpressure (503 when full)
 const RATE_MAP_HARD_CAP = 10_000;          // F2: bound memory under key spray
+// Priority lanes. Each is a RESERVE carved out of an existing cap, never an
+// increase of it: community traffic sheds earlier so that priority traffic
+// still fits inside the same absolute ceiling. A carrier with no trusted tier
+// issuers configured never resolves a priority grant, so these are inert.
+const COMMUNITY_DB_BYTES = Math.floor(MAX_DB_BYTES * 0.85);   // last 15% of the store is reserved
+const COMMUNITY_CONCURRENT_WAITS = 48;                        // of MAX_CONCURRENT_WAITS
+const MAX_PRIORITY_GOOD_PER_MIN = 600;                        // priority senders bill to their own per-IP bucket
 
 export class CarrierServer {
-  constructor({ dbPath = "carrier.db", ttlDays = 14, cryptoInventory } = {}) {
+  constructor({ dbPath = "carrier.db", ttlDays = 14, cryptoInventory, trustedTierIssuers = [], keychain = null, publicUrl = null } = {}) {
     this.db = new Database(dbPath);
     this.db.pragma("journal_mode = WAL");
     this.db.exec(`
@@ -65,7 +97,16 @@ export class CarrierServer {
         created_at  text not null default (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
       );
       create index if not exists idx_envelopes_recipient on envelopes(recipient, seq);
+      -- Lifetime service counters. Kept OUTSIDE the envelopes table because
+      -- vacuum() deletes envelopes at TTL, and a seed's service history must
+      -- survive its own garbage collection.
+      create table if not exists seed_stats (
+        k text primary key,
+        v text not null
+      );
     `);
+    this.db.prepare("insert or ignore into seed_stats (k, v) values ('first_seen', ?)")
+      .run(new Date().toISOString());
     this.ttlDays = ttlDays;
     this.cryptoInventory = cryptoInventory ?? { ed25519: "active" };
     this.startedAt = Date.now();
@@ -73,6 +114,94 @@ 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 }
+    // Seed identity. Optional: a private relay runs without one and simply
+    // does not expose /v1/seed-info.
+    this.keychain = keychain;
+    this.publicUrl = publicUrl ? String(publicUrl).replace(/\/+$/, "") : null;
+  }
+
+  /** Read a lifetime counter. */
+  _stat(k, fallback = 0) {
+    const row = this.db.prepare("select v from seed_stats where k = ?").get(k);
+    if (row === undefined) return fallback;
+    const n = Number(row.v);
+    return Number.isFinite(n) ? n : row.v;
+  }
+
+  /** Bump a lifetime counter by n (creating it at 0 first). */
+  _bump(k, n = 1) {
+    this.db.prepare(
+      "insert into seed_stats (k, v) values (?, ?) on conflict(k) do update set v = cast(cast(v as integer) + ? as text)"
+    ).run(k, String(n), n);
+  }
+
+  /**
+   * The signed service claim served at /v1/seed-info.
+   *
+   * These counters are the seed's OWN account of its work and are therefore
+   * not evidence: an operator can inflate them freely. The registry records
+   * them for display and promotes strictly on what it observes itself (see
+   * net/seed-tier.mjs). What the signature does prove is the thing enrollment
+   * actually needs — that whoever controls this URL also controls this key.
+   */
+  seedInfo() {
+    if (!this.keychain?._identity || !this.publicUrl) return null;
+    const doc = {
+      v: 1,
+      url: this.publicUrl,
+      uuaid: this.keychain._identity.uuaid,
+      publicKey: this.keychain._identity.publicKeyHex,
+      startedAt: new Date(this.startedAt).toISOString(),
+      firstSeen: this.db.prepare("select v from seed_stats where k = 'first_seen'").get()?.v ?? null,
+      stats: {
+        relayed: this._stat("relayed"),
+        served: this._stat("served"),
+        stored: this.db.prepare("select count(*) as n from envelopes").get().n,
+      },
+      now: new Date().toISOString(),
+    };
+    doc.sig = this.keychain.sign(Buffer.from(jcs(doc), "utf-8")).toString("hex");
+    return doc;
+  }
+
+  /**
+   * 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, priority: false };
+    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,
+          // Only a grant the issuer actually signed as priority opens the
+          // reserved lane. verifyTierGrant has already rejected any grant
+          // whose `priority` is present but not exactly true.
+          priority: grant.priority === true,
+          seedTier: grant.seedTier ?? null,
+        }
+      : 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). */
@@ -117,7 +246,7 @@ export class CarrierServer {
     // No-op on a dead socket: close() destroys connections, and a long-poll
     // handler whose timer fires afterwards must not throw on write.
     if (res.destroyed || res.writableEnded) return;
-    const body = JSON.stringify(obj);
+    const body = JSON.stringify(withCarrierFix(code, obj));
     res.writeHead(code, { "content-type": "application/json", "content-length": Buffer.byteLength(body) });
     res.end(body);
   }
@@ -127,7 +256,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,25 +264,35 @@ 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).
       if (!this._rateAllow(`bad:${ip}`, MAX_INVALID_PER_MIN)) {
         return { code: 429, body: { accepted: false, reason: "rate-limited" } };
       }
-      return { code: 400, body: { accepted: false, reason: verdict.reason } };
+      return { code: verdict.code ?? 400, body: { accepted: false, reason: verdict.reason } };
     }
     if (typeof envelope.recipient !== "string" || !envelope.recipient.startsWith("uuaid:")) {
       return { code: 400, body: { accepted: false, reason: "bad-recipient" } };
     }
+    // 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
     // fresh-keypair spray (each new key gets a fresh sender budget).
-    if (!this._rateAllow(`g:${ip}`, MAX_GOOD_PER_MIN)) {
+    // Priority senders bill to a SEPARATE bucket: the point of the lane is
+    // that a noisy neighbour behind the same egress IP (or NAT, or CI
+    // runner) cannot consume the budget a durable seed operator earned.
+    const ipKey = tier.priority ? `p:${ip}` : `g:${ip}`;
+    const ipLimit = tier.priority ? MAX_PRIORITY_GOOD_PER_MIN : MAX_GOOD_PER_MIN;
+    if (!this._rateAllow(ipKey, ipLimit)) {
       return { code: 429, body: { accepted: false, reason: "rate-limited" } };
     }
     // F3: freshness — reject envelopes whose createdAt is missing or skewed
@@ -163,10 +302,13 @@ export class CarrierServer {
       return { code: 400, body: { accepted: false, reason: "stale-envelope" } };
     }
     // F2: backpressure — refuse ingest when the store is near-full instead of
-    // failing at disk-full mid-write.
+    // failing at disk-full mid-write. Community traffic sheds at 85% so the
+    // remaining slice stays available to priority senders; the absolute cap
+    // is identical for both, so the reserve cannot push the store past it.
     const pages = this.db.pragma("page_count", { simple: true });
     const pageBytes = this.db.pragma("page_size", { simple: true });
-    if (pages * pageBytes > MAX_DB_BYTES) {
+    const storeCap = tier.priority ? MAX_DB_BYTES : COMMUNITY_DB_BYTES;
+    if (pages * pageBytes > storeCap) {
       return { code: 503, body: { accepted: false, reason: "carrier-full" } };
     }
     const sha = createHash("sha256").update(JSON.stringify(envelope)).digest("hex");
@@ -174,6 +316,7 @@ export class CarrierServer {
       const r = this.db.prepare(
         "insert into envelopes (envelope_id, recipient, sender, sha, body) values (?,?,?,?,?)"
       ).run(envelope.id, envelope.recipient, envelope.sender, sha, JSON.stringify(envelope));
+      this._bump("relayed");
       return { code: 202, body: { accepted: true, seq: Number(r.lastInsertRowid), sha } };
     } catch (e) {
       if (/UNIQUE constraint/.test(e.message)) {
@@ -198,7 +341,17 @@ export class CarrierServer {
     // Self-authenticating: UUAID must derive from the presented pubkey.
     const localId = Keychain._localIdFromKey(Buffer.from(pubkey, "hex"));
     const derived = `uuaid:foundation:agent:${localId}`;
-    if (derived !== uuaid) return { ok: false, reason: "uuaid-pubkey-mismatch" };
+    if (derived !== uuaid) {
+      // A delegate key may read the principal's inbox only by presenting the
+      // principal-signed delegation document that names it.  Without the
+      // header this stays the legacy mismatch.
+      const raw = req.headers["x-pillar-delegation"];
+      if (raw === undefined) return { ok: false, reason: "uuaid-pubkey-mismatch" };
+      const delegated = this._verifyInboxDelegation(raw, uuaid, pubkey);
+      if (!delegated.ok) return delegated;
+    }
+    // Either the principal's own key or an authorized delegate key: in both
+    // cases it must have signed THIS request.
     const message = Buffer.from(`${sincePath}\n${ts}`, "utf-8");
     let verified = false;
     try { verified = Keychain.verifyDetached(pubkey, message, Buffer.from(sig, "hex")); }
@@ -207,6 +360,37 @@ export class CarrierServer {
     return { ok: true };
   }
 
+  /**
+   * Authorize a delegate to poll `uuaid`'s inbox from an `x-pillar-delegation`
+   * header.  Fails closed on every error and never logs the document.
+   *
+   * Reasons (all surface as HTTP 401):
+   *   delegation-too-large            header exceeds MAX_DELEGATION_HEADER
+   *   delegation-unparseable          not a string / not JSON
+   *   delegation-invalid:<reason>     verifyDelegationDoc verdict (expired,
+   *                                   bad-signature, *-uuaid-binding, ...)
+   *   delegation-principal-mismatch   doc principal is not the path uuaid
+   *   delegation-delegate-key-mismatch  doc names a different delegate key
+   *   delegation-inbox-denied         kinds cover neither "inbox" nor "*"
+   */
+  _verifyInboxDelegation(raw, uuaid, pubkey) {
+    if (typeof raw !== "string") return { ok: false, reason: "delegation-unparseable" };
+    if (Buffer.byteLength(raw, "utf-8") > MAX_DELEGATION_HEADER) {
+      return { ok: false, reason: "delegation-too-large" };
+    }
+    let doc;
+    try { doc = JSON.parse(raw); }
+    catch (_e) { return { ok: false, reason: "delegation-unparseable" }; }
+    const verdict = verifyDelegationDoc(doc);
+    if (!verdict.ok) return { ok: false, reason: `delegation-invalid:${verdict.reason}` };
+    if (doc.principal !== uuaid) return { ok: false, reason: "delegation-principal-mismatch" };
+    if (doc.delegatePublicKey.toLowerCase() !== pubkey.toLowerCase()) {
+      return { ok: false, reason: "delegation-delegate-key-mismatch" };
+    }
+    if (!delegationCoversKind(doc, "inbox")) return { ok: false, reason: "delegation-inbox-denied" };
+    return { ok: true };
+  }
+
   async _handleInbox(req, res, uuaid, url) {
     const since = Number(url.searchParams.get("since") ?? 0);
     const wait = Math.min(Number(url.searchParams.get("wait") ?? 0), MAX_WAIT_S);
@@ -215,8 +399,13 @@ export class CarrierServer {
     if (!auth.ok) return this._json(res, 401, { error: auth.reason });
 
     // F2: cap concurrent long-polls so sleeping connections cannot pin the
-    // event loop / fd table.
-    if (wait > 0 && this.activeWaits >= MAX_CONCURRENT_WAITS) {
+    // event loop / fd table. The grant is resolved against the PRINCIPAL
+    // whose inbox this is (the path uuaid), not the key that signed — a
+    // delegate polling for a priority principal inherits the reserved slots,
+    // which is the same authority it already has to read the mail.
+    const tier = this._resolveTier(req, uuaid);
+    const waitCap = tier.priority ? MAX_CONCURRENT_WAITS : COMMUNITY_CONCURRENT_WAITS;
+    if (wait > 0 && this.activeWaits >= waitCap) {
       return this._json(res, 503, { error: "busy" });
     }
     if (wait > 0) this.activeWaits++;
@@ -237,6 +426,7 @@ export class CarrierServer {
         await new Promise(r => setTimeout(r, 400));
         rows = fetchRows();
       }
+      if (rows.length) this._bump("served", rows.length);
       this._json(res, 200, {
         envelopes: rows.map(r => ({ seq: r.seq, envelope: JSON.parse(r.body) })),
         now: Date.now(),
@@ -255,7 +445,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);
@@ -264,6 +454,13 @@ export class CarrierServer {
           if (!uuaid.startsWith("uuaid:")) return this._json(res, 404, { error: "not-found" });
           return await this._handleInbox(req, res, uuaid, url);
         }
+        if (req.method === "GET" && url.pathname === "/v1/seed-info") {
+          const info = this.seedInfo();
+          // A relay with no seed identity is not a seed and must not look
+          // like one to the registry.
+          if (!info) return this._json(res, 404, { error: "not-a-seed" });
+          return this._json(res, 200, info);
+        }
         if (req.method === "GET" && url.pathname === "/v1/health") {
           const stored = this.db.prepare("select count(*) as n from envelopes").get().n;
           return this._json(res, 200, { ok: true, uptimeMs: Date.now() - this.startedAt, stored });