D01 账号与身份域 · 设计文档

本域总览见《账号计费中心 · 结构大纲》。本文为该域完整设计：定位与边界 / 角色与依赖 / 数据模型 / 核心流程 / 接口契约 / 关键约束与验收标准。

1. 定位与边界

定位：终端用户身份与凭证的统一入口，同时承担平台统一登录（OIDC IdP）的身份提供方职责。回答两个问题——「你是谁」（身份）与「如何证明你是你」（凭证）。

边界

• 本域只管身份与凭证：账号、登录、密码、联系方式、会话、单点登录、人机验证门禁、协议同意留痕。
• 不管授权业务：组织、角色、成员归属归租户与组织域；本域只告知「这个请求来自哪个用户」。
• 不管资金：本域不产生、不校验任何金额字段。
• 不做实名核验：实名属风控与合规域；本域仅承载其实名结果的回写位（identity_verified / identity_level），不实现核验。

登录方式口径

• 邮箱为主路径（验证码登录 + 密码登录），不受开关约束。
• 手机通道受能力开关控制：手机是否可用（验证码登录手机通道、短信找回、手机绑定）为单一数据源、DB 驱动、fail-closed——生产短信通道未签约时手机入口不出现。
• 微信扫码登录为一期纳入能力；真实凭据未就位时以联调模式运行，生产禁用联调模式。

2. 角色与依赖

令牌契约（对外提供）

• 门户访问令牌有效期 30 分钟，刷新令牌 7 天；签名算法 HS256 共享密钥（供统一网关复用校验）；载荷含 sub / type / roles / exp / iat / jti / typ=portal。
• 令牌区分类型：门户令牌（typ=portal）用于业务鉴权；过渡令牌（typ=wechat_bind）仅可用于绑定手机流程，业务鉴权一律拒绝。

3. 数据模型

独立表（无外键，自持一次性令牌 / 按来源 IP 与身份串计数，随 TTL 或周期清理收敛）：captchas · slider_captchas · login_throttles

本域为最底层身份域，不引用其他域的表，对外只做被引用方；上图为 users 的下游引用分布。

3.3 表清单（12 表）

邮箱验证码校验通过（一次性票据）→ 提交账号名 + 密码（弱密码 422）→ 协议勾选留痕 → 建号。企业注册额外建组织并由注册人成为拥有者。注册成功即调度账户状态键发布（新账号准入语义见账户状态与准入域）。

• 门禁判定在身份反查之前，按提交串计数；IP 维度与身份维度双维度独立计数，任一维达阈值即触发对应拦截。
• 反查凭证：命中则校验密码，未命中走恒定时间假哈希路径（耗时与命中一致）。
• 成功：签发令牌对、更新登录安全字段、写安全日志。
• 失败：双维度计数 +1（含「账号不存在」的尝试），响应码与文案与存在账号完全一致。
• 限流采用固定窗口（窗口边界对齐），计数行按 (scope, subject, window_start) 唯一、单条 UPSERT 原子自增；过期行由周期清理收敛（身份串完全由攻击者可控，无清理可被低成本撑爆）。
• 来源 IP 采信规则：仅当直连对端落在可信代理名单内才采信转发头，否则一律回落直连地址。

• 访问令牌 30 分钟；刷新令牌 7 天、单活轮换——轮换以条件更新（CAS）原子抢占水位，仅当水位不晚于所呈令牌签发时间才放行；重放 / 他端已消费 一律 401。多端语义：最后轮换者存活，其余端待访问令牌自然过期。
• 双水位失效：session_invalid_before（批量失效访问 / 刷新令牌）与 rt_invalid_before（刷新令牌单活水位）。
• 触发失效的动作：修改密码、重置密码、换绑联系方式、注销、首次设置密码。

换绑邮箱 / 手机需新值验码 + 旧凭证占有因子二选一（旧联系方式验证码，或登录密码确认）。授权依据是「账号是否已有可自证的找回通道」，而非「该类型有无已验证旧值」——仅当账号不存在任何已验证联系方式时才豁免第二因子；否则会给攻击者开一条免第二因子的找回通道生产线。绑定微信同为新增登录入口，口径与此一致。

