# 注册、登录与管理员设计

本页主体为模拟交易的邮箱会话和管理员。v0.6 发售另有独立 EOA 钱包挑战登录与 Cookie/CSRF 会话，见[发售设计](flash-sale-design.md)；下方 v0.4 说明按当时版本理解。首次接触签名先看[初学者讲解](../01-beginner/03-assets-signatures.md)。

> 当前基线：模拟 v0.3 保留，独立链模式升级为 v0.5。新增完整历史查询、任务版本保护、已确认事件索引、只读对账和基础告警，见 [设计](../07-history/v0.5-design.md)、[执行报告](../reports/2026-10-12-v0.5.md)。历史报告与证据保留原版本。

> 历史 v0.4 变更记录（当前增量见页首 v0.5）：邮箱注册、Cookie/CSRF/RBAC及pinkode本地管理员继续属于模拟模式。链模式由EOA钱包逐笔EIP712签名授权，approve与签名分开；没有邮箱绑定钱包或SIWE登录功能。管理员CREDIT不产生链资产，relayer只支付Gas且不能任意提款。 当前链实现见[v0.5架构](../07-history/v0.5-design.md)，操作见[开发](../03-development/web3-development.md)、[测试](../04-testing/web3-testing.md)、[部署](../05-deployment/web3-deployment.md)，证据见[本轮报告](../reports/2026-10-12-v0.4.md)。


更新：2026-10-11。最新要求覆盖 goal.md 的“无需登录”。当前已实现注册/登录/退出、普通用户交易权限、管理员用户管理和模拟资金增加；邮箱验证、找回密码、MFA、角色编辑未实现。

## 状态与权限边界

认证维护在外围 auth.db，bcrypt、随机数、时钟、SQL 均不进入核心。HTTP 用服务端会话中的 user.id 设置业务 account_id，用户不能在下单请求中指定他人账户。用户 ID 用安全随机数，订单 ID 仍取日志序号。

注册只能创建 USER，未知字段/role 被拒绝。ADMIN 由 EXCHANGE_ADMIN_EMAIL/PASSWORD 显式初始化；已有普通账号不能自动提权，ADMIN 不能通过管理接口被停用。前端隐藏按钮之外，后端每次检查角色。

## 密码与会话

- bcrypt cost 10，密码 12–72 字节；邮箱规范化并由 UNIQUE 约束防重复注册。
- 会话 token 为 32 字节随机值，数据库仅保存 SHA-256 摘要；Cookie HttpOnly、SameSite=Strict，24 小时绝对有效期，不随访问续期；创建新会话时清理过期记录。HTTPS 设置 Secure=true。CSRF 原值存于认证库，用于服务端校验；客户端只保存在内存。
- 写接口要求 X-CSRF-Token，并检查 Origin；CSRF token 登录后只在前端内存保存。每次受保护请求读取会话有效期和用户禁用状态。
- 注销删除当前会话；停用状态、删除全部会话与认证审计在同一事务提交；重新启用后必须重新登录，旧 token 不恢复。认证请求按直连 IP 限流且 bcrypt 并发有限；代理部署须后续明确可信代理策略，不信任任意 X-Forwarded-For。

## 资金初始化

auth.db 先提交用户；ETH 10、USDT 100000 分别通过 CREDIT 输入日志初始化，使用保留的 system.initial.<asset> 幂等键。客户端不能使用 system. 前缀。

两库不做跨库事务：若注册已完成但资金初始化失败，后续登录重新发同键命令，核心保证不重复注资。auth.db 属于权威数据，不能像 views.db 一样删除重建。

## 权限矩阵

| 功能 | 访客 | USER | ADMIN |
| --- | --- | --- | --- |
| 行情/市场/WS | 允许 | 允许 | 允许 |
| 自己余额/订单/下单/撤单 | 禁止 | 允许 | 允许 |
| 他人下单/撤单 | 禁止 | 禁止 | 禁止 |
| 全部用户/订单/审计 | 禁止 | 禁止 | 允许 |
| 停用/启用 USER | 禁止 | 禁止 | 允许 |
| 指定用户增加模拟资金 | 禁止 | 禁止 | 允许，需原因和幂等键 |
| 提权/停用 ADMIN | 禁止 | 禁止 | 首版不提供 |

资金增加走日志屏障和核心，不直接改余额；输入记录 actor_id、target、amount、reason。首版只有正向模拟注资，没有扣款。

## 停用语义

停用使会话失效并拒绝新的授权，已经授权受理的命令可能完成；已挂订单不会自动撤单。严格交易封禁需要新增进入核心序列的账户状态/撤单事件，首版停用是访问控制。

