@uuaid/pillar 0.2.0-alpha.8 → 2.0.1

package/src/vda/core.mjs

@@ -0,0 +1,290 @@
+/**
+ * VDA-1 core — claim normalization, content-addressed ids, the signed
+ * attestation envelope, offline verification, composite receipts, quorum.
+ * Spec: docs/VDA-1-SPEC.md.  No instrument logic lives here: this file is
+ * everything a CONSUMER needs to verify, and nothing an ISSUER needs to
+ * observe rails.
+ */
+import { createHash } from "node:crypto";
+import { jcs } from "../identity/jcs.mjs";
+import { Keychain } from "../identity/keychain.mjs";
+
+export const VDA_V = 1;
+export const ATTESTATION_KIND = "vda-attestation";
+export const RECEIPT_KIND = "vda-receipt";
+/** Legacy pre-VDA envelopes (accepted read-only, never emitted — spec §4). */
+export const LEGACY_ATTESTATION_KIND = "transfer-attestation";
+
+/** Closed verdict set (spec §5). */
+export const VERDICTS = ["verified", "failed", "pending", "instrument-blind", "issuer-attested", "unsupported"];
+
+/**
+ * Composite ordering (spec §7): any failed member fails the receipt; the
+ * composite verdict is the minimum over members.
+ */
+const VERDICT_RANK = { verified: 5, "issuer-attested": 4, pending: 3, "instrument-blind": 2, unsupported: 1, failed: 0 };
+export function worseVerdict(a, b) {
+  return (VERDICT_RANK[a] ?? 0) <= (VERDICT_RANK[b] ?? 0) ? a : b;
+}
+
+const DEC_RE = /^[0-9]+$/;
+const HEX_RE = /^0x[0-9a-fA-F]+$/;
+
+/**
+ * Per-kind field allowlists (spec §3): normalization keeps EXACTLY these
+ * fields, drops everything else BEFORE hashing (unknown fields are never
+ * signed), and coerces amounts to decimal strings.  EVM-style hex fields are
+ * lowercased so the same on-chain event always hashes to the same id
+ * regardless of the claimant's casing (id intersection would break
+ * otherwise).
+ */
+const CLAIM_SHAPES = {
+  // Refusal envelopes for claims that failed normalization: the claim is
+  // replaced by this well-formed stub so the refusal itself stays a
+  // conformant, offline-verifiable envelope (spec §4).
+  malformed: ["kind", "originalKind"],
+  transfer: ["kind", "rail", "chainId", "txId", "from", "to", "amount", "asset"],
+  "data-delivery": ["kind", "contentHash", "from", "to", "recipientPubKey", "envelopeId"],
+  "message-delivery": ["kind", "envelopeId", "from", "to", "envelopeSha256"],
+  "media-availability": ["kind", "locator", "contentHash", "publisher"],
+  "fiat-settlement": ["kind", "railName", "reference", "from", "to", "amount", "currency"],
+};
+
+function lcHex(v) {
+  return typeof v === "string" && HEX_RE.test(v) ? v.toLowerCase() : v;
+}
+
+/**
+ * Normalize a claim to its VDA-1 shape.  Returns { ok, claim } or
+ * { ok:false, reason } — malformed claims are refusals (fail-closed,
+ * spec §10), never guesses.
+ */
+export function normalizeClaim(raw) {
+  const kind = raw?.kind;
+  const shape = CLAIM_SHAPES[kind];
+  if (!shape) return { ok: false, reason: `unknown-claim-kind:${String(kind)}` };
+  const c = {};
+  for (const f of shape) c[f] = raw[f] === undefined ? null : raw[f];
+  c.kind = kind;
+
+  if (kind === "malformed") {
+    c.originalKind = String(c.originalKind ?? "unknown");
+  } else if (kind === "transfer") {
+    c.amount = String(c.amount ?? "");
+    if (!DEC_RE.test(c.amount)) return { ok: false, reason: "malformed-amount" };
+    if (typeof c.txId !== "string" || !c.txId) return { ok: false, reason: "malformed-txid" };
+    if (typeof c.to !== "string" || !c.to) return { ok: false, reason: "malformed-to" };
+    c.txId = lcHex(c.txId); c.to = lcHex(c.to); c.from = lcHex(c.from);
+    c.asset = typeof c.asset === "string" && c.asset ? (c.asset.startsWith("erc20:") ? "erc20:" + lcHex(c.asset.slice(6)) : c.asset) : "native";
+    c.chainId = c.chainId == null ? null : Number(c.chainId);
+  } else if (kind === "fiat-settlement") {
+    c.amount = String(c.amount ?? "");
+    if (!DEC_RE.test(c.amount)) return { ok: false, reason: "malformed-amount" };
+    if (typeof c.reference !== "string" || !c.reference) return { ok: false, reason: "malformed-reference" };
+    if (typeof c.to !== "string" || !c.to) return { ok: false, reason: "malformed-to" };
+    if (typeof c.currency !== "string" || !c.currency) return { ok: false, reason: "malformed-currency" };
+  } else if (kind === "data-delivery") {
+    if (!/^[0-9a-f]{64}$/.test(String(c.contentHash ?? ""))) return { ok: false, reason: "malformed-content-hash" };
+    if (typeof c.from !== "string" || !c.from || typeof c.to !== "string" || !c.to) return { ok: false, reason: "malformed-parties" };
+  } else if (kind === "message-delivery") {
+    if (typeof c.envelopeId !== "string" || !c.envelopeId) return { ok: false, reason: "malformed-envelope-id" };
+    if (typeof c.from !== "string" || !c.from || typeof c.to !== "string" || !c.to) return { ok: false, reason: "malformed-parties" };
+  } else if (kind === "media-availability") {
+    if (typeof c.locator !== "string" || !c.locator) return { ok: false, reason: "malformed-locator" };
+    if (!/^[0-9a-f]{64}$/.test(String(c.contentHash ?? ""))) return { ok: false, reason: "malformed-content-hash" };
+  }
+  return { ok: true, claim: c };
+}
+
+/**
+ * attestationId = FULL lowercase hex sha256(jcs(claim)) (spec §2).
+ * 256-bit ids everywhere the id is a join key (quorum, binds, dedup):
+ * truncated ids are birthday-collidable and this fleet was already burned by
+ * 16-hex collisions (AAUA handles; RedTeam spec-review B1, 2026-08-26).
+ */
+export function vdaClaimId(claim) {
+  return createHash("sha256").update(jcs(claim)).digest("hex");
+}
+
+/** Display-only short form (spec §2). NEVER a join key. */
+export function shortId(attestationId) {
+  return String(attestationId ?? "").slice(0, 16);
+}
+
+/**
+ * Hash of a complete envelope INCLUDING sig — pins one exact member of a
+ * receipt (spec §7 manifest).  attestationId identifies the CLAIM; this
+ * identifies the ATTESTATION.
+ */
+export function envelopeSha256(att) {
+  return createHash("sha256").update(jcs(att ?? {})).digest("hex");
+}
+
+/** Legacy pre-VDA id (16 hex) — read-only verification of old envelopes. */
+export function legacyClaimId(claim) {
+  return createHash("sha256").update(jcs(claim)).digest("hex").slice(0, 16);
+}
+
+/**
+ * Build (and sign) a VDA-1 envelope.  `coverage` is mandatory; negatives
+ * without coverage are non-conformant (spec §5.1) and this builder refuses
+ * to produce them.
+ */
+export function buildAttestation({ claim, verdict, evidence = null, reason = null, coverage, binds = null, keychain = null, now = null }) {
+  if (!VERDICTS.includes(verdict)) throw new Error(`vda: unknown verdict ${verdict}`);
+  if (typeof coverage !== "string" || !coverage.trim()) throw new Error("vda: coverage statement required");
+  if (verdict !== "verified" && verdict !== "issuer-attested" && (typeof reason !== "string" || !reason)) {
+    throw new Error(`vda: verdict ${verdict} requires a named reason`);
+  }
+  const att = {
+    v: VDA_V, kind: ATTESTATION_KIND,
+    attestationId: vdaClaimId(claim), claim, verdict,
+    ...(evidence ? { evidence } : {}),
+    ...(reason ? { reason } : {}),
+    coverage,
+    ...(Array.isArray(binds) && binds.length ? { binds: [...binds] } : {}),
+    verifier: keychain?._identity?.uuaid ?? null,
+    verifiedAt: now ?? new Date().toISOString(),
+  };
+  if (keychain) att.sig = keychain.sign(Buffer.from(jcs(att), "utf-8")).toString("hex");
+  return att;
+}
+
+/**
+ * Offline verification of one envelope (spec §4): recompute the id from the
+ * claim AND verify the signature.  Nothing else may be required.  Accepts
+ * legacy `transfer-attestation` envelopes read-only.
+ */
+export function verifyEnvelope(publicKeyHex, att) {
+  const kindOk = att?.v === VDA_V && (att?.kind === ATTESTATION_KIND || att?.kind === LEGACY_ATTESTATION_KIND);
+  let sigOk = false;
+  try {
+    const { sig, ...rest } = att ?? {};
+    sigOk = kindOk && typeof sig === "string" &&
+      Keychain.verifyDetached(publicKeyHex, Buffer.from(jcs(rest), "utf-8"), Buffer.from(sig, "hex"));
+  } catch (_e) { sigOk = false; }
+  let idOk = false;
+  let claimOk = true;
+  if (kindOk && att?.kind === ATTESTATION_KIND) {
+    // Spec §4: the embedded claim MUST equal its own normalization — an
+    // envelope smuggling extra/renamed claim fields is non-conformant even
+    // with a valid signature (RedTeam spec-review finding 4).
+    const n = normalizeClaim(att?.claim ?? {});
+    claimOk = n.ok && jcs(n.claim) === jcs(att.claim);
+    idOk = claimOk && att?.attestationId === vdaClaimId(att.claim);
+  } else if (kindOk) {
+    idOk = att?.attestationId === legacyClaimId(att?.claim ?? {});
+  }
+  return { ok: sigOk && idOk && claimOk, sigOk, idOk, claimOk };
+}
+
+/**
+ * Composite receipt verification (spec §7), fully offline.
+ * keyResolver(verifierUuaid, verifiedAtIso) -> publicKeyHex | null.
+ * Returns { ok, verdict, members } — ok only when every member verifies,
+ * every bind resolves inside the bundle, and no member failed.
+ */
+export function verifyReceipt(receipt, keyResolver) {
+  if (receipt?.v !== VDA_V || receipt?.kind !== RECEIPT_KIND || !Array.isArray(receipt?.attestations) || receipt.attestations.length === 0) {
+    return { ok: false, verdict: "unsupported", reason: "malformed-receipt", members: [] };
+  }
+  const present = new Set(receipt.attestations.map((a) => a?.attestationId));
+  // Spec §7 manifest: a receipt DECLARES its full member set, so presenting
+  // a subset (dropping the weaker leg to inflate the composite verdict) is
+  // detectable — RedTeam spec-review finding 3.  Entries are ENVELOPE
+  // hashes, not claim ids: two verifiers attesting the same claim share an
+  // attestationId, so only the envelope hash pins exact members.  Receipts
+  // without a manifest are legacy-tolerated; conformant issuers MUST
+  // include one.
+  if (Array.isArray(receipt.manifest)) {
+    const have = receipt.attestations.map((a) => envelopeSha256(a));
+    const haveSet = new Set(have);
+    const missing = receipt.manifest.filter((h) => !haveSet.has(h));
+    const undeclared = have.filter((h) => !receipt.manifest.includes(h));
+    if (missing.length || undeclared.length) {
+      return {
+        ok: false, verdict: "failed", reason: "manifest-mismatch",
+        ...(missing.length ? { missing } : {}), ...(undeclared.length ? { undeclared } : {}),
+        members: [],
+      };
+    }
+  }
+  const members = [];
+  let verdict = "verified";
+  let ok = true;
+  for (const att of receipt.attestations) {
+    const key = typeof keyResolver === "function" ? keyResolver(att?.verifier ?? null, att?.verifiedAt ?? null) : null;
+    const env = key ? verifyEnvelope(key, att) : { ok: false, sigOk: false, idOk: att?.attestationId === vdaClaimId(att?.claim ?? {}) };
+    const badBinds = (att?.binds ?? []).filter((b) => !present.has(b));
+    const memberOk = env.ok && badBinds.length === 0;
+    members.push({
+      attestationId: att?.attestationId ?? null, verifier: att?.verifier ?? null,
+      verdict: att?.verdict ?? "unsupported", envelope: env,
+      ...(key ? {} : { keyUnresolved: true }),
+      ...(badBinds.length ? { unresolvedBinds: badBinds } : {}),
+    });
+    ok = ok && memberOk;
+    verdict = worseVerdict(verdict, memberOk ? (att?.verdict ?? "unsupported") : "failed");
+  }
+  return { ok: ok && verdict !== "failed", verdict, members };
+}
+
+/**
+ * M-of-N quorum over independent attestations of ONE claim (spec §9):
+ * agreement is set intersection on the content-addressed id.  Counts
+ * DISTINCT verifiers whose envelope verifies offline and whose verdict is
+ * `verified`.  Members with unresolvable keys or bad signatures are listed
+ * but never counted.
+ *
+ * Independence caveat (spec §9, RedTeam spec-review finding 2): distinct
+ * KEYS are what this function can verify; distinct OPERATORS/ENDPOINTS are
+ * a deployment property the consumer must judge — the report surfaces each
+ * member's verifier so that judgment is possible, and `m` is honest about
+ * being a distinct-key count, nothing stronger.  n = attestations examined.
+ */
+export function quorumReport(attestations, keyResolver, { require = 2 } = {}) {
+  const list = Array.isArray(attestations) ? attestations : [];
+  if (list.length === 0) return { ok: false, reason: "no-attestations", m: 0, n: 0, members: [] };
+  const id = list[0]?.attestationId ?? null;
+  const members = [];
+  const counted = new Set();
+  const uuaidOfKey = new Map();
+  // verdicts by verifier — VALID envelopes only, so a forged "contradiction"
+  // cannot knock an honest verifier out of the count.
+  const validVerdicts = new Map();
+  for (const att of list) {
+    const sameClaim = att?.attestationId === id && id != null;
+    const key = typeof keyResolver === "function" ? keyResolver(att?.verifier ?? null, att?.verifiedAt ?? null) : null;
+    const env = key && sameClaim ? verifyEnvelope(key, att) : { ok: false };
+    // dedupe key = the RESOLVED KEY (spec §9 "distinct keys"): two uuaids
+    // sharing one key are one voter (RedTeam round-2 rec 4)
+    if (env.ok && att?.verifier) {
+      uuaidOfKey.set(key, att.verifier);
+      const set = validVerdicts.get(key) ?? new Set();
+      set.add(att?.verdict ?? "unsupported");
+      validVerdicts.set(key, set);
+    }
+    const countable = sameClaim && env.ok === true && att?.verdict === "verified" && att?.verifier && !counted.has(key);
+    if (countable) counted.add(key);
+    members.push({
+      verifier: att?.verifier ?? null, verdict: att?.verdict ?? null,
+      counted: Boolean(countable),
+      ...(sameClaim ? {} : { reason: "claim-mismatch" }),
+      ...(key ? {} : { reason: "key-unresolved" }),
+      ...(key && sameClaim && !env.ok ? { reason: "envelope-invalid" } : {}),
+    });
+  }
+  // Equivocation (spec §11): one key VALIDLY signing contradictory verdicts
+  // for the same claim.  Excluded from the count and named — a signed
+  // contradiction is evidence about the VERIFIER.
+  const equivocatorKeys = [...validVerdicts.entries()].filter(([, s]) => s.size > 1).map(([k]) => k);
+  for (const k of equivocatorKeys) counted.delete(k);
+
+  const m = counted.size;
+  return {
+    ok: m >= require, attestationId: id, m, n: list.length, require,
+    verifiers: [...counted].map((k) => uuaidOfKey.get(k) ?? k),
+    ...(equivocatorKeys.length ? { equivocators: equivocatorKeys.map((k) => uuaidOfKey.get(k) ?? k) } : {}),
+    members,
+  };
+}

