zoe/remotedesk

Fork 0

Files

T

曾志威 d5288dbf5e feat: add cross-platform Drone packaging

2026-09-04 00:52:18 +08:00

36 KiB

Raw Blame History

RemoteDesk 协议设计

1. 目标

协议服务于 Windows 客户端与自研 Linux Agent，不用于 Windows RDP。设计目标：

设备先配对，再创建桌面或终端会话。
信令、输入、媒体、剪贴板和文件相互隔离。
支持断线恢复、能力协商和动态网络质量。
消息可演进，旧版本能明确拒绝不兼容能力。
所有入口有大小、速率、状态和权限校验。

2. 分层

Application
├── Pairing / Device authorization
├── Session lifecycle
├── Input / Clipboard / File / Terminal
└── Quality control

Transport
├── TLS WebSocket              authentication/signaling
├── WebRTC RTP/RTCP            video/audio/feedback
└── WebRTC DataChannel         control/data

本地模式由 Agent 监听 TLS WebSocket；边缘模式由 Agent 主动连接 Rendezvous Gateway。WebRTC 媒体和 DataChannel 始终在会话进程与客户端之间建立，agentd/Gateway 只转发 SDP/ICE 信令。

3. 协议版本

每个 Envelope 包含：

message Envelope {
  uint32 protocol_major = 1;
  uint32 protocol_minor = 2;
  bytes message_id = 3;       // 16-byte UUID
  bytes session_id = 4;       // empty before session creation
  uint64 sequence = 5;
  uint64 sender_mono_us = 6;  // only meaningful within one sender
  MessageType type = 7;
  bytes payload = 8;
}

规则：

主版本不一致直接返回 INCOMPATIBLE_PROTOCOL。
次版本通过 capability bitset 协商。
未识别的可选字段忽略。
未满足的 required capability 导致请求失败，不静默降级。
monotonic timestamp 不跨机器比较；RTT 使用带 nonce 的 Ping/Pong 测量。
message/session ID 使用随机 UUID，不能由递增数据库 ID 替代。

4. WebSocket 帧

一个 binary WebSocket message 对应一个 Protobuf Envelope。
默认最大信令消息 1 MiB；握手、输入和控制使用更小的类型级限制。
压缩默认关闭，避免对包含认证数据的消息产生压缩侧信道。
未认证连接只能发送 ClientHello、配对相关消息和有限 Ping。
认证前执行连接数、消息速率和失败次数限制。

5. 设备配对

5.1 设备身份

Agent 安装时生成长期 Ed25519 设备密钥。
Windows 客户端首次启动生成长期客户端设备密钥。
私钥从不通过协议传输。
已配对记录绑定客户端公钥、名称、权限和撤销状态。

5.2 首次配对流程

Windows Client                         Linux agentd/local UI
      |                                         |
      |---- TLS ClientHello ------------------->|
      |<--- AgentHello + cert fingerprint ------|
      |---- PairStart(pairing code) ------------>|
      |<--- PairChallenge + nonce ---------------|
      |---- client key + signed transcript ------>|
      |<--- local confirmation pending -----------|
      |       user compares short fingerprint     |
      |<--- PairAccepted + permissions -----------|

配对码必须限时、限次且只能由 Linux 本地用户开启。双方显示由完整握手 transcript 派生的短指纹，由用户在 Linux 本地确认客户端名称和指纹。最终实现应使用经过审查的 PAKE/安全配对库；不得自行组合加密原语。

5.3 后续连接

使用已保存设备密钥进行双向认证。
TLS certificate/fingerprint 变化时中止自动连接。
每次连接使用新 nonce，签名覆盖双方 nonce、协议版本和 capability digest。
被撤销客户端在认证阶段拒绝，不能进入会话创建。

6. 权限模型

配对设备按能力授权：

DESKTOP_VIEW
DESKTOP_INPUT
AUDIO_RECEIVE
CLIPBOARD_READ
CLIPBOARD_WRITE
FILE_SEND_TO_HOST
FILE_RECEIVE_FROM_HOST
TERMINAL_OPEN
TERMINAL_RESUME
UNATTENDED_REQUEST

桌面查看不隐含输入权限，终端权限不隐含文件权限。权限变化立即增加 authorization_epoch；旧 epoch 的会话票据失效。

7. 能力协商

客户端和 Agent 交换：

Session types：Wayland、Xorg、Terminal。
Video codecs/profiles/levels。
Hardware encode/decode results，不只报告插件名称。
Raw-frame memory paths：DMA-BUF/D3D11 surface、GPU copy、CPU upload、software，以及是否经过短帧验证。
Agent GPU/DRM identity、DMA-BUF modifier/import 与硬件编码器的同设备匹配结果。
Audio codec 和 FEC/DTX。
Display count、尺寸、scale 和 capture type。
Input types：absolute、relative、keyboard、touch。
Clipboard MIME types 和最大大小。
RTX/NACK/FEC/TWCC 支持。
Portal permission level 和恢复能力。

