rdsh-gateway 0.8.3 → 0.8.5

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

@@ -91,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;
 /**
@@ -99,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";
@@ -131,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"];
@@ -183,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) {
@@ -208,8 +260,22 @@ export function startJoin(opts) {
     };
     const lock = acquireJoinLock(opts.role, opts.lockPath);
     if (!lock.ok) {
-        throw new Error(`join lock held by ${lock.heldBy.role} (pid ${lock.heldBy.pid}); stop it first`);
+        // 「同机单隧道」铁律：任何活锁都拒绝（含本进程自己的 pid —— 那是热重载时的同进程重复获取）
+        throw new Error("contended" in lock
+            ? "join lock is contended by another instance; retry"
+            : lock.heldBy.pid === process.pid
+                ? "another tunnel is already running in this process"
+                : `join lock held by ${lock.heldBy.role} (pid ${lock.heldBy.pid}); stop it first`);
     }
+    /**
+     * 构造期同步抛错必须把锁还回去（否则本进程再也起不来隧道，还谎报「本进程已有隧道」）。
+     * 现实抛点：E2EE 密钥生成/序列化（`loadOrCreateE2eeKeyPair`）与 `connect()` 里的
+     * `new WebSocket(非法 URL)`、以及 embedder 的 onState 钩子。
+     */
+    const releaseLockAndRethrow = (err) => {
+        releaseJoinLock(opts.lockPath);
+        throw err;
+    };
     const parser = new FrameParser();
     let shuttingDown = false;
     let reconnectDelay = RECONNECT_BASE_MS;
@@ -233,6 +299,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"];
@@ -326,7 +394,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);
@@ -385,6 +462,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,
@@ -392,22 +471,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);
                     });
@@ -417,10 +491,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);
                 });
@@ -429,8 +538,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 });
@@ -506,15 +617,36 @@ export function startJoin(opts) {
     }
     const plainDispatcher = makeInnerDispatcher(sendTunnelFrame, { jsPatch: () => uiCompat.trustE2EEAsLoopback, gate: true });
     // host 端 E2EE 静态密钥对（持久化 ~/.rdsh/e2ee-key.json；join 注册时上送指纹）
-    const hostE2eeKeypair = loadOrCreateE2eeKeyPair();
+    let hostE2eeKeypair;
+    try {
+        hostE2eeKeypair = loadOrCreateE2eeKeyPair();
+    }
+    catch (err) {
+        releaseLockAndRethrow(err);
+    }
     const rawStreams = new Map();
     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),
@@ -621,7 +753,6 @@ export function startJoin(opts) {
         const url = `${hubWsBase}/tunnel`;
         const client = new WebSocket(url, { headers: { authorization: `Bearer ${opts.token}` }, rejectUnauthorized: !opts.insecure });
         currentClient = client;
-        setState("connecting", { message: `connecting to ${opts.hubUrl}` });
         // 401/403 = token 被拒（吊销/不存在）。监听此事件后 ws 不再自动 abort，
         // 需手动 terminate → 触发 close → 决定「重配对」还是「普通重连」。
         let tokenRejected = false;
@@ -714,8 +845,16 @@ export function startJoin(opts) {
                 /* 已关闭 */
             }
         });
+        // 状态回调放在所有监听器挂好**之后**：embedder 的 onState 若抛错，异常会向上抛并被
+        // releaseLockAndRethrow 处理；此时 socket 已有 error 监听，不会因后续连接失败变成未捕获 error 崩进程。
+        setState("connecting", { message: `connecting to ${opts.hubUrl}` });
+    }
+    try {
+        connect();
+    }
+    catch (err) {
+        releaseLockAndRethrow(err);
     }
