Key: user:{userId}:refresh_token
Value: {refreshToken}
TTL: 604800 (7일, 초 단위)

Key: user:{userId}:device:{deviceId}:refresh_token
Value: {refreshToken}
TTL: 604800

Signature = HMACSHA256(
  base64UrlEncode(header) + "." + base64UrlEncode(payload),
  secret
)

// config/redisClient.js
const redis = require('redis');

// Redis 클라이언트 생성 및 설정
const client = redis.createClient({
    url: `redis://${process.env.REDIS_HOST}:${process.env.REDIS_PORT}`,
    password: process.env.REDIS_PASSWORD,
    socket: {
        connectTimeout: 5000,
        // V4부터 reconnectStrategy는 더 이상 사용되지 않으며,
        // 대신 기본적으로 지수 백오프(exponential backoff) 전략이 내장되어 있습니다.
        // 커스텀 로직이 필요한 경우 'error' 이벤트와 조합하여 구현할 수 있습니다.
    }
});

// 에러 핸들링
client.on('error', (err) => {
    console.error('Redis Client Error:', err);
    // 프로덕션에서는 모니터링 시스템에 알림 전송 (예: Sentry, DataDog)
});

client.on('connect', () => {
    console.log('Redis에 성공적으로 연결되었습니다.');
});

client.on('reconnecting', () => {
    console.log('Redis 재연결 시도 중...');
});

// 연결 초기화
(async () => {
    try {
        await client.connect();
    } catch (err) {
        console.error('Redis 초기 연결 실패:', err);
        process.exit(1); // 애플리케이션 시작 실패
    }
})();

// Graceful Shutdown
process.on('SIGINT', async () => {
    await client.quit();
    console.log('Redis 연결이 정상적으로 종료되었습니다.');
    process.exit(0);
});

module.exports = client;

# docker-compose.yml
version: '3.8'
services:
  redis:
    image: redis:8-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data
    command: redis-server --appendonly yes
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 5

volumes:
  redis_data:

# .env
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=your_secure_password

ACCESS_TOKEN_SECRET=your_access_token_secret_key_256bit
REFRESH_TOKEN_SECRET=your_refresh_token_secret_key_256bit
ACCESS_TOKEN_EXPIRES_IN=15m
REFRESH_TOKEN_EXPIRES_IN=7d

// utils/tokenUtils.js
const jwt = require('jsonwebtoken');

/**
 * Access Token 생성
 */
function generateAccessToken(userId) {
    return jwt.sign(
        { id: userId, type: 'access' },
        process.env.ACCESS_TOKEN_SECRET,
        { expiresIn: process.env.ACCESS_TOKEN_EXPIRES_IN || '15m' }
    );
}

/**
 * Refresh Token 생성
 */
function generateRefreshToken(userId) {
    return jwt.sign(
        { id: userId, type: 'refresh' },
        process.env.REFRESH_TOKEN_SECRET,
        { expiresIn: process.env.REFRESH_TOKEN_EXPIRES_IN || '7d' }
    );
}

/**
 * Access Token 검증
 */
function verifyAccessToken(token) {
    try {
        return jwt.verify(token, process.env.ACCESS_TOKEN_SECRET);
    } catch (err) {
        throw new Error('Invalid or expired access token');
    }
}

/**
 * Refresh Token 검증
 */
function verifyRefreshToken(token) {
    try {
        return jwt.verify(token, process.env.REFRESH_TOKEN_SECRET);
    } catch (err) {
        throw new Error('Invalid or expired refresh token');
    }
}

module.exports = {
    generateAccessToken,
    generateRefreshToken,
    verifyAccessToken,
    verifyRefreshToken
};

// routes/auth.js
const express = require('express');
const bcrypt = require('bcrypt');
const redisClient = require('../config/redisClient');
const { generateAccessToken, generateRefreshToken } = require('../utils/tokenUtils');

const router = express.Router();

const BCRYPT_SALT_ROUNDS = 12;

/**
 * 로그인 엔드포인트
 */