package/src/vda/directory.mjs

@@ -0,0 +1,87 @@
+/**
+ * VDA-1 verifier key directory (spec §8) — append-only records
+ * { uuaid, publicKeyHex, validFrom, revokedAt } resolved by validity window
+ * at the attestation's verifiedAt.  Content-addressed: directoryId =
+ * sha256(jcs(records)) so any two holders can compare directories by hash.
+ *
+ * Transport is out of band by design (file, pin, DHT profile); this class
+ * only enforces the RESOLUTION rules: window containment, append-only
+ * rotation, never-rewrite.
+ */
+import { createHash } from "node:crypto";
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { dirname } from "node:path";
+import { jcs } from "../identity/jcs.mjs";
+
+export class VerifierDirectory {
+  constructor(records = []) {
+    this.records = [...records];
+  }
+
+  /**
+   * Load a directory, optionally pinning its content hash.  The directory is
+   * the identity root (spec §8): an unpinned load trusts whatever file is at
+   * the path — pass expectedId (obtained out of band: a pin, a chain anchor,
+   * a config constant) to make substitution detectable (RedTeam spec-review
+   * finding 1).
+   */
+  static fromFile(path, { expectedId = null } = {}) {
+    if (!existsSync(path)) {
+      if (expectedId) throw new Error(`directory: ${path} missing but an expectedId was pinned`);
+      return new VerifierDirectory([]);
+    }
+    const doc = JSON.parse(readFileSync(path, "utf-8"));
+    const d = new VerifierDirectory(Array.isArray(doc?.records) ? doc.records : []);
+    if (expectedId && d.id() !== String(expectedId).toLowerCase()) {
+      throw new Error(`directory: content hash ${d.id()} does not match pinned ${expectedId}`);
+    }
+    return d;
+  }
+
+  toFile(path) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify({ v: 1, kind: "vda-verifier-directory", directoryId: this.id(), records: this.records }, null, 2) + "\n");
+  }
+
+  id() {
+    return createHash("sha256").update(jcs(this.records)).digest("hex");
+  }
+
+  /** Append a key record.  Rotation = append; rewriting an existing record is refused. */
+  add({ uuaid, publicKeyHex, validFrom, revokedAt = null }) {
+    if (typeof uuaid !== "string" || !uuaid) throw new Error("directory: uuaid required");
+    if (!/^[0-9a-fA-F]{64}$/.test(String(publicKeyHex ?? ""))) throw new Error("directory: publicKeyHex must be 32-byte hex");
+    if (typeof validFrom !== "string" || Number.isNaN(Date.parse(validFrom))) throw new Error("directory: validFrom must be RFC3339");
+    const dup = this.records.find((r) => r.uuaid === uuaid && r.publicKeyHex === publicKeyHex.toLowerCase() && r.validFrom === validFrom);
+    if (dup) throw new Error("directory: identical record exists (append-only; rotation adds a NEW record)");
+    this.records.push({ uuaid, publicKeyHex: publicKeyHex.toLowerCase(), validFrom, revokedAt });
+  }
+
+  /** Revoke = set revokedAt on the matching record (the one permitted mutation; never removes). */
+  revoke({ uuaid, publicKeyHex, revokedAt }) {
+    if (typeof revokedAt !== "string" || Number.isNaN(Date.parse(revokedAt))) throw new Error("directory: revokedAt must be RFC3339");
+    const rec = this.records.find((r) => r.uuaid === uuaid && r.publicKeyHex === String(publicKeyHex).toLowerCase() && r.revokedAt == null);
+    if (!rec) throw new Error("directory: no live record to revoke");
+    rec.revokedAt = revokedAt;
+  }
+
+  /**
+   * Resolve the key for (uuaid, atIso): a record whose [validFrom, revokedAt)
+   * window contains atIso.  Multiple live windows -> newest validFrom wins
+   * (rotation overlap during cutover).  Returns publicKeyHex or null.
+   */
+  resolve(uuaid, atIso) {
+    const at = Date.parse(atIso ?? "");
+    if (Number.isNaN(at)) return null;
+    const live = this.records
+      .filter((r) => r.uuaid === uuaid)
+      .filter((r) => Date.parse(r.validFrom) <= at && (r.revokedAt == null || at < Date.parse(r.revokedAt)))
+      .sort((a, b) => Date.parse(b.validFrom) - Date.parse(a.validFrom));
+    return live[0]?.publicKeyHex ?? null;
+  }
+
+  /** keyResolver closure for verifyReceipt / quorumReport. */
+  resolver() {
+    return (uuaid, atIso) => this.resolve(uuaid, atIso);
+  }
+}

