Claims and Validation

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

// Correct issuer validation
const TRUSTED_ISSUERS = [
    'https://auth.example.com',
    'https://auth.staging.example.com',
];
 
function validateIssuer(payload: JwtPayload): void {
    if (!payload.iss) {
        throw new ValidationError('Token missing issuer claim');
    }
    
    if (!TRUSTED_ISSUERS.includes(payload.iss)) {
        // Log for security monitoring
        logger.warn('Token from untrusted issuer', { issuer: payload.iss });
        throw new ValidationError('Token from untrusted issuer');
    }
}
 
// Common mistake: Substring matching (VULNERABLE!)
// DON'T DO THIS - attacker could register "auth.example.com.evil.com"
if (payload.iss.includes('example.com')) { /* WRONG! */ }

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

// Good: Immutable internal ID
{ "sub": "usr_7a3b9c2d4e5f" }
 
// Bad: Email (can change)
{ "sub": "john@example.com" }  // User changes email = identity confusion
 
// Bad: Username (can change)
{ "sub": "john_doe" }          // User renames = broken references
 
// Multi-tenant consideration: namespace subjects
{ 
    "sub": "usr_123",
    "tenant_id": "org_456"     // Or use iss per tenant
}
 
// Or use composite subject
{ "sub": "org_456:usr_123" }   // Clear ownership

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

// Token payload
{
    "aud": ["https://api.example.com", "https://analytics.example.com"]
}
 
// Service-side validation
const MY_AUDIENCE = 'https://api.example.com';
 
function validateAudience(payload: JwtPayload): void {
    if (!payload.aud) {
        throw new ValidationError('Token missing audience claim');
    }
    
    // aud can be string or array
    const audiences = Array.isArray(payload.aud) 
        ? payload.aud 
        : [payload.aud];
    
    if (!audiences.includes(MY_AUDIENCE)) {
        throw new ValidationError('Token not intended for this service');
    }
}
 
// Common vulnerability: Accepting ANY valid token
// If api-admin.example.com doesn't check audience,
// a regular user token for api.example.com could be replayed there

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

// Setting expiration (auth server)
function createToken(userId: string): string {
    const now = Math.floor(Date.now() / 1000);
    
    return jwt.sign({
        sub: userId,
        iat: now,
        exp: now + 3600,  // Expires in 1 hour
    }, secret);
}
 
// Validating expiration (consuming service)
function validateExpiration(payload: JwtPayload): void {
    if (!payload.exp) {
        throw new ValidationError('Token missing expiration');
    }
    
    const now = Math.floor(Date.now() / 1000);
    
    if (now >= payload.exp) {
        throw new ValidationError('Token has expired');
    }
}
 
// With clock tolerance (recommended)
const CLOCK_TOLERANCE_SECONDS = 30;
 
function validateExpirationWithTolerance(payload: JwtPayload): void {
    if (!payload.exp) {
        throw new ValidationError('Token missing expiration');
    }
    
    const now = Math.floor(Date.now() / 1000);
    
    // Allow 30 seconds of clock drift
    if (now >= payload.exp + CLOCK_TOLERANCE_SECONDS) {
        throw new ValidationError('Token has expired');
    }
}

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

// Maximum token age validation
const MAX_TOKEN_AGE_SECONDS = 86400; // 24 hours
 
function validateTokenAge(payload: JwtPayload): void {
    if (!payload.iat) {
        // Depending on policy, missing iat could be an error
        logger.warn('Token missing iat claim');
        return;
    }
    
    const now = Math.floor(Date.now() / 1000);
    const tokenAge = now - payload.iat;
    
    if (tokenAge > MAX_TOKEN_AGE_SECONDS) {
        throw new ValidationError('Token exceeds maximum age');
    }
}
 
