feat: support permanent credentials and overlapping token rotation

docs/reports/credential-overlap.md

@@ -0,0 +1,29 @@
+# 长期凭据与平滑换证（2026-09-27）
+
+新建应用与 bootstrap 默认长期 Token，可选有限有效期。已有 Token 支持 SET_EXPIRY 原地修改有效期，原秘密和接入配置保持不变；默认换证保留 7 天过渡，支持按配置调整，确认全部服务切换后可提前 FINALIZE。REVOKE 同时拒绝两代秘密。
+
+## 实现与兼容
+
+- 000032 在 orbit_credentials 增加 previous_secret_digest、previous_valid_until，CHECK 要求成对为空/非空。中文模型与 SQL 注释齐全，当前空库基线为 32，无外键。历史迁移不修改。
+- 认证在原事务共享锁下读取两代摘要及各自截止；HTTP 和 Worker/结果消费复用原认证入口。截止使用数据库时间，不依赖内存、清理任务或节点时钟。
+- 旧代实际截止不晚于其原有效期；重复轮换不会挤掉尚未切换的旧代，调整当前有效期也不会顺带延长旧代。凭据 ID、权限、任务、订阅与交付身份不变。
+- 管理操作、版本、固定过渡截止、审计及幂等回执同事务。格式 v2 新增长期和过渡语义，历史 v1 仍按原固定到期/立即轮换恢复；重放历史轮换不复活已经停用的旧代。
+- 管理端增加长期选项、调整有效期、平滑换证及结束过渡；CLI 增加 expiry/finalize、默认 --valid-for 0 和轮换 --grace 168h。没有修改 SDK 接口或 Token 格式。
+
+## 验证
+
+| 验证 | 证据 |
+| --- | --- |
+| 标准回归 | `make test vet build` 七模块竞态测试、静态检查和构建通过 |
+| 原 Token 改长期与在途执行 | `TestIntegrationCredentialOverlap`：运行中的任务原凭据改长期后继续授权；换证期间旧 Token 续租、完成结果、释放许可；两代认证、并发原操作去重、重复轮换冲突、结束过渡、历史重报、两代撤销及审计脱敏通过 |
+| 期限与旧代隔离 | `TestIntegrationCredentialOverlapDeadline`：不超过旧有效期、两代独立到期、到期无需清理即可拒绝、下一轮不复活更旧秘密通过；时间边界由隔离测试库明确设置，不把测试耗时当作长期运行证据 |
+| 双节点真实 WS | `TestIntegrationCredentialOverlapWebSocket`：两个 HTTP/WS 节点共享真实 MySQL；原长连接在轮换后可发控制命令，旧 Token 可跨节点重连，新 Token 同时连接；结束过渡后旧连接命令和新握手被拒绝，新连接继续可用 |
+| 提交结果未知 | `TestIntegrationCredentialCommitFaults`：COMMIT 前截断及数据库提交成功后丢确认；旧 Token 始终可用，新 Token 只在实际提交后生效，原操作核对恢复 |
+| 管理 HTTP | `scripts/test-console-applications.py`：真实 Cookie 管理、CSRF、定期改长期且原 Token 200、双 Token 过渡、提前结束、旧 Token 401、新 Token 200、历史回执不能复活旧秘密、原任务/订阅读取和退出失效通过 |
+| 容器端到端 | `make console-e2e` 全新 MySQL/Orbit、上述管理链路、原登录/Worker/重试/定时/归档验收通过 |
+
+## 使用边界
+
+调用方在截止前完成滚动更新并正常收尾在途任务。SDK 在创建客户端时读取 Token，改 `.env` 不会热更新现有客户端；须重建客户端或逐台重启服务。单实例重启仍有短暂停顿，平台不能替业务服务保证副本容量。提前结束过渡或到期会拒绝尚未切换的旧 Token，不承诺强行停用旧身份后其连接还能继续工作。
+
+这次数据库升级完成且所有 Orbit 节点更新后才能启用双 Token 换证；旧版本节点不认识上一代摘要。只修改有授权的本地测试凭据为长期，迁移不会自动延长其他已有凭据。完整操作顺序见[凭据手册](../api/authentication.md)和[管理接口](../api/console-applications.md)。