• 授权端点：参数白名单校验，失败一律 400 HTML，绝不重定向到未验证地址。
• 兑换在集群内完成：校验授权码未消费、未过期、客户端与回调一致、PKCE。
• scope 含门户的客户端，兑换时另加发门户令牌对。
• IdP 全局会话服务端硬上限 7 天、固定不滚动，与业务刷新令牌完全独立、互不吊销。
• 统一登出为续跳链：逐客户端通知（best-effort），链尽回落地页；无会话同样走清 cookie 与续跳（幂等）。
• 撤销时机：统一登出、重置密码、修改密码、首次设置密码均撤销该用户全部未撤销 IdP 会话——只前移门户水位不撤销 IdP 会话时，失窃会话持有者仍可经授权端点静默续出客户端令牌，改密自救失效。

签发 state（防 CSRF，10 分钟）→ 回调换 openid → 已绑定手机直接登录；未绑手机发过渡令牌（15 分钟，仅可调绑定手机端点）→ 绑定手机后换发正式门户令牌。首次登录可即时建号，建号前须完成绑定手机（手机为实名锚点）。

• 图形验证码：用于登录失败重试场景；5 分钟有效、单条最多校验 3 次，达限作废。
• 滑块验证：验证码发码前的前置门禁；token 2 分钟有效、横向容差 2px、轨迹须非匀速、单 token 最多校验 2 次；校验通过签发一次性票据，发码凭票据一次性消费。
• 阈值设计目标：单 token 通过率 < 5%（容差 × 尝试数 / 取值域）。
• 发码频控：同 target 重发间隔 60 秒、每日 10 次；单 IP 每日 50 次；素材生成单 IP 每日 200 次。
• 失败频控：图形码单 IP 窗口内错误 20 次 → 429；滑块单 token 失败上限 2 次、单 IP 窗口内 15 次 → 429。

协议版本由服务端单一常量定义；同意写入只增历史表 + 审计，并在用户行留「当前生效」快照。版本不一致（未同意 / 协议已更新）时，下单被 403 terms_not_agreed 拦下——门禁开关可按环境关闭（灰度 / 演示）。

5. 接口契约

5.1 门户认证（/api/account/auth）

5.2 注册与账号管理（/api/account）

5.3 人机验证（/api/account/slider-captcha）

5.4 微信扫码（/api/account）

5.5 统一登录（IdP，非 /api/account 前缀）

6. 关键约束与验收标准

6.1 约束

1. 不得泄露账号存在性：门禁判定先于身份反查，且不存在账号与存在账号走完全相同的计数与响应路径；不存在用户路径跑恒定时间假哈希，防时序侧信道。
2. 凭证不可逆与最小化：密码、验证码答案哈希存储；证书 / 密钥类凭据经环境注入，不入库、不回显。
3. 状态多副本共享 + 原子消费：图形码 / 滑块 / 验证码状态落库；消费一律 UPDATE ... RETURNING 抢占，并发双消费恒至多一次成功。
4. 令牌单活：刷新令牌消费即失效、重放 401；改密 / 换绑 / 注销须同时前移门户水位并撤销 IdP 会话，二者缺一即构成自救失败。
5. 开放跳转面为零：授权端点参数错误一律 400 HTML，不 302；回跳目标由服务端签发并验签，不接受客户端传入。
6. 令牌端点不可公网直达：令牌兑换端点仅集群内可达，浏览器全程不直连。
7. 登录页无注入面：服务端渲染登录页不回显任何请求输入，错误统一静态文案。
8. 能力开关 fail-closed：手机通道、微信登录、单点登录任一能力未就位时其入口不下发；联调模式凭据在生产一律拒绝（白名单判定为「环境 = 开发」，非「≠ 生产」）。
9. 限流覆盖不存在账号：两维度计数均覆盖「账号不存在」的尝试，否则攻击者可对任意账号试 2 次绕过图形码与锁定。

6.2 验收标准

6.3 待后续设计细化的开放项

• 账号名一期不可改，后续是否开放改名（含改名冷却与占用释放）。
• 手机通道开放后，手机与邮箱同时存在时的主联系方式重算规则。
• 微信扫码在真实凭据下的多应用（公众号 / 开放平台）账号归并口径。