openpencil 协作传输层解析:op-collab-transport 的 Noise/TCP 框架、准入边界与设备密钥持久化

原创2026-10-11 18:39:081,415 阅读

openpencil 协作传输层解析:op-collab-transport 的 Noise/TCP 框架、准入边界与设备密钥持久化

本篇技术指南以 openpencil 仓库中的 op-collab-transport crate 为主体,系统讲解 OpenPencil 点对点实时协作所依赖的原生传输层:M1 代 TCP 记录分帧(record framing)、Noise XX 握手、经认证的分块传输、准入边界、连接资源限制、设备静态密钥持久化以及可选的 mDNS 局域网发现。读完本文,你将掌握 ConnectionDriver 事件循环的驱动方式、ConnectionLimiter 的防洪设计、入站方向策略与重组预算的配合,以及 OsKeyStore/FileKeyStore 两级密钥存储与票证续期生命周期,并能直接在本地运行 mDNS 冒烟测试验证整条链路。

crate 边界:传输层负责什么,不负责什么

从 lib.rs 的模块声明与公开导出可以看出,op-collab-transport 是 OpenPencil 协作体系中原生(native)侧的传输实现,它拥有以下职责:

  • M1 代 TCP 记录分帧与 Noise_XX_25519_ChaChaPoly_BLAKE2s 双向握手(见 noise.rs);
  • 经认证的传输分块(transfer chunking)与重组(reassembly);
  • 准入边界(admission boundary)与连接资源限制(connection limits);
  • 设备静态密钥持久化(OS 凭据存储 + 文件回退);
  • 可选的 mDNS 局域网发现(mdns feature)。

同时,README 明确划清了边界:协作序列化与文档变更逻辑并不在本 crate 中,它们属于保持 wasm 纯净的 op-collab crate;生产环境中的签名密钥、设备令牌、账户凭据也不进入本 crate——票证验证通过一个窄化的公开 trait(TicketVerifier)由宿主注入(见 admission.rs)。

在 Cargo.toml 中可以看到 feature 设计:默认 native(启用 keyring、secret-service、windows-sys 三个平台凭据依赖),mdns = ["native", "dep:mdns-sd"] 额外引入 mdns-sd,另有 test-support 供测试使用;且 native feature 在 wasm32 目标上会直接触发编译错误,从侧面印证了本 crate 只面向原生平台。

生产驱动:ConnectionDriver 事件循环

README 给出的核心生产用法是:让 ConnectionDriver 成为一条已连接 TcpStream 及其 Noise 状态的唯一拥有者。它在两个方向上都是非阻塞的,保留部分读/写,对排队与重组数据设上限,并且从不跨 I/O 持有 Noise 锁。GUI 线程与文档线程应当把类型化命令发送给事件循环线程,而不是直接触碰连接。

下面是 README 中的驱动骨架(原样保留,可直接对照源码理解):

let (_, secure) = connect_secure_tcp(
    address,
    &device_static_key,
    selected_discovery_id.as_deref(),
    config,
)?;
let budget = SharedQueueBudget::new(config.connections.global_queued_bytes)?;
let inbound_policy = if is_initiator {
    InboundTransferPolicy::OwnerToGuest
} else {
    InboundTransferPolicy::PeerToOwner
};
let mut driver = ConnectionDriver::new(secure, budget, inbound_policy)?;

if is_initiator {
    driver.queue_admission(&local_hello, Instant::now())?;
}

