@kirkelabs/walletless-kit 0.1.0 → 0.2.0

package/src/draw.js

@@ -17,7 +17,7 @@
  */
 
 import { createHash } from 'node:crypto';
-import { merkleRoot } from './audit.js';
+import { merkleRoot, merkleProof, verifyMerkleProof, leafHash } from './merkle.js';
 
 const MAX_ENTRIES = 5_000_000;
 const ALGORITHM = 'fisher-yates-sha256-v1';
@@ -149,6 +149,43 @@ export function verifyDraw(proof, entries) {
   }
 }
 
+// ─── Entrant inclusion proofs ────────────────────────────────────────────────
+// A draw proof commits to the exact entry set via `entriesRoot`. These let a
+// single entrant verify "my reference was in the set that produced the winner",
+// against the published root alone — WITHOUT being handed every other entrant's
+// reference (which would leak the field). Answers "were my tickets counted?".
+
+/**
+ * Inclusion proof that `entries[index]` is committed by `entriesRoot`.
+ * Hand the returned object (plus the public `entriesRoot`) to the entrant.
+ * @returns {{entry:any, index:number, leaf:string, path:{side:string,hash:string}[]}}
+ */
+export function entryProof(entries, index) {
+  if (!Array.isArray(entries) || index < 0 || index >= entries.length)
+    throw new Error('entryProof: index out of range');
+  const { leaf, path } = merkleProof(entries, index);
+  return { entry: entries[index], index, leaf, path };
+}
+
+/**
+ * Verify an entrant inclusion proof against the published `entriesRoot`. Checks
+ * BOTH that the proof recomputes the root AND that its leaf is the hash of the
+ * claimed `entry` (so the proof can't be replayed for a different value).
+ * Robust to malformed input (never throws).
+ * @returns {{ok:boolean, reason?:string}}
+ */
+export function verifyEntryProof(args) {
+  try {
+    const { entry, leaf, path, entriesRoot } = args || {};
+    const expected = leafHash(entry).toString('hex');
+    if (String(leaf) !== expected) return { ok: false, reason: 'leaf_entry_mismatch' };
+    const r = verifyMerkleProof({ leaf, path, root: entriesRoot });
+    return r.ok ? { ok: true } : { ok: false, reason: r.reason ?? 'root_mismatch' };
+  } catch (e) {
+    return { ok: false, reason: `verify_error:${e.message}` };
+  }
+}
+
 // ─── Seed adapters ──────────────────────────────────────────────────────────
 // Each returns { source, value, ...context }. Document manipulability honestly.
 
@@ -195,3 +232,111 @@ export function beaconSeed({ value, round, beacon = 'drand' }) {
   if (!value) throw new Error('beaconSeed: value is required');
   return { source: 'beacon', beacon, round: round == null ? null : Number(round), value: String(value) };
 }