能力摘要使用稳定排序后计算 digest，创建会话时将 digest 写入票据，避免协商过程被替换。

8. 会话创建

8.1 请求

CreateSessionRequest 至少包含：

request_id
session_type
target_user
requested_permissions
display_selection
quality_profile
zero_copy_policy: required_end_to_end | compatibility
client_capabilities_digest

required_end_to_end 是 Linux 图形会话默认值。Agent 在捕获/缩放/编码端、native-video helper 在解码/呈现端分别发送带 generation 的 EndpointMemoryPath；SessionController 只有在两端均为经过验证的 zero_copy 后才进入 Connected。任一端报告 gpu_copy、cpu_upload、software 或 opaque_gpu_path 都使协商失败。compatibility 必须由用户显式选择，不能由远端或自动重连自行降低策略。

EndpointMemoryPath:
endpoint: agent_encode | client_render
generation
status: zero_copy | gpu_copy | cpu_upload | software | opaque_gpu_path
adapter_identity
capture_device_identity
surface_type: dmabuf | d3d11 | cpu | opaque
cpu_map_count
cross_adapter_copy_count
verification_source

切换显示器、GPU、编码器、decoder 或分辨率会递增 generation，并使旧验证立即失效。两端必须重新报告；计数非零或验证信息缺失时不能进入严格 Connected 状态。

agentd 完成设备权限、目标用户、会话存在性和并发限制校验后，签发短期单次使用的 Session Ticket。

8.2 Ticket

Ticket 绑定：

client public key hash。
session ID/type/target UID。
permission bitset 和 authorization epoch。
issue/expiry time。
一次性 nonce。
capability digest。

Session 进程只接受 agentd 签名且未过期的 Ticket。Ticket 使用一次后进入短期 replay cache。

8.3 生命周期

CREATED -> AUTHORIZING -> NEGOTIATING -> CONNECTED
                                      -> DEGRADED
                                      -> RECONNECTING
                                      -> CLOSING -> CLOSED
                       failures ----------------> FAILED

所有状态变化包含 reason code、可重试标记和用户安全展示文本 ID。不得仅发送任意字符串错误。

8.4 多显示器布局

显示拓扑是独立、带版本的安全边界：

DisplayLayout:
  generation
  displays[]:
    stable_id: 16 bytes
    rect: x, y, width, height
    scale: numerator / denominator
    is_primary

DisplaySelection:
  layout_generation
  mode: single | all | custom
  display_ids[]

坐标使用物理桌面像素，主屏原点固定为 (0, 0)；位于主屏左侧或上方的显示器使用负坐标。布局必须恰好有一个主屏，并拒绝空布局、重复 ID、零尺寸、无效缩放、坐标端点溢出和累计像素数溢出。自定义选择拒绝空集合、重复/未知 ID 以及 generation 不匹配。

显示器热插拔、位置、旋转、DPI、分辨率或主屏变化都会发布新 generation。输入、捕获选择、分辨率请求和零拷贝报告必须绑定同一 generation；收到旧 generation 时丢弃请求并重新同步，不能按数组序号猜测显示器身份。

Windows RDP helper 把验证后的本地布局映射为 Display Control Dynamic Monitor Layout。Linux Agent 把同一选择模型映射到 Portal/PipeWire 或 XRandR 捕获源，但不会修改 Linux 实体显示模式。

8.5 Windows Headless Compatibility Contract

Windows Headless compatibility 模式允许无硬件 GPU 主机使用可用的 Desktop Duplication 或 IDD 输出、WARP 或 CPU 编码，但必须显式报告 software 和 degraded。能力结果至少包含 capture_backend、adapter_type、surface_type、encoder_backend、hardware_encoder_verified、hardware_pipeline_verified、hardware_path_verified、cpu_map_count、max_width、max_height、max_fps 和 concurrent_sessions。hardware_encoder_verified 只代表真实短样本编码成功；DDA staging/readback 仍有 CPU map，因此该路径的 hardware_pipeline_verified 和 hardware_path_verified 必须为 false。若请求硬性要求 4K/120 或硬件编码，而本地只有 software 路径，Agent 返回 HARDWARE_ENCODER_UNAVAILABLE，不得静默降级。

Windows Headless 媒体契约固定为 SDR 8-bit：video codec 为 H.264/AVC、H.265/HEVC 或 AV1，输入格式为 NV12，audio codec 为 Opus。IDD 不提供本项目的 HDR10/10-bit 能力，不得出现 P010、Main10 或 HDR metadata。