// Invalidate tokens issued before password change
async function validatePostPasswordChange(
    payload: JwtPayload,
    userId: string
): Promise<void> {
    const user = await userRepository.findById(userId);
    
    if (!user.passwordChangedAt) return;
    
    const passwordChangedTimestamp = Math.floor(
        user.passwordChangedAt.getTime() / 1000
    );
    
    if (payload.iat && payload.iat < passwordChangedTimestamp) {
        throw new ValidationError(
            'Token issued before password change - please re-authenticate'
        );
    }
}

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

import { randomUUID } from 'crypto';
 
// Token creation with jti
function createToken(userId: string): string {
    return jwt.sign({
        sub: userId,
        jti: randomUUID(),  // e.g., "550e8400-e29b-41d4-a716-446655440000"
        iat: Math.floor(Date.now() / 1000),
        exp: Math.floor(Date.now() / 1000) + 3600,
    }, secret);
}
 
// Token revocation using jti (Redis-based blocklist)
interface TokenBlocklist {
    add(jti: string, expiresAt: number): Promise<void>;
    contains(jti: string): Promise<boolean>;
}
 
class RedisTokenBlocklist implements TokenBlocklist {
    constructor(private redis: RedisClient) {}
    
    async add(jti: string, expiresAt: number): Promise<void> {
        // Store until token would have expired anyway
        const ttlSeconds = expiresAt - Math.floor(Date.now() / 1000);
        if (ttlSeconds > 0) {
            await this.redis.setex(`blocklist:${jti}`, ttlSeconds, '1');
        }
    }
    
    async contains(jti: string): Promise<boolean> {
        const result = await this.redis.get(`blocklist:${jti}`);
        return result !== null;
    }
}
 
// Validation middleware
async function validateNotRevoked(
    payload: JwtPayload,
    blocklist: TokenBlocklist
): Promise<void> {
    if (!payload.jti) {
        // Policy decision: require jti or allow without
        throw new ValidationError('Token missing jti claim');
    }
    
    if (await blocklist.contains(payload.jti)) {
        throw new ValidationError('Token has been revoked');
    }
}
 
// One-time use tokens (for sensitive operations)
class OneTimeTokenValidator {
    private usedTokens: Set<string> = new Set();
    
    async validateAndConsume(jti: string): Promise<boolean> {
        if (this.usedTokens.has(jti)) {
            return false;  // Already used
        }
        this.usedTokens.add(jti);
        return true;
    }
}

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

// Pattern 1: Flat role list
{
    "sub": "usr_123",
    "roles": ["user", "editor", "billing_admin"]
}
 
// Pattern 2: Scoped permissions (OAuth2-style)
{
    "sub": "usr_123",
    "scope": "read:users write:articles delete:comments"
}
 
// Pattern 3: Resource-specific permissions
{
    "sub": "usr_123",
    "permissions": {
        "users": ["read", "list"],
        "articles": ["read", "write", "delete"],
        "comments": ["read", "write"]
    }
}
 
// Pattern 4: Minimal claims with role lookup
{
    "sub": "usr_123",
    "roles": ["editor"]
    // Actual permissions resolved from database based on role
}
 
// Pattern 5: Multi-tenant with tenant context
{
    "sub": "usr_123",
    "tenant_id": "org_456",
    "tenant_role": "admin",
    "global_role": "user"
}
 
// Anti-pattern: Too much data (increases token size)
{
    "sub": "usr_123",
    "full_name": "John Doe",
    "email": "john@example.com",
    "phone": "+1-555-0123",
    "address": { "street": "...", "city": "...", "country": "..." },
    "preferences": { /* pages of preferences */ },
    "order_history": [ /* hundreds of orders */ ]
}

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

interface ValidationConfig {
    trustedIssuers: string[];
    expectedAudience: string;
    algorithms: string[];
    clockToleranceSeconds: number;
    requireJti: boolean;
    maxTokenAgeSeconds?: number;
}
 
interface ValidatedToken {
    header: JwtHeader;
    payload: JwtPayload;
    signature: string;
}
 
