# ============================================================================= # 企微IT智能服务台 — 高危操作守卫服务 # ============================================================================= # 说明：集中处理高危操作（Phase 1.3 task #19）的 OTP 验证状态管理 # 决策来源：otm-secondary-auth.md（2026-06-21 决策） # # 核心职责： # 1. 标记管理员 OTP 验证通过（write） # 2. 查询管理员 OTP 验证状态（read） # 3. 撤销管理员 OTP 验证（revoke） # 4. 列出全部 5 类高危操作白名单（白名单查询） # # Redis key 设计： # key: mfa:verified:{employee_id} # value: 验证方式（"totp" / "sms_backup"）+ 时间戳 # TTL: 1800 秒（30 分钟） # # 与 dependencies.py 中 require_high_risk_otp 配套使用： # - mfa.py 在 /api/mfa/verify 成功后调 mark_verified(...) # - require_high_risk_otp 在每个高危端点 Depends 时调 is_verified(...) # ============================================================================= import json import logging from datetime import datetime from typing import Dict, List, Optional import redis.asyncio as aioredis logger = logging.getLogger(__name__) # ----------------------------------------------------------------------------- # 5 类高危操作白名单（与 dependencies.HIGH_RISK_OPERATIONS 保持一致） # ----------------------------------------------------------------------------- # 注意:这里再做一次定义是为了让 service 层独立可测,不依赖 dependencies 模块 # （避免循环引用 + 方便单测） # ----------------------------------------------------------------------------- HIGH_RISK_OPERATIONS_WHITELIST: Dict[str, Dict] = { "role_change": { "category": "改权限", "require_otp": True, "examples": ["POST /api/admin/roles/assign", "POST /api/admin/roles/revoke"], "description": "分配或撤销用户角色", }, "config_change": { "category": "改配置", "require_otp": True, "examples": ["PUT /api/admin/configs/{key}"], "description": "修改系统配置项", }, "data_export": { "category": "导出数据", "require_otp": True, "examples": ["GET /api/admin/export/*"], "description": "导出敏感数据（会话、坐席统计等）", }, "account_disable": { "category": "封号", "require_otp": True, "examples": ["DELETE /api/admin/agents/{id}"], "description": "禁用/删除坐席账号", }, "account_create_reset": { "category": "新增账号/重置", "require_otp": True, "examples": ["POST /api/admin/agents", "POST /api/admin/mfa/reset/{id}"], "description": "新增坐席或重置 MFA", }, } class HighRiskGuard: """高危操作守卫服务。 负责 OTP 验证状态的读写，配套 require_high_risk_otp 依赖使用。 Attributes: redis_client: Redis 异步客户端 ttl_seconds: OTP 验证有效期（默认 1800 秒 = 30 分钟） """ # Redis key 前缀 — 必须与 dependencies.MFA_VERIFIED_KEY_PREFIX 一致 KEY_PREFIX = "mfa:verified:" # 默认 30 分钟 TTL — 必须与 dependencies.MFA_VERIFIED_TTL_SECONDS 一致 DEFAULT_TTL_SECONDS = 30 * 60 def __init__( self, redis_client: aioredis.Redis, ttl_seconds: int = DEFAULT_TTL_SECONDS, ): """初始化高危操作守卫。 Args: redis_client: Redis 异步客户端 ttl_seconds: OTP 验证有效期（秒），默认 30 分钟 """ self.redis = redis_client self.ttl_seconds = ttl_seconds def _key(self, employee_id: str) -> str: """构造 Redis key。 Args: employee_id: 企微 UserID Returns: str: Redis key，如 mfa:verified:admin001 """ return f"{self.KEY_PREFIX}{employee_id}" async def mark_verified( self, employee_id: str, method: str = "totp", ) -> bool: """标记管理员已通过 OTP 验证。 由 mfa.py 在 /api/mfa/verify 成功后调用。 Args: employee_id: 企微 UserID method: 验证方式，"totp" 或 "sms_backup" Returns: bool: 是否成功写入 """ # value 用 JSON 存验证方式和时间,审计用 value = json.dumps( { "method": method, "verified_at": datetime.now().isoformat(), }, ensure_ascii=False, ) try: await self.redis.setex( self._key(employee_id), self.ttl_seconds, value, ) logger.info( f"管理员 {employee_id} OTP 验证通过: method={method}, " f"ttl={self.ttl_seconds}s" ) return True except Exception as e: logger.error(f"写入 OTP verified key 失败: {e}") return False async def is_verified(self, employee_id: str) -> bool: """检查管理员是否在有效期内通过过 OTP。 由 require_high_risk_otp 依赖调用。 Args: employee_id: 企微 UserID Returns: bool: 是否已通过 OTP 验证 """ try: value = await self.redis.get(self._key(employee_id)) # 空字符串 / None / 空 bytes 全部算"未通过" if not value: return False return True except Exception as e: logger.error(f"读取 OTP verified key 失败: {e}") # Redis 故障时保守放行?不,安全优先,默认不通过 return False async def get_verification_info( self, employee_id: str, ) -> Optional[Dict]: """获取管理员 OTP 验证详情（含方式和时间）。 用于审计/前端展示"上次验证时间"。 Args: employee_id: 企微 UserID Returns: Optional[Dict]: 验证信息 dict，未验证返回 None 示例: {"method": "totp", "verified_at": "2026-06-21T15:30:00"} """ try: value = await self.redis.get(self._key(employee_id)) if not value: return None if isinstance(value, bytes): value = value.decode("utf-8") return json.loads(value) except Exception as e: logger.error(f"解析 OTP verified info 失败: {e}") return None async def revoke(self, employee_id: str) -> bool: """撤销管理员 OTP 验证（强制重新验证）。 场景:安全事件触发 / 管理员主动撤销 / 登出时清理。 Args: employee_id: 企微 UserID Returns: bool: 是否成功撤销（key 不存在也算成功） """ try: deleted = await self.redis.delete(self._key(employee_id)) logger.info( f"管理员 {employee_id} OTP 验证已撤销: deleted={deleted}" ) return True except Exception as e: logger.error(f"撤销 OTP verified key 失败: {e}") return False async def refresh_ttl(self, employee_id: str) -> bool: """刷新 OTP 验证的 TTL（滑动窗口）。 每次高危操作通过守卫后调用，延长 30 分钟有效期。 已在 dependencies.require_high_risk_otp 内联调用,这里冗余暴露给 service 层。 Args: employee_id: 企微 UserID Returns: bool: 是否刷新成功 """ try: # 只有 key 存在时才刷新 TTL,防止误创建空 key value = await self.redis.get(self._key(employee_id)) if not value: return False await self.redis.expire(self._key(employee_id), self.ttl_seconds) return True except Exception as e: logger.error(f"刷新 OTP verified TTL 失败: {e}") return False @staticmethod def get_whitelist() -> Dict[str, Dict]: """获取 5 类高危操作白名单。 静态方法,供前端文档化展示"哪些操作需要 OTP"。 Returns: Dict[str, Dict]: 白名单字典 """ return HIGH_RISK_OPERATIONS_WHITELIST.copy() @staticmethod def is_valid_category(category: str) -> bool: """检查 category 是否在 5 类白名单内。 Args: category: 类别标识 Returns: bool: 是否合法 """ return category in HIGH_RISK_OPERATIONS_WHITELIST @staticmethod def list_categories() -> List[str]: """列出全部 5 类高危操作标识。 Returns: List[str]: category 列表 """ return list(HIGH_RISK_OPERATIONS_WHITELIST.keys()) # ----------------------------------------------------------------------------- # 工厂函数：方便在非 FastAPI DI 场景使用 # ----------------------------------------------------------------------------- def create_high_risk_guard(redis_client: aioredis.Redis) -> HighRiskGuard: """创建 HighRiskGuard 实例。 Args: redis_client: Redis 异步客户端 Returns: HighRiskGuard: 守卫服务实例 """ return HighRiskGuard(redis_client)