Access Tokens and Refresh 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
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

// Robust Token Refresh Pattern
interface TokenSet {
    accessToken: string;
    refreshToken: string;
    expiresAt: number; // Unix timestamp
}
 
class TokenManager {
    private tokens: TokenSet | null = null;
    private refreshPromise: Promise<TokenSet> | null = null;
    
    constructor(
        private tokenEndpoint: string,
        private clientId: string,
    ) {}
    
    // Get valid access token, refreshing if needed
    async getAccessToken(): Promise<string> {
        if (!this.tokens) {
            throw new Error('Not authenticated');
        }
        
        // Check if token expires within buffer period (60 seconds)
        const bufferMs = 60 * 1000;
        const isExpiringSoon = Date.now() > (this.tokens.expiresAt - bufferMs);
        
        if (isExpiringSoon) {
            await this.refreshTokens();
        }
        
        return this.tokens.accessToken;
    }
    
    // Refresh tokens with concurrency handling
    private async refreshTokens(): Promise<void> {
        // Prevent multiple concurrent refresh requests
        if (this.refreshPromise) {
            await this.refreshPromise;
            return;
        }
        
        this.refreshPromise = this.executeRefresh();
        
        try {
            this.tokens = await this.refreshPromise;
        } finally {
            this.refreshPromise = null;
        }
    }
    
    private async executeRefresh(): Promise<TokenSet> {
        const response = await fetch(this.tokenEndpoint, {
            method: 'POST',
            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
            body: new URLSearchParams({
                grant_type: 'refresh_token',
                refresh_token: this.tokens!.refreshToken,
                client_id: this.clientId,
            }),
        });
        
        if (!response.ok) {
            // Refresh failed - likely revoked or expired
            this.tokens = null;
            throw new Error('Session expired - please log in again');
        }
        
        const data = await response.json();
        
        return {
            accessToken: data.access_token,
            // Use new refresh token if provided (rotation)
            refreshToken: data.refresh_token || this.tokens!.refreshToken,
            expiresAt: Date.now() + (data.expires_in * 1000),
        };
    }
    
    // Authenticated fetch wrapper
    async authenticatedFetch(url: string, options: RequestInit = {}) {
        const token = await this.getAccessToken();
        
        const response = await fetch(url, {
            ...options,
            headers: {
                ...options.headers,
                'Authorization': `Bearer ${token}`,
            },
        });
        
        // Handle 401 by refreshing and retrying once
        if (response.status === 401) {
            await this.refreshTokens();
            const newToken = await this.getAccessToken();
            
            return fetch(url, {
                ...options,
                headers: {
                    ...options.headers,
                    'Authorization': `Bearer ${newToken}`,
                },
            });
        }
        
        return response;
    }
}

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

// Server-side Refresh Token Rotation Implementation
interface RefreshTokenRecord {
    tokenHash: string;
    userId: string;
    clientId: string;
    scope: string;
    familyId: string; // Links related tokens for revocation
    createdAt: Date;
    expiresAt: Date;
    usedAt: Date | null;
    replacedByHash: string | null;
}
 
class RefreshTokenService {
    constructor(private db: Database, private crypto: CryptoService) {}
    
    // Issue new refresh token
    async issueRefreshToken(
        userId: string,
        clientId: string,
        scope: string,
        familyId?: string, // New family for initial login
    ): Promise<string> {
        const token = this.crypto.generateSecureToken(256);
        const tokenHash = await this.crypto.hashToken(token);
        
        await this.db.refreshTokens.create({
            tokenHash,
            userId,
            clientId,
            scope,
            familyId: familyId || this.crypto.generateUUID(),
            createdAt: new Date(),
            expiresAt: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000), // 30 days
            usedAt: null,
            replacedByHash: null,
        });
        
