OpenPencil op-collab-relay-client 实战解析:受限的 TCP 到 WebSocket 中继数据面桥与挑战绑定认证

原创2026-10-11 17:19:331,462 阅读

OpenPencil op-collab-relay-client 实战解析:受限的 TCP 到 WebSocket 中继数据面桥与挑战绑定认证

op-collab-relay-client 是 OpenPencil 的开源原生中继数据面(data-plane)客户端:它把桌面端既有的回环 TCP 协作传输无缝适配到公网 WebSocket 中继上,却始终不终止、不解析内层 Noise 会话。本文从该 crate 的 README 出发,结合 lib.rs、auth.rs、endpoint.rs、limits.rs、owner.rs、guest.rs 等源码与测试,讲清它如何做「窄桥」设计、挑战绑定认证(challenge-bound authentication)、资源上限与生命周期管理,以及它如何被桌面宿主(op-collab-host)集成,让跨地域的 P2P 协作会话可经中继互联而文档权限边界不被破坏。

定位:中继只转发,不解析

crate 的定位一句话可以概括:把现有回环 TCP 协作传输桥接到一个公网 WebSocket 中继上,桥本身对内层 Noise 会话完全透明。lib.rs 的 crate 文档明确写道:

The relay forwards the bytes produced by the existing inner Noise/TCP transport. This crate does not parse, decrypt, log, or reinterpret them.

也就是说,文档帧在内层是 Noise 密文,对中继保持不透明;中继桥只负责搬运字节。但「转发」不等于「什么都看不到」——中继运营方依然能以明文看到承载票据(bearer ticket)、客户端 hello 以及握手前以明文出现的服务端 prelude(它属于 Noise prologue,无法加密)。关于「到底泄露了什么、还有哪些缓解措施」,README 明确指引读者参考 p2p-collaboration-threat-model.md 中的 "Relay operator visibility" 一节(该节的完整细节见下文「中继运营方可见性」)。

在 crate 分层上,op-collab-relay-client 与以下相邻模块协同:

  • op-collab-relay-protocol:定义挑战、证明、hello、reauth 等线上协议类型与编解码(如 RelayServerChallengeV1、RelayChallengeProofV2、RelayClientHello);
  • op-collab / op-collab-transport:内层 Noise 会话、票据准入、文档状态机;
  • op-collab-host:桌面端运行时,负责把本 crate 的桥接入真实的邀请、配对与启动流程。

本 crate 不包含任何签名密钥、服务凭据、账户策略或中继服务端实现——它是纯客户端数据面桥。

传输策略与端点约束

RelayEndpoint:一个「已被校验过传输策略」的 URL

RelayEndpoint 不是普通的 URL 包装:它在 parse 阶段就完成了传输策略校验,不合法就构造不出来。校验规则来自 RelayEndpoint::parse:

  • 长度不超过 MAX_ENDPOINT_BYTES(2_048 字节);
  • 不允许 URL 内携带用户名/密码(CredentialsNotAllowed);
  • 不允许 fragment(FragmentNotAllowed)与 query(QueryNotAllowed)——防止把秘密塞进 URL;
  • 路径必须精确等于 /v1/tunnel(InvalidPath);
  • 必须有 host(MissingHost);
  • scheme 必须是 wss;ws 仅在 debug/test 构建且端点为数字回环地址时被接受,否则报 InsecureEndpoint;其他 scheme 报 UnsupportedScheme。

其中 is_numeric_loopback 只认可 Host::Ipv4/Host::Ipv6 的回环地址——ws://localhost:30123/v1/tunnel 这种域名别名在 debug 下也会被拒绝,测试 debug_ws_accepts_only_numeric_loopback 验证了这一点。RelayEndpoint 的 Debug 输出同样整体脱敏为 [REDACTED]。

为什么生产必须 wss

桥的传输策略与威胁模型一致:中继会先做 TLS 终结再做准入认证,明文 ws:// 会把承载票据与 hello 直接暴露给网络路径。因此生产端点必须走 wss://,未加密的 ws:// 只作为调试与测试的例外通道存在。

