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