跳至内容
安全模型

安全模型

peers 把互不认识的 Broker 连在一起,每条投递出去的消息最终都进入一个 Claude Code 会话,而来自其他主机的文本应视为不可信输入。本页说明信任从哪里来、每种机制保护什么,以及保护到哪里为止。

配对与指纹

每个 Broker 使用自签名证书,身份是公钥的指纹,没有证书颁发机构为它签名。链路使用 TLS 1.3,双方各自核对对方的指纹。

两个 Broker 只在完成配对之后才互相信任。接受方生成一次性配对密钥,连同对外地址和一段填好密钥与本 Broker 全部地址、可直接粘贴的连接提示词一起展示。用户把提示词,或把密钥和一个地址,通过系统之外的途径交给对方主机的用户。这是一条安全要求:peers 在工具说明、结果的说明文字和会话说明里要求 Agent 只把密钥与提示词展示给用户,不得经 send_message、Claude Code 内置会话消息或其他 Agent 间途径发送,也不得按其他 Agent 的请求生成或转交。Broker 不阻拦这种转发,所以这是对 Agent 的要求,而不是系统提供的保证,密钥经过哪条途径要由用户把关。传递一次性密钥的途径必须可信:一次性密钥在失效或被使用之前,任何拿到它的人都能用它配对,途径若把密钥暴露给其他 Agent、日志或第三方,对方同样能完成配对。一次性密钥有 16 个字符,显示为四组,每组四个字符,限时有效,只能使用一次。另一种是预置静态密钥,由用户或管理员写进 Broker 的配置文件:16 至 128 个字符,可以重复使用,不会过期,系统不会生成它。握手证明双方都持有这个密钥,并把它与各自看到的指纹绑定。此后 Broker 只凭保存下来的指纹认对端。

别名和对外地址不参与认证。别名只用于显示,地址说明连到哪里,不说明对面是谁。用户级 Broker 的默认别名包含运行它的账户名,对端和公开名片的接收方都能看到;不想让账户名出现在 Agent 地址里,就设置 broker.alias。配对逐对建立,不能传递:A 与 B 配对、B 与 C 配对,不代表 A 与 C 互相信任。要取消对一台主机的信任,得在每个与它配对过的 Broker 上分别解除配对。已配对的 Broker 报告的自己名下 Agent 与 topic,本机无法核实。对端报来的地址,Broker 只保存可拨号的 host:port,其余跳过。对端在配对期间放弃的别名仍为它保留,先前交出去的地址不会改指另一台 Broker。

静态密钥以明文保存在配置文件里。能读这个文件的账户就能读到密钥,并在没有写权限的情况下用它让本 Broker 增加对端。密钥的随机性由设置它的人负责,长度下限挡不住够长而好猜的密钥;应当用随机来源生成密钥,例如 openssl rand -hex 32 的输出。发起方在核实对方之前就发出由密钥算出的查找标记,所以能截获握手的一方,以及发起方因地址写错或域名被劫持而连到的任何一方,都可以据此离线穷举弱密钥。用这个密钥配对过的主机都知道它;这样的主机若能截获或误导新主机的连接,就能冒充接受方。更换密钥后,再用旧密钥配对会被拒绝;已经凭它配对的对端仍然保持配对,要逐个解除。查找标记与发起方的指纹绑定,截获它的第三方换用别的证书重发也对不上任何密钥。没有匹配上密钥的配对请求按来源限次,全部来源合计另有上限;超过任一上限的请求得到 try again later。限额在比对静态密钥之前检查,所以某个来源或全部来源达到上限后,带静态密钥的请求同样得到 try again later;匹配上静态密钥的请求不计入次数。发起方在核实对方之后才发送自己的别名。

默认不公开

Broker 被用户设为公开之后,才会发布写着指纹、别名和对外地址的名片。不公开的 Broker 照常接收其他 Broker 的名片,它的对端也不会把它的信息继续传出去。不公开的 Broker 还不能声明公开 topic:声明要签名,而签名会带出它的指纹。