挑战绑定认证:一次 attempt 绑定一个新票据

begin_attempt 的「一次性」语义

RelayAuthenticator::begin_attempt 返回一个不可克隆(non-cloneable)的 attempt,它独占一枚全新的 bearer。README 明确了这枚 bearer 的三段旅程:

  1. 放在 WebSocket 升级请求(upgrade request)上(即 Authorization: Bearer <token>);
  2. 在解析 101 响应携带的挑战(challenge)期间被保留;
  3. 被绑定进动态生成的 mode-2 hello 证明(possession proof)里。

源码路径:session.rs 的 connect_socket 在 ChallengeBound 模式下调用 begin_attempt 后立即 request.headers_mut().insert(AUTHORIZATION, value),并把 attempt 保存在 challenge_attempt 中;随后 parse_challenge 从响应头读取挑战(要求 openpencil-relay-challenge 头恰好出现一次,缺失/重复/畸形都会导致 Authentication 失败);最后 RelayAuthAttempt::finish 用同一 attempt 与挑战生成 hello。

关键在于:owner 车道(lane)补充与每一次重连都会开启新的 attempt。这样票据刷新永远不会把新 bearer 与旧证明混在一起——这正是 begin_attempt 返回不可克隆对象的目的(auth.rs 的 trait 文档:防止「刷新的 bearer 配上陈旧证明」)。

RelayClientX25519Agreement 与 PinnedRelayX25519Keys

  • RelayClientX25519Agreement:只暴露「设备已有公钥」与一次「归零化(zeroizing)的 X25519 协商」;绝不导出设备私钥。实现可以委托给 OS 密钥库或硬件密钥。
  • PinnedRelayX25519Keys:由应用/控制面提供的有界中继公钥集,通过挑战携带的 key_id 选择对应中继公钥(public_key(key_id) 查表)。构造约束包括:不能为空、最多 MAX_PINNED_RELAY_X25519_KEYS(32)个、key_id 不得重复、公钥不能全零(auth.rs 的 RelayServerX25519PublicKey::new)。

mode-2 证明的生成

RelayAuthAttempt::finish 的流程(auth.rs):

  1. 用挑战的 key_id 从固定公钥集中选中中继公钥(未知 key_id → UnknownRelayKey);
  2. key_agreement.agree(relay_public_key) 得到零化的共享秘密;
  3. 构造 RelayClientHello 的挑战绑定 v2 模板(new_challenge_bound_v2,角色 + 路由 + 无 possession proof 的认证扩展);
  4. RelayChallengeProofV2::derive(&shared_secret, &challenge, bearer_bytes, &template) 生成证明;
  5. 把证明塞回认证扩展,生成最终 hello。

证明的密码学细节在 challenge.rs:证明是 33 字节(1 字节版本 + 32 字节 HMAC 标签),密钥由 HKDF-SHA256(salt 为挑战 nonce、info 含域分隔符 .../challenge-proof-key/v2、key_id 与版本)派生,MAC 覆盖「域分隔符 .../challenge-proof-binding/v2 + 挑战规范二进制 + bearer 的 SHA-256 摘要 + 归一化 hello」——把 bearer、挑战、路由、角色全部绑死。RelayChallengeProofV2::verify 走常数时间的 verify_slice。

严格 API 与降级兼容路径

桥提供了两套启动入口:

  • 严格模式(start / start_default_lanes):要求挑战绑定认证器(Arc<dyn RelayAuthenticator>),当响应中挑战缺失、重复、畸形或选择了未知固定密钥时fail closed;
  • 降级兼容模式(start_ticket_binding_only / start_default_lanes_ticket_binding_only):只接受 Arc<dyn RelayCredentialProvider>,是唯一的 reduced-assurance 兼容路径,绝不可能从 mode 2 静默降级。

注意降级模式与 mode-2 的关系:降级客户端不会回答严格 reauth 控制挑战——测试 reduced_assurance_client_never_answers_strict_reauth_control 断言中继发来严格 reauth 文本帧后,降级客户端不会回文本帧,而是以 TextFrame 失败关闭,避免「假装降级、实际混用两种模式」。