package/src/vda/instruments.mjs

@@ -0,0 +1,246 @@
+/**
+ * VDA-1 instruments (spec §6) — the observation side.  One small function
+ * per domain; every path returns a full signed envelope via buildAttestation
+ * so verdict/coverage/reason discipline is enforced in one place.
+ *
+ *   transfer            -> delegated to TransferVerifier (rails; Phase 0)
+ *   data-delivery       -> recipient-signed delivery-ack (§6.2)
+ *   message-delivery    -> pillar mailbox chain-hashed logs (§6.3)
+ *   media-availability  -> fetch-and-hash probe (§6.4)
+ *   fiat-settlement     -> issuer artifact wrap, `issuer-attested` at best (§6.5)
+ */
+import { createHash } from "node:crypto";
+import { jcs } from "../identity/jcs.mjs";
+import { Keychain } from "../identity/keychain.mjs";
+import { normalizeClaim, buildAttestation } from "./core.mjs";
+
+export const ACK_KIND = "delivery-ack";
+
+/** sha256 hex of raw bytes (the contentHash every data/media claim carries). */
+export function contentHashOf(bytes) {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
+/**
+ * Recipient side: produce a signed delivery acknowledgment for received
+ * bytes.  The ack is the INSTRUMENT for data-delivery claims — hold it with
+ * the content, hand it to whoever needs to attest delivery.
+ */
+export function makeDeliveryAck({ keychain, contentHash, from, to, envelopeId = null, now = null }) {
+  if (!/^[0-9a-f]{64}$/.test(String(contentHash ?? ""))) throw new Error("delivery-ack: contentHash must be sha256 hex");
+  const ack = { v: 1, kind: ACK_KIND, contentHash, from, to, envelopeId, at: now ?? new Date().toISOString() };
+  const ackSig = keychain.sign(Buffer.from(jcs(ack), "utf-8")).toString("hex");
+  return { ack, ackSig, recipientPubKey: keychain._identity.publicKeyHex };
+}
+
+function refuse(claimRaw, reason, keychain) {
+  // Refusals still normalize what they can so the id is stable when the
+  // claim is well-formed but the instrument declines; a malformed claim is
+  // replaced by the conformant `malformed` stub (spec §4).
+  const n = normalizeClaim(claimRaw ?? {});
+  const claim = n.ok ? n.claim : normalizeClaim({ kind: "malformed", originalKind: String(claimRaw?.kind ?? "unknown") }).claim;
+  return buildAttestation({
+    claim, verdict: "unsupported", reason,
+    coverage: "Verifier refused before consulting any instrument; this attestation observes nothing about the event.",
+    keychain,
+  });
+}
+
+/**
+ * Attest a data-delivery claim from a delivery-ack (spec §6.2).
+ * Key binding honesty: recipientPubKey in the CLAIM means "the claimant
+ * asserts this key is the recipient's"; `directory` (optional) upgrades the
+ * binding by resolving `to` at ack time.  Coverage names which binding was
+ * used — a claim-supplied key proves possession of that key, not identity.
+ */
+export function attestDataDelivery({ claim: claimRaw, ack, ackSig, recipientPubKey = null, directory = null, keychain = null, binds = null }) {
+  const n = normalizeClaim({ ...claimRaw, kind: "data-delivery" });
+  if (!n.ok) return refuse(claimRaw, n.reason, keychain);
+  const claim = n.claim;
+
+  const directoryKey = directory ? directory.resolve(claim.to, ack?.at ?? null) : null;
+  const key = directoryKey ?? claim.recipientPubKey ?? recipientPubKey;
+  const binding = directoryKey ? "directory-resolved" : "claim-supplied";
+  const coverage =
+    `Instrument: recipient-signed delivery-ack under a ${binding} Ed25519 key; proves the holder of that key ` +
+    `acknowledged bytes with this contentHash — not retention, use, or (for claim-supplied keys) recipient identity.`;
+
+  if (!key) {
+    return buildAttestation({ claim, verdict: "unsupported", reason: "no-recipient-key", coverage, keychain });
+  }
+  if (ack?.kind !== ACK_KIND || ack?.v !== 1) {
+    return buildAttestation({ claim, verdict: "unsupported", reason: "malformed-ack", coverage, keychain });
+  }
+  let sigOk = false;
+  try {
+    sigOk = Keychain.verifyDetached(key, Buffer.from(jcs(ack), "utf-8"), Buffer.from(String(ackSig ?? ""), "hex"));
+  } catch (_e) { sigOk = false; }
+  if (!sigOk) {
+    return buildAttestation({ claim, verdict: "failed", reason: "ack-signature-invalid", coverage, keychain });
+  }
+  const mismatch =
+    ack.contentHash !== claim.contentHash ? "content-hash-mismatch" :
+    ack.from !== claim.from ? "from-mismatch" :
+    ack.to !== claim.to ? "to-mismatch" :
+    claim.envelopeId != null && ack.envelopeId !== claim.envelopeId ? "envelope-id-mismatch" : null;
+  if (mismatch) {
+    return buildAttestation({ claim, verdict: "failed", reason: mismatch, coverage, keychain });
+  }
+  return buildAttestation({
+    claim, verdict: "verified",
+    evidence: { ack, ackSig, recipientPubKey: key, binding },
+    coverage, keychain, binds,
+  });
+}
+
+/**
+ * Attest a message-delivery claim from a pillar Mailbox (spec §6.3).
+ * `source` picks the instrument: "inbox" (recipient's own mailbox — proves
+ * the envelope was recorded as received) or "outbox-ack" (sender's mailbox
+ * — proves the sender HOLDS a delivery acknowledgment).  Different facts;
+ * coverage names which.  The mailbox passed in must belong to the named
+ * party or the instrument is blind.
+ */
+export function attestMessageDelivery({ claim: claimRaw, mailbox, mailboxOwner, source = "inbox", keychain = null }) {
+  const n = normalizeClaim({ ...claimRaw, kind: "message-delivery" });
+  if (!n.ok) return refuse(claimRaw, n.reason, keychain);
+  const claim = n.claim;
+
+  const coverageInbox =
+    "Instrument: the RECIPIENT's chain-hashed inbox log; sees only envelopes this mailbox recorded as received. " +
+    "Proves recording at the recipient, not that the sender's copy matches.";
+  const coverageOutbox =
+    "Instrument: the SENDER's chain-hashed outbox log with delivery ack; proves the sender holds an acknowledgment, " +
+    "not what the recipient's mailbox contains.";
+
+  if (source === "inbox") {
+    if (mailboxOwner !== claim.to) {
+      return buildAttestation({
+        claim, verdict: "instrument-blind", reason: "mailbox-not-recipients",
+        coverage: coverageInbox + " This mailbox does not belong to the claimed recipient, so it is structurally blind to the claim.",
+        keychain,
+      });
+    }
+    // Full sight within the recipient's own inbox: absent = failed (§10.6 satisfied).
+    const row = mailbox.getInbound(claim.envelopeId);
+    if (!row) {
+      return buildAttestation({ claim, verdict: "failed", reason: "not-in-recipient-inbox", coverage: coverageInbox, keychain });
+    }
+    if (row.sender !== claim.from) {
+      return buildAttestation({ claim, verdict: "failed", reason: "sender-mismatch", coverage: coverageInbox, keychain });
+    }
+    if (claim.envelopeSha256 != null && row.envelope_sha256 !== claim.envelopeSha256) {
+      return buildAttestation({ claim, verdict: "failed", reason: "envelope-hash-mismatch", coverage: coverageInbox, keychain });
+    }
+    return buildAttestation({
+      claim, verdict: "verified",
+      evidence: { source: "inbox", seq: row.seq, envelopeSha256: row.envelope_sha256, chainHash: row.chain_hash, receivedAt: row.received_at },
+      coverage: coverageInbox, keychain,
+    });
+  }
+
+  if (source === "outbox-ack") {
+    if (mailboxOwner !== claim.from) {
+      return buildAttestation({
+        claim, verdict: "instrument-blind", reason: "mailbox-not-senders",
+        coverage: coverageOutbox + " This mailbox does not belong to the claimed sender, so it is structurally blind to the claim.",
+        keychain,
+      });
+    }
+    const row = mailbox.getOutbound(claim.envelopeId);
+    if (!row) {
+      return buildAttestation({ claim, verdict: "failed", reason: "not-in-sender-outbox", coverage: coverageOutbox, keychain });
+    }
+    if (row.recipient !== claim.to) {
+      return buildAttestation({ claim, verdict: "failed", reason: "recipient-mismatch", coverage: coverageOutbox, keychain });
+    }
+    if (claim.envelopeSha256 != null && row.envelope_sha256 !== claim.envelopeSha256) {
+      return buildAttestation({ claim, verdict: "failed", reason: "envelope-hash-mismatch", coverage: coverageOutbox, keychain });
+    }
+    if (row.status !== "delivered" || !row.ack_sha256) {
+      return buildAttestation({ claim, verdict: "pending", reason: "no-delivery-ack-yet", coverage: coverageOutbox, keychain });
+    }
+    return buildAttestation({
+      claim, verdict: "verified",
+      evidence: { source: "outbox-ack", seq: row.seq, envelopeSha256: row.envelope_sha256, chainHash: row.chain_hash, ackSha256: row.ack_sha256, deliveredAt: row.delivered_at },
+      coverage: coverageOutbox, keychain,
+    });
+  }
+
+  return refuse(claimRaw, `unknown-source:${String(source)}`, keychain);
+}
+
+/**
+ * Attest media availability by fetch-and-hash (spec §6.4).  Point-in-time by
+ * construction; unreachable is `pending`, only a hash mismatch of fetched
+ * bytes is `failed`.  `fetcher(locator) -> Buffer` is injectable for tests;
+ * default uses global fetch.
+ */
+export async function attestMediaAvailability({ claim: claimRaw, fetcher = null, keychain = null, maxBytes = 64 * 1024 * 1024 }) {
+  const n = normalizeClaim({ ...claimRaw, kind: "media-availability" });
+  if (!n.ok) return refuse(claimRaw, n.reason, keychain);
+  const claim = n.claim;
+  const coverage =
+    "Instrument: point-in-time fetch-and-hash of the locator; proves what the locator served AT verifiedAt to this " +
+    "verifier's vantage — not availability at any other time, place, or path.";
+
+  let bytes;
+  try {
+    if (fetcher) {
+      bytes = await fetcher(claim.locator);
+    } else {
+      const res = await fetch(claim.locator, { redirect: "follow" });
+      if (!res.ok) return buildAttestation({ claim, verdict: "pending", reason: `locator-unreachable:http-${res.status}`, coverage, keychain });
+      const buf = Buffer.from(await res.arrayBuffer());
+      bytes = buf;
+    }
+  } catch (e) {
+    return buildAttestation({ claim, verdict: "pending", reason: `locator-unreachable:${String(e?.message ?? e).slice(0, 120)}`, coverage, keychain });
+  }
+  if (!Buffer.isBuffer(bytes)) bytes = Buffer.from(bytes);
+  if (bytes.length > maxBytes) {
+    return buildAttestation({ claim, verdict: "unsupported", reason: "content-exceeds-max-bytes", coverage, keychain });
+  }
+  const observedHash = contentHashOf(bytes);
+  if (observedHash !== claim.contentHash) {
+    return buildAttestation({
+      claim, verdict: "failed", reason: "content-hash-mismatch",
+      evidence: { fetchedAt: new Date().toISOString(), byteLength: bytes.length, observedHash },
+      coverage, keychain,
+    });
+  }
+  return buildAttestation({
+    claim, verdict: "verified",
+    evidence: { fetchedAt: new Date().toISOString(), byteLength: bytes.length, observedHash },
+    coverage, keychain,
+  });
+}
+
+/**
+ * Wrap a fiat issuer artifact (spec §6.5).  `issuer-attested` at BEST, never
+ * `verified` — the verifier vouches for the artifact's presence and hash,
+ * not for settlement.  artifactBytes is hashed here so the envelope pins the
+ * exact artifact the verdict rests on.
+ */
+export function attestFiatSettlement({ claim: claimRaw, artifactBytes, artifactKind, issuer, artifactExcerpt = null, keychain = null }) {
+  const n = normalizeClaim({ ...claimRaw, kind: "fiat-settlement" });
+  if (!n.ok) return refuse(claimRaw, n.reason, keychain);
+  const claim = n.claim;
+  const coverage =
+    "Instrument: an issuer-mediated artifact; the verifier attests the artifact's presence and hash only. " +
+    "Settlement itself is asserted by the issuer, not observed by this verifier — hence issuer-attested, never verified.";
+  if (!Buffer.isBuffer(artifactBytes) || artifactBytes.length === 0) {
+    return buildAttestation({ claim, verdict: "unsupported", reason: "no-issuer-artifact", coverage, keychain });
+  }
+  if (typeof artifactKind !== "string" || !artifactKind || typeof issuer !== "string" || !issuer) {
+    return buildAttestation({ claim, verdict: "unsupported", reason: "artifact-provenance-missing", coverage, keychain });
+  }
+  return buildAttestation({
+    claim, verdict: "issuer-attested",
+    evidence: {
+      artifactSha256: contentHashOf(artifactBytes), artifactKind, issuer,
+      ...(artifactExcerpt ? { artifactExcerpt: String(artifactExcerpt).slice(0, 500) } : {}),
+    },
+    coverage, keychain,
+  });
+}