Prune stale docs and update .hermes content
Delete a large set of outdated documentation (many files under docs/ and .hermes/plans/, including audits, design, prd, technical, planning, assets, and todos). Update and consolidate .hermes content: refresh shared-memory pages (decision-log, development-workflow, document-map, pitfalls, project-overview, team-conventions) and several skills/references under .hermes/skills. Also modify AGENTS.md, README.md, UI_CODING_STANDARD.md, docs/README.md and .encoding-check-ignore. Purpose: clean up stale planning/audit material and keep current hermes documentation and related top-level docs in sync.
This commit is contained in:
@@ -1,173 +0,0 @@
|
||||
# platform-auth refresh cookie 适配设计
|
||||
|
||||
日期：`2026-04-21`
|
||||
|
||||
## 1. 文档目的
|
||||
|
||||
这份文档用于指导 `M2` 中“实现 refresh cookie 读取”这条任务落地，目标是先把 refresh cookie 的读取边界、配置口径与 `api-server` 的最小接线固定下来。
|
||||
|
||||
本阶段只解决：
|
||||
|
||||
1. `platform-auth` 如何统一读取 refresh cookie。
|
||||
2. `api-server` 如何把读取结果挂到请求上下文。
|
||||
|
||||
本阶段不解决：
|
||||
|
||||
1. refresh token 轮换。
|
||||
2. refresh session 吊销。
|
||||
3. refresh cookie 写回浏览器。
|
||||
|
||||
## 2. 设计输入
|
||||
|
||||
本任务直接受以下文档约束：
|
||||
|
||||
1. [SPACETIMEDB_REFRESH_SESSION_TABLE_DESIGN_2026-04-21.md](./SPACETIMEDB_REFRESH_SESSION_TABLE_DESIGN_2026-04-21.md)
|
||||
2. [SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md](./SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md)
|
||||
|
||||
关键冻结点：
|
||||
|
||||
1. 浏览器 cookie 只存原始 refresh token。
|
||||
2. 服务端真相表只存 `sha256(refresh_token)`。
|
||||
3. cookie 名默认是 `genarrative_refresh_session`。
|
||||
4. cookie `Path` 默认是 `/api/auth`。
|
||||
5. 默认 `SameSite=Lax`。
|
||||
|
||||
## 3. crate 边界
|
||||
|
||||
### 3.1 `platform-auth`
|
||||
|
||||
负责：
|
||||
|
||||
1. 统一 refresh cookie 配置结构。
|
||||
2. 统一 cookie 名、Path、SameSite、Secure、TTL 的平台配置。
|
||||
3. 从 `Cookie` 请求头解析当前 refresh token。
|
||||
|
||||
不负责：
|
||||
|
||||
1. 直接操作 `Set-Cookie` 响应头。
|
||||
2. 决定请求是否应该被视为已登录。
|
||||
3. 访问 `refresh_session` 真相表。
|
||||
|
||||
### 3.2 `api-server`
|
||||
|
||||
负责：
|
||||
|
||||
1. 从环境变量读取 refresh cookie 配置。
|
||||
2. 在启动时构造唯一一份 `RefreshCookieConfig`。
|
||||
3. 在请求链中读取 refresh cookie 并挂到 request extensions。
|
||||
4. 为阶段验收提供最小内部调试入口。
|
||||
|
||||
不负责：
|
||||
|
||||
1. 重写一套独立 cookie 解析逻辑。
|
||||
2. 在这一步直接实现 `/api/auth/refresh`。
|
||||
|
||||
## 4. 配置口径
|
||||
|
||||
当前阶段 `api-server` 读取以下环境变量：
|
||||
|
||||
| 配置项 | 环境变量 | 默认值 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| cookie 名 | `AUTH_REFRESH_COOKIE_NAME` | `genarrative_refresh_session` | 读取 refresh cookie 时匹配的键名。 |
|
||||
| cookie path | `AUTH_REFRESH_COOKIE_PATH` | `/api/auth` | 当前阶段只用于冻结配置口径。 |
|
||||
| cookie secure | `AUTH_REFRESH_COOKIE_SECURE` | `false` | 当前阶段只读配置，不在读取路径参与判断。 |
|
||||
| cookie same-site | `AUTH_REFRESH_COOKIE_SAME_SITE` | `Lax` | 固定枚举为 `Lax`、`Strict`、`None`。 |
|
||||
| session TTL 天数 | `AUTH_REFRESH_SESSION_TTL_DAYS` | `30` | 当前阶段只读配置，不参与读取判断。 |
|
||||
|
||||
说明：
|
||||
|
||||
1. 这组变量直接对齐当前 Node 口径。
|
||||
2. 本阶段读取链路只真正依赖 `cookie_name`，其余配置主要用于冻结统一初始化边界。
|
||||
|
||||
## 5. Rust 结构设计
|
||||
|
||||
### 5.1 `RefreshCookieSameSite`
|
||||
|
||||
用途：
|
||||
|
||||
1. 避免不同 crate 手写 `Lax` / `Strict` / `None` 字符串。
|
||||
2. 在启动阶段尽早拒绝非法配置。
|
||||
|
||||
### 5.2 `RefreshCookieConfig`
|
||||
|
||||
字段：
|
||||
|
||||
1. `cookie_name`
|
||||
2. `cookie_path`
|
||||
3. `cookie_secure`
|
||||
4. `cookie_same_site`
|
||||
5. `refresh_session_ttl_days`
|
||||
|
||||
约束：
|
||||
|
||||
1. `cookie_name` 不能为空。
|
||||
2. `cookie_path` 不能为空。
|
||||
3. `refresh_session_ttl_days` 必须大于 `0`。
|
||||
|
||||
## 6. 读取规则
|
||||
|
||||
`read_refresh_session_token(cookie_header, config)` 固定按以下规则工作：
|
||||
|
||||
1. 若 `Cookie` 头为空，返回 `None`。
|
||||
2. 按 `;` 分割各 cookie 项。
|
||||
3. 只匹配与 `config.cookie_name` 完全相等的键名。
|
||||
4. 若匹配项值为空，返回 `None`。
|
||||
5. 对匹配值执行 URL decode。
|
||||
6. decode 成功则返回原始 refresh token，失败则返回 `None`。
|
||||
|
||||
说明：
|
||||
|
||||
1. 当前阶段读取逻辑只做“解析”，不做权限判断。
|
||||
2. 请求是否能继续 refresh，要在后续应用层结合 `refresh_session` 真相表判断。
|
||||
|
||||
## 7. api-server 最小接线
|
||||
|
||||
本阶段 `api-server` 只做三件事：
|
||||
|
||||
1. `AppConfig` 增加 refresh cookie 配置。
|
||||
2. `AppState` 启动时构造 `RefreshCookieConfig`。
|
||||
3. `attach_refresh_session_token` 中间件从请求头读取 cookie，并把结果以 `RefreshSessionToken` 写入 request extensions。
|
||||
|
||||
阶段验收入口：
|
||||
|
||||
1. `/_internal/auth/refresh-cookie`
|
||||
|
||||
该入口仅返回：
|
||||
|
||||
1. `cookieName`
|
||||
2. `present`
|
||||
3. `tokenLength`
|
||||
|
||||
说明：
|
||||
|
||||
1. 当前不回显原始 refresh token，避免把敏感值直接暴露到响应体中。
|
||||
2. `tokenLength` 只用于阶段测试与调试，不是最终对外 contract。
|
||||
|
||||
## 8. 测试策略
|
||||
|
||||
当前阶段至少覆盖：
|
||||
|
||||
1. 纯函数能正确提取目标 cookie。
|
||||
2. URL 编码的 cookie 值能正确解码。
|
||||
3. 缺少目标 cookie 时返回空。
|
||||
4. `api-server` 在无 cookie 时能返回 `present = false`。
|
||||
5. `api-server` 在有 cookie 时能返回 `present = true`。
|
||||
|
||||
## 9. 完成定义
|
||||
|
||||
满足以下条件时，本任务视为完成：
|
||||
|
||||
1. `platform-auth` 中存在真实可编译的 refresh cookie 配置与读取逻辑。
|
||||
2. `api-server` 已接入统一 refresh cookie 配置。
|
||||
3. 请求链已能读取 cookie 并挂到 extensions。
|
||||
4. 编译与测试通过。
|
||||
5. 任务清单已同步更新。
|
||||
|
||||
## 10. 后续衔接
|
||||
|
||||
这条任务完成后，下一步继续衔接：
|
||||
|
||||
1. refresh token 哈希与 `refresh_session` 表查询。
|
||||
2. refresh token 轮换。
|
||||
3. `/api/auth/refresh` 正式接口。
|
||||
4. `/api/auth/logout`、`/api/auth/logout-all` 的会话吊销。
|
||||
Reference in New Issue
Block a user