主机配对 KonnectSuite/dsh-host-pairing

description: "Host 配对入口：用短时一次性配对码换取浏览器会话 cookie，并报告手机可达的地址；面向远程访问的使用者与维护者。"
kind: "package-reference"

@deepseek-ai/dsh-host-pairing

概述

Host 构建聚合引用本包的 TypeScript 项目；路由测试传入已解析的配置，并明确指定配对码有效期。

dsh web 通过在启动时打印的 URL 中放入一次性进程令牌来认证浏览器。这只能在运行服务器的机器上生效：操作者必须手动把一个长期有效的密钥搬到第二台设备上。本包挂载 GET /pair?code=…，用短时一次性配对码换取同一个按 authority 绑定的会话 cookie，并挂载 GET /pair/offer，生成配对码并报告同一私有网络内设备可达的每个地址。

目录

- 使用本包
- 理解实现
- 进一步探索
- 模型体验
- 已知限制与后续工作
- 开发备注

使用本包

把本行挂在 connection 与 webserver 旁边即可，无需其他配置。随发行版 Web bundle 已含该行。

要让手机连上，还需要一个手机能访问的绑定。dsh web --host 0.0.0.0 仍被拒绝，因为它会不加说明地暴露服务器；dsh web --remote 以明确选择的方式选定同一绑定。此后 offer 会先报告 tailnet 地址，再列出局域网地址。

交换

设备打开配对 URL，即 http://<authority>/pair?code=。有效配对码会铸造与 GET /?token=… 相同的 cookie——绑定到请求到达时使用的 authority——并重定向到 ./。无论结果如何，该请求都会消耗配对码，因此重放或猜测的配对码无法对仍然有效的条目重试。

Offer

GET /pair/offer 需要完整的浏览器会话，因为它的响应会交出一份凭据；已经有会话的设备不需要配对。当服务器只绑定 loopback 时，offer 报告 exposed: false 并返回空地址列表，而不是给出无法访问的 URL，客户端因此可以说明该改什么，而不是在扫码时失败。

配置

codeTtlSeconds 限定配对码的绝对生存期，默认 300 秒。两侧都会校验：活得比走到手机还久的配对码等于常驻凭据，而在扫码中途过期的配对码则无法使用。

理解实现

实现内部细节——点击展开

配对码只存在于内存中，因此重启会让所有尚未使用的 offer 失效，而不是在磁盘上留下凭据；兑换是同步的"比较并删除"，因此两个请求争抢同一个配对码时不会都观测到它仍然有效。配对码是来自去除了易混字符的字母表的八个字符，用 randomBytes 加拒绝采样抽取，使每个符号等概率。

一个地址被广播，要么因为它落在 Tailscale 分配的范围内（RFC 6598 运营商级 NAT 段），要么因为它是本机持有的另一个非内部 IPv4 地址。该范围在各平台上都能识别 tailnet 地址；改为匹配接口名会漏掉 macOS 的 utun* 与 Linux 的 tailscale0。

交换是唯一必须接纳未认证请求的路由，因此它只应用 Connection 的 Host/Origin 围栏，并把配对码当作凭据；围栏仍会在读取配对码之前拒绝不受信任的 authority，且被拒绝的尝试不会消耗配对码。cookie 的受众是请求自身的 Host，因此通过其他方式接纳请求的路由无法被诱导为它并不服务的 authority 签发凭据。

进一步探索

- client-connection —— 拥有浏览器会话 cookie、信任围栏，以及本交换所调用的铸造方法。
- host-webserver —— 两个端点注册所在的路径载体。
- ui-mobile —— 请求 offer 并将其渲染为二维码的客户端。

模型体验

None, as pairing admits a browser session; nothing here reaches a model request.

KV Cache effect

None; this package neither assembles nor sends a provider request.

已知限制与后续工作

这些限制界定了当前配对入口。它们是当前包约束，不是任务积压。

- 绑定全部接口而非某一个 —— webserver 只接受 loopback 或全部接口两种绑定，因此 --remote 会暴露本机持有的每个接口，包括公网接口。配对码是这份暴露与 API 之间唯一的屏障。
- 使用 tailnet 地址而非其名称 —— 地址来自接口表，因此 offer 携带的是 tailnet 的 IPv4 字面量。MagicDNS 名称能在地址变化后继续有效，但需要 tailscale CLI，本包不运行它。

开发备注

维护者的工作上下文——点击展开

路由规格通过 Loader 启动真实 webserver 并经由 HTTP 驱动它；暴露状态的 offer 分支单独覆盖，因为 loopback 测试服务器无法在不把端口发布到所有接口的前提下报告 exposed: true。