XHIM 凭证轮换与网络故障矩阵

1. 密钥和 Token 轮换

XHIM 服务端 JWT 使用 Ed25519 kid 选择验证密钥。TokenManager 同时保留一个 活动签名私钥和最多八个只读公钥；相同 kid 不允许替换成不同密钥。客户端 Endpoint Bundle 验证也使用最多八个不可变公钥，避免服务端切换后旧 SDK 立即 失联。

正式轮换必须分三阶段：

1. 扩展信任环：离线生成新 Ed25519 密钥；把新公钥加入所有服务端 XHIM_SIGNING_VERIFY_KEYS_BASE64，并把 XHIM_REFERENCE_SIGNING_VERIFY_KEYS 编进新客户端制品。此时仍由旧私钥签名。
2. 切换签名：所有验证方都接受新 kid 后，把服务端 XHIM_SIGNING_KEY_ID 和 XHIM_SIGNING_PRIVATE_KEY_BASE64 切到新密钥，滚动 发布。旧公钥继续保留。
3. 退役旧密钥：至少等待“最大 Token 有效期 + 15 秒校验容差 + 最长滚动 发布/离线客户端重试窗口”，确认旧 kid 已无验签流量，再从服务端和下一版 客户端信任环移除。

私钥只允许来自 KMS/Secret Manager 注入，不能写入 .env、镜像、日志或发布 证据。轮换演练必须证明旧 Token 在重叠窗口仍可用、新 Token 使用新 kid、未知 kid 被拒绝、活动密钥不能退役。

2. 用户凭证刷新

网络返回 401/403 或 Adapter 报告 credential_required 时，Core 进入 CREDENTIAL_REQUIRED，停止发送 Worker，不把普通业务失败当成重新登录。 业务从自有鉴权服务获取新 Token 后调用 updateCredential；账号 Epoch 不变， 但 credential generation 增长，旧请求结果会被丢弃。刷新失败时保持本地 Outbox，不得清库或换号。

五个原生 OS 的 Facade 默认 Business Authentication 会安装一个账号会话级 Credential Provider，并自动完成首次获取、同代 Single Flight 和 updateCredential。手工更新只用于固定 Token、Provider 恢复或高级宿主编排； 页面和消息 Cell 不得自行获取或保存 Token。

3. 网络故障决策矩阵

故障	处置	自动重试	Retry-After
主动取消	retryable completion，仅结束本次请求	由调用方决定	保留
离线、DNS、连接超时	retryable	是，有限退避	保留
网关不可用、内部传输错误	retryable	是，有限退避	保留
401/403、凭证缺失	credential required	否，先刷新凭证	保留
TLS/证书错误	permanent	否	清零
协议错误、超限响应	permanent	否	清零
业务拒绝	permanent	否	清零
HTTP 408/425/429/500/502/503/504	retryable	是	保留
其他非 2xx	permanent	否	清零
无状态码且无明确网络错误	invalid response / permanent	否	清零

任何重试都受最大次数、最大延迟、账号 Epoch 和 credential generation 约束。 TLS 错误不得通过关闭证书校验“修复”。正式黑盒矩阵还必须在真实网络环境执行 DNS 污染、证书过期、代理断流、切 Wi-Fi/蜂窝、前后台恢复、429 和 5xx。

Realtime Session 的重连采用独立的有限预算：首次断线立即尝试一次，后续失败 使用 capped exponential Full Jitter（uniform(0, exponential_cap)）。 Backend 的 retry_after_ms 是最早重试下限；负值按零处理，超过 reconnect_max_delay_ms 时截断到该上限，最终延迟取 Jitter 与该下限的较大值。 默认随机种子来自系统熵并混入进程内唯一序列；只有可重复故障测试才应配置非零 reconnect_random_seed。恢复 Sync 到达 high watermark 后不会立即清零尝试 次数，连接还必须持续健康达到 reconnect_stable_window_ms；窗口内再次断开会 保留已消耗预算，避免短周期抖动无限续命。配置的 operation timeout、退避、 稳定窗口和尝试次数均有 Core 强制上限，越界配置会在 Coordinator 构造时拒绝。

平台网络监控可在线程安全地调用稳定 C API xhim_v1_client_notify_network_available()；C++ Product Adapter 内部对应 SessionCoordinator::notify_network_available()。提示只会唤醒当前 epoch / generation 且正处于 WaitingToReconnect 的 Session，取消其现有 timer 后进入 同一 Runtime retry transition；当前没有待重连任务时成功返回并保持 no-op。 重复提示幂等，不能绕过最大次数、凭证、TLS/协议安全、logout 或 shutdown fence。旧 timer 即使已经投递，也会被 stage token 和连接 fence 丢弃。