refactor: 收口 Admin 会话与授权边界
This commit is contained in:
1 parent
0788480ce3
commit
4ef4be2071
67 files changed
+1890
-392
No files matched your search
@@ -0,0 +1,33 @@
|
||||
# 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 过期策略继续失效。
|
||||
+39
-10
@@ -122,15 +122,30 @@ paths:
|
||||
$ref: "#/components/schemas/AdminLogin"
|
||||
responses:
|
||||
"201":
|
||||
description: Admin session token
|
||||
description: Admin session created; the access token is set as an HttpOnly cookie
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/AdminTokenResponse"
|
||||
$ref: "#/components/schemas/AdminLoginSession"
|
||||
/admin/session/current:
|
||||
get:
|
||||
operationId: getAdminSession
|
||||
security:
|
||||
- cookieAuth: []
|
||||
- bearerAuth: []
|
||||
responses:
|
||||
"200":
|
||||
description: Current admin session
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/AdminSession"
|
||||
/admin/session/logout:
|
||||
post:
|
||||
operationId: logoutAdmin
|
||||
security: [bearerAuth: []]
|
||||
security:
|
||||
- cookieAuth: []
|
||||
- bearerAuth: []
|
||||
responses:
|
||||
"201":
|
||||
description: Admin session revoked
|
||||
@@ -256,6 +271,10 @@ components:
|
||||
bearerAuth:
|
||||
type: http
|
||||
scheme: bearer
|
||||
cookieAuth:
|
||||
type: apiKey
|
||||
in: cookie
|
||||
name: admin_session
|
||||
parameters:
|
||||
BookingId:
|
||||
in: path
|
||||
@@ -353,13 +372,23 @@ components:
|
||||
required: [loggedOut]
|
||||
properties:
|
||||
loggedOut: { type: boolean, enum: [true] }
|
||||
AdminTokenResponse:
|
||||
allOf:
|
||||
- $ref: "#/components/schemas/TokenResponse"
|
||||
- type: object
|
||||
required: [displayName]
|
||||
properties:
|
||||
displayName: { type: string }
|
||||
AdminSession:
|
||||
type: object
|
||||
required: [authenticated, displayName, mustChangePassword, role, platformTemplateRole]
|
||||
properties:
|
||||
authenticated: { type: boolean, enum: [true] }
|
||||
displayName: { type: string }
|
||||
mustChangePassword: { type: boolean }
|
||||
role: { type: string }
|
||||
platformTemplateRole: { type: string, enum: [none, template_admin] }
|
||||
AdminLoginSession:
|
||||
type: object
|
||||
required: [displayName, mustChangePassword, role, platformTemplateRole]
|
||||
properties:
|
||||
displayName: { type: string }
|
||||
mustChangePassword: { type: boolean }
|
||||
role: { type: string }
|
||||
platformTemplateRole: { type: string, enum: [none, template_admin] }
|
||||
UpdateBookingStatus:
|
||||
type: object
|
||||
required: [status]
|
||||
|
||||
Reference in new issue
Block a user