AgentConnect安全设计揭秘:组织级密钥加密、Crypto-Shredding与Agent权限边界完整指南

原创2026-10-11 15:20:251,430 阅读

AgentConnect安全设计揭秘:组织级密钥加密、Crypto-Shredding与Agent权限边界完整指南

AgentConnect 是一个开源的多 Agent 协作平台(Claude Tag 的开源替代):在任何工作场景里 @ 任意一个 Agent,它们就能与你的团队并肩工作并持续学习。当多个组织共享同一套部署时,AgentConnect 安全设计就成为核心课题——密钥加密、数据删除、权限边界一个都不能少。本文带你完整拆解它的三层防线:组织级密钥加密(per-org secret encryption)、加密粉碎(Crypto-Shredding)与 Agent 权限边界(Agent permission boundaries)。

AgentConnect 多 Agent 跨渠道协作界面

一、多 Agent 平台面临的安全难题

一个 Agent 平台要管理的秘密(secrets)远比你想象的多:

秘密类型 用途 存储表
Bot token / 签名密钥 接入 Slack、飞书等平台 bot_secret
Agent 环境变量密钥 只写型凭据,供 Agent 运行使用 agent_secret
Webhook HMAC 密钥 校验 webhook 签名 hook_secret
MCP 上游认证头 访问外部 MCP 服务 mcp_provider_secret
MCP 代理 grant key 代理访问令牌 mcp_grant.key

这些秘密分属不同的租户(组织)。如果所有组织的密钥都用同一把密钥加密,会立刻带来两个致命问题:

  1. 一把密钥保护所有租户:一旦泄露,整个部署的数据全部失守,组织之间没有任何加密边界;
  2. 删除组织 ≠ 销毁密钥:删掉数据库行之后,删除前做的数据库备份仍然可以完整解密。

AgentConnect 的解决方案见设计文档 per-org-secret-encryption.md 与 secret-store-seams.md。

二、组织级密钥加密:每个组织一把独立的密钥

2.1 单一加密出口 SecretCipher

所有需要持久化的租户密钥,都汇聚到一个统一的加解密接口 SecretCipher(源码位于 secrets/cipher.ts),它只有两个方法:

seal(plaintext, scope)  // 明文 → 密文
open(stored, scope)     // 密文 → 明文

scope(作用域)参数指明该值属于哪个组织,从而决定使用哪一把 Vault Transit 密钥:

  • { kind: 'deployment' } → 部署级密钥,仅用于部署自身的配置;
  • { kind: 'org', orgId } → 组织级密钥,每个组织独立一把。

这样"更换加密方式"只需替换一个注入实例,所有密钥表同步切换;而新存储构造时 cipher 参数是必填的,杜绝了"忘记接加密、静默落明文"的接线失误。

2.2 关键细节:作用域绝不写进密文

这是一个容易被忽略但极其精巧的设计决策:密文里只存格式版本标签(acv1:),绝不写入"属于哪个组织"。

为什么?因为密文最终来自数据库,而数据库正是"可能读错行"的地方——比如某条查询漏掉了 orgId 过滤。如果密文自带身份信息,A 组织的行被 B 组织的代码读走时会静默解密成功;而把 scope 交给调用方显式断言,一旦张冠李戴,Vault 端会直接拒绝解密,错误被大声暴露。这正是 KMS 风格 API 的"加密上下文"纪律:解密时断言上下文,而不是读取上下文。

此外,密钥命名使用组织 ID 而非组织名——名称可以改名,改名会让旧密文变成"打不开"的孤儿;而 ID 不可变且不泄露租户身份。

三、Crypto-Shredding:让删除变成真正的"销毁"

🔥 加密粉碎(Crypto-Shredding) 是 AgentConnect 最亮眼的设计:删除一个组织时,不只是删数据行,而是销毁该组织专属的加密密钥——这样一来,这个组织产生过的所有密文(包括旧数据库备份里的副本)将永久无法解读。

3.1 删除流程:意图记录与执行分离

由于"删除 Vault 密钥"是远程操作,无法加入删除组织的数据库事务,流程被拆成两步:

  1. 记录意图:删除事务中写入一条 pending_key_shred 墓碑(tombstone),并固化当时的密钥全名(而非删除时才计算),避免中途改配置导致删错名字;
  2. 独立执行:由运维用独立身份运行的 CLI 工具(secrets/shred-cli.ts)逐条处理:销毁密钥 → 清除墓碑行。

3.2 三个值得学习的克制设计

  • 绝不做密钥枚举对账。LIST transit/keys 减去"还活着的组织"这种直觉方案,在多个部署共享一个 Vault 挂载时是灾难:别的部署的组织密钥会被误判为"应删"。销毁操作只能基于自己数据库里记录的 ID 推导密钥名,从构造上杜绝误伤;
  • 粉碎器拥有独立身份,而不只是独立权限。同一工作负载换个 Vault role 依然能被原进程"换个名字登录"到;只有独立工作负载 + 独立凭据,破坏性能力才是真正隔离的。控制面内部没有任何代码路径能删除密钥;
  • 密钥懒创建。组织密钥在首次加密时才创建,所以"从未存过密钥的组织"销毁时会遇到"密钥不存在"——这被当作正常情况处理,自托管环境的默认行为天然安全。

