From 52166feca2ca3af86992738e65ef9397bf39f0ee Mon Sep 17 00:00:00 2001
From: Sebastian Krupinski <krupinski01@gmail.com>
Date: Fri, 28 Aug 2026 19:36:43 -0400
Subject: [PATCH] refactor(core): centralize reserved system user identity

Signed-off-by: Sebastian Krupinski <krupinski01@gmail.com>
---
 .../Mail/Provider/ProviderBaseInterface.php   | 11 +++-----
 shared/lib/Resource/SystemIdentity.php        | 20 +++++++++++++++
 .../php/Unit/Resource/SystemIdentityTest.php  | 25 +++++++++++++++++++
 3 files changed, 48 insertions(+), 8 deletions(-)
 create mode 100644 shared/lib/Resource/SystemIdentity.php
 create mode 100644 tests/php/Unit/Resource/SystemIdentityTest.php

diff --git a/shared/lib/Mail/Provider/ProviderBaseInterface.php b/shared/lib/Mail/Provider/ProviderBaseInterface.php
index 592bdb7..81b4223 100644
--- a/shared/lib/Mail/Provider/ProviderBaseInterface.php
+++ b/shared/lib/Mail/Provider/ProviderBaseInterface.php
@@ -11,6 +11,7 @@ namespace KTXF\Mail\Provider;
 
 use KTXF\Mail\Service\ServiceBaseInterface;
 use KTXF\Resource\Provider\ResourceProviderBaseInterface;
+use KTXF\Resource\SystemIdentity;
 
 /**
  * Provider Base Interface
@@ -24,15 +25,9 @@ interface ProviderBaseInterface extends ResourceProviderBaseInterface{
     public const JSON_TYPE = 'mail:provider';
 
     /**
-     * Reserved user identifier for system-owned mail services
-     *
-     * Services stored under this user id belong to the tenant itself rather
-     * than any real user (e.g. accounts used to deliver system-generated
-     * messages such as verification codes and password resets).
-     *
-     * @since 2026.07.01
+     * @deprecated Use SystemIdentity::USER.
      */
-    public const USER_SYSTEM = 'system';
+    public const USER_SYSTEM = SystemIdentity::USER;
     
     /**
      * Finds a service that handles a specific email address
diff --git a/shared/lib/Resource/SystemIdentity.php b/shared/lib/Resource/SystemIdentity.php
new file mode 100644
index 0000000..1926014
--- /dev/null
+++ b/shared/lib/Resource/SystemIdentity.php
@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KTXF\Resource;
+
+/**
+ * Reserved identities used by tenant-scoped internal services.
+ */
+final class SystemIdentity
+{
+    /**
+     * User identifier for resources owned by the tenant rather than a person.
+     */
+    public const USER = 'system';
+
+    private function __construct()
+    {
+    }
+}
diff --git a/tests/php/Unit/Resource/SystemIdentityTest.php b/tests/php/Unit/Resource/SystemIdentityTest.php
new file mode 100644
index 0000000..d61d2c2
--- /dev/null
+++ b/tests/php/Unit/Resource/SystemIdentityTest.php
@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KTXT\Unit\Resource;
+
+use KTXF\Mail\Provider\ProviderBaseInterface;
+use KTXF\Resource\SystemIdentity;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+
+final class SystemIdentityTest extends TestCase
+{
+    #[Test]
+    public function exposesTheReservedSystemUser(): void
+    {
+        self::assertSame('system', SystemIdentity::USER);
+    }
+
+    #[Test]
+    public function retainsTheLegacyMailAlias(): void
+    {
+        self::assertSame(SystemIdentity::USER, ProviderBaseInterface::USER_SYSTEM);
+    }
+}