@uuaid/pillar 0.2.0-alpha.8 → 2.0.1

package/src/escrow/verify.mjs

@@ -0,0 +1,119 @@
+/**
+ * TransferVerifier — the VDA-1 `transfer` instrument (spec: docs/VDA-1-SPEC.md).
+ * "Did transfer X (from, to, amount, asset) really settle on rail R?" is
+ * answered from the RAIL'S OWN record (chain receipt + logs at depth), never
+ * from the claimant's story, and emitted as a signed, content-addressed
+ * VDA-1 envelope.
+ *
+ * Design carried from the uuaid/iaaso governance stack: content-addressed
+ * ids (sha256(jcs(claim))[:16]); Ed25519 over JCS (offline verification);
+ * fail-closed token registry; instrument-blind honesty (fleet SOP §4.12) —
+ * a rail structurally blind to a claim answers "instrument-blind", never a
+ * vacuous negative.  Every envelope carries a mandatory instrument-coverage
+ * statement (spec §5.1).
+ *
+ * Envelopes emitted before VDA-1 (kind "transfer-attestation", claims
+ * without `kind`) remain verifiable via verifyAttestationSig/verifyEnvelope —
+ * accepted read-only, never emitted (spec §4 legacy note).
+ */
+import { jcs } from "../identity/jcs.mjs";
+import { Keychain } from "../identity/keychain.mjs";
+import { railKeyOfTerms } from "./rails/index.mjs";
+import { normalizeClaim, buildAttestation } from "../vda/core.mjs";
+
+export const ATTESTATION_V = 1;
+
+// NOTE: the old 16-hex `claimId` export was deleted (RedTeam round-2 rec 5)
+// so a truncated join key cannot be resurrected.  Legacy envelope ids are
+// handled inside vda/core.mjs (legacyClaimId, read-only branch).
+
+/** Offline signature check for VDA-1 AND legacy envelopes. */
+export function verifyAttestationSig(publicKeyHex, attestation) {
+  try {
+    const { sig, ...rest } = attestation;
+    if (attestation.v !== ATTESTATION_V || typeof sig !== "string") return false;
+    return Keychain.verifyDetached(publicKeyHex, Buffer.from(jcs(rest), "utf-8"), Buffer.from(sig, "hex"));
+  } catch (_e) {
+    return false;
+  }
+}
+
+export class TransferVerifier {
+  /**
+   * @param rails         RailSet (rails may implement verifyTransfer; those
+   *                      that don't are instrument-blind for standalone claims)
+   * @param keychain      loaded Keychain; attestations are signed by it.
+   *                      Omit for unsigned (local-only) verification.
+   * @param tokenRegistry optional fail-closed allowlist (chains + tokens)
+   */
+  constructor({ rails, keychain = null, tokenRegistry = null }) {
+    if (!rails) throw new Error("TransferVerifier: rails required");
+    this.rails = rails;
+    this.keychain = keychain;
+    this.tokenRegistry = tokenRegistry;
+  }
+
+  /**
+   * Verify one transfer claim and return a (signed) VDA-1 attestation.
+   * claim: { rail: "evm"|"zilligon", chainId?, txId, from?, to, amount, asset? }
+   * Amounts are decimal base-unit strings (wei / Gons) — spec §2.
+   */
+  async verify(claimRaw) {
+    const n = normalizeClaim({ ...claimRaw, kind: "transfer" });
+    const coverageRefused =
+      "Verifier refused before consulting any instrument; this attestation observes nothing about the event.";
+    if (!n.ok) {
+      const claim = normalizeClaim({ kind: "malformed", originalKind: "transfer" }).claim;
+      return buildAttestation({ claim, verdict: "unsupported", reason: n.reason, coverage: coverageRefused, keychain: this.keychain });
+    }
+    const claim = n.claim;
+    const finish = (verdict, extra = {}) => buildAttestation({ claim, verdict, keychain: this.keychain, ...extra });
+
+    const railKey = railKeyOfTerms({ v: 2, rail: claim.rail, chainId: claim.chainId });
+    const rail = railKey ? this.rails.get(railKey) : null;
+    if (!rail) return finish("unsupported", { reason: "rail-unsupported", coverage: coverageRefused });
+
+    // Fail-closed allowlist, same gate the escrow applies at the door.
+    if (this.tokenRegistry && claim.rail === "evm") {
+      if (!this.tokenRegistry.isChainApproved(claim.chainId)) {
+        return finish("unsupported", { reason: "chain-not-registered", coverage: coverageRefused });
+      }
+      if (claim.asset !== "native" && !this.tokenRegistry.isAssetApproved(claim.chainId, claim.asset)) {
+        return finish("unsupported", { reason: "token-not-registered", coverage: coverageRefused });
+      }
+    }
+
+    if (typeof rail.verifyTransfer !== "function") {
+      return finish("instrument-blind", {
+        reason: "rail-cannot-attest-standalone-claims",
+        coverage:
+          "Instrument: this rail sees only its own wallet's rows and cannot observe arbitrary third-party transfers; " +
+          "this verdict is explicitly NOT evidence the transfer did not settle.",
+      });
+    }
+
+    const coverage =
+      `Instrument: the ${claim.rail} rail's own record (receipt and event logs at confirmation depth) via a single ` +
+      "RPC endpoint; full sight of the transaction hash space on that chain, subject to that endpoint's honesty — " +
+      "use a quorum of independent verifiers to bound endpoint trust.";
+
+    let res;
+    try {
+      res = await rail.verifyTransfer({ txId: claim.txId, from: claim.from, to: claim.to, amount: claim.amount, asset: claim.asset });
+    } catch (e) {
+      return finish("unsupported", { reason: `instrument-error: ${String(e.message ?? e)}`, coverage });
+    }
+    if (res?.verified) {
+      return finish("verified", {
+        coverage,
+        // blockNumber as a string: spec §3 — quantities that can exceed 2^53
+        evidence: { blockNumber: String(res.blockNumber), depth: res.depth, from: res.from, to: res.to, amount: res.amount, asset: res.asset },
+      });
+    }
+    if (res?.reason === "unconfirmed") return finish("pending", { reason: "below-confirmation-depth", coverage });
+    if (res?.reason === "instrument-blind") {
+      return finish("instrument-blind", { reason: res.detail ?? "instrument-blind", coverage });
+    }
+    return finish("failed", { reason: res?.reason ?? "not-found", coverage });
+  }
+}

