@yezack/dsh-remote-mobile 0.0.0-stage → 1.9.1

package/lib/auth/gate.d.ts

@@ -0,0 +1,29 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { SessionStore } from './token.js';
+/**
+ * 判断请求是否来自本机回环
+ */
+export declare function isLoopbackRequest(req: IncomingMessage): 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;
+/**
+ * 判断是否为无需鉴权的公开静态/登录路径
+ */
+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,139 @@
+import { isTailscaleIp, isLanIp, getClientIp } from './tailscale.js';
+import { resolveRedirectPath } from './prefix.js';
+/**
+ * 判断请求是否来自本机回环
+ */
+export function isLoopbackRequest(req) {
+    const ip = getClientIp(req);
+    return ip === '127.0.0.1' || ip === '::1' || ip === 'localhost';
+}
+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/';
+/**
+ * 判断请求是否携带浏览器跨站信号（用于回环 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;
+    if (typeof origin === 'string' && origin) {
+        if (origin === 'null')
+            return true; // 沙箱 iframe 等场景的不透明 Origin，一律视为跨站
+        try {
+            const originHost = new URL(origin).host;
+            return originHost !== '' && originHost !== (req.headers.host || '');
+        }
+        catch {
+            return true; // 无法解析的 Origin 视为不可信
+        }
+    }
+    return req.headers['sec-fetch-site'] === 'cross-site';
+}
+/**
+ * 判断是否为无需鉴权的公开静态/登录路径
+ */
+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/') && STATIC_ASSET_EXT_REGEX.test(pathname))
+        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;
+        };
+        // 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)) {
+            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: '已拦截来自其他网站的跨站写请求。',
+            }));
+            return false;
+        }
+        // 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) {
+            const authLocation = resolveRedirectPath(req.headers, '/auth');
+            res.writeHead(302, {
+                Location: authLocation,
+                '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;
+    };
+}

package/lib/auth/prefix.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 反向代理路径前缀解析与安全重定向工具
+ */
+/**
+ * 校验并提取反向代理传递的前缀路径 (如 X-Forwarded-Prefix)
+ *
+ * 安全约束：
+ * 1. 必须以单个 / 开头，且不能以 // 开头（防御协议相对 URL 与开放重定向）
+ * 2. 不能包含协议标识 (http:, https:, etc.)
+ * 3. 不能包含反斜杠或控制字符（防御浏览器 URL 规范化逃逸与 CRLF 注入）
+ * 4. 去除末尾冗余的斜杠
+ */
+export declare function resolveForwardedPrefix(raw: unknown): string;
+/**
+ * 构造带网关前缀的重定向目标路径
+ * @param headers 请求头
+ * @param targetPath 目标相对路径，如 '/auth' 或 '/'
+ */
+export declare function resolveRedirectPath(headers: Record<string, string | string[] | undefined> | undefined, targetPath: string): string;

package/lib/auth/prefix.js

@@ -0,0 +1,41 @@
+/**
+ * 反向代理路径前缀解析与安全重定向工具
+ */
+/**
+ * 校验并提取反向代理传递的前缀路径 (如 X-Forwarded-Prefix)
+ *
+ * 安全约束：
+ * 1. 必须以单个 / 开头，且不能以 // 开头（防御协议相对 URL 与开放重定向）
+ * 2. 不能包含协议标识 (http:, https:, etc.)
+ * 3. 不能包含反斜杠或控制字符（防御浏览器 URL 规范化逃逸与 CRLF 注入）
+ * 4. 去除末尾冗余的斜杠
+ */
+export function resolveForwardedPrefix(raw) {
+    if (typeof raw !== 'string')
+        return '';
+    const trimmed = raw.trim();
+    if (!trimmed || trimmed === '/')
+        return '';
+    // 必须以单个 / 开头，拒绝 // (如 //evil.com)、带有协议字符、以及含反斜杠与控制字符
+    if (!trimmed.startsWith('/') ||
+        trimmed.startsWith('//') ||
+        /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(trimmed) ||
+        /[\\\x00-\x1F\x7F]/.test(trimmed)) {
+        return '';
+    }
+    return trimmed.replace(/\/+$/, '');
+}
+/**
+ * 构造带网关前缀的重定向目标路径
+ * @param headers 请求头
+ * @param targetPath 目标相对路径，如 '/auth' 或 '/'
+ */
+export function resolveRedirectPath(headers, targetPath) {
+    const rawPrefix = headers?.['x-forwarded-prefix'];
+    const prefix = resolveForwardedPrefix(typeof rawPrefix === 'string' ? rawPrefix : Array.isArray(rawPrefix) ? rawPrefix[0] : '');
+    const normPath = targetPath.startsWith('/') ? targetPath : `/${targetPath}`;
+    if (!prefix) {
+        return normPath;
+    }
+    return `${prefix}${normPath}`;
+}