+
+// ─── drand: non-manipulable public randomness ────────────────────────────────
+// A drand beacon (the League of Entropy "quicknet" network) emits a fresh random
+// value every `period` seconds. Each value is a BLS THRESHOLD signature: no single
+// operator — including you — can predict, withhold, or grind it. Committing to a
+// FUTURE drand round before entries close therefore gives a seed that is both
+// unpredictable in advance and independently checkable after the fact, closing the
+// "a block producer could bias the block hash" hole in `blockHashSeed`.
+//
+// The publicly recomputable binding is `randomness == SHA256(signature)`; this
+// adapter enforces it with `node:crypto` (zero deps). Full BLS verification — that
+// the signature is a valid threshold signature over the round under the network's
+// public key — is stronger still; pass an async `verifySignature({round,signature,
+// previous})` (e.g. backed by @noble/curves bls12_381) to enforce it too.
+
+/** drand quicknet defaults (League of Entropy). Override for other chains. */
+export const DRAND_QUICKNET = {
+  chainHash: '52db9ba70e0cc0f6eaf7803dd07447a1f5477735fd3f661792ba94600c84e971',
+  genesisTime: 1692803367,
+  period: 3,
+  url: 'https://api.drand.sh',
+};
+
+function sha256hex(hexInput) {
+  return sha256(Buffer.from(String(hexInput), 'hex')).toString('hex');
+}
+
+/**
+ * The drand round whose randomness will first be available at-or-after `unixTime`.
+ * Use this to COMMIT a future round before entries close (publish it via
+ * `commitSeedSource({ source:'drand', round })`), so the seed is fixed in advance.
+ * @param {number} unixTime seconds since epoch (e.g. your entry-close time)
+ * @param {{genesisTime?:number, period?:number}} [chain] defaults to quicknet
+ */
+export function drandRoundAt(unixTime, chain = DRAND_QUICKNET) {
+  const t = Number(unixTime);
+  const { genesisTime, period } = { ...DRAND_QUICKNET, ...chain };
+  if (!Number.isFinite(t) || t < genesisTime) throw new Error('drandRoundAt: unixTime before genesis');
+  return Math.floor((t - genesisTime) / period) + 1;
+}
+
+/**
+ * Build a seed from a drand beacon value, verifying the public binding
+ * `randomness == SHA256(signature)`. Pass the `{round, randomness, signature}`
+ * you fetched from a drand HTTP endpoint (see `fetchDrandRound`).
+ * @param {object} beacon
+ * @param {number} beacon.round
+ * @param {string} beacon.randomness hex
+ * @param {string} beacon.signature  hex (BLS signature)
+ * @param {string} [beacon.chainHash]
+ * @param {(b:object)=>Promise<boolean>|boolean} [verifySignature] optional BLS check
+ * @returns {Promise<{source:string, value:string, round:number, signature:string, chainHash:string|null, manipulable:false, blsVerified:boolean}>}
+ */
+export async function drandSeed(
+  { round, randomness, signature, previousSignature = null, chainHash = null },
+  verifySignature,
+) {
+  if (round == null || !Number.isInteger(Number(round)))
+    throw new Error('drandSeed: round is required');
+  if (!/^[0-9a-f]+$/i.test(String(signature ?? '')))
+    throw new Error('drandSeed: signature (hex) is required');
+  if (!/^[0-9a-f]{64}$/i.test(String(randomness ?? '')))
+    throw new Error('drandSeed: randomness (32-byte hex) is required');
+  if (sha256hex(signature) !== String(randomness).toLowerCase())
+    throw new Error('drandSeed: randomness does not match SHA256(signature) — beacon value rejected');
+  let blsVerified = false;
+  if (typeof verifySignature === 'function') {
+    blsVerified = !!(await verifySignature({
+      round: Number(round),
+      randomness,
+      signature,
+      previousSignature,
+      chainHash,
+    }));
+    if (!blsVerified) throw new Error('drandSeed: BLS signature verification failed');
+  }
+  return {
+    source: 'drand',
+    value: String(randomness).toLowerCase(),
+    round: Number(round),
+    signature: String(signature),
+    chainHash: chainHash == null ? null : String(chainHash),
+    manipulable: false,
+    blsVerified,
+  };
+}
+
+/**
+ * Fetch a drand round over HTTP. `fetch` is injectable (defaults to global fetch)
+ * so this is testable offline and SSRF-scoped to the drand host you pass.
+ * @param {number} round
+ * @param {{url?:string, chainHash?:string, fetch?:Function}} [opts]
+ */
+export async function fetchDrandRound(round, opts = {}) {
+  const { url, chainHash, fetch: f = globalThis.fetch } = { ...DRAND_QUICKNET, ...opts };
+  if (typeof f !== 'function') throw new Error('fetchDrandRound: no fetch available');
+  const endpoint = `${url}/${chainHash}/public/${Number(round)}`;
+  const res = await f(endpoint);
+  if (!res.ok) throw new Error(`fetchDrandRound: HTTP ${res.status}`);
+  const body = await res.json();
+  return {
+    round: Number(body.round),
+    randomness: body.randomness,
+    signature: body.signature,
+    previousSignature: body.previous_signature ?? null, // present on chained beacons
+    chainHash,
+  };
+}

