host-execution-mcp 1.0.0

package/dist/access/session-pool.js

@@ -0,0 +1,46 @@
+import { bashSingleQuote, buildSshRemoteCommand } from "../utils/shell-quote.js";
+/**
+ * Session pool keyed by context.key. Context itself never holds clients.
+ * Phase 1: access entry ??AccessClient; derived ??parent accessClient + ssh/sshpass.
+ */
+export class SessionPool {
+    accessClient;
+    entries = new Map();
+    constructor(accessClient) {
+        this.accessClient = accessClient;
+    }
+    bindAccess(ctx) {
+        this.entries.set(ctx.key, { kind: "access" });
+    }
+    bindDerived(ctx, spec) {
+        if (!ctx.parentKey) {
+            throw new Error("derived context requires parentKey");
+        }
+        this.entries.set(ctx.key, {
+            kind: "derived",
+            parentKey: ctx.parentKey,
+            host: spec.host,
+            user: spec.user,
+            password: spec.password,
+        });
+    }
+    getEntry(contextKey) {
+        return this.entries.get(contextKey);
+    }
+    async exec(ctx, command, timeoutMs, cwd) {
+        const entry = this.entries.get(ctx.key);
+        if (!entry) {
+            throw new Error(`No SessionPool binding for context key=${ctx.key}`);
+        }
+        if (entry.kind === "access") {
+            return this.accessClient.exec(command, timeoutMs, cwd);
+        }
+        // Derived host: wrap command in ssh from ACCESS (accessClient) session.
+        const remoteCommand = cwd
+            ? `cd ${bashSingleQuote(cwd)} && ${command}`
+            : command;
+        const sshCommand = buildSshRemoteCommand(entry.user, entry.host, remoteCommand, entry.password);
+        return this.accessClient.exec(sshCommand, timeoutMs);
+    }
+}
+//# sourceMappingURL=session-pool.js.map

package/dist/access/session-pool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-pool.js","sourceRoot":"","sources":["../../src/access/session-pool.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAajF;;;GAGG;AACH,MAAM,OAAO,WAAW;IAGO;IAFZ,OAAO,GAAG,IAAI,GAAG,EAAqB,CAAC;IAExD,YAA6B,YAA0B;QAA1B,iBAAY,GAAZ,YAAY,CAAc;IAAG,CAAC;IAE3D,UAAU,CAAC,GAAyB;QAClC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;IAChD,CAAC;IAED,WAAW,CAAC,GAAyB,EAAE,IAAgB;QACrD,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC;YACnB,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;QACxD,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE;YACxB,IAAI,EAAE,SAAS;YACf,SAAS,EAAE,GAAG,CAAC,SAAS;YACxB,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,QAAQ,EAAE,IAAI,CAAC,QAAQ;SACxB,CAAC,CAAC;IACL,CAAC;IAED,QAAQ,CAAC,UAAkB;QACzB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IACtC,CAAC;IAED,KAAK,CAAC,IAAI,CACR,GAAyB,EACzB,OAAe,EACf,SAAkB,EAClB,GAAY;QAEZ,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACxC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,KAAK,CAAC,0CAA0C,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC;QACvE,CAAC;QACD,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC5B,OAAO,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,CAAC,CAAC;QACzD,CAAC;QACD,wEAAwE;QACxE,MAAM,aAAa,GAAG,GAAG;YACvB,CAAC,CAAC,MAAM,eAAe,CAAC,GAAG,CAAC,OAAO,OAAO,EAAE;YAC5C,CAAC,CAAC,OAAO,CAAC;QACZ,MAAM,UAAU,GAAG,qBAAqB,CACtC,KAAK,CAAC,IAAI,EACV,KAAK,CAAC,IAAI,EACV,aAAa,EACb,KAAK,CAAC,QAAQ,CACf,CAAC;QACF,OAAO,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;IACvD,CAAC;CACF"}

package/dist/access/ssh-transport.d.ts

@@ -0,0 +1,16 @@
+import type { AppConfig } from "../config.js";
+import { type DeriveSpec, type HostExecutionContext } from "./types.js";
+/**
+ * SSH AccessTransport: produce HostExecutionContext only (no sessions).
+ * Phase 1: ACCESS_KIND=ssh. Paradi is Phase 3.
+ */
+export declare class SshAccessTransport {
+    createAccessContext(config: AppConfig): HostExecutionContext;
+    /**
+     * Derive a child context for a second-hop host.
+     * Does not open SSH; SessionPool binds credentials separately.
+     */
+    deriveContext(parent: HostExecutionContext, spec: DeriveSpec): HostExecutionContext;
+    /** Default derive target from config (selector only ??does not create a Context). */
+    defaultDeriveSpec(config: AppConfig): DeriveSpec | undefined;
+}