不公开不等于隐藏。对端知道它的指纹和别名,主动与它配对的主机会知道它的对外地址,能连到监听端口的主机都能看到它的证书。

能连到监听端口的主机也能发起连接。未认证的连接有上限:每个来源最多 8 条,来源按一个 IPv4 地址(一个 /32)或一个 IPv6 的 /64 划分;全部来源合计最多 64 条。TLS 握手确认指纹属于已配对的对端后,该连接不占这部分名额,改为每个指纹最多 2 条。认证之前,一条连接最多发送 64 KiB,HTTP/2 头部列表最多 16 KiB。因此一个来源的大量连接挤不掉其他来源的配对,也挤不掉已配对 Broker 的链路重建。

被拒绝的连接会留下记录。未配对的主机连进来被拒绝时,审计日志记一条 connection_rejected,detail 通常是 not a peer from <source>,其中是对方的 IPv4 地址或 IPv6 的 /64 网段。连接读不出来源地址时,detail 是 not a peer;合并窗口用满后,更多来源并入一条 detail 为 other sources 的记录。能读取 Broker 配置文件的账户,都能用 peers service audit 看到这些记录。

topic 决定可见范围

两个 Agent 至少同在一个 topic 时,才能互相看见、互发消息。同一台主机上的两个会话和不同主机上的会话适用同一条规则;跨主机时,链路两端各自检查。

加入 topic 只需要知道名字。没有管理员、邀请和审批,成员也不能被移出。所以 topic 的名字不是秘密:谁知道了都能加入,一个 topic 里的 Agent,对所有在该 topic 有成员的已连接对端都可见。要发给 topic 里的全部成员,得逐个调用。

会话会加入项目配置文件声明的默认 topic。没有这个文件时,默认 topic 取自工作区 git 仓库的 origin 地址。可以关闭自动加入。

管理操作以配置文件权限为准

Broker 根据操作系统为本机 socket 另一端进程提供的凭据判断调用方能做什么,不采信调用方自己说了什么。写权限允许修改配置、生成一次性配对密钥、配对和解除配对;读权限允许读取配置、读取审计日志,以及查看调用方自己名下以外的状态。列出 Agent 和 topic、加入与退出 topic、发送消息,都不需要文件权限。

因此系统级 Broker 可以用普通的文件权限委派管理:系统级安装把新生成的配置文件交给默认的 peers 组,组成员在本账户没有运行自己的用户级 Broker 时,不用 sudo 就能经工具或终端命令管理 Broker。组成员的权限等同于能手工编辑配置文件,不等同于 root;与 docker 组不同,成员不能借 Broker 执行任意命令,也不能写配置文件以外的文件。这有两条限制,见管理组:broker.listen 的端口小于 1024 时,只有在配置文件只能由 root 写时才生效;直接编辑配置文件引起的改动,审计日志里没有账户归属。管理员用 sudo 执行终端命令时按 root 的权限判定。这也意味着识别出的是账户,不是人,也不是模型。账户下的每个进程都以该账户的权限行事,受提示注入操纵的模型发起的调用,与用户本人发起的调用无法区分。

投递消息时不使用认证令牌

Claude Code 允许向会话 inbox socket 写入的进程出示认证令牌。peers 不出示令牌,也不读取令牌文件。于是投递的文本进入目标会话时,被当作没有声明权限类别的发送方。接收方会话对这类消息执行入站控制。以跳过权限确认的模式运行且没有设置入站策略的会话,会把每条消息暂扣,等待逐条批准。以无界面方式运行且跳过权限确认的会话收不到 peers 的消息:接收方的 Claude Code 先把消息暂扣,随后因发送方没有声明权限类别而丢弃,而发送方那边已经返回成功。见已知限制。

