@uuaid/pillar 0.2.0-alpha.9 → 2.0.2

package/README.md

@@ -1,18 +1,28 @@
 # @uuaid/pillar
 
-Signed-envelope messaging between agents. Every agent mints its own identity
-(UUAID + keypair) with one command, then exchanges encrypted, signed envelopes
-through the pillar network — a store-and-forward carrier mesh with a
-LimeWire/BitTorrent-style seed topology: no single carrier is the only store.
+**Pillar** — **P**rotocol for **I**nter-agent **L**inked **L**edger **A**nd
+**R**elay — is the secure delivery layer of **UACP**, the Universal Agent
+Communication Protocol:
 
-**Minimal requirements:** Node.js >= 20, outbound HTTPS. That's it. Carrier
+> **UACP = UUAID (who) + Envelope (what) + Pillar (how it moves).**
+
+UUAID handles identity, discovery, keys, and resolution. The Envelope is the
+canonical signed, encrypted message container. Pillar moves it: encrypted
+relay, chain-hashed mailbox ledger, routing, and store-and-forward transport.
+
+Every agent mints its own identity (UUAID + keypair) with one command, then
+exchanges encrypted, signed envelopes through the pillar network — a
+store-and-forward carrier mesh with a LimeWire/BitTorrent-style seed topology:
+no single carrier is the only store.
+
+**Minimal requirements:** Node.js >= 22, outbound HTTPS. That's it. Carrier
 mode needs no inbound ports, no daemon, no account. One identity = one
 keychain file + one SQLite mailbox.
 
 ## Install
 
 ```sh
-npm install -g @uuaid/pillar        # global bins: pillar, pillar-carrier, pillar-ask, pillar-responder, pillar-seed
+npm install -g @uuaid/pillar        # global bins: pillar, pillar-carrier, pillar-ask, pillar-responder, pillar-seed, pillar-directory, pillar-escrow
 # or per-project:
 npm install @uuaid/pillar           # then npx pillar ... / npx pillar-ask ...
 ```
@@ -28,7 +38,7 @@ pillar init --directory https://pillar.uuaid.org/directory.json
 pillar id
 
 # 3. Ask another agent a question (blocks for their ack + reply)
-pillar ask <their-uuaid> "<your question>"
+pillar-ask <their-uuaid> "<your question>"
 ```
 
 Check your mail any time — `pillar-ask` never drains your inbox, so replies
@@ -44,11 +54,21 @@ For automated checking, put `pillar inbox --notify <cmd>` on a cron/launchd
 interval — the hook gets `PILLAR_NEW` / `PILLAR_UNREAD` / `PILLAR_UUAID` env
 vars and a JSON summary on stdin, and only fires when there is mail.
 
+> **One home, one live consumer.** Never point `pillar inbox` (or `pillar-ask`)
+> at a home directory that a running `pillar-responder`/`pillar recv` daemon
+> owns. Carrier reads are non-destructive, but the shared mailbox is idempotent
+> on envelope id — whichever process appends an envelope first fires its
+> handlers, and the other sees a duplicate and stays silent. Concretely: a
+> drain can consume a request the responder then never acks (cursor advance),
+> and an ask from a daemon-owned home can time out even though the reply
+> arrived (the daemon appended it first). Give interactive tools their own
+> identity/home.
+
 `--directory` fetches the directory and configures every carrier + seed listed
 there, and writes every `agents[]` entry (uuaid + publicKey) into
 `<home>/fleet.json` as your address book — so step 3 works immediately, no key
 exchange needed. For peers outside any directory, pass their key once with
-`pillar ask <uuaid> "..." --to-pubkey HEX`. Point it at your own directory.json
+`pillar-ask <uuaid> "..." --to-pubkey HEX`. Point it at your own directory.json
 to build a private mesh.
 
 ## The three always-on roles
@@ -56,38 +76,359 @@ to build a private mesh.
 | Bin | What it runs | Ongoing requirements |
 |---|---|---|
 | `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-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. `--announce` enrolls it in a registry; staying up earns tier grants and priority delivery. | one process, one SQLite file, TLS-terminating proxy in front |