package/dist/access/ssh-transport.js

@@ -0,0 +1,74 @@
+import { createHash } from "node:crypto";
+import { buildContextKey, initialCapabilities, } from "./types.js";
+function deriveAuthIdentity(spec) {
+    if (!spec.password) {
+        return "key-or-agent";
+    }
+    const digest = createHash("sha256").update(spec.password).digest("hex").slice(0, 16);
+    return `pw:${digest}`;
+}
+/**
+ * SSH AccessTransport: produce HostExecutionContext only (no sessions).
+ * Phase 1: ACCESS_KIND=ssh. Paradi is Phase 3.
+ */
+export class SshAccessTransport {
+    createAccessContext(config) {
+        if (config.accessKind !== "ssh") {
+            throw new Error(`SshAccessTransport only supports ACCESS_KIND=ssh (got ${config.accessKind})`);
+        }
+        const host = config.accessHost;
+        const user = config.accessUser;
+        return {
+            key: buildContextKey({
+                transport: "ssh",
+                host,
+                user,
+                port: config.accessPort,
+                authIdentity: user,
+            }),
+            transport: "ssh",
+            endpoint: { host, user, port: config.accessPort },
+            capabilities: initialCapabilities(true),
+        };
+    }
+    /**
+     * Derive a child context for a second-hop host.
+     * Does not open SSH; SessionPool binds credentials separately.
+     */
+    deriveContext(parent, spec) {
+        if (parent.transport !== "ssh") {
+            throw new Error(`deriveContext requires parent transport=ssh (got ${parent.transport})`);
+        }
+        return {
+            key: buildContextKey({
+                transport: "ssh",
+                host: spec.host,
+                user: spec.user,
+                port: spec.port ?? 22,
+                parentKey: parent.key,
+                authIdentity: deriveAuthIdentity(spec),
+            }),
+            transport: "ssh",
+            endpoint: { host: spec.host, user: spec.user, port: spec.port ?? 22 },
+            parentKey: parent.key,
+            capabilities: initialCapabilities(true),
+        };
+    }
+    /** Default derive target from config (selector only ??does not create a Context). */
+    defaultDeriveSpec(config) {
+        const host = config.targetHost?.trim();
+        if (!host) {
+            return undefined;
+        }
+        const user = config.targetUser?.trim();
+        if (!user) {
+            throw new Error("TARGET_HOST is set but TARGET_USER is missing");
+        }
+        return {
+            host,
+            user,
+            password: config.targetPassword,
+        };
+    }
+}
+//# sourceMappingURL=ssh-transport.js.map

package/dist/access/ssh-transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssh-transport.js","sourceRoot":"","sources":["../../src/access/ssh-transport.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EACL,eAAe,EACf,mBAAmB,GAGpB,MAAM,YAAY,CAAC;AAEpB,SAAS,kBAAkB,CAAC,IAAgB;IAC1C,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACnB,OAAO,cAAc,CAAC;IACxB,CAAC;IACD,MAAM,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACrF,OAAO,MAAM,MAAM,EAAE,CAAC;AACxB,CAAC;AAED;;;GAGG;AACH,MAAM,OAAO,kBAAkB;IAC7B,mBAAmB,CAAC,MAAiB;QACnC,IAAI,MAAM,CAAC,UAAU,KAAK,KAAK,EAAE,CAAC;YAChC,MAAM,IAAI,KAAK,CACb,yDAAyD,MAAM,CAAC,UAAU,GAAG,CAC9E,CAAC;QACJ,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,CAAC;QAC/B,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,CAAC;QAC/B,OAAO;YACL,GAAG,EAAE,eAAe,CAAC;gBACnB,SAAS,EAAE,KAAK;gBAChB,IAAI;gBACJ,IAAI;gBACJ,IAAI,EAAE,MAAM,CAAC,UAAU;gBACvB,YAAY,EAAE,IAAI;aACnB,CAAC;YACF,SAAS,EAAE,KAAK;YAChB,QAAQ,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,UAAU,EAAE;YACjD,YAAY,EAAE,mBAAmB,CAAC,IAAI,CAAC;SACxC,CAAC;IACJ,CAAC;IAED;;;OAGG;IACH,aAAa,CAAC,MAA4B,EAAE,IAAgB;QAC1D,IAAI,MAAM,CAAC,SAAS,KAAK,KAAK,EAAE,CAAC;YAC/B,MAAM,IAAI,KAAK,CAAC,oDAAoD,MAAM,CAAC,SAAS,GAAG,CAAC,CAAC;QAC3F,CAAC;QACD,OAAO;YACL,GAAG,EAAE,eAAe,CAAC;gBACnB,SAAS,EAAE,KAAK;gBAChB,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,EAAE;gBACrB,SAAS,EAAE,MAAM,CAAC,GAAG;gBACrB,YAAY,EAAE,kBAAkB,CAAC,IAAI,CAAC;aACvC,CAAC;YACF,SAAS,EAAE,KAAK;YAChB,QAAQ,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,EAAE,EAAE;YACrE,SAAS,EAAE,MAAM,CAAC,GAAG;YACrB,YAAY,EAAE,mBAAmB,CAAC,IAAI,CAAC;SACxC,CAAC;IACJ,CAAC;IAED,qFAAqF;IACrF,iBAAiB,CAAC,MAAiB;QACjC,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC;QACvC,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC;QACvC,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;QACnE,CAAC;QACD,OAAO;YACL,IAAI;YACJ,IAAI;YACJ,QAAQ,EAAE,MAAM,CAAC,cAAc;SAChC,CAAC;IACJ,CAAC;CACF"}

