Token Validation

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

// JWT Structure Visualization
interface JWTHeader {
    alg: string;  // Algorithm: "RS256", "ES256", "HS256", etc.
    typ: string;  // Type: typically "JWT"
    kid?: string; // Key ID: identifies which key signed this token
}
 
interface JWTPayload {
    // Standard claims (registered)
    iss?: string;  // Issuer: who created and signed this token
    sub?: string;  // Subject: who this token is about (user ID)
    aud?: string | string[]; // Audience: intended recipient(s)
    exp?: number;  // Expiration: unix timestamp when token expires
    nbf?: number;  // Not Before: token invalid before this time
    iat?: number;  // Issued At: when token was created
    jti?: string;  // JWT ID: unique identifier for this token
    
    // OIDC-specific
    nonce?: string;    // Prevents replay attacks
    auth_time?: number; // When user authenticated
    acr?: string;      // Auth context class
    amr?: string[];    // Auth methods used
    
    // Custom claims
    scope?: string;    // OAuth scopes
    roles?: string[];  // User roles
    permissions?: string[]; // Fine-grained permissions
    [key: string]: any; // Extension claims
}
 
// Decoding (NOT validating) a JWT
function decodeJWT(token: string): { header: JWTHeader; payload: JWTPayload } {
    const parts = token.split('.');
    if (parts.length !== 3) {
        throw new Error('Invalid JWT format');
    }
    
    const header = JSON.parse(
        Buffer.from(parts[0], 'base64url').toString()
    );
    const payload = JSON.parse(
        Buffer.from(parts[1], 'base64url').toString()
    );
    
    // WARNING: This only decodes, it does NOT validate!
    // Never use decoded claims without signature verification
    return { header, payload };
}

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

// Secure Signature Verification with jose library
import * as jose from 'jose';
 
// ========================================
// Asymmetric Verification (RS256, ES256)
// ========================================
 
// For OIDC providers: Fetch public keys from JWKS
async function verifyWithJWKS(
    token: string,
    jwksUrl: string,
    expectedIssuer: string,
    expectedAudience: string
): Promise<jose.JWTPayload> {
    // Create JWKS client (handles key caching, rotation)
    const JWKS = jose.createRemoteJWKSet(new URL(jwksUrl));
    
    const { payload } = await jose.jwtVerify(
        token,
        JWKS,
        {
            issuer: expectedIssuer,
            audience: expectedAudience,
            // CRITICAL: Restrict allowed algorithms
            algorithms: ['RS256', 'ES256'],
            // Reject tokens from the future
            clockTolerance: 30, // 30 seconds tolerance for clock skew
        }
    );
    
    return payload;
}
 
// For self-managed keys: Use public key directly
async function verifyWithPublicKey(
    token: string,
    publicKeyPEM: string,
    expectedIssuer: string,
    expectedAudience: string
): Promise<jose.JWTPayload> {
    const publicKey = await jose.importSPKI(publicKeyPEM, 'RS256');
    
    const { payload } = await jose.jwtVerify(
        token,
        publicKey,
        {
            issuer: expectedIssuer,
            audience: expectedAudience,
            algorithms: ['RS256'], // Only accept expected algorithm
        }
    );
    
    return payload;
}
 
// ========================================
// Symmetric Verification (HS256)
// ========================================
 
// WARNING: Only for first-party tokens where validator = issuer
async function verifyWithSecret(
    token: string,
    secret: string,
    expectedIssuer: string,
    expectedAudience: string
): Promise<jose.JWTPayload> {
    // Secret must be sufficiently random (256+ bits for HS256)
    const secretKey = new TextEncoder().encode(secret);
    
    const { payload } = await jose.jwtVerify(
        token,
        secretKey,
        {
            issuer: expectedIssuer,
            audience: expectedAudience,
            algorithms: ['HS256'], // Explicit algorithm restriction
        }
    );
    
    return payload;
}
 
