# iroh 实验性连接

iroh 用加密直连（打不通时走中继）代替公网域名和隧道账号：手机先找到电脑的加密身份，再把流量送回本机网关。你不需要准备域名、端口映射或另一套 HTTPS 隧道。

> 插件 0.7.0 和 App 0.7.0 完整版整合电脑端通道、固定 TLS、配对界面和 Android 原生传输。功能默认关闭，仍标记为实验性；能否直连、是否经过中继及连接速度取决于两端网络，不保证在所有校园网、企业网或运营商环境下可用。
> 相关设计见独立仓的[集成接缝](https://github.com/saya-ch/dsh-mobile-iroh/blob/main/docs/INTEGRATION_SEAM.md)。

## 前提

- Windows x64 或 Linux x64（sidecar 只发布这两个目标）。
- Android 10+，安装含 iroh 的完整版 `-iroh.apk`，支持 arm64-v8a 和 x86_64。普通 `.apk` 是无原生库的兼容版，保留原有 HTTPS 连接并供旧版自动更新使用；不支持 iroh，也不支持手机浏览器直接接入。两个 APK 使用相同包名和正式签名，只需安装一个。
- 点 **安装官方组件** 一次下好 sidecar：插件从固定的 `dsh-mobile-iroh 0.1.0-alpha.1` 发行版按平台下载（Windows x64 约 15 MB，Linux x64 约 24 MB），校验 SHA-256 后放进插件私有目录；已装配套插件且副本校验通过时会直接复用，不再下载。Rust 源码随主仓在 `native/iroh-host`（公共 core 在 `native/iroh-core`）维护，CI 按平台构建校验。
- DSH Mobile 保持启用；iroh 默认关闭。局域网独立运行，远程通道为单选，切换到 iroh 会停止之前的远程通道。

## 使用

1. 在 **移动访问** 选择 `iroh（实验性）`。
2. 点 **安装官方组件**（带下载大小）：首次下载并校验 sidecar，通过才算就绪；再次点击会复用已校验的副本。哈希不对、平台不支持都会直接给出原因，不会启动半截通道。注意只是点开通道开关不会触发下载。
3. 打开远程开关：插件依次解析端点身份、签发端点专属网关证书（自有 CA，90 天叶子、30 天提前续）、起专用网关、拉起 sidecar 进程并等待 `ready`。`ready` 表示 sidecar 已连接且网关在回环监听。
4. 点 **生成 iroh 配对二维码**，用完整版 App 扫描。描述符绑定 sidecar 的 6 位码、网关的一次性 token 和固定 CA；再次生成会替换旧配对窗口，手机通过 iroh 上的普通 pair 接口核销网关 token。
5. 关闭或切换通道会停止自有进程与网关，不删除已保存的配对。独立实验 App 的包名不同，其 Keystore 凭据不会自动迁移到本 App。

未安装组件时不显示主操作按钮；安装后，开关、生成二维码和复制配对链接三个按钮保持同排。复制按钮在没有有效配对内容时置灰，生成后才可用，重复复制不会重新生成配对码。

需要回收组件占用空间时，先关闭 iroh 远程访问，再展开组件详情，选择 **移除已下载的 iroh 组件**。它只删除本插件下载的固定版本程序，不删除身份、配对或外部伴随包；再次使用时可重新安装或复用已校验的外部副本。运行中不允许清理，直接调用管理 API 也会被拒绝。

## 安全边界

- sidecar 只允许代理到 `127.0.0.1`/`::1` 的回环网关，TLS 仍端到端；命令与事件都是版本化、定长、未知字段直接拒绝。
- 换指纹/换二进制/挪文件都会让校验失败并停在 `unavailable`，不会静默跑旧通道。
- 传输层撤销与设备 Token 撤销是两套授权，统一管理界面是 Phase 2 内容；电脑端撤销仍按现有设备管理生效。

## 排障

iroh 身份和证书必须存放在仅当前用户或受信系统账户可写的目录树。Windows 默认的用户 profile 下 DSH 状态目录符合此用途；自定义状态位置时也要检查父目录权限。某些 AppData 或共享目录允许其他账户写入，会被拒绝；不要通过放宽 ACL、删除真实身份或移入不可信目录来绕过检查。已有身份应先备份并保留。

组件发布前必须使用目录中固定的二进制验证首次启用，不能只测本地编译的 host 或手工初始化过的目录。控制器调用 `tls-prepare`，因为 `id` 只读取既有身份。Windows 可设置 `DSH_IROH_PINNED_FIRST_USE=<已校验的程序>` 后运行 `npx vitest run tests/iroh-pinned-first-use.test.ts`，检查私有测试目录中的初始化、复用与损坏拒绝。失败应阻止组件验收，不得通过放松目录 ACL 检查或替换真实身份来让测试通过。

| 现象 | 含义 |
| --- | --- |
| `iroh_companion_missing` | 还没点安装（或配套不在常规布局旁）；先点安装官方组件，或用 `DSH_MOBILE_IROH_COMPANION` 指向配套绝对路径复用 |
| `iroh_sidecar_invalid` | 已装文件被改动过；重新点安装即可覆盖修复，配套副本损坏则重装配套 |
| `iroh_platform_unsupported` | 当前系统/架构没有 sidecar 发布 |
| `iroh_identity_invalid` / `iroh_identity_failed` | 先检查状态目录及父目录是否私有、已有身份是否损坏，保留原文件再排查；`id` 仅检查已有身份，首次创建使用 `tls-prepare`，不是靠复制或删除身份修复 |
| `iroh_start_timeout` | 查看 DSH 日志中的 iroh 错误及网络连接，确认固定组件可运行；不要反复重新配对来替代进程排查 |
| 通道 `ready` 但手机连不上 | 检查 App 是否为完整版、设备是否支持打包的 ABI，以及描述符是否有效；电脑就绪不等于手机已连通，连接中继服务也不等于数据一定经过中继 |

## VPN/代理与网络环境

iroh 直连优先、中继兜底。直连使用 QUIC/UDP，发现和中继还要求相应网络服务可达。以下环境因素**可能**干扰连接，属于排查方向，并非每一种 VPN 或网络都已确认存在的故障机制：

- **全局 VPN/TUN**（系统级虚拟网卡）可能接管 UDP 与 DNS，使直连和中继握手都无法完成。有用户在 Win11 + WSL2 镜像网络、手机移动数据下反馈：关闭全局 VPN 后约 6 秒可用，把 DSH Mobile 加入 VPN 分应用排除后同样恢复。这是社区实测，不代表所有 VPN/网络组合或两种 ABI。
- **DNS 策略**（fake-IP、过滤规则）：域名发现依赖 DNS 解析，fake-IP 模式可能把发现域名解析到代理虚拟 IP。
- **回环入口**：App 通过 `*.iroh.localhost` 访问本机网关，本机回环地址不应交给远程代理/DNS 处理。

可尝试的排查（自愿进行，以本机安全策略为准）：

1. 在 VPN/代理客户端把 DSH Mobile（包名 `io.github.sayach.dshmobile`）加入分应用绕过/排除列表；调试包与独立实验 App 的包名不同。这指社区 Android App，不是官方 DSH Desktop，请按实际安装的包配置。
2. 若客户端支持按域名规则，可将发现/中继相关域名设为直连。以 Clash Meta 为例（仅示意，语法以你的客户端为准）：`DOMAIN-SUFFIX,iroh.link,DIRECT`；使用 fake-ip 时可在 `fake-ip-filter` 中加入 `+.iroh.link`。域名规则只能覆盖客户端解析相关的部分，**不能**保证覆盖全部直连 peer IP、中继服务与回环路径，也不能概括为“必须有 UDP 否则一定不可用”。
3. `*.iroh.localhost` 是 App 的本机入口，不应送往远程代理/DNS。
4. Always-on/锁定类 VPN 策略可能不允许分应用绕过；本插件不会绕过系统安全策略、关闭证书校验或强制切换网络。

原生“检测 VPN 并提示”只是可选后续，当前版本不含该功能；是否开关 VPN 由用户自行决定。

英文版见 [IROH.en.md](IROH.en.md)。