@uuaid/pillar 0.2.0-alpha.9 → 2.0.1

package/src/net/delegation.mjs

@@ -0,0 +1,209 @@
+/**
+ * Device/persona delegation — UACP/1.0 protocol extension (carrier side).
+ *
+ * A long-lived "persona" UUAID (the principal) authorizes a short-lived
+ * device identity (the delegate) to act on its behalf for specific envelope
+ * kinds and a bounded time window.  The persona signs a JCS-canonical
+ * delegation document; the device embeds that document in the envelope's
+ * `delegation` field and signs the whole envelope with ITS OWN key.
+ *
+ *   delegation = {
+ *     version:   "uuaid-delegation/1",
+ *     id:        "del-...",
+ *     principal: persona uuaid,   principalPublicKey: hex,
+ *     delegate:  device  uuaid,   delegatePublicKey:  hex,
+ *     kinds:     ["*"] or ["request","reply",...],
+ *     notBefore, notAfter: ISO 8601,
+ *     signature: { alg: "ed25519", publicKey, signature },
+ *   }
+ *   signature = ed25519(JCS(delegation minus .signature), principalSeed)
+ *
+ * Wire-compatible with @uuaid/pillar-client's delegation.ts (mintDelegation /
+ * verifyDelegation / sealWithDelegation / verifyDelegatedEnvelope): same
+ * document shape, same JCS canonicalization, same rejection reason strings,
+ * so a carrier and a pillar-client peer reach the same verdict on the same
+ * bytes.
+ *
+ * Envelope acceptance rules (envelope.mjs open() branches here when the
+ * optional `delegation` field is present; absent -> legacy behavior,
+ * unchanged):
+ *   (a) envelope transport signature valid under the DELEGATE's pubkey and
+ *       transportSignature.keyId === delegate uuaid;
+ *   (b) delegation document signature valid under the PRINCIPAL's pubkey,
+ *       principal === envelope.sender, delegate === signing key's uuaid;
+ *   (c) local-id binding for BOTH identities:
+ *       sha256(pubkey)[:16] (UUID-dash formatted) === uuaid local-id;
+ *   (d) now within [notBefore, notAfter];
+ *   (e) envelope.kind covered by the delegation `kinds` allowlist
+ *       ("*" covers everything), and not a capability-only name such as
+ *       "inbox" — those are poll capabilities, never deliverable kinds, and
+ *       are refused even under "*" (see CAPABILITY_ONLY_KINDS).
+ * All five must pass; any failure rejects with
+ * `delegation-invalid:<reason>` (HTTP 403 at the carrier).
+ *
+ * Storage/mailbox attribution is unchanged: the envelope's `sender` IS the
+ * principal, so carriers key mailboxes, rate limits, and audits to the
+ * principal UUAID exactly as before.
+ */
+import { randomBytes } from "node:crypto";
+import { jcs } from "../identity/jcs.mjs";
+import { Keychain } from "../identity/keychain.mjs";
+
+export const DELEGATION_VERSION = "uuaid-delegation/1";
+
+/**
+ * Mint a delegation document, signed by the PRINCIPAL keychain.
+ *
+ * The counterpart to verifyDelegationDoc below, and the .mjs twin of
+ * pillar-client's mintDelegation (delegation.ts): same field order, same
+ * id shape, same JCS canonicalization, same signature placement — so a
+ * document minted here verifies byte-identically in a browser, and vice
+ * versa. A divergence in either direction is a wire break, not a style
+ * difference.
+ *
+ * Nothing here knows what KIND of principal is signing. A phone, a CLI and
+ * a daemon mint the same bytes; the only requirement is custody of the
+ * persona seed. That is what lets a headless agent link a browser.
+ *
+ * CALLER BEWARE — ttlDays defaults to 90 to match pillar-client, but the
+ * desktop-link path enforces a 7-day ceiling of its own (D14, chat-web's
+ * withinLinkTtl) and DROPS a longer grant in silence. Pass ttlDays <= 7 for
+ * a browser link; see bin/pillar.mjs cmdDelegate, which refuses rather than
+ * let that failure be invisible.
+ */
+export function mintDelegationDoc(keychain, opts = {}) {
+  const principal = keychain?._identity;
+  if (!principal?.publicKeyHex) throw new Error("mintDelegationDoc: principal identity not loaded");
+  const { delegate, delegatePublicKey } = opts;
+  if (typeof delegate !== "string" || !delegate.startsWith("uuaid:")) {
+    throw new Error("mintDelegationDoc: delegate uuaid required");
+  }
+  if (typeof delegatePublicKey !== "string" || !/^[0-9a-f]{64}$/i.test(delegatePublicKey)) {
+    throw new Error("mintDelegationDoc: delegatePublicKey must be 64 hex");
+  }
+  const kinds = Array.isArray(opts.kinds) && opts.kinds.length ? [...opts.kinds] : ["*"];
+  const start = opts.notBefore instanceof Date ? opts.notBefore : new Date();
+  const ttlDays = Number.isFinite(opts.ttlDays) ? opts.ttlDays : 90;
+  const end = new Date(start.getTime() + ttlDays * 24 * 60 * 60 * 1000);
+  const unsigned = {
+    version: DELEGATION_VERSION,
+    id: `del-${Date.now().toString(36)}-${randomBytes(6).toString("hex")}`,
+    principal: principal.uuaid,
+    principalPublicKey: principal.publicKeyHex,
+    delegate,
+    delegatePublicKey: delegatePublicKey.toLowerCase(),
+    kinds,
+    notBefore: start.toISOString(),
+    notAfter: end.toISOString(),
+  };
+  const signature = keychain.sign(jcs(unsigned));
+  return {
+    ...unsigned,
+    signature: {
+      alg: "ed25519",
+      publicKey: principal.publicKeyHex,
+      signature: Buffer.from(signature).toString("hex"),
+    },
+  };
+}
+
+/**
+ * Extract the local-id of a UUAID with pillar-client parseUuaid semantics:
+ * exactly four colon-separated segments with the "uuaid" prefix.
+ * Returns null for anything else (never throws).
+ */
+export function uuaidLocalId(uuaid) {
+  if (typeof uuaid !== "string") return null;
+  const parts = uuaid.split(":");
+  if (parts.length !== 4 || parts[0] !== "uuaid") return null;
+  return parts[3];
+}
+
+/** Self-authenticating identity check: sha256(pubkey)[:16] === uuaid local-id. */
+export function uuaidBindingOk(uuaid, publicKeyHex) {
+  const localId = uuaidLocalId(uuaid);
+  if (localId === null) return false;
+  if (typeof publicKeyHex !== "string" || !/^[0-9a-f]{64}$/i.test(publicKeyHex)) return false;
+  return Keychain.localIdFromKey(Buffer.from(publicKeyHex, "hex")) === localId;
+}
+
+/**
+ * Verify a delegation document on its own: shape, identity bindings, time
+ * window, and the principal's signature over JCS(doc minus .signature).
+ *
+ * Reason strings intentionally mirror @uuaid/pillar-client verifyDelegation
+ * so tooling sees identical diagnostics on both implementations.
+ *
+ * Returns { ok: true } or { ok: false, reason }.
+ */
+export function verifyDelegationDoc(d, now = new Date()) {
+  if (!d || typeof d !== "object" || Array.isArray(d)) return { ok: false, reason: "not-object" };
+  if (d.version !== DELEGATION_VERSION) return { ok: false, reason: `bad-version:${d.version}` };
+  if (!/^[0-9a-f]{64}$/i.test(d.principalPublicKey ?? "")) return { ok: false, reason: "bad-principal-pubkey" };
+  if (!/^[0-9a-f]{64}$/i.test(d.delegatePublicKey ?? "")) return { ok: false, reason: "bad-delegate-pubkey" };
+  if (!uuaidBindingOk(d.principal, d.principalPublicKey)) {
+    return { ok: false, reason: "principal-uuaid-binding" };
+  }
+  if (!uuaidBindingOk(d.delegate, d.delegatePublicKey)) {
+    return { ok: false, reason: "delegate-uuaid-binding" };
+  }
+  if (!Array.isArray(d.kinds) || d.kinds.length === 0 || d.kinds.some(k => typeof k !== "string")) {
+    return { ok: false, reason: "bad-kinds" };
+  }
+  const nb = Date.parse(d.notBefore);
+  const na = Date.parse(d.notAfter);
+  if (Number.isNaN(nb) || Number.isNaN(na)) return { ok: false, reason: "bad-time" };
+  if (na <= nb) return { ok: false, reason: "empty-window" };
+  const t = now instanceof Date ? now.getTime() : Number(now);
+  if (t < nb) return { ok: false, reason: "not-yet-valid" };
+  if (t > na) return { ok: false, reason: "expired" };
+
+  const sig = d.signature;
+  if (!sig || sig.alg !== "ed25519" || sig.publicKey !== d.principalPublicKey) {
+    return { ok: false, reason: "bad-signature-shape" };
+  }
+  if (typeof sig.signature !== "string" || !/^[0-9a-f]{128}$/i.test(sig.signature)) {
+    return { ok: false, reason: "bad-signature-shape" };
+  }
+  // The signature covers JCS of everything except .signature.
+  const { signature: _drop, ...unsigned } = d;
+  let canonical;
+  try { canonical = jcs(unsigned); } catch (_e) { return { ok: false, reason: "bad-canonical" }; }
+  let okSig = false;
+  try {
+    okSig = Keychain.verifyDetached(sig.publicKey, Buffer.from(canonical, "utf-8"), Buffer.from(sig.signature, "hex"));
+  } catch (_e) {
+    return { ok: false, reason: "verify-threw" };
+  }
+  if (!okSig) return { ok: false, reason: "bad-signature" };
+  return { ok: true };
+}
+
+/**
+ * Names that may appear in a delegation's `kinds` as CAPABILITIES but are not
+ * envelope kinds, and so must never be deliverable.
+ *
+ * `kinds` is a single namespace answering two different questions: "may this
+ * delegate SEND envelopes of kind K" (envelope.mjs) and "may this delegate
+ * POLL the principal's inbox" (carrier-server.mjs, capability "inbox"). The
+ * overlap means a token minted read-only as `kinds: ["inbox"]` also satisfies
+ * the send check for an envelope whose `kind` is literally "inbox" — verified
+ * against a live alpha.15 carrier, which returned 202 for exactly that forgery
+ * while correctly returning 403 kind-not-covered for message/request/reply.
+ *
+ * Nothing consumes `kind: "inbox"`, so this is latent rather than live. It
+ * stops being latent the moment a read-only poll token is issued to anyone,
+ * which is what the push relay is being rebuilt to use.
+ *
+ * Enforced on the send path in envelope.mjs. Deliberately NOT enforced inside
+ * delegationCoversKind: that helper serves both questions, and the capability
+ * lookup in carrier-server.mjs depends on "inbox" matching there.
+ */
+export const CAPABILITY_ONLY_KINDS = new Set(["inbox"]);
+
+/** Does this delegation cover envelopes of `kind`?  "*" covers all. */
+export function delegationCoversKind(d, kind) {
+  if (!Array.isArray(d?.kinds)) return false;
+  if (d.kinds.includes("*")) return true;
+  return d.kinds.includes(kind);
+}