package/src/escrow/zilligon.mjs

@@ -0,0 +1,266 @@
+/**
+ * Zilligon ZGN rail client — the ONLY money surface of the blind escrow.
+ *
+ * VERIFIED live against zilligon.com (2026-08-21, read-only / OPTIONS /
+ * invalid-body probes — no money has ever moved):
+ *   POST /api/v1/auth/token   {apiKey, grantType:"api_key"}
+ *        -> {success, data:{accessToken, expiresIn:900, scopes}}
+ *   POST /api/v1/wallet/transfer {recipientHandle, amount}   (JWT Bearer)
+ *        The route EXISTS (OPTIONS -> 204 Allow: OPTIONS, POST) though it
+ *        appears in NO docs.  Validation, elicited with invalid bodies:
+ *        recipientHandle required string; amount must be a positive number
+ *        (strings rejected, non-integers NOT rejected at validation);
+ *        unknown handle -> 404 RECIPIENT_NOT_FOUND; self-transfer -> 400
+ *        SELF_TRANSFER; extra fields tolerated.
+ *        LIVE-VERIFIED end-to-end 2026-08-21: the rewards-service sidecar is
+ *        now DEPLOYED on the prod cluster (REWARDS_SERVICE_URL +
+ *        INTERNAL_SERVICE_SECRET wired on the live task-def) and an
+ *        owner-authorized 10-Gon transfer returned HTTP 200 with
+ *        {transactionId, newBalance, recipient, amount}.  transactionId is
+ *        the Tip row's id, which equals BOTH wallet rows' sourceId — the
+ *        response's txId is the cross-side link (verified on the live rows).
+ *        Also verified live: recipient must be status "ACTIVE" or the route
+ *        returns 404 RECIPIENT_NOT_FOUND — 46,162 of the agents are DORMANT
+ *        and only 37 platform-wide can receive transfers at all.
+ *   GET  /api/token/wallet?handle=<h>   public by handle, NO auth — but a
+ *        browser User-Agent is REQUIRED (403 "Automated access not
+ *        permitted" without one, 200 with).  Last ~20 tx rows:
+ *        -> {handle, reputation, wallet:{zgnBalance, zgnLocked, zgnStaked,
+ *            transactions:[{type, amount, currency, status, source, date}]}}
+ *
+ * VERIFIED tx vocabulary (20 rows sampled across 3 wallets, 2026-08-21):
+ * every observed row is {type:"EARNING", currency:"GONS",
+ * status:"CONFIRMED", source:"CODE_FORGE", date:ISO}.
+ *
+ * TRANSFER ROW CONTRACT (verified LIVE in-container 2026-08-21 on the prod
+ * DB — matches services/rewards-service internal.ts:290-348): one Tip + two
+ * WalletTransaction rows in a single prisma.$transaction:
+ *   sender   row: type "TIP_SENT",   amount NEGATIVE, fee set,
+ *   receiver row: type "TIP_RECEIVED", amount net
+ *                 (amount - floor(amount*0.005)), fee unset -> 0,
+ *   both rows: currency "GONS", sourceType "transfer" (public API projects
+ *   `source: "transfer"`), sourceId = tip.id (the ONLY link between the two
+ *   sides — and the id the transfer API returns as transactionId), status
+ *   "CONFIRMED", balanceAfter set.  A row's own Prisma cuid `id` is NOT the
+ *   transactionId.
+ * The public wallet API (/api/token/wallet) historically projected ONLY
+ * {type, amount, currency, status, source, date}; an additive projection fix
+ * (Zilligon-Lead, 2026-08-21) adds {id, sourceId, fee, balanceAfter}.
+ * Consequence for the matchers:
+ *   - "source" on a transfer row is the literal string "transfer", NOT a
+ *     handle — source-binding is only enforced when the field actually
+ *     looks like a handle ("@..."), otherwise the row stays unbound.
+ *   - TIP_SENT rows carry NEGATIVE amounts — the payout matcher compares
+ *     magnitudes.
+ *   - A buyer's claimed txId (the transfer response's transactionId) equals
+ *     row.sourceId, NOT row.id — the matchers accept a claimed txId against
+ *     EITHER, bind on an explicit sourceId claim, and HARD-REJECT a row
+ *     whose sourceId disagrees with the claim (no silent amount+window
+ *     fallthrough).  Pre-fix rows (no id/sourceId in the projection) still
+ *     degrade to amount+window attestation — the documented caveat for the
+ *     IAASO ratification doc.
+ *
+ * Fee (verified in source: config.ts:52 tipFeePercent 0.005 + internal.ts:288
+ * fee = floor(amount * 0.005)): every transfer below 200 Gons is FEE-FREE;
+ * the receiver nets exactly `amount`.  200 Gons is the first amount that
+ * pays 1.  The escrow fee math in terms.mjs mirrors this exactly.
+ */
+
+const BROWSER_UA = "Mozilla/5.0"; // the exact UA verified to pass the wallet-view gate
+
+/**
+ * Verified background-noise tx types — never a payment/payout signal.
+ * TIP_SENT / TIP_RECEIVED (the transfer-created rows) are NOT noise — they
+ * are the exchange rows the matchers hunt for.
+ */
+export const TX_NOISE_TYPES = ["earning"];
+
+export class ZilligonClient {
+  constructor({ baseUrl = "https://zilligon.com", apiKey, handle }) {
+    if (!apiKey) throw new Error("ZilligonClient: apiKey required");
+    if (!handle) throw new Error("ZilligonClient: handle required (escrow's own @handle)");
+    this.baseUrl = baseUrl.replace(/\/+$/, "");
+    this.apiKey = apiKey;
+    this.handle = handle;
+    this._token = null; // { accessToken, expiresAt }
+  }
+
+  async getToken() {
+    if (this._token && this._token.expiresAt > Date.now() + 30_000) return this._token.accessToken;
+    const res = await fetch(`${this.baseUrl}/api/v1/auth/token`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ apiKey: this.apiKey, grantType: "api_key" }),
+    });
+    if (!res.ok) throw new Error(`zilligon auth/token: HTTP ${res.status}`);
+    const json = await res.json();
+    if (json.success !== true || !json.data?.accessToken) {
+      throw new Error(`zilligon auth/token rejected: ${json.error || json.message || "unknown"}`);
+    }
+    this._token = {
+      accessToken: json.data.accessToken,
+      expiresAt: Date.now() + (json.data.expiresIn ?? 900) * 1000,
+    };
+    return this._token.accessToken;
+  }
+
+  async _authed(method, path, body) {
+    const token = await this.getToken();
+    const res = await fetch(`${this.baseUrl}${path}`, {
+      method,
+      headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
+      body: body === undefined ? undefined : JSON.stringify(body),
+    });
+    const json = await res.json().catch(() => ({}));
+    if (!res.ok || json.success === false) {
+      throw new Error(`zilligon ${path}: HTTP ${res.status} ${json.error || json.message || ""}`.trim());
+    }
+    return json;
+  }
+
+  /**
+   * Transfer Gons to a handle.  The body carries ONLY the verified fields
+   * {recipientHandle, amount}.  Local guards mirror the rail's verified
+   * rejection set (self-transfer) plus an integer guard stricter than the
+   * rail's validation (which accepts any positive number — Gons are whole).
+   */
+  async transfer({ recipientHandle, amount }) {
+    if (typeof amount !== "number" || !Number.isInteger(amount) || amount < 1) {
+      throw new Error(`transfer: amount must be an integer >= 1 Gons, got ${amount}`);
+    }
+    if (recipientHandle === this.handle) throw new Error("transfer: self-transfer rejected by rail");
+    return this._authed("POST", "/api/v1/wallet/transfer", { recipientHandle, amount });
+  }
+
+  /** Public wallet view for a handle — needs a browser User-Agent (verified). */
+  async getWallet(handle = this.handle) {
+    const res = await fetch(`${this.baseUrl}/api/token/wallet?handle=${encodeURIComponent(handle)}`, {
+      headers: { "User-Agent": BROWSER_UA },
+    });
+    if (!res.ok) throw new Error(`zilligon wallet?handle=: HTTP ${res.status}`);
+    return res.json();
+  }
+
+  /**
+   * Attest the buyer's payment from THIS client's wallet: poll until a
+   * matching non-noise row appears.  Returns the row, or null once attempts
+   * are exhausted.
+   */
+  async findPayment({ buyerHandle, expectedAmount, txId, sourceId, since, attempts = 6, delayMs = 5000 }) {
+    for (let i = 0; i < attempts; i++) {
+      let view;
+      try {
+        view = await this.getWallet(this.handle);
+      } catch (_e) {
+        view = null; // transient rail hiccup — retry
+      }
+      const hit = view ? findPaymentInWallet(view, { buyerHandle, expectedAmount, txId, sourceId, since }) : null;
+      if (hit) return hit;
+      await new Promise((r) => setTimeout(r, delayMs));
+    }
+    return null;
+  }
+}
+
+/** Extract a transaction id from any shape the rail might return. */
+export function txIdOf(tx) {
+  return tx?.txId ?? tx?.id ?? tx?.transactionId ?? tx?._id ?? null;
+}
+
+const asNum = (v) => {
+  const n = Number(v);
+  return Number.isFinite(n) ? n : null;
+};
+
+/**
+ * Handle-like source/destination fields ("@handle") bind a row to a
+ * counterparty.  Transfer rows carry the literal type string ("transfer") in
+ * `source` — NOT a handle — so binding must only fire on handle-shaped values.
+ */
+const looksLikeHandle = (s) => typeof s === "string" && s.startsWith("@");
+
+/** A row is a candidate payment/payout iff its type is not verified noise. */
+function isExchangeRow(tx) {
+  const t = String(tx?.type ?? "").toLowerCase();
+  if (!t) return true; // unknown vocabulary — can't classify as noise
+  return !TX_NOISE_TYPES.includes(t);
+}
+
+/** ISO-string window check; rows that can't be compared are NOT filtered. */
+function afterSince(dateStr, sinceStr) {
+  const d = Date.parse(dateStr);
+  const s = Date.parse(sinceStr);
+  if (Number.isNaN(d) || Number.isNaN(s)) return true;
+  return d >= s;
+}
+
+/**
+ * Pure matcher — shared by the live client and the integration-test mock so
+ * the mock exercises the SAME attestation logic.  A payment hit needs:
+ *   1. a non-noise row (only EARNING rows are proven noise; transfer rows
+ *      are TIP_SENT/TIP_RECEIVED — non-noise, see header),
+ *   2. amount === expectedAmount Gons exactly,
+ *   3. date >= since, when a window is given,
+ *   4. counterparty binding, strongest first (verified live 2026-08-21: the
+ *      transfer response's transactionId equals BOTH rows' sourceId, NOT a
+ *      row's own id — so a claimed txId matches against EITHER):
+ *        a. claimed txId === row.id OR row.sourceId  -> hit;
+ *        b. explicit sourceId claim === row.sourceId -> hit;
+ *        c. row.sourceId present but DISAGREEING with a claim -> the row is
+ *           someone else's transfer: hard-skip, never amount+window
+ *           fallthrough;
+ *   5. and — when the row carries a handle-SHAPED source field ("@...") and
+ *      buyerHandle is known — that source equals the buyer.  A non-handle
+ *      source (the literal "transfer" on rail rows) with no id/sourceId
+ *      (pre-projection-fix rows) leaves the row UNBOUND: it attests by
+ *      amount+window alone.
+ */
+export function findPaymentInWallet(walletView, { buyerHandle, expectedAmount, txId, sourceId, since }) {
+  const wallet = walletView?.wallet ?? walletView ?? {};
+  const txs = Array.isArray(wallet.transactions) ? wallet.transactions : [];
+  for (const tx of txs) {
+    if (typeof tx !== "object" || tx === null) continue;
+    if (!isExchangeRow(tx)) continue;
+    if (asNum(tx.amount) !== expectedAmount) continue;
+    if (since && !afterSince(tx.date, since)) continue;
+    const source = tx.source ?? tx.from ?? tx.senderHandle ?? null;
+    const id = txIdOf(tx);
+    const rowSourceId = tx.sourceId ?? null;
+    // (a) claimed txId matches row id or row sourceId — the strongest link
+    //     (the transfer API's transactionId IS the rows' sourceId).
+    if (txId && ((id && String(id) === String(txId)) || (rowSourceId && String(rowSourceId) === String(txId)))) return tx;
+    // (b) explicit sourceId claim matches the row's.
+    if (sourceId && rowSourceId && String(rowSourceId) === String(sourceId)) return tx;
+    // (c) the row carries a sourceId that conflicts with our claims — it is
+    //     someone else's transfer: hard-skip.
+    if (rowSourceId && ((txId && String(rowSourceId) !== String(txId)) || (sourceId && String(rowSourceId) !== String(sourceId)))) continue;
+    if (buyerHandle && looksLikeHandle(source) && source !== buyerHandle) continue; // bound and mismatched
+    return tx;
+  }
+  return null;
+}
+
+/**
+ * Matcher for the escrow's own payout: a non-noise row of the exact amount
+ * (magnitude — the escrow's sender-side rows are TIP_SENT with NEGATIVE
+ * amounts, see header).  dest-binding only fires on handle-shaped fields;
+ * an explicit sourceId claim binds hard (match -> hit, disagreement -> skip).
+ */
+export function findPayoutInWallet(walletView, { sellerHandle, amount, sourceId, since }) {
+  const wallet = walletView?.wallet ?? walletView ?? {};
+  const txs = Array.isArray(wallet.transactions) ? wallet.transactions : [];
+  for (const tx of txs) {
+    if (typeof tx !== "object" || tx === null) continue;
+    if (!isExchangeRow(tx)) continue;
+    const mag = asNum(tx.amount);
+    if (mag === null || Math.abs(mag) !== amount) continue; // TIP_SENT rows are negative (see header)
+    if (since && !afterSince(tx.date, since)) continue;
+    const rowSourceId = tx.sourceId ?? null;
+    if (sourceId && rowSourceId && String(rowSourceId) === String(sourceId)) return tx;
+    if (sourceId && rowSourceId && String(rowSourceId) !== String(sourceId)) continue; // hard disagreement — someone else's transfer
+    const dest = tx.destination ?? tx.to ?? tx.recipientHandle ?? null;
+    if (sellerHandle && looksLikeHandle(dest) && dest !== sellerHandle) continue; // bound and mismatched
+    return tx;
+  }
+  return null;
+}

