@ahhaohho/auth-middleware 1.0.8 → 2.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ahhaohho/auth-middleware",
-  "version": "1.0.8",
-  "description": "Shared authentication middleware with Passport.js for ahhaohho microservices",
+  "version": "2.0.0",
+  "description": "Shared authentication and authorization middleware for ahhaohho microservices",
   "main": "src/index.js",
   "scripts": {
     "test": "echo \"Warning: no test specified\" && exit 0",
@@ -22,6 +22,9 @@
     "passport",
     "jwt",
     "authentication",
+    "authorization",
+    "rbac",
+    "api-key",
     "middleware",
     "ahhaohho"
   ],

package/src/index.js

@@ -1,36 +1,79 @@
 /**
  * @ahhaohho/auth-middleware
  *
- * Shared authentication middleware with Passport.js
+ * Shared authentication and authorization middleware
  * for ahhaohho microservices
+ *
+ * @version 2.0.0
  */
 
+// JWT 인증 미들웨어
 const { authenticateJWT, authenticateRefresh, optionalAuth, authenticateHybrid } = require('./middleware/auth');
+
+// API 키 인증 미들웨어
+const { authenticateApiKey, optionalApiKey, combinedAuth, combinedAuthHybrid } = require('./middleware/apiKey');
+
+// 역할/권한 인가 미들웨어
+const {
+  requireRoles,
+  requirePermission,
+  requireAccess,
+  requireOwnership,
+  requireAny,
+  clearPermissionCache,
+  fetchRolePermissions
+} = require('./middleware/authorization');
+
+// 유틸리티
 const { verifyTokenWithFallback, signToken, getCurrentSigningKey } = require('./utils/jwtValidator');
 const { isBlacklisted, addToBlacklist, clearBlacklist } = require('./utils/blacklist');
 const { getJwtKeys, invalidateCache } = require('./utils/secretManager');
+const { verifyApiKey, getApiKeyTTL } = require('./utils/apiKeyValidator');
 const redisManager = require('./config/redis');
 
-// 메인 export - Express 미들웨어
 module.exports = {
-  // 미들웨어
-  authenticateJWT,
-  authenticateRefresh,
-  optionalAuth,
-  authenticateHybrid,
+  // ===== JWT 인증 미들웨어 =====
+  authenticateJWT,       // JWT Access Token 필수 인증
+  authenticateRefresh,   // Refresh Token 인증
+  optionalAuth,          // JWT 선택적 인증 (없어도 통과)
+  authenticateHybrid,    // JWT + Refresh Token 자동 갱신
+
+  // ===== API 키 인증 미들웨어 =====
+  authenticateApiKey,    // API 키 필수 인증
+  optionalApiKey,        // API 키 선택적 인증
+  combinedAuth,          // API 키 + JWT 복합 인증
+  combinedAuthHybrid,    // API 키 + JWT Hybrid 복합 인증
+
+  // ===== 역할/권한 인가 미들웨어 =====
+  requireRoles,          // 역할 기반 인가: requireRoles(['admin', 'teacher'])
+  requirePermission,     // 권한 기반 인가: requirePermission('content:write')
+  requireAccess,         // 접근 범위 기반 인가: requireAccess('AdminPanel')
+  requireOwnership,      // 리소스 소유자 검증: requireOwnership('userId')
+  requireAny,            // 복합 조건 인가: requireAny({ roles: [...], permissions: [...] })
 
-  // 유틸리티 함수 (필요시 직접 사용)
+  // ===== 유틸리티 함수 =====
   utils: {
+    // JWT 관련
     verifyTokenWithFallback,
     signToken,
     getCurrentSigningKey,
+    getJwtKeys,
+    invalidateCache,
+
+    // 블랙리스트 관련
     isBlacklisted,
     addToBlacklist,
     clearBlacklist,
-    getJwtKeys,
-    invalidateCache
+
+    // API 키 관련
+    verifyApiKey,
+    getApiKeyTTL,
+
+    // 권한 캐시 관련
+    clearPermissionCache,
+    fetchRolePermissions
   },
 
-  // Redis 관리자 (필요시 직접 접근)
+  // Redis 관리자
   redisManager
 };

