@yezack/dsh-remote-mobile 1.9.2 → 1.10.0

package/lib/auth/gate.d.ts

@@ -1,22 +1,52 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { SessionStore } from './token.js';
 /**
- * 判断请求是否来自本机回环
+ * 判断请求是否来自本机回环。
+ *
+ * 不能只看 socket：同机反向代理同样从 127.0.0.1 连入，但 Host/Forwarded 头
+ * 指向外部域名。若仍按回环无条件放行，会把所有反代外部用户当成本机。
+ *
+ * 规则：
+ * - 受信网关（底座补丁校验 Secret 后打标）始终按回环处理；
+ * - 物理回环 + 本地 Host（localhost、127.x、::1）且无 Forwarded 头 → 本机；
+ * - 物理回环 + 外部 Host 或 X-Forwarded-* / X-Real-IP → 按外部/反代处理，走正常鉴权。
  */
 export declare function isLoopbackRequest(req: IncomingMessage): boolean;
+/**
+ * 提取主机名（去除端口与 IPv6 方括号）
+ */
+export declare function extractBareHostname(hostWithPort?: string): string;
+/**
+ * 提取端口号字符串
+ */
+export declare function extractPortString(hostWithPort?: string): string;
+/**
+ * 获取外部请求的有效协议（兼容 Nginx / Caddy / Tailscale Serve 等反代的 X-Forwarded-Proto）。
+ *
+ * 注意：该值用于同源判断与重定向，不用于认证。反向代理应正确设置 X-Forwarded-Proto；
+ * 直接 HTTP 访问没有该头时按 http 处理。
+ */
+export declare function getRequestProtocol(req: IncomingMessage): 'http' | 'https';
+/**
+ * 判断两个 Authority (host:port) 是否同源或属于本地回环等价。
+ *
+ * 当同时提供 Origin/请求的协议时，先严格比较协议，杜绝 http↔https 跨协议 CSRF；
+ * 并仅按对应协议的默认端口（http:80 / https:443）做反向代理兼容。
+ * 未提供协议时只做精确 authority 比较，不做默认端口放宽。
+ */
+export declare function isSameOriginOrLocalEquivalent(originAuthority: string, requestHost: string, originProtocol?: string, requestProtocol?: string): boolean;
+/**
+ * 判断请求 Host 是否属于受信任主机（本机回环、本机网卡 IP、Tailscale IP 或静态 trustedHosts）。
+ *
+ * 该函数只校验主机名，不强制校验端口：反向代理、端口映射、TLS 终结场景的
+ * 外部端口通常不是网关实际 boundPort，端口不应作为 DNS-Rebinding 的信任边界。
+ */
+export declare function isTrustedHost(hostHeader: string | undefined, store: SessionStore, extraHosts?: string[]): boolean;
 /**
  * 判断请求是否携带浏览器跨站信号（用于回环 CSRF / drive-by 防御）。
  *
  * Origin 与 Sec-Fetch-Site 由浏览器强制填写，页面脚本无法伪造或隐藏；
  * 恶意网页驱使浏览器向本机回环发起的写请求必然携带这些信号。
- * 不带这些头的客户端（curl / 本机脚本 / 旧内核 WebView）不受影响，保持向后兼容。
- *
- * 说明（有意取舍，非缺陷）：
- * - 仅比较 host:port，不比较 scheme：插件主要运行于 HTTP 局域网/回环场景，
- *   同 host:port 下出现 HTTPS 恶意来源的现实可能性极低；
- * - 无 Origin 时仅将 Sec-Fetch-Site: cross-site 判为跨站，same-site 不拦截：
- *   回环场景无域名层级概念，子域场景不适用；收紧为「非 same-origin 即拦截」
- *   会误伤不发送这些头的旧内核 WebView，与向后兼容目标冲突。
  */
 export declare function hasCrossSiteSignal(req: IncomingMessage): boolean;
 /**

package/lib/auth/gate.js

@@ -1,28 +1,205 @@
-import { isTailscaleIp, isLanIp, getClientIp } from './tailscale.js';
+import { isTailscaleIp, isLanIp, getClientIp, getAllNetworkIps } from './tailscale.js';
 import { resolveRedirectPath } from './prefix.js';
 /**
- * 判断请求是否来自本机回环
+ * 判断请求是否来自本机回环。
+ *
+ * 不能只看 socket：同机反向代理同样从 127.0.0.1 连入，但 Host/Forwarded 头
+ * 指向外部域名。若仍按回环无条件放行，会把所有反代外部用户当成本机。
+ *
+ * 规则：
+ * - 受信网关（底座补丁校验 Secret 后打标）始终按回环处理；
+ * - 物理回环 + 本地 Host（localhost、127.x、::1）且无 Forwarded 头 → 本机；
+ * - 物理回环 + 外部 Host 或 X-Forwarded-* / X-Real-IP → 按外部/反代处理，走正常鉴权。
  */
 export function isLoopbackRequest(req) {
     const ip = getClientIp(req);
-    return ip === '127.0.0.1' || ip === '::1' || ip === 'localhost';
+    const socketIsLoopback = ip === '127.0.0.1' || ip === '::1' || ip === 'localhost';
+    if (!socketIsLoopback)
+        return false;
+    // 底座补丁已用网关内部 Secret 验证该请求来自受信 Gateway
+    if (req.__dsh_rm_trusted_gateway__)
+        return true;
+    const host = extractBareHostname(req.headers.host);
+    if (host && !isLocalVariant(host))
+        return false;
+    // 注意：插件自身会为 loopback 请求注入 x-forwarded-for / x-real-ip /
+    // x-forwarded-host（值均为 127.0.0.1），不能把“存在 Forwarded 头”直接
+    // 等同于“同机反向代理”，否则会误伤 3080 根路径的 connection 鉴权。
+    // 只有转发值指向外部主机/外部 IP，或出现 X-Forwarded-Proto 时，才判为代理。
+    const forwardedFor = firstHeaderValue(req.headers['x-forwarded-for']);
+    if (forwardedFor && !isLoopbackIpValue(forwardedFor))
+        return false;
+    const realIp = firstHeaderValue(req.headers['x-real-ip']);
+    if (realIp && !isLoopbackIpValue(realIp))
+        return false;
+    const forwardedHost = firstHeaderValue(req.headers['x-forwarded-host']);
+    if (forwardedHost) {
+        const bareForwardedHost = extractBareHostname(forwardedHost);
+        if (!bareForwardedHost || !isLocalVariant(bareForwardedHost))
+            return false;
+    }
+    // X-Forwarded-Proto 由反向代理/TLS 终结器写入；插件自身不会为 loopback 注入
+    if (firstHeaderValue(req.headers['x-forwarded-proto']))
+        return false;
+    return true;
+}
+/** 取请求头首个值（兼容 Node 合并的数组形式） */
+function firstHeaderValue(value) {
+    if (Array.isArray(value))
+        return (value[0] || '').trim();
+    return typeof value === 'string' ? value.trim() : '';
+}
+/** 判断一个转发头 IP 是否仍是本机回环地址 */
+function isLoopbackIpValue(value) {
+    const first = value.split(',')[0].trim();
+    if (!first)
+        return false;
+    const clean = first
+        .replace(/^\[/, '')
+        .replace(/\]$/, '')
+        .replace(/^::ffff:/i, '')
+        .toLowerCase();
+    return isLocalVariant(clean);
 }
 const STATIC_ASSET_EXT_REGEX = /\.(js|mjs|cjs|css|png|jpg|jpeg|gif|svg|webp|ico|woff|woff2|ttf|eot|otf|map|json|txt|wasm)$/i;