class JWTValidator {
    constructor(
        private config: ValidationConfig,
        private keyProvider: KeyProvider,
        private blocklist?: TokenBlocklist
    ) {}
    
    async validate(token: string): Promise<ValidatedToken> {
        // Step 1: Structure validation
        const parts = this.validateStructure(token);
        
        // Step 2: Decode header (without verification yet)
        const header = this.decodeHeader(parts[0]);
        
        // Step 3: Algorithm validation
        this.validateAlgorithm(header);
        
        // Step 4: Get signing key
        const key = await this.keyProvider.getKey(header.kid);
        
        // Step 5: Signature verification
        this.verifySignature(token, key, header.alg);
        
        // Step 6: Decode payload
        const payload = this.decodePayload(parts[1]);
        
        // Step 7: Registered claims validation
        this.validateRegisteredClaims(payload);
        
        // Step 8: Revocation check (if jti present)
        if (this.blocklist && payload.jti) {
            await this.validateNotRevoked(payload.jti);
        }
        
        return {
            header,
            payload,
            signature: parts[2],
        };
    }
    
    private validateStructure(token: string): string[] {
        if (typeof token !== 'string') {
            throw new ValidationError('Token must be a string');
        }
        
        const parts = token.split('.');
        if (parts.length !== 3) {
            throw new ValidationError('Token must have 3 parts');
        }
        
        // Each part must be valid Base64URL
        for (const part of parts) {
            if (!/^[A-Za-z0-9_-]+$/.test(part)) {
                throw new ValidationError('Invalid Base64URL encoding');
            }
        }
        
        return parts;
    }
    
    private validateAlgorithm(header: JwtHeader): void {
        if (!header.alg) {
            throw new ValidationError('Token missing algorithm');
        }
        
        // CRITICAL: Explicitly check against allowed algorithms
        if (!this.config.algorithms.includes(header.alg)) {
            throw new ValidationError(`Algorithm ${header.alg} not allowed`);
        }
        
        // CRITICAL: Explicitly reject "none" algorithm
        if (header.alg.toLowerCase() === 'none') {
            throw new ValidationError('Algorithm "none" is not permitted');
        }
    }
    
    private validateRegisteredClaims(payload: JwtPayload): void {
        const now = Math.floor(Date.now() / 1000);
        const tolerance = this.config.clockToleranceSeconds;
        
        // Validate issuer
        if (!this.config.trustedIssuers.includes(payload.iss!)) {
            throw new ValidationError('Untrusted issuer');
        }
        
        // Validate audience
        const audiences = Array.isArray(payload.aud) 
            ? payload.aud 
            : [payload.aud];
        if (!audiences.includes(this.config.expectedAudience)) {
            throw new ValidationError('Token not for this audience');
        }
        
        // Validate expiration
        if (!payload.exp) {
            throw new ValidationError('Token missing expiration');
        }
        if (now >= payload.exp + tolerance) {
            throw new ValidationError('Token expired');
        }
        
        // Validate not-before (if present)
        if (payload.nbf && now < payload.nbf - tolerance) {
            throw new ValidationError('Token not yet valid');
        }
        
        // Validate token age (if configured)
        if (this.config.maxTokenAgeSeconds && payload.iat) {
            if (now - payload.iat > this.config.maxTokenAgeSeconds) {
                throw new ValidationError('Token exceeds max age');
            }
        }
        
        // Validate jti requirement
        if (this.config.requireJti && !payload.jti) {
            throw new ValidationError('Token missing jti');
        }
    }
    
    private async validateNotRevoked(jti: string): Promise<void> {
        if (await this.blocklist!.contains(jti)) {
            throw new ValidationError('Token has been revoked');
        }
    }
}

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

// VULNERABLE: Library chooses algorithm from token
jwt.verify(token, secretOrPublicKey);  // Uses token's alg claim!
 