Windows Headless 视频使用 Hysteria2 不可靠 datagram，允许丢失。缺少一个分片时丢弃整个帧；过期帧不重传；首帧非 IDR、sequence 中断、discontinuity、解码失败或关键帧损坏时，经独立可靠控制流发送带 session ID 的 request_keyframe。Client 以 250 ms 最小间隔合并请求，Agent 以容量 1 的队列合并请求并通过 CODECAPI_AVEncVideoForceKeyFrame 请求编码器输出 IDR。收到新 codec config 和 IDR 后才能恢复普通帧。

本地 encoded-ring descriptor 只能经 \\.\pipe\RemoteDesk\... 命名空间交付。Pipe DACL 只授权当前用户 SID，拒绝远程客户端并启用首实例保护；双方从进程环境取得同一个随机 32 字节 base64url bootstrap，Agent 为每个连接发送 32 字节随机 nonce，Go bridge 返回 HMAC-SHA256(key, "RemoteDesk Windows Agent pipe auth v1\\0" || nonce)。bootstrap 不进入命令行或 JSON，双方读取后从各自环境删除；认证和 hello 共用有界握手时限。仅 authenticated: true 的连接可作为生产 descriptor 来源，ring 路径、session ID、generation、owner PID 和 geometry 必须全部校验后才能映射。

RDA1 音频 datagram 使用固定 40 字节 little-endian header：magic/version/reserved/header_bytes、stream ID、generation、sequence、PTS、duration_ms 和 flags，后接一个不超过 4 KiB 的独立 Opus packet。reserved 必须为 0，当前仅定义 discontinuity flag，duration 仅允许 10/20/40/60 ms；未知 flags、零 identity、空 payload 和超限 packet 必须在进入 jitter buffer 前拒绝。音频 packet 不依赖 RDV1 frame ID，不因视频分片缺失而等待或丢弃。

输入控制使用独立可靠高优先级流，带 input_seq 和 layout_generation。输入发送不等待视频帧、编码完成、媒体 ACK 或音频播放。文件和剪贴板使用独立可靠低优先级流，不能阻塞输入、音频或视频。

音视频共享 session clock/QPC 映射和 generation，但独立采集、编码、队列和发送。客户端以音频播放时钟同步视频，视频落后时丢弃旧帧，不为追求完整帧率而增加播放延迟。

Hysteria2 音频包使用独立的 RDA1 datagram，不进入视频分片重组器。固定 40 字节头包含 stream、generation、sequence、100ns media PTS、duration（10/20/40/60 ms）和 flags，Opus payload 上限为 4 KiB。音频包独立丢弃或播放，视频缺片不能阻塞音频，音频丢包也不能阻塞视频。Windows compatibility runtime 已使用独立 worker 完成 WASAPI loopback、48 kHz 双声道 20 ms Opus、独立 mmap ring、Go RDA1 发送，以及 viewer 有界 jitter/FEC/PLC/WASAPI playback 的源码接线；统一 session-start QPC、长时间漂移校正和真实设备验收仍是发布前条件。

9. WebRTC 信令

Offer/Answer 和 ICE candidate 放入 Protobuf 信令消息。
SDP 大小和 candidate 数量有限制。
DTLS fingerprint 必须与 Session Ticket/握手身份绑定。
ICE 优先直连，并接受 Allocator 签发的短期 TURN credential。
Allocator 返回 DIRECT/SINGLE_EDGE/DUAL_EDGE 候选路径、Client/Agent POP 和路径 generation。
智能优选可以让两个端点使用不同 relay candidate，经供应商骨干连接两个 POP。
TURN credential 绑定 POP、session/allocation、有效期和配额，不能替代 Session Ticket。
边缘 Gateway 只路由已签名请求，Agent 仍是最终授权方。
网络接口变化可以触发 ICE restart；失败后重建 PeerConnection。
路径变化使用递增 generation，旧 POP 探测和 credential 结果不得覆盖新选择。

当前 Edge HTTP 信令边界使用域隔离的 EdgeNegotiationEnvelopeV1，只允许已被 Agent 接受且仍有效的 Session Intent 建立 mailbox。send/poll 都由对应 Client 或 Agent Ed25519 key 签名；签名覆盖 request ID、session ID、端点角色、操作、sequence、generation、消息类型、payload、nonce、签发和过期时间。send sequence 从 1 开始并按端点严格递增；共享 generation 从 1 开始，只有 restart 可精确加一；poll 的 sequence 是已消费的 peer cursor。服务端拒绝过期、重放、跨会话、跨角色、乱序、错误 generation 和超限消息，只返回 peer 产生的消息。

