feat: support permanent credentials and overlapping token rotation

2026-09-27 11:45:15 +08:00
parent 87aa710013
commit 385a618154
29 changed files with 718 additions and 161 deletions
--- a/docs/api/authentication.md
+++ b/docs/api/authentication.md
@@ -2,7 +2,7 @@

 状态：P1 已实现。业务接口每次在数据库事务内校验凭据摘要、撤销/到期、应用与命名空间启停，以及动作和队列范围。授权与写入使用同一事务；管理变更与已经获得授权锁的请求按事务先后次序生效。

-已提供单管理员[应用接入页面](console-applications.md)：新建应用、查看队列与凭据、重新生成 Token、复制 SDK 配置。下方 CLI 继续用于首次安装及运维。
+已提供单管理员[应用接入页面](console-applications.md)：新建应用、查看队列与凭据、长期凭据、调整有效期、平滑换证、复制 SDK 配置。下方 CLI 继续用于首次安装及运维。

 ## 初始化一个新的接入应用

@@ -21,7 +21,7 @@ go run ./cmd/orbit-admin bootstrap \

 ORBIT_MYSQL_DSN 通过环境注入，命令不读取 .env。所有名称必填，以字母/数字开头，后续允许字母、数字、`_ . : -`；environment 最长 32，其余最长 128。输出文件必须不存在，以 0600 创建；原始凭据不会打印到 stdout/stderr。`.local/` 和 `*.credentials.json` 已被 Git 忽略。

-输出 JSON 包含 application_id / namespace_id / queue_id / credential_id / token / expires_at。初始凭据有效期为 30 天，权限包括当前命名空间内的五个 P1 动作和全部队列。初始队列 max_concurrency=4、rate_per_second=10、max_unfinished_tasks=100000；并发、开始限速与积压背压已生效，语义及管理方式见 [队列接口](queues.md)。这些默认值是开发基线，不是容量承诺。
+输出 JSON 包含 application_id / namespace_id / queue_id / credential_id / token，可选 expires_at。初始凭据默认长期有效（expires_at 省略），可用 `--valid-for 720h` 显式选择 30 天；0 表示长期，其他值为 1 小时至 365 天。权限包括当前命名空间内的五个 P1 动作和全部队列。初始队列 max_concurrency=4、rate_per_second=10、max_unfinished_tasks=100000；并发、开始限速与积压背压已生效，语义及管理方式见 [队列接口](queues.md)。这些默认值是开发基线，不是容量承诺。

 如果希望在第一次初始化时同时创建控制台管理员，可在同一条 bootstrap 事务中提供账号，并从标准输入交付密码：

@@ -46,7 +46,7 @@ secret-manager read orbit/console-admin-password | \

 ## 轮换与撤销

-管理 CLI 在受保护的数据库管理环境执行；控制台也可由部署指定的单管理员轮换凭据，见[应用接入](console-applications.md)。业务 SDK 不开放凭据管理，撤销仍由 CLI 执行。轮换保留 `credential_id`，因此订阅和 Worker 实例的授权绑定仍指向同一记录；新的 Worker 进程必须按现有进程身份规则重新连接，旧令牌不能再通过任何 API 或 WSS 认证。平台不会批量改写在途任务、交付记录或历史会话证据。
+管理 CLI 在受保护的数据库管理环境执行；控制台也可由部署指定的单管理员轮换凭据，见[应用接入](console-applications.md)。业务 SDK 不开放凭据管理，撤销仍由 CLI 执行。轮换保留 `credential_id`，因此订阅和 Worker 实例的授权绑定仍指向同一记录；新进程仍遵循原 Worker 身份规则；过渡期内旧 Token 的 API 请求、原 WS 控制命令及跨节点重连都继续有效。新 Token 立即可用，结束过渡或超过截止后旧 Token 才被拒绝。平台不会批量改写在途任务、交付记录或历史会话证据。

 先读取脱敏状态和当前版本：