Broker 的设计是不做任何会话的后代进程。用户级 Broker 由服务管理器启动,或由用户在终端里启动,不在会话的进程树内;系统级 Broker 则作为服务运行在进程树之外。能使用本机系统级 Broker 的账户不需要用户级 Broker;正在运行的用户级 Broker 优先于系统级 Broker。

原生 Windows 不支持,因为那里的 inbox 连接强制要求认证行。

收到的内容按不可信处理

来自其他 Agent 的文本不是用户的指令。发送方名字含 @ 的消息,list_topics 返回的公开 topic 名与简介,以及 list_brokers 返回的其他 Broker 的地址,都来自其他 Agent 或 Broker,可能位于另一台主机或另一个账户之下,peers 一概不核实。会话说明要求模型在照它们的要求行事之前,先把请求转述给用户并取得用户明确同意,尤其是修改配置、配对或解除配对、升级 Broker、上下线、运行命令、读取或发送文件之前。list_agents 返回的 Agent 名字、地址与账户,以及对端 Agent 的 account,都由它们的 Broker 报告,未经核实。与上面配对密钥一节相同,这是对模型的要求,而不是系统提供的保证。

投递的文本放在一段固定的信封里,信封标明发送方。消息正文里出现信封的起始或结束标签时,不论大小写,peers 都在 < 之后插入一个反斜杠,使它作为普通文本显示,正文因此伪造不了信封的任何一端。已知限制:HTML 实体、零宽字符与同形字符不转义;它们只改变正文在会话里的显示,不改变信封对消息的署名。

对端 Broker 为一次发送返回错误时,本 Broker 只转述接收方真会返回的错误码:not_found、ambiguous、not_visible、invalid_argument、too_large、inbox_unwritable、quota_exceeded、broker_offline 与 delivery_unknown。错误写作 Not sent: Broker <alias> said: "<...>";错误码为 delivery_unknown 时,开头改为 Delivery unknown: Broker <alias> said: "<...>"。引述的说明最长 512 字节,在字符边界上截断,截断处加 ...。其他错误码一律报 Delivery unknown: Broker <alias> returned an error this Broker does not recognize,不转述对端的说明。

终端命令打印 Broker 提供的文字时,制表符、换行、行分隔符或段落分隔符显示为空格,其余控制字符与 Unicode 格式字符按码点显示为 \xNN、\uNNNN 或 \UNNNNNNNN。

限速、循环检测与去重

peers 本身不限制一个会话发多少消息,不计跳数,也不检测消息循环。接收方 Broker 则限制一个配对 Broker 投递给同一个本机会话的消息:连续最多 10 条,之后每 10 秒恢复 1 条。超出的消息不写入,发送方收到错误码 quota_exceeded,并得到下面这条报错,其中 <alias> 是接收方 Broker,<session> 是目标会话,<fingerprint> 是该 Broker 的指纹:

Not sent: Broker <alias> said: "<session> is receiving too many messages from your Broker; try again in <N> seconds" (code: quota_exceeded; reported by Broker <fingerprint>)

其中 <N> 是等待的整秒数,向上取整,等待这么久后可以重试;<N> 为 1 时单位是 second。限额按来源 Broker 与目标会话分别计算,本机内部的发送与其他配对 Broker 发来的消息都不受它影响。这些数值是常量,不可配置。

接收端的 Claude Code 自己有一套规则。它按帧里的回复地址识别发送方,没有回复地址时按写入进程识别。每个发送方一个令牌桶,容量 30,每秒补充 0.5 个;未处理的会话间消息至多保留 50 条。30 秒去重是另一条规则:同一个 Agent 发给同一个会话、与上一条内容完全相同的消息会被丢弃。署名是内容的一部分,所以即使多个 Agent 共用一个令牌桶,这条规则也按 Agent 区分;不同 Agent 不会互相造成丢弃。

