eventsourcingdb-merkle 1.3.0 → 2.1.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,12 +20,25 @@ 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. 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
- eventsourcingdb-merkle validate-chain backup.json
41
+ eventsourcingdb-merkle validate-chain --backup=backup.json
29
42
  ```
30
43
 
31
44
  If the chain is valid, you will see a confirmation message with the total number of events:
@@ -57,29 +70,40 @@ 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. 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
- eventsourcingdb-merkle merkle-root backup.json
76
+ eventsourcingdb-merkle merkle-root --backup=backup.json
64
77
  ```
65
78
 
66
- The command outputs the Merkle root and the total number of events:
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
82
  Merkle Root: d1f6713af7ba3896ff238bb51f3986b2bad53b09bda7f23370e0a8b6eb97eeab
70
83
  Total events: 4
84
+ Last event ID: 3
85
+ ```
86
+
87
+ #### Calculating the Merkle Root of an Earlier State
88
+
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:
90
+
91
+ ```shell
92
+ eventsourcingdb-merkle merkle-root --backup=backup-2025.json --last-event-id=3
71
93
  ```
72
94
 
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
+
73
97
  ### Validating Individual Events
74
98
 
75
99
  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.
76
100
 
77
- #### Validating an Event from a Backup File
101
+ #### Validating an Event from a Backup File or a Database
78
102
 
79
- To validate an event by its ID from a backup file, call the `validate-event-hash` command with the `--file` and `--event-id` flags:
103
+ 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:
80
104
 
81
105
  ```shell
82
- eventsourcingdb-merkle validate-event-hash --file=backup.json --event-id=42
106
+ eventsourcingdb-merkle validate-event-hash --backup=backup.json --event-id=42
83
107
  ```
84
108
 
85
109
  If the hash is valid, you will see a confirmation message:
@@ -99,6 +123,14 @@ Stored hash: abc123...
99
123
  Calculated hash: def456...
100
124
  ```
101
125
 
126
+ 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:
127
+
128
+ ```
129
+ ✗ Hash mismatch
130
+ Event ID: 42
131
+ Stored hash: abc123...
132
+ ```
133
+
102
134
  #### Validating an Event from JSON
103
135
 
104
136
  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:
@@ -107,18 +139,19 @@ You can also validate an event provided as a JSON string. This is useful when yo
107
139
  eventsourcingdb-merkle validate-event-hash --event='{"specversion":"1.0","id":"0",...,"hash":"esdb:hash:v2:..."}'
108
140
  ```
109
141
 
110
- If you provide a CloudEvent without a stored hash, the command simply calculates and displays the hash of version 1, since nothing tells which version is meant:
142
+ If you provide a CloudEvent without a stored hash, the command simply calculates and displays the hash in every version, since nothing tells which version is meant:
111
143
 
112
144
  ```
113
- Calculated hash: abc123...
145
+ Calculated hash (version 1): abc123...
146
+ Calculated hash (version 2): esdb:hash:v2:def456...
114
147
  ```
115
148
 
116
149
  ### Generating Merkle Proofs
117
150
 
118
- 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 and the event ID:
151
+ 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`:
119
152
 
120
153
  ```shell
121
- eventsourcingdb-merkle get-proof backup.json 42
154
+ eventsourcingdb-merkle get-proof --backup=backup.json --event-id=42
122
155
  ```
123
156
 
124
157
  The command outputs the proof in a human-readable format:
@@ -135,12 +168,18 @@ Sibling Hashes (3):
135
168
  3. jkl012... (left)
136
169
  ```
137
170
 
171
+ To prove an event against the root of an earlier state, pass its last event ID with `--last-event-id`, as for `merkle-root`. An event after it is not part of that tree, so the command refuses to prove it:
172
+
173
+ ```shell
174
+ eventsourcingdb-merkle get-proof --backup=backup.json --event-id=42 --last-event-id=1234566
175
+ ```
176
+
138
177
  #### Outputting JSON
139
178
 
140
179
  To get the proof as JSON for programmatic use, add the `--json` flag:
141
180
 
142
181
  ```shell