loop {
    let now = Instant::now();
    let polled = driver.poll(now)?;

    match polled.event {
        Some(DriverEvent::Admission(hello)) => {
            let identity = driver.verify_remote_admission(
                &hello,
                &ticket_verifier,
                expected_issuer,
                expected_subject,
                now_unix_ms(),
                now,
            )?;
            if !is_initiator {
                // The responder reveals its ticket only after authenticating
                // the initiator.
                driver.queue_admission(&local_hello, now)?;
            }
            authorize(identity)?;
            driver.authorize_remote(remote_role)?;
            driver.activate(now)?;
        }
        Some(DriverEvent::Frame { frame, .. }) => handle_frame(frame)?,
        None => {}
    }

    if driver.ticket_renewal_due(now) {
        request_or_expect_renewal();
    }

    let wake_at = [polled.rate_ready_at, driver.next_deadline()]
        .into_iter()
        .flatten()
        .min();
    schedule_socket_or_timer(wake_at, polled.has_pending_output);
}

事件循环的内部原理

结合 driver.rs 源码,这个循环背后有几条关键机制:

  • 每轮最多 64 步 I/O:MAX_IO_STEPS_PER_POLL(driver.rs)限制单次 poll 的读写推进量,写一次、读一次交替进行,任何一侧没有进展就提前退出,避免饥饿;
  • 进度截止(ProgressDeadline):解码器持有半条记录、或出站仍有未写完的密文时,check_progress_deadlines 会在 read_write(默认 15 秒)超时后报 ReadTimeout/WriteTimeout,防止卡死的对端长期占用事件循环;
  • 单一唤醒点:next_deadline() 聚合了票证续期/硬到期、心跳、空闲、重组超时、读写进度、读写限速恢复共 8 类单调时钟截止,返回最早的那个,配合 rate_ready_at 决定 socket 或定时器何时唤醒;
  • 速率令牌桶:读写两侧各维护 bytes 与 records 两个令牌桶(见 runtime.rs 的 TokenBucket::new)。发送每条记录前先计算 rate_ready_at,未到恢复时刻则返回 WaitingForRate(deadline) 而不加密、不占 nonce;
  • 心跳排他:出站队列为空且距上次发送超过 heartbeat(30 秒)时,maybe_start_heartbeat 才构造心跳记录;已有待发数据时心跳被推迟,保证心跳不挤占业务流量。

阻塞式辅助 API 与"原子化"发送

README 强调:SecureConnection 还暴露一个阻塞式辅助 API,供聚焦型工具和测试使用。其 send_transfer(runtime.rs)会先把整个传输按配置的突发额度(burst)原子化预检:先通过 TransferChunkIter 计算记录数与线上字节数,检查两个出站令牌桶的可用额度,不足则整体返回 RuntimeError::RateLimited——因此限速拒绝不会留下半个传输。生产驱动 ConnectionDriver 则相反:逐条经认证的分块进行限速与恢复,天然支持大传输的平滑续发。测试 tcp_noise_mutual_admission_activation_frame_and_rate_limit(tcp.rs)专门验证了这一点:把 bytes_per_second 压到 1 后,send_transfer 立即返回 RateLimited,而对端随后读到的是 unexpected.is_err()——即没有部分传输被写上半截。

握手与连接准入边界:ConnectionLimiter

README 对 accepted socket 的处理给出了明确纪律:在派生 worker 之前先获取 ConnectionLimiter::try_begin_handshake,随后调用 accept_secure_tcp_guarded,只有在票证准入成功后才把 pending 守卫转换成 active 守卫。每个存活中的 pending worker 都持续占用一个全局席位和一个按地址计数的席位;被守卫的 accept 把 handshake_first_message 作为 socket 的真实读取截止——直到收到第一条合法 Noise 消息为止,静默的 worker 会在释放席位之前退出。

为什么"先占座、后加密"

源码注释(config.rs)解释了设计动机:pending 席位在任何密码学工作之前就被占用,且只在票证准入后转换为 active 连接。一个 pending 席位的成本被限制为:一个 Noise 记录(MAX_NOISE_CIPHERTEXT_BYTES,60 KiB + 16 B)加一个正在重组的 Ticket 传输(MAX_TICKET_TRANSFER_BYTES,64 KiB),合计不足 128 KiB。在默认 128 个席位的上限下,最坏情况是 128 × 128 KiB ≈ 16 MiB,最多被持有 timeouts.handshake(5 秒)。