package/src/net/envelope.mjs

@@ -30,6 +30,7 @@ import { createHash, randomBytes } from "node:crypto";
 import { jcs } from "../identity/jcs.mjs";
 import { Keychain } from "../identity/keychain.mjs";
 import { sealPayload, openPayload, E2E_ALG } from "../crypto/e2e.mjs";
+import { verifyDelegationDoc, delegationCoversKind, CAPABILITY_ONLY_KINDS } from "./delegation.mjs";
 
 export const ENVELOPE_VERSION = "uuaid-pillar-envelope/2";
 export { E2E_ALG };
@@ -92,6 +93,11 @@ export function seal(keychain, body) {
  * Verify an envelope's transport signature and structure.  Does NOT decrypt.
  * Anyone (carriers, relays, auditors) can call this.
  * Returns { ok: true } or { ok: false, reason }.
+ *
+ * DELEGATED ENVELOPES (UACP/1.0 ext): when the optional `delegation` field is
+ * present, the self-authenticating-sender rule is replaced by the delegation
+ * chain — see openDelegated() below and src/net/delegation.mjs.  When the
+ * field is ABSENT the checks below are byte-for-byte the legacy behavior.
  */
 export function open(envelope, { cryptoInventory } = {}) {
   if (!envelope || typeof envelope !== "object" || Array.isArray(envelope)) return { ok: false, reason: "not-object" };
@@ -101,6 +107,9 @@ export function open(envelope, { cryptoInventory } = {}) {
   if (cryptoInventory && cryptoInventory[sig.alg] !== "active") {
     return { ok: false, reason: `alg-not-active:${sig.alg}` };
   }
+  if (envelope.delegation !== undefined) {
+    return openDelegated(envelope, { cryptoInventory });
+  }
   if (sig.keyId !== envelope.sender) return { ok: false, reason: "keyId-sender-mismatch" };
   if (typeof sig.publicKey !== "string" || !/^[0-9a-f]{64}$/i.test(sig.publicKey)) return { ok: false, reason: "bad-publicKey" };
   if (typeof sig.signature !== "string" || !/^[0-9a-f]{128}$/i.test(sig.signature)) return { ok: false, reason: "bad-signature-encoding" };
@@ -136,6 +145,78 @@ export function open(envelope, { cryptoInventory } = {}) {
   return { ok: true };
 }
 
+/**
+ * Delegated path of open() — UACP/1.0 extension.  Invoked when the envelope
+ * carries a `delegation` document; the legacy self-authenticating-sender rule
+ * is REPLACED by the five delegation checks (see delegation.mjs):
+ *
+ *   (a) envelope signature valid under the DELEGATE's key,
+ *       transportSignature.keyId === delegation.delegate;
+ *   (b) delegation document signature valid under the PRINCIPAL's key,
+ *       delegation.principal === envelope.sender,
+ *       delegation.delegate === the signing key's uuaid;
+ *   (c) local-id binding for BOTH identities (inside verifyDelegationDoc);
+ *   (d) now within [notBefore, notAfter] (inside verifyDelegationDoc);
+ *   (e) envelope.kind covered by delegation.kinds.
+ *
+ * Fail-open is not an option: any failure rejects with
+ * { ok: false, reason: "delegation-invalid:<reason>", code: 403 }.  Pure
+ * wire-format failures (enc block, hex encodings) keep the legacy reasons and
+ * 400 status — they are not delegation verdicts.
+ *
+ * The `delegation` field is part of the SIGNED body (sealed inside the
+ * canonicalization by the delegate), so a carrier cannot strip or swap it
+ * without breaking the envelope signature.
+ */
+function openDelegated(envelope, { cryptoInventory } = {}) {
+  const reject = (reason) => ({ ok: false, reason: `delegation-invalid:${reason}`, code: 403 });
+  const sig = envelope.transportSignature;
+  if (typeof sig.publicKey !== "string" || !/^[0-9a-f]{64}$/i.test(sig.publicKey)) return { ok: false, reason: "bad-publicKey" };
+  if (typeof sig.signature !== "string" || !/^[0-9a-f]{128}$/i.test(sig.signature)) return { ok: false, reason: "bad-signature-encoding" };
+  // Structural checks on the encryption block — same rules as the legacy path.
+  const enc = envelope.enc;
+  if (!enc || typeof enc !== "object") return { ok: false, reason: "missing-enc" };
+  if (enc.alg !== E2E_ALG) return { ok: false, reason: `enc-alg-not-supported:${enc.alg}` };
+  if (cryptoInventory && cryptoInventory[enc.alg] && cryptoInventory[enc.alg] !== "active") {
+    return { ok: false, reason: `enc-alg-not-active:${enc.alg}` };
+  }
+  if (typeof enc.epk !== "string" || !/^[0-9a-f]{64}$/i.test(enc.epk)) return { ok: false, reason: "bad-epk" };
+  if (typeof enc.iv !== "string" || !/^[0-9a-f]{24}$/i.test(enc.iv)) return { ok: false, reason: "bad-iv" };
+  if (typeof enc.ct !== "string" || !/^[0-9a-f]{32,}$/i.test(enc.ct)) return { ok: false, reason: "bad-ct" };
+
+  const d = envelope.delegation;
+  // (b-i) + (c) + (d): the delegation document itself — shape, both local-id
+  // bindings, time window, and the principal's signature over it.
+  const dv = verifyDelegationDoc(d);
+  if (!dv.ok) return reject(dv.reason);
+  // (b-ii) the persona this envelope acts as must be the delegation principal.
+  if (d.principal !== envelope.sender) return reject("sender-not-principal");
+  // (b-iii) the actual signer must be the named delegate, key and all.
+  if (sig.keyId !== d.delegate) return reject("signer-not-delegate");
+  if (sig.publicKey !== d.delegatePublicKey) return reject("signer-key-mismatch");
+  // (e) the delegation must cover this envelope kind.
+  //
+  // A capability name is checked FIRST and unconditionally — including under
+  // kinds:["*"] — because these names are not envelope kinds at all. Without
+  // this, a read-only kinds:["inbox"] poll token doubles as authority to send
+  // envelopes of kind "inbox" as the principal. See CAPABILITY_ONLY_KINDS.
+  if (CAPABILITY_ONLY_KINDS.has(envelope.kind)) return reject("kind-reserved-capability");
+  if (!delegationCoversKind(d, envelope.kind)) return reject("kind-not-covered");
+  // (a) the envelope signature under the delegate key, over the canonical
+  // body INCLUDING the delegation field (exactly what the delegate signed).
+  const { transportSignature: _sig, ...withoutSig } = envelope;
+  let canonical;
+  try { canonical = jcs(withoutSig); } catch (_e) { return { ok: false, reason: "bad-canonical" }; }
+  let okSig;
+  try {
+    okSig = Keychain.verifyDetached(sig.publicKey, Buffer.from(canonical, "utf-8"), Buffer.from(sig.signature, "hex"));
+  } catch (_e) {
+    return { ok: false, reason: "verify-threw" };
+  }
+  if (!okSig) return reject("bad-envelope-signature");
+  return { ok: true, delegated: true, actingFor: d.principal };
+}
+
 /**
  * Decrypt an envelope's payload.  Only the recipient can do this.
  * keychain must be the recipient's loaded keychain.

package/src/net/link-offer.mjs

@@ -0,0 +1,107 @@
+/**
+ * `uuaid://link/…` — desktop linking offer, principal side.
+ *
+ * A browser tab that is not yet paired mints its OWN device identity and
+ * publishes it as an offer:
+ *
+ *   uuaid://link/<url-encoded-delegate-uuaid>?pk=<64hex>&nonce=<hex>&exp=<iso>
+ *
+ * A phone renders that string as a QR and scans it. Nothing about the offer
+ * requires a camera: the QR is a rendering of this string, not a format of
+ * its own, so any principal that can read the string can complete the
+ * handshake. That is what makes `pillar delegate --to-browser` possible for
+ * an agent, which has a persona seed but no phone.
+ *
+ * Structural parity with `apps/mobile/src/services/link-offer.ts` is
+ * deliberate and load-bearing — same regexes, same rejection points, same
+ * "null means ignore safely" contract — because the browser on the other end
+ * validates what the phone would have sent. Change one, change both.
+ *
+ * Parsing is not authorization: `parseLinkOffer` checks shape only. Liveness
+ * (`isLinkOfferLive`) and single-use are the caller's job.
+ */
+
+export const LINK_OFFER_DEEPLINK_HOST = "link";
+
+/**
+ * The kinds a desktop-link grant covers: exactly what the phone grants
+ * (apps/mobile pillar.ts LINK_GRANT_KINDS, plan D12). No "inbox": the desktop
+ * polls its OWN inbox and never reads the principal's, and no "*", which a
+ * carrier reads as covering "inbox" (carrier-server delegationCoversKind).
+ */
+export const LINK_GRANT_KINDS = Object.freeze(["message", "request", "reply", "ack"]);
+
+const UUAID_RE = /^uuaid:[a-z0-9-]+:[a-z0-9-]+:[a-z0-9][a-z0-9-]*$/i;
+const PK_RE = /^[0-9a-f]{64}$/i;
+const NONCE_RE = /^[0-9a-f]{8,64}$/i;
+
+export function isValidLinkDelegate(delegate) {
+  return typeof delegate === "string" && UUAID_RE.test(delegate);
+}
+
+export function isValidLinkPublicKey(pk) {
+  return typeof pk === "string" && PK_RE.test(pk);
+}
+
+export function isValidLinkNonce(nonce) {
+  return typeof nonce === "string" && NONCE_RE.test(nonce);
+}
+
+/**
+ * Parse a `uuaid://link/…` offer. Structural validation only — shape and
+ * field formats, including that `exp` parses as a date. Does NOT check
+ * whether the offer has expired (see isLinkOfferLive). Returns null for
+ * anything malformed; callers must treat null as "ignore safely".
+ */
+export function parseLinkOffer(raw) {
+  if (typeof raw !== "string") return null;
+  const trimmed = raw.trim();
+  if (!trimmed) return null;
+  let u;
+  try {
+    // URL/URLSearchParams can silently mangle malformed percent escapes
+    // rather than throwing, so validate the encoding across the whole link
+    // before trusting any field of it.
+    decodeURI(trimmed);
+    u = new URL(trimmed);
+  } catch {
+    return null;
+  }
+  if (u.protocol.toLowerCase() !== "uuaid:") return null;
+  if (u.hostname.toLowerCase() !== LINK_OFFER_DEEPLINK_HOST) return null;
+  let delegate;
+  try {
+    delegate = decodeURIComponent(u.pathname.replace(/^\/+/, ""));
+  } catch {
+    return null;
+  }
+  if (!isValidLinkDelegate(delegate)) return null;
+  const pk = (u.searchParams.get("pk") ?? "").trim().toLowerCase();
+  const nonce = (u.searchParams.get("nonce") ?? "").trim().toLowerCase();
+  const exp = (u.searchParams.get("exp") ?? "").trim();
+  if (!isValidLinkPublicKey(pk)) return null;
+  if (!isValidLinkNonce(nonce)) return null;
+  if (!exp || Number.isNaN(Date.parse(exp))) return null;
+  return { delegate, pk, nonce, exp };
+}
+
+/** Build the offer string (the form a browser publishes; here for tests). */
+export function buildLinkOffer(offer) {
+  if (!isValidLinkDelegate(offer?.delegate)) throw new Error("link offer: invalid delegate uuaid");
+  if (!isValidLinkPublicKey(offer?.pk)) throw new Error("link offer: invalid pk (need 64 hex)");
+  if (!isValidLinkNonce(offer?.nonce)) throw new Error("link offer: invalid nonce");
+  if (Number.isNaN(Date.parse(offer?.exp))) throw new Error("link offer: invalid exp (need ISO date)");
+  const params = new URLSearchParams({
+    pk: offer.pk.toLowerCase(),
+    nonce: offer.nonce.toLowerCase(),
+    exp: offer.exp,
+  });
+  return `uuaid://${LINK_OFFER_DEEPLINK_HOST}/${encodeURIComponent(offer.delegate)}?${params.toString()}`;
+}
+
+/** True while `now` is strictly before the offer's exp instant. */
+export function isLinkOfferLive(offer, now = Date.now()) {
+  const expMs = Date.parse(offer?.exp);
+  if (Number.isNaN(expMs)) return false;
+  return now < expMs;
+}

package/src/net/refusals.mjs

@@ -0,0 +1,126 @@
+/**
+ * Refusals in agent language: every refusal is a stable `code` plus one
+ * imperative `fix` line, and the CLIs print exactly `<code>: <fix>`.
+ *
+ * The carrier's codes are the `reason` (refused send) or `error` (refused
+ * inbox read) values it has always sent (carrier-server.mjs, envelope.mjs,
+ * delegation.mjs). Those values and their status codes never change here;
+ * the carrier only ADDS a `fix` field, and a client talking to an older
+ * carrier looks the fix up in this same map. The blob broker sends its own
+ * `code` + `fix`, which is printed as received.
+ *
+ * CLOSED AND STATIC. Every fix this package produces is a value of
+ * REFUSAL_FIXES: a fixed string, never built from request data, a remote
+ * reason or an exception message. A parameterised reason
+ * (`delegation-invalid:<why>`, `bad-version <v>`, `alg-not-active:<alg>`)
+ * resolves by its family key, so the parameter never reaches the fix.
+ *
+ * Documented, with statuses, in HOSTING-LIMITS.md "Refusal codes".
+ */
+
+const RESEAL = "re-seal the envelope with seal() from @uuaid/pillar or @uuaid/pillar-client; this one does not verify";
+
+/** code -> one-line fix. Frozen: add, never rename, never interpolate. */
+export const REFUSAL_FIXES = Object.freeze({
+  // Carrier, POST /v1/envelopes
+  "rate-limited": "back off: budgets refill over a sliding 60 s, so retry after 5 s, doubling to 60 s",
+  "body-too-large": "send the payload as a blob (pillar-blob send); maxBodyBytes is your tier's inline limit",
+  "stale-envelope": "seal a new envelope and check your clock; createdAt must be within 24 h of carrier time",
+  "carrier-full": "use your other carriers and do not retry this one soon; its store is full",
+  "bad-recipient": "address the envelope to a full UUAID (uuaid:<namespace>:<type>:<id>)",
+  "bad-json": "POST the envelope as one JSON object",
+  "keyId-sender-mismatch": "sign with transportSignature.keyId equal to the sender UUAID, or send under a delegation",
+  "publicKey-sender-mismatch": "send from the UUAID your signing key derives, or attach the principal's delegation",
+  "bad-signature": "sign again with this identity's own key over the exact bytes; the signature does not verify",
+  "delegation-invalid": "mint a fresh delegation from the principal, then resend",
+  // Carrier, envelope shape and crypto (envelope.mjs open()): one fix for all
+  "not-object": RESEAL,
+  "bad-version": RESEAL,
+  "missing-or-bad-alg": RESEAL,
+  "alg-not-active": RESEAL,
+  "bad-publicKey": RESEAL,
+  "bad-signature-encoding": RESEAL,
+  "missing-enc": RESEAL,
+  "enc-alg-not-supported": RESEAL,
+  "enc-alg-not-active": RESEAL,
+  "bad-epk": RESEAL,
+  "bad-iv": RESEAL,
+  "bad-ct": RESEAL,
+  "bad-canonical": RESEAL,
+  "verify-threw": RESEAL,
+  // Carrier, GET /v1/inbox/<uuaid>
+  "missing-auth-headers": "send x-pillar-pubkey, x-pillar-ts and x-pillar-sig",
+  "bad-pubkey": "send x-pillar-pubkey as the raw Ed25519 key in 64 hex characters",
+  "bad-sig-encoding": "send x-pillar-sig as 128 hex characters",
+  "clock-skew": "fix your clock (NTP) to within 5 min of the carrier; retrying does not help",
+  "uuaid-pubkey-mismatch": "read the inbox of the UUAID your key derives, or send that UUAID's delegation in x-pillar-delegation",
+  "delegation-unparseable": "send x-pillar-delegation as the JSON delegation document",
+  "delegation-too-large": "send a delegation document under 8,192 bytes",
+  "delegation-principal-mismatch": "use a delegation whose principal is the inbox UUAID",
+  "delegation-delegate-key-mismatch": "sign with the key the delegation names as delegate",
+  "delegation-inbox-denied": "ask the principal for a delegation that covers inbox (or *)",
+  "busy": "retry after at least 2 s with jitter, or poll with wait=0 for a while",
+  // Carrier, any route
+  "not-found": "use POST /v1/envelopes or GET /v1/inbox/<uuaid>",
+  "not-a-seed": "do not list this carrier as a seed; it runs without a seed identity",
+  "internal-error": "retry later; if it repeats, tell the carrier operator",
+  // Client side: no server gave a code
+  "carrier-unreachable": "check the carrier URLs and your network, then retry",
+  "carrier-bad-response": "retry, or use another carrier; the carrier or its proxy answered without a reason",
+  "over-tier-limit": "send the payload as a blob (pillar-blob send, or Pillar.sendBlob)",
+  "blob-key-unproven": "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": "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",
+});
+
+/**
+ * The fix for a carrier reason, or null for a reason this map does not know.
+ * An exact key wins; otherwise the reason's family (the part before the
+ * first ":" or space) is looked up, so `delegation-invalid:expired` and
+ * `bad-version 2` resolve to their family's fix. The result is always a
+ * value of REFUSAL_FIXES or null; nothing from `reason` is copied into it.
+ */
+export function carrierFix(reason) {
+  if (typeof reason !== "string" || !reason) return null;
+  if (Object.hasOwn(REFUSAL_FIXES, reason)) return REFUSAL_FIXES[reason];
+  const family = reason.split(/[: ]/, 1)[0];
+  return family !== reason && Object.hasOwn(REFUSAL_FIXES, family) ? REFUSAL_FIXES[family] : null;
+}
+
+/**
+ * A carrier response body with its `fix` added. Pure addition: only a
+ * refusal (status >= 400) that names a `reason` or `error` and has no `fix`
+ * yet gains one; every other field, and every other body, is returned as is.
+ */
+export function withCarrierFix(status, body) {
+  if (!(status >= 400) || !body || typeof body !== "object" || Array.isArray(body) || body.fix !== undefined) return body;
+  const fix = carrierFix(typeof body.reason === "string" ? body.reason : body.error);
+  return fix ? { ...body, fix } : body;
+}
+
+/**
+ * Terminal safety only: a line break or control character a remote sent
+ * becomes a space, so the output stays one line and cannot drive the
+ * terminal. Every other character is printed as received.
+ */
+function oneLine(value) {
+  return String(value).replace(/[\u0000-\u001f\u007f-\u009f]+/g, " ").trim();
+}
+
+/**
+ * `<code>: <fix>` for an error that carries both (a carrier or broker
+ * refusal, or a client error that knows its next step), else null so the
+ * caller keeps its old output. A server's fix is printed as received.
+ */
+export function refusalLine(error) {
+  const code = typeof error?.code === "string" ? oneLine(error.code) : "";
+  const fix = typeof error?.fix === "string" ? oneLine(error.fix) : "";
+  return code && fix ? `${code}: ${fix}` : null;
+}
+
+/** `{ code, fix }` of an error, for a result row, omitting what is absent. */
+export function refusalFields(error) {
+  return {
+    ...(typeof error?.code === "string" && error.code ? { code: error.code } : {}),
+    ...(typeof error?.fix === "string" && error.fix ? { fix: error.fix } : {}),
+  };
+}