eventsourcingdb-merkle 2.0.0 → 3.0.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.
package/README.md CHANGED
@@ -20,9 +20,22 @@ Or use it directly with `npx` without installing:
20
20
  npx eventsourcingdb-merkle [COMMAND]
21
21
  ```
22
22
 
23
+ ### Choosing the Source
24
+
25
+ Every command that reads events reads them either from a backup file, which you name with `--backup`, or from a running EventSourcingDB, which you name with `--esdb-url` and its API token with `--esdb-api-token`:
26
+
27
+ ```shell
28
+ eventsourcingdb-merkle validate-chain --backup=backup.json
29
+ eventsourcingdb-merkle validate-chain --esdb-url=http://localhost:3000 --esdb-api-token="$ESDB_API_TOKEN"
30
+ ```
31
+
32
+ A backup freezes the events it holds, and it can be handed on to someone who should verify it. A running database needs no backup first. Note that EventSourcingDB has no API token that only reads, so whoever reads a running database holds a token that could write as well. Passing the token from a variable, as above, keeps it out of the history of your shell.
33
+
34
+ The tool reads a running database through the client SDK of EventSourcingDB, which uses the v2 API where the server offers it, from release 1.3 on. There, a read that is cut short fails rather than passing as complete. A server before release 1.3 offers only the v1 API, where the two cannot be told apart. The SDK verifies the hash of each event itself, so where one does not match, the tool names the stored hash, but not the one the SDK calculated.
35
+
23
36
  ### Validating Event Chains
24
37
 
25
- To ensure that a backup file has not been tampered with or corrupted, call the `validate-chain` command and provide the path to your backup file with `--backup`. The command verifies that each event's hash is correctly calculated, that the predecessor hash of each event matches the hash of the previous event, and that the first event has a null predecessor hash as expected:
38
+ To ensure that a backup file has not been tampered with or corrupted, call the `validate-chain` command and name the backup file or the database, as described above. The command verifies that each event's hash is correctly calculated, that the predecessor hash of each event matches the hash of the previous event, and that the first event has a null predecessor hash as expected:
26
39
 
27
40
  ```shell
28
41
  eventsourcingdb-merkle validate-chain --backup=backup.json
@@ -57,7 +70,7 @@ Such an event cannot be verified, which is not the same as being tampered with,
57
70
 
58
71
  ### Calculating the Merkle Root
59
72
 
60
- To calculate the Merkle root for all events in a backup file, call the `merkle-root` command and provide the path to your backup file with `--backup`. The Merkle root is a single hash that represents the entire event chain and can be used to verify the integrity of the backup:
73
+ To calculate the Merkle root for all events in a backup file, call the `merkle-root` command and name the backup file or the database. The Merkle root is a single hash that represents the entire event chain and can be used to verify the integrity of the backup:
61
74
 
62
75
  ```shell
63
76
  eventsourcingdb-merkle merkle-root --backup=backup.json
@@ -66,28 +79,49 @@ eventsourcingdb-merkle merkle-root --backup=backup.json
66
79
  The command outputs the Merkle root, the total number of events, and the ID of the last event it covers:
67
80
 
68
81
  ```
69
- Merkle Root: d1f6713af7ba3896ff238bb51f3986b2bad53b09bda7f23370e0a8b6eb97eeab
82
+ Merkle Root: esdb:merkle:v2:d1f6713af7ba3896ff238bb51f3986b2bad53b09bda7f23370e0a8b6eb97eeab
70
83
  Total events: 4
71
84
  Last event ID: 3
72
85
  ```
73
86
 
74
87
  #### Calculating the Merkle Root of an Earlier State
75
88
 
76
- A root that you published once has to be calculated again later, for instance to generate proofs against it. Since events are never changed, a newer backup holds the events of an older one, followed by those written since. Pass the last event ID that the root covered with `--last-event-id`, and the command calculates the root over the events up to it, which is the root of the older backup:
89
+ A root that you published once has to be calculated again later, for instance to generate proofs against it. Since events are never changed, a newer backup, or the database itself, holds the events of an older backup, followed by those written since. Pass the last event ID that the root covered with `--last-event-id`, and the command calculates the root over the events up to it, which is the root of the older backup:
77
90
 
78
91
  ```shell
79
92
  eventsourcingdb-merkle merkle-root --backup=backup-2025.json --last-event-id=3
