@uuaid/pillar 0.2.0-alpha.11 → 0.2.0-alpha.13

package/src/pillar.mjs

@@ -22,6 +22,7 @@ import { createTransport, PILLAR_PROTOCOL, uuaidToDhtKey, peerIdFromEd25519Hex }
 import { seal, open, decrypt, envelopeSha, ENVELOPE_VERSION } from "./net/envelope.mjs";
 import { Mailbox } from "./mailbox/mailbox.mjs";
 import { CarrierClient } from "./net/carrier-client.mjs";
+import { Observability } from "./observability.mjs";
 
 const VALUE_STORE_PREFIX = "/uuaid/1.0";
 
@@ -39,6 +40,7 @@ export class Pillar {
     cryptoInventory = { ed25519: "active", "ml-dsa-65": "reserved", "slh-dsa-128s": "reserved" },
     trust = null, // { policy, allow, block } from loadTrustPolicy(); null = open
     tierGrant = null, // signed grant object (tier.mjs) sent with carrier delivers
+    metrics = null, // Observability instance; a default is created internally
   }) {
     if (!keychain?._identity) throw new Error("Pillar: keychain must be loaded before construction");
     this.keychain = keychain;
@@ -55,6 +57,7 @@ export class Pillar {
     this.cryptoInventory = cryptoInventory;
     this.node = null;
     this.trust = trust;
+    this.metrics = metrics ?? new Observability();
     this._envelopeHandlers = new Set();
     this._openStreams = new Map(); // peerIdString -> pushable
   }
@@ -238,7 +241,11 @@ export class Pillar {
    * once at fleet-up time.
    */
   async send({ recipient, recipientPublicKey, kind = "message", payload = {}, resolveTimeoutMs = 5000 }) {
-    if (!this.node && !this.carrierClient) throw new Error("pillar not started");
+    if (!this.node && !this.carrierClient) {
+      this.metrics.inc("send.error.not-started");
+      throw new Error("pillar not started");
+    }
+    const t0 = Date.now();
 
     const book = this.addressBook?.get(recipient);
 
@@ -254,6 +261,7 @@ export class Pillar {
       } catch (_e) { /* fall through to the error below */ }
     }
     if (!pubkey) {
+      this.metrics.inc("send.error.no-public-key");
       throw new Error(`send: no public key known for ${recipient} — encryption is mandatory; register the peer (address book / fleet.json) or pass recipientPublicKey`);
     }
 
@@ -263,9 +271,15 @@ export class Pillar {
     // 1. Address book path: direct libp2p dial (lowest latency, no third party).
     if (this.node && book?.peerId && book?.multiaddr) {
       try {
-        return { envelope, persisted, via: "direct", delivery: await this._deliverToPeer(envelope, book.peerId, book.multiaddr) };
+        const delivery = await this._deliverToPeer(envelope, book.peerId, book.multiaddr);
+        this.metrics.inc("send.via.direct");
+        this.metrics.observe("send.latencyMs.via.direct", Date.now() - t0);
+        return { envelope, persisted, via: "direct", delivery };
       } catch (e) {
-        if (!this.carrierClient) throw e; // else fall through to carrier
+        if (!this.carrierClient) {
+          this.metrics.inc("send.error.direct-delivery-failed");
+          throw e;
+        } // else fall through to carrier
       }
     }
 
@@ -273,16 +287,27 @@ export class Pillar {
     if (this.carrierClient) {
       const receipt = await this.carrierClient.deliver(envelope);
       this.mailbox.markOutboundDelivered(envelope.id, envelopeSha(envelope));
+      this.metrics.inc("send.via.carrier");
+      this.metrics.observe("send.latencyMs.via.carrier", Date.now() - t0);
       return { envelope, persisted, via: "carrier", delivery: receipt };
     }
 
     // 3. DHT path.
-    if (!this.node) throw new Error(`send: cannot resolve ${recipient}: no carrier configured and libp2p not started`);
+    if (!this.node) {
+      this.metrics.inc("send.error.no-route");
+      throw new Error(`send: cannot resolve ${recipient}: no carrier configured and libp2p not started`);
+    }
     if (!dhtAdvert) {
       try { dhtAdvert = await this.resolveUuaid(recipient, { timeoutMs: resolveTimeoutMs }); }
-      catch (e) { throw new Error(`send: cannot resolve ${recipient}: ${e.message}`); }
+      catch (e) {
+        this.metrics.inc("send.error.resolve-failed");
+        throw new Error(`send: cannot resolve ${recipient}: ${e.message}`);
+      }
     }
-    return { envelope, persisted, via: "dht", delivery: await this._deliverToPeer(envelope, dhtAdvert.peerId, dhtAdvert.addrs?.[0]) };
+    const delivery = await this._deliverToPeer(envelope, dhtAdvert.peerId, dhtAdvert.addrs?.[0]);
+    this.metrics.inc("send.via.dht");
+    this.metrics.observe("send.latencyMs.via.dht", Date.now() - t0);
+    return { envelope, persisted, via: "dht", delivery };
   }
 
   /**
@@ -312,6 +337,9 @@ export class Pillar {
         results.push({ member, ok: false, error: e.message });
       }
     }
+    this.metrics.inc("sendGroup");
+    const failed = results.filter((r) => !r.ok).length;
+    if (failed) this.metrics.inc("sendGroup.failed", failed);
     return { group, results };
   }
 
@@ -331,8 +359,11 @@ export class Pillar {
       onEnvelope: async (envelope, { carrier, seq }) => {
         await this._receive(JSON.stringify(envelope), null);
         this.mailbox.setCarrierCursor?.(carrier, seq);
+        this.metrics.inc(`carrier.poll.${carrier}`);
+      },
+      onError: (_e, meta) => {
+        this.metrics.inc(`carrier.poll.error.${meta?.carrier ?? "unknown"}`);
       },
-      onError: (_e) => { /* transient poll errors are expected; backoff is in client */ },
     });
     return this._carrierPoller;
   }
