feat: Add support for signatures and verification. (#259)

* feat: Add support for signatures and verification.

* Implement verifyHash.

* Implement verifySignatures.

Author: goloroden

README.md

@@ -422,7 +422,29 @@ controller.abort();
 To list a specific event type, call the `readEventType` function with the event type as an argument. The function returns the detailed event type, which includes the schema:
 
 ```typescript
-eventType = await client.readEventType("io.eventsourcingdb.library.book-acquired")
+eventType = await client.readEventType("io.eventsourcingdb.library.book-acquired");
+```
+
+### Verifying an Event's Hash
+
+To verify the integrity of an event, call the `verifyHash` function on the event instance. This recomputes the event's hash locally and compares it to the hash stored in the event. If the hashes differ, the function returns an error:
+
+```typescript
+event.VerifyHash();
+```
+
+*Note that this only verifies the hash. If you also want to verify the signature, you can skip this step and call `verifySignature` directly, which performs a hash verification internally.*
+
+### Verifying an Event's Signature
+
+To verify the authenticity of an event, call the `verifySignature` function on the event instance. This requires the public key that matches the private key used for signing on the server.
+
+The function first verifies the event's hash, and then checks the signature. If any verification step fails, it returns an error:
+
+```typescript
+const verificationKey = // an ed25519 public key
+
+event.verifySignature(verificationKey);
 ```
 
 ### Using Testcontainers
@@ -465,6 +487,22 @@ const container = new Container()
   .withApiToken('secret');
 ```
 
+If you want to sign events, call the `withSigningKey` function. This generates a new signing and verification key pair inside the container:
+
+```typescript
+const container = new Container()
+  .withSigningKey();
+```
+
+You can retrieve the private key (for signing) and the public key (for verifying signatures) once the container has been started:
+
+```typescript
+const signingKey = container.getSigningKey();
+const verificationKey = container.getVerificationKey();
+```
+
+The `signingKey` can be used when configuring the container to sign outgoing events. The `verificationKey` can be passed to `verifySignature` when verifying events read from the database.
+
 #### Configuring the Client Manually
 
 In case you need to set up the client yourself, use the following functions to get details on the container:

package.json

@@ -25,7 +25,7 @@
     "typescript": "5.9.2"
   },
   "scripts": {
-    "analyze": "npx biome check --error-on-warnings .",
+    "analyze": "npx tsc --noEmit && npx biome check --error-on-warnings .",
     "build": "npx tsc --noEmit && npx tsup --clean --dts --format cjs,esm --minify --out-dir=./dist/ ./src/index.ts",
     "format": "npx biome check --write .",
     "qa": "npm run analyze && npm run test",

src/Client.ts

@@ -14,6 +14,21 @@ import { isStreamHeartbeat } from './stream/isStreamHeartbeat.js';
 import { isStreamRow } from './stream/isStreamRow.js';
 import { isStreamSubject } from './stream/isStreamSubject.js';
 import { hasShapeOf } from './types/hasShapeOf.js';
+import { isBoolean } from './types/isBoolean.js';
+import { isString } from './types/isString.js';
+
+interface ResponseBodyPing {
+	type: string;
+}
+
+interface ResponseBodyVerifyApiToken {
+	type: string;
+}
+
+interface ResponseBodyReadEventType {
+	eventType: string;
+	isPhantom: boolean;
+}
 
 class Client {
 	#url: URL;
@@ -39,7 +54,11 @@ class Client {
 		}
 
 		const responseBody = await response.json();
-		if (!hasShapeOf(responseBody, { type: 'string' })) {
+		if (
+			!hasShapeOf<ResponseBodyPing>(responseBody, {
+				type: isString,
+			})
+		) {
 			throw new Error('Failed to parse response.');
 		}
 
@@ -65,7 +84,11 @@ class Client {
 		}
 
 		const responseBody = await response.json();
-		if (!hasShapeOf(responseBody, { type: 'string' })) {
+		if (
+			!hasShapeOf<ResponseBodyVerifyApiToken>(responseBody, {
+				type: isString,
+			})
+		) {
 			throw new Error('Failed to parse response.');
 		}
 
@@ -444,9 +467,9 @@ class Client {
 		}
 		const responseBody = await response.json();
 		if (
-			!hasShapeOf(responseBody, {
-				eventType: 'string',
-				isPhantom: true,
+			!hasShapeOf<ResponseBodyReadEventType>(responseBody, {
+				eventType: isString,
+				isPhantom: isBoolean,
 			})
 		) {
 			throw new Error('Failed to parse response.');

src/CloudEvent.ts

@@ -11,6 +11,7 @@ interface CloudEvent {
 	predecessorhash: string;
 	traceparent?: string;
 	tracestate?: string;
+	signature: string | null;
 }
 
 export type { CloudEvent };

src/Container.ts

@@ -1,12 +1,20 @@
-import type { StartedTestContainer } from 'testcontainers';
+import crypto from 'node:crypto';
+import type { Content, StartedTestContainer } from 'testcontainers';
 import { GenericContainer, Wait } from 'testcontainers';
 import { Client } from './Client.js';
 
+type ContentToCopy = {
+	content: Content;
+	target: string;
+	mode?: number;
+};
+
 class Container {
 	#imageName = 'thenativeweb/eventsourcingdb';
 	#imageTag = 'latest';
 	#internalPort = 3000;
 	#apiToken = 'secret';
+	#signingKey: crypto.KeyObject | undefined;
 	#container: StartedTestContainer | undefined;
 
 	public withImageTag(tag: string): this {
@@ -19,22 +27,44 @@ class Container {
 		return this;
 	}
 
+	public withSigningKey(): this {
+		const { privateKey } = crypto.generateKeyPairSync('ed25519');
+		this.#signingKey = privateKey;
+		return this;
+	}
+
 	public withPort(port: number): this {
 		this.#internalPort = port;
 		return this;
 	}
 
 	public async start(): Promise<void> {
+		const command = [
+			'run',
+			'--api-token',
+			this.#apiToken,
+			'--data-directory-temporary',
+			'--http-enabled',
+			'--https-enabled=false',
+		];
+
+		const contents: ContentToCopy[] = [];
+
+		if (this.#signingKey !== undefined) {
+			command.push('--signing-key-file');
+			command.push('/etc/esdb/signing-key.pem');
+
+			contents.push({
+				content: this.#signingKey.export({ format: 'pem', type: 'pkcs8' }),
+				target: '/etc/esdb/signing-key.pem',
+				mode: 0o777,
+			});
+		}
+
 		this.#container = await new GenericContainer(`${this.#imageName}:${this.#imageTag}`)
 			.withExposedPorts(this.#internalPort)
-			.withCommand([
-				'run',
-				'--api-token',
-				this.#apiToken,
-				'--data-directory-temporary',
-				'--http-enabled',
-				'--https-enabled=false',
-			])
+			.withCommand(command)
+			.withCopyContentToContainer(contents)
 			.withWaitStrategy(Wait.forHttp('/api/v1/ping', this.#internalPort).withStartupTimeout(10_000))
 			.start();
 	}
@@ -70,6 +100,22 @@ class Container {
 		return this.#apiToken;
 	}
 
+	public getSigningKey(): crypto.KeyObject {
+		if (this.#signingKey === undefined) {
+			throw new Error('Signing key not set.');
+		}
+		return this.#signingKey;
+	}
+
+	public getVerificationKey(): crypto.KeyObject {
+		if (this.#signingKey === undefined) {
+			throw new Error('Signing key not set.');
+		}
+
+		const verificationKey = crypto.createPublicKey(this.#signingKey);
+		return verificationKey;
+	}
+
 	public isRunning(): boolean {
 		return this.#container !== undefined;
 	}