package/dist/access/types.d.ts

@@ -0,0 +1,43 @@
+export type AccessTransportKind = "ssh" | "paradi-gateway";
+/** Capability tri-state: never infer docker/kubectl from SSH success alone. */
+export type Cap = true | false | "unknown";
+export interface ContextCapabilities {
+    exec: Cap;
+    docker: Cap;
+    kubectl: Cap;
+    /** Declared by transport (e.g. paradi); not overwritten by CLI probe. */
+    sftp?: Cap | "degraded";
+    /** Gateway may rate-limit SSH channel opens ? avoid parallel hammering. */
+    channelOpenSensitive?: boolean;
+}
+/**
+ * Host execution descriptor ? must NOT hold SSH sessions or live clients.
+ * Connections live in SessionPool, keyed by stable `key`.
+ */
+export interface HostExecutionContext {
+    key: string;
+    transport: AccessTransportKind;
+    endpoint: {
+        host: string;
+        user?: string;
+        port?: number;
+    };
+    parentKey?: string;
+    capabilities: ContextCapabilities;
+}
+export interface DeriveSpec {
+    host: string;
+    user: string;
+    password?: string;
+    port?: number;
+}
+export declare function initialCapabilities(exec?: Cap): ContextCapabilities;
+/** Stable pool key ? never a per-call random uuid. */
+export declare function buildContextKey(parts: {
+    transport: AccessTransportKind;
+    host: string;
+    user?: string;
+    port?: number;
+    parentKey?: string;
+    authIdentity?: string;
+}): string;

package/dist/access/types.js

@@ -0,0 +1,21 @@
+import { createHash } from "node:crypto";
+export function initialCapabilities(exec = true) {
+    return {
+        exec,
+        docker: "unknown",
+        kubectl: "unknown",
+    };
+}
+/** Stable pool key ? never a per-call random uuid. */
+export function buildContextKey(parts) {
+    const payload = [
+        parts.transport,
+        parts.host,
+        parts.user ?? "",
+        String(parts.port ?? 22),
+        parts.parentKey ?? "",
+        parts.authIdentity ?? "",
+    ].join("|");
+    return createHash("sha256").update(payload).digest("hex").slice(0, 24);
+}
+//# sourceMappingURL=types.js.map