package/lib/auth/tailscale.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 判断 IP 是否为 Tailscale 官方虚拟私网 IP (CGNAT 网段 100.64.0.0/10)
+ * 范围: 100.64.0.0 ~ 100.127.255.255
+ */
+export declare function isTailscaleIp(rawIp?: string): boolean;
+/**
+ * 判断 IP 是否为局域网私有 IP (RFC 1918 规范: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)
+ */
+export declare function isLanIp(rawIp?: string): boolean;
+/**
+ * 提取请求的客户端真实 IP（基于底层 Socket 连接，防止外部伪造 X-Forwarded-For，且兼容虚拟化场景）
+ */
+export declare function getClientIp(req: {
+    socket?: {
+        remoteAddress?: string;
+        __dsh_real_remote_address__?: string;
+    };
+    headers?: Record<string, string | string[] | undefined>;
+}): string;
+/**
+ * 获取当前本机的 Tailscale IP
+ */
+export declare function getLocalTailscaleIp(): string | null;
+/**
+ * 获取当前本机局域网 IP (优先常见 en0 / eth0 / wlan0 等)
+ */
+export declare function getLocalLanIp(): string | null;
+/**
+ * 获取本机所有可用的网络 IP
+ */
+export declare function getAllNetworkIps(): {
+    name: string;
+    ip: string;
+    isTailscale: boolean;
+    isLan: boolean;
+}[];

package/lib/auth/tailscale.js

