fix: better JWT claims and headers type handling - docs

Author: chr15k

docs/API_CHEATSHEET.md

@@ -185,3 +185,63 @@ The following algorithms are supported for Digest Authentication:
 | DigestAlgorithm::MD5_SESS | MD5-sess variant with client nonce (RFC 2617) |
 | DigestAlgorithm::SHA256 | SHA-256 algorithm (RFC 7616) |
 | DigestAlgorithm::SHA256_SESS | SHA-256-sess variant with client nonce (RFC 7616) |
+
+## JWT Validation Rules
+
+### Headers
+JWT headers must contain simple scalar values (strings, numbers, booleans):
+
+```php
+// ✅ Valid header values
+$jwt->header('kid', 'key-123');           // string
+$jwt->header('version', 1);               // integer
+$jwt->header('debug', true);              // boolean
+$jwt->header('rate', 1.5);                // float
+
+// ❌ Invalid header values (will throw InvalidArgumentException)
+$jwt->header('metadata', ['key' => 'value']);  // array not allowed
+$jwt->header('config', new stdClass());        // object not allowed
+
+// ℹ️ Null values are ignored (header won't be added)
+$jwt->header('optional', null);           // No error, but header is skipped
+```
+
+### Claims (Payload)
+JWT claims can contain complex data structures as long as they're JSON serializable:
+
+```php
+// ✅ Valid claim values
+$jwt->claim('user_id', 123);                    // scalar values
+$jwt->claim('roles', ['admin', 'user']);        // arrays
+$jwt->claim('profile', [                        // nested objects
+    'name' => 'John Doe',
+    'settings' => ['theme' => 'dark']
+]);
+$jwt->claim('permissions', [
+    'read' => true,
+    'write' => false,
+    'admin' => ['users', 'settings']
+]);
+
+// ❌ Invalid claim values (will throw InvalidArgumentException)
+$jwt->claim('resource', fopen('file.txt', 'r')); // resources not allowed
+$jwt->claim('callback', function() {});          // closures not allowed
+```
+
+## RFC Compliance
+
+The validation rules ensure compliance with JWT standards:
+
+- **Headers (RFC 7515)**: Scalar values only - ensures interoperability
+- **Claims (RFC 7519)**: Any JSON data - supports standard and custom claims
+- **Standard claims**: `iss`, `sub`, `aud`, `exp`, `iat`, `nbf`, `jti` are properly handled
+
+```php
+// RFC-compliant JWT
+$jwt = AuthGenerator::jwt()
+    ->claim('iss', 'https://app.com')     // Standard issuer claim
+    ->claim('aud', ['api', 'web'])        // Audience can be array (RFC 7519)
+    ->claim('custom', ['data' => 'ok'])   // Custom claims support objects
+    ->header('kid', 'key-1')              // Header values are strings
+    ->toString();
+```

docs/USER_GUIDE.md

@@ -234,32 +234,87 @@ $token = AuthGenerator::jwt()
     ->toString();
 ```
 
-### Supported Algorithms
+### Working with Complex Data
 
-The library supports various algorithms for JWT signing:
+JWT claims can contain complex nested data structures:
 
 ```php
