WIP-CHECKPOINT[auth-refactor]: 固化工程师崩溃前部分成果 + 同树其他未提交WIP（仅源码，不含密钥/二进制）-- 待重激活工程师续作
This commit is contained in:
Simon
@@ -0,0 +1,364 @@
|
||||
# =============================================================================
|
||||
# 企微IT智能服务台 — 统一 OTP 二次认证 API（三端认证重构 AUTH-03）
|
||||
# =============================================================================
|
||||
# 说明：三端（H5 员工端 / 坐席端 / 管理端）统一的 OTP(TOTP) 二次认证路由。
|
||||
#
|
||||
# 端点列表（前缀 /auth，nginx 会剥离 /api 前缀，对外即 /api/auth/otp-*）：
|
||||
# 1. GET /auth/otp-status — 查询绑定状态（路由守卫用）
|
||||
# 2. POST /auth/otp-bind — 生成 secret + 二维码（尚未启用）
|
||||
# 3. POST /auth/otp-verify — 输入 OTP 通过验证（写 Redis 30 分钟）
|
||||
# 4. POST /auth/otp-unbind — 用户主动关闭 MFA
|
||||
# 5. POST /auth/otp-admin-reset/{id} — 管理员重置（员工丢手机兜底）
|
||||
# 6. GET /auth/otp-admin-users — 管理员查看全部坐席 MFA 绑定状态
|
||||
#
|
||||
# 设计要点（与 system_design.md 对齐）：
|
||||
# - 复用 MFAService（pyotp + qrcode）与 agents 表的 mfa_* 字段
|
||||
# - 验证通过后在 Redis 写 mfa:verified:{employee_id}，TTL=1800s
|
||||
# - 与 dependencies.require_high_risk_otp 共用同一 Redis key（契约不变）
|
||||
# - 取代原 /mfa/* 与 /admin/mfa/* 以及 agents 内联 /agents/otp-* 端点
|
||||
#
|
||||
# 鉴权：
|
||||
# - 1-4 用 get_current_user（任意已登录用户）
|
||||
# - 5-6 用 require_role("admin")（管理员）
|
||||
# =============================================================================
|
||||
|
||||
import logging
|
||||
from datetime import datetime
|
||||
from typing import Optional
|
||||
|
||||
import redis.asyncio as aioredis
|
||||
from fastapi import APIRouter, Depends
|
||||
from sqlalchemy import select
|
||||
from sqlalchemy.ext.asyncio import AsyncSession
|
||||
|
||||
from app.config import settings
|
||||
from app.database import get_db
|
||||
from app.dependencies import UserInfo, get_current_user, require_role
|
||||
from app.models.agent import Agent
|
||||
from app.schemas.mfa import (
|
||||
MFABindConfirmRequest,
|
||||
MFABindStartResponse,
|
||||
MFADisableRequest,
|
||||
MFADisableResponse,
|
||||
MFAStatusResponse,
|
||||
MFAVerifyRequest,
|
||||
MFAVerifyResponse,
|
||||
)
|
||||
from app.services.mfa_service import MFA_VERIFIED_TTL_SECONDS, MFAService
|
||||
from app.utils.error_codes import ErrorCode
|
||||
from app.utils.response import AppException, success_response
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# 路由配置：统一前缀 /auth
|
||||
# -----------------------------------------------------------------------------
|
||||
router = APIRouter(prefix="/auth", tags=["OTP二次认证"])
|
||||
|
||||
|
||||
def _get_redis() -> aioredis.Redis:
|
||||
"""获取 Redis 客户端（模块级 helper，便于测试 patch）。
|
||||
|
||||
Returns:
|
||||
aioredis.Redis: Redis 异步客户端
|
||||
"""
|
||||
return settings.create_redis_client()
|
||||
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# 通用工具：根据 user_id(employee_id) 查 Agent 记录
|
||||
# -----------------------------------------------------------------------------
|
||||
async def _get_agent_by_employee_id(
|
||||
db: AsyncSession, employee_id: str
|
||||
) -> Optional[Agent]:
|
||||
"""按 user_id（employee_id）查询 Agent 行。
|
||||
|
||||
Args:
|
||||
db: 数据库会话
|
||||
employee_id: 用户标识（企微 userid）
|
||||
|
||||
Returns:
|
||||
Optional[Agent]: 找不到返回 None
|
||||
"""
|
||||
stmt = select(Agent).where(Agent.user_id == employee_id)
|
||||
result = await db.execute(stmt)
|
||||
return result.scalars().first()
|
||||
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# 通用工具：验证当前用户是否已登录 + 取得 Agent 行
|
||||
# -----------------------------------------------------------------------------
|
||||
async def _require_agent(
|
||||
db: AsyncSession, current_user: UserInfo
|
||||
) -> Agent:
|
||||
"""根据当前 token 取出对应的 Agent 行，不存在则 404。
|
||||
|
||||
MFA 状态 / secret 都存放在 agents 表，不是 employees 表。
|
||||
|
||||
Raises:
|
||||
AppException: 坐席不存在（E4001）
|
||||
"""
|
||||
agent = await _get_agent_by_employee_id(db, current_user.employee_id)
|
||||
if not agent:
|
||||
raise AppException(ErrorCode.AGENT_NOT_FOUND, "坐席不存在，无法进行 OTP 操作")
|
||||
return agent
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# 1. GET /auth/otp-status — 查询绑定状态
|
||||
# =============================================================================
|
||||
@router.get("/otp-status", response_model=None)
|
||||
async def get_otp_status(
|
||||
current_user: UserInfo = Depends(get_current_user),
|
||||
db: AsyncSession = Depends(get_db),
|
||||
redis: aioredis.Redis = Depends(_get_redis),
|
||||
):
|
||||
"""查询当前用户的 OTP 绑定状态。
|
||||
|
||||
前端路由守卫使用：
|
||||
- bound=false → 强制走绑定流程
|
||||
- bound=true → 跳到"输入 OTP 验证"或继续业务
|
||||
|
||||
Returns:
|
||||
success_response({bound, enabled, last_verified_at, verified})
|
||||
"""
|
||||
agent = await _require_agent(db, current_user)
|
||||
|
||||
# 是否处于 30 分钟验证窗口内（与 require_high_risk_otp 共用 key）
|
||||
verified = await MFAService.is_verified(redis, agent.user_id)
|
||||
|
||||
return success_response(data=MFAStatusResponse(
|
||||
bound=bool(agent.mfa_enabled and agent.mfa_secret),
|
||||
enabled=bool(agent.mfa_enabled),
|
||||
last_verified_at=agent.mfa_last_verified_at,
|
||||
).model_dump(mode="json") | {"verified": verified})
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# 2. POST /auth/otp-bind — 生成 secret + 二维码
|
||||
# =============================================================================
|
||||
@router.post("/otp-bind", response_model=None)
|
||||
async def bind_otp(
|
||||
current_user: UserInfo = Depends(get_current_user),
|
||||
db: AsyncSession = Depends(get_db),
|
||||
):
|
||||
"""生成 TOTP 密钥和二维码。
|
||||
|
||||
行为：
|
||||
- 生成 32 位 base32 secret
|
||||
- 把 secret 写入 agents.mfa_secret（mfa_enabled=False, mfa_bound_at=None）
|
||||
- 返回 otpauth URI + base64 二维码 PNG（给前端展示）
|
||||
|
||||
重复调用策略：
|
||||
- 已 enabled=True → 拒绝，要求先 unbind 再重新绑定
|
||||
- 仅 secret 存在但 enabled=False → 复用旧 secret（支持"刷新二维码"）
|
||||
|
||||
Returns:
|
||||
success_response({secret, otpauth_url, qr_code_base64})
|
||||
"""
|
||||
agent = await _require_agent(db, current_user)
|
||||
|
||||
# 已启用则拒绝重新绑定（必须先 unbind）
|
||||
if agent.mfa_enabled:
|
||||
raise AppException(
|
||||
ErrorCode.INVALID_PARAMETER,
|
||||
"已绑定 OTP，如需重新绑定请先关闭",
|
||||
)
|
||||
|
||||
# 复用旧 secret 还是新生成？
|
||||
if agent.mfa_secret:
|
||||
secret = agent.mfa_secret
|
||||
else:
|
||||
secret = MFAService.generate_secret()
|
||||
agent.mfa_secret = secret
|
||||
# mfa_enabled 保持 False，mfa_bound_at 等首次验证通过再写
|
||||
db.add(agent)
|
||||
await db.flush()
|
||||
|
||||
otpauth_url = MFAService.build_provisioning_uri(secret, agent.user_id)
|
||||
qr_base64 = MFAService.render_qrcode_base64(otpauth_url)
|
||||
|
||||
logger.info(f"OTP bind: agent={agent.user_id}, secret_prefix={secret[:4]}...")
|
||||
|
||||
return success_response(data=MFABindStartResponse(
|
||||
secret=secret,
|
||||
otpauth_url=otpauth_url,
|
||||
qr_code_base64=qr_base64,
|
||||
).model_dump())
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# 3. POST /auth/otp-verify — 输入 OTP 通过验证（写 Redis 30 分钟）
|
||||
# =============================================================================
|
||||
@router.post("/otp-verify", response_model=None)
|
||||
async def verify_otp(
|
||||
body: MFAVerifyRequest,
|
||||
current_user: UserInfo = Depends(get_current_user),
|
||||
db: AsyncSession = Depends(get_db),
|
||||
redis: aioredis.Redis = Depends(_get_redis),
|
||||
):
|
||||
"""校验 6 位码，在 Redis 写 30 分钟复用标记。
|
||||
|
||||
行为：
|
||||
- 校验通过 → mfa:verified:{employee_id}=1 TTL 1800s
|
||||
+ 更新 mfa_last_verified_at
|
||||
- 校验失败 → verified=false（不抛异常，前端可重试）
|
||||
|
||||
Returns:
|
||||
success_response({verified, expires_in})
|
||||
"""
|
||||
agent = await _require_agent(db, current_user)
|
||||
|
||||
if not agent.mfa_enabled or not agent.mfa_secret:
|
||||
# 用户还没绑定 OTP，直接返回 verified=false（前端可据此跳转绑定流程）
|
||||
return success_response(data=MFAVerifyResponse(
|
||||
verified=False,
|
||||
expires_in=0,
|
||||
).model_dump())
|
||||
|
||||
# 校验
|
||||
if not MFAService.verify_code(agent.mfa_secret, body.otp_code):
|
||||
logger.warning(f"OTP verify 验证码错误: agent={agent.user_id}")
|
||||
return success_response(data=MFAVerifyResponse(
|
||||
verified=False,
|
||||
expires_in=0,
|
||||
).model_dump())
|
||||
|
||||
# 写 Redis 复用标记（与 require_high_risk_otp 共用 key）
|
||||
await MFAService.mark_verified(redis, agent.user_id, MFA_VERIFIED_TTL_SECONDS)
|
||||
|
||||
# 更新最后验证时间
|
||||
now = datetime.now()
|
||||
agent.mfa_last_verified_at = now
|
||||
db.add(agent)
|
||||
await db.flush()
|
||||
|
||||
logger.info(f"OTP verify 通过: agent={agent.user_id}")
|
||||
|
||||
return success_response(data=MFAVerifyResponse(
|
||||
verified=True,
|
||||
expires_in=MFA_VERIFIED_TTL_SECONDS,
|
||||
).model_dump())
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# 4. POST /auth/otp-unbind — 用户主动关闭 OTP
|
||||
# =============================================================================
|
||||
@router.post("/otp-unbind", response_model=None)
|
||||
async def unbind_otp(
|
||||
body: MFADisableRequest,
|
||||
current_user: UserInfo = Depends(get_current_user),
|
||||
db: AsyncSession = Depends(get_db),
|
||||
redis: aioredis.Redis = Depends(_get_redis),
|
||||
):
|
||||
"""关闭 OTP（清空 secret + disabled 标记）。
|
||||
|
||||
安全要求：必须先校验当前 OTP，防止误操作或被劫持后恶意关闭。
|
||||
|
||||
Returns:
|
||||
success_response({success: true})
|
||||
"""
|
||||
agent = await _require_agent(db, current_user)
|
||||
|
||||
if not agent.mfa_enabled or not agent.mfa_secret:
|
||||
# 没绑定过，直接幂等成功
|
||||
return success_response(data=MFADisableResponse(success=True).model_dump())
|
||||
|
||||
# 必须先验证 OTP
|
||||
if not MFAService.verify_code(agent.mfa_secret, body.otp_code):
|
||||
raise AppException(ErrorCode.INVALID_PARAMETER, "OTP 验证码错误，无法关闭 OTP")
|
||||
|
||||
# 清空字段
|
||||
agent.mfa_secret = None
|
||||
agent.mfa_enabled = False
|
||||
agent.mfa_bound_at = None
|
||||
# mfa_last_verified_at 保留，作为历史记录
|
||||
db.add(agent)
|
||||
await db.flush()
|
||||
|
||||
# 顺手清掉 Redis 验证标记（避免遗留）
|
||||
await MFAService.clear_verified(redis, agent.user_id)
|
||||
|
||||
logger.info(f"OTP unbind: agent={agent.user_id}")
|
||||
|
||||
return success_response(data=MFADisableResponse(success=True).model_dump())
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# 5. POST /auth/otp-admin-reset/{employee_id} — 管理员重置（丢手机兜底）
|
||||
# =============================================================================
|
||||
# 注意：此端点不要求 otp_code（员工已无法提供），只校验 admin 角色
|
||||
# 鉴权：@require_role("admin") 装饰器强制
|
||||
# =============================================================================
|
||||
@router.post("/otp-admin-reset/{employee_id}", response_model=None)
|
||||
@require_role("admin")
|
||||
async def admin_reset_otp(
|
||||
employee_id: str,
|
||||
current_user: UserInfo = Depends(get_current_user),
|
||||
db: AsyncSession = Depends(get_db),
|
||||
redis: aioredis.Redis = Depends(_get_redis),
|
||||
):
|
||||
"""管理员重置指定员工的 OTP 绑定（无 OTP 验证）。
|
||||
|
||||
使用场景：
|
||||
- 员工丢手机 / 换手机 → 管理员后台"重置 OTP"按钮
|
||||
|
||||
Returns:
|
||||
success_response({success: true})
|
||||
"""
|
||||
stmt = select(Agent).where(Agent.user_id == employee_id)
|
||||
result = await db.execute(stmt)
|
||||
agent = result.scalars().first()
|
||||
|
||||
if not agent:
|
||||
raise AppException(ErrorCode.AGENT_NOT_FOUND, f"坐席 {employee_id} 不存在")
|
||||
|
||||
agent.mfa_secret = None
|
||||
agent.mfa_enabled = False
|
||||
agent.mfa_bound_at = None
|
||||
# mfa_last_verified_at 保留，作为审计
|
||||
db.add(agent)
|
||||
await db.flush()
|
||||
|
||||
# 顺手清 Redis 标记
|
||||
await MFAService.clear_verified(redis, employee_id)
|
||||
|
||||
logger.info(f"OTP admin reset: employee_id={employee_id} by={current_user.employee_id}")
|
||||
|
||||
return success_response(data={"success": True})
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# 6. GET /auth/otp-admin-users — 管理员查看全部坐席 OTP 绑定状态
|
||||
# =============================================================================
|
||||
@router.get("/otp-admin-users", response_model=None)
|
||||
@require_role("admin")
|
||||
async def admin_list_otp_users(
|
||||
current_user: UserInfo = Depends(get_current_user),
|
||||
db: AsyncSession = Depends(get_db),
|
||||
):
|
||||
"""管理员查看全部坐席的 OTP 绑定状态。
|
||||
|
||||
Returns:
|
||||
success_response([{employee_id, name, mfa_enabled, mfa_bound_at,
|
||||
mfa_last_verified_at}, ...])
|
||||
"""
|
||||
stmt = select(Agent).order_by(Agent.user_id)
|
||||
result = await db.execute(stmt)
|
||||
agents = result.scalars().all()
|
||||
|
||||
users = [
|
||||
{
|
||||
"employee_id": a.user_id,
|
||||
"name": getattr(a, "name", "") or "",
|
||||
"mfa_enabled": bool(a.mfa_enabled),
|
||||
"mfa_bound_at": a.mfa_bound_at.isoformat() if a.mfa_bound_at else None,
|
||||
"mfa_last_verified_at": (
|
||||
a.mfa_last_verified_at.isoformat() if a.mfa_last_verified_at else None
|
||||
),
|
||||
}
|
||||
for a in agents
|
||||
]
|
||||
|
||||
return success_response(data=users)
|
||||
Reference in New Issue
Block a user