dsh-remote-mobile 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,178 @@
+# dsh-remote-mobile
+
+[English Documentation](./README_EN.md) | 简体中文
+
+`dsh-remote-mobile` 是专为 DeepSeek Hub (DSH) 设计的远程与移动端安全接入插件。
+
+DSH 核心服务默认仅允许本地回环地址（`127.0.0.1`）访问 Web 界面。本项目通过门禁中间件与请求上下文虚拟化机制，安全地开放了 Tailscale 虚拟局域网以及本地局域网（LAN）访问能力，并提供扫码配对、长期密码认证、防暴力破解限频、落盘持久化和 SSE 实时状态推送。
+
+---
+
+## 🌟 主要功能
+
+### 1. 网络接入支持
+- **Tailscale 虚拟私网**：自动识别本机的 Tailscale IP（`100.64.0.0/10` CGNAT 网段），生成专属访问二维码，支持端到端加密免密直连选项。
+- **局域网 (LAN)**：自动识别 RFC 1918 私有 IP（如 `192.168.x.x`、`10.x.x.x`、`172.16-31.x.x`），提供独立的局域网访问二维码与高危醒目警示配置。
+- **二维码快速配对**：支持手机相机或微信扫码直接打开登录页面。
+
+### 2. 多重认证机制
+- **动态配对码**：生成 6 位短期配对码（5 分钟有效，一次性消费），手机扫码输入后换取 365 天有效期的认证 Cookie。
+- **长期访问密码**：支持设置访问密码（需包含字母与数字，长度不小于 6 位），验证成功后同样派发 365 天长效 Cookie。
+- **免密直连模式**：可针对 Tailscale 或局域网环境单独开启免密直连。关闭免密后会自动清理临时设备凭证并重置状态。
+- **设备会话管理**：实时查看已连接设备的类型、操作系统、浏览器、来源 IP 及最近活跃时间，支持单设备注销与一键全部踢出。
+
+### 3. 企业级安全防护
+- **传输层加密**：登录认证接口支持 RSA 密钥加密（RSA-OAEP-SHA256 与 PKCS#1 v1.5 兼容），密文在客户端加密后再通过网络传输。
+- **慢哈希存储**：服务端采用 `scrypt` 加盐慢哈希算法（`scrypt:${salt}:${hash}`）对密码进行落盘存储，比对过程采用 `crypto.timingSafeEqual` 恒定时间比对以防范时序侧信道攻击。
+- **防暴力破解与限频**：
+  - 连续输错 5 次凭证自动锁定该 IP 15 分钟，拦截后续验证请求并返回 HTTP 429；
+  - 滑动窗口限频（默认 60 次/分钟），防止高频刷量；
+  - 访问审计与锁定状态持久化保存，服务重启后自动恢复；
+  - 支持管理员在面板中手动一键解除 IP 锁定。
+- **请求头安全**：仅信任底层 Socket 真实连接地址，防范 `X-Forwarded-For` 伪造。
+
+### 4. 实时状态同步与国际化支持
+- **SSE 事件通道**：基于 Server-Sent Events 实现新设备配对、重连上线、会话撤销及安全告警的实时通知，无需前端轮询。
+- **全界面中英文双语自适应**：根据 DSH 语言偏好设置与浏览器语言，动态自适应中英文面板、提示及手机端登录界面。
+- **非 HTTPS 兼容补丁**：自动向 HTML 页面注入 `crypto.randomUUID` Polyfill，解决部分移动端浏览器在 HTTP 非安全上下文下缺少原生 API 的问题。
+
+---
+
+## 🛠️ 安装与前置配置
+
+### 步骤 1：安装插件
+
+#### 方式 1：通过 DSH 命令行一键安装（推荐）
+
+使用 DSH 内置的插件管理工具直接从 npm 官方仓库安装到 web profile：
+
+```bash
+dsh plugin --profile web add dsh-remote-mobile
+```
+
+#### 方式 2：通过 Web 设置页「插件管理」图形化安装
+
+在浏览器打开 DSH Web 控制台：
+1. 点击左下角 **设置 ⚙️ -> 插件**；
+2. 切换到顶部的 **「插件管理」** Tab；
+3. 在输入框中输入 npm 包名 **`dsh-remote-mobile`**，点击 **「安装」**；
+4. 安装完成后重启 DSH 即可生效。
+
+#### 方式 3：手动在 Profile 目录中通过包管理器安装
+
+```bash
+# 1. 进入 DSH Web Profile 目录
+cd ~/.dsh/profiles/web
+
+# 2. 通过 pnpm 安装
+pnpm add dsh-remote-mobile
+
+# 3. 检查 ~/.dsh/profiles/web/package.json
+# 确保 dsh.profile.bundles 数组中已包含 "dsh-remote-mobile"
+```
+
+#### 方式 4：本地开发与源码安装
+
+```bash
+# 1. 克隆或下载源码至本地目录
+cd ~/Myfile/www-self/dsh-remote-mobile
+
+# 2. 安装依赖并编译打包
+npm install
+npm run build && npm test && npm pack
+
+# 3. 在 DSH 中以本地包形式安装
+cd ~/.dsh/profiles/web
+pnpm add /path/to/dsh-remote-mobile/dsh-remote-mobile-1.0.0.tgz
+```
+
+---
+
+### 步骤 2：开放网络监听配置（前置必配）
+
+由于 DSH 默认出于安全考虑仅监听 `127.0.0.1`（本地回环），为了使 Tailscale 私网或局域网设备能够连通，请在 `~/.dsh/profiles/web/cordis.patch.yml` 中确保包含以下配置：
+
+```yaml
+# 1. 覆盖 webserver 配置监听 0.0.0.0:3080（必选：允许接收外部连接）
+- id: webserver
+  name: '@deepseek-ai/dsh-host-webserver'
+  inject: [webStartup]
+  config:
+    host: '0.0.0.0'
+    port: 3080
+
+# 2. 禁用 @linxin666/dsh-web-ui-all 全家桶自带的远程插件（必选：防止路由冲突与界面覆盖）
+- id: web-ui-remote-web-ui
+  disabled: true
+```
+
+> **💡 说明**：插件自身的注册已由 DSH Bundle 自动处理，**无需**在 `cordis.patch.yml` 中额外添加 `id: remote-mobile`。
+
+---
+
+### 步骤 3：启动服务
+
+```bash
+dsh web
+```
+
+启动后，在 PC 端浏览器打开 `http://127.0.0.1:3080`，进入 **设置 ⚙️ -> 远程与移动端 (Remote & Mobile)** 即可查看配对二维码或配置访问密码。
+
+---
+
+## ⚙️ 配置项说明
+
+在 `~/.dsh/settings.yaml` 中可配置插件参数（**推荐直接在 Web 面板中可视化调整**，修改后自动写回持久化）：
+
+```yaml
+dsh-remote-mobile:
+  # 免密直连开关
+  allowTailscale: true        # boolean，默认 false：Tailscale 节点访问是否免密
+  allowLan: false             # boolean，默认 false：局域网 (Wi-Fi) 设备访问是否免密
+
+  # 长期访问密码哈希（在面板中输入明文会自动生成加盐哈希保存）
+  secretHash: ''              # string，默认空
+
+  # 全局高级安全防护参数
+  maxVisitsPerMinute: 60      # number，默认 60：单 IP 每分钟打开 /auth 页面最大允许次数
+  maxFailedAttempts: 5        # number，默认 5：密码连续输错阈值
+  lockDurationMs: 900000      # number，默认 900000 (15分钟)：IP 锁定持续时间（毫秒）
+```
+
+| 配置项 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| `allowTailscale` | `boolean` | `false` | 是否允许 Tailscale 私网 IP 免密访问 |
+| `allowLan` | `boolean` | `false` | 是否允许局域网私有 IP 免密访问（高危警示） |
+| `secretHash` | `string` | `""` | 长期密码的 scrypt 加盐哈希值 |
+| `maxVisitsPerMinute` | `number` | `60` | 单 IP 每分钟最大访问登录页次数 |
+| `maxFailedAttempts` | `number` | `5` | 连续认证失败最大次数（达到后自动封锁 IP） |
+| `lockDurationMs` | `number` | `900000` | 触发防暴破后的 IP 锁定时间（毫秒） |
+
+---
+
+## 📂 本地文件存储位置
+
+- **设备会话与安全审计数据**：`~/.dsh/remote-mobile/devices.json`
+- **RSA 传输加密密钥对**：`~/.dsh/remote-mobile/rsa-keys.json`（权限模式为 `0600`，首次启动自动就地生成）
+
+---
+
+## 🔒 安全建议
+
+1. **局域网免密风险**：若在公共 Wi-Fi、咖啡厅或共享网络环境下使用，**严禁开启 `allowLan`（局域网免密直连）**。
+2. **Tailscale 推荐**：建议优先配合 Tailscale 虚拟专用网络使用，既能保障公网不可达，又能获得端到端加密传输保障。
+3. **密码复杂度**：若使用长期密码，建议设置包含字母与数字且 6 位以上的高强度密码。
+
+---
+
+## 🗑️ 卸载插件
+
+```bash
+dsh plugin --profile web remove dsh-remote-mobile
+```
+
+---
+
+## 📄 开源许可
+
+[MIT License](./LICENSE)