@@ -361,6 +392,7 @@ export class Pillar {
           this.mailbox.setCarrierCursor?.(base, seq);
           since = Math.max(since, seq);
           total++;
+          this.metrics.inc(`carrier.drain.${base}`);
         }
       }
     }
@@ -454,15 +486,20 @@ export class Pillar {
   async _receive(rawLine, connection) {
     let envelope;
     try { envelope = JSON.parse(rawLine); }
-    catch (_e) { return; }
+    catch (_e) {
+      this.metrics.inc("received.unparsable");
+      return;
+    }
     const verdict = open(envelope, { cryptoInventory: this.cryptoInventory });
     if (!verdict.ok) {
+      this.metrics.inc(`received.rejected.${verdict.reason}`);
       // eslint-disable-next-line no-console
       console.warn("pillar: rejected envelope from", connection?.remotePeer?.toString(), verdict.reason);
       return;
     }
     if (envelope.recipient !== this.uuaid) {
       // Not for us.  Store-and-forward would go here in v0.3.
+      this.metrics.inc("received.wrong-recipient");
       return;
     }
     // E2E: decrypt the sealed payload.  Ciphertext-at-rest: the mailbox stores
@@ -471,12 +508,17 @@ export class Pillar {
     try {
       payload = decrypt(this.keychain, envelope);
     } catch (e) {
+      this.metrics.inc("received.decrypt-failed");
       // eslint-disable-next-line no-console
       console.warn("pillar: envelope decrypt failed (dropping)", envelope.id, e.message);
       return;
     }
     const persisted = this.mailbox.appendInbound(envelope);
-    if (persisted.duplicate) return; // replay: do not re-fire handlers
+    if (persisted.duplicate) {
+      this.metrics.inc("received.duplicate");
+      return; // replay: do not re-fire handlers
+    }
+    this.metrics.inc(`received.kind.${envelope.kind}`);
     // Trust gate (recipient consent): quarantine-not-drop. The envelope is
     // already persisted (chain-hashed evidence); a gated sender just never
     // reaches handlers. An ack/reply passes the gate ONLY if its inReplyTo
@@ -491,6 +533,7 @@ export class Pillar {
         const verdict = evaluateTrust(this.trust, envelope.sender, known);
         if (!verdict.deliver) {
           this.mailbox.markQuarantined(envelope.id, verdict.reason);
+          this.metrics.inc(`received.quarantined.${verdict.reason}`);
           // eslint-disable-next-line no-console
           console.warn(`pillar: quarantined ${envelope.id} from ${envelope.sender} (${verdict.reason})`);
           return;
@@ -500,7 +543,10 @@ export class Pillar {
     const view = { ...envelope, payload };
     for (const h of this._envelopeHandlers) {
       try { await h(view, persisted); }
-      catch (e) { console.error("pillar: envelope handler threw", e); }
+      catch (e) {
+        this.metrics.inc("received.handler-error");
+        console.error("pillar: envelope handler threw", e);
+      }
     }
   }
 }

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