@@ -63,12 +63,13 @@ go run ./cmd/orbit-admin credential rotate \
  --namespace-id <namespace_id> \
  --credential-id <credential_id> \
  --expected-revision 1 \
-  --valid-for 720h \
+  --valid-for 0 \
+  --grace 168h \
  --reason "scheduled credential rotation" \
  --output .local/rotated.credentials.json
 ```

-命令先读取并核对版本，生成一个固定 `operation_id`、令牌和绝对到期时间，写入新的 `0600` 私有操作文件，然后提交数据库事务。文件不得已存在；提交结果不明、网络断开或数据库返回未知错误时必须保留文件，并使用同一个文件执行 `credential apply --file`，不能重新执行 `rotate` 生成第二个秘密。`--valid-for` 限定在 1 小时到 1 年。数据库只保存秘密摘要、请求摘要和脱敏回执。
+命令先读取并核对版本，生成一个固定 `operation_id`、令牌、可选绝对到期时间和固定过渡截止，写入新的 `0600` 私有操作文件，然后提交数据库事务。文件不得已存在；提交结果不明、网络断开或数据库返回未知错误时必须保留文件，并使用同一个文件执行 `credential apply --file`，不能重新执行 `rotate` 生成第二个秘密。`--valid-for` 默认 0（长期），也可配置 1 小时到 365 天；`--grace` 默认 168h（7 天），范围 0–720h，0 表示立即停用旧 Token。旧 Token 的实际截止取过渡截止与原到期时间的较早者，不复活已过期秘密。数据库只保存秘密摘要、请求摘要和脱敏回执。

 ```sh
 go run ./cmd/orbit-admin credential apply \
@@ -77,6 +78,36 @@ go run ./cmd/orbit-admin credential apply \

 `apply` 会严格拒绝软链接、非 0600 文件、未知 JSON 字段、重复 JSON 对象和修改过的操作内容。重复应用已提交的文件只返回原回执，回执中的 `deduplicated` 为 `true`，不会重新轮换或新增审计。

+### 原 Token 调整有效期
+
+无需换 Token：读取当前 revision 后执行以下命令，业务侧继续使用原配置。缩短有效期同样会生效，应按预期截止配置。
+
+```sh
+go run ./cmd/orbit-admin credential expiry \
+  --namespace-id <namespace_id> --credential-id <credential_id> \
+  --expected-revision 1 --valid-for 0 \
+  --reason "service credential remains valid until revoked" \
+  --output .local/expiry.operation.json
+```
+
+### 平滑切换的完整顺序
+
+1. 生成新 Token，保留默认 7 天过渡。凭据 ID、权限、任务、订阅和交付身份不变。
+2. 把新 Token 发布到调用方配置，逐台更新 API 服务、Worker 和结果消费者。SDK v0.1.1 的 `Options.Token` 在创建客户端时读取，修改 `.env` 不会自动刷新正在运行的客户端；新建客户端或滚动重启服务，按 [HTTP 宿主示例](../examples/http-service.md) 正常排空在途工作。
+3. 在截止前确认所有旧进程已完成任务回报和 ACK，并已经退出或用新 Token 重新连接。HTTP 调用无须整体停机；持续执行能力依赖业务侧保留足够副本。单实例重启本身会产生短暂停顿。
+4. 全部切换后可提前结束过渡；否则旧 Token 到时自动失效，认证使用数据库时间，不依赖定时清理。
+
+```sh
+go run ./cmd/orbit-admin credential finalize \
+  --namespace-id <namespace_id> --credential-id <credential_id> \
+  --expected-revision 2 --reason "all service instances switched and drained" \
+  --output .local/finalize.operation.json
+```
+
+结束过渡立即停用旧 Token，当前 Token 不变。长期 Token 仍受主动撤销、应用/命名空间停用约束。旧代仍在有效过渡期时再次轮换返回 409，避免误伤未切换服务；先完成本次切换。修改当前有效期不延长旧代截止。若旧 Token 本身即将到期而需要更长切换窗口，应先调整当前有效期，再发起换证。
+
+新固定操作文件使用 version=2；历史 version=1 仍按原来的固定到期和立即轮换语义重放，不自动延长旧秘密。
+
 发生泄露或 Worker 必须立即停用时执行撤销：

 ```sh
@@ -88,7 +119,7 @@ go run ./cmd/orbit-admin credential revoke \
  --reason "incident response"
 ```

