@uuaid/agent-commons 0.0.0 → 0.2.0-alpha.4

package/src/vendor/pillar/net/carrier-client.mjs

@@ -0,0 +1,219 @@
+/**
+ * Carrier client — lets a pillar deliver + receive envelopes through one or
+ * more carrier servers using only outbound HTTP(S).
+ *
+ * This is the universal transport: works from sandboxes, NATed laptops,
+ * serverless, anywhere.  No listening socket required.
+ */
+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
+ * `probation` — the primary carrier from a directory has no seed tier and
+ * should not be assumed better than a seed that earned one, nor worse.
+ * Array.prototype.sort is stable, so a client given no tier information at
+ * all keeps its list in exactly the order it was constructed with.
+ */
+function byTier(tiers) {
+  return (a, b) => seedTier(tiers[a] ?? "probation").listRank - seedTier(tiers[b] ?? "probation").listRank;
+}
+
+/**
+ * The carrier's signed acceptance receipt (uuaid.carrier-receipt.v1), kept as
+ * the carrier sent it, plus this client's own clock when the answer arrived
+ * (design §12 rule 3: record received-at beside the carrier's acceptedAt,
+ * which is only the carrier's claim). NOT verified here: verify against the
+ * pinned key for this carrier and the exact envelope posted. {} when the
+ * carrier sent no receipt (an older or keyless carrier): that never fails a
+ * delivery, the outcome is simply unreceipted.
+ */
+function keptReceipt(body) {
+  const r = body?.receipt;
+  if (!r || typeof r !== "object" || Array.isArray(r) || typeof body.receiptSig !== "string") return {};
+  return { receipt: r, receiptSig: body.receiptSig, receivedAt: new Date().toISOString() }; // @rule client.keeps-receipt
+}
+
+export class CarrierClient {
+  /**
+   * @param {{keychain: import('../identity/keychain.mjs').Keychain, carriers: string[]}} opts
+   *   carriers: base URLs, e.g. ["https://pillar.uuaid.org"]
+   */
+  /**
+   * @param {object} opts
+   *   carrierTiers  optional { "<url>": "<seed tier>" } from a directory's
+   *                 seeds[]. Drives which carrier's receipt is authoritative
+   *                 and which one is polled first — see `deliver`.
+   */
+  constructor({ keychain, carriers, tierGrant = null, carrierTiers = {} }) {
+    if (!keychain?._identity) throw new Error("CarrierClient needs a loaded keychain");
+    if (!carriers?.length) throw new Error("CarrierClient needs at least one carrier URL");
+    this.keychain = keychain;
+    // Normalise tier keys the same way as carrier URLs so a trailing slash on
+    // one side does not silently drop a seed to `probation`.
+    this.carrierTiers = Object.fromEntries(
+      Object.entries(carrierTiers).map(([u, t]) => [String(u).replace(/\/+$/, ""), t]),
+    );
+    this.carriers = carriers.map(u => u.replace(/\/+$/, "")).sort(byTier(this.carrierTiers));
+    // Tier label for the local preflight: a signed grant raises it; default
+    // stays community (matches the carrier's unauthenticated tier).
+    this.tier = tierGrant?.tier ?? "community";
+    this.maxBodyBytes = Number.isInteger(tierGrant?.maxBodyBytes) ? tierGrant.maxBodyBytes : null;
+    // Optional signed tier grant (tier.mjs) — sent as a header on deliver so
+    // qualifying senders get raised budgets at carriers that trust the issuer.
+    this.tierGrantB64 = tierGrant
+      ? Buffer.from(JSON.stringify(tierGrant), "utf-8").toString("base64")
+      : null;
+    this._stopPolling = false;
+  }
+
+  get uuaid() { return this.keychain._identity.uuaid; }
+  get publicKeyHex() { return this.keychain._identity.publicKeyHex; }
+
+  /**
+   * Deliver an envelope to ALL carriers in parallel — p2p seed replication:
+   * the message lands on every configured seed (like a file seeded on many
+   * peers), so it survives any single carrier dying before the recipient
+   * polls.  Duplicate copies are harmless: the recipient mailbox dedups on
+   * envelope.id and re-fires no handlers.
+   *
+   * Resolves once every carrier has answered.  Succeeds if at least one
+   * accepted; throws if every carrier rejects.  Returns the receipt from the
+   * most PROVEN accepting carrier as the primary ({ carrier, seq, sha,
+   * duplicate, receipt?, receiptSig?, receivedAt? }) plus `all` with every
+   * carrier's outcome ({ carrier, ok, seq?, sha?, duplicate?, receipt?,
+   * receiptSig?, receivedAt?, error?, status?, reason?, fix? }).
+   *
+   * `receipt` / `receiptSig` are present only when that carrier signed one
+   * (uuaid.carrier-receipt.v1); they are unverified carrier output, and
+   * `receivedAt` is this client's clock, not the carrier's.
+   *
+   * 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
+   * still be there. With no tier information every carrier ranks equally and
+   * the first-in-list receipt wins, exactly as before.
+   */
+  async deliver(envelope, { timeoutMs = 10000 } = {}) {
+    // Preflight against the carrier limits BEFORE any network call: the
+    // tier inline limit first, then the 2 MiB direct hard cap — no tier
+    // grant can raise the hard cap.  Typed failure, not a carrier 413.
+    const pf = preflightBodyBytes(envelopeBodyBytes(envelope), { tier: this.tier, maxBodyBytes: this.maxBodyBytes });
+    if (!pf.ok) {
+      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) => {
+      try {
+        const res = await fetch(`${base}/v1/envelopes`, {
+          method: "POST",
+          headers: {
+            "content-type": "application/json",
+            ...(this.tierGrantB64 ? { "x-pillar-tier-grant": this.tierGrantB64 } : {}),
+          },
+          body: JSON.stringify(envelope),
+          signal: AbortSignal.timeout(timeoutMs),
+        });
+        const raw = await res.text();
+        let body = {};
+        try { body = raw ? JSON.parse(raw) : {}; } catch (_error) {}
+        if (res.status === 202 && body.accepted) {
+          return { carrier: base, ok: true, seq: body.seq, sha: body.sha, duplicate: !!body.duplicate, ...keptReceipt(body) };
+        }
+        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 };
+      }
+    };
+    const all = await Promise.allSettled(this.carriers.map(attempt)).then(rs =>
+      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) {
+      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, receipt, receiptSig, receivedAt } = ranked[0];
+    return { carrier, seq, sha, duplicate, ...(receipt ? { receipt, receiptSig, receivedAt } : {}), all };
+  }
+
+  /**
+   * Fetch envelopes addressed to us with seq > since from a specific carrier.
+   * Signed request; carrier verifies our key before serving.
+   */
+  async fetchInbox(base, { since = 0, waitS = 0, timeoutMs = 40000, signal = null } = {}) {
+    const path = `GET /v1/inbox/${this.uuaid}?since=${since}`;
+    const ts = String(Date.now());
+    const sig = this.keychain.sign(Buffer.from(`${path}\n${ts}`, "utf-8")).toString("hex");
+    const res = await fetch(`${base}/v1/inbox/${encodeURIComponent(this.uuaid)}?since=${since}&wait=${waitS}`, {
+      headers: {
+        "x-pillar-pubkey": this.publicKeyHex,
+        "x-pillar-ts": ts,
+        "x-pillar-sig": sig,
+      },
+      // `signal` lets a caller cancel a long-poll early (peekCarrierInbox stops
+      // the other carriers once one has mail).
+      signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(timeoutMs)]) : AbortSignal.timeout(timeoutMs),
+    });
+    if (res.status !== 200) {
+      const body = await res.json().catch(() => ({}));
+      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 }
+  }
+
+  /**
+   * Long-poll every carrier in parallel forever, invoking onEnvelope for each
+   * new envelope.  Tracks per-carrier cursor.  Returns a stop() function.
+   * onError(error, { carrier }) — the carrier context is passed so callers
+   * can attribute failures per carrier in metrics.
+   */
+  startPolling({ onEnvelope, cursors = {}, waitS = 25, onError }) {
+    this._stopPolling = false;
+    const state = { cursors: { ...cursors } };
+    const loops = this.carriers.map(async (base) => {
+      while (!this._stopPolling) {
+        try {
+          const r = await this.fetchInbox(base, { since: state.cursors[base] ?? 0, waitS });
+          for (const { seq, envelope } of r.envelopes) {
+            state.cursors[base] = Math.max(state.cursors[base] ?? 0, seq);
+            try { await onEnvelope(envelope, { carrier: base, seq }); }
+            catch (e) { onError?.(new Error(`onEnvelope threw: ${e.message}`), { carrier: base }); }
+          }
+        } catch (e) {
+          onError?.(e, { carrier: base });
+          // Back off on error so a dead carrier doesn't spin the CPU.
+          await new Promise(r2 => setTimeout(r2, 2000));
+        }
+      }
+    });
+    return {
+      stop: () => { this._stopPolling = true; },
+      cursors: () => ({ ...state.cursors }),
+      done: Promise.allSettled(loops),
+    };
+  }
+}

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