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

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

package/src/vda/shims.mjs

@@ -0,0 +1,77 @@
+/**
+ * VDA-1 adoption shims (plan Phase 5) — wrap other protocols' settlement
+ * artifacts into VDA envelopes and emit VDA ids in their native shapes.
+ * The shims TRANSLATE; they never upgrade trust: an x402 settlement wraps
+ * into a `transfer` claim verified against the CHAIN (same instrument as
+ * any transfer), and an A2A artifact / MCP tool result carries the
+ * attestation, not a re-statement of it.
+ */
+import { normalizeClaim } from "./core.mjs";
+
+/**
+ * Map an x402 payment-settlement (HTTP 402 flow) onto a VDA transfer claim.
+ * x402 settles on-chain; its receipt fields name network, tx hash, payer,
+ * payee, asset, amount.  The output is a CLAIM — verification still runs
+ * through TransferVerifier against the chain, so the shim adds zero trust.
+ *
+ * settlement: { network: "eip155:<chainId>"|<chainId>, txHash, payer?,
+ *               payee, amount, asset? ("native" | erc20 address) }
+ */
+export function claimFromX402(settlement) {
+  const s = settlement ?? {};
+  let chainId = null;
+  if (typeof s.network === "string" && s.network.startsWith("eip155:")) chainId = Number(s.network.slice(7));
+  else if (s.network != null && !Number.isNaN(Number(s.network))) chainId = Number(s.network);
+  const asset = s.asset == null || s.asset === "native" ? "native"
+    : String(s.asset).startsWith("erc20:") ? String(s.asset) : `erc20:${String(s.asset)}`;
+  const n = normalizeClaim({
+    kind: "transfer", rail: "evm", chainId,
+    txId: s.txHash ?? s.txId ?? null,
+    from: s.payer ?? null, to: s.payee ?? null,
+    amount: s.amount != null ? String(s.amount) : null,
+    asset,
+  });
+  if (!n.ok) return { ok: false, reason: `x402-unmappable:${n.reason}` };
+  return { ok: true, claim: n.claim };
+}
+
+/**
+ * Emit an attestation as an A2A task artifact (A2A artifacts are named parts
+ * with data payloads).  The artifact carries the FULL envelope so any A2A
+ * client can verify offline; the name carries the content-addressed id.
+ */
+export function a2aArtifactOfAttestation(att) {
+  if (att?.kind !== "vda-attestation") throw new Error("a2a shim: not a vda-attestation");
+  return {
+    artifactId: `vda-${att.attestationId}`,
+    name: `vda-attestation:${att.attestationId}`,
+    description: `VDA-1 ${att.claim?.kind} attestation, verdict=${att.verdict}, verifier=${att.verifier ?? "unsigned"}`,
+    parts: [{ kind: "data", data: att }],
+  };
+}
+
+/**
+ * MCP tool descriptor for a server exposing VDA verification.  The handler
+ * wiring is host-specific; this is the portable contract (name, schema,
+ * annotations) so any MCP host can demand receipts the same way.
+ */
+export const MCP_VERIFY_TOOL = {
+  name: "vda_verify_transfer",
+  description:
+    "Verify that a transfer (native or ERC-20) actually settled on-chain, from the chain's own record. " +
+    "Returns a signed, content-addressed VDA-1 attestation verifiable offline. " +
+    "Verdicts: verified | failed | pending | instrument-blind | unsupported (fail-closed).",
+  inputSchema: {
+    type: "object",
+    required: ["chainId", "txId", "to", "amount"],
+    properties: {
+      chainId: { type: "integer", description: "EVM chain id (e.g. 137)" },
+      txId: { type: "string", description: "transaction hash" },
+      from: { type: "string", description: "expected sender (optional)" },
+      to: { type: "string", description: "expected recipient" },
+      amount: { type: "string", description: "decimal base units (wei) — string, never a number" },
+      asset: { type: "string", description: '"native" or "erc20:<tokenAddress>"' },
+    },
+  },
+  annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+};