80
93
  ```
81
94
 
82
- So you do not have to keep the older backup to prove against its root. If the backup holds no event with that ID, the command refuses rather than calculating a root over other events.
95
+ So you do not have to keep the older backup to prove against its root. If the backup or the database holds no event with that ID, the command refuses rather than calculating a root over other events.
96
+
97
+ #### Salting the Leaves
98
+
99
+ A proof names the hashes next to the path from its event to the root, and the first of them belongs to a neighboring event. That hash does not reveal the event, but whoever holds the proof and has a guess about the neighbor, such as its type, its subject, its time, and its data, can calculate its hash and so check the guess. Where your events can be guessed like that, salt the leaves of the tree: a random value in front of every leaf, which only a proof of that leaf discloses, makes the other hashes in a proof tell nothing.
100
+
101
+ The tool derives the salt of every leaf from a key, so that no salt has to be kept. Generate the key once, and pass it with `--salt-key-file` whenever you calculate the root, or a proof against it:
102
+
103
+ ```shell
104
+ eventsourcingdb-merkle generate-salt-key --output=merkle.key
105
+ eventsourcingdb-merkle merkle-root --backup=backup.json --salt-key-file=merkle.key
106
+ ```
107
+
108
+ The key file holds 64 hexadecimal digits. `generate-salt-key` never overwrites a file, and it lets nobody write the key, and on Linux and macOS, only the owner of the file read it. Windows knows only whether a file is read-only, so there, who can read the key follows from the permissions of its folder. Keep the key as long as the root, and as safely as a password: a root calculated with it is calculated again with that key only, so without it, no further proof can be generated for the root, and whoever has it can calculate the salt of every leaf. A proof carries the salt of its own leaf, so verifying it needs no key.
109
+
110
+ #### Calculating a Root of Version 1
111
+
112
+ Releases before 3.0 built the tree in another way, which is version 1 of the tree: it hashes leaves and inner nodes alike, and pairs the last node of a level with itself where it has no partner, so that a list of hashes has the same root as the same list with its last hash twice. A root of version 2 starts with `esdb:merkle:v2:`, a root of version 1 has no prefix. To calculate a root of version 1 again, or to prove an event against one, pass `--tree-version=1`. Version 1 knows no salts:
113
+
114
+ ```shell
115
+ eventsourcingdb-merkle merkle-root --backup=backup.json --tree-version=1
116
+ ```
83
117
 
84
118
  ### Validating Individual Events
85
119
 
86
120
  Sometimes you want to verify the integrity of a single event without processing the entire backup. The `validate-event-hash` command provides two ways to do this.
87
121
 
88
- #### Validating an Event from a Backup File
122
+ #### Validating an Event from a Backup File or a Database
89
123
 
90
- To validate an event by its ID from a backup file, call the `validate-event-hash` command with the `--backup` and `--event-id` flags:
124
+ To validate an event by its ID from a backup file or a database, call the `validate-event-hash` command with `--event-id` and the source:
91
125
 
92
126
  ```shell
93
127
  eventsourcingdb-merkle validate-event-hash --backup=backup.json --event-id=42
@@ -110,6 +144,14 @@ Stored hash: abc123...
110
144
  Calculated hash: def456...
111
145
  ```
112
146
 
147
+ Read from a database, the client SDK verifies the hash and keeps the hash it calculated to itself, so the command shows the stored hash only:
148
+
149
+ ```
150
+ ✗ Hash mismatch
151
+ Event ID: 42
152
+ Stored hash: abc123...
153
+ ```
154
+
113
155
  #### Validating an Event from JSON
114
156
 
115
157
  You can also validate an event provided as a JSON string. This is useful when you receive an event from an external source and want to verify its hash without having access to the backup file. The command takes a line of a backup, a line of `read-events`, or an event on its own, with its hash:
@@ -127,7 +169,7 @@ Calculated hash (version 2): esdb:hash:v2:def456...
127
169
 
128
170
  ### Generating Merkle Proofs
129
171
 
130
- A Merkle proof allows you to prove that a specific event is part of a backup without revealing the entire backup. To generate a proof for an event, call the `get-proof` command with the path to your backup file in `--backup` and the event ID in `--event-id`:
172
+ A Merkle proof allows you to prove that a specific event is part of a backup without revealing the entire backup. To generate a proof for an event, call the `get-proof` command with the source and the event ID in `--event-id`:
131
173
 
132
174
  ```shell
133
175
  eventsourcingdb-merkle get-proof --backup=backup.json --event-id=42
@@ -138,8 +180,8 @@ The command outputs the proof in a human-readable format:
138
180
  ```
139
181
  Merkle Proof for Event 42
140
182
 
141
- Event Hash: abc123...
142
- Merkle Root: d1f6713af7ba3896ff238bb51f3986b2bad53b09bda7f23370e0a8b6eb97eeab
183
+ Event Hash: esdb:hash:v2:abc123...
184
+ Merkle Root: esdb:merkle:v2:d1f6713af7ba3896ff238bb51f3986b2bad53b09bda7f23370e0a8b6eb97eeab
143
185
 
144
186
  Sibling Hashes (3):
145
187
  1. def456... (left)
@@ -153,6 +195,20 @@ To prove an event against the root of an earlier state, pass its last event ID w
153
195
  eventsourcingdb-merkle get-proof --backup=backup.json --event-id=42 --last-event-id=1234566
154
196
  ```