package/dist/access/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/access/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAoCzC,MAAM,UAAU,mBAAmB,CAAC,OAAY,IAAI;IAClD,OAAO;QACL,IAAI;QACJ,MAAM,EAAE,SAAS;QACjB,OAAO,EAAE,SAAS;KACnB,CAAC;AACJ,CAAC;AAED,sDAAsD;AACtD,MAAM,UAAU,eAAe,CAAC,KAO/B;IACC,MAAM,OAAO,GAAG;QACd,KAAK,CAAC,SAAS;QACf,KAAK,CAAC,IAAI;QACV,KAAK,CAAC,IAAI,IAAI,EAAE;QAChB,MAAM,CAAC,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC;QACxB,KAAK,CAAC,SAAS,IAAI,EAAE;QACrB,KAAK,CAAC,YAAY,IAAI,EAAE;KACzB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACZ,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AACzE,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,52 @@
+import type { AccessTransportKind } from "./access/types.js";
+import { type ParadiAuthSetting } from "./access/paradi-auth.js";
+export interface AppConfig {
+    accessKind: AccessTransportKind;
+    accessHost: string;
+    accessUser: string;
+    accessPort: number;
+    accessPrivateKeyPath?: string;
+    accessPassword?: string;
+    /**
+     * Paradi gateway auth encoding. Default auto = try slash then compound; pin winner
+     * for this MCP process. Customers normally leave unset.
+     */
+    accessParadiAuth?: ParadiAuthSetting;
+    /** Default derive selector (ssh only) — does not create a Context at init. */
+    targetHost?: string;
+    targetUser?: string;
+    targetPassword?: string;
+    defaultTimeoutMs: number;
+    maxOutputChars: number;
+    /** Policy (k8s only); not part of Access matrix. Prefer ACCESS_POLICY_ALLOWED_NAMESPACES. */
+    allowedNamespaces?: string[];
+}
+/**
+ * Hop-1 SSH identity: where we TCP-connect and which username to present.
+ * Paradi: uses pinned/auto-preferred mode for username (password resolved separately).
+ */
+export declare function resolveAccessSshIdentity(config: AppConfig): {
+    host: string;
+    port: number;
+    username: string;
+};
+/**
+ * Load MCP config. Only ACCESS_* / TARGET_* (and policy ALLOWED_NAMESPACES).
+ * Legacy BASTION_* / REMOTE_SSH_* aliases were removed in 4.0.0.
+ */
+export declare function loadConfig(env?: NodeJS.ProcessEnv): AppConfig;
+export declare function assertNamespaceAllowed(config: AppConfig, namespace: string): void;
+export declare function resolveDefaultKeyPaths(homeDir?: string, exists?: (path: string) => boolean): string[];
+export interface ResolveSshAuthDeps {
+    env?: NodeJS.ProcessEnv;
+    homeDir?: string;
+    existsSync?: (path: string) => boolean;
+    readFileSync?: (path: string) => Buffer;
+}
+/** Collect every configured ACCESS auth method; ssh2 tries them until one succeeds. */
+export declare function resolveSshAuthOptions(config: AppConfig, deps?: ResolveSshAuthDeps): {
+    privateKey?: Buffer | string;
+    password?: string;
+    agent?: string;
+    authMethods: string[];
+};

package/dist/config.js