Agent Presence 注册、续期和注销使用域隔离的 AgentPresenceProofV1。Agent 首次启动自动生成并保护 Ed25519 设备身份，不要求用户提供密钥文件；Device ID 从设备公钥稳定派生。签名覆盖 Device ID、公钥、region、gateway、connection ID、register/unregister 动作、注册租约到期时间、一次性 nonce 和签发时间。Edge 在修改路由前验证身份绑定、最长 30 秒时钟偏差和 nonce 未使用，因此共享 Presence token 只能作为 API 访问凭据，不能单独创建、覆盖或删除设备路由。Agent signal poll/ack 继续使用独立的设备签名证明和一次性 nonce。

资源上限为 SDP 128 KiB、单 candidate 4 KiB、每端点每 generation 128 candidates、每会话 512 消息、单次 poll 64 条且 payload 最多 192 KiB、最多 1024 活跃 mailbox 和总 payload 8 MiB。该 mailbox 只完成控制信令转发；DTLS fingerprint、TURN credential 和最终媒体连接仍必须由端点 WebRTC 层验证。

9.1 Edge Path Messages

边缘路径协商增加：

PathProbeRequest(candidate_pops, token, expires_at)
PathProbeReport(endpoint, pop, udp/tcp/tls metrics, token)
BackboneMetric(pop_a, pop_b, rtt/loss/jitter, provider_signature)
PathSelection(mode, client_pop, agent_pop, transport, generation)
RelayCredential(pop, endpoint, allocation_id, expires_at, quota)
PathSwitchRequest(old_generation, candidates, reason)

端点探测只代表最后一公里；POP 间骨干指标必须来自受信控制面或供应商测量，不能由客户端任意声明。PathSelection 不授予会话权限，必须与有效 Session Ticket 同时使用。

10. DataChannel

Channel	ordered	retransmit	优先级
control	是	无限/连接级超时	最高
key_button	是	有限时间可靠	最高
pointer_motion	否	0 或极低	高
terminal	是	可靠	高
clipboard	是	可靠	低
file	是	可靠	最低

键盘按键与鼠标按钮不能与高频移动共用不可靠 channel。SCTP buffered amount 达到高水位时，文件和剪贴板生产者暂停。

11. 输入协议

键盘事件：

event_id
hid_usage
pressed
modifiers
layout_id
unicode_text optional

鼠标事件：

event_id
mode absolute|relative
display_id
topology_version
x/y or dx/dy
buttons
wheel_x/wheel_y

绝对坐标使用固定整数范围归一化，避免浮点差异。显示器拓扑版本不匹配时丢弃位置事件并请求最新拓扑。重连、失焦和断开时交换完整按键状态，释放可能卡住的键。

12. 质量控制协议

分辨率控制使用可靠、有序的 Control DataChannel。客户端先读取 DisplayCapabilities：

display_ids/topology_version
source_width/source_height
min_width/min_height
max_width/max_height
max_pixels
width_alignment/height_alignment
dynamic_reconfigure
supported_modes: follow_window | source_native | fixed

客户端发送 ResolutionRequest，Agent 返回 ResolutionApplied 或结构化错误：

request_id
generation
mode
target_width/target_height optional
adaptive_downscale
topology_version

ResolutionApplied:
request_id/generation
source_width/source_height
encoded_width/encoded_height
reason: requested | network_downscale | capability_clamp | source_changed

宽高在进入媒体管线前校验并按编码器约束对齐，不能由 Agent 静默放大到超出用户目标。旧 generation 的请求和确认均忽略。Linux 的请求只改变编码尺寸，不代表修改 Wayland/Xorg 的实体显示模式。RDP 使用相同的客户端状态模型，但请求由 RDP helper 映射到 Display Control，而不是发给 Linux Agent。

Agent 周期性发送 QualityReport：

rtt_ms
loss_fraction
jitter_ms
gcc_target_bps
nack_rate
pli_count
encode_time_ms
send_queue_ms
current_ladder
source_width/source_height
encoded_width/encoded_height
resolution_generation
capture_memory_path
encode_memory_path
client_render_memory_path
zero_copy_verified

客户端返回 decode/render time、dropped frames 和 DataChannel buffer。质量档位切换消息带 generation，旧 generation 的异步结果忽略。媒体自适应细节见 network-adaptation.md。

13. 剪贴板

Offer/Request/Data 三阶段，不收到 Request 不发送内容。
文本第一版只支持 UTF-8 plain text。
MIME type allowlist 和单项大小限制。
内容带 content hash，重复内容不循环同步。
本地/远端 sequence 防止双方互相回写。
权限撤销、锁屏或会话结束立即清理缓冲。

