feat(lib): add auth-kit

docs/INTEGRATION_GUIDE.md

@@ -0,0 +1,115 @@
+# IAM Service 集成基线（接口清单 & 鉴权流程）
+
+本文用于后续其他服务（如 CMS）集成时对齐以下能力基线：
+
+- 租户隔离（Tenant Context / X-Tenant-ID / Token tenant_id 一致性校验）
+- 用户注册/登录/刷新
+- 基础租户管理
+- 基于 JWT 的认证中间件
+- RBAC 权限校验（服务端校验接口）
+
+## 核心 Header/Token 约定
+
+- `Authorization: Bearer <access_token>`
+- `X-Tenant-ID: <tenant_uuid>`
+  - 当请求携带 `Authorization` 时，若同时提供 `X-Tenant-ID`，必须与 JWT claims 内的 `tenant_id` 一致，否则返回 403（`tenant:mismatch`）。
+
+## 接口清单（REST）
+
+### 文档
+
+- `GET /scalar`：Scalar UI
+
+### Auth（公开）
+
+- `POST /tenants/register`：创建租户（初始租户管理员账号由后续 `/auth/register` + 首用户 bootstrap 完成）
+- `POST /auth/register`：用户注册（需要 `X-Tenant-ID`）
+- `POST /auth/login`：用户登录（需要 `X-Tenant-ID`）
+- `POST /auth/refresh`：刷新 access token（refresh token 一次性轮换）
+
+### Tenant（需认证 + 权限）
+
+- `GET /tenants/me`（`tenant:read`）
+- `PATCH /tenants/me`（`tenant:write`）
+- `DELETE /tenants/me`（`tenant:write`）
+- `POST /tenants/me/status`（`tenant:write`）
+
+### Me（需认证）
+
+- `GET /me/permissions`：查询当前用户在当前租户下的权限码列表
+
+### RBAC（供其他服务复用）
+
+- `POST /authorize/check`：服务端校验“当前用户”是否具备指定权限码（用于各业务微服务鉴权复用）
+
+### User（需认证 + 权限）
+
+- `GET /users`
+- `GET /users/{id}`
+- `PATCH /users/{id}`
+- `DELETE /users/{id}`
+- `POST /users/me/password/reset`
+- `POST /users/{id}/password/reset`
+- `GET /users/{id}/roles`
+- `PUT /users/{id}/roles`
+
+### Role（需认证 + 权限）
+
+- `GET /roles`
+- `POST /roles`
+- `GET /roles/{id}`
+- `PATCH /roles/{id}`
+- `DELETE /roles/{id}`
+- `POST /roles/{id}/permissions/grant`
+- `POST /roles/{id}/permissions/revoke`
+- `POST /roles/{id}/users/grant`
+- `POST /roles/{id}/users/revoke`
+
+### Permission（需认证 + 权限）
+
+- `GET /permissions`
+
+### Platform（需认证；平台权限）
+
+- `GET /platform/tenants/{tenant_id}/enabled-apps`
+- `PUT /platform/tenants/{tenant_id}/enabled-apps`
+- `GET /platform/apps`
+- `POST /platform/apps`
+- `GET /platform/apps/{app_id}`
+- `PATCH /platform/apps/{app_id}`
+- `DELETE /platform/apps/{app_id}`
+- `POST /platform/apps/{app_id}/status-change-requests`
+- `GET /platform/app-status-change-requests`
+- `POST /platform/app-status-change-requests/{request_id}/approve`
+- `POST /platform/app-status-change-requests/{request_id}/reject`
+
+## 鉴权流程图（请求 → 认证 → 租户隔离 → 权限校验）
+
+```mermaid
+flowchart TD
+  A[HTTP 请求进入] --> B[trace_http_request: 创建 http.request span]
+  B --> C{是否公开路径?}
+  C -- 是 --> H[进入 Handler]
+  C -- 否 --> D[JWT 认证中间件: Authorization Bearer]
+  D -->|验签/解析失败| E[返回 401]
+  D -->|成功| F[注入 AuthContext<br/>tenant_id/user_id/roles/permissions<br/>并 record span 字段]
+  F --> G[租户解析中间件: resolve_tenant]
+  G -->|缺少 X-Tenant-ID 且 Token 无 tenant| I[返回 400]
+  G -->|X-Tenant-ID 与 Token tenant 不一致| J[返回 403 tenant:mismatch]
+  G -->|成功| K[注入 TenantId 到 extensions 并 record span tenant_id]
+  K --> H
+  H --> L{是否需要 RBAC 权限?}
+  L -- 否 --> M[返回业务响应]
+  L -- 是 --> N[调用 AuthorizationService::require_permission]
+  N -->|无权限| O[返回 403 PermissionDenied]
+  N -->|通过| M
+```
+
+## 集成建议（面向业务微服务）
+
+- 业务服务应直接复用 iam-service 的 JWT 认证中间件与 Tenant 解析中间件，并在业务路由层按以下顺序挂载：
+  - `trace_http_request`（生成请求 span）
+  - `authenticate`（解析 token 并注入 user/tenant 字段到 span）
+  - `resolve_tenant`（统一 TenantId 注入，并校验 X-Tenant-ID 与 token tenant 一致性）
+- 权限校验禁止在业务侧实现一套 RBAC 聚合逻辑；应通过 `POST /authorize/check` 由 IAM 统一裁决。
+