143
- eventsourcingdb-merkle get-proof backup.json 42 --json
182
+ eventsourcingdb-merkle get-proof --backup=backup.json --event-id=42 --json
144
183
  ```
145
184
 
146
185
  The output can then be saved to a file and shared with others:
@@ -1,34 +1,67 @@
1
- import { Args, Flags } from '@oclif/core';
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';
5
+ import { parseEventId } from '../lib/eventId.js';
4
6
  import { generateMerkleProof } from '../lib/merkleTree.js';
7
+ import { getSource, readEvents, sourceFlags } from '../lib/source.js';
5
8
  export default class GetProof extends BaseCommand {
6
- static description = 'Generate a Merkle proof for a specific event';
9
+ static description = 'Generate a Merkle proof for a specific event of an EventSourcingDB backup file or a running EventSourcingDB';
7
10
  static examples = [
8
- '<%= config.bin %> <%= command.id %> backup.json 42',
9
- '<%= config.bin %> <%= command.id %> /path/to/backup.json 0 --json',
11
+ '<%= config.bin %> <%= command.id %> --backup=backup.json --event-id=42',
12
+ '<%= config.bin %> <%= command.id %> --backup=/path/to/backup.json --event-id=0 --json',
13
+ '<%= config.bin %> <%= command.id %> --backup=backup.json --event-id=42 --last-event-id=1234566',
14
+ '<%= config.bin %> <%= command.id %> --esdb-url=http://localhost:3000 --esdb-api-token="$ESDB_API_TOKEN" --event-id=42',
10
15
  ];
11
- static args = {
12
- file: Args.string({ description: 'Path to the backup file', required: true }),
13
- 'event-id': Args.string({ description: 'Event ID to generate proof for', required: true }),
14
- };
15
16
  static flags = {
17
+ ...sourceFlags,
18
+ 'event-id': Flags.string({ description: 'Event ID to generate proof for' }),
19
+ 'last-event-id': Flags.string({
20
+ description: 'ID of the last event the root covers, to prove against the root of an earlier state',
21
+ }),
16
22
  json: Flags.boolean({ description: 'Output proof as JSON' }),
17
23
  };
24
+ static args = {};
18
25
  async run() {
19
- const { args, flags } = await this.parse(GetProof);
26
+ const { flags } = await this.parse(GetProof);
27
+ const source = getSource(flags);
28
+ if ('refusal' in source) {
29
+ this.refuseCall(source.refusal);
30
+ return;
31
+ }
32
+ const eventId = flags['event-id'];
33
+ if (!eventId) {
34
+ this.refuseCall('--event-id is required when using --backup or --esdb-url');
35
+ return;
36
+ }
37
+ const lastEventId = flags['last-event-id'];
38
+ if (lastEventId !== undefined && parseEventId(lastEventId) === undefined) {
39
+ this.refuseCall(`--last-event-id has to be an event ID, but is '${lastEventId}'`);
40
+ return;
41
+ }
20
42
  try {
21
- const entries = await readBackupFile(args.file);
22
- const entry = findEventById(entries, args['event-id']);
23
- if (!entry) {
24
- this.log(`✗ Event with ID ${args['event-id']} not found`);
43
+ const events = await readEvents(source, { lastEventId });
44
+ // An event after the last one is not part of the tree, so it has no
45
+ // proof against its root, although the source holds it.
46
+ const eventNumber = parseEventId(eventId);
47
+ const lastEventNumber = lastEventId === undefined ? undefined : parseEventId(lastEventId);
48
+ if (eventNumber !== undefined &&
49
+ lastEventNumber !== undefined &&
50
+ eventNumber > lastEventNumber) {
51
+ this.log(`✗ Event ${eventId} lies beyond the last event ID ${lastEventId}`);
52
+ process.exitCode = 1;
53
+ return;
54
+ }
55
+ const event = findEventById(events, eventId);
56
+ if (!event) {
57
+ this.log(`✗ Event with ID ${eventId} not found`);
25
58
  process.exitCode = 1;
26
59
  return;
27
60
  }
28
- const hashes = entries.map(e => e.payload.hash);
29
- const proofData = generateMerkleProof(hashes, entry.payload.hash);
61
+ const hashes = events.map(e => e.hash);
62
+ const proofData = generateMerkleProof(hashes, event.hash);
30
63
  const proof = {
31
- eventId: entry.payload.event.id,
64
+ eventId: event.id,
32
65
  ...proofData,
33
66
  };
34
67
  if (flags.json) {
@@ -46,7 +79,7 @@ export default class GetProof extends BaseCommand {
46
79
  }
47
80
  }
48
81
  catch (error) {
49
- this.log(`✗ Failed to generate Merkle proof: ${error instanceof Error ? error.message : String(error)}`);
82
+ this.log(`✗ Failed to generate Merkle proof: ${describeError(error)}`);
50
83
  process.exitCode = 1;
51
84
  }
52
85
  }
@@ -1,27 +1,47 @@
1
- import { Args } from '@oclif/core';
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
+ import { parseEventId } from '../lib/eventId.js';
4
5
  import { buildMerkleRoot } from '../lib/merkleTree.js';
6
+ import { getSource, readEvents, sourceFlags } from '../lib/source.js';
5
7
  export default class MerkleRoot extends BaseCommand {
6
- static description = 'Calculate the Merkle root for an EventSourcingDB backup file';
8
+ static description = 'Calculate the Merkle root for an EventSourcingDB backup file or a running EventSourcingDB';
7
9
  static examples = [
8
- '<%= config.bin %> <%= command.id %> backup.json',
9
- '<%= config.bin %> <%= command.id %> /path/to/backup.json',
10
+ '<%= config.bin %> <%= command.id %> --backup=backup.json',
11
+ '<%= config.bin %> <%= command.id %> --backup=/path/to/backup.json --last-event-id=41',
12
+ '<%= config.bin %> <%= command.id %> --esdb-url=http://localhost:3000 --esdb-api-token="$ESDB_API_TOKEN"',
10
13
  ];
11
- static args = {
12
- file: Args.string({ description: 'Path to the backup file', required: true }),
14
+ static flags = {
15
+ ...sourceFlags,
16
+ 'last-event-id': Flags.string({
17
+ description: 'ID of the last event to cover, to calculate the root of an earlier state again',
18
+ }),
13
19
  };
20
+ static args = {};
14
21
  async run() {
15
- const { args } = await this.parse(MerkleRoot);
22
+ const { flags } = await this.parse(MerkleRoot);
23
+ const source = getSource(flags);
24
+ if ('refusal' in source) {
25
+ this.refuseCall(source.refusal);
26
+ return;
27
+ }
28
+ const lastEventId = flags['last-event-id'];
29
+ if (lastEventId !== undefined && parseEventId(lastEventId) === undefined) {
30
+ this.refuseCall(`--last-event-id has to be an event ID, but is '${lastEventId}'`);
31
+ return;
32
+ }
16
33
  try {
17
- const entries = await readBackupFile(args.file);
18
- const hashes = entries.map(entry => entry.payload.hash);
34
+ const events = await readEvents(source, { lastEventId });
35
+ const hashes = events.map(event => event.hash);
19
36
  const merkleRoot = buildMerkleRoot(hashes);
37
+ // The ID of the last event is what calculates this root again later,
38
+ // from a source that has grown since.
20
39
  this.log(`Merkle Root: ${merkleRoot}`);
21
- this.log(`Total events: ${entries.length}`);
40
+ this.log(`Total events: ${events.length}`);
41
+ this.log(`Last event ID: ${events.at(-1)?.id}`);
22
42
  }
23
43
  catch (error) {
24
- this.log(`✗ Failed to calculate Merkle root: ${error instanceof Error ? error.message : String(error)}`);
44
+ this.log(`✗ Failed to calculate Merkle root: ${describeError(error)}`);
25
45
  process.exitCode = 1;
26
46
  }
27
47
  }
@@ -1,21 +1,27 @@
1
- import { Args } 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
- '<%= config.bin %> <%= command.id %> backup.json',
9
- '<%= config.bin %> <%= command.id %> /path/to/backup.json',
8
+ '<%= config.bin %> <%= command.id %> --backup=backup.json',
9
+ '<%= config.bin %> <%= command.id %> --esdb-url=http://localhost:3000 --esdb-api-token="$ESDB_API_TOKEN"',
10
10
  ];
11
- static args = {
12
- file: Args.string({ description: 'Path to the backup file', required: true }),
11
+ static flags = {
12
+ ...sourceFlags,
13
13
  };
14
+ static args = {};
14
15
  async run() {
15
- const { args } = await this.parse(ValidateChain);
16
+ const { flags } = await this.parse(ValidateChain);
17
+ const source = getSource(flags);
18
+ if ('refusal' in source) {
19
+ this.refuseCall(source.refusal);
20
+ return;
21
+ }
16
22
  try {
17
- const entries = await readBackupFile(args.file);
18
- const result = validateChain(entries);
23
+ const events = await readEvents(source);
24
+ const result = validateChain(events);
19
25
  if (!result.isValid) {
20
26
  this.log(`✗ Chain validation failed`);
21
27
  this.log(`Total events: ${result.totalEvents}`);
@@ -30,7 +36,7 @@ export default class ValidateChain extends BaseCommand {
30
36
  this.log(`✓ Chain is valid (${result.totalEvents} events)`);
31
37
  }
32
38
  catch (error) {
33
- this.log(`✗ Failed to validate chain: ${error instanceof Error ? error.message : String(error)}`);
39
+ this.log(`✗ Failed to validate chain: ${describeError(error)}`);
34
40
  process.exitCode = 1;
35
41
  }
36
42
  }
@@ -1,88 +1,84 @@
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, 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
- '<%= config.bin %> <%= command.id %> --file=backup.json --event-id=42',
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
- file: 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 --file)',
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: ['file', '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.file && !flags.event) {
28
- this.log('✗ Either --file and --event-id, or --event must be provided');
29
- this.log('See more help with --help');
30
- process.exitCode = 2;
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');
31
33
  return;
32
34
  }
33
- if (flags.file && !flags['event-id']) {
34
- this.log('✗ --event-id is required when using --file');
35
- this.log('See more help with --help');
36
- process.exitCode = 2;
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');
37
39
  return;
38
40
  }
39
- const filePath = flags.file;
40
- const eventId = flags['event-id'];
41
41
  try {
42
42
  let event;
43
- let storedHash;
44
- let originalDataString;
45
43
  if (flags.event) {
46
44
  const eventFromText = readEventText(flags.event);
47
45
  if (eventFromText === undefined) {
48
- this.log('✗ --event is neither an event nor a line of a backup or of read-events');
49
- this.log('See more help with --help');
50
- process.exitCode = 2;
46
+ this.refuseCall('--event is neither an event nor a line of a backup or of read-events');
51
47
  return;
52
48
  }
49
+ // Without a stored hash, nothing tells which version of the hash is
50
+ // meant, so it is calculated in every version.
53
51
  if (eventFromText.storedHash === undefined) {
54
- // No stored hash to compare against
55
- const calculatedHash = calculateEventHash(eventFromText.event, eventFromText.originalDataString);
56
- this.log(`Calculated hash: ${calculatedHash}`);
52
+ for (const { version, hash } of calculateEventHashInEveryVersion(eventFromText.event, eventFromText.originalDataString)) {
53
+ this.log(`Calculated hash (version ${version}): ${hash}`);
54
+ }
57
55
  return;
58
56
  }
59
- event = eventFromText.event;
60
- storedHash = eventFromText.storedHash;
61
- originalDataString = eventFromText.originalDataString;
57
+ event = fromCloudEvent(eventFromText.event, eventFromText.storedHash, eventFromText.originalDataString);
62
58
  }
63
59
  else {
64
- // Read from file
65
- if (!filePath || !eventId) {
66
- this.log('✗ File path and event ID are required');
67
- 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');
68
67
  return;
69
68
  }
70
- const entries = await readBackupFile(filePath);
71
- const entry = findEventById(entries, eventId);
72
- if (!entry) {
69
+ const eventFromSource = await readEvent(source, eventId);
70
+ if (!eventFromSource) {
73
71
  this.log(`✗ Event with ID ${eventId} not found`);
74
72
  process.exitCode = 1;
75
73
  return;
76
74
  }
77
- event = entry.payload.event;
78
- storedHash = entry.payload.hash;
79
- originalDataString = entry.payload.originalDataString;
75
+ event = eventFromSource;
80
76
  }
81
77
  // A hash of a version the tool does not know is no mismatch, so it is
82
78
  // reported apart from one, with the hash that names the version.
83
- let calculatedHash;
79
+ let hashCheck;
84
80
  try {
85
- calculatedHash = calculateEventHash(event, originalDataString, storedHash);
81
+ hashCheck = event.checkHash();
86
82
  }
87
83
  catch (error) {
88
84
  if (!(error instanceof UnsupportedHashVersionError)) {
@@ -90,24 +86,23 @@ export default class ValidateEventHash extends BaseCommand {
90
86
  }
91
87
  this.log(`✗ ${error.message}`);
92
88
  this.log(`Event ID: ${event.id}`);
93
- this.log(`Stored hash: ${storedHash}`);
89
+ this.log(`Stored hash: ${event.hash}`);
94
90
  process.exitCode = 1;
95
91
  return;
96
92
  }
97
- if (calculatedHash !== storedHash) {
98
- this.log(`✗ Hash mismatch`);
99
- this.log(`Event ID: ${event.id}`);
100
- this.log(`Stored hash: ${storedHash}`);
101
- this.log(`Calculated hash: ${calculatedHash}`);
93
+ if (!hashCheck.isMatching) {
94
+ for (const line of describeHashMismatch(event, hashCheck.calculatedHash)) {
95
+ this.log(line);
96
+ }
102
97
  process.exitCode = 1;
103
98
  return;
104
99
  }
105
100
  this.log(`✓ Hash is valid`);
106
101
  this.log(`Event ID: ${event.id}`);
107
- this.log(`Hash: ${storedHash}`);
102
+ this.log(`Hash: ${event.hash}`);
108
103
  }
109
104
  catch (error) {
110
- this.log(`✗ Failed to validate event hash: ${error instanceof Error ? error.message : String(error)}`);
105
+ this.log(`✗ Failed to validate event hash: ${describeError(error)}`);
111
106
  process.exitCode = 1;
112
107
  }
113
108
  }
@@ -1,16 +1,23 @@
1
1
  import { Command } from '@oclif/core';
2
2
  export default class BaseCommand extends Command {
3
+ // refuseCall reports a call whose arguments or flags do not fit together, as
4
+ // oclif does for those it refuses itself, with the exit code 2.
5
+ refuseCall(message) {
6
+ this.log(`✗ ${message}`);
7
+ this.log('See more help with --help');
8
+ process.exitCode = 2;
9
+ }
3
10
  catch(error) {
4
- const errorName = error.constructor.name;
5
- // Check if it's a RequiredArgsError or NonExistentFlagsError
6
- if (errorName === 'RequiredArgsError' || errorName === 'NonExistentFlagsError') {
11
+ // oclif ends with the exit code 2 where it refuses the arguments and flags
12
+ // of a call, such as an argument that is missing or unexpected, a flag that
13
+ // does not exist, or two flags that cannot be used together. Such a call
14
+ // gets a message of its own rather than a stack trace.
15
+ if (error.oclif?.exit === 2) {
7
16
  // Remove the "See more help with --help" line from oclif
8
17
  const lines = error.message.split('\n');
9
18
  const filteredLines = lines.filter(line => !line.includes('See more help'));
10
19
  const message = filteredLines.join('\n').trim();
11
- this.log(`✗ ${message}`);
12
- this.log('See more help with --help');
13
- process.exitCode = 2;
20
+ this.refuseCall(message);
14
21
  return Promise.resolve();
15
22
  }
16
23
  // For other errors, use default oclif error handling
@@ -1,13 +1,12 @@
1
1
  import { createReadStream } from 'node:fs';
2
2
  import { access } from 'node:fs/promises';
3
3
  import { createInterface } from 'node:readline';
4
+ import { parseEventId } from './eventId.js';
4
5
  import { isObject } from './isObject.js';
5
6
  import { getCompactValue, getRawValue } from './rawJson.js';
6
7
  // The version of the format in which the v2 API writes a backup. The backups
7
8
  // of the v1 API carry no version of their own.
8
9
  const backupFormatVersion = 2;
9
- // An event ID is an integer, which EventSourcingDB reads with an optional sign.
10
- const eventIdPattern = /^[+-]?\d+$/u;
11
10
  export const readBackupFile = async (filePath) => {
12
11
  // Check if file exists and is readable
13
12
  try {
@@ -222,11 +221,6 @@ const isSameEvent = (anchor, endedAt) => {
222
221
  if (typeof id !== 'string' || typeof hash !== 'string') {
223
222
  return false;
224
223
  }
225
- if (!eventIdPattern.test(id) || !eventIdPattern.test(endedAt.id)) {
226
- return false;
227
- }
228
- return BigInt(id) === BigInt(endedAt.id) && hash === endedAt.hash;
229
- };
230
- export const findEventById = (entries, eventId) => {
231
- return entries.find(entry => entry.payload.event.id === eventId);
224
+ const anchorId = parseEventId(id);
225
+ return anchorId !== undefined && anchorId === parseEventId(endedAt.id) && hash === endedAt.hash;
232
226
  };
@@ -0,0 +1,52 @@
1
+ import { HashVerificationFailedError } from 'eventsourcingdb';
2
+ import { parseEventId } from './eventId.js';
3
+ import { assertKnownHashVersion, calculateEventHash } from './hash.js';
4
+ // An event that the tool read from text is hashed by the tool itself, over the
5
+ // data as the text holds it, so the hash it calculated is known.
6
+ export const fromCloudEvent = (event, hash, originalDataString) => {
7
+ return {
8
+ id: event.id,
9
+ hash,
10
+ predecessorhash: event.predecessorhash,
11
+ checkHash: () => {
12
+ const calculatedHash = calculateEventHash(event, originalDataString, hash);
13
+ return { isMatching: calculatedHash === hash, calculatedHash };
14
+ },
15
+ };
16
+ };
17
+ export const fromBackupEntry = (entry) => {
18
+ const { event, hash, originalDataString } = entry.payload;
19
+ return fromCloudEvent(event, hash, originalDataString);
20
+ };
21
+ // An event that the SDK read from a running database verifies its own hash,
22
+ // over the data and the time as the server sent them, which it keeps to
23
+ // itself, so the hash it calculated is not known.
24
+ export const fromDatabaseEvent = (event) => {
25
+ return {
26
+ id: event.id,
27
+ hash: event.hash,
28
+ predecessorhash: event.predecessorhash,
29
+ checkHash: () => {
30
+ assertKnownHashVersion(event.hash);
31
+ try {
32
+ event.verifyHash();
33
+ }
34
+ catch (error) {
35
+ if (error instanceof HashVerificationFailedError) {
36
+ return { isMatching: false, calculatedHash: undefined };
37
+ }
38
+ throw error;
39
+ }
40
+ return { isMatching: true, calculatedHash: undefined };
41
+ },
42
+ };
43
+ };
44
+ // findEventById compares IDs as numbers, as EventSourcingDB reads them, so that
45
+ // an ID in another notation of the same number finds the event.
46
+ export const findEventById = (events, eventId) => {
47
+ const wanted = parseEventId(eventId);
48
+ if (wanted === undefined) {
49
+ return undefined;
50
+ }
51
+ return events.find(event => parseEventId(event.id) === wanted);
52
+ };
@@ -1,16 +1,17 @@
1
- import { calculateEventHash, UnsupportedHashVersionError } from './hash.js';
2
- export const validateChain = (entries) => {
1
+ import { UnsupportedHashVersionError } from './hash.js';
2
+ export const validateChain = (events) => {
3
3
  const errors = [];
4
- for (const [i, entry] of entries.entries()) {
5
- const event = entry.payload.event;
6
- const storedHash = entry.payload.hash;
4
+ for (const [i, event] of events.entries()) {
5
+ const storedHash = event.hash;
7
6
  // Validate hash
8
7
  try {
9
- const calculatedHash = calculateEventHash(event, entry.payload.originalDataString, storedHash);
10
- if (calculatedHash !== storedHash) {
8
+ const { isMatching, calculatedHash } = event.checkHash();
9
+ if (!isMatching) {
11
10
  errors.push({
12
11
  eventId: event.id,
13
- message: `Hash mismatch: expected ${storedHash}, got ${calculatedHash}`,
12
+ message: calculatedHash === undefined
13
+ ? `Hash mismatch: expected ${storedHash}`
14
+ : `Hash mismatch: expected ${storedHash}, got ${calculatedHash}`,
14
15
  });
15
16
  }
16
17
  }
@@ -24,8 +25,8 @@ export const validateChain = (entries) => {
24
25
  }
25
26
  // Validate predecessor hash
26
27
  if (i > 0) {
27
- const previousEntry = entries[i - 1];
28
- const expectedPredecessorHash = previousEntry?.payload.hash;
28
+ const previousEvent = events[i - 1];
29
+ const expectedPredecessorHash = previousEvent?.hash;
29
30
  if (event.predecessorhash !== expectedPredecessorHash) {
30
31
  errors.push({
31
32
  eventId: event.id,
@@ -46,7 +47,7 @@ export const validateChain = (entries) => {
46
47
  }
47
48
  return {
48
49
  isValid: errors.length === 0,
49
- totalEvents: entries.length,
50
+ totalEvents: events.length,
50
51
  errors,
51
52
  };
52
53
  };
@@ -0,0 +1,30 @@
1
+ import { Client } from 'eventsourcingdb';
2
+ import { parseEventId } from './eventId.js';
3
+ // readDatabase reads the events of a running database in the order they were
4
+ // written, through the client SDK, up to the given last event if there is one,
5
+ // or only the given event. The SDK reads the v2 API where the server offers it,
6
+ // whose stream ends with an end item, so that a read cut short fails rather
7
+ // than passing as complete; against a server that offers only the v1 API, it
8
+ // cannot tell the two apart. EventSourcingDB reads an ID in any notation of
9
+ // its number, as the tool does for a backup.
10
+ export const readDatabase = async (url, apiToken, { lastEventId, eventId }) => {
11
+ const options = { recursive: true };
12
+ if (eventId !== undefined) {
13
+ // An ID that names no number names no event, as for a backup, rather than
14
+ // a request that the server refuses.
15
+ if (parseEventId(eventId) === undefined) {
16
+ return [];
17
+ }
18
+ options.lowerBound = { id: eventId, type: 'inclusive' };
19
+ options.upperBound = { id: eventId, type: 'inclusive' };
20
+ }
21
+ else if (lastEventId !== undefined) {
22
+ options.upperBound = { id: lastEventId, type: 'inclusive' };
23
+ }
24
+ const client = new Client(new URL(url), apiToken);
25
+ const events = [];
26
+ for await (const event of client.readEvents('/', options)) {
27
+ events.push(event);
28
+ }
29
+ return events;
30
+ };
@@ -0,0 +1,10 @@
1
+ // describeError names what went wrong, and why, where an error has a cause: a
2
+ // request that fails before the server answers says only that it failed, and
3
+ // leaves the reason, such as a connection that was refused or a host that is
4
+ // not known, to its cause.
5
+ export const describeError = (error) => {
6
+ if (!(error instanceof Error)) {
7
+ return String(error);
8
+ }
9
+ return error.cause instanceof Error ? `${error.message}: ${error.cause.message}` : error.message;
10
+ };
@@ -0,0 +1,8 @@
1
+ // An event ID is an integer, which EventSourcingDB reads with an optional sign.
2
+ const eventIdPattern = /^[+-]?\d+$/u;
3
+ // parseEventId returns the number that an event ID names, so that IDs in other
4
+ // notations of the same number compare as equal, or undefined for text that
5
+ // names no number.
6
+ export const parseEventId = (id) => {
7
+ return eventIdPattern.test(id) ? BigInt(id) : undefined;
8
+ };
package/dist/lib/hash.js CHANGED
@@ -39,22 +39,40 @@ const calculateEventHashOfVersion2 = (event, dataString) => {
39
39
  ].join('\n');
40
40
  return `${hashVersion2Prefix}${getSha256(input)}`;
41
41
  };
42
+ // assertKnownHashVersion refuses a stored hash whose prefix names a version
43
+ // that the tool does not know, the way EventSourcingDB tells them apart: a hash
44
+ // without the prefix is of version 1, and every other hash with it of a version
45
+ // it does not know.
46
+ export const assertKnownHashVersion = (storedHash) => {
47
+ if (!storedHash.startsWith(hashPrefix) || storedHash.startsWith(hashVersion2Prefix)) {
48
+ return;
49
+ }
50
+ const [version = ''] = storedHash.slice(hashPrefix.length).split(':');
51
+ throw new UnsupportedHashVersionError(version);
52
+ };
42
53
  // calculateEventHash computes the hash of an event in the version that its
43
54
  // stored hash names, since an event keeps the version of the hash it was
44
- // written with, or in version 1 without a stored hash to go by. A stored hash
55
+ // written with. An event without a stored hash names no version, which is what
56
+ // calculateEventHashInEveryVersion is for. A stored hash
45
57
  // whose prefix names a version that the tool does not know cannot be verified,
46
58
  // which is not the same as being tampered with, so it is refused rather than
47
59
  // computed in another version that could only fail to match.
48
60
  export const calculateEventHash = (event, originalDataString, storedHash) => {
61
+ assertKnownHashVersion(storedHash);
49
62
  const dataString = originalDataString ?? JSON.stringify(event.data);
50
- if (storedHash === undefined || !storedHash.startsWith(hashPrefix)) {
51
- return calculateEventHashOfVersion1(event, dataString);
52
- }
53
- if (storedHash.startsWith(hashVersion2Prefix)) {
54
- return calculateEventHashOfVersion2(event, dataString);
55
- }
56
- const [version = ''] = storedHash.slice(hashPrefix.length).split(':');
57
- throw new UnsupportedHashVersionError(version);
63
+ return storedHash.startsWith(hashVersion2Prefix)
64
+ ? calculateEventHashOfVersion2(event, dataString)
65
+ : calculateEventHashOfVersion1(event, dataString);
66
+ };
67
+ // calculateEventHashInEveryVersion computes the hash of an event in every
68
+ // version the tool knows, for an event without a stored hash that would tell
69
+ // which version is meant.
70
+ export const calculateEventHashInEveryVersion = (event, originalDataString) => {
71
+ const dataString = originalDataString ?? JSON.stringify(event.data);
72
+ return [
73
+ { version: 1, hash: calculateEventHashOfVersion1(event, dataString) },
74
+ { version: 2, hash: calculateEventHashOfVersion2(event, dataString) },
75
+ ];
58
76
  };
59
77
  export const hashPair = (left, right) => {
60
78
  return crypto.createHash('sha256').update(`${left}${right}`).digest('hex');
@@ -0,0 +1,14 @@
1
+ // describeHashMismatch names an event whose hash does not match its content.
2
+ // Where the hash was calculated by the client SDK rather than by the tool, the
3
+ // SDK keeps it to itself, so only the stored hash is named.
4
+ export const describeHashMismatch = (event, calculatedHash) => {
5
+ if (calculatedHash === undefined) {
6
+ return ['✗ Hash mismatch', `Event ID: ${event.id}`, `Stored hash: ${event.hash}`];
7
+ }
8
+ return [
9
+ '✗ Hash mismatch',
10
+ `Event ID: ${event.id}`,
11
+ `Stored hash: ${event.hash}`,
12
+ `Calculated hash: ${calculatedHash}`,
13
+ ];
14
+ };
@@ -0,0 +1,69 @@
1
+ import { Flags } from '@oclif/core';
2
+ import { readBackupFile } from './backupReader.js';
3
+ import { findEventById, fromBackupEntry, fromDatabaseEvent, } from './chainEvent.js';
4
+ import { readDatabase } from './databaseReader.js';
5
+ import { parseEventId } from './eventId.js';
6
+ // The flags that name where a command reads its events from: a backup, or a
7
+ // running database with its API token. The token is taken as a flag only, as
8
+ // EventSourcingDB and the other tools around it take it.
9
+ export const sourceFlags = {
10
+ backup: Flags.string({ description: 'Path to the backup file' }),
11
+ 'esdb-url': Flags.string({ description: 'URL of a running EventSourcingDB to read from' }),
12
+ 'esdb-api-token': Flags.string({ description: 'API token of the EventSourcingDB to read from' }),
13
+ };
14
+ // getSource returns the source that the flags name, or why they do not name
15
+ // exactly one. The messages name the flags, never the token, so that it does
16
+ // not end up in a terminal or a log.
17
+ export const getSource = (flags) => {
18
+ const filePath = flags.backup || undefined;
19
+ const url = flags['esdb-url'] || undefined;
20
+ const apiToken = flags['esdb-api-token'] || undefined;
21
+ if (filePath !== undefined && url !== undefined) {
22
+ return { refusal: '--backup and --esdb-url cannot be used together' };
23
+ }
24
+ if (filePath !== undefined && apiToken !== undefined) {
25
+ return { refusal: '--backup and --esdb-api-token cannot be used together' };
26
+ }
27
+ if (filePath !== undefined) {
28
+ return { type: 'backup', filePath };
29
+ }
30
+ if (url !== undefined) {
31
+ if (apiToken === undefined) {
32
+ return { refusal: '--esdb-api-token is required when using --esdb-url' };
33
+ }
34
+ return { type: 'database', url, apiToken };
35
+ }
36
+ return { refusal: 'Either --backup or --esdb-url must be provided' };
37
+ };
38
+ // readEvents reads the events of a source, up to the given last event if there
39
+ // is one, so that the Merkle root of an earlier state can be calculated again
40
+ // from a source that has grown since. A database is asked for those events
41
+ // alone, but a bound beyond its latest event reads up to the latest one, so the
42
+ // bound is checked against what was read, for either source: a last event that
43
+ // the source does not hold is refused rather than taken as the end, since the
44
+ // root would then cover other events than the ones it was meant to.
45
+ export const readEvents = async (source, { lastEventId } = {}) => {
46
+ const events = source.type === 'database'
47
+ ? (await readDatabase(source.url, source.apiToken, { lastEventId })).map(fromDatabaseEvent)
48
+ : (await readBackupFile(source.filePath)).map(fromBackupEntry);
49
+ if (lastEventId === undefined) {
50
+ return events;
51
+ }
52
+ const last = parseEventId(lastEventId);
53
+ const index = last === undefined ? -1 : events.findIndex(event => parseEventId(event.id) === last);
54
+ if (index === -1) {
55
+ throw new Error(`the ${source.type} holds no event with ID ${lastEventId}`);
56
+ }
57
+ return events.slice(0, index + 1);
58
+ };
59
+ // readEvent reads the single event with the given ID, or undefined where the
60
+ // source does not hold it. A database is asked for that event alone rather than
61
+ // for all of them.
62
+ export const readEvent = async (source, eventId) => {
63
+ if (source.type === 'database') {
64
+ const [event] = await readDatabase(source.url, source.apiToken, { eventId });
65
+ return event === undefined ? undefined : fromDatabaseEvent(event);
66
+ }
67
+ const events = (await readBackupFile(source.filePath)).map(fromBackupEntry);
68
+ return findEventById(events, eventId);
69
+ };
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "eventsourcingdb-merkle",
3
- "version": "1.3.0",
4
- "description": "Merkle tree utilities for EventSourcingDB backups.",
3
+ "version": "2.1.0",
4
+ "description": "Merkle tree utilities for EventSourcingDB backups and databases.",
5
5
  "author": {
6
6
  "name": "the native web GmbH",
7
7
  "email": "hello@thenativeweb.io"
@@ -17,7 +17,8 @@
17
17
  "commands": "./dist/commands"
18
18
  },
19
19
  "dependencies": {
20
- "@oclif/core": "5.1.2"
20
+ "@oclif/core": "5.1.2",
21
+ "eventsourcingdb": "2.0.1"
21
22
  },
22
23
  "devDependencies": {
23
24
  "@biomejs/biome": "2.5.15",