@yezack/dsh-remote-mobile 1.9.2 → 1.10.2

package/lib/gateway/detector.d.ts

@@ -0,0 +1,40 @@
+/**
+ * DSH 底座运行模式探测器
+ *
+ * 负责检测宿主 DSH WebServer 当前的网络暴露姿态：
+ * 1. 默认使用代理模式 ('proxy')：宿主仅监听本地回环地址 (127.0.0.1 / localhost)，
+ *    由插件启动独立安全接入代理 (0.0.0.0:3081)；
+ * 2. 若宿主已监听 0.0.0.0 或具体的外部网卡 IP，则外部网络可直连，
+ *    自动回退直连模式 ('direct')，沿用原生的 Hook 拦截机制，不额外占用端口；
+ * 3. 用户可通过 options.mode ('proxy' | 'direct') 显式选择；不再提供 auto 模式。
+ */
+export type ProxyMode = 'proxy' | 'direct';
+export interface ServerModeDetectionResult {
+    /** 最终生效的运行模式 */
+    mode: ProxyMode;
+    /** 底座核心监听的 host（未配置时默认 127.0.0.1，在 proxy 模式下已安全规范化为回环 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（仅在 proxy 模式下作为 proxy target 使用）
+ * 将通配或 localhost 规范化为明确的回环 IP，消除 Node 18+ 的 Happy Eyeballs IPv6 优先解析 502 隐患
+ */
+export declare function normalizeGatewayTargetHost(host: string): string;
+/**
+ * 探测底座运行姿态并裁决插件的工作模式
+ *
+ * @param ctx Cordis 上下文（含 webServer / webStartup 等服务）
+ * @param configuredMode 用户显式配置的运行模式 ('proxy' | 'direct')
+ * @param defaultCorePort 底座默认核心端口（3080）
+ */
+export declare function detectServerMode(ctx: any, configuredMode?: 'proxy' | 'direct', defaultCorePort?: number): ServerModeDetectionResult;

package/lib/gateway/detector.js

@@ -0,0 +1,75 @@
+/**
+ * DSH 底座运行模式探测器
+ *
+ * 负责检测宿主 DSH WebServer 当前的网络暴露姿态：
+ * 1. 默认使用代理模式 ('proxy')：宿主仅监听本地回环地址 (127.0.0.1 / localhost)，
+ *    由插件启动独立安全接入代理 (0.0.0.0:3081)；
+ * 2. 若宿主已监听 0.0.0.0 或具体的外部网卡 IP，则外部网络可直连，
+ *    自动回退直连模式 ('direct')，沿用原生的 Hook 拦截机制，不额外占用端口；
+ * 3. 用户可通过 options.mode ('proxy' | 'direct') 显式选择；不再提供 auto 模式。
+ */
+/**
+ * 判断指定 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（仅在 proxy 模式下作为 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 用户显式配置的运行模式 ('proxy' | 'direct')
+ * @param defaultCorePort 底座默认核心端口（3080）
+ */
+export function detectServerMode(ctx, configuredMode = 'proxy', 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);
+    // proxy 是默认模式，但只在核心回环时成立；核心已对外监听时回退 direct，
+    // 以兼容旧版 webserver 配置或用户显式绑定的具体网卡 IP。
+    const finalMode = configuredMode === 'direct' || !isLoopback ? 'direct' : 'proxy';
+    // 仅对最终生效的 proxy 模式的目标核心地址执行 proxyTarget 规范化
+    const coreHost = finalMode === 'proxy' ? normalizeGatewayTargetHost(rawCoreHost) : rawCoreHost;
+    return {
+        mode: finalMode,
+        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;
+}