@hyzyn/dsh-tty 0.10.3 → 0.12.0

package/lib/probe.d.ts

@@ -0,0 +1,42 @@
+import type { HostKeyStore, SshSpec } from './ssh.js';
+/** TCP 预检超时（毫秒）：DNS 解析 + 建连。 */
+export declare const PROBE_TCP_TIMEOUT_MS = 6000;
+/** ssh2 握手/认证阶段超时（毫秒）；覆盖 buildConnectConfig 的 readyTimeout。 */
+export declare const PROBE_AUTH_TIMEOUT_MS = 8000;
+/** 分类结果载荷（HTTP 回传；字段全部可 JSON）。 */
+export interface ProbeResult {
+    /** tcp 阶段：DNS 解析 + TCP 建连。 */
+    tcp: {
+        ok: boolean;
+        error?: string;
+        ms?: number;
+    };
+    /** hostkey 阶段：TOFU 比对（未到握手时为 unknown）。 */
+    hostkey: {
+        state: 'unknown' | 'matched' | 'recorded' | 'mismatch';
+        /** 服务端 host key 的 sha256 指纹（hostHash:'sha256' 下 hostVerifier 收到的原样值）。 */
+        fingerprint: string;
+        /** 已记录指纹（mismatch 时展示对照）。 */
+        known?: string;
+        /** mismatch 时的完整指引文案（与 spawnSsh 一致）。 */
+        error?: string;
+    };
+    /** auth 阶段：认证是否通过（ready）。 */
+    auth: {
+        ok: boolean;
+        error?: string;
+        ms?: number;
+    };
+    /** 总耗时。 */
+    totalMs: number;
+}
+/** 仅校验一份连接簿 / 对话框条目的形状（新增 / 编辑前先过一遍；不做网络请求）。 */
+export declare function validateSshFields(input: Record<string, unknown>): {
+    spec?: SshSpec;
+    error?: string;
+};
+/**
+ * 单次连接诊断。无论成败都会关闭连接、在超时内返回，绝不悬挂。
+ * 分类见文件头；tcp 预检通过后才进入 ssh2 握手。
+ */
+export declare function probeSsh(spec: SshSpec, store?: HostKeyStore): Promise<ProbeResult>;

package/lib/probe.js