        return token;
    }
    
    // Rotate refresh token (called during token refresh)
    async rotateRefreshToken(oldToken: string): Promise<{
        newToken: string;
        accessToken: string;
        userId: string;
    }> {
        const oldTokenHash = await this.crypto.hashToken(oldToken);
        
        const record = await this.db.refreshTokens.findUnique({
            where: { tokenHash: oldTokenHash },
        });
        
        // Token doesn't exist
        if (!record) {
            throw new TokenError('invalid_grant', 'Refresh token not found');
        }
        
        // Token expired
        if (record.expiresAt < new Date()) {
            await this.revokeTokenFamily(record.familyId);
            throw new TokenError('invalid_grant', 'Refresh token expired');
        }
        
        // CRITICAL: Detect token reuse (already used = potential theft)
        if (record.usedAt !== null) {
            // This token was already used! Revoke ENTIRE family
            // Either the token was stolen, or the legitimate client is out of sync
            await this.revokeTokenFamily(record.familyId);
            
            // Log security event for investigation
            await this.logSecurityEvent('REFRESH_TOKEN_REUSE', {
                userId: record.userId,
                clientId: record.clientId,
                familyId: record.familyId,
                originalUseTime: record.usedAt,
                reuseAttemptTime: new Date(),
            });
            
            throw new TokenError(
                'invalid_grant',
                'Token reuse detected - session terminated for security'
            );
        }
        
        // Issue new refresh token in same family
        const newToken = await this.issueRefreshToken(
            record.userId,
            record.clientId,
            record.scope,
            record.familyId, // Same family
        );
        
        const newTokenHash = await this.crypto.hashToken(newToken);
        
        // Mark old token as used (not deleted - kept for reuse detection)
        await this.db.refreshTokens.update({
            where: { tokenHash: oldTokenHash },
            data: {
                usedAt: new Date(),
                replacedByHash: newTokenHash,
            },
        });
        
        // Issue new access token
        const accessToken = await this.issueAccessToken(
            record.userId,
            record.clientId,
            record.scope,
        );
        
        return { newToken, accessToken, userId: record.userId };
    }
    
    // Revoke all tokens in a family (used for logout or breach detection)
    async revokeTokenFamily(familyId: string): Promise<void> {
        await this.db.refreshTokens.updateMany({
            where: { familyId },
            data: { expiresAt: new Date() }, // Immediately expire
        });
    }
    
    // Revoke all tokens for a user (password change, account compromise)
    async revokeAllUserTokens(userId: string): Promise<void> {
        await this.db.refreshTokens.updateMany({
            where: { userId },
            data: { expiresAt: new Date() },
        });
    }
}

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

// Configurable Token Lifetime Policy
interface TokenLifetimePolicy {
    accessTokenTTL: number;      // seconds
    refreshTokenTTL: number;     // seconds
    absoluteSessionTTL: number;  // seconds - max total session length
    inactivityTimeout: number;   // seconds - revoke if no activity
    rotateRefreshTokens: boolean;
    requireReauthForSensitive: boolean;
}
 
const policies: Record<string, TokenLifetimePolicy> = {
    consumer: {
        accessTokenTTL: 60 * 60,              // 1 hour
        refreshTokenTTL: 90 * 24 * 60 * 60,   // 90 days
        absoluteSessionTTL: 365 * 24 * 60 * 60, // 1 year
        inactivityTimeout: 30 * 24 * 60 * 60, // 30 days
        rotateRefreshTokens: true,
        requireReauthForSensitive: true,
    },
    enterprise: {
        accessTokenTTL: 30 * 60,              // 30 minutes
        refreshTokenTTL: 14 * 24 * 60 * 60,   // 14 days
        absoluteSessionTTL: 30 * 24 * 60 * 60, // 30 days
        inactivityTimeout: 7 * 24 * 60 * 60,  // 7 days
        rotateRefreshTokens: true,
        requireReauthForSensitive: true,
    },
    banking: {
        accessTokenTTL: 10 * 60,              // 10 minutes
        refreshTokenTTL: 8 * 60 * 60,         // 8 hours (workday)
        absoluteSessionTTL: 24 * 60 * 60,     // 24 hours
        inactivityTimeout: 15 * 60,           // 15 minutes
        rotateRefreshTokens: true,
        requireReauthForSensitive: true,
    },
};
 
class TokenLifetimeManager {
    constructor(private policy: TokenLifetimePolicy) {}
    
    calculateAccessTokenExpiry(): Date {
        return new Date(Date.now() + this.policy.accessTokenTTL * 1000);
    }
    
