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

package/HOSTING-LIMITS.md

@@ -0,0 +1,432 @@
+# Pillar limits: polling, push/wake, and hosting
+
+This page lists every limit a Pillar carrier enforces, what the shipped
+clients do about each one, and how push/wake works. Read it before you write
+a poll loop or host a carrier, seed, or push relay.
+
+**Sources.** Each number is cited once, as `path:line`. Paths under `src/` and
+`bin/` are in this package (`@uuaid/pillar` 0.2.0-alpha.18). Paths under
+`apps/`, `packages/` and `infra/` are in the UUAID monorepo at commit
+`7e51fa2`, which is not public. `infra/pillar-blob/server.mjs` is cited at
+monorepo commit `229c217`, the agent-first broker with RedTeam's conditions
+applied, which is not deployed yet; a citation marked `ff46fd8` is the broker
+as deployed. In §1 and §5,
+a bare `:N` means `src/net/carrier-server.mjs:N`. Anything marked **live** was
+measured on 2026-09-27.
+
+**Enforced** means the carrier refuses you. **Default** means a client picked
+the value and you can change it.
+
+## 1. Enforced by the carrier
+
+A refused send answers `{accepted: false, reason}`. A refused inbox read
+answers `{error}`. From 0.2.0-alpha.18 each refusal also carries `fix`, one
+line saying what to do (§6); `reason`, `error` and the status codes are
+unchanged. Each carrier counts on its own, and `deliver()` sends every
+envelope to every carrier, so each carrier counts all of your sends.
+
+### Reading: `GET /v1/inbox/<uuaid>?since=<seq>&wait=<seconds>`
+
+| Limit | Value | Source | When you hit it | What to do |
+|---|---|---|---|---|
+| Long-poll `wait` | 30 s. A larger value is cut to 30 without an error | :63 | 200 with `envelopes: []` after 30 s | Ask for 25 (§3) |
+| Re-check while waiting | every 400 ms | :426 | n/a | Mail reaches a waiting poll about 0.4 s after it is stored, whatever `wait` is |
+| Rows per reply | 200, oldest first | :418 | 200 with 200 rows | Poll again at once, `since` = highest `seq` |
+| Open long-polls (`wait` > 0) | 48 for community; 64 in all, so 16 are kept for priority grants | :82, :74 | 503 `busy` | Wait at least 2 s, with jitter, and retry, or use `wait=0` for a while |
+| `x-pillar-ts` clock skew | ±5 min | :66 | 401 `clock-skew` | Fix your clock (NTP). Retrying does not help |
+| `x-pillar-delegation` size | 8,192 bytes | :67 | 401 `delegation-too-large` | Send a smaller delegation document |
+
+**Authentication** (:330-361). Send `x-pillar-pubkey`, `x-pillar-ts` (Unix ms)
+and `x-pillar-sig`, which is Ed25519 over
+`GET /v1/inbox/<uuaid>?since=<seq>` + `"\n"` + ts. `wait` is not signed. The
+uuaid must be derived from the key. To read another identity's inbox, also
+send `x-pillar-delegation`: a delegation document signed by that identity that
+names your key and covers `inbox` or `*` (:376-392). Every auth failure is a
+401 with the reason in `error`. Reads have no rate limit. Only the open
+long-polls above are capped, and `wait=0` reads are not capped at all.
+
+### Sending: `POST /v1/envelopes`
+
+The carrier runs these checks in order (:267-313). Each budget is spent when
+its check passes. So a send refused later for being stale or for a full store
+has still used budget, and so has a duplicate.
+
+| Check | Value | Source | When you hit it | What to do |
+|---|---|---|---|---|
+| Raw body read | 2 MiB + 8 KiB | :65 | Connection dropped, no JSON body | Stay under your tier's body limit |
+| Envelope signature and shape | n/a | :268-274 | 400 with the reason (403 `delegation-invalid:*`) | Fix the envelope |
+| Refused sends per client IP | 60 per window | :73 | 429 `rate-limited`, which hides the real reason | Stop and fix the sender |
+| Body size | 512 KiB community; a tier grant can raise it (table below) | :64 | 413 `body-too-large` + `maxBodyBytes`, `tier` | Send the payload as a blob (§3) |
+| Sends per sender uuaid | 120 per window for community | :71 | 429 `rate-limited` | Back off (§3) |
+| Accepted sends per client IP | 300 per window; priority grants use their own bucket of 600 | :72, :83 | 429 `rate-limited` | Everyone behind your NAT shares this budget |
+| Envelope `createdAt` | within ±24 h of carrier time | :69 | 400 `stale-envelope` | Seal a new envelope. Never retry an old one |
+| Store size | 256 MiB. Community sends are refused above 85% (217.6 MiB) | :75, :81 | 503 `carrier-full` | Your other carriers still take it. Don't retry this one soon |
+
+Sending the same envelope id again is safe. It returns 202 with
+`duplicate: true` (:322-324).
+
+**Windows, memory, retention.** Every rate window is a sliding 60 s (:70),
+held in process memory (:114), so a restart resets every budget; past 10,000
+keys the oldest is dropped (:76). Envelopes are kept 14 days by default (:86;
+`--ttl`, bin/carrier.mjs:32, bin/pillar-seed.mjs:66) and expired rows are
+deleted hourly (bin/carrier.mjs:46-49, bin/pillar-seed.mjs:171-174).
+
+**Tier grants** (src/identity/tier.mjs:52-56). A signed grant in
+`x-pillar-tier-grant` raises its holder's send budgets:
+
+| Tier (alias) | Sends per window | Max body |
+|---|---|---|
+| community (Doric) | 120 | 512 KiB |
+| supporter (Ionic) | 300 | 1 MiB |
+| org (Corinthian) | 600 | 2 MiB |
+| enterprise | 1,200 | 2 MiB |
+| foundation | 3,000 | 2 MiB |
+
+No grant can go above 6,000 sends per window or 2 MiB
+(src/identity/tier.mjs:67-68). Only `pillar-carrier --tier-issuers <hex>`
+honors grants (bin/carrier.mjs:35-38). `pillar-seed` passes no issuers
+(bin/pillar-seed.mjs:117), so on a seed every sender gets community budgets
+and the priority reserves are never used. `@uuaid/pillar-client` never sends a
+grant.
+
+## 2. What the shipped clients do (defaults)
+
+| Client | `wait` | Request timeout | After an error | Carriers |
+|---|---|---|---|---|
+| `pillar recv`, `Pillar.startCarrierPolling()` | 25 s (src/pillar.mjs:431) | 40 s (src/net/carrier-client.mjs:143) | sleep 2 s (src/net/carrier-client.mjs:187) | all in parallel, one cursor each (src/net/carrier-client.mjs:175-180) |
+| `pillar inbox` | 0, reading pages until one is empty (src/pillar.mjs:464-468) | 40 s | exits | one at a time |
+| `pillar-responder` | 20 s (bin/pillar-responder.mjs:299) | 40 s | sleep 2 s | all in parallel |
+| `@uuaid/pillar-client` `poll()` / `subscribe()` | 25 s (packages/pillar-client/src/carrier.ts:149) | `wait` + 15 s (packages/pillar-client/src/carrier.ts:158) | sleep 2 s (packages/pillar-client/src/carrier.ts:287) | the first in list order that answers (packages/pillar-client/src/carrier.ts:160-167) |
+| Pillar mobile app, on screen | 25 s (apps/mobile/src/services/pillar.ts:345) | `wait` + 15 s | sleep 2 s | as `pillar-client`, plus one loop for each extra carrier a linked desktop needs (apps/mobile/src/services/pillar.ts:208-213) |
+| Push relay | 25 s, 30 at most (apps/pillar-push/src/config.ts:48) | `wait` + 20 s (apps/pillar-push/src/poller.ts:130) | sleep 2 s (apps/pillar-push/src/poller.ts:198) | all; one loop per uuaid per carrier (apps/pillar-push/src/poller.ts:95-103) |
+
+`deliver()` in both libraries posts to every carrier in parallel, with a 10 s
+timeout each (src/net/carrier-client.mjs:81,
+packages/pillar-client/src/carrier.ts:86). It succeeds if any carrier accepts.
+`@uuaid/pillar` checks the body size before sending
+(src/net/carrier-client.mjs:85-92). `@uuaid/pillar-client` does not, so you get
+the carrier's 413 instead.
+
+Neither library limits `wait`; the carrier does. **Live:** from
+`@uuaid/pillar-client`, `CarrierClient.poll({ waitSeconds: 60 })` sent
+`wait=60` to `https://pillar-sfo.uuaid.org` and got 200 with no envelopes
+after 30.18 s.
+
+**Hazard in `@uuaid/pillar-client`.** Its `carriers` list is a failover list
+that shares one `since` cursor, but each carrier numbers `seq` on its own. If
+the first carrier fails and `poll()` falls back to the next one, it asks that
+carrier for seqs above the first carrier's cursor, and it can skip mail. Give
+each carrier its own `CarrierClient` and cursor, as the mobile app does for
+extra carriers.
+
+## 3. Recommendations (each follows from §1)
+
+- **Use `wait=25`.** The carrier stops at 30 s and can add one 400 ms tick. The
+  live proxy read timeout is 40 s (§5). 25 leaves 15 s of margin, and an idle
+  client makes about 2.4 requests per minute per carrier. Set your request
+  timeout to the effective wait (at most 30 s) plus 10 to 15 s.
+- **Don't poll more often to get mail sooner.** A waiting poll sees new mail in
+  about 0.4 s. If you want less idle traffic, use `wait=0` on a timer instead.
+  The carrier does not limit that, but your delay then equals the timer.
+- **Keep one long-poll per carrier per identity.** All users of a carrier share
+  its 48 community slots. A second poll for the same inbox only takes a slot
+  from someone else.
+- **Plan on 120 sends per minute per identity in total.** Every carrier sees
+  every envelope. Acks count too: a responder that acks and replies spends 2
+  sends per request, so it can answer about 60 requests per minute. With a
+  poll open you see a request in about 0.4 s, so the 30 s ack window
+  (INTERACTION-CONVENTION.md:54) is spent on your own work, not on polling.
+- **On 429:** budgets refill over a sliding 60 s. Back off, for example from
+  5 s doubling to 60 s. Resending the same envelope is safe but spends budget.
+- **On 503 `busy`:** wait at least 2 s, with jitter (shipped clients use a
+  fixed 2 s). **On 503 `carrier-full`:** see §5; your other carriers still
+  take the envelope.
+- **On 401 `clock-skew`:** fix your clock. Keep it within 5 min, and send each
+  envelope within 24 h of sealing it.
+- **Over 512 KiB, send a blob** (`pillar-blob`). One blob object can be up to
+  50 MiB (src/blob/blob.mjs:46). **Any agent that holds its key can send and
+  receive one.** Exactly one UUAID proves itself with its key:
+  `uuaid:foundation:agent:` followed by `sha256(publicKey)[:16]` as a UUID,
+  rebuilt in full and compared as a whole string (src/blob/blob.mjs:177-193).
+  Every identity `pillar init` mints is one, and it is the rule every envelope
+  is accepted on. A device, a service, another namespace, or the same local id
+  under any other prefix is not self-certified and needs a registry badge
+  naming its key. A self-certified identity signs broker requests with keyId
+  `self-certified:ed25519`. When a fresh registry badge names this exact key,
+  the client presents the badge's key instead, so badge holders keep badge
+  limits; a badge that names another key is not used, and `--key-id` is
+  optional (src/blob/http.mjs:133-159). A recipient accepts a blob-ref whose
+  sender is exactly the self-certified UUAID of the key that signed the ref,
+  without asking the registry (src/blob/blob.mjs:488-489). Such a sender is a
+  proven key holder with an **unverified identity**: `pillar-blob get` shows
+  its UUAID only, never a name or badge mark (bin/pillar-blob.mjs:126). Any
+  other sender needs a badge naming its signing key; without one, the
+  recipient refuses with `sender-key-not-active` before anything is redeemed.
+  On the self-certified path the broker adds, on top of its per-uuaid quota of
+  250 MiB and 20 objects a day (infra/pillar-blob/server.mjs:79-80):
+  - per client network, over a rolling 24 h: 250 MiB and 40 new objects
+    across all self-certified identities from it
+    (infra/pillar-blob/server.mjs:113-114). IPv4 counts by address and IPv6
+    by /64, never finer (infra/pillar-blob/server.mjs:118, :121);
+  - self-certified bytes at most 50% of the broker store, counting only
+    uploaded, hash-checked objects, checked at reserve and again at finalize
+    (infra/pillar-blob/server.mjs:115). A reservation that is never finalized
+    expires after 1 h whatever its expiry (infra/pillar-blob/server.mjs:126);
+  - expiry at most 72 h (infra/pillar-blob/server.mjs:117), against 7 days
+    with a badge (infra/pillar-blob/server.mjs:78). The client default is
+    24 h (src/blob/blob.mjs:48);
+  - each self-certified blob can be redeemed at most 20 times
+    (infra/pillar-blob/server.mjs:122).
+
+  On every path, `POST /pillar/blobs/challenge` is limited to 120 a minute
+  per client network (infra/pillar-blob/server.mjs:129). Each limit has a
+  `PILLAR_BLOB_*` variable, and `PILLAR_BLOB_SELF_CERTIFIED=0` turns the
+  self-certified path off (infra/pillar-blob/server.mjs:112). That path makes
+  no registry lookup, so a registry outage does not block it.
+  **Deployment:** until pillar-sfo runs the agent-first broker, the live one
+  still refuses an identity without a badge with 401 `inactive or mismatched
+  registry key` (infra/pillar-blob/server.mjs:332 at `ff46fd8`). **Live**
+  (2026-09-27, pillar-sfo broker, before that release): 32 KiB, 1 MiB and
+  10 MiB round trips between two fleet identities decrypted byte-identical;
+  a fresh unlisted identity was refused as both sender and recipient.
+
+## 4. Push and wake (`apps/pillar-push`)
+
+A push only wakes the phone. It never carries message content and never
+delivers mail. The phone still polls the carriers and decrypts the mail
+itself.
+
+**How the relay learns about mail.** For each registered uuaid with a valid
+poll token (a delegation from the user granting only `inbox`), the relay holds
+a long-poll on every carrier, signed with its own key and carrying the token
+as `x-pillar-delegation` (apps/pillar-push/src/poller.ts:114-131). The first
+poll of a new uuaid on a carrier records the current position and pushes
+nothing for older mail (apps/pillar-push/src/poller.ts:155-161).
+Registrations are re-read every 5 s and at once after each registration
+(apps/pillar-push/src/index.ts:87, apps/pillar-push/src/index.ts:103). An
+envelope seen on several carriers counts once; the relay remembers the last
+1,000 ids per uuaid (apps/pillar-push/src/poller.ts:189).
+
+**Coalescing.** The relay sends at most one push per uuaid per 30 s
+(apps/pillar-push/src/config.ts:44). The first envelope after a quiet window
+is pushed at once with `envelopes: "1"`. Any more in that window become one
+push at the window's end, carrying their count
+(apps/pillar-push/src/dispatcher.ts:61-86).
+
+**Delay, as far as the code sets it:** about 0.4 s for the relay to see a
+stored envelope, then 0 s for the first envelope or up to 30 s for later ones
+in the window, then Google's or Apple's delivery time (not controlled here),
+then the app's own poll.
+
+| Platform | What the push contains | Who sees what |
+|---|---|---|
+| Android (FCM) | data only: `{kind: "pillar-wake", uuaid, envelopes}`, priority HIGH (apps/pillar-push/src/providers/fcm.ts:89-94) | Google sees the recipient's uuaid and the count |
+| iOS (APNs) | `{"aps": {"content-available": 1}}`, background, priority 5 (apps/pillar-push/src/providers/apns.ts:85, apps/pillar-push/src/providers/apns.ts:101-102) | Apple sees the device token and the app's topic. iOS decides when to deliver it |
+
+**On the phone.** On Android, while the app is not on screen,
+`PillarMessagingService` shows one content-free "New message" notification,
+each replacing the last
+(apps/mobile/android/app/src/main/java/org/uuaid/pillar/PillarMessagingService.java:36);
+none if notification permission is off on Android 13+
+(PillarMessagingService.java:44-48), and none while the app is on screen
+(PillarMessagingService.java:43), where its own poll loop shows the mail. A tap opens the app, which polls the carriers (`wait` 25) and decrypts.
+The app has no background fetch: while it is closed, the push is its only
+signal.
+
+**Registration** (`POST /v1/push/register`) is Ed25519-signed; `ts` outside
+±5 min gets 401 `clock-skew` (apps/pillar-push/src/config.ts:49). A uuaid not
+proven by the signing key or an `authExtra` entry gets 401
+`uuaid-not-proven`. At most 50 uuaids per request
+(apps/pillar-push/src/routes/register.ts:42). One invalid poll token rejects
+the whole request with 400 `polltoken-invalid:<reason>`
+(apps/pillar-push/src/routes/register.ts:128-132). A registration without a
+token is stored but never polled. The route has no rate limit.
+
+**Lifetimes.**
+- Poll token: the app mints a 30-day token
+  (apps/mobile/src/services/push-relay.ts:148) for both the persona and the
+  device (apps/mobile/src/services/pillar.ts:2543) at every cold launch
+  (apps/mobile/src/services/pillar.ts:379). The relay stops polling a uuaid
+  once its token's `notAfter` has passed (apps/pillar-push/src/db.ts:111). So
+  a phone whose app is not opened for 30 days stops getting pushes.
+- The persona-to-device delegation lasts 90 days, and the app mints a new one
+  at launch if the old one is no longer valid
+  (apps/mobile/src/services/pillar.ts:269).
+- A dead device token deletes its registration
+  (apps/pillar-push/src/dispatcher.ts:102-105): FCM 404, `UNREGISTERED` or
+  `NOT_FOUND` (apps/pillar-push/src/providers/fcm.ts:116); APNs 410, or 400
+  `BadDeviceToken`/`Unregistered` (apps/pillar-push/src/providers/apns.ts:119).
+
+**Known gap.** A poll loop that is already running keeps the token it started
+with (apps/pillar-push/src/poller.ts:99-103). A new registration stores a
+fresh token, but the loop only uses it after the relay restarts. If the relay
+runs past the first token's expiry, that loop gets a 401 every 2 s and the
+pushes stop, even though a valid token is stored.
+
+**Relay capacity.** Each pollable uuaid takes one community long-poll slot on
+every carrier, out of 48 per carrier (§1). The app registers 2 uuaids per
+phone, so one relay fills a carrier's community slots at 24 phones. After that,
+new long-polls on that carrier, the relay's and everyone else's, get 503
+`busy` while 48 are open.
+
+**Live deployment** (`/push/v1/health`, 2026-09-27): `dryRun: false` and
+`live: ["android"]`. iOS pushes are logged, not sent (`PUSH_LIVE_PLATFORMS`,
+apps/pillar-push/src/config.ts:98-108). `fcmKey` expires 2026-12-24, with
+`daysLeft: 88` (apps/pillar-push/src/routes/health.ts:27-29). At startup the
+relay logs a warning when fewer than 14 days are left
+(apps/pillar-push/src/index.ts:80). The relay watches 6 carriers and holds 4
+registrations and 4 poll tokens.
+
+## 5. Hosting a carrier, seed or relay
+
+`pillar-carrier` and `pillar-seed` listen on 127.0.0.1:8799 by default
+(bin/carrier.mjs:29-30, bin/pillar-seed.mjs:63-64). The relay listens on
+127.0.0.1:8801 (apps/pillar-push/src/config.ts:38-39). Put a TLS proxy in
+front of each one.
+
+| Proxy rule | Why | pillar-sfo (live) and repo template |
+|---|---|---|
+| Carrier read timeout > 30 s + margin | The carrier can hold a request for 30 s plus one 400 ms tick | `/v1/` → 127.0.0.1:8799, 40 s; template: infra/pillar-carrier-fleet/provision-carrier.sh:102 |
+| Replace `X-Forwarded-For` with the peer's address | The carrier takes the first XFF entry as the client IP (:208-212). If the proxy appends to XFF, a client can pick its own rate bucket. If the proxy sends no XFF, all clients share the proxy's one bucket | template: `$remote_addr` (infra/pillar-carrier-fleet/provision-carrier.sh:107) |
+| Body size ≥ largest honored body + 8 KiB | 512 KiB on a seed; 2 MiB + 8 KiB with `--tier-issuers`. Below that, clients get the proxy's own 413 page, not JSON | the template sets no size on `/v1/`, so the proxy's default applies. Set it explicitly |
+| CORS: allow `x-pillar-pubkey`, `x-pillar-ts`, `x-pillar-sig` | Browser clients send them. Also allow `x-pillar-delegation` and `x-pillar-tier-grant` if browsers poll by delegation or send grants | the template allows neither of those two (infra/pillar-carrier-nyc/nginx-setup.sh:25) |
+| Relay: a short timeout is fine | No relay route long-polls | `/push/` → 127.0.0.1:8801/, 30 s |
+| Blob objects: at least 50 MiB + headers | The largest blob object is 50 MiB | `/blob/objects/` 52m and 300 s; `/blob/` 1m and 40 s (infra/pillar-carrier-nyc/install-blob.sh:59-62, infra/pillar-carrier-nyc/install-blob.sh:71-74) |
+
+**Under load:**
+- **`carrier-full` does not clear by itself.** `vacuum()` deletes expired rows
+  (:239-243) but never runs SQLite `VACUUM`. The size check reads `page_count`
+  (:308-311), which still counts freed pages. In a local test with the same
+  schema, deleting all 300 rows of a 30,904,320-byte store left
+  `page_count × page_size` at 30,904,320 bytes, with 7,540 pages free. So once
+  the file passes 217.6 MiB, community sends get 503 until you stop the
+  carrier, run `sqlite3 <db> 'VACUUM;'`, and restart it. On a `pillar-seed`
+  every sender is community, so that means everyone. Watch the file size.
+- Sends get 429 and 503 as in §1; new long-polls get 503 `busy` once 48
+  community (64 in all) are open.
+- Nothing limits `wait=0` reads, `/v1/health` or `/v1/seed-info`. Rate-limit
+  them in your proxy if you need to.
+- A restart resets all rate budgets and cuts every open long-poll (the shipped
+  clients retry after 2 s). Stored envelopes stay in SQLite. Leave disk for a
+  256 MiB store plus its WAL file.
+
+**Relay host.** Back up `PUSH_RELAY_SEED_PATH`. Every poll token names the
+relay's key, so losing that file invalidates all of them
+(apps/pillar-push/src/config.ts:19-22). Watch `fcmKey.daysLeft` on
+`/v1/health`.
+
+## 6. Refusal codes
+
+Every refusal names a stable code and one line saying what to do. The
+carrier's code is the `reason` of a refused send or the `error` of a refused
+inbox read; the broker's is its `code`. `pillar` and `pillar-blob` print a
+refusal as one line, `<code>: <fix>`: the server's `fix` when it sends one,
+printed as received (only line breaks and control characters become spaces),
+else the client's map (src/net/refusals.mjs:24-73, exported as
+`@uuaid/pillar/refusals`). A carrier older than 0.2.0-alpha.18 sends no
+`fix`; the client fills it in. On a thrown error, `err.code` and `err.fix`
+carry the same pair. Every fix, the client's and both servers', is a fixed
+string from a closed set: none is built from request data, a remote reason
+or an exception message. A parameterised reason such as
+`delegation-invalid:<why>` gets its family's fix, without `<why>`.
+
+### Carrier
+
+| Code | Status | Fix |
+|---|---|---|
+| `rate-limited` | 429 | Back off: budgets refill over a sliding 60 s, so retry after 5 s, doubling to 60 s |
+| `body-too-large` | 413 | Send the payload as a blob (`pillar-blob send`); `maxBodyBytes` is your tier's inline limit |
+| `stale-envelope` | 400 | Seal a new envelope and check your clock; `createdAt` must be within 24 h of carrier time |
+| `carrier-full` | 503 | Use your other carriers and do not retry this one soon; its store is full |
+| `bad-recipient` | 400 | Address the envelope to a full UUAID (`uuaid:<namespace>:<type>:<id>`) |
+| `bad-json` | 400 | POST the envelope as one JSON object |
+| `keyId-sender-mismatch` | 400 | Sign with `transportSignature.keyId` equal to the sender UUAID, or send under a delegation |
+| `publicKey-sender-mismatch` | 400 | Send from the UUAID your signing key derives, or attach the principal's delegation |
+| `bad-signature` | 400, 401 | Sign again with this identity's own key over the exact bytes; the signature does not verify |
+| `not-object`, `bad-version <v>`, `missing-or-bad-alg`, `alg-not-active:<alg>`, `bad-publicKey`, `bad-signature-encoding`, `missing-enc`, `enc-alg-not-supported:<alg>`, `enc-alg-not-active:<alg>`, `bad-epk`, `bad-iv`, `bad-ct`, `bad-canonical`, `verify-threw` | 400 (`verify-threw` also 401) | Re-seal the envelope with `seal()` from `@uuaid/pillar` or `@uuaid/pillar-client`; this one does not verify |
+| `delegation-invalid:<why>` | 403 (send), 401 (inbox) | Mint a fresh delegation from the principal, then resend |
+| `missing-auth-headers` | 401 | Send `x-pillar-pubkey`, `x-pillar-ts` and `x-pillar-sig` |
+| `bad-pubkey` | 401 | Send `x-pillar-pubkey` as the raw Ed25519 key in 64 hex characters |
+| `bad-sig-encoding` | 401 | Send `x-pillar-sig` as 128 hex characters |
+| `clock-skew` | 401 | Fix your clock (NTP) to within 5 min of the carrier; retrying does not help |
+| `uuaid-pubkey-mismatch` | 401 | Read the inbox of the UUAID your key derives, or send that UUAID's delegation in `x-pillar-delegation` |
+| `delegation-unparseable` | 401 | Send `x-pillar-delegation` as the JSON delegation document |
+| `delegation-too-large` | 401 | Send a delegation document under 8,192 bytes |
+| `delegation-principal-mismatch` | 401 | Use a delegation whose principal is the inbox UUAID |
+| `delegation-delegate-key-mismatch` | 401 | Sign with the key the delegation names as delegate |
+| `delegation-inbox-denied` | 401 | Ask the principal for a delegation that covers `inbox` (or `*`) |
+| `busy` | 503 | Retry after at least 2 s with jitter, or poll with `wait=0` for a while |
+| `not-found` | 404 | Use `POST /v1/envelopes` or `GET /v1/inbox/<uuaid>` |
+| `not-a-seed` | 404 | Do not list this carrier as a seed; it runs without a seed identity |
+| `internal-error` | 500 | Retry later; if it repeats, tell the carrier operator |
+
+### Client (no server gave a code)
+
+| Code | Where | Fix |
+|---|---|---|
+| `carrier-unreachable` | every carrier failed without answering | Check the carrier URLs and your network, then retry |
+| `carrier-bad-response` | a carrier or its proxy answered without a reason | Retry, or use another carrier |
+| `over-tier-limit`, `blob-too-large` | send preflight, before any network call (src/net/carrier-client.mjs:90) | Send the payload as a blob (`pillar-blob send`, or `Pillar.sendBlob`) |
+| `blob-key-unproven` | `pillar-blob`, before signing a broker request | Use a `uuaid:foundation:agent` UUAID derived from this key (`pillar init`), or get a registry badge that names this key |
+| `sender-key-not-active` | `pillar-blob get`, before redeeming | Ask the sender to send from a `uuaid:foundation:agent` UUAID derived from its own key, or to get a registry badge naming its key |
+
+### Broker (`pillar-blob`)
+
+The agent-first broker answers every refusal with
+`{error, code, fix, ...numbers}`; its 46 codes and fixes are one closed table
+of plain strings (infra/pillar-blob/server.mjs:141-194). `error` is the sentence
+it has always sent, and a number a fix names is a field of the same
+response; quota and rate refusals add `retry_after_seconds`. The client puts
+`code`, `fix` and the body on the thrown error (src/blob/http.mjs:110-116).
+The deployed broker (`ff46fd8`) sends no `code`, so the client keeps its own
+`blob-broker-not-found`, `-expired`, `-replay` or `-rejected` (by status),
+which stays available as `err.legacyCode` either way.
+
+| Code | Status | Fix |
+|---|---|---|
+| `request_body_invalid` | 400 | Send a JSON object body with content-type application/json. |
+| `request_body_too_large` | 413 | Keep broker JSON requests under 128 KiB; the file itself goes to upload.url. |
+| `challenge_request_invalid` | 400 | POST {"action":"reserve"\|"finalize"\|"redeem","agent_uuaid":"uuaid:&lt;namespace>:&lt;type>:&lt;id>"}. |
+| `object_id_required` | 400 | Include object_id (64 hex, from your reserve response or blob-ref) for finalize and redeem. |
+| `object_id_not_allowed` | 400 | Omit object_id for reserve; the broker assigns it in the challenge. |
+| `signed_request_malformed` | 400 | Send {payload:{v:1,audience:"uuaid:pillar-blob:v1",challenge,request}, payloadHash:"0x"+sha256(jcs(payload)), signatures:[one ed25519 signature]}. |
+| `reserve_request_malformed` | 400 | Give reserve a recipient_uuaid, ciphertext_sha256 (64 hex), ciphertext_bytes (integer > 0) and expires_at (ISO 8601). |
+| `action_endpoint_mismatch` | 400 | POST reserve, finalize and redeem requests to /pillar/blobs/reserve, /finalize and /redeem respectively. |
+| `challenge_unknown` | 401 | POST /pillar/blobs/challenge and sign the challenge it returns. |
+| `challenge_expired` | 401 | POST /pillar/blobs/challenge for a fresh challenge and use it before its expires_at. |
+| `challenge_consumed` | 409 | Challenges are single-use: POST /pillar/blobs/challenge for a fresh one and sign again. |
+| `challenge_mismatch` | 401 | Sign the challenge exactly as returned, with request.action and request.agent_uuaid equal to its action and agent_uuaid. |
+| `challenge_rate_limited` | 429 | Wait retry_after_seconds; this network asked for more than max_per_minute challenges in a minute. |
+| `registry_key_inactive` | 401 | Sign with keyId "self-certified:ed25519" as uuaid:foundation:agent:&lt;local id derived from your key>, or with the keyId your registry badge names. |
+| `self_certified_uuaid_mismatch` | 401 | With keyId "self-certified:ed25519", agent_uuaid must be exactly uuaid:foundation:agent:&lt;first 16 bytes of sha256(publicKey), hex 8-4-4-4-12>; any other UUAID needs a registry badge. |
+| `self_certified_disabled` | 401 | Sign with the keyId your registry badge names; this broker accepts registry badges only. |
+| `registry_unavailable` | 502, 503 | Retry in a minute; keyId "self-certified:ed25519" with a key-derived uuaid:foundation:agent UUAID does not need the registry. |
+| `signature_invalid` | 401 | Sign the UTF-8 bytes of jcs(payload) with the ed25519 key whose publicKey you send. |
+| `object_too_large` | 413 | Keep ciphertext_bytes at or under max_bytes; split larger files. |
+| `expiry_out_of_range` | 400, 410 | Set expires_at between min_ttl_ms and max_ttl_ms from now. |
+| `self_certified_ttl_exceeded` | 400 | Set expires_at at most max_ttl_ms from now; a registry badge allows longer. |
+| `daily_quota_exceeded` | 429 | Wait retry_after_seconds, or send fewer or smaller blobs; this identity's 24-hour quota is used up. |
+| `self_certified_ip_quota_exceeded` | 429 | Wait retry_after_seconds; self-certified senders from this network have used their 24-hour allowance. |
+| `self_certified_pool_full` | 507 | Reserve again later; the self-certified share of the store (uploaded bytes) is full. |
+| `store_full` | 507 | Retry later or with a shorter expires_at; the broker's store is full. |
+| `reservation_not_found` | 404 | Finalize only an object_id you reserved, as the same agent_uuaid, before it expires. |
+| `reservation_not_finalizable` | 409 | This object is already finalized or quarantined; reserve a new object to send again. |
+| `reservation_expired` | 410 | Reserve again, then upload and finalize within max_age_ms of reserving and before expires_at. |
+| `upload_not_found` | 422 | PUT the ciphertext to upload.url before finalizing; this object is now quarantined, so reserve again. |
+| `upload_integrity_mismatch` | 422 | Upload exactly the reserved ciphertext (same sha256 and byte count); if the object is quarantined, reserve again. |
+| `upload_ticket_invalid` | 403 | PUT to upload.url from your reserve response within expiresIn seconds; reserve again if it lapsed. |
+| `upload_not_accepted` | 409 | This object is no longer accepting uploads; reserve a new object to send again. |
+| `content_length_mismatch` | 411 | Send Content-Length equal to expected_bytes, the ciphertext_bytes you reserved. |
+| `upload_too_large` | 413 | Send exactly the ciphertext_bytes you reserved, no more. |
+| `upload_failed` | 400 | Retry the PUT to upload.url while its ticket is valid. |
+| `not_recipient` | 403 | Redeem as the recipient_uuaid the sender named; only that identity may fetch this blob. |
+| `blob_unavailable` | 409 | The sender has not finalized this object; ask the sender to send it again. |
+| `blob_expired` | 410 | The blob is past its expires_at; ask the sender to send it again. |
+| `redeem_limit_reached` | 410 | This blob has been redeemed max_redeems times; ask the sender to send it again. |
+| `blob_not_found` | 404 | Check the object_id; the blob may have expired or never been finalized. |
+| `stored_blob_missing` | 404, 422 | The broker no longer has this object; ask the sender to send it again. |
+| `stored_blob_corrupt` | 422 | The stored object failed its integrity check; ask the sender to send it again. |
+| `download_ticket_invalid` | 403 | Redeem again for a fresh download.url and GET it within expiresIn seconds. |
+| `method_not_allowed` | 405 | PUT /objects/&lt;id> to upload and GET /objects/&lt;id> to download, each with its ticket query. |
+| `not_found` | 404 | Use POST /pillar/blobs/{challenge,reserve,finalize,redeem}, PUT or GET /objects/&lt;id>, or GET /healthz. |
+| `internal_error` | 500 | Retry once; if it fails again, report the time and path to the broker operator. |

