1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

// HEADER (Base64URL decoded)
{
  "alg": "RS256",     // Algorithm used for signing
  "typ": "JWT",       // Token type
  "kid": "key-2024-01" // Key ID for signature verification
}
 
// PAYLOAD (Base64URL decoded)
{
  // Registered claims (standardized by RFC 7519)
  "iss": "https://auth.example.com",  // Issuer
  "sub": "user-12345",                 // Subject (who this token is about)
  "aud": "api.example.com",            // Audience (who should accept this token)
  "iat": 1704067200,                   // Issued At (Unix timestamp)
  "exp": 1704070800,                   // Expiration Time (Unix timestamp)
  "nbf": 1704067200,                   // Not Before (Unix timestamp)
  "jti": "a1b2c3d4-e5f6-7890-abcd",   // JWT ID (unique identifier)
  
  // Public claims (registered with IANA, optional)
  "email": "user@example.com",
  "email_verified": true,
  "name": "Jane Doe",
  
  // Private claims (application-specific)
  "scope": "read:accounts write:transfers",
  "tenant_id": "tenant-abc",
  "roles": ["user", "premium"],
  "permissions": ["accounts.read", "transfers.create"]
}
 
// SIGNATURE
// Created by signing the header and payload with the private key:
// signature = RS256(
//   base64UrlEncode(header) + "." + base64UrlEncode(payload),
//   privateKey
// )

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

function validateExpiration(claims: JwtPayload, clockSkewSeconds: number = 30): void {
    const now = Math.floor(Date.now() / 1000);
    
    if (!claims.exp) {
        // Tokens without expiration are dangerous - reject by default
        throw new JwtValidationError(
            "missing_expiration",
            "Token has no expiration claim"
        );
    }
    
    // Allow small clock skew between issuer and validator
    const expirationWithSkew = claims.exp + clockSkewSeconds;
    
    if (now > expirationWithSkew) {
        throw new JwtValidationError(
            "token_expired",
            `Token expired at ${new Date(claims.exp * 1000).toISOString()}`,
            { expiredAt: claims.exp, serverTime: now }
        );
    }
}
 
// Production configuration
const CLOCK_SKEW_CONFIG = {
    // Standard clock skew tolerance
    default: 30,  // 30 seconds
    
    // For high-security environments, reduce tolerance
    highSecurity: 5,  // 5 seconds
    
    // Maximum safe skew (beyond this indicates clock issues)
    maximum: 60,  // 1 minute
};

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

function validateIssuer(claims: JwtPayload, allowedIssuers: string[]): void {
    if (!claims.iss) {
        throw new JwtValidationError(
            "missing_issuer",
            "Token has no issuer claim"
        );
    }
    
    // Exact match required - no partial matching or regex!
    if (!allowedIssuers.includes(claims.iss)) {
        throw new JwtValidationError(
            "invalid_issuer",
            `Issuer '${claims.iss}' is not trusted`,
            { received: claims.iss, allowed: allowedIssuers }
        );
    }
}
 
// Configuration example: Multiple issuers for migration or federation
const ALLOWED_ISSUERS = [
    "https://auth.example.com",           // Primary IdP
    "https://auth-eu.example.com",        // Regional IdP
    "https://partner-auth.example.com",   // Federated partner (if applicable)
];
 
// WARNING: Never accept issuer URLs with trailing slashes inconsistently
// "https://auth.example.com" !== "https://auth.example.com/"
// Normalize in configuration or reject inconsistent tokens

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

function validateAudience(claims: JwtPayload, expectedAudience: string | string[]): void {
    if (!claims.aud) {
        throw new JwtValidationError(
            "missing_audience",
            "Token has no audience claim"
        );
    }
    
    // Audience can be a string or array of strings
    const tokenAudiences = Array.isArray(claims.aud) ? claims.aud : [claims.aud];
    const requiredAudiences = Array.isArray(expectedAudience) 
        ? expectedAudience 
        : [expectedAudience];
    
    // Token must contain at least one expected audience
    const hasValidAudience = tokenAudiences.some(aud => 
        requiredAudiences.includes(aud)
    );
    
    if (!hasValidAudience) {
        throw new JwtValidationError(
            "invalid_audience",
            "Token is not intended for this service",
            { received: tokenAudiences, expected: requiredAudiences }
        );
    }
}
 