RelayCredential:b64token 字符集与 48 KiB 上限

RelayCredential 接受 RFC 6750 的 b64token 字符集(字母数字、-、.、_、~、+、/),bearer 本身上限为 48 KiB(MAX_RELAY_BEARER_BYTES,在 reauth.rs 中定义并跨 crate 契约测试固定到 op_auth_bridge::MAX_COLLAB_TICKET_BYTES)。完整的 Authorization 值还要加上 7 字节的 Bearer 前缀——auth.rs 中 BEARER_PREFIX_BYTES = 7,并有测试 credential_accepts_the_authentication_bridge_ticket_ceiling 断言 7 + 48*1024 的精确长度。

字符集校验的严格程度直接服务于安全:credentials_reject_header_injection_and_redact_debug 测试证明 abc\r\nx-leak: yes、含逗号、含 = 的 bearer 都会被判为 InvalidCredential(防 header 注入),且 Debug 输出中 token 被替换为 [REDACTED]。

Debug 脱敏约定

README 承诺:locator、路由能力、凭据、端点与载荷值绝不进入 Debug 输出或错误信息。这一点贯穿全部类型:RelayCredential、RelayServerX25519PublicKey、PinnedRelayX25519Keys、RelayAuthAttempt、RelayAttemptResponse、RelayEndpoint、RelayHandshake 的 Debug 均为 [REDACTED],测试 handshake_debug_redacts_locator_capability_and_device_proof 与 endpoint_debug_is_redacted 直接断言不泄露 session-test、host 与路径。

资源上限与生命周期

常量与默认限值(limits.rs)

常量 值 含义
DEFAULT_OWNER_LANE_COUNT 4 owner 默认中继车道数
MAX_OWNER_LANE_COUNT 8 owner 车道数硬上限
MAX_RELAY_BINARY_BYTES 64 KiB 单帧二进制消息上限
MAX_RELAY_CONNECTION_BYTES 1 GiB 单连接累计字节上限

RelayLimits 默认的分阶段超时:

阶段 默认值 触发失败类型
connect(建连) 10 s ConnectTimeout
hello(发送 hello) 10 s HelloTimeout
pair(等待配对) 5 min PairTimeout
idle(空闲) 2 min IdleTimeout
lifetime(连接寿命) 24 h LifetimeExceeded
retry(车道重试间隔) 1 s —
stop(停止等待) 5 s RelayStopError::Timeout

establish_relay_with_ready_hook(protocol.rs)把每个阶段的时间预算与 lifetime 挂钩:phase_timeout 取「剩余寿命」与「阶段上限」的较小者,保证整条连接从建立到配对始终受 24 h 总寿命约束。

帧与字节的边界

pump(session.rs)是双向搬运循环,严格执行:

  • 只接受二进制应用消息:空二进制帧与超大帧(> max_binary_bytes)分别以 Protocol、BinaryFrameTooLarge 失败;
  • 文本帧只能作为 reauth 控制挑战被消费(严格模式),不参与转发;TextFrame 是一个独立的失败类型;
  • Ping/Pong 正常回放;Close 与对端断开正常结束;
  • 双向字节累计受 max_connection_bytes 限制,用 checked_add 防溢出,超限即 ByteLimitExceeded;
  • 空闲与寿命双 deadline 全程在场(sleep_until 与取消选择并行)。

WebSocket 配置(WebSocketConfig)的 max_message_size/max_frame_size 取 max_binary_bytes 与 reauth 响应文本上限的较大者,max_write_buffer_size 为该值的 3 倍——从传输层就开始封顶。

ReauthBudget:防中继把客户端当放大器

服务端发起的重认证受 reauth_budget.rs 双重约束(README 未展开,但源码文档解释得很清楚):

  • 最小间隔 = idle / 2(默认 60 s):合法票据轮换不可能快于一个 idle 窗口,再留 2 倍时钟抖动余量;
  • 最大次数 = 2 * (lifetime / idle)(默认 2 * (86400 / 120) = 1440):全程合法票据轮换至多 720 次,正好是上限一半。

