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

package/src/blob/http.mjs

@@ -9,16 +9,22 @@ import {
   BlobNotFoundError,
   BlobSenderKeyError,
   BlobUploadError,
+  SELF_CERTIFIED_KEY_ID,
+  isSelfCertifiedUuaid,
+  senderSelfCertified,
 } from "./blob.mjs";
+import { REFUSAL_FIXES } from "../net/refusals.mjs";
 
 export const PILLAR_BLOB_AUDIENCE = "uuaid:pillar-blob:v1";
+export { SELF_CERTIFIED_KEY_ID };
+const KEY_ID_TTL_MS = 300_000;
 
 function payloadHash(payload) {
   return `0x${createHash("sha256").update(jcs(payload)).digest("hex")}`;
 }
 
 function signedRequest(keychain, keyId, challenge, request) {
-  if (!keyId) throw new BlobBrokerError("blob-broker-key-id-required", "a registry-bound presentation key id is required");
+  if (!keyId) throw new BlobBrokerError("blob-broker-key-id-required", "a presentation key id is required (registry badge key or self-certified:ed25519)");
   const payload = { v: 1, audience: PILLAR_BLOB_AUDIENCE, challenge, request };
   return {
     payload,
@@ -33,6 +39,25 @@ function signedRequest(keychain, keyId, challenge, request) {
   };
 }
 
+/** `{ code, fix, body }` from a refusal body; empty for a non-JSON one (e.g. S3 XML). */
+async function refusalOf(response) {
+  const body = await response.json().catch(() => null);
+  if (!body || typeof body !== "object" || Array.isArray(body)) return {};
+  return {
+    code: typeof body.code === "string" && body.code ? body.code : null,
+    fix: typeof body.fix === "string" && body.fix ? body.fix : null,
+    body,
+  };
+}
+
+/** Put the broker's code/fix on a typed error; its own code moves to legacyCode. */
+function withRefusal(error, { code = null, fix = null, body = null } = {}) {
+  if (code && code !== error.code) { error.legacyCode = error.code; error.code = code; }
+  if (fix) error.fix = fix;
+  if (body) error.body = body;
+  return error;
+}
+
 function safeBase(url) {
   const parsed = new URL(url);
   if (parsed.protocol !== "https:" && parsed.hostname !== "127.0.0.1" && parsed.hostname !== "localhost") {
@@ -41,17 +66,35 @@ function safeBase(url) {
   return parsed.href.replace(/\/+$/, "");
 }
 
-/** HTTP client for the UUAID broker. URLs are returned only to the live caller. */
+/**
+ * HTTP client for the UUAID broker. URLs are returned only to the live caller.
+ *
+ * `keyId` is optional. Given, it is presented as is. Omitted, the client
+ * resolves one per identity (resolveKeyId): the registry badge's key when a
+ * badge names this exact key, else "self-certified:ed25519" when the UUAID is
+ * exactly the key's uuaid:foundation:agent UUAID, else a `blob-key-unproven`
+ * refusal.
+ */
+/**
+ * The brokers this package talks to without being told, same list and order as
+ * @uuaid/pillar-client (hosts.ts BLOB_BROKERS). pillar-sfo runs broker 1.1.0,
+ * which also serves self-certified identities; api.uuaid.org serves registry
+ * badges only, so it is no longer the default (pass --broker to use it).
+ */
+export const BLOB_BROKERS = Object.freeze(["https://pillar-sfo.uuaid.org/blob", "https://pillar-nyc.uuaid.org/blob"]);
+export const DEFAULT_BLOB_BROKER = BLOB_BROKERS[0];
+
 export class PillarBlobHttpClient {
-  constructor({ baseUrl = "https://api.uuaid.org", keychain, keyId, fetchImpl = globalThis.fetch, timeoutMs = 15_000 } = {}) {
+  constructor({ baseUrl = DEFAULT_BLOB_BROKER, keychain, keyId = null, fetchImpl = globalThis.fetch, timeoutMs = 15_000 } = {}) {
     if (!keychain?._identity) throw new BlobBrokerError("blob-broker-no-identity", "loaded keychain required");
     if (typeof fetchImpl !== "function") throw new BlobBrokerError("blob-broker-no-fetch", "fetch implementation required");
     this.baseUrl = safeBase(baseUrl);
     this.keychain = keychain;
-    this.keyId = keyId;
+    this.keyId = keyId || null;
     this.fetch = fetchImpl;
     this.timeoutMs = timeoutMs;
     this._trust = null;
+    this._resolvedKeyId = null;
   }
 
   async _json(path, { method = "POST", body } = {}) {
@@ -68,15 +111,62 @@ export class PillarBlobHttpClient {
     }
     const parsed = await response.json().catch(() => ({}));
     if (!response.ok) {
-      const code = response.status === 404 ? "blob-broker-not-found"
+      const legacyCode = response.status === 404 ? "blob-broker-not-found"
         : response.status === 410 ? "blob-broker-expired"
           : response.status === 409 ? "blob-broker-replay"
             : "blob-broker-rejected";
-      throw new BlobBrokerError(code, parsed.error ?? `blob broker returned ${response.status}`, response.status);
+      // The broker's own code + fix win; an older broker sends neither.
+      const brokerCode = typeof parsed?.code === "string" && parsed.code ? parsed.code : null;
+      const fix = typeof parsed?.fix === "string" && parsed.fix ? parsed.fix : null;
+      throw new BlobBrokerError(brokerCode ?? legacyCode, parsed?.error ?? `blob broker returned ${response.status}`, response.status, {
+        fix,
+        legacyCode,
+        body: parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null,
+      });
     }
     return parsed;
   }
 
+  /**
+   * The keyId this identity presents, strongest proof first:
+   *   1. the constructor's explicit `keyId`;
+   *   2. the registry badge's presentation keyId, when a fresh registry-signed
+   *      badge for this UUAID names this exact public key (badge limits);
+   *   3. "self-certified:ed25519", when this UUAID is exactly
+   *      `uuaid:foundation:agent:` + the key's local id (self-certified
+   *      limits; the full string, as the broker compares it);
+   * else throws `blob-key-unproven`. A badge that names another key, a
+   * missing badge and an unreachable registry all fall through to 3.
+   * Cached for 5 minutes.
+   */
+  async resolveKeyId() {
+    if (this.keyId) return this.keyId;
+    if (this._resolvedKeyId && this._resolvedKeyId.until > Date.now()) return this._resolvedKeyId.value;
+    const { uuaid, publicKeyHex } = this.keychain._identity;
+    let value = null;
+    let badgeProblem = "no registry badge names this key";
+    try {
+      const presentation = await this._verifiedPresentationKey(uuaid);
+      if (presentation && presentation.publicKey.toLowerCase() === publicKeyHex.toLowerCase()
+        && typeof presentation.keyId === "string" && presentation.keyId) {
+        value = presentation.keyId;
+      }
+    } catch (error) {
+      badgeProblem = `registry badge lookup failed (${error.code ?? error.message})`;
+    }
+    if (!value && isSelfCertifiedUuaid(uuaid, publicKeyHex)) value = SELF_CERTIFIED_KEY_ID;
+    if (!value) {
+      throw new BlobBrokerError(
+        "blob-key-unproven",
+        `${uuaid} cannot sign broker requests: ${badgeProblem}, and it is not the uuaid:foundation:agent UUAID derived from its key`,
+        null,
+        { fix: REFUSAL_FIXES["blob-key-unproven"] },
+      );
+    }
+    this._resolvedKeyId = { value, until: Date.now() + KEY_ID_TTL_MS };
+    return value;
+  }
+
   challenge(action, objectId = null) {
     return this._json("/pillar/blobs/challenge", {
       body: {
@@ -87,9 +177,10 @@ export class PillarBlobHttpClient {
     }).then((body) => body.challenge);
   }
 
-  reserve(challenge, { recipient, ciphertextSha256, ciphertextBytes, expiresAt }) {
+  async reserve(challenge, { recipient, ciphertextSha256, ciphertextBytes, expiresAt }) {
+    const keyId = await this.resolveKeyId();
     return this._json("/pillar/blobs/reserve", {
-      body: signedRequest(this.keychain, this.keyId, challenge, {
+      body: signedRequest(this.keychain, keyId, challenge, {
         action: "reserve",
         agent_uuaid: this.keychain._identity.uuaid,
         recipient_uuaid: recipient,
@@ -100,36 +191,44 @@ export class PillarBlobHttpClient {
     });
   }
 
-  finalize(objectId) {
-    return this.challenge("finalize", objectId).then((challenge) => this._json("/pillar/blobs/finalize", {
-      body: signedRequest(this.keychain, this.keyId, challenge, {
+  async finalize(objectId) {
+    const keyId = await this.resolveKeyId();
+    const challenge = await this.challenge("finalize", objectId);
+    return this._json("/pillar/blobs/finalize", {
+      body: signedRequest(this.keychain, keyId, challenge, {
         action: "finalize",
         agent_uuaid: this.keychain._identity.uuaid,
       }),
-    }));
+    });
   }
 
-  redeem(objectId) {
-    return this.challenge("redeem", objectId).then((challenge) => this._json("/pillar/blobs/redeem", {
-      body: signedRequest(this.keychain, this.keyId, challenge, {
+  async redeem(objectId) {
+    const keyId = await this.resolveKeyId();
+    const challenge = await this.challenge("redeem", objectId);
+    return this._json("/pillar/blobs/redeem", {
+      body: signedRequest(this.keychain, keyId, challenge, {
         action: "redeem",
         agent_uuaid: this.keychain._identity.uuaid,
       }),
-    }));
+    });
   }
 
   async upload(ticket, ciphertext) {
+    let response;
     try {
-      const response = await this.fetch(ticket.url, {
+      response = await this.fetch(ticket.url, {
         method: "PUT",
         headers: ticket.headers,
         body: ciphertext,
         signal: AbortSignal.timeout(this.timeoutMs),
       });
-      if (!response.ok) throw new Error(`upload returned ${response.status}`);
     } catch (error) {
       throw new BlobUploadError(`temporary blob upload failed: ${error.message}`, error);
     }
+    if (!response.ok) {
+      const cause = new Error(`upload returned ${response.status}`);
+      throw withRefusal(new BlobUploadError(`temporary blob upload failed: ${cause.message}`, cause), await refusalOf(response));
+    }
   }
 
   async download(ticket) {
@@ -139,9 +238,12 @@ export class PillarBlobHttpClient {
     } catch (error) {
       throw new BlobFetchError(`temporary blob download failed: ${error.message}`, error);
     }
-    if (response.status === 404) throw new BlobNotFoundError("temporary-object");
-    if (response.status === 403) throw new BlobExpiryError("temporary blob download capability expired");
-    if (!response.ok) throw new BlobFetchError(`temporary blob download returned ${response.status}`);
+    if (!response.ok) {
+      const error = response.status === 404 ? new BlobNotFoundError("temporary-object")
+        : response.status === 403 ? new BlobExpiryError("temporary blob download capability expired")
+          : new BlobFetchError(`temporary blob download returned ${response.status}`);
+      throw withRefusal(error, await refusalOf(response));
+    }
     return Buffer.from(await response.arrayBuffer());
   }
 
@@ -155,16 +257,28 @@ export class PillarBlobHttpClient {
     return value;
   }
 
-  /** Fail closed unless a fresh registry-signed badge names this exact active key. */
-  async assertRegistryActiveSender(sender, expectedPublicKey) {
+  /**
+   * The presentation key ({ alg, keyId, publicKey }) of a fresh badge for
+   * `uuaid` whose payload hash matches and whose ed25519 signature pins to a
+   * live key of the registry trust root; null when there is no badge (404)
+   * or it fails any of those checks. Other broker errors propagate.
+   */
+  async _verifiedPresentationKey(uuaid) {
+    let badge;
+    try {
+      badge = await this._json(`/iaaso/v1/badge/${encodeURIComponent(uuaid)}`, { method: "GET" });
+    } catch (error) {
+      if (error?.status === 404) return null;
+      throw error;
+    }
     const trust = await this._registryTrust();
-    const badge = await this._json(`/iaaso/v1/badge/${encodeURIComponent(sender)}`, { method: "GET" });
     const presentation = badge?.payload?.subject?.presentationKey;
-    const keyMatches = badge?.payload?.subject?.uuaid === sender
+    const subjectMatches = badge?.payload?.subject?.uuaid === uuaid
       && presentation?.alg === "ed25519"
-      && presentation?.publicKey?.toLowerCase() === expectedPublicKey?.toLowerCase();
+      && typeof presentation?.publicKey === "string";
     const fresh = Number.isFinite(Date.parse(badge?.payload?.freshUntil)) && Date.parse(badge.payload.freshUntil) > Date.now();
-    const hashMatches = badge?.payloadHash === payloadHash(badge?.payload);
+    let hashMatches = false;
+    try { hashMatches = badge?.payloadHash === payloadHash(badge?.payload); } catch (_error) { hashMatches = false; }
     const registrySignature = Array.isArray(badge?.signatures)
       ? badge.signatures.find((signature) => {
         if (signature.alg !== "ed25519") return false;
@@ -175,12 +289,36 @@ export class PillarBlobHttpClient {
         } catch (_error) { return false; }
       })
       : null;
-    if (!keyMatches || !fresh || !hashMatches || !registrySignature) {
+    return subjectMatches && fresh && hashMatches && registrySignature ? presentation : null;
+  }
+
+  /**
+   * Fail closed unless a fresh registry-signed badge names this exact active
+   * key. The receive flows call this only for a sender whose UUAID does not
+   * derive from its signing key; see assertSenderKey.
+   */
+  async assertRegistryActiveSender(sender, expectedPublicKey) {
+    const presentation = await this._verifiedPresentationKey(sender);
+    const keyMatches = typeof expectedPublicKey === "string"
+      && presentation?.publicKey.toLowerCase() === expectedPublicKey.toLowerCase();
+    if (!keyMatches) {
       throw new BlobSenderKeyError("sender presentation key is not registry-active", sender, "inactive");
     }
     return "active";
   }
 
+  /**
+   * Recipient sender gate for a received blob-ref. "self-certified" when the
+   * ref's signature verifies and its sender is exactly that signing key's
+   * uuaid:foundation:agent UUAID (proven key holder, unverified identity);
+   * otherwise "active" when a registry badge names that key; otherwise
+   * throws BlobSenderKeyError (code sender-key-not-active, with a fix).
+   */
+  async assertSenderKey(ref) {
+    if (senderSelfCertified(ref)) return "self-certified";
+    return this.assertRegistryActiveSender(ref?.sender, ref?.sig?.publicKey);
+  }
+
   crossCheckRedemption(ref, brokerRecord) {
     if (
       brokerRecord?.object_id !== ref.object ||

package/src/identity/tier.mjs

@@ -30,8 +30,25 @@ import { createHash } from "node:crypto";
 import { jcs } from "./jcs.mjs";
 import { Keychain } from "./keychain.mjs";
 
-/** Tier ladder. community = the unauthenticated default (F2 hardening values). */
-export const TIER_DEFAULTS = {
+/** Tier ladder. community = the unauthenticated default (F2 hardening values).
+ *
+ *  Greek-order names (Doric, Ionic, Corinthian) are ALIASES for the lower
+ *  three rungs of the canonical ladder. They were added 2026-09-19 so that
+ *  grants may carry a feature-tier name — Doric = pillar core only,
+ *  Ionic = + plinth mix hops, Corinthian = + full optional stack — while
+ *  the carrier still enforces a single budget table. A grant with
+ *  `tier: "Doric"` and a grant with `tier: "community"` resolve to the same
+ *  rate/size budget; carriers verify by `TIER_DEFAULTS[grant.tier]` and
+ *  never see the difference.
+ *
+ *  Aliasing is additive — the canonical five names still work, no carrier
+ *  upgrade required. Enterprise and foundation keep their original names
+ *  (no alias needed; they are not feature-presence markers).
+ *
+ *  Adding a new alias is a one-line change here: spread the budget object
+ *  under the new key. No other file needs to know.
+ */
+const _CANONICAL_TIERS = {
   community:  { envelopesPerMin: 120,  maxBodyBytes: 512 * 1024 },
   supporter:  { envelopesPerMin: 300,  maxBodyBytes: 1024 * 1024 },
   org:        { envelopesPerMin: 600,  maxBodyBytes: 2 * 1024 * 1024 },
@@ -39,6 +56,13 @@ export const TIER_DEFAULTS = {
   foundation: { envelopesPerMin: 3000, maxBodyBytes: 2 * 1024 * 1024 },
 };
 
+export const TIER_DEFAULTS = {
+  ..._CANONICAL_TIERS,
+  Doric:      _CANONICAL_TIERS.community,    // alias of community
+  Ionic:      _CANONICAL_TIERS.supporter,    // alias of supporter
+  Corinthian: _CANONICAL_TIERS.org,          // alias of org
+};
+
 /** Hard ceiling any grant can reach — also the carrier's raw-body stream cap. */
 export const ABSOLUTE_MAX_BODY = 2 * 1024 * 1024;
 export const ABSOLUTE_MAX_RATE = 6000;

package/src/index.mjs

@@ -36,6 +36,9 @@ export {
   signBlobRef, verifyBlobRefSig, blobRefMetadata, blobRefSecret, refSerializedBytes,
   makeBlobRef, validateBlobRef, envelopeBodyBytes, preflightBodyBytes, chooseTransport,
   prepareBlobSend, fetchAndDecryptBlob, prepareBrokerBlobSend, fetchBrokerBlob,
+  SELF_CERTIFIED_KEY_ID, isSelfCertifiedUuaid, selfCertifiedUuaidFor, senderSelfCertified,
 } from "./blob/blob.mjs";
 export { MemoryBlobStore, FsBlobStore } from "./blob/store.mjs";
 export { PillarBlobHttpClient, PILLAR_BLOB_AUDIENCE } from "./blob/http.mjs";
+// Refusals in agent language: carrier reason -> one-line fix, `<code>: <fix>`.
+export { REFUSAL_FIXES, carrierFix, withCarrierFix, refusalLine, refusalFields } from "./net/refusals.mjs";

package/src/net/carrier-client.mjs

@@ -7,6 +7,7 @@
  */
 import { envelopeBodyBytes, preflightBodyBytes } from "../blob/blob.mjs";
 import { seedTier } from "./seed-tier.mjs";
+import { carrierFix, REFUSAL_FIXES } from "./refusals.mjs";
 
 /**
  * Rank carriers by how proven they are, best first. Unknown carriers rank as
@@ -66,7 +67,11 @@ export class CarrierClient {
    * accepted; throws if every carrier rejects.  Returns the receipt from the
    * most PROVEN accepting carrier as the primary ({ carrier, seq, sha,
    * duplicate }) plus `all` with every carrier's outcome ({ carrier, ok,
-   * seq?, sha?, duplicate?, error? }).
+   * seq?, sha?, duplicate?, error?, status?, reason?, fix? }).
+   *
+   * When every carrier refuses, the thrown error carries `code` (the most
+   * proven carrier's `reason`, else carrier-unreachable / carrier-bad-response),
+   * `fix`, `status`, `carrier` and `refusals` (= `all`).
    *
    * Which receipt is primary matters because callers quote its seq back as a
    * cursor and cite its carrier in receipts: it should name a seed that will
@@ -82,6 +87,7 @@ export class CarrierClient {
       const e = new Error(`carrier preflight: body ${pf.bytes}B exceeds ${pf.source} limit ${pf.limit}B — use the blob transport`);
       e.code = pf.source === "direct-cap" ? "blob-too-large" : "over-tier-limit";
       e.limit = pf.limit; e.source = pf.source;
+      e.fix = REFUSAL_FIXES["over-tier-limit"];
       throw e;
     }
     const attempt = async (base) => {
@@ -101,7 +107,13 @@ export class CarrierClient {
         if (res.status === 202 && body.accepted) {
           return { carrier: base, ok: true, seq: body.seq, sha: body.sha, duplicate: !!body.duplicate };
         }
-        return { carrier: base, ok: false, error: `${res.status} ${body.reason ?? body.error ?? (raw ? "non-json-response" : "empty-response")}` };
+        const reason = typeof body.reason === "string" && body.reason ? body.reason
+          : typeof body.error === "string" && body.error ? body.error : null;
+        return {
+          carrier: base, ok: false, status: res.status,
+          error: `${res.status} ${body.reason ?? body.error ?? (raw ? "non-json-response" : "empty-response")}`,
+          ...(reason ? { reason, fix: (typeof body.fix === "string" && body.fix) || carrierFix(reason) } : {}),
+        };
       } catch (e) {
         return { carrier: base, ok: false, error: e.message };
       }
@@ -110,7 +122,14 @@ export class CarrierClient {
       rs.map(r => r.status === "fulfilled" ? r.value : { carrier: "?", ok: false, error: String(r.reason) }));
     const accepted = all.filter(r => r.ok);
     if (!accepted.length) {
-      throw new Error(`carrier deliver failed on all carriers: ${all.map(r => `${r.carrier}: ${r.error}`).join("; ")}`);
+      const e = new Error(`carrier deliver failed on all carriers: ${all.map(r => `${r.carrier}: ${r.error}`).join("; ")}`);
+      // `all` is in rank order, so this is the most proven carrier's answer.
+      const primary = all.find(r => r.reason) ?? all.find(r => r.status) ?? null;
+      e.code = primary?.reason ?? (primary ? "carrier-bad-response" : "carrier-unreachable");
+      e.fix = primary?.fix ?? carrierFix(e.code);
+      if (primary) { e.status = primary.status; e.carrier = primary.carrier; }
+      e.refusals = all;
+      throw e;
     }
     const ranked = accepted.slice().sort((a, b) => byTier(this.carrierTiers)(a.carrier, b.carrier));
     const { carrier, seq, sha, duplicate } = ranked[0];
@@ -135,7 +154,11 @@ export class CarrierClient {
     });
     if (res.status !== 200) {
       const body = await res.json().catch(() => ({}));
-      throw new Error(`inbox fetch ${base}: ${res.status} ${body.error ?? ""}`);
+      const e = new Error(`inbox fetch ${base}: ${res.status} ${body.error ?? ""}`);
+      e.code = typeof body.error === "string" && body.error ? body.error : "carrier-bad-response";
+      e.fix = (typeof body.fix === "string" && body.fix) || carrierFix(e.code);
+      e.status = res.status; e.carrier = base;
+      throw e;
     }
     return res.json(); // { envelopes: [{seq, envelope}], now }
   }

package/src/net/carrier-server.mjs

@@ -58,6 +58,7 @@ import { Keychain } from "../identity/keychain.mjs";
 import { jcs } from "../identity/jcs.mjs";
 import { verifyTierGrant } from "../identity/tier.mjs";
 import { verifyDelegationDoc, delegationCoversKind } from "./delegation.mjs";
+import { withCarrierFix } from "./refusals.mjs"; // additive `fix` on refusals; reason/error/status unchanged
 
 const MAX_WAIT_S = 30;
 const MAX_BODY = 512 * 1024; // 512 KiB per envelope (community tier)
@@ -245,7 +246,7 @@ export class CarrierServer {
     // No-op on a dead socket: close() destroys connections, and a long-poll
     // handler whose timer fires afterwards must not throw on write.
     if (res.destroyed || res.writableEnded) return;
-    const body = JSON.stringify(obj);
+    const body = JSON.stringify(withCarrierFix(code, obj));
     res.writeHead(code, { "content-type": "application/json", "content-length": Buffer.byteLength(body) });
     res.end(body);
   }

package/src/net/delegation.mjs

@@ -45,11 +45,68 @@
  * 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.

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;
+}