管理员审计包含 AUTH 状态动作和投影后的 CREDIT 执行结果。资金审计带 `code/replayed`：拒绝或原键确认都不能画成新增资金成功。输入日志只证明输入持久化，业务结果需查看对应投影结果；AUTH 与 CREDIT 分组分页，各自固定上界，不是跨库全局时间快照。

## 实际接口

| 接口 | 功能 |
| --- | --- |
| POST /api/v1/auth/register、/login | 注册/登录，返回 user、csrf_token、dataset_id，设置 Cookie |
| GET /api/v1/auth/me | 当前用户/CSRF/数据集 |
| POST /api/v1/auth/logout | 注销当前会话 |
| GET /api/v1/admin/users | 用户页对象；limit 1–100，页面使用 20，next_cursor 继续翻页 |
| PATCH /api/v1/admin/users/{id} | disabled 字段 |
| POST /api/v1/admin/credits | 正向模拟注资 |
| GET /api/v1/admin/orders、/audit | 全部订单与操作审计 |

交易实际接口为 /api/v1/orders、/balances、/snapshot、/stream；订单/资金写入需 Idempotency-Key。实现文件：[auth.go](../../backend/auth.go)、[http.go](../../backend/http.go)、[前端](../../frontend/src/App.tsx)。

## v0.2 认证响应与恢复

认证响应新增 dataset_id（重启/投影重建不变），已登录前端用 X-Dataset-ID 限制后续请求。Cookie/CSRF/RBAC 规则保持；pending 原请求保存在 sessionStorage 的数据集/账户域，重新登录相同身份可恢复，新身份不能复用旧操作。密码、会话 token、CSRF 不写入 pending。管理员注资仍通过原 POST 确认，未开放任意目标账户按键查询。详见[v0.2 设计](../07-history/v0.2-design.md)。

## v0.3 管理查询与离线维护

用户/审计返回页对象，前端各自翻页，完整历史不再固定 200/100 上限。认证审计和资金审计分组分页，资金来自投影明确显示拒绝/重复确认；不从 journal 写者连接查询 JSON 日志。AUTH 与业务投影不同事务域，分页上界分别固定，不能说跨库全局快照。

停机 init-admin/check/backup/restore 使用同一独占锁；身份/会话库和日志一并 checkpoint/备份，恢复到新目录保留会话身份。bcrypt 依赖升级 x/crypto v0.58.0，既有哈希与旧数据不重写，认证/恢复回归仍适用。diag loopback 不提供管理权限绕过或密码/会话读取接口。

## 初始化、失败与验证说明

`BootstrapAdmin` 先查询规范邮箱；已有 ADMIN 原样返回，不校验所提供密码是否与旧密码相同，也不重新生成哈希。已有 USER 拒绝提权。更改启动环境密码不会成为密码重置流程；当前没有密码重置接口。

注册时身份提交、两条初始化 CREDIT、创建会话依次进行，跨库不原子。响应失败时用户可能已经存在，后续登录用系统保留键补齐资金；不要通过删身份记录“重做注册”。停用是接入授权边界，已受理命令与活动挂单仍可能成交。

验证入口：[认证单元测试](../../backend/auth_unit_test.go)、[安全集成测试](../../backend/security_boundary_test.go)、[HTTP 边界测试](../../backend/http_boundary_test.go)、[管理员浏览器测试](../../frontend/tests/admin.spec.ts)。具体执行与证据见[测试手册](../04-testing/testing-guide.md)及[测试完善报告](../reports/2026-10-11-test-hardening.md)。客户端流程见[接口使用指南](../03-development/api-guide.md)。

## Windows 本地管理员例外

用户指定八字节密码，一键脚本显式启用 EXCHANGE_LOCAL_ADMIN_NAME。服务在打开数据库前强制数值回环监听，不与常规管理员邮箱混用；可信初始化允许 8–72 字节，注册/常规管理员仍 12–72。登录别名映射为 name@localhost，数据库/响应仍邮箱身份，默认模式无别名。bcrypt、Cookie/CSRF/权限不变；已有管理员不重置密码、USER 不提权。详见[本地启动说明](../05-deployment/windows-local-run.md)与[本轮报告](../reports/2026-10-11-windows-launcher.md)。

## v0.5 权限边界

模拟登录/注册/管理员 RBAC 保留；新增链历史只含公开钱包和签单。钱包筛选是查询条件，不是权限认证。任务详情删除 raw；对账仅回环，不允许公网写修复。邮箱用户仍未绑定钱包，不把钱包筛选伪装成受保护个人数据。