但上限本身不是全部防线:tcp.rs 中的 accept_secure_tcp_guarded 通过 on_first_message 回调,在 Noise 应答方第一条有效握手消息通过校验时报告进度,并同时把 I/O 截止从 handshake_first_message 切换到完整握手窗口。测试 silent_guarded_accept_exits_at_first_message_deadline_before_releasing_its_seat(tcp.rs)模拟了一个只建连、不发字节的静默对端:它在 handshake_first_message(测试中 100ms)到期后退出并释放席位,此前新地址的握手会被 PendingHandshakesFull 拒绝;a_guarded_accept_keeps_the_pending_seat_after_the_first_handshake_message(tcp.rs)则验证了完成握手后席位会继续持有,直到连接真正结束。

每地址配额与平台差异处理

ConnectionLimiter(connection_limit.rs)内部维护 pending_by_ip 计数:每个源地址最多 max_pending_handshakes_per_ip(默认 4)个 pending 席位。配置测试 pending_ceiling_leaves_headroom_for_honest_joins_under_a_silent_flood(config.rs)断言:即便 4 个地址各自打满配额,洪水占用的席位仍低于 128 上限,且 128 / 4 = 32——填满 pending 池至少需要 32 个不同源地址,而不是旧版 16 席位时只要 4 个。

accept_secure_tcp_inner(tcp.rs)还有一个易被忽视的平台坑:BSD/macOS 的 accept 会继承监听 socket 的非阻塞标志(Linux 不会),而握手读取依赖 set_read_timeout,该超时只在阻塞 socket 上生效——若不重置,macOS 上每条入站连接的第一个应答读都会瞬间返回 WouldBlock 被踢掉。因此 accept 路径无条件执行 stream.set_nonblocking(false)。测试 accept_completes_on_a_stream_inheriting_the_listener_nonblocking_flag(tcp.rs)在每个目标平台都强制模拟继承标志来覆盖这一行为。

入站方向策略:谁可以发 Snapshot

README 指出,入站方向策略属于分配准入的一部分:owner 会在认证头部解析后、预留 snapshot 重组预算之前,拒绝 guest 发起的 Snapshot 传输;而 guest 允许 owner 发起的 snapshot 用于初始同步与日志缺口恢复。

源码中对应实现有两个层次:

  1. InboundTransferPolicy(driver.rs):allows() 直接禁止 (PeerToOwner, TransferClass::Snapshot) 组合,frame_direction() 把策略映射为 op_collab::InboundFrameDirection,用于帧解码时的消息方向校验;
  2. SecureConnection::ensure_inbound_transfer_allowed(runtime.rs):阻塞路径上,若远端角色是 guest(方向为 GuestToOwner)且类别为 Snapshot,返回 ForbiddenInboundClass。

README 强调的"信任方向"还决定预解析 JSON 信封的上限:guest 攻击者声明的消息类别无法选中更大的 owner Snapshot 预算——因为 ChunkHeader::decode 与方向策略都在解码之前就把类别钉死了。此外,聚合重组预留(aggregate reassembly reservation)在最后一个分块之后仍然计费,只有完整字节被解码或丢弃后才释放(见 chunk.rs 的 CompletedTransfer._reservation 注释)。DEFAULT_GLOBAL_INBOUND_REASSEMBLY_BYTES = 128 MiB 的注释(config.rs)给出算账:64 个已认证对端 × 4 MiB 事务会吃掉 256 MiB,远超任何单连接上限,因此必须有一个进程级聚合上限;该上限恰好容纳 1 个完整 owner snapshot(64 MiB)+ 16 个最大事务(16 × 4 MiB),并把传输侧入站堆占用压到出站聚合(256 MiB)的一半。config.rs 甚至用编译期断言 assert!(DEFAULT_GLOBAL_INBOUND_REASSEMBLY_BYTES >= MAX_SNAPSHOT_TRANSFER_BYTES) 和 <= DEFAULT_GLOBAL_QUEUED_BYTES 固定这两个常量关系(config.rs)。

