@coffre/core 0.14.5 → 0.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,197 @@
1
+ import { HASH_SIZE, nodeHash, treeHash, type Hash, type Nodes } from './tree.ts';
2
+
3
+ /**
4
+ * The tree's storage: tiles, as Go's sumdb and C2SP tlog-tiles lay them out,
5
+ * of height 8. The tile at (level t, index i) holds up to 256 hashes: the
6
+ * nodes at tree level 8t numbered i·256 onwards, concatenated. A level-0 tile
7
+ * holds leaf hashes; a level-1 tile, the roots of 256-leaf subtrees; and so
8
+ * on. Any perfect subtree's hash is in one tile or is at most 128 hashes away
9
+ * from one, so a proof reads one tile per 8 levels: 4 tiles at 2^32 leaves.
10
+ *
11
+ * A tile's hashes never change once written, only grow (the partial tile at
12
+ * the tree's right edge), so a tile is read for any older tree size by taking
13
+ * its prefix.
14
+ */
15
+ export const HEIGHT = 8;
16
+ export const WIDTH = 256;
17
+
18
+ export type TileKey = { level: number; index: number };
19
+ export type Tile = TileKey & { hashes: Buffer };
20
+
21
+ export const tileKey = (level: number, index: number) => `${level}/${index}`;
22
+
23
+ /** Which tile, and where in it, holds what node (level, index) is computed from. */
24
+ export function tileOf(level: number, index: number): { tile: TileKey; offset: number; count: number } {
25
+ const t = Math.floor(level / HEIGHT);
26
+ const count = 2 ** (level - t * HEIGHT);
27
+ const first = index * count;
28
+ return { tile: { level: t, index: Math.floor(first / WIDTH) }, offset: first % WIDTH, count };
29
+ }
30
+
31
+ /**
32
+ * The leaves a tile's hashes stand for: [first, end). Tiles are partitioned by
33
+ * it (a level-0 tile by the 256 leaves it holds), so retention drops whole
34
+ * ranges of them instead of deleting rows.
35
+ */
36
+ export function tileLeaves(t: TileKey): { first: number; end: number } {
37
+ const span = 2 ** (HEIGHT * (t.level + 1));
38
+ return { first: t.index * span, end: (t.index + 1) * span };
39
+ }
40
+
41
+ /**
42
+ * Whether a tile is still read once retention has cut the tree below leaf
43
+ * `cut`: proofs of leaves at or above the cut, and consistency proofs from
44
+ * sizes at or above it, read only tiles that reach past it, which at each
45
+ * level is the tile holding the cut and those after it. Every tile wholly
46
+ * below the cut can go, at every level: about one tile per level stays
47
+ * where a day of tiles would.
48
+ */
49
+ export const keptAbove = (t: TileKey, cut: number): boolean => tileLeaves(t).end > cut;
50
+
51
+ /** A `Nodes` over a set of tiles, keyed by `tileKey`: each node from the hashes of its tile. */
52
+ export function nodesFrom(tiles: ReadonlyMap<string, Buffer>): Nodes {
53
+ return (level, index) => {
54
+ const { tile, offset, count } = tileOf(level, index);
55
+ const hashes = tiles.get(tileKey(tile.level, tile.index));
56
+ if (hashes === undefined || hashes.length < (offset + count) * HASH_SIZE) {
57
+ throw new Error(`tile ${tile.level}/${tile.index} lacks node ${level}/${index}`);
58
+ }
59
+ const layer: Hash[] = [];
60
+ for (let i = 0; i < count; i += 1) layer.push(hashes.subarray((offset + i) * HASH_SIZE, (offset + i + 1) * HASH_SIZE));
61
+ return hashUp(layer);
62
+ };
63
+ }
64
+
65
+ /** The root of a perfect subtree from its 2^k bottom hashes. */
66
+ function hashUp(hashes: readonly Hash[]): Hash {
67
+ let layer = hashes;
68
+ while (layer.length > 1) {
69
+ const up: Hash[] = [];
70
+ for (let i = 0; i < layer.length; i += 2) up.push(nodeHash(layer[i]!, layer[i + 1]!));
71
+ layer = up;
72
+ }
73
+ return Buffer.from(layer[0]!);
74
+ }
75
+
76
+ /** The tiles a computation over `Nodes` reads: run it once against a recorder, then fetch them all in one query. */
77
+ export function tilesFor(compute: (nodes: Nodes) => unknown): TileKey[] {
78
+ const seen = new Map<string, TileKey>();
79
+ compute((level, index) => {
80
+ const { tile } = tileOf(level, index);
81
+ seen.set(tileKey(tile.level, tile.index), tile);
82
+ return Buffer.alloc(HASH_SIZE);
83
+ });
84
+ return [...seen.values()];
85
+ }
86
+
87
+ export function tileMap(tiles: readonly Tile[]): Map<string, Buffer> {
88
+ return new Map(tiles.map((t) => [tileKey(t.level, t.index), t.hashes]));
89
+ }
90
+
91
+ /** The tiles at the right edge of a tree of `size` leaves, one per level, with their widths: all the state appending needs. */
92
+ export function edgeOf(size: number): (TileKey & { width: number })[] {
93
+ const edge: (TileKey & { width: number })[] = [];
94
+ for (let t = 0; ; t += 1) {
95
+ const below = Math.floor(size / 2 ** (t * HEIGHT));
96
+ edge.push({ level: t, index: Math.floor(below / WIDTH), width: below % WIDTH });
97
+ if (below < WIDTH) return edge;
98
+ }
99
+ }
100
+
101
+ /**
102
+ * The tree's growing edge, in memory: the partial tile at each level.
103
+ * Appending leaves fills level 0; each tile that fills up pushes its root into
104
+ * the level above. What changed comes back as tiles to write: every tile
105
+ * filled, and every partial edge tile that grew.
106
+ */
107
+ export class Edge {
108
+ size: number;
109
+ private tiles: Hash[][];
110
+
111
+ private constructor(size: number, tiles: Hash[][]) {
112
+ this.size = size;
113
+ this.tiles = tiles;
114
+ }
115
+
116
+ static empty(): Edge {
117
+ return new Edge(0, [[]]);
118
+ }
119
+
120
+ /** From the stored edge tiles of a tree of `size` leaves (`edgeOf(size)`), each cut to its width. */
121
+ static load(size: number, stored: ReadonlyMap<string, Buffer>): Edge {
122
+ const tiles = edgeOf(size).map(({ level, index, width }) => {
123
+ if (width === 0) return [];
124
+ const hashes = stored.get(tileKey(level, index));
125
+ if (hashes === undefined || hashes.length < width * HASH_SIZE) throw new Error(`edge tile ${level}/${index} missing or short`);
126
+ return Array.from({ length: width }, (_, i) => Buffer.from(hashes.subarray(i * HASH_SIZE, (i + 1) * HASH_SIZE)));
127
+ });
128
+ return new Edge(size, tiles);
129
+ }
130
+
131
+ /** A copy to append to, so a failed write leaves this edge at the head it was. */
132
+ clone(): Edge {
133
+ return new Edge(this.size, this.tiles.map((t) => [...t]));
134
+ }
135
+
136
+ append(leaves: readonly Hash[]): Tile[] {
137
+ const changed: Tile[] = [];
138
+ // Levels whose partial tile grew: written as they stand once every leaf is in.
139
+ const grew = new Set<number>();
140
+ for (const leaf of leaves) {
141
+ let hash = leaf;
142
+ for (let t = 0; ; t += 1) {
143
+ const tile = (this.tiles[t] ??= []);
144
+ tile.push(hash);
145
+ if (tile.length < WIDTH) {
146
+ grew.add(t);
147
+ break;
148
+ }
149
+ // A full tile is written now and never again; its root goes up a level.
150
+ changed.push({ level: t, index: Math.floor(this.size / 2 ** ((t + 1) * HEIGHT)), hashes: Buffer.concat(tile) });
151
+ grew.delete(t);
152
+ hash = hashUp(tile);
153
+ this.tiles[t] = [];
154
+ }
155
+ this.size += 1;
156
+ }
157
+ for (const t of grew) changed.push({ level: t, index: Math.floor(this.size / 2 ** ((t + 1) * HEIGHT)), hashes: Buffer.concat(this.tiles[t]!) });
158
+ return changed;
159
+ }
160
+
161
+ /** The tree head now. */
162
+ root(): Hash {
163
+ return treeHash(nodesFrom(tileMap(this.edgeTiles())), this.size);
164
+ }
165
+
166
+ /**
167
+ * The tile at the right edge of each level, as it stands. With the tiles an append filled, they hold every node a
168
+ * proof of a leaf that append added reads: the tile of the leaf's ancestor at each level is one of them, and so is
169
+ * every tile to its right.
170
+ */
171
+ edgeTiles(): Tile[] {
172
+ return edgeOf(this.size).map(({ level, index }) => ({ level, index, hashes: Buffer.concat(this.tiles[level] ?? []) }));
173
+ }
174
+ }
175
+
176
+ /** Go's tile path, `tile/8/<L>/<N>[.p/<W>]`, N in groups of three digits (x001/x234/067). */
177
+ export function tilePath(t: TileKey, width: number): string {
178
+ let n = String(t.index);
179
+ const groups: string[] = [];
180
+ while (n.length > 3) {
181
+ groups.unshift(n.slice(-3));
182
+ n = n.slice(0, -3);
183
+ }
184
+ const parts = [n.padStart(3, '0'), ...groups].map((g, i, all) => (i < all.length - 1 ? `x${g}` : g));
185
+ return `tile/${HEIGHT}/${t.level}/${parts.join('/')}${width < WIDTH ? `.p/${width}` : ''}`;
186
+ }
187
+
188
+ export function parseTilePath(path: string): (TileKey & { width: number }) | null {
189
+ const m = /^tile\/8\/(\d{1,2})\/((?:x\d{3}\/)*\d{3})(?:\.p\/(\d{1,3}))?$/.exec(path);
190
+ if (m === null) return null;
191
+ // A partial tile holds 1 to 255 hashes; a full one has no `.p` part.
192
+ const width = m[3] === undefined ? WIDTH : Number(m[3]);
193
+ if (width < 1 || (m[3] !== undefined && width >= WIDTH)) return null;
194
+ const tile = { level: Number(m[1]), index: Number(m[2]!.replaceAll('x', '').replaceAll('/', '')), width };
195
+ // Canonical only, as Go writes them: no leading zeros in the level, no padded groups, so one tile has one path.
196
+ return Number.isSafeInteger(tile.index) && tilePath(tile, width) === path ? tile : null;
197
+ }
@@ -0,0 +1,163 @@
1
+ import { createHash } from 'node:crypto';
2
+
3
+ /**
4
+ * RFC 9162's Merkle tree (Certificate Transparency 2.0, the same tree as RFC
5
+ * 6962), byte for byte: a leaf hashes as SHA-256(0x00 || data), a node as
6
+ * SHA-256(0x01 || left || right), and a tree of n leaves splits at the largest
7
+ * power of two below n. Go's golang.org/x/mod/sumdb/tlog checks what this
8
+ * produces (packages/core/test/go, docs/design/audit-tree.md).
9
+ *
10
+ * Every hash here comes from `Nodes`, which answers for perfect subtrees only
11
+ * (2^level leaves starting at leaf index·2^level). Tiles store those; a proof
12
+ * never needs another kind.
13
+ *
14
+ * Sizes and indexes are plain numbers: exact to 2^53 leaves, 285,000 years at
15
+ * 1,000 a second. No bitwise operator touches them, since JavaScript's cut to
16
+ * 32 bits, and a log passes 2^32 leaves in 50 days at that rate.
17
+ */
18
+ export type Hash = Buffer;
19
+
20
+ export const HASH_SIZE = 32;
21
+
22
+ const LEAF = Buffer.from([0]);
23
+ const NODE = Buffer.from([1]);
24
+
25
+ export function leafHash(data: Uint8Array): Hash {
26
+ return createHash('sha256').update(LEAF).update(data).digest();
27
+ }
28
+
29
+ export function nodeHash(left: Hash, right: Hash): Hash {
30
+ return createHash('sha256').update(NODE).update(left).update(right).digest();
31
+ }
32
+
33
+ /** The head of the empty tree: SHA-256 of nothing. */
34
+ export const EMPTY_ROOT: Hash = createHash('sha256').digest();
35
+
36
+ /** The hash of the perfect subtree of 2^level leaves starting at leaf index·2^level. */
37
+ export type Nodes = (level: number, index: number) => Hash;
38
+
39
+ /** The largest power of two strictly below n (n ≥ 2). */
40
+ function split(n: number): number {
41
+ let k = 1;
42
+ while (k * 2 < n) k *= 2;
43
+ return k;
44
+ }
45
+
46
+ const log2 = (n: number) => Math.round(Math.log2(n));
47
+
48
+ export const isPowerOfTwo = (n: number) => n > 0 && 2 ** log2(n) === n;
49
+
50
+ /** MTH(D[start:start+n]): the hash of any range, from the perfect subtrees it decomposes into. */
51
+ export function rangeHash(nodes: Nodes, start: number, n: number): Hash {
52
+ if (n === 0) return EMPTY_ROOT;
53
+ if (isPowerOfTwo(n) && start % n === 0) return nodes(log2(n), start / n);
54
+ const k = split(n);
55
+ return nodeHash(rangeHash(nodes, start, k), rangeHash(nodes, start + k, n - k));
56
+ }
57
+
58
+ /** The tree head: MTH of the first `size` leaves. */
59
+ export function treeHash(nodes: Nodes, size: number): Hash {
60
+ return rangeHash(nodes, 0, size);
61
+ }
62
+
63
+ /** RFC 9162 2.1.3.1, PATH(m, D[n]): the inclusion proof of leaf m in the tree of n leaves, leaf to root. */
64
+ export function inclusionProof(nodes: Nodes, m: number, n: number): Hash[] {
65
+ if (!Number.isSafeInteger(m) || m < 0 || m >= n) throw new Error(`leaf ${m} is not in a tree of ${n}`);
66
+ const path: Hash[] = [];
67
+ const walk = (m: number, start: number, n: number): void => {
68
+ if (n === 1) return;
69
+ const k = split(n);
70
+ if (m < k) {
71
+ walk(m, start, k);
72
+ path.push(rangeHash(nodes, start + k, n - k));
73
+ } else {
74
+ walk(m - k, start + k, n - k);
75
+ path.push(rangeHash(nodes, start, k));
76
+ }
77
+ };
78
+ walk(m, 0, n);
79
+ return path;
80
+ }
81
+
82
+ /** RFC 9162 2.1.4.1, PROOF(m, D[n]): that the tree of m leaves is a prefix of the tree of n. */
83
+ export function consistencyProof(nodes: Nodes, m: number, n: number): Hash[] {
84
+ if (!Number.isSafeInteger(m) || m < 0 || m > n) throw new Error(`no consistency from ${m} to ${n}`);
85
+ if (m === 0 || m === n) return [];
86
+ const path: Hash[] = [];
87
+ const sub = (m: number, start: number, n: number, whole: boolean): void => {
88
+ if (m === n) {
89
+ if (!whole) path.push(rangeHash(nodes, start, n));
90
+ return;
91
+ }
92
+ const k = split(n);
93
+ if (m <= k) {
94
+ sub(m, start, k, whole);
95
+ path.push(rangeHash(nodes, start + k, n - k));
96
+ } else {
97
+ sub(m - k, start + k, n - k, false);
98
+ path.push(rangeHash(nodes, start, k));
99
+ }
100
+ };
101
+ sub(m, 0, n, true);
102
+ return path;
103
+ }
104
+
105
+ /** RFC 9162 2.1.3.2: whether `proof` shows `leaf` at index m of the tree of n leaves whose head is `root`. */
106
+ export function verifyInclusion(leaf: Hash, m: number, n: number, proof: readonly Hash[], root: Hash): boolean {
107
+ if (!Number.isSafeInteger(m) || !Number.isSafeInteger(n) || m < 0 || m >= n) return false;
108
+ let fn = m;
109
+ let sn = n - 1;
110
+ let r = leaf;
111
+ for (const p of proof) {
112
+ if (sn === 0) return false;
113
+ if (fn % 2 === 1 || fn === sn) {
114
+ r = nodeHash(p, r);
115
+ if (fn % 2 === 0) {
116
+ while (fn % 2 === 0 && fn !== 0) {
117
+ fn = Math.floor(fn / 2);
118
+ sn = Math.floor(sn / 2);
119
+ }
120
+ }
121
+ } else {
122
+ r = nodeHash(r, p);
123
+ }
124
+ fn = Math.floor(fn / 2);
125
+ sn = Math.floor(sn / 2);
126
+ }
127
+ return sn === 0 && r.equals(root);
128
+ }
129
+
130
+ /** RFC 9162 2.1.4.2: whether `proof` shows the tree of m leaves (head `first`) a prefix of the tree of n (head `second`). */
131
+ export function verifyConsistency(m: number, n: number, first: Hash, second: Hash, proof: readonly Hash[]): boolean {
132
+ if (!Number.isSafeInteger(m) || !Number.isSafeInteger(n) || m < 0 || m > n) return false;
133
+ if (m === 0) return proof.length === 0 && first.equals(EMPTY_ROOT) && (n > 0 || second.equals(EMPTY_ROOT));
134
+ if (m === n) return proof.length === 0 && first.equals(second);
135
+ const path = isPowerOfTwo(m) ? [first, ...proof] : [...proof];
136
+ if (path.length === 0) return false;
137
+ let fn = m - 1;
138
+ let sn = n - 1;
139
+ while (fn % 2 === 1) {
140
+ fn = Math.floor(fn / 2);
141
+ sn = Math.floor(sn / 2);
142
+ }
143
+ let fr = path[0]!;
144
+ let sr = path[0]!;
145
+ for (const c of path.slice(1)) {
146
+ if (sn === 0) return false;
147
+ if (fn % 2 === 1 || fn === sn) {
148
+ fr = nodeHash(c, fr);
149
+ sr = nodeHash(c, sr);
150
+ if (fn % 2 === 0) {
151
+ while (fn % 2 === 0 && fn !== 0) {
152
+ fn = Math.floor(fn / 2);
153
+ sn = Math.floor(sn / 2);
154
+ }
155
+ }
156
+ } else {
157
+ sr = nodeHash(sr, c);
158
+ }
159
+ fn = Math.floor(fn / 2);
160
+ sn = Math.floor(sn / 2);
161
+ }
162
+ return sn === 0 && fr.equals(first) && sr.equals(second);
163
+ }