-/** 插件私有变更类 API 前缀（非 GET 请求需做跨站信号校验） */
-const MUTATION_API_PREFIX = '/api/remote-mobile/';
+/**
+ * 提取主机名（去除端口与 IPv6 方括号）
+ */
+export function extractBareHostname(hostWithPort = '') {
+    if (!hostWithPort)
+        return '';
+    let host = hostWithPort.trim();
+    if (host.startsWith('[')) {
+        host = host.slice(1).split(']')[0];
+    }
+    else {
+        host = host.split(':')[0];
+    }
+    // 去除通配符 *. 与末尾 FQDN 点
+    return host.replace(/^\*\./, '').replace(/\.+$/, '').toLowerCase();
+}
+/**
+ * 提取端口号字符串
+ */
+export function extractPortString(hostWithPort = '') {
+    if (!hostWithPort)
+        return '';
+    const trimmed = hostWithPort.trim();
+    if (trimmed.startsWith('[')) {
+        const after = trimmed.split(']')[1];
+        return after && after.startsWith(':') ? after.slice(1) : '';
+    }
+    return trimmed.includes(':') ? trimmed.split(':')[1] : '';
+}
+/**
+ * 判断主机是否属于本地回环变体 (localhost, 127.*, ::1 等)
+ */
+function isLocalVariant(hostname = '') {
+    if (!hostname)
+        return false;
+    return (hostname === 'localhost' ||
+        hostname === '::1' ||
+        hostname === '0:0:0:0:0:0:0:1' ||
+        hostname === '127.0.0.1' ||
+        /^127\./.test(hostname));
+}
+/**
+ * 获取外部请求的有效协议（兼容 Nginx / Caddy / Tailscale Serve 等反代的 X-Forwarded-Proto）。
+ *
+ * 注意：该值用于同源判断与重定向，不用于认证。反向代理应正确设置 X-Forwarded-Proto；
+ * 直接 HTTP 访问没有该头时按 http 处理。
+ */
+export function getRequestProtocol(req) {
+    const raw = req?.headers?.['x-forwarded-proto'];
+    const value = Array.isArray(raw) ? raw[0] : raw;
+    if (typeof value === 'string' && value.split(',')[0].trim().toLowerCase() === 'https') {
+        return 'https';
+    }
+    if (req?.socket?.encrypted)
+        return 'https';
+    return 'http';
+}
+/**
+ * 判断两个 Authority (host:port) 是否同源或属于本地回环等价。
+ *
+ * 当同时提供 Origin/请求的协议时，先严格比较协议，杜绝 http↔https 跨协议 CSRF；
+ * 并仅按对应协议的默认端口（http:80 / https:443）做反向代理兼容。
+ * 未提供协议时只做精确 authority 比较，不做默认端口放宽。
+ */
+export function isSameOriginOrLocalEquivalent(originAuthority, requestHost, originProtocol, requestProtocol) {
+    if (!originAuthority || !requestHost)
+        return false;
+    const originScheme = String(originProtocol || '').replace(/:$/, '').toLowerCase();
+    const requestScheme = String(requestProtocol || '').replace(/:$/, '').toLowerCase();
+    if (originScheme && requestScheme && originScheme !== requestScheme)
+        return false;
+    if (originAuthority.toLowerCase() === requestHost.toLowerCase())
+        return true;
+    const origHost = extractBareHostname(originAuthority);
+    const reqHost = extractBareHostname(requestHost);
+    const origPort = extractPortString(originAuthority);
+    const reqPort = extractPortString(requestHost);
+    const defaultPort = originScheme === 'https' ? '443' : originScheme === 'http' ? '80' : '';
+    const isDefaultPort = (port) => Boolean(defaultPort) && port === defaultPort;
+    // 外部主机：裸主机名相同，且端口相同或一方省略、另一方为该 Origin 协议的默认端口
+    if (origHost && origHost === reqHost) {
+        if (origPort === reqPort)
+            return true;
+        if (isDefaultPort(origPort) && reqPort === '')
+            return true;
+        if (origPort === '' && isDefaultPort(reqPort))
+            return true;
+    }
+    // 本地变体等价判断：host 均属本地变体，且端口相同或为该协议的默认端口
+    if (isLocalVariant(origHost) && isLocalVariant(reqHost)) {
+        if (origPort === reqPort)
+            return true;
+        if (isDefaultPort(origPort) && reqPort === '')
+            return true;
+        if (origPort === '' && isDefaultPort(reqPort))
+            return true;
+    }
+    return false;
+}
+/**
+ * 判断请求 Host 是否属于受信任主机（本机回环、本机网卡 IP、Tailscale IP 或静态 trustedHosts）。
+ *
+ * 该函数只校验主机名，不强制校验端口：反向代理、端口映射、TLS 终结场景的
+ * 外部端口通常不是网关实际 boundPort，端口不应作为 DNS-Rebinding 的信任边界。
+ */
+export function isTrustedHost(hostHeader, store, extraHosts = []) {
+    const host = extractBareHostname(hostHeader);
+    if (!host)
+        return false;
+    // 通配地址永远不能被当作受信任 Host
+    if (host === '0.0.0.0' || host === '::')
+        return false;
+    if (isLocalVariant(host))
+        return true;
+    try {
+        const networkIps = getAllNetworkIps().map((i) => i.ip.toLowerCase());
+        if (networkIps.includes(host))
+            return true;
+    }
+    catch { }
+    try {
+        const statics = (store.getOptions().trustedHosts || [])
+            .map((h) => extractBareHostname(String(h)))
+            .filter((h) => Boolean(h) && h !== '0.0.0.0' && h !== '::');
+        if (statics.includes(host))
+            return true;
+    }
+    catch { }
+    const extras = extraHosts
+        .map((h) => extractBareHostname(String(h)))
+        .filter((h) => Boolean(h) && h !== '0.0.0.0' && h !== '::');
+    return extras.includes(host);
+}
 /**
  * 判断请求是否携带浏览器跨站信号（用于回环 CSRF / drive-by 防御）。
  *
  * Origin 与 Sec-Fetch-Site 由浏览器强制填写，页面脚本无法伪造或隐藏；
  * 恶意网页驱使浏览器向本机回环发起的写请求必然携带这些信号。
- * 不带这些头的客户端（curl / 本机脚本 / 旧内核 WebView）不受影响，保持向后兼容。
- *
- * 说明（有意取舍，非缺陷）：
- * - 仅比较 host:port，不比较 scheme：插件主要运行于 HTTP 局域网/回环场景，
- *   同 host:port 下出现 HTTPS 恶意来源的现实可能性极低；
- * - 无 Origin 时仅将 Sec-Fetch-Site: cross-site 判为跨站，same-site 不拦截：
- *   回环场景无域名层级概念，子域场景不适用；收紧为「非 same-origin 即拦截」
- *   会误伤不发送这些头的旧内核 WebView，与向后兼容目标冲突。
  */
 export function hasCrossSiteSignal(req) {
     const origin = req.headers.origin;
@@ -30,8 +207,9 @@ export function hasCrossSiteSignal(req) {
         if (origin === 'null')
             return true; // 沙箱 iframe 等场景的不透明 Origin，一律视为跨站
         try {
-            const originHost = new URL(origin).host;
-            return originHost !== '' && originHost !== (req.headers.host || '');
+            const originUrl = new URL(origin);
+            const reqHost = req.headers.host || '';
+            return !isSameOriginOrLocalEquivalent(originUrl.host, reqHost, originUrl.protocol, getRequestProtocol(req));
         }
         catch {
             return true; // 无法解析的 Origin 视为不可信
@@ -54,7 +232,7 @@ export function isPublicPath(url = '') {
         return true;
     if (pathname.startsWith('/assets/'))
         return true;
-    if (pathname === '/favicon.ico')
+    if (pathname === '/favicon.ico' || pathname === '/manifest.webmanifest' || pathname === '/manifest.json')
         return true;
     return false;
 }
@@ -63,55 +241,75 @@ export function isPublicPath(url = '') {
  */
 export function createGlobalAuthGate(store) {
     return function authGateMiddleware(req, res, next) {
-        const pass = () => {
+        const pass = (reason) => {
+            ;
+            req.__dsh_rm_gate_result = reason;
             if (typeof next === 'function')
                 next();
             return true;
         };
-        // 0. 变更类插件 API 的跨站写请求防御（先于回环放行，且运行在上下文虚拟化改写之前，
-        //    保证 Origin / Sec-Fetch-Site 为浏览器原始值）：本机回环虽免认证，但恶意网页驱使
-        //    浏览器发起的跨站写请求（drive-by）必然携带跨站信号，在此直接拒绝。
-        const pathname = (req.url || '').split('?')[0];
-        if (pathname.startsWith(MUTATION_API_PREFIX) &&
-            req.method !== 'GET' &&
-            req.method !== 'HEAD' &&
-            hasCrossSiteSignal(req)) {
+        // 0. 全局非 GET/HEAD 写请求的跨站防御（在上下文虚拟化改写之前运行，
+        //    保证 Origin / Sec-Fetch-Site 为浏览器原始值）：
+        //    不论回环还是外部，恶意跨站写请求（Local Drive-by / CSWSH）直接 403 阻断。
+        if (req.method !== 'GET' && req.method !== 'HEAD' && hasCrossSiteSignal(req)) {
             res.writeHead(403, {
                 'Content-Type': 'application/json; charset=utf-8',
                 'Cache-Control': 'no-cache, no-store, must-revalidate',
             });
             res.end(JSON.stringify({
                 error: 'Forbidden',
-                message: '已拦截来自其他网站的跨站写请求。',
+                message: '已拦截来自其他网站的跨站写请求 (Cross-Site Request Blocked)。',
             }));
             return false;
         }
         // 1. 本机 127.0.0.1 回环无条件放行（保证本机 PC 始终可用）
         if (isLoopbackRequest(req)) {
-            return pass();
+            return pass('loopback');
+        }
+        // 1.5 非回环请求必须先通过 Host 白名单（DNS-Rebinding / 恶意 Host 防御）。
+        // GatewayServer 在转发前已经用自己的 Host 白名单校验过，并打上 __dsh_rm_host_allowed__，
+        // 这里避免对同一请求重复校验（尤其是 gatewayHost 为自定义域名时）。
+        if (req.headers.host &&
+            !req.__dsh_rm_host_allowed__ &&
+            !isTrustedHost(req.headers.host, store)) {
+            res.writeHead(403, {
+                'Content-Type': 'application/json; charset=utf-8',
+                'Cache-Control': 'no-cache, no-store, must-revalidate',
+            });
+            res.end(JSON.stringify({
+                error: 'Forbidden',
+                message: '未受信任的 Host。若使用 Tailscale MagicDNS 或自定义域名，请在 trustedHosts 中声明。',
+            }));
+            return false;
         }
         // 2. 公开登录页面与认证接口放行
         if (isPublicPath(req.url)) {
-            return pass();
+            return pass('public');
         }
         const clientIp = getClientIp(req);
         const options = store.getOptions();
+        // 反向代理同样可能位于 LAN/Tailscale 网段；若携带 Forwarded 头，说明是代理而非
+        // 真实客户端，不能再按 allowLan/allowTailscale 免密放行，否则外部用户可借代理绕过认证。
+        const hasForwardedHeaders = Boolean(req.headers['x-forwarded-for'] ||
+            req.headers['x-forwarded-host'] ||
+            req.headers['x-forwarded-proto'] ||
+            req.headers['x-real-ip']);
         // 3. 如果开启了 Tailscale 私网免密直连，且客户端来源是 Tailscale 虚拟网段，自动归因并放行
-        if (options.allowTailscale && isTailscaleIp(clientIp)) {
+        if (!hasForwardedHeaders && options.allowTailscale && isTailscaleIp(clientIp)) {
             const ua = req.headers['user-agent'] || '';
             store.registerBypassDevice(clientIp, ua, 'Tailscale');
-            return pass();
+            return pass('bypass-tailscale');
         }
         // 4. 如果开启了局域网 LAN 免密直连，且客户端来源是局域网私有网段 (10.x / 172.16-31.x / 192.168.x)，自动归因并放行
-        if (options.allowLan && isLanIp(clientIp)) {
+        if (!hasForwardedHeaders && options.allowLan && isLanIp(clientIp)) {
             const ua = req.headers['user-agent'] || '';
             store.registerBypassDevice(clientIp, ua, 'LAN');
-            return pass();
+            return pass('bypass-lan');
         }
         // 5. 检查是否携带有效的授权会话 Token (Cookie / Header / URL Token)
         const token = store.extractTokenFromRequest(req);
         if (token && store.validateToken(token, clientIp)) {
-            return pass();
+            return pass('token');
         }
         // 5. 未授权访问拦截处理：
         // 只有主文档请求（GET 根路径或请求头明确包含 text/html）才 302 重定向到 /auth 登录页，子资源与 API 请求一律返回 401

package/lib/auth/tailscale.d.ts

@@ -8,7 +8,16 @@ export declare function isTailscaleIp(rawIp?: string): boolean;
  */
 export declare function isLanIp(rawIp?: string): boolean;
 /**
- * 提取请求的客户端真实 IP（基于底层 Socket 连接，防止外部伪造 X-Forwarded-For，且兼容虚拟化场景）
+ * 获取底层物理连接的真实 Socket IP（严格基于底座物理连接，绝不受任何请求头篡改，仅去除 IPv6 映射前缀）
+ * 专用于底座与网关内部的物理信任边界判定（如 isLoopbackSocket）
+ */
+export declare function getPhysicalSocketIp(req: {
+    socket?: {
+        remoteAddress?: string;
+    };
+}): string;
+/**
+ * 提取请求的物理 Socket 来源 IP（兼容历史接口，保持物理连接语义）
  */
 export declare function getClientIp(req: {
     socket?: {
@@ -26,7 +35,20 @@ export declare function getLocalTailscaleIp(): string | null;
  */
 export declare function getLocalLanIp(): string | null;
 /**
- * 获取本机所有可用的网络 IP
+ * 设置模拟网络网卡 IP（仅供单测模拟切换 Wi-Fi / 新网卡场景）
+ */
+export declare function setMockNetworkIps(mockList: {
+    name: string;
+    ip: string;
+    isTailscale: boolean;
+    isLan: boolean;
+}[] | null): void;
+/**
+ * 清除网络网卡 IP 缓存
+ */
+export declare function clearNetworkIpCache(): void;
+/**
+ * 获取本机所有可用的网络 IP（带 2 秒短缓存，兼顾动态切换 Wi-Fi 响应与高频访问性能）
  */
 export declare function getAllNetworkIps(): {
     name: string;

package/lib/auth/tailscale.js

@@ -42,11 +42,19 @@ export function isLanIp(rawIp) {
     return false;
 }
 /**
- * 提取请求的客户端真实 IP（基于底层 Socket 连接，防止外部伪造 X-Forwarded-For，且兼容虚拟化场景）
+ * 获取底层物理连接的真实 Socket IP（严格基于底座物理连接，绝不受任何请求头篡改，仅去除 IPv6 映射前缀）
+ * 专用于底座与网关内部的物理信任边界判定（如 isLoopbackSocket）
+ */
+export function getPhysicalSocketIp(req) {
+    const raw = req?.socket?.remoteAddress;
+    return raw ? raw.replace(/^::ffff:/, '').trim() : '127.0.0.1';
+}
+/**
+ * 提取请求的物理 Socket 来源 IP（兼容历史接口，保持物理连接语义）
  */
 export function getClientIp(req) {
     const realAddress = req.socket?.__dsh_real_remote_address__ || req.socket?.remoteAddress;
-    return realAddress?.replace(/^::ffff:/, '') || '127.0.0.1';
+    return realAddress?.replace(/^::ffff:/, '').trim() || '127.0.0.1';
 }
 /**
  * 获取当前本机的 Tailscale IP
@@ -103,10 +111,35 @@ export function getLocalLanIp() {
     catch { }
     return null;
 }
+let cachedNetworkIps = null;
+let cacheExpiresAt = 0;
+let mockNetworkIps = null;
+/**
+ * 设置模拟网络网卡 IP（仅供单测模拟切换 Wi-Fi / 新网卡场景）
+ */
+export function setMockNetworkIps(mockList) {
+    mockNetworkIps = mockList;
+    cachedNetworkIps = null;
+    cacheExpiresAt = 0;
+}
 /**
- * 获取本机所有可用的网络 IP
+ * 清除网络网卡 IP 缓存
+ */
+export function clearNetworkIpCache() {
+    cachedNetworkIps = null;
+    cacheExpiresAt = 0;
+}
+/**
+ * 获取本机所有可用的网络 IP（带 2 秒短缓存，兼顾动态切换 Wi-Fi 响应与高频访问性能）
  */
 export function getAllNetworkIps() {
+    if (mockNetworkIps) {
+        return [...mockNetworkIps];
+    }
+    const now = Date.now();
+    if (cachedNetworkIps && now < cacheExpiresAt) {
+        return cachedNetworkIps;
+    }
     const list = [];
     try {
         const interfaces = networkInterfaces();
@@ -124,5 +157,7 @@ export function getAllNetworkIps() {
         }
     }
     catch { }
+    cachedNetworkIps = list;
+    cacheExpiresAt = now + 2000;
     return list;
 }

package/lib/auth/token.d.ts

@@ -106,6 +106,10 @@ export interface SessionStoreOptions {
     maxFailedAttempts?: number;
     lockDurationMs?: number;
     maxVisitsPerMinute?: number;
+    gatewayPort?: number;
+    gatewayHost?: string;
+    mode?: 'auto' | 'gateway' | 'direct';
+    trustedHosts?: string[];
 }
 /**
  * 将 User-Agent 字符串解析为人类友好的设备名称
@@ -120,8 +124,26 @@ export declare class SessionStore extends EventEmitter {
     private debounceTimer;
     readonly persistPath: string;
     readonly settingsFilePath: string | null;
+    /** 网关运行时状态契约 */
+    private gatewayStatus;
     constructor(options?: SessionStoreOptions);
     getOptions(): Required<SessionStoreOptions>;
+    /** 设置网关当前生效的运行时参数与状态契约 */
+    setActiveGatewayInfo(mode: 'gateway' | 'direct', activePort: number, corePort: number, running?: boolean, error?: string | null): void;
+    /** 获取网关完整运行状态对象 (供 /api/remote-mobile/status 消费) */
+    getGatewayStatus(): {
+        mode: 'gateway' | 'direct';
+        running: boolean;
+        port: number;
+        corePort: number;
+        error: string | null;
+    };
+    /** 获取当前实际对外提供访问的模式 (gateway | direct) */
+    getActiveMode(): 'gateway' | 'direct';
+    /** 获取当前实际对外提供访问的端口 (3081 或 3080) */
+    getActivePort(): number;
+    /** 获取底层 DSH 本地核心端口 (通常为 3080) */
+    getCorePort(): number;
     hasSecret(): boolean;
     setSettingsMutator(mutator: (patch: Partial<SessionStoreOptions>) => void): void;
     updateOptions(newOpts: Partial<SessionStoreOptions>, syncToSettings?: boolean): void;

package/lib/auth/token.js

@@ -1,7 +1,7 @@
 import { randomBytes, randomInt } from 'node:crypto';
 import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync, unlinkSync, chmodSync, readdirSync } from 'node:fs';
 import { dirname, join } from 'node:path';
-import { homedir } from 'node:os';
+import { homedir, tmpdir } from 'node:os';
 import { EventEmitter } from 'node:events';
 import { hashSecret, verifySecretHash } from './crypto.js';
 import { isTailscaleIp, isLanIp } from './tailscale.js';
@@ -188,6 +188,15 @@ export function readPluginSettingsJson(filePath = SETTINGS_FILE) {
             result.lockDurationMs = data.lockDurationMs;
         if (typeof data.maxVisitsPerMinute === 'number' && data.maxVisitsPerMinute > 0)
             result.maxVisitsPerMinute = data.maxVisitsPerMinute;
+        if (typeof data.gatewayPort === 'number' && data.gatewayPort > 0)
+            result.gatewayPort = data.gatewayPort;
+        if (typeof data.gatewayHost === 'string' && data.gatewayHost)
+            result.gatewayHost = data.gatewayHost;
+        if (data.mode === 'auto' || data.mode === 'gateway' || data.mode === 'direct')
+            result.mode = data.mode;
+        if (Array.isArray(data.trustedHosts)) {
+            result.trustedHosts = data.trustedHosts.filter((h) => typeof h === 'string' && h.trim());
+        }
         return result;
     }
     catch {
@@ -211,6 +220,10 @@ export function writePluginSettingsJson(options, filePath = SETTINGS_FILE) {
             maxFailedAttempts: options.maxFailedAttempts || 5,
             lockDurationMs: options.lockDurationMs || 900000,
             maxVisitsPerMinute: options.maxVisitsPerMinute || 60,
+            gatewayPort: options.gatewayPort || 3081,
+            gatewayHost: options.gatewayHost || '0.0.0.0',
+            mode: options.mode || 'auto',
+            trustedHosts: Array.isArray(options.trustedHosts) ? options.trustedHosts : [],
         };
         writeFileSync(tmpPath, JSON.stringify(payload, null, 2), { encoding: 'utf8', mode: 0o600 });
         renameSync(tmpPath, filePath);
@@ -277,6 +290,10 @@ export function resolveInitialStoreOptions(explicit = {}, own = null, legacy = {
         maxFailedAttempts: merged.maxFailedAttempts ?? 5,
         lockDurationMs: merged.lockDurationMs ?? 15 * 60 * 1000,
         maxVisitsPerMinute: merged.maxVisitsPerMinute ?? 60,
+        gatewayPort: merged.gatewayPort ?? 3081,
+        gatewayHost: merged.gatewayHost ?? '0.0.0.0',
+        mode: merged.mode ?? 'auto',
+        trustedHosts: Array.isArray(merged.trustedHosts) ? merged.trustedHosts : [],
     };
 }
 /**
@@ -334,6 +351,14 @@ export class SessionStore extends EventEmitter {
     debounceTimer = null;
     persistPath;
     settingsFilePath;
+    /** 网关运行时状态契约 */
+    gatewayStatus = {
+        mode: 'direct',
+        running: true,
+        port: 3080,
+        corePort: 3080,
+        error: null,
+    };
     constructor(options = {}) {
         super();
         this.setMaxListeners(100);
@@ -348,7 +373,12 @@ export class SessionStore extends EventEmitter {
         const ownOpts = isTestEnv ? {} : (hasOwnSettings ? readPluginSettingsJson(SETTINGS_FILE) : null);
         const legacyOpts = isTestEnv || hasOwnSettings ? {} : readLegacyDshSettings();
         this.options = resolveInitialStoreOptions(options, ownOpts, legacyOpts);
-        this.persistPath = this.options.devicesFile;
+        // 测试隔离必须同时覆盖 devices.json，而不仅是 settings.json。
+        // 否则测试里的 store.verify() 会持续写入用户真实的 ~/.dsh/remote-mobile/devices.json。
+        const testPersistPath = isTestEnv && (!options.devicesFile || options.devicesFile === DEFAULT_PERSIST_FILE)
+            ? join(tmpdir(), `dsh-rm-test-devices-${process.pid}-${randomBytes(6).toString('hex')}.json`)
+            : this.options.devicesFile;
+        this.persistPath = testPersistPath;
         // 首次启动迁移：自有配置不存在但旧 settings.yaml / settings.yaml.imported 中仍有配置时，
         // 落盘一次到自有 settings.json，把旧配置（如长期密码哈希、限频）救回。
         if (!isTestEnv && !hasOwnSettings && Object.keys(legacyOpts).length > 0) {
@@ -360,6 +390,32 @@ export class SessionStore extends EventEmitter {
     getOptions() {
         return { ...this.options };
     }
+    /** 设置网关当前生效的运行时参数与状态契约 */
+    setActiveGatewayInfo(mode, activePort, corePort, running = true, error = null) {
+        this.gatewayStatus = {
+            mode,
+            running,
+            port: activePort,
+            corePort,
+            error,
+        };
+    }
+    /** 获取网关完整运行状态对象 (供 /api/remote-mobile/status 消费) */
+    getGatewayStatus() {
+        return { ...this.gatewayStatus };
+    }
+    /** 获取当前实际对外提供访问的模式 (gateway | direct) */
+    getActiveMode() {
+        return this.gatewayStatus.mode;
+    }
+    /** 获取当前实际对外提供访问的端口 (3081 或 3080) */
+    getActivePort() {
+        return this.gatewayStatus.port;
+    }
+    /** 获取底层 DSH 本地核心端口 (通常为 3080) */
+    getCorePort() {
+        return this.gatewayStatus.corePort;
+    }
     hasSecret() {
         return Boolean(this.options.secretHash || this.options.secret);
     }