router.post('/auth/login', async (req, res) => {
    try {
        const { email, password } = req.body;

        // 입력 검증
        if (!email || !password) {
            return res.status(400).json({ message: '이메일과 비밀번호를 입력해주세요.' });
        }

        // 사용자 조회 (실제로는 데이터베이스에서 조회)
        const user = await getUserByEmail(email);
        if (!user) {
            // 보안을 위해 구체적인 실패 이유를 노출하지 않음
            return res.status(401).json({ message: '인증에 실패했습니다.' });
        }

        // 비밀번호 검증
        const isPasswordValid = await bcrypt.compare(password, user.passwordHash);
        if (!isPasswordValid) {
            return res.status(401).json({ message: '인증에 실패했습니다.' });
        }

        // 토큰 생성
        const accessToken = generateAccessToken(user.id);
        const refreshToken = generateRefreshToken(user.id);

        // Redis에 Refresh Token 저장 (7일 TTL)
        const ttl = 7 * 24 * 60 * 60; // 7일을 초 단위로
        await redisClient.setEx(
            `user:${user.id}:refresh_token`,
            ttl,
            refreshToken
        );

        // Refresh Token은 HttpOnly 쿠키로 전송
        res.cookie('refreshToken', refreshToken, {
            httpOnly: true,
            secure: process.env.NODE_ENV === 'production', // HTTPS only in production
            sameSite: 'strict',
            maxAge: ttl * 1000 // 밀리초 단위
        });

        // Access Token은 응답 body로 전송
        res.json({
            accessToken,
            user: {
                id: user.id,
                email: user.email,
                name: user.name
            }
        });

    } catch (err) {
        console.error('로그인 에러:', err);
        res.status(500).json({ message: '서버 오류가 발생했습니다.' });
    }
});

/**
 * 사용자 조회 함수 (예시)
 * 실제로는 데이터베이스 쿼리로 구현
 */
async function getUserByEmail(email) {
    // 예시: PostgreSQL, MongoDB 등에서 사용자 조회
    // const user = await db.users.findOne({ email });
    // return user;
    return null; // placeholder
}

module.exports = router;

/**
 * 토큰 갱신 엔드포인트 (Refresh Token Rotation 적용)
 */
router.post('/auth/refresh', async (req, res) => {
    try {
        // 1. 쿠키에서 Refresh Token 추출
        const { refreshToken } = req.cookies;
        
        if (!refreshToken) {
            return res.status(401).json({ message: '인증이 필요합니다.' });
        }

        // 2. Refresh Token 검증 (서명 및 만료 확인)
        let decoded;
        try {
            decoded = verifyRefreshToken(refreshToken);
        } catch (err) {
            return res.status(403).json({ message: '유효하지 않은 토큰입니다.' });
        }

        const userId = decoded.id;

        // 3. Redis에 저장된 토큰과 대조
        const savedToken = await redisClient.get(`user:${userId}:refresh_token`);
        
        // 4. 토큰 불일치 시 Reuse Detection (재사용 탐지)
        if (!savedToken || savedToken !== refreshToken) {
            // 토큰이 이미 사용되었거나 탈취된 것으로 의심
            // 해당 사용자의 모든 세션 무효화 (보안 조치)
            await redisClient.del(`user:${userId}:refresh_token`);
            
            console.warn(`[보안 경고] Refresh Token 재사용 탐지 - User ID: ${userId}`);
            // 실제 프로덕션에서는 사용자에게 알림을 보내거나 추가 인증 요구
            
            return res.status(403).json({ 
                message: '보안 위협이 감지되었습니다. 다시 로그인해주세요.' 
            });
        }

        // 5. 새로운 토큰 쌍 생성 (RTR: Rotation)
        const newAccessToken = generateAccessToken(userId);
        const newRefreshToken = generateRefreshToken(userId);

        // 6. Redis에 새로운 Refresh Token 저장 (기존 토큰 덮어쓰기)
        const ttl = 7 * 24 * 60 * 60;
        await redisClient.setEx(
            `user:${userId}:refresh_token`,
            ttl,
            newRefreshToken
        );

        // 7. 새로운 Refresh Token을 쿠키로 전송
        res.cookie('refreshToken', newRefreshToken, {
            httpOnly: true,
            secure: process.env.NODE_ENV === 'production',
            sameSite: 'strict',
            maxAge: ttl * 1000
        });

        // 8. 새로운 Access Token 응답
        res.json({ 
            accessToken: newAccessToken
        });

    } catch (err) {
        console.error('토큰 갱신 에러:', err);
        res.status(500).json({ message: '서버 오류가 발생했습니다.' });
    }
});