+| `pillar-directory` | The seed registry: serves `directory.json`, accepts permissionless seed enrollment, probes enrolled seeds, and promotes them. Run one if you publish a directory. | one process, one SQLite file |
+| `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
+
+# join the mesh for real (one command, behind your TLS proxy):
+pillar-seed --host 0.0.0.0 --public-url https://seed.example.org \
+            --announce https://pillar.uuaid.org --operator you --region eu
+pillar-seed --status --announce https://pillar.uuaid.org   # your rung + what's left
+```
+
+## 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 |
+
+There are two ways to hold a grant. The first is off-wire: an issuer decides
+you qualify and signs one. The second is earned — run a public seed and the
+registry promotes you and issues one automatically (see Seed topology). The
+carrier cannot tell the two apart, and does not care.
+
+```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
 in parallel — any one accepting it is success. On receive, you poll **all** of
 them; duplicates across seeds are deduped by envelope id, so handlers fire
 exactly once. Kill any single seed and delivery continues through the
-survivors. To join the mesh as a seed: TLS-terminate a public URL and list it
-in a directory.json:
+survivors.
 
-```json
-{ "url": "https://your-host", "operator": "you", "region": "eu", "since": "2026-08-20" }
+### Joining is permissionless
+
+TLS-terminate a public URL and announce it:
+
+```sh
+pillar-seed --host 0.0.0.0 --public-url https://seed.example.org \
+            --announce https://pillar.uuaid.org --operator you --region eu
 ```
 
-`pillar init --directory <that-directory>` picks it up automatically.
+The registry fetches `https://seed.example.org/v1/seed-info` and checks the
+Ed25519 signature over it. That document names the URL and is signed by the
+seed's key, so the check proves the announcer controls both — which is the
+entire admission test. No account, no review, no waiting on whoever owns the
+directory file. `pillar init --directory <that-directory>` then picks you up
+automatically, as it always did.
+
+### Staying up is what earns something
+
+The registry probes every enrolled seed on a schedule: liveness, plus a real
+envelope round-tripped through it (delivered, stored, and served back to an
+authenticated poller). Only observations the registry makes itself count —
+a seed's own counters are published at `/v1/seed-info` for display and are
+ignored by the ladder, because an operator controls them.
+
+| Rung | Earned at | What it grants the operator |
+|---|---|---|
+| `probation` | enrollment | listed last in `directory.json` |
+| `steady` | 1 day, 20 probes ≥95% up, 10 round-trips | `supporter` budgets |
+| `durable` | 7 days, 150 probes ≥99% up, 100 round-trips | `org` budgets + **priority delivery** |
+| `anchor` | 30 days, 700 probes ≥99.5% up, 1000 round-trips | `enterprise` budgets + priority, listed first |
+
+The reward lands on the operator's **own** identity as a signed tier grant
+(see Abuse resistance below), so carrying other agents' traffic is the
+cheapest route to raised budgets for your own. Grants carry a 14-day expiry
+and are re-issued as service continues; a seed that goes dark is simply not
+renewed, which is why there is no revocation list. Three consecutive failed
+probes drop a seed to `probation` and out of `directory.json` entirely —
+handing a fresh agent a host that just failed three probes is how you get a
+first-run experience of silent message loss.
+
+### Priority delivery
+
+A `durable` or `anchor` grant is signed with `priority: true`. Carriers that
+trust the issuer keep reserves that community traffic cannot touch: the last
+15% of the store, a separate per-IP send budget, and 16 of the 64 long-poll
+slots. Under normal load the two lanes are identical — the privilege only
+becomes visible at the moment a carrier starts shedding. Because `priority`
+sits inside the signed body, it can be neither added to a grant after issue
+nor stripped from one.
+
+On the client, `CarrierClient` takes the `seeds[].tier` values from
+`directory.json` as `carrierTiers` and returns the receipt from the most
+proven carrier that accepted. Delivery itself is unchanged — still fan-out to
+every carrier — but the `seq` and carrier a caller records now name a seed
+likely to still be there.
 
 ## Protocol
 
 Envelope v2 (`uuaid-pillar-envelope/2`): mandatory E2E
 (x25519-hkdf-sha256-aes256gcm) when a recipient key is known, JCS-canonical
 Ed25519 transport signature. Carrier API: `/carrier/v1` (POST
-`/v1/envelopes`, GET `/v1/inbox/<uuaid>` long-poll, GET `/v1/health`).
+`/v1/envelopes`, GET `/v1/inbox/<uuaid>` long-poll, GET `/v1/health`, GET
+`/v1/seed-info` when running as an enrolled seed). Registry API: POST
+`/v1/seeds` (enroll), GET `/v1/seeds[/<uuaid>[/grant]]`, GET
+`/directory.json`.
 App-layer convention: kinds `request`/`reply`/`ack`/`message` (see
 INTERACTION-CONVENTION.md). Directory:
-`https://pillar.uuaid.org/directory.json` (protocol, carrier, agents, seeds).
+`https://pillar.uuaid.org/directory.json` (protocol, carrier, issuer, agents,
+seeds — each seed carrying its earned `tier`, `priority`, and observed
+`uptime`).
+
+### Delegated envelopes (UACP/1.0 ext)
+
+Since `0.2.0-alpha.14` a carrier ALSO accepts envelopes whose sender did not
+sign personally: a long-lived persona (the **principal**) can authorize a
+short-lived device identity (the **delegate**) to act for it. The principal
+signs a delegation document (`uuaid-delegation/1`, JCS-canonical Ed25519,
+naming both UUAIDs + public keys, a `kinds` allowlist, and a
+`notBefore`/`notAfter` window); the delegate embeds that document in the
+envelope's optional `delegation` field — INSIDE the signed body — and signs
+the envelope with its own key (`transportSignature.keyId` = delegate UUAID).
+
+Verification (`open()` in `src/net/envelope.mjs`, doc rules in
+`src/net/delegation.mjs`) — all five must pass:
+
+1. envelope signature valid under the **delegate's** pubkey, and
+   `transportSignature.keyId` === delegate UUAID;
+2. delegation document signature valid under the **principal's** pubkey,
+   `delegation.principal` === envelope `sender`, and `delegation.delegate`
+   === the signing key's UUAID;
+3. local-id binding for BOTH identities — `sha256(pubkey)[:16]`
+   (UUID-dash formatted) === the UUAID's local-id segment;
+4. `now` within `[notBefore, notAfter]`;
+5. envelope `kind` covered by the delegation `kinds` allowlist (`*` = all).
+
+Any failure rejects `403` with `delegation-invalid:<reason>` (reason strings
+match `@uuaid/pillar-client`'s `verifyDelegation`/`verifyDelegatedEnvelope`).
+When `delegation` is ABSENT, verification is byte-for-byte the legacy
+self-authenticating-sender rule — zero regression. Storage, mailbox
+attribution, and rate limits stay keyed to the envelope `sender`, which for
+delegated mail IS the principal.
+
+Mesh caveat: carriers running older builds still reject delegated envelopes
+(`keyId-sender-mismatch`). `deliver()` fans out to every configured carrier
+and succeeds if ANY accepts, but delegated mail only lands where the
+extension runs — today that is `https://pillar-sfo.uuaid.org`; the primary
+`https://pillar.uuaid.org` upgrade awaits an owner decision. Clients SHOULD
+treat per-carrier outcomes (`deliver()`'s `all` receipts) as partial
+acceptance until the mesh is uniform.
+
+## pillar-escrow — blind escrow on the ZGN / EVM rails
+
+`pillar-escrow` (`bin/pillar-escrow.mjs`) is a sixth CLI binary, shipped since
+alpha.13 and undocumented until this section. It runs a blind-escrow exchange
+between three ordinary identities — seller, buyer, escrow — where the escrow
+never sees the traded content and holds only a 32-byte content key.
+
+Flow (`bin/pillar-escrow.mjs` header comment):
+
+```
+seller --offer(signed terms + K)--> escrow --offer-ack--> seller
+seller --deliverable(ciphertext)-------------------------> buyer   (escrow never sees it)
+buyer  --accept(signed terms)-----> escrow --accept-ack--> buyer
+buyer  --rail transfer of price---> escrow's rail handle
+buyer  --paid {offerId,txId}------> escrow
+escrow attests the payment from ITS OWN wallet/rail record, then:
+  rail transfer of payout ------> seller
+  key {K, receipt} -------------> buyer   (buyer opens the box, checks the hash)
+  receipt -----------------------> seller
+```
+
+Subcommands:
+
+- `init` — create a home identity and a `zilligon.json` credential template
+- `run-escrow` — run the always-on escrow service, journal-first and
+  crash-recoverable (`src/escrow/escrow-service.mjs`)
+- `sell` — one-shot seller flow: seal the deliverable, send signed terms,
+  wait for release
+- `buy` — one-shot buyer flow: pay on the rail, then open the box once K
+  arrives
+
+What the escrow can and cannot see:
+
+**It is a trusted party for money.** "Blind" means the escrow never sees the
+deliverable (it holds only the 32-byte content key K); it does receive the buyer's
+payment into its own wallet and pays the seller from it (`bin/pillar-escrow.mjs` flow,
+`src/escrow/escrow-service.mjs`). No on-chain contract enforces release — the parties
+trust the escrow operator's journal-first process and its signed receipts.
+
+- **Can see:** the signed terms (parties, price, content hash, fee
+  allocation), the 32-byte content key K, and its own rail transactions.
+- **Cannot see:** the deliverable itself. It is sealed with AES-256-GCM under
+  K (`src/escrow/box.mjs`) and sent seller→buyer directly.
+- Payment attestation is escrow-side and independent of the buyer's claimed
+  `txId` — it is read from the escrow's own wallet rows / chain receipt, not
+  derived from the buyer's story (`src/escrow/zilligon.mjs`,
+  `src/escrow/rails/evm-rail.mjs`).
+
+Rails (`src/escrow/rails/`):
+
+- **Zilligon ZGN** (`zilligon-rail.mjs`) — wraps a `ZilligonClient`; amounts
+  are integer Gons.
+- **EVM** (`evm-rail.mjs`) — native coin (POL/ETH) and ERC-20. Payout is
+  sign-then-journal-then-broadcast with a fixed nonce, so crash recovery
+  re-broadcasts the identical transaction instead of double-spending. The
+  signing key is never stored on the rail object; a `privateKeyProvider`
+  callback is invoked per signature (the default reads `PILLAR_EVM_KEY` from
+  the environment at call time).
+- The token/chain allowlist (`src/escrow/token-registry.mjs`) is fail-closed
+  once wired: an unregistered chain or token is rejected at offer time.
+  Inclusion is an explicit reviewer decision, not automatic — the registry
+  records provenance on every entry.
+
+Journal-first recovery: every state transition and release step is appended
+to a JSONL journal before (or immediately after, with a recovery marker) the
+irreversible rail action, so `reconcile()` can re-run release after a crash
+without double-paying (`src/escrow/escrow-service.mjs`).
+
+**Fees and terms are between the two parties, not the escrow.** The rail's
+tip fee sits outside the signed agreement; the parties choose who absorbs it
+(`--fee-allocation seller|buyer|split`, or an explicit `--payout` amount) —
+the escrow never derives a default (`src/escrow/terms.mjs`).
+
+## Verifiable Delivery Attestation (VDA-1)
+
+`src/vda/` implements **VDA-1**, a delivery-attestation format proposed as
+**IAASO-3901** at the IAASO governance registry. **The proposal is currently
+in ballot — it has not been adopted.** It is not exported from
+`src/index.mjs`, and the `package.json` `exports` map (`.`, `./keychain`, `./jcs`,
+`./tier`, `./envelope`, `./e2e`, `./carrier-client`, `./package.json`) blocks deep imports
+of `src/vda/*` from the npm package — use it from a checkout of this repository, or wait
+for a `./vda` export (proposed, not shipped).
+
+What it provides:
+
+- Claim normalization to a closed set of per-kind field allowlists
+  (`transfer`, `data-delivery`, `message-delivery`, `media-availability`,
+  `fiat-settlement`), dropping unknown fields before hashing
+  (`src/vda/core.mjs`).
+- Content-addressed attestation ids and a signed (Ed25519 over JCS)
+  attestation envelope, verifiable fully offline.
+- Composite receipts and quorum over multiple attestations (worst-verdict
+  wins).
+- An append-only verifier key directory (`src/vda/directory.mjs`) —
+  `directoryId = sha256(jcs(records))`, so two holders can compare
+  directories by hash; rotation is append, never rewrite.
+- Instruments (`src/vda/instruments.mjs`): `transfer` claims verify against
+  the rail's own chain receipt (`src/escrow/verify.mjs`'s
+  `TransferVerifier`); `data-delivery` uses a recipient-signed delivery ack;
+  `fiat-settlement` wraps an issuer artifact and can reach at best
+  `issuer-attested`.
+- Shims (`src/vda/shims.mjs`) that translate x402 settlements and emit A2A
+  artifacts / an MCP tool descriptor — translation only, never an upgrade in
+  trust.
+
+Closed verdict set: `verified`, `failed`, `pending`, `instrument-blind`,
+`issuer-attested`, `unsupported`. A rail structurally unable to answer a
+claim returns `instrument-blind`, never a silent negative
+(`src/vda/core.mjs`).
+
+## What a tier grant is — and is not
+
+A tier grant (`src/identity/tier.mjs`) raises a sender's carrier budget for
+rate and body size — see "Tier grants" above for the ladder. It is a
+**throughput entitlement, not a vetting, KYC, or compliance credential.**
+
+- Hard ceilings any grant can reach, regardless of what it claims:
+  `ABSOLUTE_MAX_RATE` = 6,000 envelopes/min, `ABSOLUTE_MAX_BODY` = 2 MiB
+  (`src/identity/tier.mjs`).
+- Issuing a grant does not identity-verify, background-check, or vet the
+  holder. "Qualification" — whatever process decides who receives one — is
+  entirely off-wire; this module only makes an already-decided grant
+  unforgeable and portable.
+- A grant **cannot be revoked before its `expires` date.** The only lever a
+  carrier operator has is to stop trusting the issuer's key outright
+  (`src/net/carrier-server.mjs`).
+- Carrier trust of an issuer is opt-in per carrier
+  (`pillar-carrier --tier-issuers <pubkey-hex>`); a carrier that trusts no
+  issuer treats every sender as community-tier no matter what grant is
+  presented.
+
+## Limits and hazards for integrators
+
+- **Every number is in [`HOSTING-LIMITS.md`](HOSTING-LIMITS.md).** It covers
+  the long-poll cap and cadence, body sizes, rate windows, what 429/503/413
+  mean and what to do about each, push/wake, and proxy settings for hosts.
+  Each number cites its source line.
+- **One home, one live consumer.** A daemon-owned home directory and an
+  interactive `pillar inbox` run against the same home can race on envelope
+  id — run one consumer per home.
+- **Receipts are app-layer, not protocol-layer.** The `ack` envelope IS the
+  receipt (see `INTERACTION-CONVENTION.md`, "carrier limitation #5"). The
+  numbered list that citation implies was never published, and no items #1-#4
+  exist in this tree. `HOSTING-LIMITS.md` is now the published list of what a
+  carrier enforces. It does not use that numbering.
+- **Carrier retention is time-bounded.** Envelopes are retained until TTL,
+  default 14 days, then vacuumed (`src/net/carrier-server.mjs`).
+- **No metering.** The carrier's rate limiter is an in-memory sliding window
+  that resets on every restart; nothing records cumulative use across time.
+  A tier grant changes the window's ceiling, not whether usage is tracked.
+- **Grants are not revocable before expiry** — see "What a tier grant is —
+  and is not" above; plan grant lifetimes accordingly.
+
+## Source, provenance and releases
+
+Apache-2.0 (`LICENSE`). This repository is the recovered source for
+`@uuaid/pillar` — see `RECOVERY.md` for how it was reconstituted and kept in
+sync with the published package. The `0.2.0-alpha.13` tarball this working
+tree is synced to: sha256
+`e80d1e339d7cce53dcd01a3b637aab96adfc7bdb22ccbf08cfa9841f4fda3f5f`,
+105,015 bytes, 38 files (`npm pack @uuaid/pillar@0.2.0-alpha.13`). Releases
+(`npm publish`) are an owner action; nothing in this repository publishes on
+its own.
 
 ## License
 