// ========================================
// Algorithm Confusion Prevention
// ========================================
 
// WRONG: Naive verification vulnerable to alg confusion
async function vulnerableVerify(token: string, keyOrSecret: unknown) {
    const { header } = jose.decodeJwt(token);
    
    // DANGEROUS: Trusting the token's claimed algorithm!
    if (header.alg === 'none') {
        // Attacker removes signature entirely
        return jose.decodeJwt(token); // No verification!
    }
    
    if (header.alg.startsWith('HS')) {
        // Attacker switches RS256 to HS256, uses public key as HMAC secret
        return jose.jwtVerify(token, keyOrSecret as Uint8Array);
    }
    
    // This code is INSECURE - never use in production
}
 
// CORRECT: Algorithm is enforced, not trusted from token
async function secureVerify(
    token: string,
    key: jose.KeyLike,
    expectedAlgorithm: string
): Promise<jose.JWTPayload> {
    const { payload } = await jose.jwtVerify(token, key, {
        algorithms: [expectedAlgorithm], // You decide the algorithm, not the token
    });
    return payload;
}

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

// Comprehensive Claims Validation
interface ValidationConfig {
    issuer: string;
    audience: string | string[];
    clockToleranceSeconds: number;
    maxTokenAgeSeconds?: number;
    requiredScopes?: string[];
    requiredClaims?: string[];
}
 
interface ValidationResult {
    valid: boolean;
    payload?: Record<string, any>;
    error?: string;
}
 
class ClaimsValidator {
    constructor(private config: ValidationConfig) {}
    
    validate(payload: Record<string, any>, expectedNonce?: string): ValidationResult {
        try {
            // 1. Validate issuer (exact match required)
            this.validateIssuer(payload);
            
            // 2. Validate audience
            this.validateAudience(payload);
            
            // 3. Validate temporal claims
            this.validateTemporalClaims(payload);
            
            // 4. Validate nonce if provided (OIDC)
            if (expectedNonce) {
                this.validateNonce(payload, expectedNonce);
            }
            
            // 5. Validate required scopes
            if (this.config.requiredScopes) {
                this.validateScopes(payload, this.config.requiredScopes);
            }
            
            // 6. Validate required claims are present
            if (this.config.requiredClaims) {
                this.validateRequiredClaims(payload, this.config.requiredClaims);
            }
            
            return { valid: true, payload };
        } catch (error) {
            return { 
                valid: false, 
                error: error instanceof Error ? error.message : 'Validation failed' 
            };
        }
    }
    
    private validateIssuer(payload: Record<string, any>): void {
        // Exact match - trailing slashes, protocol all matter
        if (payload.iss !== this.config.issuer) {
            throw new Error(
                `Invalid issuer: expected '${this.config.issuer}', got '${payload.iss}'`
            );
        }
    }
    
    private validateAudience(payload: Record<string, any>): void {
        const tokenAudience = Array.isArray(payload.aud) 
            ? payload.aud 
            : [payload.aud];
        const expectedAudiences = Array.isArray(this.config.audience)
            ? this.config.audience
            : [this.config.audience];
        
        const hasValidAudience = tokenAudience.some(
            aud => expectedAudiences.includes(aud)
        );
        
        if (!hasValidAudience) {
            throw new Error(
                `Token not intended for this audience. Expected: ${expectedAudiences.join(', ')}`
            );
        }
        
        // For multi-audience tokens, check azp (authorized party)
        if (tokenAudience.length > 1 && payload.azp) {
            if (!expectedAudiences.includes(payload.azp)) {
                throw new Error('Token authorized party does not match');
            }
        }
    }
    