-撤销同样先写入固定操作文件，再提交事务；提交不明时用 `credential apply --file .local/revoke.operation.json` 重试。撤销只标记凭据失效，不删除订阅、任务、交付或历史记录。即使应用或命名空间已停用，管理撤销仍可执行。重复应用同一撤销文件只返回原回执，不追加重复审计。审计主体取自 MySQL 管理连接的 `CURRENT_USER()`，审计摘要不包含秘密原文或秘密摘要。
+撤销同样先写入固定操作文件，再提交事务；提交不明时用 `credential apply --file .local/revoke.operation.json` 重试。撤销使当前和过渡中的上一代同时失效，不删除订阅、任务、交付或历史记录。即使应用或命名空间已停用，管理撤销仍可执行。重复应用同一撤销文件只返回原回执，不追加重复审计。审计主体取自 MySQL 管理连接的 `CURRENT_USER()`，审计摘要不包含秘密原文或秘密摘要。

 ## 凭据格式与作用域

@@ -130,3 +161,7 @@ P3 结果订阅核心新增 `events:read`、`events:manage` 和 `events:consume`
 P4定义发布新增`workflows:definitions:read`与`workflows:definitions:publish`，仅显式`--workflow-access`授予。创建/读取元数据作用于命名空间，发布及读取完整版本额外校验全部引用队列；默认提交/Worker凭据不获此权限。发布不创建任务，不要求tasks:submit，详见[定义API](workflow-definitions.md)。

 P4/P5实例公共接入增加`workflows:start/read/control/signal/recover`及`workflows:audit:read`。五个独立CLI开关`--workflow-run-access`、`--workflow-control-access`、`--workflow-signal-access`、`--workflow-recovery-access`、`--workflow-audit-access`分别明确授予。前四个同时包含实例读取；audit只授予流程操作审计读取。原`--workflow-access`仍仅授予定义读/发布，任务`--recovery-access`不授予流程恢复。全部固定队列仍按当前凭据校验，详见[实例权限表](workflows.md#1-路由权限与-sdk)。初始化权限集合在交付凭据前校验。
+
+## 部署升级
+
+迁移 `000032` 为凭据表增加上一代摘要与 UTC 截止，并以 CHECK 约束成对为空；不新增外键、不改变已有秘密或有效期。新安装的基线同步到 32。按部署流程应用迁移并更新全部 Orbit 节点后再使用平滑换证；旧版本节点只认识当前摘要，不能在混合版本期间承诺旧 Token 可用。既有凭据不会被迁移自动改为长期，须通过有审计的 expiry 操作显式调整。
--- a/docs/api/console-applications.md
+++ b/docs/api/console-applications.md
@@ -1,6 +1,6 @@
 # 控制台应用接入

-单管理员在「应用接入」页面创建应用、初始队列与 SDK 凭据，查看环境、队列、权限和有效期，重新生成 Token，复制或下载 `.env` 配置。数据库只保存 Token 摘要：完整 Token 仅在新建或轮换时交付，列表和详情不能反查旧秘密。
+单管理员在「应用接入」页面创建应用、初始队列与 SDK 凭据，查看环境、队列、权限和有效期，平滑换证，复制或下载 `.env` 配置。数据库只保存 Token 摘要：完整 Token 仅在新建或轮换时交付，列表和详情不能反查旧秘密。

 ## 1. 启用和使用

@@ -18,7 +18,8 @@ export ORBIT_CONSOLE_APPLICATION_ADMIN=admin
 2. 选择 Worker、结果订阅、定时、流程等需要的能力及有效期。基础权限包含任务提交/查询/取消、队列读取/管理。
 3. 创建成功后复制或下载完整 `.env`，交给该应用的服务端配置。默认地址使用当前页面来源，详情中可改为容器地址或部署域名。
 4. 已接入应用可以随时查看元数据和配置模板。模板中的 Token 是占位值，必须替换成已经保存的原 Token。
-5. 「重新生成 Token」保留 application_id、namespace_id、credential_id、队列、任务和订阅；旧 Token 在轮换事务提交后不能再通过业务认证，服务端配置需要同步更新。
+5. 「平滑换证」保留 application_id、namespace_id、credential_id、队列、任务和订阅；新 Token 立即生效，旧 Token 在配置的过渡期内继续使用（页面默认 7 天，支持 1/7/30 天），便于逐台更新配置。详情展示旧 Token 实际截止，全部服务切换后可点「结束过渡」。
+6. 默认「长期有效」，不需要每月人工换证；已有凭据可点「调整有效期」直接设为长期，原 Token 保持不变。

 环境与命名空间形成隔离边界。不同应用应分别创建；同一应用的多个命名空间在列表中分别展示。页面目前支持新建应用及其初始队列，未提供应用删除、身份迁移、跨应用任务列表或现有应用新增命名空间的表单；已有 CLI 的 `--application-id` 仍可增加命名空间，队列 SDK 可增加同范围队列。接入管理页不会改变其他业务页面的账号默认范围。

@@ -48,31 +49,31 @@ prepare 请求：
  "queue": "orders",
  "capabilities": ["worker", "events", "schedules", "workflows"],
  "expected_revision": "0",
-  "valid_days": 30,
+  "valid_days": 0,
  "reason": "接入订单服务"
 }
 ```

-名称以字母或数字开头，后续只允许字母、数字、`_ . : -`，environment 最长 32，其余最长 128。valid_days 为 1–365 的整数；reason 非空、最多 1024 个 Unicode 字符，不含换行或 NUL。capabilities 可选 `worker`、`events`、`schedules`、`workflows`、`recovery`、`resources`，不可重复。新建不传 namespace_id / credential_id，expected_revision 省略或为字符串 `"0"`。
+名称以字母或数字开头，后续只允许字母、数字、`_ . : -`，environment 最长 32，其余最长 128。valid_days 为 0–365 的整数，默认 0 表示长期有效；reason 非空、最多 1024 个 Unicode 字符，不含换行或 NUL。capabilities 可选 `worker`、`events`、`schedules`、`workflows`、`recovery`、`resources`，不可重复。新建不传 namespace_id / credential_id，expected_revision 省略或为字符串 `"0"`。

 prepare 响应 data 为固定操作对象：

 ```json
 {
-  "input": {"kind":"CREATE","application":"order-service","namespace":"default","environment":"test","queue":"orders","capabilities":["worker","events"],"expected_revision":"0","valid_days":30,"reason":"接入订单服务"},
+  "version": 2,
+  "input": {"kind":"CREATE","application":"order-service","namespace":"default","environment":"test","queue":"orders","capabilities":["worker","events"],"expected_revision":"0","valid_days":0,"reason":"接入订单服务"},
  "operation_id": "11111111111111111111111111111111",
  "application_id": "22222222222222222222222222222222",
  "namespace_id": "33333333333333333333333333333333",
  "queue_id": "44444444444444444444444444444444",
  "credential_id": "55555555555555555555555555555555",
-  "token": "服务端生成的完整 Token",
-  "expires_at": "2026-10-27T02:00:00Z"
+  "token": "服务端生成的完整 Token"
 }
 ```

 以上是结构示意，ID、令牌及时间以服务端返回为准。将 **data 整体原样** POST 到 apply，不包 `data` 外层。应用、额度、命名空间、队列、凭据摘要、审计和幂等回执在同一事务提交。初始队列并发 4、开始速率 10/秒，沿用 bootstrap 默认策略；凭据队列范围为新命名空间的全部队列。重名应用返回 409，不覆盖原资源。

-## 4. 重新生成 Token
+## 4. 平滑换证

 prepare 请求：

@@ -82,12 +83,13 @@ prepare 请求：
  "namespace_id": "33333333333333333333333333333333",
  "credential_id": "55555555555555555555555555555555",
  "expected_revision": "1",
-  "valid_days": 30,
+  "valid_days": 0,
+  "grace_days": 7,
  "reason": "更新接入凭据"
 }
 ```