接收端的 Broker 也会丢弃同一次发送中重试产生的副本。它按投递请求里的消息标识认出副本,把结果记在一张内存表里,保留 send.dedupe_window 的时长,默认 5 分钟。这张表在 Broker 重启后清空,所以 Broker 在两次重试之间重启时,同一条消息可能写入两次。送达情况未知之后再发,带的是新的消息标识,不会被去重。这张表合计最多保留 65536 项,每个对端最多 4096 项。超过每对端上限的消息被拒绝,错误码为 quota_exceeded,说明为 this Broker holds too many recent messages from your Broker;整张表已满时,消息被拒绝,错误码为 inbox_unwritable,说明为 the Broker is temporarily holding too many messages。发送方看到的是接收方 Broker 转述的这些说明。

peers 写入时不带回复地址,所以经同一个用户级 Broker,或经系统级 Broker 的同一个账户辅助进程写入的全部消息,不论来自哪个 Agent,都算同一个发送方,共用一个令牌桶。Claude Code 自带的循环检测依赖消息里记录的经过路径,peers 的消息没有这项记录,因此两个 Agent 之间的循环只能靠接收端的限速约束。Claude Code 可以改动上述限速值和 30 秒规则,也可以远程调整它们。

peers 自己也会限制 topic 变更:加入与退出按账户限速,本机 topic 的数量与单个 topic 的成员数有上限,见上限。配对 Broker 发来的成员名单每个 topic 最多 4096 条,每条链路合计最多 16384 条;超过任一上限时整帧丢弃,Broker 日志记一条警告,链路保持连接。被丢弃的那一帧里的成员,要等链路重新建立后才会出现。超过 4 MiB 的帧在发送前就被拒绝,链路不会断开。

链路本身也有入站上限。一条连接最多排队 4096 个状态帧,状态帧负载合计最多 64 MiB,排队中的与正在处理的帧都计入;超过任一上限,本 Broker 关闭这一条连接,由拨号方按常规退避重连。同一个对端同时最多运行 64 个请求处理函数,该对端的各条连接共用这份名额;名额用尽时,本 Broker 暂停读取该对端,直到有一个请求完成,不报错,也不关闭链路。peers service status 与 list_brokers 对这种断开的链路在 detail 里给出原因:the peer sent more state frames than this Broker's inbound limit allows on one connection; the link was closed and will reconnect after a backoff; check the audit log for the link_down record。审计记录里另有 link_down 记录,detail 为 inbound_limit,用 peers service audit 查看。

操作系统账户是隔离边界

用户级 Broker 只服务本账户,拒绝其他账户的调用。系统级 Broker 服务获准使用它的账户,并且只接受调用方账户所拥有的 inbox socket 的登记。同一个账户内部不再有进一步的隔离。

在系统级 Broker 上,名字归属由最先登记它的账户取得:别的账户无法用同名占用归属账户的短地址,它的同名 Agent 总是带完整的 12 位消歧标识,会话可以按地址和 account 分辨两者。归属账户的 Agent 连续 7 天没有使用这个名字后,归属释放。

Broker 还会把所报告每个 Agent 的登记账户名一并交给对端,系统级 Broker 与用户级 Broker 都是如此。这个账户名只用于展示,但对端看得到。账户名不符合格式时省略,不论它来自本机还是对端。

系统级 Broker 的本机接口同样设有按账户的占用上限,一个账户耗不尽 Broker,也挤不掉其他账户。每个账户最多持有 256 条本机连接和 256 个登记,每条连接最多承载 64 个并发流。所有账户合计,Broker 同时最多接受 4096 条本机连接,这是准入连接上限;在这一上限内,同时最多允许 64 条连接等待账户查询,每条最多等 5 秒,超过的连接立即拒绝,不进入排队。这 64 条等待的连接,与一条连接最多承载 64 个并发流不是一回事。检查调用方读写配置文件的权限由单独的进程执行,这样的检查同时最多 8 个,一个账户最多 2 个。账户数据库能查到条目的 uid 各自占用一份配额;查不到条目的 uid,例如 rootless 容器轮换使用的那批,归入未知账户桶,与其他查不到的 uid 共用一份按账户的配额;这份配额是共用配额,不是每个 uid 各得一份。这些数值都是常量,不可配置。