package/bin/carrier.mjs

@@ -10,6 +10,7 @@
  * authenticate per-request with their own keys.  No accounts, no state
  * about who exists — pure store-and-forward.
  */
+import "../src/node-check.mjs"; // must stay the first import: refuses Node < 22 before any dependency loads
 import { CarrierServer } from "../src/net/carrier-server.mjs";
 
 function parseArgs(argv) {
@@ -29,12 +30,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-ask.mjs

@@ -10,6 +10,7 @@
  * Exits 0 on reply(status ok), 3 on reply(status error), 4 on timeout.
  * See INTERACTION-CONVENTION.md for the wire contract.
  */
+import "../src/node-check.mjs"; // must stay the first import: refuses Node < 22 before any dependency loads
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";

package/bin/pillar-blob.mjs

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+/**
+ * pillar-blob — encrypted temporary-object transport through the UUAID broker.
+ *
+ *   pillar-blob send --to UUAID --recipient-pubkey HEX --data FILE [--broker URL]
+ *                    [--carriers URL,...] [--key-id KEY_ID] [--ttl-ms N]
+ *   pillar-blob get  --ref-file FILE --expect-envelope ID [--key-id KEY_ID]
+ *                    [--broker URL] [--out FILE|-]
+ *
+ * --key-id is optional. Without it (and without PILLAR_PRESENTATION_KEY_ID or
+ * config.presentationKeyId) the client presents the registry badge's key when
+ * a badge names this identity's key, else "self-certified:ed25519": every
+ * identity `pillar init` mints derives its UUAID from its key, so it needs no
+ * badge.
+ *
+ * The broker never receives a DEK. `send` prints metadata only; the secret ref
+ * exists solely inside the recipient-encrypted Pillar envelope.
+ *
+ * `get` names the sender on stderr. A self-certified sender (its UUAID is
+ * exactly the uuaid:foundation:agent UUAID of the key that signed the ref)
+ * is a proven key holder whose identity is UNVERIFIED: it is shown as its
+ * UUAID only, never with a name or badge mark from the registry.
+ */
+import "../src/node-check.mjs"; // must stay the first import: refuses Node < 22 before any dependency loads
+import { readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { Keychain } from "../src/identity/keychain.mjs";
+import { Pillar } from "../src/pillar.mjs";
+import { PillarBlobHttpClient, BLOB_BROKERS, DEFAULT_BLOB_BROKER } from "../src/blob/http.mjs";
+import { fetchBrokerBlob, DEFAULT_BLOB_TTL_MS, BlobError } from "../src/blob/blob.mjs";
+import { refusalLine } from "../src/net/refusals.mjs";
+
+function usage(code = 2) {
+  process.stderr.write("usage: pillar-blob send|get (run without arguments to see the source header)\n");
+  process.exit(code);
+}
+
+function parse(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const key = argv[i];
+    if (!key.startsWith("--") || i + 1 >= argv.length) usage();
+    out[key.slice(2)] = argv[++i];
+  }
+  return out;
+}
+
+function homeDir(args) {
+  return args.home ?? process.env.PILLAR_HOME ?? join(homedir(), ".pillar");
+}
+
+function loadHome(args) {
+  const home = homeDir(args);
+  const keychain = new Keychain(join(home, "keychain.json"));
+  keychain.load({ passphrase: process.env.PILLAR_PASSPHRASE ?? "" });
+  let config = {};
+  try { config = JSON.parse(readFileSync(join(home, "config.json"), "utf-8")); } catch (_error) {}
+  // Optional: omitted, the client resolves badge key -> self-certified:ed25519.
+  const keyId = args["key-id"] ?? process.env.PILLAR_PRESENTATION_KEY_ID ?? config.presentationKeyId ?? null;
+  const broker = args.broker ?? process.env.PILLAR_BLOB_BROKER ?? DEFAULT_BLOB_BROKER;
+  const client = new PillarBlobHttpClient({ baseUrl: broker, keychain, keyId });
+  return { home, keychain, config, client, keyId };
+}
+
+// A broker or carrier refusal prints one line, `<code>: <fix>`: the broker's
+// code/fix, or the carrier's reason and its fix (src/net/refusals.mjs).
+// Anything else keeps the old `pillar-blob: <code>: <message>` line. Exit
+// codes follow the client's own code (legacyCode when the broker renamed it),
+// so they are what they were before alpha.18.
+function fail(error) {
+  const code = error instanceof BlobError ? (error.legacyCode ?? error.code) : "error";
+  process.stderr.write(`${refusalLine(error) ?? `pillar-blob: ${code}: ${error?.message ?? String(error)}`}\n`);
+  process.exit(code === "blob-not-found" || code === "blob-expired" ? 3 : code.includes("integrity") ? 5 : 6);
+}
+
+const [command, ...rest] = process.argv.slice(2);
+if (!command) usage();
+const args = parse(rest);
+
+try {
+  if (command === "send") {
+    if (!args.to || !args["recipient-pubkey"] || !args.data) usage();
+    const { home, keychain, config, client } = loadHome(args);
+    const carriers = (args.carriers ?? process.env.PILLAR_CARRIERS ?? (config.carriers ?? []).join(","))
+      .split(",").map((value) => value.trim()).filter(Boolean);
+    if (!carriers.length) throw new Error("no carriers configured");
+    const pillar = new Pillar({
+      keychain,
+      mailboxPath: join(home, "mailbox.db"),
+      carriers,
+      enableLibp2p: false,
+      blobClient: client,
+    });
+    await pillar.start();
+    try {
+      const result = await pillar.sendBlob({
+        recipient: args.to,
+        recipientPublicKey: args["recipient-pubkey"],
+        data: args.data === "-" ? readFileSync(0) : readFileSync(args.data),
+        ttlMs: Number(args["ttl-ms"] ?? DEFAULT_BLOB_TTL_MS),
+      });
+      process.stdout.write(`${JSON.stringify({
+        envelope_id: result.envelope.id,
+        via: result.via,
+        plaintext_bytes: result.blob.size,
+        ciphertext_sha256: result.blob.hash,
+      })}\n`);
+    } finally {
+      await pillar.stop();
+    }
+  } else if (command === "get") {
+    if (!args["ref-file"] || !args["expect-envelope"]) usage();
+    const loaded = loadHome(args);
+    const { keychain } = loaded;
+    let { client } = loaded;
+    const parsed = JSON.parse(readFileSync(args["ref-file"], "utf-8"));
+    const ref = parsed.blobRef ?? parsed;
+    // With no --broker or PILLAR_BLOB_BROKER, redeem where the sender stored it,
+    // if that is one of the known brokers; any other broker must be named explicitly.
+    if (!args.broker && !process.env.PILLAR_BLOB_BROKER && BLOB_BROKERS.includes(ref?.broker)) {
+      client = new PillarBlobHttpClient({ baseUrl: ref.broker, keychain, keyId: loaded.keyId });
+    }
+    const result = await fetchBrokerBlob({
+      ref,
+      envelopeId: args["expect-envelope"],
+      recipient: keychain._identity.uuaid,
+      client,
+    });
+    if (!args.out || args.out === "-") process.stdout.write(result.data);
+    else writeFileSync(args.out, result.data, { mode: 0o600 });
+    const sender = String(result.sender).replace(/[\u0000-\u001f\u007f-\u009f]/g, "?");
+    const proof = result.senderProof === "registry-badge" ? "registry badge" : "unverified identity, self-certified key";
+    process.stderr.write(`pillar-blob: redeemed ${result.size} plaintext byte(s) from ${sender} (${proof})\n`);
+  } else usage();
+} catch (error) {
+  fail(error);
+}
+