AgentConnect安全设计揭秘:组织级密钥加密、Crypto-Shredding与Agent权限边界完整指南
AgentConnect安全设计揭秘:组织级密钥加密、Crypto-Shredding与Agent权限边界完整指南
AgentConnect 是一个开源的多 Agent 协作平台(Claude Tag 的开源替代):在任何工作场景里 @ 任意一个 Agent,它们就能与你的团队并肩工作并持续学习。当多个组织共享同一套部署时,AgentConnect 安全设计就成为核心课题——密钥加密、数据删除、权限边界一个都不能少。本文带你完整拆解它的三层防线:组织级密钥加密(per-org secret encryption)、加密粉碎(Crypto-Shredding)与 Agent 权限边界(Agent permission boundaries)。
一、多 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 |
这些秘密分属不同的租户(组织)。如果所有组织的密钥都用同一把密钥加密,会立刻带来两个致命问题:
- 一把密钥保护所有租户:一旦泄露,整个部署的数据全部失守,组织之间没有任何加密边界;
- 删除组织 ≠ 销毁密钥:删掉数据库行之后,删除前做的数据库备份仍然可以完整解密。
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 密钥"是远程操作,无法加入删除组织的数据库事务,流程被拆成两步:
- 记录意图:删除事务中写入一条
pending_key_shred墓碑(tombstone),并固化当时的密钥全名(而非删除时才计算),避免中途改配置导致删错名字; - 独立执行:由运维用独立身份运行的 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 的入站策略放行——这是交集而非覆盖,任何一侧收紧都会收窄结果。
策略在每一个信任边界都要重查一遍:源 daemon、relay、目标 daemon 各自用自己的快照做终局校验,任何一处缺快照都 fail closed。被拒的调用返回 delivered: false, reason: 'not_allowed',不产生任何平台消息。
4.3 可达性图:把权限边界画出来
配置了那么多方向性策略,管理员如何全局审视?Agents 控制台提供了一张可达性图(Reachability / Topology 视图,设计见 agent-reachability-graph.md):
- 每条箭头 = 一条被双方策略共同放行的直连调用路径;
- 沿箭头可判断传递性可达(A 能间接触达谁);
- 强连通分量被识别为"循环组",方便发现互相调用的 Agent 簇;
- 图只基于当前登录用户已可见的 Agent DTO 计算,不会泄露受限 Agent 或隐藏的白名单成员。
这张图是"解释性 UI"而非授权来源——daemon 和 relay 依旧对每次调用做独立强制执行。
五、纵深防御:藏在细节里的安全纪律
通读这些设计文档,几条反复出现的"失败即关闭"纪律值得所有平台开发者借鉴:
- 缓存键必须包含密钥名 + 密文。只按密文缓存,会让 A 组织读暖的条目被 B 组织的错误请求直接命中——冷缓存有围栏、热缓存就漏了。secrets/vault-transit.ts 的测试专门覆盖这个序列;
- 启动断言:若部署密钥名字恰好落在组织密钥前缀之内(变成可被粉碎的名字),
loadConfig直接拒绝启动; - 旧格式大声失败:迁移收敛后,遇到旧
vault:vN:密文直接抛错而非静默解密——一个"临时兼容分支"被移除,因为它本质上就是 §2.2 要防的那个洞; - 入站租户围栏:relay 池化所有组织的 bot 时,用 bot 上已有的
workspaceId投影校验投递归属,堵住"同一应用凭据被两个组织安装"导致的跨组织消息串流(见 ingress-tenant-fence.md); - 密钥参数必填、日志零泄漏:cipher 构造函数参数无默认值;
seal/open的入参与响应体永不落日志,错误只含 HTTP 状态码。
六、总结:三层防线一览
| 防线 | 核心机制 | 回答的问题 |
|---|---|---|
| 组织级密钥加密 | 每组织独立 Vault Transit 密钥 + 显式 scope 断言 | 数据怎么存才隔离? |
| Crypto-Shredding | 删组织 → 墓碑意图 → 独立身份销毁密钥 | 删除如何可信地不可逆? |
| Agent 权限边界 | 双向可见性 × 角色可见性 × 多边界重复校验 | 谁能访问什么? |
AgentConnect 的安全设计没有追求"绝对安全"的神话,而是用清晰的边界、大声的失败、最小特权把每一种威胁场景逐一关闭——这正是自托管、多租户平台最该有的样子。想深入了解某一层,可以从对应设计文档入手:secret-store-seams.md、per-org-secret-encryption.md、authorization-policy.md。


