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

package/README.md

@@ -77,13 +77,66 @@ to build a private mesh.
 |---|---|---|
 | `pillar-responder` | Always-on auto-attendant: acks requests instantly, replies from fixed text or a command hook. Run it as a service; agents anywhere get ack+reply without you being live. | one process, outbound HTTPS |
 | `pillar-seed` | A carrier seed — makes you part of the p2p mesh. Any agent that lists your URL replicates every envelope to you and polls you in parallel with other seeds. | one process, one SQLite file, TLS-terminating proxy in front |
-| `pillar` | The full CLI (`init`, `id`, `send`, `send-group`, `recv`, `inbox`, `peers`) — optional libp2p DHT, or carrier-only. | only when used interactively |
+| `pillar` | The full CLI (`init`, `id`, `send`, `send-group`, `recv`, `inbox`, `trust`, `tier`, `peers`) — optional libp2p DHT, or carrier-only. | only when used interactively |
 
 ```sh
 pillar-responder --home ~/.pillar-responder --reply-text "ack" &
 pillar-seed --port 8799 --db /var/lib/pillar/seed.db &   # loopback by default
 ```
 
+## Abuse resistance — consent at the edge, budgets at the carrier
+
+Identity is unforgeable (the sender derives from the signing key), the
+carrier is rate-limited and payload-blind, and **consent lives with the
+recipient**:
+
+```sh
+pillar trust set directory        # only address-book senders reach handlers
+pillar trust allow uuaid:...      # enroll a specific sender (any policy)
+pillar trust block uuaid:...      # never deliver (stored as quarantined evidence)
+pillar trust quarantine           # inspect gated mail; --release ID to accept one
+```
+
+Policies: `open` (default — today's behavior), `directory` (address-book
+senders only), `allowlist` (explicit allow list only). Gated mail is
+**quarantined, never dropped** — it stays in the chain-hashed mailbox with a
+reason, invisible to handlers. Genuine `ack`/`reply` receipts for your own
+outbox always pass. `pillar-responder` defaults its command hook to the
+`directory` policy: strangers still get ack + a fixed reply (first contact
+keeps working), but their payload never reaches your hook process; per-sender
+reply rate is capped.
+
+## Tier grants — qualified volume for foundations, orgs, enterprises
+
+Default (community) carrier budgets: 120 envelopes/min per sender, 512 KiB
+per envelope. Organizations that qualify through the UUAID Foundation's
+review receive a **signed tier grant** — a portable JSON credential
+(Ed25519, expiry-bound, offline-verifiable) that raises their budgets at any
+carrier that trusts the issuer:
+
+| Tier | Envelopes/min | Max body |
+|---|---|---|
+| community (default, no grant) | 120 | 512 KiB |
+| supporter | 300 | 1 MiB |
+| org | 600 | 2 MiB |
+| enterprise | 1200 | 2 MiB |
+| foundation | 3000 | 2 MiB |
+
+```sh
+# Issuer (e.g. the foundation identity) signs a grant:
+pillar tier issue uuaid:foundation:agent:... org --expires 2027-01-01T00:00:00Z
+# Grantee installs it (auto-attached to every carrier deliver):
+pillar tier install tier-grant-<fp>.json
+# Carrier operator opts in:
+pillar-carrier --tier-issuers <issuer-pubkey-hex>
+```
+
+Grants are verified locally (signature + expiry + ceiling clamp) — no
+registry lookup, no account, consistent with the self-authenticating design.
+An invalid or foreign grant silently falls back to community budgets; it can
+never break plain delivery. Wire format unchanged: the grant rides an HTTP
+header (`x-pillar-tier-grant`), not the envelope.
+
 ## Seed topology — how messages survive
 
 On send, `deliver()` replicates the envelope to **every** carrier in your set

package/bin/carrier.mjs

@@ -29,12 +29,17 @@ const port = Number(args.port ?? process.env.CARRIER_PORT ?? 8799);
 const host = args.host ?? process.env.CARRIER_HOST ?? "127.0.0.1";
 const dbPath = args.db ?? process.env.CARRIER_DB ?? "carrier.db";
 const ttlDays = Number(args.ttl ?? process.env.CARRIER_TTL_DAYS ?? 14);
+// Tier grants: comma-separated issuer pubkeys (hex) whose signed grants this
+// carrier honors for raised budgets. Unset = all senders get community tier.
+const tierIssuers = String(args["tier-issuers"] ?? process.env.CARRIER_TIER_ISSUERS ?? "")
+  .split(",").map(s => s.trim()).filter(s => /^[0-9a-f]{64}$/i.test(s));
 
