feat: Add event signing verification. (#147)

* feat: Add event signing verification.

* Fix tests.

* Fix tests.

Author: goloroden

README.md

@@ -511,10 +511,26 @@ event_type = await client.read_event_type("io.eventsourcingdb.library.book-acqui
 To verify the integrity of an event, call the `verify_hash` 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 raises an error:
 
 ```python
-event.verify_hash();
+event.verify_hash()
 ```
 
-*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.*
+*Note that this only verifies the hash. If you also want to verify the signature, you can skip this step and call `verify_signature` directly, which performs a hash verification internally.*
+
+### Verifying an Event's Signature
+
+To verify the authenticity of an event, call the `verify_signature` 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 raises an error:
+
+```python
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+
+# ...
+
+verification_key = # public key as Ed25519PublicKey
+
+event.verify_signature(verification_key)
+```
 
 ### Using Testcontainers
 
@@ -560,6 +576,24 @@ container = (
 )
 ```
 
+If you want to sign events, call the `with_signing_key` function. This generates a new signing and verification key pair inside the container:
+
+```python
+container = (
+  Container()
+    .with_signing_key()
+)
+```
+
+You can retrieve the private key (for signing) and the public key (for verifying signatures) once the container has been started:
+
+```python
+signing_key = container.get_signing_key()
+verification_key = container.get_verification_key()
+```
+
+The `signing_key` can be used when configuring the container to sign outgoing events. The `verification_key` can be passed to `verify_signature` 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:

eventsourcingdb/container.py

@@ -1,10 +1,14 @@
+import io
 import logging
+import tarfile
 import time
 from http import HTTPStatus
 
 import docker
 import requests
 from docker import DockerClient, errors
+from cryptography.hazmat.primitives.asymmetric import ed25519
+from cryptography.hazmat.primitives import serialization
 
 from .client import Client
 
@@ -21,6 +25,7 @@ def __init__(
         self._docker_client: DockerClient = docker.from_env()
         self._mapped_port: int | None = None
         self._host = "localhost"
+        self._signing_key: ed25519.Ed25519PrivateKey | None = None
 
     def _cleanup_existing_containers(self) -> None:
         try:
@@ -44,20 +49,57 @@ def _cleanup_existing_containers(self) -> None:
 
     def _create_container(self) -> None:
         port_bindings = {f"{self._internal_port}/tcp": None}
+
+        command = [
+            "run",
+            "--api-token",
+            self._api_token,
+            "--data-directory-temporary",
+            "--http-enabled",
+            "--https-enabled=false",
+        ]
+
+        if self._signing_key is not None:
+            target_path = "/etc/esdb/signing-key.pem"
+            command.extend(["--signing-key-file", target_path])
+
         self._container = self._docker_client.containers.run(
             f"{self._image_name}:{self._image_tag}",
-            command=[
-                "run",
-                "--api-token",
-                self._api_token,
-                "--data-directory-temporary",
-                "--http-enabled",
-                "--https-enabled=false",
-            ],
+            command=command,
             ports=port_bindings,  # type: ignore
             detach=True,
         )  # type: ignore
 
+        # Copy signing key into container if needed
+        if self._signing_key is not None:
+            signing_key_bytes = self._signing_key.private_bytes(
+                encoding=serialization.Encoding.PEM,
+                format=serialization.PrivateFormat.PKCS8,
+                encryption_algorithm=serialization.NoEncryption()
+            )
+
+            # Create tar archive with both the directory structure and the key file
+            tar_stream = io.BytesIO()
+            tar = tarfile.TarFile(fileobj=tar_stream, mode='w')
+
+            # Add directory entry
+            dir_info = tarfile.TarInfo(name='esdb')
+            dir_info.type = tarfile.DIRTYPE
+            dir_info.mode = 0o755
+            tar.addfile(dir_info)
+
+            # Add the key file
+            file_info = tarfile.TarInfo(name='esdb/signing-key.pem')
+            file_info.size = len(signing_key_bytes)
+            file_info.mode = 0o644
+            tar.addfile(file_info, io.BytesIO(signing_key_bytes))
+
+            tar.close()
+            tar_stream.seek(0)
+
+            # Put the archive into /etc which should exist
+            self._container.put_archive('/etc', tar_stream)
+
     def _extract_port_from_container_info(self, container_info) -> int | None:
         port = None
         valid_mapping = True
@@ -233,3 +275,17 @@ def with_image_tag(self, tag: str) -> "Container":
     def with_port(self, port: int) -> "Container":
         self._internal_port = port
         return self
+
+    def with_signing_key(self) -> "Container":
+        self._signing_key = ed25519.Ed25519PrivateKey.generate()
+        return self
+
+    def get_signing_key(self) -> ed25519.Ed25519PrivateKey:
+        if self._signing_key is None:
+            raise RuntimeError("Signing key not set.")
+        return self._signing_key
+
+    def get_verification_key(self) -> ed25519.Ed25519PublicKey:
+        if self._signing_key is None:
+            raise RuntimeError("Signing key not set.")
+        return self._signing_key.public_key()

eventsourcingdb/event/event.py

@@ -4,6 +4,8 @@
 from hashlib import sha256
 from typing import Any, TypeVar
 
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+
 from ..errors.internal_error import InternalError
 from ..errors.validation_error import ValidationError
 
@@ -25,6 +27,7 @@ class Event:
     hash: str
     trace_parent: str | None = None
     trace_state: str | None = None
+    signature: str | None = None
 
     @staticmethod
     def parse(unknown_object: dict) -> "Event":
@@ -78,6 +81,10 @@ def parse(unknown_object: dict) -> "Event":
         if trace_state is not None and not isinstance(trace_state, str):
             raise ValidationError(f"Failed to parse trace_state '{trace_state}' to string.")
 
+        signature = unknown_object.get("signature")
+        if signature is not None and not isinstance(signature, str):
+            raise ValidationError(f"Failed to parse signature '{signature}' to string.")
+
         data = unknown_object.get("data")
         if not isinstance(data, dict):
             raise ValidationError(f"Failed to parse data '{data}' to object.")
@@ -95,6 +102,7 @@ def parse(unknown_object: dict) -> "Event":
             hash=hash,
             trace_parent=trace_parent,
             trace_state=trace_state,
+            signature=signature,
         )
         event._time_from_server = time_from_server
 
@@ -130,6 +138,30 @@ def verify_hash(self) -> None:
         if final_hash_hex != self.hash:
             raise ValidationError("Failed to verify hash.")
 
+    def verify_signature(self, verification_key: Ed25519PublicKey) -> None:
+        if self.signature is None:
+            raise ValidationError("Signature must not be none.")
+
+        self.verify_hash()
+
+        signature_prefix = "esdb:signature:v1:"
+
+        if not self.signature.startswith(signature_prefix):
+            raise ValidationError(f"Signature must start with '{signature_prefix}'.")
+
+        signature_hex = self.signature[len(signature_prefix):]
+        try:
+            signature_bytes = bytes.fromhex(signature_hex)
+        except ValueError as error:
+            raise ValidationError("Failed to decode signature.") from error
+
+        hash_bytes = self.hash.encode("utf-8")
+
+        try:
+            verification_key.verify(signature_bytes, hash_bytes)
+        except Exception as error:
+            raise ValidationError("Signature verification failed.") from error
+
     def to_json(self) -> dict[str, Any]:
         json = {
             "specversion": self.spec_version,
@@ -148,6 +180,8 @@ def to_json(self) -> dict[str, Any]:
             json["traceparent"] = self.trace_parent
         if self.trace_state is not None:
             json["tracestate"] = self.trace_state
+        if self.signature is not None:
+            json["signature"] = self.signature
         json["data"] = self.data
 
         return json

pyproject.toml

@@ -8,6 +8,7 @@ readme = "README.md"
 license = "MIT"
 dependencies = [
     "aiohttp==3.13.0",
+    "cryptography==43.0.0",
     "testcontainers==4.13.2",
 ]
 
@@ -29,7 +30,7 @@ build-backend = "hatchling.build"
 
 [tool.bandit]
 exclude_dirs = ["tests", ".venv"]
-skips = ["B101"]  
+skips = ["B101"]
 
 [tool.hatch.build.targets.wheel]
 packages = ["eventsourcingdb"]