/**
 * 로그아웃 엔드포인트
 */
router.post('/auth/logout', async (req, res) => {
    try {
        const { refreshToken } = req.cookies;
        
        if (refreshToken) {
            // Refresh Token에서 사용자 ID 추출
            try {
                const decoded = verifyRefreshToken(refreshToken);
                const userId = decoded.id;
                
                // Redis에서 Refresh Token 삭제
                await redisClient.del(`user:${userId}:refresh_token`);
            } catch (err) {
                // 토큰이 이미 만료되었거나 유효하지 않은 경우에도 계속 진행
                console.log('로그아웃 중 토큰 검증 실패 (무시):', err.message);
            }
        }

        // 쿠키 삭제
        res.clearCookie('refreshToken', {
            httpOnly: true,
            secure: process.env.NODE_ENV === 'production',
            sameSite: 'strict'
        });

        res.json({ message: '로그아웃되었습니다.' });

    } catch (err) {
        console.error('로그아웃 에러:', err);
        res.status(500).json({ message: '서버 오류가 발생했습니다.' });
    }
});

// middleware/authMiddleware.js
const { verifyAccessToken } = require('../utils/tokenUtils');

/**
 * Access Token 검증 미들웨어
 */
function authenticateToken(req, res, next) {
    // Authorization 헤더에서 토큰 추출
    const authHeader = req.headers['authorization'];
    const token = authHeader && authHeader.split(' ')[1]; // "Bearer TOKEN"

    if (!token) {
        return res.status(401).json({ message: '인증이 필요합니다.' });
    }

    try {
        // 토큰 검증
        const decoded = verifyAccessToken(token);
        req.user = decoded; // 요청 객체에 사용자 정보 추가
        next();
    } catch (err) {
        return res.status(403).json({ message: '유효하지 않은 토큰입니다.' });
    }
}

module.exports = { authenticateToken };

const { authenticateToken } = require('../middleware/authMiddleware');

// 보호된 라우트
router.get('/api/profile', authenticateToken, async (req, res) => {
    try {
        const userId = req.user.id;
        const userProfile = await getUserProfile(userId);
        res.json(userProfile);
    } catch (err) {
        res.status(500).json({ message: '서버 오류가 발생했습니다.' });
    }
});

res.cookie('refreshToken', token, {
    httpOnly: true,      // (1) XSS 방어
    secure: true,        // (2) HTTPS 전용
    sameSite: 'strict',  // (3) CSRF 방어
    maxAge: 604800000,   // (4) 7일 (밀리초)
    path: '/auth',       // (5) 경로 제한 (선택사항)
    domain: '.example.com' // (6) 도메인 제한 (선택사항)
});

// CSRF 토큰 생성 (로그인 시)
const crypto = require('crypto');
const csrfToken = crypto.randomBytes(32).toString('hex');

// 세션에 저장 (Redis 또는 서버 메모리)
await redisClient.setEx(`csrf:${userId}`, 3600, csrfToken);

// 클라이언트에 전달 (일반 쿠키 또는 응답 body)
res.cookie('csrfToken', csrfToken, {
    httpOnly: false, // JavaScript에서 읽을 수 있어야 함
    secure: true,
    sameSite: 'strict'
});

// 클라이언트는 상태 변경 요청 시 헤더에 포함
// X-CSRF-Token: {csrfToken}

// 서버에서 검증
const receivedToken = req.headers['x-csrf-token'];
const storedToken = await redisClient.get(`csrf:${userId}`);
if (receivedToken !== storedToken) {
    return res.status(403).json({ message: 'CSRF 토큰 불일치' });
}

// 연결 풀 설정 예시 (ioredis 사용)
const Redis = require('ioredis');

const redis = new Redis({
    host: process.env.REDIS_HOST,
    port: process.env.REDIS_PORT,
    password: process.env.REDIS_PASSWORD,
    maxRetriesPerRequest: 3,
    enableReadyCheck: true,
    connectTimeout: 10000,
    // 연결 풀 크기 조정
    lazyConnect: true
});

const rateLimit = require('express-rate-limit');
const { RedisStore } = require('rate-limit-redis');
const redisClient = require('../config/redisClient');