协议 minor 15 将文本剪贴板接入 X11 桌面会话。begin_direct_web_rtc 和 open_desktop 新增默认关闭的 clipboard_read、clipboard_write，分别表示 Client 可读取被控端剪贴板、可写入被控端剪贴板；agentd 必须再次对照配对授权检查方向，并只透明转发结构化消息，root 进程不得读取内容。发送方先用单调非零 sequence、UTF-8 字节数和小写 SHA-256 发送 DesktopClipboardOffer，接收方验证 32 KiB 上限后以同 sequence 请求，发送方才返回无 padding 的 canonical Base64 DesktopClipboardData。接收方将 Data 与当前待处理 Offer 的 sequence、长度和摘要绑定，拒绝无效 UTF-8、NUL、非规范 Base64、CR/CRLF 未规范化或摘要不匹配的内容。双方记录最近应用/发出的摘要，避免系统剪贴板所有权变化造成回写循环；只保留最新待请求内容。minor 14 及更早客户端缺少协商字段时两方向均为 false。当前源码实现 X11 与 Windows CF_UNICODETEXT，Wayland Portal 剪贴板尚未接入。

协议 minor 16 在 Ed25519 challenge 签名成功后增加强制 TOTP 步骤。Agent 发送 TotpRequired { digits: 6, period_seconds: 30 }，Client 必须在 30 秒内返回 VerifyTotp，随后 Agent 才能消费一次性配对码或返回 Authenticated。Agent 不保存客户端提交的动态码，对失败来源执行限流，并按已验证 Client 公钥拒绝同一时间步重放。未配置 TOTP 的 agentd 拒绝启动；Edge relay 仅透明转发这段固定证书的 TLS/WSS 流量，不参与 TOTP 校验。

14. 文件传输

FileOffer -> Accept(path policy) -> Chunk* -> Complete(hash)
          -> Reject/Cancel

文件名是名称，不允许携带绝对路径或 ..。
Agent 生成目标临时路径，完成哈希校验后原子改名。
Chunk 使用固定最大大小和 offset，支持已确认范围恢复。
总大小、并发数、速率和磁盘剩余空间均有限制。
软链接、特殊文件和设备节点默认拒绝。
Critical 网络状态暂停数据块但保留控制消息。

当前文件协议 minor 4 的上传请求包含由 Client 对 target user、相对路径、声明大小和整文件 SHA-256 派生的稳定 transfer ID。Agent 不信任 Client 提供 offset；降权 file helper 只打开目标目录中该 ID 对应的普通 partial 文件，读取实际长度并哈希已有前缀，再通过 FileReady.offset 返回。中断时保留 partial，续传只接收剩余字节；达到声明大小但整文件 SHA-256 不符时删除 partial，成功时才原子替换目标。

协议 minor 5 增加 X11 桌面兼容传输。OpenDesktop 绑定授权普通用户、最大宽高和 1..30 FPS；会话中的 DesktopResize 可把最大宽高重配为 200..8192。Client 合并连续窗口变化后发送最终尺寸，Agent 在当前帧收到 DesktopFrameAck 后才按新上限捕获下一帧，不修改 Xorg 的实体显示模式。每帧先发送 DesktopFrameStart，再发送严格递增的 45 KiB DesktopFrameChunk，最后用 DesktopFrameComplete 携带未压缩 BGRA 的 SHA-256。Client 只有在分块数量、压缩长度、解压后精确字节数和 SHA-256 全部匹配且窗口成功呈现后才发送 DesktopFrameAck；Agent 在收到该 ACK 前不捕获下一帧。DesktopPing/DesktopPong 在当前 WSS 或 Edge relay 会话内测量实际往返时间，不依赖两端时钟。单帧最多 33,177,600 像素、128 MiB 未压缩数据和 64 MiB 压缩数据，解压读取使用精确上限防止压缩炸弹。

桌面输入使用 DesktopInput，包含绝对指针、五键鼠标、水平/垂直滚轮、X11 keysym 按下/释放和 release_all。Agent 根据当前用户 X server 的 keyboard mapping 将 keysym 转为 keycode，客户端不能直接注入平台相关 X keycode。桌面断开、窗口失焦和退出都会释放 Agent 跟踪的按键状态。

协议 minor 6 为 X11 兼容链路增加短时会话续接。首次 OpenDesktop 不携带令牌，用户会话进程生成 32 字节随机 URL-safe Base64 令牌，并在 DesktopOpened 返回；agentd 从已完成 Ed25519 认证的 ClientGrant 注入客户端指纹，远程请求不能自行指定该绑定。WSS 或 Edge relay 异常断开时立即释放 XTEST 输入状态，丢弃未完成帧和 ACK，但保留 X11 连接、递增帧序列和自适应 pacer 15 秒。Client 按 1、2、4 秒有界重连，重新执行证书固定和 Client 身份认证，Edge 路径重新申请一次性 relay 票据，再以同一用户和令牌调用 OpenDesktop。只有令牌、客户端指纹、目标用户和有效期全部匹配才恢复；成功后令牌立即旋转，旧令牌不可重放。Windows Client 还把最新令牌保存到当前用户 Credential Manager，并按 Agent TLS 证书指纹和 Linux 用户隔离；helper 进程异常退出后，在 15 秒租约内以相同身份重新启动可读取令牌继续会话。正常关闭、服务端关闭或恢复拒绝会删除该记录，令牌不进入 argv、浏览器状态或普通文件。恢复从新的完整帧边界开始，不重放断线期间的输入、帧分块或 ACK。命令解析、状态校验、采集或输入注入失败也统一释放 XTEST 输入，但不建立恢复租约；正常 Close 同样不创建租约。

