# 安全评估与接口治理建议（IAM Service）

本文面向本仓库当前实现，给出“暴露面审查、风险识别、接口分级、敏感操作二次验证、隐藏策略”建议，并标注已落地的控制点。

## 1) 当前接口暴露面概览（按访问级别）

### 公开接口（Public）

特点：无需 Bearer Token；可被外部直接调用（应最小化）。

- `POST /tenants/register`：创建租户
- `POST /auth/register`：租户内注册用户（依赖 Header `X-Tenant-ID`）
- `POST /auth/login`：租户内登录（依赖 Header `X-Tenant-ID`）
- `GET /scalar`：OpenAPI/Scalar 文档

### 认证接口（Authenticated）

特点：要求 Bearer Token；应默认通过网关/WAF 暴露。

- `GET /tenants/me`、`PATCH /tenants/me`、`DELETE /tenants/me`
- `POST /tenants/me/status`
- `GET /me/permissions`
- `GET/PATCH/DELETE /users...`、`GET/PUT /users/{id}/roles`
- `GET/POST /roles`

### 内部/平台接口（Internal / Platform）

特点：平台权限（系统角色）才能访问，建议网关层做更严格限制（IP allowlist、mTLS、独立域名等）。

- `GET/PUT /platform/tenants/{tenant_id}/enabled-apps`
- `GET/POST /platform/apps`、`GET/PATCH/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|reject`

## 2) 风险识别（重点）

- **租户创建为公开接口**：可能被滥用批量创建租户，造成资源耗尽、审计噪声、后续越权风险面扩大。
- **注册为公开接口**：对任意租户 ID 可注册用户（虽然要求 `X-Tenant-ID`，但租户 ID 可被枚举/泄露）。
- **平台接口暴露风险**：即便有平台权限控制，一旦 token 泄露将影响全局（enabled_apps 与 apps 注册表）。
- **文档暴露**：`/scalar` 默认公开，可能暴露内部接口与参数细节。

## 3) 已落地控制点（本次实现）

- **敏感操作二次验证（可选开关）**
  - 通过环境变量 `IAM_SENSITIVE_ACTION_TOKEN` 启用二次验证。
  - 当启用时，下列操作必须额外携带 Header `X-Sensitive-Token: <token>`：
    - `POST /tenants/register`
    - `DELETE /platform/apps/{app_id}`
  - 目的：降低“单一 Bearer Token 泄露”或“误调用”带来的破坏面。

- **平台权限细分**
  - apps 生命周期管理引入平台权限码：`iam:app:read|write|approve|delete`
  - enabled_apps 管理权限码：`iam:tenant:enabled_apps:read|write`

## 4) 建议的接口分级制度（治理）

建议把接口按“公开 / 认证 / 内部平台”分级，并在网关与代码侧同时落实：

- Public（公开）
  - 强制：限流、验证码/人机校验（可选）、IP 风控、灰度开关、审计
  - 建议：对 `tenants/register` 改为“邀请制/工单制”，或迁移到平台后台

- Authenticated（认证）
  - 强制：最小权限、全链路审计、错误码统一、分页上限、输入校验

- Internal / Platform（内部）
  - 强制：网关层隔离（独立域名/路由、mTLS 或 IP allowlist）、更严格限流、短 TTL token、专用账号
  - 建议：默认不在公开文档展示（需要登录后才能看到或独立文档入口）

## 5) 接口隐藏策略建议（不改变业务语义）

- 网关层
  - 路由隔离：`/platform/*` 走独立 upstream 或仅内网可达
  - 访问控制：IP allowlist、mTLS、JWT audience/issuer 分离
  - 速率限制：对平台接口与租户创建设置更低阈值

- 版本管理
  - 对内部平台接口采用独立版本前缀：如 `/platform/v1/...`
  - 对外接口保持稳定；内部接口可快速迭代

- 文档权限
  - 将 `/scalar` 拆分为 public 与 internal 两份，或对 internal 文档加登录保护

## 6) 下一步改造建议（按风险优先级）

1. 将 `POST /tenants/register` 从公开接口迁移为平台接口（或邀请制），并引入更强风控。
2. 对 `POST /auth/register` 引入租户级注册策略（开关、邀请、允许域名白名单等）。
3. 对 `/platform/*` 接口在网关实现“物理隔离”（内网 + mTLS）而不仅是逻辑权限校验。