Usecase Overview

业务目标：在高风险插件或操作前引入多因子认证，确保只有通过绑定验证的用户才能执行敏感动作，同时提供锁定、恢复与审计闭环。
成功度量：MFA 绑定成功率 ≥ 95%；验证成功率 ≥ 97%；锁定误报率 ≤ 0.5%；恢复处理 SLA ≤ 15 分钟。
场景关联：支撑主场景 SCN-IAM-LOGIN-AUTH-001 Stage 3，与 SSO、API Token、风险处置共享登录上下文、告警通道与审计链路。

摘要：构建多因子策略、绑定、验证、锁定与恢复的一体化能力，确保敏感操作“安全可控、体验可接受、审计可追溯”。

Context & Assumptions

前置条件
- Feature Flag：iam-mfa-policy, iam-mfa-recovery, notify-transactional, audit-streaming 已启用并配置默认值。
- 通知服务支持短信、邮件、站内信等通知通道；硬件 Key 需通过 WebAuthn 接口接入。
- 安全管理员具备策略配置权限，用户具备访问敏感插件的授权。
- 风险引擎订阅 security.mfa.* 事件，用于监控锁定统计与误报分析。
输入/输出
- 输入：策略配置（插件、操作、验证方式、失败阈值）、用户绑定请求、验证码/签名、恢复码、管理员重置指令。
- 输出：MFA 绑定状态、验证票据、锁定/恢复事件、通知消息、审计与告警记录。
边界
- 不处理终端设备管理（MDM）与硬件 Key 采购；不涵盖非敏感操作的提示性验证。
- 账号生命周期、角色授权由其他子用例负责，本用例只关注敏感操作的额外校验。

层	主要组件/模块	责任	代码入口
策略层	`internal/service/auth/mfa_policy_service.go`	策略 CRUD、租户/插件/操作粒度评估、阈值计算	`services/auth`
绑定层	`internal/service/auth/mfa_enrollment_service.go`	首次绑定流程、恢复码生成、绑定信息存储	`services/auth`
验证层	`pkg/mfa/providers/{totp,webauthn,sms}.go`	提供各类验证器实现、容差与失败计数	`pkg/mfa/providers`
通知层	`pkg/notify/dispatchers/mfa.js`	锁定通知、恢复提醒、管理员审批工作流	`pkg/notify`
审计与风控	`pkg/audit/mfa_logger.go`, `pkg/risk/analyzers/mfa_anomaly.go`	审计事件写入、锁定监控、误报回滚记录	`pkg/audit`, `pkg/risk/analyzers`

Inbound API
- POST /internal/security/mfa/policies — 配置策略，字段包括 plugin, operations[], methods[], fail_threshold, grace_period_minutes, backup_methods[]。
- POST /auth/mfa/enroll — 生成绑定挑战，返回二维码、秘密种子、WebAuthn Challenge、恢复码。
- POST /auth/mfa/verify — 提交验证码/签名，返回 verification_id 与状态；失败时返回 LOCKED, INVALID_CODE, EXPIRED 等错误码。
- POST /internal/security/mfa/lock / unlock — 锁定或解锁用户，供管理员或风控调用。
Events
- security.mfa.assigned、security.mfa.verified、security.mfa.locked、security.mfa.recovered — 审计事件，包含 tenant_id, user_id, method, plugin, status, trace_id。
配置与脚本
- config/mfa/policies.yaml — 默认策略、阈值、失败宽限。
- config/mfa/providers.yaml — 各验证器的容差、重试及依赖配置。
- scripts/mfa/generate-recovery-codes.sh、scripts/mfa/unlock-users.sh — 批量恢复/解锁工具。

项目	描述	完成状态	负责人
策略模型	设计策略表结构、租户隔离字段、索引	[ ]	Li Wei
绑定流程	实现绑定向导、恢复码生成、重复绑定检测	[ ]	Li Wei
通知与告警	配置锁定通知、审批提醒、告警阈值	[ ]	Matrix Ops
审计联动	接入审计事件、风险误报回滚机制	[ ]	Matrix Ops
文档与 Runbook	更新 `docs/standards/security/mfa-policy-guide.md`、运维手册	[ ]	Li Wei

指标：auth.mfa.enroll_success_total, auth.mfa.verify_success_total, auth.mfa.verify_fail_total, auth.mfa.locked_total, auth.mfa.reset_total。
日志：记录 tenant_id, user_id, plugin, method, status, error_code, trace_id（敏感信息脱敏）。
告警：验证失败率 >5%/5 分钟触发 PagerDuty；锁定事件 >5 次/租户/10 分钟推送 Slack；恢复失败触发工单。
仪表板：Grafana IAM / MFA Overview、Datadog auth-mfa-*、reports/iam/auth-security-dashboard。

回滚步骤：回滚最新部署；关闭 iam-mfa-policy 功能开关；撤销策略变更。
补救措施：使用 scripts/mfa/unlock-users.sh --tenant <id> 批量解锁；scripts/mfa/generate-recovery-codes.sh 补发恢复码；通知管理员手动审批。
数据修复：通过审计事件回放修复锁定状态；手动清理异常绑定记录；同步更新通知与风险系统。

风险/事项	影响	缓解方案	负责人	ETA
海外短信通道延迟导致验证超时	验证成功率	增加备用渠道/就近节点，加速短信发送	Matrix Ops	2025-11-20
硬件 Key 灰度尚未完成	绑定覆盖率	扩充测试矩阵，与采购协同部署	Li Wei	2025-11-12

完成 Seed 后，请运行 npm run publish:usecases -- --scn-id SCN-IAM-LOGIN-AUTH-001 --validate-only 校验结构，再按流程分发到下游仓库。