本页汇总 pair-demo 命令行参数与退出码、iroh-pairing / connector-core 公开 API 概览、仓库内协议与技术文档永久链接，以及项目的开源许可证与归属说明。
pair-demo invite [OPTIONS]
pair-demo peers list --state-dir <DIR>
pair-demo peers revoke <ENDPOINT-ID> --state-dir <DIR>
pair-demo serve --state-dir <DIR> [--lan-only | --relay <URL>]
pair-demo ping <ENDPOINT-ID> --state-dir <DIR> [--direct <ADDR>]...
stdout：仅输出单行结构化 JSON 结果（不含邀请 token、密钥或聊天正文）。stderr：输出终端二维码、备用邀请行（Invitation (paste/scan): <value>）、7 项 SAS 提示、本地交互提示及白名单 tracing 诊断。- 无自动确认开关：生产 CLI 不提供
--auto-confirm 或任何环境变量自动确认开关，SAS 比较结果必须由本地终端 stdin 输入。
| 参数 |
默认值 |
说明 |
--profile <ID> |
generic.pair |
业务 profile 标识；两端必须完全一致，未知自定义 ID 同样支持由通用扫码器介绍 |
--namespace <TEXT> |
iroh.pairing.demo |
应用命名空间；两端必须完全一致 |
--role <ROLE> |
peer |
本端声明的角色（不按扫码先后分配） |
--accept-role <ROLE> |
等于 --role |
可重复指定；对端声明的 --role 必须包含在此集合内 |
--purpose <TEXT> |
内置演示说明 |
人类可读用途说明；两端可不同，但会被 SAS 上下文完整绑定 |
--scope <ITEM> |
demo.echo |
可重复指定；显式传入时覆盖默认 demo.echo（若不含 demo.echo，验证后将跳过回显业务动作） |
--name <TEXT> |
pair-demo-device |
自报设备名称 |
--payload-file <PATH> |
无 |
验证完成后交换的本地文件（上限 65536 字节 / 64 KiB） |
--content-type <TEXT> |
application/octet-stream |
验证后 payload 的 MIME / 内容类型 |
--schema-version <U32> |
1 |
验证后 payload 的应用 schema 版本号 |
--lan-only |
关闭 |
禁用 relay 与地址发现，仅使用直连 UDP 地址（与 --relay 互斥） |
--relay <URL> |
无 |
仅使用指定的自定义 relay，不启用额外发现（与 --lan-only 互斥） |
--connector-url <URL> |
无 |
将邀请编码为 <URL>#<envelope>（wire 契约固定要求路径恰好为无尾斜杠的 /pair，如 https://iroh-pairing.gjz010.page/pair；HTTPS 或 loopback HTTP，总长 ≤ 2048 字节） |
--qr-svg <PATH> |
无 |
将二维码额外导出为独立 SVG 文件 |
--state-dir <DIR> |
无 |
在 <DIR>/state.json 持久化本机长期身份与 Persistent 授权记录 |
| 参数 |
默认值 |
说明 |
--name <TEXT> |
pair-demo-chat |
自报设备名称 |
--lan-only |
关闭 |
禁用 relay 与地址发现，仅使用直连 UDP 地址（与 --relay 互斥） |
--relay <URL> |
无 |
仅使用指定的自定义 relay（与 --lan-only 互斥） |
--ttl <SECS> |
300 |
未使用邀请的有效期（秒，1..=3600） |
pair-demo peers list --state-dir <DIR>：列出 <DIR>/state.json 中已保存的持久授权记录。pair-demo peers revoke <ENDPOINT-ID> --state-dir <DIR>：按 64 位小写十六进制 EndpointId 幂等删除持久授权记录（重启 serve 后对新连接生效）。pair-demo serve --state-dir <DIR> [--lan-only | --relay <URL>]：使用已保存的长期身份启动受保护的 /iroh-pairing/demo-echo/1 服务，等待 Ctrl-C。pair-demo ping <ENDPOINT-ID> --state-dir <DIR> [--direct <ADDR>]...：使用已保存的长期身份与持久授权向目标对端发起一次受保护回显请求（可重复传入 --direct <IP:PORT> 覆盖重启后变化的直连端口）。
| 退出码 |
常量 |
含义 |
0 |
EXIT_OK |
成功完成（身份验证、载荷交换及所需的业务回显或聊天会话均完成） |
1 |
EXIT_LOCAL |
本地配置、payload 文件读取、状态文件校验或二维码导出错误 |
2 |
EXIT_CANCELLED |
本地取消（输入 no、stdin EOF、本地 cancel 或 Ctrl-C） |
3 |
EXIT_EXPIRED |
邀请已过期 |
4 |
EXIT_NETWORK |
网络、relay、可达性或传输层失败 |
5 |
EXIT_VERIFICATION |
SAS 验证失败，或业务授权缺失/被对端 Gate 以 403 拒绝 |
6 |
EXIT_EXCHANGE |
身份已验证，但载荷交换失败、结果不确定（Indeterminate），或业务回显校验失败 |
64 |
EXIT_USAGE |
命令行参数语法或互斥选项错误 |
源码位于 crates/iroh-pairing/src/lib.rs：
| 类型 / 常量 |
核心方法 / 说明 |
PAIRING_ALPN |
b"/iroh-pairing/1" 专用配对协议 ALPN 常量 |
Pairing |
Pairing::attach(endpoint, config)、pairing.handler()（用于 Router::accept）、pairing.accept(connection)（用于手写 accept loop）、pairing.create_invite(request) |
PairingConfig |
配置活跃会话上限（默认 4）、未使用邀请 TTL（默认 5 min）、介绍后活跃期限（默认 10 min）、RPC/连接超时及可选 HostValidator |
InviteRequest |
InviteRequest::new(app_name, device_name, application, network)、.with_payload(payload)；network 取 NetworkMode::Internet 或 NetworkMode::Lan |
Session |
invite()、invite_url(connector_url)、snapshot()、subscribe()、confirm(matches)、accept_payload()、accept_payload_with_digest(expected)、cancel()、revoke_invite()、verified()、result().await |
SessionEvent |
PhaseChanged、SasReady { display }、Verified { peer }、PayloadReceived { payload, content_digest }、PayloadAccepted、ExchangeFinished { outcome }、Failed、Indeterminate |
VerifiedPeer |
经完整 SAS 与双向 MAC 验证的对端身份：remote_id()、local_id()、transaction_id()、context()、application()、scope()、addresses()、role() |
AuthorizationState |
AuthorizationState::new(protected_alpns)、state.gate()（安装至 EndpointBuilder::hooks）、state.grant(&peer, alpn, lifetime)、state.authorization(remote_id, alpn)、state.records()、state.restore(record)、state.revoke(remote_id) |
源码位于 crates/connector-core/ 与 crates/connector-android-bindings/：
- Rust
Connector：Connector::new(config).await、set_slot(slot, input)、clear_slot(slot)、check_compatibility()、start_introduction().await、snapshot()、watch_progress()、detach().await、cancel_before_handoff().await、reset().await、close().await。
- Web WASM 绑定（
WasmConnector）：导出与上述方法对应的 JSON 字符串接口及 parse_invite_json / parse_invite_json_at。
- Android UniFFI Kotlin 绑定（
com.gjz010.irohpairing.core）：导出 NativeBootstrap.install(applicationContext)（进程级 JNI/DNS 初始化）与 NativeConnector（注意关闭顺序：先异步调用 closeEndpoint() 关闭手机 Endpoint，再调用 AutoCloseable.close() 释放 UniFFI handle）。
- 冻结协议规范与测试向量：
- 仓库根部实现与验证文档：
- 维护者与独立性声明：
iroh-pairing 由 gjz010 独立开发与维护。iroh-pairing 是独立社区项目，与 iroh 项目及其官方团队、n0 computer 不存在隶属或其他官方关联，也未获其赞助、认可或背书。相关名称与商标归各自权利人所有。
- 官方链接：
- 项目许可证：本仓库源码采用 Apache License 2.0 许可发布。项目品牌 Logo（
assets/icon.svg 及其派生品牌图标）由 gjz010 创作，采用 CC BY 4.0 许可发布（详见 assets/LICENSE.md 与 NOTICE）。connector-web 与 connector-android 的“设置 → 关于”面板同样内置展示上述仓库地址、文档主页与 Apache-2.0 许可信息。
- 包名与上游第三方归属：