package/src/middleware/apiKey.js

@@ -0,0 +1,196 @@
+const { verifyApiKey } = require('../utils/apiKeyValidator');
+
+/**
+ * API 키 인증 미들웨어
+ * Redis에서 로컬 검증 수행
+ */
+
+/**
+ * API 키 필수 인증 미들웨어
+ * x-api-key와 device-id 헤더가 필수
+ *
+ * @example
+ * router.post('/internal', authenticateApiKey, handler);
+ */
+async function authenticateApiKey(req, res, next) {
+  const apiKey = req.headers['x-api-key'];
+  const deviceId = req.headers['device-id'];
+
+  if (!apiKey || !deviceId) {
+    return res.status(401).json({
+      type: 'client',
+      error: 'Unauthorized',
+      message: 'API key and device ID are required'
+    });
+  }
+
+  const result = await verifyApiKey(deviceId, apiKey);
+
+  if (!result.valid) {
+    return res.status(401).json({
+      type: 'client',
+      error: 'Unauthorized',
+      message: result.error || 'Invalid API key'
+    });
+  }
+
+  // 인증 성공: 플래그 및 정보 설정
+  req.apiKeyVerified = true;
+  req.skipAuthorization = true;  // 하위 호환성
+  req.deviceId = deviceId;
+
+  console.log('[@ahhaohho/auth-middleware] API key verified for device:', deviceId);
+  next();
+}
+
+/**
+ * API 키 선택적 인증 미들웨어
+ * API 키가 없어도 통과, 있으면 검증
+ *
+ * @example
+ * router.get('/public', optionalApiKey, handler);
+ */
+async function optionalApiKey(req, res, next) {
+  const apiKey = req.headers['x-api-key'];
+  const deviceId = req.headers['device-id'];
+
+  if (!apiKey || !deviceId) {
+    return next();
+  }
+
+  const result = await verifyApiKey(deviceId, apiKey);
+
+  if (result.valid) {
+    req.apiKeyVerified = true;
+    req.skipAuthorization = true;
+    req.deviceId = deviceId;
+    console.log('[@ahhaohho/auth-middleware] Optional API key verified for device:', deviceId);
+  }
+
+  next();
+}
+
+/**
+ * API 키 + JWT 복합 인증 미들웨어
+ * API 키 먼저 시도, 실패하면 JWT로 fallback
+ *
+ * @example
+ * router.get('/resource', combinedAuth, handler);
+ */
+async function combinedAuth(req, res, next) {
+  const apiKey = req.headers['x-api-key'];
+  const deviceId = req.headers['device-id'];
+
+  // 1. API 키가 있으면 먼저 시도
+  if (apiKey && deviceId) {
+    const result = await verifyApiKey(deviceId, apiKey);
+
+    if (result.valid) {
+      req.apiKeyVerified = true;
+      req.skipAuthorization = true;
+      req.deviceId = deviceId;
+
+      // 하위 호환성: req.userId, req.userRole 설정
+      req.userId = null;
+      req.userRole = 'api_client';
+
+      console.log('[@ahhaohho/auth-middleware] Combined auth: API key verified');
+      return next();
+    }
+
+    console.log('[@ahhaohho/auth-middleware] Combined auth: API key failed, trying JWT...');
+  }
+
+  // 2. JWT 인증으로 fallback
+  const { authenticateJWT } = require('./auth');
+
+  authenticateJWT(req, res, (err) => {
+    if (err) {
+      return res.status(401).json({
+        type: 'client',
+        error: 'Unauthorized',
+        message: 'No valid authentication provided'
+      });
+    }
+
+    // JWT 인증 실패 (req.user가 없음)
+    if (!req.user) {
+      return res.status(401).json({
+        type: 'client',
+        error: 'Unauthorized',
+        message: 'No valid authentication provided'
+      });
+    }
+
+    // 하위 호환성: req.userId, req.userRole 설정
+    req.userId = req.user.userId;
+    req.userRole = req.user.userRole;
+
+    next();
+  });
+}
+
+/**
+ * API 키 + JWT Hybrid 인증 미들웨어
+ * API 키 먼저 시도, 실패하면 JWT Hybrid(자동 갱신)로 fallback
+ *
+ * @example
+ * router.get('/resource', combinedAuthHybrid, handler);
+ */
+async function combinedAuthHybrid(req, res, next) {
+  const apiKey = req.headers['x-api-key'];
+  const deviceId = req.headers['device-id'];
+
+  // 1. API 키가 있으면 먼저 시도
+  if (apiKey && deviceId) {
+    const result = await verifyApiKey(deviceId, apiKey);
+
+    if (result.valid) {
+      req.apiKeyVerified = true;
+      req.skipAuthorization = true;
+      req.deviceId = deviceId;
+
+      req.userId = null;
+      req.userRole = 'api_client';
+
+      console.log('[@ahhaohho/auth-middleware] Combined hybrid auth: API key verified');
+      return next();
+    }
+
+    console.log('[@ahhaohho/auth-middleware] Combined hybrid auth: API key failed, trying JWT hybrid...');
+  }
+
+  // 2. JWT Hybrid 인증으로 fallback (자동 토큰 갱신)
+  const { authenticateHybrid } = require('./auth');
+
+  authenticateHybrid(req, res, (err) => {
+    if (err) {
+      return res.status(401).json({
+        type: 'client',
+        error: 'Unauthorized',
+        message: 'No valid authentication provided'
+      });
+    }
+
+    if (!req.user) {
+      return res.status(401).json({
+        type: 'client',
+        error: 'Unauthorized',
+        message: 'No valid authentication provided'
+      });
+    }
+
+    // 하위 호환성
+    req.userId = req.user.userId;
+    req.userRole = req.user.userRole;
+
+    next();
+  });
+}
+
+module.exports = {
+  authenticateApiKey,
+  optionalApiKey,
+  combinedAuth,
+  combinedAuthHybrid
+};

