eventsourcingdb-merkle 1.1.13 → 1.3.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
@@ -45,6 +45,14 @@ Event 42: Hash mismatch: expected abc..., got def...
45
45
  Event 43: Predecessor hash mismatch: expected def..., got ghi...
46
46
  ```
47
47
 
48
+ An event whose hash names a version of the hash that the tool does not know is listed as such, rather than as a mismatch:
49
+
50
+ ```
51
+ Event 44: Unsupported hash version: v3
52
+ ```
53
+
54
+ Such an event cannot be verified, which is not the same as being tampered with, and a newer version of the tool may know its version.
55
+
48
56
  *Note that the command will exit with a non-zero exit code if the chain is invalid, which makes it suitable for use in CI/CD pipelines.*
49
57
 
50
58
  ### Calculating the Merkle Root
@@ -93,13 +101,13 @@ Calculated hash: def456...
93
101
 
94
102
  #### Validating an Event from JSON
95
103
 
96
- 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:
104
+ 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:
97
105
 
98
106
  ```shell
99
- eventsourcingdb-merkle validate-event-hash --event='{"specversion":"1.0","id":"0",...}'
107
+ eventsourcingdb-merkle validate-event-hash --event='{"specversion":"1.0","id":"0",...,"hash":"esdb:hash:v2:..."}'
100
108
  ```
101
109
 
102
- If you provide a CloudEvent without a stored hash, the command simply calculates and displays the hash:
110
+ If you provide a CloudEvent without a stored hash, the command simply calculates and displays the hash of version 1, since nothing tells which version is meant:
103
111
 
104
112
  ```
105
113
  Calculated hash: abc123...
@@ -195,11 +203,21 @@ Merkle Root: d1f6713af7ba3896ff238bb51f3986b2bad53b09bda7f23370e0a8b6eb97eeab
195
203
 
196
204
  ## Understanding the Technical Details
197
205
 
198
- The tool implements Merkle trees using SHA-256 hashing, following the EventSourcingDB specification for event hash calculation. Event hashes are computed by first creating a metadata string from the CloudEvents fields, then hashing the metadata and the data separately, and finally hashing the concatenation of both hashes. 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.
206
+ The tool implements Merkle trees using SHA-256 hashing, following the EventSourcingDB specification for event hash calculation, which knows two versions. An event keeps the version of the hash it was written with, so the tool verifies every hash in the version it names:
207
+
208
+ - A hash of version 2, which EventSourcingDB writes from release 1.3 on, starts with `esdb:hash:v2:`. It is the SHA-256 of that prefix and of the fields `specversion`, `id`, `predecessorhash`, `time`, `source`, `subject`, `type`, `datacontenttype`, `traceparent`, `tracestate`, and `data`, each on a line of its own, with `-` for a field that the event does not have.
209
+ - A hash without a prefix is of version 1. It is computed by first creating a metadata string from the CloudEvents fields, then hashing the metadata and the data separately, and finally hashing the concatenation of both hashes. It covers neither `traceparent` nor `tracestate`.
210
+
211
+ 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.
212
+
213
+ The Merkle tree is constructed by treating event hashes, as they are stored, prefix included, as leaf nodes. Internal nodes are created by hashing the concatenation of their child hashes. If the number of nodes at any level is odd, the last node is duplicated to create a complete binary tree. This process continues until a single root hash remains.
214
+
215
+ 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:
199
216
 
200
- The Merkle tree is constructed by treating event hashes as leaf nodes. Internal nodes are created by hashing the concatenation of their child hashes. If the number of nodes at any level is odd, the last node is duplicated to create a complete binary tree. This process continues until a single root hash remains.
217
+ - A backup of the v1 API, which EventSourcingDB writes on `/api/v1/backup`, holds a JSON object with a `type` and a `payload` field on each line. A line of the type `event` holds a CloudEvents-compliant event and its hash. A line of the type `schema` holds the schema of an event type, which the tool skips, since neither the hashes nor the chain cover it.
218
+ - A backup of the v2 API, which EventSourcingDB writes on `/api/v2/management/create-backup` from release 1.3 on, holds a JSON object with a `type` and a `data` field on each line. It begins with a line of the type `backup`, which names the version of its format, and ends with a line of the type `end`. An incremental backup follows on the last event of the backup before it. To verify one, append it to the full backup and the increments before it, in their order, as a restore takes them, for example with `cat full.ndjson increment-1.ndjson increment-2.ndjson`: across them, the chain is the ordinary chain of the events.
201
219
 
