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 +28 -7
- package/dist/commands/get-proof.js +18 -16
- package/dist/commands/merkle-root.js +14 -13
- package/dist/commands/validate-chain.js +11 -10
- package/dist/commands/validate-event-hash.js +37 -38
- package/dist/lib/backupReader.js +0 -9
- package/dist/lib/chainEvent.js +52 -0
- package/dist/lib/chainValidator.js +12 -11
- package/dist/lib/databaseReader.js +30 -0
- package/dist/lib/describeError.js +10 -0
- package/dist/lib/hash.js +15 -8
- package/dist/lib/hashReport.js +14 -0
- package/dist/lib/source.js +69 -0
- package/package.json +4 -3
- package/dist/lib/lastEventId.js +0 -16
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
26
|
-
|
|
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
|
|
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
|
|
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
|
|
54
|
-
if (!
|
|
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 =
|
|
60
|
-
const proofData = generateMerkleProof(hashes,
|
|
61
|
+
const hashes = events.map(e => e.hash);
|
|
62
|
+
const proofData = generateMerkleProof(hashes, event.hash);
|
|
61
63
|
const proof = {
|
|
62
|
-
eventId:
|
|
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: ${
|
|
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 {
|
|
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
|
-
|
|
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
|
-
|
|
23
|
-
|
|
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
|
|
33
|
-
const
|
|
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
|
|
38
|
+
// from a source that has grown since.
|
|
38
39
|
this.log(`Merkle Root: ${merkleRoot}`);
|
|
39
|
-
this.log(`Total events: ${
|
|
40
|
-
this.log(`Last 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: ${
|
|
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 %> --
|
|
9
|
+
'<%= config.bin %> <%= command.id %> --esdb-url=http://localhost:3000 --esdb-api-token="$ESDB_API_TOKEN"',
|
|
10
10
|
];
|
|
11
11
|
static flags = {
|
|
12
|
-
|
|
12
|
+
...sourceFlags,
|
|
13
13
|
};
|
|
14
14
|
static args = {};
|
|
15
15
|
async run() {
|
|
16
16
|
const { flags } = await this.parse(ValidateChain);
|
|
17
|
-
|
|
18
|
-
|
|
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
|
|
23
|
-
const result = validateChain(
|
|
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: ${
|
|
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 {
|
|
3
|
+
import { fromCloudEvent } from '../lib/chainEvent.js';
|
|
4
|
+
import { describeError } from '../lib/describeError.js';
|
|
4
5
|
import { readEventText } from '../lib/eventText.js';
|
|
5
|
-
import {
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
28
|
-
|
|
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
|
-
|
|
32
|
-
|
|
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
|
-
|
|
61
|
-
if (
|
|
62
|
-
this.
|
|
63
|
-
|
|
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
|
|
67
|
-
|
|
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 =
|
|
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
|
|
79
|
+
let hashCheck;
|
|
80
80
|
try {
|
|
81
|
-
|
|
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: ${
|
|
89
|
+
this.log(`Stored hash: ${event.hash}`);
|
|
90
90
|
process.exitCode = 1;
|
|
91
91
|
return;
|
|
92
92
|
}
|
|
93
|
-
if (
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
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: ${
|
|
102
|
+
this.log(`Hash: ${event.hash}`);
|
|
104
103
|
}
|
|
105
104
|
catch (error) {
|
|
106
|
-
this.log(`✗ Failed to validate event hash: ${
|
|
105
|
+
this.log(`✗ Failed to validate event hash: ${describeError(error)}`);
|
|
107
106
|
process.exitCode = 1;
|
|
108
107
|
}
|
|
109
108
|
}
|
package/dist/lib/backupReader.js
CHANGED
|
@@ -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 {
|
|
2
|
-
export const validateChain = (
|
|
1
|
+
import { UnsupportedHashVersionError } from './hash.js';
|
|
2
|
+
export const validateChain = (events) => {
|
|
3
3
|
const errors = [];
|
|
4
|
-
for (const [i,
|
|
5
|
-
const
|
|
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 =
|
|
10
|
-
if (
|
|
8
|
+
const { isMatching, calculatedHash } = event.checkHash();
|
|
9
|
+
if (!isMatching) {
|
|
11
10
|
errors.push({
|
|
12
11
|
eventId: event.id,
|
|
13
|
-
message:
|
|
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
|
|
28
|
-
const expectedPredecessorHash =
|
|
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:
|
|
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
|
-
|
|
52
|
-
|
|
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.
|
|
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",
|
package/dist/lib/lastEventId.js
DELETED
|
@@ -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
|
-
};
|