# SSF/CAEP 实时会话撤销运行手册

Gateway 可选接收 Auth Center 通过 RFC 8935 Push 投递的 RFC 8417 Security Event Token，并处理 OpenID CAEP `session-revoked`。默认关闭；关闭时不会注册接收路由或启动状态机，也不会改变 OIDC、BFF、API Key 或 Legacy JWT 行为。

## 启用前提

- Auth Center 已创建属于当前 Application/租户的 paused Stream，Audience 为 `urn:easyai:ssf:receiver:{application-public-id}`。
- Gateway OIDC `iss`、`tid` 与 Stream 绑定完全一致；Stream ID 为公开 UUID，不使用认证内核 ID。
- 接收 Bearer、Management Client Secret、RFC 7662 Client Secret 仅从 Git 忽略的 `.env`、Kubernetes Secret 或 Secret Manager 注入。
- `OIDC_SECURITY_EVENTS_PUBLIC_ENDPOINT` 必须是外部可访问的精确 HTTPS 地址；本地测试环境才允许 localhost HTTP。
- Management Client 至少有 `ssf.stream.read ssf.stream.verify`，不能使用浏览器 PKCE Client。

完整配置键见仓库根目录 `.env.example`。启用时 `OIDC_SECURITY_EVENTS_ENABLED=true`，且 RFC 7662 Client ID/Secret 必须同时存在，否则启动失败。

## 启用顺序

1. 运行数据库迁移，部署仍保持功能关闭。
2. 在 Secret Store 创建接收 Bearer、Management Client Secret 和内省 Client Secret；不要把值放进日志或工单。
3. 启用 Gateway。启动模式为 `bootstrap`，所有 OIDC Token 都先内省。
4. 在 Auth Center 对 paused Stream 发起 Verification，确认 Gateway 返回空 Body 的 `202`。
5. 启用 Stream。首次 Verification 成功后仍内省 360 秒，覆盖启用前已签发的最长 300 秒 Token。
6. 观察 `easyai_gateway_ssf_mode{mode="push_healthy"}` 变为 1，再执行测试用户撤销。

健康时 Gateway 每 60 秒请求一次 Verification，不按业务 QPS 请求 Auth Center。180 秒没有匹配的有效 Verification 会进入 `introspection_fallback`；只有最近收到的 Stream 状态为 `enabled` 时，连续两次 Verification 成功才会恢复，`paused`/`disabled` 状态下心跳不会错误恢复推送信任。降级期间内省不可用会对 OIDC 返回可审计的 503，API Key 继续工作。

## 零停机 Bearer 轮换

1. 在 Gateway 写入 `OIDC_SECURITY_EVENTS_BEARER_SECRET_NEXT`，同时接受 current/next。
2. 更新 Auth Center 的 Stream `credential_ref` 指向 next。
3. 发起 Verification，并确认投递和状态机健康。
4. 等待至少 180 秒后，将 next 提升为 current 并清空旧值。

Gateway 使用常量时间比较两个值。响应、日志、审计和指标都不得包含 Authorization Header 或原始 SET。

## 监控与告警

`GET /metrics` 输出以下低基数指标；生产入口应仅允许监控网络访问该路径：

- `easyai_gateway_ssf_receipts_total{outcome}`：accepted/rejected/duplicate。
- `easyai_gateway_ssf_sessions_deleted_total`：被撤销删除的 BFF Session。
- `easyai_gateway_ssf_watermark_rejections_total`：本地水位拒绝的 Token。
- `easyai_gateway_ssf_processing_duration_seconds`：Receiver 数据库事务处理直方图，用于 P99 告警。
- `easyai_gateway_ssf_verification_age_seconds` 和 `easyai_gateway_ssf_mode{mode}`。
- `easyai_gateway_ssf_heartbeat_requests_total{outcome}`。
- `easyai_gateway_oidc_introspection_total{outcome}`。
- `easyai_gateway_jwks_refresh_failures_total{source}`：SSF/OIDC JWKS 刷新失败。

至少配置以下告警：Verification age 超过 120 秒、fallback 超过 5 分钟、内省 failed 增长、SET rejected 增长、撤销端到端 P99 超过 3 秒。日志只能携带脱敏 Trace ID、Audit ID 和错误类别。

## 回滚

先在 Auth Center 暂停 Stream，再保持 Gateway 启用但持续使用 RFC 7662，确认没有遗漏撤销后才关闭接收功能。保留迁移表和 Secret，不做破坏性数据库回滚。Legacy HS256 Token 和 API Key 不在本协议撤销范围内。

## 验收证据

真实链路验收只能使用明确标记为测试用途的 Application，且必须在自动化测试通过后执行。报告需包含脱敏 Trace、Claims 结构、截图、Audit ID、投递延迟、fallback 与恢复证据。涉及人工、真实设备或第三方操作时记录 `SKIPPED_HUMAN_OR_THIRD_PARTY_REQUIRED`，Mock、契约和安全测试不得跳过。