mcp-for-i 0.1.13 → 0.3.0

package/dist/controlplane/connectionTest.js

@@ -0,0 +1,329 @@
+import crypto from "crypto";
+import dns from "dns/promises";
+import fs from "fs/promises";
+import net from "net";
+import { createRequire } from "module";
+import { Tools } from "../ibmi/Tools.js";
+import { ACCEPT_NEW_HOSTKEY_ENV, getKnownHostsPath, hostKeyFingerprint, isNewHostKeyAccepted, knownHostId, readKnownHosts } from "../ibmi/knownHosts.js";
+const DNS_TIMEOUT_MS = 5000;
+const PORT_TIMEOUT_MS = 5000;
+const SSH_TIMEOUT_MS = 20000;
+const PROFILE_TIMEOUT_MS = 20000;
+const REJECTED_TTL_MS = 15 * 60 * 1000;
+const PASSWORD_WARNING_DAYS = 14;
+/** Passwords the IBM i rejected recently, by hash of host, port, user and password. */
+const rejected = new Map();
+function rejectionKey(target, port) {
+    return crypto.createHash("sha256")
+        .update([target.host.trim().toLowerCase(), port, target.username.trim().toUpperCase(), target.password || ""].join("\0"))
+        .digest("hex");
+}
+function wasRejected(key, now) {
+    const at = rejected.get(key);
+    if (at === undefined)
+        return false;
+    if (now - at > REJECTED_TTL_MS) {
+        rejected.delete(key);
+        return false;
+    }
+    return true;
+}
+/** Forgets every remembered rejection (for tests). */
+export function clearRejectedPasswords() {
+    rejected.clear();
+}
+export async function testConnection(target, deps = {}) {
+    const d = { ...defaultDeps, ...deps };
+    const started = d.now();
+    const steps = [];
+    const warnings = [];
+    let hostKey;
+    let profile;
+    const finish = (code, message) => ({
+        ok: code === "ok",
+        code,
+        message,
+        steps,
+        warnings,
+        ...(hostKey ? { hostKey } : {}),
+        ...(profile ? { profile } : {}),
+        testedAt: new Date(d.now()).toISOString(),
+        durationMs: Math.max(0, d.now() - started)
+    });
+    const host = String(target?.host ?? "").trim();
+    const username = String(target?.username ?? "").trim();
+    const port = Number(target?.port || 22);
+    if (!host || !username)
+        return finish("invalid-input", "Enter a host and a username to test.");
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        return finish("invalid-input", "The SSH port must be between 1 and 65535.");
+    // 1. Name lookup
+    let address;
+    try {
+        address = await withTimeout(d.lookup(host), DNS_TIMEOUT_MS, "lookup");
+        steps.push({ name: "Host lookup", ok: true, detail: address === host ? host : `${host} is ${address}` });
+    }
+    catch (err) {
+        steps.push({ name: "Host lookup", ok: false, detail: err?.code || err?.message || String(err) });
+        return finish("host-not-found", `Host ${host} was not found. Check the spelling, or that this computer can resolve it (VPN or DNS).`);
+    }
+    // 2. SSH port
+    try {
+        const banner = await d.probePort(address, port, PORT_TIMEOUT_MS);
+        if (banner && !banner.startsWith("SSH-")) {
+            steps.push({ name: "SSH port", ok: false, detail: `Port ${port} answered, but not with SSH` });
+            return finish("not-ssh", `Port ${port} on ${host} is open but is not an SSH server. Check the port number.`);
+        }
+        steps.push({ name: "SSH port", ok: true, detail: banner ? banner.trim() : `Port ${port} accepted the connection` });
+    }
+    catch (err) {
+        const code = err?.code;
+        steps.push({ name: "SSH port", ok: false, detail: code || err?.message || String(err) });
+        if (code === "ECONNREFUSED") {
+            return finish("port-closed", `${host} refused a connection on port ${port}. SSH may not be running there (STRTCPSVR SERVER(*SSHD)), or the port is wrong.`);
+        }
+        if (code === "ETIMEDOUT" || code === "TIMEOUT") {
+            return finish("port-timeout", `No answer from ${host} on port ${port}. The system may be down, or a firewall or VPN is blocking the port.`);
+        }
+        if (code === "EHOSTUNREACH" || code === "ENETUNREACH") {
+            return finish("host-unreachable", `${host} cannot be reached from this computer. Check the network or VPN.`);
+        }
+        return finish("error", `Could not open port ${port} on ${host}: ${err?.message || err}`);
+    }
+    // 3. Credentials available?
+    let privateKey;
+    if (target.privateKeyPath) {
+        try {
+            privateKey = await d.readKey(target.privateKeyPath);
+        }
+        catch (err) {
+            steps.push({ name: "Private key", ok: false, detail: err?.code || err?.message || String(err) });
+            return finish("key-unreadable", `The private key ${target.privateKeyPath} could not be read on this computer.`);
+        }
+    }
+    if (!target.password && !privateKey) {
+        return finish("no-credentials", "The host and SSH port work. Enter a password or a private key path to test the sign-on.");
+    }
+    const key = rejectionKey(target, port);
+    if (target.password && !privateKey && wasRejected(key, d.now())) {
+        return finish("password-already-rejected", `${host} already rejected this password for ${username.toUpperCase()}. It was not sent again, because every failed sign-on counts toward disabling the profile. Enter a different password.`);
+    }
+    // 4. Host key and sign-on
+    const outcome = await d.ssh({
+        host,
+        port,
+        username,
+        password: target.password,
+        privateKey,
+        timeoutMs: SSH_TIMEOUT_MS,
+        checkHostKey: async (raw) => {
+            const check = await d.checkHostKey(host, port, raw);
+            hostKey = check;
+            return check;
+        }
+    });
+    if (hostKey && hostKey.status !== "changed") {
+        steps.push({
+            name: "Host key",
+            ok: true,
+            detail: hostKey.status === "trusted" ? "Matches the saved key" : `New key ${hostKey.fingerprint}, saved on the first connection`
+        });
+    }
+    if (outcome.kind === "host-key-changed") {
+        hostKey = outcome.hostKey;
+        steps.push({ name: "Host key", ok: false, detail: `Saved ${outcome.hostKey.stored}, server sent ${outcome.hostKey.fingerprint}` });
+        return finish("host-key-changed", `The SSH host key of ${host} has changed, so the password was not sent. If the system was rebuilt or its keys were regenerated, remove its entry from ${getKnownHostsPath()} or set ${ACCEPT_NEW_HOSTKEY_ENV}=${knownHostId(host, port)}.`);
+    }
+    if (outcome.kind === "password-expired") {
+        steps.push({ name: "Sign-on", ok: false, detail: outcome.prompt || "Password change required" });
+        return finish("password-expired", `The password for ${username.toUpperCase()} has expired. Change it on the IBM i (for example with a 5250 sign-on), then save the new one here.`);
+    }
+    if (outcome.kind === "error") {
+        const err = outcome.error;
+        const level = err?.level;
+        const text = String(err?.message || err);
+        steps.push({ name: "Sign-on", ok: false, detail: text });
+        if (level === "client-authentication" || /authentication methods failed/i.test(text)) {
+            if (target.password && !privateKey)
+                rejected.set(key, d.now());
+            return finish("auth-failed", privateKey && !target.password
+                ? `${host} did not accept the private key for ${username.toUpperCase()}. Check that its public key is in the user's ~/.ssh/authorized_keys on the IBM i.`
+                : `${host} rejected the username or password for ${username.toUpperCase()}. A disabled profile or an expired password gets the same answer over SSH, so check those too if the password is right.`);
+        }
+        if (level === "client-timeout" || /timed out/i.test(text)) {
+            return finish("timeout", `${host} did not finish the SSH sign-on in time. The system may be busy; try again.`);
+        }
+        if (/privateKey|private key|Unsupported key format|Cannot parse/i.test(text)) {
+            return finish("key-unreadable", `The private key ${target.privateKeyPath} could not be used: ${text}`);
+        }
+        return finish("error", `The SSH sign-on failed: ${text}`);
+    }
+    rejected.delete(key);
+    steps.push({ name: "Sign-on", ok: true, detail: `Signed on as ${username.toUpperCase()} and signed off` });
+    const days = outcome.profile?.daysUntilPasswordExpires;
+    if (typeof days === "number") {
+        profile = { daysUntilPasswordExpires: days };
+        if (days >= 0 && days <= PASSWORD_WARNING_DAYS) {
+            warnings.push(days === 0 ? "The password expires today." : `The password expires in ${days} day${days === 1 ? "" : "s"}.`);
+        }
+    }
+    return finish("ok", `Connected to ${host} as ${username.toUpperCase()}.`);
+}
+function withTimeout(promise, ms, what) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(Object.assign(new Error(`${what} timed out`), { code: "TIMEOUT" })), ms);
+        promise.then(value => { clearTimeout(timer); resolve(value); }, err => { clearTimeout(timer); reject(err); });
+    });
+}
+async function lookupHost(host) {
+    if (net.isIP(host))
+        return host;
+    const result = await dns.lookup(host);
+    return result.address;
+}
+function probePort(address, port, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const socket = net.connect({ host: address, port });
+        let connected = false;
+        let banner = "";
+        const done = (err) => {
+            clearTimeout(timer);
+            socket.destroy();
+            if (err)
+                reject(err);
+            else
+                resolve(banner);
+        };
+        const timer = setTimeout(() => {
+            // Connected but silent: still a working port, just no banner yet.
+            if (connected)
+                done();
+            else
+                done(Object.assign(new Error("Connection timed out"), { code: "ETIMEDOUT" }));
+        }, timeoutMs);
+        socket.once("connect", () => { connected = true; });
+        socket.on("data", chunk => {
+            banner += chunk.toString("latin1");
+            if (banner.includes("\n") || banner.length >= 255) {
+                banner = banner.split(/\r?\n/)[0];
+                done();
+            }
+        });
+        socket.once("error", err => done(err));
+        socket.once("end", () => done());
+    });
+}
+async function checkStoredHostKey(host, port, key) {
+    const fingerprint = hostKeyFingerprint(key);
+    const data = await readKnownHosts(getKnownHostsPath());
+    const existing = data.hosts[knownHostId(host, port)];
+    if (!existing)
+        return { status: "new", fingerprint };
+    if (existing.fingerprint === fingerprint)
+        return { status: "trusted", fingerprint };
+    if (isNewHostKeyAccepted(process.env[ACCEPT_NEW_HOSTKEY_ENV], host, port, fingerprint)) {
+        return { status: "new", fingerprint, stored: existing.fingerprint };
+    }
+    return { status: "changed", fingerprint, stored: existing.fingerprint };
+}
+/** Days until the password expires (null when it never does). */
+const PROFILE_SQL = "SELECT DAYS_UNTIL_PASSWORD_EXPIRES AS DAYS FROM QSYS2.USER_INFO WHERE AUTHORIZATION_NAME = USER";
+const PROFILE_COMMAND = "LC_ALL=EN_US.UTF-8 /QOpenSys/usr/bin/qsh -c " +
+    Tools.shellQuote(`system "call QSYS/QZDFMDB2 PARM('-d' '-i' '-t')"`);
+function sshAttempt(options) {
+    const require = createRequire(import.meta.url);
+    const { Client } = require("ssh2");
+    return new Promise(resolve => {
+        const client = new Client();
+        let settled = false;
+        let hostKeyChanged;
+        const settle = (outcome) => {
+            if (settled)
+                return;
+            settled = true;
+            try {
+                client.end();
+            }
+            catch { /* already closed */ }
+            resolve(outcome);
+        };
+        client.on("change password", (prompt) => {
+            // Never change the password from a test; just report it.
+            settle({ kind: "password-expired", prompt });
+        });
+        client.on("error", (error) => {
+            if (hostKeyChanged)
+                settle({ kind: "host-key-changed", hostKey: hostKeyChanged });
+            else
+                settle({ kind: "error", error });
+        });
+        client.on("close", () => {
+            if (hostKeyChanged)
+                settle({ kind: "host-key-changed", hostKey: hostKeyChanged });
+            else
+                settle({ kind: "error", error: new Error("The server closed the connection") });
+        });
+        client.on("ready", async () => {
+            const profile = await readProfile(client).catch(() => undefined);
+            settle({ kind: "ready", profile });
+        });
+        client.connect({
+            host: options.host,
+            port: options.port,
+            username: options.username,
+            password: options.password,
+            privateKey: options.privateKey,
+            tryKeyboard: false,
+            readyTimeout: options.timeoutMs,
+            hostVerifier: (key, verify) => {
+                options.checkHostKey(key)
+                    .then(check => {
+                    if (check.status === "changed")
+                        hostKeyChanged = check;
+                    verify(check.status !== "changed");
+                })
+                    .catch(() => verify(false));
+            }
+        });
+    });
+}
+function readProfile(client) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error("profile query timed out")), PROFILE_TIMEOUT_MS);
+        client.exec(PROFILE_COMMAND, (err, stream) => {
+            if (err) {
+                clearTimeout(timer);
+                reject(err);
+                return;
+            }
+            let stdout = "";
+            stream.on("data", (chunk) => { stdout += chunk.toString("utf8"); });
+            stream.stderr.on("data", () => undefined);
+            stream.on("close", () => {
+                clearTimeout(timer);
+                try {
+                    const rows = Tools.db2Parse(stdout, PROFILE_SQL);
+                    const row = rows[0];
+                    if (!row)
+                        return resolve(undefined);
+                    const days = row.DAYS === null || row.DAYS === undefined || row.DAYS === "" ? undefined : Number(row.DAYS);
+                    resolve({
+                        daysUntilPasswordExpires: Number.isFinite(days) ? days : undefined
+                    });
+                }
+                catch (parseErr) {
+                    reject(parseErr);
+                }
+            });
+            stream.end(`${PROFILE_SQL}\n`);
+        });
+    });
+}
+const defaultDeps = {
+    lookup: lookupHost,
+    probePort,
+    readKey: path => fs.readFile(path, "utf8"),
+    checkHostKey: checkStoredHostKey,
+    ssh: sshAttempt,
+    now: () => Date.now()
+};