这样恶意中继最多每分钟逼客户端铸造一枚新 bearer、每条连接最多 1440 次,避免被用作对自身认证后端的免费放大攻击。越界分别以 ReauthTooFrequent 与 ReauthBudgetExhausted 失败关闭,绝不静默忽略(测试 default_bounds_match_the_documented_arithmetic、normal_reauth_cadence_over_a_full_tunnel_lifetime_stays_within_budget 等验证了这套算术)。

两种桥:Owner 车道池与 Guest 单隧道

RelayOwnerBridge:有界车道池

owner.rs 的 RelayOwnerBridge 是一个「有界 owner 中继车道池」:start_inner 校验车道数在 1..=MAX_OWNER_LANE_COUNT,本地 socket 必须是非零端口回环地址。每个车道(lane)循环执行:

  1. 建立中继连接(发送 hello、等待 Ready 后 Paired);
  2. 连接本机 owner 协作 socket;
  3. 双向泵送(pump);
  4. 隧道结束后按 retry 间隔自动补充新车道(spawn_lane(delayed=true))。

wait_until_ready 等待「至少一条车道被中继认证并接受」(Waiting 或 Active 即返回),与配对无关——测试 owner_readiness_waits_for_relay_acceptance_not_pairing 验证 relay 发来 Ready 而未 Paired 时 wait_until_ready 已返回成功,状态为 Waiting。

RelayGuestBridge:单次使用的回环监听器

guest.rs 的 RelayGuestBridge 是一个「单次使用」的 loopback listener:绑定 127.0.0.1:0 随机端口,把一个既有 guest TCP 驱动连接到一条认证过的中继隧道。start_inner 在 lifetime 内等待首个客户端连接(超时则以 LifetimeExceeded 失败),随后 establish_relay(角色为 Guest)→ Active → pump。

状态机与失败类型

两个桥共享 error.rs 的状态模型:

  • RelayBridgePhase:Starting / Waiting / Active / Degraded / Stopped / Failed;
  • RelayBridgeStatus { phase, waiting_lanes, active_tunnels, last_error },通过 watch 频道可订阅(subscribe / status);
  • RelayFailureKind 覆盖 Authentication、Connect、各阶段超时、Rejected、Protocol、TextFrame、ReauthTooFrequent、ReauthBudgetExhausted、BinaryFrameTooLarge、IdleTimeout、LifetimeExceeded、ByteLimitExceeded、LocalIo、RelayIo、Closed 等,全部是封闭的、日志安全的类型。

owner 桥的 publish_owner 把池状态映射为:有活跃隧道→Active,只有等待车道→Waiting,有错误→Degraded,否则→Starting。

stop 与 Drop 语义

  • stop(BridgeHandle::stop)先发取消信号,然后在 stop_timeout(默认 5 s)内 join 工作任务;超时则 abort 并返回 RelayStopError::Timeout;
  • Drop 桥会发送取消并同步 abort 任务(BridgeHandle::Drop)——保证即使调用方忘记 stop,桥也不会泄漏后台任务。

桌面宿主中的真实集成

桥的调用方是 op-collab-host 的 relay 运行时:

  • owner 侧:解析一份已签名的中继 bootstrap,选定 home region 对应的完整条目(relay 端点 + locator 验证键 + relay X25519 固定键),构造 VerifiedRelayRoute 与 RelayHandshake,然后 RelayOwnerBridge::start_default_lanes(...) 并 wait_until_ready(OWNER_RELAY_READY_TIMEOUT)(22 秒)等待至少一条车道被接受;
  • guest 侧:经邀请(opc1_ 片段)或 10 字符配对码换取的密封邀请,验证 locator 后取 expected_discovery_id 与 owner 的 Noise 静态公钥,再 RelayGuestBridge::start(...) 在回环端口上等待本地 guest 驱动接入(guest_runtime.rs 记录了 Bootstrap → PairingClaim → RegionSelection → Clock → InviteVerification → LocalAuthentication → RelayBridge 的凭证无关启动阶段诊断);
  • home region 决定:OPENPENCIL_COLLAB_RELAY_HOME_REGION=cn|global 可作为 owner 侧本地覆盖;guest 侧 region 只来自签名邀请/配对码。README 强调:客户端不会根据 guest 当前所在区域静默迁移会话——中国驻留的 owner 可以把会话锚定在中继上,海外 guest 也连接到同一端点,绝不擅自切到 Global 入口。

