[feat] pin coordinated UDP punching and validation tooling

docs/p2p-punching-implementation-plan.md

@@ -1,10 +1,10 @@
 # CrossDesk 双端 UDP 打洞增强实现方案
 
-状态：设计基线保留；已实现 P0 单端点后端与实验工具，macOS 本机机制验证通过，P0 双平台/双端抓包总验收尚未完成。P1–P5 尚未启动。日期：2026-09-13。
+状态：P0 门槛已通过；P1–P4 默认关闭原型、受控运行与跨平台构建已实现；P5 实验工具已交付，真实未知 NAT 对照和最终双端应用切换验收待执行。日期：2026-09-14。第 15 节保留 P0 历史记录，最新进展与边界见第 16 节。
 
 源码基线：CrossDesk `73e3bf709d7c054df7bd75cfafceda0721c6cda1`；MiniRTC 子模块 `f169a696cb4e6cb59037ec02e85532e30d3c1262`；libnice `0.1.24` 加仓库已有补丁。
 
-本文规定第一版的范围、接口职责、协议、资源预算、开发顺序和验收条件。新增名称、配置、接口和测试目标均为拟实现内容；现有代码位置另外标明。本文不代表功能已经实现或成功率已得到验证。
+本文规定第一版的范围、接口职责、协议、资源预算、开发顺序和验收条件。第 1–14 节保留设计基线，实际接口及完成情况以第 15–16 节和所链接的执行报告为准。实现和受控测试不代表真实 NAT 成功率已得到验证。
 
 ## 1. 目标与取证依据
 
@@ -407,7 +407,7 @@ P0 工具只能使用实验提供的明确对端地址，不含广范围探测
 交付：A/B/C 配置、自动汇总脚本、双端抓包复核和实验结论。
 
 - A：现有策略，增强关闭。
-- B：相同新协议与固定角色，一侧单端点，另一侧扩大目的端口。
+- B：相同新协议与相同的自动角色判定规则，一侧单端点，另一侧扩大目的端口；角色必须由有效观测支持。
 - C：与 B 相同，但使用端口池。
 
 按交错顺序重复 A/B/C，第一轮每组至少 30 次；保持网络、版本、STUN/TURN 和其余配置相同，记录每次启动间隔和真实端点。观察到一次成功不等于方案验收完成。
@@ -493,7 +493,7 @@ P0 工具只能使用实验提供的明确对端地址，不含广范围探测
 MiniRTC 实施提交：`7f0e666216891c9b79bd4a8f75b63741fe1fabf2`。
 本机最终检查为 22/22 通过，包括 en1 实际 IPv4 与内核接口绑定读回；这不是跨 NAT
 成功率。详情见 [P0 测试记录](../deps/submodules/minirtc/tests/ice/lab/p0-validation-2026-09-13.md)
-与 [构建、双机执行和抓包步骤](../deps/submodules/minirtc/tests/ice/lab/README.md)。
+与 [构建、双机执行和抓包步骤](../deps/submodules/minirtc/tests/ice/lab/p0-experiments.md)。
 
 本节是执行记录，不改变 P0→P5 的依赖门槛。**本轮没有完成可启用的“双端
 UDP 打洞增强”产品功能。** P0 的本机机制已可运行；Windows、双端物理网卡抓包
@@ -509,7 +509,7 @@ UDP 打洞增强”产品功能。** P0 的本机机制已可运行；Windows、
 - `tests/ice/punch_peer_test.cpp`：两个独立进程/两台 LAN 主机的 P0 实验入口，
   私有共享目录提供测试信令，便于 Windows/macOS 后续配合；不是生产控制协议。
 - `tests/ice/lab/run_p0.py`：临时 coturn、STUN 就绪检查、场景矩阵、二进制 SHA、
-  结构化结果与清理；`tests/ice/lab/README.md` 给出准确构建、双机操作和抓包清单。
+  结构化结果与清理；`tests/ice/lab/p0-experiments.md` 给出准确构建、双机操作和抓包清单。
 - `src/ice/ice_agent.*`：明确 `dtls_peer_verified_`，统一两个握手完成入口的指纹
   验证；导出 SRTP 前要求验证成功；有界保留早于本端 READY 的 DTLS flight。
 
@@ -557,7 +557,7 @@ P1 的生产认证上下文、P2 速率公平预算、P3 广范围组合探测
 ### 15.3 验收和下一步
 
 当前可运行的构建与实验步骤见子模块