@@ -0,0 +1,179 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { getPinnedParadiAuth, parseParadiAuthSetting, resolveParadiConnectParams, } from "./access/paradi-auth.js";
+function parseAllowedNamespaces(value) {
+    if (!value?.trim()) {
+        return undefined;
+    }
+    const list = value
+        .split(",")
+        .map((item) => item.trim())
+        .filter(Boolean);
+    return list.length > 0 ? list : undefined;
+}
+/**
+ * Hop-1 SSH identity: where we TCP-connect and which username to present.
+ * Paradi: uses pinned/auto-preferred mode for username (password resolved separately).
+ */
+export function resolveAccessSshIdentity(config) {
+    if (config.accessKind === "paradi-gateway") {
+        const mode = getPinnedParadiAuth(config) ??
+            (config.accessParadiAuth === "compound" ? "compound" : "slash");
+        const params = resolveParadiConnectParams(config, mode);
+        return {
+            host: params.host,
+            port: params.port,
+            username: params.username,
+        };
+    }
+    return {
+        host: config.accessHost,
+        port: config.accessPort,
+        username: config.accessUser,
+    };
+}
+function firstDefined(...values) {
+    for (const value of values) {
+        const trimmed = value?.trim();
+        if (trimmed) {
+            return trimmed;
+        }
+    }
+    return undefined;
+}
+/**
+ * Load MCP config. Only ACCESS_* / TARGET_* (and policy ALLOWED_NAMESPACES).
+ * Legacy BASTION_* / REMOTE_SSH_* aliases were removed in 4.0.0.
+ */
+export function loadConfig(env = process.env) {
+    rejectRemovedEnvAliases(env);
+    const kindRaw = (env.ACCESS_KIND?.trim() || "ssh").toLowerCase();
+    if (kindRaw !== "ssh" && kindRaw !== "paradi-gateway") {
+        throw new Error(`ACCESS_KIND must be "ssh" or "paradi-gateway" (got "${env.ACCESS_KIND}")`);
+    }
+    const accessKind = kindRaw;
+    const accessHost = env.ACCESS_HOST?.trim();
+    const accessUser = env.ACCESS_USER?.trim();
+    if (!accessHost) {
+        throw new Error("ACCESS_HOST is required");
+    }
+    if (!accessUser) {
+        throw new Error("ACCESS_USER is required");
+    }
+    const port = Number(env.ACCESS_PORT?.trim() || "22");
+    if (!Number.isFinite(port) || port <= 0) {
+        throw new Error("ACCESS_PORT must be a positive number");
+    }
+    const targetHost = env.TARGET_HOST?.trim() || undefined;
+    const targetUser = env.TARGET_USER?.trim() || undefined;
+    // TARGET_PASSWORD ignored for paradi default auth (gateway password is ACCESS_PASSWORD)
+    const targetPassword = accessKind === "paradi-gateway"
+        ? undefined
+        : env.TARGET_PASSWORD || undefined;
+    if (accessKind === "paradi-gateway") {
+        if (!targetHost || !targetUser) {
+            throw new Error("ACCESS_KIND=paradi-gateway requires TARGET_HOST and TARGET_USER");
+        }
+    }
+    else if (targetHost && !targetUser) {
+        throw new Error("TARGET_HOST is set but TARGET_USER is missing (do not fallback to ACCESS_USER)");
+    }
+    const accessParadiAuth = accessKind === "paradi-gateway"
+        ? parseParadiAuthSetting(env.ACCESS_PARADI_AUTH)
+        : undefined;
+    const defaultTimeoutMs = Number(env.DEFAULT_TIMEOUT_MS ?? "60000");
+    const maxOutputChars = Number(env.MAX_OUTPUT_CHARS ?? "65536");
+    if (!Number.isFinite(defaultTimeoutMs) || defaultTimeoutMs <= 0) {
+        throw new Error("DEFAULT_TIMEOUT_MS must be a positive number");
+    }
+    if (!Number.isFinite(maxOutputChars) || maxOutputChars <= 0) {
+        throw new Error("MAX_OUTPUT_CHARS must be a positive number");
+    }
+    return {
+        accessKind,
+        accessHost,
+        accessUser,
+        accessPort: port,
+        accessPrivateKeyPath: env.ACCESS_PRIVATE_KEY_PATH?.trim() || undefined,
+        accessPassword: env.ACCESS_PASSWORD || undefined,
+        accessParadiAuth,
+        targetHost,
+        targetUser,
+        targetPassword,
+        defaultTimeoutMs,
+        maxOutputChars,
+        allowedNamespaces: parseAllowedNamespaces(firstDefined(env.ACCESS_POLICY_ALLOWED_NAMESPACES, env.ALLOWED_NAMESPACES)),
+    };
+}
+/** Fail fast with rename hints when removed env names are still set. */
+function rejectRemovedEnvAliases(env) {
+    const removed = [
+        ["BASTION_HOST", "ACCESS_HOST"],
+        ["BASTION_USER", "ACCESS_USER"],
+        ["BASTION_PORT", "ACCESS_PORT"],
+        ["BASTION_PASSWORD", "ACCESS_PASSWORD"],
+        ["BASTION_PRIVATE_KEY_PATH", "ACCESS_PRIVATE_KEY_PATH"],
+        ["REMOTE_SSH_USER", "TARGET_USER"],
+        ["REMOTE_SSH_PASSWORD", "TARGET_PASSWORD"],
+    ];
+    const hits = removed.filter(([oldName]) => Boolean(env[oldName]?.trim()));
+    if (hits.length === 0) {
+        return;
+    }
+    const hints = hits.map(([oldName, neu]) => `${oldName} ? ${neu}`).join("; ");
+    throw new Error(`Removed env aliases (4.0.0): ${hints}. Use ACCESS_* / TARGET_* only.`);
+}
+export function assertNamespaceAllowed(config, namespace) {
+    if (!config.allowedNamespaces) {
+        return;
+    }
+    if (!config.allowedNamespaces.includes(namespace)) {
+        throw new Error(`Namespace "${namespace}" is not allowed. Allowed: ${config.allowedNamespaces.join(", ")}`);
+    }
+}
+export function resolveDefaultKeyPaths(homeDir = os.homedir(), exists = fs.existsSync) {
+    const sshDir = path.join(homeDir, ".ssh");
+    return ["id_ed25519", "id_rsa", "id_ecdsa"]
+        .map((name) => path.join(sshDir, name))
+        .filter((keyPath) => exists(keyPath));
+}
+/** Collect every configured ACCESS auth method; ssh2 tries them until one succeeds. */
+export function resolveSshAuthOptions(config, deps = {}) {
+    const env = deps.env ?? process.env;
+    const existsSync = deps.existsSync ?? fs.existsSync;
+    const readFileSync = deps.readFileSync ?? fs.readFileSync;
+    const homeDir = deps.homeDir ?? os.homedir();
+    const authMethods = [];
+    let privateKey;
+    if (config.accessPrivateKeyPath) {
+        if (!existsSync(config.accessPrivateKeyPath)) {
+            throw new Error(`ACCESS_PRIVATE_KEY_PATH not found: ${config.accessPrivateKeyPath}`);
+        }
+        privateKey = readFileSync(config.accessPrivateKeyPath);
+        authMethods.push(`key:${config.accessPrivateKeyPath}`);
+    }
+    else {
+        for (const keyPath of resolveDefaultKeyPaths(homeDir, existsSync)) {
+            privateKey = readFileSync(keyPath);
+            authMethods.push(`key:${keyPath}`);
+            break;
+        }
+    }
+    const agentSocket = env.SSH_AUTH_SOCK?.trim();
+    let agent;
+    if (agentSocket && existsSync(agentSocket)) {
+        agent = agentSocket;
+        authMethods.push("agent");
+    }
+    let password;
+    if (config.accessPassword) {
+        password = config.accessPassword;
+        authMethods.push("password");
+    }
+    if (!privateKey && !agent && !password) {
+        throw new Error("No SSH authentication available. Configure SSH agent, ACCESS_PRIVATE_KEY_PATH, default ~/.ssh keys, or ACCESS_PASSWORD.");
+    }
+    return { privateKey, password, agent, authMethods };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadConfig } from "./config.js";
+import { createServer } from "./server.js";
+async function main() {
+    const config = loadConfig();
+    const server = createServer(config);
+    const transport = new StdioServerTransport();
+    process.on("SIGINT", () => {
+        process.exit(0);
+    });
+    await server.connect(transport);
+}
+main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`[host-execution-mcp] Fatal: ${message}`);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;IAC5B,MAAM,MAAM,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IACpC,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAE7C,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE;QACxB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;IAEH,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IAC9B,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACvE,OAAO,CAAC,KAAK,CAAC,+BAA+B,OAAO,EAAE,CAAC,CAAC;IACxD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/instructions.d.ts

