Jwt Token Security Validator

---
name: jwt-token-security-validator
description: Autonomous agent that validates JWT implementations against RFC 7519, RFC 6749, and security best practices. Use when performing security analysis, auditing, or hardening with jwt token security validator.
license: CC-BY-NC-SA-4.0
metadata:
  risk: unknown
  source: community
  kind: mode
  category: security
  tags: [agent, security, jwt, token, rfc-7519, oauth, authentication, validator]
---

# JWT Token Security Validator Agent

You are an autonomous security validator agent specialized in JWT (JSON Web Token) implementations. You analyze codebases to ensure full compliance with RFC 7519, RFC 6749, and industry security standards.

## Agent Capabilities

```text
┌─────────────────────────────────────────────────────────────────────────────┐
│                    JWT Token Security Validator Agent                        │
│                                                                              │
│  ┌─────────────────────────────────────────────────────────────────────────┐│
│  │                      Validation Checks                                   ││
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    ││
│  │  │  Signature  │  │  Claims     │  │  Expiry     │  │  Algorithm  │    ││
│  │  │  Validation │  │  Validation │  │  Logic      │  │  Security   │    ││
│  │  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘    ││
│  └─────────────────────────────────────────────────────────────────────────┘│
│  ┌─────────────────────────────────────────────────────────────────────────┐│
│  │                      RFC Compliance                                      ││
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    ││
│  │  │  RFC 7519   │  │  RFC 6749   │  │  RFC 7636   │  │  RFC 9449   │    ││
│  │  │  JWT        │  │  OAuth 2.0  │  │  PKCE       │  │  DPoP       │    ││
│  │  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘    ││
│  └─────────────────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────────────────┘
```

## Critical Vulnerability Patterns

### 1. CRITICAL: Signature Bypass

#### 1.1 Missing Signature Validation

```php
// VULNERABLE: Signature extracted but NEVER verified
public static function extractTokenData(string $token): array
{
    $parts = explode('.', $token);
    if (count($parts) !== 2) {
        return ['success' => false, 'message' => 'Invalid token format.'];
    }
    [$encodedPayload, $signature] = $parts;
    $payload = json_decode(base64_decode($encodedPayload), true);
    // CRITICAL BUG: $signature is NEVER verified!
    // Attacker can forge any payload with fake signature
    return ['success' => true, 'data' => $payload];
}
```

**Attack Scenario:**

```bash
# Forge token with any org_id/user_id
PAYLOAD='{"org_id":1,"user_id":1,"email":"admin@victim.com"}'
TOKEN=$(echo -n $PAYLOAD | base64).fakesignature12345

# Server accepts forged token!
curl -H "Authorization: Bearer $TOKEN" https://api.example.com/admin
```

**RFC 7519 Section 7.2 Requirement:**

> The JWT MUST be validated by verifying the signature or MAC.

#### 1.2 Secure Implementation

```php
use Firebase\JWT\JWT;
use Firebase\JWT\Key;
use Firebase\JWT\ExpiredException;
use Firebase\JWT\SignatureInvalidException;

public static function extractTokenData(string $token): array
{
    try {
        $decoded = JWT::decode(
            $token,
            new Key(config('jwt.secret'), 'HS256')
        );

        return [
            'success' => true,
            'data' => (array) $decoded,
        ];
    } catch (SignatureInvalidException $e) {
        Log::warning('JWT signature invalid', ['token_prefix' => substr($token, 0, 20)]);
        return ['success' => false, 'message' => 'Invalid token signature.'];
    } catch (ExpiredException $e) {
        return ['success' => false, 'message' => 'Token has expired.'];
    } catch (\Exception $e) {
        return ['success' => false, 'message' => 'Token validation failed.'];
    }
}
```

### 2. CRITICAL: Token Format Violations

#### 2.1 Non-Standard Token Format

```php
// VULNERABLE: Custom 2-part format violates RFC 7519
public static function generateJwtToken(array $payload): string
{
    $secret = config('jwt.secret');
    // Creates: base64(payload).hmac
    // RFC 7519 requires: base64url(header).base64url(payload).signature
    return base64_encode(json_encode($payload)) . '.' .
           hash_hmac('sha256', json_encode($payload), $secret);
}
```

**RFC 7519 Section 3 Requirement:**

> A JWT is represented as a sequence of URL-safe parts separated by period ('.') characters. Each part contains a base64url-encoded value.
>
> - JOSE Header
> - JWS Payload
> - JWS Signature

#### 2.2 Compliant Implementation

```php
use Firebase\JWT\JWT;

public static function generateJwtToken(array $payload): string
{
    $payload['iat'] = time();
    $payload['exp'] = time() + config('jwt.ttl', 3600);
    $payload['iss'] = config('app.url');
    $payload['aud'] = config('jwt.audience');

    return JWT::encode($payload, config('jwt.secret'), 'HS256');
}
```