记录层与传输分块:record framing 与 ChunkHeader

密文记录:2 字节大端前缀 + Noise AEAD

record.rs 定义了线上最小单元——密文记录:

  • 每条记录 = 2 字节大端长度前缀(u16)+ Noise 密文;
  • 密文长度上限 MAX_NOISE_CIPHERTEXT_BYTES = 60 KiB + 16 B(NOISE_AEAD_TAG_BYTES),明文上限 MAX_NOISE_PLAINTEXT_BYTES = 60 KiB(config.rs);
  • encrypt_record/decrypt_record 在长度校验通过后才读写,解密结果包在 Zeroizing<Vec<u8>> 中,防残留;
  • read_ciphertext_record 先校验长度再分配——长度为零或超限的记录在分配缓冲区之前就被拒绝(测试 reader_rejects_length_before_allocating_or_reading_body 覆盖);
  • 篡改检测由 Noise 的 AEAD 认证天然完成(测试 tampering_is_authenticated 翻转最后一个字节即报 Decrypt 错误)。

活跃性标记也定义在此:record.rs 的 TRANSPORT_HEARTBEAT_PLAINTEXT = b"OPHB\0\0\0\x01",8 字节固定明文,经同一 AEAD 加密后走普通记录通道。

分块:24 字节头部 + 每块不超过 60 KiB

chunk.rs 定义了 CHUNK_HEADER_BYTES = 24 与 MAX_CHUNK_PAYLOAD = 60 KiB - 24。ChunkHeader 结构如下:

字段 长度 说明
version 1 B 当前为 1,不支持即拒绝
class 1 B Control=1 / Ticket=2 / Txn=3 / Snapshot=4
reserved 2 B 必须为 0,否则 ReservedBits
transfer_id 8 B 大端 u64,禁止为 0,且不允许回放(ReplayedTransferId)
chunk_index 4 B 大端 u32,严格递增,首个分块必须是 0
chunk_count 4 B 与 total_len 推导值必须一致
total_len 4 B 大端 u32,非零且不超过类别上限

四种类别的单次传输上限(config.rs):

  • MAX_CONTROL_TRANSFER_BYTES = 64 KiB(Control)
  • MAX_TICKET_TRANSFER_BYTES = 64 KiB(Ticket),其中票证本体上限 MAX_TICKET_BYTES = 48 KiB
  • MAX_TXN_TRANSFER_BYTES = 4 MiB(Txn)
  • MAX_SNAPSHOT_TRANSFER_BYTES = 64 MiB(Snapshot)

Reassembler 的 push_inner(chunk.rs)在首块(chunk 0)时就按对端声明的 total_len 向聚合预算预留内存,超预算立即报 InboundBudgetExhausted,杜绝"对端先声明内存、进程级预算却看不见"的攻击面;随后逐块校验 class/transfer_id/chunk_count/total_len 四元组一致、chunk_index 严格等于预期、每块 payload 长度与 expected_payload_len 吻合。任何差错都会清空 in_flight 并释放预留。check_timeout 按类别选择超时(Snapshot 走 snapshot_transfer 60 秒,其余走 ordinary_transfer 10 秒,见 chunk.rs),即使后续分块不再到来也会在截止时刻自行超时。

帧编码器与敏感路径:RenewTicket 永不落入共享队列

