rdsh-gateway 0.8.2 → 0.8.4

package/dist/config.d.ts

@@ -43,6 +43,13 @@ export interface GatewayConfig {
 export interface DshUiCompat {
     /** E2EE 激活（或宿主启用）时 patch JS；false = 保持 DSH 原样（共享 host/敏感场景） */
     trustE2EEAsLoopback?: boolean;
+    /**
+     * LAN / 已配对会话是否同样视同 loopback（默认 true）。
+     * 背景：DSH 的设置与"持久化凭据"界面只对 loopback 开放，而 LAN 访问的 hostname 是局域网 IP，
+     * 不满足 DSH 的 loopback 判定 ⇒ 不打开时 LAN 用户无法在界面里输入 API key。
+     * false = 严格模式（LAN 用户需自行在 `~/.dsh/.credentials.yaml` 配置）。
+     */
+    trustPairedAsLoopback?: boolean;
 }
 export declare const DEFAULT_HOST_CONFIG_PATH: string;
 /** 解析配置文件路径（--config > $RDSH_CONFIG > 默认 host.json）。 */

package/dist/config.js

@@ -21,7 +21,7 @@ const DEFAULTS = {
     behindProxy: false,
     allowFrom: [],
     auth: DEFAULT_AUTH,
-    dshUiCompat: { trustE2EEAsLoopback: true },
+    dshUiCompat: { trustE2EEAsLoopback: true, trustPairedAsLoopback: true },
     gateway: { accessCode: null },
 };
 /** 解析配置文件路径（--config > $RDSH_CONFIG > 默认 host.json）。 */
@@ -182,12 +182,20 @@ export function normalizeConfig(raw, source = "config") {
             throw new Error(`${source}: "dshUiCompat" must be an object`);
         }
         const compat = cfg.dshUiCompat;
+        const compatOut = {};
         if (compat.trustE2EEAsLoopback !== undefined) {
             if (typeof compat.trustE2EEAsLoopback !== "boolean") {
                 throw new Error(`${source}: "dshUiCompat.trustE2EEAsLoopback" must be boolean`);
             }
-            out.dshUiCompat = { trustE2EEAsLoopback: compat.trustE2EEAsLoopback };
+            compatOut.trustE2EEAsLoopback = compat.trustE2EEAsLoopback;
         }
+        if (compat.trustPairedAsLoopback !== undefined) {
+            if (typeof compat.trustPairedAsLoopback !== "boolean") {
+                throw new Error(`${source}: "dshUiCompat.trustPairedAsLoopback" must be boolean`);
+            }
+            compatOut.trustPairedAsLoopback = compat.trustPairedAsLoopback;
+        }
+        out.dshUiCompat = compatOut;
     }
     // ---- gateway（访问口令；缺省 accessCode null = gate off）----
     if (cfg.gateway !== undefined) {

package/dist/http-encoding.d.ts

@@ -0,0 +1,6 @@
+/** 取首个 content-encoding（小写；identity/空 → ""）。 */
+export declare function firstEncoding(value: string | string[] | undefined): string;
+/** 解码为明文；不支持/损坏 → null。 */
+export declare function decodeBody(body: Buffer, encoding: string): Buffer | null;
+/** 按原编码重新压缩；identity → 原样；不支持/失败 → null。 */
+export declare function encodeBody(body: Buffer, encoding: string): Buffer | null;

package/dist/http-encoding.js

@@ -0,0 +1,51 @@
+/**
+ * http-encoding.ts — 响应体 `content-encoding` 的解码/重编码（供 loopback JS 补丁使用）。
+ *
+ * 背景（2026-09-14 实测事故）：dsh 在客户端声明 `accept-encoding` 时会对 JS **gzip 压缩**，
+ * 而 `patchLoopbackJs()` 是在字节里做字面量替换 —— 在压缩体上必然 miss（fail-open 静默失效），
+ * 导致前端 `isLoopback` 判定没被改写、DSH 设置页/API key 界面不可用。
+ *
+ * 约定：只处理 identity/gzip/deflate/br；**未知或多重编码返回 null**，调用方 fail-open（原样透传）。
+ */
+import { brotliCompressSync, brotliDecompressSync, deflateSync, gunzipSync, gzipSync, inflateSync } from "node:zlib";
+/** 取首个 content-encoding（小写；identity/空 → ""）。 */
+export function firstEncoding(value) {
+    const raw = Array.isArray(value) ? value[0] : value;
+    const enc = (raw ?? "").split(",")[0]?.trim().toLowerCase() ?? "";
+    return enc === "identity" ? "" : enc;
+}
+/** 解码为明文；不支持/损坏 → null。 */
+export function decodeBody(body, encoding) {
+    try {
+        if (encoding === "")
+            return body;
+        if (encoding === "gzip")
+            return gunzipSync(body);
+        if (encoding === "deflate")
+            return inflateSync(body);
+        if (encoding === "br")
+            return brotliDecompressSync(body);
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/** 按原编码重新压缩；identity → 原样；不支持/失败 → null。 */
+export function encodeBody(body, encoding) {
+    try {
+        if (encoding === "")
+            return body;
+        if (encoding === "gzip")
+            return gzipSync(body);
+        if (encoding === "deflate")
+            return deflateSync(body);
+        if (encoding === "br")
+            return brotliCompressSync(body);
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=http-encoding.js.map

package/dist/join.d.ts

@@ -62,6 +62,16 @@ export interface StartJoinOptions {
     name?: string;
     /** 宿主代持的 dsh 浏览器会话 cookie（`dsh-auth-*`，0.1.2+）；有值时注入隧道→本地转发 */
     dshAuthCookieHeader?: string | null;
+    /**
+     * 心跳间隔（缺省 30s，协议 PROTOCOL.md「心跳与重连」）。
+     * 测试可注入毫秒级小值以快速验证超时判定。
+     */
+    heartbeatMs?: number;
+    /**
+     * 发出 PING 后等待对端任何帧的上限（缺省 10s）；超时即判连接已死并主动断开。
+     * 测试可注入小值。
+     */
+    pongTimeoutMs?: number;
 }
 /** 可停止的 join 隧道句柄。 */
 export interface JoinHandle {
@@ -81,6 +91,18 @@ export declare function registerJoin(opts: JoinOptions): Promise<RegisterOutcome
  * 启动 join 隧道（no-spawn）：转发到外部 `opts.target`，不 spawn dsh、不 process.exit。
  * 获取 pid 锁（opts.role）；返回 `JoinHandle`，`stop()` 干净停止（关 WS/清 heartbeat/释放锁）。
  */
+/**
+ * 上游失败分类。
+ *
+ * 旧实现把所有 `up.on("error")` 都报成 `UPSTREAM_UNREACHABLE: dsh not reachable`，
+ * 于是"dsh 已接受连接、但在读请求体阶段就断开（常见于 401/413）"被伪装成部署故障，
+ * 掩盖真实原因（2026-09-14 实测：上传大文件得到 502 "dsh not reachable"，与事实不符）。
+ */
+export declare function classifyUpstreamFailure(code: string | undefined, responded: boolean, message?: string): {
+    kind: "error" | "close";
+    code: string;
+    message: string;
+};
 /** JS 响应判定（content-type 含 javascript）。 */
 export declare function isJsContentType(headers: IncomingHttpHeaders): boolean;
 /**
@@ -89,6 +111,13 @@ export declare function isJsContentType(headers: IncomingHttpHeaders): boolean;
  * fail-open：未命中目标串 → 返回 null，调用方原样透传（DSH 升级不炸）。
  */
 export declare function patchLoopbackJs(body: Buffer): Buffer | null;
+/**
+ * E2EE 包装的固定开销：内层帧 15 B 头（MAGIC4+ver1+flags1+type1+streamId4+len4）+ AEAD
+ * nonce 12 B + GCM tag 16 B = **43 B**。WS 消息判界必须预留它，否则"明文 ≤16 MiB"的 WS 消息
+ * 经 E2EE 加密后刚好超出隧道上限，`encodeFrame` 在加密发送器里抛 `ProtocolError` 打死 host
+ *（2026-09-14 第三审发现的 28 B 窗口，加上内层帧头实为 43 B）。
+ */
+export declare const E2EE_FRAME_OVERHEAD: number;
 export declare function startJoin(opts: StartJoinOptions): JoinHandle;
 /** `rdsh host serve`（join 模式）的 CLI 封装：spawn dsh + 信号退出 + startJoin(role:cli)。 */
 export declare function join(opts: JoinOptions): Promise<void>;

package/dist/join.js

@@ -13,10 +13,11 @@ import { request as httpRequest } from "node:http";
 import { request as httpsRequest } from "node:https";
 import { hostname as osHostname } from "node:os";
 import { WebSocket } from "ws";
-import { FrameParser, FRAME_TYPE, encodeFrame, jsonPayload, parseJsonPayload, FLAG_E2E } from "rdsh-tunnel";
+import { FrameParser, FRAME_TYPE, encodeFrame, jsonPayload, parseJsonPayload, FLAG_E2E, MAX_PAYLOAD_LENGTH } from "rdsh-tunnel";
 import { findDsh, spawnDsh, exchangeDshSessionCookie, detectDshVersion, dshVersionWarning } from "./spawn-dsh.js";
 import { rewriteHeadersForDsh } from "./proxy.js";
 import { clearPersistedToken, persistToken, readPersistedToken } from "./token-store.js";
+import { decodeBody, encodeBody, firstEncoding } from "./http-encoding.js";
 import { acquireJoinLock, releaseJoinLock } from "./lock.js";
 import { responderHandshake, Aead } from "./e2ee.js";
 import { loadOrCreateE2eeKeyPair } from "./e2ee-key-store.js";
@@ -41,6 +42,8 @@ export async function detectInsecure(hubUrl) {
     }
 }
 const HEARTBEAT_MS = 30_000;
+/** 发出 PING 后等待对端任何帧的上限：超时即判连接已死并主动断开（协议 PROTOCOL.md）。 */
+const PONG_TIMEOUT_MS = 10_000;
 const RECONNECT_BASE_MS = 1_000;
 const RECONNECT_MAX_MS = 60_000;
 /** hub HTTP 调用（node:https 支持自签跳过校验 —— undici fetch 不受 NODE_TLS_REJECT_UNAUTHORIZED 影响）。 */
@@ -129,6 +132,25 @@ async function register(hubUrl, joinToken, name, insecure, e2eePublicKey) {
  * 启动 join 隧道（no-spawn）：转发到外部 `opts.target`，不 spawn dsh、不 process.exit。
  * 获取 pid 锁（opts.role）；返回 `JoinHandle`，`stop()` 干净停止（关 WS/清 heartbeat/释放锁）。
  */
+/**
+ * 上游失败分类。
+ *
+ * 旧实现把所有 `up.on("error")` 都报成 `UPSTREAM_UNREACHABLE: dsh not reachable`，
+ * 于是"dsh 已接受连接、但在读请求体阶段就断开（常见于 401/413）"被伪装成部署故障，
+ * 掩盖真实原因（2026-09-14 实测：上传大文件得到 502 "dsh not reachable"，与事实不符）。
+ */
+export function classifyUpstreamFailure(code, responded, message) {
+    const reason = code !== undefined && code !== "" ? code : (message ?? "unknown");
+    if (responded) {
+        // 客户端已拿到状态头/部分 body：此时只能发 CLOSE 表示"响应体被截断"
+        return { kind: "close", code: "UPSTREAM_ABORTED", message: `upstream aborted mid-response (${reason})` };
+    }
+    const unreachable = code === "ECONNREFUSED" || code === "ENOTFOUND" || code === "EAI_AGAIN" || code === "EHOSTUNREACH" || code === "ENETUNREACH";
+    if (unreachable) {
+        return { kind: "error", code: "UPSTREAM_UNREACHABLE", message: `dsh not reachable (${reason})` };
+    }
+    return { kind: "error", code: "UPSTREAM_ABORTED", message: `upstream closed before responding (${reason})` };
+}
 /** JS 响应判定（content-type 含 javascript）。 */
 export function isJsContentType(headers) {
     const ct = headers["content-type"];
@@ -181,10 +203,42 @@ function gateChallengeHtml(hostName, actionPath, error, acceptLanguage) {
         `<button type="submit" style="width:100%;margin-top:12px;height:38px;border:none;border-radius:8px;background:#2563eb;color:#fff;font-size:14px;cursor:pointer">${t.submit}</button>` +
         `</form>${errHtml}</div></body></html>`);
 }
+/** http 响应体的分片发送上限：单帧超过隧道 16 MiB 会让 `encodeFrame` 抛 `ProtocolError`，
+ *  抛点在响应回调里未捕获 ⇒ 打死 host（gateway）进程（P1，2026-09-14 复审发现）。1 MiB 远低于上限，
+ *  且给 E2EE 方向（密文 = 内层帧 + 28 B nonce/tag）也留足余量。 */
+const DATA_FRAME_CHUNK = 1 << 20;
+/**
+ * E2EE 包装的固定开销：内层帧 15 B 头（MAGIC4+ver1+flags1+type1+streamId4+len4）+ AEAD
+ * nonce 12 B + GCM tag 16 B = **43 B**。WS 消息判界必须预留它，否则"明文 ≤16 MiB"的 WS 消息
+ * 经 E2EE 加密后刚好超出隧道上限，`encodeFrame` 在加密发送器里抛 `ProtocolError` 打死 host
+ *（2026-09-14 第三审发现的 28 B 窗口，加上内层帧头实为 43 B）。
+ */
+export const E2EE_FRAME_OVERHEAD = 15 + 12 + 16;
+/** 按 DATA_FRAME_CHUNK 分片发送响应体（多 DATA 帧在 hub/浏览器侧天然拼回同一个 body）。 */
+function sendChunkedBody(send, streamId, body) {
+    if (body.length === 0)
+        return;
+    for (let off = 0; off < body.length; off += DATA_FRAME_CHUNK) {
+        send(encodeFrame(FRAME_TYPE.DATA, streamId, body.subarray(off, Math.min(off + DATA_FRAME_CHUNK, body.length))));
+    }
+}
+/**
+ * WS 消息转发：**一条消息 = 一帧，不能分片**（分片会破坏 host 侧的消息边界）。
+ * 超限（>16 MiB − E2EE_FRAME_OVERHEAD）时发 CLOSE(1009) 给客户端并返回 false，由调用方关掉上游
+ * —— 绝不让 `encodeFrame` 的 `ProtocolError` 逃逸到 ws 回调打死 host 进程。
+ */
+function sendWsData(send, streamId, buf) {
+    if (buf.length > MAX_PAYLOAD_LENGTH - E2EE_FRAME_OVERHEAD) {
+        send(encodeFrame(FRAME_TYPE.CLOSE, streamId, jsonPayload({ code: 1009, message: "upstream ws message too large" })));
+        return false;
+    }
+    send(encodeFrame(FRAME_TYPE.DATA, streamId, buf));
+    return true;
+}
 /** 发送合成的 HTTP 响应帧（gateway 不触达 dsh）。 */
 function sendSyntheticHttp(send, streamId, status, headers, body) {
     send(encodeFrame(FRAME_TYPE.OPEN, streamId, jsonPayload({ kind: "http", status, reason: undefined, headers })));
-    send(encodeFrame(FRAME_TYPE.DATA, streamId, body));
+    sendChunkedBody(send, streamId, body);
     send(encodeFrame(FRAME_TYPE.CLOSE, streamId, jsonPayload({ code: 0 })));
 }
 export function startJoin(opts) {
@@ -212,7 +266,13 @@ export function startJoin(opts) {
     let shuttingDown = false;
     let reconnectDelay = RECONNECT_BASE_MS;
     let heartbeat;
+    /** 发出 PING 后的存活死线：期间收到**任何**入站帧即撤销（PROTOCOL.md 心跳与重连）。 */
+    let livenessDeadline;
     let currentClient;
+    const heartbeatMs = opts.heartbeatMs ?? HEARTBEAT_MS;
+    const pongTimeoutMs = opts.pongTimeoutMs ?? PONG_TIMEOUT_MS;
+    /** 日志用人类可读单位：生产 30000ms → "30s"；测试注入的毫秒值原样显示。 */
+    const heartbeatLabel = heartbeatMs % 1000 === 0 ? `${heartbeatMs / 1000}s` : `${heartbeatMs}ms`;
     /** 发送一个隧道帧（走当前隧道 WS；flags 由调用方在 encodeFrame 时给定）。 */
     function sendTunnelFrame(frame) {
         if (currentClient !== undefined && currentClient.readyState === currentClient.OPEN) {
@@ -225,6 +285,8 @@ export function startJoin(opts) {
         const wsStreams = new Map();
         // gate 未过、等待 code 提交的 http 流（OPEN 后缓冲 DATA，CLOSE 时校验）
         const gatedHttp = new Map();
+        /** 已报告过"loopback 补丁未命中"的路径（每个路径只报一次，避免日志刷屏）。 */
+        const patchMissReported = new Set();
         /** 从转发头里取 rdsh_gate cookie（hub D12 白名单透传）。 */
         function gateCookie(headers) {
             const ck = headers["cookie"];
@@ -318,7 +380,16 @@ export function startJoin(opts) {
                     : Buffer.isBuffer(data)
                         ? data
                         : Buffer.from(data);
-                send(encodeFrame(FRAME_TYPE.DATA, streamId, buf));
+                if (!sendWsData(send, streamId, buf)) {
+                    // 超限：已发 CLOSE(1009) 给客户端，这里关掉上游 dsh 连接，绝不让异常逃逸
+                    console.error(`[join] upstream ws message too large (${buf.length}B), closing stream ${streamId}`);
+                    try {
+                        upstream.close(1009, "message too big");
+                    }
+                    catch {
+                        /* 已关闭 */
+                    }
+                }
             });
             const cleanup = () => {
                 wsStreams.delete(streamId);
@@ -377,6 +448,8 @@ export function startJoin(opts) {
                 return;
             }
             const streamId = frame.streamId;
+            /** 响应头是否已发给客户端（决定失败时能回 ERROR 还是只能用 CLOSE 表示截断）。 */
+            let responded = false;
             const up = httpRequest({
                 host: opts.target.host,
                 port: opts.target.port,
@@ -384,22 +457,17 @@ export function startJoin(opts) {
                 method,
                 headers: rewriteHeadersForDsh(headers, opts.target, dshAuthCookie),
             }, (upRes) => {
-                send(encodeFrame(FRAME_TYPE.OPEN, streamId, jsonPayload({
-                    kind: "http",
-                    status: upRes.statusCode ?? 502,
-                    reason: upRes.statusMessage,
-                    headers: normalizeRespHeaders(upRes.headers),
-                })));
-                if (dio?.jsPatch?.() === true && isJsContentType(upRes.headers)) {
-                    // 最小 patch：E2EE 流上的 JS 响应，把前端 isLoopback 判定替换为 true
-                    // （fail-open：未命中 → 原样透传；DSH 升级不炸）
-                    const chunks = [];
-                    upRes.on("data", (chunk) => chunks.push(chunk));
+                responded = true;
+                const status = upRes.statusCode ?? 502;
+                const baseHeaders = normalizeRespHeaders(upRes.headers);
+                const wantsPatch = dio?.jsPatch?.() === true && isJsContentType(upRes.headers);
+                // 非 JS / 未开补丁：保持原流式路径（OPEN 立即发，body 边到边发）
+                if (!wantsPatch) {
+                    send(encodeFrame(FRAME_TYPE.OPEN, streamId, jsonPayload({ kind: "http", status, reason: upRes.statusMessage, headers: baseHeaders })));
+                    upRes.on("data", (chunk) => {
+                        sendChunkedBody(send, streamId, chunk);
+                    });
                     upRes.on("end", () => {
-                        const body = Buffer.concat(chunks);
-                        const patched = patchLoopbackJs(body);
-                        // fail-open：未命中也必须原样发 body（否则空响应白屏）
-                        send(encodeFrame(FRAME_TYPE.DATA, streamId, patched !== null ? patched : body));
                         send(encodeFrame(FRAME_TYPE.CLOSE, streamId, jsonPayload({ code: 0 })));
                         httpStreams.delete(streamId);
                     });
@@ -409,10 +477,45 @@ export function startJoin(opts) {
                     });
                     return;
                 }
-                upRes.on("data", (chunk) => {
-                    send(encodeFrame(FRAME_TYPE.DATA, streamId, chunk));
-                });
+                // JS + 补丁：**必须先缓冲/处理再发 OPEN** —— patch 与"按原编码重压"都会改变 body 长度，
+                // 而 OPEN 帧里的 content-length 必须与实际字节一致（否则浏览器截断或一直等）。
+                // dsh 会按 accept-encoding 压缩 JS（gzip 等），所以这里必须先解码再补丁、再按原编码重压。
+                const chunks = [];
+                upRes.on("data", (chunk) => chunks.push(chunk));
                 upRes.on("end", () => {
+                    const raw = Buffer.concat(chunks);
+                    const encoding = firstEncoding(upRes.headers["content-encoding"]);
+                    const decoded = decodeBody(raw, encoding);
+                    let body = raw;
+                    let outHeaders = baseHeaders;
+                    let hit = false;
+                    if (decoded !== null) {
+                        const patched = patchLoopbackJs(decoded);
+                        const recoded = patched === null ? null : encodeBody(patched, encoding);
+                        if (recoded !== null) {
+                            body = recoded;
+                            hit = true;
+                            outHeaders = { ...baseHeaders, "content-length": String(body.length) };
+                            delete outHeaders["transfer-encoding"];
+                            // 不能沿用上游的 `immutable` / 长 max-age：补丁改了 body 但 URL(rev) 由上游内容决定，
+                            // 浏览器会把"旧的未补丁 bundle"缓存很久 ⇒ 修复无法生效（2026-09-14 实测踩到）。
+                            outHeaders["cache-control"] = "public, max-age=300";
+                        }
+                    }
+                    // 未命中必须留痕（每个路径一次）：fail-open 是刻意设计，但"补丁从未生效"不能静默
+                    //（2026-09-14 gzip 事故正是因为没有这条日志而排查了很久）
+                    if (!hit) {
+                        const key = (path.split("?")[0] ?? path).slice(0, 120);
+                        if (!patchMissReported.has(key)) {
+                            patchMissReported.add(key);
+                            console.log(`[patch] miss: ${key} (${raw.length}B, content-encoding=${encoding === "" ? "identity" : encoding})`);
+                        }
+                    }
+                    else if (process.env.RDSH_DEBUG_PATCH === "1") {
+                        console.log(`[patch] hit: ${path.slice(0, 120)} (${raw.length}B → ${body.length}B, ${encoding === "" ? "identity" : encoding})`);
+                    }
+                    send(encodeFrame(FRAME_TYPE.OPEN, streamId, jsonPayload({ kind: "http", status, reason: upRes.statusMessage, headers: outHeaders })));
+                    sendChunkedBody(send, streamId, body);
                     send(encodeFrame(FRAME_TYPE.CLOSE, streamId, jsonPayload({ code: 0 })));
                     httpStreams.delete(streamId);
                 });
@@ -421,8 +524,10 @@ export function startJoin(opts) {
                     httpStreams.delete(streamId);
                 });
             });
-            up.on("error", () => {
-                send(encodeFrame(FRAME_TYPE.ERROR, streamId, jsonPayload({ code: "UPSTREAM_UNREACHABLE", message: "dsh not reachable" })));
+            up.on("error", (err) => {
+                const outcome = classifyUpstreamFailure(err.code, responded, err.message);
+                const type = outcome.kind === "close" ? FRAME_TYPE.CLOSE : FRAME_TYPE.ERROR;
+                send(encodeFrame(type, streamId, jsonPayload({ code: outcome.code, message: outcome.message })));
                 httpStreams.delete(streamId);
             });
             httpStreams.set(streamId, { up });
@@ -503,10 +608,25 @@ export function startJoin(opts) {
     function startRawStream(streamId) {
         const inner = makeInnerDispatcher((frame) => {
             const raw = rawStreams.get(streamId);
-            if (raw?.encryptor !== null && raw?.encryptor !== undefined) {
+            if (raw?.encryptor === null || raw?.encryptor === undefined)
+                return;
+            try {
                 const ct = raw.encryptor.encrypt(frame, Buffer.alloc(0));
+                if (ct.length > MAX_PAYLOAD_LENGTH) {
+                    // 结构兜底：内层帧经 E2EE 包装（+43 B）后超限。绝不能让 encodeFrame 的 ProtocolError
+                    // 逃逸；给该内层流回一个 ERROR（小帧，加密后必然放得下），消费方据此干净报错。
+                    const innerId = frame.length >= 11 ? frame.readUInt32BE(7) : 0;
+                    const errCt = raw.encryptor.encrypt(encodeFrame(FRAME_TYPE.ERROR, innerId, jsonPayload({ code: "FRAME_TOO_LARGE", message: "e2ee frame too large" })), Buffer.alloc(0));
+                    console.error(`[join] e2ee frame too large (${ct.length}B) for inner stream ${innerId}`);
+                    sendTunnelFrame(encodeFrame(FRAME_TYPE.DATA, streamId, errCt, FLAG_E2E));
+                    return;
+                }
                 sendTunnelFrame(encodeFrame(FRAME_TYPE.DATA, streamId, ct, FLAG_E2E));
             }
+            catch (err) {
+                // 最后一道：任何加密/封帧异常只记录，绝不重抛打死 host
+                console.error(`[join] e2ee send failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
         }, { jsPatch: () => uiCompat.trustE2EEAsLoopback });
         rawStreams.set(streamId, {
             handshakeBuf: Buffer.alloc(0),
@@ -597,6 +717,10 @@ export function startJoin(opts) {
             clearInterval(heartbeat);
             heartbeat = undefined;
         }
+        if (livenessDeadline !== undefined) {
+            clearTimeout(livenessDeadline);
+            livenessDeadline = undefined;
+        }
         plainDispatcher.cleanup();
         for (const raw of rawStreams.values())
             raw.inner.cleanup();
@@ -626,18 +750,38 @@ export function startJoin(opts) {
         client.on("open", () => {
             reconnectDelay = RECONNECT_BASE_MS;
             setState("connected");
-            log("info", "tunnel established (heartbeat 30s)");
+            log("info", `tunnel established (heartbeat ${heartbeatLabel})`);
             if (heartbeat !== undefined)
                 clearInterval(heartbeat);
             heartbeat = setInterval(() => {
                 if (client.readyState === client.OPEN) {
                     client.send(encodeFrame(FRAME_TYPE.PING, 0, jsonPayload({ ts: Date.now() })));
+                    // 发出 PING 后武装死线：pongTimeoutMs 内收到任何入站帧即撤销（下方 message 处理）。
+                    // 只在**没有未决死线**时武装——上一发 PING 未获回应时原死线继续计时，不重置。
+                    if (livenessDeadline === undefined) {
+                        livenessDeadline = setTimeout(() => {
+                            livenessDeadline = undefined;
+                            log("info", `heartbeat timeout — no frame from hub within ${pongTimeoutMs}ms; reconnecting`);
+                            try {
+                                client.terminate();
+                            }
+                            catch {
+                                /* 已关闭 */
+                            }
+                        }, pongTimeoutMs);
+                        livenessDeadline.unref?.();
+                    }
                 }
-            }, HEARTBEAT_MS);
+            }, heartbeatMs);
         });
         client.on("message", (data, isBinary) => {
             if (!isBinary)
                 return;
+            // 任何入站帧都是存活证据 → 撤销死线（不限于 PONG）
+            if (livenessDeadline !== undefined) {
+                clearTimeout(livenessDeadline);
+                livenessDeadline = undefined;
+            }
             const chunk = Array.isArray(data)
                 ? Buffer.concat(data)
                 : Buffer.isBuffer(data)

package/dist/proxy.d.ts

@@ -16,6 +16,12 @@ export interface ForwardOptions {
      * 提供时合并进每个转发/升级请求的 cookie 头，穿透 dsh 0.1.2 认证层。
      */
     authCookie?: string | null;
+    /**
+     * JS 响应补丁（LAN 路径；隧道路径见 `join.ts` 的 `patchLoopbackJs`）。
+     * 命中 content-type 含 `javascript` 时缓冲后调用；返回 `null` = 原样透传（fail-open）。
+     * 用途：把 DSH 前端的 `isLoopback` 判定替换为 `true` —— DSH 的设置/凭据界面只对 loopback 开放。
+     */
+    jsPatch?: (body: Buffer) => Buffer | null;
 }
 /**
  * 重写转发头以通过 DSH 围栏（isTrustedApiRequest 要求 Host/Origin 一致且为 loopback）。

package/dist/proxy.js

@@ -6,6 +6,7 @@
  */
 import { request } from "node:http";
 import { WebSocket, WebSocketServer } from "ws";
+import { decodeBody, encodeBody, firstEncoding } from "./http-encoding.js";
 /**
  * 重写转发头以通过 DSH 围栏（isTrustedApiRequest 要求 Host/Origin 一致且为 loopback）。
  * - Host → 127.0.0.1:<port>（M1 事实：DSH 只信任 loopback/trusted Host）
@@ -80,6 +81,37 @@ export function forwardHttp(req, res, target, opts) {
             });
             return;
         }
+        const canPatchJs = opts?.jsPatch !== undefined && typeof contentType === "string" && /javascript/i.test(contentType);
+        if (canPatchJs) {
+            // JS bundle 需缓冲后才能替换目标串；先按 content-encoding 解码（dsh 会 gzip JS），
+            // 补丁后按原编码重压（fail-open：未命中/不支持编码 → 原字节原头透传）
+            void (async () => {
+                const chunks = [];
+                for await (const chunk of upstreamRes)
+                    chunks.push(chunk);
+                const raw = Buffer.concat(chunks);
+                const encoding = firstEncoding(upstreamRes.headers["content-encoding"]);
+                const decoded = decodeBody(raw, encoding);
+                const patched = decoded === null ? null : opts.jsPatch(decoded);
+                const recoded = patched === null ? null : encodeBody(patched, encoding);
+                const outBody = recoded ?? raw;
+                const outHeaders = { ...upstreamRes.headers };
+                if (recoded !== null) {
+                    outHeaders["content-length"] = String(outBody.length);
+                    delete outHeaders["transfer-encoding"];
+                    // 同 join.ts：补丁后不可沿用 immutable/长 max-age（URL 不变，旧未补丁体可能被长期缓存）
+                    outHeaders["cache-control"] = "public, max-age=300";
+                }
+                delete outHeaders.connection;
+                res.writeHead(upstreamRes.statusCode ?? 200, outHeaders);
+                res.end(outBody);
+            })().catch(() => {
+                if (!res.headersSent)
+                    res.writeHead(502, { "content-type": "text/plain" });
+                res.end("bad gateway");
+            });
+            return;
+        }
         res.writeHead(upstreamRes.statusCode ?? 502, upstreamRes.headers);
         upstreamRes.pipe(res);
     });

package/dist/serve.js

@@ -62,6 +62,7 @@ export async function serve(opts) {
             authVersion: config.auth.version,
             allowFrom: config.allowFrom,
             behindProxy: config.behindProxy,
+            dshUiCompat: config.dshUiCompat,
             tlsMaterial,
             userManager,
             configPath,

package/dist/server.d.ts

@@ -26,6 +26,13 @@ export interface GatewayOptions {
     dshPort: number;
     /** 宿主代持的 dsh 浏览器会话 cookie（`dsh-auth-*`，0.1.2+）；有值时注入转发 */
     dshAuthCookieHeader?: string | null;
+    /**
+     * DSH UI 兼容（LAN 路径）：`trustPairedAsLoopback` 默认 true —— 把已通过本机配对/登录的
+     * LAN 会话视同 loopback，使 DSH 的设置与"持久化凭据"界面可用（否则 LAN 用户无法在界面里输入 API key）。
+     */
+    dshUiCompat?: {
+        trustPairedAsLoopback?: boolean;
+    };
     /** true = 启动时重置会话密钥（全部会话失效） */
     reset?: boolean;
     /** 会话密钥目录（默认 ~/.rdsh；测试可注入临时目录） */

package/dist/server.js

@@ -18,6 +18,7 @@ import { basename, dirname } from "node:path";
 import { SessionManager, sessionTokenFromCookie } from "./session.js";
 import { PairManager } from "./pair.js";
 import { createUpgradeProxy, forwardHttp } from "./proxy.js";
+import { patchLoopbackJs } from "./join.js";
 import { pairPageHtml } from "./pair-page.js";
 import { loginPageHtml } from "./login-page.js";
 import { SECURE_CONTEXT_POLYFILL } from "./secure-context-polyfill.js";
@@ -70,6 +71,7 @@ export async function startGateway(opts) {
         authMode,
         behindProxy,
         dshAuthCookieHeader: opts.dshAuthCookieHeader ?? null,
+        trustPairedAsLoopback: opts.dshUiCompat?.trustPairedAsLoopback !== false,
         getVersion: () => currentVersion,
         isAllowed: (ip) => currentAllowFrom.length === 0 || ipInCidrs(ip, currentAllowFrom),
         userManager: opts.userManager,
@@ -156,7 +158,11 @@ async function handleHttp(req, res, ctx, loginLimiter) {
         return;
     }
     if (ctx.authMode === "none") {
-        forwardHttp(req, res, ctx.target, { htmlInject: SECURE_CONTEXT_POLYFILL, authCookie: ctx.dshAuthCookieHeader });
+        forwardHttp(req, res, ctx.target, {
+            htmlInject: SECURE_CONTEXT_POLYFILL,
+            authCookie: ctx.dshAuthCookieHeader,
+            jsPatch: ctx.trustPairedAsLoopback ? patchLoopbackJs : undefined,
+        });
         return;
     }
     if (!hasValidSession(req, ctx)) {
@@ -164,7 +170,13 @@ async function handleHttp(req, res, ctx, loginLimiter) {
         res.end();
         return;
     }
-    forwardHttp(req, res, ctx.target, { htmlInject: SECURE_CONTEXT_POLYFILL, authCookie: ctx.dshAuthCookieHeader });
+    forwardHttp(req, res, ctx.target, {
+        htmlInject: SECURE_CONTEXT_POLYFILL,
+        authCookie: ctx.dshAuthCookieHeader,
+        // 会话分支同样要打 loopback 补丁：LAN 没有 E2EE shim，设置/API key 唯一依赖这个补丁；
+        // 旧实现只在 authMode==="none" 分支传了 jsPatch ⇒ 配对/登录模式下设置页打不开（2026-09-14 复审发现）
+        jsPatch: ctx.trustPairedAsLoopback ? patchLoopbackJs : undefined,
+    });
 }
 async function handlePairPost(req, res, ctx) {
     const ip = req.socket.remoteAddress ?? "unknown";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rdsh-gateway",
-  "version": "0.8.2",
+  "version": "0.8.4",
   "description": "rdsh host-side component: LAN auth gateway + outbound tunnel endpoint (spawns dsh web)",
   "license": "MIT",
   "type": "module",