开发模式

start_unauthenticated_for_development 只存在于 test/debug 构建,且要求端点必须是数字回环(DevelopmentEndpointNotLoopback 否则);桌面端还需要 OPENPENCIL_COLLAB_RELAY_DEV_UNSIGNED=1 与未加密回环 WebSocket 端点才进入 unsigned 开发回路。release 构建中这些 API 与分支都不存在。

中继运营方可见性:透明是设计决策

威胁模型 p2p-collaboration-threat-model.md 的 "Relay operator visibility" 一节与 README 相互印证:隧道载荷是 LAN 路径同款 prelude、Noise 握手与加密记录的逐字节桥接,配对后帧按不透明二进制转发、不被解析,中继永远看不到文档内容。但它能在自己的 TLS 终结后看到:

  • 完整准入票据(WSS Authorization: Bearer),其中含全局账户 subject、设备 id、展示名与头像 URL——README 因此强调 bearer「只准入中继带宽」,不是文档授权:内层 Noise 握手、签名协作票据与桌面的 owner-key/session/generation 校验仍是文档权限边界;
  • 客户端 hello(路由 id、角色、设备 X25519 公钥、possession proof、签名 locator);
  • 流量形态与明文服务端 prelude(携带 session_id/epoch 关联句柄)。

也就是说,本 crate 之所以把「不解析、不记录、不落盘」写进设计,正是为了在「中继必然可见准入元数据」的前提下,把文档内容的暴露面收敛为零。

测试验证:行为即契约

bridge/tests.rs 用真实 TCP/WebSocket 端点(非 mock)验证了核心行为:

  • guest_bridges_bytes_both_ways_and_preserves_authorization:双向字节转发 + Authorization 头原样保留;
  • strict_guest_reauthenticates_without_forwarding_text_or_losing_binary:严格模式下 reauth 文本帧被本地消费、二进制不丢失,每次 attempt 用新 bearer 生成可验证的 mode-2 证明(测试中 attempt-1 → attempt-2);
  • owner_refresh_attempts_use_fresh_bearers_challenges_and_proofs:owner 车道重连时挑战与证明都重新生成且互不相同;
  • owner_replenishes_lane_after_each_tunnel_and_bridges_both_ways:隧道结束后车道自动补充;
  • text_application_frame_becomes_a_redacted_error_status:非二进制应用帧导致 Failed 且错误输出不含帧内容。

这些测试既证明 README 承诺的「每个连接阶段、帧、字节数与寿命都有界」,也证明「只接受二进制应用消息」与「脱敏」不是口头约定而是可执行契约。

总结:桥的边界清单

  • 传输:生产必须 wss://;ws:// 仅限数字回环的 debug/test;路径固定 /v1/tunnel。
  • 认证:调用方拥有的 RelayAuthenticator,一次 attempt = 一枚新 bearer + 动态 mode-2 证明;start_ticket_binding_only 是唯一且显式的降级兼容路径,永不清零为 mode 2 静默回退。
  • 凭据:b64token 字符集、48 KiB 上限、7 字节前缀;Debug/错误全程脱敏。
  • 资源:64 KiB 单帧、1 GiB 单连接、24 h 寿命、2 min 空闲、5 s 停止超时、owner 车道 1–8 条、reauth 每分钟至多一次且每连接至多 1440 次。
  • 职责:只转发内层字节;不解析、不解密、不记录、不落盘;不含签名密钥与服务端实现——文档权限始终由内层 Noise 握手、签名票据与 owner-key/session/generation 校验守护。
登录后查看全文
openpencil