202
- Backup files are expected to be in the NDJSON format that EventSourcingDB writes on `/api/v1/backup`, where each line contains a JSON object with a `type` and a `payload` field. A line of the type `event` holds a CloudEvents-compliant event and its hash. A line of the type `schema` holds the schema of an event type, which the tool skips, since neither the hashes nor the chain cover it. A backup that holds a line of the type `error` was cut short, and the tool refuses it, as it refuses a line of any other type or one that is not valid JSON, naming the line.
220
+ A backup that holds a line of the type `error` was cut short, and the tool refuses it, as it refuses a line of any type that its format does not know, a line that is not valid JSON, and a backup of the v2 API whose structure a restore would refuse, naming the line.
203
221
 
204
222
  ## Running Quality Assurance
205
223
 
@@ -1,8 +1,8 @@
1
1
  import { Flags } from '@oclif/core';
2
2
  import BaseCommand from '../lib/BaseCommand.js';
3
3
  import { findEventById, readBackupFile } from '../lib/backupReader.js';
4
- import { calculateEventHash } from '../lib/hash.js';
5
- import { getCompactValue } from '../lib/rawJson.js';
4
+ import { readEventText } from '../lib/eventText.js';
5
+ import { calculateEventHash, UnsupportedHashVersionError } from '../lib/hash.js';
6
6
  export default class ValidateEventHash extends BaseCommand {
7
7
  static description = 'Validate the hash of a specific event (with or without backup file)';
8
8
  static examples = [
@@ -39,27 +39,26 @@ export default class ValidateEventHash extends BaseCommand {
39
39
  const filePath = flags.file;
40
40
  const eventId = flags['event-id'];
41
41
  try {
42
- let entry;
43
42
  let event;
44
43
  let storedHash;
45
44
  let originalDataString;
46
45
  if (flags.event) {
47
- // Parse event from JSON string
48
- const parsed = JSON.parse(flags.event);
49
- // Check if it's a BackupEntry or a CloudEvent
50
- if ('type' in parsed && parsed.type === 'event' && 'payload' in parsed) {
51
- entry = parsed;
52
- event = entry.payload.event;
53
- storedHash = entry.payload.hash;
54
- originalDataString = getCompactValue(flags.event, ['payload', 'event', 'data']);
46
+ const eventFromText = readEventText(flags.event);
47
+ if (eventFromText === undefined) {
48
+ this.log('✗ --event is neither an event nor a line of a backup or of read-events');
49
+ this.log('See more help with --help');
50
+ process.exitCode = 2;
51
+ return;
55
52
  }
56
- else {
57
- event = parsed;
53
+ if (eventFromText.storedHash === undefined) {
58
54
  // No stored hash to compare against
59
- const calculatedHash = calculateEventHash(event, getCompactValue(flags.event, ['data']));
55
+ const calculatedHash = calculateEventHash(eventFromText.event, eventFromText.originalDataString);
60
56
  this.log(`Calculated hash: ${calculatedHash}`);
61
57
  return;
62
58
  }
59
+ event = eventFromText.event;
60
+ storedHash = eventFromText.storedHash;
61
+ originalDataString = eventFromText.originalDataString;
63
62
  }
64
63
  else {
65
64
  // Read from file
@@ -69,7 +68,7 @@ export default class ValidateEventHash extends BaseCommand {
69
68
  return;
70
69
  }
71
70
  const entries = await readBackupFile(filePath);
72
- entry = findEventById(entries, eventId);
71
+ const entry = findEventById(entries, eventId);
73
72
  if (!entry) {
74
73
  this.log(`✗ Event with ID ${eventId} not found`);
75
74
  process.exitCode = 1;
@@ -79,7 +78,22 @@ export default class ValidateEventHash extends BaseCommand {
79
78
  storedHash = entry.payload.hash;
80
79
  originalDataString = entry.payload.originalDataString;
81
80
  }
82
- const calculatedHash = calculateEventHash(event, originalDataString);
81
+ // A hash of a version the tool does not know is no mismatch, so it is
82
+ // reported apart from one, with the hash that names the version.
83
+ let calculatedHash;
84
+ try {
85
+ calculatedHash = calculateEventHash(event, originalDataString, storedHash);
86
+ }
87
+ catch (error) {
88
+ if (!(error instanceof UnsupportedHashVersionError)) {
89
+ throw error;
90
+ }
91
+ this.log(`✗ ${error.message}`);
92
+ this.log(`Event ID: ${event.id}`);
93
+ this.log(`Stored hash: ${storedHash}`);
94
+ process.exitCode = 1;
95
+ return;
96
+ }
83
97
  if (calculatedHash !== storedHash) {
84
98
  this.log(`✗ Hash mismatch`);
85
99
  this.log(`Event ID: ${event.id}`);
@@ -1,7 +1,13 @@
1
1
  import { createReadStream } from 'node:fs';
2
2
  import { access } from 'node:fs/promises';
3
3
  import { createInterface } from 'node:readline';
4
- import { getCompactValue } from './rawJson.js';
4
+ import { isObject } from './isObject.js';
5
+ import { getCompactValue, getRawValue } from './rawJson.js';
6
+ // The version of the format in which the v2 API writes a backup. The backups
7
+ // of the v1 API carry no version of their own.
8
+ const backupFormatVersion = 2;
9
+ // An event ID is an integer, which EventSourcingDB reads with an optional sign.
10
+ const eventIdPattern = /^[+-]?\d+$/u;
5
11
  export const readBackupFile = async (filePath) => {
6
12
  // Check if file exists and is readable
7
13
  try {
@@ -16,62 +22,210 @@ export const readBackupFile = async (filePath) => {
16
22
  input: fileStream,
17
23
  crlfDelay: Number.POSITIVE_INFINITY,
18
24
  });
25
+ let formatReader;
19
26
  let lineNumber = 0;
20
- for await (const line of rl) {
27
+ for await (const text of rl) {
21
28
  lineNumber++;
22
- if (line.trim() === '') {
29
+ if (text.trim() === '') {
23
30
  continue;
24
31
  }
25
- const entry = readLine(line, lineNumber);
32
+ const line = parseLine(text, lineNumber);
33
+ // A server sends heartbeats while it reads a large store, and they carry
34
+ // nothing to verify.
35
+ if (line.type === 'heartbeat') {
36
+ continue;
37
+ }
38
+ // A backup that the v1 API wrote begins with a line of its own rather than
39
+ // with a backup line, and holds payloads rather than data, which is how
40
+ // the restore of EventSourcingDB tells the two formats apart as well.
41
+ formatReader ??=
42
+ line.type !== 'backup' && line.payload !== undefined ? createV1Reader() : createV2Reader();
43
+ const entry = formatReader.readLine(line);
26
44
  if (entry !== undefined) {
27
45
  entries.push(entry);
28
46
  }
29
47
  }
48
+ formatReader?.finish();
30
49
  return entries;
31
50
  };
32
- // readLine reads a line of a backup, and returns the event it holds, or nothing
33
- // for a line that holds a schema, which neither the hashes nor the chain cover.
34
- // Every other line ends the reading: an error line means that the backup was
35
- // cut short, and a line of a type the format does not know means that the file
36
- // is no backup the tool can read. Skipping either would let the events before
37
- // it pass as a complete, valid chain.
38
- const readLine = (line, lineNumber) => {
51
+ const parseLine = (text, lineNumber) => {
39
52
  let parsed;
40
53
  try {
41
- parsed = JSON.parse(line);
54
+ parsed = JSON.parse(text);
42
55
  }
43
56
  catch (error) {
44
57
  throw new Error(`line ${lineNumber} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
45
58
  }
46
- const { type, payload } = (typeof parsed === 'object' && parsed !== null ? parsed : {});
59
+ const { type, payload, data } = isObject(parsed) ? parsed : {};
47
60
  if (typeof type !== 'string') {
48
61
  throw new Error(`line ${lineNumber} has no type`);
49
62
  }
50
- switch (type) {
51
- case 'schema':
52
- return undefined;
53
- case 'error':
54
- throw new Error(`the backup is incomplete: line ${lineNumber} reports an error: ${typeof payload === 'string' ? payload : JSON.stringify(payload)}`);
55
- case 'event':
56
- return readEventLine(line, payload, lineNumber);
57
- default:
58
- throw new Error(`line ${lineNumber} has an unknown type: ${type}`);
59
- }
63
+ return { text, number: lineNumber, type, payload, data };
64
+ };
65
+ // A backup of the v1 API holds a line for every schema, which neither the hashes
66
+ // nor the chain cover, and a line for every event. Every other line ends the
67
+ // reading: an error line means that the backup was cut short, and a line of a
68
+ // type the format does not know means that the file is no backup the tool can
69
+ // read. Skipping either would let the events before it pass as a complete,
70
+ // valid chain.
71
+ const createV1Reader = () => {
72
+ return {
73
+ readLine: line => {
74
+ switch (line.type) {
75
+ case 'schema':
76
+ return undefined;
77
+ case 'error':
78
+ throw new Error(`the backup is incomplete: line ${line.number} reports an error: ${typeof line.payload === 'string' ? line.payload : JSON.stringify(line.payload)}`);
79
+ case 'event':
80
+ return readV1EventLine(line);
81
+ default:
82
+ throw new Error(`line ${line.number} has an unknown type: ${line.type}`);
83
+ }
84
+ },
85
+ finish: () => {
86
+ // The format has no line that ends it, so a backup that was cut short
87
+ // without an error line cannot be told from a complete one.
88
+ },
89
+ };
60
90
  };
61
- const readEventLine = (line, payload, lineNumber) => {
62
- const { event, hash } = (typeof payload === 'object' && payload !== null ? payload : {});
63
- if (typeof event !== 'object' || event === null) {
64
- throw new Error(`line ${lineNumber} has an event line without an event`);
91
+ const readV1EventLine = (line) => {
92
+ const { event, hash } = isObject(line.payload) ? line.payload : {};
93
+ if (!isObject(event)) {
94
+ throw new Error(`line ${line.number} has an event line without an event`);
65
95
  }
66
96
  if (typeof hash !== 'string') {
67
- throw new Error(`line ${lineNumber} has an event line without a hash`);
97
+ throw new Error(`line ${line.number} has an event line without a hash`);
68
98
  }
69
- const entry = {
99
+ return {
70
100
  type: 'event',
71
- payload: { event: event, hash },
101
+ payload: {
102
+ event: event,
103
+ hash,
104
+ originalDataString: getCompactValue(line.text, ['payload', 'event', 'data']),
105
+ },
106
+ };
107
+ };
108
+ // A backup of the v2 API is a sequence of parts in one file: a full backup,
109
+ // followed by any number of increments, each beginning with a backup line and
110
+ // ending with an end line, as the restore of EventSourcingDB takes them. An
111
+ // increment follows on the event that the part before it ended at, so across
112
+ // the parts the chain is the ordinary chain of the events. The reader checks the
113
+ // structure as the restore does, since a backup that the restore refuses holds
114
+ // no chain that could be restored, but leaves the values of the events and the
115
+ // schemas to the restore, which checks them with the rules of the server.
116
+ const createV2Reader = () => {
117
+ let partIndex = -1;
118
+ let isPartOpen = false;
119
+ let hasPartEvents = false;
120
+ let endedAt;
121
+ const readBackupLine = (line) => {
122
+ if (isPartOpen) {
123
+ throw new Error(`line ${line.number} begins a part before the part before it ended`);
124
+ }
125
+ const { lastBackedUpEvent } = isObject(line.data) ? line.data : {};
126
+ partIndex++;
127
+ // The restore reads the version as the text of a number, so it takes one
128
+ // in quotes as well, and counts null as a version that is left out.
129
+ const rawFormatVersion = getRawValue(line.text, ['data', 'formatVersion']);
130
+ const formatVersion = rawFormatVersion === undefined || rawFormatVersion === 'null'
131
+ ? undefined
132
+ : rawFormatVersion.startsWith('"')
133
+ ? JSON.parse(rawFormatVersion)
134
+ : rawFormatVersion;
135
+ if (formatVersion !== String(backupFormatVersion)) {
136
+ throw new Error(`line ${line.number} has an unsupported backup format version: ${formatVersion ?? 'none'}`);
137
+ }
138
+ // The first part is a full backup, and every later one follows on the event
139
+ // the part before it ended at, or on its anchor, where it held no event.
140
+ if (partIndex === 0 && lastBackedUpEvent !== null && lastBackedUpEvent !== undefined) {
141
+ throw new Error(`line ${line.number} begins an increment, but a backup has to begin with a full backup`);
142
+ }
143
+ if (partIndex > 0 && !isSameEvent(lastBackedUpEvent, endedAt)) {
144
+ throw new Error(`line ${line.number} begins an increment that does not follow on the part before it`);
145
+ }
146
+ isPartOpen = true;
147
+ hasPartEvents = false;
148
+ return undefined;
149
+ };
150
+ const readEventLine = (line) => {
151
+ if (!isObject(line.data)) {
152
+ throw new Error(`line ${line.number} has an event line without an event`);
153
+ }
154
+ const { hash } = line.data;
155
+ if (typeof hash !== 'string') {
156
+ throw new Error(`line ${line.number} has an event line without a hash`);
157
+ }
158
+ const event = line.data;
159
+ hasPartEvents = true;
160
+ endedAt = { id: event.id, hash };
161
+ return {
162
+ type: 'event',
163
+ payload: {
164
+ event,
165
+ hash,
166
+ originalDataString: getCompactValue(line.text, ['data', 'data']),
167
+ },
168
+ };
169
+ };
170
+ return {
171
+ readLine: line => {
172
+ if (!isPartOpen && line.type !== 'backup') {
173
+ throw new Error(`line ${line.number} has to begin a part with a backup line, but has the type ${line.type}`);
174
+ }
175
+ switch (line.type) {
176
+ case 'backup':
177
+ return readBackupLine(line);
178
+ case 'eventSchema':
179
+ if (hasPartEvents) {
180
+ throw new Error(`line ${line.number} holds a schema after the events of its part`);
181
+ }
182
+ return undefined;
183
+ case 'event':
184
+ return readEventLine(line);
185
+ case 'lastBackedUpEvent':
186
+ // The event a part ended at follows from its events or its anchor
187
+ // already, so the line that names it adds nothing to check.
188
+ return undefined;
189
+ case 'error': {
190
+ const { description } = isObject(line.data) ? line.data : {};
191
+ throw new Error(`the backup is incomplete: line ${line.number} reports an error: ${typeof description === 'string' ? description : JSON.stringify(line.data)}`);
192
+ }
193
+ case 'end':
194
+ isPartOpen = false;
195
+ return undefined;
196
+ default:
197
+ throw new Error(`line ${line.number} has an unknown type: ${line.type}`);
198
+ }
199
+ },
200
+ finish: () => {
201
+ if (isPartOpen) {
202
+ throw new Error(`the backup is incomplete: part ${partIndex} lacks its end line`);
203
+ }
204
+ },
72
205
  };
73
- entry.payload.originalDataString = getCompactValue(line, ['payload', 'event', 'data']);
74
- return entry;
206
+ };
207
+ // isSameEvent tells whether the anchor that an increment names, as its backup
208
+ // line holds it, is the event that the part before it ended at, by its ID as a
209
+ // number, since creating a backup takes the ID in any notation that
210
+ // EventSourcingDB reads, and by its hash. An anchor of null names no event, and
211
+ // follows on a part that ended at none, such as a full backup of an empty store.
212
+ // Any other anchor that does not name an event by its ID and hash follows on
213
+ // nothing.
214
+ const isSameEvent = (anchor, endedAt) => {
215
+ if (anchor === null || anchor === undefined) {
216
+ return endedAt === undefined;
217
+ }
218
+ if (endedAt === undefined || !isObject(anchor)) {
219
+ return false;
220
+ }
221
+ const { id, hash } = anchor;
222
+ if (typeof id !== 'string' || typeof hash !== 'string') {
223
+ return false;
224
+ }
225
+ if (!eventIdPattern.test(id) || !eventIdPattern.test(endedAt.id)) {
226
+ return false;
227
+ }
228
+ return BigInt(id) === BigInt(endedAt.id) && hash === endedAt.hash;
75
229
  };
76
230
  export const findEventById = (entries, eventId) => {
77
231
  return entries.find(entry => entry.payload.event.id === eventId);
@@ -1,4 +1,4 @@
1
- import { calculateEventHash } from './hash.js';
1
+ import { calculateEventHash, UnsupportedHashVersionError } from './hash.js';
2
2
  export const validateChain = (entries) => {
3
3
  const errors = [];
4
4
  for (const [i, entry] of entries.entries()) {
@@ -6,7 +6,7 @@ export const validateChain = (entries) => {
6
6
  const storedHash = entry.payload.hash;
7
7
  // Validate hash
8
8
  try {
9
- const calculatedHash = calculateEventHash(event, entry.payload.originalDataString);
9
+ const calculatedHash = calculateEventHash(event, entry.payload.originalDataString, storedHash);
10
10
  if (calculatedHash !== storedHash) {
11
11
  errors.push({
12
12
  eventId: event.id,
@@ -17,7 +17,9 @@ export const validateChain = (entries) => {
17
17
  catch (error) {
18
18
  errors.push({
19
19
  eventId: event.id,
20
- message: `Failed to calculate hash: ${error instanceof Error ? error.message : String(error)}`,
20
+ message: error instanceof UnsupportedHashVersionError
21
+ ? error.message
22
+ : `Failed to calculate hash: ${error instanceof Error ? error.message : String(error)}`,
21
23
  });
22
24
  }
23
25
  // Validate predecessor hash
@@ -0,0 +1,53 @@
1
+ import { isObject } from './isObject.js';
2
+ import { getCompactValue } from './rawJson.js';
3
+ const isEvent = (value) => {
4
+ return isObject(value) && typeof value.specversion === 'string';
5
+ };
6
+ // readEventText reads an event from text in every form one can copy it from:
7
+ // a line of a backup of the v1 API, which holds the event and its hash side by
8
+ // side, a line of read-events of the v1 API, which holds the event with its
9
+ // hash, a line of a backup or of read-events of the v2 API, which holds the
10
+ // event with its hash as data, or the event alone, with its hash or without.
11
+ // The data is taken from the text rather than from what JSON.parse makes of
12
+ // it, since the hash covers it as EventSourcingDB wrote it. Text in any other
13
+ // form gives undefined, a line whose event or hash is missing included, since
14
+ // a line carries no spec version of its own and so is never taken for an event
15
+ // alone.
16
+ export const readEventText = (text) => {
17
+ const parsed = JSON.parse(text);
18
+ if (isObject(parsed) && parsed.type === 'event' && isObject(parsed.payload)) {
19
+ const { payload } = parsed;
20
+ if (isEvent(payload.event) && typeof payload.hash === 'string') {
21
+ return {
22
+ event: payload.event,
23
+ storedHash: payload.hash,
24
+ originalDataString: getCompactValue(text, ['payload', 'event', 'data']),
25
+ };
26
+ }
27
+ if (isEvent(payload) && typeof payload.hash === 'string') {
28
+ return {
29
+ event: payload,
30
+ storedHash: payload.hash,
31
+ originalDataString: getCompactValue(text, ['payload', 'data']),
32
+ };
33
+ }
34
+ }
35
+ if (isObject(parsed) && parsed.type === 'event' && isEvent(parsed.data)) {
36
+ const { data } = parsed;
37
+ if (typeof data.hash === 'string') {
38
+ return {
39
+ event: data,
40
+ storedHash: data.hash,
41
+ originalDataString: getCompactValue(text, ['data', 'data']),
42
+ };
43
+ }
44
+ }
45
+ if (isEvent(parsed)) {
46
+ return {
47
+ event: parsed,
48
+ storedHash: typeof parsed.hash === 'string' ? parsed.hash : undefined,
49
+ originalDataString: getCompactValue(text, ['data']),
50
+ };
51
+ }
52
+ return undefined;
53
+ };
package/dist/lib/hash.js CHANGED
@@ -1,12 +1,60 @@
1
1
  import crypto from 'node:crypto';
2
- export const calculateEventHash = (event, originalDataString) => {
2
+ // A hash that names its version starts with this prefix. A hash without it is
3
+ // of version 1, which predates the prefix.
4
+ const hashPrefix = 'esdb:hash:';
5
+ const hashVersion2Prefix = `${hashPrefix}v2:`;
6
+ // The input of a hash of version 2 writes a field that the event does not have
7
+ // as this, which no value of such a field can be.
8
+ const missingField = '-';
9
+ export class UnsupportedHashVersionError extends Error {
10
+ constructor(version) {
11
+ super(`Unsupported hash version: ${version}`);
12
+ this.name = 'UnsupportedHashVersionError';
13
+ }
14
+ }
15
+ const getSha256 = (input) => {
16
+ return crypto.createHash('sha256').update(input).digest('hex');
17
+ };
18
+ // The hash of version 1 covers neither traceparent nor tracestate.
19
+ const calculateEventHashOfVersion1 = (event, dataString) => {
3
20
  const metadata = `${event.specversion}|${event.id}|${event.predecessorhash}|${event.time}|${event.source}|${event.subject}|${event.type}|${event.datacontenttype}`;
4
- const metadataHash = crypto.createHash('sha256').update(metadata).digest('hex');
5
- // Use original data string if available to preserve Unicode escapes
21
+ return getSha256(`${getSha256(metadata)}${getSha256(dataString)}`);
22
+ };
23
+ // The hash of version 2 covers the prefix and every field, each on a line of its
24
+ // own, without a final line break, as EventSourcingDB computes it.
25
+ const calculateEventHashOfVersion2 = (event, dataString) => {
26
+ const input = [
27
+ hashVersion2Prefix,
28
+ event.specversion,
29
+ event.id,
30
+ event.predecessorhash,
31
+ event.time,
32
+ event.source,
33
+ event.subject,
34
+ event.type,
35
+ event.datacontenttype,
36
+ event.traceparent ?? missingField,
37
+ event.tracestate ?? missingField,
38
+ dataString,
39
+ ].join('\n');
40
+ return `${hashVersion2Prefix}${getSha256(input)}`;
41
+ };
42
+ // calculateEventHash computes the hash of an event in the version that its
43
+ // stored hash names, since an event keeps the version of the hash it was
44
+ // written with, or in version 1 without a stored hash to go by. A stored hash
45
+ // whose prefix names a version that the tool does not know cannot be verified,
46
+ // which is not the same as being tampered with, so it is refused rather than
47
+ // computed in another version that could only fail to match.
48
+ export const calculateEventHash = (event, originalDataString, storedHash) => {
6
49
  const dataString = originalDataString ?? JSON.stringify(event.data);
7
- const dataHash = crypto.createHash('sha256').update(dataString).digest('hex');
8
- const finalHash = crypto.createHash('sha256').update(`${metadataHash}${dataHash}`).digest('hex');
9
- return finalHash;
50
+ if (storedHash === undefined || !storedHash.startsWith(hashPrefix)) {
51
+ return calculateEventHashOfVersion1(event, dataString);
52
+ }
53
+ if (storedHash.startsWith(hashVersion2Prefix)) {
54
+ return calculateEventHashOfVersion2(event, dataString);
55
+ }
56
+ const [version = ''] = storedHash.slice(hashPrefix.length).split(':');
57
+ throw new UnsupportedHashVersionError(version);
10
58
  };
11
59
  export const hashPair = (left, right) => {
12
60
  return crypto.createHash('sha256').update(`${left}${right}`).digest('hex');
@@ -0,0 +1,3 @@
1
+ export const isObject = (value) => {
2
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
3
+ };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "eventsourcingdb-merkle",
3
- "version": "1.1.13",
3
+ "version": "1.3.0",
4
4
  "description": "Merkle tree utilities for EventSourcingDB backups.",
5
5
  "author": {
6
6
  "name": "the native web GmbH",