feat: manage existing credential actions with audited replay
This commit is contained in:
@@ -1,6 +1,8 @@
|
||||
# Orbit 持续开发与回归计划
|
||||
|
||||
更新：2026-09-24。此计划对应持续开发目标，由开发过程同步维护。数据库已按用户要求采用无外键设计，迁移 000008 移除历史外键，关联一致性由服务端事务保证。
|
||||
更新：2026-11-01。此计划对应持续开发目标，由开发过程同步维护。数据库已按用户要求采用无外键设计，迁移 000008 移除历史外键，关联一致性由服务端事务保证。
|
||||
|
||||
2026-11-01 补齐旧凭据动作权限管理：控制台与管理 CLI 共用 SET_PERMISSIONS v3 固定操作、revision 校验、幂等回执和原子审计；保留队列范围、秘密、有效期及过渡时间。隔离 MySQL 已验证原 Token 即时授予/收回、真实锁等待竞争、审计失败回滚和 v1/v2 旧操作兼容；HTTP 与页面提交重试回归通过。无新增迁移，业务 SDK 仍不开放凭据管理，原生产验收边界不变。协议及命令见 [认证手册](api/authentication.md#原-token-调整动作权限) 与 [控制台接入](api/console-applications.md#调整已有凭据的动作权限)，验证范围见 [权限管理回归](reports/credential-permissions-20261101.md)。
|
||||
|
||||
## 1. 最终交付目标
|
||||
|
||||
|
||||
@@ -56,7 +56,7 @@ go run ./cmd/orbit-admin credential status \
|
||||
--credential-id <credential_id>
|
||||
```
|
||||
|
||||
状态输出不包含令牌、秘密摘要或权限正文；`revision` 是后续变更的并发条件。
|
||||
状态输出包含精确动作与队列权限，不包含令牌或秘密摘要；`revision` 是后续变更的并发条件。
|
||||
|
||||
```sh
|
||||
go run ./cmd/orbit-admin credential rotate \
|
||||
@@ -106,7 +106,25 @@ go run ./cmd/orbit-admin credential finalize \
|
||||
|
||||
结束过渡立即停用旧 Token，当前 Token 不变。长期 Token 仍受主动撤销、应用/命名空间停用约束。旧代仍在有效过渡期时再次轮换返回 409，避免误伤未切换服务；先完成本次切换。修改当前有效期不延长旧代截止。若旧 Token 本身即将到期而需要更长切换窗口，应先调整当前有效期，再发起换证。
|
||||
|
||||
新固定操作文件使用 version=2；历史 version=1 仍按原来的固定到期和立即轮换语义重放，不自动延长旧秘密。
|
||||
轮换、有效期、结束过渡与撤销的新固定操作文件继续使用 version=2；历史 version=1 仍按原来的固定到期和立即轮换语义重放，不自动延长旧秘密。权限修改使用下面的 version=3，不改变旧操作内容或摘要。
|
||||
|
||||
### 原 Token 调整动作权限
|
||||
|
||||
`credential permissions` 修改已有凭据的完整动作集合，保留队列授权范围、Token、密文、有效期、旧代过渡期和资源身份。先用 status 读取当前权限与 revision，再明确保留或移除哪些动作。`--actions` 是全量替换，不能只填写希望新增的动作；空集合、未知动作、通配符和重复动作会被拒绝，准备时按字典序固定。
|
||||
|
||||
```sh
|
||||
go run ./cmd/orbit-admin credential permissions \
|
||||
--namespace-id <namespace_id> --credential-id <credential_id> \
|
||||
--expected-revision <revision> \
|
||||
--actions 'queues:read,schedules:manage,schedules:read,tasks:read,tasks:submit' \
|
||||
--reason 'enable scheduling for this credential' \
|
||||
--output .local/permissions.operation.json --prepare-only
|
||||
go run ./cmd/orbit-admin credential apply --file .local/permissions.operation.json
|
||||
```
|
||||
|
||||
上例动作仅作格式示例，实际必须根据原 status 核对完整集合。`--prepare-only` 只保存 0600 固定操作，不修改凭据；不带该参数则保存后立即应用，沿用其他 credential 命令的行为。权限修改不接受 `--valid-for` 或 `--grace`，固定操作不含 Token。当前版本校验、权限变更、前后权限审计和原键回执在一个事务内提交，审计失败整笔回滚；提交不明时用原文件 apply，不能换 operation_id。旧操作重放只返回原回执，不会恢复后来已收回的权限。
|
||||
|
||||
权限随下一次认证/授权检查生效，原 Token 无须重新分发；移除 Worker 或消费相关权限可能影响既有连接的后续授权。该管理能力仅由管理员控制台或受保护的管理 CLI 提供，业务 SDK 不获得凭据管理接口。
|
||||
|
||||
发生泄露或 Worker 必须立即停用时执行撤销：
|
||||
|
||||
|
||||
@@ -21,6 +21,7 @@ export ORBIT_CREDENTIAL_KEY_FILE=/run/orbit-secrets/credential-keys.json
|
||||
4. 已接入应用点击「查看接入信息」或「复制接入配置」，获取包含当前 Token 的完整配置；也可下载 orbit.env。
|
||||
5. 「平滑换证」保留 application_id、namespace_id、credential_id、队列、任务和订阅；新 Token 立即生效，旧 Token 在配置的过渡期内继续使用（页面默认 7 天，支持 1/7/30 天），便于逐台更新配置。详情展示旧 Token 实际截止，全部服务切换后可点「结束过渡」。
|
||||
6. 默认「长期有效」，不需要每月人工换证；已有凭据可点「调整有效期」直接设为长期，原 Token 保持不变。
|
||||
7. 在凭据的「管理与权限」中选择「调整权限」，核对当前精确动作集合并填写原因。只修改动作，队列授权、Token、有效期和过渡期保持不变；高级恢复、审计和额度权限需要明确选择。
|
||||
|
||||
凭据卡片提供「查看接入信息」「复制接入配置」。配置包含 ORBIT_URL、ORBIT_APPLICATION_ID、ORBIT_NAMESPACE_ID、ORBIT_QUEUE_ID、ORBIT_TOKEN；可直接粘贴为环境配置。先选择业务服务实际可访问的地址和队列，再复制；应用 ID 用于识别，真正认证身份来自 Token。过渡期始终返回当前新 Token，调整有效期或结束旧代过渡后仍可查看。历史凭据尚无密文时提供「导入当前 Token」，不能把仍可用的旧代 Token 导入为当前代次。
|
||||
|
||||
@@ -132,6 +133,26 @@ SET_EXPIRY 不生成新 Token，只更新当前有效期；valid_days=0 为长
|
||||
|
||||
完整滚动更新及 SDK 客户端生命周期说明见[凭据手册](authentication.md)。更换配置不会自动刷新已创建的客户端，须在过渡截止前完成重建或逐台重启并排空在途任务。
|
||||
|
||||
### 调整已有凭据的动作权限
|
||||
|
||||
prepare 使用 `kind=SET_PERMISSIONS`，携带当前 namespace_id、credential_id、expected_revision、完整 actions 数组和 reason；valid_days 为 0，grace_days 省略或为 0。actions 必须非空，至多 32 个，拒绝重复、未知动作与通配符。其他操作类型不接受 actions，不能把权限修改混入换证或有效期调整。
|
||||
|
||||
```json
|
||||
{
|
||||
"kind": "SET_PERMISSIONS",
|
||||
"namespace_id": "33333333333333333333333333333333",
|
||||
"credential_id": "55555555555555555555555555555555",
|
||||
"expected_revision": "2",
|
||||
"valid_days": 0,
|
||||
"actions": ["queues:read", "schedules:manage", "schedules:read", "tasks:read", "tasks:submit"],
|
||||
"reason": "允许该凭据管理定时计划"
|
||||
}
|
||||
```
|
||||
|
||||
actions 为**全量替换**，示例不能代替读取原权限；页面默认勾选原有动作，不默认补齐能力组。prepare 返回 version=3 的固定操作，不生成或返回 Token、期限或过渡时间；原对象整体提交到已有 apply 路由。新动作要求 version=3，旧 CREATE、ROTATE、SET_EXPIRY、FINALIZE 保持原固定格式与重放语义。
|
||||
|
||||
服务端仅更新原凭据动作集合和 revision，保留原队列授权与所有秘密/有效期字段；权限前后快照、管理员身份、原因和回执原子提交。审计失败不改权限，旧版本返回冲突，提交不明重放原 operation_id。页面成功后刷新详情；旧回执不代表当前权限仍等于该次修改后的状态。权限将在后续认证/授权检查生效，移除正在使用的能力可能影响对应连接后续操作。
|
||||
|
||||
## 6. 超时、重复和审计
|
||||
|
||||
- 页面提交前把整个固定操作保留在当前内存；请求超时或结果未知时，按钮变成「重试确认」，重用同一份内容。不能再次 prepare 来代替核对。
|
||||
|
||||
39
docs/reports/credential-permissions-20261101.md
Normal file
39
docs/reports/credential-permissions-20261101.md
Normal file
@@ -0,0 +1,39 @@
|
||||
# 既有凭据权限管理回归
|
||||
|
||||
日期：2026-11-01。
|
||||
|
||||
## 功能范围
|
||||
|
||||
管理员通过控制台或 orbit-admin credential permissions 调整既有凭据的完整动作集合。SET_PERMISSIONS 使用 version=3 固定操作；旧动作仍使用原 v1/v2 格式，字段省略规则和历史摘要保持兼容。队列授权范围、Token 摘要及密文、有效期、旧代过渡期、资源 ID 均不改变。只更新动作集合与 revision，并将前后权限、主体、原因、固定回执同事务保存。
|
||||
|
||||
控制台入口仍只接受指定管理员会话与同源请求，业务 Bearer 不获得管理权限。页面使用精确动作勾选，默认保持原集合；高级核查、重试、审计与额度动作单独标识。未知动作、重复动作、通配符和空集合被拒绝；权限修改不能夹带有效期、过渡期或队列变化。
|
||||
|
||||
## 已执行验证
|
||||
|
||||
本批真库测试使用新建的一次性 MySQL 8.4 容器，核心与控制台测试各用独立数据库，没有对既有业务库执行故障注入。
|
||||
|
||||
| 验证 | 结果与边界 |
|
||||
| --- | --- |
|
||||
| 核心与历史凭据真库 race | 新权限前原 Token 调度请求为 403，授予后可实际创建计划，收回后当前/旧代 Token 均被拒绝；额外队列仍不可访问 |
|
||||
| 凭据保留 | 比对秘密摘要、密文、密钥编号、有效期、过渡截止、队列 JSON；只改变明确请求的动作与 revision |
|
||||
| 并发与重放 | 通过 performance_schema 确认实际数据库锁等待；同版本竞争仅一次生效，原操作重放无第二次审计，不恢复后来已收回的权限 |
|
||||
| 审计失败 | 隔离库注入审计写入失败，权限、revision 和幂等回执全部回滚 |
|
||||
| 兼容性 | v1/v2 固定 JSON/摘要不变；v1 → v3 → 旧回执重放 → v2 调整期限通过 |
|
||||
| 控制台 HTTP 与真库 | prepare/apply 的管理员、Cookie、Origin、Fetch Metadata、严格 JSON、注销后拒绝、两代 Token 与单队列隔离通过 |
|
||||
| 页面事件回归 | 执行实际 applications.js；默认精确集合、原操作重试、成功刷新、不读取 Token、其他模式及撤销状态隔离通过 |
|
||||
| 管理 CLI | 动作参数校验、禁止期限参数、0600 固定文件往返通过；另在隔离库通过真实 CLI 验证 prepare-only 前后状态不变，apply 与原文件重放仅增加一次 revision，队列范围保持 |
|
||||
| 标准检查 | make test、make vet、make build、make console-check、make docs-check 全部通过 |
|
||||
|
||||
## 复现入口与限制
|
||||
|
||||
```sh
|
||||
make test
|
||||
make vet
|
||||
make build
|
||||
make console-check
|
||||
make docs-check
|
||||
# ORBIT_TEST_MYSQL_DSN 从隔离环境私密配置加载，不指向共享业务库。
|
||||
go test -race -count=1 ./internal/storage/mysql -run 'TestIntegrationCredential|TestIntegrationConsole.*Permission|TestIntegrationConsoleApplications'
|
||||
```
|
||||
|
||||
没有新增数据库迁移、修改 SDK 协议或赋予普通凭据跨应用权限。上述验证不能替代生产多节点部署、权限变更审批和目标拓扑的正式验收；实际接入方授权记录位于工作区对接文档，不写入通用平台代码。
|
||||
Reference in New Issue
Block a user