veritrail 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aris Rhiannon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,163 @@
+# veritrail
+
+[![ci](https://github.com/ArisRhiannon/veritrail/actions/workflows/ci.yml/badge.svg)](https://github.com/ArisRhiannon/veritrail/actions/workflows/ci.yml)
+
+**Tamper-evident, verifiable append-only logs and maps for TypeScript.** Zero
+dependencies. RFC 6962 / RFC 9162 Merkle trees with **inclusion *and* consistency**
+proofs, Ed25519-signed checkpoints, and a sparse-Merkle **verifiable map** (inclusion +
+non-inclusion proofs). Runs anywhere Node or Bun runs. No server, no network.
+
+## Why
+
+The JS/TS ecosystem has generic Merkle-tree libraries, but few modern, dependency-light,
+spec-faithful primitives for building your own *transparency logs* / tamper-evident audit
+trails with both inclusion and consistency proofs. Robust implementations live in Rust
+(`ct-merkle`) or in server-scale infrastructure (Trillian). `veritrail` fills that gap as
+a small, auditable library: its proofs are byte-for-byte interoperable with the RFC 6962
+reference implementation (see the cross-implementation vectors in `test/`), and the whole
+core fits in a few hundred lines you can read in an afternoon.
+
+It targets small-to-moderate logs (in-memory or single-file). It is **not** a replacement
+for Trillian/CT at billions of entries — see [Performance & scale](#performance--scale).
+
+Use it for: supply-chain / release transparency, compliance audit trails (provably
+append-only), verifiable action logs for agents/automation, secure timestamping, and
+key-transparency-style verifiable maps.
+
+## Install
+
+```sh
+npm i veritrail      # or: bun add veritrail / pnpm add veritrail / yarn add veritrail
+```
+
+Ships compiled ESM + type declarations (`dist/`), so it imports under plain Node ≥ 20 (no
+loader needed) and Bun. The `veritrail` CLI runs on Node. From source: `git clone … &&
+bun install && bun run check`.
+
+## Data model
+
+Hashing follows RFC 6962 §2.1 (domain-separated):
+
+```
+leafHash(entry)        = SHA256(0x00 || entry)
+nodeHash(left, right)  = SHA256(0x01 || left || right)
+emptyRoot()            = SHA256("")
+```
+
+- **Log**: an ordered list of entries; its *Merkle Tree Head* (root) commits to the whole
+  history. An **inclusion proof** shows an entry is in the tree; a **consistency proof**
+  shows tree *n* is an append-only extension of tree *m* (nothing was edited or removed).
+- **Checkpoint**: `{size, rootHash, timestamp}`, optionally **Ed25519-signed** — a
+  portable, independently verifiable commitment to the log state.
+- **Verifiable map** (sparse Merkle tree, 256-bit keys): proves `key → value`
+  (inclusion) *and* `key is absent` (non-inclusion).
+
+## Library quickstart
+
+```ts
+import { Log, verifyInclusion, verifyConsistency, generateKeyPair, verifyCheckpoint, utf8 } from "veritrail";
+
+const log = new Log();
+log.append(utf8("event-1"));
+log.append(utf8("event-2"));
+
+// Inclusion: prove entry 0 is in the log.
+const n = log.size, root = log.root();
+const proof = log.inclusionProof(0);
+verifyInclusion(proof, 0, n, log.leaf(0), root); // => true
+
+// Consistency: prove the size-2 tree extends the size-1 tree.
+const before = new Log(); before.append(utf8("event-1"));
+const cproof = log.consistencyProof(1);
+verifyConsistency(cproof, 1, 2, before.root(), root); // => true
+
+// Signed checkpoint.
+const { publicKey, privateKey } = generateKeyPair();
+const { checkpoint, signature } = log.signedCheckpoint(privateKey);
+verifyCheckpoint(checkpoint, signature, publicKey); // => true
+```
+
+Verifiable map:
+
+```ts
+import { SparseMerkleTree, smtKey, verifyMapInclusion, verifyMapNonInclusion, utf8 } from "veritrail";
+
+const t = new SparseMerkleTree();
+t.set(smtKey("alice"), utf8("100"));
+const root = t.root();
+verifyMapInclusion(smtKey("alice"), utf8("100"), t.proof(smtKey("alice")), root);    // true
+verifyMapNonInclusion(smtKey("bob"), t.proof(smtKey("bob")), root);                   // true
+```
+
+## CLI
+
+```sh
+veritrail keygen priv.pem pub.pem
+veritrail append log.json "first entry"      # -> size=1 root=…
+veritrail append log.json "second entry"     # -> size=2 root=…
+veritrail prove log.json 0 > incl.json        # JSON inclusion proof
+veritrail verify incl.json                     # -> OK            (exit 0)
+veritrail consistency log.json 1 2 > cons.json
+veritrail verify cons.json                     # -> OK
+veritrail sign log.json priv.pem > signed.json
+veritrail audit log.json signed.json pub.pem   # -> OK   (recomputes root + checks signature)
+```
+
+`verify` and `audit` exit `0` when valid and non-zero when tampering is detected.
+
+## Threat model
+
+Protects against **undetectable mutation of history**: editing, reordering, deleting, or
+truncating past entries is caught by inclusion/consistency proof verification, and a
+signed checkpoint binds a specific `(size, root)` to a key holder. It does **not** provide
+confidentiality (entries are not encrypted), availability, or protection against an
+attacker who controls the verifier's copy of the trusted root/public key. Crypto uses the
+platform `node:crypto` (SHA-256, Ed25519); verification performs no secret-dependent work.
+
+## Performance & scale
+
+Honest complexity (the core favors auditability over asymptotics):
+
+- `merkleRoot` / `inclusionProof` / `consistencyProof` are **recomputed from the full
+  entry set** — O(n) hashes per call (proof generation does not yet use cached subtrees).
+- `FileStore.append` rewrites the whole file — O(n) I/O per append.
+- `SparseMerkleTree` recomputes over populated nodes — O(k·256) for k entries.
+- Verification (`verifyInclusion` / `verifyConsistency`) is O(log n) and supports tree
+  sizes up to `Number.MAX_SAFE_INTEGER` (2⁵³−1).
+
+This is comfortable for thousands to low-millions of entries. For billion-entry,
+high-throughput logs use Trillian / a tiled log; incremental hashing and cached subtrees
+are on the roadmap.
+
+**Concurrency:** `FileStore` serializes appends across processes with an exclusive lock
+file (stale-lock recovery included) and writes atomically (`temp → fsync → rename`), so a
+crash or a concurrent writer can neither corrupt the store nor lose an entry. The lock is
+advisory with a 10 s stale timeout (a crashed writer's lock is reclaimed); it is **not**
+intended for high-contention or suspendable workloads, and it is a single-machine store,
+not a distributed one.
+
+## API summary
+
+| Area | Exports |
+|------|---------|
+| Hash | `sha256`, `leafHash`, `nodeHash`, `emptyRoot`, `equal`, `toHex`, `fromHex`, `utf8` |
+| Merkle | `merkleRoot`, `inclusionPath`, `verifyInclusion`, `consistencyProof`, `verifyConsistency` |
+| Log/Store | `Log`, `Store`, `MemoryStore`, `FileStore` |
+| Checkpoint | `Checkpoint`, `generateKeyPair`, `signCheckpoint`, `verifyCheckpoint`, `encodeCheckpoint`, PEM import/export |
+| Verifiable map | `SparseMerkleTree`, `smtKey`, `smtEmptyRoot`, `verifyMapInclusion`, `verifyMapNonInclusion` |
+| Serialization | `inclusionToJSON`, `consistencyToJSON`, `verifyBundleJSON`, checkpoint (de)serializers |
+
+## Status
+
+v0.2 covers the full v1 scope: Merkle core, append-only log with signed checkpoints,
+verifiable map, CLI, RFC 6962 cross-implementation vectors + 500-trial property tests, CI.
+Proof verifiers are total (never throw on untrusted input) and support tree sizes up to
+`Number.MAX_SAFE_INTEGER`; the file store writes atomically and durably. Key design
+decisions are recorded in `docs/adr/`. Roadmap: networked witness/gossip, tiled logs,
+inclusion-proof batching.
+
+## License
+
+[MIT](LICENSE) © 2026 Aris Rhiannon. Permissive, OSI-approved open source — free to
+use, modify, and embed (including in commercial and networked services) with no
+revenue or headcount restrictions.

package/dist/checkpoint.d.ts

@@ -0,0 +1,19 @@
+import { type KeyObject } from "node:crypto";
+/** A signed-tree-head: a commitment to the log state at a point in time. */
+export interface Checkpoint {
+    size: number;
+    rootHash: Uint8Array;
+    timestamp: number;
+}
+/** Deterministic, unambiguous byte encoding used as the signing payload. */
+export declare function encodeCheckpoint(c: Checkpoint): Uint8Array;
+export declare function generateKeyPair(): {
+    publicKey: KeyObject;
+    privateKey: KeyObject;
+};
+export declare function signCheckpoint(c: Checkpoint, privateKey: KeyObject): Uint8Array;
+export declare function verifyCheckpoint(c: Checkpoint, signature: Uint8Array, publicKey: KeyObject): boolean;
+export declare function exportPublicKeyPem(key: KeyObject): string;
+export declare function exportPrivateKeyPem(key: KeyObject): string;
+export declare function importPublicKeyPem(pem: string): KeyObject;
+export declare function importPrivateKeyPem(pem: string): KeyObject;

package/dist/checkpoint.js

@@ -0,0 +1,27 @@
+import { generateKeyPairSync, sign, verify, createPublicKey, createPrivateKey } from "node:crypto";
+import { toHex, utf8 } from "./hash.js";
+/** Deterministic, unambiguous byte encoding used as the signing payload. */
+export function encodeCheckpoint(c) {
+    return utf8(`veritrail-checkpoint\n${c.size}\n${toHex(c.rootHash)}\n${c.timestamp}\n`);
+}
+export function generateKeyPair() {
+    return generateKeyPairSync("ed25519");
+}
+export function signCheckpoint(c, privateKey) {
+    return new Uint8Array(sign(null, encodeCheckpoint(c), privateKey));
+}
+export function verifyCheckpoint(c, signature, publicKey) {
+    return verify(null, encodeCheckpoint(c), publicKey, signature);
+}
+export function exportPublicKeyPem(key) {
+    return key.export({ type: "spki", format: "pem" }).toString();
+}
+export function exportPrivateKeyPem(key) {
+    return key.export({ type: "pkcs8", format: "pem" }).toString();
+}
+export function importPublicKeyPem(pem) {
+    return createPublicKey(pem);
+}
+export function importPrivateKeyPem(pem) {
+    return createPrivateKey(pem);
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+import { readFileSync, writeFileSync } from "node:fs";
+import { FileStore } from "./store.js";
+import { Log } from "./log.js";
+import { merkleRoot, consistencyProof } from "./merkle.js";
+import { toHex, utf8, equal } from "./hash.js";
+import { inclusionToJSON, consistencyToJSON, verifyBundleJSON, signedCheckpointToJSON, signedCheckpointFromJSON, } from "./serialize.js";
+import { generateKeyPair, exportPublicKeyPem, exportPrivateKeyPem, importPrivateKeyPem, importPublicKeyPem, verifyCheckpoint, } from "./checkpoint.js";
+function die(msg, code = 2) {
+    console.error(msg);
+    process.exit(code);
+}
+// Convert any unexpected error (missing/unreadable file, malformed JSON, bad
+// hex, bad PEM, …) into a clean message with exit code 2. This keeps the
+// pipeline contract crisp: 0 = valid, 1 = verification FAIL, 2 = usage/format
+// error — and never leaks a stack trace on untrusted input.
+process.on("uncaughtException", (e) => die(`error: ${e instanceof Error ? e.message : String(e)}`, 2));
+const HELP = `veritrail — tamper-evident verifiable logs
+commands:
+  append <store> <entry>        append an entry; prints size + root
+  root <store>                  print current size + root
+  prove <store> <index>         emit a JSON inclusion proof
+  consistency <store> <m> <n>   emit a JSON consistency proof (sizes m<=n)
+  verify <bundle.json|->         verify a proof bundle (exit 0 ok / 1 fail)
+  keygen <priv.pem> <pub.pem>   generate an Ed25519 key pair
+  sign <store> <priv.pem>       emit a signed checkpoint for current state
+  audit <store> <signed.json> <pub.pem>   verify root + signature (exit 0/1)`;
+const [cmd, ...args] = process.argv.slice(2);
+const open = (f) => new Log(new FileStore(f));
+switch (cmd) {
+    case "append": {
+        const [f, entry] = args;
+        if (!f || entry === undefined)
+            die("usage: append <store> <entry>");
+        const l = open(f);
+        const size = l.append(utf8(entry));
+        console.log(`size=${size} root=${toHex(l.root())}`);
+        break;
+    }
+    case "root": {
+        const [f] = args;
+        if (!f)
+            die("usage: root <store>");
+        const l = open(f);
+        console.log(`size=${l.size} root=${toHex(l.root())}`);
+        break;
+    }
+    case "prove": {
+        const [f, idx] = args;
+        if (!f || idx === undefined)
+            die("usage: prove <store> <index>");
+        const l = open(f);
+        const i = Number(idx);
+        if (!Number.isInteger(i) || i < 0 || i >= l.size)
+            die(`index out of range (size=${l.size})`);
+        const b = { type: "inclusion", index: i, treeSize: l.size, leaf: l.leaf(i), path: l.inclusionProof(i), root: l.root() };
+        console.log(inclusionToJSON(b));
+        break;
+    }
+    case "consistency": {
+        const [f, ms, ns] = args;
+        if (!f || ms === undefined || ns === undefined)
+            die("usage: consistency <store> <m> <n>");
+        const l = open(f);
+        const m = Number(ms), n = Number(ns), es = l.entries();
+        if (!(Number.isInteger(m) && Number.isInteger(n) && 0 < m && m <= n && n <= es.length))
+            die(`bad range (size=${es.length})`);
+        const sub = es.slice(0, n);
+        const b = { type: "consistency", first: m, second: n, firstRoot: merkleRoot(es.slice(0, m)), secondRoot: merkleRoot(sub), path: consistencyProof(m, sub) };
+        console.log(consistencyToJSON(b));
+        break;
+    }
+    case "verify": {
+        const [f] = args;
+        const json = f && f !== "-" ? readFileSync(f, "utf8") : readFileSync(0, "utf8");
+        const ok = verifyBundleJSON(json);
+        console.log(ok ? "OK" : "FAIL");
+        process.exit(ok ? 0 : 1);
+        break;
+    }
+    case "keygen": {
+        const [priv, pub] = args;
+        if (!priv || !pub)
+            die("usage: keygen <priv.pem> <pub.pem>");
+        const { publicKey, privateKey } = generateKeyPair();
+        writeFileSync(priv, exportPrivateKeyPem(privateKey));
+        writeFileSync(pub, exportPublicKeyPem(publicKey));
+        console.log("keys written");
+        break;
+    }
+    case "sign": {
+        const [f, priv] = args;
+        if (!f || !priv)
+            die("usage: sign <store> <priv.pem>");
+        const l = open(f);
+        const sc = l.signedCheckpoint(importPrivateKeyPem(readFileSync(priv, "utf8")), Date.now());
+        console.log(signedCheckpointToJSON(sc));
+        break;
+    }
+    case "audit": {
+        const [f, scFile, pubFile] = args;
+        if (!f || !scFile || !pubFile)
+            die("usage: audit <store> <signed.json> <pub.pem>");
+        const l = open(f);
+        const sc = signedCheckpointFromJSON(readFileSync(scFile, "utf8"));
+        const pub = importPublicKeyPem(readFileSync(pubFile, "utf8"));
+        if (sc.checkpoint.size > l.size)
+            die(`TAMPERED: checkpoint size ${sc.checkpoint.size} > log size ${l.size}`, 1);
+        const recomputed = merkleRoot(l.entries().slice(0, sc.checkpoint.size));
+        const rootOk = equal(recomputed, sc.checkpoint.rootHash);
+        const sigOk = verifyCheckpoint(sc.checkpoint, sc.signature, pub);
+        if (rootOk && sigOk) {
+            console.log(`OK size=${sc.checkpoint.size} root=${toHex(sc.checkpoint.rootHash)}`);
+            process.exit(0);
+        }
+        die(`TAMPERED rootOk=${rootOk} sigOk=${sigOk}`, 1);
+        break;
+    }
+    case "help":
+    case "--help":
+    case "-h":
+    case undefined:
+        console.log(HELP);
+        break;
+    default:
+        die(`unknown command: ${cmd}\n\n${HELP}`, 2);
+}

package/dist/hash.d.ts

@@ -0,0 +1,16 @@
+/** Domain-separation prefixes per RFC 6962 §2.1. */
+export declare const LEAF_PREFIX = 0;
+export declare const NODE_PREFIX = 1;
+/** SHA-256 over the concatenation of chunks. */
+export declare function sha256(...chunks: Uint8Array[]): Uint8Array;
+/** Leaf hash: SHA-256(0x00 || entry). */
+export declare function leafHash(entry: Uint8Array): Uint8Array;
+/** Interior node hash: SHA-256(0x01 || left || right). */
+export declare function nodeHash(left: Uint8Array, right: Uint8Array): Uint8Array;
+/** Root of the empty tree: SHA-256(""). */
+export declare function emptyRoot(): Uint8Array;
+/** Constant-time-ish equality for hashes (no early exit). */
+export declare function equal(a: Uint8Array, b: Uint8Array): boolean;
+export declare function toHex(b: Uint8Array): string;
+export declare function fromHex(s: string): Uint8Array;
+export declare function utf8(s: string): Uint8Array;

package/dist/hash.js

@@ -0,0 +1,43 @@
+import { createHash } from "node:crypto";
+/** Domain-separation prefixes per RFC 6962 §2.1. */
+export const LEAF_PREFIX = 0x00;
+export const NODE_PREFIX = 0x01;
+/** SHA-256 over the concatenation of chunks. */
+export function sha256(...chunks) {
+    const h = createHash("sha256");
+    for (const c of chunks)
+        h.update(c);
+    return new Uint8Array(h.digest());
+}
+/** Leaf hash: SHA-256(0x00 || entry). */
+export function leafHash(entry) {
+    return sha256(Uint8Array.of(LEAF_PREFIX), entry);
+}
+/** Interior node hash: SHA-256(0x01 || left || right). */
+export function nodeHash(left, right) {
+    return sha256(Uint8Array.of(NODE_PREFIX), left, right);
+}
+/** Root of the empty tree: SHA-256(""). */
+export function emptyRoot() {
+    return sha256(new Uint8Array(0));
+}
+/** Constant-time-ish equality for hashes (no early exit). */
+export function equal(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let d = 0;
+    for (let i = 0; i < a.length; i++)
+        d |= a[i] ^ b[i];
+    return d === 0;
+}
+export function toHex(b) {
+    return Buffer.from(b).toString("hex");
+}
+export function fromHex(s) {
+    if (s.length % 2 !== 0 || /[^0-9a-fA-F]/.test(s))
+        throw new Error("invalid hex");
+    return new Uint8Array(Buffer.from(s, "hex"));
+}
+export function utf8(s) {
+    return new TextEncoder().encode(s);
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./hash.js";
+export * from "./merkle.js";
+export * from "./store.js";
+export * from "./checkpoint.js";
+export * from "./log.js";
+export * from "./smt.js";
+export * from "./serialize.js";

package/dist/index.js

@@ -0,0 +1,7 @@
+export * from "./hash.js";
+export * from "./merkle.js";
+export * from "./store.js";
+export * from "./checkpoint.js";
+export * from "./log.js";
+export * from "./smt.js";
+export * from "./serialize.js";

package/dist/log.d.ts

@@ -0,0 +1,23 @@
+import { type Store } from "./store.js";
+import { type Checkpoint } from "./checkpoint.js";
+import type { KeyObject } from "node:crypto";
+/** An append-only, tamper-evident log over a pluggable Store. */
+export declare class Log {
+    private readonly store;
+    constructor(store?: Store);
+    get size(): number;
+    append(entry: Uint8Array): number;
+    entries(): Uint8Array[];
+    entry(index: number): Uint8Array;
+    /** Leaf hash of the entry at `index`. */
+    leaf(index: number): Uint8Array;
+    /** Current Merkle tree head (root). */
+    root(): Uint8Array;
+    inclusionProof(index: number): Uint8Array[];
+    consistencyProof(first: number): Uint8Array[];
+    checkpoint(timestamp?: number): Checkpoint;
+    signedCheckpoint(privateKey: KeyObject, timestamp?: number): {
+        checkpoint: Checkpoint;
+        signature: Uint8Array;
+    };
+}

package/dist/log.js

@@ -0,0 +1,44 @@
+import { leafHash } from "./hash.js";
+import { merkleRoot, inclusionPath, consistencyProof } from "./merkle.js";
+import { MemoryStore } from "./store.js";
+import { signCheckpoint } from "./checkpoint.js";
+/** An append-only, tamper-evident log over a pluggable Store. */
+export class Log {
+    store;
+    constructor(store = new MemoryStore()) {
+        this.store = store;
+    }
+    get size() {
+        return this.store.size();
+    }
+    append(entry) {
+        return this.store.append(entry);
+    }
+    entries() {
+        return this.store.all();
+    }
+    entry(index) {
+        return this.store.get(index);
+    }
+    /** Leaf hash of the entry at `index`. */
+    leaf(index) {
+        return leafHash(this.store.get(index));
+    }
+    /** Current Merkle tree head (root). */
+    root() {
+        return merkleRoot(this.store.all());
+    }
+    inclusionProof(index) {
+        return inclusionPath(index, this.store.all());
+    }
+    consistencyProof(first) {
+        return consistencyProof(first, this.store.all());
+    }
+    checkpoint(timestamp = Date.now()) {
+        return { size: this.size, rootHash: this.root(), timestamp };
+    }
+    signedCheckpoint(privateKey, timestamp = Date.now()) {
+        const checkpoint = this.checkpoint(timestamp);
+        return { checkpoint, signature: signCheckpoint(checkpoint, privateKey) };
+    }
+}

package/dist/merkle.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Merkle Tree Hash (RFC 6962 §2.1). `entries` are raw leaf data (NOT pre-hashed).
+ * MTH({}) = SHA256(""); MTH({d0}) = leafHash(d0);
+ * MTH(D) = nodeHash(MTH(D[0:k]), MTH(D[k:n])), k = largest power of 2 < n.
+ */
+export declare function merkleRoot(entries: Uint8Array[]): Uint8Array;
+/** Inclusion (audit) path for leaf index m in a tree of entries (RFC 6962 §2.1.1). */
+export declare function inclusionPath(m: number, entries: Uint8Array[]): Uint8Array[];
+/**
+ * Verify an inclusion proof (RFC 9162 §2.1.3.2). `leaf` is the leaf hash.
+ * Reconstructs the root from `leaf` + `path` and compares to `root`.
+ * Tree sizes up to Number.MAX_SAFE_INTEGER (2^53 − 1) are supported.
+ */
+export declare function verifyInclusion(path: Uint8Array[], index: number, treeSize: number, leaf: Uint8Array, root: Uint8Array): boolean;
+/** Consistency proof between first size m and full tree (RFC 6962 §2.1.2). 0 < m <= n. */
+export declare function consistencyProof(m: number, entries: Uint8Array[]): Uint8Array[];
+/**
+ * Verify a consistency proof (RFC 9162 §2.1.4.2).
+ * Sizes up to Number.MAX_SAFE_INTEGER (2^53 − 1) are supported.
+ */
+export declare function verifyConsistency(path: Uint8Array[], first: number, second: number, firstRoot: Uint8Array, secondRoot: Uint8Array): boolean;

package/dist/merkle.js

@@ -0,0 +1,135 @@
+import { emptyRoot, leafHash, nodeHash, equal } from "./hash.js";
+/** Largest power of two strictly less than n (n >= 2). Uses multiplication to
+ *  stay correct beyond 2^31 (a signed `<<` would overflow). */
+function splitPoint(n) {
+    let k = 1;
+    while (k * 2 < n)
+        k *= 2;
+    return k;
+}
+/**
+ * Merkle Tree Hash (RFC 6962 §2.1). `entries` are raw leaf data (NOT pre-hashed).
+ * MTH({}) = SHA256(""); MTH({d0}) = leafHash(d0);
+ * MTH(D) = nodeHash(MTH(D[0:k]), MTH(D[k:n])), k = largest power of 2 < n.
+ */
+export function merkleRoot(entries) {
+    const n = entries.length;
+    if (n === 0)
+        return emptyRoot();
+    if (n === 1)
+        return leafHash(entries[0]);
+    const k = splitPoint(n);
+    return nodeHash(merkleRoot(entries.slice(0, k)), merkleRoot(entries.slice(k)));
+}
+/** Inclusion (audit) path for leaf index m in a tree of entries (RFC 6962 §2.1.1). */
+export function inclusionPath(m, entries) {
+    const n = entries.length;
+    if (m < 0 || m >= n)
+        throw new RangeError(`index ${m} out of range for size ${n}`);
+    if (n === 1)
+        return [];
+    const k = splitPoint(n);
+    if (m < k)
+        return [...inclusionPath(m, entries.slice(0, k)), merkleRoot(entries.slice(k))];
+    return [...inclusionPath(m - k, entries.slice(k)), merkleRoot(entries.slice(0, k))];
+}
+/**
+ * Verify an inclusion proof (RFC 9162 §2.1.3.2). `leaf` is the leaf hash.
+ * Reconstructs the root from `leaf` + `path` and compares to `root`.
+ * Tree sizes up to Number.MAX_SAFE_INTEGER (2^53 − 1) are supported.
+ */
+export function verifyInclusion(path, index, treeSize, leaf, root) {
+    if (!Number.isSafeInteger(index) || !Number.isSafeInteger(treeSize) || index < 0 || index >= treeSize)
+        return false;
+    let fn = index;
+    let sn = treeSize - 1;
+    let r = leaf;
+    for (const p of path) {
+        if (sn === 0)
+            return false;
+        if (fn % 2 === 1 || fn === sn) {
+            r = nodeHash(p, r);
+            if (fn % 2 === 0) {
+                do {
+                    fn = Math.floor(fn / 2);
+                    sn = Math.floor(sn / 2);
+                } while (fn % 2 === 0 && fn !== 0);
+            }
+        }
+        else {
+            r = nodeHash(r, p);
+        }
+        fn = Math.floor(fn / 2);
+        sn = Math.floor(sn / 2);
+    }
+    return sn === 0 && equal(r, root);
+}
+function isPowerOfTwo(x) {
+    if (x <= 0)
+        return false;
+    const b = BigInt(x);
+    return (b & (b - 1n)) === 0n;
+}
+/** SUBPROOF helper (RFC 6962 §2.1.2). */
+function subproof(m, entries, b) {
+    const n = entries.length;
+    if (m === n)
+        return b ? [] : [merkleRoot(entries)];
+    const k = splitPoint(n);
+    if (m <= k)
+        return [...subproof(m, entries.slice(0, k), b), merkleRoot(entries.slice(k))];
+    return [...subproof(m - k, entries.slice(k), false), merkleRoot(entries.slice(0, k))];
+}
+/** Consistency proof between first size m and full tree (RFC 6962 §2.1.2). 0 < m <= n. */
+export function consistencyProof(m, entries) {
+    const n = entries.length;
+    if (m <= 0 || m > n)
+        throw new RangeError(`first size ${m} out of range for size ${n}`);
+    if (m === n)
+        return [];
+    return subproof(m, entries, true);
+}
+/**
+ * Verify a consistency proof (RFC 9162 §2.1.4.2).
+ * Sizes up to Number.MAX_SAFE_INTEGER (2^53 − 1) are supported.
+ */
+export function verifyConsistency(path, first, second, firstRoot, secondRoot) {
+    if (!Number.isSafeInteger(first) || !Number.isSafeInteger(second) || first < 0 || first > second)
+        return false;
+    if (first === 0)
+        return path.length === 0;
+    if (first === second)
+        return path.length === 0 && equal(firstRoot, secondRoot);
+    const work = isPowerOfTwo(first) ? [firstRoot, ...path] : path;
+    if (work.length === 0)
+        return false;
+    let fn = first - 1;
+    let sn = second - 1;
+    while (fn % 2 === 1) {
+        fn = Math.floor(fn / 2);
+        sn = Math.floor(sn / 2);
+    }
+    let fr = work[0];
+    let sr = work[0];
+    for (let i = 1; i < work.length; i++) {
+        const c = work[i];
+        if (sn === 0)
+            return false;
+        if (fn % 2 === 1 || fn === sn) {
+            fr = nodeHash(c, fr);
+            sr = nodeHash(c, sr);
+            if (fn % 2 === 0) {
+                do {
+                    fn = Math.floor(fn / 2);
+                    sn = Math.floor(sn / 2);
+                } while (fn % 2 === 0 && fn !== 0);
+            }
+        }
+        else {
+            sr = nodeHash(sr, c);
+        }
+        fn = Math.floor(fn / 2);
+        sn = Math.floor(sn / 2);
+    }
+    return sn === 0 && equal(fr, firstRoot) && equal(sr, secondRoot);
+}

package/dist/serialize.d.ts

@@ -0,0 +1,35 @@
+import type { Checkpoint } from "./checkpoint.js";
+export interface InclusionBundle {
+    type: "inclusion";
+    index: number;
+    treeSize: number;
+    leaf: Uint8Array;
+    path: Uint8Array[];
+    root: Uint8Array;
+}
+export interface ConsistencyBundle {
+    type: "consistency";
+    first: number;
+    second: number;
+    firstRoot: Uint8Array;
+    secondRoot: Uint8Array;
+    path: Uint8Array[];
+}
+export declare function inclusionToJSON(b: InclusionBundle): string;
+export declare function consistencyToJSON(b: ConsistencyBundle): string;
+/**
+ * Verify a serialized proof bundle. This is the untrusted-input trust boundary:
+ * it is TOTAL — any malformed input (bad JSON, missing/typed-wrong fields,
+ * invalid hex, unknown type) yields `false` rather than throwing.
+ */
+export declare function verifyBundleJSON(json: string): boolean;
+export declare function checkpointToJSON(c: Checkpoint): string;
+export declare function checkpointFromJSON(s: string): Checkpoint;
+export declare function signedCheckpointToJSON(sc: {
+    checkpoint: Checkpoint;
+    signature: Uint8Array;
+}): string;
+export declare function signedCheckpointFromJSON(s: string): {
+    checkpoint: Checkpoint;
+    signature: Uint8Array;
+};

package/dist/serialize.js

@@ -0,0 +1,96 @@
+import { toHex, fromHex } from "./hash.js";
+import { verifyInclusion, verifyConsistency } from "./merkle.js";
+function hexStr(x) {
+    if (typeof x !== "string")
+        throw new TypeError("expected hex string");
+    return fromHex(x);
+}
+function hexArray(a) {
+    if (!Array.isArray(a))
+        throw new Error("expected array");
+    return a.map(hexStr);
+}
+export function inclusionToJSON(b) {
+    return JSON.stringify({
+        type: "inclusion", index: b.index, treeSize: b.treeSize,
+        leaf: toHex(b.leaf), path: b.path.map(toHex), root: toHex(b.root),
+    });
+}
+export function consistencyToJSON(b) {
+    return JSON.stringify({
+        type: "consistency", first: b.first, second: b.second,
+        firstRoot: toHex(b.firstRoot), secondRoot: toHex(b.secondRoot), path: b.path.map(toHex),
+    });
+}
+/** Parse a proof bundle and verify it self-consistently. Returns the verdict. */
+function uint(x) {
+    const v = Number(x);
+    return Number.isSafeInteger(v) && v >= 0 ? v : NaN;
+}
+/**
+ * Verify a serialized proof bundle. This is the untrusted-input trust boundary:
+ * it is TOTAL — any malformed input (bad JSON, missing/typed-wrong fields,
+ * invalid hex, unknown type) yields `false` rather than throwing.
+ */
+export function verifyBundleJSON(json) {
+    let o;
+    try {
+        o = JSON.parse(json);
+    }
+    catch {
+        return false;
+    }
+    try {
+        if (o?.type === "inclusion") {
+            const index = uint(o.index), treeSize = uint(o.treeSize);
+            if (Number.isNaN(index) || Number.isNaN(treeSize))
+                return false;
+            return verifyInclusion(hexArray(o.path), index, treeSize, hexStr(o.leaf), hexStr(o.root));
+        }
+        if (o?.type === "consistency") {
+            const first = uint(o.first), second = uint(o.second);
+            if (Number.isNaN(first) || Number.isNaN(second))
+                return false;
+            return verifyConsistency(hexArray(o.path), first, second, hexStr(o.firstRoot), hexStr(o.secondRoot));
+        }
+        return false; // unknown or missing bundle type
+    }
+    catch {
+        return false; // invalid hex, wrong field types, etc.
+    }
+}
+function reqUint(x, field) {
+    const v = Number(x);
+    if (!Number.isSafeInteger(v) || v < 0)
+        throw new Error(`invalid checkpoint field: ${field}`);
+    return v;
+}
+function reqFinite(x, field) {
+    const v = Number(x);
+    if (!Number.isFinite(v))
+        throw new Error(`invalid checkpoint field: ${field}`);
+    return v;
+}
+export function checkpointToJSON(c) {
+    return JSON.stringify({ size: c.size, rootHash: toHex(c.rootHash), timestamp: c.timestamp });
+}
+export function checkpointFromJSON(s) {
+    const o = JSON.parse(s);
+    return { size: reqUint(o.size, "size"), rootHash: hexStr(o.rootHash), timestamp: reqFinite(o.timestamp, "timestamp") };
+}
+export function signedCheckpointToJSON(sc) {
+    return JSON.stringify({
+        checkpoint: { size: sc.checkpoint.size, rootHash: toHex(sc.checkpoint.rootHash), timestamp: sc.checkpoint.timestamp },
+        signature: toHex(sc.signature),
+    });
+}
+export function signedCheckpointFromJSON(s) {
+    const o = JSON.parse(s);
+    const c = o.checkpoint;
+    if (typeof c !== "object" || c === null)
+        throw new Error("invalid signed checkpoint: missing checkpoint");
+    return {
+        checkpoint: { size: reqUint(c.size, "size"), rootHash: hexStr(c.rootHash), timestamp: reqFinite(c.timestamp, "timestamp") },
+        signature: hexStr(o.signature),
+    };
+}

package/dist/smt.d.ts

@@ -0,0 +1,19 @@
+/** Root of the empty map (= DEFAULTS[0]). */
+export declare function smtEmptyRoot(): Uint8Array;
+/** Derive a 32-byte key from an arbitrary string. */
+export declare function smtKey(s: string): Uint8Array;
+export declare class SparseMerkleTree {
+    private items;
+    private static hex;
+    private static checkKey;
+    get size(): number;
+    set(key: Uint8Array, value: Uint8Array): void;
+    delete(key: Uint8Array): void;
+    has(key: Uint8Array): boolean;
+    root(): Uint8Array;
+    proof(key: Uint8Array): Uint8Array[];
+}
+/** Verify that `key` maps to `value` under `root`. */
+export declare function verifyMapInclusion(key: Uint8Array, value: Uint8Array, proof: Uint8Array[], root: Uint8Array): boolean;
+/** Verify that `key` is absent under `root` (its leaf is the empty default). */
+export declare function verifyMapNonInclusion(key: Uint8Array, proof: Uint8Array[], root: Uint8Array): boolean;

package/dist/smt.js

@@ -0,0 +1,107 @@
+import { sha256, leafHash, nodeHash, equal, utf8 } from "./hash.js";
+/**
+ * Sparse Merkle Tree over a 256-bit key space (depth 256).
+ * - Empty subtree at level L is a precomputed default: D[256] = 32 zero bytes,
+ *   D[L] = nodeHash(D[L+1], D[L+1]).
+ * - An occupied leaf is `leafHash(value)` (domain-separated, never all-zero).
+ * - Supports inclusion AND non-inclusion proofs (a non-inclusion proof shows the
+ *   leaf at the key's path is the empty default).
+ */
+const KEY_BYTES = 32;
+const DEPTH = 256;
+const ZERO = new Uint8Array(KEY_BYTES);
+const DEFAULTS = (() => {
+    const d = new Array(DEPTH + 1);
+    d[DEPTH] = ZERO;
+    for (let L = DEPTH - 1; L >= 0; L--)
+        d[L] = nodeHash(d[L + 1], d[L + 1]);
+    return d;
+})();
+/** Root of the empty map (= DEFAULTS[0]). */
+export function smtEmptyRoot() {
+    return DEFAULTS[0];
+}
+/** Derive a 32-byte key from an arbitrary string. */
+export function smtKey(s) {
+    return sha256(utf8(s));
+}
+function bit(key, index) {
+    return (key[index >> 3] >> (7 - (index & 7))) & 1;
+}
+function computeRoot(level, items) {
+    if (items.length === 0)
+        return DEFAULTS[level];
+    if (level === DEPTH)
+        return items[0].leaf;
+    const left = [];
+    const right = [];
+    for (const it of items)
+        (bit(it.key, level) === 0 ? left : right).push(it);
+    return nodeHash(computeRoot(level + 1, left), computeRoot(level + 1, right));
+}
+function proofPath(level, items, key) {
+    if (level === DEPTH)
+        return [];
+    const left = [];
+    const right = [];
+    for (const it of items)
+        (bit(it.key, level) === 0 ? left : right).push(it);
+    if (bit(key, level) === 0)
+        return [computeRoot(level + 1, right), ...proofPath(level + 1, left, key)];
+    return [computeRoot(level + 1, left), ...proofPath(level + 1, right, key)];
+}
+/** Reconstruct the root from a leaf + 256 sibling hashes (top→bottom order). */
+function reconstruct(key, leaf, proof) {
+    if (proof.length !== DEPTH)
+        return null;
+    let cur = leaf;
+    for (let L = DEPTH - 1; L >= 0; L--) {
+        const sib = proof[L];
+        cur = bit(key, L) === 0 ? nodeHash(cur, sib) : nodeHash(sib, cur);
+    }
+    return cur;
+}
+export class SparseMerkleTree {
+    items = new Map();
+    static hex(k) {
+        return Buffer.from(k).toString("hex");
+    }
+    static checkKey(key) {
+        if (key.length !== KEY_BYTES)
+            throw new RangeError(`key must be ${KEY_BYTES} bytes`);
+    }
+    get size() {
+        return this.items.size;
+    }
+    set(key, value) {
+        SparseMerkleTree.checkKey(key);
+        this.items.set(SparseMerkleTree.hex(key), { key: Uint8Array.from(key), leaf: leafHash(value) });
+    }
+    delete(key) {
+        this.items.delete(SparseMerkleTree.hex(key));
+    }
+    has(key) {
+        return this.items.has(SparseMerkleTree.hex(key));
+    }
+    root() {
+        return computeRoot(0, [...this.items.values()]);
+    }
+    proof(key) {
+        SparseMerkleTree.checkKey(key);
+        return proofPath(0, [...this.items.values()], key);
+    }
+}
+/** Verify that `key` maps to `value` under `root`. */
+export function verifyMapInclusion(key, value, proof, root) {
+    if (key.length !== KEY_BYTES)
+        return false;
+    const r = reconstruct(key, leafHash(value), proof);
+    return r !== null && equal(r, root);
+}
+/** Verify that `key` is absent under `root` (its leaf is the empty default). */
+export function verifyMapNonInclusion(key, proof, root) {
+    if (key.length !== KEY_BYTES)
+        return false;
+    const r = reconstruct(key, ZERO, proof);
+    return r !== null && equal(r, root);
+}

package/dist/store.d.ts

@@ -0,0 +1,38 @@
+/** Append-only entry storage. Implementations must preserve insertion order. */
+export interface Store {
+    size(): number;
+    get(index: number): Uint8Array;
+    append(entry: Uint8Array): number;
+    all(): Uint8Array[];
+}
+export declare class MemoryStore implements Store {
+    private entries;
+    constructor(initial?: Uint8Array[]);
+    size(): number;
+    get(index: number): Uint8Array;
+    append(entry: Uint8Array): number;
+    all(): Uint8Array[];
+}
+/** File-backed store. Persists entries as a JSON array of hex strings.
+ *  Note: each append rewrites the whole file (O(n)); fine at library scale.
+ *  Concurrency: appends across processes are serialized with an exclusive
+ *  lock file, so concurrent writers cannot lose or corrupt entries. */
+export declare class FileStore implements Store {
+    private readonly path;
+    private entries;
+    constructor(path: string);
+    /** (Re)read entries from disk; throws on a corrupt store (fail-closed). */
+    private load;
+    /** Run `fn` while holding an exclusive lock file (O_CREAT|O_EXCL), with a
+     *  bounded wait and stale-lock recovery so a crashed writer can't deadlock. */
+    private withLock;
+    /** Atomic + durable: write a temp file, fsync it, then rename over the target.
+     *  A crash mid-write can never leave a partially written or truncated store.
+     *  The directory is then fsync'd so the rename itself survives power loss
+     *  (best-effort: silently skipped on platforms without directory fsync). */
+    private persist;
+    size(): number;
+    get(index: number): Uint8Array;
+    append(entry: Uint8Array): number;
+    all(): Uint8Array[];
+}

package/dist/store.js

@@ -0,0 +1,147 @@
+import { readFileSync, existsSync, openSync, writeSync, fsyncSync, closeSync, renameSync, unlinkSync, statSync } from "node:fs";
+import { dirname } from "node:path";
+import { toHex, fromHex } from "./hash.js";
+const LOCK_STALE_MS = 10_000;
+const LOCK_TIMEOUT_MS = 10_000;
+const LOCK_POLL_MS = 10;
+/** Synchronous sleep with no busy-spin (zero-dependency). */
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+function copy(e) {
+    return Uint8Array.from(e);
+}
+export class MemoryStore {
+    entries;
+    constructor(initial) {
+        this.entries = initial ? initial.map(copy) : [];
+    }
+    size() {
+        return this.entries.length;
+    }
+    get(index) {
+        const e = this.entries[index];
+        if (!e)
+            throw new RangeError(`index ${index} out of range for size ${this.entries.length}`);
+        return copy(e);
+    }
+    append(entry) {
+        this.entries.push(copy(entry));
+        return this.entries.length;
+    }
+    all() {
+        return this.entries.map(copy);
+    }
+}
+/** File-backed store. Persists entries as a JSON array of hex strings.
+ *  Note: each append rewrites the whole file (O(n)); fine at library scale.
+ *  Concurrency: appends across processes are serialized with an exclusive
+ *  lock file, so concurrent writers cannot lose or corrupt entries. */
+export class FileStore {
+    path;
+    entries = [];
+    constructor(path) {
+        this.path = path;
+        this.load();
+    }
+    /** (Re)read entries from disk; throws on a corrupt store (fail-closed). */
+    load() {
+        if (!existsSync(this.path)) {
+            this.entries = [];
+            return;
+        }
+        const arr = JSON.parse(readFileSync(this.path, "utf8"));
+        if (!Array.isArray(arr))
+            throw new Error(`corrupt store: ${this.path}`);
+        this.entries = arr.map((h) => fromHex(String(h)));
+    }
+    /** Run `fn` while holding an exclusive lock file (O_CREAT|O_EXCL), with a
+     *  bounded wait and stale-lock recovery so a crashed writer can't deadlock. */
+    withLock(fn) {
+        const lock = `${this.path}.lock`;
+        const deadline = Date.now() + LOCK_TIMEOUT_MS;
+        for (;;) {
+            try {
+                closeSync(openSync(lock, "wx"));
+                break;
+            }
+            catch (e) {
+                if (e.code !== "EEXIST")
+                    throw e;
+                try {
+                    if (Date.now() - statSync(lock).mtimeMs > LOCK_STALE_MS) {
+                        unlinkSync(lock); // steal a stale lock left by a crashed writer
+                        continue;
+                    }
+                }
+                catch {
+                    continue; // lock vanished between stat and use; retry immediately
+                }
+                if (Date.now() > deadline)
+                    throw new Error(`timeout acquiring lock: ${lock}`);
+                sleepSync(LOCK_POLL_MS);
+            }
+        }
+        try {
+            return fn();
+        }
+        finally {
+            try {
+                unlinkSync(lock);
+            }
+            catch {
+                /* already removed */
+            }
+        }
+    }
+    /** Atomic + durable: write a temp file, fsync it, then rename over the target.
+     *  A crash mid-write can never leave a partially written or truncated store.
+     *  The directory is then fsync'd so the rename itself survives power loss
+     *  (best-effort: silently skipped on platforms without directory fsync). */
+    persist() {
+        const tmp = `${this.path}.tmp`;
+        const data = Buffer.from(JSON.stringify(this.entries.map(toHex)));
+        const fd = openSync(tmp, "w");
+        try {
+            writeSync(fd, data);
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        renameSync(tmp, this.path);
+        try {
+            const dir = openSync(dirname(this.path) || ".", "r");
+            try {
+                fsyncSync(dir);
+            }
+            finally {
+                closeSync(dir);
+            }
+        }
+        catch {
+            // directory fsync is unsupported on some platforms (e.g. Windows); the
+            // temp+fsync+rename above already guarantees the store is never corrupt.
+        }
+    }
+    size() {
+        return this.entries.length;
+    }
+    get(index) {
+        const e = this.entries[index];
+        if (!e)
+            throw new RangeError(`index ${index} out of range for size ${this.entries.length}`);
+        return copy(e);
+    }
+    append(entry) {
+        return this.withLock(() => {
+            this.load(); // pick up entries appended by other processes since we loaded
+            this.entries.push(copy(entry));
+            this.persist();
+            return this.entries.length;
+        });
+    }
+    all() {
+        return this.entries.map(copy);
+    }
+}

package/docs/adr/0001-hashing.md

@@ -0,0 +1,20 @@
+# ADR-0001: RFC 6962 domain-separated SHA-256 hashing
+
+**Status**: Accepted · **Date**: 2026-05-31 · **Decider**: Aris Rhiannon
+
+## Context
+We need a hash construction for the Merkle tree that is interoperable, well-reviewed, and
+resistant to second-preimage/leaf-node confusion attacks.
+
+## Decision
+Adopt RFC 6962 §2.1 exactly: `leafHash = SHA256(0x00 ‖ entry)`,
+`nodeHash = SHA256(0x01 ‖ left ‖ right)`, `emptyRoot = SHA256("")`. SHA-256 comes from the
+platform `node:crypto` (works on Node and Bun); no third-party crypto.
+
+## Consequences
+- **+** Interoperable with the large RFC 6962/9162 ecosystem; testable against the spec.
+- **+** Domain separation prevents leaf/node confusion (a leaf hash can never be mistaken
+  for an interior node), defeating a class of second-preimage attacks.
+- **+** Zero runtime dependencies; trivially auditable.
+- **−** SHA-256 is fixed for v1 (no agility). Acceptable; revisit only if a successor
+  standard emerges. Domain tags make a future migration straightforward.

package/docs/adr/0002-storage-and-signing.md

@@ -0,0 +1,22 @@
+# ADR-0002: Pluggable storage + Ed25519 signed checkpoints
+
+**Status**: Accepted · **Date**: 2026-05-31 · **Decider**: Aris Rhiannon
+
+## Context
+The library must stay self-contained (no DB/server) yet support persistence, and let a log
+publish a portable, independently verifiable commitment to its state.
+
+## Decision
+- Define a tiny `Store` interface (`size/get/append/all`) with `MemoryStore` and
+  `FileStore` (JSON array of hex) implementations; `Log` depends only on the interface.
+- A `Checkpoint` is `{size, rootHash, timestamp}` with a **deterministic** byte encoding
+  (`veritrail-checkpoint\n{size}\n{rootHex}\n{timestamp}\n`) used as the signing payload.
+- Signatures use **Ed25519** via `node:crypto` (`sign(null, …)`); keys are `KeyObject`s
+  with PEM import/export for portability.
+
+## Consequences
+- **+** Embeddable; users can supply their own `Store` (e.g. SQLite) without touching core.
+- **+** Deterministic encoding ⇒ signatures are reproducible and unambiguous.
+- **+** Ed25519: small, fast, misuse-resistant, built into the platform.
+- **−** `FileStore` rewrites the whole file per append (O(n)); fine for moderate logs.
+  A tiled/append-only on-disk format is future work.

package/docs/adr/0003-sparse-merkle-tree.md

@@ -0,0 +1,22 @@
+# ADR-0003: Sparse Merkle tree for the verifiable map
+
+**Status**: Accepted · **Date**: 2026-05-31 · **Decider**: Aris Rhiannon
+
+## Context
+We want a verifiable key→value map supporting both inclusion and **non-inclusion** proofs,
+without materializing a 2^256-node tree.
+
+## Decision
+Use a fixed-depth (256) sparse Merkle tree keyed by a 32-byte key (`smtKey = SHA256(s)`).
+Empty subtrees collapse to precomputed default nodes: `D[256] = 32 zero bytes`,
+`D[L] = nodeHash(D[L+1], D[L+1])`. Occupied leaves are `leafHash(value)` (never all-zero,
+so an occupied leaf is distinguishable from the empty default). Roots and proofs are
+computed by recursing only over populated branches; a non-inclusion proof reconstructs the
+root with the empty-leaf default at the key's path.
+
+## Consequences
+- **+** Inclusion and non-inclusion proofs share one verification routine.
+- **+** Order-independent: the root depends only on the key/value *set*.
+- **+** Reuses the same `nodeHash`/`leafHash` domain separation as the log.
+- **−** Proof generation recomputes subtree roots (O(k·depth)); fine at library scale.
+  Caching/persistent nodes are future work.

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "veritrail",
+  "version": "0.2.0",
+  "description": "Tamper-evident, verifiable append-only logs and maps for TypeScript. RFC 6962 Merkle trees with inclusion & consistency proofs, Ed25519-signed checkpoints, and a sparse Merkle verifiable map. Zero dependencies.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Aris Rhiannon",
+  "homepage": "https://github.com/ArisRhiannon/veritrail#readme",
+  "repository": { "type": "git", "url": "git+https://github.com/ArisRhiannon/veritrail.git" },
+  "bugs": { "url": "https://github.com/ArisRhiannon/veritrail/issues" },
+  "keywords": ["merkle-tree", "transparency-log", "rfc6962", "rfc9162", "tamper-evident", "inclusion-proof", "consistency-proof", "sparse-merkle-tree", "audit-log", "verifiable", "zero-dependency", "typescript"],
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" } },
+  "bin": { "veritrail": "dist/cli.js" },
+  "files": ["dist", "docs", "LICENSE", "README.md"],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "check": "bun run typecheck && bun test",
+    "prepack": "tsc -p tsconfig.build.json"
+  },
+  "engines": { "bun": ">=1.1.0", "node": ">=20" },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/bun": "^1.1.0",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  }
+}