155
197
 
198
+ To prove an event against a root whose leaves are salted, pass the same key with `--salt-key-file`, and to prove it against a root of version 1, pass `--tree-version=1`, as for `merkle-root`. A proof against a salted root carries the salt of the leaf of its event, right after the hash of the event:
199
+
200
+ ```shell
201
+ eventsourcingdb-merkle get-proof --backup=backup.json --event-id=42 --salt-key-file=merkle.key
202
+ ```
203
+
204
+ ```
205
+ Merkle Proof for Event 42
206
+
207
+ Event Hash: esdb:hash:v2:abc123...
208
+ Salt: 9c1f0b...
209
+ Merkle Root: esdb:merkle:v2:5f0c3e...
210
+ ```
211
+
156
212
  #### Outputting JSON
157
213
 
158
214
  To get the proof as JSON for programmatic use, add the `--json` flag:
@@ -166,7 +222,7 @@ The output can then be saved to a file and shared with others:
166
222
  ```json
167
223
  {
168
224
  "eventId": "42",
169
- "eventHash": "abc123...",
225
+ "eventHash": "esdb:hash:v2:abc123...",
170
226
  "siblingHashes": [
171
227
  {
172
228
  "hash": "def456...",
@@ -181,10 +237,12 @@ The output can then be saved to a file and shared with others:
181
237
  "position": "left"
182
238
  }
183
239
  ],
184
- "merkleRoot": "d1f6713af7ba3896ff238bb51f3986b2bad53b09bda7f23370e0a8b6eb97eeab"
240
+ "merkleRoot": "esdb:merkle:v2:d1f6713af7ba3896ff238bb51f3986b2bad53b09bda7f23370e0a8b6eb97eeab"
185
241
  }
186
242
  ```
187
243
 
244
+ A proof against a salted root holds its salt in `salt`, right after `eventHash`.
245
+
188
246
  ### Verifying Merkle Proofs
189
247
 
190
248
  Once you have a Merkle proof, you can verify it without needing the original backup file. This is particularly useful when you receive a proof from someone else and want to verify that the event is indeed part of the backup with the claimed Merkle root.
@@ -201,13 +259,15 @@ Or with a JSON string:
201
259
  eventsourcingdb-merkle verify-proof '{"eventId":"42","eventHash":"...","siblingHashes":[],"merkleRoot":"..."}'
202
260
  ```
203
261
 
262
+ The command verifies proofs of either version of the tree, which it tells apart by their root, and takes the salt of a salted proof from the proof itself, so it needs neither the backup nor the key.
263
+
204
264
  If the proof is valid, the command confirms this and displays the event details:
205
265
 
206
266
  ```
207
267
  ✓ Merkle proof is valid
208
268
  Event ID: 42
209
- Event Hash: abc123...
210
- Merkle Root: d1f6713af7ba3896ff238bb51f3986b2bad53b09bda7f23370e0a8b6eb97eeab
269
+ Event Hash: esdb:hash:v2:abc123...
270
+ Merkle Root: esdb:merkle:v2:d1f6713af7ba3896ff238bb51f3986b2bad53b09bda7f23370e0a8b6eb97eeab
211
271
  ```
212
272
 
213
273
  If the proof is invalid, the command indicates this with a non-zero exit code:
@@ -215,8 +275,8 @@ If the proof is invalid, the command indicates this with a non-zero exit code:
215
275
  ```
216
276
  ✗ Merkle proof is invalid
217
277
  Event ID: 42