@@ -0,0 +1,4 @@
+import type { AppConfig } from "./config.js";
+/** TARGET_* default derive auth so agents omit configured defaults instead of asking the human. */
+export declare function buildDerivedHostAuthGuidance(config: AppConfig): string;
+export declare function buildServerInstructions(config: AppConfig): string;

package/dist/instructions.js

@@ -0,0 +1,93 @@
+function buildSshBaseInstructions() {
+    return `You are connected to host-execution-mcp, a HostExecutionContext-based remote execution MCP.
+
+Execution model:
+  Access:  MCP client → AccessTransport → HostExecutionContext (landing)
+  Runtime: selected Context → shell / docker / k8s / copy (SessionPool; Runtime never creates SSH)
+  Derive:  context_derive → contextKey (ACCESS_KIND=ssh only). NOT SSH from the laptop.
+
+Context vs shell:
+- context_derive — create a derived HostExecutionContext; returns contextKey (does not probe reachability)
+- shell_exec — shell on a Context; never creates Context (omit contextKey = AccessTransport landing)
+- ssh_exec — shortcut for context_derive + shell_exec; returns reusable contextKey. Prefer for derive+shell in one call; reuse the key for follow-up docker_*/remote_*/shell_exec
+
+docker_* / context_probe: Runtime on selected Context.
+Omit contextKey = AccessTransport landing (ACCESS under ssh; TARGET under paradi-gateway).
+
+remote_* target=context = HostExecutionContext by contextKey (from context_derive / ssh_exec).
+
+Tool selection:
+- access_check — Local→ACCESS connectivity (≤10s; NOT kubectl). First session / after ACCESS_UNAVAILABLE
+- shell_exec — landing or derived shell (contextKey)
+- context_derive — need a contextKey without running a command yet
+- ssh_exec — one-shot derive+shell (returns contextKey)
+- docker_* — Docker on landing or contextKey
+- k8s_* — kubectl on landing only (by design). kubectl on a derived host: shell_exec(contextKey, "kubectl …")
+- remote_* target=landing|pod|context — files/ps/copy
+- remote_copy_file vs remote_copy_start — sync vs async; never auto-promote; prefer start when size>256MB or ETA>2min
+
+Hard rules:
+- access_check.reachable=false or code=ACCESS_UNAVAILABLE → stop (VPN / ACCESS_HOST); do not retry other tools
+- SSH success ≠ docker/kubectl; unknown ≠ true — never invent true; never reuse capabilities across Contexts
+- Before pkill/kill/rm: remote_ps or user confirmation
+- Never assume namespace/paths; never reuse ACCESS_USER as TARGET_USER / derive user
+- success=false: read stdout (stderr merged). truncated → more lines / remote_copy_*
+- Multi-container pods: pass container name
+- Operational cookbook (shell quoting, CRLF, docker login quirks, registry probes): see docs/AGENT_GUIDE.md`;
+}
+function buildParadiBaseInstructions(config) {
+    const target = config.targetHost?.trim() || "<TARGET_HOST>";
+    return `You are connected to host-execution-mcp, a HostExecutionContext-based remote execution MCP (ACCESS_KIND=paradi-gateway).
+
+Landing endpoint is TARGET (${target}) — not the gateway OS. Runtime does not know gateway details; never creates SSH.
+
+Derive / context_derive / ssh_exec / remote_* target=context / contextKey: unsupported by current Paradi AccessTransport (landing is already TARGET). Handlers throw if called — omit contextKey; use target=landing|pod|local.
+
+Default workflow:
+- Shell: shell_exec or remote_* target=landing
+- Docker / context_probe: omit contextKey (landing = TARGET)
+- Pods: k8s_* / remote_* target=pod (kubectl on landing)
+- Copy: local↔landing or pod/local; SFTP degraded — prefer remote_copy_start for large files
+
+Hard rules:
+- access_check.reachable=false or ACCESS_UNAVAILABLE → stop (VPN / ACCESS_HOST)
+- unknown ≠ true; SSH success ≠ docker/kubectl; never reuse capabilities across Contexts
+- Before pkill/kill/rm: remote_ps or user confirmation
+- Never assume namespace/paths
+- Operational cookbook: docs/AGENT_GUIDE.md`;
+}
+/** TARGET_* default derive auth so agents omit configured defaults instead of asking the human. */
+export function buildDerivedHostAuthGuidance(config) {
+    if (config.accessKind === "paradi-gateway") {
+        const host = config.targetHost?.trim();
+        return `
+Paradi landing: Context endpoint is TARGET${host ? ` (${host})` : ""}. Derive unsupported by current Paradi AccessTransport — omit contextKey; context_derive / ssh_exec / target=context throw if called. Use shell_exec, docker_*, k8s_*, target=landing|pod|local.`;
+    }
+    const user = config.targetUser?.trim();
+    const passwordSet = Boolean(config.targetPassword);
+    const host = config.targetHost?.trim();
+    const hostHint = host ? ` TARGET_HOST=${host}.` : "";
+    const noAccessUserFallback = " Never reuse ACCESS_USER as TARGET_USER / derive user — pass TARGET_USER (or tool user) explicitly.";
+    const shortcutHint = " ssh_exec = context_derive + shell_exec shortcut (returns reusable contextKey).";
+    if (!user && !passwordSet) {
+        return `
+Derive host auth: TARGET_* unset — pass user (password if no key).${hostHint}${noAccessUserFallback}${shortcutHint} Do not invent defaults.`;
+    }
+    if (user && passwordSet) {
+        return `
+Derive host auth: TARGET_* active (user=${user}, password=set)${hostHint} — omit user/password on context_derive / ssh_exec; do not ask the human. Override only for a different account.${noAccessUserFallback}${shortcutHint}`;
+    }
+    if (user) {
+        return `
+Derive host auth: TARGET_USER=${user}${hostHint} — omit user on context_derive / ssh_exec; pass password only if no key.${noAccessUserFallback}${shortcutHint}`;
+    }
+    return `
+Derive host auth: TARGET_PASSWORD set${hostHint} — omit password on context_derive / ssh_exec; still pass user (TARGET_USER unset). Do not invent a username.${noAccessUserFallback}${shortcutHint}`;
+}
+export function buildServerInstructions(config) {
+    const base = config.accessKind === "paradi-gateway"
+        ? buildParadiBaseInstructions(config)
+        : buildSshBaseInstructions();
+    return `${base}${buildDerivedHostAuthGuidance(config)}`;
+}
+//# sourceMappingURL=instructions.js.map

