verifyhash 0.1.0 → 0.1.2

package/verifier/dist/verify-vh-standalone.js.sha256

@@ -0,0 +1 @@
+6de719e11e3885c733aca329a10e4d25f0dff1e5f24d85934a43b3f766d4c0b0  verify-vh-standalone.js

package/verifier/lib/canonical.js

@@ -0,0 +1,141 @@
+"use strict";
+
+// verifier/lib/canonical.js — INDEPENDENT canonical UNSIGNED serialization.
+//
+// WHY THIS EXISTS
+//   For the independent `verifier/` to sign/hash over BYTE-IDENTICAL input to the production path, it must
+//   reproduce the family's canonical UNSIGNED serialization itself — WITHOUT importing the producer code in
+//   `cli/`. If the verifier imported `cli/dataset.js`'s `serializeAttestation`, a cross-check would be
+//   circular (it would be comparing a function to itself). So this file re-derives the SAME byte string,
+//   from first principles, and the cross-check test asserts it equals what the producer emits.
+//
+// THE CANONICAL CONVENTION (must match cli/core/attestation.js + cli/dataset.js#serializeAttestation)
+//   * A FIXED key order — NOT JSON.stringify's insertion order by accident, but an EXPLICIT ordered key
+//     list per object shape. We emit keys in that exact order.
+//   * NO insignificant whitespace (separators ",", ":").
+//   * A SINGLE trailing newline ("\n") terminating the document.
+//   The result is byte-deterministic: the same logical value always serializes to the same bytes.
+
+/**
+ * Serialize a value to canonical JSON with an EXPLICIT key order, no insignificant whitespace, and NO
+ * trailing newline (the newline is the document-level convention added by the envelope serializers below).
+ *
+ * Key order: when `keyOrder[<path-or-shape>]` is provided we use it; otherwise keys are emitted in the
+ * object's own insertion order (matching the producer's explicit object literals, which V8 preserves).
+ * Because the producers always build their canonical objects via explicit ordered literals, reproducing
+ * that same ordered literal here yields byte-identical output WITHOUT a generic key-sorting pass.
+ *
+ * This is a minimal, dependency-free JSON emitter that matches JSON.stringify's escaping for the value
+ * shapes this family uses (strings, integers, booleans, null, nested objects/arrays).
+ *
+ * @param {*} value
+ * @returns {string} canonical JSON (no trailing newline)
+ */
+function canonicalJson(value) {
+  // JSON.stringify with no spacing already emits ","/":" separators and standard string escaping with no
+  // insignificant whitespace. The ONLY thing it does not do for us is reorder keys — but the family's
+  // canonical objects are built as explicit ordered literals, so insertion order IS the canonical order.
+  // We therefore use JSON.stringify directly on a value whose keys are already in canonical order. This is
+  // intentionally the SAME primitive the producer uses, but driven from an INDEPENDENTLY constructed,
+  // explicitly-ordered object here (so the bytes are reproduced, not imported).
+  return JSON.stringify(value);
+}
+
+/**
+ * Reproduce the canonical UNSIGNED dataset-attestation bytes, byte-for-byte identical to
+ * `cli/dataset.js#serializeAttestation` — WITHOUT importing it.
+ *
+ * Canonical top-level key order (from the producer's explicit object literal):
+ *   kind, schemaVersion, note, root, fileCount, manifestDigest, signed, signature
+ * then a single trailing newline.
+ *
+ * @param {object} env a validated UNSIGNED attestation envelope
+ * @returns {string} the canonical serialization (newline-terminated)
+ */
+function serializeUnsignedDatasetAttestation(env) {
+  if (env == null || typeof env !== "object" || Array.isArray(env)) {
+    throw new Error("serializeUnsignedDatasetAttestation requires an attestation envelope object");
+  }
+  // Build the canonical object via an EXPLICIT ordered literal — independently of the producer.
+  const canonical = {
+    kind: env.kind,
+    schemaVersion: env.schemaVersion,
+    note: env.note,
+    root: env.root,
+    fileCount: env.fileCount,
+    manifestDigest: env.manifestDigest,
+    signed: env.signed,
+    signature: env.signature,
+  };
+  return canonicalJson(canonical) + "\n";
+}
+
+/**
+ * Generic canonical envelope serializer for the family's signed-attestation containers, reproducing
+ * `cli/core/attestation.js#serializeSignedAttestation` byte-for-byte WITHOUT importing it.
+ *
+ * Canonical key order: kind, schemaVersion, note, attestation, signature{scheme,signer,signature}
+ * then a single trailing newline.
+ *
+ * @param {object} container a signed-attestation container
+ * @returns {string} the canonical serialization (newline-terminated)
+ */
+function serializeSignedContainer(container) {
+  if (container == null || typeof container !== "object" || Array.isArray(container)) {
+    throw new Error("serializeSignedContainer requires a signed-attestation container object");
+  }
+  const sig = container.signature || {};
+  const canonical = {
+    kind: container.kind,
+    schemaVersion: container.schemaVersion,
+    note: container.note,
+    attestation: container.attestation,
+    signature: {
+      scheme: sig.scheme,
+      signer: sig.signer,
+      signature: sig.signature,
+    },
+  };
+  return canonicalJson(canonical) + "\n";
+}
+
+// The reserved relPath of the synthetic HEADER leaf a reconciliation seal binds its verdict + input
+// role partition into, byte-identical to trustledger/seal.js#SEAL_HEADER_RELPATH. A real file may not
+// occupy it; the verifier folds the header content in under this relPath when re-deriving the root.
+const TRUST_SEAL_HEADER_RELPATH = "__trustledger.seal-header__v1";
+
+/**
+ * Reproduce the canonical "content" bytes of a reconciliation seal's verdict/role HEADER entry, byte-for-
+ * byte identical to trustledger/seal.js#_headerBytes — WITHOUT importing it. The header binds the recorded
+ * verdict (pass/reportDate/period) + each input's logical role→relPath into the SAME committed Merkle
+ * root as the files, so a verdict/role edit changes the header content -> its leaf -> the root.
+ *
+ * Canonical layout (FIXED key order, no insignificant whitespace, roles sorted by role):
+ *   { v: 1, verdict: { pass, reportDate, period }, roles: [{ role, relPath }, ...] }
+ *
+ * @param {object} verdict { pass, reportDate, period }
+ * @param {{role:string, relPath:string}[]} inputs the seal's input role bindings
+ * @returns {Buffer} the canonical UTF-8 header content
+ */
+function trustSealHeaderBytes(verdict, inputs) {
+  const canonical = {
+    v: 1,
+    verdict: {
+      pass: verdict.pass,
+      reportDate: verdict.reportDate,
+      period: verdict.period == null ? null : String(verdict.period),
+    },
+    roles: inputs
+      .map((i) => ({ role: i.role, relPath: i.relPath }))
+      .sort((a, b) => (a.role < b.role ? -1 : a.role > b.role ? 1 : 0)),
+  };
+  return Buffer.from(JSON.stringify(canonical), "utf8");
+}
+
+module.exports = {
+  canonicalJson,
+  serializeUnsignedDatasetAttestation,
+  serializeSignedContainer,
+  TRUST_SEAL_HEADER_RELPATH,
+  trustSealHeaderBytes,
+};