    private validateTemporalClaims(payload: Record<string, any>): void {
        const now = Math.floor(Date.now() / 1000);
        const tolerance = this.config.clockToleranceSeconds;
        
        // Token must not be expired
        if (payload.exp !== undefined) {
            if (now > payload.exp + tolerance) {
                throw new Error('Token has expired');
            }
        }
        
        // Token must be valid now (not before)
        if (payload.nbf !== undefined) {
            if (now < payload.nbf - tolerance) {
                throw new Error('Token not yet valid');
            }
        }
        
        // Token must have been issued in the past
        if (payload.iat !== undefined) {
            if (payload.iat > now + tolerance) {
                throw new Error('Token issued in the future');
            }
            
            // Optional: Reject very old tokens
            if (this.config.maxTokenAgeSeconds) {
                const tokenAge = now - payload.iat;
                if (tokenAge > this.config.maxTokenAgeSeconds) {
                    throw new Error('Token is too old');
                }
            }
        }
    }
    
    private validateNonce(payload: Record<string, any>, expectedNonce: string): void {
        if (payload.nonce !== expectedNonce) {
            throw new Error('Nonce mismatch - possible token replay or injection');
        }
    }
    
    private validateScopes(payload: Record<string, any>, required: string[]): void {
        const tokenScopes = (payload.scope || '').split(' ').filter(Boolean);
        
        for (const requiredScope of required) {
            if (!tokenScopes.includes(requiredScope)) {
                throw new Error(`Missing required scope: ${requiredScope}`);
            }
        }
    }
    
    private validateRequiredClaims(
        payload: Record<string, any>, 
        required: string[]
    ): void {
        for (const claim of required) {
            if (!(claim in payload) || payload[claim] == null) {
                throw new Error(`Missing required claim: ${claim}`);
            }
        }
    }
}
 
// Usage
const validator = new ClaimsValidator({
    issuer: 'https://auth.example.com',
    audience: 'my-app-client-id',
    clockToleranceSeconds: 30,
    maxTokenAgeSeconds: 3600, // 1 hour
    requiredScopes: ['read', 'write'],
    requiredClaims: ['sub', 'email'],
});
 
const result = validator.validate(tokenPayload, sessionNonce);
if (!result.valid) {
    throw new AuthError(`Token validation failed: ${result.error}`);
}

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

// Scope and Permission Validation System
type ScopePattern = string; // e.g., "users:read", "payments:*"
 
interface ScopeValidationConfig {
    scopeClaim: string; // Usually 'scope' or 'scp'
    hierarchical: boolean; // Does 'users:*' include 'users:read'?
    caseSensitive: boolean;
}
 
class ScopeValidator {
    constructor(private config: ScopeValidationConfig = {
        scopeClaim: 'scope',
        hierarchical: true,
        caseSensitive: true,
    }) {}
    
    // Extract scopes from token payload
    extractScopes(payload: Record<string, any>): string[] {
        const scopeValue = payload[this.config.scopeClaim];
        
        if (!scopeValue) {
            return [];
        }
        
        // Handle both space-delimited string and array formats
        if (Array.isArray(scopeValue)) {
            return scopeValue;
        }
        
        return scopeValue.split(' ').filter(Boolean);
    }
    
    // Check if token has specific scope
    hasScope(tokenScopes: string[], required: ScopePattern): boolean {
        const normalizedRequired = this.normalize(required);
        
        return tokenScopes.some(tokenScope => {
            const normalized = this.normalize(tokenScope);
            
            // Exact match
            if (normalized === normalizedRequired) {
                return true;
            }
            
            // Hierarchical match (admin includes everything)
            if (this.config.hierarchical) {
                // Check wildcard patterns
                if (this.matchesWildcard(normalizedRequired, normalized)) {
                    return true;
                }
                
                // Check hierarchy (users:read:own covered by users:read:*)
                if (this.matchesHierarchy(normalizedRequired, normalized)) {
                    return true;
                }
            }
            
            return false;
        });
    }
    
    // Check if token has ALL required scopes
    hasAllScopes(tokenScopes: string[], required: ScopePattern[]): boolean {
        return required.every(scope => this.hasScope(tokenScopes, scope));
    }
    