package/src/index.js

@@ -27,12 +27,31 @@ export {
   merkleRoot,
   merkleProof,
   verifyMerkleProof,
+  consistencyProof,
+  verifyConsistencyProof,
+  trailConsistencyProof,
+  verifyTrailConsistency,
   trailHash,
   trailRoot,
   verifyTrail,
   anchor,
 } from './audit.js';
 
+// Zero-dependency canonical JSON (the hashing primitive the whole kit shares).
+export { canonicalJson } from './merkle.js';
+
+// Independent, dependency-free verifier + portable proof bundle. `verifyDrawProof`
+// re-derives a draw without trusting draw.js; `verifyBundle` checks a whole
+// artifact. See SPEC.md and test/vectors.json (the conformance suite).
+export { bundleProof, verifyBundle, verifyDrawProof, BUNDLE_VERSION } from './verify.js';
+
+// NOTE: real BLS verification of drand beacons (`makeDrandVerifier`,
+// `verifyDrandBeacon`, `DRAND_QUICKNET_SCHEME`, …) is intentionally NOT re-exported
+// here. It needs the OPTIONAL peer dependency `@noble/curves`, so it lives only at
+// the `@kirkelabs/walletless-kit/drand-bls` subpath — keeping this core entrypoint
+// (and the zero-dependency verifier) free of pairing-crypto. Import it explicitly:
+//   import { makeDrandVerifier } from '@kirkelabs/walletless-kit/drand-bls';
+
 export {
   createEphemeralAccount,
   isExpired,
@@ -57,8 +76,14 @@ export {
   runDraw,
   publishDrawProof,
   verifyDraw,
+  entryProof,
+  verifyEntryProof,
   commitSeedSource,
   blockHashSeed,
   vrfSeed,
   beaconSeed,
+  drandSeed,
+  drandRoundAt,
+  fetchDrandRound,
+  DRAND_QUICKNET,
 } from './draw.js';

package/src/ledger.js

@@ -104,6 +104,53 @@ export class Ledger {
       winnerProofLink,
     };
   }
+
+  /**
+   * Conservation invariant: you can never allocate (to charity + escrow) plus
+   * deduct in fees MORE than actually came in. A pure, deterministic check over
+   * the three books — the kind of statement an auditor or a charity board can
+   * recompute. `retainedMicro` is what's left for the operator after allocations.
+   *
+   * `fee` entries in ANY book are treated as deductions from inflow; `charity`
+   * and `escrow` book balances are allocations. Returns the breakdown plus a
+   * boolean `balanced` (allocations + fees ≤ inflow) and the residual.
+   * @returns {{balanced:boolean, inflowMicro:number, feesMicro:number, charityMicro:number, escrowMicro:number, retainedMicro:number}}
+   */
+  conservation() {
+    const sum = (arr) => arr.reduce((s, e) => s + e.amountMicro, 0);
+    const inflowMicro = this.balance('inflow');
+    const feesMicro = sum(
+      [...this._books.inflow, ...this._books.charity, ...this._books.escrow].filter(
+        (e) => e.kind === 'fee',
+      ),
+    );
+    const charityMicro = this.balance('charity');
+    const escrowMicro = this.balance('escrow');
+    const retainedMicro = inflowMicro - feesMicro - charityMicro - escrowMicro;
+    return {
+      balanced: retainedMicro >= 0,
+      inflowMicro,
+      feesMicro,
+      charityMicro,
+      escrowMicro,
+      retainedMicro,
+    };
+  }
+
+  /**
+   * Throw unless the conservation invariant holds (allocations + fees ≤ inflow).
+   * Call after posting allocations to fail closed on an over-allocation bug
+   * before it reaches a reconciliation sheet or an on-chain payout.
+   * @returns {Ledger} this (chainable)
+   */
+  assertConservation() {
+    const c = this.conservation();
+    if (!c.balanced)
+      throw new Error(
+        `ledger: conservation violated — allocated/fees (${c.feesMicro + c.charityMicro + c.escrowMicro}) exceed inflow (${c.inflowMicro}) by ${-c.retainedMicro} microALGO`,
+      );
+    return this;
+  }
 }
 
 /** Convenience factory. */

