agent foundation

lib/Support/Crypto.php

@@ -2,6 +2,8 @@
 
 namespace MintyPHP\Support;
 
+// AES-256-GCM encryption/decryption for sensitive stored values (e.g. SSO secrets).
+// Requires APP_CRYPTO_KEY — see EnvValidator for accepted key formats.
 class Crypto
 {
     private const CIPHER = 'aes-256-gcm';
@@ -33,6 +35,8 @@ class Crypto
             throw new \RuntimeException('Encryption failed');
         }
 
+        // Outer base64 wraps a JSON object with v (version), iv, auth tag, and ciphertext —
+        // all inner binary values are base64url-encoded to stay JSON-safe.
         $payload = json_encode([
             'v' => 1,
             'iv' => self::base64UrlEncode($iv),
@@ -94,6 +98,7 @@ class Crypto
             return null;
         }
 
+        // Accepts 64-char hex (32 bytes) or base64-encoded 32 bytes — both yield a 256-bit key.
         $hex = preg_match('/^[0-9a-f]{64}$/i', $raw) ? hex2bin($raw) : false;
         if (is_string($hex) && strlen($hex) === 32) {
             return $hex;
@@ -107,6 +112,7 @@ class Crypto
         return null;
     }
 
+    // URL-safe base64: replaces +/ with -_ and strips = padding.
     private static function base64UrlEncode(string $value): string
     {
         return rtrim(strtr(base64_encode($value), '+/', '-_'), '=');