@dshn/agent 0.2.0 → 0.3.0

package/README.md

@@ -1,7 +1,10 @@
 # dshn — DeepSeek Harness Network
 
+**English** · [中文](./README.zh.md)
+
+[![awesome · DSH plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com/)
+[![npm](https://img.shields.io/npm/v/@dshn/agent?label=%40dshn%2Fagent&color=cb3837)](https://www.npmjs.com/package/@dshn/agent)
 [![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
-[![dsh-plugin](https://img.shields.io/badge/dsh-plugin-6aa84f.svg)](https://awesome-dsh-plugin.com/)
 
 Expose a locally-running **DeepSeek Harness** (`dsh`) web UI to the public
 internet under a `*.ds.hn` subdomain, gated by a login. Install the plugin, open
@@ -70,7 +73,7 @@ dsh  (local web server)                                fence sees a loopback req
 | package | what it is | runs where |
 |---|---|---|
 | `@dshn/protocol` | the WSS frame contract both ends compile against | shared |
-| `dshn` | the dsh plugin: setup form + outbound tunnel + status widget + e2e | user's machine, inside dsh |
+| `@dshn/agent` | the dsh plugin: setup form + outbound tunnel + status widget + e2e | user's machine, inside dsh |
 | `@dshn/relay` | login gate + claim store + subdomain router + HTTP/WS bridge | your server, behind Cloudflare |
 
 The claim store (`packages/relay/src/claims.ts`) is trust-on-first-use for now;
@@ -119,13 +122,15 @@ Agent environment (all optional; sensible defaults):
 ## Self-host your own network
 
 You don't have to use `ds.hn` — run the whole thing on your own domain. The relay
-ships as **`@dshn/relay`** (npm) and a Docker image; your agents point at it with
+ships as **`@dshn/relay`** (npm) and a Docker image; point your agents at it in
+the setup form (pick **自托管 / Self-hosted** and paste the relay URL) or with
 `DSHN_RELAY_HOST`. Full guide, including DNS + TLS options: **[SELF-HOSTING.md](./SELF-HOSTING.md)**.
 
 ```sh
-# your server
-DSHN_APEX=tunnel.example.com DSHN_COOKIE_SECRET=$(openssl rand -hex 32) npx @dshn/relay
-# your dsh
+# your server — the only thing you set is your apex; the cookie secret is
+# auto-generated and persisted, claims + secret live in --data-dir
+npx @dshn/relay --apex tunnel.example.com --data-dir /var/lib/dshn
+# your dsh — or just set it in Settings → 公网转发 → 自托管
 DSHN_RELAY_HOST=wss://tunnel.example.com dsh --profile web
 ```
 
@@ -133,22 +138,21 @@ Or from source:
 
 ```sh
 pnpm install && pnpm build
-DSHN_COOKIE_SECRET=$(openssl rand -hex 32) \
-DSHN_APEX=ds.hn \
-DSHN_RELAY_PORT=8787 \
-DSHN_CLAIMS=./claims.json \
-DSHN_TLS_CERT=./cert.pem DSHN_TLS_KEY=./key.pem \
-  node packages/relay/lib/index.js
+node packages/relay/lib/index.js --apex ds.hn --data-dir ./dshn-data
 ```
 
-| var | required | purpose |
-|---|---|---|
-| `DSHN_COOKIE_SECRET` | ✅ | HMAC secret for session cookies (rotating it logs everyone out) |
-| `DSHN_APEX` | — (`ds.hn`) | apex domain the wildcard hangs off |
-| `DSHN_RELAY_PORT` | — (`8787`) | listen port |
-| `DSHN_CLAIMS` | — | JSON file the relay creates/maintains (subdomain → scrypt hash) |
-| `DSHN_TLS_CERT` / `DSHN_TLS_KEY` | — | PEM paths to serve HTTPS directly (else plain HTTP behind CF) |
-| `DSHN_SITE` | — | apex landing-page HTML |
+The only setting you need is `--apex`. The cookie secret is auto-generated and
+persisted under `--data-dir` (no `openssl rand`), reused across restarts; every
+flag also has an env var (`DSHN_APEX`, …). `--help` lists them all:
+
+| flag | env | default | purpose |
+|---|---|---|---|
+| `--apex` | `DSHN_APEX` | `ds.hn` | apex the wildcard hangs off |
+| `--data-dir` | `DSHN_DATA_DIR` | `./dshn-data` | holds `claims.json` + the auto-generated `cookie-secret` |
+| `--port` | `DSHN_RELAY_PORT` | `8787` | listen port |
+| `--secret` | `DSHN_COOKIE_SECRET` | *(auto)* | cookie HMAC secret; set only to pin it |
+| `--tls-cert` / `--tls-key` | `DSHN_TLS_CERT` / `DSHN_TLS_KEY` | — | PEM paths to serve HTTPS directly (else plain HTTP behind CF) |
+| `--site` | `DSHN_SITE` | — | apex landing-page HTML |
 
 Cloudflare: proxy `*.ds.hn` (orange cloud) to the relay's origin. Harden the
 origin to accept only Cloudflare — firewall to the

package/README.zh.md

@@ -0,0 +1,110 @@
+# dshn — DeepSeek Harness Network
+
+[English](./README.md) · **中文**
+
+[![awesome · DSH plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com/)
+[![npm](https://img.shields.io/npm/v/@dshn/agent?label=%40dshn%2Fagent&color=cb3837)](https://www.npmjs.com/package/@dshn/agent)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+把本机运行的 **DeepSeek Harness**（`dsh`）网页界面,通过 `*.ds.hn` 子域名安全地开放到公网,并由登录门禁把守。安装插件、在本地打开 dsh,设置里的表单会让你填一个**子域前缀**和一个**密码**——这两项就是凭据。无需 token、无需环境变量、无需任何预置。还可选设置一个**端到端密码**加密流量,连中继运营者也只能看到密文。
+
+> ⚠️ **dsh 内置 bash 与文件系统工具,公网可达的 dsh 界面就是一个远程 Shell。** 中继的登录门禁不是可选项,不要关掉它。请使用高强度密码,敏感场景优先启用端到端加密。
+
+## 特性
+
+- **零配置凭据。** 在 dsh 设置里填一次 `(子域, 密码)` → 插件即认领子域并连接。凭据持久化到 dsh 自己的 `~/.dsh/settings.yaml`,重启自动重连。
+- **信任首次使用(TOFU)。** 首个认领空闲子域的 agent 设定其密码(在中继上以 scrypt 哈希存储);此后的连接与每一次浏览器登录都必须匹配它——防抢占。
+- **多设备。** 多台机器可用同一凭据绑定**同一个**子域,各自显示为一台具名设备。有 ≥2 台在线时,打开链接会出现设备选择页,页面侧栏底部也有切换器;选择按浏览器记住(路由 cookie),切换即对另一台机器做一次干净的重载。仅一台在线时行为与从前完全一致。
+- **可选端到端加密**(默认关闭)。一个**独立**的 e2e 密码(绝不发往中继)加密 `/api` 请求体与事件流:PBKDF2-SHA256(21 万次)→ AES-256-GCM。访客在浏览器里输入一次即可,可按设备记在 `localStorage`(永不传输)。
+- **原生 UI。** 配置就在 dsh 自己的设置里(「公网转发」),页脚一行实时显示延迟并可点入。
+- **自持数据面。** 流量经 Cloudflare 边缘回到**你自己的**服务器——无需每用户的 Cloudflare 账号,无需 NS 委派。
+
+## 架构
+
+```
+浏览器  alice.ds.hn
+  │  HTTPS
+  ▼
+Cloudflare 边缘  (*.ds.hn 代理 / 橙色云)              免费 DDoS、WAF、TLS、
+  │  回源                                              Anycast、隐藏源站
+  ▼
+中继 relay  (你的服务器, @dshn/relay)                 登录门禁 + 子域认领表;
+  │  每设备一条多路复用 WSS                            只搬运字节
+  ▼
+dshn  (dsh 插件, 在用户机器上)                        把 HTTP + WS 重放给 dsh,
+  │  http://127.0.0.1:<dsh 端口>                       Host/Origin 改写为环回
+  ▼
+dsh  (本地网页服务)                                   信任门禁看到的是一个环回请求
+```
+
+- **不改 trustedHosts。** agent 把每个转发请求的 Host/Origin 改写为环回,于是 dsh 的 `/api` 浏览器信任门禁把它当作**任意**运行时选定子域的本地同源请求接受——这正是「子域来自表单而非组合」得以成立的原因。访问由中继登录把守,而非该门禁。
+- **端到端模式** 在 agent 处密封请求/响应体、在浏览器里解开;中继始终是一个盲搬运者。应用外壳与插件包保持明文,以便浏览器自举并弹出解锁弹窗。它能防住被动/好奇的中继与静态数据泄露,但防不住一个主动作恶、篡改所投送 JS 的中继。
+
+## 包结构
+
+| 包 | 是什么 | 运行在哪 |
+|---|---|---|
+| `@dshn/protocol` | 两端共同编译的 WSS 帧协议 | 共享 |
+| `@dshn/agent` | dsh 插件:设置表单 + 出站隧道 + 状态挂件 + e2e | 用户机器,dsh 之内 |
+| `@dshn/relay` | 登录门禁 + 认领表 + 子域路由 + HTTP/WS 桥接 | 你的服务器,Cloudflare 之后 |
+
+认领表（`packages/relay/src/claims.ts`）目前是信任首次使用;账号化的控制面日后替换它。
+
+## 安装 agent(用户机器)
+
+从 npm 安装(推荐——一条命令,完全自包含):
+
+```sh
+dsh plugin --profile web add @dshn/agent
+dsh --profile web
+```
+
+或从最新 GitHub Release 下载预构建 tarball:
+
+```sh
+curl -L -o dshn.tgz \
+  https://github.com/jsdvjx/dshn/releases/latest/download/dshn.tgz
+dsh plugin --profile web add ./dshn.tgz
+```
+
+或从源码构建:
+
+```sh
+pnpm install && node scripts/build-dist.mjs
+dsh plugin --profile web add ./dist/dshn
+dsh --profile web
+```
+
+随后在本地打开 dsh,进入 **设置 → 公网转发**,填写子域前缀与密码(可选端到端密码),点**连接**。用同一个访问密码即可从手机登录。每个子域最多跑**一个** agent——相同凭据的两个 agent 会互相争抢。
+
+agent 环境变量(全部可选,均有合理默认值):
+
+| 变量 | 默认值 | 用途 |
+|---|---|---|
+| `DSHN_ENABLED` | `1` | 设为 `0` 则加载插件但不启用 |
+| `DSHN_RELAY_HOST` | `relay.ds.hn` | 中继地址;直连(绕开 Cloudflare)用 `wss://origin.ds.hn:8787` |
+| `DSHN_ORIGIN_CA` | — | 钉扎自签名直连源站证书的 PEM |
+| `DSHN_STATE` | `~/.dsh/dshn-agent.json` | 旧版状态文件(凭据现在存于 `settings.yaml`) |
+| `DSH_HOME` | `~/.dsh` | dsh 主目录 |
+
+## 自托管你自己的网络
+
+你不必用 `ds.hn`——整套都能跑在你自己的域名上。中继以 **`@dshn/relay`**(npm)及 Docker 镜像发布;在设置表单里选 **自托管**、填入中继地址即可指过去(也可用 `DSHN_RELAY_HOST`)。完整指南(含 DNS 与 TLS 各选项):**[SELF-HOSTING.md](./SELF-HOSTING.md)**。
+
+```sh
+# 你的服务器 —— 唯一必填的只有 apex;登录密钥自动生成并持久化,
+# claims 与密钥都放在 --data-dir 里
+npx @dshn/relay --apex tunnel.example.com --data-dir /var/lib/dshn
+# 你的 dsh —— 或直接在 设置 → 公网转发 → 自托管 里填
+DSHN_RELAY_HOST=wss://tunnel.example.com dsh --profile web
+```
+
+Cloudflare:把 `*.ds.hn`(橙色云代理)指向中继源站。请把源站加固为仅接受 Cloudflare——按 [Cloudflare IP 段](https://www.cloudflare.com/ips/)做防火墙,并启用 Authenticated Origin Pulls(mTLS)。因为 Cloudflare 约 100 秒关闭空闲 WebSocket,两端每 25 秒心跳——已内置。若要承载持续大流量的直连隧道,加一条灰云(仅 DNS)`origin.ds.hn` A 记录,并让 agent 用 `DSHN_RELAY_HOST` + `DSHN_ORIGIN_CA` 指过去。
+
+## 现状
+
+端到端可用。已知不足:偶发的隧道套接字断开会让该连接上的在途请求失败(尚无请求重放);持续大流量下 Cloudflare 可能重置隧道(改用直连源站方案);CF 免费版 100 MB 请求上限会截断较大的 dsh 图片上传;认领表仍是信任首次使用、无账号层;生产环境应把中继源站锁定到 Cloudflare IP 段并启用 Authenticated Origin Pulls。
+
+## 许可
+
+[MIT](./LICENSE)

package/client.js

@@ -417,6 +417,7 @@ window.__ModuleLoader__.load({
           savedHint: '手机访问用这个密码登录。忘记时点“复制/显示”取回。',
           weak: '弱', fair: '一般', good: '较强', strong: '强',
           infoRelay: '线路', infoMode: { direct: '直连源站', cloudflare: '经 Cloudflare' },
+          routePremium: '高级线路（加速）', routeStandard: '标准线路',
           infoUptime: '在线时长', infoServed: '已转发请求', infoPort: '本地端口', infoLatency: '延迟', infoDevice: '设备名',
           e2eLabel: '端到端密码（可选）', e2eHint: '设置后，会话内容用它加密，云端也看不到；密码不出本机。访问时需在网页再输一次。',
           e2eApply: '设置端到端密码', e2eUpdate: '更新端到端密码', e2eDisable: '关闭加密', e2eApplied: '✓ 端到端加密已开启', e2eOff2: '✓ 端到端加密已关闭', e2eIndep: '独立设置，不影响上面的连接。',
@@ -442,6 +443,7 @@ window.__ModuleLoader__.load({
           savedHint: 'Log in from a phone with this password. Copy/show it here if you forget.',
           weak: 'weak', fair: 'fair', good: 'good', strong: 'strong',
           infoRelay: 'Link', infoMode: { direct: 'direct to origin', cloudflare: 'via Cloudflare' },
+          routePremium: 'premium route (accelerated)', routeStandard: 'standard route',
           infoUptime: 'Uptime', infoServed: 'Requests served', infoPort: 'Local port', infoLatency: 'Latency', infoDevice: 'Device name',
           e2eLabel: 'End-to-end password (optional)', e2eHint: 'If set, session content is encrypted with it — even the cloud cannot read it, and it never leaves this machine. Visitors enter it again in the browser.',
           e2eApply: 'Set e2e password', e2eUpdate: 'Update e2e password', e2eDisable: 'Turn off', e2eApplied: '✓ End-to-end encryption on', e2eOff2: '✓ End-to-end encryption off', e2eIndep: 'Applied on its own — does not affect the connection above.',
@@ -478,6 +480,7 @@ window.__ModuleLoader__.load({
         P('M7 1.7c2.3 2.3 2.3 8.3 0 10.6'), P('M7 1.7c-2.3 2.3-2.3 8.3 0 10.6')],
       cloud: () => [P('M4.4 10.6a2.6 2.6 0 01.2-5.2 3.4 3.4 0 016.5.9 2.2 2.2 0 01-.4 4.3z')],
       plug: () => [P('M5 2.3v2.2M9 2.3v2.2'), P('M4 4.6h6v1.9a3 3 0 01-6 0z'), P('M7 9.4v2.3')],
+      bolt: () => [P('M7.6 1.8L3.3 7.8h3.1l-.8 4.4 4.3-6h-3.1z')],
       gauge: () => [P('M2.2 10.4a5 5 0 019.6 0'), P('M7 10.4l2.4-2.7'), h('circle', { key: 'd', cx: 7, cy: 10.4, r: .5, fill: 'currentColor' })],
       clock: () => [h('circle', { key: 'c', cx: 7, cy: 7, r: 5.3 }), P('M7 4.1v3.1l2 1.2')],
       swap: () => [P('M3.4 5h7.2l-2-2'), P('M10.6 9H3.4l2 2')],
@@ -641,9 +644,13 @@ window.__ModuleLoader__.load({
         })() : null,
 
         configured && s.connected ? h('div', { className: 'dshn-info' },
+          // The route is the operator's assignment (premium = accelerated path via
+          // the tunnel's own hostname); the mode is how the default relay is reached.
           h('div', { className: 'dshn-info-row' },
-            h('span', { className: 'dshn-info-k' }, Icon(s.mode === 'direct' ? 'plug' : 'cloud'), T.infoRelay),
-            h('span', { className: 'dshn-info-v' }, (T.infoMode[s.mode] || s.mode || '') + (s.relayHost ? ' · ' + s.relayHost : ''))),
+            h('span', { className: 'dshn-info-k' }, Icon(s.route === 'premium' ? 'bolt' : s.mode === 'direct' ? 'plug' : 'cloud'), T.infoRelay),
+            h('span', { className: 'dshn-info-v', style: s.route === 'premium' ? { color: '#c9930f' } : undefined },
+              (s.route === 'premium' ? T.routePremium : s.route === 'standard' ? T.routeStandard + ' · ' + (T.infoMode[s.mode] || s.mode || '') : (T.infoMode[s.mode] || s.mode || ''))
+              + (s.relayHost ? ' · ' + s.relayHost : ''))),
           h('div', { className: 'dshn-info-row' },
             h('span', { className: 'dshn-info-k' }, Icon('gauge'), T.infoLatency),
             h('span', { className: 'dshn-info-v', style: { color: latColor(s.latencyMs) } }, s.latencyMs == null ? '—' : s.latencyMs + ' ms')),

package/lib/index.js

@@ -4628,7 +4628,8 @@ var CREDS_SCHEMA = Schema.object({
   e2ePassword: Schema.string().role("secret").default(""),
   e2eSalt: Schema.string().default(""),
   relayHost: Schema.string().default(""),
-  originCa: Schema.string().default("")
+  originCa: Schema.string().default(""),
+  routeHost: Schema.string().default("")
 });
 function readCredsFile(path) {
   try {
@@ -4640,7 +4641,8 @@ function readCredsFile(path) {
         e2ePassword: typeof raw.e2ePassword === "string" && raw.e2ePassword !== "" ? raw.e2ePassword : void 0,
         e2eSalt: typeof raw.e2eSalt === "string" ? raw.e2eSalt : void 0,
         relayHost: typeof raw.relayHost === "string" && raw.relayHost !== "" ? raw.relayHost : void 0,
-        originCa: typeof raw.originCa === "string" && raw.originCa !== "" ? raw.originCa : void 0
+        originCa: typeof raw.originCa === "string" && raw.originCa !== "" ? raw.originCa : void 0,
+        routeHost: typeof raw.routeHost === "string" && raw.routeHost !== "" ? raw.routeHost : void 0
       };
     }
   } catch {
@@ -4660,7 +4662,7 @@ function settingsStore(scope, migrateFrom) {
   const store = {
     load: () => {
       const v = scope.get() ?? {};
-      return typeof v.subdomain === "string" && v.subdomain !== "" ? { subdomain: v.subdomain, password: v.password ?? "", e2ePassword: v.e2ePassword || void 0, e2eSalt: v.e2eSalt || void 0, relayHost: v.relayHost || void 0, originCa: v.originCa || void 0 } : null;
+      return typeof v.subdomain === "string" && v.subdomain !== "" ? { subdomain: v.subdomain, password: v.password ?? "", e2ePassword: v.e2ePassword || void 0, e2eSalt: v.e2eSalt || void 0, relayHost: v.relayHost || void 0, originCa: v.originCa || void 0, routeHost: v.routeHost || void 0 } : null;
     },
     save: (creds) => {
       Promise.resolve(scope.update({
@@ -4669,7 +4671,8 @@ function settingsStore(scope, migrateFrom) {
         e2ePassword: creds?.e2ePassword ?? "",
         e2eSalt: creds?.e2eSalt ?? "",
         relayHost: creds?.relayHost ?? "",
-        originCa: creds?.originCa ?? ""
+        originCa: creds?.originCa ?? "",
+        routeHost: creds?.routeHost ?? ""
       })).catch(() => {
       });
     }
@@ -4691,6 +4694,16 @@ function settingsStore(scope, migrateFrom) {
   }
   return store;
 }
+var ROUTE_FAIL_MAX = 3;
+var ROUTE_FALLBACK_MS = 5 * 6e4;
+var ROUTE_FALLBACK_MAX_MS = 60 * 6e4;
+var ROUTE_PROBE_TIMEOUT_MS = 1e4;
+function isValidRouteHost(raw) {
+  if (typeof raw !== "string" || raw.length === 0 || raw.length > 253)
+    return false;
+  const bare = raw.replace(/^wss?:\/\//, "");
+  return /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*(:\d{1,5})?$/i.test(bare);
+}
 function toBuf(data) {
   if (Buffer.isBuffer(data))
     return data;
@@ -4769,6 +4782,16 @@ var AgentTunnel = class {
   latencyMs = null;
   /** ms epoch the outstanding latency ping was sent (0 = none in flight). */
   pingSentAt = 0;
+  /** The authority the current control socket was dialled through. */
+  dialledHost = null;
+  /** Consecutive dials/probes of the premium host that failed. */
+  routeFails = 0;
+  /** Until when (ms epoch) the premium host is skipped in favour of the default relay. */
+  routeFallbackUntil = 0;
+  /** The next fallback period (grows while the premium host keeps failing). */
+  routeFallbackMs = ROUTE_FALLBACK_MS;
+  /** The in-flight probe of the premium host, if one is running. */
+  routeProbe = null;
   constructor(config, localPort, store) {
     this.config = config;
     this.localPort = localPort;
@@ -4783,7 +4806,8 @@ var AgentTunnel = class {
       connected: false,
       publicUrl: null,
       subdomain: this.creds?.subdomain ?? null,
-      lastError: null
+      lastError: null,
+      route: null
     };
   }
   /**
@@ -4825,7 +4849,14 @@ var AgentTunnel = class {
       return "Password must be at least 8 characters.";
     const rh = typeof relayHost === "string" ? relayHost.trim() : this.creds?.relayHost ?? "";
     const ca = typeof originCa === "string" ? originCa.trim() : this.creds?.originCa ?? "";
-    this.creds = { subdomain: label, password: String(password), e2ePassword: this.creds?.e2ePassword, e2eSalt: this.creds?.e2eSalt, relayHost: rh || void 0, originCa: ca || void 0 };
+    const sameTarget = this.creds?.subdomain === label && (this.creds?.relayHost ?? "") === (rh || "");
+    this.creds = { subdomain: label, password: String(password), e2ePassword: this.creds?.e2ePassword, e2eSalt: this.creds?.e2eSalt, relayHost: rh || void 0, originCa: ca || void 0, routeHost: sameTarget ? this.creds?.routeHost : void 0 };
+    this.status.route = null;
+    if (!sameTarget) {
+      this.routeFails = 0;
+      this.routeFallbackUntil = 0;
+      this.routeFallbackMs = ROUTE_FALLBACK_MS;
+    }
     this.refreshE2E();
     this.saveCreds(this.creds);
     this.status.configured = true;
@@ -4899,9 +4930,12 @@ var AgentTunnel = class {
   info() {
     const host = this.effectiveRelayHost();
     const direct = /^wss?:\/\//.test(host) || this.effectiveOriginCa() !== null;
+    const live = this.status.connected && this.dialledHost !== null ? this.dialledHost : host;
     return {
-      relayHost: host.replace(/^wss?:\/\//, "").replace(/\/.*$/, ""),
+      relayHost: live.replace(/^wss?:\/\//, "").replace(/\/.*$/, ""),
       direct,
+      route: this.status.route,
+      routeHost: this.creds?.routeHost ?? null,
       connectedSince: this.connectedSince,
       served: this.served,
       localPort: this.localPort(),
@@ -4916,6 +4950,10 @@ var AgentTunnel = class {
     this.status.connected = false;
     this.status.publicUrl = null;
     this.status.subdomain = null;
+    this.status.route = null;
+    this.routeFails = 0;
+    this.routeFallbackUntil = 0;
+    this.routeFallbackMs = ROUTE_FALLBACK_MS;
     if (this.reconnectTimer !== null) {
       clearTimeout(this.reconnectTimer);
       this.reconnectTimer = null;
@@ -4934,15 +4972,168 @@ var AgentTunnel = class {
       clearTimeout(this.reconnectTimer);
     if (this.heartbeatTimer !== null)
       clearInterval(this.heartbeatTimer);
+    this.dropStreams();
+    this.control?.close();
+    this.control = null;
+    this.status.connected = false;
+  }
+  /**
+   * Tear down every stream bridged over the current control socket. Must run
+   * whenever that socket is abandoned — on close AND on a deliberate redial —
+   * because the relay numbers streams per connection from 1: a request or
+   * browser socket left over from the old connection would otherwise answer to
+   * the ids of the new one and leak its bytes into a stranger's stream.
+   */
+  dropStreams() {
     for (const req of this.requests.values())
       req.destroy();
     for (const sock of this.sockets.values())
       sock.close();
     this.requests.clear();
     this.sockets.clear();
-    this.control?.close();
+    this.reqE2E.clear();
+  }
+  /**
+   * Which authority to dial: the relay-assigned premium host when one is
+   * remembered and not in a fallback period, else the default relay host. The
+   * premium host is only ever set by a route announcement from the relay.
+   */
+  dialHost() {
+    const route = this.creds?.routeHost;
+    if (route !== void 0 && route !== "" && Date.now() >= this.routeFallbackUntil)
+      return route;
+    return this.effectiveRelayHost();
+  }
+  /** Whether the live control socket was dialled through the remembered premium host. */
+  onPremiumPath() {
+    const route = this.creds?.routeHost;
+    return route !== void 0 && route !== "" && this.dialledHost === route;
+  }
+  /** Whether the premium host is currently being skipped after repeated failures. */
+  inRouteFallback() {
+    return Date.now() < this.routeFallbackUntil;
+  }
+  /**
+   * Apply a route announcement (READY or a mid-session ROUTE frame).
+   *
+   * `status.route` reflects the OPERATOR'S ASSIGNMENT, because that is what a
+   * public visitor experiences: enabling premium points the subdomain's DNS at
+   * the accelerator, so browser traffic is accelerated no matter which host the
+   * agent's own control socket happens to use. Moving the control socket onto
+   * the premium host too is a best-effort bonus for the uplink — it may briefly
+   * fail while the fresh DNS record propagates, and if the host stays
+   * unreachable the agent quietly keeps its control socket on the default relay.
+   * Neither case changes the displayed route or breaks the tunnel.
+   *
+   * - `premium` with a usable host: show premium, remember the host, and (unless
+   *   in a fallback window) PROBE it; only a host that answers gets the control
+   *   socket moved onto it — a working tunnel is never dropped for a dead host.
+   * - `standard`: the operator withdrew the fast path — show standard, forget
+   *   the host, and return the control socket to the default relay.
+   */
+  applyRoute(route, routeHost) {
+    if (this.creds === null)
+      return;
+    if (route === "premium" && isValidRouteHost(routeHost)) {
+      this.status.route = "premium";
+      if (this.creds.routeHost !== routeHost) {
+        this.creds = { ...this.creds, routeHost };
+        this.saveCreds(this.creds);
+        this.routeFails = 0;
+        this.routeFallbackUntil = 0;
+        this.routeFallbackMs = ROUTE_FALLBACK_MS;
+      }
+      this.tryPremium();
+      return;
+    }
+    if (route === "standard" || route === "premium") {
+      this.status.route = "standard";
+      this.routeFallbackUntil = 0;
+      this.routeFails = 0;
+      this.routeFallbackMs = ROUTE_FALLBACK_MS;
+      const hadRoute = this.creds.routeHost !== void 0 && this.creds.routeHost !== "";
+      if (hadRoute) {
+        this.creds = { ...this.creds, routeHost: void 0 };
+        this.saveCreds(this.creds);
+        if (this.dialledHost !== this.effectiveRelayHost())
+          this.redial();
+      }
+    }
+  }
+  /**
+   * Move the control socket onto the premium host when that is worth doing:
+   * assigned premium, currently on the default relay, not in a fallback window,
+   * and no probe already running. The host is probed first (a plain WebSocket
+   * handshake, no HELLO — so the relay never sees a second agent) and the live
+   * socket is only redialled once the host has answered. A failed probe counts
+   * like a failed dial; enough of them open a fallback window.
+   */
+  tryPremium() {
+    const host = this.creds?.routeHost;
+    if (host === void 0 || host === "" || this.routeProbe !== null)
+      return;
+    if (!this.status.connected || this.onPremiumPath() || this.inRouteFallback())
+      return;
+    this.routeProbe = this.probeHost(host).then((ok) => {
+      this.routeProbe = null;
+      if (this.stopped || this.creds?.routeHost !== host || this.status.route !== "premium")
+        return;
+      if (!this.status.connected || this.onPremiumPath())
+        return;
+      if (ok)
+        this.redial();
+      else
+        this.noteRouteFailure();
+    });
+  }
+  /** Whether `host` accepts a WebSocket on the agent path right now (no HELLO is sent). */
+  probeHost(host) {
+    return new Promise((resolve2) => {
+      const base = host.includes("://") ? host : `wss://${host}`;
+      let ws;
+      try {
+        ws = new import_websocket.default(`${base}${AGENT_WS_PATH}`, { handshakeTimeout: ROUTE_PROBE_TIMEOUT_MS });
+      } catch {
+        resolve2(false);
+        return;
+      }
+      let done = false;
+      const finish = (ok) => {
+        if (done)
+          return;
+        done = true;
+        if (process.env.DSHN_DEBUG)
+          console.error(`[dshn-agent] premium probe of ${host}: ${ok ? "reachable" : "unreachable"}`);
+        resolve2(ok);
+        if (ok)
+          ws.close();
+        else
+          ws.terminate();
+      };
+      ws.on("open", () => finish(true));
+      ws.on("error", () => finish(false));
+      ws.on("close", () => finish(false));
+    });
+  }
+  /** Count a failed dial/probe of the premium host; enough in a row open a (growing) fallback window. */
+  noteRouteFailure() {
+    this.routeFails++;
+    if (this.routeFails < ROUTE_FAIL_MAX)
+      return;
+    this.routeFails = 0;
+    this.routeFallbackUntil = Date.now() + this.routeFallbackMs;
+    this.routeFallbackMs = Math.min(this.routeFallbackMs * 2, ROUTE_FALLBACK_MAX_MS);
+  }
+  /** Drop the live socket and dial again right away (route change). */
+  redial() {
+    if (process.env.DSHN_DEBUG)
+      console.error(`[dshn-agent] route change \u2192 redialling via ${this.dialHost()}`);
+    this.backoffMs = 1e3;
+    const ws = this.control;
     this.control = null;
-    this.status.connected = false;
+    this.dropStreams();
+    ws?.close();
+    this.connect();
   }
   connect() {
     if (this.stopped || this.creds === null)
@@ -4954,11 +5145,12 @@ var AgentTunnel = class {
       clearTimeout(this.reconnectTimer);
       this.reconnectTimer = null;
     }
-    const relayHost = this.effectiveRelayHost();
+    const relayHost = this.dialHost();
     const base = relayHost.includes("://") ? relayHost : `wss://${relayHost}`;
+    this.dialledHost = relayHost;
     const wsOpts = { maxPayload: 512 * 1024 * 1024 };
     const ca = this.effectiveOriginCa();
-    if (ca !== null)
+    if (ca !== null && relayHost === this.effectiveRelayHost())
       wsOpts.ca = ca;
     const ws = new import_websocket.default(`${base}${AGENT_WS_PATH}`, wsOpts);
     this.control = ws;
@@ -5011,10 +5203,14 @@ var AgentTunnel = class {
         this.control.terminate();
         return;
       }
+      if (this.status.route === "premium")
+        this.tryPremium();
       this.sendPing();
     }, LATENCY_PING_MS);
   }
   onClose() {
+    if (!this.status.connected && this.onPremiumPath())
+      this.noteRouteFailure();
     this.status.connected = false;
     this.connectedSince = null;
     this.latencyMs = null;
@@ -5024,12 +5220,7 @@ var AgentTunnel = class {
       clearInterval(this.heartbeatTimer);
       this.heartbeatTimer = null;
     }
-    for (const req of this.requests.values())
-      req.destroy();
-    for (const sock of this.sockets.values())
-      sock.close();
-    this.requests.clear();
-    this.sockets.clear();
+    this.dropStreams();
     if (this.stopped)
       return;
     if (this.reconnectTimer !== null)
@@ -5071,12 +5262,22 @@ var AgentTunnel = class {
     switch (frame.t) {
       case "ready":
         this.backoffMs = 1e3;
+        this.routeFails = 0;
+        if (this.onPremiumPath())
+          this.routeFallbackMs = ROUTE_FALLBACK_MS;
         this.status.connected = true;
         this.status.publicUrl = frame.publicUrl;
         this.status.subdomain = frame.subdomain;
         this.status.lastError = null;
         this.connectedSince = Date.now();
         this.sendPing();
+        if (frame.route !== void 0)
+          this.applyRoute(frame.route, frame.routeHost);
+        else if (this.creds?.routeHost)
+          this.applyRoute("standard", void 0);
+        break;
+      case "route":
+        this.applyRoute(frame.route, frame.routeHost);
         break;
       case "deny":
         this.status.lastError = frame.reason;
@@ -5375,6 +5576,10 @@ function apply(ctx, rawConfig) {
         // Connection details for the panel.
         relayHost: info.relayHost,
         mode: info.direct ? "direct" : "cloudflare",
+        // Which path the relay assigned: 'premium' (accelerated, via routeHost)
+        // or 'standard'; null until a route-aware relay has said.
+        route: info.route,
+        routeHost: info.routeHost,
         connectedSince: info.connectedSince,
         served: info.served,
         localPort: info.localPort,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dshn/agent",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Forward a local dsh web service to the public internet over ds.hn (bundled).",
   "keywords": [
     "dsh",
@@ -31,6 +31,7 @@
     "client.js",
     "cordis.patch.yml",
     "README.md",
+    "README.zh.md",
     "LICENSE"
   ],
   "dsh": {