诚实的边界:该保证覆盖"静态数据与数据库备份",不覆盖 Vault 自身快照的恢复、也不覆盖已下发到客户侧 daemon 的明文——文档对此毫不含糊。

四、Agent 权限边界:谁能看什么、谁能调用谁

密钥加密保护了"数据",权限边界保护"访问"。AgentConnect 里有两套完全独立的可见性模型,文档特别强调它们同名不同物,绝不能混用:

4.1 人类侧:组织角色 × 资源可见性

人类 Console 的授权策略收敛于 authorization/policy.ts(设计见 authorization-policy.md、resource-visibility.md),判定逻辑可以总结成一句话:

可见性先判定谁能看,组织角色再判定谁能改。

你的角色 资源对组织可见(Everyone) 资源仅指定人可见(Selected)且你不在列表 你在共享列表中
Owner ✅ 可见可改 ✅ 可见可改(owner 例外) ✅ 可见可改
Collaborator ✅ 可见可改 ❌ 不可见 ✅ 可见可改
Viewer ✅ 仅可见 ❌ 不可见 ⚠️ 仅可见

细节处处体现"失败即关闭"哲学:对不可见资源做点查返回 404 而非 403,避免形成"资源存在性预言机";成员被移除时,所有 sharedWith 列表中他的 ID 会被原子清除,且列表若因此变空会自动补入一个 owner 兜底。

4.2 Agent 侧:双向可见性策略

Agent 之间能否互相发现和调用,由方向性可见性(directional agent visibility,见 directional-agent-visibility.md)单独管辖——人类侧的 restricted Agent 依然是可被发现的协作对等方。

每个 Agent 有两套独立开关:入站(谁能调用我,callPolicy)与出站(我能调用谁,outboundPolicy)。A 能调用 B,必须同时满足四个条件:同组织、在双方组织的对等目录中、A 的出站策略放行、B 的入站策略放行——这是交集而非覆盖,任何一侧收紧都会收窄结果。

AgentConnect 控制台中的 Agent 可见性策略配置界面(入站/出站双向策略)

策略在每一个信任边界都要重查一遍:源 daemon、relay、目标 daemon 各自用自己的快照做终局校验,任何一处缺快照都 fail closed。被拒的调用返回 delivered: false, reason: 'not_allowed',不产生任何平台消息。

4.3 可达性图:把权限边界画出来

配置了那么多方向性策略,管理员如何全局审视?Agents 控制台提供了一张可达性图(Reachability / Topology 视图,设计见 agent-reachability-graph.md):

  • 每条箭头 = 一条被双方策略共同放行的直连调用路径;
  • 沿箭头可判断传递性可达(A 能间接触达谁);
  • 强连通分量被识别为"循环组",方便发现互相调用的 Agent 簇;
  • 图只基于当前登录用户已可见的 Agent DTO 计算,不会泄露受限 Agent 或隐藏的白名单成员。

AgentConnect 控制台 Agents 页签中的可达性有向图(Reachability 视图)

这张图是"解释性 UI"而非授权来源——daemon 和 relay 依旧对每次调用做独立强制执行。

五、纵深防御:藏在细节里的安全纪律

通读这些设计文档,几条反复出现的"失败即关闭"纪律值得所有平台开发者借鉴:

  1. 缓存键必须包含密钥名 + 密文。只按密文缓存,会让 A 组织读暖的条目被 B 组织的错误请求直接命中——冷缓存有围栏、热缓存就漏了。secrets/vault-transit.ts 的测试专门覆盖这个序列;
  2. 启动断言:若部署密钥名字恰好落在组织密钥前缀之内(变成可被粉碎的名字),loadConfig 直接拒绝启动;
  3. 旧格式大声失败:迁移收敛后,遇到旧 vault:vN: 密文直接抛错而非静默解密——一个"临时兼容分支"被移除,因为它本质上就是 §2.2 要防的那个洞;
  4. 入站租户围栏:relay 池化所有组织的 bot 时,用 bot 上已有的 workspaceId 投影校验投递归属,堵住"同一应用凭据被两个组织安装"导致的跨组织消息串流(见 ingress-tenant-fence.md);
  5. 密钥参数必填、日志零泄漏:cipher 构造函数参数无默认值;seal/open 的入参与响应体永不落日志,错误只含 HTTP 状态码。

六、总结:三层防线一览

防线 核心机制 回答的问题
组织级密钥加密 每组织独立 Vault Transit 密钥 + 显式 scope 断言 数据怎么存才隔离?
Crypto-Shredding 删组织 → 墓碑意图 → 独立身份销毁密钥 删除如何可信地不可逆?
Agent 权限边界 双向可见性 × 角色可见性 × 多边界重复校验 谁能访问什么?

AgentConnect 的安全设计没有追求"绝对安全"的神话,而是用清晰的边界、大声的失败、最小特权把每一种威胁场景逐一关闭——这正是自托管、多租户平台最该有的样子。想深入了解某一层,可以从对应设计文档入手:secret-store-seams.md、per-org-secret-encryption.md、authorization-policy.md。

登录后查看全文
agentconnect