auth-security-expert

now ) throw new Error ( 'Token not yet valid' ) ; // 6. Check token revocation (if implementing revocation list) if ( await isTokenRevoked ( decoded . jti ) ) { throw new Error ( 'Token has been revoked' ) ; } // 7. Validate custom claims if ( decoded . scope && ! decoded . scope . includes ( 'read:resource' ) ) { throw new Error ( 'Insufficient permissions' ) ; } return decoded ; } catch ( error ) { // NEVER use the token if ANY validation fails console . error ( 'JWT validation failed:' , error . message ) ; throw new Error ( 'Invalid token' ) ; } } JWT Claims (RFC 7519) Registered Claims (Standard): iss (issuer): Authorization server URL - VALIDATE sub (subject): User ID (unique, immutable) - REQUIRED aud (audience): API/service identifier - VALIDATE exp (expiration): Unix timestamp - REQUIRED, ≤15 min for access tokens iat (issued at): Unix timestamp - REQUIRED nbf (not before): Unix timestamp - OPTIONAL jti (JWT ID): Unique token ID - REQUIRED for revocation Custom Claims (Application-Specific): const payload = { // Standard claims iss : 'https://auth.example.com' , sub : 'user_12345' , aud : 'api.example.com' , exp : Math . floor ( Date . now ( ) / 1000 ) + 15 * 60 , // 15 minutes iat : Math . floor ( Date . now ( ) / 1000 ) , jti : crypto . randomUUID ( ) , // Custom claims scope : 'read:profile write:profile admin:users' , role : 'admin' , tenant_id : 'tenant_789' , email : 'user@example.com' , // OK for access token, not sensitive // NEVER include: password, SSN, credit card, etc. } ; ⚠️ NEVER Store Sensitive Data in JWT: JWTs are base64-encoded, NOT encrypted (anyone can decode) Assume all JWT contents are public Use encrypted JWE (JSON Web Encryption) if you must include sensitive data Token Storage Security ✅ CORRECT: HttpOnly Cookies (Server-Side) // Server sets tokens as HttpOnly cookies after OAuth callback app . post ( '/auth/callback' , async ( req , res ) => { const { access_token , refresh_token } = await exchangeCodeForTokens ( req . body . code ) ; // Access token cookie res . cookie ( 'access_token' , access_token , { httpOnly : true , // Cannot be accessed by JavaScript (XSS protection) secure : true , // HTTPS only sameSite : 'strict' , // CSRF protection (blocks cross-site requests) maxAge : 15 * 60 * 1000 , // 15 minutes path : '/' , domain : '.example.com' , // Allow subdomains } ) ; // Refresh token cookie (more restricted) res . cookie ( 'refresh_token' , refresh_token , { httpOnly : true , secure : true , sameSite : 'strict' , maxAge : 7 * 24 * 60 * 60 * 1000 , // 7 days path : '/auth/refresh' , // ONLY accessible by refresh endpoint domain : '.example.com' , } ) ; res . json ( { success : true } ) ; } ) ; // Client makes authenticated requests (browser sends cookie automatically) fetch ( 'https://api.example.com/user/profile' , { credentials : 'include' , // Include cookies in request } ) ; ❌ WRONG: localStorage/sessionStorage // ❌ VULNERABLE TO XSS ATTACKS localStorage . setItem ( 'access_token' , token ) ; sessionStorage . setItem ( 'access_token' , token ) ; // Any XSS vulnerability (even third-party script) can steal tokens: // Why HttpOnly Cookies Prevent XSS Theft: httpOnly: true makes cookie inaccessible to JavaScript (document.cookie returns empty) Even if XSS exists, attacker cannot read the token Browser automatically includes cookie in requests (no JavaScript needed) Refresh Token Rotation with Reuse Detection The Attack: Refresh Token Theft If attacker steals refresh token, they can generate unlimited access tokens until refresh token expires (days/weeks). The Defense: Rotation + Reuse Detection Every refresh generates new refresh token and invalidates old one. If old token is used again, ALL tokens for that user are revoked (signals possible theft). Server-Side Implementation: app . post ( '/auth/refresh' , async ( req , res ) => { const oldRefreshToken = req . cookies . refresh_token ; try { // 1. Validate refresh token (check signature, expiry) const decoded = jwt . verify ( oldRefreshToken , publicKey , { algorithms : [ 'RS256' ] , issuer : 'https://auth.example.com' , } ) ; // 2. Look up token in database (we store hashed refresh tokens) const tokenHash = crypto . createHash ( 'sha256' ) . update ( oldRefreshToken ) . digest ( 'hex' ) ; const tokenRecord = await db . refreshTokens . findOne ( { tokenHash , userId : decoded . sub , } ) ; if ( ! tokenRecord ) { throw new Error ( 'Refresh token not found' ) ; } // 3. CRITICAL: Detect token reuse (possible theft) if ( tokenRecord . isUsed ) { // Token was already used - this is a REUSE ATTACK await db . refreshTokens . deleteMany ( { userId : decoded . sub } ) ; // Revoke ALL tokens await logSecurityEvent ( 'REFRESH_TOKEN_REUSE_DETECTED' , { userId : decoded . sub , tokenId : decoded . jti , ip : req . ip , userAgent : req . headers [ 'user-agent' ] , } ) ; // Send alert to user's email await sendSecurityAlert ( decoded . sub , 'Token theft detected - all sessions terminated' ) ; return res . status ( 401 ) . json ( { error : 'token_reuse' , error_description : 'Refresh token reuse detected - all sessions revoked' , } ) ; } // 4. Mark old token as used (ATOMIC operation before issuing new tokens) await db . refreshTokens . updateOne ( { tokenHash } , { $set : { isUsed : true , lastUsedAt : new Date ( ) } , } ) ; // 5. Generate new tokens const newAccessToken = jwt . sign ( { sub : decoded . sub , scope : decoded . scope , exp : Math . floor ( Date . now ( ) / 1000 ) + 15 * 60 , } , privateKey , { algorithm : 'RS256' } ) ; const newRefreshToken = jwt . sign ( { sub : decoded . sub , scope : decoded . scope , exp : Math . floor ( Date . now ( ) / 1000 ) + 7 * 24 * 60 * 60 , // 7 days jti : crypto . randomUUID ( ) , } , privateKey , { algorithm : 'RS256' } ) ; // 6. Store new refresh token (hashed) const newTokenHash = crypto . createHash ( 'sha256' ) . update ( newRefreshToken ) . digest ( 'hex' ) ; await db . refreshTokens . create ( { userId : decoded . sub , tokenHash : newTokenHash , isUsed : false , expiresAt : new Date ( Date . now ( ) + 7 * 24 * 60 * 60 * 1000 ) , createdAt : new Date ( ) , userAgent : req . headers [ 'user-agent' ] , ipAddress : req . ip , } ) ; // 7. Set new tokens as cookies res . cookie ( 'access_token' , newAccessToken , { httpOnly : true , secure : true , sameSite : 'strict' , maxAge : 15 * 60 * 1000 , } ) ; res . cookie ( 'refresh_token' , newRefreshToken , { httpOnly : true , secure : true , sameSite : 'strict' , maxAge : 7 * 24 * 60 * 60 * 1000 , path : '/auth/refresh' , } ) ; res . json ( { success : true } ) ; } catch ( error ) { // Clear invalid cookies res . clearCookie ( 'refresh_token' ) ; res . status ( 401 ) . json ( { error : 'invalid_token' } ) ; } } ) ; Database Schema (Refresh Tokens): { userId : 'user_12345' , tokenHash : 'sha256_hash_of_refresh_token' , // NEVER store plaintext isUsed : false , // Set to true when token is used for refresh expiresAt : ISODate ( '2026-02-01T00:00:00Z' ) , createdAt : ISODate ( '2026-01-25T00:00:00Z' ) , lastUsedAt : null , // Updated when isUsed set to true userAgent : 'Mozilla/5.0...' , ipAddress : '192.168.1.1' , jti : 'uuid-v4' , // Matches JWT 'jti' claim } Password Hashing (2026 Best Practices) Recommended: Argon2id Winner of Password Hashing Competition (2015) Resistant to both GPU cracking and side-channel attacks Configurable memory, time, and parallelism parameters // Argon2id example (Node.js) import argon2 from 'argon2' ; // Hash password const hash = await argon2 . hash ( password , { type : argon2 . argon2id , memoryCost : 19456 , // 19 MiB timeCost : 2 , parallelism : 1 , } ) ; // Verify password const isValid = await argon2 . verify ( hash , password ) ; Acceptable Alternative: bcrypt Still secure but slower than Argon2id for same security level Work factor: minimum 12 (recommended 14+ in 2026) // bcrypt example import bcrypt from 'bcryptjs' ; const hash = await bcrypt . hash ( password , 14 ) ; // Cost factor 14 const isValid = await bcrypt . compare ( password , hash ) ; NEVER use: MD5, SHA-1, SHA-256 alone (not designed for passwords) Plain text storage Reversible encryption Multi-Factor Authentication (MFA) Types of MFA: TOTP (Time-based One-Time Passwords) Apps: Google Authenticator, Authy, 1Password 6-digit codes that rotate every 30 seconds Offline-capable WebAuthn/FIDO2 (Passkeys) Most secure option (phishing-resistant) Hardware tokens (YubiKey) or platform authenticators (Face ID, Touch ID) Public key cryptography, no shared secrets SMS-based (Legacy - NOT recommended) Vulnerable to SIM swapping attacks Use only as fallback, never as primary MFA Backup Codes Provide one-time recovery codes during MFA enrollment Store securely (hashed in database) Implementation Best Practices: Allow multiple MFA methods per user Enforce MFA for admin/privileged accounts Provide clear enrollment and recovery flows Never bypass MFA without proper verification Passkeys / WebAuthn Why Passkeys: Phishing-resistant (cryptographic binding to origin) No shared secrets to leak or intercept Passwordless authentication Synced across devices (Apple, Google, Microsoft ecosystems) Implementation: Use @simplewebauthn/server (Node.js) or similar libraries Support both platform authenticators (biometrics) and roaming authenticators (security keys) Provide fallback authentication method during transition WebAuthn Registration Flow: Server generates challenge Client creates credential with authenticator Client sends public key to server Server stores public key associated with user account WebAuthn Authentication Flow: Server generates challenge Client signs challenge with private key (stored in authenticator) Server verifies signature with stored public key Session Management Secure Session Practices: Use secure, HTTP-only cookies for session tokens Set-Cookie: session=...; Secure; HttpOnly; SameSite=Strict Implement absolute timeout (e.g., 24 hours) Implement idle timeout (e.g., 30 minutes of inactivity) Regenerate session ID after login (prevent session fixation) Provide "logout all devices" functionality Session Storage: Server-side session store (Redis, database) Don't store sensitive data in client-side storage Implement session revocation on password change Security Headers Essential HTTP Security Headers: Strict-Transport-Security: max-age=31536000; includeSubDomains (HSTS) X-Content-Type-Options: nosniff X-Frame-Options: DENY or SAMEORIGIN Content-Security-Policy: default-src 'self' X-XSS-Protection: 1; mode=block (legacy support) Common Vulnerabilities to Prevent Injection Attacks: Use parameterized queries (SQL injection prevention) Validate and sanitize all user input Use ORMs with built-in protection Cross-Site Scripting (XSS): Escape output in templates Use Content Security Policy headers Never use eval() or innerHTML with user input Cross-Site Request Forgery (CSRF): Use CSRF tokens for state-changing operations Verify origin/referer headers Use SameSite cookie attribute Broken Authentication: Enforce strong password policies Implement account lockout after failed attempts Use MFA for sensitive operations Never expose user enumeration (same error for "user not found" and "invalid password") Consolidated Skills This expert skill consolidates 1 individual skills: auth-security-expert