218
- Event Hash: abc123...
219
- Merkle Root: d1f6713af7ba3896ff238bb51f3986b2bad53b09bda7f23370e0a8b6eb97eeab
278
+ Event Hash: esdb:hash:v2:abc123...
279
+ Merkle Root: esdb:merkle:v2:d1f6713af7ba3896ff238bb51f3986b2bad53b09bda7f23370e0a8b6eb97eeab
220
280
  ```
221
281
 
222
282
  ## Understanding the Technical Details
@@ -228,7 +288,13 @@ The tool implements Merkle trees using SHA-256 hashing, following the EventSourc
228
288
 
229
289
  In both versions, the data is hashed as it appears in the backup or in the event given with `--event`, rather than parsed and serialized again, since that would change escape sequences such as `\u003c` for `<` and the notation of numbers. Only the whitespace between its tokens is left out, which EventSourcingDB never writes, so that an event formatted afterwards, as by a viewer or by `jq` without `-c`, still verifies.
230
290
 
231
- The Merkle tree is constructed by treating event hashes, as they are stored, prefix included, as leaf nodes. Internal nodes are created by hashing the concatenation of their child hashes. If the number of nodes at any level is odd, the last node is duplicated to create a complete binary tree. This process continues until a single root hash remains.
291
+ The Merkle tree of version 2 follows [RFC 6962](https://www.rfc-editor.org/rfc/rfc6962), as the tree of [eventsourcingdb-auditing](https://github.com/thenativeweb/eventsourcingdb-auditing) does:
292
+
293
+ - The data of a leaf is the hash of its event as it is stored, prefix included, as text in UTF-8. Where the leaves are salted, its salt comes first: the HMAC-SHA256 of that text under the salt key. Since nothing marks where the salt ends, the tree takes only hashes in the form of version 1 or 2, which give the data of a leaf other lengths with a salt than without one, and refuses an event with any other hash, as `verify-proof` refuses a proof of one.
294
+ - The hash of a leaf is the SHA-256 of the byte `0x00` followed by its data, and the hash of an inner node is the SHA-256 of the byte `0x01` followed by the hashes of its two children, so that neither can pass for the other.
295
+ - The tree splits its leaves at the largest power of two smaller than their number, and never duplicates a node. Its root is the hash of its top node in hexadecimal, after the prefix `esdb:merkle:v2:`.
296
+
297
+ The tree of version 1 takes the stored hashes as its leaves, and hashes the concatenation of the hashes of its two children, as text, for an inner node. Where a level has an odd number of nodes, it pairs the last one with itself.
232
298
 
233
299
  Backup files are expected to be in one of the two NDJSON formats that EventSourcingDB writes, and the tool reads every backup that a restore of EventSourcingDB takes. It checks the structure of a backup, the hashes, and the chain, but neither the values of the events nor the schemas, which a restore checks with the rules of the server:
234
300
 
@@ -0,0 +1,27 @@
1
+ import { Flags } from '@oclif/core';
2
+ import BaseCommand from '../lib/BaseCommand.js';
3
+ import { describeError } from '../lib/describeError.js';
4
+ import { writeSaltKey } from '../lib/saltKey.js';
5
+ export default class GenerateSaltKey extends BaseCommand {
6
+ static description = 'Generate a key to salt the leaves of Merkle trees with';
7
+ static examples = ['<%= config.bin %> <%= command.id %> --output=merkle.key'];
8
+ static flags = {
9
+ output: Flags.string({
10
+ description: 'File to write the salt key to; an existing file is never overwritten',
11
+ required: true,
12
+ }),
13
+ };
14
+ static args = {};
15
+ async run() {
16
+ const { flags } = await this.parse(GenerateSaltKey);
17
+ try {
18
+ await writeSaltKey(flags.output);
19
+ this.log(`✓ Salt key written to ${flags.output}`);
20
+ this.log('Keep it safe: without it, no further proof can be generated for a root calculated with it.');
21
+ }
22
+ catch (error) {
23
+ this.log(`✗ Failed to generate salt key: ${describeError(error)}`);
24
+ process.exitCode = 1;
25
+ }
26
+ }
27
+ }
@@ -1,34 +1,40 @@
1
1
  import { Flags } from '@oclif/core';
2
2
  import BaseCommand from '../lib/BaseCommand.js';
3
- import { findEventById, readBackupFile } from '../lib/backupReader.js';
3
+ import { findEventById } from '../lib/chainEvent.js';
4
+ import { describeError } from '../lib/describeError.js';
4
5
  import { parseEventId } from '../lib/eventId.js';
5
- import { takeEntriesUpTo } from '../lib/lastEventId.js';
6
6
  import { generateMerkleProof } from '../lib/merkleTree.js';
7
+ import { getSource, readEvents, sourceFlags } from '../lib/source.js';
8
+ import { getTree, getTreeFlags, getTreeHashes, readTreeOptions } from '../lib/tree.js';
7
9
  export default class GetProof extends BaseCommand {
8
- static description = 'Generate a Merkle proof for a specific event';
10
+ static description = 'Generate a Merkle proof for a specific event of an EventSourcingDB backup file or a running EventSourcingDB';
9
11
  static examples = [
10
12
  '<%= config.bin %> <%= command.id %> --backup=backup.json --event-id=42',
11
13
  '<%= config.bin %> <%= command.id %> --backup=/path/to/backup.json --event-id=0 --json',
12
14
  '<%= config.bin %> <%= command.id %> --backup=backup.json --event-id=42 --last-event-id=1234566',
15
+ '<%= config.bin %> <%= command.id %> --backup=backup.json --event-id=42 --salt-key-file=merkle.key',
16
+ '<%= config.bin %> <%= command.id %> --esdb-url=http://localhost:3000 --esdb-api-token="$ESDB_API_TOKEN" --event-id=42',
13
17
  ];
14
18
  static flags = {
15
- backup: Flags.string({ description: 'Path to the backup file' }),
19
+ ...sourceFlags,
16
20
  'event-id': Flags.string({ description: 'Event ID to generate proof for' }),
17
21
  'last-event-id': Flags.string({
18
22
  description: 'ID of the last event the root covers, to prove against the root of an earlier state',
19
23
  }),
20
24
  json: Flags.boolean({ description: 'Output proof as JSON' }),
25
+ ...getTreeFlags('Version of the Merkle tree: 1 to prove against roots that releases before 3.0 calculated'),
21
26
  };
22
27
  static args = {};
23
28
  async run() {
24
29
  const { flags } = await this.parse(GetProof);
25
- if (!flags.backup) {
26
- this.refuseCall('--backup must be provided');
30
+ const source = getSource(flags);
31
+ if ('refusal' in source) {
32
+ this.refuseCall(source.refusal);
27
33
  return;
28
34
  }
29
35
  const eventId = flags['event-id'];
30
36
  if (!eventId) {
31
- this.refuseCall('--event-id is required when using --backup');
37
+ this.refuseCall('--event-id is required when using --backup or --esdb-url');
32
38
  return;
33
39
  }
34
40
  const lastEventId = flags['last-event-id'];
@@ -36,11 +42,16 @@ export default class GetProof extends BaseCommand {
36
42
  this.refuseCall(`--last-event-id has to be an event ID, but is '${lastEventId}'`);
37
43
  return;
38
44
  }
45
+ const tree = getTree(flags);
46
+ if ('refusal' in tree) {
47
+ this.refuseCall(tree.refusal);
48
+ return;
49
+ }
39
50
  try {
40
- const allEntries = await readBackupFile(flags.backup);
41
- const entries = lastEventId === undefined ? allEntries : takeEntriesUpTo(allEntries, lastEventId);
51
+ const treeOptions = await readTreeOptions(tree);
52
+ const events = await readEvents(source, { lastEventId });
42
53
  // An event after the last one is not part of the tree, so it has no
43
- // proof against its root, although the backup holds it.
54
+ // proof against its root, although the source holds it.
44
55
  const eventNumber = parseEventId(eventId);
45
56
  const lastEventNumber = lastEventId === undefined ? undefined : parseEventId(lastEventId);
46
57
  if (eventNumber !== undefined &&
@@ -50,16 +61,16 @@ export default class GetProof extends BaseCommand {
50
61
  process.exitCode = 1;
51
62
  return;
52
63
  }
53
- const entry = findEventById(entries, eventId);
54
- if (!entry) {
64
+ const event = findEventById(events, eventId);
65
+ if (!event) {
55
66
  this.log(`✗ Event with ID ${eventId} not found`);
56
67
  process.exitCode = 1;
57
68
  return;
58
69
  }
59
- const hashes = entries.map(e => e.payload.hash);
60
- const proofData = generateMerkleProof(hashes, entry.payload.hash);
70
+ const hashes = getTreeHashes(events, treeOptions);
71
+ const proofData = generateMerkleProof(hashes, events.indexOf(event), treeOptions);
61
72
  const proof = {
62
- eventId: entry.payload.event.id,
73
+ eventId: event.id,
63
74
  ...proofData,
64
75
  };
65
76
  if (flags.json) {
@@ -69,6 +80,9 @@ export default class GetProof extends BaseCommand {
69
80
  this.log(`Merkle Proof for Event ${proof.eventId}`);
70
81
  this.log('');
71
82
  this.log(`Event Hash: ${proof.eventHash}`);
83
+ if (proof.salt !== undefined) {
84
+ this.log(`Salt: ${proof.salt}`);
85
+ }
72
86
  this.log(`Merkle Root: ${proof.merkleRoot}`);
73
87
  this.log('');
74
88
  this.log(`Sibling Hashes (${proof.siblingHashes.length}):`);
@@ -77,7 +91,7 @@ export default class GetProof extends BaseCommand {
77
91
  }
78
92
  }
79
93
  catch (error) {
80
- this.log(`✗ Failed to generate Merkle proof: ${error instanceof Error ? error.message : String(error)}`);
94
+ this.log(`✗ Failed to generate Merkle proof: ${describeError(error)}`);
81
95
  process.exitCode = 1;
82
96
  }
83
97
  }
@@ -1,26 +1,32 @@
1
1
  import { Flags } from '@oclif/core';
2
2
  import BaseCommand from '../lib/BaseCommand.js';
3
- import { readBackupFile } from '../lib/backupReader.js';
3
+ import { describeError } from '../lib/describeError.js';
4
4
  import { parseEventId } from '../lib/eventId.js';
5
- import { takeEntriesUpTo } from '../lib/lastEventId.js';
6
- import { buildMerkleRoot } from '../lib/merkleTree.js';
5
+ import { calculateMerkleRoot } from '../lib/merkleTree.js';
6
+ import { getSource, readEvents, sourceFlags } from '../lib/source.js';
7
+ import { getTree, getTreeFlags, getTreeHashes, readTreeOptions } from '../lib/tree.js';
7
8
  export default class MerkleRoot extends BaseCommand {
8
- static description = 'Calculate the Merkle root for an EventSourcingDB backup file';
9
+ static description = 'Calculate the Merkle root for an EventSourcingDB backup file or a running EventSourcingDB';
9
10
  static examples = [
10
11
  '<%= config.bin %> <%= command.id %> --backup=backup.json',
11
12
  '<%= config.bin %> <%= command.id %> --backup=/path/to/backup.json --last-event-id=41',
13
+ '<%= config.bin %> <%= command.id %> --backup=backup.json --salt-key-file=merkle.key',
14
+ '<%= config.bin %> <%= command.id %> --backup=backup.json --tree-version=1',
15
+ '<%= config.bin %> <%= command.id %> --esdb-url=http://localhost:3000 --esdb-api-token="$ESDB_API_TOKEN"',
12
16
  ];
13
17
  static flags = {
14
- backup: Flags.string({ description: 'Path to the backup file' }),
18
+ ...sourceFlags,
15
19
  'last-event-id': Flags.string({
16
20
  description: 'ID of the last event to cover, to calculate the root of an earlier state again',
17
21
  }),
22
+ ...getTreeFlags('Version of the Merkle tree: 1 for roots that releases before 3.0 calculated'),
18
23
  };
19
24
  static args = {};
20
25
  async run() {
21
26
  const { flags } = await this.parse(MerkleRoot);
22
- if (!flags.backup) {
23
- this.refuseCall('--backup must be provided');
27
+ const source = getSource(flags);
28
+ if ('refusal' in source) {
29
+ this.refuseCall(source.refusal);
24
30
  return;
25
31
  }
26
32
  const lastEventId = flags['last-event-id'];
@@ -28,19 +34,24 @@ export default class MerkleRoot extends BaseCommand {
28
34
  this.refuseCall(`--last-event-id has to be an event ID, but is '${lastEventId}'`);
29
35
  return;
30
36
  }
37
+ const tree = getTree(flags);
38
+ if ('refusal' in tree) {
39
+ this.refuseCall(tree.refusal);
40
+ return;
41
+ }
31
42
  try {
32
- const allEntries = await readBackupFile(flags.backup);
33
- const entries = lastEventId === undefined ? allEntries : takeEntriesUpTo(allEntries, lastEventId);
34
- const hashes = entries.map(entry => entry.payload.hash);
35
- const merkleRoot = buildMerkleRoot(hashes);
43
+ const treeOptions = await readTreeOptions(tree);
44
+ const events = await readEvents(source, { lastEventId });
45
+ const hashes = getTreeHashes(events, treeOptions);
46
+ const merkleRoot = calculateMerkleRoot(hashes, treeOptions);
36
47
  // The ID of the last event is what calculates this root again later,
37
- // from a backup that has grown since.
48
+ // from a source that has grown since.
38
49
  this.log(`Merkle Root: ${merkleRoot}`);
39
- this.log(`Total events: ${entries.length}`);
40
- this.log(`Last event ID: ${entries.at(-1)?.payload.event.id}`);
50
+ this.log(`Total events: ${events.length}`);
51
+ this.log(`Last event ID: ${events.at(-1)?.id}`);
41
52
  }
42
53
  catch (error) {
43
- this.log(`✗ Failed to calculate Merkle root: ${error instanceof Error ? error.message : String(error)}`);
54
+ this.log(`✗ Failed to calculate Merkle root: ${describeError(error)}`);
44
55
  process.exitCode = 1;
45
56
  }
46
57
  }
@@ -1,26 +1,27 @@
1
- import { Flags } from '@oclif/core';
2
1
  import BaseCommand from '../lib/BaseCommand.js';
3
- import { readBackupFile } from '../lib/backupReader.js';
4
2
  import { validateChain } from '../lib/chainValidator.js';
3
+ import { describeError } from '../lib/describeError.js';
4
+ import { getSource, readEvents, sourceFlags } from '../lib/source.js';
5
5
  export default class ValidateChain extends BaseCommand {
6
- static description = 'Validate the hash chain in an EventSourcingDB backup file';
6
+ static description = 'Validate the hash chain in an EventSourcingDB backup file or a running EventSourcingDB';
7
7
  static examples = [
8
8
  '<%= config.bin %> <%= command.id %> --backup=backup.json',
9
- '<%= config.bin %> <%= command.id %> --backup=/path/to/backup.json',
9
+ '<%= config.bin %> <%= command.id %> --esdb-url=http://localhost:3000 --esdb-api-token="$ESDB_API_TOKEN"',
10
10
  ];
11
11
  static flags = {
12
- backup: Flags.string({ description: 'Path to the backup file' }),
12
+ ...sourceFlags,
13
13
  };
14
14
  static args = {};
15
15
  async run() {
16
16
  const { flags } = await this.parse(ValidateChain);
17
- if (!flags.backup) {
18
- this.refuseCall('--backup must be provided');
17
+ const source = getSource(flags);
18
+ if ('refusal' in source) {
19
+ this.refuseCall(source.refusal);
19
20
  return;
20
21
  }
21
22
  try {
22
- const entries = await readBackupFile(flags.backup);
23
- const result = validateChain(entries);
23
+ const events = await readEvents(source);
24
+ const result = validateChain(events);
24
25
  if (!result.isValid) {
25
26
  this.log(`✗ Chain validation failed`);
26
27
  this.log(`Total events: ${result.totalEvents}`);
@@ -35,7 +36,7 @@ export default class ValidateChain extends BaseCommand {
35
36
  this.log(`✓ Chain is valid (${result.totalEvents} events)`);
36
37
  }
37
38
  catch (error) {
38
- this.log(`✗ Failed to validate chain: ${error instanceof Error ? error.message : String(error)}`);
39
+ this.log(`✗ Failed to validate chain: ${describeError(error)}`);
39
40
  process.exitCode = 1;
40
41
  }
41
42
  }
@@ -1,43 +1,45 @@
1
1
  import { Flags } from '@oclif/core';
2
2
  import BaseCommand from '../lib/BaseCommand.js';
3
- import { findEventById, readBackupFile } from '../lib/backupReader.js';
3
+ import { fromCloudEvent } from '../lib/chainEvent.js';
4
+ import { describeError } from '../lib/describeError.js';
4
5
  import { readEventText } from '../lib/eventText.js';
5
- import { calculateEventHash, calculateEventHashInEveryVersion, UnsupportedHashVersionError, } from '../lib/hash.js';
6
+ import { calculateEventHashInEveryVersion, UnsupportedHashVersionError } from '../lib/hash.js';
7
+ import { describeHashMismatch } from '../lib/hashReport.js';
8
+ import { getSource, readEvent, sourceFlags } from '../lib/source.js';
6
9
  export default class ValidateEventHash extends BaseCommand {
7
- static description = 'Validate the hash of a specific event (with or without backup file)';
10
+ static description = 'Validate the hash of a specific event, from a backup file, a running EventSourcingDB, or JSON';
8
11
  static examples = [
9
12
  '<%= config.bin %> <%= command.id %> --backup=backup.json --event-id=42',
13
+ '<%= config.bin %> <%= command.id %> --esdb-url=http://localhost:3000 --esdb-api-token="$ESDB_API_TOKEN" --event-id=42',
10
14
  // biome-ignore lint/security/noSecrets: This is an example command, not a secret
11
15
  '<%= config.bin %> <%= command.id %> --event=\'{"specversion":"1.0",...}\'',
12
16
  ];
13
17
  static flags = {
14
- backup: Flags.string({ description: 'Path to the backup file', exclusive: ['event'] }),
18
+ ...sourceFlags,
15
19
  'event-id': Flags.string({
16
- description: 'Event ID to validate (requires --backup)',
17
- exclusive: ['event'],
20
+ description: 'Event ID to validate (requires --backup or --esdb-url)',
18
21
  }),
19
22
  event: Flags.string({
20
23
  description: 'JSON string of the event to validate',
21
- exclusive: ['backup', 'event-id'],
24
+ exclusive: ['backup', 'esdb-url', 'event-id'],
22
25
  }),
23
26
  };
24
27
  static args = {};
25
28
  async run() {
26
29
  const { flags } = await this.parse(ValidateEventHash);
27
- if (!flags.backup && !flags.event) {
28
- this.refuseCall('Either --backup with --event-id, or --event must be provided');
30
+ const eventId = flags['event-id'];
31
+ if (!flags.backup && !flags['esdb-url'] && !flags.event) {
32
+ this.refuseCall('Either --backup or --esdb-url with --event-id, or --event must be provided');
29
33
  return;
30
34
  }
31
- if (flags.backup && !flags['event-id']) {
32
- this.refuseCall('--event-id is required when using --backup');
35
+ // The token is checked here rather than by oclif, whose message would name
36
+ // its value.
37
+ if (flags.event && flags['esdb-api-token']) {
38
+ this.refuseCall('--event and --esdb-api-token cannot be used together');
33
39
  return;
34
40
  }
35
- const filePath = flags.backup;
36
- const eventId = flags['event-id'];
37
41
  try {
38
42
  let event;
39
- let storedHash;
40
- let originalDataString;
41
43
  if (flags.event) {
42
44
  const eventFromText = readEventText(flags.event);
43
45
  if (eventFromText === undefined) {
@@ -52,33 +54,31 @@ export default class ValidateEventHash extends BaseCommand {
52
54
  }
53
55
  return;
54
56
  }
55
- event = eventFromText.event;
56
- storedHash = eventFromText.storedHash;
57
- originalDataString = eventFromText.originalDataString;
57
+ event = fromCloudEvent(eventFromText.event, eventFromText.storedHash, eventFromText.originalDataString);
58
58
  }
59
59
  else {
60
- // Read from file
61
- if (!filePath || !eventId) {
62
- this.log('✗ File path and event ID are required');
63
- process.exitCode = 2;
60
+ const source = getSource(flags);
61
+ if ('refusal' in source) {
62
+ this.refuseCall(source.refusal);
63
+ return;
64
+ }
65
+ if (!eventId) {
66
+ this.refuseCall('--event-id is required when using --backup or --esdb-url');
64
67
  return;
65
68
  }
66
- const entries = await readBackupFile(filePath);
67
- const entry = findEventById(entries, eventId);
68
- if (!entry) {
69
+ const eventFromSource = await readEvent(source, eventId);
70
+ if (!eventFromSource) {
69
71
  this.log(`✗ Event with ID ${eventId} not found`);
70
72
  process.exitCode = 1;
71
73
  return;
72
74
  }
73
- event = entry.payload.event;
74
- storedHash = entry.payload.hash;
75
- originalDataString = entry.payload.originalDataString;
75
+ event = eventFromSource;
76
76
  }
77
77
  // A hash of a version the tool does not know is no mismatch, so it is
78
78
  // reported apart from one, with the hash that names the version.
79
- let calculatedHash;
79
+ let hashCheck;
80
80
  try {
81
- calculatedHash = calculateEventHash(event, originalDataString, storedHash);
81
+ hashCheck = event.checkHash();
82
82
  }
83
83
  catch (error) {
84
84
  if (!(error instanceof UnsupportedHashVersionError)) {
@@ -86,24 +86,23 @@ export default class ValidateEventHash extends BaseCommand {
86
86
  }
87
87
  this.log(`✗ ${error.message}`);
88
88
  this.log(`Event ID: ${event.id}`);
89
- this.log(`Stored hash: ${storedHash}`);
89
+ this.log(`Stored hash: ${event.hash}`);
90
90
  process.exitCode = 1;
91
91
  return;
92
92
  }
93
- if (calculatedHash !== storedHash) {
94
- this.log(`✗ Hash mismatch`);
95
- this.log(`Event ID: ${event.id}`);
96
- this.log(`Stored hash: ${storedHash}`);
97
- this.log(`Calculated hash: ${calculatedHash}`);
93
+ if (!hashCheck.isMatching) {
94
+ for (const line of describeHashMismatch(event, hashCheck.calculatedHash)) {
95
+ this.log(line);
96
+ }
98
97
  process.exitCode = 1;
99
98
  return;
100
99
  }
101
100
  this.log(`✓ Hash is valid`);
102
101
  this.log(`Event ID: ${event.id}`);
103
- this.log(`Hash: ${storedHash}`);
102
+ this.log(`Hash: ${event.hash}`);
104
103
  }
105
104
  catch (error) {
106
- this.log(`✗ Failed to validate event hash: ${error instanceof Error ? error.message : String(error)}`);
105
+ this.log(`✗ Failed to validate event hash: ${describeError(error)}`);
107
106
  process.exitCode = 1;
108
107
  }
109
108
  }
@@ -1,6 +1,6 @@
1
1
  import { Args } from '@oclif/core';
2
2
  import BaseCommand from '../lib/BaseCommand.js';
3
- import { verifyMerkleProof } from '../lib/merkleTree.js';
3
+ import { findProofStructureProblem, verifyMerkleProof } from '../lib/merkleTree.js';
4
4
  export default class VerifyProof extends BaseCommand {
5
5
  static description = 'Verify a Merkle proof';
6
6
  static examples = [
@@ -27,10 +27,10 @@ export default class VerifyProof extends BaseCommand {
27
27
  const fileContent = readFileSync(args.proof, 'utf-8');
28
28
  proof = JSON.parse(fileContent);
29
29
  }
30
- // Validate proof structure
31
- if (!proof.eventHash || !proof.merkleRoot || !proof.siblingHashes) {
30
+ const structureProblem = findProofStructureProblem(proof);
31
+ if (structureProblem !== undefined) {
32
32
  this.log('✗ Invalid proof structure');
33
- this.log('Must contain eventHash, merkleRoot, and siblingHashes');
33
+ this.log(structureProblem);
34
34
  process.exitCode = 1;
35
35
  return;
36
36
  }
@@ -224,12 +224,3 @@ const isSameEvent = (anchor, endedAt) => {
224
224
  const anchorId = parseEventId(id);
225
225
  return anchorId !== undefined && anchorId === parseEventId(endedAt.id) && hash === endedAt.hash;
226
226
  };
227
- // findEventById compares IDs as numbers, as EventSourcingDB reads them, so that
228
- // an ID in another notation of the same number finds the event.
229
- export const findEventById = (entries, eventId) => {
230
- const wanted = parseEventId(eventId);
231
- if (wanted === undefined) {
232
- return undefined;
233
- }
234
- return entries.find(entry => parseEventId(entry.payload.event.id) === wanted);
235
- };