@agenticstechnologies/verify 0.0.0-stage → 1.0.0

package/src/cleared.mjs

@@ -0,0 +1,120 @@
+// Cleared-text leaf check. Shared by the evidence export, the proof bundle,
+// and the server (lib/gateway/proof.ts passes its own leafHash).
+//
+// Retention and deletion null free text and set text_cleared_at. They do not
+// rewrite receipt_hash. The older leaf (hash_version null, 2, or 3) covers
+// `outcome`, so a straight recompute misses after that column is null.
+//
+// When text_cleared_at is set:
+//   * Cleared fields are not put back. The stored hash is their commitment.
+//   * Older leaves: try the historical outcome labels in memory. A match means
+//     every field that was not cleared still agrees with the stored hash.
+//     The label that matched is not returned.
+//   * Version 4: reason, target, outcome, and error_message were inside the
+//     leaf. uncleared_digest, sealed when the text was cleared, is the hash of
+//     the leaf with those keys removed. Without that digest the leaf fails.
+//     An older outcome that is not in the historical list uses the same kind
+//     of digest, with outcome removed. Chain linkage is the caller's check.
+//
+// A receipt with no text_cleared_at still has to recompute exactly.
+
+export const LEGACY_OUTCOMES = Object.freeze([
+  "success",
+  "failed",
+  "partial",
+  "blocked",
+  "escalated",
+  "timeout",
+  "settled",
+  "attempted",
+  "circuit_open",
+  "fallback",
+  "retried",
+  "deployed",
+  "not_deployed",
+  "ok",
+  "clean",
+  "reversed",
+  "pending",
+  "human_override",
+  "escalation_needed",
+]);
+
+const HEX64 = /^[0-9a-f]{64}$/;
+const V4_CLEARED = ["reason", "target", "outcome", "error_message"];
+
+function hex64(value) {
+  const text = String(value ?? "").trim().toLowerCase();
+  return HEX64.test(text) ? text : "";
+}
+
+/**
+ * @param {Record<string, unknown>} canonical
+ * @param {string} storedHash
+ * @param {(canonical: Record<string, unknown>) => Promise<string>} leafHash
+ * @param {readonly string[]} [extraOutcomes]
+ */
+export async function legacyClearedMatches(canonical, storedHash, leafHash, extraOutcomes) {
+  const claimed = hex64(storedHash);
+  if (!claimed) return false;
+  const base = { ...(canonical || {}) };
+  delete base.text_cleared_at;
+  delete base.uncleared_digest;
+  const seen = new Set();
+  const list = extraOutcomes ? [...LEGACY_OUTCOMES, ...extraOutcomes] : LEGACY_OUTCOMES;
+  for (const outcome of list) {
+    if (typeof outcome !== "string") continue;
+    const label = outcome.trim();
+    if (!label || seen.has(label)) continue;
+    seen.add(label);
+    if (await leafHash({ ...base, outcome: label }) === claimed) return true;
+  }
+  return false;
+}
+
+/**
+ * Direct recompute, then the cleared-text rule.
+ * `meta.text_cleared_at` is the sibling flag. It is not part of the leaf.
+ *
+ * @param {Record<string, unknown>} canonical
+ * @param {string} storedHash
+ * @param {(canonical: Record<string, unknown>) => Promise<string>} leafHash
+ * @param {{ text_cleared_at?: unknown, hash_version?: unknown, uncleared_digest?: unknown, status?: unknown }} [meta]
+ */
+export async function clearedLeafMatches(canonical, storedHash, leafHash, meta) {
+  const raw = String(storedHash ?? "");
+  const claimed = hex64(raw);
+  let recomputed = "";
+  try {
+    recomputed = await leafHash(canonical || {});
+  } catch {
+    recomputed = "";
+  }
+  if (recomputed && (recomputed === raw || recomputed === claimed)) return true;
+  const cleared = meta?.text_cleared_at || canonical?.text_cleared_at;
+  if (!cleared) return false;
+  const version = Number(meta?.hash_version ?? canonical?.hash_version);
+  if (version === 4) {
+    if (!claimed) return false;
+    const digest = hex64(meta?.uncleared_digest || canonical?.uncleared_digest);
+    if (!digest) return false;
+    const body = { ...(canonical || {}) };
+    delete body.receipt_id;
+    delete body.batch_id;
+    delete body.text_cleared_at;
+    delete body.uncleared_digest;
+    for (const key of V4_CLEARED) delete body[key];
+    const partial = await leafHash(body);
+    return partial === digest;
+  }
+  const extra = [];
+  if (typeof meta?.status === "string" && meta.status.trim()) extra.push(meta.status.trim());
+  if (await legacyClearedMatches(canonical, claimed, leafHash, extra)) return true;
+  const digest = hex64(meta?.uncleared_digest || canonical?.uncleared_digest);
+  if (!digest) return false;
+  const body = { ...(canonical || {}) };
+  delete body.text_cleared_at;
+  delete body.uncleared_digest;
+  delete body.outcome;
+  return (await leafHash(body)) === digest;
+}

