iam-service/docs/SECURITY_GOVERNANCE.md

安全评估与接口治理建议（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）而不仅是逻辑权限校验。