Files
persionalBrand/docs/adr/0032-admin-session-cookie.md

2.5 KiB
Raw Permalink Blame History

0032: Admin Session 使用 HttpOnly Cookie

Context

Admin 前端此前把 access token 保存在 localStorage,并由 feature 代码注入 Authorization header。这导致 token 可被 XSS 读取、品牌切换 token 需要在前端流转,也让部分页面依赖本地登录态而非服务端会话。与此同时,Admin authorization 曾按 URL 字符串匹配,method-level 角色规则无法可靠覆盖 class-level 品牌 rule。

Decision

  • Admin access token 只通过 admin_session HttpOnly cookie 交付;浏览器端不再持久化或读取 Admin token。
  • Admin API 继续接受 Bearer token,供集成测试、服务端调用和可审计工具使用。
  • AdminMembershipGuard 只读取 decorator metadata:AdminPublic、AdminBrand、AdminRoles、AdminTemplateAdmin、AdminTokenOnly。不再匹配 route 字符串。
  • method-level metadata 必须写入 Nest handler function,因此 method decorator 会覆盖 class-level metadata。
  • 登录、品牌切换和修改密码都由 API 设置新 cookie;切换品牌和登录响应不再返回 Admin token。
  • logout 只要求有效 Admin token,不额外要求当前品牌 membership,确保停用品牌成员仍可退出。
  • Customer session 仍使用 token 响应,因为小程序宿主负责安全存储和请求注入。

Alternatives

  • 继续 localStorage:XSS 暴露面大,且本地状态容易与服务端 token version 漂移。
  • 内存 token:刷新后丢失,需要重新登录,不能表达品牌切换后的当前会话。
  • 继续按 route 字符串 guard:每新增 controller 都可能漏配,method-level 规则容易失效。

Consequences

  • Admin 前端跨站点调用必须允许 same-origin cookie;生产部署保持 Admin 与 API 同源或由网关代理。
  • 测试必须把登录后的 token 从 cookie 提取,而不是从 response body 读取。
  • Admin 登录/切换品牌/修改密码的 request/response contract 已同步更新到 API Client 和 OpenAPI。
  • Guard 的 decorator metadata 目标是关键契约;错误写入 prototype property metadata 会让 class-level rule 覆盖 method rule,集成测试必须保留 editor 403 case。
  • 新证据必须重新登记 sourceTreeHash,避免沿用旧代码的 template doctor 审计结果。

Migration

一次性切换 Admin browser state 到 /admin/session/current;删除 auth-storage,不再添加兼容读取路径。已有未撤销 token 会随原 token version 过期策略继续失效。