协议 minor 7 在 DesktopFrameMetadata 增加实际 compression_level。X11 兼容链路从 zlib level 1 启动：连续两个慢呈现 ACK 且最近编码耗时不超过当前帧预算三分之一时，逐级提高压缩至最多 6；连续两帧编码耗时超过帧预算一半时逐级降低；连续 60 个在帧预算内完成的 ACK 后逐级回到 level 1。等级和帧率控制器都使用真实编码计时与呈现 ACK，状态随 15 秒恢复租约保留。每帧诊断同时报告等级、压缩后/未压缩字节比例和编码耗时，客户端仍按元数据长度上限、精确解压长度与 SHA-256 完整性验证后才呈现。

协议 minor 8 为桌面打开命令增加签名 Intent 的 edge_session_id 和 Agentd 到用户会话的显式 webrtc_h264 协商位，并增加 DesktopH264Start/Chunk/Complete/Unavailable 内部事件。Agentd 只有在 session ID、过期时间、目标用户和已认证 Client 指纹全部匹配时才单次消费 WebRTC sender，直连请求不能取走 Edge sender。每个 Annex-B access unit 独立声明尺寸、时长、关键帧、编码耗时、编码器和分块数；Agentd 按 16 MiB AU 上限、45 KiB 分块、严格顺序、canonical base64、精确长度及 SHA-256 验证后才发送。

协议 minor 9 增加显式 DesktopVideoMode、DesktopVideoModeChanged 和 DesktopH264FrameAck。Client 只有在实际呈现第一张原生 H.264 帧后才请求 webrtc_h264 模式；用户会话会等待当前 zlib 帧的呈现 ACK，在完整帧边界确认切换。确认后每次捕获只发送 H.264，不再编码或传输完整 zlib 帧，并等待对应 sequence 的 H.264 呈现 ACK 后才捕获下一帧。Agentd 只向 Client 转发 H.264 Start 元数据用于 sequence 绑定、采集和编码遥测，Chunk/Complete 仍仅在 root/user IPC 内使用。RTP 序号中断会立即产生恢复事件并切回 zlib，同时继续监听关键帧以便重新进入原生模式；客户端解码失败、媒体邮箱积压、轨道结束、sender/encoder 失败或三秒内未收到 H.264 ACK 时也显式回退。服务端确认回退后从下一张完整帧恢复兼容传输。zlib ACK 有五秒绝对上限，错误类型或旧 sequence 的 ACK 不推进采集节奏。

协议 minor 10 为 X11 桌面输入增加 pointer_delta。Windows helper 只有在用户启用相对鼠标并成功抓取当前窗口光标后才读取 Raw Input；同一事件循环批次的位移会合并，保留小数余量，并将每轴单消息限制为 -4096..4096。零位移、越界值和未知字段由 Agent 拒绝。X11 用户会话使用 XTEST root=None 的相对移动语义，不把相对量误当成缩放后的绝对坐标。Ctrl+Alt+Home 在本地切换捕获；失焦、重连、全屏切换和退出都会释放远端按键/按钮，失焦、重连和退出还会解除光标抓取并丢弃未发送位移。

协议 minor 11 为 DesktopFrameEncoding 增加 webrtc_h264，用于没有 zlib 原始帧回退的 Wayland 严格媒体会话。Agent 只有在认证后的 Portal 返回单个有效 PipeWire stream、DMABUF 到 VA surface/H.264 管线产生首个 IDR、EIS Sender 完成 seat/device/keymap 协商且 Agentd 已绑定对应 WebRTC sender 后才发送 DesktopOpened。每个 H.264 sequence 由实际呈现后的 DesktopH264FrameAck 推进；DesktopResize 在上一帧 ACK 后先停止旧管线，再重建管线并等待新 IDR。绝对输入必须匹配 Portal stream 与 EIS region 的 mapping_id；相对指针、五键、滚轮和键盘通过同一 EIS emulation 生命周期提交。严格管线不允许退回 CPU BGRA，协商或客户端硬解失败会结束该 Wayland 会话。