README 明确了几个严格约束,源码逐条可查:

  • 预编码帧只能由经过校验的帧编码器创建:EncodedFrameTransfer(frame.rs)内部把字节分为 Shared(Arc<[u8]>) 与 Sensitive(SensitiveFrameJson) 两种存储;
  • 非票证传输可跨对端队列共享不可变编码:普通帧走 Shared 引用计数,一个编码好的 Commit 可以同时排入多个对端队列而不复制事务负载(try_clone_shared/shares_storage_with 只允许共享存储克隆);
  • 票证传输保持唯一所有权:QueueItem::reliable 与 coalescing 两个构造器对 Ticket 类别直接返回 SensitiveTransferNotShareable(queue.rs),票证只能通过 sensitive_ticket_frame/sensitive_admission 进入队列,且 Zeroizing 保证每条 drop 路径都会清零;
  • 队列项类型是 crate 私有的,收到的传输字段通过借用访问器暴露,而不是公开的可克隆存储——TransportTransfer/CompletedTransfer 只公开 class、transfer_id、bytes()(借用)与 encoded_len;
  • 带负载的传输类型实现"脱敏 Debug":NoiseSession、AdmissionHello、VerifiedTicketClaims、CompletedTransfer、TransportTransfer 等类型的 Debug 输出只报告类别、ID、编码长度等元数据,私钥/票证/主体一律 "<a href="https://link.gitcode.com/i/a374fd85a156c79c511d9420f9fb3237" target="_blank">REDACTED]"(例如 [admission.rs)。

对于 RenewTicket:README 指出通用 raw JSON 与帧传输编码器会拒绝它。对应实现是 EncodedFrameTransfer::encode 的分流(frame.rs)——遇到 CollabMessage::RenewTicket 走 encode_renew_ticket,调用 op_collab 的 encode_renew_ticket_frame_to_zeroizing_json 直接写入唯一持有的 zeroizing 存储,不先构造 serde_json::Value、也不经过普通编码缓冲区。准入、分块、解密、重组与续期命令一路搬运这份不可共享的所有权,全程不克隆票证明文。

活跃性与票证生命周期

心跳与空闲判定

准入激活后,空闲连接交换由 Noise 加密认证的固定传输层心跳。README 特别强调:只有成功解密后的入站记录才会刷新入站空闲截止——本进程自己发出的写操作不能让自己活着,无法响应的心跳方会在 idle(120 秒)到期后被判定死亡。源码中 poll_read_once 在 plaintext == TRANSPORT_HEARTBEAT_PLAINTEXT 时刷新 last_activity/last_received_at 并继续(driver.rs);receive_transfer_inner 的阻塞路径同样只对心跳刷新活跃时钟,注释明确说明"心跳保活会话,但只发心跳的对端不能把调用钉满整个票证生命周期"(runtime.rs)。

票证续期:80% TTL 单次提醒 + 硬到期

票证过期在安装时被转换为单调时钟截止(ticket_deadlines,runtime.rs):renewal_at = now + 剩余 TTL × 4/5(即剩余 TTL 的 80% 处),deadline = now + 剩余 TTL。ConnectionDriver::ticket_renewal_due 是一个一次性提醒(ticket_renewal_notified 置位后不再重复),直到续期成功才为新票证重新武装(driver.rs)。

续期校验(verify_renewal_ticket,admission.rs)要求:

  • 同一个 issuer、subject、device_id 与 Noise 静态公钥;
  • 新票证到期时间必须晚于旧票证(RenewalDidNotExtend 否则);
  • 新票证未过期;
  • 成功后 renew_ticket 原子地重装 ticket_renewal_at 与 ticket_deadline 两个截止(runtime.rs)。

准入状态机

AdmissionState 定义了四个阶段(admission.rs):Encrypted(Noise 完成)→ IdentityVerified(票证校验通过)→ OwnerAuthorized(owner 显式授权)→ Active(激活)。authorize 只允许从 IdentityVerified 前进,activate 只允许从 OwnerAuthorized 前进——Active 必须经过 OwnerAuthorized,跨账户场景下的人类审批闸门不可跳过(对应 admission.rs 中 PeerIdentityPolicy::AnyIssuedAccount 的注释:只有两种前置条件允许选择它——owner 侧的人工审批,或 guest 侧已通过带签名 locator 线下固定对端 Noise 公钥)。PeerIdentityPolicy::SameAccount { subject } 则是多设备同步场景(尤其 LAN 加入,mDNS 可被伪造、无预先已知密钥)下认证对端身份的唯一来源。