package/dist/instructions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../src/instructions.ts"],"names":[],"mappings":"AAEA,SAAS,wBAAwB;IAC/B,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4GAkCmG,CAAC;AAC7G,CAAC;AAED,SAAS,2BAA2B,CAAC,MAAiB;IACpD,MAAM,MAAM,GAAG,MAAM,CAAC,UAAU,EAAE,IAAI,EAAE,IAAI,eAAe,CAAC;IAC5D,OAAO;;8BAEqB,MAAM;;;;;;;;;;;;;;;4CAeQ,CAAC;AAC7C,CAAC;AAED,mGAAmG;AACnG,MAAM,UAAU,4BAA4B,CAAC,MAAiB;IAC5D,IAAI,MAAM,CAAC,UAAU,KAAK,gBAAgB,EAAE,CAAC;QAC3C,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC;QACvC,OAAO;4CACiC,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,kMAAkM,CAAC;IACrQ,CAAC;IAED,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC;IACvC,MAAM,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;IACnD,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC;IACvC,MAAM,QAAQ,GAAG,IAAI,CAAC,CAAC,CAAC,gBAAgB,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IACrD,MAAM,oBAAoB,GACxB,qGAAqG,CAAC;IACxG,MAAM,YAAY,GAChB,iFAAiF,CAAC;IAEpF,IAAI,CAAC,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;QAC1B,OAAO;oEACyD,QAAQ,GAAG,oBAAoB,GAAG,YAAY,0BAA0B,CAAC;IAC3I,CAAC;IAED,IAAI,IAAI,IAAI,WAAW,EAAE,CAAC;QACxB,OAAO;0CAC+B,IAAI,kBAAkB,QAAQ,mHAAmH,oBAAoB,GAAG,YAAY,EAAE,CAAC;IAC/N,CAAC;IAED,IAAI,IAAI,EAAE,CAAC;QACT,OAAO;gCACqB,IAAI,GAAG,QAAQ,2EAA2E,oBAAoB,GAAG,YAAY,EAAE,CAAC;IAC9J,CAAC;IAED,OAAO;uCAC8B,QAAQ,gHAAgH,oBAAoB,GAAG,YAAY,EAAE,CAAC;AACrM,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,MAAiB;IACvD,MAAM,IAAI,GACR,MAAM,CAAC,UAAU,KAAK,gBAAgB;QACpC,CAAC,CAAC,2BAA2B,CAAC,MAAM,CAAC;QACrC,CAAC,CAAC,wBAAwB,EAAE,CAAC;IACjC,OAAO,GAAG,IAAI,GAAG,4BAA4B,CAAC,MAAM,CAAC,EAAE,CAAC;AAC1D,CAAC"}

