dsh-push-host 0.3.1 → 0.4.0

package/README.md

@@ -53,6 +53,18 @@ ask_user_question (工具, 进程内)
    时调用它返回 `false`。此时**不 ack**、留在队列里，等前台等待结束（timed 的 timeout / UI 作答）
    下一轮再投。
 
+## 发布后从 npm 装回来时踩的坑（2026-10-27，第六个）
+
+1. **`priority` 只能是整数 1–5，字符串 `'default'` 会被 relay 判成非法 JSON。**
+   `RelayClient.push()` 的默认值原来是字符串 `'default'`（那是 ntfy **请求头**写法里的取值），
+   而 ntfy 的 **JSON body** 只接受数字 ⇒ 服务端回
+   `400 {"code":40024,"error":"invalid request: request body must be valid JSON"}`。
+   这条报错把人往"body 不是合法 JSON"上引，实际 body 完全合法，只是 `priority` 类型不对。
+   插件内部三个调用点都显式传了 `4 / 1 / 3`，所以线上一直没暴露；**只有"没传 priority"的外部
+   调用方（自己写脚本验证、第三方集成）会踩**。0.3.2 起默认值改成整数 `3`。
+   同一条规则也解释了为什么 `priority: 'high'`、`priority: '4'` 都 400，而 `3`、`4`、`"4"` 之外
+   的数字全 200 —— **别把请求头的取值抄进 JSON body。**
+
 ## 生产切换踩过的坑（2026-10-12/13，五个，都在这份代码里修掉了）
 
 1. **schema 校验后的空默认值会盖掉凭据文件。** `apply()` 拿到的 `config` 已经过 schema 校验，
@@ -158,14 +170,17 @@ timed 路径行为不变。插件侧修不了（`firstOf` 赢后够不着那条
 
 本包按可发布的 npm 包组织（`package.json` 带 `repository` / `homepage` / `bugs` / `author` /
 `publishConfig.access: public` / `engines` / `files` 白名单，MIT `LICENSE` 随包）。
-发布由仓库维护者做（`npm publish`，本机没有 npm，见下），用户侧只需 `dsh plugin add`：
+用户侧只需 `dsh plugin add`：
+
+**已发布到 npm：`dsh-push-host@0.3.2`（2026-10-27）** — https://registry.npmjs.org/dsh-push-host
+（`latest` 即最新版；`repository.directory = host-plugin`，市场据此自动关联 npm 包）
 
 ```powershell
-# 从 npm 装（发布后）
+# 从 npm 装（推荐，免 allowBuilds 构建授权）
 & $dsh plugin --profile <profile> add dsh-push-host
 
 # 从 tarball 装（离线/内网，等价路径，已实测）
-& $dsh plugin --profile <profile> add ./dsh-push-host-0.2.1.tgz
+& $dsh plugin --profile <profile> add ./dsh-push-host-0.3.2.tgz
 
 # 从本地目录装（开发期，改完立即生效）
 & $dsh plugin --profile <profile> add "link:<仓库>/host-plugin"
@@ -174,12 +189,12 @@ timed 路径行为不变。插件侧修不了（`firstOf` 赢后够不着那条
 三种方式在 profile 里的落点完全相同：`package.json` 的 `dependencies` 多一项、`dsh.profile.bundles`
 多一项（DSH 读到本包的 `dsh.bundle.patch` 自动登记 bundle 层）。
 
-**打包**：有 npm 的机器直接 `npm pack`（`files` 白名单已配好）；本机没装 npm（DSH 只带 pnpm），
-所以仓库里配了等价工具，输出同样的 `npm notice` 清单与 sha1：
+**打包**：有 npm 的机器直接 `npm pack`（`files` 白名单已配好）。
+DSH 运行时只带 pnpm 的机器上，仓库里配了等价工具，输出同样的 `npm notice` 清单与 sha1：
 
 ```powershell
 & $node tools/pack-npm-tarball.mjs host-plugin --dry-run   # 只看清单，不落盘
-& $node tools/pack-npm-tarball.mjs host-plugin             # 落盘 host-plugin/dsh-push-host-0.2.1.tgz
+& $node tools/pack-npm-tarball.mjs host-plugin             # 落盘 host-plugin/dsh-push-host-0.3.2.tgz
 ```
 
 实测产物 9 个文件：`LICENSE`、`README.md`、`cordis.patch.yml`、`package.json`、
@@ -202,7 +217,7 @@ $dsh = '<DSH 安装目录>\resources\runtime\cli\bin\dsh.cmd'      # 不在 PATH
 & $dsh --profile pushdist --from-default-profile headless --dump-config
 
 # 2. 把包（或 tarball）装进去
-& $dsh plugin --profile pushdist add ./dsh-push-host-0.2.1.tgz
+& $dsh plugin --profile pushdist add ./dsh-push-host-0.3.2.tgz
 
 # 3. 验收挂载：看 dump-config 尾部
 & $dsh --profile pushdist --dump-config | Select-Object -Last 3
@@ -224,7 +239,7 @@ $dsh = '<DSH 安装目录>\resources\runtime\cli\bin\dsh.cmd'      # 不在 PATH
 ```powershell
 & powershell -NoProfile -ExecutionPolicy Bypass -File deploy/windows/install-user.ps1 `
     -Profile <profile> -DshCli "<DSH 安装目录>\resources\runtime\cli\bin\dsh.cmd" `
-    -Source .\dsh-push-host-0.2.1.tgz
+    -Source .\dsh-push-host-0.3.2.tgz
 # 成功后照打印的 next steps 走：重启 DSH（工具注册是冷的）→ 用新会话（变体钉在会话创建时）
 ```
 
@@ -333,6 +348,51 @@ harness 自己的 `~\.dsh\dsh-runtimes\...` 那个 node 同为 v24.21.0、`os.tm
   只粘一串 `tk_…` 的老通行证在 App 里仍按默认 topic `dsh` 处理，所以现有手机不会被这次改动破坏。
 - 发号失败（401 无密钥 / 409 名字占用 / 服务不可达）都在面板上显示中文原因，**不动本机凭据文件、不影响已工作的推送链路**。
 
+## 远程访问：没装 Tailscale 也能从外网打开（v0.4.0）
+
+前面所有能力都假设手机和电脑在同一个 tailnet 里。真实用户经常没有 —— 这一版给一条不依赖
+Tailscale 的公网入口，而且**重启后不用重新扫码**。
+
+设置 → 常规 → 远程访问 → 打开，系统会：
+
+1. 在 `127.0.0.1:<随机端口>` 起一个**内层改写网关**；
+2. 用 `cloudflared tunnel` 把它挂到 Cloudflare 的快速隧道，拿到一个 `https://xxx.trycloudflare.com`；
+3. 把 `https://xxx.trycloudflare.com/?k=<口令>` 经 ntfy 推到你手机。
+
+点开这个链接：第一次访问会种一个 **30 天有效**的 cookie，然后 303 把 `?k=` 从地址栏抹掉。
+之后 30 天内换电脑重启、换 DSH token 都不用再扫。
+
+### 为什么不能直接把 3081 暴露出去
+
+DSH 有两道栅栏，都是 2026-10-28 实测的：
+
+| 请求 | Host | Origin | 结果 |
+|---|---|---|---|
+| `GET /api/session/list` | `abc.trycloudflare.com` | — | **403 host-not-trusted** |
+| `GET /api/session/list` | `127.0.0.1:3081` | `https://abc.trycloudflare.com` | **403 origin-not-trusted** |
+
+所以只改 `--trusted-host` 不够，Origin 也要改。网关把 Host/Origin/Referer 全程改写成回环，
+再替客户端注入 DSH 自己的登录 cookie（从 `~/.dsh/web.log` 现取，随 DSH 重启自动刷新）——
+**这就是「用户不用重新扫码」的实现方式**：会变的 token 藏在内层，对外只发自己的 30 天口令。
+
+### 几个实现上的硬点（改代码前先读）
+
+- **口令存凭据文件，不进 `cordis.patch.yml`**，且 cookie 里存的是 `HMAC-SHA256(secret)` 而不是口令原文。
+- **`.volatile()` 字段在 `resolvePluginConfig` 里是 cosmokit ref 对象**，既不是 `''` 也不是 `undefined`，
+  会被当成"用户显式配置"；`String(ref)` 得到 `[object Object]` 把凭据文件的值盖掉。2026-10-28 就因此
+  每次开机重新生成口令、前一天推的链接当天失效。**必须先用 `volatileValue()` 解开 ref 再判空**。
+- 开关的落盘键是 `remoteEnabled: 'on'|'off'`，**不复用 schema 里的 `remoteAccess` 布尔**（布尔默认值
+  `false` 会反压文件里的 `true`）。
+- 起隧道后 Cloudflare 边缘还要 **3~8 秒**才挂上域名，这期间访问回 **530**。`waitPublic()` 会先自打
+  `/__dshpush/status` 到「不是 5xx」再推链接，否则用户点开就是 Cloudflare 报错页。
+- WebSocket 升级时要**补回 `Connection`/`Upgrade`**（`HOP_BY_HOP` 会剔掉它们，缺了上游不触发 upgrade）。
+- 隧道换了域名会自动重推；`remotePhase` 是给人看的一句话（未开启 / 正在连接 / 隧道建立中 / 已就绪）。
+
+### 局限
+
+快速隧道的域名每次重启都变（Cloudflare 免费策略），**但口令不变，所以旧链接仍然可用到过期**；
+域名变了会重推一条新的。想要固定地址需要自己的域名 + 命名隧道，那是下一版的事。
+
 ## 给一个真实用户开通（凭据文件 + 配对）
 
 **目标**：开通一个用户，操作者要做的只有两件事 —— 在 relay 上跑一条开号命令、把打印出来的