-const server = new CarrierServer({ dbPath, ttlDays });
+const server = new CarrierServer({ dbPath, ttlDays, trustedTierIssuers: tierIssuers });
 const addr = await server.listen(port, host);
 console.log(`carrier listening on ${addr.address}:${addr.port}`);
 console.log(`  db:  ${dbPath}`);
 console.log(`  ttl: ${ttlDays} days`);
+console.log(`  tiers: ${tierIssuers.length ? `${tierIssuers.length} trusted issuer(s)` : "disabled (community budgets for all)"}`);
 
 // Vacuum expired envelopes hourly.
 const vacuumTimer = setInterval(() => {

package/bin/pillar-responder.mjs

@@ -38,11 +38,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 +167,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 +212,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 +244,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 +272,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.mjs

@@ -9,6 +9,8 @@
  *   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,
@@ -21,6 +23,7 @@ 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";
 
 function parseArgs(argv) {
   const args = { _: [] };
@@ -60,6 +63,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 +85,8 @@ function loadPillar(args) {
     dhtClientMode: cfg.dhtClientMode ?? true,
     carriers,
     enableLibp2p: !(args["carrier-only"] || cfg.carrierOnly === true),
+    trust,
+    tierGrant,
   });
 }
 
@@ -414,6 +432,9 @@ 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();
   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 }));