    // Check if token has ANY of the scopes
    hasAnyScope(tokenScopes: string[], required: ScopePattern[]): boolean {
        return required.some(scope => this.hasScope(tokenScopes, scope));
    }
    
    private normalize(scope: string): string {
        return this.config.caseSensitive ? scope : scope.toLowerCase();
    }
    
    private matchesWildcard(required: string, tokenScope: string): boolean {
        // users:* matches users:read, users:write, etc.
        if (tokenScope.endsWith('*')) {
            const prefix = tokenScope.slice(0, -1);
            return required.startsWith(prefix);
        }
        return false;
    }
    
    private matchesHierarchy(required: string, tokenScope: string): boolean {
        // admin:users includes admin:users:read
        const requiredParts = required.split(':');
        const tokenParts = tokenScope.split(':');
        
        // Token scope must be equal or more general
        if (tokenParts.length > requiredParts.length) {
            return false;
        }
        
        return tokenParts.every((part, index) => {
            if (part === '*') return true;
            return part === requiredParts[index];
        });
    }
}
 
// Express middleware for scope validation
function requireScopes(...requiredScopes: string[]) {
    return (req: Request, res: Response, next: NextFunction) => {
        const tokenScopes = req.tokenPayload?.scope?.split(' ') || [];
        const validator = new ScopeValidator();
        
        if (!validator.hasAllScopes(tokenScopes, requiredScopes)) {
            return res.status(403).json({
                error: 'insufficient_scope',
                required: requiredScopes,
                provided: tokenScopes,
            });
        }
        
        next();
    };
}
 
// Route-level scope enforcement
app.get('/api/users', 
    authenticateToken,
    requireScopes('users:read'),
    async (req, res) => {
        // Token has users:read scope
        const users = await getUsers();
        res.json(users);
    }
);
 
app.post('/api/payments',
    authenticateToken,
    requireScopes('payments:write', 'financial:access'),
    async (req, res) => {
        // Token has both payments:write AND financial:access
        const payment = await createPayment(req.body);
        res.json(payment);
    }
);

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

// Production Revocation Checking Implementation
import Redis from 'ioredis';
 
const redis = new Redis(process.env.REDIS_URL);
 
// ========================================
// Strategy 1: Deny List with Redis
// ========================================
 
class TokenDenyList {
    private readonly prefix = 'token:revoked:';
    
    async revokeToken(jti: string, expiresAt: number): Promise<void> {
        const now = Math.floor(Date.now() / 1000);
        const ttl = expiresAt - now;
        
        if (ttl > 0) {
            // Only store until token would have expired anyway
            await redis.set(`${this.prefix}${jti}`, '1', 'EX', ttl);
        }
    }
    
    async isRevoked(jti: string): Promise<boolean> {
        const result = await redis.get(`${this.prefix}${jti}`);
        return result !== null;
    }
    
    // Revoke all tokens for a user (logout everywhere)
    async revokeUserTokens(userId: string): Promise<void> {
        // This requires tracking all tokens per user, or...
        // Use token versioning instead (see below)
    }
}
 
// ========================================
// Strategy 2: Token Versioning
// ========================================
 
interface TokenVersionStore {
    getUserTokenVersion(userId: string): Promise<number>;
    incrementTokenVersion(userId: string): Promise<number>;
}
 
class TokenVersionValidator {
    constructor(private versionStore: TokenVersionStore) {}
    
    async isValidVersion(userId: string, tokenVersion?: number): Promise<boolean> {
        if (tokenVersion === undefined) {
            // Tokens without version are always invalid in this system
            return false;
        }
        
        const currentVersion = await this.versionStore.getUserTokenVersion(userId);
        return tokenVersion >= currentVersion;
    }
    
