Genarrative/server-rs/crates/platform-auth/README.md

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
2. ../../../docs/technical/PLATFORM_AUTH_JWT_ADAPTER_DESIGN_2026-04-21.md
3. ../../../docs/technical/PLATFORM_AUTH_REFRESH_COOKIE_ADAPTER_DESIGN_2026-04-21.md