协议 minor 12 为 webrtc_h264 会话启用与 X11 相同的轮换恢复令牌语义。意外断线立即释放全部 EIS 输入并销毁旧编码器，但用户会话进程最多保留 Portal、PipeWire remote 和 EIS 连接 15 秒；租约同时绑定 Agentd 注入的已认证 Client 指纹和目标 Linux 用户。Client 仅对 minor 12 及以上持久化该令牌。恢复连接必须先建立并授权新的 WebRTC sender，提交相同绑定的令牌后 Agent 才消费租约、重建严格编码器、等待新 IDR 并以连续递增的 sequence 返回 DesktopOpened(resumed=true)。令牌在每次恢复时轮换；错误令牌、不同 Client/用户、显式关闭、ACK 超时、输入/编码错误或租约到期都会拒绝恢复并显式关闭 Portal。

协议 minor 13 增加认证 WSS 内的直连 WebRTC 信令。Client 先发送绑定目标用户、尺寸和帧率的 begin_direct_web_rtc，Agent 完成现有桌面权限校验后返回 ready；后续 direct_web_rtc_signal 只接受严格有界的 offer、answer、ICE candidate 和 ice_end。双方只有在 PeerConnection connected、本地 ice_end 已发送且远端 ice_end 已消费后才离开信令阶段，从而保证后续 OpenDesktop 不会与残留 ICE 消息混用。OpenDesktop 的用户、尺寸和帧率必须与授权阶段完全一致，Client 指纹仍由 Agent 注入。直连仅使用 host candidates，不依赖 Edge/TURN；失败时 Client 发送 abort_direct_web_rtc，Agent 返回一次 direct_web_rtc_unavailable 后才允许 OpenDesktop(webrtc_h264=false) 进入 X11 zlib。Wayland 不接受该软件回退。成功时 Agent 直接把本次 PeerConnection 的 H.264 sender 交给用户会话代理，并在桌面结束或任一代理错误后显式关闭 ICE/DTLS/SRTP。

协议 minor 14 为 begin_direct_web_rtc 和 open_desktop 增加默认关闭的 opus_audio。Client 只有在对端 minor 不低于 14 且本次 WebRTC 媒体会话存在时才发送 true；minor 13 及更早 JSON 缺少该字段时反序列化为 false。直连授权把音频选择与 Client 指纹、用户、尺寸和帧率一同绑定，失败回退时视频和音频都必须关闭；Edge 路径也只在请求显式开启且取到绑定当前 session/user/Client 的媒体 sender 后向用户会话注入 true。未协商音频时用户会话不启动系统输出捕获，agentd 不向 Client 转发任何 Opus packet/unavailable 事件。协商后 Linux 用户会话仅捕获 Pulse/PipeWire 的默认输出 monitor（或经严格名称校验的管理员覆盖），编码为 48 kHz 双声道、20 ms、96 kbps Opus；每包限制 4 KiB，序号、时长、编码耗时和 canonical Base64 在 root/user IPC 边界重新校验。音频 sender 或 Windows 本地解码/播放失败只关闭音频，不中断 H.264 或 zlib 视频。

X11 用户会话把请求的 1..30 FPS 视为上限，并使用“帧写入 IPC 完成到客户端成功呈现 ACK”的真实反馈调整捕获节奏。连续两帧 ACK 超过当前帧预算两倍或 250 ms 时将目标速率降为当前值的约 75%，最低 1 FPS；连续 30 帧在预算内时每次恢复 1 FPS，最高不超过请求值。档位变化从新的完整周期开始，输入、Ping/Pong 和关闭消息不受帧计时器限制；丢失、错误序列或未呈现的帧不会被当作快速样本。

客户端主动退出时先发送 release_all 和 Close。用户会话进程完成 XTEST 按键/按钮释放后返回 DesktopClosed { reason: "client_closed" }，system Agent 最多等待 2 秒并转发该终止事件；控制端在收到关闭握手或超时后关闭 WebSocket。窗口仅保留 Ctrl+Alt+F 全屏切换，其他键盘事件直接进入远端输入链路。

下载请求携带本地隐藏 partial 的实际长度。Agent 按远端文件真实大小拒绝越界 offset，返回同一 offset、完整大小和 SHA-256，并只发送剩余区间。Client 在追加前重新读取并哈希已有前缀，完成后校验前缀与新增数据组成的整文件哈希；不匹配时删除 partial，匹配后才原子改名。partial 路径不允许替代已存在的最终目标。

15. 终端协议

终端消息包括：

PTY output bytes。
Client input bytes。
Resize(cols, rows, pixel width/height optional)。
Signal(INT/TERM/HUP allowlist)。
Exit(code/signal/core flag)。
Resume(last received sequence)。

协议传输字节而非命令字符串，Agent 不拼接 shell 命令。输出环形缓冲区有固定上限，超过后返回 OUTPUT_GAP，客户端明确提示丢失历史输出。