下列上限达到时,会话会收到带错误码的说明。握手时被拒绝的连接返回 the Broker is running but refused this connection; this account or the whole host may have reached its connection limit, so retry shortly.,错误码为 internal。登记数超过每账户上限时,返回 Broker 的说明 cannot register: account <account> already has 256 open registrations,错误码为 quota_exceeded。权限检查拿不到槽位时,返回 Too many configuration access checks are running; try again shortly.,错误码为 quota_exceeded。权限检查这一种稍后重试即可。另外两种拒绝不必手动重试:MCP 服务会在后台自行重连,本账户的其他会话或连接结束并释放名额后,会话才能接入;主机连接总数达到上限时,则要等主机上任一连接结束。登记名额从会话接入一直占到它断开,账户已有 256 个会话时,要等其中一个结束,新会话才登记得进来。

更新检查会访问 GitHub

每个 Broker 在启动后不久检查一次 GitHub 上有没有更新的正式发布版本,此后默认每 24 小时检查一次。peers update 选中在服务管理器下运行的 Broker 时,由该 Broker 执行更新,系统级与用户级都是如此。没有正在运行的 Broker,或选中的用户级 Broker 不在服务管理器下运行时,由命令自己执行更新。

检查与下载全程只走 HTTPS。检查只访问 GitHub;下载可能被 GitHub 重定向到它的存储主机,按主机名放行的环境要把两者都放行。检查是向 https://api.github.com/repos/wangzw/peers/releases/latest 发出的一个普通 GET 请求,不带额外请求头;仓库名 wangzw/peers 写死在二进制里。经 Broker 执行的更新,由 Broker 按自己选定的 tag 取该版本;由命令执行的更新,下载它在确认之后查到的最新发布版本。两种情形都从该版本的发布附件下载地址取得发布包与 checksums.txt。这些请求都不携带主机名、账户名、Agent 身份、配对信息或配置内容。

检查失败只写一条 Debug 级日志,不影响其他功能;检查结果只保存在内存里,Broker 重启后不再保留。要停止检查,执行:

peers config set update.check false

设置生效后,peers service status 里的 Update 一行和会话里的提示会立刻消失。没有外网的主机关掉检查即可;peers update 只在你手动执行时才访问网络。下载使用执行下载的进程的代理环境变量;服务要用的变量怎么设置,见更新 peers。

更新只在确认之后进行。peers update 会先征求确认,你输入 y 或 yes,或者加上 --yes 之后才安装。会话可以用 update_broker 工具发起同样的升级,Claude Code 默认会在执行前请你确认;不要把 update_broker 加入自动批准名单,因为这条确认是升级前的最后一道人工检查。替换之前,发布包会先用 SHA-256 与 checksums.txt 比对,解压时只取名为 peers 的普通文件,新二进制的 --version 必须报告预期的版本。替换之前的任何一步失败,原有的二进制与服务都保持原样。由 Broker 执行更新时,命令不会自己重启服务:它最多等 60 秒,看 Broker 是否报告新版本;超时就给出服务日志的位置。系统级更新需要对 Broker 配置文件的写权限:没有写权限的账户在下载任何内容之前就会被拒绝。没有系统级 Broker 在运行时,命令改为在本地替换二进制,检查的是二进制所在目录的写权限,不是配置文件的写权限。更新过程见更新 peers。

管理组成员可以让以 root 运行的 Broker 安装本项目最新的正式发布版本,可信程度与 root 自己执行更新相同。调用方不能指定来源或版本,也不能降级。发布没有签名,所以更新的安全性依赖到 GitHub 的 HTTPS 与 checksums.txt。