package/lib/client.js

@@ -71,6 +71,13 @@ window.__ModuleLoader__.load({
 				order: 130,
 				label: "通行证",
 			}, () => PassPanelRow(scope, listeners, notify)))), "dsh-push-host: pass panel row");
+			// v0.4.0：远程访问——给没装 Tailscale 的人一条 30 天免登录的公网入口（宿主侧跑 cloudflared）。
+			ctx.effect(() => ctx.configForms.whileServed([NS], () => ctx.slots.inject("settings.general.item", () => ctx.slots.register({
+				name: "settings.general.item",
+				id: "push-host-remote",
+				order: 140,
+				label: "远程访问",
+			}, () => RemoteRow(scope, listeners, notify)))), "dsh-push-host: remote access row");
 			// v0.2.2：把推送链接 hash 里的来源会话切到主视图（与设置行互不相干，各自独立生效）。
 			revealFromHash(ctx);
 		}
@@ -235,6 +242,102 @@ window.__ModuleLoader__.load({
 						btn("吊销", () => ask("revoke", row.name), !writable)))) : null);
 		}
 
+		/**
+		 * 远程访问（v0.4.0）：给没装 Tailscale 的人一条公网入口。
+		 *
+		 * 为什么不直接暴露 3081：DSH 自己有两道栅栏（Host 不在白名单 403 host-not-trusted、
+		 * Origin 不在白名单 403 origin-not-trusted，2026-10-28 实测），而且它的 token 每次重启
+		 * 都变 —— 用户「重启后还得再扫码」正是要避免的事。所以宿主侧起一个内层改写网关
+		 * （把 Host/Origin 改回回环）再挂 cloudflared，对外只发一条 30 天有效的口令链接。
+		 *
+		 * 这一行只负责：开关、口令（可换）、看状态、把链接再推一次。真正的隧道在
+		 * lib/index.js:RemoteAccessor + lib/remote.js。
+		 * @param scope - 绑定了 push-host 的配置表单。
+		 * @param listeners - 订阅回调集合。
+		 * @param notify - 唤醒全部订阅者。
+		 */
+		function RemoteRow(scope, listeners, notify) {
+			const [snapshot, setSnapshot] = react.useState(() => scope.getSnapshot());
+			const [busy, setBusy] = react.useState(false);
+			const [copied, setCopied] = react.useState(false);
+			react.useEffect(() => {
+				const update = () => setSnapshot(scope.getSnapshot());
+				listeners.add(update);
+				update();
+				return () => {
+					listeners.delete(update);
+				};
+			}, []);
+			const ready = snapshot.status === "ready";
+			const value = snapshot.value ?? {};
+			const text = (key) => (typeof value[key] === "string" ? value[key] : "");
+			const on = value.remoteAccess === true;
+			const phase = text("remotePhase");
+			const url = text("remoteUrl");
+			const status = text("remoteStatus");
+			const pushResult = text("remotePushResult");
+			const secret = text("remoteSecret");
+			const done = text("remoteDone");
+			const seq = text("remoteSeq");
+			react.useEffect(() => {
+				if (busy && done !== "" && done === seq) setBusy(false);
+			}, [done, seq, busy]);
+			const writable = ready && snapshot.writable === true && !busy;
+			// 30 天口令链接：宿主 pushLink 发的是同一条（remoteMessage），这里现拼一条方便复制。
+			const link = url !== "" && secret !== "" ? (url + "/?k=" + secret) : "";
+			const write = (ops) => {
+				if (!writable) return;
+				const nextSeq = String(Date.now()) + "-" + Math.floor(Math.random() * 1e6).toString(36);
+				setBusy(true);
+				setCopied(false);
+				setTimeout(() => setBusy(false), 30000);
+				Promise.resolve()
+					.then(() => scope.mutate(ops.concat([{ op: "set", path: ["remoteSeq"], value: nextSeq }]), snapshot.revision))
+					.catch(() => setBusy(false))
+					.then(() => notify());
+			};
+			const act = (action) => write([{ op: "set", path: ["remoteAction"], value: action }]);
+			const toggle = () => write([{ op: "set", path: ["remoteAccess"], value: !on }]);
+			const copy = () => {
+				if (link === "") return;
+				try {
+					navigator.clipboard.writeText(link);
+					setCopied(true);
+				} catch {
+					setCopied(false);
+				}
+			};
+			const btn = (label, onClick, disabled) => react.createElement("button", {
+				type: "button", disabled: disabled, onClick: onClick,
+				style: { padding: "6px 12px", borderRadius: 8, border: "1px solid currentColor", opacity: disabled ? 0.5 : 1 },
+			}, label);
+			return react.createElement("div", { style: { display: "flex", flexDirection: "column", gap: 6, padding: "8px 0" } },
+				react.createElement("div", { style: { fontWeight: 600 } }, "远程访问"),
+				react.createElement("div", { style: { fontSize: 13, opacity: 0.75 } },
+					"没装 Tailscale 也能用：给这台机器开一条公网入口，手机打开一次就记住 30 天，重启不用重新扫码。"),
+				react.createElement("div", { style: { display: "flex", gap: 6, alignItems: "center", flexWrap: "wrap" } },
+					btn(on ? "关闭远程访问" : "开启远程访问", toggle, !writable),
+					on ? btn("重新推送链接", () => act("push"), !writable) : null,
+					on ? btn("换一个口令", () => act("rotate"), !writable) : null,
+					on ? btn("重建隧道", () => act("reconnect"), !writable) : null),
+				react.createElement("div", { style: { fontSize: 12, opacity: 0.6 } },
+					on
+						? ("状态：" + (phase || "…") + (status !== "" ? ("（" + status + "）") : ""))
+						: "未开启。开启后需要本机有 cloudflared（放 ~/.dsh/bin/cloudflared.exe，或在 PATH 里）；没有也能开，只是会提示找不到程序。"),
+				link !== ""
+					? react.createElement("div", { style: { display: "flex", gap: 6, alignItems: "center", flexWrap: "wrap" } },
+						react.createElement("textarea", {
+							readOnly: true, value: link, rows: 2,
+							onFocus: (event) => { try { event.target.select(); } catch {} },
+							style: { flex: "1 1 240px", padding: "6px 8px", borderRadius: 8, border: "1px solid currentColor", background: "transparent", color: "inherit", fontFamily: "monospace", fontSize: 12 },
+						}),
+						btn(copied ? "已复制" : "复制", copy, false))
+					: null,
+				pushResult !== "" ? react.createElement("div", { style: { fontSize: 12, opacity: 0.7 } }, pushResult) : null,
+				react.createElement("div", { style: { fontSize: 12, opacity: 0.55 } },
+					"这条链接里的口令就是开关机钥匙：谁拿到谁能进。泄露了就在这里点「换一个口令」，旧链接立刻作废。地址是 Cloudflare 快速隧道，每次重建都会换域名，换了宿主会自动再推一次到手机。"));
+		}
+
 
 		/**
 		 * v0.2.2：推送里的 `#web` 链接把来源会话放在 **URL hash 片段**（`…#session-<uuid>`，服务端

package/lib/credentials.mjs

@@ -91,10 +91,16 @@ export const CREDENTIAL_KEYS = {
   provisionToken: ['provisiontoken'],
   provisionBase: ['provisionbase'],
   webLog: ['weblog'],
+  // v0.4.0 远程访问。三处都要有：index.js 的 CREDENTIAL_CONFIG_KEYS（允许从文件读）、
+  // 这张表（真的去读），以及 selftest 的两条清单对账断言（漏一个就 FAIL，2026-10-17 踩过）。
+  // remoteEnabled 是 'on'/'off' 字符串而不是布尔：布尔开关的 schema 默认值会反压文件值。
+  remoteSecret: ['remotesecret'],
+  remoteBin: ['remotebin'],
+  remoteEnabled: ['remoteenabled'],
 }
 
 /** Keys that hold secrets: they are never echoed back in logs or diagnostic output. */