16. 重连与幂等

Create/Close/Transfer 等请求携带 request ID，Agent 维护短期幂等缓存。
会话租约由 heartbeat 延长，断线后进入有限 grace period。
重连请求携带 session ID、resume token 和各 channel 最后确认 sequence。
输入事件默认不跨断线重放；终端/文件按各自序号恢复。
恢复成功后请求视频 IDR 并重新同步显示器、权限和输入状态。

17. 错误模型

错误分为：

AUTH_*          配对、证书、票据、权限
SESSION_*       类型、状态、并发、用户会话
CAPABILITY_*    编码、Portal、显示器、输入
MEDIA_*         捕获、编码、WebRTC、解码
TERMINAL_*      PAM、PTY、Shell、退出
FILE_*          路径、空间、哈希、权限
NETWORK_*       超时、重连、协商
INTERNAL_*      非预期内部错误

错误包含稳定 code、retryable、retry delay 和 correlation ID。内部路径、堆栈和密钥信息不发送给远端。

18. 资源限制

实现前锁定默认上限：

未认证连接数和每 IP 配对尝试。
每设备并发桌面/终端会话。
Protobuf message、SDP、candidate 和字符串长度。
分辨率宽高、总像素、像素率和运行时重配频率。
剪贴板、文件、终端输出缓存和日志大小。
DataChannel buffered amount。
会话创建、Portal 授权、协商和重连超时。

上限由安全配置决定，远端请求只能降低，不能提高系统硬限制。

19. 测试

Protobuf golden vectors 与 round-trip。
主/次版本兼容和 unknown fields。
状态机非法转换的 property tests。
重复 request、过期 Ticket 和 replay。
截断、超长、乱序和未知消息 fuzz。
输入断线后的卡键恢复。
文件路径穿越、磁盘不足和 hash mismatch。
DataChannel 拥塞时输入优先级。
协议日志脱敏测试。

Windows Agent Android transport

After mandatory TOTP authentication, Windows Agent protocol minor 3 advertises supported_media_transports: ["webrtc", "plain_stream"]. Android requests WebRTC first:

{"kind":"open_desktop","capture_mode":"compatibility","media_transport":"webrtc","frames_per_second":30}

The Agent starts bounded Windows H.264 capture and returns webrtc_media_ready with the desktop dimensions, ICE server list, and negotiation timeout. Android is the sole offerer; the Agent is the answerer. Both sides exchange one JSON object per TCP line:

{"kind":"webrtc_signal","signal_kind":"offer|answer|ice_candidate|ice_end","payload":"..."}

SDP is capped at 128 KiB and ICE candidates at 4 KiB by the shared WebRTC boundary. Both endpoints must signal candidate completion. The Agent returns desktop_opened only after ICE/DTLS connects and both remotedesk-control and remotedesk-pointer DataChannels arrive. H.264 uses WebRTC RTP, RTCP feedback, NACK/RTX and DTLS-SRTP. Reliable ordered keyboard, button, text, keyframe, and close commands use remotedesk-control; pointer moves use an unordered, short-lived channel. Android's native WebRTC stack owns RTP, jitter handling, H.264 decode, and Flutter Texture rendering.

The Windows Agent optionally reads at most eight validated STUN/TURN entries from REMOTEDESK_WINDOWS_ICE_SERVERS. It passes the same session credentials to Android only after TOTP succeeds. With no configured entries, both peers use host candidates for LAN/VPN routing.

If WebRTC negotiation or Windows H.264 capture is unavailable, the Agent returns webrtc_media_unavailable and Android requests media_transport: "plain_stream" on the same authenticated TCP connection. RDWF v2 uses a 40-byte header followed immediately by the zlib payload:

Offset	Size	Value
0	4	ASCII `RDWF`
4	1	Protocol version (`2`; readers also accept `1`)
5	1	Codec (`1` = BGRA8 + zlib)
6	2	Reserved (`0`)
8	4	Width
12	4	Height
16	4	Uncompressed BGRA byte length
20	4	Compressed payload byte length
24	8	GDI capture latency in microseconds (v2)
32	8	zlib encode latency in microseconds (v2)

BGRA rows are top-down and tightly packed at four bytes per pixel. The Agent caps this fallback at 30 FPS, a 16384-pixel dimension, and 256 MiB for raw/compressed frames; Android applies the tighter 33,177,600-pixel and 64 MiB compressed-frame limits before inflating in a worker isolate. WebRTC media and DataChannels are encrypted, but the direct TCP signaling channel has no TLS or host identity. TOTP alone does not prevent a signaling MITM, so this mode remains limited to a trusted LAN, private VPN, or authenticated AnyTLS tunnel.

36 KiB Raw Blame History Unescape Escape