    calculateRefreshTokenExpiry(sessionStartTime: Date): Date {
        const normalExpiry = Date.now() + this.policy.refreshTokenTTL * 1000;
        const absoluteLimit = sessionStartTime.getTime() + 
            this.policy.absoluteSessionTTL * 1000;
        
        // Refresh token can't extend beyond absolute session limit
        return new Date(Math.min(normalExpiry, absoluteLimit));
    }
    
    shouldRevokeForInactivity(lastActivityTime: Date): boolean {
        const inactiveMs = Date.now() - lastActivityTime.getTime();
        return inactiveMs > this.policy.inactivityTimeout * 1000;
    }
    
    shouldRequireReauth(
        operation: string, 
        lastAuthTime: Date,
        sensitiveOps: string[]
    ): boolean {
        if (!this.policy.requireReauthForSensitive) return false;
        if (!sensitiveOps.includes(operation)) return false;
        
        // Require re-auth if last auth was more than 15 min ago
        const reauthThreshold = 15 * 60 * 1000;
        return Date.now() - lastAuthTime.getTime() > reauthThreshold;
    }
}

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

// Pattern 1: Backend-for-Frontend (BFF) - Recommended for SPAs
// The BFF is a server-side component that holds tokens and proxies API requests
 
// BFF Server (Express/Node.js)
const express = require('express');
const session = require('express-session');
const RedisStore = require('connect-redis').default;
 
const app = express();
 
// Session configuration with httpOnly cookies
app.use(session({
    store: new RedisStore({ client: redisClient }),
    secret: process.env.SESSION_SECRET,
    resave: false,
    saveUninitialized: false,
    cookie: {
        httpOnly: true,     // Prevents XSS access to cookie
        secure: true,       // HTTPS only
        sameSite: 'strict', // CSRF protection
        maxAge: 24 * 60 * 60 * 1000, // 24 hours
    },
}));
 
// BFF token storage in session
app.post('/bff/auth/callback', async (req, res) => {
    const { code } = req.body;
    
    // Exchange code for tokens (server-side, secure)
    const tokens = await exchangeCodeForTokens(code);
    
    // Store tokens in server session - NEVER sent to browser
    req.session.tokens = {
        accessToken: tokens.access_token,
        refreshToken: tokens.refresh_token,
        expiresAt: Date.now() + tokens.expires_in * 1000,
    };
    
    res.json({ success: true }); // Only success indicator to frontend
});
 
// BFF API proxy - adds token to requests
app.all('/bff/api/*', async (req, res) => {
    if (!req.session.tokens) {
        return res.status(401).json({ error: 'Not authenticated' });
    }
    
    // Refresh if needed
    if (Date.now() > req.session.tokens.expiresAt - 60000) {
        req.session.tokens = await refreshTokens(req.session.tokens);
    }
    
    // Proxy request to actual API with token
    const apiPath = req.path.replace('/bff/api', '');
    const response = await fetch(`https://api.example.com${apiPath}`, {
        method: req.method,
        headers: {
            'Authorization': `Bearer ${req.session.tokens.accessToken}`,
            'Content-Type': req.headers['content-type'],
        },
        body: ['GET', 'HEAD'].includes(req.method) ? undefined : JSON.stringify(req.body),
    });
    
    res.status(response.status).json(await response.json());
});

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

// Multi-Strategy Token Revocation System
interface RevocationConfig {
    enableDenyList: boolean;
    enableTokenVersioning: boolean;
    denyListTTL: number; // How long to keep revoked tokens in list
}
 
class TokenRevocationService {
    constructor(
        private redis: Redis,
        private db: Database,
        private config: RevocationConfig,
    ) {}
    
    // Revoke a specific token (e.g., on logout)
    async revokeToken(tokenId: string, expiresAt: Date): Promise<void> {
        if (!this.config.enableDenyList) return;
        
        // Only need to deny-list until token would naturally expire
        const ttlMs = expiresAt.getTime() - Date.now();
        if (ttlMs <= 0) return; // Already expired
        
        // Add to Redis deny list with automatic expiration
        await this.redis.set(
            `revoked:${tokenId}`,
            '1',
            'PX',
            Math.min(ttlMs, this.config.denyListTTL * 1000),
        );
    }
    
