From 909f7abaa4595323da61413e2ab5bba1c151b087 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C3=A9r=C3=A9my=20Munsch?= <github@jeremydev.ovh>
Date: Tue, 18 Aug 2026 12:03:22 +0200
Subject: [PATCH] feat(shared): add security interfaces, user details contracts
 and UUID helper

---
 src/Shared/DDD/Exception/NotFoundException.php   |  9 +++++++++
 src/Shared/DDD/Exception/SecurityException.php   |  9 +++++++++
 src/Shared/DDD/Security/UserDetails.php          | 16 ++++++++++++++++
 src/Shared/DDD/Security/UserDetailsProvider.php  | 10 ++++++++++
 src/Shared/DDD/Security/UserIdentifier.php       | 12 ++++++++++++
 src/Shared/DDD/Security/UserType.php             | 12 ++++++++++++
 .../Helpers/Exceptions/InvalidUuidException.php  | 13 +++++++++++++
 src/Shared/Helpers/UuidHelper.php                |  9 +++++++++
 8 files changed, 90 insertions(+)
 create mode 100644 src/Shared/DDD/Exception/NotFoundException.php
 create mode 100644 src/Shared/DDD/Exception/SecurityException.php
 create mode 100644 src/Shared/DDD/Security/UserDetails.php
 create mode 100644 src/Shared/DDD/Security/UserDetailsProvider.php
 create mode 100644 src/Shared/DDD/Security/UserIdentifier.php
 create mode 100644 src/Shared/DDD/Security/UserType.php
 create mode 100644 src/Shared/Helpers/Exceptions/InvalidUuidException.php

diff --git a/src/Shared/DDD/Exception/NotFoundException.php b/src/Shared/DDD/Exception/NotFoundException.php
new file mode 100644
index 0000000..2420ad0
--- /dev/null
+++ b/src/Shared/DDD/Exception/NotFoundException.php
@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Shared\DDD\Exception;
+
+class NotFoundException extends \RuntimeException
+{
+}
diff --git a/src/Shared/DDD/Exception/SecurityException.php b/src/Shared/DDD/Exception/SecurityException.php
new file mode 100644
index 0000000..501c634
--- /dev/null
+++ b/src/Shared/DDD/Exception/SecurityException.php
@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Shared\DDD\Exception;
+
+class SecurityException extends \RuntimeException
+{
+}
diff --git a/src/Shared/DDD/Security/UserDetails.php b/src/Shared/DDD/Security/UserDetails.php
new file mode 100644
index 0000000..1d053ff
--- /dev/null
+++ b/src/Shared/DDD/Security/UserDetails.php
@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Shared\DDD\Security;
+
+interface UserDetails
+{
+    public function id(): string;
+
+    public function name(): string;
+
+    public function type(): UserType;
+
+    public function identifier(): string;
+}
diff --git a/src/Shared/DDD/Security/UserDetailsProvider.php b/src/Shared/DDD/Security/UserDetailsProvider.php
new file mode 100644
index 0000000..83dcab3
--- /dev/null
+++ b/src/Shared/DDD/Security/UserDetailsProvider.php
@@ -0,0 +1,10 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Shared\DDD\Security;
+
+interface UserDetailsProvider
+{
+    public function currentUser(): ?UserDetails;
+}
diff --git a/src/Shared/DDD/Security/UserIdentifier.php b/src/Shared/DDD/Security/UserIdentifier.php
new file mode 100644
index 0000000..69260d6
--- /dev/null
+++ b/src/Shared/DDD/Security/UserIdentifier.php
@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Shared\DDD\Security;
+
+use Shared\DDD\Model\Equatable;
+
+interface UserIdentifier extends Equatable
+{
+    public function value(): string;
+}
diff --git a/src/Shared/DDD/Security/UserType.php b/src/Shared/DDD/Security/UserType.php
new file mode 100644
index 0000000..2a79f90
--- /dev/null
+++ b/src/Shared/DDD/Security/UserType.php
@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Shared\DDD\Security;
+
+use Shared\DDD\Model\Equatable;
+
+interface UserType extends Equatable
+{
+    public function type(): string;
+}
diff --git a/src/Shared/Helpers/Exceptions/InvalidUuidException.php b/src/Shared/Helpers/Exceptions/InvalidUuidException.php
new file mode 100644
index 0000000..8031744
--- /dev/null
+++ b/src/Shared/Helpers/Exceptions/InvalidUuidException.php
@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Shared\Helpers\Exceptions;
+
+final class InvalidUuidException extends \InvalidArgumentException
+{
+    public static function forValue(string $uuid): self
+    {
+        return new self("Invalid UUID: {$uuid}");
+    }
+}
diff --git a/src/Shared/Helpers/UuidHelper.php b/src/Shared/Helpers/UuidHelper.php
index 2a5cb4c..4571ea7 100644
--- a/src/Shared/Helpers/UuidHelper.php
+++ b/src/Shared/Helpers/UuidHelper.php
@@ -5,7 +5,9 @@ declare(strict_types=1);
 namespace Shared\Helpers;
 
 use Ramsey\Uuid\Rfc4122\FieldsInterface as Rfc4122FieldsInterface;
+use Ramsey\Uuid\Uuid;
 use Ramsey\Uuid\UuidInterface;
+use Shared\Helpers\Exceptions\InvalidUuidException;
 
 final readonly class UuidHelper
 {
@@ -44,4 +46,11 @@ final readonly class UuidHelper
 
         return 0;
     }
+
+    public static function validateUuid(UuidInterface $uuid): void
+    {
+        if (! Uuid::isValid($uuid->toString())) {
+            throw InvalidUuidException::forValue($uuid->toString());
+        }
+    }
 }