@uuaid/pillar 0.2.0-alpha.9 → 2.0.2

package/bin/pillar-responder.mjs

@@ -27,10 +27,11 @@
  * Carrier-only by default (outbound HTTPS only — runs on any machine or
  * webserver; no inbound ports, no libp2p).  Pass --libp2p to also listen.
  *
- *   pillar-responder --home ~/.pillar-fleet/zz-master-responder \
- *     --reply-text "zz-master is away — left a message" \
+ *   pillar-responder --home ~/.pillar-responder \
+ *     --reply-text "my-agent is away — left a message" \
  *     --forward-to uuaid:foundation:agent:… --forward-pubkey <hex>
  */
+import "../src/node-check.mjs"; // must stay the first import: refuses Node < 22 before any dependency loads
 import { existsSync, readFileSync, appendFileSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
@@ -38,11 +39,16 @@ import { argv, exit } from "node:process";
 import { spawn } from "node:child_process";
 import { Keychain } from "../src/identity/keychain.mjs";
 import { Pillar } from "../src/pillar.mjs";
+import { loadTrustPolicy, evaluateTrust, POLICIES } from "../src/identity/trust.mjs";
+import { loadFleetAddressBook } from "../src/address-book.mjs";
 
 const DEFAULT_REPLY = "pillar-responder: request acked — owner will respond through the normal channel";
+const STRANGER_REPLY = "pillar-responder: request received. This responder runs its command hook only for enrolled senders; ask the operator to `pillar trust allow` your uuaid.";
 const MAX_REPLY_BYTES = 8192;
 const HOOK_TIMEOUT_MS = 60_000;
 const REPLAY_WINDOW_MS = 24 * 3600_000;
+const SENDER_REPLIES_PER_HOUR = 30; // amplification cap: max hook/reply cycles per sender
+const RATE_WINDOW_MS = 3600_000;
 
 function parseArgs(argv) {
   const args = { _: [] };
@@ -162,6 +168,26 @@ if (!carriers.length && !enableLibp2p) {
 
 const replyText = args["reply-text"] ?? rcfg.replyText ?? DEFAULT_REPLY;
 const hookCmd = args.command ?? rcfg.command ?? null;
+// Trust gate. Default policy for the COMMAND HOOK is "directory": strangers
+// still get ack + a fixed reply (universality preserved — first contact
+// works), but attacker-controlled JSON only reaches the hook process from
+// senders the operator knows. --hook-policy open restores old behavior.
+const trust = loadTrustPolicy(home);
+const hookPolicy = args["hook-policy"] ?? rcfg.hookPolicy ?? "directory";
+if (!POLICIES.includes(hookPolicy)) {
+  console.error(`--hook-policy must be one of ${POLICIES.join("|")}`);
+  exit(2);
+}
+const senderRate = new Map(); // sender uuaid -> [ms timestamps]
+function senderAllowed(sender) {
+  const now = Date.now();
+  let arr = senderRate.get(sender);
+  if (!arr) { arr = []; senderRate.set(sender, arr); }
+  while (arr.length && now - arr[0] > RATE_WINDOW_MS) arr.shift();
+  if (arr.length >= SENDER_REPLIES_PER_HOUR) return false;
+  arr.push(now);
+  return true;
+}
 const hookTimeoutMs = Number(args["timeout-ms"] ?? rcfg.timeoutMs ?? HOOK_TIMEOUT_MS);
 const hookMaxBytes = Number(args["max-reply-bytes"] ?? MAX_REPLY_BYTES);
 const fwd = args["forward-to"] || rcfg.forwardTo?.uuaid
@@ -187,10 +213,14 @@ const p = new Pillar({
 
 await p.start();
 
+// Address book feeds the "directory" hook policy (known senders = fleet.json).
+const abCount = loadFleetAddressBook(join(home, "fleet.json"), p);
+
 console.log(`pillar-responder up — ${p.uuaid}`);
 console.log(`  pubkey:    ${p.publicKeyHex}`);
 console.log(`  carriers:  ${carriers.length ? carriers.join(", ") : "(none — libp2p only)"}`);
 console.log(`  reply:     ${hookCmd ? `hook ${hookCmd}` : "builtin text"}`);
+if (hookCmd) console.log(`  hook gate: policy=${hookPolicy}, known senders=${abCount}, cap=${SENDER_REPLIES_PER_HOUR}/h per sender`);
 if (fwd) console.log(`  forwardTo: ${fwd.uuaid}`);
 
 // Replay journaled-but-unfinished requests first (at-least-once).
@@ -215,7 +245,21 @@ p.onEnvelope(async (env) => {
     const thread = env.payload?.thread ?? env.id;
     let status = "ok";
     let text = replyText;
-    if (hookCmd) {
+    // Amplification cap: over-budget senders get ack only, no reply/hook.
+    if (!senderAllowed(env.sender)) {
+      await p.send({ recipient: env.sender, recipientPublicKey: senderKey, kind: "ack", payload: { inReplyTo: env.id } });
+      journalDone(home, env.id, { text: "(rate-capped: ack only)", status: "capped" });
+      console.log(`  ${env.sender.slice(-8)} request ${env.id.slice(0, 16)}… → ack only (rate cap)`);
+      return;
+    }
+    // Hook gate: strangers get the fixed reply, never the command hook.
+    const gate = evaluateTrust({ ...trust, policy: hookPolicy }, env.sender, new Set(p.addressBook?.keys() ?? []));
+    if (gate.reason === "blocked") {
+      journalDone(home, env.id, { text: "(blocked sender: dropped)", status: "blocked" });
+      console.log(`  ${env.sender.slice(-8)} request ${env.id.slice(0, 16)}… → dropped (blocked)`);
+      return;
+    }
+    if (hookCmd && gate.deliver) {
       const r = await runHook(hookCmd, {
         id: env.id,
         sender: env.sender,
@@ -229,6 +273,8 @@ p.onEnvelope(async (env) => {
         status = "error";
         text = r.reason;
       }
+    } else if (hookCmd && !gate.deliver) {
+      text = STRANGER_REPLY; // stranger: fixed reply, hook never sees the payload
     }
     await p.send({ recipient: env.sender, recipientPublicKey: senderKey, kind: "ack", payload: { inReplyTo: env.id } });
     const replyPayload = { thread, inReplyTo: env.id, status, text };

package/bin/pillar-seed.mjs

@@ -4,6 +4,8 @@
  * the p2p store-and-forward mesh, like a LimeWire/BitTorrent seed peer.
  *
  *   pillar-seed --port 8799 --db /opt/pillar-seed/seed.db
+ *   pillar-seed --public-url https://seed.example.org --announce https://pillar.uuaid.org
+ *   pillar-seed --status --announce https://pillar.uuaid.org
  *
  * A seed IS a carrier server with a public URL — nothing else.  Agents
  * anywhere list your URL in their carriers[] and then:
@@ -13,18 +15,36 @@
  * Minimal ongoing requirements: one process, one SQLite file, outbound-free
  * (all traffic comes TO you).  That is the whole contract.
  *
- * Defaults to loopback (RedTeam F5).  To become a real seed, put it behind a
- * TLS-terminating proxy (nginx/Caddy) and advertise the PUBLIC https:// URL —
- * never the loopback one — as a seeds[] entry in a pillar directory.json:
+ * JOINING
+ *
+ * Announce yourself to a registry with --announce and you are enrolled: the
+ * registry fetches /v1/seed-info from the URL you gave, checks that it is
+ * signed by your seed key, and lists you.  No account, no review, no waiting
+ * on whoever owns the directory file.
+ *
+ * WHAT YOU EARN
+ *
+ * The registry then probes you — liveness plus a real envelope round-tripped
+ * through your seed — and promotes you as the evidence accumulates:
+ *
+ *   probation -> steady (a day) -> durable (a week) -> anchor (a month)
  *
- *   { "url": "https://<your-host>", "operator": "<you>", "region": "<region>", "since": "<ISO date>" }
+ * From `steady` up, your OWN identity is issued a signed tier grant: raised
+ * send budgets at every carrier that trusts the registry's issuer key.  From
+ * `durable` up that grant also carries priority, which reserves you
+ * admission capacity at those carriers when they are shedding load.  Run
+ * --status to see your rung and exactly what is left to reach the next one.
  *
- * Anyone running `pillar init --directory <directory-url>` then picks you up
- * automatically as one of their carriers.  You can also be someone's ENTIRE
- * carrier set (`--carriers https://<your-host>`) — two agents can talk with
- * only your seed between them, no official carrier involved.
+ * Defaults to loopback (RedTeam F5).  To become a real seed, put it behind a
+ * TLS-terminating proxy (nginx/Caddy) and pass the PUBLIC https:// URL as
+ * --public-url — never the loopback one.
  */
+import "../src/node-check.mjs"; // must stay the first import: refuses Node < 22 before any dependency loads
+import { mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
 import { CarrierServer } from "../src/net/carrier-server.mjs";
+import { Keychain } from "../src/identity/keychain.mjs";
 
 function parseArgs(argv) {
   const args = {};
@@ -39,16 +59,68 @@ function parseArgs(argv) {
 }
 
 const args = parseArgs(process.argv.slice(2));
+const home = args.home ?? process.env.SEED_HOME ?? join(homedir(), ".pillar-seed");
 const port = Number(args.port ?? process.env.SEED_PORT ?? 8799);
 const host = args.host ?? process.env.SEED_HOST ?? "127.0.0.1";
 const dbPath = args.db ?? process.env.SEED_DB ?? "pillar-seed.db";
 const ttlDays = Number(args.ttl ?? process.env.SEED_TTL_DAYS ?? 14);
+const publicUrl = args["public-url"] ?? process.env.SEED_PUBLIC_URL ?? null;
+const registryUrl = typeof args.announce === "string" ? args.announce.replace(/\/+$/, "") : null;
+const operator = args.operator ?? process.env.SEED_OPERATOR ?? null;
+const region = args.region ?? process.env.SEED_REGION ?? null;
+
+/**
+ * The seed's identity. Distinct from any agent keychain on the box: it names
+ * the SEED, is what /v1/seed-info is signed with, and is the subject of any
+ * tier grant the seed earns.
+ */
+mkdirSync(home, { recursive: true });
+const keychain = new Keychain(join(home, "seed-keychain.json"));
+if (!keychain.exists()) {
+  keychain.save(Keychain.generate());
+  console.log(`minted seed identity -> ${join(home, "seed-keychain.json")}`);
+}
+keychain.load();
 
-const server = new CarrierServer({ dbPath, ttlDays });
+/** Ask a registry where we stand and print the ladder position. */
+async function printStanding(registry, uuaid) {
+  try {
+    const res = await fetch(`${registry}/v1/seeds/${encodeURIComponent(uuaid)}`);
+    if (res.status === 404) {
+      console.log(`  standing: not enrolled at ${registry} — run with --announce ${registry}`);
+      return;
+    }
+    if (!res.ok) { console.log(`  standing: registry ${res.status}`); return; }
+    const s = await res.json();
+    console.log(`  tier:    ${s.tier}${s.demoted ? " (DEMOTED — failing probes)" : ""} — ${s.blurb}`);
+    console.log(`  earned:  ${s.grantTier ? `${s.grantTier} grant${s.priority ? " + priority delivery" : ""}` : "nothing yet"}`);
+    const o = s.observed ?? {};
+    console.log(`  observed: ${o.probes?.passed ?? 0}/${o.probes?.total ?? 0} probes (${((o.uptime ?? 0) * 100).toFixed(1)}% uptime), ${o.roundTrips?.passed ?? 0} relay round-trips`);
+    if (s.next) console.log(`  next:    ${s.next} — needs ${s.missing.join(", ")}`);
+    else if (!s.demoted) console.log(`  next:    top of the ladder`);
+  } catch (e) {
+    console.log(`  standing: unreachable — ${e.message}`);
+  }
+}
+
+// --status is a query, not a server: report and exit.
+if (args.status) {
+  if (!registryUrl) {
+    console.error("--status needs --announce <registry-url> to know which registry to ask");
+    process.exit(1);
+  }
+  console.log(`seed ${keychain._identity.uuaid}`);
+  await printStanding(registryUrl, keychain._identity.uuaid);
+  process.exit(0);
+}
+
+const server = new CarrierServer({ dbPath, ttlDays, keychain, publicUrl });
 const addr = await server.listen(port, host);
 console.log(`pillar-seed listening on http://${addr.address}:${addr.port}`);
+console.log(`  uuaid: ${keychain._identity.uuaid}`);
 console.log(`  db:  ${dbPath}`);
 console.log(`  ttl: ${ttlDays} days`);
+if (publicUrl) console.log(`  public url: ${publicUrl}`);
 
 // Boot self-check on the address we actually serve — verify before claim.
 try {
@@ -60,11 +132,39 @@ try {
   console.log(`  health: unreachable — ${e.message}`);
 }
 
-if (host === "127.0.0.1") {
+if (registryUrl) {
+  if (!publicUrl) {
+    console.log(`\n  --announce needs --public-url <https://your-host>: the registry enrolls a URL,`);
+    console.log(`  and it must be one it can reach and that you can prove you operate.`);
+  } else {
+    console.log(`\n  announcing ${publicUrl} to ${registryUrl} ...`);
+    try {
+      const res = await fetch(`${registryUrl}/v1/seeds`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ url: publicUrl, operator, region }),
+      });
+      const body = await res.json().catch(() => ({}));
+      if (res.ok && body.ok) {
+        console.log(`  enrolled${body.already ? " (already)" : ""} as ${body.uuaid}`);
+        await printStanding(registryUrl, keychain._identity.uuaid);
+      } else {
+        console.log(`  enrollment refused: ${body.reason ?? res.status}`);
+        if (String(body.reason ?? "").startsWith("seed-unreachable")) {
+          console.log(`  (the registry could not fetch ${publicUrl}/v1/seed-info — check DNS, TLS, and your proxy)`);
+        }
+      }
+    } catch (e) {
+      console.log(`  enrollment failed: ${e.message}`);
+    }
+  }
+} else if (host === "127.0.0.1") {
   console.log(`\n  loopback seed — reachable only from this machine.`);
-  console.log(`  To join the mesh as a real seed: TLS-terminate a public URL and list it:`);
-  console.log(`    { "url": "https://<your-host>", "operator": "<you>", "region": "<region>", "since": "${new Date().toISOString().slice(0, 10)}" }`);
-  console.log(`  in the seeds[] array of your pillar directory.json.`);
+  console.log(`  To join the mesh as a real seed: TLS-terminate a public URL, then`);
+  console.log(`    pillar-seed --host 0.0.0.0 --public-url https://<your-host> \\`);
+  console.log(`                --announce https://pillar.uuaid.org --operator <you> --region <region>`);
+  console.log(`  Enrollment is permissionless: the registry verifies the URL against your`);
+  console.log(`  seed key and lists you. Staying up is what earns the rest.`);
 }
 
 // Vacuum expired envelopes hourly.

package/bin/pillar.mjs

@@ -9,11 +9,14 @@
  *   pillar recv  [--home ~/.pillar] [--follow]   listen for envelopes and print them
  *   pillar inbox [--home ~/.pillar] [--unread] [--notify CMD] [--mark-read]
  *                                                one-shot: pull pending mail, print, exit
+ *   pillar trust [set|allow|block|unlist|quarantine]   recipient consent policy
+ *   pillar tier  [issue|install|verify]          signed volume/size tier grants
  *   pillar peers                                 list currently connected peers
  *
  * All commands respect --home to point at an alternate pillar directory,
  * useful for running multiple pillars on one machine (Zestro dogfood etc.).
  */
+import "../src/node-check.mjs"; // must stay the first import: refuses Node < 22 before any dependency loads
 import { mkdirSync, existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { homedir } from "node:os";
@@ -21,6 +24,10 @@ import { argv, exit } from "node:process";
 import { Keychain } from "../src/identity/keychain.mjs";
 import { Pillar } from "../src/pillar.mjs";
 import { loadFleetAddressBook } from "../src/address-book.mjs";
+import { loadTrustPolicy, POLICIES } from "../src/identity/trust.mjs";
+import { parseLinkOffer, isLinkOfferLive, LINK_GRANT_KINDS } from "../src/net/link-offer.mjs";
+import { mintDelegationDoc } from "../src/net/delegation.mjs";
+import { refusalLine } from "../src/net/refusals.mjs";
 
 function parseArgs(argv) {
   const args = { _: [] };
@@ -60,6 +67,19 @@ function loadPillar(args) {
   const carriers = args.carrier
     ? [args.carrier]
     : (process.env.PILLAR_CARRIERS ? process.env.PILLAR_CARRIERS.split(",") : (cfg.carriers ?? []));
+  // Trust gate: --policy overrides trust.json's policy for this invocation.
+  const trust = loadTrustPolicy(home);
+  if (args.policy) {
+    if (!POLICIES.includes(args.policy)) {
+      console.error(`--policy must be one of ${POLICIES.join("|")}`);
+      exit(2);
+    }
+    trust.policy = args.policy;
+  }
+  // Tier grant: <home>/tier-grant.json (issued via `pillar tier issue`) is
+  // attached to carrier delivers — raises budgets at carriers trusting the issuer.
+  const tgPath = join(home, "tier-grant.json");
+  const tierGrant = existsSync(tgPath) ? JSON.parse(readFileSync(tgPath, "utf-8")) : null;
   return new Pillar({
     keychain: kc,
     mailboxPath: mbPath,
@@ -69,6 +89,8 @@ function loadPillar(args) {
     dhtClientMode: cfg.dhtClientMode ?? true,
     carriers,
     enableLibp2p: !(args["carrier-only"] || cfg.carrierOnly === true),
+    trust,
+    tierGrant,
   });
 }
 
@@ -247,6 +269,121 @@ async function cmdSend(args) {
   }
 }
 
+
+// ── delegate ──────────────────────────────────────────────────────────────────
+// The desktop-link ceiling enforced by chat-web (browser-chat-session.ts,
+// LINK_TTL_MS). A grant with a longer window verifies fine and is then DROPPED
+// by the browser without a word, so this side refuses it loudly instead.
+const LINK_TTL_DAYS_MAX = 7;
+
+/**
+ * pillar delegate --to-browser '<uuaid://link/...>'
+ *
+ * Pair a browser tab to THIS pillar identity. The tab publishes an offer
+ * carrying its own freshly minted device key; this mints a delegation naming
+ * that key as delegate and this identity as principal, and sends it as a
+ * `_link` grant to the tab's inbox.
+ *
+ * The persona seed never leaves this machine — only a signed, time-boxed
+ * document does. Identical in every respect to what a phone sends: the
+ * handshake authenticates the PRINCIPAL (the envelope sender must equal the
+ * delegation principal), and never the kind of device the principal runs on.
+ * That is what lets a headless agent hold a desktop.
+ */
+async function cmdDelegate(args) {
+  const offerRaw = typeof args["to-browser"] === "string" ? args["to-browser"] : args._[1];
+  if (!offerRaw || args["to-browser"] === true) {
+    console.error("usage: pillar delegate --to-browser '<uuaid://link/...>' [--ttl-days N] [--name NAME]");
+    console.error("  Paste the offer string the browser shows under its QR code.");
+    exit(2);
+  }
+
+  const offer = parseLinkOffer(offerRaw);
+  if (!offer) {
+    console.error("not a valid link offer. Expected: uuaid://link/<delegate-uuaid>?pk=<64hex>&nonce=<hex>&exp=<iso>");
+    exit(2);
+  }
+  if (!isLinkOfferLive(offer)) {
+    console.error(`offer expired at ${offer.exp} — reload the browser tab for a fresh one`);
+    exit(1);
+  }
+
+  const ttlDays = args["ttl-days"] !== undefined ? Number(args["ttl-days"]) : LINK_TTL_DAYS_MAX;
+  if (!Number.isFinite(ttlDays) || ttlDays <= 0) {
+    console.error("--ttl-days must be a positive number");
+    exit(2);
+  }
+  // Refuse rather than mint a grant the far side discards in silence.
+  if (ttlDays > LINK_TTL_DAYS_MAX) {
+    console.error(`--ttl-days ${ttlDays} exceeds the ${LINK_TTL_DAYS_MAX}-day desktop-link ceiling.`);
+    console.error("A longer grant is a VALID document that the browser drops without reporting why.");
+    exit(2);
+  }
+
+  const p = loadPillar(args);
+  await p.start();
+  try {
+    const me = p.keychain._identity;
+    const delegation = mintDelegationDoc(p.keychain, {
+      delegate: offer.delegate,
+      delegatePublicKey: offer.pk,
+      kinds: [...LINK_GRANT_KINDS], // never "*": that would let the desktop read this identity's inbox
+      ttlDays,
+    });
+
+    // The snapshot's persona MUST equal the delegation principal exactly — the
+    // browser rejects the whole grant on any mismatch, treating a disagreeing
+    // snapshot as evidence that neither half can be trusted.
+    // fleet.json is { fleet: { "<role>": { uuaid, publicKey, ... } } } — keyed by
+    // ROLE, which is also the human-readable name the desktop shows. A row
+    // without a publicKey cannot be sealed to, so it is not a contact.
+    const contacts = [];
+    const fp = fleetPath(args);
+    if (existsSync(fp)) {
+      let fleet = {};
+      try {
+        fleet = JSON.parse(readFileSync(fp, "utf-8")).fleet ?? {};
+      } catch {
+        console.error(`warning: ${fp} is not readable JSON — sending 0 contacts`);
+      }
+      for (const [role, entry] of Object.entries(fleet)) {
+        if (typeof entry?.uuaid !== "string" || typeof entry?.publicKey !== "string") continue;
+        contacts.push({ uuaid: entry.uuaid, publicKey: entry.publicKey, name: String(role) });
+      }
+    }
+
+    const payload = {
+      _link: { v: 1, op: "grant", nonce: offer.nonce },
+      delegation,
+      snapshot: {
+        persona: { uuaid: me.uuaid, publicKey: me.publicKeyHex },
+        displayName: typeof args.name === "string" ? args.name : null,
+        contacts,
+      },
+    };
+
+    const { envelope } = await p.send({
+      recipient: offer.delegate,
+      kind: "message",
+      payload,
+      recipientPublicKey: offer.pk,
+      resolveTimeoutMs: 5000,
+    });
+
+    console.log(`linked ${offer.delegate}`);
+    console.log(`  principal: ${me.uuaid}`);
+    console.log(`  window:    ${delegation.notBefore} -> ${delegation.notAfter} (${ttlDays}d)`);
+    console.log(`  contacts:  ${contacts.length}`);
+    console.log(`  envelope:  ${envelope.id}`);
+    console.log("");
+    console.log("The tab pairs when it polls. If it does not, the grant was refused in");
+    console.log("silence — check the offer is unexpired and unclaimed, and that the tab");
+    console.log("still shows the same QR (a reload rotates the nonce and voids this grant).");
+  } finally {
+    await p.stop();
+  }
+}
+
 async function cmdSendGroup(args) {
   const [groupName, kind, jsonStr] = args._.slice(1);
   if (!groupName || !kind) {
@@ -268,7 +405,7 @@ async function cmdSendGroup(args) {
     let failed = 0;
     for (const r of results) {
       if (r.ok) console.log(`  ✓ ${r.member}  via ${r.via}  ${r.envelopeId}`);
-      else { failed++; console.error(`  ✗ ${r.member}  ${r.error}`); }
+      else { failed++; console.error(`  ✗ ${r.member}  ${refusalLine(r) ?? r.error}`); }
     }
     console.log(`group "${groupName}": ${results.length - failed}/${results.length} delivered`);
     if (failed) exit(1);
@@ -377,7 +514,7 @@ async function cmdRecv(args) {
           await p.send({ recipient: env.sender, recipientPublicKey: senderKey, kind: "reply", payload: { thread, inReplyTo: env.id, status: "error", reason: e.message.slice(0, 300), text: `zestro bridge error: ${e.message.slice(0, 300)}` } });
         }
       }
-    } else if (bridge) {
+    } else if (bridge && env.kind !== "ack" && env.kind !== "reply") {
       try {
         const result = await bridge.sendCommand({ command: JSON.stringify({ kind: env.kind, payload: env.payload, sender: env.sender }) });
         console.log(`  → zestro result: ${JSON.stringify(result).slice(0, 200)}`);
@@ -390,6 +527,10 @@ async function cmdRecv(args) {
           console.error(`  → zestro bridge error: ${e.message}`);
         }
       }
+    } else if (bridge) {
+      // ack/reply are receipts for OUR earlier sends — bridging them would
+      // inject a Zestro agent turn per receipt. Print-only (line above).
+      console.log(`  → zestro: not bridged (kind=${env.kind} is a receipt)`);
     }
   });
 
@@ -410,9 +551,16 @@ async function cmdInbox(args) {
   const fresh = [];
   p.onEnvelope((env) => { fresh.push(env); });
   await p.start();
+  // Address book BEFORE the drain: the trust "directory" policy needs known
+  // senders loaded, or every fresh envelope counts as a stranger.
+  loadFleetAddressBook(fleetPath(args), p);
   const pulled = await p.drainCarrierInbox();
+  // fromPublicKey: the sender's verified Ed25519 key (transportSignature —
+  // open() binds it to `from`). Lets a drain-and-reply consumer (the fleet
+  // courier's auto-ack, a bot) seal back to a sender who is NOT in fleet.json
+  // via `pillar send … --to-pubkey <fromPublicKey>`. Additive field.
   for (const env of fresh) {
-    console.log(JSON.stringify({ new: true, id: env.id, from: env.sender, kind: env.kind, at: env.createdAt, payload: env.payload }));
+    console.log(JSON.stringify({ new: true, id: env.id, from: env.sender, fromPublicKey: env.transportSignature?.publicKey ?? null, kind: env.kind, at: env.createdAt, payload: env.payload }));
   }
   // Backlog: rows stored earlier (e.g. by a recv daemon) but never surfaced.
   const { decrypt } = await import("../src/net/envelope.mjs");
@@ -423,10 +571,11 @@ async function cmdInbox(args) {
       const env = JSON.parse(row.envelope_json);
       let payload = null;
       try { payload = decrypt(p.keychain, env); } catch (_e) { payload = { error: "decrypt failed" }; }
-      console.log(JSON.stringify({ new: false, id: env.id, from: env.sender, kind: env.kind, at: env.createdAt, payload }));
+      console.log(JSON.stringify({ new: false, id: env.id, from: env.sender, fromPublicKey: env.transportSignature?.publicKey ?? null, kind: env.kind, at: env.createdAt, payload }));
     }
   }
-  console.log(`inbox: ${pulled} new, ${backlog.length} older unread${args.unread ? "" : " (--unread to print)"}`);
+  const qCount = (p.mailbox.inboxQuarantined?.(500) ?? []).length;
+  console.log(`inbox: ${fresh.length} new, ${backlog.length} older unread${args.unread ? "" : " (--unread to print)"}${qCount ? `, ${qCount} quarantined (pillar trust quarantine)` : ""}`);
   if (args["mark-read"]) {
     for (const env of fresh) p.mailbox.markInboxRead?.(env.id);
     if (args.unread) for (const row of backlog) p.mailbox.markInboxRead?.(row.envelope_id);
@@ -445,6 +594,144 @@ async function cmdInbox(args) {
   exit(0);
 }
 
+async function cmdTrust(args) {
+  // pillar trust                          show policy + lists + quarantine count
+  // pillar trust set <open|directory|allowlist>
+  // pillar trust allow|block <uuaid>      add to list (removes from the other)
+  // pillar trust unlist <uuaid>           remove from both lists
+  // pillar trust quarantine [--release ID]  list quarantined mail / release one
+  const home = homePath(args);
+  const tPath = join(home, "trust.json");
+  const t = loadTrustPolicy(home);
+  const sub = args._[1];
+  const save = () => writeFileSync(tPath, JSON.stringify({ policy: t.policy, allow: t.allow, block: t.block }, null, 2));
+  if (!sub) {
+    console.log(`policy: ${t.policy}${t.exists ? "" : " (no trust.json — default)"}`);
+    console.log(`allow (${t.allow.length}):`); for (const u of t.allow) console.log(`  ${u}`);
+    console.log(`block (${t.block.length}):`); for (const u of t.block) console.log(`  ${u}`);
+    const { Mailbox } = await import("../src/mailbox/mailbox.mjs");
+    const mb = new Mailbox(join(home, "mailbox.db"));
+    const q = mb.inboxQuarantined(500);
+    console.log(`quarantined: ${q.length} (pillar trust quarantine to list)`);
+    mb.close();
+    return;
+  }
+  if (sub === "set") {
+    const pol = args._[2];
+    if (!POLICIES.includes(pol)) { console.error(`usage: pillar trust set <${POLICIES.join("|")}>`); exit(2); }
+    t.policy = pol; save();
+    console.log(`policy: ${pol} (${tPath})`);
+    return;
+  }
+  if (sub === "allow" || sub === "block") {
+    const u = args._[2];
+    if (!u?.startsWith("uuaid:")) { console.error(`usage: pillar trust ${sub} <uuaid:...>`); exit(2); }
+    t.allow = t.allow.filter(x => x !== u);
+    t.block = t.block.filter(x => x !== u);
+    t[sub === "allow" ? "allow" : "block"].push(u);
+    save();
+    console.log(`${sub}: ${u}`);
+    return;
+  }
+  if (sub === "unlist") {
+    const u = args._[2];
+    t.allow = t.allow.filter(x => x !== u);
+    t.block = t.block.filter(x => x !== u);
+    save();
+    console.log(`unlisted: ${u}`);
+    return;
+  }
+  if (sub === "quarantine") {
+    const { Mailbox } = await import("../src/mailbox/mailbox.mjs");
+    const mb = new Mailbox(join(home, "mailbox.db"));
+    if (args.release) {
+      mb.db.prepare("update inbox set quarantined = null where envelope_id = ?").run(args.release);
+      console.log(`released: ${args.release} (now visible to pillar inbox --unread)`);
+      mb.close();
+      return;
+    }
+    for (const row of mb.inboxQuarantined(500)) {
+      console.log(JSON.stringify({ id: row.envelope_id, from: row.sender, reason: row.quarantined, at: row.received_at }));
+    }
+    mb.close();
+    return;
+  }
+  console.error("usage: pillar trust [set <policy>|allow <uuaid>|block <uuaid>|unlist <uuaid>|quarantine [--release ID]]");
+  exit(2);
+}
+
+async function cmdTier(args) {
+  // pillar tier                                    show installed grant
+  // pillar tier issue <uuaid> <tier> [--expires ISO] [--rate N] [--max-body N] [--out FILE]
+  //                                                sign a grant with THIS home's key (issuer)
+  // pillar tier install <grant.json>               install a received grant into this home
+  // pillar tier verify <grant.json> --issuer HEX   verify signature/expiry locally
+  const { makeTierGrant, verifyTierGrant, grantFingerprint, TIER_DEFAULTS } =
+    await import("../src/identity/tier.mjs");
+  const home = homePath(args);
+  const sub = args._[1];
+  if (!sub) {
+    const tgPath = join(home, "tier-grant.json");
+    if (!existsSync(tgPath)) { console.log("no tier grant installed (community tier)"); return; }
+    const g = JSON.parse(readFileSync(tgPath, "utf-8"));
+    console.log(`tier: ${g.tier}  rate: ${g.envelopesPerMin}/min  maxBody: ${g.maxBodyBytes}B`);
+    console.log(`subject: ${g.uuaid}`);
+    console.log(`issuer:  ${g.issuer}`);
+    console.log(`expires: ${g.expires}  fingerprint: ${grantFingerprint(g)}`);
+    return;
+  }
+  if (sub === "issue") {
+    const [, , uuaid, tier] = args._;
+    if (!uuaid || !TIER_DEFAULTS[tier]) {
+      console.error(`usage: pillar tier issue <uuaid:...> <${Object.keys(TIER_DEFAULTS).join("|")}> [--expires ISO] [--rate N] [--max-body BYTES] [--out FILE]`);
+      exit(2);
+    }
+    const kc = new Keychain(join(home, "keychain.json"));
+    kc.load({ passphrase: process.env.PILLAR_PASSPHRASE ?? "" });
+    const expires = args.expires ?? new Date(Date.now() + 365 * 86400_000).toISOString();
+    const grant = makeTierGrant(kc, {
+      uuaid, tier, expires,
+      envelopesPerMin: args.rate ? Number(args.rate) : undefined,
+      maxBodyBytes: args["max-body"] ? Number(args["max-body"]) : undefined,
+    });
+    const out = typeof args.out === "string" ? args.out : `tier-grant-${grantFingerprint(grant)}.json`;
+    writeFileSync(out, JSON.stringify(grant, null, 2));
+    console.log(`issued ${tier} grant for ${uuaid}`);
+    console.log(`  rate ${grant.envelopesPerMin}/min, maxBody ${grant.maxBodyBytes}B, expires ${expires}`);
+    console.log(`  issuer ${grant.issuer}`);
+    console.log(`  -> ${out} (send to the grantee; they run: pillar tier install ${out})`);
+    return;
+  }
+  if (sub === "install") {
+    const file = args._[2];
+    if (!file || !existsSync(file)) { console.error("usage: pillar tier install <grant.json>"); exit(2); }
+    const g = JSON.parse(readFileSync(file, "utf-8"));
+    const kc = new Keychain(join(home, "keychain.json"));
+    kc.load({ passphrase: process.env.PILLAR_PASSPHRASE ?? "" });
+    if (g.uuaid !== kc._identity.uuaid) {
+      console.error(`grant subject ${g.uuaid} != this home's identity ${kc._identity.uuaid}`);
+      exit(1);
+    }
+    const v = verifyTierGrant(g, [g.issuer]); // structural check (sig by named issuer, expiry, ceilings)
+    if (!v.ok) { console.error(`grant invalid: ${v.reason}`); exit(1); }
+    writeFileSync(join(home, "tier-grant.json"), JSON.stringify(g, null, 2));
+    console.log(`installed ${g.tier} grant (fingerprint ${grantFingerprint(g)}) — sent with every carrier deliver`);
+    console.log(`note: budgets rise only at carriers that trust issuer ${g.issuer.slice(0, 16)}…`);
+    return;
+  }
+  if (sub === "verify") {
+    const file = args._[2];
+    const issuer = args.issuer;
+    if (!file || !existsSync(file) || !issuer) { console.error("usage: pillar tier verify <grant.json> --issuer HEX"); exit(2); }
+    const g = JSON.parse(readFileSync(file, "utf-8"));
+    const v = verifyTierGrant(g, [String(issuer)]);
+    console.log(v.ok ? `VALID: ${g.tier} for ${g.uuaid} until ${g.expires}` : `INVALID: ${v.reason}`);
+    exit(v.ok ? 0 : 1);
+  }
+  console.error("usage: pillar tier [issue|install|verify]");
+  exit(2);
+}
+
 async function cmdPeers(args) {
   const p = loadPillar(args);
   await p.start();
@@ -465,11 +752,16 @@ async function main() {
     case "groups": return cmdGroups(args);
     case "recv":  return cmdRecv(args);
     case "inbox": return cmdInbox(args);
+    case "trust": return cmdTrust(args);
+    case "tier":  return cmdTier(args);
     case "peers": return cmdPeers(args);
+    case "delegate": return cmdDelegate(args);
     default:
-      console.error(`usage: pillar <init|id|send|send-group|groups|recv|inbox|peers> [--home DIR]`);
+      console.error(`usage: pillar <init|id|send|send-group|groups|recv|inbox|trust|tier|peers|delegate> [--home DIR]`);
       exit(2);
   }
 }
 
-main().catch(e => { console.error(e); exit(1); });
+// A carrier or broker refusal prints one line, `<code>: <fix>` (src/net/refusals.mjs);
+// anything else keeps the full error.
+main().catch(e => { console.error(refusalLine(e) ?? e); exit(1); });