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

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(() => {