// API Gateway configuration
const GATEWAY_AUDIENCE = [
    "api.example.com",           // General API audience
    "https://api.example.com",   // URL format (some IdPs use this)
];

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

function validateNotBefore(claims: JwtPayload, clockSkewSeconds: number = 30): void {
    if (!claims.nbf) {
        // nbf is optional - if not present, token is valid immediately upon issuance
        return;
    }
    
    const now = Math.floor(Date.now() / 1000);
    
    // Allow small clock skew
    const notBeforeWithSkew = claims.nbf - clockSkewSeconds;
    
    if (now < notBeforeWithSkew) {
        throw new JwtValidationError(
            "token_not_yet_valid",
            `Token is not valid until ${new Date(claims.nbf * 1000).toISOString()}`,
            { validFrom: claims.nbf, serverTime: now }
        );
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

{
  "keys": [
    {
      "kty": "RSA",                    // Key Type
      "use": "sig",                    // Usage: signature (vs encryption)
      "alg": "RS256",                  // Algorithm
      "kid": "key-2024-01",            // Key ID (matches JWT header 'kid')
      "n": "0vx7agoebGcQSuuP...",      // RSA modulus (Base64URL)
      "e": "AQAB"                      // RSA exponent (Base64URL)
    },
    {
      "kty": "RSA",
      "use": "sig",
      "alg": "RS256",
      "kid": "key-2024-02",            // Second key for rotation
      "n": "1b8mMNUYMdKQ...",
      "e": "AQAB"
    },
    {
      "kty": "EC",                     // Elliptic Curve key
      "use": "sig",
      "alg": "ES256",
      "kid": "ec-key-2024-01",
      "crv": "P-256",                  // Curve name
      "x": "f83OJ3D2xF1Bg8vub9tLe...", // X coordinate
      "y": "x_FEzRu9m36HLN_tue659..."  // Y coordinate
    }
  ]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176

interface JwksCacheConfig {
    // How long to cache JWKS (seconds)
    cacheTtl: number;
    
    // When to proactively refresh (percentage of TTL)
    refreshThreshold: number;  // e.g., 0.75 = refresh at 75% of TTL
    
    // Maximum stale cache age during failures (seconds)
    staleMaxAge: number;
    
    // HTTP client settings
    fetchTimeout: number;
    retryAttempts: number;
    retryDelay: number;
}
 
const PRODUCTION_CONFIG: JwksCacheConfig = {
    cacheTtl: 3600,           // 1 hour cache
    refreshThreshold: 0.75,   // Refresh after 45 minutes
    staleMaxAge: 86400,       // Allow 24-hour stale cache in emergencies
    fetchTimeout: 5000,       // 5 second fetch timeout
    retryAttempts: 3,
    retryDelay: 1000,
};
 
class JwksClient {
    private cache = new Map<string, JwksCacheEntry>();
    private refreshPromises = new Map<string, Promise<void>>();
    
    constructor(private config: JwksCacheConfig) {}
    
    async getKey(issuer: string, kid: string): Promise<crypto.KeyObject> {
        const cacheKey = issuer;
        let entry = this.cache.get(cacheKey);
        
        // Cache miss: must fetch
        if (!entry) {
            await this.fetchJwks(issuer);
            entry = this.cache.get(cacheKey)!;
        }
        // Cache hit but stale: fetch synchronously
        else if (this.isExpired(entry)) {
            await this.fetchJwks(issuer);
            entry = this.cache.get(cacheKey)!;
        }
        // Cache hit, nearing expiry: background refresh
        else if (this.shouldRefresh(entry)) {
            this.backgroundRefresh(issuer);
        }
        
        // Look up key by ID
        const key = entry.keys.get(kid);
        if (!key) {
            // Key not found - maybe it was just added?
            // Try one refresh if we haven't recently
            if (!entry.recentlyRefreshed) {
                await this.fetchJwks(issuer);
                entry = this.cache.get(cacheKey)!;
                entry.recentlyRefreshed = true;
                
                const retryKey = entry.keys.get(kid);
                if (retryKey) return retryKey;
            }
            
            throw new JwksError(
                "unknown_key",
                `Key ID '${kid}' not found in JWKS for issuer '${issuer}'`
            );
        }
        
        return key;
    }
    
    private async fetchJwks(issuer: string): Promise<void> {
        // Coalesce concurrent requests
        let existingPromise = this.refreshPromises.get(issuer);
        if (existingPromise) {
            return existingPromise;
        }
        
        const fetchPromise = this.doFetch(issuer);
        this.refreshPromises.set(issuer, fetchPromise);
        
        try {
            await fetchPromise;
        } finally {
            this.refreshPromises.delete(issuer);
        }
    }
    
    private async doFetch(issuer: string): Promise<void> {
        const jwksUri = await this.discoverJwksUri(issuer);
        
        let lastError: Error | null = null;
        for (let attempt = 0; attempt < this.config.retryAttempts; attempt++) {
            try {
                const response = await fetch(jwksUri, {
                    signal: AbortSignal.timeout(this.config.fetchTimeout),
                    headers: { 
                        "Accept": "application/json",
                        "User-Agent": "APIGateway/1.0",
                    },
                });
                
                if (!response.ok) {
                    throw new Error(`JWKS fetch failed: HTTP ${response.status}`);
                }
                
                const jwks = await response.json();
                this.cacheJwks(issuer, jwks);
                return;
                
            } catch (error) {
                lastError = error as Error;
                if (attempt < this.config.retryAttempts - 1) {
                    await this.delay(this.config.retryDelay * (attempt + 1));
                }
            }
        }
        
        // All retries failed - check if we have stale cache
        const staleEntry = this.cache.get(issuer);
        if (staleEntry && this.isUsableStale(staleEntry)) {
            console.warn(`JWKS refresh failed for ${issuer}, using stale cache`);
            staleEntry.stale = true;
            this.emitMetric("jwks.stale_cache_used", { issuer });
            return;
        }
        
        throw new JwksError(
            "fetch_failed",
            `Failed to fetch JWKS from ${issuer}: ${lastError?.message}`
        );
    }
    
    private async discoverJwksUri(issuer: string): Promise<string> {
        // Try OIDC discovery first
        const discoveryUrl = `${issuer}/.well-known/openid-configuration`;
        
        try {
            const response = await fetch(discoveryUrl, {
                signal: AbortSignal.timeout(this.config.fetchTimeout),
            });
            
            if (response.ok) {
                const config = await response.json();
                return config.jwks_uri;
            }
        } catch {
            // Discovery failed, fall back to standard location
        }
        
        // Standard JWKS location
        return `${issuer}/.well-known/jwks.json`;
    }
    
    private cacheJwks(issuer: string, jwks: any): void {
        const keys = new Map<string, crypto.KeyObject>();
        
        for (const jwk of jwks.keys || []) {
            if (!jwk.kid) continue;
            if (jwk.use && jwk.use !== "sig") continue;  // Only signing keys
            
            const keyObject = crypto.createPublicKey({ key: jwk, format: "jwk" });
            keys.set(jwk.kid, keyObject);
        }
        
        this.cache.set(issuer, {
            keys,
            fetchedAt: Date.now(),
            expiresAt: Date.now() + (this.config.cacheTtl * 1000),
            stale: false,
            recentlyRefreshed: false,
        });
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172

const ALLOWED_ALGORITHMS = new Set(["RS256", "RS384", "RS512", "ES256", "ES384"]);
 
interface ValidationResult {
    valid: boolean;
    claims: JwtPayload | null;
    error: JwtValidationError | null;
}
 
async function verifyJwtSignature(
    token: string,
    jwksClient: JwksClient,
    expectedIssuer: string
): Promise<ValidationResult> {
    // Step 1: Parse token structure
    const parts = token.split(".");
    if (parts.length !== 3) {
        return {
            valid: false,
            claims: null,
            error: new JwtValidationError(
                "malformed_token",
                "JWT must have three parts separated by dots"
            ),
        };
    }
    
    const [encodedHeader, encodedPayload, encodedSignature] = parts;
    
    // Step 2: Decode header (do NOT verify yet)
    let header: JwtHeader;
    try {
        header = JSON.parse(base64UrlDecode(encodedHeader));
    } catch {
        return {
            valid: false,
            claims: null,
            error: new JwtValidationError(
                "invalid_header",
                "JWT header is not valid JSON"
            ),
        };
    }
    
    // Step 3: Validate algorithm BEFORE any cryptographic operations
    if (!header.alg) {
        return {
            valid: false,
            claims: null,
            error: new JwtValidationError(
                "missing_algorithm",
                "JWT header missing 'alg' claim"
            ),
        };
    }
    
    if (header.alg.toLowerCase() === "none") {
        // Critical security check
        return {
            valid: false,
            claims: null,
            error: new JwtValidationError(
                "forbidden_algorithm",
                "Algorithm 'none' is not allowed"
            ),
        };
    }
    
    if (!ALLOWED_ALGORITHMS.has(header.alg)) {
        return {
            valid: false,
            claims: null,
            error: new JwtValidationError(
                "unsupported_algorithm",
                `Algorithm '${header.alg}' is not in allowed list`,
                { allowed: Array.from(ALLOWED_ALGORITHMS) }
            ),
        };
    }
    
    // Step 4: Verify key ID is present
    if (!header.kid) {
        return {
            valid: false,
            claims: null,
            error: new JwtValidationError(
                "missing_key_id",
                "JWT header missing 'kid' claim"
            ),
        };
    }
    
    // Step 5: Retrieve public key
    let publicKey: crypto.KeyObject;
    try {
        publicKey = await jwksClient.getKey(expectedIssuer, header.kid);
    } catch (error) {
        return {
            valid: false,
            claims: null,
            error: new JwtValidationError(
                "key_not_found",
                `Cannot find key '${header.kid}' for issuer '${expectedIssuer}'`
            ),
        };
    }
    
    // Step 6: Verify signature
    const signedContent = `${encodedHeader}.${encodedPayload}`;
    const signature = base64UrlDecodeToBuffer(encodedSignature);
    
    let isValid: boolean;
    try {
        isValid = crypto.verify(
            getHashAlgorithm(header.alg),
            Buffer.from(signedContent),
            publicKey,
            signature
        );
    } catch (error) {
        return {
            valid: false,
            claims: null,
            error: new JwtValidationError(
                "verification_error",
                "Cryptographic verification failed"
            ),
        };
    }
    
    if (!isValid) {
        return {
            valid: false,
            claims: null,
            error: new JwtValidationError(
                "invalid_signature",
                "JWT signature verification failed"
            ),
        };
    }
    
    // Step 7: Decode and return payload
    let payload: JwtPayload;
    try {
        payload = JSON.parse(base64UrlDecode(encodedPayload));
    } catch {
        return {
            valid: false,
            claims: null,
            error: new JwtValidationError(
                "invalid_payload",
                "JWT payload is not valid JSON"
            ),
        };
    }
    
    return { valid: true, claims: payload, error: null };
}
 
function getHashAlgorithm(jwtAlg: string): string {
    const mapping: Record<string, string> = {
        RS256: "sha256",
        RS384: "sha384",
        RS512: "sha512",
        ES256: "sha256",
        ES384: "sha384",
        ES512: "sha512",
        PS256: "sha256",
        PS384: "sha384",
        PS512: "sha512",
    };
    return mapping[jwtAlg] || "sha256";
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54

interface OidcConfiguration {
    issuer: string;
    authorization_endpoint: string;
    token_endpoint: string;
    userinfo_endpoint: string;
    jwks_uri: string;
    response_types_supported: string[];
    subject_types_supported: string[];
    id_token_signing_alg_values_supported: string[];
    scopes_supported: string[];
    claims_supported: string[];
}
 
class OidcClient {
    private configCache = new Map<string, OidcConfiguration>();
    
    async discover(issuer: string): Promise<OidcConfiguration> {
        const cached = this.configCache.get(issuer);
        if (cached) return cached;
        
        // Standard OIDC discovery URL
        const discoveryUrl = new URL("/.well-known/openid-configuration", issuer);
        
        const response = await fetch(discoveryUrl.toString(), {
            headers: { "Accept": "application/json" },
            signal: AbortSignal.timeout(5000),
        });
        
        if (!response.ok) {
            throw new OidcError(
                "discovery_failed",
                `OIDC discovery failed for ${issuer}: HTTP ${response.status}`
            );
        }
        
        const config = await response.json() as OidcConfiguration;
        
        // Validate issuer matches (security requirement per spec)
        if (config.issuer !== issuer) {
            throw new OidcError(
                "issuer_mismatch",
                `Discovered issuer '${config.issuer}' doesn't match expected '${issuer}'`
            );
        }
        
        this.configCache.set(issuer, config);
        return config;
    }
    
    async getJwksUri(issuer: string): Promise<string> {
        const config = await this.discover(issuer);
        return config.jwks_uri;
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71

async function validateIdToken(
    token: string,
    expectedClientId: string,
    expectedNonce?: string
): Promise<IdTokenClaims> {
    // Standard JWT validation first
    const { valid, claims, error } = await verifyJwtSignature(
        token, jwksClient, expectedIssuer
    );
    
    if (!valid) throw error;
    
    // ID token specific validations
    
    // 1. 'sub' (Subject) is required
    if (!claims.sub) {
        throw new JwtValidationError(
            "missing_subject",
            "ID token must contain 'sub' claim"
        );
    }
    
    // 2. 'iat' (Issued At) is required
    if (!claims.iat) {
        throw new JwtValidationError(
            "missing_iat",
            "ID token must contain 'iat' claim"
        );
    }
    
    // 3. Audience must contain the client ID
    const audiences = Array.isArray(claims.aud) ? claims.aud : [claims.aud];
    if (!audiences.includes(expectedClientId)) {
        throw new JwtValidationError(
            "invalid_audience",
            "ID token audience doesn't include expected client ID"
        );
    }
    
    // 4. If audience has multiple values, 'azp' (Authorized Party) must be present
    if (audiences.length > 1) {
        if (!claims.azp || claims.azp !== expectedClientId) {
            throw new JwtValidationError(
                "invalid_azp",
                "Multi-audience ID token must have 'azp' matching client ID"
            );
        }
    }
    
    // 5. Nonce validation (for authorization code flow)
    if (expectedNonce) {
        if (claims.nonce !== expectedNonce) {
            throw new JwtValidationError(
                "nonce_mismatch",
                "ID token nonce doesn't match expected value"
            );
        }
    }
    
    // 6. Check token age (ID tokens should be recent)
    const maxAge = 300;  // 5 minutes
    const age = Math.floor(Date.now() / 1000) - claims.iat;
    if (age > maxAge) {
        throw new JwtValidationError(
            "id_token_too_old",
            `ID token was issued ${age} seconds ago, max allowed is ${maxAge}`
        );
    }
    
    return claims as IdTokenClaims;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114

interface IntrospectionResponse {
    active: boolean;
    
    // Only present if active=true
    scope?: string;
    client_id?: string;
    username?: string;
    token_type?: string;
    exp?: number;
    iat?: number;
    nbf?: number;
    sub?: string;
    aud?: string | string[];
    iss?: string;
    jti?: string;
    
    // Extension claims
    [key: string]: unknown;
}
 
class TokenIntrospectionClient {
    private responseCache: LRUCache<string, IntrospectionResponse>;
    private circuitBreaker: CircuitBreaker;
    
    constructor(
        private introspectionEndpoint: string,
        private clientId: string,
        private clientSecret: string,
        config: IntrospectionConfig
    ) {
        this.responseCache = new LRUCache({
            max: config.cacheMaxSize || 10000,
            ttl: config.cacheTtl || 30000,  // 30 seconds
        });
        
        this.circuitBreaker = new CircuitBreaker({
            failureThreshold: 5,
            successThreshold: 2,
            timeout: 30000,
        });
    }
    
    async introspect(token: string): Promise<IntrospectionResponse> {
        // Check cache first (hash token for key)
        const cacheKey = this.hashToken(token);
        const cached = this.responseCache.get(cacheKey);
        if (cached) {
            return cached;
        }
        
        // Check circuit breaker
        if (this.circuitBreaker.isOpen()) {
            throw new IntrospectionError(
                "circuit_open",
                "Introspection endpoint is currently unavailable"
            );
        }
        
        try {
            const response = await this.doIntrospect(token);
            
            // Cache the response
            if (response.active) {
                this.responseCache.set(cacheKey, response);
            }
            
            this.circuitBreaker.recordSuccess();
            return response;
            
        } catch (error) {
            this.circuitBreaker.recordFailure();
            throw error;
        }
    }
    
    private async doIntrospect(token: string): Promise<IntrospectionResponse> {
        // RFC 7662: POST with form-encoded body
        const body = new URLSearchParams({
            token: token,
            token_type_hint: "access_token",
        });
        
        const response = await fetch(this.introspectionEndpoint, {
            method: "POST",
            headers: {
                "Content-Type": "application/x-www-form-urlencoded",
                "Authorization": `Basic ${this.encodeCredentials()}`,
                "Accept": "application/json",
            },
            body: body.toString(),
            signal: AbortSignal.timeout(1000),  // Fast timeout for critical path
        });
        
        if (!response.ok) {
            throw new IntrospectionError(
                "introspection_failed",
                `Introspection returned HTTP ${response.status}`
            );
        }
        
        const result = await response.json() as IntrospectionResponse;
        
        return result;
    }
    
    private hashToken(token: string): string {
        // Use first 32 chars of SHA-256 for cache key (don't store full token)
        return crypto.createHash("sha256").update(token).digest("hex").slice(0, 32);
    }
    
    private encodeCredentials(): string {
        return Buffer.from(`${this.clientId}:${this.clientSecret}`).toString("base64");
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217

interface AuthResult {
    authenticated: boolean;
    identity: {
        subject: string;
        issuer: string;
        email?: string;
        scopes: string[];
        claims: Record<string, unknown>;
    } | null;
    error: {
        code: string;
        message: string;
        details?: Record<string, unknown>;
    } | null;
    tokenType: "jwt" | "opaque" | null;
    validationDurationMs: number;
}
 
class TokenValidator {
    constructor(
        private jwksClient: JwksClient,
        private introspectionClient: TokenIntrospectionClient,
        private config: TokenValidationConfig
    ) {}
    
    async validate(token: string, request: Request): Promise<AuthResult> {
        const startTime = performance.now();
        
        try {
            // Determine token type
            const tokenType = this.detectTokenType(token);
            
            let result: AuthResult;
            if (tokenType === "jwt") {
                result = await this.validateJwt(token);
            } else {
                result = await this.validateOpaque(token);
            }
            
            result.validationDurationMs = performance.now() - startTime;
            
            // Emit metrics
            this.emitMetrics(result, request);
            
            return result;
            
        } catch (error) {
            const duration = performance.now() - startTime;
            this.emitMetrics({
                authenticated: false,
                identity: null,
                error: { code: "unexpected_error", message: (error as Error).message },
                tokenType: null,
                validationDurationMs: duration,
            }, request);
            
            throw error;
        }
    }
    
    private detectTokenType(token: string): "jwt" | "opaque" {
        // JWTs have exactly 2 dots and Base64URL-encoded parts
        const parts = token.split(".");
        if (parts.length !== 3) {
            return "opaque";
        }
        
        // Try to decode header as JSON
        try {
            const header = JSON.parse(base64UrlDecode(parts[0]));
            if (header.alg && header.typ) {
                return "jwt";
            }
        } catch {
            return "opaque";
        }
        
        return "opaque";
    }
    
    private async validateJwt(token: string): Promise<AuthResult> {
        // Step 1: Signature verification
        const { valid, claims, error } = await verifyJwtSignature(
            token,
            this.jwksClient,
            this.config.expectedIssuer
        );
        
        if (!valid) {
            return {
                authenticated: false,
                identity: null,
                error: { code: error!.code, message: error!.message },
                tokenType: "jwt",
                validationDurationMs: 0,
            };
        }
        
        // Step 2: Claims validation
        try {
            validateExpiration(claims!, this.config.clockSkewSeconds);
            validateIssuer(claims!, [this.config.expectedIssuer]);
            validateAudience(claims!, this.config.expectedAudience);
            validateNotBefore(claims!, this.config.clockSkewSeconds);
            
            // Custom validations
            if (this.config.requiredScopes.length > 0) {
                this.validateScopes(claims!, this.config.requiredScopes);
            }
            
        } catch (validationError) {
            return {
                authenticated: false,
                identity: null,
                error: {
                    code: (validationError as JwtValidationError).code,
                    message: (validationError as JwtValidationError).message,
                },
                tokenType: "jwt",
                validationDurationMs: 0,
            };
        }
        
        // Step 3: Build identity
        return {
            authenticated: true,
            identity: {
                subject: claims!.sub!,
                issuer: claims!.iss!,
                email: claims!.email as string | undefined,
                scopes: this.parseScopes(claims!.scope),
                claims: claims as Record<string, unknown>,
            },
            error: null,
            tokenType: "jwt",
            validationDurationMs: 0,
        };
    }
    
    private async validateOpaque(token: string): Promise<AuthResult> {
        const introspection = await this.introspectionClient.introspect(token);
        
        if (!introspection.active) {
            return {
                authenticated: false,
                identity: null,
                error: { code: "inactive_token", message: "Token is not active" },
                tokenType: "opaque",
                validationDurationMs: 0,
            };
        }
        
        // Validate issuer if present
        if (introspection.iss && introspection.iss !== this.config.expectedIssuer) {
            return {
                authenticated: false,
                identity: null,
                error: {
                    code: "invalid_issuer",
                    message: "Token issuer mismatch",
                },
                tokenType: "opaque",
                validationDurationMs: 0,
            };
        }
        
        return {
            authenticated: true,
            identity: {
                subject: introspection.sub!,
                issuer: introspection.iss || this.config.expectedIssuer,
                email: introspection.username,
                scopes: this.parseScopes(introspection.scope),
                claims: introspection as Record<string, unknown>,
            },
            error: null,
            tokenType: "opaque",
            validationDurationMs: 0,
        };
    }
    
    private validateScopes(claims: JwtPayload, required: string[]): void {
        const tokenScopes = this.parseScopes(claims.scope);
        const missing = required.filter(s => !tokenScopes.includes(s));
        
        if (missing.length > 0) {
            throw new JwtValidationError(
                "insufficient_scope",
                `Missing required scopes: ${missing.join(", ")}`,
                { required, present: tokenScopes }
            );
        }
    }
    
    private parseScopes(scope: unknown): string[] {
        if (typeof scope === "string") {
            return scope.split(/\s+/).filter(Boolean);
        }
        if (Array.isArray(scope)) {
            return scope.filter(s => typeof s === "string");
        }
        return [];
    }
    
    private emitMetrics(result: AuthResult, request: Request): void {
        metrics.histogram("auth.validation.duration_ms", result.validationDurationMs, {
            token_type: result.tokenType || "unknown",
            success: String(result.authenticated),
        });
        
        if (!result.authenticated) {
            metrics.increment("auth.validation.failure", {
                error_code: result.error?.code || "unknown",
            });
        }
    }
}