-`tests/ice/lab/README.md`；可公开的测试摘要保存在同目录的结果记录中。
+`tests/ice/lab/p0-experiments.md`；可公开的测试摘要保存在同目录的结果记录中。
 成功意味着本机真实中继 → 验证过的 DTLS → 新 socket 的认证入站 → 正常 STUN/
 nomination → 同一 socket 的双向 SRTP，不能将编译、短包 ACK 或一次局域网成功
 当作 P0 总验收或 P5 的真实网络收益。
@@ -565,3 +565,142 @@ nomination → 同一 socket 的双向 SRTP，不能将编译、短包 ACK 或
 P0 总门槛仍需 Windows x64 编译/执行、Windows/macOS 双端抓包、两个 ICE 角色、
 实际桌面媒体连续性及退出检查。完成这些后再冻结生产后端接口并进入 P1，沿用本文
 其余协议、预算和 P1–P5 验收要求。此处没有通过降低验收要求提前启动广范围探索。
+
+2026-09-13 后续进展：用户报告同步后的 Windows 构建成功，尚未取得 Windows
+网络测试日志或二进制哈希；不能将构建成功记为 P0 运行验收。两端实际不在同一
+局域网，当前双机夹具要求明确且互相可达的 UDP 地址，因此不能直接使用两端
+私网 IP 运行该夹具。`run_p0.py` 新增外部实验 TURN 模式，使 Windows 可以先
+独立完成本机双 ICE 角色、SRTP 和资源清理矩阵，无需本机安装 coturn。外部 TURN
+不等于双机直连拓扑，此调整不改变 P0 门槛、原升级窗口或后续阶段依赖。
+
+### 15.4 两台 Mac 局域网实测
+
+用户提供同局域网的第二台 arm64 Mac 后，已在 `192.168.31.125/en1` 与
+`192.168.31.102/en0` 执行真实双机 P0；双方系统均为 macOS 26.6.2。
+`run_p0_ssh.py` 仅用 SSH 传递实验 JSON 信令，探测、STUN 和 SRTP 仍通过真实
+LAN UDP socket 与原受控门控转发。没有改用 SSH 隧道承载被测传输。
+
+四种 ICE/端口池角色组合的媒体断言均通过。首轮严格双端逐包核对为 3/4 通过，
+另一组有一个 SRTP 包只出现在发送端抓包中，原始失败记录已保留，未改判为成功。
+该组以新端口、新 run ID 复测后通过，两端均取得零内核丢包统计。四种组合现均有
+探测 HMAC → 认证 STUN/提名 → 命中 socket 上双向 SRTP 的双机报文证据。
+
+双机夹具增加开池前至少 10 个中继 SRTP、停止探测后至少 10 个直连 SRTP、
+selected socket 的物理接口绑定读回；全部仍在原升级窗口内。仓库新增
+`verify_p0_capture.py`，核对实际 pcapng、ICE MESSAGE-INTEGRITY、提名 TID 和
+门控两侧的相同报文，私有密钥和原始抓包不入库。
+
+完整次数、哈希、例外、复现和清理记录见
+[双 Mac P0 实测记录](../deps/submodules/minirtc/tests/ice/lab/p0-lan-validation-2026-09-13.md)。
+本轮完成 Mac 双机机制与抓包验证，**没有替代 Windows 运行、跨平台及实际应用
+媒体验收**。P0 总验收仍未完成，P1–P5 继续保持未启动，生产功能默认关闭。
+
+### 15.5 Windows 局域网验收准备（2026-09-14）
+
+用户另提供同局域网 Windows：WLAN `192.168.31.220/24`，仓库
+`D:\SourceCode\crossdesk`，账户 `desktop-ri1qfbe\kunkundi`。用户输出确认
+Python 3.13.5 可用，MiniRTC 为 `7f0e666`，两个 P0 测试 EXE 文件存在。
+这些信息不代表测试已运行；升级后的双机媒体断言需要同步并重新构建 peer 目标。
+
+实验驱动增加 `--remote-shell powershell`，通过编码命令传入 Windows 的字面路径，
+仍仅使用 SSH 管道传递私有信令。抓包核验器允许显式指定两端物理和本地回环接口名，
+以适配 Npcap 的命名；未将虚拟网卡或回环流量当作物理网卡交付证据。
+README 补充 Windows SSH 驱动、两接口抓包和精确接口名核验步骤。
+
+本机已检查 Python 语法、带空格/单引号/中文路径的命令编码、POSIX 参数兼容，
+并用原 Mac 抓包回归默认和显式接口选择；改写接口名后的同一份 Mac 报文也能核验，
+错误物理接口或 anchor 回环接口会被拒绝。这只是工具回归，**未执行 Windows
+PowerShell 启动、Windows 网络矩阵或 Npcap 验证**。当前等待 Windows SSH 接入，
+后续使用本机临时 TURN 开展单机矩阵和四种跨平台角色组合，保持原 P0 门槛。
+
+### 15.6 Windows/macOS P0 验收完成（2026-09-14）
+
+Windows 真实单机矩阵 20/20 通过，包含两个 ICE 角色、100 次生命周期、取消、
+未命中、错误指纹和原截止时间。跨平台四角色均已取得命中端口上的认证 STUN、
+提名及双向 SRTP 的严格双端抓包证据。完整结果、二进制和抓包 SHA、失败样本及
+边界见 [Windows/macOS P0 记录](../deps/submodules/minirtc/tests/ice/lab/p0-windows-validation-2026-09-14.md)。
+
+本轮没有把全部尝试改判为通过：初次双机抓包为 3/4，修正夹具收尾后为 4/5。
+最终普通 Mac pool/controlling 一组有中段一个 SRTP 包只出现在 Mac 抓包；同角色
+的单向通知延迟 1 秒组严格通过，因此四种角色均已有最终版本证据。另一次 Windows
+开池前 TURN 媒体基线失败，针对两种角色复测均通过，原失败仍保留且原因未确立。
+Windows 抓包统计包含 16 个 flushed，pcap/dumpcap/接口丢包为 0；未声称总丢包为 0。
+
+经源码和最小实验确认两处夹具修正：Windows `IP_UNICAST_IF` GET 已为主机序，
+去掉重复转换；旧夹具等待对端完成消息时仍发媒体，另一端可先销毁 gate，单向
+延迟实验复现最后 13 包未转发。新增停止发送、交换最终序号、双端认证接收确认后
+再销毁的屏障；没有修改标准 ICE、原窗口、DTLS 或降低媒体门槛。
+
+完整 CrossDesk 两端编译成功，Mac 使用 `xmake r crossdesk` 提供 Slint 运行环境。
+用户对双向画面、声音、鼠标键盘和三次重连请求回复已完成，未报告异常；此项作为
+用户报告的普通应用回归，不能声称独立测量了 pool 切换时的实际编解码连续性。
+命中 socket 的切换与认证媒体由 P0 真实 SRTP 夹具验证。
+
+P0 后端接口、所有权与取消语义按 15.2 冻结，允许进入 P1。P0 仍是每 component
+一个实验端点；P3 扩展数量时必须继续遵守同一 socket、标准检查和选中资源所有权。
+生产能力、广范围探索和默认启用尚未交付，P5 真实未知 NAT 的收益仍需后续对照。
+
+## 16. P1–P4 实现与 P5 实验入口（2026-09-14）
+
+本节更新当前状态；第 15 节“未开始 P1–P5”等文字是对应时间点的历史记录。
+在 P0 跨平台门槛通过后依次完成 P1/P2 基础、P3 多端点接入和 P4 生命周期/构建，
+没有在 P0 前放大探索范围。源码及实验工具由主仓库当前 gitlink 固定。完整证据见
+[P1–P4 验证记录](../deps/submodules/minirtc/tests/ice/lab/punch-runtime-validation-2026-09-14.md)，
+准确命令见 [v1 实验步骤](../deps/submodules/minirtc/tests/ice/lab/punch-v1-experiments.md)。
+
+| 阶段 | 当前交付及边界 |
+| --- | --- |
+| P0 | 已通过原门槛，保持单端点 ABI 1 与原始失败记录 |
+| P1 | 配置/能力、指纹验证后 exporter、认证协议与协商完成；默认关闭，新旧/未知能力纯逻辑及实际生成能力检查通过 |
+| P2 | 同源观测、角色、CSPRNG 采样、本地与进程预算完成；首次实现时 Mac/Windows/Linux 各 2,952 个单元断言通过，后续清理回归见验证记录 |
+| P3 | 独立 ABI 2、64/128 端点、同 socket 提升/标准检查/提名/媒体闭环实现；三个平台受控 runtime 各 12/12 |
+| P4 | owner context 清理、DRAINING、取消、重连身份和接口/base 检查实现；百次 source/agent 生命周期、Mac/Windows 完整应用、Linux ICE smoke、iOS 静态库已验证。物理网卡真实切换和最终应用互连仍待双端验证 |
+| P5 | 90 次交错清单与核验工具已准备；有 1 次增强成功双端日志但无该轮物理抓包。后续双端抓包取得 A/off 的 3 个完整窗口样本（均中继），B/wide-only 的 2 次已启动未命中和 1 次启动前跳过。跳过暴露的 READY 重查时序问题已修复，真实双端修复后复测及正式随机 A/B/C 仍待进行；保留先前 SDP 失败，不作收益或默认开启决定 |
+
+### 16.1 对实际源码的必要调整
+
+- 保留已验收的 `punch_pool_0.1.24.patch`，追加 `punch_v1_0.1.24.patch`。
+  `nice_agent_punch_get_v1_abi/open_v1` 与 P0 API 区分；v1 每池最多 128、进程 256，
+  提升最多 8。补丁 SHA 与包身份版本进入 MiniRTC 配方，不依赖本机缓存改动。
+- `PunchRuntime` 由 IceAgent 持有，在同一 GMainContext 使用真实句柄，直接收包
+  与 TURN 控制分流，认证命中后由 pool 提升。实际 selected pair 才报告结果，
+  各自的原始截止不会因 HELLO/重传/START 被延长。
+- SDP 指纹最小实验发现原解析吞并 fingerprint 之后所有行并截断 SDP，导致新增
+  候选/能力位于其后时 DTLS 校验失败。改为逐行解析、保留其余 SDP、拒绝冲突指纹，
+  并加入真实握手与位置测试；没有通过禁用指纹校验绕过失败。
+- 通用 DEBUG 日志在现有项目中编译关闭，因此添加独立、默认关闭的
+  `MINIRTC_UDP_PUNCH_TRACE=1`，只记录有界探测元数据。应用原有 SDP 日志包含 ICE
+  密码，原始实验文件必须保持私有；新代码不记录 exporter 或完整 tag。
+- 首次启用后的真实应用试跑发现 eligibility 日志读取未赋值的旧 ufrag 指针，
+  在接收 SDP 时崩溃；最小实验复现后，eligibility/skip 与 exporter 统一从当前
+  libnice stream 读取 generation 凭据。补充双角色真实 SDP 接收/重建及自动 skip
+  的 TURN/SRTP 回归，详情见验证记录。此修复不改变协议或绕过探测前置条件。
+- Mac off 试跑发现传输层复制指纹行后缺少 LF，追加原能力时产生 CR CR LF，
+  无 v1 能力的 SDP 被严格校验拒绝。完整 IceTransport 实验复现后在拼接处补齐
+  LF；三种运行模式各 36 个组合及错误指纹拒绝通过，证书校验和默认关闭不变。
+- B 组一次启动遇到 READY → CONNECTED → READY 的正常候选重查。后端截止时间
+  查询只在 READY 有效，旧入口把暂时返回 0 当作最终跳过。保存首次 READY 时
+  后端提供的真实截止时间；在该时间内等待 CONNECTED 恢复，随后重新让后端验证
+  是否可探测。不在 CONNECTED 开池，不从恢复时间重新计算窗口；新增真实 TURN
+  的 `auto-recheck` 夹具，覆盖两个角色、原截止不变和单次 DTLS/认证中继媒体。
+- 第 10 节 B 组原“固定角色”明确为**固定自动判定规则**，与第 4 节生产禁用强制
+  角色保持一致。受控夹具仍可固定角色；真实实验记录观测/角色变化及跳过，不把
+  它们隐藏为成功或擅自在生产中绕过适用条件。
+
+### 16.2 验收边界与下一步
+
+已验证 DRAINING 后真实 STUN 重传仍能提名并传输、认证 CANCEL 保留 relay、
+TURN 内层同形载荷不会产生直接命中，以及选中 socket 的实际存活和配额保持。
+Windows 64 端点百次压力测试在单一窗口到期后拒绝分配；工具通过多个新连接分批，
+最终两角色合计 20/20，各累计 100 次分配/停止/端口重绑定，没有扩大 ICE 窗口。
+分批首轮 15/20 暴露开池前基线只按发送次数判断的问题；改为原截止前等待双方
+各实际收到至少 10 个认证 SRTP 包后才开池。所有初次失败和修正理由保存在报告中，
+不追溯认定所有历史媒体缺包原因相同。
+
+用户已报告完成的普通画面/声音/控制/三次重连回归属于 P0 时点，不代表后续原型
+已通过真实应用切换验收。后续已有异网配对的双端成功日志，下一步补齐物理抓包，
+并在同步接收端修复后，用同一版本、同一信令
+与 STUN/TURN 配置，按文档交错执行 A/B/C；首先确认新鲜多 STUN 观测符合一侧稳定、
+另一侧目的相关。每个增强成功必须核验双端物理报文、标准提名、同一命中 socket、
+同一 DTLS/SRTP 会话以及实际画面/声音/控制。至少每组 30 次、保留全部失败/缺测。
+在这些工作完成前，原型仍默认关闭，不能声称已提高真实网络成功率。