package/verifier/lib/keccak.js

@@ -0,0 +1,30 @@
+"use strict";
+
+// verifier/lib/keccak.js — the keccak256 used by the INDEPENDENT verifier core.
+//
+// WHY A SHIM (and not a re-implementation)
+//   The whole point of `verifier/` is to be an INDEPENDENT re-derivation of the family's crypto that can
+//   be CROSS-CHECKED against the production (ethers) path, so the two can never silently diverge. keccak256
+//   is a fixed, standardized permutation; re-rolling it by hand would add risk, not independence. So we
+//   take it from `js-sha3` — an audited, dependency-free implementation that is ALREADY a direct dependency
+//   of this project (package.json), and is the SAME primitive ethers itself uses under the hood. The
+//   independence that matters for the anti-divergence guard is the EIP-191 framing + secp256k1 recovery +
+//   canonical serialization, all of which `verifier/` implements WITHOUT ethers/hardhat. This file has NO
+//   dependency on `cli/` or `trustledger/`.
+
+const { keccak256: keccakHex } = require("js-sha3");
+
+/**
+ * keccak256 over a byte buffer, returning a 32-byte Buffer.
+ * @param {Buffer|Uint8Array} bytes
+ * @returns {Buffer} the 32-byte digest
+ */
+function keccak256(bytes) {
+  if (!(bytes instanceof Uint8Array) && !Buffer.isBuffer(bytes)) {
+    throw new TypeError("keccak256 requires a Buffer/Uint8Array of input bytes");
+  }
+  // js-sha3's keccak256 accepts a byte array and returns a lowercase hex string (no 0x).
+  return Buffer.from(keccakHex.create().update(bytes).hex(), "hex");
+}
+
+module.exports = { keccak256 };