package/README_EN.md

@@ -0,0 +1,178 @@
+# dsh-remote-mobile
+
+English Documentation | [简体中文](./README.md)
+
+`dsh-remote-mobile` is a remote and mobile security access plugin tailored for DeepSeek Hub (DSH).
+
+By default, the DSH core service restricts Web UI access to localhost (`127.0.0.1`). This project safely enables Tailscale VPN and Local Area Network (LAN/Wi-Fi) remote connectivity using a custom authentication gate and context virtualization. It features QR code pairing, persistent passwords, brute-force rate-limiting, local data persistence, and realtime SSE push notifications.
+
+---
+
+## 🌟 Key Features
+
+### 1. Network Connectivity
+- **Tailscale Virtual Private Network**: Automatically detects Tailscale CGNAT IPs (`100.64.0.0/10`), generates a dedicated access QR code, and offers an end-to-end encrypted passwordless bypass option.
+- **Local Area Network (LAN / Wi-Fi)**: Automatically detects RFC 1918 private IPs (`192.168.x.x`, `10.x.x.x`, `172.16-31.x.x`), provides an independent LAN QR code, and includes high-risk visual safety warnings.
+- **Quick QR Pairing**: Direct scanning with mobile camera or WeChat to open the authorization portal.
+
+### 2. Multi-Tiered Authentication
+- **Dynamic 6-Digit Code**: Generates temporary one-time pairing codes (valid for 5 minutes). Entering it on mobile grants a 365-day persistent session cookie.
+- **Persistent Password (Secret)**: Set a custom password (letters + numbers, 6+ chars) to gain persistent authentication on any mobile device.
+- **Passwordless Bypass Mode**: Selectively enable bypass for Tailscale or LAN. Turning off bypass automatically purges temporary credentials and resets device statuses.
+- **Device Management**: View connected device types, OS, browsers, IP addresses, and last seen timestamps. Supports individual device revocation and one-click global purge.
+
+### 3. Enterprise-Grade Security
+- **Transport Layer Encryption**: Login verification supports RSA encryption (RSA-OAEP-SHA256 & PKCS#1 v1.5 compatible). Passwords and codes are encrypted on the browser before network transit.
+- **Slow Salted Hashing**: Stores passwords locally using `scrypt` slow hashing (`scrypt:${salt}:${hash}`). Employs `crypto.timingSafeEqual` for constant-time comparisons against timing attacks.
+- **Brute-Force & Rate-Limiting Defense**:
+  - Automatically locks out an IP for 15 minutes after 5 consecutive failed attempts (returns HTTP 429);
+  - Sliding-window rate limiter (default: 60 requests/min) to prevent high-frequency abuse;
+  - Audit logs and lockout states persist across DSH restarts;
+  - Manual one-click IP unlock support from the management UI.
+- **Socket-Level Verification**: Only inspects low-level socket remote addresses, defending against forged `X-Forwarded-For` headers.
+
+### 4. Realtime Push & Full Internationalization (i18n)
+- **Server-Sent Events (SSE)**: Delivers instant push notifications for new device pairing, reconnections, revocations, and security alerts without client polling.
+- **Bilingual Adaptive UI**: Dynamically switches between English and Simplified Chinese based on DSH preferences and browser settings.
+- **Non-HTTPS Crypto Polyfill**: Injects a lightweight `crypto.randomUUID` Polyfill into HTML headers to support mobile browsers running in HTTP non-secure contexts.
+
+---
+
+## 🛠️ Installation & Setup
+
+### Step 1: Install the Plugin
+
+#### Option 1: One-Click via DSH CLI (Recommended)
+
+Use the DSH built-in plugin manager to install from npm directly into the web profile:
+
+```bash
+dsh plugin --profile web add dsh-remote-mobile
+```
+
+#### Option 2: Visual Install via Web Settings (Plugin Manager)
+
+Open the DSH Web UI in your browser:
+1. Navigate to **Settings ⚙️ -> Plugins**;
+2. Switch to the **"Plugin Manager"** (插件管理) tab at the top;
+3. Enter the npm package name **`dsh-remote-mobile`** in the input field and click **"Install"** (安装);
+4. Restart DSH to activate the plugin.
+
+#### Option 3: Manual Installation via Package Manager in Profile Directory
+
+```bash
+# 1. Enter the DSH Web Profile directory
+cd ~/.dsh/profiles/web
+
+# 2. Install via pnpm
+pnpm add dsh-remote-mobile
+
+# 3. Check ~/.dsh/profiles/web/package.json
+# Ensure "dsh-remote-mobile" is present in dsh.profile.bundles
+```
+
+#### Option 4: Local Development & Source Installation
+
+```bash
+# 1. Clone or download the repository locally
+cd ~/Myfile/www-self/dsh-remote-mobile
+
+# 2. Install dependencies, build and pack
+npm install
+npm run build && npm test && npm pack
+
+# 3. Install the packed tarball into DSH
+cd ~/.dsh/profiles/web
+pnpm add /path/to/dsh-remote-mobile/dsh-remote-mobile-1.0.0.tgz
+```
+
+---
+
+### Step 2: Configure Network Binding (Required)
+
+Since DSH defaults to listening only on `127.0.0.1` (localhost), you need to bind the webserver to `0.0.0.0` in `~/.dsh/profiles/web/cordis.patch.yml` to accept connections from Tailscale or LAN:
+
+```yaml
+# 1. Override webserver to listen on 0.0.0.0:3080 (Required for remote access)
+- id: webserver
+  name: '@deepseek-ai/dsh-host-webserver'
+  inject: [webStartup]
+  config:
+    host: '0.0.0.0'
+    port: 3080
+
+# 2. Disable the built-in remote plugin from @linxin666/dsh-web-ui-all (Required: prevent route conflicts and UI overlaps)
+- id: web-ui-remote-web-ui
+  disabled: true
+```
+
+> **💡 Note**: The plugin is automatically registered by the DSH Bundle loader. You **do not** need to add `id: remote-mobile` to `cordis.patch.yml`.
+
+---
+
+### Step 3: Start DSH
+
+```bash
+dsh web
+```
+
+Open `http://127.0.0.1:3080` in your PC browser and navigate to **Settings ⚙️ -> Remote & Mobile** to configure pairing.
+
+---
+
+## ⚙️ Configuration
+
+Options can be customized in `~/.dsh/settings.yaml` (or interactively configured via **Settings ⚙️ -> Remote & Mobile**):
+
+```yaml
+dsh-remote-mobile:
+  # Bypass options
+  allowTailscale: true        # boolean, default: false - Allow passwordless Tailscale access
+  allowLan: false             # boolean, default: false - Allow passwordless LAN (Wi-Fi) access
+
+  # Persistent password hash (auto-generated when saved in the UI)
+  secretHash: ''              # string, default: empty
+
+  # Advanced security policies
+  maxVisitsPerMinute: 60      # number, default: 60 - Max visits to /auth per minute per IP
+  maxFailedAttempts: 5        # number, default: 5 - Lockout threshold for wrong passwords
+  lockDurationMs: 900000      # number, default: 900000 (15 min) - Lockout duration in ms
+```
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `allowTailscale` | `boolean` | `false` | Enable passwordless access for Tailscale nodes |
+| `allowLan` | `boolean` | `false` | Enable passwordless access for local Wi-Fi devices (High Risk) |
+| `secretHash` | `string` | `""` | Salted scrypt hash for persistent password |
+| `maxVisitsPerMinute` | `number` | `60` | Max /auth page visits per minute per IP |
+| `maxFailedAttempts` | `number` | `5` | Maximum failed attempts before IP lockout |
+| `lockDurationMs` | `number` | `900000` | IP lockout duration (ms) |
+
+---
+
+## 📂 Local Storage Paths
+
+- **Device Sessions & Security Audit**: `~/.dsh/remote-mobile/devices.json`
+- **RSA Transport Keypair**: `~/.dsh/remote-mobile/rsa-keys.json` (auto-generated on first launch with `0600` permissions)
+
+---
+
+## 🔒 Security Best Practices
+
+1. **LAN Bypass Risk**: **NEVER enable `allowLan`** on public Wi-Fi, cafes, hotels, or untrusted shared networks.
+2. **Tailscale Recommended**: Prioritize Tailscale for encrypted private access without exposing ports to the public internet.
+3. **Password Strength**: When setting a persistent password, choose a strong alphanumeric combination (6+ characters).
+
+---
+
+## 🗑️ Uninstalling
+
+```bash
+dsh plugin --profile web remove dsh-remote-mobile
+```
+
+---
+
+## 📄 License
+
+[MIT License](./LICENSE)

package/cordis.patch.yml

@@ -0,0 +1,4 @@
+- insert:
+    - id: remote-mobile
+      name: 'dsh-remote-mobile'
+

package/lib/auth/crypto.d.ts

@@ -0,0 +1,24 @@
+export declare const RSA_KEY_FILE: string;
+/**
+ * 获取服务端的持久化 RSA 公钥 (PEM 格式)
+ */
+export declare function getPublicKeyPem(): string;
+/**
+ * 使用 RSA 私钥解密客户端发来的 Base64 密文 (多填充算法自适应兼容)
+ */
+export declare function decryptWithPrivateKey(encryptedBase64: string): string;
+/**
+ * 校验长期密码强度：必须 >= 6 位且包含字母与数字
+ */
+export declare function validateSecretStrength(secret: string): {
+    valid: boolean;
+    reason?: string;
+};
+/**
+ * 将明文密码转换为加盐哈希（采用 scrypt 慢哈希算法，杜绝彩虹表与 GPU 暴力破解）
+ */
+export declare function hashSecret(plainSecret: string): string;
+/**
+ * 比对明文密码与存储的加盐哈希（恒定时间比对，抵御时序侧信道攻击）
+ */
+export declare function verifySecretHash(plainSecret: string, storedHashOrPlain: string): boolean;

package/lib/auth/crypto.js

@@ -0,0 +1,144 @@
+import { generateKeyPairSync, privateDecrypt, constants, randomBytes, createHash, scryptSync, timingSafeEqual } from 'node:crypto';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { homedir } from 'node:os';
+export const RSA_KEY_FILE = `${homedir()}/.dsh/remote-mobile/rsa-keys.json`;
+let keyPair;
+function loadOrCreateKeyPair() {
+    try {
+        if (existsSync(RSA_KEY_FILE)) {
+            const content = readFileSync(RSA_KEY_FILE, 'utf8');
+            const data = JSON.parse(content);
+            if (data && data.publicKey && data.privateKey) {
+                return data;
+            }
+        }
+    }
+    catch { }
+    const pair = generateKeyPairSync('rsa', {
+        modulusLength: 2048,
+        publicKeyEncoding: {
+            type: 'spki',
+            format: 'pem',
+        },
+        privateKeyEncoding: {
+            type: 'pkcs8',
+            format: 'pem',
+        },
+    });
+    try {
+        mkdirSync(dirname(RSA_KEY_FILE), { recursive: true });
+        writeFileSync(RSA_KEY_FILE, JSON.stringify(pair, null, 2), { encoding: 'utf8', mode: 0o600 });
+    }
+    catch { }
+    return pair;
+}
+keyPair = loadOrCreateKeyPair();
+/**
+ * 获取服务端的持久化 RSA 公钥 (PEM 格式)
+ */
+export function getPublicKeyPem() {
+    return keyPair.publicKey;
+}
+/**
+ * 使用 RSA 私钥解密客户端发来的 Base64 密文 (多填充算法自适应兼容)
+ */
+export function decryptWithPrivateKey(encryptedBase64) {
+    if (!encryptedBase64)
+        return '';
+    try {
+        const buffer = Buffer.from(encryptedBase64, 'base64');
+        // 2048 位 RSA 密文标准长度必须为 256 字节
+        if (buffer.length !== 256)
+            return '';
+        // 1. 优先尝试 RSA-OAEP SHA-256 (Web Crypto 规范标准)
+        try {
+            const decrypted = privateDecrypt({
+                key: keyPair.privateKey,
+                padding: constants.RSA_PKCS1_OAEP_PADDING,
+                oaepHash: 'sha256',
+            }, buffer);
+            return decrypted.toString('utf8');
+        }
+        catch { }
+        // 2. 尝试 RSA-OAEP SHA-1 兼容模式
+        try {
+            const decrypted = privateDecrypt({
+                key: keyPair.privateKey,
+                padding: constants.RSA_PKCS1_OAEP_PADDING,
+                oaepHash: 'sha1',
+            }, buffer);
+            return decrypted.toString('utf8');
+        }
+        catch { }
+        // 3. 尝试 PKCS#1 v1.5 填充兼容模式
+        try {
+            const decrypted = privateDecrypt({
+                key: keyPair.privateKey,
+                padding: constants.RSA_PKCS1_PADDING,
+            }, buffer);
+            return decrypted.toString('utf8');
+        }
+        catch { }
+    }
+    catch { }
+    return '';
+}
+/**
+ * 校验长期密码强度：必须 >= 6 位且包含字母与数字
+ */
+export function validateSecretStrength(secret) {
+    const trimmed = (secret || '').trim();
+    if (!trimmed)
+        return { valid: true }; // 允许留空（不设置长期密码）
+    if (trimmed.length < 6) {
+        return { valid: false, reason: '密码长度不能少于 6 位' };
+    }
+    const hasLetter = /[A-Za-z]/.test(trimmed);
+    const hasDigit = /\d/.test(trimmed);
+    if (!hasLetter || !hasDigit) {
+        return { valid: false, reason: '密码必须同时包含字母和数字组合' };
+    }
+    return { valid: true };
+}
+/**
+ * 将明文密码转换为加盐哈希（采用 scrypt 慢哈希算法，杜绝彩虹表与 GPU 暴力破解）
+ */
+export function hashSecret(plainSecret) {
+    if (!plainSecret)
+        return '';
+    const salt = randomBytes(16).toString('hex');
+    const hash = scryptSync(plainSecret, salt, 64).toString('hex');
+    return `scrypt:${salt}:${hash}`;
+}
+/**
+ * 比对明文密码与存储的加盐哈希（恒定时间比对，抵御时序侧信道攻击）
+ */
+export function verifySecretHash(plainSecret, storedHashOrPlain) {
+    if (!storedHashOrPlain || !plainSecret)
+        return false;
+    if (storedHashOrPlain.startsWith('scrypt:')) {
+        const parts = storedHashOrPlain.split(':');
+        if (parts.length !== 3)
+            return false;
+        const salt = parts[1];
+        const expectedHash = parts[2];
+        const actualHash = scryptSync(plainSecret, salt, 64).toString('hex');
+        if (actualHash.length !== expectedHash.length)
+            return false;
+        return timingSafeEqual(Buffer.from(actualHash, 'hex'), Buffer.from(expectedHash, 'hex'));
+    }
+    // 兼容老版本 sha256 存储
+    if (storedHashOrPlain.startsWith('sha256:')) {
+        const parts = storedHashOrPlain.split(':');
+        if (parts.length !== 3)
+            return false;
+        const salt = parts[1];
+        const expectedHash = parts[2];
+        const actualHash = createHash('sha256').update(plainSecret + ':' + salt).digest('hex');
+        if (actualHash.length !== expectedHash.length)
+            return false;
+        return timingSafeEqual(Buffer.from(actualHash, 'hex'), Buffer.from(expectedHash, 'hex'));
+    }
+    return false;
+}

package/lib/auth/gate.d.ts

@@ -0,0 +1,14 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { SessionStore } from './token.js';
+/**
+ * 判断请求是否来自本机回环
+ */
+export declare function isLoopbackRequest(req: IncomingMessage): boolean;
+/**
+ * 判断是否为无需鉴权的公开静态/登录路径
+ */
+export declare function isPublicPath(url?: string): boolean;
+/**
+ * 构造全局 HTTP & WebSocket 门禁拦截处理器
+ */
+export declare function createGlobalAuthGate(store: SessionStore): (req: IncomingMessage, res: ServerResponse, next?: () => void) => boolean;

package/lib/auth/gate.js

@@ -0,0 +1,87 @@
+import { isTailscaleIp, isLanIp, getClientIp } from './tailscale.js';
+/**
+ * 判断请求是否来自本机回环
+ */
+export function isLoopbackRequest(req) {
+    const ip = getClientIp(req);
+    return ip === '127.0.0.1' || ip === '::1' || ip === 'localhost';
+}
+/**
+ * 判断是否为无需鉴权的公开静态/登录路径
+ */
+export function isPublicPath(url = '') {
+    const pathname = url.split('?')[0];
+    if (pathname === '/auth')
+        return true;
+    if (pathname.startsWith('/api/remote-mobile/public-key'))
+        return true;
+    if (pathname.startsWith('/api/remote-mobile/verify'))
+        return true;
+    if (pathname.startsWith('/plugins/'))
+        return true;
+    if (pathname.startsWith('/assets/'))
+        return true;
+    if (pathname === '/favicon.ico')
+        return true;
+    return false;
+}
+/**
+ * 构造全局 HTTP & WebSocket 门禁拦截处理器
+ */
+export function createGlobalAuthGate(store) {
+    return function authGateMiddleware(req, res, next) {
+        const pass = () => {
+            if (typeof next === 'function')
+                next();
+            return true;
+        };
+        // 1. 本机 127.0.0.1 回环无条件放行（保证本机 PC 始终可用）
+        if (isLoopbackRequest(req)) {
+            return pass();
+        }
+        // 2. 公开登录页面与认证接口放行
+        if (isPublicPath(req.url)) {
+            return pass();
+        }
+        const clientIp = getClientIp(req);
+        const options = store.getOptions();
+        // 3. 如果开启了 Tailscale 私网免密直连，且客户端来源是 Tailscale 虚拟网段，自动归因并放行
+        if (options.allowTailscale && isTailscaleIp(clientIp)) {
+            const ua = req.headers['user-agent'] || '';
+            store.registerBypassDevice(clientIp, ua, 'Tailscale');
+            return pass();
+        }
+        // 4. 如果开启了局域网 LAN 免密直连，且客户端来源是局域网私有网段 (10.x / 172.16-31.x / 192.168.x)，自动归因并放行
+        if (options.allowLan && isLanIp(clientIp)) {
+            const ua = req.headers['user-agent'] || '';
+            store.registerBypassDevice(clientIp, ua, 'LAN');
+            return pass();
+        }
+        // 5. 检查是否携带有效的授权会话 Token (Cookie / Header / URL Token)
+        const token = store.extractTokenFromRequest(req);
+        if (token && store.validateToken(token, clientIp)) {
+            return pass();
+        }
+        // 5. 未授权访问拦截处理：
+        // 只有主文档请求（GET 根路径或请求头明确包含 text/html）才 302 重定向到 /auth 登录页，子资源与 API 请求一律返回 401
+        const accept = req.headers['accept'] || '';
+        const isHtmlRequest = req.method === 'GET' && (accept.includes('text/html') || req.url === '/' || req.url?.startsWith('/?'));
+        if (isHtmlRequest) {
+            res.writeHead(302, {
+                Location: '/auth',
+                'Cache-Control': 'no-cache, no-store, must-revalidate',
+            });
+            res.end();
+            return false;
+        }
+        res.writeHead(401, {
+            'Content-Type': 'application/json; charset=utf-8',
+            'Cache-Control': 'no-cache, no-store, must-revalidate',
+        });
+        res.end(JSON.stringify({
+            error: 'Unauthorized',
+            message: '设备未授权或会话已注销，请前往 /auth 重新配对。',
+        }));
+        return false;
+    };
+}