// 로그인 엔드포인트에 Rate Limit 적용
const loginLimiter = rateLimit({
    windowMs: 15 * 60 * 1000, // 15분
    max: 5, // IP당 최대 5회 시도
    message: '너무 많은 로그인 시도가 있었습니다. 나중에 다시 시도해주세요.',
    standardHeaders: true,
    legacyHeaders: false,
    // Redis 기반 스토어 사용 (분산 환경 대응)
    store: new RedisStore({
        sendCommand: (...args) => redisClient.sendCommand(args),
    })
});

router.post('/auth/login', loginLimiter, async (req, res) => {
    // 로그인 로직
});

// 토큰 갱신 엔드포인트
const refreshLimiter = rateLimit({
    windowMs: 15 * 60 * 1000,
    max: 10,
    message: '토큰 갱신 요청이 너무 많습니다.'
});

router.post('/auth/refresh', refreshLimiter, async (req, res) => {
    // 토큰 갱신 로직
});

const winston = require('winston');

const securityLogger = winston.createLogger({
    level: 'info',
    format: winston.format.json(),
    transports: [
        new winston.transports.File({ filename: 'security.log' })
    ]
});

// RTR Reuse Detection 발생 시
securityLogger.warn({
    event: 'REFRESH_TOKEN_REUSE_DETECTED',
    userId: userId,
    ip: req.ip,
    userAgent: req.headers['user-agent'],
    timestamp: new Date().toISOString()
});

// 로그인 실패 시
securityLogger.warn({
    event: 'LOGIN_FAILED',
    email: email,
    ip: req.ip,
    timestamp: new Date().toISOString()
});

const Redis = require('ioredis');

const redis = new Redis({
    sentinels: [
        { host: 'sentinel1.example.com', port: 26379 },
        { host: 'sentinel2.example.com', port: 26379 },
        { host: 'sentinel3.example.com', port: 26379 }
    ],
    name: 'mymaster',
    password: process.env.REDIS_PASSWORD
});

1. 클라이언트: 이메일/비밀번호 전송
2. 서버: 사용자 인증 (bcrypt)
3. 서버: Access Token + Refresh Token 생성
4. 서버: Refresh Token을 Redis에 저장 (TTL 7일)
5. 서버: Refresh Token을 HttpOnly 쿠키로 전송
6. 서버: Access Token을 응답 body로 전송
7. 클라이언트: Access Token을 메모리에 저장

1. 클라이언트: Authorization 헤더에 Access Token 포함
2. 서버: Access Token 검증 (서명, 만료)
3. 서버: 유효하면 요청 처리
4. 서버: 만료되었으면 401 응답
5. 클라이언트: 401 수신 시 토큰 갱신 요청

1. 클라이언트: 쿠키의 Refresh Token 자동 전송
2. 서버: Refresh Token 검증 (서명, 만료)
3. 서버: Redis의 저장된 토큰과 비교
4. 서버: 불일치 시 → 재사용 탐지 → 모든 세션 무효화
5. 서버: 일치 시 → 새로운 토큰 쌍 생성
6. 서버: 새 Refresh Token을 Redis에 저장 (기존 토큰 덮어쓰기)
7. 서버: 새 Refresh Token을 HttpOnly 쿠키로 전송
8. 서버: 새 Access Token을 응답 body로 전송
9. 클라이언트: 새 Access Token으로 원래 요청 재시도

1. 클라이언트: 로그아웃 요청
2. 서버: Refresh Token 추출 및 검증
3. 서버: Redis에서 Refresh Token 삭제
4. 서버: Refresh Token 쿠키 삭제
5. 클라이언트: 메모리의 Access Token 삭제

// Passkey 라이브러리 예시 (simplewebauthn 사용)
// routes/passkey.js

// 1. 등록 옵션 생성
router.get('/passkey/register-options', (req, res) => {
    // ... simplewebauthn 라이브러리를 사용하여 옵션 생성
});

// 2. 등록 검증
router.post('/passkey/verify-registration', (req, res) => {
    // ... 디바이스에서 받은 응답 검증 후 공개 키 저장
});

// 3. 인증 옵션 생성
router.get('/passkey/authenticate-options', (req, res) => {
    // ... 챌린지를 포함한 인증 옵션 생성
});

// 4. 인증 검증
router.post('/passkey/verify-authentication', (req, res) => {
    // ... 서명 검증 후 로그인 처리 (JWT 토큰 발급)
});