feat: enforce trusted session identity

docs/refactor/multitenant-auth-security-contract.md

@@ -17,13 +17,16 @@
 
 ## 当前迁移期状态
 
-当前后端仍存在这些迁移期实现：
+当前后端已经进入“session 优先、迁移头受控兼容”的状态：
 
-- `x-tenant-id` 用于租户上下文。
-- `x-user-id` 或 body/query 的 `userId` 用于用户上下文。
-- `x-platform-admin-key` 用于平台管理员接口。
+- `Authorization: Bearer <tk_session>` 会优先解析 `app_private.auth_sessions`，并作为用户身份来源。
+- 登录后如果请求中的 `x-user-id`、query/body `userId` 与 session 用户不一致，后端返回 `AUTH_USER_MISMATCH`。
+- 登录后如果请求中的 `x-tenant-id` 与 session 租户不一致，后端返回 `AUTH_TENANT_MISMATCH`。
+- 带了无效 bearer token 的用户态接口不会回退到 `x-user-id`。
+- `x-user-id` 或 body/query 的 `userId` 只允许在 `ALLOW_LEGACY_AUTH_HEADERS=true` 的本地/迁移期环境使用。
+- `x-platform-admin-key` 只允许在 `ALLOW_PLATFORM_ADMIN_KEY=true` 的本地/迁移期环境使用。
 - 本地短信 provider 可使用 `mock`。
-- 默认开发密钥存在于 `.env.example` 和 config fallback。
+- `NODE_ENV=production` 下禁止 `ALLOW_LEGACY_AUTH_HEADERS=true`、`ALLOW_PLATFORM_ADMIN_KEY=true`、`AUTH_SMS_PROVIDER=mock`、默认/弱密钥和 `CORS_ORIGIN=*`。
 
 这些只允许用于本地开发和内网联调，不允许作为正式云端验收方案。
 
@@ -32,9 +35,10 @@ Supabase 官方允许前端用 Data API 访问数据，但前提是 RLS、最小
 ## P0：正式云端测试前必须完成
 
 1. 正式用户鉴权
-   - 使用 Supabase Auth/JWT 或服务端 session 解析可信 userId。
-   - 禁止前端通过 query/body/header 指定 userId。
-   - `GET /api/auth/me` 返回当前用户、租户成员、角色、权限。
+   - 已支持服务端 session 解析可信 userId。
+   - 生产前继续接 Supabase Auth/JWT，或将现有 server session 明确作为正式方案。
+   - 前端禁止通过 query/body/header 指定 userId。
+   - `GET /api/auth/me` 后续要补租户成员、角色、权限返回。
 
 2. 正式租户上下文
    - H5 可由域名解析租户。
@@ -43,7 +47,8 @@ Supabase 官方允许前端用 Data API 访问数据，但前提是 RLS、最小
    - 跨租户请求必须返回 403 或 404。
 
 3. 平台管理员鉴权
-   - 替换 `x-platform-admin-key`。
+   - `x-platform-admin-key` 已可通过 `ALLOW_PLATFORM_ADMIN_KEY=false` 禁用。
+   - 生产前仍需替换为平台管理员 JWT/session 和审计日志。
    - 平台管理员也要有 JWT/session、角色、审计日志。
 
 4. 生产配置 fail-fast
@@ -52,6 +57,8 @@ Supabase 官方允许前端用 Data API 访问数据，但前提是 RLS、最小
    - 禁止默认 `PLATFORM_ADMIN_API_KEY`。
    - 禁止 `CORS_ORIGIN=*`。
    - 禁止 `AUTH_SMS_PROVIDER=mock`。
+   - 禁止 `ALLOW_LEGACY_AUTH_HEADERS=true`。
+   - 禁止 `ALLOW_PLATFORM_ADMIN_KEY=true`。
 
 5. 请求体大小限制
    - 普通 JSON API 必须有默认上限。