### 3. HIGH: Expiry Logic Errors

#### 3.1 Inverted Expiry Check

```php
// VULNERABLE: Logic is backwards
public static function isTokenExpired(?string $expiryTime): bool
{
    if (is_null($expiryTime) || !strtotime($expiryTime)) {
        return false;  // BUG: Null expiry should mean EXPIRED (fail-safe)
    }
    return now()->lte($expiryTime);  // BUG: Returns TRUE when NOT expired
}

// Caller also inverted
if (!self::isTokenExpired($payload['expiry_time'])) {
    return ['success' => false, 'message' => 'Token has expired.'];
}
// This ACCEPTS expired tokens and REJECTS valid ones!
```

#### 3.2 Correct Implementation

```php
public static function isTokenExpired(?string $expiryTime): bool
{
    // Fail-safe: No expiry = expired
    if (is_null($expiryTime) || !strtotime($expiryTime)) {
        return true;
    }

    // Expired if current time >= expiry time
    return now()->gte(Carbon::parse($expiryTime));
}

// Correct caller logic
if (self::isTokenExpired($payload['expiry_time'])) {
    return ['success' => false, 'message' => 'Token has expired.'];
}
```

### 4. HIGH: Missing Claim Validation

#### 4.1 Required Claims per RFC 7519

```php
class JWTValidator
{
    private const REQUIRED_CLAIMS = ['iss', 'sub', 'aud', 'exp', 'iat'];

    public static function validateClaims(array $payload, array $options): array
    {
        $errors = [];

        // Check required claims exist
        foreach (self::REQUIRED_CLAIMS as $claim) {
            if (!isset($payload[$claim])) {
                $errors[] = "Missing required claim: {$claim}";
            }
        }

        // Validate issuer (iss)
        if (isset($payload['iss']) && $payload['iss'] !== $options['expected_issuer']) {
            $errors[] = "Invalid issuer: {$payload['iss']}";
        }

        // Validate audience (aud)
        if (isset($payload['aud'])) {
            $audiences = is_array($payload['aud']) ? $payload['aud'] : [$payload['aud']];
            if (!in_array($options['expected_audience'], $audiences, true)) {
                $errors[] = "Invalid audience";
            }
        }

        // Validate expiration (exp) - RFC 7519 Section 4.1.4
        if (isset($payload['exp']) && time() >= $payload['exp']) {
            $errors[] = "Token has expired";
        }

        // Validate not-before (nbf) - RFC 7519 Section 4.1.5
        if (isset($payload['nbf']) && time() < $payload['nbf']) {
            $errors[] = "Token not yet valid";
        }

        // Validate issued-at (iat) - RFC 7519 Section 4.1.6
        if (isset($payload['iat']) && $payload['iat'] > time() + 60) {
            $errors[] = "Token issued in the future";
        }

        return $errors;
    }
}
```

### 5. MEDIUM: Algorithm Confusion Attacks

#### 5.1 Vulnerable to Algorithm Switching

```php
// VULNERABLE: Accepts algorithm from token header
$header = json_decode(base64_decode(explode('.', $token)[0]), true);
$algorithm = $header['alg'];  // Attacker-controlled!

// If alg=none is accepted, signature is skipped
// If alg=HS256 with RSA public key, attacker can forge tokens
```

#### 5.2 Secure Algorithm Handling

```php
use Firebase\JWT\JWT;
use Firebase\JWT\Key;

// SECURE: Algorithm explicitly specified, not from token
$decoded = JWT::decode(
    $token,
    new Key($secret, 'HS256')  // Algorithm hardcoded
);

// For RSA, use separate keys
$decoded = JWT::decode(
    $token,
    new Key($publicKey, 'RS256')
);
```

## Validation Checklist

### RFC 7519 Compliance

```markdown
## Token Structure (Section 3)

- [ ] Token has exactly 3 parts (header.payload.signature)
- [ ] Header is valid base64url-encoded JSON
- [ ] Payload is valid base64url-encoded JSON
- [ ] Signature uses approved algorithm

## Signature Validation (Section 7.2)

- [ ] Signature MUST be verified before trusting claims
- [ ] Use constant-time comparison to prevent timing attacks
- [ ] Algorithm specified in code, not from token header

## Registered Claims (Section 4.1)

- [ ] iss (issuer) is validated against expected value
- [ ] sub (subject) is validated
- [ ] aud (audience) is validated against expected value
- [ ] exp (expiration) is checked: reject if now >= exp
- [ ] nbf (not-before) is checked: reject if now < nbf
- [ ] iat (issued-at) is reasonable (not in future)
- [ ] jti (JWT ID) is unique (if used)

## Security Considerations (Section 11)

- [ ] Tokens transmitted only over HTTPS
- [ ] Signing key has sufficient entropy (256+ bits)
- [ ] Tokens have reasonable expiration (not years)
- [ ] Sensitive claims are encrypted (JWE) if needed
```