@@ -0,0 +1,274 @@
+/**
+ * @hyzyn/dsh-tty — SSH 连接测试（probe）模块。
+ *
+ * 「连接测试」按钮的数据源：不占会话名额、不开 shell channel，只做一次
+ * 链路诊断，把分段结果带回设置卡片 / SSH 连接对话框：
+ *
+ *   阶段     做法                                                    判定
+ *   tcp      net.connect 预检（DNS + TCP 建连，6s 超时）               → 主机可达 / DNS / 拒绝 / 超时
+ *   hostkey  ssh2 握手；hostVerifier 内做 TOFU 比对                    → 已匹配 / 新指纹 / 不匹配拒绝
+ *   auth     ssh2 ready / error（认证被拒、协商超时等）                → 认证通过或分类失败
+ *
+ * host key 两种策略（与隧道/SFTP 的 hostKeyStore 用法对齐）：
+ *   - 提供 store（设置卡片「测试」按钮）：完整 TOFU——新指纹当场持久化
+ *     record（测试即「首次连接」语义），不匹配拒绝并给出与 spawnSsh 完全
+ *     一致的指引文案（含已记录指纹与本次指纹，供对照）；
+ *   - 不提供 store（SSH 连接对话框试连，尚未保存/未必入库）：只比对不
+ *     记录（避免给未保存的草稿建立钉扎），不匹配照样拒绝。
+ *
+ * 认证失败返回服务端标准错误消息原文（如 `All configured authentication
+ * methods failed`）不额外臆测——真实原因（密码错 / 用户不存在 / 方法未开）
+ * 由服务端决定，用户可据原文排查。
+ */
+import { Client } from 'ssh2';
+import { connect as netConnect } from 'node:net';
+import { buildConnectConfig, sshTarget } from './ssh.js';
+/** TCP 预检超时（毫秒）：DNS 解析 + 建连。 */
+export const PROBE_TCP_TIMEOUT_MS = 6_000;
+/** ssh2 握手/认证阶段超时（毫秒）；覆盖 buildConnectConfig 的 readyTimeout。 */
+export const PROBE_AUTH_TIMEOUT_MS = 8_000;
+/** 把底层错误分类为人类可读诊断；原文保留在返回串里便于对照排查。 */
+function classifyError(message) {
+    if (message === 'Host key verification failed') {
+        return '主机密钥校验失败（TOFU 不匹配，见 hostkey 指引）';
+    }
+    if (message.includes('All configured authentication methods failed')) {
+        return '认证被拒绝：所有认证方式均失败（用户名/密码/密钥是否正确，或服务端是否允许该认证方式）';
+    }
+    if (message.includes('Timed out')) {
+        return '超时：主机无响应或认证协商超时（检查地址 / 端口 / 防火墙 / 网络）';
+    }
+    const lower = message.toLowerCase();
+    if (lower.includes('econnrefused'))
+        return '连接被拒绝（ECONNREFUSED）：端口未监听或服务未启动';
+    if (lower.includes('enetunreach'))
+        return '网络不可达（ENETUNREACH）：路由不通或主机离线';
+    if (lower.includes('ehostunreach'))
+        return '主机不可达（EHOSTUNREACH）';
+    if (lower.includes('eai_again') || lower.includes('eai_noname') || lower.includes('enotfound'))
+        return 'DNS 解析失败：主机名无法解析';
+    if (lower.includes('getaddrinfo'))
+        return 'DNS 解析失败：主机名无法解析';
+    if (lower.includes('unable to exchange encryption keys') || lower.includes('encryption') || lower.includes('kex')) {
+        return '密钥交换失败：服务端可能不是 SSH 服务，或加密算法不兼容';
+    }
+    if (lower.includes('keepalive'))
+        return '连接保活超时（keepalive）';
+    if (lower.includes('protocol'))
+        return '协议错误：' + message;
+    return message;
+}
+/** 与 spawnSsh 的 applyHostKeyPolicy 一致的 TOFU 指引文案。 */
+function mismatchMessage(target, host, port, known, current) {
+    return (`SSH 主机密钥指纹变更：${target} 已记录 sha256:${known}，本次为 sha256:${current}。` +
+        '可能是主机重装或换钥匙，也可能是中间人（MITM）冒充；确认安全后，到 设置 → 插件 → 终端面板 → SSH 主机密钥记录 删除该主机再重连。');
+}
+/** 收集 hostVerifier 收到的指纹（ssh2 可能对多 host key 调用多次，取最后一次）。 */
+function makeHostKeyVerifier(options) {
+    const { spec, store, onResult } = options;
+    const port = spec.port ?? 22;
+    const target = sshTarget(spec);
+    let seen = '';
+    return (hash) => {
+        seen = hash;
+        const known = store?.get(spec.host, port);
+        if (known === undefined) {
+            if (store !== undefined) {
+                // 完整 TOFU：新指纹当场持久化（与 spawnSsh 的 hostVerifier 同语义）
+                store.record(spec.host, port, hash);
+                onResult({ state: 'recorded', fingerprint: hash });
+            }
+            else {
+                // 试连（对话框）：只比对不落盘
+                onResult({ state: 'matched', fingerprint: hash });
+            }
+            return true;
+        }
+        if (known === hash) {
+            onResult({ state: 'matched', fingerprint: hash, known });
+            return true;
+        }
+        onResult({ state: 'mismatch', fingerprint: hash, known, error: mismatchMessage(target, spec.host, port, known, hash) });
+        return false;
+    };
+}
+/** 仅校验一份连接簿 / 对话框条目的形状（新增 / 编辑前先过一遍；不做网络请求）。 */
+export function validateSshFields(input) {
+    const host = typeof input.host === 'string' ? input.host.trim() : '';
+    const username = typeof input.username === 'string' ? input.username.trim() : '';
+    if (host === '')
+        return { error: '主机必填' };
+    if (username === '')
+        return { error: '用户名必填' };
+    let port = 22;
+    if (input.port !== undefined && input.port !== '') {
+        const value = Number(input.port);
+        if (!Number.isInteger(value) || value < 1 || value > 65535)
+            return { error: '端口必须是 1~65535 的整数' };
+        port = value;
+    }
+    const auth = input.auth === 'key' || input.auth === 'password' ? input.auth : 'agent';
+    const spec = { host, port, username, auth };
+    if (auth === 'key') {
+        const keyPath = typeof input.keyPath === 'string' ? input.keyPath.trim() : '';
+        if (keyPath === '')
+            return { error: 'auth=key 需要私钥路径' };
+        spec.keyPath = keyPath;
+        const passphrase = typeof input.passphrase === 'string' ? input.passphrase : '';
+        if (passphrase !== '')
+            spec.passphrase = passphrase;
+    }
+    if (auth === 'password') {
+        const password = typeof input.password === 'string' ? input.password : '';
+        if (password === '')
+            return { error: 'auth=password 需要密码' };
+        spec.password = password;
+    }
+    if (input.agentForward === true)
+        spec.agentForward = true;
+    return { spec };
+}
+/**
+ * 单次连接诊断。无论成败都会关闭连接、在超时内返回，绝不悬挂。
+ * 分类见文件头；tcp 预检通过后才进入 ssh2 握手。
+ */
+export async function probeSsh(spec, store) {
+    const startedAt = Date.now();
+    const result = {
+        tcp: { ok: false },
+        hostkey: { state: 'unknown', fingerprint: '' },
+        auth: { ok: false },
+        totalMs: 0,
+    };
+    const finish = () => {
+        result.totalMs = Date.now() - startedAt;
+        return result;
+    };
+    const port = spec.port ?? 22;
+    const target = sshTarget(spec);
+    // ---- 阶段 1：agent 预检（与 spawnSsh 同款，快速失败） ----
+    if (spec.auth === 'agent' && (process.env.SSH_AUTH_SOCK === undefined || process.env.SSH_AUTH_SOCK === '')) {
+        const message = 'agent 认证需要 SSH_AUTH_SOCK（本机未运行 ssh-agent 或变量未设置）';
+        result.tcp = { ok: false, error: message, ms: 0 };
+        result.auth = { ok: false, error: message };
+        return finish();
+    }
+    // ---- 阶段 1：TCP 预检（DNS + 建连） ----
+    const tcpResult = await new Promise((resolve) => {
+        const sock = netConnect({ host: spec.host, port });
+        const tcpStart = Date.now();
+        const done = (ok, error) => {
+            try {
+                sock.destroy();
+            }
+            catch {
+                /* 已关闭 */
+            }
+            resolve({ ok, error, ms: Date.now() - tcpStart });
+        };
+        sock.setTimeout(PROBE_TCP_TIMEOUT_MS, () => {
+            done(false, 'TCP 连接超时：主机无响应（检查地址 / 防火墙 / 网络）');
+        });
+        sock.once('connect', () => done(true));
+        sock.once('error', (error) => {
+            done(false, classifyError(error.message));
+        });
+    });
+    result.tcp = tcpResult;
+    if (!tcpResult.ok) {
+        result.auth = { ok: false, error: tcpResult.error };
+        return finish();
+    }
+    // ---- 阶段 2+3：ssh2 握手（host key 交换 + 认证） ----
+    let connectConfig;
+    try {
+        connectConfig = buildConnectConfig(spec);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        result.auth = { ok: false, error: classifyError(message) };
+        return finish();
+    }
+    // 探针专属更短握手超时（buildConnectConfig 默认 20s 对测试太长）
+    connectConfig.readyTimeout = PROBE_AUTH_TIMEOUT_MS;
+    const password = spec.auth === 'password' ? connectConfig.password ?? '' : '';
+    const tryKeyboard = connectConfig.tryKeyboard === true;
+    return new Promise((resolve) => {
+        let settled = false;
+        let seenHostKey = false;
+        let hostkeyState = { state: 'unknown', fingerprint: '' };
+        const settle = () => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            try {
+                conn.end();
+            }
+            catch {
+                /* 已断开 */
+            }
+            resolve(finish());
+        };
+        // hostVerifier 的 onResult 同步回调：把结论收集到 hostkeyState
+        connectConfig.hostVerifier = makeHostKeyVerifier({
+            spec,
+            store,
+            onResult: (next) => {
+                seenHostKey = true;
+                hostkeyState = { ...next, error: next.error };
+            },
+        });
+        // password 认证挂 keyboard-interactive 自动应答（同 spawnSsh/tunnels/sftp）
+        const conn = new Client();
+        if (tryKeyboard) {
+            conn.on('keyboard-interactive', (_name, _instructions, _lang, _prompts, finishKb) => {
+                finishKb([password]);
+            });
+        }
+        const authStart = Date.now();
+        const timer = setTimeout(() => {
+            if (seenHostKey) {
+                result.hostkey = hostkeyState;
+                result.auth = { ok: false, error: '认证/协商超时（服务端在 8s 内未完成认证）', ms: Date.now() - authStart };
+            }
+            else {
+                result.auth = { ok: false, error: '握手超时（服务端未在 8s 内完成密钥交换）', ms: Date.now() - authStart };
+            }
+            settle();
+        }, PROBE_AUTH_TIMEOUT_MS + 1000);
+        timer.unref?.();
+        conn.on('ready', () => {
+            result.hostkey = hostkeyState;
+            result.auth = { ok: true, ms: Date.now() - authStart };
+            settle();
+        });
+        conn.on('error', (error) => {
+            const classified = classifyError(error.message);
+            if (error.message === 'Host key verification failed' && hostkeyState.state === 'mismatch') {
+                result.hostkey = hostkeyState;
+                result.auth = { ok: false, error: '主机密钥校验失败（见 hostkey 指引）', ms: Date.now() - authStart };
+                settle();
+                return;
+            }
+            result.hostkey = seenHostKey ? hostkeyState : { state: 'unknown', fingerprint: '' };
+            // TCP 已通：这里只可能是协商 / 认证 / 协议层错误
+            result.auth = { ok: false, error: classified, ms: Date.now() - authStart };
+            settle();
+        });
+        conn.on('close', () => {
+            // 正常路径（ready / error / 超时）已 settle；未 settle 的 close 兜底
+            result.auth = { ok: false, error: '连接已关闭（服务端主动断开）', ms: Date.now() - authStart };
+            settle();
+        });
+        try {
+            conn.connect(connectConfig);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            result.auth = { ok: false, error: classifyError(message), ms: Date.now() - authStart };
+            settle();
+        }
+    });
+}
+//# sourceMappingURL=probe.js.map