-export const SECRET_KEYS = ['hostToken', 'ntfyToken', 'phoneToken', 'regToken', 'provisionToken']
+export const SECRET_KEYS = ['hostToken', 'ntfyToken', 'phoneToken', 'regToken', 'provisionToken', 'remoteSecret']
 
 /** `~` / `~/x` / `~\x` → the real home path; everything else resolves against `base`. */
 export function expandHome(input, home = homedir()) {

package/lib/index.js

@@ -47,6 +47,7 @@ import { join } from 'node:path'
 import { randomUUID } from 'node:crypto'
 import z from '@deepseek-ai/schemastery'
 import { RelayClient } from './relay.js'
+import { RemoteAccess, newRemoteSecret, remoteMessage } from './remote.js'
 import { credentialsPath, loadCredentials } from './credentials.mjs'
 
 /** Cordis plugin name used by loader diagnostics. */
@@ -90,6 +91,15 @@ const DEFAULTS = {
   echoAnswers: true,
   claimForeground: false,
   log: true,
+  // 远程访问（v0.4.0）：默认关闭，关着的时候整条链路是惰性的（不装 cloudflared 也不报错）。
+  // remoteSecret 就是用户手里那条 30 天链接里的口令；remotePort=0 表示让系统随便挑个空闲端口。
+  // remoteEnabled 不是 schema 键：它是凭据文件里的「上次开关状态」（'on'/'off'），
+  // 因为布尔开关的 schema 默认值 false 会反压凭据文件里的 true（见 CREDENTIAL_CONFIG_KEYS 注释）。
+  remoteAccess: false,
+  remoteSecret: '',
+  remoteBin: '',
+  remotePort: 0,
+  remoteEnabled: '',
 }
 
 /** Config keys (schema/overlay vocabulary) = the defaults above. */
@@ -178,6 +188,30 @@ export const Config = z.object({
   provisionDefault: z.string().default('').volatile(),
   /** 宿主处理完的请求号回写。 */
   provisionDone: z.string().default('').volatile(),
+
+  // ── 远程访问（v0.4.0）────────────────────────────────────────────────────────────
+  /** 总开关：只有 true 才起网关 + 隧道。 */
+  remoteAccess: z.boolean().default(false).volatile(),
+  /** 长期口令（30 天链接里的 `?k=`）。空着且打开开关 = 让宿主自动生成一串。 */
+  remoteSecret: z.string().default('').volatile(),
+  /** cloudflared 可执行文件；空 = 先找 `~/.dsh/bin/cloudflared[.exe]`，再找 PATH。 */
+  remoteBin: z.string().default('').volatile(),
+  /** 网关端口；0 = 挑空闲端口（推荐，避免与他人自跑的 cloudflared 抢端口）。 */
+  remotePort: z.number().step(1).min(0).max(65535).default(0).volatile(),
+  /** 当前公网地址（宿主写，设置行展示 + 复制；隧道重启换了域名会更新）。 */
+  remoteUrl: z.string().default('').volatile(),
+  /** 最近一次错误（'' = 正常），设置行直接显示给人看。 */
+  remoteStatus: z.string().default('').volatile(),
+  /** 一句人话状态：未开启 / 正在连接 / 已就绪。 */
+  remotePhase: z.string().default('').volatile(),
+  /** 上一次「推送链接到手机」的结果（'' = 没点过）。 */
+  remotePushResult: z.string().default('').volatile(),
+  /** 请求号：设置行按一次「重新连接」写一个新值，宿主据此重启隧道。 */
+  remoteSeq: z.string().default('').volatile(),
+  /** 动作：'' = 无；push = 把当前链接推到手机；reconnect = 重起隧道；rotate = 换口令。 */
+  remoteAction: z.union(['', 'push', 'reconnect', 'rotate']).default('').volatile(),
+  /** 宿主处理完的请求号回写（设置行据此清 busy）。 */
+  remoteDone: z.string().default('').volatile(),
 })
 
 /** `[{label, description?}]` (service vocabulary) → `[label]` (what the relay/phone render). */
@@ -798,7 +832,15 @@ export function resolvePluginConfig(config = {}, { env = process.env, readFile =
   // as "not set", so the file can fill it in. `false` stays meaningful (never dropped).
   const fromCredentials = pickConfigKeys(file.value)
   const explicit = {}
-  for (const [key, value] of Object.entries(config)) {
+  for (const [key, rawValue] of Object.entries(config)) {
+    // 2026-10-28 fix: a `.volatile()` field arrives here as a cosmokit ref OBJECT, so it is neither
+    // '' nor undefined/null and used to count as "explicitly configured"; `String(ref)` then became
+    // "[object Object]" (15 chars) and overrode the real value from the credentials file. remoteSecret
+    // is validated by length >= 16, so the plugin regenerated the passphrase on every boot and the
+    // 30-day link pushed the day before died. Unwrap the ref before deciding.
+    const value = (rawValue !== null && typeof rawValue === 'object' && typeof rawValue.get === 'function')
+      ? volatileValue(rawValue, '')
+      : rawValue
     if (value !== '' && value !== undefined && value !== null) explicit[key] = value
   }
   const resolved = resolveConfig({ ...fromCredentials, ...explicit })
@@ -843,6 +885,14 @@ export const CREDENTIAL_CONFIG_KEYS = [
   'regToken',
   'provisionBase',
   'provisionToken',
+  // v0.4.0 远程访问：口令与 cloudflared 路径可以写进凭据文件（用户级、与其余凭据同生死）。
+  // 开关单独用 `remoteEnabled: 'on'` 表达，**不复用 schema 里的 `remoteAccess` 布尔**：那个键的
+  // schema 默认值是 `false`，而 resolvePluginConfig 的 explicit 只丢掉 ''/undefined/null（false 是
+  // 显式值），所以凭据文件里的 true 会被默认 false 反压回去；`remoteEnabled` 不是 DEFAULTS 的键，
+  // resolveConfig 会原样带过来，RemoteAccessor 拿它判断「上次是开着还是关着」。
+  'remoteSecret',
+  'remoteBin',
+  'remoteEnabled',
 ]
 
 function pickConfigKeys(values) {
@@ -1394,6 +1444,312 @@ export class PassProvisioner {
   }
 }
 
+/**
+ * 远程访问（v0.4.0）的宿主侧壳：把 `RemoteAccess`（lib/remote.js）挂到插件生命周期上，
+ * 并把运行态镜像回 `remote*` 那几个 volatile 字段给网页设置行看。
+ *
+ * 三条设计约束（都是踩过的坑换来的）：
+ *
+ * 1. **口令存凭据文件，不存 volatile**。浏览器写 volatile 会被持久化进 profile 的
+ *    `cordis.patch.yml`（0.3.0 的通行证面板实测过），把长期口令写进用户的补丁文件既难看
+ *    又难撤。所以 `remoteSecret` 只做「显示/输入」通道，真正的落盘走
+ *    `writeCredentialsPatch(remoteSecret / remoteAccess)`，下次开机由 `resolvePluginConfig`
+ *    从凭据文件读回来。
+ * 2. **改 volatile 会热重启本插件 fiber** ⇒ 任何持久化都不能在同一次 `run()` 里做完就指望
+ *    内存还活着。做法与 PassProvisioner 相同：结果挂到进程级 store，新 fiber 启动时回灌。
+ * 3. **失败绝不致命**：起不来隧道只是 `remoteStatus` 有值，推送/作答链路完全不受影响。
+ *    宿主会把未处理的 rejection 当致命加载错误并退出进程，所以所有入口都吞掉异常。
+ */
+export class RemoteAccessor {
+  constructor(ctx, config, resolved, host, log, deps = {}) {
+    this.ctx = ctx
+    this.config = config
+    this.resolved = resolved
+    this.host = host
+    this.log = log
+    this.writeCreds = deps.writeCredentialsPatch || writeCredentialsPatch
+    this.credentialsPath = deps.credentialsPath || ''
+    this.engine = null
+    this.busy = false
+    this.scheduled = false
+    this.lastSeq = ''
+    /** 上一次推给手机的地址，避免隧道抖动时反复推送。 */
+    this.pushedUrl = ''
+    /** 正在把凭据文件里的开关状态回写进 volatile（此时的 volatile-update 不是用户操作）。 */
+    this.mirroring = false
+  }
+
+  read(key) { return volatileValue(this.config[key], '') }
+
+  /**
+   * 读一个「既可能在 volatile 里（本次会话刚改）、也可能只在凭据文件里」的配置。
+   *
+   * 2026-10-28 修的缺陷：`read()` 只看 `this.config[key]`，而 `Config` schema 的默认值是空串，
+   * 凭据文件里的值落在 `this.resolved` 上 ⇒ 只读 config 就等于永远读不到存盘的口令，**每次开机
+   * 都会重新生成一串新口令**，昨天推给手机的 30 天链接当天就失效。凡是持久化的键都必须走这里。
+   */
+  readAny(key) {
+    const live = this.read(key)
+    if (live !== '' && live !== undefined && live !== null && live !== false) return live
+    const saved = this.resolved ? this.resolved[key] : undefined
+    return saved === undefined || saved === null ? '' : saved
+  }
+
+  write(key, value) { setVolatileValue(this.config, key, value) }
+
+  storeKey() {
+    return 'remote|' + String(this.resolved.host || '') + '|' + String(this.credentialsPath || '')
+  }
+
+  /** 把最近状态回灌进当前 fiber（fiber 刚被热重启时设置行不该是空的）。 */
+  applyStore() {
+    const saved = remoteStore()[this.storeKey()]
+    if (!saved) return
+    this.write('remoteUrl', String(saved.url || ''))
+    this.write('remoteStatus', String(saved.status || ''))
+    this.write('remotePhase', String(saved.phase || ''))
+    this.write('remotePushResult', String(saved.pushResult || ''))
+    this.write('remoteDone', String(saved.done || ''))
+  }
+
+  saveStore() {
+    remoteStore()[this.storeKey()] = {
+      url: String(this.read('remoteUrl') || ''),
+      status: String(this.read('remoteStatus') || ''),
+      phase: String(this.read('remotePhase') || ''),
+      pushResult: String(this.read('remotePushResult') || ''),
+      done: String(this.read('remoteDone') || ''),
+    }
+  }
+
+  /**
+   * 把值写进 volatile，但**不让自己的 volatile-update 监听把它当成用户操作**（否则会再跑一遍
+   * persistEnabled/up，无限自激）。设置行读的是 volatile，开机时必须回灌一次，否则口令框是空的、
+   * 复制链接也复制不出东西。
+   */
+  mirror(key, value) {
+    if (this.read(key) === value) return
+    this.mirroring = true
+    try { this.write(key, value) } finally { this.mirroring = false }
+  }
+
+  /** 口令：配置里的（凭据文件/补丁）优先，都没有就生成一串并存盘。 */
+  ensureSecret() {
+    const given = String(this.readAny('remoteSecret') || '').trim()
+    if (given.length >= 16) return given
+    const generated = newRemoteSecret()
+    this.write('remoteSecret', generated)
+    this.persist({ remoteSecret: generated })
+    this.log('已生成远程访问口令（32 字节随机；存进凭据文件，不在补丁里）')
+    return generated
+  }
+
+  /** 落盘（凭据文件）；用于口令与开关，避免它们进 cordis.patch.yml。 */
+  persist(patch) {
+    if (!this.credentialsPath) return
+    try {
+      const saved = this.writeCreds(this.credentialsPath, patch)
+      this.log('远程访问设置已写回凭据文件 ' + saved.path)
+    } catch (error) {
+      this.log('写凭据文件失败：' + String(error?.message ?? error))
+    }
+  }
+
+  /** 起引擎（幂等）。@returns {Promise<void>} */
+  async up() {
+    const secret = this.ensureSecret()
+    this.mirror('remoteSecret', secret)
+    if (!this.engine) {
+      this.engine = new RemoteAccess({
+        log: this.log,
+        secret,
+        binPath: String(this.readAny('remoteBin') || ''),
+        webLog: this.resolved.webLog,
+        port: Number(this.readAny('remotePort') || 0) || 0,
+        onUrl: (url) => this.onUrl(url),
+      })
+    } else {
+      this.engine.setSecret(secret)
+    }
+    this.write('remotePhase', '正在连接…')
+    this.write('remoteStatus', '')
+    try {
+      const state = await this.engine.start()
+      if (state.running === false) {
+        this.write('remotePhase', '未运行')
+        this.write('remoteStatus', state.error || '启动失败')
+        return
+      }
+      // 地址可能比 server.listen 晚几秒才拿到（等 cloudflared），先给个中间态。
+      if (!state.url) this.write('remotePhase', '隧道建立中…')
+    } catch (error) {
+      this.write('remotePhase', '未运行')
+      this.write('remoteStatus', '启动失败：' + String(error?.message ?? error))
+      this.log('远程访问启动失败：' + String(error?.message ?? error))
+    }
+  }
+
+  /** 引擎拿到公网地址（或换了地址）时：镜像 + 首次/变更时推手机。 */
+  onUrl(url) {
+    this.write('remoteUrl', url)
+    this.write('remotePhase', '隧道建立中…')
+    this.write('remoteStatus', '')
+    this.saveStore()
+    const secret = String(this.readAny('remoteSecret') || '')
+    if (this.pushedUrl === url) return
+    this.pushedUrl = url
+    // 先等 Cloudflare 边缘真的挂上再推（否则用户点开是 530 报错页，实测 3~8 秒）。
+    Promise.resolve()
+      .then(() => this.engine?.waitPublic?.())
+      .then((ok) => {
+        this.write('remotePhase', ok === false ? '已就绪（边缘可能还要几秒）' : '已就绪')
+        this.saveStore()
+        return this.pushLink(secret)
+      })
+      .catch(() => {})
+  }
+
+  /** 把 30 天链接经 ntfy 送到手机（复用 RelayClient，不新增通道）。 */
+  async pushLink(secret) {
+    const url = String(this.read('remoteUrl') || '')
+    if (!url || !secret) return { ok: false, error: '还没有可用地址' }
+    if (!this.host || this.host.enabled !== true) return { ok: false, error: '推送通道未配置（先配通行证）' }
+    const link = remoteMessage(url, secret)
+    try {
+      const result = await this.host.relay.push({
+        title: 'DSH 远程访问地址',
+        body: '手机/异地浏览器打开这个链接即可（30 天免登录）：\n' + link,
+        priority: 3,
+        tags: ['globe_with_meridians'],
+      })
+      const ok = result?.status === 200
+      this.write('remotePushResult', ok ? '已推送到手机' : ('推送失败：HTTP ' + String(result?.status)))
+      this.log('远程链接推送 -> HTTP ' + String(result?.status))
+      this.saveStore()
+      return { ok }
+    } catch (error) {
+      this.write('remotePushResult', '推送异常：' + String(error?.message ?? error))
+      this.saveStore()
+      return { ok: false, error: String(error?.message ?? error) }
+    }
+  }
+
+  /** volatile-update 发生在 settings RPC 事务里 ⇒ 挪到下一个宏任务（同 PassProvisioner）。 */
+  schedule() {
+    if (this.scheduled) return
+    this.scheduled = true
+    setTimeout(() => {
+      this.scheduled = false
+      Promise.resolve(this.run()).catch(() => {})
+    }, 0)
+  }
+
+  /** 处理设置行的动作：push / reconnect / rotate。 */
+  async run() {
+    const seq = String(this.read('remoteSeq') || '')
+    const action = String(this.read('remoteAction') || '')
+    if (this.busy || seq === '' || seq === this.lastSeq) return
+    if (action !== 'push' && action !== 'reconnect' && action !== 'rotate') return
+    this.lastSeq = seq
+    this.busy = true
+    try {
+      if (action === 'push') {
+        await this.pushLink(String(this.readAny('remoteSecret') || ''))
+      } else if (action === 'reconnect') {
+        if (this.engine) this.engine.dispose()
+        this.engine = null
+        this.pushedUrl = ''
+        await this.up()
+      } else if (action === 'rotate') {
+        const fresh = newRemoteSecret()
+        this.write('remoteSecret', fresh)
+        this.persist({ remoteSecret: fresh })
+        if (this.engine) this.engine.setSecret(fresh)
+        this.pushedUrl = ''
+        this.write('remotePushResult', '')
+        this.write('remoteStatus', '')
+        this.log('远程访问口令已更换')
+        await this.pushLink(fresh)
+      }
+    } catch (error) {
+      this.write('remoteStatus', String(error?.message ?? error))
+    } finally {
+      this.write('remoteDone', seq)
+      this.busy = false
+      this.saveStore()
+    }
+  }
+
+  /** 开关的权威值：volatile（本次会话刚点过）优先，否则看凭据文件里的 `remoteEnabled`。 */
+  isEnabled() {
+    if (this.read('remoteAccess') === true) return true
+    return String(this.resolved?.remoteEnabled || '') === 'on'
+  }
+
+  /** 开关落盘（凭据文件；`off` 而不是删键——writeCredentialsPatch 只并非空字符串）。 */
+  persistEnabled(on) {
+    this.persist({ remoteEnabled: on ? 'on' : 'off' })
+  }
+
+  start() {
+    this.applyStore()
+    const enabled = this.isEnabled()
+    // 设置行的开关读的是 volatile 的 `remoteAccess`；开机时它总是默认 false，而真值在凭据文件里。
+    // 不把真值写回去，界面就会显示「开启远程访问」而隧道其实正在跑（用户会以为开关坏了）。
+    if (enabled && this.read('remoteAccess') !== true) {
+      // 自己写自己监听：不设这个闸，下面那个 volatile-update 分支会把它当成「用户刚点开启」
+      // 再跑一遍 persistEnabled + up()（会多写一次凭据文件、多启一次引擎）。
+      this.mirroring = true
+      try { this.write('remoteAccess', true) } finally { this.mirroring = false }
+    }
+    const mine = ['remoteSeq', 'remoteAction', 'remoteAccess', 'remoteSecret']
+    this.ctx.on('loader/volatile-update', (paths) => {
+      if (this.mirroring) return
+      const touched = Array.isArray(paths) && paths.some((path) =>
+        Array.isArray(path) && mine.includes(path[0]))
+      if (!touched) return
+      // 开关/口令是「配置」类变化，不需要请求号；直接按新配置重启引擎。
+      const switched = Array.isArray(paths) && paths.some((path) =>
+        Array.isArray(path) && (path[0] === 'remoteAccess' || path[0] === 'remoteSecret'))
+      if (switched) {
+        setTimeout(() => {
+          const on = this.read('remoteAccess') === true
+          this.persistEnabled(on)
+          if (on) { Promise.resolve(this.up()).catch(() => {}) } else if (this.engine) {
+            this.engine.dispose()
+            this.engine = null
+            this.write('remotePhase', '未开启')
+            this.write('remoteUrl', '')
+            this.saveStore()
+          }
+        }, 0)
+        return
+      }
+      this.schedule()
+    })
+    if (!enabled) {
+      this.write('remotePhase', '未开启')
+      this.log('远程访问未开启（设置 → 常规 → 远程访问 里可打开）')
+      return
+    }
+    // 本次 volatile 说开着、但凭据文件里还不是 on ⇒ 补齐。否则「第一次点开启」之后只要没
+    // 走到 volatile-update 那条分支（例如开关值随 config 一起来），下次开机就又变回关着。
+    if (this.read('remoteAccess') === true && String(this.resolved?.remoteEnabled || '') !== 'on') {
+      this.persistEnabled(true)
+    }
+    Promise.resolve(this.up()).catch(() => {})
+  }
+}
+
+/** 远程访问镜像的进程级暂存（同 panelStore 的理由：volatile 写入会热重启 fiber）。 */
+export const REMOTE_STORE_KEY = '__DSHPUSH_REMOTE__'
+
+export function remoteStore() {
+  const g = globalThis
+  if (!g[REMOTE_STORE_KEY]) g[REMOTE_STORE_KEY] = {}
+  return g[REMOTE_STORE_KEY]
+}
+
 export function apply(ctx, config = {}) {
   const { resolved, file } = resolvePluginConfig(config)
   const host = new PushHost(ctx, resolved)
@@ -1417,6 +1773,11 @@ export function apply(ctx, config = {}) {
   new PassProvisioner(ctx, config, resolved, (message) => host.log(message), {
     credentialsPath: file.path,
   }).start()
+  // 远程访问（v0.4.0）：默认关。开着就走「内层改写网关 + cloudflared 快速隧道」，
+  // 把公网域名换成 30 天口令链接；隧道换了域名会自动重推给手机。
+  new RemoteAccessor(ctx, config, resolved, host, (message) => host.log(message), {
+    credentialsPath: file.path,
+  }).start()
 }
 
 export { PushHost, resolveConfig, CONFIG_KEYS }

package/lib/relay.js

@@ -27,8 +27,16 @@ export class RelayClient {
     try { return JSON.parse(text); } catch { return { ok: false, raw: text.slice(0, 200) }; }
   }
 
-  /** Publish a notification to the phone through ntfy (same JSON body shape the app expects). */
-  async push({ title, body, click, priority = 'default', tags = [] }) {
+  /**
+   * Publish a notification to the phone through ntfy (same JSON body shape the app expects).
+   *
+   * `priority` MUST be an integer 1-5. ntfy's JSON body only accepts numbers here: passing the
+   * string 'default' (which is what ntfy's *header* form uses) makes the server answer
+   * 400 `invalid request: request body must be valid JSON` — a message that points nowhere near
+   * the real cause. Callers inside this plugin always pass 1/3/4; the default used to be the
+   * string 'default', which broke every caller that omitted it.
+   */
+  async push({ title, body, click, priority = 3, tags = [] }) {
     const r = await this.fetchImpl(this.base + '/', {
       method: 'POST',
       headers: { 'Content-Type': 'application/json', Authorization: 'Bearer ' + this.ntfyToken },

package/lib/remote.js

@@ -0,0 +1,596 @@
+/**
+ * remote.js — 「不带 Tailscale 也能远程访问」的宿主侧实现（v0.4.0）。
+ *
+ * 目标：让**没装 Tailscale、没有公网 IP** 的人也能在手机/异地浏览器里打开这台机器的 DSH Web，
+ * 而且**不用重新登录/扫码**（凭据约 30 天有效）。
+ *
+ * 链路（全部进程内，不需要用户改 DSH 配置、不需要重启 DSH）：
+ *
+ *   手机 ──https──▶ Cloudflare 快速隧道 ──▶ 本模块的【网关】(127.0.0.1:<port>)
+ *                                              │ ① 自己的 30 天口令门
+ *                                              │ ② 自动注入 DSH 的登录 cookie
+ *                                              │ ③ Host/Origin/Referer 改写成回环
+ *                                              ▼
+ *                                        DSH Web (127.0.0.1:3081)
+ *
+ * 为什么必须有 ① 和 ②（2026-10-28 实测，缺一条都不行）：
+ *   - DSH 有两道栅栏：Host 不在白名单 → 403 `host-not-trusted`；Origin 不在白名单 →
+ *     403 `origin-not-trusted`。所以**光起隧道不行**，Host 和 Origin 都得改写成回环；
+ *   - 但把 Host 改成回环以后，DSH 认的是它自己发的 `dsh-auth-<hash>` cookie，而那个 cookie
+ *     的签发 token 每次 `dsh web` 重启都会换（用户说的「不希望重启后还得再扫码」就是它）。
+ *     所以本模块**在内部**用 web.log 里的 token 自取 cookie 并随请求注入，对外只发自己的
+ *     长期口令 —— 会变的东西被藏在网关后面，用户手里的链接不用变。
+ *
+ * 为什么口令放在**链接里**（`?k=`）而不是只放 cookie：
+ *   快速隧道的域名每次重启都会变（`https://xxx.trycloudflare.com`），而 cookie 是绑域名的，
+ *   换域名就丢。把口令嵌进链接，域名怎么变都能一链直达；同时再种一个 30 天 cookie，
+ *   之后在站内点来点去就不用带参数了。
+ *
+ * @module dsh-push-host/remote
+ */
+import http from 'node:http'
+import { spawn } from 'node:child_process'
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto'
+import { existsSync, mkdirSync, readFileSync, appendFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+/** cookie 名（本模块自己发的，与 DSH 的 dsh-auth-* 互不相干）。 */
+const COOKIE = 'dshpush-remote'
+/** 30 天：用户明确要求「重启后不用再扫码」。 */
+const COOKIE_MAX_AGE = 30 * 24 * 60 * 60
+/** 逐跳头，不能转发。 */
+const HOP_BY_HOP = new Set([
+  'connection', 'keep-alive', 'proxy-authenticate', 'proxy-authorization',
+  'te', 'trailer', 'transfer-encoding', 'upgrade',
+])
+/** 快速隧道地址出现在 cloudflared 日志里的形态。 */
+const TUNNEL_URL_RE = /https:\/\/[a-z0-9][a-z0-9-]*\.trycloudflare\.com/
+/** web.log 里 DSH 打印的访问链接。 */
+const WEB_URL_RE = /dsh web: (https?:\/\/\S+)/
+
+/** 定长比较，避免把口令比较写成可计时侧信道。 */
+function safeEq(a, b) {
+  const x = Buffer.from(String(a))
+  const y = Buffer.from(String(b))
+  if (x.length !== y.length) return false
+  return timingSafeEqual(x, y)
+}
+
+/** 从 cookie 头里取一个键（不引第三方依赖）。 */
+function cookieValue(header, name) {
+  if (typeof header !== 'string') return ''
+  for (const part of header.split(';')) {
+    const at = part.indexOf('=')
+    if (at < 0) continue
+    if (part.slice(0, at).trim() === name) return part.slice(at + 1).trim()
+  }
+  return ''
+}
+
+/** 去掉指定的 cookie 键，其余原样保留（拼回 Cookie 头）。 */
+function dropCookie(header, name) {
+  if (typeof header !== 'string') return ''
+  return header
+    .split(';')
+    .map((part) => part.trim())
+    .filter((part) => part.length > 0 && !part.startsWith(name + '='))
+    .join('; ')
+}
+
+/** 32 字节随机口令，base64url 之后 43 字符（够短可贴，够长不可猜）。 */
+export function newRemoteSecret() {
+  return randomBytes(32).toString('base64url')
+}
+
+/** cookie 里存的不是口令原文，而是它的 HMAC（cookie 泄露也不等于口令泄露）。 */
+export function remoteCookieToken(secret) {
+  return createHmac('sha256', String(secret)).update('dshpush-remote-cookie-v1').digest('base64url')
+}
+
+/**
+ * 远程访问服务：管一条 cloudflared 子进程 + 一个改写网关。
+ *
+ * 生命周期由宿主插件的 fiber 管（unload 时 `dispose()`），失败不致命：
+ * 任何一步起不来都只是 `state.lastError` 有值，推送/作答链路照常。
+ */
+export class RemoteAccess {
+  /**
+   * @param {object} options
+   * @param {(message: string) => void} options.log 日志出口（宿主 logger）。
+   * @param {string} options.secret 长期口令（空 = 未启用）。
+   * @param {string} [options.binPath] cloudflared 可执行文件（空 = 按默认路径找）。
+   * @param {string} [options.webLog] DSH 的 web.log 路径（取 token / 端口）。
+   * @param {number} [options.port] 网关监听端口（0 = 随机挑一个空闲端口）。
+   * @param {(url: string) => void} [options.onUrl] 公网地址变化时回调（用于推送手机）。
+   */
+  constructor(options) {
+    this.log = options.log ?? (() => {})
+    this.secret = String(options.secret ?? '')
+    this.binPath = String(options.binPath ?? '')
+    this.webLog = String(options.webLog ?? join(homedir(), '.dsh', 'web.log'))
+    this.port = Number(options.port ?? 0) || 0
+    this.onUrl = options.onUrl ?? (() => {})
+
+    /** 网关实际端口（start 后才有值）。 */
+    this.listenPort = 0
+    /** 当前公网地址（空 = 还没起来）。 */
+    this.url = ''
+    /** 最近一次错误（'' = 正常）。 */
+    this.lastError = ''
+    this.startedAt = 0
+    this.tunnelStarts = 0
+
+    this.server = null
+    this.child = null
+    this.disposed = false
+    this.restartTimer = null
+    /** DSH 自己的登录 cookie 缓存：`dsh-auth-xxx=v1.…`。 */
+    this.dshCookie = ''
+    this.dshCookieAt = 0
+  }
+
+  /** 给设置行/诊断用的状态快照。 */
+  state() {
+    return {
+      running: this.server !== null,
+      url: this.url,
+      port: this.listenPort,
+      error: this.lastError,
+      since: this.startedAt,
+      restarts: this.tunnelStarts,
+      hasSecret: this.secret.length > 0,
+    }
+  }
+
+  /** 找 cloudflared：显式配置 > ~/.dsh/bin > PATH。 */
+  resolveBin() {
+    if (this.binPath) return this.binPath
+    const local = join(homedir(), '.dsh', 'bin', process.platform === 'win32' ? 'cloudflared.exe' : 'cloudflared')
+    if (existsSync(local)) return local
+    return process.platform === 'win32' ? 'cloudflared.exe' : 'cloudflared'
+  }
+
+  /** 起网关 + 隧道。重复调用安全（已起就返回）。 */
+  async start() {
+    if (this.disposed) return this.state()
+    if (this.secret.length === 0) {
+      this.lastError = '未设置远程口令'
+      return this.state()
+    }
+    if (this.server) return this.state()
+
+    // 先把 DSH 的 cookie 拿到，网关一起来就能直接放行；拿不到不算致命（请求时会再试）。
+    await this.refreshDshCookie().catch(() => {})
+
+    await new Promise((resolve, reject) => {
+      const server = http.createServer((req, res) => {
+        this.handle(req, res).catch((error) => {
+          try { res.writeHead(502, { 'content-type': 'text/plain; charset=utf-8' }) } catch { /* already sent */ }
+          try { res.end('dsh-push remote: ' + String(error?.message ?? error)) } catch { /* gone */ }
+        })
+      })
+      server.on('upgrade', (req, socket, head) => this.handleUpgrade(req, socket, head))
+      server.on('error', (error) => {
+        this.lastError = '网关监听失败：' + String(error?.message ?? error)
+        reject(error)
+      })
+      server.listen(this.port, '127.0.0.1', () => {
+        this.server = server
+        this.listenPort = server.address().port
+        this.startedAt = Date.now()
+        this.lastError = ''
+        this.log('远程网关已监听 127.0.0.1:' + String(this.listenPort))
+        resolve()
+      })
+    })
+
+    this.spawnTunnel()
+    return this.state()
+  }
+
+  /** 停网关 + 隧道（可重复调用）。 */
+  dispose() {
+    this.disposed = true
+    if (this.restartTimer !== null) {
+      clearTimeout(this.restartTimer)
+      this.restartTimer = null
+    }
+    this.killTunnel()
+    if (this.server) {
+      try { this.server.close() } catch { /* already closed */ }
+      this.server = null
+    }
+    this.url = ''
+  }
+
+  /** 换口令：清掉旧 cookie 缓存，网关不用重起。 */
+  setSecret(secret) {
+    this.secret = String(secret ?? '')
+  }
+
+  /**
+   * 等公网地址真的可用再交出去（2026-10-28 实测：cloudflared 打印出域名后，Cloudflare 边缘
+   * 还要 3~8 秒才把这个主机名挂上，这期间访问回 **530**）。如果这时就把链接推给手机，用户点
+   * 进去看到的是 Cloudflare 的报错页，会以为功能坏了。所以推送前先自打一遍：
+   * 只要不是 5xx 就算就绪（401 是口令门，说明链路已通）。
+   * @param {number} [timeoutMs] 最多等多久（默认 60 秒）。
+   * @returns {Promise<boolean>} 是否就绪。
+   */
+  async waitPublic(timeoutMs = 60000) {
+    const url = this.url
+    if (!url) return false
+    const deadline = Date.now() + timeoutMs
+    while (Date.now() < deadline) {
+      if (this.disposed) return false
+      try {
+        const res = await fetch(url + '/__dshpush/status', { redirect: 'manual' })
+        if (res.status < 500) {
+          this.log('公网链路已就绪（status=' + String(res.status) + '）')
+          return true
+        }
+      } catch { /* 还没就绪，继续等 */ }
+      await new Promise((resolve) => setTimeout(resolve, 1500))
+    }
+    this.log('公网链路 ' + String(Math.round(timeoutMs / 1000)) + ' 秒内未就绪（链接可能点开会先看到 Cloudflare 的 530）')
+    return false
+  }
+
+  killTunnel() {
+    if (!this.child) return
+    const child = this.child
+    this.child = null
+    try { child.kill() } catch { /* already gone */ }
+  }
+
+  /** 起 cloudflared 快速隧道，从它自己的日志文件里读出公网地址。 */
+  spawnTunnel() {
+    if (this.disposed) return
+    const bin = this.resolveBin()
+    const logDir = join(homedir(), '.dsh', 'logs')
+    try { mkdirSync(logDir, { recursive: true }) } catch { /* best effort */ }
+    const logFile = join(logDir, 'cloudflared-remote.log')
+    try { appendFileSync(logFile, '\n--- start ' + new Date().toISOString() + ' ---\n') } catch { /* best effort */ }
+
+    // 每次起隧道前把日志读到末尾位置，只认本次新增的行，避免重启后误读上一轮那个已失效的域名。
+    let offset = 0
+    try { offset = readFileSync(logFile, 'utf8').length } catch { offset = 0 }
+    let settled = false
+
+    const args = [
+      'tunnel',
+      '--url', 'http://127.0.0.1:' + String(this.listenPort),
+      '--no-autoupdate',
+      '--logfile', logFile,
+      '--loglevel', 'info',
+      // 指标端口随机，避免和用户自己跑的 cloudflared 撞 20241。
+      '--metrics', '127.0.0.1:0',
+    ]
+    let child
+    try {
+      child = spawn(bin, args, { windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] })
+    } catch (error) {
+      this.lastError = '起不了 cloudflared：' + String(error?.message ?? error)
+      this.log(this.lastError)
+      this.scheduleRestart()
+      return
+    }
+    this.child = child
+    this.tunnelStarts += 1
+    this.log('cloudflared 已启动（第 ' + String(this.tunnelStarts) + ' 次）：' + bin)
+
+    const tail = () => {
+      if (settled) return
+      let text = ''
+      try {
+        text = readFileSync(logFile, 'utf8').slice(offset)
+      } catch {
+        return
+      }
+      const hit = TUNNEL_URL_RE.exec(text)
+      if (!hit) return
+      settled = true
+      this.url = hit[0]
+      this.lastError = ''
+      this.log('公网地址：' + this.url)
+      try { this.onUrl(this.url) } catch { /* caller's problem */ }
+    }
+
+    const timer = setInterval(tail, 400)
+    // 60 秒还没拿到地址就判失败（实测正常 3~6 秒内就有）。
+    const giveUp = setTimeout(() => {
+      if (settled) return
+      settled = true
+      this.lastError = 'cloudflared 60 秒内没有给出公网地址'
+      this.log(this.lastError)
+    }, 60000)
+
+    child.on('exit', (code) => {
+      clearInterval(timer)
+      clearTimeout(giveUp)
+      if (this.child === child) this.child = null
+      if (this.disposed) return
+      this.url = ''
+      if (!settled) this.lastError = 'cloudflared 退出，code=' + String(code)
+      this.log('cloudflared 退出 code=' + String(code) + '，准备重连')
+      this.scheduleRestart()
+    })
+    child.on('error', (error) => {
+      clearInterval(timer)
+      clearTimeout(giveUp)
+      this.lastError = 'cloudflared 启动失败：' + String(error?.message ?? error)
+      this.log(this.lastError)
+      this.scheduleRestart()
+    })
+  }
+
+  /** 隧道断了就退避重连（10s → 20s → 40s，封顶 60s）；地址变了会重新推送。 */
+  scheduleRestart() {
+    if (this.disposed || this.restartTimer !== null) return
+    const delay = Math.min(60000, 10000 * Math.pow(2, Math.min(3, this.tunnelStarts - 1)))
+    this.restartTimer = setTimeout(() => {
+      this.restartTimer = null
+      this.spawnTunnel()
+    }, delay)
+  }
+
+  /** 从 web.log 取当前 token，换成 DSH 自己的登录 cookie。 */
+  async refreshDshCookie() {
+    let text = ''
+    try {
+      text = readFileSync(this.webLog, 'utf8')
+    } catch {
+      this.log('读不到 web.log：' + this.webLog + '（远程访问需要它来取 DSH token）')
+      return ''
+    }
+    const matches = [...text.matchAll(new RegExp(WEB_URL_RE, 'g'))]
+    if (matches.length === 0) return ''
+    const url = matches[matches.length - 1][1]
+    let target
+    try {
+      target = new URL(url)
+    } catch {
+      return ''
+    }
+    // 只在回环上取 cookie：绝不用隧道域名去自打（那会再撞一次 Host/Origin 栅栏）。
+    target.hostname = '127.0.0.1'
+    const res = await fetch(target.toString(), { redirect: 'manual', headers: { 'cache-control': 'no-store' } })
+    const list = typeof res.headers.getSetCookie === 'function' ? res.headers.getSetCookie() : []
+    const auth = list.find((line) => line.startsWith('dsh-auth-'))
+    if (!auth) {
+      this.log('DSH 没有下发 dsh-auth-* cookie（status=' + String(res.status) + '）')
+      return this.dshCookie
+    }
+    this.dshCookie = auth.split(';')[0].trim()
+    this.dshCookieAt = Date.now()
+    this.log('已取得 DSH 登录 cookie（有效期由 DSH 决定，本模块会自动刷新）')
+    return this.dshCookie
+  }
+
+  /** 口令校验：链接里的 ?k= 或 30 天 cookie。 */
+  authorize(req) {
+    let query = ''
+    try {
+      query = new URL(req.url ?? '/', 'http://placeholder').searchParams.get('k') ?? ''
+    } catch {
+      query = ''
+    }
+    if (query.length > 0 && safeEq(query, this.secret)) return { ok: true, viaQuery: true }
+    const cookie = cookieValue(req.headers.cookie, COOKIE)
+    if (cookie.length > 0 && safeEq(cookie, remoteCookieToken(this.secret))) return { ok: true }
+    return { ok: false }
+  }
+
+  /** 登录页（用户手输口令，或从设置行复制链接）。 */
+  loginPage(message = '') {
+    return '<!doctype html><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">' +
+      '<title>DSH 远程访问</title>' +
+      '<style>body{font:16px/1.6 -apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;margin:0;' +
+      'display:flex;min-height:100vh;align-items:center;justify-content:center;background:#f6f7fb;color:#1d2430}' +
+      'form{background:#fff;padding:28px 24px;border-radius:16px;box-shadow:0 8px 30px rgba(20,30,60,.12);width:min(92vw,380px)}' +
+      'h1{font-size:18px;margin:0 0 6px}p{font-size:13px;opacity:.7;margin:0 0 18px}' +
+      'input{width:100%;box-sizing:border-box;padding:12px 14px;border:1px solid #d8dce6;border-radius:10px;font-size:15px}' +
+      'button{margin-top:14px;width:100%;padding:12px;border:0;border-radius:10px;background:#2f6df6;color:#fff;font-size:15px}' +
+      '.err{margin-top:12px;color:#c0392b;font-size:13px}</style>' +
+      '<form method="post" action="/__dshpush/login">' +
+      '<h1>DSH 远程访问</h1><p>请输入这台机器的访问口令（在设置里生成，可用 30 天）。</p>' +
+      '<input name="k" type="password" placeholder="访问口令" autofocus autocomplete="current-password">' +
+      '<button type="submit">进入</button>' +
+      (message ? '<div class="err">' + message + '</div>' : '') +
+      '</form>'
+  }
+
+  /** 网关主处理：口令门 → 注入 DSH cookie → 改写 Host/Origin → 转发。 */
+  async handle(req, res) {
+    const path = (req.url ?? '/').split('?')[0]
+
+    // 登录表单提交（POST /__dshpush/login，body 是 k=…）
+    if (path === '/__dshpush/login' && req.method === 'POST') {
+      const body = await readBody(req, 4096)
+      const typed = new URLSearchParams(body).get('k') ?? ''
+      if (!safeEq(typed, this.secret)) {
+        res.writeHead(401, { 'content-type': 'text/html; charset=utf-8' })
+        res.end(this.loginPage('口令不对。'))
+        return
+      }
+      res.writeHead(303, {
+        location: '/',
+        'set-cookie': COOKIE + '=' + remoteCookieToken(this.secret) + '; Max-Age=' + String(COOKIE_MAX_AGE) +
+          '; Path=/; HttpOnly; SameSite=Lax' + (this.isHttps(req) ? '; Secure' : ''),
+        'cache-control': 'no-store',
+      })
+      res.end()
+      return
+    }
+
+    // 诊断口（要口令）：给设置行/排障看状态，不含任何秘密。
+    if (path === '/__dshpush/status') {
+      if (!this.authorize(req).ok) {
+        res.writeHead(401, { 'content-type': 'application/json' })
+        res.end(JSON.stringify({ ok: false }))
+        return
+      }
+      res.writeHead(200, { 'content-type': 'application/json', 'cache-control': 'no-store' })
+      res.end(JSON.stringify({ ok: true, ...this.state() }))
+      return
+    }
+
+    const auth = this.authorize(req)
+    if (!auth.ok) {
+      res.writeHead(401, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' })
+      res.end(this.loginPage())
+      return
+    }
+    // 链接里带口令进来的：立刻换成 cookie，并把 ?k= 从地址栏抹掉（避免被截图/转发泄露）。
+    if (auth.viaQuery) {
+      const query = new URL(req.url, 'http://placeholder')
+      query.searchParams.delete('k')
+      const rest = query.searchParams.toString()
+      res.writeHead(303, {
+        location: path + (rest ? '?' + rest : ''),
+        'set-cookie': COOKIE + '=' + remoteCookieToken(this.secret) + '; Max-Age=' + String(COOKIE_MAX_AGE) +
+          '; Path=/; HttpOnly; SameSite=Lax' + (this.isHttps(req) ? '; Secure' : ''),
+        'cache-control': 'no-store',
+      })
+      res.end()
+      return
+    }
+
+    this.forward(req, res, (status) => status === 401 || status === 403)
+  }
+
+  /** WebSocket 升级：同样先过口令门，再改写头转发。 */
+  handleUpgrade(req, socket, head) {
+    if (!this.authorize(req).ok) {
+      try { socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n') } catch { /* gone */ }
+      try { socket.destroy() } catch { /* gone */ }
+      return
+    }
+    const headers = this.upstreamHeaders(req)
+    // ★ 2026-10-28 实测：`upstreamHeaders` 会剔掉逐跳头（含 Connection/Upgrade），这对普通请求是
+    // 对的，但升级请求**必须**带这两个头，否则上游回的是普通响应、`upgrade` 事件永不触发——浏览器
+    // 那头表现成「WebSocket 挂着不连，最后 closed before established」。这里补回来。
+    headers.connection = 'Upgrade'
+    headers.upgrade = String(req.headers.upgrade || 'websocket')
+    const up = http.request({
+      host: '127.0.0.1',
+      port: this.targetPort(),
+      method: req.method,
+      path: req.url,
+      headers,
+    })
+    up.on('upgrade', (upRes, upSocket, upHead) => {
+      const lines = ['HTTP/1.1 101 Switching Protocols']
+      for (let i = 0; i < upRes.rawHeaders.length; i += 2) {
+        lines.push(upRes.rawHeaders[i] + ': ' + upRes.rawHeaders[i + 1])
+      }
+      try { socket.write(lines.join('\r\n') + '\r\n\r\n') } catch { /* gone */ }
+      if (upHead && upHead.length > 0) socket.write(upHead)
+      if (head && head.length > 0) upSocket.write(head)
+      upSocket.pipe(socket)
+      socket.pipe(upSocket)
+    })
+    up.on('error', () => {
+      try { socket.destroy() } catch { /* gone */ }
+    })
+    up.end()
+  }
+
+  /** 从 web.log 现取目标端口（DSH 可能换端口，每次现读更稳）。 */
+  targetPort() {
+    try {
+      const text = readFileSync(this.webLog, 'utf8')
+      const matches = [...text.matchAll(new RegExp(WEB_URL_RE, 'g'))]
+      if (matches.length > 0) return Number(new URL(matches[matches.length - 1][1]).port) || 3081
+    } catch { /* fall through */ }
+    return 3081
+  }
+
+  isHttps(req) {
+    const proto = String(req.headers['x-forwarded-proto'] ?? '').toLowerCase()
+    if (proto === 'https') return true
+    const host = String(req.headers.host ?? '')
+    return !/^(127\.0\.0\.1|localhost|\[::1\])(:\d+)?$/.test(host) && !host.startsWith('127.0.0.1:')
+  }
+
+  /** 转发用的头：抹掉逐跳头、抹掉自己的 cookie、注入 DSH cookie、改回环。 */
+  upstreamHeaders(req) {
+    const headers = {}
+    for (const [key, value] of Object.entries(req.headers)) {
+      if (HOP_BY_HOP.has(key.toLowerCase())) continue
+      headers[key] = value
+    }
+    const target = '127.0.0.1:' + String(this.targetPort())
+    headers.host = target
+    if (headers.origin) headers.origin = 'http://' + target
+    if (headers.referer) {
+      try {
+        const ref = new URL(headers.referer)
+        headers.referer = 'http://' + target + ref.pathname + ref.search
+      } catch {
+        headers.referer = 'http://' + target + '/'
+      }
+    }
+    const kept = dropCookie(req.headers.cookie, COOKIE)
+    headers.cookie = [kept, this.dshCookie].filter((part) => part.length > 0).join('; ')
+    if (headers.cookie.length === 0) delete headers.cookie
+    return headers
+  }
+
+  /**
+   * 真正转发。`isRetry` 时先刷一次 DSH cookie（token 可能刚换过）再重发一次。
+   */
+  forward(req, res, retryOn, isRetry = false) {
+    const up = http.request({
+      host: '127.0.0.1',
+      port: this.targetPort(),
+      method: req.method,
+      path: req.url,
+      headers: this.upstreamHeaders(req),
+    }, (upRes) => {
+      const status = upRes.statusCode ?? 502
+      if (!isRetry && retryOn(status)) {
+        upRes.resume()
+        this.refreshDshCookie()
+          .then(() => this.forward(req, res, retryOn, true))
+          .catch(() => {
+            try { res.writeHead(502, { 'content-type': 'text/plain; charset=utf-8' }) } catch { /* sent */ }
+            try { res.end('dsh-push remote: DSH 认证失败且刷新 cookie 也失败') } catch { /* gone */ }
+          })
+        return
+      }
+      const headers = {}
+      for (const [key, value] of Object.entries(upRes.headers)) {
+        if (HOP_BY_HOP.has(key.toLowerCase())) continue
+        headers[key] = value
+      }
+      try { res.writeHead(status, headers) } catch { /* headers already sent */ }
+      upRes.pipe(res)
+    })
+    up.on('error', (error) => {
+      try { res.writeHead(502, { 'content-type': 'text/plain; charset=utf-8' }) } catch { /* sent */ }
+      try { res.end('dsh-push remote: ' + String(error?.message ?? error)) } catch { /* gone */ }
+    })
+    req.pipe(up)
+  }
+}
+
+/** 读一小段请求体（登录表单用），超过上限直接截断。 */
+function readBody(req, limit) {
+  return new Promise((resolve) => {
+    let data = ''
+    req.setEncoding('utf8')
+    req.on('data', (chunk) => {
+      if (data.length < limit) data += chunk
+    })
+    req.on('end', () => resolve(data.slice(0, limit)))
+    req.on('error', () => resolve(data.slice(0, limit)))
+  })
+}
+
+/** 拼一条给手机看的文本：地址 + 30 天口令链接。 */
+export function remoteMessage(url, secret) {
+  if (!url) return ''
+  const link = url + '/?k=' + encodeURIComponent(secret)
+  return link
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-push-host",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "DSH host-side phone push: question events to ntfy + in-process answering via relay polling (replaces the external notifier + answer bridge)",
   "keywords": [
     "dsh",
@@ -30,6 +30,7 @@
     "./pairing": "./lib/pairing.mjs",
     "./pairing-lib": "./lib/pairing-lib.mjs",
     "./relay": "./lib/relay.js",
+    "./remote": "./lib/remote.js",
     "./cordis.patch.yml": "./cordis.patch.yml",
     "./package.json": "./package.json"
   },