eventsourcingdb-merkle 2.0.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,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
@@ -73,21 +86,21 @@ Last event ID: 3
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.
83
96
 
84
97
  ### Validating Individual Events
85
98
 
86
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.
87
100
 
88
- #### Validating an Event from a Backup File
101
+ #### Validating an Event from a Backup File or a Database
89
102
 
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:
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:
91
104
 
92
105
  ```shell
93
106
  eventsourcingdb-merkle validate-event-hash --backup=backup.json --event-id=42
@@ -110,6 +123,14 @@ Stored hash: abc123...
110
123
  Calculated hash: def456...
111
124
  ```
112
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
+
113
134
  #### Validating an Event from JSON
114
135
 
115
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:
@@ -127,7 +148,7 @@ Calculated hash (version 2): esdb:hash:v2:def456...
127
148
 
128
149
  ### Generating Merkle Proofs
129
150
 
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`:
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`:
131
152
 
132
153
  ```shell
133
154
  eventsourcingdb-merkle get-proof --backup=backup.json --event-id=42
@@ -1,18 +1,20 @@
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';
7
8
  export default class GetProof extends BaseCommand {
8
- 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';
9
10
  static examples = [
10
11
  '<%= config.bin %> <%= command.id %> --backup=backup.json --event-id=42',
11
12
  '<%= config.bin %> <%= command.id %> --backup=/path/to/backup.json --event-id=0 --json',
12
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',
13
15
  ];
14
16
  static flags = {
15
- backup: Flags.string({ description: 'Path to the backup file' }),
17
+ ...sourceFlags,
16
18
  'event-id': Flags.string({ description: 'Event ID to generate proof for' }),
17
19
  'last-event-id': Flags.string({
18
20
  description: 'ID of the last event the root covers, to prove against the root of an earlier state',
@@ -22,13 +24,14 @@ export default class GetProof extends BaseCommand {
22
24
  static args = {};
23
25
  async run() {
24
26
  const { flags } = await this.parse(GetProof);
25
- if (!flags.backup) {
26
- this.refuseCall('--backup must be provided');
27
+ const source = getSource(flags);
28
+ if ('refusal' in source) {
29
+ this.refuseCall(source.refusal);
27
30
  return;
28
31
  }
29
32
  const eventId = flags['event-id'];
30
33
  if (!eventId) {
31
- this.refuseCall('--event-id is required when using --backup');
34
+ this.refuseCall('--event-id is required when using --backup or --esdb-url');
32
35
  return;
33
36
  }
34
37
  const lastEventId = flags['last-event-id'];
@@ -37,10 +40,9 @@ export default class GetProof extends BaseCommand {
37
40
  return;
38
41
  }
39
42
  try {
40
- const allEntries = await readBackupFile(flags.backup);
41
- const entries = lastEventId === undefined ? allEntries : takeEntriesUpTo(allEntries, lastEventId);
43
+ const events = await readEvents(source, { lastEventId });
42
44
  // 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.
45
+ // proof against its root, although the source holds it.
44
46
  const eventNumber = parseEventId(eventId);
45
47
  const lastEventNumber = lastEventId === undefined ? undefined : parseEventId(lastEventId);
46
48
  if (eventNumber !== undefined &&
@@ -50,16 +52,16 @@ export default class GetProof extends BaseCommand {
50
52
  process.exitCode = 1;
51
53
  return;
52
54
  }
53
- const entry = findEventById(entries, eventId);
54
- if (!entry) {
55
+ const event = findEventById(events, eventId);
56
+ if (!event) {
55
57
  this.log(`✗ Event with ID ${eventId} not found`);
56
58
  process.exitCode = 1;
57
59
  return;
58
60
  }
59
- const hashes = entries.map(e => e.payload.hash);
60
- const proofData = generateMerkleProof(hashes, entry.payload.hash);
61
+ const hashes = events.map(e => e.hash);
62
+ const proofData = generateMerkleProof(hashes, event.hash);
61
63
  const proof = {
62
- eventId: entry.payload.event.id,
64
+ eventId: event.id,
63
65
  ...proofData,
64
66
  };
65
67
  if (flags.json) {
@@ -77,7 +79,7 @@ export default class GetProof extends BaseCommand {
77
79
  }
78
80
  }
79
81
  catch (error) {
80
- this.log(`✗ Failed to generate Merkle proof: ${error instanceof Error ? error.message : String(error)}`);
82
+ this.log(`✗ Failed to generate Merkle proof: ${describeError(error)}`);
81
83
  process.exitCode = 1;
82
84
  }
83
85
  }
@@ -1,17 +1,18 @@
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
5
  import { buildMerkleRoot } from '../lib/merkleTree.js';
6
+ import { getSource, readEvents, sourceFlags } from '../lib/source.js';
7
7
  export default class MerkleRoot extends BaseCommand {
8
- 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';
9
9
  static examples = [
10
10
  '<%= config.bin %> <%= command.id %> --backup=backup.json',
11
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"',
12
13
  ];
13
14
  static flags = {
14
- backup: Flags.string({ description: 'Path to the backup file' }),
15
+ ...sourceFlags,
15
16
  'last-event-id': Flags.string({
16
17
  description: 'ID of the last event to cover, to calculate the root of an earlier state again',
17
18
  }),
@@ -19,8 +20,9 @@ export default class MerkleRoot extends BaseCommand {
19
20
  static args = {};
20
21
  async run() {
21
22
  const { flags } = await this.parse(MerkleRoot);
22
- if (!flags.backup) {
23
- this.refuseCall('--backup must be provided');
23
+ const source = getSource(flags);
24
+ if ('refusal' in source) {
25
+ this.refuseCall(source.refusal);
24
26
  return;
25
27
  }
26
28
  const lastEventId = flags['last-event-id'];
@@ -29,18 +31,17 @@ export default class MerkleRoot extends BaseCommand {
29
31
  return;
30
32
  }
31
33
  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);
34
+ const events = await readEvents(source, { lastEventId });
35
+ const hashes = events.map(event => event.hash);
35
36
  const merkleRoot = buildMerkleRoot(hashes);
36
37
  // The ID of the last event is what calculates this root again later,
37
- // from a backup that has grown since.
38
+ // from a source that has grown since.
38
39
  this.log(`Merkle Root: ${merkleRoot}`);
39
- this.log(`Total events: ${entries.length}`);
40
- this.log(`Last event ID: ${entries.at(-1)?.payload.event.id}`);
40
+ this.log(`Total events: ${events.length}`);
41
+ this.log(`Last event ID: ${events.at(-1)?.id}`);
41
42
  }
42
43
  catch (error) {
43
- this.log(`✗ Failed to calculate Merkle root: ${error instanceof Error ? error.message : String(error)}`);
44
+ this.log(`✗ Failed to calculate Merkle root: ${describeError(error)}`);
44
45
  process.exitCode = 1;
45
46
  }
46
47
  }
@@ -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
  }
@@ -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
- };
@@ -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
+ };
package/dist/lib/hash.js CHANGED
@@ -39,6 +39,17 @@ 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
55
  // written with. An event without a stored hash names no version, which is what
@@ -47,15 +58,11 @@ const calculateEventHashOfVersion2 = (event, dataString) => {
47
58
  // which is not the same as being tampered with, so it is refused rather than
48
59
  // computed in another version that could only fail to match.
49
60
  export const calculateEventHash = (event, originalDataString, storedHash) => {
61
+ assertKnownHashVersion(storedHash);
50
62
  const dataString = originalDataString ?? JSON.stringify(event.data);
51
- if (!storedHash.startsWith(hashPrefix)) {
52
- return calculateEventHashOfVersion1(event, dataString);
53
- }
54
- if (storedHash.startsWith(hashVersion2Prefix)) {
55
- return calculateEventHashOfVersion2(event, dataString);
56
- }
57
- const [version = ''] = storedHash.slice(hashPrefix.length).split(':');
58
- throw new UnsupportedHashVersionError(version);
63
+ return storedHash.startsWith(hashVersion2Prefix)
64
+ ? calculateEventHashOfVersion2(event, dataString)
65
+ : calculateEventHashOfVersion1(event, dataString);
59
66
  };
60
67
  // calculateEventHashInEveryVersion computes the hash of an event in every
61
68
  // version the tool knows, for an event without a stored hash that would tell
@@ -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": "2.0.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",
@@ -1,16 +0,0 @@
1
- import { parseEventId } from './eventId.js';
2
- // takeEntriesUpTo returns the events of a backup up to the one with the given
3
- // ID, which it includes, so that the Merkle root of an earlier state can be
4
- // calculated again from a backup that has grown since. An ID that the backup
5
- // does not hold is refused rather than taken as the end of the backup, since
6
- // the root would then cover other events than the ones it was meant to.
7
- export const takeEntriesUpTo = (entries, lastEventId) => {
8
- const last = parseEventId(lastEventId);
9
- const index = last === undefined
10
- ? -1
11
- : entries.findIndex(entry => parseEventId(entry.payload.event.id) === last);
12
- if (index === -1) {
13
- throw new Error(`the backup holds no event with ID ${lastEventId}`);
14
- }
15
- return entries.slice(0, index + 1);
16
- };