# 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)