package/verifier/lib/keccak256-vendored.js

@@ -0,0 +1,206 @@
+"use strict";
+
+// verifier/lib/keccak256-vendored.js — a PURE-JS, ZERO-DEPENDENCY keccak256 (T-35.1).
+//
+// WHY THIS FILE EXISTS
+//   The whole point of the free verifier is "save ONE file, run it with `node`, no `npm install`, audit it
+//   in one sitting." The in-tree verifier core takes keccak256 from `js-sha3` (verifier/lib/keccak.js) — an
+//   audited, dependency-free package that is already a project dependency — which is correct for the
+//   IN-TREE path. But `js-sha3` is still a RUNTIME dependency: a third party handed a single sealed packet
+//   would have to `npm install` it. This module is the LAST piece needed to inline the verifier into one
+//   self-contained file: a from-scratch keccak256 that `require`s NOTHING (no `js-sha3`, no Node core, no
+//   relative module). It is ADDITIVE — keccak.js and verifier/package.json's `dependencies: ["js-sha3"]`
+//   are deliberately left UNCHANGED so the existing tree + isolation test stay green.
+//
+// CORRECTNESS, NOT NOVELTY
+//   keccak256 is the FIXED, standardized Keccak[c=512] sponge over the Keccak-f[1600] permutation with the
+//   ORIGINAL Keccak padding (a single 0x01 domain byte, NOT SHA3's 0x06) and a 256-bit squeeze — exactly
+//   what Ethereum/ethers and `js-sha3.keccak256` compute. This is a textbook implementation of FIPS-202's
+//   Keccak-f (theta, rho, pi, chi, iota) done with 32-bit lane halves (lo/hi) so it runs on plain JS numbers
+//   with no BigInt and no 64-bit-int dependency. test/verifier.keccak-vendored.test.js proves byte-identical
+//   output vs BOTH `js-sha3` AND the production `ethers` keccak path across the empty input, the known
+//   vectors, and ≥500 random buffers — a single mismatch FAILS. So this is independent CODE but never an
+//   independent ALGORITHM: it cannot silently diverge from the standard.
+//
+// REQUIRES NOTHING: a grep of this source finds no CommonJS require call and no bare-name import.
+// (Intentional — this property is asserted by test/verifier.keccak-vendored.test.js.)
+
+// ---- Keccak-f[1600] round constants, split into 32-bit (hi, lo) halves --------------------------------
+// The 24 RC[i] are the canonical Keccak iota constants; here each 64-bit constant is pre-split so we never
+// need a 64-bit integer type. RC_HI[i] is bits 63..32, RC_LO[i] is bits 31..0.
+const RC_HI = [
+  0x00000000, 0x00000000, 0x80000000, 0x80000000, 0x00000000, 0x00000000, 0x80000000, 0x80000000,
+  0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x80000000, 0x80000000, 0x80000000,
+  0x80000000, 0x80000000, 0x00000000, 0x80000000, 0x80000000, 0x80000000, 0x00000000, 0x80000000,
+];
+const RC_LO = [
+  0x00000001, 0x00008082, 0x0000808a, 0x80008000, 0x0000808b, 0x80000001, 0x80008081, 0x00008009,
+  0x0000008a, 0x00000088, 0x80008009, 0x8000000a, 0x8000808b, 0x0000008b, 0x00008089, 0x00008003,
+  0x00008002, 0x00000080, 0x0000800a, 0x8000000a, 0x80008081, 0x00008080, 0x80000001, 0x80008008,
+];
+
+// Rotation offsets r[x,y] for the rho step, indexed by lane number (x + 5*y). Lane 0 is never rotated.
+const RHO = [
+  0, 1, 62, 28, 27, 36, 44, 6, 55, 20, 3, 10, 43, 25, 39, 41, 45, 15, 21, 8, 18, 2, 61, 56, 14,
+];
+// pi permutation: destination lane for each source lane. pi maps (x,y) -> (y, 2x+3y), so source lane
+// (x + 5y) is written to lane (y + 5*((2x+3y) mod 5)); PI[src] = dst.
+const PI = [
+  0, 10, 20, 5, 15, 16, 1, 11, 21, 6, 7, 17, 2, 12, 22, 23, 8, 18, 3, 13, 14, 24, 9, 19, 4,
+];
+
+// The state is 25 lanes; we hold each lane as two 32-bit halves in parallel arrays sLo/sHi (index = lane).
+
+// Keccak-f[1600] permutation, in place, on (sLo, sHi). 24 rounds of theta, rho+pi, chi, iota.
+function keccakF(sLo, sHi) {
+  const bcLo = new Array(5);
+  const bcHi = new Array(5);
+  const tLo = new Array(25);
+  const tHi = new Array(25);
+
+  for (let round = 0; round < 24; round++) {
+    // --- theta ---
+    for (let x = 0; x < 5; x++) {
+      bcLo[x] = sLo[x] ^ sLo[x + 5] ^ sLo[x + 10] ^ sLo[x + 15] ^ sLo[x + 20];
+      bcHi[x] = sHi[x] ^ sHi[x + 5] ^ sHi[x + 10] ^ sHi[x + 15] ^ sHi[x + 20];
+    }
+    for (let x = 0; x < 5; x++) {
+      // d = bc[x-1] XOR rotl1(bc[x+1])
+      const x1 = (x + 1) % 5;
+      const x4 = (x + 4) % 5;
+      const rotLo = ((bcLo[x1] << 1) | (bcHi[x1] >>> 31)) >>> 0;
+      const rotHi = ((bcHi[x1] << 1) | (bcLo[x1] >>> 31)) >>> 0;
+      const dLo = (bcLo[x4] ^ rotLo) >>> 0;
+      const dHi = (bcHi[x4] ^ rotHi) >>> 0;
+      for (let y = 0; y < 25; y += 5) {
+        sLo[x + y] = (sLo[x + y] ^ dLo) >>> 0;
+        sHi[x + y] = (sHi[x + y] ^ dHi) >>> 0;
+      }
+    }
+
+    // --- rho + pi --- (write permuted, rotated lanes into t)
+    for (let i = 0; i < 25; i++) {
+      const r = RHO[i];
+      const dest = PI[i];
+      let outLo, outHi;
+      if (r === 0) {
+        outLo = sLo[i];
+        outHi = sHi[i];
+      } else if (r < 32) {
+        outLo = ((sLo[i] << r) | (sHi[i] >>> (32 - r))) >>> 0;
+        outHi = ((sHi[i] << r) | (sLo[i] >>> (32 - r))) >>> 0;
+      } else if (r === 32) {
+        outLo = sHi[i];
+        outHi = sLo[i];
+      } else {
+        const rr = r - 32;
+        outLo = ((sHi[i] << rr) | (sLo[i] >>> (32 - rr))) >>> 0;
+        outHi = ((sLo[i] << rr) | (sHi[i] >>> (32 - rr))) >>> 0;
+      }
+      tLo[dest] = outLo;
+      tHi[dest] = outHi;
+    }
+
+    // --- chi --- a[x] = t[x] XOR ((NOT t[x+1]) AND t[x+2]), per row
+    for (let y = 0; y < 25; y += 5) {
+      for (let x = 0; x < 5; x++) {
+        const x1 = y + ((x + 1) % 5);
+        const x2 = y + ((x + 2) % 5);
+        sLo[y + x] = (tLo[y + x] ^ (~tLo[x1] & tLo[x2])) >>> 0;
+        sHi[y + x] = (tHi[y + x] ^ (~tHi[x1] & tHi[x2])) >>> 0;
+      }
+    }
+
+    // --- iota ---
+    sLo[0] = (sLo[0] ^ RC_LO[round]) >>> 0;
+    sHi[0] = (sHi[0] ^ RC_HI[round]) >>> 0;
+  }
+}
+
+// keccak256 over `bytes` (a Uint8Array/Buffer or array of byte values), returning a 32-byte Uint8Array.
+// Rate r = 1088 bits = 136 bytes (c = 512), original Keccak padding (0x01 .. 0x80), 256-bit output.
+function keccak256Bytes(bytes) {
+  const RATE = 136; // bytes absorbed per permutation
+  const sLo = new Array(25).fill(0);
+  const sHi = new Array(25).fill(0);
+
+  // Build the padded message: append a single 0x01 domain/pad start byte, zero-fill, set the high bit
+  // (0x80) of the final rate block. (If the 0x01 lands on the last byte of a block, it merges to 0x81.)
+  const inLen = bytes.length;
+  const padLen = RATE - (inLen % RATE); // 1..RATE, guarantees room for the 0x01 and 0x80 markers
+  const total = inLen + padLen;
+  const msg = new Uint8Array(total);
+  for (let i = 0; i < inLen; i++) msg[i] = bytes[i] & 0xff;
+  msg[inLen] = 0x01; // start of the original-Keccak pad (NOT SHA3's 0x06)
+  msg[total - 1] = (msg[total - 1] | 0x80) & 0xff; // final-block high bit
+
+  // Absorb: XOR each RATE-byte block into the state (little-endian lanes) and permute.
+  for (let off = 0; off < total; off += RATE) {
+    for (let i = 0; i < RATE; i += 8) {
+      const lane = i >> 3; // lane index within the rate region (0..16), block-relative
+      const b = off + i;
+      const lo =
+        ((msg[b] | (msg[b + 1] << 8) | (msg[b + 2] << 16) | (msg[b + 3] << 24)) >>> 0);
+      const hi =
+        ((msg[b + 4] | (msg[b + 5] << 8) | (msg[b + 6] << 16) | (msg[b + 7] << 24)) >>> 0);
+      sLo[lane] = (sLo[lane] ^ lo) >>> 0;
+      sHi[lane] = (sHi[lane] ^ hi) >>> 0;
+    }
+    keccakF(sLo, sHi);
+  }
+
+  // Squeeze 256 bits = 32 bytes = the first 4 lanes (little-endian), no further permutation needed.
+  const out = new Uint8Array(32);
+  for (let lane = 0; lane < 4; lane++) {
+    const lo = sLo[lane];
+    const hi = sHi[lane];
+    const base = lane * 8;
+    out[base] = lo & 0xff;
+    out[base + 1] = (lo >>> 8) & 0xff;
+    out[base + 2] = (lo >>> 16) & 0xff;
+    out[base + 3] = (lo >>> 24) & 0xff;
+    out[base + 4] = hi & 0xff;
+    out[base + 5] = (hi >>> 8) & 0xff;
+    out[base + 6] = (hi >>> 16) & 0xff;
+    out[base + 7] = (hi >>> 24) & 0xff;
+  }
+  return out;
+}
+
+// Lowercase hex (no 0x prefix) of a byte array — used by the hex-string entry point.
+function toHex(bytes) {
+  let s = "";
+  for (let i = 0; i < bytes.length; i++) {
+    const b = bytes[i] & 0xff;
+    s += (b < 16 ? "0" : "") + b.toString(16);
+  }
+  return s;
+}
+
+/**
+ * keccak256 over a byte buffer.
+ * @param {Uint8Array|Buffer|number[]} bytes input bytes
+ * @returns {Uint8Array} the 32-byte digest
+ */
+function keccak256(bytes) {
+  if (
+    !(bytes instanceof Uint8Array) &&
+    !Array.isArray(bytes) &&
+    !(typeof Buffer !== "undefined" && Buffer.isBuffer && Buffer.isBuffer(bytes))
+  ) {
+    throw new TypeError("keccak256 requires a Uint8Array/Buffer/byte-array of input bytes");
+  }
+  return keccak256Bytes(bytes);
+}
+
+/**
+ * keccak256 over a byte buffer, returned as a lowercase hex string WITHOUT a 0x prefix
+ * (matching `js-sha3`'s keccak256().hex() output, for drop-in cross-checking).
+ * @param {Uint8Array|Buffer|number[]} bytes input bytes
+ * @returns {string} 64-char lowercase hex
+ */
+function keccak256Hex(bytes) {
+  return toHex(keccak256(bytes));
+}
+
+module.exports = { keccak256, keccak256Hex };

