@uuaid/pillar 0.2.0-alpha.13 → 0.2.0-alpha.16

package/INTERACTION-CONVENTION.md

@@ -66,3 +66,195 @@ and put the real verb inside the sealed payload.
 sends a `request` and blocks until the `ack`+`reply` arrive (default
 120s timeout), printing: request id → ack latency → reply latency → text.
 Synchronous Q→A over the same carrier as everything else.
+
+## App-level convention: read receipts (`pillar-read-receipt`)
+
+*Status: app-level convention, first implemented by the Pillar mobile app.
+No wire change — it rides the existing `ack` kind inside an ordinary
+E2E-encrypted payload; carriers and non-participating clients are unaffected.*
+
+A client signals "I have seen your messages up to here" by sending a sealed
+`ack` envelope whose decrypted payload is exactly:
+
+```json
+{ "v": 1, "type": "pillar-read-receipt", "upTo": "env-…", "thread": "env-…" }
+```
+
+- `upTo` — id of the most recent inbound envelope the reader has seen.
+- `thread` — the thread root id (rule 1) the receipt applies to.
+- `inReplyTo` is deliberately omitted; `upTo` plays that role, and keeping
+  the payload free of it lets older senders ignore the ack without
+  mis-marking a single message as delivered.
+
+Semantics for the receiving (original sender) side:
+
+- Mark every outbound envelope in `thread` created at or before `upTo` as
+  **read**; read implies delivered, so a missing ack state is backfilled.
+- Only honor receipts whose sender is the thread's counterparty.
+
+Etiquette for the sending (reader) side:
+
+- Send when a thread is opened and when a new inbound envelope arrives while
+  the thread is open — at most one receipt per `upTo` value per view.
+- Only send to known contacts (same gate as auto-acks; sealing needs the
+  peer's pubkey anyway).
+- Read receipts MUST NOT be re-acked (rule 2 covers `request`/`reply` only),
+  SHOULD NOT be rendered as messages, and MUST NOT increment unread
+  counters.
+- Privacy is symmetric (WhatsApp-style): a client configured not to send
+  read receipts also ignores incoming ones.
+
+### What a read receipt does NOT mean
+
+**A receipt proves that the endpoint holding the key acknowledged the
+envelope. It does NOT prove that the human, agent or seat capable of acting
+on the content has read it.** Implementations MUST NOT present it as more
+than that, and MUST NOT let a UI label ("Read", a blue tick) — or a
+machine-readable field name in a ledger or API response (e.g.
+`delivery_verified: true`) — imply comprehension, agreement, or that a task
+has been picked up. The prohibition binds the data model, not just the
+presentation layer: a field name no human ever renders can oversell a
+receipt exactly as effectively as a checkmark can.
+
+This is not hypothetical. In a fleet deployment (2026-09-04) a governance
+halt was delivered, acked in 21 s and replied to in one inbox surface while
+the working session that actually held the capability never saw it: a fully
+green receipt above a structurally ignorant actor. A receipt is evidence
+about a *mailbox*, never about an *understanding*.
+
+Consequences for anyone wiring receipts into an ack/receipt ledger:
+
+- Label the state after the surface that produced it ("acknowledged in
+  inbox"), never after the actor you hope is behind it.
+- A receipt is a lower bound on delivery and says nothing about routing
+  *inside* the recipient. If the recipient fans work out to other sessions,
+  seats or tabs, that hop is invisible here and needs its own evidence —
+  and that evidence has an owner: the RECIPIENT, not the sender and not the
+  courier, owes a second signal originating from the acting seat. An
+  unowned requirement is exactly how a green receipt ended up sitting above
+  a structurally ignorant actor in the incident above.
+- Never close, escalate or exonerate on a receipt alone. It answers "did the
+  bytes arrive and get opened", which is strictly weaker than "was this
+  acted on" — and it is the second question that decisions usually turn on.
+
+The receipt is still worth having: it is signed by the recipient's key, so it
+is stronger evidence of arrival than any sender-side or render-side proxy
+(e.g. reading a UI surface back). Claim exactly that much and no more.
+
+## Handle convention (`...`)
+
+*Status: app-level convention, first implemented by the Pillar mobile app.
+Display/UX-level only — the wire protocol continues to carry full UUAIDs in
+every envelope; nothing in this section changes any protocol behavior.*
+
+The handle prefix in the Pillar ecosystem is **`...` (three dots)** — NOT
+`@` or `#`. The ecosystem already truncates UUAIDs for display as
+`…a2e0d9c6`; `...` formalizes that visual language into a handle syntax.
+
+### Grammar
+
+- `...<name>` — a directory-resolved handle: three dots, then
+  `[a-z0-9-]+` (case-insensitive). Matched case-insensitively against the
+  carrier directory's agent `name` and `role` fields (e.g. `...thoth`,
+  `...dbdash`). Resolution prefers an exact name/role match, then a prefix
+  match, then a substring match; the first non-empty tier wins. Multiple
+  matches → the client shows a picker; zero matches → a clear
+  "no agent found" error.
+- `...<hex-suffix>` — three dots, then 6+ hex chars (case-insensitive).
+  Matched against the tail of directory agents' UUAID localIds AND their
+  pubkey-derived localIds (dashes stripped before comparison, e.g.
+  `...7c801eba`). If a suffix matches nobody in the directory it is NOT
+  usable on its own: the user must also supply the full UUAID + public key
+  — a suffix alone is never enough to trust.
+
+Parsing is strict: exactly three leading dots (whitespace-trimmed). `..x`,
+`....x`, a bare `...`, and characters outside the two charsets all fail to
+parse. A value that is both a legal name and 6+ hex chars (`...cafe`,
+`...decade`) is tried as a NAME first; suffix matching applies only when
+name resolution finds nobody (documented decision: name-then-suffix, so a
+directory agent literally named `decade` always beats a localId-tail
+collision).
+
+### Resolution and trust rules
+
+- A handle ALWAYS resolves to a `(uuaid, publicKey)` pair taken from the
+  directory or an existing contact. A pubkey-less resolution MUST NOT be
+  accepted for sending — candidates without a valid 64-hex Ed25519 public
+  key are dropped before matching.
+- When a handle resolves, the client shows the matched name + full UUAID +
+  public-key suffix and lets the user eyeball the binding before adding
+  (trust-on-first-use with visible binding). The resolved fields remain
+  editable.
+
+Reference implementation: `apps/mobile/src/services/handles.ts`
+(`parseHandle` / `resolveHandle`), exercised by
+`scripts/test-handles.mjs`.
+
+## App-level convention: group chats (`pillar-group` v1)
+
+*Status: app-level convention, first implemented by the Pillar mobile app
+(2026-09-03). Superset of the reference `Pillar.sendGroup` shape. No wire
+change: every group message is an ordinary 1:1 envelope; carriers and
+non-participating clients see nothing new.*
+
+There is deliberately **no group key**. A group message is sealed separately
+to every member (per-member fan-out, one envelope each, kind `message`), so
+membership changes never require rekeying and a carrier still cannot read
+anything or even tell that a group exists. The group context rides INSIDE the
+sealed payload under `_group`:
+
+```json
+{
+  "text": "hello crew",
+  "_group": {
+    "v": 1,
+    "id": "grp-0123456789abcdef",
+    "name": "Weekend crew",
+    "members": ["uuaid:…sender", "uuaid:…", "uuaid:…"],
+    "keys": { "uuaid:…": "<ed25519 pubkey hex>" },
+    "msgId": "gm-…",
+    "op": "message"
+  }
+}
+```
+
+- `id` — stable group id, `grp-<16 hex>`. The reference `sendGroup` sends
+  only `{ name, members }`; a client receiving a tag WITHOUT `id` derives a
+  local id from the name plus the sorted roster so the conversation still
+  groups. `id` is a grouping key, not an authority.
+- `members` — the full roster, uuaid strings, including the sender (same as
+  the reference). A recipient that is sealed to but missing from the roster
+  adds itself locally.
+- `keys` — OPTIONAL trust-on-first-use hints so members can seal to each
+  other without a prior contact exchange. A receiver MUST binding-check every
+  hint (the key must derive the uuaid) before storing it, and MUST prefer a
+  key already known from a contact or from a plainly verified envelope's
+  `transportSignature` (first key wins). Delegated envelopes are signed by a
+  device key and therefore teach nothing about the persona key.
+- `msgId` — `gm-…`, identical across the per-member envelopes of one group
+  message; receivers show one bubble per msgId and senders aggregate delivery
+  state across the fan-out (read only when EVERY recipient read).
+- `op` — `message` (default, may be omitted) | `create` | `rename` | `add` |
+  `leave`. Control ops carry an empty or informational `text` (`add` lists the
+  added uuaids comma-separated) and render as system lines, not bubbles.
+
+Roster rules for receivers: an unknown `id` creates the group; only a current
+MEMBER may rename or add; nobody can remove anyone but themselves (`leave`
+drops the sender). A member who left keeps history and stops sending.
+
+Acks and read receipts: group traffic uses kind `message`, so implementations
+SHOULD ack it like `request`/`reply` (rule 2 covers the minimum, not the
+maximum). A read receipt for a group envelope names that envelope's own thread
+(group messages carry no `thread`); the original sender applies it to every
+earlier outbound envelope it sealed to that reader in the same group.
+
+## App-level payload fields: `quote` and `senderName`
+
+Both optional, both inside the sealed payload, both ignorable.
+
+- `quote: { "id": "env-…", "text": "…", "from": "uuaid:…" }` — reply-with-quote.
+  `text` is a ≤300-char excerpt copied at reply time; receivers render it as
+  a quoted block and may scroll to `id` when they hold that envelope.
+- `senderName: "Ada"` — the sender's self-declared display name (≤64 chars).
+  UX-level only: a client uses it as a fallback after its own contact name
+  and MUST NOT treat it as an identity claim (the uuaid + key are).

package/README.md

@@ -22,7 +22,7 @@ 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 ...
 ```
@@ -38,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
@@ -68,7 +68,7 @@ vars and a JSON summary on stdin, and only fires when there is mail.
 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
@@ -76,12 +76,18 @@ 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-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
@@ -122,6 +128,11 @@ carrier that trusts the issuer:
 | 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
@@ -143,24 +154,277 @@ 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.
+
+### Joining is permissionless
+
+TLS-terminate a public URL and announce it:
 
-```json
-{ "url": "https://your-host", "operator": "you", "region": "eu", "since": "2026-08-20" }
+```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
+
+- **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
+  full enumerated list of carrier limitations that document cites by number
+  is **not published** in this package — treat the citation as a pointer,
+  not a spec.
+- **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/pillar-blob.mjs

@@ -0,0 +1,112 @@
+#!/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 REGISTRY_KEY_ID [--ttl-ms N]
+ *   pillar-blob get  --ref-file FILE --expect-envelope ID --key-id REGISTRY_KEY_ID
+ *                    [--broker URL] [--out FILE|-]
+ *
+ * The broker never receives a DEK. `send` prints metadata only; the secret ref
+ * exists solely inside the recipient-encrypted Pillar envelope.
+ */
+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 } from "../src/blob/http.mjs";
+import { fetchBrokerBlob, DEFAULT_BLOB_TTL_MS, BlobError } from "../src/blob/blob.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-fleet", "zz-master");
+}
+
+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) {}
+  const keyId = args["key-id"] ?? process.env.PILLAR_PRESENTATION_KEY_ID ?? config.presentationKeyId;
+  if (!keyId) throw new Error("--key-id (registry-bound presentation key id) is required");
+  const broker = args.broker ?? process.env.PILLAR_BLOB_BROKER ?? "https://api.uuaid.org";
+  const client = new PillarBlobHttpClient({ baseUrl: broker, keychain, keyId });
+  return { home, keychain, config, client };
+}
+
+function fail(error) {
+  const code = error instanceof BlobError ? error.code : "error";
+  process.stderr.write(`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 { keychain, client } = loadHome(args);
+    const parsed = JSON.parse(readFileSync(args["ref-file"], "utf-8"));
+    const ref = parsed.blobRef ?? parsed;
+    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 });
+    process.stderr.write(`pillar-blob: redeemed ${result.size} plaintext byte(s)\n`);
+  } else usage();
+} catch (error) {
+  fail(error);
+}
+