0012 账号、会话与首次安装
- 状态:已接受(2026-10-23);登录的账号维度限流已由 0014 更新(启用验证码时改为要求验证码,不再锁定)
- 相关:设计文档 02 §1.1(F03、F05、F09)、03(S01、S02、S05、S08、S11、S15)、04 §5.1–5.3、§8
背景
M1 的第一步是"站点有主人":首次安装创建超级管理员,之后用账号登录、管理后台。Blessing Skin 在这里有一串问题:安装向导谁先打开谁就能接管站点(S11),登录区分"用户不存在/密码错误"(S05),密码长度规则四处不一(S15),改密只登出当前会话(S08)。
决策
- 表:
users(邮箱规范化后唯一,唯一性只靠数据库索引判定)、sessions、auth_tokens(一次性令牌,按用途区分)、audit_logs(不建外键,用户删除后日志仍在)。 - 密码:新哈希一律 argon2id(19 MiB、2 次迭代、1 线程,OWASP 最低推荐),PHC 字符串存储;同时最多 CPU 核数个哈希并发,登录洪峰排队而不是耗尽内存。从 Blessing Skin 导入的哈希(BCRYPT、ARGON2I、MD5、SALTED2MD5、SHA256、SALTED2SHA256、SHA512、SALTED2SHA512,
password_algo记录算法,加盐的存为<hex>:<salt>)照常验证,登录成功即升级为 argon2id。解析哈希时拒绝超大参数,防止坏数据让一次登录吃掉数 GB 内存。密码长度统一 8–128 个字符(按字符计,不按字节)。 - 会话:Cookie
skinloom_session里放 32 字节随机令牌,数据库只存它的 SHA-256,库泄露也无法冒充登录。HttpOnly、SameSite=Lax,经可信代理识别为 HTTPS 时加Secure。不勾"记住我"是浏览器会话 Cookie(服务端最长 1 天),勾选则 30 天。last_seen_at每 5 分钟最多写一次。被封禁用户的会话立即失效。API 请求只有在用到当前用户时才查会话(每次页面渲染都会调用的 bootstrap 不查)。 - CSRF:带会话 Cookie 的写请求(以及登录、安装这两个会建立会话的接口)必须带
X-SkinLoom-Request头;浏览器跨站发自定义头需要 CORS 预检,而 SkinLoom 从不放行。若浏览器带了Origin,还必须与请求的公开主机或site.url一致。只用 Bearer 令牌、不带 Cookie 的脚本不受影响。 - 登录:未注册邮箱和错误密码返回同一个 401(未注册时也跑一次 argon2,响应时间一致)。失败次数每 15 分钟分三层计数,超出返回 429 +
Retry-After:同一客户端地址(IPv6 按 /64)50 次;同一地址对同一账号 10 次;同一账号来自所有地址 100 次。第二层挡住单点猜密码,又不会让一个攻击者把真正的用户(比如超级管理员)锁在门外;第三层给分布式撞库设上限,验证码上线后改为"要求验证码"而不是直接拒绝。真实用户登录成功只清零自己那一层。封禁只在密码正确后才告知。图形验证码在后续切片接入(F04 Provider 抽象)。 - 首次安装:安装接口是公开的,所以先用廉价的检查拒绝无关请求(令牌格式、站点是否已安装、令牌是否存在且未过期),通过之后才计算密码哈希。站点没有完成安装时,
skinloom up每次启动都在控制台打印一次性链接/setup?token=…(24 小时有效,--open直接打开它;skinloom setup-link可再生成一个,容器内也能用)。只有能看到控制台或日志的人才能完成安装。完成安装是一个事务:验证令牌 → 写入system_state的setup.completed行(主键保证并发的两次安装只有一次成功)→ 创建超级管理员 → 作废全部安装令牌 → 建立会话 → 写审计。这一行此后永久存在,即使超级管理员被删除,安装页也不会重新开放。 - 管理 API:接受管理员会话;
data/secrets/admin.token保留给脚本(Bearer),直到 M3 的个人访问令牌上线。设置修改记录updated_by与审计日志。 - 每个账号接口的错误只返回状态码和固定文案,细节进服务端日志(S06)。
备选方案
- 会话 ID 直接作主键明文存储:实现更简单,但数据库备份或只读注入即可整站冒充。
- JWT 无状态会话:无法立即吊销(S08 要求改密/封禁后立刻踢人),每次仍需查黑名单。
- 双提交 Cookie 防 CSRF:要求前端读取 Cookie,与
HttpOnly冲突;自定义头方案对同源前端零成本。 - 首次访问即进入安装向导(BS 做法):公网部署的窗口期会被接管(S11)。
影响
- 前端所有写请求都经
@skinloom/api-client的apiFetch,它自动加 CSRF 头;插件前端(P2)同样通过它请求。 - 多副本部署时失败计数各副本独立,限额按副本数等比放宽;需要全局限流时再接 Redis。
- 新增依赖
golang.org/x/crypto(argon2、bcrypt)。