WP2 · API 接鉴权（starter-security 网关前置 + superadmin 门控）

[JIAQIA]

父 Issue：#3（M1 自拆解简报 · 入口级交付）· WP2

目标

消除 API 裸奔：高危端点限平台管理员（superadmin）。控制平面承载跨租户高权操作，上线前须接入鉴权 + 角色门控。

⚠️ 纠偏（对父 Issue WP2 表述）

starter-security 是网关前置鉴权模型，应用不二次校验 token：GatewayPreAuthFilter 据网关下发的 X-User/X-Roles（ROLE_ 前缀）还原 SecurityContext，默认开启即把非放行路径置为 authenticated() 并启用方法级授权。故父 Issue「本地可配 Keycloak Bearer」应理解为网关验 token、应用读头；本仓不接 JWT decoder。

范围（文件清单）

• pom.xml：+ hashmatrix-starter-security（BOM 已管理，零版本号）。
• tenant/web/TenantController.java：高危端点加 @PreAuthorize("hasRole('SUPERADMIN')") —— approve / reject / suspend / resume / delete（跨租户高权变更）。register/list/get 留 authenticated()（或按需把 register 列入 permitPaths，实现者决定）。
• 改现有集成测试（硬约束）：ControlPlaneIntegrationTest、ProvisioningFailureIntegrationTest 现为无鉴权 MockMvc → 加 starter-security 后默认 401。须注入 X-User/X-Roles（或 Spring Security Test user().roles("SUPERADMIN")）使其重新通过。
• 移除/更新 TenantController 顶部「尚未接入认证/鉴权」TODO。

起点（精确路径 + 真/stub/缺失）

• 缺失：依赖、@PreAuthorize 注解、测试鉴权头。
• 现状：tenant/web/TenantController.java:27 TODO 自陈端点未接鉴权；pom.xml 无 starter-security。
• 默认放行路径（starter 内置）：/actuator/health /actuator/info /actuator/prometheus。

预估 LOC

~90–130（依赖 + 5 注解 + 2 测试类改造）。

测试

• 无头 → 401；非 superadmin（X-Roles: USER）→ 高危端点 403；superadmin → 200。
• 探针放行仍 200。
• 现有两个集成测试改造后全绿（main 可消费的前提）。

依赖

• Blocked by：无（可与 WP1/WP4 并行起步）。
• Blocks：M1 自拆解简报 · 入口级交付 #3-WP3（/me/tenants 需本 WP 提供已认证主体）、M1 自拆解简报 · 入口级交付 #3-WP5（安全矩阵）。

可独立 ship

✅ 自带现有测试修复，merge 后 main 编译 + 全测通过、无过渡债。

验收

• 高危端点（approve/reject/suspend/resume/delete）非 superadmin → 403、无头 → 401。
• superadmin → 200。
• 探针 permitPaths 仍放行。
• 现有集成测试全绿。