    async revokeAllUserTokens(userId: string): Promise<void> {
        await this.versionStore.incrementTokenVersion(userId);
    }
}
 
// ========================================
// Strategy 3: Token Introspection (RFC 7662)
// ========================================
 
interface IntrospectionResponse {
    active: boolean;
    scope?: string;
    client_id?: string;
    username?: string;
    token_type?: string;
    exp?: number;
    iat?: number;
    nbf?: number;
    sub?: string;
    aud?: string;
    iss?: string;
    jti?: string;
}
 
class TokenIntrospector {
    constructor(
        private introspectionEndpoint: string,
        private clientId: string,
        private clientSecret: string,
    ) {}
    
    async introspect(token: string): Promise<IntrospectionResponse> {
        const response = await fetch(this.introspectionEndpoint, {
            method: 'POST',
            headers: {
                'Content-Type': 'application/x-www-form-urlencoded',
                'Authorization': `Basic ${Buffer.from(
                    `${this.clientId}:${this.clientSecret}`
                ).toString('base64')}`,
            },
            body: new URLSearchParams({
                token: token,
                token_type_hint: 'access_token',
            }),
        });
        
        return response.json();
    }
    
    async isTokenActive(token: string): Promise<boolean> {
        const result = await this.introspect(token);
        return result.active === true;
    }
}
 
// ========================================
// Combined Validation with Revocation Check
// ========================================
 
class TokenValidator {
    constructor(
        private jwtVerifier: JWTVerifier,
        private denyList: TokenDenyList,
        private versionValidator: TokenVersionValidator,
    ) {}
    
    async validateToken(token: string): Promise<TokenPayload> {
        // Step 1: Cryptographic validation (signature, expiry, audience)
        const payload = await this.jwtVerifier.verify(token);
        
        // Step 2: Check deny list
        if (payload.jti) {
            const isRevoked = await this.denyList.isRevoked(payload.jti);
            if (isRevoked) {
                throw new TokenError('Token has been revoked');
            }
        }
        
        // Step 3: Check token version
        if (payload.sub) {
            const isValidVersion = await this.versionValidator.isValidVersion(
                payload.sub,
                payload.tokenVersion
            );
            if (!isValidVersion) {
                throw new TokenError('Token version is outdated');
            }
        }
        
        return payload;
    }
}

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

// Production Authentication Middleware
import * as jose from 'jose';
import { Request, Response, NextFunction } from 'express';
 
interface AuthConfig {
    issuer: string;
    audience: string;
    jwksUri: string;
    algorithms: string[];
    clockToleranceSeconds: number;
    tokenLookupFn?: (req: Request) => string | undefined;
}
 
interface AuthenticatedRequest extends Request {
    auth: {
        token: string;
        payload: jose.JWTPayload;
        scopes: string[];
        userId: string;
    };
}
 
class AuthMiddleware {
    private jwks: jose.JWTVerifyGetKey;
    
    constructor(private config: AuthConfig) {
        this.jwks = jose.createRemoteJWKSet(new URL(config.jwksUri));
    }
    
    // Extract token from request
    private extractToken(req: Request): string | undefined {
        // Custom extraction function
        if (this.config.tokenLookupFn) {
            return this.config.tokenLookupFn(req);
        }
        
        // Standard: Authorization header
        const authHeader = req.headers.authorization;
        if (authHeader?.startsWith('Bearer ')) {
            return authHeader.slice(7);
        }
        
        // Fallback: Query parameter (less secure, use sparingly)
        if (req.query.access_token) {
            return req.query.access_token as string;
        }
        
        return undefined;
    }
    