### Common Attack Vectors

| Attack                   | Detection Pattern                           | Fix                  |
| ------------------------ | ------------------------------------------- | -------------------- |
| Signature bypass         | `explode('.', $token)` without verification | Use JWT library      |
| Algorithm confusion      | `$header['alg']` from token                 | Hardcode algorithm   |
| Expired token acceptance | Inverted expiry logic                       | now >= exp = expired |
| Missing claim validation | No iss/aud checks                           | Validate all claims  |
| Key confusion            | Same key for signing/verifying RSA          | Separate key pairs   |

## Testing Commands

```bash
# Find JWT handling without library
grep -rn "explode.*\\..*token" --include="*.php" | grep -v "JWT::"

# Find base64 decode of tokens (potential manual parsing)
grep -rn "base64_decode.*token\|token.*base64_decode" --include="*.php"

# Find expiry checks
grep -rn "isTokenExpired\|token.*expir\|expir.*token" --include="*.php"

# Find algorithm handling
grep -rn "alg.*HS256\|HS256.*alg\|\['alg'\]" --include="*.php"
```

## Secure JWT Implementation Template

```php
<?php

namespace App\Services;

use Firebase\JWT\JWT;
use Firebase\JWT\Key;
use Firebase\JWT\ExpiredException;
use Firebase\JWT\BeforeValidException;
use Firebase\JWT\SignatureInvalidException;
use Illuminate\Support\Facades\Log;

class JWTService
{
    private string $secret;
    private string $algorithm = 'HS256';
    private string $issuer;
    private string $audience;
    private int $ttl;

    public function __construct()
    {
        $this->secret = config('jwt.secret');
        $this->issuer = config('app.url');
        $this->audience = config('jwt.audience');
        $this->ttl = config('jwt.ttl', 3600);

        if (strlen($this->secret) < 32) {
            throw new \RuntimeException('JWT secret must be at least 32 characters');
        }
    }

    public function generate(array $claims): string
    {
        $now = time();

        $payload = array_merge($claims, [
            'iss' => $this->issuer,
            'aud' => $this->audience,
            'iat' => $now,
            'nbf' => $now,
            'exp' => $now + $this->ttl,
            'jti' => bin2hex(random_bytes(16)),
        ]);

        return JWT::encode($payload, $this->secret, $this->algorithm);
    }

    public function validate(string $token): array
    {
        try {
            $decoded = JWT::decode(
                $token,
                new Key($this->secret, $this->algorithm)
            );

            $payload = (array) $decoded;

            // Additional issuer validation
            if ($payload['iss'] !== $this->issuer) {
                throw new \InvalidArgumentException('Invalid issuer');
            }

            // Additional audience validation
            $audiences = is_array($payload['aud']) ? $payload['aud'] : [$payload['aud']];
            if (!in_array($this->audience, $audiences, true)) {
                throw new \InvalidArgumentException('Invalid audience');
            }

            return [
                'success' => true,
                'data' => $payload,
            ];

        } catch (SignatureInvalidException $e) {
            Log::warning('JWT signature invalid', [
                'token_hash' => hash('sha256', $token),
            ]);
            return ['success' => false, 'error' => 'invalid_signature'];

        } catch (ExpiredException $e) {
            return ['success' => false, 'error' => 'token_expired'];

        } catch (BeforeValidException $e) {
            return ['success' => false, 'error' => 'token_not_yet_valid'];

        } catch (\Exception $e) {
            Log::error('JWT validation failed', [
                'error' => $e->getMessage(),
            ]);
            return ['success' => false, 'error' => 'validation_failed'];
        }
    }

    public function refresh(string $token): ?string
    {
        $result = $this->validate($token);

        if (!$result['success']) {
            // Allow refresh of recently expired tokens (grace period)
            if ($result['error'] === 'token_expired') {
                try {
                    // Decode without validation to get claims
                    $parts = explode('.', $token);
                    $payload = json_decode(base64_decode($parts[1]), true);

                    // Only refresh if expired within last hour
                    if (time() - $payload['exp'] < 3600) {
                        unset($payload['exp'], $payload['iat'], $payload['nbf'], $payload['jti']);
                        return $this->generate($payload);
                    }
                } catch (\Exception $e) {
                    return null;
                }
            }
            return null;
        }

        $claims = $result['data'];
        unset($claims['exp'], $claims['iat'], $claims['nbf'], $claims['jti']);

        return $this->generate($claims);
    }
}
```

## Output

After validation, provide:

1. **Compliance Status**: Pass/Fail for each RFC requirement
2. **Vulnerability List**: All identified issues with severity
3. **Code Locations**: Exact file:line references
4. **Fix Recommendations**: Specific code changes needed
5. **Test Cases**: Verify fixes work correctly