@imenam/mcp-ssh-gate 0.0.0-stage → 1.0.0

package/dist/src/core/server-store.js

@@ -0,0 +1,177 @@
+import fs from "node:fs";
+import path from "node:path";
+import ssh2 from "ssh2";
+import { MAX_NOTES_LENGTH } from "../../shared/model.js";
+import { GateError } from "./errors.js";
+import { readJson, withFileLock, writeJsonAtomic } from "./files.js";
+import { decryptSecret, encryptSecret } from "./vault.js";
+const USERNAME_PATTERN = /^[a-z_][a-z0-9_.-]*\$?$/i;
+const HOST_PATTERN = /^[a-z0-9.:\-\[\]]+$/i;
+/** Contrôle et normalise les champs saisis pour un serveur. */
+export function validateServerInput(input) {
+    const name = String(input.name ?? "").trim();
+    const host = String(input.host ?? "").trim();
+    const username = String(input.username ?? "").trim();
+    const port = Number(input.port);
+    if (!name)
+        throw new GateError("Le nom du serveur est obligatoire.");
+    if (name.length > 60)
+        throw new GateError("Le nom du serveur dépasse 60 caractères.");
+    if (!host)
+        throw new GateError("L'hôte est obligatoire.");
+    if (!HOST_PATTERN.test(host))
+        throw new GateError(`Hôte invalide : « ${host} ».`);
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        throw new GateError("Le port doit être un entier entre 1 et 65535.");
+    if (!username)
+        throw new GateError("L'utilisateur est obligatoire.");
+    if (!USERNAME_PATTERN.test(username))
+        throw new GateError(`Utilisateur invalide : « ${username} ».`);
+    return { name, host, port, username };
+}
+function slugify(name) {
+    const slug = name
+        .normalize("NFD")
+        .replace(/[̀-ͯ]/g, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return slug || "serveur";
+}
+export function toPublic(server) {
+    const { privateKeyEncrypted: _privateKey, ...rest } = server;
+    return rest;
+}
+/**
+ * Serveurs SSH : `<DATA_DIR>/servers.json`. La paire de clés est générée à la
+ * création ; seule la clé publique est lisible, la clé privée est chiffrée.
+ */
+export class ServerStore {
+    vaultKey;
+    file;
+    lockFile;
+    constructor(dataDir, vaultKey) {
+        this.vaultKey = vaultKey;
+        this.file = path.join(dataDir, "servers.json");
+        this.lockFile = `${this.file}.lock`;
+    }
+    list() {
+        if (!fs.existsSync(this.file))
+            return [];
+        return readJson(this.file).servers.map((server) => ({
+            ...server,
+            notes: server.notes ?? "",
+            notesUpdatedAt: server.notesUpdatedAt ?? null,
+            notesUpdatedBy: server.notesUpdatedBy ?? null,
+        }));
+    }
+    /** Retrouve un serveur par identifiant ou par nom (sans tenir compte de la casse). */
+    get(idOrName) {
+        const wanted = String(idOrName ?? "").trim().toLowerCase();
+        const servers = this.list();
+        const found = servers.find((s) => s.id === wanted) ?? servers.find((s) => s.name.toLowerCase() === wanted);
+        if (found)
+            return found;
+        const known = servers.map((s) => s.id).join(", ") || "none";
+        throw new GateError(`Unknown server "${idOrName}". Known servers: ${known}.`);
+    }
+    create(input) {
+        const fields = validateServerInput(input);
+        return this.mutate((servers) => {
+            const base = slugify(fields.name);
+            let id = base;
+            for (let n = 2; servers.some((s) => s.id === id); n++)
+                id = `${base}-${n}`;
+            const keys = ssh2.utils.generateKeyPairSync("ed25519", { comment: `mcp-ssh-gate@${id}` });
+            const server = {
+                id,
+                ...fields,
+                publicKey: keys.public,
+                hostKeyFingerprint: null,
+                createdAt: new Date().toISOString(),
+                notes: "",
+                notesUpdatedAt: null,
+                notesUpdatedBy: null,
+                privateKeyEncrypted: encryptSecret(keys.private, this.vaultKey),
+            };
+            servers.push(server);
+            return server;
+        });
+    }
+    /** Modifie les champs saisis. Un changement d'hôte ou de port oublie l'empreinte : c'est une autre machine. */
+    update(id, input) {
+        const fields = validateServerInput(input);
+        return this.mutate((servers) => {
+            const server = servers.find((s) => s.id === id);
+            if (!server)
+                throw new GateError(`Unknown server "${id}".`);
+            if (server.host !== fields.host || server.port !== fields.port)
+                server.hostKeyFingerprint = null;
+            Object.assign(server, fields);
+            return server;
+        });
+    }
+    setFingerprint(id, fingerprint) {
+        return this.mutate((servers) => {
+            const server = servers.find((s) => s.id === id);
+            if (!server)
+                throw new GateError(`Unknown server "${id}".`);
+            server.hostKeyFingerprint = fingerprint;
+            return server;
+        });
+    }
+    /**
+     * Remplace les notes. Avec `expectedUpdatedAt`, l'écriture est refusée si les
+     * notes ont changé depuis cette date : une saisie ne doit pas écraser une
+     * mise à jour faite entre-temps par l'agent ou par un autre onglet.
+     */
+    setNotes(id, text, by, expectedUpdatedAt) {
+        const notes = String(text ?? "").replace(/\r\n/g, "\n").trim();
+        if (notes.length > MAX_NOTES_LENGTH) {
+            throw new GateError(`Notes are limited to ${MAX_NOTES_LENGTH} characters (${notes.length} given).`);
+        }
+        return this.mutate((servers) => {
+            const server = servers.find((s) => s.id === id);
+            if (!server)
+                throw new GateError(`Unknown server "${id}".`);
+            if (expectedUpdatedAt !== undefined && (server.notesUpdatedAt ?? null) !== expectedUpdatedAt) {
+                const author = server.notesUpdatedBy === "agent" ? "l'agent" : "un autre onglet";
+                throw new GateError(`Les notes ont été modifiées par ${author} pendant ta saisie. Copie ton texte, annule, puis reprends à partir de la nouvelle version.`);
+            }
+            server.notes = notes;
+            server.notesUpdatedAt = new Date().toISOString();
+            server.notesUpdatedBy = by;
+            return server;
+        });
+    }
+    delete(id) {
+        this.mutate((servers) => {
+            const index = servers.findIndex((s) => s.id === id);
+            if (index === -1)
+                throw new GateError(`Unknown server "${id}".`);
+            servers.splice(index, 1);
+        });
+    }
+    privateKey(id) {
+        return decryptSecret(this.get(id).privateKeyEncrypted, this.vaultKey);
+    }
+    /** Vérifie que VAULT_KEY déchiffre toutes les clés enregistrées. */
+    verifyVault() {
+        for (const server of this.list()) {
+            try {
+                decryptSecret(server.privateKeyEncrypted, this.vaultKey);
+            }
+            catch {
+                throw new GateError(`VAULT_KEY does not decrypt the private key of server "${server.name}": it is not the key that was set when that server was added.`);
+            }
+        }
+    }
+    mutate(fn) {
+        return withFileLock(this.lockFile, "servers.json", () => {
+            const servers = this.list();
+            const result = fn(servers);
+            writeJsonAtomic(this.file, { servers }, 0o600);
+            return result;
+        });
+    }
+}

package/dist/src/core/ssh-session.d.ts

@@ -0,0 +1,72 @@
+export interface ShellTarget {
+    host: string;
+    port: number;
+    username: string;
+    privateKey: string;
+    /** Empreinte attendue de la clé d'hôte ; null au premier test de connexion. */
+    expectedFingerprint: string | null;
+}
+export interface CommandResult {
+    exitCode: number;
+    cwd: string;
+}
+/** Empreinte au format d'OpenSSH : `SHA256:<base64 sans remplissage>`. */
+export declare function fingerprintOf(key: Buffer): string;
+/**
+ * Script écrit dans le shell pour une commande. Le groupe `{ }` s'exécute dans
+ * le shell courant (un `cd` ou un `export` persiste), l'entrée vient de
+ * /dev/null (une commande qui attend une saisie reçoit une fin de fichier) et
+ * stderr est fusionné dans stdout. Le marqueur final porte le code de retour et
+ * le répertoire courant.
+ */
+export declare function wrapCommand(command: string, token: string): string;
+/**
+ * Découpe le flux du shell : transmet la sortie au fil de l'eau et détecte le
+ * marqueur de fin de la commande. La fin du tampon qui pourrait être un début
+ * de marqueur est retenue jusqu'au fragment suivant.
+ */
+export declare class CommandOutputParser {
+    private readonly onOutput;
+    private buffer;
+    private readonly marker;
+    constructor(token: string, onOutput: (text: string) => void);
+    /** Ajoute un fragment ; renvoie le résultat quand le marqueur complet est arrivé. */
+    push(chunk: string): CommandResult | null;
+    private emit;
+}
+/**
+ * Connexion SSH et shell bash persistant, sans terminal : les commandes
+ * s'enchaînent dans le même shell, une à la fois.
+ */
+export declare class ShellSession {
+    private readonly client;
+    private readonly channel;
+    readonly shellPid: number;
+    cwd: string;
+    readonly fingerprint: string;
+    private readonly onClose;
+    private readonly stdoutDecoder;
+    private readonly stderrDecoder;
+    private current;
+    private closedReason;
+    private constructor();
+    /**
+     * Ouvre la connexion et le shell. Avec une empreinte attendue, une clé d'hôte
+     * différente fait échouer la connexion ; sans, l'empreinte vue est renvoyée.
+     */
+    static open(target: ShellTarget, onClose: (reason: string) => void): Promise<ShellSession>;
+    get closed(): boolean;
+    /** Exécute une commande dans le shell ; `onOutput` reçoit la sortie au fil de l'eau. */
+    run(command: string, onOutput: (text: string) => void): Promise<CommandResult>;
+    /** Vérifie la syntaxe avec `bash -n`, sans rien exécuter ; renvoie le message d'erreur, ou null. */
+    checkSyntax(command: string): Promise<string | null>;
+    /**
+     * Envoie SIGINT aux processus lancés par le shell, comme un Ctrl+C. Échoue
+     * quand aucun processus n'a reçu le signal : une boucle exécutée par le shell
+     * lui-même n'a pas de processus fils à interrompre.
+     */
+    interrupt(): Promise<void>;
+    close(): void;
+    private receive;
+    private handleClose;
+}

package/dist/src/core/ssh-session.js

@@ -0,0 +1,243 @@
+import { createHash, randomBytes } from "node:crypto";
+import { StringDecoder } from "node:string_decoder";
+import ssh2 from "ssh2";
+import { GateError } from "./errors.js";
+const CONNECT_TIMEOUT_MS = 15_000;
+const READY_MARKER = /__SSHGATE_READY_(\d+)_(.*)__\n/;
+const END_MARKER_PREFIX = "__SSHGATE_END_";
+/** Empreinte au format d'OpenSSH : `SHA256:<base64 sans remplissage>`. */
+export function fingerprintOf(key) {
+    return `SHA256:${createHash("sha256").update(key).digest("base64").replace(/=+$/, "")}`;
+}
+/**
+ * Script écrit dans le shell pour une commande. Le groupe `{ }` s'exécute dans
+ * le shell courant (un `cd` ou un `export` persiste), l'entrée vient de
+ * /dev/null (une commande qui attend une saisie reçoit une fin de fichier) et
+ * stderr est fusionné dans stdout. Le marqueur final porte le code de retour et
+ * le répertoire courant.
+ */
+export function wrapCommand(command, token) {
+    return `{\n${command}\n} </dev/null 2>&1\n__sg_rc=$?\nprintf '\\n${END_MARKER_PREFIX}%s_%s_%s__\\n' '${token}' "$__sg_rc" "$PWD"\n`;
+}
+/**
+ * Découpe le flux du shell : transmet la sortie au fil de l'eau et détecte le
+ * marqueur de fin de la commande. La fin du tampon qui pourrait être un début
+ * de marqueur est retenue jusqu'au fragment suivant.
+ */
+export class CommandOutputParser {
+    onOutput;
+    buffer = "";
+    marker;
+    constructor(token, onOutput) {
+        this.onOutput = onOutput;
+        this.marker = `\n${END_MARKER_PREFIX}${token}_`;
+    }
+    /** Ajoute un fragment ; renvoie le résultat quand le marqueur complet est arrivé. */
+    push(chunk) {
+        this.buffer += chunk;
+        const at = this.buffer.indexOf(this.marker);
+        if (at === -1) {
+            const keep = Math.min(this.buffer.length, this.marker.length - 1);
+            this.emit(this.buffer.length - keep);
+            return null;
+        }
+        this.emit(at);
+        const lineEnd = this.buffer.indexOf("\n", this.marker.length);
+        if (lineEnd === -1)
+            return null;
+        const line = this.buffer.slice(this.marker.length, lineEnd);
+        this.buffer = this.buffer.slice(lineEnd + 1);
+        const match = /^(\d+)_(.*)__$/.exec(line);
+        if (!match)
+            throw new GateError(`Unreadable end marker from the shell: "${line}".`);
+        return { exitCode: Number(match[1]), cwd: match[2] };
+    }
+    emit(length) {
+        if (length <= 0)
+            return;
+        this.onOutput(this.buffer.slice(0, length));
+        this.buffer = this.buffer.slice(length);
+    }
+}
+function connectionErrorMessage(err, target) {
+    if (err?.level === "client-authentication") {
+        return `Authentification refusée pour ${target.username}@${target.host} : la clé publique n'est pas dans ~/.ssh/authorized_keys de cet utilisateur.`;
+    }
+    if (err?.level === "client-timeout")
+        return `Le serveur ${target.host}:${target.port} n'a pas répondu dans les ${CONNECT_TIMEOUT_MS / 1000} s.`;
+    return `Connexion SSH impossible à ${target.host}:${target.port} : ${err?.message ?? err}`;
+}
+/**
+ * Connexion SSH et shell bash persistant, sans terminal : les commandes
+ * s'enchaînent dans le même shell, une à la fois.
+ */
+export class ShellSession {
+    client;
+    channel;
+    shellPid;
+    cwd;
+    fingerprint;
+    onClose;
+    stdoutDecoder = new StringDecoder("utf8");
+    stderrDecoder = new StringDecoder("utf8");
+    current = null;
+    closedReason = null;
+    constructor(client, channel, shellPid, cwd, fingerprint, onClose) {
+        this.client = client;
+        this.channel = channel;
+        this.shellPid = shellPid;
+        this.cwd = cwd;
+        this.fingerprint = fingerprint;
+        this.onClose = onClose;
+        channel.on("data", (chunk) => this.receive(this.stdoutDecoder.write(chunk)));
+        channel.stderr.on("data", (chunk) => this.receive(this.stderrDecoder.write(chunk)));
+        channel.on("close", () => this.handleClose("Le shell s'est fermé."));
+        client.on("error", (err) => this.handleClose(`Connexion SSH perdue : ${err.message}`));
+        client.on("close", () => this.handleClose("Connexion SSH fermée."));
+    }
+    /**
+     * Ouvre la connexion et le shell. Avec une empreinte attendue, une clé d'hôte
+     * différente fait échouer la connexion ; sans, l'empreinte vue est renvoyée.
+     */
+    static open(target, onClose) {
+        return new Promise((resolve, reject) => {
+            const client = new ssh2.Client();
+            let seenFingerprint = null;
+            let settled = false;
+            const fail = (message) => {
+                if (settled)
+                    return;
+                settled = true;
+                client.end();
+                reject(new GateError(message));
+            };
+            client.on("ready", () => {
+                client.exec("bash -l", (err, channel) => {
+                    if (err)
+                        return fail(`Impossible d'ouvrir un shell sur ${target.host} : ${err.message}`);
+                    const decoder = new StringDecoder("utf8");
+                    let buffer = "";
+                    const timer = setTimeout(() => fail(`Le shell de ${target.host} n'a pas répondu dans les ${CONNECT_TIMEOUT_MS / 1000} s : bash est-il installé ?`), CONNECT_TIMEOUT_MS);
+                    const onData = (chunk) => {
+                        buffer += decoder.write(chunk);
+                        const match = READY_MARKER.exec(buffer);
+                        if (!match || settled)
+                            return;
+                        clearTimeout(timer);
+                        channel.off("data", onData);
+                        settled = true;
+                        resolve(new ShellSession(client, channel, Number(match[1]), match[2], seenFingerprint, onClose));
+                    };
+                    channel.on("data", onData);
+                    channel.on("close", () => {
+                        clearTimeout(timer);
+                        fail(`Le shell de ${target.host} s'est fermé au démarrage.`);
+                    });
+                    channel.write(`printf '__SSHGATE_READY_%s_%s__\\n' "$$" "$PWD"\n`);
+                });
+            });
+            client.on("error", (err) => {
+                if (target.expectedFingerprint && seenFingerprint && seenFingerprint !== target.expectedFingerprint) {
+                    return fail(`La clé d'hôte de ${target.host} a changé (${seenFingerprint}, attendue ${target.expectedFingerprint}). Connexion refusée : vérifie le serveur, puis modifie-le dans l'interface pour enregistrer la nouvelle empreinte.`);
+                }
+                fail(connectionErrorMessage(err, target));
+            });
+            client.connect({
+                host: target.host,
+                port: target.port,
+                username: target.username,
+                privateKey: target.privateKey,
+                readyTimeout: CONNECT_TIMEOUT_MS,
+                keepaliveInterval: 30_000,
+                hostVerifier: (key) => {
+                    seenFingerprint = fingerprintOf(key);
+                    return target.expectedFingerprint === null || seenFingerprint === target.expectedFingerprint;
+                },
+            });
+        });
+    }
+    get closed() {
+        return this.closedReason !== null;
+    }
+    /** Exécute une commande dans le shell ; `onOutput` reçoit la sortie au fil de l'eau. */
+    run(command, onOutput) {
+        if (this.closedReason)
+            return Promise.reject(new GateError(this.closedReason));
+        if (this.current)
+            return Promise.reject(new GateError("Une commande est déjà en cours dans ce shell."));
+        const token = randomBytes(8).toString("hex");
+        return new Promise((resolve, reject) => {
+            this.current = { parser: new CommandOutputParser(token, onOutput), resolve, reject };
+            this.channel.write(wrapCommand(command, token));
+        });
+    }
+    /** Vérifie la syntaxe avec `bash -n`, sans rien exécuter ; renvoie le message d'erreur, ou null. */
+    checkSyntax(command) {
+        return new Promise((resolve, reject) => {
+            this.client.exec("bash -n", (err, channel) => {
+                if (err)
+                    return reject(new GateError(`Vérification de syntaxe impossible : ${err.message}`));
+                let output = "";
+                channel.on("data", (chunk) => (output += chunk.toString("utf8")));
+                channel.stderr.on("data", (chunk) => (output += chunk.toString("utf8")));
+                channel.on("close", (code) => resolve(code === 0 ? null : output.trim() || `bash -n a renvoyé le code ${code}.`));
+                channel.end(`${command}\n`);
+            });
+        });
+    }
+    /**
+     * Envoie SIGINT aux processus lancés par le shell, comme un Ctrl+C. Échoue
+     * quand aucun processus n'a reçu le signal : une boucle exécutée par le shell
+     * lui-même n'a pas de processus fils à interrompre.
+     */
+    interrupt() {
+        return new Promise((resolve, reject) => {
+            this.client.exec(`pkill -INT -P ${this.shellPid}`, (err, channel) => {
+                if (err)
+                    return reject(new GateError(`Interruption impossible : ${err.message}`));
+                let output = "";
+                channel.on("data", (chunk) => (output += chunk.toString("utf8")));
+                channel.stderr.on("data", (chunk) => (output += chunk.toString("utf8")));
+                channel.on("close", (code) => {
+                    if (code === 0)
+                        return resolve();
+                    if (code === 1)
+                        return reject(new GateError("Aucun processus à interrompre : la commande s'exécute dans le shell lui-même. Ferme le shell pour l'arrêter."));
+                    reject(new GateError(`Interruption impossible : pkill a renvoyé le code ${code}${output.trim() ? ` (${output.trim()})` : ""}.`));
+                });
+            });
+        });
+    }
+    close() {
+        this.handleClose("Déconnecté.");
+    }
+    receive(text) {
+        const current = this.current;
+        if (!current || !text)
+            return;
+        let result;
+        try {
+            result = current.parser.push(text);
+        }
+        catch (err) {
+            this.current = null;
+            current.reject(err);
+            return;
+        }
+        if (!result)
+            return;
+        this.current = null;
+        this.cwd = result.cwd;
+        current.resolve(result);
+    }
+    handleClose(reason) {
+        if (this.closedReason)
+            return;
+        this.closedReason = reason;
+        const current = this.current;
+        this.current = null;
+        current?.reject(new GateError(reason));
+        this.client.end();
+        this.onClose(reason);
+    }
+}

package/dist/src/core/vault.d.ts

@@ -0,0 +1,8 @@
+/** Nouvelle clé de coffre : 32 octets aléatoires, en base64. */
+export declare function generateVaultKey(): string;
+/** Décode VAULT_KEY ; lève une erreur qui dit comment en obtenir une valide. */
+export declare function parseVaultKey(raw: string | undefined): Buffer;
+/** Chiffre en AES-256-GCM : `v1:<iv>:<tag>:<chiffré>`, chaque partie en base64. */
+export declare function encryptSecret(plaintext: string, key: Buffer): string;
+/** Déchiffre un secret produit par `encryptSecret` ; échoue si la clé n'est pas la bonne. */
+export declare function decryptSecret(payload: string, key: Buffer): string;

package/dist/src/core/vault.js

@@ -0,0 +1,45 @@
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+import { GateError } from "./errors.js";
+const KEY_BYTES = 32;
+const IV_BYTES = 12;
+const FORMAT_VERSION = "v1";
+/** Nouvelle clé de coffre : 32 octets aléatoires, en base64. */
+export function generateVaultKey() {
+    return randomBytes(KEY_BYTES).toString("base64");
+}
+/** Décode VAULT_KEY ; lève une erreur qui dit comment en obtenir une valide. */
+export function parseVaultKey(raw) {
+    const value = raw?.trim();
+    if (!value) {
+        throw new GateError("VAULT_KEY is not set. It encrypts the SSH private keys: generate one with `npx -y @imenam/mcp-ssh-gate --generate-vault-key` and set it as a secret variable of the MCP.");
+    }
+    const key = Buffer.from(value, "base64");
+    if (key.length !== KEY_BYTES || key.toString("base64") !== value) {
+        throw new GateError(`VAULT_KEY is not a valid key: expected ${KEY_BYTES} bytes encoded in base64. Generate one with \`npx -y @imenam/mcp-ssh-gate --generate-vault-key\`.`);
+    }
+    return key;
+}
+/** Chiffre en AES-256-GCM : `v1:<iv>:<tag>:<chiffré>`, chaque partie en base64. */
+export function encryptSecret(plaintext, key) {
+    const iv = randomBytes(IV_BYTES);
+    const cipher = createCipheriv("aes-256-gcm", key, iv);
+    const encrypted = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return [FORMAT_VERSION, iv.toString("base64"), tag.toString("base64"), encrypted.toString("base64")].join(":");
+}
+/** Déchiffre un secret produit par `encryptSecret` ; échoue si la clé n'est pas la bonne. */
+export function decryptSecret(payload, key) {
+    const parts = payload.split(":");
+    if (parts.length !== 4 || parts[0] !== FORMAT_VERSION) {
+        throw new GateError("Encrypted value has an unknown format.");
+    }
+    const [, iv, tag, encrypted] = parts;
+    const decipher = createDecipheriv("aes-256-gcm", key, Buffer.from(iv, "base64"));
+    decipher.setAuthTag(Buffer.from(tag, "base64"));
+    try {
+        return Buffer.concat([decipher.update(Buffer.from(encrypted, "base64")), decipher.final()]).toString("utf8");
+    }
+    catch {
+        throw new GateError("VAULT_KEY does not decrypt this value: it is not the key that was used to encrypt it.");
+    }
+}

package/dist/src/gui-worker.d.ts

@@ -0,0 +1 @@
+export {};