package/src/evidence.mjs

@@ -0,0 +1,112 @@
+// Leaf and prev_hash checks for GET /api/proof/export JSON.
+// Moved from scripts/verify-evidence.mjs so the package and that script share
+// one implementation. Behavior is unchanged:
+//   sha256Hex(JSON.stringify(canonicalize(canonical minus {receipt_id, batch_id})))
+// canonicalize sorts object keys recursively and drops null and undefined.
+// After the first row, prev_hash must equal the previous receipt_hash.
+// The first prev_hash must be 64 hex characters (genesis, or a receipt older
+// than the export window). A truncated export is not a pass.
+// When text_cleared_at is set, the stored hash covers the cleared fields
+// and every field that was not cleared is still checked.
+
+import { clearedLeafMatches } from "./cleared.mjs";
+
+export function canonicalize(v) {
+  if (v === null || v === undefined) return undefined;
+  if (Array.isArray(v)) return v.map(canonicalize);
+  if (typeof v === "object") {
+    const out = {};
+    for (const k of Object.keys(v).sort()) {
+      const cv = canonicalize(v[k]);
+      if (cv !== undefined) out[k] = cv;
+    }
+    return out;
+  }
+  return v;
+}
+
+export async function sha256Hex(input) {
+  const data = typeof input === "string" ? new TextEncoder().encode(input) : input;
+  const buf = await crypto.subtle.digest("SHA-256", data);
+  return [...new Uint8Array(buf)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+export async function leafHash(canonical) {
+  const rest = { ...canonical };
+  delete rest.receipt_id;
+  delete rest.batch_id;
+  return sha256Hex(JSON.stringify(canonicalize(rest)));
+}
+
+export { clearedLeafMatches };
+
+/**
+ * @param {unknown} bundle
+ * @returns {Promise<{ ok: boolean, checked: number, failures: Array<{ receipt_hash: string, prev_hash: string, hash_ok: boolean, chain_ok: boolean, reason: string }> }>}
+ */
+export async function verifyEvidenceExport(bundle) {
+  const receipts = bundle && Array.isArray(bundle.receipts) ? bundle.receipts : null;
+  if (!receipts) {
+    return {
+      ok: false,
+      checked: 0,
+      failures: [{
+        receipt_hash: "",
+        prev_hash: "",
+        hash_ok: false,
+        chain_ok: false,
+        reason: "bundle.receipts is missing",
+      }],
+    };
+  }
+  const failures = [];
+  for (let i = 0; i < receipts.length; i++) {
+    const row = receipts[i] ?? {};
+    const canonical = row.canonical ?? {};
+    const claimed = String(row.receipt_hash ?? "");
+    const prev = String(canonical.prev_hash ?? "");
+    let recomputed = "";
+    try {
+      recomputed = await leafHash(canonical);
+    } catch {
+      recomputed = "";
+    }
+    const hashOk = recomputed === claimed || await clearedLeafMatches(canonical, claimed, leafHash, {
+      text_cleared_at: row.text_cleared_at,
+      hash_version: row.hash_version,
+      uncleared_digest: row.uncleared_digest,
+      status: row.status,
+    });
+    let chainOk = true;
+    let reason = null;
+    if (!hashOk) reason = `leaf recomputed ${recomputed} != ${claimed}`;
+    if (i === 0) {
+      if (!/^[0-9a-f]{64}$/.test(prev)) {
+        chainOk = false;
+        reason = reason ?? "prev_hash is not 64 hex characters";
+      }
+    } else if (prev !== String(receipts[i - 1].receipt_hash ?? "")) {
+      chainOk = false;
+      reason = reason ?? "prev_hash does not match the previous receipt_hash";
+    }
+    if (!hashOk || !chainOk) {
+      failures.push({
+        receipt_hash: claimed,
+        prev_hash: prev,
+        hash_ok: hashOk,
+        chain_ok: chainOk,
+        reason: reason ?? "failed",
+      });
+    }
+  }
+  if (bundle.verification && bundle.verification.truncated === true) {
+    failures.push({
+      receipt_hash: "",
+      prev_hash: "",
+      hash_ok: false,
+      chain_ok: false,
+      reason: "export was truncated; refuse to call it complete",
+    });
+  }
+  return { ok: failures.length === 0, checked: receipts.length, failures };
+}

package/src/index.d.ts

@@ -0,0 +1,32 @@
+export function canonicalize(value: unknown): unknown;
+export function sha256Hex(input: string): Promise<string>;
+export function leafHash(canonical: unknown): Promise<string>;
+export function verifyEvidenceExport(bundle: unknown): Promise<unknown>;
+
+export function merkleRoot(leaves: string[]): Promise<string | null>;
+export function merkleProof(leaves: string[], index: number): Promise<string[] | null>;
+export function verifyProof(leaf: string, proof: string[] | null | undefined, root: string): Promise<boolean>;
+
+/** Tree rule v2 (RFC 9162 2.1). Batches name their rule in tree_rule; absent is v1. */
+export const TREE_RULE_V1: "v1";
+export const TREE_RULE_V2: "v2";
+export function treeRuleOf(value: unknown): "v1" | "v2" | null;
+export function leafHashV2(leaf: string): Promise<string>;
+export function merkleRootV2(leaves: string[]): Promise<string | null>;
+export function merkleProofV2(leaves: string[], index: number): Promise<string[] | null>;
+export function verifyProofV2(leaf: string, index: number, size: number, proof: string[] | null | undefined, root: string): Promise<boolean>;
+
+export function verifyBundle(bundle: unknown, opts?: Record<string, unknown>): Promise<unknown>;
+
+export function agentRecord(events: unknown, asOf?: string): unknown;
+export function recordBundle(input: { handle: string; as_of?: string; outcomes: unknown }): unknown;
+export function signRecord(privateJwk: Record<string, unknown>, bundle: unknown): Promise<unknown>;
+export function verifyRecord(bundle: unknown, jwks: unknown): Promise<unknown>;
+export function isRecordBundle(bundle: unknown): boolean;
+
+export function classifyCluster(
+  hint: string | null | undefined,
+  explorer?: string | null | undefined,
+): "devnet" | "testnet" | "mainnet" | null;
+export function checkSolanaMemo(opts: Record<string, unknown>): Promise<unknown>;
+export const PUBLIC_RPC: { readonly devnet: string; readonly testnet: string };

package/src/index.mjs

@@ -0,0 +1,8 @@
+export { canonicalize, sha256Hex, leafHash, verifyEvidenceExport } from "./evidence.mjs";
+export {
+  merkleRoot, merkleProof, verifyProof,
+  TREE_RULE_V1, TREE_RULE_V2, treeRuleOf, leafHashV2, merkleRootV2, merkleProofV2, verifyProofV2,
+} from "./merkle.mjs";
+export { verifyBundle } from "./bundle.mjs";
+export { agentRecord, recordBundle, signRecord, verifyRecord, isRecordBundle } from "./record.mjs";
+export { classifyCluster, checkSolanaMemo, PUBLIC_RPC } from "./solana.mjs";

package/src/merkle.mjs

@@ -0,0 +1,150 @@
+// Sorted-pair Merkle, same fold as netlify/edge-functions/lib/ledger.js
+// (imported by lib/gateway/proof.ts for buildBatch / foldLeafAtIndex):
+//   hashPair(a, b) = sha256Hex(a <= b ? a + b : b + a)
+//   odd node duplicated; empty leaf list → null (tree rule v1; v2 is at the end of this file)
+// A proof is only the sibling list. Pair order does not depend on index.
+
+import { sha256Hex } from "./evidence.mjs";
+
+async function hashPair(a, b) {
+  return sha256Hex(a <= b ? a + b : b + a);
+}
+
+export async function merkleRoot(leaves) {
+  if (!leaves || !leaves.length) return null;
+  let level = leaves.slice();
+  while (level.length > 1) {
+    const next = [];
+    for (let i = 0; i < level.length; i += 2) {
+      next.push(await hashPair(level[i], level[i + 1] ?? level[i]));
+    }
+    level = next;
+  }
+  return level[0];
+}
+
+export async function merkleProof(leaves, index) {
+  if (index < 0 || index >= leaves.length) return null;
+  const proof = [];
+  let level = leaves.slice();
+  let idx = index;
+  while (level.length > 1) {
+    const next = [];
+    for (let i = 0; i < level.length; i += 2) {
+      const left = level[i];
+      const right = level[i + 1] ?? level[i];
+      if (i === idx) proof.push(right);
+      else if (i + 1 === idx) proof.push(left);
+      next.push(await hashPair(left, right));
+    }
+    level = next;
+    idx = Math.floor(idx / 2);
+  }
+  return proof;
+}
+
+export async function verifyProof(leafHash, proof, root) {
+  let h = leafHash;
+  for (const sibling of proof || []) h = await hashPair(h, sibling);
+  return h === root;
+}
+
+// ── Tree rule v2 (L3-16): RFC 9162 section 2.1 (RFC 6962), over the 32 bytes of each hex leaf. ──
+//   leaf = SHA-256(0x00 || leaf bytes), node = SHA-256(0x01 || left || right), in position order.
+//   An odd last node is promoted unchanged (never paired with itself); empty → null; one leaf → its leaf hash.
+// A v2 proof is the RFC audit path; folding it needs the leaf index and the tree size. Batches anchored under v1
+// stay v1 for ever (anchor_batches.tree_rule): a verifier picks the fold by rule and never re-folds an old batch.
+export const TREE_RULE_V1 = "v1";
+export const TREE_RULE_V2 = "v2";
+
+function hexBytes(hex) {
+  if (typeof hex !== "string" || !/^[0-9a-f]{64}$/.test(hex)) throw new Error("merkle v2: a node must be 64 lowercase hex characters");
+  const out = new Uint8Array(32);
+  for (let i = 0; i < 32; i++) out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  return out;
+}
+
+async function prefixedHash(prefix, ...parts) {
+  const buf = new Uint8Array(1 + parts.length * 32);
+  buf[0] = prefix;
+  parts.forEach((p, i) => buf.set(p, 1 + i * 32));
+  return new Uint8Array(await crypto.subtle.digest("SHA-256", buf));
+}
+
+const bytesHex = (b) => [...b].map((x) => x.toString(16).padStart(2, "0")).join("");
+
+/** v2 leaf hash of a 64-hex leaf: SHA-256(0x00 || bytes), as hex. */
+export async function leafHashV2(leaf) {
+  return bytesHex(await prefixedHash(0x00, hexBytes(leaf)));
+}
+
+async function levelsV2(leaves) {
+  let level = [];
+  for (const l of leaves) level.push(await prefixedHash(0x00, hexBytes(l)));
+  const levels = [level];
+  while (level.length > 1) {
+    const next = [];
+    for (let i = 0; i + 1 < level.length; i += 2) next.push(await prefixedHash(0x01, level[i], level[i + 1]));
+    if (level.length % 2 === 1) next.push(level[level.length - 1]);
+    level = next;
+    levels.push(level);
+  }
+  return levels;
+}
+
+export async function merkleRootV2(leaves) {
+  if (!leaves || !leaves.length) return null;
+  const levels = await levelsV2(leaves);
+  return bytesHex(levels[levels.length - 1][0]);
+}
+
+/** The RFC audit path for the leaf at `index`, leaf to root, as hex. */
+export async function merkleProofV2(leaves, index) {
+  if (!leaves || !Number.isInteger(index) || index < 0 || index >= leaves.length) return null;
+  const levels = await levelsV2(leaves);
+  const path = [];
+  let idx = index;
+  for (const level of levels.slice(0, -1)) {
+    const sib = idx ^ 1;
+    if (sib < level.length) path.push(bytesHex(level[sib]));
+    idx >>= 1;
+  }
+  return path;
+}
+
+/** RFC 9162 2.1.3.2: fold `proof` from leaf `index` of a tree of `size` leaves and compare with `root`. */
+export async function verifyProofV2(leaf, index, size, proof, root) {
+  try {
+    if (!Number.isInteger(index) || !Number.isInteger(size) || index < 0 || index >= size) return false;
+    let fn = index;
+    let sn = size - 1;
+    let r = await prefixedHash(0x00, hexBytes(leaf));
+    for (const hex of proof || []) {
+      const p = hexBytes(hex);
+      if (sn === 0) return false;
+      if ((fn & 1) === 1 || fn === sn) {
+        r = await prefixedHash(0x01, p, r);
+        if ((fn & 1) === 0) {
+          while ((fn & 1) === 0 && fn !== 0) {
+            fn >>= 1;
+            sn >>= 1;
+          }
+        }
+      } else {
+        r = await prefixedHash(0x01, r, p);
+      }
+      fn >>= 1;
+      sn >>= 1;
+    }
+    return sn === 0 && bytesHex(r) === root;
+  } catch {
+    return false;
+  }
+}
+
+/** The fold a batch's rule names. Unknown rules are refused, never folded as v1. */
+export function treeRuleOf(value) {
+  if (value === undefined || value === null || value === "" || value === TREE_RULE_V1) return TREE_RULE_V1;
+  if (value === TREE_RULE_V2) return TREE_RULE_V2;
+  return null;
+}