feat: add platform auth jwt adapter

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

@@ -1,34 +1,71 @@
-# platform-auth 平台适配 crate 占位说明
+# platform-auth 鉴权平台适配 crate 说明
 
-日期：`2026-04-20`
+日期：`2026-04-21`
 
 ## 1. crate 职责
 
-`platform-auth` 是鉴权平台适配 crate，后续负责：
+`platform-auth` 是 Rust 工作区中的鉴权平台适配 crate，当前与后续负责：
 
-1. JWT 签发与校验适配
-2. refresh cookie 读写与轮换适配
-3. 手机验证码发送与校验适配
-4. 微信 OAuth 相关平台适配
-5. 供 `module-auth` 与 `crates/api-server` 复用的鉴权基础设施能力
+1. Access token JWT 的 claims 结构、签发与校验适配。
+2. refresh cookie 的读写、签名与轮换适配。
+3. 手机验证码发送、校验与外部 provider 适配。
+4. 微信 OAuth start / callback 的平台调用适配。
+5. 供 `module-auth` 与 `crates/api-server` 复用的鉴权基础设施能力。
 
-## 2. 当前阶段说明
+## 2. 当前阶段已落地内容
 
-当前提交仅完成目录占位，不提前进入 JWT、Cookie、短信与微信平台实现。
+本阶段已经完成 JWT 基础能力首版落地：
 
-后续与本 crate 直接相关的任务包括：
+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. 增加单元测试，覆盖基本签发/校验、issuer 不匹配与空角色拒绝。
 
-1. 落地 JWT claims、签发与校验适配
-2. 落地 refresh cookie 读取、写入与轮换适配
-3. 落地短信发送、校验与风控适配
-4. 落地微信 OAuth start / callback 适配
+当前阶段仍未进入：
 
-当前优先冻结依据：
+1. refresh cookie 读写与轮换。
+2. 短信 provider 适配。
+3. 微信 OAuth 适配。
+4. `module-auth` 领域规则与数据库真相读取。
 
-1. [../../../docs/technical/OIDC_JWT_CLAIMS_DESIGN_2026-04-21.md](../../../docs/technical/OIDC_JWT_CLAIMS_DESIGN_2026-04-21.md)
+## 3. 本阶段 API
 
-## 3. 边界约束
+当前开放给工作区其它 crate 的最小 API：
+
+1. `JwtConfig::new(...)`
+2. `AccessTokenClaims::from_input(...)`
+3. `sign_access_token(...)`
+4. `verify_access_token(...)`
+5. `AuthProvider`
+6. `BindingStatus`
+
+## 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 方案迁移平滑。
+
+## 5. 边界约束
 
 1. `platform-auth` 只承接平台适配，不承接 `module-auth` 的业务规则和状态真相。
-2. 鉴权状态最终由 `module-auth` 与 `crates/spacetime-module` 管理，前端接口由 `crates/api-server` 暴露。
-3. 不允许把短信、微信、Cookie、JWT 等外部细节重新散落到多个业务模块中各自实现。
+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)