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

package/bin/pillar.mjs

@@ -16,6 +16,7 @@
  * All commands respect --home to point at an alternate pillar directory,
  * useful for running multiple pillars on one machine (Zestro dogfood etc.).
  */
+import "../src/node-check.mjs"; // must stay the first import: refuses Node < 22 before any dependency loads
 import { mkdirSync, existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { homedir } from "node:os";
@@ -24,6 +25,9 @@ import { Keychain } from "../src/identity/keychain.mjs";
 import { Pillar } from "../src/pillar.mjs";
 import { loadFleetAddressBook } from "../src/address-book.mjs";
 import { loadTrustPolicy, POLICIES } from "../src/identity/trust.mjs";
+import { parseLinkOffer, isLinkOfferLive, LINK_GRANT_KINDS } from "../src/net/link-offer.mjs";
+import { mintDelegationDoc } from "../src/net/delegation.mjs";
+import { refusalLine } from "../src/net/refusals.mjs";
 
 function parseArgs(argv) {
   const args = { _: [] };
@@ -265,6 +269,121 @@ async function cmdSend(args) {
   }
 }
 
+
+// ── delegate ──────────────────────────────────────────────────────────────────
+// The desktop-link ceiling enforced by chat-web (browser-chat-session.ts,
+// LINK_TTL_MS). A grant with a longer window verifies fine and is then DROPPED
+// by the browser without a word, so this side refuses it loudly instead.
+const LINK_TTL_DAYS_MAX = 7;
+
+/**
+ * pillar delegate --to-browser '<uuaid://link/...>'
+ *
+ * Pair a browser tab to THIS pillar identity. The tab publishes an offer
+ * carrying its own freshly minted device key; this mints a delegation naming
+ * that key as delegate and this identity as principal, and sends it as a
+ * `_link` grant to the tab's inbox.
+ *
+ * The persona seed never leaves this machine — only a signed, time-boxed
+ * document does. Identical in every respect to what a phone sends: the
+ * handshake authenticates the PRINCIPAL (the envelope sender must equal the
+ * delegation principal), and never the kind of device the principal runs on.
+ * That is what lets a headless agent hold a desktop.
+ */
+async function cmdDelegate(args) {
+  const offerRaw = typeof args["to-browser"] === "string" ? args["to-browser"] : args._[1];
+  if (!offerRaw || args["to-browser"] === true) {
+    console.error("usage: pillar delegate --to-browser '<uuaid://link/...>' [--ttl-days N] [--name NAME]");
+    console.error("  Paste the offer string the browser shows under its QR code.");
+    exit(2);
+  }
+
+  const offer = parseLinkOffer(offerRaw);
+  if (!offer) {
+    console.error("not a valid link offer. Expected: uuaid://link/<delegate-uuaid>?pk=<64hex>&nonce=<hex>&exp=<iso>");
+    exit(2);
+  }
+  if (!isLinkOfferLive(offer)) {
+    console.error(`offer expired at ${offer.exp} — reload the browser tab for a fresh one`);
+    exit(1);
+  }
+
+  const ttlDays = args["ttl-days"] !== undefined ? Number(args["ttl-days"]) : LINK_TTL_DAYS_MAX;
+  if (!Number.isFinite(ttlDays) || ttlDays <= 0) {
+    console.error("--ttl-days must be a positive number");
+    exit(2);
+  }
+  // Refuse rather than mint a grant the far side discards in silence.
+  if (ttlDays > LINK_TTL_DAYS_MAX) {
+    console.error(`--ttl-days ${ttlDays} exceeds the ${LINK_TTL_DAYS_MAX}-day desktop-link ceiling.`);
+    console.error("A longer grant is a VALID document that the browser drops without reporting why.");
+    exit(2);
+  }
+
+  const p = loadPillar(args);
+  await p.start();
+  try {
+    const me = p.keychain._identity;
+    const delegation = mintDelegationDoc(p.keychain, {
+      delegate: offer.delegate,
+      delegatePublicKey: offer.pk,
+      kinds: [...LINK_GRANT_KINDS], // never "*": that would let the desktop read this identity's inbox
+      ttlDays,
+    });
+
+    // The snapshot's persona MUST equal the delegation principal exactly — the
+    // browser rejects the whole grant on any mismatch, treating a disagreeing
+    // snapshot as evidence that neither half can be trusted.
+    // fleet.json is { fleet: { "<role>": { uuaid, publicKey, ... } } } — keyed by
+    // ROLE, which is also the human-readable name the desktop shows. A row
+    // without a publicKey cannot be sealed to, so it is not a contact.
+    const contacts = [];
+    const fp = fleetPath(args);
+    if (existsSync(fp)) {
+      let fleet = {};
+      try {
+        fleet = JSON.parse(readFileSync(fp, "utf-8")).fleet ?? {};
+      } catch {
+        console.error(`warning: ${fp} is not readable JSON — sending 0 contacts`);
+      }
+      for (const [role, entry] of Object.entries(fleet)) {
+        if (typeof entry?.uuaid !== "string" || typeof entry?.publicKey !== "string") continue;
+        contacts.push({ uuaid: entry.uuaid, publicKey: entry.publicKey, name: String(role) });
+      }
+    }
+
+    const payload = {
+      _link: { v: 1, op: "grant", nonce: offer.nonce },
+      delegation,
+      snapshot: {
+        persona: { uuaid: me.uuaid, publicKey: me.publicKeyHex },
+        displayName: typeof args.name === "string" ? args.name : null,
+        contacts,
+      },
+    };
+
+    const { envelope } = await p.send({
+      recipient: offer.delegate,
+      kind: "message",
+      payload,
+      recipientPublicKey: offer.pk,
+      resolveTimeoutMs: 5000,
+    });
+
+    console.log(`linked ${offer.delegate}`);
+    console.log(`  principal: ${me.uuaid}`);
+    console.log(`  window:    ${delegation.notBefore} -> ${delegation.notAfter} (${ttlDays}d)`);
+    console.log(`  contacts:  ${contacts.length}`);
+    console.log(`  envelope:  ${envelope.id}`);
+    console.log("");
+    console.log("The tab pairs when it polls. If it does not, the grant was refused in");
+    console.log("silence — check the offer is unexpired and unclaimed, and that the tab");
+    console.log("still shows the same QR (a reload rotates the nonce and voids this grant).");
+  } finally {
+    await p.stop();
+  }
+}
+
 async function cmdSendGroup(args) {
   const [groupName, kind, jsonStr] = args._.slice(1);
   if (!groupName || !kind) {
@@ -286,7 +405,7 @@ async function cmdSendGroup(args) {
     let failed = 0;
     for (const r of results) {
       if (r.ok) console.log(`  ✓ ${r.member}  via ${r.via}  ${r.envelopeId}`);
-      else { failed++; console.error(`  ✗ ${r.member}  ${r.error}`); }
+      else { failed++; console.error(`  ✗ ${r.member}  ${refusalLine(r) ?? r.error}`); }
     }
     console.log(`group "${groupName}": ${results.length - failed}/${results.length} delivered`);
     if (failed) exit(1);
@@ -636,10 +755,13 @@ async function main() {
     case "trust": return cmdTrust(args);
     case "tier":  return cmdTier(args);
     case "peers": return cmdPeers(args);
+    case "delegate": return cmdDelegate(args);
     default:
-      console.error(`usage: pillar <init|id|send|send-group|groups|recv|inbox|trust|tier|peers> [--home DIR]`);
+      console.error(`usage: pillar <init|id|send|send-group|groups|recv|inbox|trust|tier|peers|delegate> [--home DIR]`);
       exit(2);
   }
 }
 
-main().catch(e => { console.error(e); exit(1); });
+// A carrier or broker refusal prints one line, `<code>: <fix>` (src/net/refusals.mjs);
+// anything else keeps the full error.
+main().catch(e => { console.error(refusalLine(e) ?? e); exit(1); });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uuaid/pillar",
-  "version": "0.2.0-alpha.16",
+  "version": "0.2.0-alpha.18",
   "description": "Pillar (Protocol for Inter-agent Linked Ledger And Relay) \u2014 the secure delivery layer of UACP, the Universal Agent Communication Protocol. UACP = UUAID (identity) + Envelope (signed, encrypted container) + Pillar (relay, mailbox, routing, store-and-forward). Reference implementation of the UACP delivery layer; includes VDA-1 (IAASO-3901, in ballot) delivery attestation and a blind escrow for the Zilligon ZGN / EVM rails.",
   "license": "Apache-2.0",
   "type": "module",
@@ -30,6 +30,7 @@
     "./blob/http": "./src/blob/http.mjs",
     "./blob/store": "./src/blob/store.mjs",
     "./blob/broker": "./src/blob/broker.mjs",
+    "./refusals": "./src/net/refusals.mjs",
     "./package.json": "./package.json"
   },
   "files": [
@@ -37,16 +38,20 @@
     "bin",
     "README.md",
     "INTERACTION-CONVENTION.md",
+    "HOSTING-LIMITS.md",
     "LICENSE"
   ],
   "scripts": {
     "test": "node --test --test-reporter spec test/unit/*.test.mjs",
     "test:int": "node --test --test-reporter spec test/integration/*.test.mjs",
     "test:chaos": "node --test --test-reporter spec test/chaos/*.test.mjs",
-    "test:all": "node --test --test-reporter spec test/unit/*.test.mjs test/integration/*.test.mjs test/chaos/*.test.mjs"
+    "test:all": "node --test --test-reporter spec test/unit/*.test.mjs test/integration/*.test.mjs test/chaos/*.test.mjs",
+    "preflight": "node scripts/preflight-publish.mjs",
+    "prepublishOnly": "node scripts/preflight-publish.mjs",
+    "postpublish": "node scripts/verify-publish.mjs"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "dependencies": {
     "@chainsafe/libp2p-noise": "^17.0.0",
@@ -66,7 +71,7 @@
     "@libp2p/websockets": "^10.1.19",
     "@multiformats/multiaddr": "^13.0.3",
     "@noble/curves": "^2.3.0",
-    "better-sqlite3": "^11.10.0",
+    "better-sqlite3": "^12.11.1",
     "it-pipe": "^3.0.1",
     "it-pushable": "^3.2.4",
     "libp2p": "^3.3.8",

package/src/blob/blob.mjs

@@ -20,19 +20,24 @@
  *      carrier-side log/telemetry may ever see) carries none of those.
  *      The serialized ref must stay <= 4 KiB.
  *   4. REDEEM on receipt: recipient checks the ref signature + expiry +
- *      recipient binding, verifies the sender's registry key is ACTIVE,
+ *      recipient binding, proves the sender (its UUAID derives from the key
+ *      that signed the ref, or else a registry badge names that key),
  *      fetches and hash-checks the object, redeems the broker challenge
  *      (single-use), then decrypts.
  *
  * Error contract: every failure throws a typed BlobError subclass with a
  * stable `.code` — blob-too-large, blob-expired, blob-not-found,
  * blob-upload-failed, blob-fetch-failed, blob-integrity-failed,
- * blob-ref-invalid, blob-broker-*, sender-key-not-active.
+ * blob-ref-invalid, blob-broker-*, blob-key-unproven, sender-key-not-active.
+ * A broker refusal carries the broker's own `.code` and `.fix` when the
+ * broker sends them (`.legacyCode` keeps the blob-broker-* value). A refusal
+ * that knows its next step has a one-line `.fix`.
  */
 import { createCipheriv, createDecipheriv, createHash, randomBytes } from "node:crypto";
 import { jcs } from "../identity/jcs.mjs";
-import { Keychain } from "../identity/keychain.mjs";
+import { Keychain, localIdFromKey } from "../identity/keychain.mjs";
 import { ABSOLUTE_MAX_BODY, TIER_DEFAULTS } from "../identity/tier.mjs";
+import { REFUSAL_FIXES } from "../net/refusals.mjs";
 
 export const BLOB_REF_V = 1;
 export const BLOB_KIND = "blob-ref";
@@ -44,10 +49,18 @@ export const DEFAULT_BLOB_TTL_MS = 24 * 3600 * 1000;
 export const DEFAULT_DIRECT_THRESHOLD_BYTES = 256_000;
 export const NONCE_BYTES = 12;
 export const DEK_BYTES = 32;
+/** keyId a broker request presents when the identity proves itself by its own key. */
+export const SELF_CERTIFIED_KEY_ID = "self-certified:ed25519";
+/** The one UUAID namespace and object type the broker accepts on the self-certified path. */
+export const SELF_CERTIFIED_NAMESPACE = "foundation";
+export const SELF_CERTIFIED_OBJECT_TYPE = "agent";
 
 // ---------------------------------------------------------------- errors ---
 export class BlobError extends Error {
-  constructor(code, message) { super(message ?? code); this.name = "BlobError"; this.code = code; }
+  constructor(code, message, { fix = null } = {}) {
+    super(message ?? code); this.name = "BlobError"; this.code = code;
+    if (fix) this.fix = fix;
+  }
 }
 export class BlobSizeError extends BlobError {
   constructor(message, { size, max } = {}) { super("blob-too-large", message); this.size = size; this.max = max; }
@@ -70,11 +83,24 @@ export class BlobIntegrityError extends BlobError {
 export class BlobRefError extends BlobError {
   constructor(message) { super("blob-ref-invalid", message); }
 }
+/**
+ * `code` is the broker's own code when it sent one; `legacyCode` is the
+ * status-derived blob-broker-* code this client has always used (set on HTTP
+ * refusals); `body` is the refusal body, numbers included.
+ */
 export class BlobBrokerError extends BlobError {
-  constructor(code, message, status = null) { super(code, message); this.status = status; }
+  constructor(code, message, status = null, { fix = null, legacyCode = null, body = null } = {}) {
+    super(code, message, { fix });
+    this.status = status;
+    if (legacyCode) this.legacyCode = legacyCode;
+    if (body) this.body = body;
+  }
 }
 export class BlobSenderKeyError extends BlobError {
-  constructor(message, sender, status) { super("sender-key-not-active", message); this.sender = sender; this.status = status; }
+  constructor(message, sender, status) {
+    super("sender-key-not-active", message, { fix: REFUSAL_FIXES["sender-key-not-active"] });
+    this.sender = sender; this.status = status;
+  }
 }
 
 // ------------------------------------------------------------- crypto -----
@@ -142,6 +168,41 @@ export function mkObjectName() {
   return randomBytes(32).toString("hex");
 }
 
+// ------------------------------------------------------ self-certified ---
+/**
+ * The one UUAID a key self-certifies, rebuilt in full:
+ * `uuaid:foundation:agent:` + sha256(publicKey)[:16] as a UUID (localIdFromKey,
+ * the twin of pillar-client's localIdFromPublicKey). Null for a malformed key.
+ */
+export function selfCertifiedUuaidFor(publicKeyHex) {
+  if (typeof publicKeyHex !== "string" || !/^[0-9a-f]{64}$/i.test(publicKeyHex)) return null;
+  const localId = localIdFromKey(Buffer.from(publicKeyHex, "hex"));
+  return `uuaid:${SELF_CERTIFIED_NAMESPACE}:${SELF_CERTIFIED_OBJECT_TYPE}:${localId}`;
+}
+
+/**
+ * True only when `uuaid` is EXACTLY the UUAID the key self-certifies (full
+ * string, namespace and object type included, the broker's rule); such an
+ * identity uses the broker without a registry badge. A device, a service,
+ * another namespace, or a matching local id under any other prefix is not
+ * self-certified: it needs a registry badge naming its key.
+ */
+export function isSelfCertifiedUuaid(uuaid, publicKeyHex) {
+  const expected = selfCertifiedUuaidFor(publicKeyHex);
+  return expected !== null && uuaid === expected;
+}
+
+/**
+ * Recipient sender gate, self-certified half: the ref's signature verifies
+ * under `ref.sig.publicKey`, and `ref.sender` derives from that same key.
+ * The sender field is inside the signed bytes, so the key that proves the
+ * UUAID is the key whose signature was checked. Checked here rather than
+ * trusted from an earlier validateBlobRef, so the gate stands on its own.
+ */
+export function senderSelfCertified(ref) {
+  return verifyBlobRefSig(ref) && isSelfCertifiedUuaid(ref?.sender, ref?.sig?.publicKey);
+}
+
 // ------------------------------------------------------------------ refs ---
 function refSignable(ref) {
   const { sig, ...rest } = ref;
@@ -329,17 +390,23 @@ export async function prepareBlobSend(keychain, { data, envelopeId, recipient, t
 
 /**
  * RECEIVE side.  Gate order: ref validation (sig/expiry/recipient) ->
- * registry-active sender key check -> fetch -> content-hash check ->
- * broker redemption (single-use, only after every prior gate passed) ->
- * decrypt -> size check.
+ * sender key gate -> fetch -> content-hash check -> broker redemption
+ * (single-use, only after every prior gate passed) -> decrypt -> size check.
+ *
+ * `senderKeyCheck(uuaid, pubkeyHex) => status` is the registry check for a
+ * sender whose UUAID does NOT derive from the key that signed the ref. A
+ * derived sender is proven by the verified ref signature alone (the same
+ * rule its envelope was accepted on), so the check is not consulted for it.
  */
 export async function fetchAndDecryptBlob({ ref, store, envelopeId, now = Date.now(), broker = null, senderKeyCheck = null }) {
   validateBlobRef(ref, { recipient: null, now });
   if (typeof ref.envelopeId === "string" && envelopeId && ref.envelopeId !== envelopeId) {
     throw new BlobRefError(`blob-ref bound to envelope ${ref.envelopeId}, received in ${envelopeId}`);
   }
-  // Registry-active sender key gate — BEFORE any redemption burns.
-  if (senderKeyCheck) {
+  // Sender key gate — BEFORE any redemption burns. Only a non-derived sender
+  // needs the registry to vouch for its key.
+  const selfCertified = senderSelfCertified(ref);
+  if (senderKeyCheck && !selfCertified) {
     const status = await senderKeyCheck(ref.sender, ref.sig?.publicKey);
     if (status !== "active") {
       throw new BlobSenderKeyError(`sender key for ${ref.sender} is ${status ?? "unknown"}, not active — refusing redemption`, ref.sender, status);
@@ -364,7 +431,10 @@ export async function fetchAndDecryptBlob({ ref, store, envelopeId, now = Date.n
   if (data.length !== ref.plaintextSize) {
     throw new BlobIntegrityError(`blob size mismatch: decrypted ${data.length}B, ref says ${ref.plaintextSize}B`);
   }
-  return { data, object: ref.object, hash: ref.hash, size: ref.size };
+  return {
+    data, object: ref.object, hash: ref.hash, size: ref.size,
+    sender: ref.sender, senderProof: selfCertified ? "self-certified" : senderKeyCheck ? "sender-key-check" : "unchecked",
+  };
 }
 
 /** Production send path through the recipient-authenticated UUAID HTTP broker. */
@@ -399,13 +469,24 @@ export async function prepareBrokerBlobSend(keychain, { data, envelopeId, recipi
   return { ...prepared, size: buf.length, hash: prepared.ref.hash, object: prepared.ref.object };
 }
 
-/** Production receive path; registry verification precedes broker redemption. */
+/**
+ * Production receive path; the sender key gate precedes broker redemption.
+ * A sender whose UUAID is exactly the uuaid:foundation:agent UUAID of the
+ * ref's verified signing key passes without a badge; any other sender needs
+ * a fresh registry badge naming that key (client.assertRegistryActiveSender).
+ *
+ * The result names the sender and how it was proven (`senderProof`):
+ * "self-certified" means the key holder is proven but the identity is
+ * UNVERIFIED (no registry name or badge applies; show the UUAID only);
+ * "registry-badge" means a fresh registry badge names the signing key.
+ */
 export async function fetchBrokerBlob({ ref, envelopeId, recipient, now = Date.now(), client }) {
   if (!client) throw new BlobError("no-broker-client", "fetchBrokerBlob: broker client required");
   validateBlobRef(ref, { recipient, now });
   if (ref.envelopeId !== envelopeId) throw new BlobRefError("blob-ref envelope binding mismatch");
   if (ref.broker !== client.baseUrl) throw new BlobRefError("blob-ref broker binding mismatch");
-  await client.assertRegistryActiveSender(ref.sender, ref.sig?.publicKey);
+  const selfCertified = senderSelfCertified(ref);
+  if (!selfCertified) await client.assertRegistryActiveSender(ref.sender, ref.sig?.publicKey);
   const redeemed = await client.redeem(ref.object);
   client.crossCheckRedemption(ref, redeemed.blob);
   const stored = await client.download(redeemed.download);
@@ -422,5 +503,8 @@ export async function fetchBrokerBlob({ ref, envelopeId, recipient, now = Date.n
   if (data.length !== ref.plaintextSize) {
     throw new BlobIntegrityError(`blob plaintext size mismatch: ${data.length}B != ${ref.plaintextSize}B`);
   }
-  return { data, object: ref.object, hash: ref.hash, size: ref.plaintextSize };
+  return {
+    data, object: ref.object, hash: ref.hash, size: ref.plaintextSize,
+    sender: ref.sender, senderProof: selfCertified ? "self-certified" : "registry-badge",
+  };
 }