package/src/merkle.js

@@ -0,0 +1,250 @@
+/**
+ * merkle.js — the zero-dependency cryptographic core of the kit.
+ *
+ * This module deliberately depends on NOTHING but `node:crypto`. It is the shared
+ * spine for both the proof-PRODUCING side (`audit.js`, `draw.js`) and the
+ * independent proof-VERIFYING side (`verify.js`). Keeping it dependency-free is
+ * what lets the verifier run anywhere — a browser, an air-gapped box, a second
+ * implementation — without trusting algosdk, oaa-core, or even this package.
+ *
+ * It provides:
+ *   - `canonicalJson`        — deterministic JSON (sorted keys), byte-identical to
+ *                              @kirkelabs/open-agent-access-core's canonicalizeJson
+ *                              (cross-checked by test), so roots match either path.
+ *   - `merkleRoot` / proofs  — RFC 6962 domain-separated tree (leaf 0x00, node 0x01)
+ *                              with lone-node promotion (no CVE-2012-2459).
+ *   - `consistencyProof`     — RFC 6962 §2.1.2 proof that an append-only log only
+ *                              GREW between two sizes and was never rewritten.
+ *
+ * Every function here is pure and deterministic.
+ */
+
+import { createHash } from 'node:crypto';
+
+const MAX_LEAVES = 1_000_000; // DoS bound (mirrors audit.js)
+export const LEAF = Buffer.from([0x00]);
+export const NODE = Buffer.from([0x01]);
+
+export function sha256(...bufs) {
+  const h = createHash('sha256');
+  for (const b of bufs) h.update(b);
+  return h.digest();
+}
+
+/**
+ * Deterministic JSON: object keys sorted recursively, `undefined` dropped, no
+ * insignificant whitespace. Byte-identical to oaa-core's canonicalizeJson for all
+ * JSON values the kit hashes (guarded by `test/canonical.test.js`). A primitive
+ * (string/number/boolean/null) round-trips through standard JSON.
+ */
+export function canonicalJson(value) {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value))
+    return '[' + value.map((v) => canonicalJson(v === undefined ? null : v)).join(',') + ']';
+  const keys = Object.keys(value)
+    .filter((k) => value[k] !== undefined)
+    .sort();
+  return '{' + keys.map((k) => JSON.stringify(k) + ':' + canonicalJson(value[k])).join(',') + '}';
+}
+
+/** Injective leaf encoding: domain-tagged hash of the item's canonical JSON. */
+export function leafHash(item) {
+  return sha256(LEAF, Buffer.from(canonicalJson(item), 'utf8'));
+}
+
+/** Internal node hash: H(0x01 ‖ left ‖ right). */
+export function nodeHash(left, right) {
+  return sha256(NODE, left, right);
+}
+
+/**
+ * RFC 6962 Merkle Tree Hash over an array of leaf buffers. Bottom-up pairing with
+ * lone-node PROMOTION (the odd node is carried up unchanged, never duplicated).
+ * This equals the recursive RFC 6962 split-at-largest-power-of-two definition
+ * (verified for n = 0..40 in test), so consistency proofs below are valid.
+ */
+function mthFromLeaves(leaves) {
+  if (leaves.length === 0) return sha256(Buffer.alloc(0));
+  let level = leaves;
+  while (level.length > 1) {
+    const next = [];
+    for (let i = 0; i < level.length; i += 2) {
+      next.push(i + 1 < level.length ? nodeHash(level[i], level[i + 1]) : level[i]);
+    }
+    level = next;
+  }
+  return level[0];
+}
+
+/**
+ * Deterministic Merkle root (hex) over an ordered list of items.
+ * Empty list → H("") (RFC 6962 empty-tree root). Single item → its leaf hash.
+ */
+export function merkleRoot(items) {
+  if (!Array.isArray(items)) throw new Error('merkleRoot: items must be an array');
+  if (items.length > MAX_LEAVES) throw new Error('merkleRoot: too many leaves');
+  return mthFromLeaves(items.map(leafHash)).toString('hex');
+}
+
+/**
+ * Inclusion proof for the item at `index`: sibling hashes (hex) + their side,
+ * which `verifyMerkleProof` replays to recompute the root.
+ */
+export function merkleProof(items, index) {
+  if (!Array.isArray(items) || index < 0 || index >= items.length)
+    throw new Error('merkleProof: index out of range');
+  let level = items.map(leafHash);
+  let idx = index;
+  const path = [];
+  while (level.length > 1) {
+    const next = [];
+    for (let i = 0; i < level.length; i += 2) {
+      if (i + 1 < level.length) {
+        next.push(nodeHash(level[i], level[i + 1]));
+        if (i === idx) path.push({ side: 'right', hash: level[i + 1].toString('hex') });
+        else if (i + 1 === idx) path.push({ side: 'left', hash: level[i].toString('hex') });
+      } else {
+        next.push(level[i]); // promoted; no sibling recorded for the lone node
+      }
+    }
+    idx = Math.floor(idx / 2);
+    level = next;
+  }
+  return { index, leaf: leafHash(items[index]).toString('hex'), path };
+}
+
+/** Verify an inclusion proof against an expected root. Never throws. */
+export function verifyMerkleProof({ leaf, path, root }) {
+  try {
+    let acc = Buffer.from(String(leaf), 'hex');
+    for (const step of path || []) {
+      const sib = Buffer.from(String(step.hash), 'hex');
+      acc = step.side === 'left' ? nodeHash(sib, acc) : nodeHash(acc, sib);
+    }
+    return { ok: acc.toString('hex') === String(root) };
+  } catch (e) {
+    return { ok: false, reason: `verify_error:${e.message}` };
+  }
+}
+
+// ─── RFC 6962 consistency proofs ─────────────────────────────────────────────
+// A consistency proof shows that the tree of size `m` is a PREFIX of the tree of
+// size `n` (m ≤ n): every leaf of the old tree is still present, unchanged, in the
+// same position. This is the Certificate-Transparency primitive that turns
+// "tamper-evident snapshot" into "provably append-only history": anyone holding an
+// old anchored root can prove the operator only appended and never rewrote it.
+
+/** MTH over a slice of leaf buffers (RFC 6962 recursive split). */
+function mthRange(leaves, start, end) {
+  return mthFromLeaves(leaves.slice(start, end));
+}
+
+/** Largest power of two strictly less than n (the RFC 6962 split point). */
+function splitPoint(n) {
+  let k = 1;
+  while (k * 2 < n) k *= 2;
+  return k;
+}
+
+/** SUBPROOF(m, leaves[start:end], b) per RFC 6962 §2.1.2. */
+function subproof(m, leaves, start, end, b) {
+  const n = end - start;
+  if (m === n) {
+    // The subtree is fully contained in the old tree.
+    return b ? [] : [mthRange(leaves, start, end)];
+  }
+  const k = splitPoint(n);
+  if (m <= k) {
+    const proof = subproof(m, leaves, start, start + k, b);
+    proof.push(mthRange(leaves, start + k, end));
+    return proof;
+  }
+  const proof = subproof(m - k, leaves, start + k, end, false);
+  proof.push(mthRange(leaves, start, start + k));
+  return proof;
+}
+
+/**
+ * Build a consistency proof that the first `oldSize` items (the old tree) are a
+ * prefix of the full `items` (the new tree). Returns hex node hashes.
+ * @param {any[]} items   the FULL current ordered list (length = new size)
+ * @param {number} oldSize  the earlier, anchored size (1 ≤ oldSize ≤ items.length)
+ * @returns {{oldSize:number,newSize:number,proof:string[]}}
+ */
+export function consistencyProof(items, oldSize) {
+  if (!Array.isArray(items)) throw new Error('consistencyProof: items must be an array');
+  const newSize = items.length;
+  const m = Number(oldSize);
+  if (!Number.isInteger(m) || m < 1 || m > newSize)
+    throw new Error('consistencyProof: oldSize must be an integer in [1, items.length]');
+  const leaves = items.map(leafHash);
+  const nodes = m === newSize ? [] : subproof(m, leaves, 0, newSize, true);
+  return { oldSize: m, newSize, proof: nodes.map((b) => b.toString('hex')) };
+}
+
+/**
+ * Verify a consistency proof: that `oldRoot` (size m) is a prefix of `newRoot`
+ * (size n). Pure replay of RFC 6962 §2.1.2 verification. Never throws.
+ * @returns {{ok:boolean, reason?:string}}
+ */
+export function verifyConsistencyProof(args) {
+  try {
+    const { oldRoot, newRoot, oldSize, newSize, proof } = args || {};
+    const m = Number(oldSize);
+    const n = Number(newSize);
+    if (!Number.isInteger(m) || !Number.isInteger(n) || m < 1 || m > n)
+      return { ok: false, reason: 'bad_sizes' };
+
+    // m == n: identical trees — roots must match and the proof must be empty.
+    if (m === n) {
+      return String(oldRoot) === String(newRoot) && (proof || []).length === 0
+        ? { ok: true }
+        : { ok: false, reason: 'size_equal_mismatch' };
+    }
+
+    // Canonical RFC 6962 consistency-proof verification (certificate-transparency
+    // reference). Walk the node/last_node indices, consuming proof nodes in order.
+    const nodes = (proof || []).map((h) => Buffer.from(String(h), 'hex'));
+    let p = 0;
+    const next = () => {
+      if (p >= nodes.length) throw new Error('proof_exhausted');
+      return nodes[p++];
+    };
+
+    let node = m - 1;
+    let last = n - 1;
+    while (node % 2 === 1) {
+      node = Math.floor(node / 2);
+      last = Math.floor(last / 2);
+    }
+
+    // If `node` reduced to 0, old tree was a perfect subtree and oldRoot is the
+    // implicit first hash; otherwise the first proof node seeds both accumulators.
+    let oldHash = node ? next() : Buffer.from(String(oldRoot), 'hex');
+    let newHash = oldHash;
+
+    while (node) {
+      if (node % 2 === 1) {
+        const sib = next(); // right child → sibling on the left
+        oldHash = nodeHash(sib, oldHash);
+        newHash = nodeHash(sib, newHash);
+      } else if (node < last) {
+        newHash = nodeHash(newHash, next()); // left child with a right sibling
+      }
+      node = Math.floor(node / 2);
+      last = Math.floor(last / 2);
+    }
+    while (last) {
+      newHash = nodeHash(newHash, next());
+      last = Math.floor(last / 2);
+    }
+
+    if (p !== nodes.length) return { ok: false, reason: 'proof_too_long' };
+    const ok =
+      oldHash.toString('hex') === String(oldRoot) &&
+      newHash.toString('hex') === String(newRoot);
+    return ok ? { ok: true } : { ok: false, reason: 'root_mismatch' };
+  } catch (e) {
+    return { ok: false, reason: `verify_error:${e.message}` };
+  }
+}