-    connect();
     return {
         setUiCompat(trustE2EEAsLoopback) {
             uiCompat.trustE2EEAsLoopback = trustE2EEAsLoopback;

package/dist/lock.d.ts

@@ -5,8 +5,11 @@ export interface JoinLock {
     role: JoinLockRole;
 }
 /**
- * 读锁。不存在/损坏/过短 → null；pid 已死（stale）→ 清除文件并返回 null。
+ * 读锁（**纯读，无副作用**）：不存在 / 损坏 / pid 已死（stale）→ null。
  * 供面板「外部托管」态判定（role=cli）与 acquire 前检测复用。
+ *
+ * 注意：不再顺手删除 stale 文件（旧实现有此行为且无二次校验，会误删他人新锁）；
+ * 清理统一由 acquire 路径的 `reapDeadLock()` 以 compare-and-delete 完成。
  */
 export declare function readJoinLock(path?: string): JoinLock | null;
 export type AcquireResult = {
@@ -14,11 +17,21 @@ export type AcquireResult = {
 } | {
     ok: false;
     heldBy: JoinLock;
+}
+/** 连续被抢占（拿不到也读不到持有者，极罕见）：不伪造持有者，由调用方给出「被占用」提示。 */
+ | {
+    ok: false;
+    contended: true;
 };
 /**
- * 获取锁：写入 `{pid: process.pid, role}`（目录 0700、文件 0600）。
- * 已有**他人**（不同 pid）持有的活锁 → 拒绝（防同机双隧道）。
+ * 获取锁：**原子发布**锁文件（临时文件 + `link`；目录 0700、文件 0600），内容 `{pid, role}`。
+ *
+ * - 已有活锁（**无论 pid 是否为自己**）→ 拒绝，防同机 / 同进程双隧道；
+ * - stale（pid 已死）或损坏残锁 → compare-and-delete 清除后重试；
+ * - 文件系统不支持硬链接 → 退回 `wx` 创建（旧实现在这些文件系统上就是这个行为，
+ *   短暂的"空文件窗口"由 `reapDeadLock` 的新鲜度保护兜住）；
+ * - 连续 3 次被抢占 → `{ok:false, contended:true}`。
  */
 export declare function acquireJoinLock(role: JoinLockRole, path?: string): AcquireResult;
-/** 释放锁：仅当锁是自己 pid 持有才删（不误删他人锁）。 */
+/** 释放锁：仅当锁是自己 pid 持有才删（不误删他人锁）；同时清本进程记账。 */
 export declare function releaseJoinLock(path?: string): void;

package/dist/lock.js

@@ -1,10 +1,18 @@
 /**
  * lock.ts — join pid 锁：CLI 与插件共享「单身份铁律」（同机单隧道，D5 档2）。
  *
- * 锁文件 `~/.rdsh/join.lock`（0600）记 `{pid, role}`；stale（pid 已死）自动视为无锁并清除。
+ * 锁文件 `~/.rdsh/join.lock`（0600）记 `{pid, role}`。
  * role = "cli"（rdsh CLI / systemd 服务持有）| "plugin"（dsh 插件持有）——面板据此显示「外部托管」。
+ *
+ * 三条不变量（2026-09-15 真机复盘：多个 `dsh web` 实例互相顶替导致面板反复掉线/连线）：
+ *   1. **原子发布**「文件 + 内容」：先写临时文件再 `link` —— 锁路径要么不存在、要么内容完整，
+ *      不存在「已存在但内容为空」的窗口（旧实现 `writeFileSync(..., {flag:"wx"})` 有这个窗口，
+ *      会被并发清理者当成坏锁删掉，两边都以为自己持锁）；
+ *   2. **拒绝任何活锁**（包括本进程自己的 pid）：同进程重复获取由 `heldPaths` 记账拦住；
+ *   3. **清理只走 compare-and-delete**：读 → 判断 → 删除之间不得误删他人刚发布的锁
+ *      （旧实现 `readJoinLock` 读到 stale 就无条件 `rmSync`，会删掉别人刚建立的新锁）。
  */
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, linkSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 const RDSH_DIR = join(homedir(), ".rdsh");
@@ -19,47 +27,144 @@ function isAlive(pid) {
         return err.code === "EPERM";
     }
 }
+/** 解析锁内容；损坏/字段非法 → null。纯函数，不碰文件系统。 */
+function parseLock(raw) {
+    try {
+        const j = JSON.parse(raw);
+        if (typeof j.pid !== "number" || (j.role !== "cli" && j.role !== "plugin"))
+            return null;
+        return { pid: j.pid, role: j.role };
+    }
+    catch {
+        return null;
+    }
+}
 /**
- * 读锁。不存在/损坏/过短 → null；pid 已死（stale）→ 清除文件并返回 null。
+ * 读锁（**纯读，无副作用**）：不存在 / 损坏 / pid 已死（stale）→ null。
  * 供面板「外部托管」态判定（role=cli）与 acquire 前检测复用。
+ *
+ * 注意：不再顺手删除 stale 文件（旧实现有此行为且无二次校验，会误删他人新锁）；
+ * 清理统一由 acquire 路径的 `reapDeadLock()` 以 compare-and-delete 完成。
  */
 export function readJoinLock(path = JOIN_LOCK_PATH) {
     try {
         if (!existsSync(path))
             return null;
-        const raw = JSON.parse(readFileSync(path, "utf8"));
-        if (typeof raw.pid !== "number" || (raw.role !== "cli" && raw.role !== "plugin"))
+        const held = parseLock(readFileSync(path, "utf8"));
+        if (held === null)
             return null;
-        if (!isAlive(raw.pid)) {
-            try {
-                rmSync(path, { force: true });
-            }
-            catch {
-                /* 忽略 */
-            }
-            return null;
-        }
-        return { pid: raw.pid, role: raw.role };
+        return isAlive(held.pid) ? held : null;
     }
     catch {
         return null;
     }
 }
+function snapshotLock(path) {
+    try {
+        const st = statSync(path);
+        return { raw: readFileSync(path, "utf8"), ino: st.ino, mtimeMs: st.mtimeMs };
+    }
+    catch {
+        return null;
+    }
+}
+/** 内容解析不出来的锁文件，多新以内视为"并发创建者写到一半"而不回收。 */
+const FRESH_LOCK_MS = 1000;
+/**
+ * 清除「确定已经死了」的残锁（pid 已死，或内容损坏且已不新），成功则锁路径变空、可重试获取。
+ *
+ * 两道保护，避免把别人的**活锁**删掉：
+ * 1. compare-and-delete 比对**内容 + inode**（同内容但换了 inode = 别人刚发布的新锁，不删）；
+ * 2. 内容解析不出来（空/半截）且文件很新 → 视为并发创建者写到一半，不删
+ *    （本实现的发布是原子的，这种文件只可能来自旧版本或外部写入者）。
+ */
+function reapDeadLock(path) {
+    const first = snapshotLock(path);
+    if (first === null)
+        return;
+    const held = parseLock(first.raw);
+    if (held !== null && isAlive(held.pid))
+        return; // 有效活锁
+    if (held === null && Date.now() - first.mtimeMs < FRESH_LOCK_MS)
+        return; // 可能是写到一半
+    const second = snapshotLock(path);
+    if (second === null || second.ino !== first.ino || second.raw !== first.raw)
+        return; // 期间被替换
+    try {
+        rmSync(path, { force: true });
+    }
+    catch {
+        /* 忽略 */
+    }
+}
+/**
+ * 本进程已持有的锁路径。pid 无法区分同进程的两次获取，必须单独记账。
+ *
+ * 必要性：插件热重载（`patchReload: "live"`）时同一进程先后起两条隧道 —— 若只按 pid 判断，
+ * 「锁是自己」会被放行（旧实现正是如此）→ 同机双隧道 → 与 hub 的顶替逻辑叠加成无限互踢。
+ */
+const heldPaths = new Set();
+/** 文件系统不支持硬链接时 `linkSync` 的 errno（SMB / FUSE / exFAT 之类）。 */
+const LINK_UNSUPPORTED = new Set(["EPERM", "ENOSYS", "ENOTSUP", "EOPNOTSUPP"]);
 /**
- * 获取锁：写入 `{pid: process.pid, role}`（目录 0700、文件 0600）。
- * 已有**他人**（不同 pid）持有的活锁 → 拒绝（防同机双隧道）。
+ * 获取锁：**原子发布**锁文件（临时文件 + `link`；目录 0700、文件 0600），内容 `{pid, role}`。
+ *
+ * - 已有活锁（**无论 pid 是否为自己**）→ 拒绝，防同机 / 同进程双隧道；
+ * - stale（pid 已死）或损坏残锁 → compare-and-delete 清除后重试；
+ * - 文件系统不支持硬链接 → 退回 `wx` 创建（旧实现在这些文件系统上就是这个行为，
+ *   短暂的"空文件窗口"由 `reapDeadLock` 的新鲜度保护兜住）；
+ * - 连续 3 次被抢占 → `{ok:false, contended:true}`。
  */
 export function acquireJoinLock(role, path = JOIN_LOCK_PATH) {
-    const held = readJoinLock(path);
-    if (held !== null && held.pid !== process.pid) {
-        return { ok: false, heldBy: held };
+    if (heldPaths.has(path)) {
+        return { ok: false, heldBy: { pid: process.pid, role } };
+    }
+    const data = JSON.stringify({ pid: process.pid, role });
+    const tmp = `${path}.${process.pid}.tmp`;
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+        try {
+            mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+            // 内容先落到临时文件（默认 flag 覆盖写，不会 EEXIST），再 link 到锁路径；
+            // link 是原子的：目标已存在则 EEXIST，且目标**一出现就带完整内容**。
+            writeFileSync(tmp, data, { mode: 0o600 });
+            linkSync(tmp, path);
+            heldPaths.add(path);
+            return { ok: true };
+        }
+        catch (err) {
+            const code = err.code;
+            if (code !== "EEXIST") {
+                if (!LINK_UNSUPPORTED.has(code ?? ""))
+                    throw err;
+                try {
+                    writeFileSync(path, data, { flag: "wx", mode: 0o600 });
+                    heldPaths.add(path);
+                    return { ok: true };
+                }
+                catch (err2) {
+                    if (err2.code !== "EEXIST")
+                        throw err2;
+                }
+            }
+        }
+        finally {
+            try {
+                rmSync(tmp, { force: true }); // 删掉临时名，锁路径（硬链接）不受影响
+            }
+            catch {
+                /* 忽略 */
+            }
+        }
+        const held = readJoinLock(path);
+        if (held !== null)
+            return { ok: false, heldBy: held };
+        reapDeadLock(path);
     }
-    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-    writeFileSync(path, JSON.stringify({ pid: process.pid, role }), { mode: 0o600 });
-    return { ok: true };
+    return { ok: false, contended: true };
 }
-/** 释放锁：仅当锁是自己 pid 持有才删（不误删他人锁）。 */
+/** 释放锁：仅当锁是自己 pid 持有才删（不误删他人锁）；同时清本进程记账。 */
 export function releaseJoinLock(path = JOIN_LOCK_PATH) {
+    heldPaths.delete(path);
     try {
         const held = readJoinLock(path);
         if (held !== null && held.pid === process.pid) {

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.3",
+  "version": "0.8.5",
   "description": "rdsh host-side component: LAN auth gateway + outbound tunnel endpoint (spawns dsh web)",
   "license": "MIT",
   "type": "module",