package/dist/kubectl/runner.d.ts

@@ -0,0 +1,32 @@
+import type { AppConfig } from "../config.js";
+import type { AccessClient } from "../ssh/access-client.js";
+export type PodOutputFormat = "wide" | "json" | "name";
+export declare function buildListPodsCommand(namespace: string, options: {
+    labelSelector?: string;
+    fieldSelector?: string;
+    output?: PodOutputFormat;
+}): string;
+export declare function buildKubectlExecCommand(namespace: string, pod: string, command: string, container?: string): string;
+export declare function buildKubectlLogsCommand(namespace: string, pod: string, options: {
+    container?: string;
+    tail?: number;
+    since?: string;
+}): string;
+export declare function runOnAccess(client: AccessClient, config: AppConfig, command: string, timeoutMs?: number, cwd?: string): Promise<import("../ssh/access-client.js").ExecOutput>;
+export declare function validateNamespace(config: AppConfig, namespace: string): void;
+export declare class KubectlRunner {
+    private readonly client;
+    private readonly config;
+    constructor(client: AccessClient, config: AppConfig);
+    listPods(namespace: string, options: {
+        labelSelector?: string;
+        fieldSelector?: string;
+        output?: PodOutputFormat;
+    }, timeoutMs?: number): Promise<import("../ssh/access-client.js").ExecOutput>;
+    exec(namespace: string, pod: string, command: string, container?: string, timeoutMs?: number): Promise<import("../ssh/access-client.js").ExecOutput>;
+    logs(namespace: string, pod: string, options: {
+        container?: string;
+        tail?: number;
+        since?: string;
+    }, timeoutMs?: number): Promise<import("../ssh/access-client.js").ExecOutput>;
+}