package/dist/controlplane/errors.js

@@ -0,0 +1,12 @@
+/**
+ * Error carrying an HTTP status code. The control-plane server maps it to the
+ * response status; any other error becomes a 500.
+ */
+export class ControlPlaneError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = "ControlPlaneError";
+    }
+}

package/dist/controlplane/runtimeService.js

@@ -4,6 +4,7 @@ import os from "os";
 import path from "path";
 import { fileURLToPath } from "url";
 import { getPlatformDescriptor } from "./platform.js";
+import { ControlPlaneError } from "./errors.js";
 import { disableBackgroundService, enableBackgroundService, getServiceStatus } from "./serviceManager.js";
 export class RuntimeService {
     rootDir;
@@ -13,6 +14,7 @@ export class RuntimeService {
         enableService: makeJob("enableService"),
         disableService: makeJob("disableService")
     };
+    pending = new Map();
     constructor(rootDir) {
         this.rootDir = rootDir;
     }
@@ -20,6 +22,7 @@ export class RuntimeService {
         return this.state;
     }
     async getVersions(options) {
+        const source = resolveSkillsSource(options);
         const mode = await this.detectExecutionModeQuiet();
         const checkedAt = new Date().toISOString();
         const mcpInstalled = await this.readLocalPackageVersion(this.rootDir);
@@ -27,8 +30,7 @@ export class RuntimeService {
         const mcpStatus = mcpInstalled && mcpLatest
             ? (mcpInstalled === mcpLatest ? "latest" : "update-available")
             : "unknown";
-        const configuredRepo = sanitizeRepoUrl(options?.repoUrl) || process.env.MCP_FOR_I_SKILLS_REPO || DEFAULT_SKILLS_REPO;
-        const configuredBranch = sanitizeBranch(options?.branch) || process.env.MCP_FOR_I_SKILLS_BRANCH || "main";
+        const { repoUrl: configuredRepo, branch: configuredBranch } = source;
         const skillsDir = path.join(this.rootDir, "skills");
         const skillsGit = path.join(skillsDir, ".git");
         const skills = {
@@ -89,14 +91,14 @@ export class RuntimeService {
         });
     }
     async updateSkills(options) {
+        // Validate before starting the job so bad input is a 400, not a failed job.
+        const { repoUrl, branch } = resolveSkillsSource(options);
         return this.runJob("updateSkills", async (push) => {
-            const repoUrl = sanitizeRepoUrl(options?.repoUrl) || process.env.MCP_FOR_I_SKILLS_REPO || DEFAULT_SKILLS_REPO;
-            const branch = sanitizeBranch(options?.branch) || process.env.MCP_FOR_I_SKILLS_BRANCH || "main";
             const skillsDir = path.join(this.rootDir, "skills");
             const hasSkills = await pathExists(skillsDir);
             push(`Using skills repository: ${repoUrl} (${branch})`);
             if (!hasSkills) {
-                await this.runCommand("git", ["clone", "--depth", "1", "--branch", branch, repoUrl, skillsDir], this.rootDir, push);
+                await this.runCommand("git", ["clone", "--depth", "1", "--branch", branch, "--", repoUrl, skillsDir], this.rootDir, push);
                 return;
             }
             const skillsGit = path.join(skillsDir, ".git");
@@ -104,7 +106,7 @@ export class RuntimeService {
                 const currentRemote = await this.getGitRemoteUrl(skillsDir, push);
                 if (currentRemote && currentRemote !== repoUrl) {
                     push(`Switching skills remote from ${currentRemote} to ${repoUrl}`);
-                    await this.runCommand("git", ["remote", "set-url", "origin", repoUrl], skillsDir, push);
+                    await this.runCommand("git", ["remote", "set-url", "--", "origin", repoUrl], skillsDir, push);
                 }
                 await this.runCommand("git", ["fetch", "origin", branch], skillsDir, push);
                 await this.runCommand("git", ["checkout", branch], skillsDir, push);
@@ -115,7 +117,7 @@ export class RuntimeService {
             push(`Existing skills directory is not a git repository. Backing it up to ${backupDir}`);
             await fs.rename(skillsDir, backupDir);
             try {
-                await this.runCommand("git", ["clone", "--depth", "1", "--branch", branch, repoUrl, skillsDir], this.rootDir, push);
+                await this.runCommand("git", ["clone", "--depth", "1", "--branch", branch, "--", repoUrl, skillsDir], this.rootDir, push);
             }
             catch (error) {
                 push("Clone failed. Restoring previous skills directory.");
@@ -152,6 +154,15 @@ export class RuntimeService {
                 push(`Target: ${status.target}`);
         });
     }
+    /** Resolves when the given job has finished (immediately if it is not running). */
+    async waitForJob(kind) {
+        await this.pending.get(kind);
+        return this.state[kind];
+    }
+    /**
+     * Starts a job in the background and returns it right away with status
+     * "running". Progress is read through getStatus() (GET /api/runtime/status).
+     */
     async runJob(kind, fn) {
         const current = this.state[kind];
         if (current.status === "running") {
@@ -167,19 +178,23 @@ export class RuntimeService {
                 job.output.splice(0, job.output.length - 300);
             }
         };
-        try {
-            await fn(push);
-            job.status = "success";
-        }
-        catch (err) {
-            job.status = "failed";
-            job.error = err?.message || String(err);
-            push(`ERROR: ${job.error}`);
-        }
-        finally {
-            job.finishedAt = new Date().toISOString();
-        }
-        return job;
+        const done = (async () => {
+            try {
+                await fn(push);
+                job.status = "success";
+            }
+            catch (err) {
+                job.status = "failed";
+                job.error = err?.message || String(err);
+                push(`ERROR: ${job.error}`);
+            }
+            finally {
+                job.finishedAt = new Date().toISOString();
+                this.pending.delete(kind);
+            }
+        })();
+        this.pending.set(kind, done);
+        return { ...job, output: [...job.output] };
     }
     runCommand(command, args, cwd, push) {
         return new Promise((resolve, reject) => {
@@ -379,7 +394,7 @@ export class RuntimeService {
     }
     async getRemoteBranchCommitQuiet(repoUrl, branch, short = false) {
         try {
-            const out = await this.runCommandCaptureSilent("git", ["ls-remote", repoUrl, branch], this.rootDir);
+            const out = await this.runCommandCaptureSilent("git", ["ls-remote", "--", repoUrl, branch], this.rootDir);
             const firstLine = out.split(/\r?\n/).find(Boolean);
             if (!firstLine)
                 return undefined;
@@ -453,22 +468,79 @@ async function resolveNpmLaunch() {
     }
     return { mode: "command", path: process.platform === "win32" ? "npm.cmd" : "npm" };
 }
-function sanitizeRepoUrl(value) {
-    if (!value)
+/**
+ * Picks the skills repository and branch (request, then environment, then
+ * defaults) and validates them. Throws a 400 error for unsafe values.
+ */
+export function resolveSkillsSource(options) {
+    const repoUrl = sanitizeRepoUrl(options?.repoUrl)
+        || sanitizeRepoUrl(process.env.MCP_FOR_I_SKILLS_REPO)
+        || DEFAULT_SKILLS_REPO;
+    const branch = sanitizeBranch(options?.branch)
+        || sanitizeBranch(process.env.MCP_FOR_I_SKILLS_BRANCH)
+        || "main";
+    return { repoUrl, branch };
+}
+/**
+ * Accepts only https://, ssh:// and scp-style (user@host:path) git URLs.
+ * Anything that git could read as an option (leading "-") or that uses another
+ * transport (ext::, file://, local paths) is rejected.
+ */
+export function sanitizeRepoUrl(value) {
+    if (typeof value !== "string")
         return undefined;
     const trimmed = value.trim();
     if (!trimmed)
         return undefined;
-    return trimmed;
+    const invalid = () => new ControlPlaneError(400, "repoUrl must be an https://, ssh:// or user@host:path git URL");
+    if (trimmed.length > 2048 || trimmed.startsWith("-") || /[\s\x00-\x1f\x7f]/.test(trimmed)) {
+        throw invalid();
+    }
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(trimmed)) {
+        let parsed;
+        try {
+            parsed = new URL(trimmed);
+        }
+        catch {
+            throw invalid();
+        }
+        if (parsed.protocol !== "https:" && parsed.protocol !== "ssh:")
+            throw invalid();
+        if (!parsed.hostname || parsed.hostname.startsWith("-") || parsed.username.startsWith("-"))
+            throw invalid();
+        return trimmed;
+    }
+    // scp-like syntax: git@github.com:owner/repo.git
+    if (/^[A-Za-z0-9._-]+@[A-Za-z0-9][A-Za-z0-9.-]*:[A-Za-z0-9._~/-]+$/.test(trimmed) && !trimmed.includes("::")) {
+        return trimmed;
+    }
+    throw invalid();
 }
-function sanitizeBranch(value) {
-    if (!value)
+/** Validates a branch name using the git check-ref-format rules. */
+export function sanitizeBranch(value) {
+    if (typeof value !== "string")
         return undefined;
     const trimmed = value.trim();
     if (!trimmed)
         return undefined;
+    if (!isSafeBranchName(trimmed)) {
+        throw new ControlPlaneError(400, `Invalid branch name: ${JSON.stringify(trimmed.slice(0, 100))}`);
+    }
     return trimmed;
 }
+function isSafeBranchName(name) {
+    if (name.length > 255)
+        return false;
+    if (name.startsWith("-") || name === "@" || name === "HEAD")
+        return false;
+    if (/[\x00-\x20\x7f~^:?*[\\]/.test(name))
+        return false;
+    if (name.includes("..") || name.includes("@{") || name.includes("//"))
+        return false;
+    if (name.startsWith("/") || name.endsWith("/") || name.endsWith("."))
+        return false;
+    return name.split("/").every(part => part.length > 0 && !part.startsWith(".") && !part.endsWith(".lock"));
+}
 async function safeRename(from, to) {
     try {
         await fs.rename(from, to);