host-execution-mcp 1.0.0

package/dist/ssh/bastion-errors.js

@@ -0,0 +1,190 @@
+/**
+
+ * Domain errors for Hop1 ACCESS connectivity (environment vs business failure).
+
+ *
+
+ * phase=connect: TCP/SSH handshake / auth — may become ACCESS_UNAVAILABLE + neg-cache
+
+ * phase=stream: mid-session channel/exec — ECONNRESET/EPIPE stay retryable, not access-down
+
+ */
+export class AccessUnavailableError extends Error {
+    code = "ACCESS_UNAVAILABLE";
+    causeCode;
+    /** Always false today — Agents must not auto-retry access-down. */
+    retryable = false;
+    hints;
+    host;
+    port;
+    constructor(input) {
+        const hints = defaultHints(input.causeCode);
+        const message = buildMessage(input.causeCode, input.host, input.port, hints, input.detail);
+        super(message, input.cause !== undefined ? { cause: input.cause } : undefined);
+        this.name = "AccessUnavailableError";
+        this.causeCode = input.causeCode;
+        this.hints = hints;
+        this.host = input.host;
+        this.port = input.port;
+    }
+    toJSON() {
+        return {
+            reachable: false,
+            host: this.host,
+            port: this.port,
+            reason: this.causeCode,
+            code: this.code,
+            retryable: this.retryable,
+            message: this.message,
+            hints: this.hints,
+            auth: this.causeCode === "AUTH_FAILED" ? "failed" : undefined,
+        };
+    }
+}
+export function isAccessUnavailableError(error) {
+    return error instanceof AccessUnavailableError;
+}
+/** Exec/command wall-clock timeout — not an ACCESS connectivity failure. */
+export function isCommandTimeoutError(error) {
+    return /Operation timed out after/i.test(errorMessage(error));
+}
+/**
+
+ * Whether the exec reconnect loop should try again (stream-phase only).
+
+ * Connect failures never enter this path — they become AccessUnavailableError first.
+
+ */
+export function shouldRetryBastionConnect(error) {
+    if (isAccessUnavailableError(error) || isCommandTimeoutError(error)) {
+        return false;
+    }
+    const code = errorCode(error);
+    // Mid-session drops: allow short reconnect.
+    if (code === "ECONNRESET" || code === "EPIPE") {
+        return true;
+    }
+    if (code === "ETIMEDOUT" ||
+        code === "ECONNREFUSED" ||
+        code === "EHOSTUNREACH" ||
+        code === "ENETUNREACH" ||
+        code === "ENOTFOUND") {
+        return false;
+    }
+    const msg = errorMessage(error);
+    if (/Timed out while waiting for handshake|Ready timeout|ECONNREFUSED|EHOSTUNREACH|ENETUNREACH|ENOTFOUND|All configured authentication methods failed|Authentication failed|Permission denied \(publickey|password|keyboard-interactive\)/i.test(msg)) {
+        return false;
+    }
+    return true;
+}
+/**
+
+ * Map an error to AccessUnavailableError, or null if it is not an access-down signal.
+
+ * Connect-phase includes ECONNRESET/EPIPE; stream-phase does not (those stay retryable).
+
+ */
+export function toAccessUnavailableError(error, host, port, phase) {
+    if (isAccessUnavailableError(error)) {
+        return error;
+    }
+    if (isCommandTimeoutError(error)) {
+        return null;
+    }
+    const code = errorCode(error);
+    const msg = errorMessage(error);
+    if (isSshAuthFailure(msg)) {
+        return new AccessUnavailableError({
+            causeCode: "AUTH_FAILED",
+            host,
+            port,
+            detail: msg,
+            cause: error,
+        });
+    }
+    if (phase === "connect" && (code === "ECONNRESET" || code === "EPIPE")) {
+        return new AccessUnavailableError({
+            causeCode: "VPN_OR_NETWORK",
+            host,
+            port,
+            detail: msg,
+            cause: error,
+        });
+    }
+    if (code === "ETIMEDOUT" ||
+        code === "ECONNREFUSED" ||
+        code === "EHOSTUNREACH" ||
+        code === "ENETUNREACH" ||
+        code === "ENOTFOUND" ||
+        /Timed out while waiting for handshake|Ready timeout|SSH closed before ready|ECONNREFUSED|EHOSTUNREACH|ENETUNREACH|getaddrinfo|connect ETIMEDOUT/i.test(msg)) {
+        return new AccessUnavailableError({
+            causeCode: "VPN_OR_NETWORK",
+            host,
+            port,
+            detail: msg,
+            cause: error,
+        });
+    }
+    if (phase === "connect" && /Connection lost before handshake/i.test(msg)) {
+        return new AccessUnavailableError({
+            causeCode: "SSH_HANDSHAKE",
+            host,
+            port,
+            detail: msg,
+            cause: error,
+        });
+    }
+    return null;
+}
+/** ssh2 auth failures only — not SFTP/file "Permission denied". */
+function isSshAuthFailure(msg) {
+    return /All configured authentication methods failed|Authentication failed|Permission denied \(publickey|password|keyboard-interactive\)/i.test(msg);
+}
+function defaultHints(cause) {
+    switch (cause) {
+        case "VPN_OR_NETWORK":
+            return [
+                "检查本地 VPN 是否已连接",
+                "确认 ACCESS_HOST / ACCESS_PORT 是否正确",
+                "确认本机到 ACCESS 网络可达（路由/防火墙）",
+            ];
+        case "AUTH_FAILED":
+            return [
+                "检查 ACCESS_USER / ACCESS_PASSWORD 或私钥配置",
+                "确认 SSH agent / ACCESS_PRIVATE_KEY_PATH 是否有效",
+            ];
+        case "SSH_HANDSHAKE":
+            return ["检查 VPN 与 ACCESS 地址", "网络不稳定时可稍后重试，或先调用 access_check"];
+        default:
+            return ["先调用 access_check 诊断本地到 ACCESS 连通性", "确认 VPN 与凭据配置"];
+    }
+}
+function buildMessage(cause, host, port, hints, detail) {
+    const title = cause === "AUTH_FAILED"
+        ? "ACCESS 认证失败"
+        : cause === "SSH_HANDSHAKE"
+            ? "ACCESS SSH 握手失败"
+            : cause === "UNKNOWN"
+                ? "ACCESS 连接失败"
+                : "无法连接 ACCESS（网络/VPN 可能不通）";
+    const lines = [
+        `${title}: ${host}:${port}`,
+        `原因分类: ${cause}`,
+        ...hints.map((h, i) => `${i + 1}. ${h}`),
+    ];
+    if (detail) {
+        lines.push(`详情: ${detail}`);
+    }
+    return lines.join("\n");
+}
+function errorCode(error) {
+    if (error && typeof error === "object" && "code" in error) {
+        const c = error.code;
+        return typeof c === "string" ? c : undefined;
+    }
+    return undefined;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=bastion-errors.js.map

package/dist/ssh/bastion-errors.js.map

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

package/dist/ssh/hop1-sftp.d.ts

@@ -0,0 +1,14 @@
+import type { AppConfig } from "../config.js";
+import { type SftpCopyOptions, type SftpTransferResult } from "../utils/copy-transfer.js";
+export type Hop1Direction = "upload" | "download";
+export interface TransferLocalBastionParams {
+    direction: Hop1Direction;
+    localPath: string;
+    remotePath: string;
+    config: AppConfig;
+    options?: SftpCopyOptions;
+}
+/**
+ * Transfer a local file or directory to/from bastion over an independent SFTP connection.
+ */
+export declare function transferLocalBastion(params: TransferLocalBastionParams, execSha256: (remotePath: string, timeoutMs: number) => Promise<string>): Promise<SftpTransferResult>;

package/dist/ssh/hop1-sftp.js

@@ -0,0 +1,437 @@
+/**
+ * Hop1 local ↔ bastion transfers via ssh2-sftp-client (independent TCP).
+ * Directory = list + per-file put/get (not uploadDir/downloadDir).
+ *
+ * skipIfComplete gate strength = verify mode (no auto-upgrade to sha256).
+ * verify fail on skip → fallthrough rewrite (never throw-only).
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import SftpClient from "ssh2-sftp-client";
+import { resolveAccessSshIdentity, resolveSshAuthOptions } from "../config.js";
+import { toAccessUnavailableError } from "./bastion-errors.js";
+import { createProgressReporter, createTransferId, DEFAULT_CONNECTION_TIMEOUT_MS, DEFAULT_PROGRESS_INTERVAL_MS, resolveEffectiveVerify, sha256File, throwIfAborted, transferSkipFields, } from "../utils/copy-transfer.js";
+function posixJoin(...parts) {
+    return parts
+        .join("/")
+        .replace(/\\/g, "/")
+        .replace(/\/+/g, "/")
+        .replace(/\/$/, "") || "/";
+}
+function isAbortError(error, signal) {
+    return signal?.aborted === true || (error instanceof Error && error.message === "Copy aborted");
+}
+async function walkLocalFiles(root) {
+    const out = [];
+    async function walk(abs, rel) {
+        const st = await fs.stat(abs);
+        if (st.isFile()) {
+            out.push({ localPath: abs, remotePath: rel, size: st.size });
+            return;
+        }
+        if (!st.isDirectory()) {
+            return;
+        }
+        const names = await fs.readdir(abs);
+        for (const name of names) {
+            await walk(path.join(abs, name), rel ? `${rel}/${name}` : name);
+        }
+    }
+    await walk(root, "");
+    return out;
+}
+async function walkRemoteFiles(sftp, root) {
+    const out = [];
+    async function walk(remoteAbs, rel) {
+        const list = await sftp.list(remoteAbs);
+        for (const item of list) {
+            const childRel = rel ? `${rel}/${item.name}` : item.name;
+            const childAbs = posixJoin(remoteAbs, item.name);
+            if (item.type === "d") {
+                await walk(childAbs, childRel);
+            }
+            else if (item.type === "-") {
+                out.push({ localPath: childRel, remotePath: childAbs, size: item.size });
+            }
+        }
+    }
+    await walk(root, "");
+    return out;
+}
+async function connectSftp(config, connectionTimeoutMs) {
+    const auth = resolveSshAuthOptions(config);
+    const identity = resolveAccessSshIdentity(config);
+    const sftp = new SftpClient();
+    const connectOpts = {
+        host: identity.host,
+        port: identity.port,
+        username: identity.username,
+        readyTimeout: connectionTimeoutMs,
+    };
+    if (auth.privateKey) {
+        connectOpts.privateKey = auth.privateKey;
+    }
+    if (auth.password) {
+        connectOpts.password = auth.password;
+    }
+    if (auth.agent) {
+        connectOpts.agent = auth.agent;
+    }
+    try {
+        await sftp.connect(connectOpts);
+        return sftp;
+    }
+    catch (error) {
+        const unavailable = toAccessUnavailableError(error, config.accessHost, config.accessPort, "connect");
+        throw unavailable ?? error;
+    }
+}
+async function safeEnd(sftp) {
+    if (!sftp) {
+        return;
+    }
+    try {
+        await sftp.end();
+    }
+    catch {
+        // ignore
+    }
+}
+async function remoteFileSize(sftp, remotePath) {
+    try {
+        const st = await sftp.stat(remotePath);
+        return st.size;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function remoteIsDirectory(sftp, remotePath) {
+    try {
+        await sftp.list(remotePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function verifyFile(sftp, localPath, remotePath, expectedSize, verify, execSha256) {
+    if (verify === "none") {
+        return;
+    }
+    const localStat = await fs.stat(localPath);
+    const remoteSize = await remoteFileSize(sftp, remotePath);
+    if (localStat.size !== expectedSize) {
+        throw new Error(`Local size mismatch: local=${localStat.size} expected=${expectedSize}`);
+    }
+    if (remoteSize !== expectedSize) {
+        throw new Error(`Remote size mismatch: remote=${remoteSize} expected=${expectedSize}`);
+    }
+    if (verify === "size+sha256") {
+        const [localHash, remoteHash] = await Promise.all([
+            sha256File(localPath),
+            execSha256(remotePath),
+        ]);
+        if (localHash !== remoteHash) {
+            throw new Error(`sha256 mismatch: local=${localHash} remote=${remoteHash}`);
+        }
+    }
+}
+/**
+ * Transfer a local file or directory to/from bastion over an independent SFTP connection.
+ */
+export async function transferLocalBastion(params, execSha256) {
+    const { direction, localPath, remotePath, config } = params;
+    const opts = params.options ?? {};
+    const transferId = opts.transferId ?? createTransferId();
+    const skipIfComplete = opts.skipIfComplete === true;
+    const verify = resolveEffectiveVerify(skipIfComplete, opts.verify);
+    const totalTimeoutMs = opts.totalTimeoutMs ?? config.defaultTimeoutMs;
+    const connectionTimeoutMs = opts.connectionTimeoutMs ?? DEFAULT_CONNECTION_TIMEOUT_MS;
+    const progressIntervalMs = opts.progressIntervalMs ?? DEFAULT_PROGRESS_INTERVAL_MS;
+    const signal = opts.signal;
+    const sha = (p) => execSha256(p, totalTimeoutMs);
+    throwIfAborted(signal);
+    let sftp = null;
+    let abortHandler;
+    const run = async () => {
+        sftp = await connectSftp(config, connectionTimeoutMs);
+        throwIfAborted(signal);
+        abortHandler = () => {
+            void safeEnd(sftp);
+        };
+        if (signal) {
+            if (signal.aborted) {
+                throw new Error("Copy aborted");
+            }
+            signal.addEventListener("abort", abortHandler, { once: true });
+        }
+        const localStat = await fs.stat(localPath).catch(() => undefined);
+        if (direction === "upload") {
+            if (!localStat) {
+                throw new Error(`Local path not found: ${localPath}`);
+            }
+            if (localStat.isFile()) {
+                return uploadOneFile(sftp, localPath, remotePath, localStat.size);
+            }
+            if (localStat.isDirectory()) {
+                return uploadDirectory(sftp, localPath, remotePath);
+            }
+            throw new Error(`Unsupported local path type: ${localPath}`);
+        }
+        const isDir = await remoteIsDirectory(sftp, remotePath).catch(() => false);
+        if (isDir) {
+            return downloadDirectory(sftp, remotePath, localPath);
+        }
+        const remoteSize = await remoteFileSize(sftp, remotePath);
+        if (remoteSize === undefined) {
+            throw new Error(`Remote path not found: ${remotePath}`);
+        }
+        return downloadOneFile(sftp, remotePath, localPath, remoteSize);
+    };
+    function resultBase(bytes, totalBytes, skippedBytes, usedFastPath) {
+        return {
+            bytes,
+            totalBytes,
+            ...transferSkipFields(skippedBytes, verify),
+            transferId,
+            verified: verify !== "none",
+            usedFastPath,
+        };
+    }
+    async function uploadOneFile(client, local, remote, size) {
+        const remoteDir = path.posix.dirname(remote.replace(/\\/g, "/"));
+        if (remoteDir && remoteDir !== ".") {
+            await client.mkdir(remoteDir, true);
+        }
+        if (skipIfComplete) {
+            try {
+                const existing = await remoteFileSize(client, remote);
+                if (existing === size) {
+                    await verifyFile(client, local, remote, size, verify, sha);
+                    opts.onProgress?.({
+                        transferred: size,
+                        total: size,
+                        percent: 100,
+                        skippedBytes: size,
+                    });
+                    return resultBase(size, size, size, false);
+                }
+            }
+            catch (error) {
+                if (isAbortError(error, signal)) {
+                    throw error;
+                }
+            }
+        }
+        const reporter = createProgressReporter(progressIntervalMs, opts.onProgress, 0);
+        await client.fastPut(local, remote, {
+            step: (total_transferred, _chunk, total) => {
+                reporter.report(total_transferred, total);
+            },
+        });
+        reporter.flush(size, size);
+        await verifyFile(client, local, remote, size, verify, sha);
+        return resultBase(size, size, 0, true);
+    }
+    async function downloadOneFile(client, remote, local, size) {
+        await fs.mkdir(path.dirname(local), { recursive: true });
+        if (skipIfComplete) {
+            try {
+                const st = await fs.stat(local);
+                if (st.isFile() && st.size === size) {
+                    await verifyFile(client, local, remote, size, verify, sha);
+                    opts.onProgress?.({
+                        transferred: size,
+                        total: size,
+                        percent: 100,
+                        skippedBytes: size,
+                    });
+                    return resultBase(size, size, size, false);
+                }
+            }
+            catch (error) {
+                if (isAbortError(error, signal)) {
+                    throw error;
+                }
+            }
+        }
+        if (size === 0) {
+            await fs.writeFile(local, "");
+            return resultBase(0, 0, 0, false);
+        }
+        const reporter = createProgressReporter(progressIntervalMs, opts.onProgress, 0);
+        await client.fastGet(remote, local, {
+            step: (total_transferred, _chunk, total) => {
+                reporter.report(total_transferred, total);
+            },
+        });
+        reporter.flush(size, size);
+        await verifyFile(client, local, remote, size, verify, sha);
+        return resultBase(size, size, 0, true);
+    }
+    async function uploadDirectory(client, localRoot, remoteRoot) {
+        const files = await walkLocalFiles(localRoot);
+        const totalBytes = files.reduce((s, f) => s + f.size, 0);
+        await client.mkdir(remoteRoot.replace(/\\/g, "/"), true);
+        let transferred = 0;
+        let skippedBytes = 0;
+        const reporter = createProgressReporter(progressIntervalMs, opts.onProgress, 0);
+        for (const file of files) {
+            throwIfAborted(signal);
+            const remoteFile = posixJoin(remoteRoot, file.remotePath);
+            const remoteDir = path.posix.dirname(remoteFile);
+            await client.mkdir(remoteDir, true);
+            let skipped = false;
+            if (skipIfComplete) {
+                try {
+                    const existing = await remoteFileSize(client, remoteFile);
+                    if (existing === file.size) {
+                        await verifyFile(client, file.localPath, remoteFile, file.size, verify, sha);
+                        skipped = true;
+                        skippedBytes += file.size;
+                        transferred += file.size;
+                        reporter.report(transferred, totalBytes);
+                    }
+                }
+                catch (error) {
+                    if (isAbortError(error, signal)) {
+                        throw error;
+                    }
+                }
+            }
+            if (!skipped) {
+                await client.fastPut(file.localPath, remoteFile, {
+                    step: (n, _c, fileTotal) => {
+                        reporter.report(transferred + n, totalBytes);
+                        void fileTotal;
+                    },
+                });
+                transferred += file.size;
+                reporter.report(transferred, totalBytes);
+            }
+        }
+        reporter.flush(transferred, totalBytes);
+        const remoteFiles = await walkRemoteFiles(client, remoteRoot.replace(/\\/g, "/"));
+        await verifyDirectoryTree(client, files, remoteFiles, "upload", verify, sha);
+        return resultBase(transferred, totalBytes, skippedBytes, skippedBytes < totalBytes);
+    }
+    async function downloadDirectory(client, remoteRoot, localRoot) {
+        const remoteFiles = await walkRemoteFiles(client, remoteRoot.replace(/\\/g, "/"));
+        const totalBytes = remoteFiles.reduce((s, f) => s + f.size, 0);
+        await fs.mkdir(localRoot, { recursive: true });
+        let transferred = 0;
+        let skippedBytes = 0;
+        const reporter = createProgressReporter(progressIntervalMs, opts.onProgress, 0);
+        const localFiles = [];
+        for (const file of remoteFiles) {
+            throwIfAborted(signal);
+            const rel = file.localPath.replace(/\\/g, "/");
+            const localFile = path.join(localRoot, rel.replace(/\//g, path.sep));
+            await fs.mkdir(path.dirname(localFile), { recursive: true });
+            let skipped = false;
+            if (skipIfComplete) {
+                try {
+                    const st = await fs.stat(localFile);
+                    if (st.isFile() && st.size === file.size) {
+                        await verifyFile(client, localFile, file.remotePath, file.size, verify, sha);
+                        skipped = true;
+                        skippedBytes += file.size;
+                        transferred += file.size;
+                        localFiles.push({
+                            localPath: localFile,
+                            remotePath: rel,
+                            size: file.size,
+                        });
+                        reporter.report(transferred, totalBytes);
+                    }
+                }
+                catch (error) {
+                    if (isAbortError(error, signal)) {
+                        throw error;
+                    }
+                }
+            }
+            if (!skipped) {
+                await client.fastGet(file.remotePath, localFile, {
+                    step: (n) => {
+                        reporter.report(transferred + n, totalBytes);
+                    },
+                });
+                transferred += file.size;
+                localFiles.push({
+                    localPath: localFile,
+                    remotePath: rel,
+                    size: file.size,
+                });
+                reporter.report(transferred, totalBytes);
+            }
+        }
+        reporter.flush(transferred, totalBytes);
+        await verifyDirectoryTree(client, localFiles, remoteFiles, "download", verify, sha);
+        return resultBase(transferred, totalBytes, skippedBytes, skippedBytes < totalBytes);
+    }
+    try {
+        const result = await Promise.race([
+            run(),
+            new Promise((_, reject) => {
+                const t = setTimeout(() => {
+                    reject(new Error(`Hop1 total timeout after ${totalTimeoutMs}ms`));
+                }, totalTimeoutMs);
+                t.unref?.();
+            }),
+        ]);
+        return result;
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        if (/total timeout/i.test(msg)) {
+            const timeoutErr = new Error(msg);
+            timeoutErr.code = "TIMEOUT";
+            throw timeoutErr;
+        }
+        throw error;
+    }
+    finally {
+        if (signal && abortHandler) {
+            signal.removeEventListener("abort", abortHandler);
+        }
+        await safeEnd(sftp);
+    }
+}
+/**
+ * Path-aligned directory verify.
+ * upload localFiles: remotePath=rel, localPath=abs
+ * download localFiles: remotePath=rel, localPath=abs
+ * remoteFiles: localPath=rel, remotePath=abs
+ */
+async function verifyDirectoryTree(sftp, localFiles, remoteFiles, _mode, verify, execSha256) {
+    if (verify === "none") {
+        return;
+    }
+    const remoteByRel = new Map(remoteFiles.map((f) => [f.localPath.replace(/\\/g, "/"), f]));
+    const localBytes = localFiles.reduce((s, f) => s + f.size, 0);
+    const remoteBytes = remoteFiles.reduce((s, f) => s + f.size, 0);
+    if (localFiles.length !== remoteFiles.length || localBytes !== remoteBytes) {
+        throw new Error(`Directory verify failed: local files=${localFiles.length} bytes=${localBytes} ` +
+            `remote files=${remoteFiles.length} bytes=${remoteBytes}`);
+    }
+    for (const lf of localFiles) {
+        const rel = lf.remotePath.replace(/\\/g, "/");
+        const rf = remoteByRel.get(rel);
+        if (!rf || rf.size !== lf.size) {
+            throw new Error(`Directory verify path/size mismatch for ${rel}`);
+        }
+    }
+    if (verify === "size+sha256") {
+        for (const lf of localFiles) {
+            const rel = lf.remotePath.replace(/\\/g, "/");
+            const rf = remoteByRel.get(rel);
+            if (!rf) {
+                throw new Error(`Directory verify missing remote for ${rel}`);
+            }
+            await verifyFile(sftp, lf.localPath, rf.remotePath, lf.size, "size+sha256", execSha256);
+        }
+    }
+}
+//# sourceMappingURL=hop1-sftp.js.map