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

34 lines
2.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 过期策略继续失效。