// VULNERABLE: Accepting any algorithm
jwt.verify(token, key, { algorithms: '*' });  // NEVER DO THIS
 
// SECURE: Explicitly specify expected algorithm
jwt.verify(token, publicKey, { 
    algorithms: ['RS256']  // Only accept RS256
});
 
// SECURE: Configuration-driven
const config = {
    hmacSecret: process.env.JWT_SECRET,
    allowedAlgorithms: ['HS256'],  // Whitelist, not blacklist
};

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

// Domain types for strong typing
type Role = 'user' | 'editor' | 'admin' | 'super_admin';
type Permission = `${'read' | 'write' | 'delete'}:${'users' | 'articles' | 'settings'}`;
 
interface AppJwtPayload extends JwtPayload {
    sub: string;
    tenant_id?: string;
    roles?: Role[];
    permissions?: Permission[];
    scope?: string;  // OAuth2-style space-separated scopes
}
 
class ClaimsValidator {
    /**
     * Validate user has required role(s)
     */
    requireRoles(
        payload: AppJwtPayload, 
        requiredRoles: Role[],
        mode: 'any' | 'all' = 'any'
    ): void {
        if (!payload.roles || payload.roles.length === 0) {
            throw new AuthorizationError('User has no roles');
        }
        
        if (mode === 'any') {
            const hasAny = requiredRoles.some(r => payload.roles!.includes(r));
            if (!hasAny) {
                throw new AuthorizationError(
                    `Requires one of: ${requiredRoles.join(', ')}`
                );
            }
        } else {
            const hasAll = requiredRoles.every(r => payload.roles!.includes(r));
            if (!hasAll) {
                throw new AuthorizationError(
                    `Requires all of: ${requiredRoles.join(', ')}`
                );
            }
        }
    }
    
    /**
     * Validate user has specific permission
     */
    requirePermission(
        payload: AppJwtPayload,
        permission: Permission
    ): void {
        // Check explicit permissions
        if (payload.permissions?.includes(permission)) {
            return;
        }
        
        // Check OAuth2-style scopes
        if (payload.scope) {
            const scopes = payload.scope.split(' ');
            if (scopes.includes(permission)) {
                return;
            }
        }
        
        throw new AuthorizationError(`Missing permission: ${permission}`);
    }
    
    /**
     * Validate tenant context
     */
    requireTenant(
        payload: AppJwtPayload,
        tenantId: string
    ): void {
        if (!payload.tenant_id) {
            throw new AuthorizationError('Token missing tenant context');
        }
        
        if (payload.tenant_id !== tenantId) {
            // Don't reveal which tenant was expected
            throw new AuthorizationError('Access denied for this resource');
        }
    }
    
    /**
     * Validate access to specific resource
     */
    requireResourceAccess(
        payload: AppJwtPayload,
        resourceType: string,
        resourceOwnerId: string,
        requiredAccess: 'read' | 'write' | 'delete'
    ): void {
        // Admins can access everything
        if (payload.roles?.includes('admin') || 
            payload.roles?.includes('super_admin')) {
            return;
        }
        
        // Check if user owns the resource
        if (payload.sub === resourceOwnerId) {
            return;
        }
        
        // Check explicit permission
        const permission = `${requiredAccess}:${resourceType}` as Permission;
        this.requirePermission(payload, permission);
    }
}
 
// Usage in route handlers
const validator = new ClaimsValidator();
 
app.delete('/api/articles/:id', authenticate, async (req, res) => {
    const payload = req.user as AppJwtPayload;
    const article = await articleService.findById(req.params.id);
    
    // Validate tenant first (if multi-tenant)
    validator.requireTenant(payload, article.tenantId);
    
    // Then validate access
    validator.requireResourceAccess(
        payload,
        'articles',
        article.authorId,
        'delete'
    );
    
    await articleService.delete(req.params.id);
    res.status(204).send();
});