设备静态密钥持久化:OsKeyStore 与 FileKeyStore

平台凭据存储

OsKeyStore(os_key_store.rs)按平台选择后端:

  • macOS:Keychain(keyring crate 的 apple-native feature);
  • Windows:Credential Manager(windows-sys 的 Win32_Foundation/Win32_Security_Credentials);
  • Linux:桌面 Secret Service(zbus + RustCrypto,经 keyring 的 async-io/async-secret-service/crypto-rust 与 secret-service crate)。

存储值带版本前缀且对文本安全:STORED_KEY_PREFIX = "op-noise-x25519-v1:" 后接 URL-safe base64(无填充)编码的 32 字节私钥(os_key_store.rs),因此对 KDE Wallet 这类 Secret Service 实现也是安全的。锁定、不可访问、歧义或畸形条目一律fail closed,绝不静默替换设备身份;Linux 上 secret_service::Error::Unavailable 被映射为 PlatformStoreUnavailable,其余错误映射为 PlatformStoreFailure/UnsafePlatformEntry/PlatformStoreAccessDenied(os_key_store.rs)。写入后还会重新读取一次再返回,保证 OS 存储始终是事实来源(并发进程可能已抢先初始化)。

文件回退的硬化要求

FileKeyStore(key_store.rs)是明确的回退方案,在 Unix 上强制:

  • 目录 0700、密钥文件 0600(create_private_directory/restrict_directory_permissions/restrict_open_file_permissions);
  • O_NOFOLLOW | O_CLOEXEC 打开,符号链接目录/文件直接报 UnsafeDirectory/UnsafeFile;
  • 原子创建:先写随机后缀的临时文件(create_new(true))、sync_all、hard_link 到最终路径、sync_directory,并发进程胜出时重新走硬化读路径验证;
  • 文件必须恰好 32 字节、不得全零(InvalidLength/AllZero 拒绝)。

README 的取舍很明确:宿主应仅在已知平台存储不可用时选择文件回退,而不是在它只是被锁定时——临时访问失败不能制造出第二个设备身份。因此桌面端默认顺序是:先 OsKeyStore,仅对 PlatformStoreUnavailable 回退;access-denied、畸形等其他失败继续 fail closed。

本地诊断开关

对于本地诊断,debug 断言构建的 openpencil-desktop 可设置环境变量 OPENPENCIL_COLLAB_DEV_FILE_KEYSTORE=1,绕过 OS 凭据存储直接使用上述同样硬化的 FileKeyStore。README 强调这个开关是精确的、release 构建忽略、不得在打包应用里启用。

配置总览:TransportConfig 的默认值与校验

TransportConfig(config.rs)由四部分组成,全部默认值如下:

TimeoutConfig(config.rs)

参数 默认值 含义
connect 5 s TCP 建连超时
handshake 5 s Noise 完整握手窗口
handshake_first_message 1 s 新接受连接产生首条合法握手消息的真实读截止
admission 10 s 建连后完成准入的窗口
ordinary_transfer 10 s Control/Ticket/Txn 传输重组超时
snapshot_transfer 60 s Snapshot 重组超时(必须 ≥ ordinary)
read_write 15 s 半条记录/半块传输的进度截止(必须 ≤ idle)
heartbeat 30 s 心跳周期
idle 120 s 入站空闲判定(必须 > heartbeat)

ConnectionLimits(config.rs)

参数 默认值 含义
max_pending_handshakes 128 全局 pending 席位上限
max_pending_handshakes_per_ip 4 每源地址 pending 上限
max_active_connections 64 active 连接上限
outbound_queue_items 8 每连接出站队列项数上限
global_queued_bytes 256 MiB 进程级出站排队字节聚合上限

RateLimitConfig(config.rs)