package/src/middleware/auth.js

@@ -52,6 +52,11 @@ function authenticateJWT(req, res, next) {
 
     // req.user에 사용자 정보 주입
     req.user = user;
+
+    // 하위 호환성: req.userId, req.userRole 설정
+    req.userId = user.userId;
+    req.userRole = user.userRole;
+
     next();
   })(req, res, next);
 }
@@ -85,6 +90,11 @@ function authenticateRefresh(req, res, next) {
     }
 
     req.user = user;
+
+    // 하위 호환성: req.userId, req.userRole 설정
+    req.userId = user.userId;
+    req.userRole = user.userRole;
+
     next();
   })(req, res, next);
 }
@@ -109,6 +119,10 @@ function optionalAuth(req, res, next) {
     // 에러나 인증 실패해도 통과
     if (user) {
       req.user = user;
+
+      // 하위 호환성: req.userId, req.userRole 설정
+      req.userId = user.userId;
+      req.userRole = user.userRole;
     }
     next();
   })(req, res, next);
@@ -144,6 +158,11 @@ async function authenticateHybrid(req, res, next) {
     // Access token이 유효한 경우
     if (user) {
       req.user = user;
+
+      // 하위 호환성: req.userId, req.userRole 설정
+      req.userId = user.userId;
+      req.userRole = user.userRole;
+
       return next();
     }
 
@@ -197,6 +216,11 @@ async function authenticateHybrid(req, res, next) {
 
         // 6. req.user 설정하고 계속 진행
         req.user = refreshUser;
+
+        // 하위 호환성: req.userId, req.userRole 설정
+        req.userId = refreshUser.userId;
+        req.userRole = refreshUser.userRole;
+
         next();
       } catch (tokenError) {
         console.error('[@ahhaohho/auth-middleware] Failed to generate new token:', tokenError.message);

package/src/middleware/authorization.js

@@ -0,0 +1,348 @@
+const redisManager = require('../config/redis');
+
+/**
+ * 역할/권한 기반 인가 미들웨어
+ */
+
+// 권한 캐시 (메모리, 5분 TTL)
+let permissionCache = {};
+const CACHE_TTL = 5 * 60 * 1000;
+
+/**
+ * 역할 권한 정보 조회 (캐시 포함)
+ * @param {string} role - 역할 이름
+ * @returns {Promise<{access: string[], permissions: string[]} | null>}
+ */
+async function fetchRolePermissions(role) {
+  const cacheKey = `role:${role}`;
+  const cached = permissionCache[cacheKey];
+
+  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
+    return cached.data;
+  }
+
+  try {
+    const redis = redisManager.getClient('default');
+    const roleDataStr = await redis.get(`role_permissions:${role}`);
+
+    if (roleDataStr) {
+      const roleData = JSON.parse(roleDataStr);
+      permissionCache[cacheKey] = {
+        data: roleData,
+        timestamp: Date.now()
+      };
+      return roleData;
+    }
+
+    return null;
+  } catch (error) {
+    console.error('[@ahhaohho/auth-middleware] Failed to fetch role permissions:', error.message);
+    return null;
+  }
+}
+
+/**
+ * 권한 캐시 초기화
+ */
+function clearPermissionCache() {
+  permissionCache = {};
+  console.log('[@ahhaohho/auth-middleware] Permission cache cleared');
+}
+
+/**
+ * 역할 기반 인가 미들웨어
+ * 사용자가 지정된 역할 중 하나를 가지고 있는지 확인
+ *
+ * @param {string[]} allowedRoles - 허용된 역할 배열
+ * @returns {Function} Express 미들웨어
+ *
+ * @example
+ * router.post('/admin', authenticateJWT, requireRoles(['admin']), handler);
+ * router.get('/content', combinedAuth, requireRoles(['admin', 'teacher', 'user']), handler);
+ */
+function requireRoles(allowedRoles) {
+  return async (req, res, next) => {
+    // API 키 인증인 경우 스킵
+    if (req.skipAuthorization || req.apiKeyVerified) {
+      return next();
+    }
+
+    // 사용자 역할 확인 (req.user 또는 req.userRole)
+    const userRole = req.user?.userRole || req.userRole;
+
+    if (!userRole) {
+      return res.status(403).json({
+        type: 'client',
+        error: 'Forbidden',
+        message: 'No role information found'
+      });
+    }
+
+    if (!allowedRoles.includes(userRole)) {
+      return res.status(403).json({
+        type: 'client',
+        error: 'Forbidden',
+        message: `Role '${userRole}' is not authorized. Required: ${allowedRoles.join(', ')}`
+      });
+    }
+
+    next();
+  };
+}
+
+/**
+ * 권한 기반 인가 미들웨어
+ * 사용자가 특정 권한을 가지고 있는지 확인
+ *
+ * @param {string} requiredPermission - 필요한 권한 (예: 'challenge:content:write')
+ * @returns {Function} Express 미들웨어
+ *
+ * @example
+ * router.delete('/post/:id', combinedAuth, requirePermission('community:post:delete'), handler);
+ */
+function requirePermission(requiredPermission) {
+  return async (req, res, next) => {
+    // API 키 인증인 경우 스킵
+    if (req.skipAuthorization || req.apiKeyVerified) {
+      return next();
+    }
+
+    const userRole = req.user?.userRole || req.userRole;
+
+    if (!userRole) {
+      return res.status(403).json({
+        type: 'client',
+        error: 'Forbidden',
+        message: 'No role information found'
+      });
+    }
+
+    // 1. 토큰에 권한이 포함되어 있는지 확인
+    const tokenPermissions = req.user?.permissions;
+    if (tokenPermissions && Array.isArray(tokenPermissions)) {
+      if (tokenPermissions.includes('*') || tokenPermissions.includes(requiredPermission)) {
+        return next();
+      }
+
+      // 와일드카드 매칭 (예: 'challenge:*' → 'challenge:content:write' 허용)
+      const hasWildcardMatch = tokenPermissions.some(perm => {
+        if (perm.endsWith(':*')) {
+          const prefix = perm.slice(0, -1);
+          return requiredPermission.startsWith(prefix);
+        }
+        return false;
+      });
+
+      if (hasWildcardMatch) {
+        return next();
+      }
+    }
+
+    // 2. 캐시/Redis에서 역할 권한 조회
+    const roleData = await fetchRolePermissions(userRole);
+
+    if (roleData && roleData.permissions) {
+      const permissions = roleData.permissions;
+
+      if (permissions.includes('*') || permissions.includes(requiredPermission)) {
+        return next();
+      }
+
+      // 와일드카드 매칭
+      const hasWildcardMatch = permissions.some(perm => {
+        if (perm.endsWith(':*')) {
+          const prefix = perm.slice(0, -1);
+          return requiredPermission.startsWith(prefix);
+        }
+        return false;
+      });
+
+      if (hasWildcardMatch) {
+        return next();
+      }
+    }
+
+    return res.status(403).json({
+      type: 'client',
+      error: 'Forbidden',
+      message: `Permission '${requiredPermission}' is required`
+    });
+  };
+}
+
+/**
+ * 접근 범위 기반 인가 미들웨어
+ * 사용자 역할이 특정 접근 범위를 가지고 있는지 확인
+ *
+ * @param {string} requiredAccess - 필요한 접근 범위 (예: 'Content', 'AdminPanel')
+ * @returns {Function} Express 미들웨어
+ *
+ * @example
+ * router.get('/admin/dashboard', combinedAuth, requireAccess('AdminPanel'), handler);
+ */
+function requireAccess(requiredAccess) {
+  return async (req, res, next) => {
+    // API 키 인증인 경우 스킵
+    if (req.skipAuthorization || req.apiKeyVerified) {
+      return next();
+    }
+
+    const userRole = req.user?.userRole || req.userRole;
+
+    if (!userRole) {
+      return res.status(403).json({
+        type: 'client',
+        error: 'Forbidden',
+        message: 'No role information found'
+      });
+    }
+
+    const roleData = await fetchRolePermissions(userRole);
+
+    if (!roleData || !roleData.access) {
+      return res.status(403).json({
+        type: 'client',
+        error: 'Forbidden',
+        message: 'Failed to verify access'
+      });
+    }
+
+    if (!roleData.access.includes('*') && !roleData.access.includes(requiredAccess)) {
+      return res.status(403).json({
+        type: 'client',
+        error: 'Forbidden',
+        message: `Access to '${requiredAccess}' is required`
+      });
+    }
+
+    next();
+  };
+}
+
+/**
+ * 리소스 소유자 검증 미들웨어
+ * 사용자가 자신의 리소스에만 접근할 수 있도록 제한
+ * admin 역할은 모든 리소스 접근 가능
+ *
+ * @param {string} paramName - 라우트 파라미터 이름 (기본값: 'userId')
+ * @returns {Function} Express 미들웨어
+ *
+ * @example
+ * router.get('/users/:userId/profile', combinedAuth, requireOwnership('userId'), handler);
+ * router.delete('/posts/:postUserId', combinedAuth, requireOwnership('postUserId'), handler);
+ */
+function requireOwnership(paramName = 'userId') {
+  return (req, res, next) => {
+    // API 키 인증인 경우 스킵
+    if (req.skipAuthorization || req.apiKeyVerified) {
+      return next();
+    }
+
+    const userId = req.user?.userId || req.userId;
+    const resourceOwnerId = req.params[paramName];
+
+    // admin은 모든 리소스 접근 가능
+    const userRole = req.user?.userRole || req.userRole;
+    if (userRole === 'admin') {
+      return next();
+    }
+
+    if (!userId) {
+      return res.status(403).json({
+        type: 'client',
+        error: 'Forbidden',
+        message: 'User ID not found'
+      });
+    }
+
+    if (userId !== resourceOwnerId) {
+      return res.status(403).json({
+        type: 'client',
+        error: 'Forbidden',
+        message: 'You can only access your own resources'
+      });
+    }
+
+    next();
+  };
+}
+
+/**
+ * 복합 권한 검증 미들웨어
+ * 여러 조건 중 하나라도 만족하면 통과
+ *
+ * @param {Object} options - 권한 옵션
+ * @param {string[]} [options.roles] - 허용된 역할 배열
+ * @param {string[]} [options.permissions] - 필요한 권한 중 하나
+ * @param {string[]} [options.access] - 필요한 접근 범위 중 하나
+ * @returns {Function} Express 미들웨어
+ *
+ * @example
+ * router.put('/content/:id', combinedAuth, requireAny({
+ *   roles: ['admin'],
+ *   permissions: ['content:write:any']
+ * }), handler);
+ */
+function requireAny(options = {}) {
+  return async (req, res, next) => {
+    // API 키 인증인 경우 스킵
+    if (req.skipAuthorization || req.apiKeyVerified) {
+      return next();
+    }
+
+    const userRole = req.user?.userRole || req.userRole;
+
+    if (!userRole) {
+      return res.status(403).json({
+        type: 'client',
+        error: 'Forbidden',
+        message: 'No role information found'
+      });
+    }
+
+    // 1. 역할 확인
+    if (options.roles && options.roles.includes(userRole)) {
+      return next();
+    }
+
+    // 역할 권한 데이터 조회
+    const roleData = await fetchRolePermissions(userRole);
+    const tokenPermissions = req.user?.permissions || [];
+    const allPermissions = roleData?.permissions || [];
+    const allAccess = roleData?.access || [];
+
+    // 2. 권한 확인
+    if (options.permissions) {
+      for (const perm of options.permissions) {
+        if (tokenPermissions.includes(perm) || allPermissions.includes(perm) || allPermissions.includes('*')) {
+          return next();
+        }
+      }
+    }
+
+    // 3. 접근 범위 확인
+    if (options.access) {
+      for (const acc of options.access) {
+        if (allAccess.includes(acc) || allAccess.includes('*')) {
+          return next();
+        }
+      }
+    }
+
+    return res.status(403).json({
+      type: 'client',
+      error: 'Forbidden',
+      message: 'Insufficient permissions'
+    });
+  };
+}
+
+module.exports = {
+  requireRoles,
+  requirePermission,
+  requireAccess,
+  requireOwnership,
+  requireAny,
+  clearPermissionCache,
+  fetchRolePermissions
+};

package/src/utils/apiKeyValidator.js

@@ -0,0 +1,71 @@
+const redisManager = require('../config/redis');
+
+/**
+ * API 키 검증 유틸리티
+ * Redis에 저장된 API 키와 비교하여 검증
+ */
+
+/**
+ * API 키 검증
+ * @param {string} deviceId - 디바이스 ID (Redis 키)
+ * @param {string} apiKey - 검증할 API 키
+ * @returns {Promise<{valid: boolean, deviceId?: string, error?: string}>}
+ */
+async function verifyApiKey(deviceId, apiKey) {
+  if (!deviceId || !apiKey) {
+    return {
+      valid: false,
+      error: 'Device ID and API key are required'
+    };
+  }
+
+  try {
+    const redis = redisManager.getClient('apikey');
+    const storedKey = await redis.get(deviceId);
+
+    if (!storedKey) {
+      return {
+        valid: false,
+        error: 'API key not found or expired'
+      };
+    }
+
+    if (apiKey !== storedKey) {
+      return {
+        valid: false,
+        error: 'Invalid API key'
+      };
+    }
+
+    return {
+      valid: true,
+      deviceId: deviceId
+    };
+  } catch (error) {
+    console.error('[@ahhaohho/auth-middleware] API key verification error:', error.message);
+    return {
+      valid: false,
+      error: 'API key verification failed'
+    };
+  }
+}
+
+/**
+ * API 키 TTL 확인
+ * @param {string} deviceId - 디바이스 ID
+ * @returns {Promise<number>} TTL in seconds (-1 if no expiry, -2 if not exists)
+ */
+async function getApiKeyTTL(deviceId) {
+  try {
+    const redis = redisManager.getClient('apikey');
+    return await redis.ttl(deviceId);
+  } catch (error) {
+    console.error('[@ahhaohho/auth-middleware] API key TTL check error:', error.message);
+    return -2;
+  }
+}
+
+module.exports = {
+  verifyApiKey,
+  getApiKeyTTL
+};