agent foundation

lib/Support/Guard.php

@@ -9,8 +9,11 @@ use MintyPHP\Service\Access\AuthorizationService;
 use MintyPHP\Service\Auth\AuthService;
 use MintyPHP\Service\Tenant\TenantService;
 
+// Session-based web auth guard. Enforces login and RBAC for page actions.
+// For API token authentication, see ApiAuth instead.
 class Guard
 {
+    // Re-check tenant assignment at most once per minute to pick up permission changes without re-login.
     private const TENANT_REFRESH_INTERVAL = 60;
     /** @var (callable(): AuthService)|null */
     private static $authServiceResolver = null;
@@ -56,7 +59,7 @@ class Guard
             return;
         }
 
-        // Current tenant was deleted, refresh session data
+        // Current tenant was deleted — reload session so the user is switched to another active tenant or logged out.
         $userId = (int) ($_SESSION['user']['id'] ?? 0);
         if ($userId > 0) {
             self::authService()->loadTenantDataIntoSession($userId);
@@ -106,6 +109,7 @@ class Guard
             ...$context,
         ]);
         if (!$decision->isAllowed()) {
+            // JSON requests get a 403/404 response body; browser requests get a redirect to the forbidden page.
             if (Request::wantsJson()) {
                 http_response_code($decision->status());
                 header('Content-Type: application/json; charset=utf-8');