From 2aca426ca384de7e8873a69c00e1fd0933ef0887 Mon Sep 17 00:00:00 2001
From: Martin Helmich <m.helmich@mittwald.de>
Date: Thu, 26 Sep 2024 10:27:27 +0200
Subject: [PATCH] Document how to do webhook verification in PHP

Don't ask why I needed this ;)
---
 docs/contribution/6-reference/4-webhooks.mdx  | 28 +++++++++++++++
 .../contribution/6-reference/4-webhooks.mdx   | 36 ++++++++++++++++---
 2 files changed, 60 insertions(+), 4 deletions(-)

diff --git a/docs/contribution/6-reference/4-webhooks.mdx b/docs/contribution/6-reference/4-webhooks.mdx
index 2b185f79..17d37b84 100644
--- a/docs/contribution/6-reference/4-webhooks.mdx
+++ b/docs/contribution/6-reference/4-webhooks.mdx
@@ -1,8 +1,11 @@
 ---
 title: Lifecycle Webhooks
 ---
+
 import OperationLink from "@site/src/components/OperationLink";
 import SchemaWithExample from "../../../src/components/openapi/SchemaWithExample";
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
 
 mittwald uses lifecycle events to notify the the external application of events that concern it.
 
@@ -544,6 +547,9 @@ You can use common cryptographic libraries in your preferred programming languag
 The complete and unprocessed request body has to be verified using the `verify` method.
 This ensures that the request body was transmitted by mittwald and was not modified by a third party.
 
+<Tabs>
+  <TabItem value="go" label="Go">
+
 ```go
 bodyBytes, err := io.ReadAll(body)
 if err != nil {
@@ -555,6 +561,28 @@ if !ed25519.Verify(publicKey, bodyBytes, signature) {
 }
 ```
 
+  </TabItem>
+  <TabItem value="php" label="PHP">
+
+```php
+$req  = new ExtensionGetPublicKeyRequest($serial);
+$resp = $apiClient->marketplace()->extensionGetPublicKey($req);
+$key = $resp->getBody()->getKey();
+
+$valid = sodium_crypto_sign_verify_detached(
+    base64_decode($signature),
+    $request->getContent(),
+    base64_decode($key),
+);
+
+if (!$valid) {
+    throw new \Exception('invalid request signature');
+}
+```
+
+  </TabItem>
+</Tabs>
+
 ### Reference Implementations of the Validation of Lifecycle Webhooks
 
 TODO
diff --git a/i18n/de/docusaurus-plugin-content-docs/current/contribution/6-reference/4-webhooks.mdx b/i18n/de/docusaurus-plugin-content-docs/current/contribution/6-reference/4-webhooks.mdx
index 145bb0a4..e841bd14 100644
--- a/i18n/de/docusaurus-plugin-content-docs/current/contribution/6-reference/4-webhooks.mdx
+++ b/i18n/de/docusaurus-plugin-content-docs/current/contribution/6-reference/4-webhooks.mdx
@@ -1,8 +1,11 @@
 ---
 title: Lifecycle Webhooks
 ---
+
 import OperationLink from "@site/src/components/OperationLink";
 import SchemaWithExample from "../../../../../../src/components/openapi/SchemaWithExample";
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
 
 Lifecycle Events werden von mittwald genutzt, um die externe Anwendung über sie betreffende Ereignisse zu informieren.
 
@@ -538,16 +541,41 @@ Algorithmus, der zum Erzeugen der Signatur verwendet wurde, derzeit immer [`Ed25
 
 Um die Signatur zu prüfen, kann eine übliche kryptographische Library in der gewählten Programmiersprache verwendet werden. Dazu wird mithilfe der `verify`-Methode der gesamte, unverarbeitete Request Body geprüft. Damit ist sichergestellt, dass der übermittelte Request Body unmodifiziert von mittwald übertragen wurde.
 
-```go
+<Tabs>
+  <TabItem value="go" label="Go">
+
+````go
 bodyBytes, err := io.ReadAll(body)
 if err != nil {
-   return err
+  return err
 }
 
 if !ed25519.Verify(publicKey, bodyBytes, signature) {
-   panic("invalid signature")
+  panic("invalid signature")
 }
-```
+    ```
+
+  </TabItem>
+  <TabItem value="php" label="PHP">
+
+```php
+$req  = new ExtensionGetPublicKeyRequest($serial);
+$resp = $apiClient->marketplace()->extensionGetPublicKey($req);
+$key = $resp->getBody()->getKey();
+
+$valid = sodium_crypto_sign_verify_detached(
+    base64_decode($signature),
+    $request->getContent(),
+    base64_decode($key),
+);
+
+if (!$valid) {
+    throw new \Exception('invalid request signature');
+}
+````
+
+  </TabItem>
+</Tabs>
 
 ### Referenzimplementierungen für die Validierung von Lifecycle Webhooks