feat: Add support for signatures and verification

README.md

@@ -458,6 +458,29 @@ To list a specific event type, call the `readEventType` function with the event
 $eventType = $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:
+
+```php
+$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:
+
+```php
+$verificationKey = // an ed25519 public key
+
+$event->verifySignature($verificationKey);
+```
+
+
 ### Using Testcontainers
 
 Import the `Container` class, call the `start` function to run a test container, get a client, run your test code, and finally call the `stop` function to stop the test container:
@@ -504,6 +527,22 @@ $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:
+
+```php
+$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:
+
+```php
+$signingKey = $container->getSigningKey();
+$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:

composer.json

@@ -25,15 +25,16 @@
   "minimum-stability": "stable",
   "require": {
     "php": ">=8.2",
-    "ext-curl": "*"
+    "ext-curl": "*",
+    "ext-openssl": "*",
+    "ext-sodium": "*",
+    "testcontainers/testcontainers": "1.0.3"
   },
   "require-dev": {
     "phpstan/phpstan": "2.1.25",
     "phpunit/phpunit": "11.5.21",
     "rector/rector": "2.1.7",
-    "symfony/http-client": "7.3.3",
-    "symplify/easy-coding-standard": "12.6.0",
-    "testcontainers/testcontainers": "1.0.3"
+    "symplify/easy-coding-standard": "12.6.0"
   },
   "scripts": {
     "analyze": [
@@ -45,7 +46,7 @@
       "vendor/bin/rector process",
       "vendor/bin/ecs check --fix"
     ],
-    "stan": "vendor/bin/phpstan analyze",
+    "stan": "vendor/bin/phpstan analyze --memory-limit 512M",
     "qa": [
       "@analyze",
       "@test"
@@ -57,7 +58,7 @@
   },
   "config": {
     "allow-plugins": {
-      "php-http/discovery": true
+      "php-http/discovery": false
     },
     "sort-packages": true
   }