@@ -0,0 +1,128 @@
+import { execSync } from 'node:child_process';
+import { networkInterfaces } from 'node:os';
+/**
+ * 判断 IP 是否为 Tailscale 官方虚拟私网 IP (CGNAT 网段 100.64.0.0/10)
+ * 范围: 100.64.0.0 ~ 100.127.255.255
+ */
+export function isTailscaleIp(rawIp) {
+    if (!rawIp)
+        return false;
+    // 规范化 IPv4 (处理 ::ffff:100.x.y.z 格式)
+    const ip = rawIp.replace(/^::ffff:/, '').trim();
+    if (!ip.startsWith('100.'))
+        return false;
+    const parts = ip.split('.');
+    if (parts.length !== 4)
+        return false;
+    const second = parseInt(parts[1], 10);
+    return second >= 64 && second <= 127;
+}
+/**
+ * 判断 IP 是否为局域网私有 IP (RFC 1918 规范: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)
+ */
+export function isLanIp(rawIp) {
+    if (!rawIp)
+        return false;
+    const ip = rawIp.replace(/^::ffff:/, '').trim();
+    if (ip === '127.0.0.1' || ip === '::1' || ip === 'localhost' || isTailscaleIp(ip))
+        return false;
+    const parts = ip.split('.').map((p) => parseInt(p, 10));
+    if (parts.length !== 4 || parts.some((p) => isNaN(p) || p < 0 || p > 255))
+        return false;
+    const [a, b] = parts;
+    // 10.0.0.0/8
+    if (a === 10)
+        return true;
+    // 172.16.0.0/12
+    if (a === 172 && b >= 16 && b <= 31)
+        return true;
+    // 192.168.0.0/16
+    if (a === 192 && b === 168)
+        return true;
+    return false;
+}
+/**
+ * 提取请求的客户端真实 IP（基于底层 Socket 连接，防止外部伪造 X-Forwarded-For，且兼容虚拟化场景）
+ */
+export function getClientIp(req) {
+    const realAddress = req.socket?.__dsh_real_remote_address__ || req.socket?.remoteAddress;
+    return realAddress?.replace(/^::ffff:/, '') || '127.0.0.1';
+}
+/**
+ * 获取当前本机的 Tailscale IP
+ */
+export function getLocalTailscaleIp() {
+    // 1. 尝试通过 CLI 快速获取
+    try {
+        const out = execSync('tailscale ip -4', { encoding: 'utf8', timeout: 800, stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+        if (out && isTailscaleIp(out)) {
+            return out;
+        }
+    }
+    catch {
+        // CLI 不可用或未在 PATH 中，回退到网卡扫描
+    }
+    // 2. 扫描系统网卡
+    try {
+        const interfaces = networkInterfaces();
+        for (const name of Object.keys(interfaces)) {
+            for (const info of interfaces[name] || []) {
+                if (info.family === 'IPv4' && !info.internal && isTailscaleIp(info.address)) {
+                    return info.address;
+                }
+            }
+        }
+    }
+    catch { }
+    return null;
+}
+/**
+ * 获取当前本机局域网 IP (优先常见 en0 / eth0 / wlan0 等)
+ */
+export function getLocalLanIp() {
+    try {
+        const interfaces = networkInterfaces();
+        // 优先匹配局域网常规网卡名
+        const preferredOrder = ['en0', 'eth0', 'wlan0', 'Wi-Fi', 'en1', 'eth1'];
+        for (const name of preferredOrder) {
+            for (const info of interfaces[name] || []) {
+                if (info.family === 'IPv4' && !info.internal && isLanIp(info.address)) {
+                    return info.address;
+                }
+            }
+        }
+        // 遍历所有其他可用网卡
+        for (const name of Object.keys(interfaces)) {
+            for (const info of interfaces[name] || []) {
+                if (info.family === 'IPv4' && !info.internal && isLanIp(info.address)) {
+                    return info.address;
+                }
+            }
+        }
+    }
+    catch { }
+    return null;
+}
+/**
+ * 获取本机所有可用的网络 IP
+ */
+export function getAllNetworkIps() {
+    const list = [];
+    try {
+        const interfaces = networkInterfaces();
+        for (const name of Object.keys(interfaces)) {
+            for (const info of interfaces[name] || []) {
+                if (info.family === 'IPv4' && !info.internal) {
+                    list.push({
+                        name,
+                        ip: info.address,
+                        isTailscale: isTailscaleIp(info.address),
+                        isLan: isLanIp(info.address),
+                    });
+                }
+            }
+        }
+    }
+    catch { }
+    return list;
+}

package/lib/auth/token.d.ts

@@ -0,0 +1,194 @@
+import { EventEmitter } from 'node:events';
+import type { IncomingMessage } from 'node:http';
+export declare const AUTH_COOKIE_NAME = "dsh_mobile_token";
+/** DSH_HOME 目录（支持 DSH_HOME 覆盖） */
+export declare const DSH_HOME: string;
+/** 插件自有数据目录 */
+export declare const REMOTE_MOBILE_DIR: string;
+export declare const DEFAULT_PERSIST_FILE: string;
+/** 插件自有配置持久化文件（DSH 0.1.7+ 起官方弃用 settings.yaml，插件改为自持存储） */
+export declare const SETTINGS_FILE: string;
+/** DSH 旧版全局设置文件（0.1.7+ 起仅作一次性迁移来源，启动时会被改名） */
+export declare const GLOBAL_SETTINGS_FILE: string;
+/** DSH 迁移后遗留的旧设置存档（legacy settings.yaml → settings.yaml.imported） */
+export declare const LEGACY_SETTINGS_IMPORTED_FILE: string;
+/**
+ * 从 ~/.dsh/settings.yaml 中安全读取 dsh-remote-mobile 命名空间的最新配置
+ */
+export declare function readFromSettingsYaml(filePath?: string): Partial<SessionStoreOptions>;
+/**
+ * 从旧版 settings.yaml 文本内容中解析 locale.preference（返回 null 表示未命中）
+ */
+export declare function parseLocaleFromSettingsYaml(content: string): 'zh' | 'en' | null;
+/**
+ * 从 cordis.patch.yml 文本内容中解析 locale entry 的 config.preference（返回 null 表示未命中）
+ */
+export declare function parseLocaleFromPatch(content: string): 'zh' | 'en' | null;
+/**
+ * 读取 DSH 全局语言偏好。
+ *
+ * DSH 0.1.7+ 起配置真实落点为当前 profile 的 cordis.patch.yml（旧版 settings.yaml
+ * 已被一次性迁移并改名为 settings.yaml.imported），因此优先读取 profile patch，
+ * 再回退旧 settings.yaml / settings.yaml.imported。
+ *
+ * @param filePath 显式传入时按旧版 settings.yaml 格式解析（向后兼容与测试）。
+ */
+export declare function readGlobalLocale(filePath?: string): 'zh' | 'en';
+/**
+ * 读取插件自有持久化配置文件 ~/.dsh/remote-mobile/settings.json
+ *
+ * 注：若文件中 secretHash 为空串 ""（表示用户清空了密码），此处会跳过赋值以归一化为 undefined。
+ * 上层 resolveInitialStoreOptions 必须根据文件存在性（own !== null）做出决策，严禁在自有配置存在时用 legacy 兜底回退。
+ */
+export declare function readPluginSettingsJson(filePath?: string): Partial<SessionStoreOptions>;
+/**
+ * 将插件配置原子写回自有配置文件 ~/.dsh/remote-mobile/settings.json（权限 0600）。
+ *
+ * DSH 0.1.7+ 起官方已弃用 ~/.dsh/settings.yaml 作为实时配置源（启动时一次性迁移为
+ * settings.yaml.imported），因此插件不再依赖该文件，改为自持存储，避免升级后配置丢失。
+ */
+export declare function writePluginSettingsJson(options: SessionStoreOptions, filePath?: string): boolean;
+/**
+ * 兼容读取 DSH 旧版 settings.yaml / 迁移后的 settings.yaml.imported 中的
+ * dsh-remote-mobile 段，用于首次启动时把旧配置迁移到自有 settings.json。
+ */
+export declare function readLegacyDshSettings(liveFile?: string, importedFile?: string): Partial<SessionStoreOptions>;
+/**
+ * 解析 SessionStore 的初始运行配置（纯函数决策逻辑）。
+ *
+ * 优先级与防反噬规则：
+ * 1. 显式传入的 explicit 参数优先级最高；
+ * 2. 若自有配置文件已存在（own !== null），则以自有配置 own 为准，此时 legacy 配置被彻底忽略（防止已清空的密码死灰复燃）；
+ * 3. 仅当自有配置文件尚不存在（own === null，即首次安装或旧版升级）时，才回退读取 legacy 配置进行一次性迁移；
+ * 4. 最终缺失项采用系统安全默认值。
+ *
+ * @param explicit 构造函数传入的显式参数
+ * @param own 插件自有 settings.json 内容；null 表示文件尚不存在（首次启动迁移状态）
+ * @param legacy 旧版 settings.yaml / settings.yaml.imported 内容
+ */
+export declare function resolveInitialStoreOptions(explicit?: SessionStoreOptions, own?: Partial<SessionStoreOptions> | null, legacy?: Partial<SessionStoreOptions>): Required<SessionStoreOptions>;
+export interface SessionRecord {
+    token: string;
+    createdAt: number;
+    lastSeenAt: number;
+    ip?: string;
+    deviceName?: string;
+    userAgent?: string;
+    authType?: string;
+    isBypass?: boolean;
+}
+export interface ShortCodeRecord {
+    code: string;
+    token: string;
+    createdAt: number;
+    expiresAt: number;
+}
+export interface IpSecurityStat {
+    ip: string;
+    authVisits: number;
+    authVisitsInWindow: number;
+    windowStart: number;
+    failedAttempts: number;
+    totalAttempts: number;
+    lockedUntil: number;
+    lastAttemptAt: number;
+    lastSeenAt: number;
+    authType?: string;
+    deviceName?: string;
+    userAgent?: string;
+}
+export interface SessionStoreOptions {
+    allowTailscale?: boolean;
+    allowLan?: boolean;
+    secret?: string;
+    secretHash?: string;
+    devicesFile?: string;
+    maxFailedAttempts?: number;
+    lockDurationMs?: number;
+    maxVisitsPerMinute?: number;
+}
+/**
+ * 将 User-Agent 字符串解析为人类友好的设备名称
+ */
+export declare function parseDeviceName(ua?: string): string;
+export declare class SessionStore extends EventEmitter {
+    private sessions;
+    private shortCodes;
+    private ipStats;
+    private options;
+    private settingsMutator?;
+    private debounceTimer;
+    readonly persistPath: string;
+    readonly settingsFilePath: string | null;
+    constructor(options?: SessionStoreOptions);
+    getOptions(): Required<SessionStoreOptions>;
+    hasSecret(): boolean;
+    setSettingsMutator(mutator: (patch: Partial<SessionStoreOptions>) => void): void;
+    updateOptions(newOpts: Partial<SessionStoreOptions>, syncToSettings?: boolean): void;
+    /**
+     * 记录 IP 打开 /auth 页面的计数并进行限频判定与设备指纹解析
+     */
+    recordAuthVisit(ip: string, userAgent?: string): {
+        allowed: boolean;
+        lockedUntil?: number;
+        reason?: string;
+    };
+    /**
+     * 检查 IP 是否被防暴力破解锁定
+     */
+    isIpLocked(ip: string): {
+        locked: boolean;
+        lockedUntil?: number;
+        remainingSeconds?: number;
+    };
+    /**
+     * 获取所有 IP 的安全审计统计数据
+     */
+    getIpSecurityStats(): IpSecurityStat[];
+    /**
+     * 管理员手动解锁某个 IP
+     */
+    unlockIp(ip: string): boolean;
+    generateShortCode(): {
+        code: string;
+        token: string;
+        expiresAt: number;
+    };
+    verify(credential: string, userAgent?: string, clientIp?: string): {
+        success: boolean;
+        token?: string;
+        reason?: string;
+        locked?: boolean;
+        remainingSeconds?: number;
+    };
+    private handleFailedAttempt;
+    validateToken(token: string, clientIp?: string): boolean;
+    extractTokenFromRequest(req: IncomingMessage): string | null;
+    /**
+     * 自动登记并归因免密直连设备（Tailscale / LAN）
+     */
+    registerBypassDevice(ip: string, userAgent: string | undefined, type: 'Tailscale' | 'LAN'): SessionRecord;
+    getSessionsList(): {
+        count: number;
+        devices: Array<Omit<SessionRecord, 'userAgent'>>;
+    };
+    revokeDevice(token: string): boolean;
+    revokeAllSessions(): void;
+    /**
+     * 清空所有 IP 安全审计与防暴破统计记录
+     */
+    clearAllIpSecurityStats(): void;
+    loadPersistedData(): void;
+    /**
+     * 同步立即持久化落盘（由关键路径调用：配对成功、密码认证、撤销设备、手动改密/配置等）
+     */
+    savePersistedData(): void;
+    /**
+     * 500ms 防抖持久化落盘（由高频访问路径调用：每次打开 /auth、validateToken 重连时间戳更新等）
+     */
+    savePersistedDataDebounced(): void;
+    /**
+     * 立即执行待写的持久化数据落盘并清理定时器
+     */
+    flushPersistedData(): void;
+}