跳转到内容
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。

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。

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

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，不要只看管理面保存成功；
  • Workers KV 的认证与注册读取存在最终一致窗口，紧急吊销后应等待传播并验证，不把它当作强一致状态；需要强一致身份状态时优先评估 Node/SQLite。

常见失败

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 “下一步”