跳转到内容
tool-bridge

权限、SK 与可见性

Secret Key（SK）是 tool-bridge 的调用者身份。每把 SK 关联 owner、路径 scope、可选过期时间和设备注册边界。服务端保存 SK hash，明文只在签发时显示一次。

本页适合网关管理员和需要给 Agent、用户或设备发放身份的操作者。你需要一把具有 system/sk 管理权限的 Admin SK，并已用 tb login 保存管理 profile。

权限由路径和 action 组成

Section titled “权限由路径和 action 组成”

当前 action 包括：

action 典型用途
read 读取节点、帮助、对象或 Feedback
write 写入 Context 等节点承载的数据
call 调用工具、提交或投票 Feedback
register 在允许位置注册设备或能力
admin 管理节点、SK、Secret、Plugin 等高权限操作；可接管或清理由他人注册的节点

scope 使用完整路径 glob：

  • tools/*：只匹配 tools 下一层；
  • tools/research/**：匹配挂载点以及任意深度后代；
  • **：匹配整棵树，包括根路径。

* 与 ** 都按路径段匹配，不是普通字符串通配符。

判定顺序

Section titled “判定顺序”

每次访问都按以下顺序判断：

  1. 任一匹配的 deny 规则出现，拒绝；
  2. 否则任一匹配的 allow 规则出现，允许；
  3. 没有匹配，默认拒绝。

无权读取的路径对调用者表现为 404，而不是暴露存在性的 403。~tree、~help、工具调用和管理读取都遵守这条可见性边界。

CLI 的 --scope 'pattern:actions' 适合创建 allow 规则；Dashboard 可以编辑 allow/deny 规则。通过直接 API 管理复杂规则前，先读取当前实例 system/sk/~help 的结构化 schema，不要依赖本站手抄的 payload。

admin 可接管他人注册的节点

Section titled “admin 可接管他人注册的节点”

普通身份只能管理自己注册的设备或反向注册节点。持 admin scope 的 SK 则可以跨注册者接管或清理节点：在目标路径上有 admin 时，registry 管理命令和 ~register 覆盖会绕过“注册者必须是当前调用者”的检查。

这让管理员能清理离线设备遗留的节点、回收被占用的注册路径，而不必找回原注册者的 SK。它是有意的运维能力，也意味着 admin 是强破坏性权限：只发给真正需要的运维身份，日常 Agent、CI 和设备都用范围更小、不含 admin 的 SK。清理和接管的确切命令与权限以目标实例 tb help system/registry 为准。

1. 创建第一把受限 Agent SK

Section titled “1. 创建第一把受限 Agent SK”

下面的身份只能读取和调用 tools/research 子树：

Terminal window
tb sk create \
  --owner agent:researcher \
  --scope 'tools/research/**:read,call' \
  --description 'Research tools only'

命令会返回 SK ID 和只显示一次的明文 secret。立即把 secret 存进调用者的密码库或受保护的 CI Secret，把 ID 留作禁用、审计与吊销。

如果 Agent 还需要只读 Context，应追加另一条 scope：

Terminal window
tb sk create \
  --owner agent:researcher \
  --scope 'tools/research/**:read,call' \
  --scope 'ctx/public-docs/**:read' \
  --description 'Research tools and public docs'

不要因为调用失败就直接授予 **:read,write,call,register,admin。先确认它缺的是哪个路径和 action。

2. 用独立 profile 验证

Section titled “2. 用独立 profile 验证”

为受限身份创建本地 profile：

Terminal window
tb login \
  --profile researcher \
  --base-url https://tb.example.com

按提示输入新 SK，然后切换并验证：

Terminal window
tb use researcher
tb use
tb whoami
tb tree --depth 3
tb help tools/research

选择该子树中的实际工具，并依据 ~help 调用。然后尝试读取一个未授权路径：

Terminal window
tb help system/sk

成功证据

Section titled “成功证据”
  • 授权子树在 tb tree 中可见；
  • 目标节点 ~help 可读且调用成功；
  • system/sk 等未授权路径返回 404；
  • 无参数的 tb use 将 researcher 标为当前 profile；tb whoami 显示预期 BaseURL、掩码 SK 和认证状态，而不是 Admin 身份。

验证完成后切回管理身份：

Terminal window
tb use default

3. 设计设备身份与 registerPaths

Section titled “3. 设计设备身份与 registerPaths”

设备反向连接不仅需要目标路径的 register action，还可以通过 registerPaths 进一步收紧可注册前缀：

Terminal window
tb sk create \
  --owner device:build-01 \
  --scope 'device/build-01/**:read,call,register' \
  --register-path device/build-01 \
  --description 'Build worker reverse connection'

registerPaths 是额外限制，不是授权来源：目标路径仍需命中 register scope。长驻设备应使用唯一、稳定的 deviceId/path，不能让多台机器共享一把宽泛设备 SK。

完整流程见接入本地设备与服务。

Device Mailbox 的授权快照

Section titled “Device Mailbox 的授权快照”

Mailbox 入队当次会重新检查完整命令路径的 read 与 call，并快照 caller 的 {keyId, owner}。之后禁用、删除或过期这把 caller SK 不会自动撤销已经授权创建的 operation；同一 owner 的另一把 SK，或对完整目标路径有 admin 的身份，仍可 get/list/cancel。需要停止未开始的任务时，应显式取消 operation，而不是只吊销 caller SK。

设备侧不同：claim/renew/complete 每次都重新认证当前 Device SK，并要求它仍匹配创建时的 device keyId、registerPaths 与 mount ownership。禁用该 Device SK 会立即阻止后续迁移；新签发的 keyId 不会自动接管旧 operation，旧记录最终按 TTL 收敛。完整边界见Device 离线投递与 Mailbox。

4. 查看、禁用与吊销

Section titled “4. 查看、禁用与吊销”
Terminal window
tb sk list --limit 50
tb sk get <sk-id>
tb sk disable <sk-id>
tb sk rm <sk-id>
  • list/get 不会返回明文 secret 或 hash；
  • disable 适合临时阻断，之后可以显式 enable；
  • rm 吊销并删除记录，调用者需要重新签发新 SK；
  • 设置 --expires 时使用带时区的 ISO 8601 时间。

精确命令以当前版本 tb sk --help 与子命令帮助为准。

安全边界

Section titled “安全边界”
  • SK 明文不进入 URL、普通日志、调用历史、截图和工单；
  • 浏览器 Dashboard profile 与本地 CLI profile 都按敏感凭证保护；
  • 不把调用者 SK 当作 MCP、HTTP、Plugin 或 remote 的上游 token；上游身份由 SecretStore 引用解析；
  • 更新 scope 后重新用目标身份做 tree/help/call，不要只看管理面保存成功；
  • 标准 Node 使用 PostgreSQL 权威记录逐请求检查 SK，禁用与吊销对新请求立即生效；Redis、搜索索引或客户端缓存不能成为授权真源。已入队 Mailbox 使用创建时的 caller 授权快照，caller SK 吊销不等于撤销已有 operation。

常见失败

Section titled “常见失败”

受限 SK 能读帮助但不能调用

Section titled “受限 SK 能读帮助但不能调用”

通常只授予了 read，缺少同一路径的 call。也可能工具路径在 virtualize 后发生变化，先重新读取挂载点 ~help。

创建的 scope 没覆盖挂载点

Section titled “创建的 scope 没覆盖挂载点”

使用按段 glob，并确认 ** 放在正确位置。tools/research/** 会匹配挂载点和后代；tools/* 只匹配一层。

Device 提示路径不允许注册

Section titled “Device 提示路径不允许注册”

同时检查 register action 与 registerPaths。后者只会收紧范围，不能替代前者。

管理员看到路径，Agent 得到 404

Section titled “管理员看到路径，Agent 得到 404”

这是预期的身份裁剪。用 Agent 自己的 profile 运行 tb tree，检查它真正能发现的起点；不要用 Admin 视图推断。

下一步

Section titled “下一步”