@@ -430,7 +451,8 @@ async function cmdInbox(args) {
       console.log(JSON.stringify({ new: false, id: env.id, from: env.sender, 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);
@@ -449,6 +471,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();
@@ -469,9 +629,11 @@ 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);
     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> [--home DIR]`);
       exit(2);
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uuaid/pillar",
-  "version": "0.2.0-alpha.10",
+  "version": "0.2.0-alpha.11",
   "description": "Pillar (Protocol for Inter-agent Linked Ledger And Relay) — the secure delivery layer of UACP, the Universal Agent Communication Protocol. UACP = UUAID (identity) + Envelope (signed, encrypted container) + Pillar (relay, mailbox, routing, store-and-forward). IAASO-3050 reference implementation: one command to mint an identity and join the network.",
   "license": "Apache-2.0",
   "type": "module",

package/src/identity/tier.mjs

@@ -0,0 +1,85 @@
+/**
+ * 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 itself is off-wire (the foundation's review process decides
+ * WHO gets a grant); this module only makes grants unforgeable and portable.
+ *
+ * Grant shape (JCS-signed over every field except `sig`):
+ *   { v: 1, uuaid, tier, envelopesPerMin, maxBodyBytes, expires, issuer, sig }
+ */
+import { createHash } from "node:crypto";
+import { jcs } from "./jcs.mjs";
+import { Keychain } from "./keychain.mjs";
+
+/** Tier ladder. community = the unauthenticated default (F2 hardening values). */
+export const TIER_DEFAULTS = {
+  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 },
+};
+
+/** 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 }) {
+  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,
+  };
+  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" };
+  }
+  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/identity/trust.mjs

@@ -0,0 +1,63 @@
+/**
+ * Trust policy — the UUAID-layer consent gate (recipient-side).
+ *
+ * The envelope layer proves WHO sent a message and that it is intact; it says
+ * nothing about whether you WANT it.  This module decides, per sender, whether
+ * an incoming envelope reaches handlers or is quarantined (stored in the
+ * mailbox with a reason, never surfaced to handlers — evidence, not /dev/null).
+ *
+ * Policy file: <home>/trust.json
+ *   {
+ *     "policy": "open" | "directory" | "allowlist",
+ *     "allow":  ["uuaid:...", ...],       // always reach handlers
+ *     "block":  ["uuaid:...", ...]        // never reach handlers (any policy)
+ *   }
+ *
+ * Semantics (evaluated in order):
+ *   1. block list        -> quarantine("blocked")           (all policies)
+ *   2. allow list        -> deliver                          (all policies)
+ *   3. policy=open       -> deliver                          (default; today's behavior)
+ *   4. policy=directory  -> deliver if sender is in the address book
+ *                           (fleet.json / directory agents), else quarantine("stranger")
+ *   5. policy=allowlist  -> quarantine("not-allowlisted")
+ *
+ * No trust.json file = policy "open" = exactly the pre-alpha.11 behavior.
+ * Wire-frozen: this is a local, recipient-side decision only.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const POLICIES = ["open", "directory", "allowlist"];
+
+export function loadTrustPolicy(home) {
+  const p = join(home, "trust.json");
+  if (!existsSync(p)) return { policy: "open", allow: [], block: [], path: p, exists: false };
+  let raw;
+  try { raw = JSON.parse(readFileSync(p, "utf-8")); }
+  catch (e) { throw new Error(`trust.json unparseable at ${p}: ${e.message}`); }
+  const policy = raw.policy ?? "open";
+  if (!POLICIES.includes(policy)) {
+    throw new Error(`trust.json: unknown policy "${policy}" (expected ${POLICIES.join("|")})`);
+  }
+  const list = (v) => Array.isArray(v) ? v.filter(s => typeof s === "string") : [];
+  return { policy, allow: list(raw.allow), block: list(raw.block), path: p, exists: true };
+}
+
+/**
+ * Decide an envelope's fate.  `knownSenders` is a Set of uuaids the recipient
+ * already knows (address book / fleet.json / directory agents).
+ * Returns { deliver: true } or { deliver: false, reason }.
+ */
+export function evaluateTrust(trust, sender, knownSenders) {
+  if (trust.block.includes(sender)) return { deliver: false, reason: "blocked" };
+  if (trust.allow.includes(sender)) return { deliver: true };
+  switch (trust.policy) {
+    case "open": return { deliver: true };
+    case "directory":
+      return knownSenders?.has(sender)
+        ? { deliver: true }
+        : { deliver: false, reason: "stranger" };
+    case "allowlist": return { deliver: false, reason: "not-allowlisted" };
+    default: return { deliver: true }; // unreachable (loadTrustPolicy validates)
+  }
+}

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,11 @@ 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);
+  }
+
   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 +166,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

@@ -11,11 +11,16 @@ 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 }) {
+  constructor({ keychain, carriers, tierGrant = null }) {
     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(/\/+$/, ""));
+    // 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;
   }
 
@@ -40,7 +45,10 @@ export class CarrierClient {
       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),
         });

package/src/net/carrier-server.mjs

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

package/src/pillar.mjs

@@ -37,6 +37,8 @@ export class Pillar {
     carriers = [],
     enableLibp2p = true,
     cryptoInventory = { ed25519: "active", "ml-dsa-65": "reserved", "slh-dsa-128s": "reserved" },
+    trust = null, // { policy, allow, block } from loadTrustPolicy(); null = open
+    tierGrant = null, // signed grant object (tier.mjs) sent with carrier delivers
   }) {
     if (!keychain?._identity) throw new Error("Pillar: keychain must be loaded before construction");
     this.keychain = keychain;
@@ -47,11 +49,12 @@ export class Pillar {
     this.dhtClientMode = dhtClientMode;
     this.dhtPeerInfoMapper = dhtPeerInfoMapper;
     this.carriers = carriers;
-    this.carrierClient = carriers.length ? new CarrierClient({ keychain, carriers }) : null;
+    this.carrierClient = carriers.length ? new CarrierClient({ keychain, carriers, tierGrant }) : null;
     this._carrierPoller = null;
     this.enableLibp2p = enableLibp2p;
     this.cryptoInventory = cryptoInventory;
     this.node = null;
+    this.trust = trust;
     this._envelopeHandlers = new Set();
     this._openStreams = new Map(); // peerIdString -> pushable
   }
@@ -474,6 +477,26 @@ export class Pillar {
     }
     const persisted = this.mailbox.appendInbound(envelope);
     if (persisted.duplicate) return; // replay: do not re-fire handlers
+    // Trust gate (recipient consent): quarantine-not-drop. The envelope is
+    // already persisted (chain-hashed evidence); a gated sender just never
+    // reaches handlers. An ack/reply passes the gate ONLY if its inReplyTo
+    // names an envelope in OUR outbox — a genuine receipt for our own send.
+    // (kind alone is spoofable; the outbox check is not.)
+    if (this.trust) {
+      const isReceipt = (envelope.kind === "ack" || envelope.kind === "reply") &&
+        typeof payload?.inReplyTo === "string" && this.mailbox.hasOutbound(payload.inReplyTo);
+      if (!isReceipt) {
+        const { evaluateTrust } = await import("./identity/trust.mjs");
+        const known = new Set(this.addressBook?.keys() ?? []);
+        const verdict = evaluateTrust(this.trust, envelope.sender, known);
+        if (!verdict.deliver) {
+          this.mailbox.markQuarantined(envelope.id, verdict.reason);
+          // eslint-disable-next-line no-console
+          console.warn(`pillar: quarantined ${envelope.id} from ${envelope.sender} (${verdict.reason})`);
+          return;
+        }
+      }
+    }
     const view = { ...envelope, payload };
     for (const h of this._envelopeHandlers) {
       try { await h(view, persisted); }