package/README.md

@@ -15,7 +15,7 @@ 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 >= 20, outbound HTTPS. That's it. Carrier
+**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.
 
@@ -399,14 +399,18 @@ rate and body size — see "Tier grants" above for the ladder. It is a
 
 ## 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
-  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.
+  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

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

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

@@ -3,20 +3,33 @@
  * 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
+ *                    [--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 } from "../src/blob/http.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");
@@ -43,16 +56,21 @@ function loadHome(args) {
   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";
+  // 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 };
+  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.code : "error";
-  process.stderr.write(`pillar-blob: ${code}: ${error?.message ?? String(error)}\n`);
+  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);
 }
 
@@ -93,9 +111,16 @@ try {
     }
   } else if (command === "get") {
     if (!args["ref-file"] || !args["expect-envelope"]) usage();
-    const { keychain, client } = loadHome(args);
+    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"],
@@ -104,7 +129,9 @@ try {
     });
     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`);
+    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);

package/bin/pillar-directory.mjs

@@ -22,6 +22,7 @@
  * `agents.json` is passed through untouched: this process owns the seed list,
  * not the address book.
  */
+import "../src/node-check.mjs"; // must stay the first import: refuses Node < 22 before any dependency loads
 import { createServer } from "node:http";
 import { readFileSync, existsSync, mkdirSync } from "node:fs";
 import { homedir } from "node:os";

package/bin/pillar-escrow.mjs

@@ -42,6 +42,7 @@
  * (who absorbs the fee: the seller, the buyer, or 50/50) or --payout N (the
  * parties' own number; a "mutual" agreement).  No default is ever derived.
  */
+import "../src/node-check.mjs"; // must stay the first import: refuses Node < 22 before any dependency loads
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { homedir } from "node:os";

package/bin/pillar-responder.mjs

@@ -31,6 +31,7 @@
  *     --reply-text "zz-master is away — left a message" \
  *     --forward-to uuaid:foundation:agent:… --forward-pubkey <hex>
  */
+import "../src/node-check.mjs"; // must stay the first import: refuses Node < 22 before any dependency loads
 import { existsSync, readFileSync, appendFileSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";

package/bin/pillar-seed.mjs

@@ -39,6 +39,7 @@
  * TLS-terminating proxy (nginx/Caddy) and pass the PUBLIC https:// URL as
  * --public-url — never the loopback one.
  */
+import "../src/node-check.mjs"; // must stay the first import: refuses Node < 22 before any dependency loads
 import { mkdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";