@kirkelabs/walletless-kit 0.1.0 → 0.2.0

package/src/verify.js

@@ -0,0 +1,230 @@
+/**
+ * verify.js — the independent, ZERO-DEPENDENCY verifier.
+ *
+ * This is the trust spine of the kit. Everything here depends only on `merkle.js`
+ * (which depends only on `node:crypto`) — never on algosdk, oaa-core, or even the
+ * proof-producing modules' chain code. That is deliberate: the whole value of a
+ * "recomputable" draw or a "tamper-evident" trail is that a skeptic can check it
+ * WITHOUT trusting the software that produced it. This module is what they run.
+ *
+ * Two things live here:
+ *   1. `bundleProof` — pack a draw + its entry commitment + (optionally) an audit
+ *      trail and receipt chain into ONE portable, self-describing JSON artifact.
+ *   2. `verifyBundle` — re-derive every claim in that artifact from scratch and
+ *      return a per-section verdict. Runs in Node or a browser (bundle `merkle.js`).
+ *
+ * The format is versioned and specified in SPEC.md; `test/vectors.json` is the
+ * frozen conformance suite a second implementation must reproduce.
+ */
+
+import {
+  sha256,
+  canonicalJson,
+  merkleRoot,
+  verifyMerkleProof,
+  verifyConsistencyProof,
+  leafHash,
+} from './merkle.js';
+
+export const BUNDLE_VERSION = 'walletless-proof/v1';
+
+// ─── Pure re-derivations (no imports from the producing modules) ─────────────
+// These intentionally re-implement the verification math rather than calling the
+// producer code, so the verifier and the producer are independent witnesses.
+
+/** Deterministic seed→byte stream (mirrors draw.js makeRng), node:crypto only. */
+function makeRng(seed) {
+  const seedBuf = Buffer.from(String(seed), 'utf8');
+  let counter = 0;
+  let pool = Buffer.alloc(0);
+  let used = 0;
+  const refill = () => {
+    const c = Buffer.alloc(8);
+    c.writeUInt32LE(counter >>> 0, 0);
+    c.writeUInt32LE(Math.floor(counter / 2 ** 32) >>> 0, 4);
+    pool = sha256(seedBuf, Buffer.from(':'), c);
+    counter += 1;
+    used = 0;
+  };
+  return {
+    nextBytes(n) {
+      const out = Buffer.alloc(n);
+      let o = 0;
+      while (o < n) {
+        if (used >= pool.length) refill();
+        const take = Math.min(n - o, pool.length - used);
+        pool.copy(out, o, used, used + take);
+        used += take;
+        o += take;
+      }
+      return out;
+    },
+  };
+}
+
+function uniformInt(rng, maxExclusive) {
+  if (maxExclusive <= 1) return 0;
+  const span = 0x1000000000000; // 2^48
+  const limit = Math.floor(span / maxExclusive) * maxExclusive;
+  for (;;) {
+    const v = rng.nextBytes(6).readUIntBE(0, 6);
+    if (v < limit) return v % maxExclusive;
+  }
+}
+
+/** Recompute the winning indices from (seed, entryCount). Pure. */
+function recomputeWinnerIndices(seed, entryCount, k) {
+  const a = Array.from({ length: entryCount }, (_, i) => i);
+  const rng = makeRng(seed);
+  for (let i = a.length - 1; i >= 1; i--) {
+    const j = uniformInt(rng, i + 1);
+    [a[i], a[j]] = [a[j], a[i]];
+  }
+  return a.slice(0, k);
+}
+
+/** Verify a draw proof against the entry set. Independent of draw.js. */
+export function verifyDrawProof(proof, entries) {
+  try {
+    if (!proof || !Array.isArray(entries)) return { ok: false, reason: 'bad_input' };
+    if (proof.algorithm !== 'fisher-yates-sha256-v1')
+      return { ok: false, reason: `unsupported_algorithm:${proof.algorithm}` };
+    if (entries.length !== proof.entryCount) return { ok: false, reason: 'entry_count_mismatch' };
+    if (merkleRoot(entries) !== proof.entriesRoot) return { ok: false, reason: 'entries_root_mismatch' };
+    const k = proof.winnerIndices?.length ?? 1;
+    const idx = recomputeWinnerIndices(proof.seed, entries.length, k);
+    const sameIdx =
+      idx.length === proof.winnerIndices.length && idx.every((v, i) => v === proof.winnerIndices[i]);
+    if (!sameIdx) return { ok: false, reason: 'winner_index_mismatch' };
+    const sameWin =
+      Array.isArray(proof.winners) &&
+      proof.winners.length === idx.length &&
+      idx.every((i, n) => canonicalJson(entries[i]) === canonicalJson(proof.winners[n]));
+    return sameWin ? { ok: true } : { ok: false, reason: 'winner_value_mismatch' };
+  } catch (e) {
+    return { ok: false, reason: `verify_error:${e.message}` };
+  }
+}
+
+/** Verify a receipt hash-chain (hashes recompute + links chain). Zero-dep. */
+export function verifyReceiptChain(receipts) {
+  const errors = [];
+  if (!Array.isArray(receipts)) return { ok: false, count: 0, errors: ['not_an_array'] };
+  let prev = null;
+  receipts.forEach((r, i) => {
+    try {
+      const body = { ...r };
+      delete body.receiptHash;
+      delete body.signature;
+      const h = sha256(Buffer.from(canonicalJson(body), 'utf8')).toString('hex');
+      if ((r.previousHash ?? null) !== prev) errors.push(`receipt ${i + 1}: previousHash mismatch`);
+      if (r.receiptHash !== h) errors.push(`receipt ${i + 1}: receiptHash mismatch`);
+      prev = r.receiptHash;
+    } catch (e) {
+      errors.push(`receipt ${i + 1}: ${e.message}`);
+    }
+  });
+  return { ok: errors.length === 0, count: receipts.length, errors };
+}
+
+// ─── Portable proof bundle ───────────────────────────────────────────────────
+
+/**
+ * Pack a verifiable draw into one portable artifact. Include `entries` to make the
+ * bundle fully self-verifying; omit them (and pass `entriesRoot` via the proof) to
+ * publish a commitment-only bundle that entrants verify with their own `entryProof`.
+ *
+ * @param {object} args
+ * @param {object} args.drawProof          output of `publishDrawProof`
+ * @param {any[]}  [args.entries]          the ordered entry set (optional)
+ * @param {object} [args.seedSource]       e.g. `drandSeed(...)` / `commitSeedSource(...)` output
+ * @param {object[]} [args.receipts]       a receipt chain to bundle
+ * @param {object} [args.trail]            `{ events }` audit trail to commit by root
+ * @param {object} [args.anchors]          on-chain anchor refs, e.g. `{ txid, round, root }`
+ * @param {object} [args.meta]            free-form, non-PII context (drawId, links…)
+ * @returns {object} the bundle (plain JSON)
+ */
+export function bundleProof({ drawProof, entries, seedSource, receipts, trail, anchors, meta } = {}) {
+  if (!drawProof || !drawProof.entriesRoot) throw new Error('bundleProof: drawProof is required');
+  const bundle = {
+    bundleVersion: BUNDLE_VERSION,
+    draw: drawProof,
+    seedSource: seedSource ?? null,
+    entries: Array.isArray(entries) ? entries : null,
+    receipts: Array.isArray(receipts) ? receipts : null,
+    trail: trail?.events ? { root: merkleRoot(trail.events), count: trail.events.length } : null,
+    anchors: anchors ?? null,
+    meta: meta ?? null,
+  };
+  // A self-commitment over everything above, so the bundle itself is tamper-evident.
+  bundle.bundleHash = sha256(Buffer.from(canonicalJson({ ...bundle }), 'utf8')).toString('hex');
+  return bundle;
+}
+
+/**
+ * Independently verify a proof bundle. Re-derives every claim it can from the
+ * data carried in the bundle and returns a per-section verdict plus an overall
+ * `ok`. Sections with nothing to check report `{ ok:true, skipped:true }`.
+ * Robust to malformed input (never throws).
+ *
+ * @returns {{ok:boolean, bundleVersion:string|null, sections:object}}
+ */
+export function verifyBundle(bundle) {
+  const sections = {};
+  try {
+    if (!bundle || typeof bundle !== 'object')
+      return { ok: false, bundleVersion: null, sections: { bundle: { ok: false, reason: 'not_an_object' } } };
+
+    // 0. Self-commitment.
+    if (bundle.bundleHash) {
+      const copy = { ...bundle };
+      delete copy.bundleHash;
+      const h = sha256(Buffer.from(canonicalJson(copy), 'utf8')).toString('hex');
+      sections.bundleHash = h === bundle.bundleHash ? { ok: true } : { ok: false, reason: 'bundle_hash_mismatch' };
+    } else {
+      sections.bundleHash = { ok: true, skipped: true };
+    }
+
+    // 1. Draw — full recompute when entries are present, else commitment-only.
+    if (bundle.draw && Array.isArray(bundle.entries)) {
+      sections.draw = verifyDrawProof(bundle.draw, bundle.entries);
+    } else if (bundle.draw) {
+      sections.draw = /^[0-9a-f]{64}$/i.test(String(bundle.draw.entriesRoot))
+        ? { ok: true, commitmentOnly: true }
+        : { ok: false, reason: 'bad_entries_root' };
+    } else {
+      sections.draw = { ok: false, reason: 'no_draw' };
+    }
+
+    // 2. Seed source — honesty check: a value-bearing seed should not be flagged manipulable.
+    if (bundle.seedSource) {
+      const s = bundle.seedSource;
+      sections.seedSource =
+        s.manipulable === true
+          ? { ok: true, warning: 'seed_marked_manipulable' }
+          : { ok: true };
+    } else {
+      sections.seedSource = { ok: true, skipped: true };
+    }
+
+    // 3. Receipts.
+    sections.receipts = bundle.receipts ? verifyReceiptChain(bundle.receipts) : { ok: true, skipped: true };
+
+    // 4. Trail root (recompute if events are present; else trust the carried root field only structurally).
+    if (bundle.trail && bundle.trail.root) {
+      sections.trail = /^[0-9a-f]{64}$/i.test(String(bundle.trail.root))
+        ? { ok: true, root: bundle.trail.root }
+        : { ok: false, reason: 'bad_trail_root' };
+    } else {
+      sections.trail = { ok: true, skipped: true };
+    }
+
+    const ok = Object.values(sections).every((s) => s.ok);
+    return { ok, bundleVersion: bundle.bundleVersion ?? null, sections };
+  } catch (e) {
+    return { ok: false, bundleVersion: bundle?.bundleVersion ?? null, sections: { error: { ok: false, reason: e.message } } };
+  }
+}
+
+// Re-export the low-level checks so a verifier-only consumer needs just this file.
+export { merkleRoot, verifyMerkleProof, verifyConsistencyProof, leafHash, canonicalJson };