package/src/identity/keychain.mjs

@@ -15,6 +15,22 @@ import { randomBytes, createHash, generateKeyPairSync, sign, verify, createPubli
 
 const KEYCHAIN_VERSION = 1;
 
+/**
+ * Derive a stable, publishable local id from a raw Ed25519 public key.  This
+ * makes the UUAID self-authenticating: given the UUAID, anyone can
+ * independently check that the public key hashes to the expected local-id.
+ *
+ * Public because consumers verifying a UUAID against a public key need it
+ * without reaching into `Keychain._localIdFromKey`.
+ */
+export function localIdFromKey(rawPub) {
+  const h = createHash("sha256").update(rawPub).digest();
+  // First 16 bytes -> UUID-style dash format for readability.
+  const b = h.slice(0, 16);
+  const hex = Buffer.from(b).toString("hex");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}
+
 export class Keychain {
   constructor(path) {
     this.path = path;
@@ -48,16 +64,17 @@ export class Keychain {
     };
   }
 
-  static _localIdFromKey(rawPub) {
-    // Derive a stable, publishable local id from the public key.  This makes
-    // the UUAID self-authenticating: given the UUAID, anyone can independently
-    // check that the public key hashes to the expected local-id.
-    const h = createHash("sha256").update(rawPub).digest();
-    // First 16 bytes -> UUID-style dash format for readability.
-    const b = h.slice(0, 16);
-    const hex = Buffer.from(b).toString("hex");
-    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
-  }
+  /**
+   * Derive the local-id from a raw Ed25519 public key.
+   *
+   * Kept on the class for the call sites that already reach for it; the
+   * implementation is the module-level `localIdFromKey`, which is the public
+   * export.
+   */
+  static localIdFromKey = localIdFromKey;
+
+  /** @deprecated Alias kept for compatibility — use `localIdFromKey`. */
+  static _localIdFromKey = localIdFromKey;
 
   /**
    * Load an identity from disk.

package/src/identity/tier.mjs

@@ -0,0 +1,130 @@
+/**
+ * Tier grants — carrier-side volume/size flexibility for qualified identities.
+ *
+ * Foundations, orgs, and enterprise supporters that pass the UUAID
+ * qualification process receive a SIGNED TIER GRANT: a portable JSON object,
+ * Ed25519-signed by a trusted issuer (the UUAID Foundation identity, or any
+ * issuer a carrier operator chooses to trust).  Carriers verify the signature
+ * and expiry locally — no registry lookup, no account, consistent with the
+ * self-authenticating design.  The wire API is unchanged: a grant only
+ * raises the holder's rate/size budgets at carriers that trust the issuer.
+ *
+ * Qualification has two routes. The original is off-wire: the foundation's
+ * review process decides WHO gets a grant. The second is earned on-wire —
+ * operators who keep a public seed alive are promoted by the seed registry
+ * (net/seed-registry.mjs) and issued a grant automatically, no review. This
+ * module only makes grants unforgeable and portable; it does not care which
+ * route produced one.
+ *
+ * Grant shape (JCS-signed over every field except `sig`):
+ *   { v: 1, uuaid, tier, envelopesPerMin, maxBodyBytes, expires, issuer, sig }
+ *   ...plus optional { priority: true, seedTier, seedUrl } on earned grants.
+ *
+ * `priority` is the wire half of priority delivery: a carrier that trusts the
+ * issuer admits the holder from a reserved lane when it is otherwise shedding
+ * load. It is inside the signed body, so it cannot be added to a grant after
+ * issue. Older carriers that predate the field verify such a grant unchanged
+ * (JCS covers whatever keys are present) and simply ignore the privilege.
+ */
+import { createHash } from "node:crypto";
+import { jcs } from "./jcs.mjs";
+import { Keychain } from "./keychain.mjs";
+
+/** 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 },
+  enterprise: { envelopesPerMin: 1200, maxBodyBytes: 2 * 1024 * 1024 },
+  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;
+
+function signable(grant) {
+  const { sig, ...rest } = grant;
+  return jcs(rest);
+}
+
+/**
+ * Issue a grant, signed by the loaded keychain (the issuer identity).
+ * Rates/sizes default from the tier ladder; explicit overrides are clamped
+ * to the absolute ceilings.
+ */
+export function makeTierGrant(keychain, { uuaid, tier, envelopesPerMin, maxBodyBytes, expires, priority, seedTier, seedUrl }) {
+  if (!TIER_DEFAULTS[tier]) throw new Error(`unknown tier "${tier}" (${Object.keys(TIER_DEFAULTS).join("|")})`);
+  if (!uuaid?.startsWith("uuaid:")) throw new Error("grant subject must be a uuaid:...");
+  if (!expires || !Number.isFinite(Date.parse(expires))) throw new Error("expires must be an ISO date");
+  const grant = {
+    v: 1,
+    uuaid,
+    tier,
+    envelopesPerMin: Math.min(envelopesPerMin ?? TIER_DEFAULTS[tier].envelopesPerMin, ABSOLUTE_MAX_RATE),
+    maxBodyBytes: Math.min(maxBodyBytes ?? TIER_DEFAULTS[tier].maxBodyBytes, ABSOLUTE_MAX_BODY),
+    expires,
+    issuer: keychain._identity.publicKeyHex,
+    // Optional fields are omitted rather than set false/null so that a plain
+    // grant's signed body stays byte-identical to what pre-priority issuers
+    // produced.
+    ...(priority ? { priority: true } : {}),
+    ...(seedTier ? { seedTier } : {}),
+    ...(seedUrl ? { seedUrl } : {}),
+  };
+  grant.sig = keychain.sign(Buffer.from(signable(grant), "utf-8")).toString("hex");
+  return grant;
+}
+
+/**
+ * Verify a grant against a set of trusted issuer pubkeys (hex).
+ * Returns { ok: true, grant } or { ok: false, reason }.
+ */
+export function verifyTierGrant(grant, trustedIssuers, now = Date.now()) {
+  if (grant?.v !== 1) return { ok: false, reason: "bad-version" };
+  if (!TIER_DEFAULTS[grant.tier]) return { ok: false, reason: "unknown-tier" };
+  if (!trustedIssuers?.includes(grant.issuer)) return { ok: false, reason: "untrusted-issuer" };
+  const exp = Date.parse(grant.expires);
+  if (!Number.isFinite(exp) || exp < now) return { ok: false, reason: "expired" };
+  if (!(grant.envelopesPerMin <= ABSOLUTE_MAX_RATE) || !(grant.maxBodyBytes <= ABSOLUTE_MAX_BODY)) {
+    return { ok: false, reason: "over-ceiling" };
+  }
+  // Fail closed on a malformed privilege: `priority` is either absent or the
+  // boolean true. Anything else (a truthy string, 1, an object) is a grant we
+  // do not understand, and understanding it wrongly grants a reserved lane.
+  if ("priority" in grant && grant.priority !== true) return { ok: false, reason: "bad-priority" };
+  let verified = false;
+  try {
+    verified = Keychain.verifyDetached(grant.issuer, Buffer.from(signable(grant), "utf-8"), Buffer.from(grant.sig, "hex"));
+  } catch (_e) { return { ok: false, reason: "verify-threw" }; }
+  if (!verified) return { ok: false, reason: "bad-signature" };
+  return { ok: true, grant };
+}
+
+export function grantFingerprint(grant) {
+  return createHash("sha256").update(signable(grant)).digest("hex").slice(0, 16);
+}

package/src/identity/trust.mjs

@@ -0,0 +1,63 @@
+/**
+ * Trust policy — the UUAID-layer consent gate (recipient-side).
+ *
+ * The envelope layer proves WHO sent a message and that it is intact; it says
+ * nothing about whether you WANT it.  This module decides, per sender, whether
+ * an incoming envelope reaches handlers or is quarantined (stored in the
+ * mailbox with a reason, never surfaced to handlers — evidence, not /dev/null).
+ *
+ * Policy file: <home>/trust.json
+ *   {
+ *     "policy": "open" | "directory" | "allowlist",
+ *     "allow":  ["uuaid:...", ...],       // always reach handlers
+ *     "block":  ["uuaid:...", ...]        // never reach handlers (any policy)
+ *   }
+ *
+ * Semantics (evaluated in order):
+ *   1. block list        -> quarantine("blocked")           (all policies)
+ *   2. allow list        -> deliver                          (all policies)
+ *   3. policy=open       -> deliver                          (default; today's behavior)
+ *   4. policy=directory  -> deliver if sender is in the address book
+ *                           (fleet.json / directory agents), else quarantine("stranger")
+ *   5. policy=allowlist  -> quarantine("not-allowlisted")
+ *
+ * No trust.json file = policy "open" = exactly the pre-alpha.11 behavior.
+ * Wire-frozen: this is a local, recipient-side decision only.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const POLICIES = ["open", "directory", "allowlist"];
+
+export function loadTrustPolicy(home) {
+  const p = join(home, "trust.json");
+  if (!existsSync(p)) return { policy: "open", allow: [], block: [], path: p, exists: false };
+  let raw;
+  try { raw = JSON.parse(readFileSync(p, "utf-8")); }
+  catch (e) { throw new Error(`trust.json unparseable at ${p}: ${e.message}`); }
+  const policy = raw.policy ?? "open";
+  if (!POLICIES.includes(policy)) {
+    throw new Error(`trust.json: unknown policy "${policy}" (expected ${POLICIES.join("|")})`);
+  }
+  const list = (v) => Array.isArray(v) ? v.filter(s => typeof s === "string") : [];
+  return { policy, allow: list(raw.allow), block: list(raw.block), path: p, exists: true };
+}
+
+/**
+ * Decide an envelope's fate.  `knownSenders` is a Set of uuaids the recipient
+ * already knows (address book / fleet.json / directory agents).
+ * Returns { deliver: true } or { deliver: false, reason }.
+ */
+export function evaluateTrust(trust, sender, knownSenders) {
+  if (trust.block.includes(sender)) return { deliver: false, reason: "blocked" };
+  if (trust.allow.includes(sender)) return { deliver: true };
+  switch (trust.policy) {
+    case "open": return { deliver: true };
+    case "directory":
+      return knownSenders?.has(sender)
+        ? { deliver: true }
+        : { deliver: false, reason: "stranger" };
+    case "allowlist": return { deliver: false, reason: "not-allowlisted" };
+    default: return { deliver: true }; // unreachable (loadTrustPolicy validates)
+  }
+}