feat: make credential changes replayable

docs/api/authentication.md

@@ -23,7 +23,53 @@ ORBIT_MYSQL_DSN 通过环境注入，命令不读取 .env。所有名称必填
 
 资源、凭据摘要和初始化审计在一个事务中提交。交付文件先写入并同步到磁盘，成功后再提交事务。如果文件写入失败则回滚并移除文件；如果已经交付后提交无法确认，保留文件并报错，应使用其中凭据核对结果，不能直接覆盖或重复创建。
 
-初始文件包含真实秘密，应保管在受限目录或导入秘密管理系统。运行账户与迁移/初始化账户分开；生产只通过 HTTPS 使用凭据。凭据管理 HTTP API、轮换与细粒度运维命令在后续阶段实现，当前 bootstrap 主要用于完成独立接入与开发验证。
+初始文件包含真实秘密，应保管在受限目录或导入秘密管理系统。运行账户与迁移/初始化账户分开；生产只通过 HTTPS 使用凭据。
+
+## 轮换与撤销
+
+凭据轮换和撤销只允许在受保护的数据库管理环境执行，不提供公网管理接口。轮换保留 `credential_id`，因此订阅和 Worker 实例的授权绑定仍指向同一记录；新的 Worker 进程必须按现有进程身份规则重新连接，旧令牌不能再通过任何 API 或 WSS 认证。平台不会批量改写在途任务、交付记录或历史会话证据。
+
+先读取脱敏状态和当前版本：
+
+```sh
+go run ./cmd/orbit-admin credential status \
+  --namespace-id <namespace_id> \
+  --credential-id <credential_id>
+```
+
+状态输出不包含令牌、秘密摘要或权限正文；`revision` 是后续变更的并发条件。
+
+```sh
+go run ./cmd/orbit-admin credential rotate \
+  --namespace-id <namespace_id> \
+  --credential-id <credential_id> \
+  --expected-revision 1 \
+  --valid-for 720h \
+  --reason "scheduled credential rotation" \
+  --output .local/rotated.credentials.json
+```
+
+命令先读取并核对版本，生成一个固定 `operation_id`、令牌和绝对到期时间，写入新的 `0600` 私有操作文件，然后提交数据库事务。文件不得已存在；提交结果不明、网络断开或数据库返回未知错误时必须保留文件，并使用同一个文件执行 `credential apply --file`，不能重新执行 `rotate` 生成第二个秘密。`--valid-for` 限定在 1 小时到 1 年。数据库只保存秘密摘要、请求摘要和脱敏回执。
+
+```sh
+go run ./cmd/orbit-admin credential apply \
+  --file .local/rotated.credentials.json
+```
+
+`apply` 会严格拒绝软链接、非 0600 文件、未知 JSON 字段、重复 JSON 对象和修改过的操作内容。重复应用已提交的文件只返回原回执，回执中的 `deduplicated` 为 `true`，不会重新轮换或新增审计。
+
+发生泄露或 Worker 必须立即停用时执行撤销：
+
+```sh
+go run ./cmd/orbit-admin credential revoke \
+  --namespace-id <namespace_id> \
+  --credential-id <credential_id> \
+  --expected-revision 2 \
+  --output .local/revoke.operation.json \
+  --reason "incident response"
+```
+
+撤销同样先写入固定操作文件，再提交事务；提交不明时用 `credential apply --file .local/revoke.operation.json` 重试。撤销只标记凭据失效，不删除订阅、任务、交付或历史记录。即使应用或命名空间已停用，管理撤销仍可执行。重复应用同一撤销文件只返回原回执，不追加重复审计。审计主体取自 MySQL 管理连接的 `CURRENT_USER()`，审计摘要不包含秘密原文或秘密摘要。
 
 ## 凭据格式与作用域