    // Main authentication middleware
    authenticate() {
        return async (req: Request, res: Response, next: NextFunction) => {
            try {
                const token = this.extractToken(req);
                
                if (!token) {
                    return res.status(401).json({
                        error: 'missing_token',
                        error_description: 'No access token provided',
                    });
                }
                
                // Verify token
                const { payload } = await jose.jwtVerify(token, this.jwks, {
                    issuer: this.config.issuer,
                    audience: this.config.audience,
                    algorithms: this.config.algorithms as any[],
                    clockTolerance: this.config.clockToleranceSeconds,
                });
                
                // Optional: Additional revocation checks
                // await this.checkRevocation(payload);
                
                // Attach to request
                (req as AuthenticatedRequest).auth = {
                    token,
                    payload,
                    scopes: (payload.scope as string || '').split(' ').filter(Boolean),
                    userId: payload.sub as string,
                };
                
                next();
            } catch (error) {
                if (error instanceof jose.errors.JWTExpired) {
                    return res.status(401).json({
                        error: 'token_expired',
                        error_description: 'Access token has expired',
                    });
                }
                
                if (error instanceof jose.errors.JWTInvalid) {
                    return res.status(401).json({
                        error: 'invalid_token',
                        error_description: 'Access token is invalid',
                    });
                }
                
                if (error instanceof jose.errors.JWTClaimValidationFailed) {
                    return res.status(401).json({
                        error: 'invalid_claims',
                        error_description: error.message,
                    });
                }
                
                console.error('Auth error:', error);
                return res.status(401).json({
                    error: 'authentication_error',
                    error_description: 'Unable to authenticate request',
                });
            }
        };
    }
    
    // Scope checking middleware
    requireScopes(...requiredScopes: string[]) {
        return (req: Request, res: Response, next: NextFunction) => {
            const authReq = req as AuthenticatedRequest;
            
            if (!authReq.auth) {
                return res.status(401).json({
                    error: 'unauthenticated',
                    error_description: 'Authentication required',
                });
            }
            
            const hasScopes = requiredScopes.every(
                scope => authReq.auth.scopes.includes(scope)
            );
            
            if (!hasScopes) {
                return res.status(403).json({
                    error: 'insufficient_scope',
                    error_description: `Required scopes: ${requiredScopes.join(', ')}`,
                    required_scopes: requiredScopes,
                });
            }
            
            next();
        };
    }
    
    // Optional authentication (doesn't fail if no token)
    optionalAuth() {
        return async (req: Request, res: Response, next: NextFunction) => {
            const token = this.extractToken(req);
            
            if (!token) {
                return next(); // Continue without auth
            }
            
            try {
                const { payload } = await jose.jwtVerify(token, this.jwks, {
                    issuer: this.config.issuer,
                    audience: this.config.audience,
                    algorithms: this.config.algorithms as any[],
                    clockTolerance: this.config.clockToleranceSeconds,
                });
                
                (req as AuthenticatedRequest).auth = {
                    token,
                    payload,
                    scopes: (payload.scope as string || '').split(' ').filter(Boolean),
                    userId: payload.sub as string,
                };
            } catch {
                // Invalid token on optional route - continue unauthenticated
            }
            
            next();
        };
    }
}
 
// Usage
const auth = new AuthMiddleware({
    issuer: 'https://auth.example.com',
    audience: 'my-api',
    jwksUri: 'https://auth.example.com/.well-known/jwks.json',
    algorithms: ['RS256'],
    clockToleranceSeconds: 30,
});
 
// Protected route
app.get('/api/protected',
    auth.authenticate(),
    (req, res) => {
        const authReq = req as AuthenticatedRequest;
        res.json({ userId: authReq.auth.userId });
    }
);
 
// Route with specific scope requirement
app.delete('/api/users/:id',
    auth.authenticate(),
    auth.requireScopes('users:delete', 'admin'),
    (req, res) => {
        // Has both users:delete AND admin scopes
    }
);
 
// Optional auth route (works with or without token)
app.get('/api/content',
    auth.optionalAuth(),
    (req, res) => {
        const authReq = req as AuthenticatedRequest;
        const isAuthenticated = !!authReq.auth;
        // Return different content based on auth status
    }
);