参数 默认值 含义
bytes_per_second 8 MiB/s 每方向字节速率
byte_burst 64 MiB + 64 KiB 突发额度,恰好容纳一个最大 snapshot + 一个最大 control
records_per_second 512 每方向记录速率
record_burst 2048 记录突发额度(足以容纳最大 snapshot 的分块数)

TransportConfig::validate(config.rs)在运行时把每个字段钉死在协议硬上限内(如 max_pending_handshakes ≤ 256、global_queued_bytes ≤ 512 MiB、byte_burst ≥ MAX_NOISE_PLAINTEXT_BYTES、各超时 ≤ 24 小时),并强制参数间关系(handshake_first_message ≤ handshake、snapshot_transfer ≥ ordinary_transfer、read_write ≤ idle、admission ≤ idle、idle > heartbeat)。invalid_resource_limits_fail_closed 等测试(config.rs)逐一验证非法值返回 ConfigError::InvalidValue。此外 m1_wire_limits()(config.rs)把 op-collab 协议侧的 WireLimits 上限调低到传输层的承载能力:M1_MAX_PRESENCE_BYTES = 44 KiB(为转义后的标识符与 PresenceChanged 信封留出 64 KiB 内的空间)、M1_MAX_TXN_BODY_BYTES = 4 MiB - 32 KiB(为 Submit/Commit 信封留出空间)。

平台 mDNS 冒烟测试

发现层(discovery.rs)的服务类型为 _openpencil-collab._tcp.local.,发布随机 16 字节 discovery id(32 个十六进制字符)、最多 16 个地址,并每 5 分钟轮换一次。确定性的解析器/缓存单测在常规 CI 中运行;而真正踩宿主多播栈的冒烟测试被 #[ignore] 标记,需要在每个原生平台 runner(或发布机)上、且 LAN 多播开启时显式执行:

cargo test -p op-collab-transport --features mdns \
  --test mdns_smoke -- --ignored --exact publisher_is_discovered_and_unregisters_cleanly

该测试(mdns_smoke.rs)只发布不透明随机 discovery id、验证被浏览器发现的端点(端口 45123)、注销发布、再等待浏览器缓存将其移除。它不启用泛化托管 runner——因为这类网络普遍抑制 mDNS,会把结果变成环境相关而非确定性的。接口自动选择有歧义的 runner 可设置:

OP_COLLAB_MDNS_SMOKE_ADDRESS=<该 runner 的活动 LAN 地址>

macOS 上发现 I/O 后端通过 dns_sd.h 使用系统 Bonjour 守护进程(对应 discovery.rs 中按 target_os = "macos" 切换的 discovery_bonjour* 模块族);Linux 与 Windows 继续使用 mdns-sd。macOS 发布者保留随机服务与主机标签、只注册属于合格本地接口的地址、绝不替代用户可见的计算机名。第二个 opt-in 检查验证浏览器与系统 dns-sd 发布者的互操作性:

cargo test -p op-collab-transport --features mdns \
  --test mdns_smoke -- --ignored --exact browser_interoperates_with_system_dns_sd_publisher

它启动一个真实的系统 dns-sd -R 进程发布 _openpencil-collab._tcp.local. 服务(端口 45124),断言自定义浏览器能发现并按期望的 id= 属性解析,随后注销并等待从浏览器缓存移除(mdns_smoke.rs)。

安全红线与日志纪律

README 最后重申的边界值得单独强调:生产票证签名密钥、设备/账户凭据、令牌交换与账户授权策略都留在本 crate 之外。日志与 Debug 输出绝不能包含不透明票证、Noise 私钥、账户标识符、文档文本或 snapshot——这正是前文所述"脱敏 Debug"与 Zeroizing 所有权设计的最终目的:即使一个 Debug 或错误路径触发了 drop,敏感明文也会被清零且不进入日志。理解这一层纪律,是把 op-collab-transport 正确嵌入宿主应用的前提。

延伸阅读

登录后查看全文
openpencil