    // Revoke all tokens for a user (e.g., password change, security concern)
    async revokeAllUserTokens(userId: string): Promise<void> {
        // Strategy 1: Revoke all refresh tokens in database
        await this.db.refreshTokens.updateMany({
            where: { userId },
            data: { revokedAt: new Date() },
        });
        
        // Strategy 2: Increment user's token version
        if (this.config.enableTokenVersioning) {
            await this.db.users.update({
                where: { id: userId },
                data: { tokenVersion: { increment: 1 } },
            });
        }
        
        // Strategy 3: Publish revocation event for distributed systems
        await this.publishRevocationEvent({
            type: 'USER_TOKENS_REVOKED',
            userId,
            timestamp: new Date(),
        });
    }
    
    // Check if token is revoked (called during validation)
    async isTokenRevoked(tokenId: string, userId: string, tokenVersion?: number): Promise<boolean> {
        // Check deny list
        if (this.config.enableDenyList) {
            const revoked = await this.redis.get(`revoked:${tokenId}`);
            if (revoked) return true;
        }
        
        // Check token version
        if (this.config.enableTokenVersioning && tokenVersion !== undefined) {
            const user = await this.db.users.findUnique({
                where: { id: userId },
                select: { tokenVersion: true },
            });
            
            if (user && user.tokenVersion > tokenVersion) {
                return true; // Token from older generation
            }
        }
        
        return false;
    }
    
    // Publish revocation event for distributed systems
    private async publishRevocationEvent(event: RevocationEvent): Promise<void> {
        await this.redis.publish('token-revocation', JSON.stringify(event));
    }
}
 
// Token Validator incorporating revocation checks
class TokenValidator {
    constructor(
        private jwtVerifier: JWTVerifier,
        private revocationService: TokenRevocationService,
    ) {}
    
    async validateAccessToken(token: string): Promise<TokenPayload> {
        // Step 1: Verify JWT signature and expiration
        const payload = await this.jwtVerifier.verify(token);
        
        // Step 2: Check revocation
        const isRevoked = await this.revocationService.isTokenRevoked(
            payload.jti,     // Token ID
            payload.sub,     // User ID
            payload.version, // Token version (if present)
        );
        
        if (isRevoked) {
            throw new TokenError('invalid_token', 'Token has been revoked');
        }
        
        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

// Secure API Client with Token Transmission Best Practices
class SecureApiClient {
    private baseUrl: string;
    private tokenManager: TokenManager;
    
    constructor(baseUrl: string, tokenManager: TokenManager) {
        // Enforce HTTPS
        if (!baseUrl.startsWith('https://')) {
            throw new Error('API base URL must use HTTPS');
        }
        this.baseUrl = baseUrl;
        this.tokenManager = tokenManager;
    }
    
    async request<T>(
        method: string,
        path: string,
        options: RequestOptions = {}
    ): Promise<T> {
        const token = await this.tokenManager.getAccessToken();
        
        const headers: Record<string, string> = {
            'Authorization': `Bearer ${token}`,
            'Content-Type': 'application/json',
            // Additional security headers
            'X-Request-ID': crypto.randomUUID(), // For correlation
        };
        
        // NEVER put token in URL
        const url = new URL(path, this.baseUrl);
        
        const response = await fetch(url.toString(), {
            method,
            headers,
            body: options.body ? JSON.stringify(options.body) : undefined,
            credentials: 'omit', // Don't send cookies to API
        });
        
        if (response.status === 401) {
            // Token might be expired or revoked
            await this.tokenManager.refresh();
            return this.request(method, path, options);
        }
        
        if (!response.ok) {
            throw new ApiError(response.status, await response.text());
        }
        
        return response.json();
    }
}
 
// Express middleware to redact tokens from logs
import morgan from 'morgan';
 
// Custom morgan token that redacts Authorization header
morgan.token('headers-safe', (req) => {
    const headers = { ...req.headers };
    if (headers.authorization) {
        // Keep token type, redact actual token
        headers.authorization = headers.authorization.replace(
            /^(Bearer )(.+)$/,
            '$1[REDACTED]'
        );
    }
    return JSON.stringify(headers);
});
 
app.use(morgan(':method :url :status - :headers-safe'));