@yezack/dsh-remote-mobile 1.9.2 → 1.10.0

package/lib/client.js

@@ -1065,7 +1065,7 @@ var import_jsx_runtime = require("react/jsx-runtime");
 function NetworkCard({ status, toggleTailscale, toggleLan, copyText, lang }) {
   const tsHost = status.tailscaleIp || "100.x.y.z";
   const lanHost = status.lanIp || "127.0.0.1";
-  const port = typeof window !== "undefined" && window.location.port || "3080";
+  const port = status && status.gateway && status.gateway.activePort || typeof window !== "undefined" && window.location.port || "3080";
   return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
     "div",
     {
@@ -1099,6 +1099,29 @@ function NetworkCard({ status, toggleTailscale, toggleLan, copyText, lang }) {
             children: t("netCardDesc", lang)
           }
         ),
+        status?.gateway?.mode === "gateway" && status.gateway.running === false ? /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
+          "div",
+          {
+            style: {
+              background: "rgba(239, 68, 68, 0.12)",
+              border: "1px solid rgba(239, 68, 68, 0.35)",
+              borderRadius: "8px",
+              padding: "10px 12px",
+              marginBottom: "16px",
+              fontSize: "12px",
+              color: "var(--dsw-alias-label-error, #ef4444)",
+              lineHeight: "1.5",
+              textAlign: "left"
+            },
+            children: [
+              /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("strong", { children: [
+                "\u26A0\uFE0F ",
+                lang === "en" ? "Gateway Service Not Ready" : "\u5B89\u5168\u53CD\u5411\u4EE3\u7406\u7F51\u5173\u672A\u5C31\u7EEA"
+              ] }),
+              /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { children: status.gateway.error ? `${lang === "en" ? "Failure reason: " : "\u542F\u52A8\u5931\u8D25\uFF1A"}${status.gateway.error}` : lang === "en" ? "Gateway is initializing or failed to bind port. External devices cannot connect currently." : "\u7F51\u5173\u6B63\u5728\u542F\u52A8\u6216\u7AEF\u53E3\u7ED1\u5B9A\u5931\u8D25\uFF0C\u5916\u90E8\u624B\u673A\u8BBE\u5907\u5F53\u524D\u6682\u65F6\u65E0\u6CD5\u8FDE\u63A5\u3002" })
+            ]
+          }
+        ) : null,
         /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
           "div",
           {
@@ -1568,7 +1591,7 @@ function QrPairingCard({
   copyDirectLink,
   lang
 }) {
-  const port = typeof window !== "undefined" && window.location.port || "3080";
+  const port = status && status.gateway && status.gateway.activePort || typeof window !== "undefined" && window.location.port || "3080";
   const isExpired = timeLeft <= 0;
   const currentHost = selectedTab === "lan" && status.lanIp ? status.lanIp : status.tailscaleIp || status.lanIp || typeof window !== "undefined" && window.location.hostname || "127.0.0.1";
   const directLink = `http://${currentHost}:${port}/auth?token=${status.code || ""}`;
@@ -1606,7 +1629,31 @@ function QrPairingCard({
             children: t("pairingCardDesc", lang)
           }
         ),
-        showQr ? /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)(
+        status?.gateway?.mode === "gateway" && status.gateway.running === false ? /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)(
+          "div",
+          {
+            style: {
+              background: "rgba(239, 68, 68, 0.12)",
+              border: "1px solid rgba(239, 68, 68, 0.35)",
+              borderRadius: "8px",
+              padding: "12px 14px",
+              marginBottom: "14px",
+              fontSize: "13px",
+              color: "var(--dsw-alias-label-error, #ef4444)",
+              lineHeight: "1.6",
+              textAlign: "left"
+            },
+            children: [
+              /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("strong", { children: [
+                "\u26A0\uFE0F ",
+                lang === "en" ? "Standalone Gateway Error" : "\u5B89\u5168\u53CD\u5411\u4EE3\u7406\u7F51\u5173\u672A\u5C31\u7EEA"
+              ] }),
+              /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("div", { style: { marginTop: "4px", fontSize: "12px" }, children: status.gateway.error ? `${lang === "en" ? "Failure reason: " : "\u542F\u52A8\u5931\u8D25\uFF1A"}${status.gateway.error}` : lang === "en" ? "Gateway is initializing or port binding failed. External devices cannot connect currently." : "\u7F51\u5173\u6B63\u5728\u542F\u52A8\u6216\u7AEF\u53E3\u7ED1\u5B9A\u5931\u8D25\uFF0C\u5916\u90E8\u624B\u673A\u8BBE\u5907\u6682\u65F6\u65E0\u6CD5\u626B\u7801\u8FDE\u63A5\u3002" }),
+              /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("div", { style: { marginTop: "4px", fontSize: "11px", color: "var(--dsw-alias-label-tertiary, #888)" }, children: lang === "en" ? "Tip: Check if port 3081 is in use or inspect background logs." : "\u6392\u67E5\u5EFA\u8BAE\uFF1A\u8BF7\u68C0\u67E5 3081 \u7AEF\u53E3\u662F\u5426\u88AB\u5176\u4ED6\u8FDB\u7A0B\u5360\u7528\uFF0C\u6216\u68C0\u67E5\u540E\u53F0\u7EC8\u7AEF\u65E5\u5FD7\u3002" })
+            ]
+          }
+        ) : null,
+        showQr && !(status?.gateway?.mode === "gateway" && status.gateway.running === false) ? /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)(
           "div",
           {
             style: {
@@ -1767,28 +1814,30 @@ function QrPairingCard({
                     fontSize: "32px",
                     fontWeight: "800",
                     letterSpacing: showCode ? "6px" : "4px",
-                    color: isExpired ? "var(--dsw-alias-label-error, #ef4444)" : "var(--dsw-alias-brand-primary, #3b82f6)",
+                    color: status?.gateway?.mode === "gateway" && status.gateway.running === false || isExpired ? "var(--dsw-alias-label-error, #ef4444)" : "var(--dsw-alias-brand-primary, #3b82f6)",
                     fontFamily: "monospace",
                     userSelect: "all"
                   },
-                  children: isExpired ? lang === "en" ? "EXPIRED" : "\u5DF2\u8FC7\u671F" : showCode ? status.code : "\u2022\u2022\u2022\u2022\u2022\u2022"
+                  children: status?.gateway?.mode === "gateway" && status.gateway.running === false ? lang === "en" ? "DISABLED" : "\u5DF2\u505C\u7528" : isExpired ? lang === "en" ? "EXPIRED" : "\u5DF2\u8FC7\u671F" : showCode ? status.code : "\u2022\u2022\u2022\u2022\u2022\u2022"
                 }
               ),
               /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
                 "button",
                 {
                   type: "button",
+                  disabled: status?.gateway?.mode === "gateway" && status.gateway.running === false,
                   onClick: () => setShowCode(!showCode),
                   title: showCode ? t("clickToHide", lang) : t("clickToReveal", lang),
                   style: {
                     background: "transparent",
                     border: "none",
                     color: "var(--dsw-alias-label-secondary, #888)",
-                    cursor: "pointer",
+                    cursor: status?.gateway?.mode === "gateway" && status.gateway.running === false ? "not-allowed" : "pointer",
                     display: "flex",
                     alignItems: "center",
                     justifyContent: "center",
-                    padding: "4px"
+                    padding: "4px",
+                    opacity: status?.gateway?.mode === "gateway" && status.gateway.running === false ? 0.4 : 1
                   },
                   children: showCode ? /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("svg", { style: { width: "20px", height: "20px", fill: "currentColor" }, viewBox: "0 0 24 24", children: /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("path", { d: "M12 4.5C7 4.5 2.73 7.61 1 12c1.73 4.39 6 7.5 11 7.5s9.27-3.11 11-7.5c-1.73-4.39-6-7.5-11-7.5zM12 17c-2.76 0-5-2.24-5-5s2.24-5 5-5 5 2.24 5 5-2.24 5-5 5zm0-8c-1.66 0-3 1.34-3 3s1.34 3 3 3 3-1.34 3-3-1.34-3-3-3z" }) }) : /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("svg", { style: { width: "20px", height: "20px", fill: "currentColor" }, viewBox: "0 0 24 24", children: /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("path", { d: "M12 7c2.76 0 5 2.24 5 5 0 .65-.13 1.26-.36 1.83l2.92 2.92c1.51-1.26 2.7-2.89 3.43-4.75-1.73-4.39-6-7.5-11-7.5-1.4 0-2.74.25-3.98.7l2.16 2.16C10.74 7.13 11.35 7 12 7zM2 4.27l2.28 2.28.46.46C3.08 8.3 1.78 10.02 1 12c1.73 4.39 6 7.5 11 7.5 1.55 0 3.03-.3 4.38-.84l.42.42L19.73 22 21 20.73 3.27 3 2 4.27zM7.53 9.8l1.55 1.55c-.05.21-.08.43-.08.65 0 1.66 1.34 3 3 3 .22 0 .44-.03.65-.08l1.55 1.55c-.67.33-1.41.53-2.2.53-2.76 0-5-2.24-5-5 0-.79.2-1.53.53-2.2zm4.31-.78l3.15 3.15.02-.16c0-1.66-1.34-3-3-3l-.17.01z" }) })
                 }
@@ -1801,7 +1850,7 @@ function QrPairingCard({
           {
             style: {
               fontSize: "12px",
-              color: isExpired ? "var(--dsw-alias-label-error, #ef4444)" : "var(--dsw-alias-label-secondary, #888)",
+              color: status?.gateway?.mode === "gateway" && status.gateway.running === false || isExpired ? "var(--dsw-alias-label-error, #ef4444)" : "var(--dsw-alias-label-secondary, #888)",
               margin: "4px 0 16px 0",
               display: "flex",
               alignItems: "center",
@@ -1817,11 +1866,11 @@ function QrPairingCard({
                     width: "8px",
                     height: "8px",
                     borderRadius: "50%",
-                    background: isExpired ? "#ef4444" : "#10b981"
+                    background: status?.gateway?.mode === "gateway" && status.gateway.running === false || isExpired ? "#ef4444" : "#10b981"
                   }
                 }
               ),
-              isExpired ? `\u26A0\uFE0F ${t("codeExpired", lang)}` : `${t("codeValidUntil", lang)}${formatCountdown(timeLeft, lang)}`
+              status?.gateway?.mode === "gateway" && status.gateway.running === false ? `\u26A0\uFE0F ${lang === "en" ? "Gateway Service Error" : "\u7F51\u5173\u670D\u52A1\u5F02\u5E38"}` : isExpired ? `\u26A0\uFE0F ${t("codeExpired", lang)}` : `${t("codeValidUntil", lang)}${formatCountdown(timeLeft, lang)}`
             ]
           }
         ),
@@ -1839,6 +1888,7 @@ function QrPairingCard({
                 "button",
                 {
                   type: "button",
+                  disabled: status?.gateway?.mode === "gateway" && status.gateway.running === false,
                   onClick: () => setShowQr(!showQr),
                   style: {
                     padding: "7px 16px",
@@ -1848,7 +1898,8 @@ function QrPairingCard({
                     borderRadius: "8px",
                     fontSize: "13px",
                     fontWeight: "600",
-                    cursor: "pointer",
+                    cursor: status?.gateway?.mode === "gateway" && status.gateway.running === false ? "not-allowed" : "pointer",
+                    opacity: status?.gateway?.mode === "gateway" && status.gateway.running === false ? 0.4 : 1,
                     whiteSpace: "nowrap",
                     flexShrink: 0
                   },
@@ -1859,6 +1910,7 @@ function QrPairingCard({
                 "button",
                 {
                   type: "button",
+                  disabled: status?.gateway?.mode === "gateway" && status.gateway.running === false,
                   onClick: refreshStatusAndCode,
                   style: {
                     padding: "7px 16px",
@@ -1868,7 +1920,8 @@ function QrPairingCard({
                     borderRadius: "8px",
                     fontSize: "13px",
                     fontWeight: "600",
-                    cursor: "pointer",
+                    cursor: status?.gateway?.mode === "gateway" && status.gateway.running === false ? "not-allowed" : "pointer",
+                    opacity: status?.gateway?.mode === "gateway" && status.gateway.running === false ? 0.4 : 1,
                     whiteSpace: "nowrap",
                     flexShrink: 0
                   },
@@ -3538,8 +3591,8 @@ function StylesCard({ lang, showToast }) {
 }
 
 // src/client/version.js
-var PLUGIN_VERSION = "v1.9.2";
-var BUILD_TIME = "2026-10-13 13:09:49";
+var PLUGIN_VERSION = "v1.10.0";
+var BUILD_TIME = "2026-10-22 13:21:34";
 
 // src/client/components/MainSection.jsx
 var import_jsx_runtime9 = require("react/jsx-runtime");

package/lib/gateway/detector.d.ts

@@ -0,0 +1,42 @@
+/**
+ * DSH 底座运行模式探测器
+ *
+ * 负责检测宿主 DSH WebServer 当前的网络暴露姿态：
+ * 1. 若宿主仅监听本地回环地址 (127.0.0.1 / localhost)，则外部网络无法直连，
+ *    自适应判定为网关模式 ('gateway')，由插件启动独立安全反代网关 (0.0.0.0:3081)；
+ * 2. 若宿主已监听 0.0.0.0 或具体的外部网卡 IP，则外部网络可直连，
+ *    判定为直连模式 ('direct')，沿用原生的 Hook 拦截机制，不额外占用端口；
+ * 3. 支持用户通过 options.mode ('auto' | 'gateway' | 'direct') 强制覆盖。
+ */
+export type GatewayMode = 'gateway' | 'direct';
+export interface ServerModeDetectionResult {
+    /** 最终生效的运行模式 */
+    mode: GatewayMode;
+    /** 是否为自动探测得出 */
+    isAuto: boolean;
+    /** 底座核心监听的 host（未配置时默认 127.0.0.1，在 gateway 模式下已安全规范化为回环 target） */
+    coreHost: string;
+    /** 底座核心监听的端口（默认 3080） */
+    corePort: number;
+    /** 底座原始配置是否判定为纯回环监听 */
+    isLoopback: boolean;
+    /** 原始底座 host */
+    rawCoreHost: string;
+}
+/**
+ * 判断指定 host 是否属于本地回环地址（支持 localhost, 127.*, ::1, 0:0:0:0:0:0:0:1 等完整形态）
+ */
+export declare function isLoopbackHost(host?: string | null): boolean;
+/**
+ * 规范化网关内部转发的目标核心 Host（仅在 gateway 模式下作为 proxy target 使用）
+ * 将通配或 localhost 规范化为明确的回环 IP，消除 Node 18+ 的 Happy Eyeballs IPv6 优先解析 502 隐患
+ */
+export declare function normalizeGatewayTargetHost(host: string): string;
+/**
+ * 探测底座运行姿态并裁决插件的工作模式
+ *
+ * @param ctx Cordis 上下文（含 webServer / webStartup 等服务）
+ * @param configuredMode 用户显式配置的运行模式 ('auto' | 'gateway' | 'direct')
+ * @param defaultCorePort 底座默认核心端口（3080）
+ */
+export declare function detectServerMode(ctx: any, configuredMode?: 'auto' | 'gateway' | 'direct', defaultCorePort?: number): ServerModeDetectionResult;

package/lib/gateway/detector.js

@@ -0,0 +1,88 @@
+/**
+ * DSH 底座运行模式探测器
+ *
+ * 负责检测宿主 DSH WebServer 当前的网络暴露姿态：
+ * 1. 若宿主仅监听本地回环地址 (127.0.0.1 / localhost)，则外部网络无法直连，
+ *    自适应判定为网关模式 ('gateway')，由插件启动独立安全反代网关 (0.0.0.0:3081)；
+ * 2. 若宿主已监听 0.0.0.0 或具体的外部网卡 IP，则外部网络可直连，
+ *    判定为直连模式 ('direct')，沿用原生的 Hook 拦截机制，不额外占用端口；
+ * 3. 支持用户通过 options.mode ('auto' | 'gateway' | 'direct') 强制覆盖。
+ */
+/**
+ * 判断指定 host 是否属于本地回环地址（支持 localhost, 127.*, ::1, 0:0:0:0:0:0:0:1 等完整形态）
+ */
+export function isLoopbackHost(host) {
+    if (!host || typeof host !== 'string')
+        return true; // 默认回环
+    let trimmed = host.trim().toLowerCase();
+    if (!trimmed)
+        return true;
+    if (trimmed.startsWith('[') && trimmed.endsWith(']')) {
+        trimmed = trimmed.slice(1, -1);
+    }
+    if (trimmed === 'localhost' || trimmed === '::1' || trimmed === '0:0:0:0:0:0:0:1')
+        return true;
+    if (trimmed === '127.0.0.1' || trimmed.startsWith('127.'))
+        return true;
+    if (trimmed === '::ffff:127.0.0.1' || trimmed.startsWith('::ffff:127.'))
+        return true;
+    return false;
+}
+/**
+ * 规范化网关内部转发的目标核心 Host（仅在 gateway 模式下作为 proxy target 使用）
+ * 将通配或 localhost 规范化为明确的回环 IP，消除 Node 18+ 的 Happy Eyeballs IPv6 优先解析 502 隐患
+ */
+export function normalizeGatewayTargetHost(host) {
+    const trimmed = host.trim().toLowerCase();
+    if (trimmed === '0.0.0.0' || trimmed === 'localhost')
+        return '127.0.0.1';
+    if (trimmed === '::' || trimmed === '[::]')
+        return '::1';
+    // Node http.request 的 hostname 不接受 IPv6 方括号；去掉后由 coreTargetAuthority 重新加回
+    if (trimmed.startsWith('[') && trimmed.endsWith(']')) {
+        return host.trim().slice(1, -1);
+    }
+    return host.trim();
+}
+/**
+ * 探测底座运行姿态并裁决插件的工作模式
+ *
+ * @param ctx Cordis 上下文（含 webServer / webStartup 等服务）
+ * @param configuredMode 用户显式配置的运行模式 ('auto' | 'gateway' | 'direct')
+ * @param defaultCorePort 底座默认核心端口（3080）
+ */
+export function detectServerMode(ctx, configuredMode = 'auto', defaultCorePort = 3080) {
+    const webServer = (typeof ctx?.get === 'function' ? ctx.get('webServer') : undefined) || ctx?.webServer;
+    const webStartup = (typeof ctx?.get === 'function' ? ctx.get('webStartup') : undefined) || ctx?.webStartup;
+    // 提取宿主底座的 host 与 port 配置（保持原始字面量用于模式判定）
+    const coreHostRaw = webServer?.config?.host ?? webServer?.options?.host ?? webStartup?.host ?? '127.0.0.1';
+    const corePortRaw = webServer?.config?.port ?? webServer?.options?.port ?? webStartup?.port ?? webServer?.port ?? defaultCorePort;
+    const rawCoreHost = String(coreHostRaw || '127.0.0.1').trim();
+    const corePort = Number(corePortRaw) || defaultCorePort;
+    const isLoopback = isLoopbackHost(rawCoreHost);
+    let finalMode = 'direct';
+    const isAuto = configuredMode === 'auto';
+    if (configuredMode === 'gateway') {
+        if (!isLoopback && rawCoreHost !== '0.0.0.0' && rawCoreHost !== '::') {
+            throw new Error(`[dsh-remote-mobile] 无法在具体外部 IP ("${rawCoreHost}") 上启用网关模式 (mode: 'gateway')。网关模式要求底座监听在本地回环 (127.0.0.1)；若需直接对外开放请使用 direct 模式。`);
+        }
+        finalMode = 'gateway';
+    }
+    else if (configuredMode === 'direct') {
+        finalMode = 'direct';
+    }
+    else {
+        // auto 自适应模式：底座为回环则启用网关，底座已对外开放（0.0.0.0 / 具体外部IP）则直连
+        finalMode = isLoopback ? 'gateway' : 'direct';
+    }
+    // 仅对最终生效的 gateway 模式的目标核心地址执行 proxyTarget 规范化
+    const coreHost = finalMode === 'gateway' ? normalizeGatewayTargetHost(rawCoreHost) : rawCoreHost;
+    return {
+        mode: finalMode,
+        isAuto,
+        coreHost,
+        corePort,
+        isLoopback,
+        rawCoreHost,
+    };
+}

package/lib/gateway/secret.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 生成 32 字节高强度密码学随机密钥
+ */
+export declare function generateGatewaySecret(): string;
+/**
+ * 设置网关内部共享密钥
+ * @param serverOrKey - 关联的 Server 实例（可选）
+ * @param secret - 密钥字符串
+ */
+export declare function setGatewaySecret(serverOrKey: any, secret: string): void;
+/**
+ * 获取当前有效的网关内部共享密钥
+ * @param serverOrKey - 关联的 Server 实例（可选）
+ */
+export declare function getGatewaySecret(serverOrKey?: any): string;
+/**
+ * 清除网关内部密钥
+ */
+export declare function clearGatewaySecret(serverOrKey?: any): void;
+/**
+ * 恒定时间安全比对两个密钥，防止时序侧信道攻击
+ */
+export declare function safeCompareSecret(candidate: string | string[] | undefined, actual: string): boolean;

package/lib/gateway/secret.js

@@ -0,0 +1,65 @@
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+/**
+ * 内部网关私密握手密钥管理器
+ *
+ * 用于网关与底层 DSH HTTP Server 之间的受信通信鉴权：
+ * 仅当底层物理连接为回环 Socket (127.0.0.1 / ::1) 且携带匹配的私密握手密钥时，
+ * 底层虚拟化补丁才采纳网关上报的真实客户端 IP (x-dsh-real-ip)。
+ *
+ * 采用全局活跃单例兼 WeakMap 绑定实例机制，完美兼容 Cordis 插件热重载与多实例隔离场景。
+ */
+let globalActiveSecret = '';
+const serverSecretMap = new WeakMap();
+/**
+ * 生成 32 字节高强度密码学随机密钥
+ */
+export function generateGatewaySecret() {
+    return randomBytes(32).toString('hex');
+}
+/**
+ * 设置网关内部共享密钥
+ * @param serverOrKey - 关联的 Server 实例（可选）
+ * @param secret - 密钥字符串
+ */
+export function setGatewaySecret(serverOrKey, secret) {
+    globalActiveSecret = secret;
+    if (serverOrKey && (typeof serverOrKey === 'object' || typeof serverOrKey === 'function')) {
+        serverSecretMap.set(serverOrKey, secret);
+    }
+}
+/**
+ * 获取当前有效的网关内部共享密钥
+ * @param serverOrKey - 关联的 Server 实例（可选）
+ */
+export function getGatewaySecret(serverOrKey) {
+    if (serverOrKey && (typeof serverOrKey === 'object' || typeof serverOrKey === 'function')) {
+        const bound = serverSecretMap.get(serverOrKey);
+        if (bound)
+            return bound;
+    }
+    return globalActiveSecret;
+}
+/**
+ * 清除网关内部密钥
+ */
+export function clearGatewaySecret(serverOrKey) {
+    if (serverOrKey && (typeof serverOrKey === 'object' || typeof serverOrKey === 'function')) {
+        serverSecretMap.delete(serverOrKey);
+    }
+    globalActiveSecret = '';
+}
+/**
+ * 恒定时间安全比对两个密钥，防止时序侧信道攻击
+ */
+export function safeCompareSecret(candidate, actual) {
+    if (!candidate || !actual)
+        return false;
+    const candStr = Array.isArray(candidate) ? candidate[0] : candidate;
+    if (typeof candStr !== 'string')
+        return false;
+    const bufCand = Buffer.from(candStr, 'utf8');
+    const bufActual = Buffer.from(actual, 'utf8');
+    if (bufCand.length !== bufActual.length)
+        return false;
+    return timingSafeEqual(bufCand, bufActual);
+}

package/lib/gateway/server.d.ts

@@ -0,0 +1,108 @@
+/**
+ * DSH 移动端远程独立安全网关服务 (GatewayServer)
+ *
+ * 架构定位：
+ * 解决 DSH 0.2.1+ 底层强行禁止 0.0.0.0 监听的问题。
+ * DSH 官方 WebServer 继续保持纯粹、安全的 127.0.0.1:3080 本地回环监听（零外部暴露风险）；
+ * 由本服务在 0.0.0.0:3081 启动专用安全反代网关，接纳局域网与 Tailscale 流量，
+ * 执行端到端 RSA 加密、扫码配对、慢哈希密码认证与防暴力破解 IP 熔断，
+ * 并将合法的流量全双工代理至底座核心服务，彻底解决换 Wi-Fi 崩溃、无法兼顾多网卡与本机回环失效的痛点。
+ */
+import http, { type IncomingMessage, type ServerResponse } from 'node:http';
+import type { SessionStore } from '../auth/token.js';
+export interface GatewayServerOptions {
+    /** 网关监听端口，默认 3081 */
+    port?: number;
+    /** 网关监听网络地址，默认 0.0.0.0 */
+    host?: string;
+    /** DSH 宿主核心服务端口，默认 3080 */
+    corePort: number;
+    /** DSH 宿主核心服务主机，默认 127.0.0.1 */
+    coreHost?: string;
+    /** 端口冲突时是否允许自动向后递增探测，默认 true */
+    autoIncrementPort?: boolean;
+    /** WebSocket 升级握手超时（毫秒），默认 10000ms */
+    upgradeTimeoutMs?: number;
+}
+export type GatewayServerStatus = 'stopped' | 'starting' | 'running' | 'error';
+export declare class GatewayServer {
+    private server;
+    private activeSockets;
+    private store;
+    private gateMiddleware;
+    private configuredPort;
+    private boundPort;
+    private host;
+    private corePort;
+    private coreHost;
+    private coreTargetAuthority;
+    private autoIncrementPort;
+    private upgradeTimeoutMs;
+    private status;
+    private lastError;
+    private logger?;
+    constructor(options: GatewayServerOptions, store: SessionStore, gateMiddleware: (req: IncomingMessage, res: ServerResponse, next?: () => void) => boolean, logger?: any);
+    /** 获取网关当前运行状态契约 */
+    getStatus(): GatewayServerStatus;
+    /** 获取网关最近发生的异常信息 */
+    getLastError(): string | null;
+    /** 获取网关实际生效绑定的端口 */
+    getBoundPort(): number;
+    /** 获取网关监听的 host */
+    getHost(): string;
+    /** 获取内部转发的目标核心端口 */
+    getCorePort(): number;
+    /** 获取内部底层 Server 实例（供测试或状态检测） */
+    getServer(): http.Server | null;
+    /**
+     * 检验请求的 Host 头是否符合动态白名单（防 DNS-Rebinding 与非法主机注入）
+     */
+    isHostAllowed(hostHeader?: string): boolean;
+    /**
+     * 获取外部访问协议（兼容 Nginx / Caddy / Tailscale Serve 等反代的 X-Forwarded-Proto）
+     */
+    private getExternalProtocol;
+    /**
+     * 计算转发到底座的真实客户端 IP。
+     *
+     * 正常 LAN/Tailscale 客户端直接连网关，socket IP 即真实 IP；
+     * 同机反向代理从 127.0.0.1 连入时，若门禁已判定为非回环（Host/Forwarded 表明是代理），
+     * 则采用 X-Forwarded-For 首个合法 IP，恢复防暴破/审计的真实来源。
+     */
+    private getEffectiveClientIp;
+    /** 请求是否携带反向代理透传头 */
+    private hasForwardedHeaders;
+    /**
+     * 启动网关服务（带端口冲突自愈探测与状态机落定）
+     */
+    start(): Promise<{
+        port: number;
+        host: string;
+    }>;
+    /**
+     * 优雅关闭网关服务，立即释放端口与所有客户端 Socket
+     */
+    close(): Promise<void>;
+    /**
+     * 处理 HTTP 请求：
+     * 1. 严格校验 Host 白名单（阻断 DNS-Rebinding）
+     * 2. 执行安全门禁 gateMiddleware 与跨站写拦截
+     * 3. 构造请求头：抹除客户端伪造 Secret，注入真实 IP 与内部有效握手密钥
+     * 4. 实施成对虚拟化决策矩阵
+     * 5. 转发到底座并流式透明 Pipe
+     */
+    private handleHttpRequest;
+    /**
+     * 转发已授权的 HTTP 请求至 DSH 本地核心服务
+     */
+    private proxyHttpRequest;
+    /**
+     * 处理 WebSocket Upgrade 协议升级代理（支持超时清除、非 101 状态传递与 CSWSH 防御）
+     */
+    private handleUpgrade;
+    /**
+     * 改写底座 30x 重定向的目标 Location，将回环地址替换为外部真实访问的 Host
+     * 兼容 127.0.0.1, localhost, [::1] 以及 127.* 回环变体
+     */
+    rewriteRedirectLocation(location: string, originalHost: string, externalProto?: 'http' | 'https'): string;
+}