-use Chr15k\AuthGenerator\Enums\Algorithm;
+$token = AuthGenerator::jwt()
+    ->key('secret-key')
+    ->claim('user', [
+        'id' => 123,
+        'name' => 'John Doe',
+        'roles' => ['admin', 'user'],
+        'permissions' => [
+            'read' => true,
+            'write' => true,
+            'admin' => ['users', 'settings']
+        ]
+    ])
+    ->claim('metadata', [
+        'ip' => '192.168.1.1',
+        'device' => 'mobile',
+        'location' => ['city' => 'New York', 'country' => 'US']
+    ])
+    ->toString();
+```
 
-// HMAC algorithms
-$token = AuthGenerator::jwt()->algorithm(Algorithm::HS256)->toString(); // HMAC with SHA-256
-$token = AuthGenerator::jwt()->algorithm(Algorithm::HS384)->toString(); // HMAC with SHA-384
-$token = AuthGenerator::jwt()->algorithm(Algorithm::HS512)->toString(); // HMAC with SHA-512
+### Data Type Rules
 
-// RSA algorithms
-$token = AuthGenerator::jwt()->algorithm(Algorithm::RS256)->toString(); // RSA with SHA-256
-$token = AuthGenerator::jwt()->algorithm(Algorithm::RS384)->toString(); // RSA with SHA-384
-$token = AuthGenerator::jwt()->algorithm(Algorithm::RS512)->toString(); // RSA with SHA-512
+The library enforces different validation rules for headers vs claims:
 
-// ECDSA algorithms
-$token = AuthGenerator::jwt()->algorithm(Algorithm::ES256)->toString(); // ECDSA with P-256 and SHA-256
-$token = AuthGenerator::jwt()->algorithm(Algorithm::ES384)->toString(); // ECDSA with P-384 and SHA-384
-$token = AuthGenerator::jwt()->algorithm(Algorithm::ES256K)->toString(); // ECDSA with secp256k1 and SHA-256
+**Headers** - Must be scalar values (strings, numbers, booleans):
+```php
+$jwt->header('kid', 'key-123');      // ✅ String
+$jwt->header('version', 1);          // ✅ Integer
+$jwt->header('debug', true);         // ✅ Boolean
+$jwt->header('invalid', []);         // ❌ Arrays not allowed
+$jwt->header('optional', null);      // ℹ️ Null values are ignored
+```
 
-// Edwards-curve Digital Signature Algorithm
-$token = AuthGenerator::jwt()->algorithm(Algorithm::EdDSA)->toString(); // EdDSA
+**Claims** - Can be any JSON-serializable data:
+```php
+$jwt->claim('simple', 123);          // ✅ Scalar values
+$jwt->claim('array', [1, 2, 3]);     // ✅ Arrays
+$jwt->claim('nested', ['a' => ['b' => 'c']]); // ✅ Nested structures
+$jwt->claim('invalid', fopen('file', 'r'));   // ❌ Resources not allowed
 ```
 
+### Validation Alignment with RFC Standards
+
+The library's validation rules are designed to ensure compliance with JWT standards:
+
+**RFC 7515 (JSON Web Signature) - Headers:**
+- Headers contain algorithm parameters and metadata for token processing
+- Values should be simple strings or numbers for interoperability
+- Complex data structures in headers can cause compatibility issues with other JWT libraries
+- Our validation enforces scalar types (strings, numbers, booleans) to maintain standard compliance
+
+**RFC 7519 (JSON Web Token) - Claims:**
+- Claims are designed to convey assertions about an entity (typically the user)
+- The payload can contain any valid JSON data structure
+- Standard claims like `iss`, `sub`, `aud` can be strings or arrays
+- Custom claims can be any JSON-serializable data to support application-specific requirements
+- Our validation allows complex data structures while preventing non-serializable types
+
+**Example of RFC-compliant usage:**
+```php
+$jwt = AuthGenerator::jwt()
+    ->key('secret-key')
+    // RFC 7519 standard claims
+    ->claim('iss', 'https://myapp.com')           // Issuer (string)
+    ->claim('sub', 'user-123')                    // Subject (string)
+    ->claim('aud', ['api', 'mobile'])             // Audience (string or array)
+    ->claim('exp', time() + 3600)                 // Expiration (number)
+    ->claim('iat', time())                        // Issued at (number)
+    // Custom claims with complex data (RFC compliant)
+    ->claim('permissions', ['read', 'write'])     // Array
+    ->claim('profile', ['name' => 'John'])        // Object
+    // RFC 7515 compliant headers
+    ->header('kid', 'key-id-123')                 // Key ID (string)
+    ->header('typ', 'JWT')                        // Type (string)
+    ->toString();
+```
 ## HTTP Headers
 
 The library provides helper methods to format tokens for use in HTTP headers.