package/lib/probe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"probe.js","sourceRoot":"","sources":["../src/probe.ts"],"names":[],"mappings":"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"}

package/lib/sftp.d.ts

@@ -49,11 +49,39 @@ export interface SftpUpload {
     /** 写入完成（流 close）resolve，写入失败 reject——路由 await 它再回包。 */
     done: Promise<void>;
 }
+/**
+ * 传输任务（0.12.0）：双栏 ⇨/⇦ 的服务端直传任务化——start 立刻返回 id，
+ * 客户端轮询 /cancel 端点中止。无它时一个目录递归直传在 HTTP 请求里同步跑
+ * 完，浏览器无法打断（只能关窗口，服务端还在写远端）。
+ */
+export interface SftpTransferJob {
+    id: string;
+    direction: 'up' | 'down';
+    /** 起始路径对（进度行展示用）。 */
+    localPath: string;
+    remotePath: string;
+    /** 已完成字节 / 总字节（总字节在开传前递归统计，统计中可为 0）。 */
+    bytes: number;
+    total: number;
+    /** 当前正在搬运的文件相对名（展示用）。 */
+    current: string;
+    state: 'running' | 'done' | 'error' | 'canceled';
+    error?: string;
+}
+/** 取消感知的传输选项（直传任务内部用；HTTP 上传/下载路由不传 signal）。 */
+export interface SftpTransferOptions {
+    signal?: AbortSignal;
+    /** 每搬运一个文件前回调（进度行显示当前文件名）。 */
+    onFile?: (name: string) => void;
+    /** 字节累加（进度条分子）。 */
+    onBytes?: (delta: number) => void;
+}
 export declare class SftpManager {
     private readonly logger;
     private readonly store;
     private readonly conns;
     private sweeper;
+    private readonly jobs;
     constructor(logger: SftpLogger, store: HostKeyStore);
     /** 插件卸载：关定时器与全部连接（幂等）。 */
     disposeAll(): void;
@@ -90,13 +118,35 @@ export declare class SftpManager {
     /**
      * 本机文件 / 目录 → 远程（双栏「→ 传输」）。目录递归建目录后逐个上传；
      * 同名文件直接覆盖（openUpload 'w'）。不经过浏览器，字节不出宿主进程。
+     * signal 中止时销毁读写流并删除半截的远程文件（删除失败只记日志）。
      */
-    uploadFromLocal(spec: SshSpec, localPath: string, remotePath: string): Promise<void>;
+    uploadFromLocal(spec: SshSpec, localPath: string, remotePath: string, options?: SftpTransferOptions): Promise<void>;
     /**
      * 远程文件 / 目录 → 本机（双栏「← 传输」）。目录递归建本地目录后逐个下载；
      * 同名文件直接覆盖（'w' 写流）。远程符号链接按文件下载（跟随目标）。
+     * signal 中止时销毁读写流并删除半截的本机文件（删除失败只记日志）。
+     */
+    downloadToLocal(spec: SshSpec, remotePath: string, localPath: string, options?: SftpTransferOptions): Promise<void>;
+    /**
+     * 带字节计数与取消感知的 pipe：source→sink 之间插一个 PassThrough 只做
+     * 「数了就转发」；取消时 destroy 它——pipeline 随即结束并销毁两端流，
+     * 不留悬挂的 SFTP 句柄，也不会误报成「传输失败」。
+     */
+    private pipeCounted;
+    /** 删远端文件（取消后的半截清理）：失败只记日志，不影响取消本身。 */
+    deleteRemoteQuiet(spec: SshSpec, path: string): Promise<void>;
+    /**
+     * 预扫描总字节数（直传进度分母）：目录递归累加文件大小，只数「源头一侧」
+     * ——up 数本机、down 数远程（对侧尚未创建，数不到也不该数）。目的是让
+     * 进度条有真实百分比：纯统计（不搬运），单项失败按 0 计、不阻断传输。
      */
-    downloadToLocal(spec: SshSpec, remotePath: string, localPath: string): Promise<void>;
+    private estimateBytes;
+    /** 开一个可取消的直传任务（路由 /transfer 的 start 分支）。 */
+    startTransfer(spec: SshSpec, direction: 'up' | 'down', localPath: string, remotePath: string): SftpTransferJob;
+    /** 任务快照（路由 /transfer?job=<id> 轮询）。 */
+    getTransfer(id: string): SftpTransferJob | undefined;
+    /** 中止任务（路由 /transfer 的 cancel 分支）；已终态的任务返回 undefined。 */
+    cancelTransfer(id: string): SftpTransferJob | undefined;
     /** 取（或建立）该 spec 的 SFTP 通道；连接断开的旧条目在此处自动重建。 */
     private acquire;
     private ensureSweeper;