-expected_revision 为读取到的字符串版本。只允许上述轮换字段，不混入新应用名称或能力组。准备对象包含原 application_id / namespace_id / credential_id，没有 queue_id。apply 复用原有凭据轮换事务：替换秘密摘要与到期时间，版本加一，保存脱敏回执及人类账号审计；权限组不改变。已撤销的凭据禁止轮换。
+expected_revision 为读取到的字符串版本。只允许上述轮换字段，不混入新应用名称或能力组。准备对象包含原 application_id / namespace_id / credential_id，没有 queue_id。apply 复用原有凭据轮换事务：将原摘要保留到固定过渡截止，替换当前摘要与可选到期时间，版本加一，保存脱敏回执及人类账号审计；权限组不改变。已撤销的凭据禁止变更。ROTATE 的 grace_days 范围 0–30，API 省略/0 保持立即停用旧 Token 的兼容语义，页面显式提交 7；实际截止不超过旧 Token 原到期时间。过渡未结束时再次轮换返回 409。

 apply 成功 data：

@@ -102,7 +104,28 @@ apply 成功 data：
 }
 ```

-## 5. 超时、重复和审计
+## 5. 调整有效期与结束过渡
+
+prepare 输入示例：
+
+```json
+{
+  "kind": "SET_EXPIRY",
+  "namespace_id": "33333333333333333333333333333333",
+  "credential_id": "55555555555555555555555555555555",
+  "expected_revision": "2",
+  "valid_days": 0,
+  "reason": "服务凭据设置为长期有效"
+}
+```
+
+SET_EXPIRY 不生成新 Token，只更新当前有效期；valid_days=0 为长期，1–365 为从准备时间计算的天数。FINALIZE 使用相同身份/版本字段，kind 改为 FINALIZE，valid_days 必须为 0，用于提前停用旧 Token。两者均禁止 grace_days 和新建字段，prepare 不返回 token；FINALIZE 也不返回 expires_at。apply 使用完整原对象，具有相同的并发版本、幂等和审计约束。
+
+新版 prepare 对象带 version=2；expires_at 为空时**省略字段**，不要传显式 null。ROTATE 有过渡期时另外包含固定 previous_valid_until；详情中的 previous_valid_until 是受旧到期时间约束后的实际截止，未设置时省略。详情/回执不会返回旧秘密。历史不带 version 的固定操作仍按原语义重放。
+
+完整滚动更新及 SDK 客户端生命周期说明见[凭据手册](authentication.md)。更换配置不会自动刷新已创建的客户端，须在过渡截止前完成重建或逐台重启并排空在途任务。
+
+## 6. 超时、重复和审计

 - 页面提交前把整个固定操作保留在当前内存；请求超时或结果未知时，按钮变成「重试确认」，重用同一份内容。不能再次 prepare 来代替核对。
 - 页面允许「保存待核对操作」下载私密 JSON；含真实 Token，应放到受限目录。恢复时登录同一管理员后，向 apply 发送该文件正文。不要把 Cookie 或操作文件提交 Git，也不要放到 URL。