79 lines
3.6 KiB
Markdown
79 lines
3.6 KiB
Markdown
# platform-auth 鉴权平台适配 crate 说明
|
||
|
||
日期：`2026-04-21`
|
||
|
||
## 1. crate 职责
|
||
|
||
`platform-auth` 是 Rust 工作区中的鉴权平台适配 crate，当前与后续负责：
|
||
|
||
1. Access token JWT 的 claims 结构、签发与校验适配。
|
||
2. refresh cookie 的读写、签名与轮换适配。
|
||
3. 手机验证码发送、校验与外部 provider 适配。
|
||
4. 微信 OAuth start / callback 的平台调用适配。
|
||
5. 供 `module-auth` 与 `crates/api-server` 复用的鉴权基础设施能力。
|
||
|
||
## 2. 当前阶段已落地内容
|
||
|
||
本阶段已经完成 JWT 基础能力首版落地：
|
||
|
||
1. 新增 `JwtConfig`，统一管理 `issuer`、`secret` 与 access token TTL。
|
||
2. 新增 `AccessTokenClaimsInput` 与 `AccessTokenClaims`，把文档中冻结的 `iss/sub/sid/provider/roles/ver/phone_verified/binding_status/display_name` 映射到 Rust 结构。
|
||
3. 新增 `sign_access_token(...)`，按 `HS256` 签发 access token。
|
||
4. 新增 `verify_access_token(...)`，统一校验 `iss/sub/exp/iat` 与 JWT 签名。
|
||
5. 新增 `RefreshCookieConfig`、`RefreshCookieSameSite` 与 `read_refresh_session_token(...)`，统一 refresh cookie 读取口径。
|
||
6. 增加单元测试，覆盖 JWT 回环、issuer 不匹配、空角色拒绝与 refresh cookie 读取。
|
||
|
||
当前阶段仍未进入：
|
||
|
||
1. refresh cookie 写入与轮换。
|
||
2. 短信 provider 适配。
|
||
3. 微信 OAuth 适配。
|
||
4. `module-auth` 领域规则与数据库真相读取。
|
||
|
||
## 3. 本阶段 API
|
||
|
||
当前开放给工作区其它 crate 的最小 API：
|
||
|
||
1. `JwtConfig::new(...)`
|
||
2. `AccessTokenClaims::from_input(...)`
|
||
3. `sign_access_token(...)`
|
||
4. `verify_access_token(...)`
|
||
5. `RefreshCookieConfig::new(...)`
|
||
6. `read_refresh_session_token(...)`
|
||
7. `AuthProvider`
|
||
8. `BindingStatus`
|
||
9. `RefreshCookieSameSite`
|
||
|
||
## 4. 配置口径
|
||
|
||
当前 `api-server` 接入时采用以下环境变量口径：
|
||
|
||
1. `GENARRATIVE_JWT_ISSUER`
|
||
默认值：`https://auth.genarrative.local`
|
||
2. `GENARRATIVE_JWT_SECRET`
|
||
默认值：`genarrative-dev-secret`
|
||
3. `GENARRATIVE_JWT_ACCESS_TOKEN_TTL_SECONDS`
|
||
默认值：`7200`
|
||
4. 兼容读取旧变量：`JWT_ISSUER`、`JWT_SECRET`、`JWT_EXPIRES_IN`
|
||
|
||
说明：
|
||
|
||
1. `JWT_EXPIRES_IN` 当前兼容 `2h`、`30m`、`900` 这类简单时长格式。
|
||
2. 当前阶段保持 `HS256`，优先保证与旧 Node 方案迁移平滑。
|
||
3. refresh cookie 当前采用 `AUTH_REFRESH_COOKIE_NAME`、`AUTH_REFRESH_COOKIE_PATH`、`AUTH_REFRESH_COOKIE_SAME_SITE`、`AUTH_REFRESH_COOKIE_SECURE`、`AUTH_REFRESH_SESSION_TTL_DAYS`。
|
||
4. refresh cookie 默认值与 Node 基线保持一致：`genarrative_refresh_session`、`/api/auth`、`Lax`、`false`、`30` 天。
|
||
|
||
## 5. 边界约束
|
||
|
||
1. `platform-auth` 只承接平台适配，不承接 `module-auth` 的业务规则和状态真相。
|
||
2. `sub` 必须是稳定 `user_id`，`sid` 必须是会话 ID，不能退化为一次 token 的随机 ID。
|
||
3. 不允许把手机号、openid、refresh token hash、风控状态等敏感或高频变化字段塞进 JWT。
|
||
4. 鉴权状态最终由 `module-auth` 与 `crates/spacetime-module` 管理，前端接口由 `crates/api-server` 暴露。
|
||
5. 不允许把短信、微信、Cookie、JWT 等外部细节重新散落到多个业务模块中各自实现。
|
||
|
||
## 6. 关联文档
|
||
|
||
1. [../../../docs/technical/OIDC_JWT_CLAIMS_DESIGN_2026-04-21.md](../../../docs/technical/OIDC_JWT_CLAIMS_DESIGN_2026-04-21.md)
|
||
2. [../../../docs/technical/PLATFORM_AUTH_JWT_ADAPTER_DESIGN_2026-04-21.md](../../../docs/technical/PLATFORM_AUTH_JWT_ADAPTER_DESIGN_2026-04-21.md)
|
||
3. [../../../docs/technical/PLATFORM_AUTH_REFRESH_COOKIE_ADAPTER_DESIGN_2026-04-21.md](../../../docs/technical/PLATFORM_AUTH_REFRESH_COOKIE_ADAPTER_DESIGN_2026-04-21.md)
|