@uuaid/agent-commons 0.0.0-stage → 0.2.0-alpha.2

package/src/vendor/pillar/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/vendor/pillar/net/envelope.mjs

@@ -0,0 +1,258 @@
+/**
+ * Envelope v2 — the wire format for pillar-to-pillar messages.
+ *
+ * ENCRYPTION IS FUNDAMENTAL.  There is no plaintext payload mode.  Every
+ * envelope's payload is sealed to the recipient's key before the envelope
+ * is signed.  Anyone can VERIFY an envelope (transport signature is public);
+ * only the recipient can READ it.
+ *
+ * Envelope v2 = {
+ *   version:   "uuaid-pillar-envelope/2",
+ *   id:        "env-...",
+ *   sender:    "uuaid:...",
+ *   recipient: "uuaid:...",
+ *   kind:      "message" | "work-order" | ...   (routing hint, NOT secret)
+ *   createdAt: ISO 8601,
+ *   enc: { alg: "x25519-hkdf-sha256-aes256gcm", epk, iv, ct },   // sealed payload
+ *   transportSignature: { alg: "ed25519", keyId, publicKey, signature, created },
+ * }
+ *
+ * The transport signature covers everything (including the ciphertext), so
+ * tamper detection works WITHOUT decrypting — carriers verify-then-store.
+ * The GCM AAD binds the ciphertext to the envelope id, so a valid ciphertext
+ * cannot be transplanted into a different envelope even by the sender.
+ *
+ * seal() enforces identity binding: recipient UUAID local-id must equal
+ * sha256(recipientPublicKey) — you cannot encrypt to a key that doesn't own
+ * the UUAID you're addressing.
+ */
+import { createHash, randomBytes } from "node:crypto";
+import { jcs } from "../identity/jcs.mjs";
+import { Keychain, isStrictEd25519PublicKey } 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 };
+
+/**
+ * Build, encrypt, and sign an envelope.
+ *
+ * keychain: a loaded Keychain (has .sign()).
+ * body: {
+ *   recipient:           "uuaid:..."          REQUIRED
+ *   recipientPublicKey:  ed25519 pubkey hex   REQUIRED (E2E is not optional)
+ *   kind, payload, id, createdAt              optional
+ * }
+ */
+export function seal(keychain, body) {
+  const identity = keychain._identity;
+  if (!identity) throw new Error("keychain not loaded");
+  const sender = body.sender ?? identity.uuaid;
+  if (sender !== identity.uuaid) {
+    throw new Error(`envelope.sender ${sender} does not match keychain identity ${identity.uuaid}`);
+  }
+  if (!body.recipient || typeof body.recipient !== "string") {
+    throw new Error("seal: recipient required");
+  }
+  if (!body.recipientPublicKey || !/^[0-9a-f]{64}$/i.test(body.recipientPublicKey)) {
+    throw new Error("seal: recipientPublicKey (ed25519 hex) is REQUIRED — encryption is not optional");
+  }
+  // Identity binding: the key must own the UUAID.
+  const expectedLocalId = Keychain._localIdFromKey(Buffer.from(body.recipientPublicKey, "hex"));
+  const recipientLocalId = body.recipient.split(":")[3];
+  if (recipientLocalId !== expectedLocalId) {
+    throw new Error(`seal: recipientPublicKey does not derive recipient UUAID (key owns ...${expectedLocalId.slice(0, 13)}, envelope addressed to ...${String(recipientLocalId).slice(0, 13)})`);
+  }
+
+  const id = body.id ?? mkEnvelopeId();
+  const enc = sealPayload(body.recipientPublicKey, body.payload ?? {}, { aad: id });
+
+  const envelope = {
+    version: ENVELOPE_VERSION,
+    id,
+    sender,
+    recipient: body.recipient,
+    kind: body.kind ?? "message",
+    enc,
+    createdAt: body.createdAt ?? new Date().toISOString(),
+  };
+  const canonical = jcs(envelope);
+  const sigBytes = keychain.sign(Buffer.from(canonical, "utf-8"));
+  envelope.transportSignature = {
+    alg: "ed25519",
+    keyId: identity.uuaid,
+    publicKey: identity.publicKeyHex,
+    signature: sigBytes.toString("hex"),
+    created: envelope.createdAt,
+  };
+  return envelope;
+}
+
+/**
+ * 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" };
+  if (envelope.version !== ENVELOPE_VERSION) return { ok: false, reason: `bad-version ${envelope.version}` };
+  const sig = envelope.transportSignature;
+  if (!sig || typeof sig !== "object" || sig.alg !== "ed25519") return { ok: false, reason: "missing-or-bad-alg" };
+  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 (!isStrictEd25519PublicKey(sig.publicKey)) return { ok: false, reason: "weak-publicKey" }; // @rule envelope.open-strict-key
+  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 — an envelope without one is invalid.
+  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" };
+  // Verify the signature over the envelope WITHOUT the signature block.
+  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 { ok: false, reason: "bad-signature" };
+  // Sender binding (self-authenticating identity): the sender UUAID's
+  // local-id MUST derive from the signing key — the sender-side mirror of
+  // seal()'s recipient binding.  Without this, anyone can sign an envelope
+  // with their own key while claiming another agent's sender UUAID.
+  const expectedSenderLocalId = Keychain._localIdFromKey(Buffer.from(sig.publicKey, "hex"));
+  if (expectedSenderLocalId !== String(envelope.sender).split(":")[3]) {
+    return { ok: false, reason: "publicKey-sender-mismatch" };
+  }
+  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 (!isStrictEd25519PublicKey(sig.publicKey)) return { ok: false, reason: "weak-publicKey" }; // @rule envelope.open-delegated-strict-key
+  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.
+ * Throws on wrong recipient, wrong key, tamper, or AAD mismatch.
+ */
+export function decrypt(keychain, envelope) {
+  const identity = keychain._identity;
+  if (!identity) throw new Error("decrypt: keychain not loaded");
+  if (envelope.recipient !== identity.uuaid) {
+    throw new Error(`decrypt: envelope addressed to ${envelope.recipient}, not us (${identity.uuaid})`);
+  }
+  const seed = keychainSeed(keychain);
+  return openPayload(seed, envelope.enc, { aad: envelope.id });
+}
+
+/** Extract the 32-byte Ed25519 seed from a loaded keychain. */
+export function keychainSeed(keychain) {
+  const der = keychain._identity.privateKey.export({ type: "pkcs8", format: "der" });
+  return Buffer.from(der.subarray(der.length - 32));
+}
+
+/**
+ * Envelope id: 16 random bytes hex + a small timestamp prefix for
+ * human-readable sort.  Not sensitive; not secret.  Used as GCM AAD.
+ */
+export function mkEnvelopeId() {
+  const now = Date.now().toString(36);
+  const rnd = randomBytes(8).toString("hex");
+  return `env-${now}-${rnd}`;
+}
+
+/**
+ * Content-hash of an envelope, computable by anyone.
+ */
+export function envelopeSha(envelope) {
+  return createHash("sha256").update(jcs(envelope)).digest("hex");
+}

package/src/vendor/pillar/net/refusals.mjs

@@ -0,0 +1,127 @@
+/**
+ * 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",
+  "weak-publicKey": "use a real Ed25519 identity key; this key is a small-order or non-canonical point that can sign anything, so no signature under it counts",
+  "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 } : {}),
+  };
+}