package/verifier/lib/merkle.js

@@ -0,0 +1,145 @@
+"use strict";
+
+// verifier/lib/merkle.js — INDEPENDENT re-derivation of the family's path-bound, domain-separated
+// Merkle convention, using ONLY ./keccak (js-sha3). NO ethers, NO hardhat, NO require back into cli/.
+//
+// WHY THIS EXISTS
+//   To verify an evidence seal / reconciliation seal / proof bundle OFFLINE without the producer stack,
+//   the independent verifier must RE-DERIVE the same per-file leaves and the same Merkle root the
+//   producer (cli/hash.js) computes. cli/hash.js uses `ethers` (keccak256/concat/toUtf8Bytes), which the
+//   verifier explicitly refuses to depend on. So this file reproduces the EXACT byte composition of
+//   pathLeaf / leafHash / nodeHash / buildTree from first principles — and test/verifier.cli.test.js
+//   cross-checks the result is byte-identical to the producer's. The two can never silently diverge.
+//
+// THE CONVENTION (must match cli/hash.js VERBATIM)
+//   * content digest      c          = keccak256(file bytes)
+//   * DIR_LEAF_DOMAIN      = keccak256("verifyhash/dir-leaf/v1")  (a fixed 32-byte prefix)
+//   * path-bound leaf      pathLeaf   = keccak256(DIR_LEAF_DOMAIN ++ utf8(relPath) ++ 0x00 ++ c)
+//   * tagged leaf          leafHash   = keccak256(0x00 ++ leaf)
+//   * interior node        nodeHash   = keccak256(0x01 ++ min(a,b) ++ max(a,b))   (sorted 32-byte pair)
+//   * tree                 sorted-leaf, "duplicate the lone odd node" pairing (OpenZeppelin style)
+//   relPath is normalized with no leading "./", exactly as the producer's toPosixRel does. CRUCIALLY
+//   this must be BYTE-FOR-BYTE the producer's normalization (cli/hash.js#toPosixRel) — see toPosixRel
+//   below — or the verifier would re-derive a DIFFERENT root than the producer sealed for some input
+//   class and would either falsely reject a genuine artifact or falsely accept the wrong one.
+
+const { keccak256 } = require("./keccak");
+
+// Domain tags, byte-identical to ContributionRegistry / cli/hash.js LEAF_TAG / NODE_TAG.
+const LEAF_TAG = Buffer.from([0x00]);
+const NODE_TAG = Buffer.from([0x01]);
+const PATH_SEP = Buffer.from([0x00]);
+
+// The fixed, versioned domain prefix for path-bound directory leaves: keccak256 of the ASCII tag.
+const DIR_LEAF_DOMAIN_STR = "verifyhash/dir-leaf/v1";
+const DIR_LEAF_DOMAIN = keccak256(Buffer.from(DIR_LEAF_DOMAIN_STR, "utf8")); // 32-byte Buffer
+
+const HEX32_RE = /^0x[0-9a-fA-F]{64}$/;
+
+// 0x-hex string (no 0x, lowercase) <-> 32-byte Buffer.
+function hexToBuf32(hex) {
+  if (typeof hex !== "string" || !HEX32_RE.test(hex)) {
+    throw new Error(`expected a 0x-prefixed 32-byte hex string, got: ${String(hex)}`);
+  }
+  return Buffer.from(hex.slice(2), "hex");
+}
+function bufToHex(buf) {
+  return "0x" + Buffer.from(buf).toString("hex");
+}
+
+/** keccak256 of raw bytes, returned as a 0x-prefixed 32-byte hex string (matches cli/hash.js hashBytes). */
+function hashBytes(bytes) {
+  const buf = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes);
+  return bufToHex(keccak256(buf));
+}
+
+/**
+ * Normalize a relPath EXACTLY as the producer (cli/hash.js#toPosixRel) does, so the verifier
+ * re-derives the IDENTICAL root the producer sealed. The producer is `split(path.sep).join("/")`
+ * then `.replace(/^\.\//, "")`. The artifacts the verifier reads carry relPaths the producer wrote,
+ * and those are produced on POSIX hosts (cli/evidence.js#loadDirEntries does the same `path.sep`
+ * split) — where `path.sep === "/"`, so the split/join is a no-op and a literal backslash byte is a
+ * CONTENT byte that survives into the hash. We therefore must NOT collapse backslashes: a previous
+ * version unconditionally mapped "\\"->"/", which made the verifier hash `a/b.txt` while the producer
+ * hashed `a\b.txt` — a silent root divergence that could falsely REJECT a genuine backslash-named
+ * directory or falsely ACCEPT one where `a/b.txt` and `a\b.txt` collide. All we strip is the leading
+ * "./", which the producer also strips on every host. (Windows-authored relPaths, if ever needed,
+ * must be converted to "/" on BOTH the producer and verifier sides identically — not only here.)
+ */
+function toPosixRel(relPath) {
+  return String(relPath).replace(/^\.\//, "");
+}
+
+/**
+ * pathLeaf(relPath, contentDigest) = keccak256(DIR_LEAF_DOMAIN ++ utf8(relPath) ++ 0x00 ++ c).
+ * @param {string} relPath
+ * @param {string} contentDigest 0x bytes32
+ * @returns {string} 0x bytes32
+ */
+function pathLeaf(relPath, contentDigest) {
+  const relBytes = Buffer.from(toPosixRel(relPath), "utf8");
+  const c = hexToBuf32(contentDigest);
+  return bufToHex(keccak256(Buffer.concat([DIR_LEAF_DOMAIN, relBytes, PATH_SEP, c])));
+}
+
+/** leafHash(c) = keccak256(LEAF_TAG ++ c). */
+function leafHash(c) {
+  return bufToHex(keccak256(Buffer.concat([LEAF_TAG, hexToBuf32(c)])));
+}
+
+/** nodeHash(a,b) = keccak256(NODE_TAG ++ min(a,b) ++ max(a,b)) comparing as 32-byte big-endian values. */
+function nodeHash(a, b) {
+  const A = hexToBuf32(a);
+  const B = hexToBuf32(b);
+  const [lo, hi] = Buffer.compare(A, B) <= 0 ? [A, B] : [B, A];
+  return bufToHex(keccak256(Buffer.concat([NODE_TAG, lo, hi])));
+}
+
+/**
+ * Build the sorted-leaf, domain-separated Merkle root from an array of per-file PATH-BOUND leaves
+ * (the same values pathLeaf produces). Leaves are sorted ascending by their 32-byte value, tagged via
+ * leafHash, then folded with nodeHash, pairing a lone odd node with itself — byte-identical to
+ * cli/hash.js buildTree's root.
+ * @param {string[]} leaves array of 0x bytes32 path-bound leaves
+ * @returns {string} the 0x bytes32 root
+ */
+function rootFromLeaves(leaves) {
+  if (!Array.isArray(leaves) || leaves.length === 0) {
+    throw new Error("cannot build a Merkle tree from zero leaves");
+  }
+  const sorted = leaves
+    .slice()
+    .sort((a, b) => Buffer.compare(hexToBuf32(a), hexToBuf32(b)));
+  let layer = sorted.map((c) => leafHash(c));
+  while (layer.length > 1) {
+    const next = [];
+    for (let i = 0; i < layer.length; i += 2) {
+      const right = i + 1 < layer.length ? layer[i + 1] : layer[i];
+      next.push(nodeHash(layer[i], right));
+    }
+    layer = next;
+  }
+  return layer[0];
+}
+
+/**
+ * Re-derive the top-level root from a flat list of { relPath, contentHash } — the SAME computation the
+ * seal cores use: pathLeaf each, then rootFromLeaves. PURE.
+ * @param {{relPath:string, contentHash:string}[]} flat
+ * @returns {string} 0x bytes32 root
+ */
+function rootFromFlat(flat) {
+  return rootFromLeaves(flat.map((e) => pathLeaf(e.relPath, e.contentHash)));
+}
+
+module.exports = {
+  HEX32_RE,
+  DIR_LEAF_DOMAIN_STR,
+  hashBytes,
+  toPosixRel,
+  pathLeaf,
+  leafHash,
+  nodeHash,
+  rootFromLeaves,
+  rootFromFlat,
+};