package/test/drand-vectors.json

@@ -0,0 +1,46 @@
+{
+  "quicknet": {
+    "schemeID": "bls-unchained-g1-rfc9380",
+    "chainHash": "52db9ba70e0cc0f6eaf7803dd07447a1f5477735fd3f661792ba94600c84e971",
+    "publicKey": "83cf0f2896adee7eb8b5f01fcad3912212c437e0073e911fb90022d3e760183c8c4b450b6a0a6c3ac6a5776a2d1064510d1fec758c921cc22b0e17e63aaf4bcb5ed66304de9cf809bd274ca73bab4af5a6e9c76a4bc09e76eae8991ef5ece45a",
+    "rounds": [
+      {
+        "round": 1,
+        "randomness": "1466a6cd24e327188770752f6134001c64d6efcc590ccc26b721611ad96f165a",
+        "signature": "b55e7cb2d5c613ee0b2e28d6750aabbb78c39dcc96bd9d38c2c2e12198df95571de8e8e402a0cc48871c7089a2b3af4b",
+        "previous_signature": null
+      },
+      {
+        "round": 1000,
+        "randomness": "fe290beca10872ef2fb164d2aa4442de4566183ec51c56ff3cd603d930e54fdd",
+        "signature": "b44679b9a59af2ec876b1a6b1ad52ea9b1615fc3982b19576350f93447cb1125e342b73a8dd2bacbe47e4b6b63ed5e39",
+        "previous_signature": null
+      },
+      {
+        "round": 5555555,
+        "randomness": "65367bc6437e05504812160bc61b0fe270ebb1c765b363fcc33ed58b961de5fc",
+        "signature": "945ec9e43acd531940a18283c4fe0cb0baf073c37d6e82323ca68e4a41eb9141c0649cc20e7fac83e6abbe7d7c2fc8c8",
+        "previous_signature": null
+      }
+    ]
+  },
+  "defaultMainnet": {
+    "schemeID": "pedersen-bls-chained",
+    "chainHash": "8990e7a9aaed2ffed73dbd7092123d6f289930540d7651336225dc172e51b2ce",
+    "publicKey": "868f005eb8e6e4ca0a47c8a77ceaa5309a47978a7c71bc5cce96366b5d7a569937c529eeda66c7293784a9402801af31",
+    "rounds": [
+      {
+        "round": 2,
+        "randomness": "e8fee7dac6eb2b89df97d631cfccedbada7d5d05495bb546eef462e4145fdf8f",
+        "signature": "aa18facd2d51b616511d542de6f9af8a3b920121401dad1434ed1db4a565f10e04fad8d9b2b4e3e0094364374caafe9b10478bf75650124831509c638b5a36a7a232ec70289f8751a2adb47fc32eb70b57dc81c39d48cbcac9fec46cdfc31663",
+        "previous_signature": "8d61d9100567de44682506aea1a7a6fa6e5491cd27a0a0ed349ef6910ac5ac20ff7bc3e09d7c046566c9f7f3c6f3b10104990e7cb424998203d8f7de586fb7fa5f60045417a432684f85093b06ca91c769f0e7ca19268375e659c2a2352b4655"
+      },
+      {
+        "round": 1000,
+        "randomness": "a40d3e0e7e3c71f28b7da2fd339f47f0bcf10910309f5253d7c323ec8cea3212",
+        "signature": "99bf96de133c3d3937293cfca10c8152b18ab2d034ccecf115658db324d2edc00a16a2044cd04a8a38e2a307e5ecff3511315be8d282079faf24098f283e0ed2c199663b334d2e84c55c032fe469b212c5c2087ebb83a5b25155c3283f5b79ac",
+        "previous_signature": "af0d93299a363735fe847f5ea241442c65843dc1bd3a7b79646b3b10072e908bf034d35cd69d378e3341f139100cd4cd03030399864ef8803a5a4f5e64fccc20bbae36d1ca22a6ddc43d2630c41105e90598fab11e5c7456df3925d4b577b113"
+      }
+    ]
+  }
+}

package/test/vectors.json

@@ -0,0 +1,107 @@
+{
+  "merkle": {
+    "items": [
+      {
+        "i": 0,
+        "v": "a"
+      },
+      {
+        "i": 1,
+        "v": "b"
+      },
+      {
+        "i": 2,
+        "v": "c"
+      }
+    ],
+    "root": "ad9038016cbac0607a9d55697fc95fb4ba2479957c19b7442c0381136d984ccb",
+    "empty": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+  },
+  "consistency": {
+    "items": [
+      {
+        "i": 0,
+        "v": "a"
+      },
+      {
+        "i": 1,
+        "v": "b"
+      },
+      {
+        "i": 2,
+        "v": "c"
+      },
+      {
+        "i": 3,
+        "v": "d"
+      },
+      {
+        "i": 4,
+        "v": "e"
+      },
+      {
+        "i": 5,
+        "v": "f"
+      },
+      {
+        "i": 6,
+        "v": "g"
+      }
+    ],
+    "oldSize": 3,
+    "oldRoot": "ad9038016cbac0607a9d55697fc95fb4ba2479957c19b7442c0381136d984ccb",
+    "newRoot": "4cf2fe0f243d015dbb079ef81ba243162c3045836211e2e5ac1dbd310eed8104",
+    "newSize": 7,
+    "proof": [
+      "bcb2d59ec5e39006a1849c837748c2a01c9bc72c12b094dd7924a87ec3ef5c7a",
+      "42f306854a1e45000ca8428a885a083cc7ae23ea013d38a5c93a623840957435",
+      "1ee35ef00a46acd051a6ee6302b7744123fe40eb122cc1811b749e637351d9f1",
+      "3eca0c9c81749ef476c4ef5bd2fd96857a41c9acf5cefc347cc0f7acf68a990c"
+    ]
+  },
+  "draw": {
+    "entries": [
+      "refA",
+      "refB",
+      "refC",
+      "refD",
+      "refE"
+    ],
+    "algorithm": "fisher-yates-sha256-v1",
+    "seed": "committed-seed-v1",
+    "entryCount": 5,
+    "entriesRoot": "e9ebb4b3a89ca3a0e55cd438dcbb5d550f5b8095ef5143c972cfa68b0dd05291",
+    "winners": [
+      "refB",
+      "refA"
+    ],
+    "winnerIndices": [
+      1,
+      0
+    ]
+  },
+  "entryInclusion": {
+    "entry": "refD",
+    "index": 3,
+    "leaf": "81f104ecd0f0586039e8ca1cca719672ccf4cb4c24bbde6b95f829eb6d8ccc01",
+    "path": [
+      {
+        "side": "left",
+        "hash": "f6072b32af474f7d54435beb393ecc946b499d809f5248b4c63301062740a578"
+      },
+      {
+        "side": "left",
+        "hash": "cc6bff02c29f94a13b842da42e138f8c0b6b18aee115028e788edfd8cda16478"
+      },
+      {
+        "side": "right",
+        "hash": "e272792fb87ac12f2a1aa54f84722cf368df721218ee6c2ee662ecb20e18c012"
+      }
+    ]
+  },
+  "drand": {
+    "round": 1234,
+    "signature": "1a2b3c4d5e6f",
+    "randomness": "948a85c2414389065a8fbada0bf8a1f430c526e716544e19b1032c05544dab31"
+  }
+}