@patimweb/pi-ssh 1.0.0

package/src/known-hosts.ts

@@ -0,0 +1,189 @@
+/**
+ * Host key verification against known_hosts.
+ *
+ * Trust on first use: an unknown host is recorded with its fingerprint, and
+ * from then on a changed key is a hard failure rather than a prompt. That is
+ * the only part of SSH that protects against someone sitting between you and
+ * the server, so it is not something to skip for convenience.
+ *
+ * OpenSSH's own file is used by default, which means hosts already visited
+ * with `ssh` are recognised, and hosts recorded here are recognised by `ssh`.
+ */
+
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { keyBlobType, keyFingerprint } from "./keys.ts";
+
+export type HostKeyVerdict = "match" | "unknown" | "changed" | "revoked";
+
+export interface HostKeyCheck {
+  readonly verdict: HostKeyVerdict;
+  readonly fingerprint: string;
+  readonly keyType: string;
+  /** Fingerprints already on record for this host, when the key changed. */
+  readonly knownFingerprints: ReadonlyArray<string>;
+  readonly file: string;
+}
+
+export interface KnownHostEntry {
+  readonly hosts: string;
+  readonly keyType: string;
+  readonly blob: Buffer;
+  readonly marker?: string;
+}
+
+export function defaultKnownHostsPath(): string {
+  const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
+  return path.join(home, ".ssh", "known_hosts");
+}
+
+/** How OpenSSH writes a host: bare, or [host]:port for a non-default port. */
+export function hostPattern(host: string, port: number): string {
+  return port === 22 ? host : `[${host}]:${port}`;
+}
+
+// --- Parsing --------------------------------------------------------------
+
+export function parseKnownHosts(content: string): KnownHostEntry[] {
+  const entries: KnownHostEntry[] = [];
+
+  for (const rawLine of content.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+
+    let parts = line.split(/\s+/);
+    let marker: string | undefined;
+
+    // A line may start with @cert-authority or @revoked.
+    if (parts[0]?.startsWith("@")) {
+      marker = parts[0].slice(1);
+      parts = parts.slice(1);
+    }
+    if (parts.length < 3) continue;
+
+    const [hosts, keyType, encoded] = parts;
+    let blob: Buffer;
+    try {
+      blob = Buffer.from(encoded, "base64");
+    } catch {
+      continue;
+    }
+    if (blob.length === 0) continue;
+
+    entries.push({ hosts, keyType, blob, marker });
+  }
+  return entries;
+}
+
+/**
+ * Does this entry cover the given host?
+ *
+ * Handles the three forms OpenSSH writes: a comma-separated list of plain
+ * patterns, and hashed entries of the form |1|salt|hash.
+ */
+export function entryMatchesHost(entryHosts: string, pattern: string): boolean {
+  if (entryHosts.startsWith("|1|")) {
+    const [, salt, hash] = entryHosts.split("|").filter((part) => part.length > 0);
+    if (!salt || !hash) return false;
+    try {
+      const digest = crypto
+        .createHmac("sha1", Buffer.from(salt, "base64"))
+        .update(pattern)
+        .digest("base64");
+      return digest === hash;
+    } catch {
+      return false;
+    }
+  }
+
+  return entryHosts.split(",").some((candidate) => candidate.trim() === pattern);
+}
+
+// --- Verification ---------------------------------------------------------
+
+export function readKnownHosts(file: string): KnownHostEntry[] {
+  try {
+    return parseKnownHosts(fs.readFileSync(file, "utf-8"));
+  } catch {
+    // A missing file simply means nothing is known yet.
+    return [];
+  }
+}
+
+/**
+ * Compare a host key offered during the handshake against what is on record.
+ */
+export function checkHostKey(
+  host: string,
+  port: number,
+  key: Buffer,
+  file = defaultKnownHostsPath(),
+): HostKeyCheck {
+  const pattern = hostPattern(host, port);
+  const fingerprint = keyFingerprint(key);
+  const keyType = keyBlobType(key);
+  const entries = readKnownHosts(file).filter((entry) =>
+    entryMatchesHost(entry.hosts, pattern),
+  );
+
+  const base = { fingerprint, keyType, file };
+
+  if (entries.some((entry) => entry.marker === "revoked" && entry.blob.equals(key))) {
+    return { ...base, verdict: "revoked", knownFingerprints: [] };
+  }
+  if (entries.some((entry) => entry.marker !== "revoked" && entry.blob.equals(key))) {
+    return { ...base, verdict: "match", knownFingerprints: [] };
+  }
+
+  // Only keys of the same type count as a conflict: a host legitimately
+  // offers an ed25519 key even when only its RSA key was recorded.
+  const sameType = entries.filter((entry) => entry.keyType === keyType);
+  if (sameType.length > 0) {
+    return {
+      ...base,
+      verdict: "changed",
+      knownFingerprints: sameType.map((entry) => keyFingerprint(entry.blob)),
+    };
+  }
+
+  return { ...base, verdict: "unknown", knownFingerprints: [] };
+}
+
+/** Append a host key, creating the file and its directory if needed. */
+export function addKnownHost(
+  host: string,
+  port: number,
+  key: Buffer,
+  file = defaultKnownHostsPath(),
+): void {
+  const line = `${hostPattern(host, port)} ${keyBlobType(key)} ${key.toString("base64")}\n`;
+  const dir = path.dirname(file);
+
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  }
+  // A known_hosts that already exists keeps its permissions; a new one is
+  // created the way OpenSSH would.
+  const needsNewline =
+    fs.existsSync(file) && fs.statSync(file).size > 0 && !fs.readFileSync(file, "utf-8").endsWith("\n");
+
+  fs.appendFileSync(file, `${needsNewline ? "\n" : ""}${line}`, { mode: 0o600 });
+}
+
+/** The message shown when a host's key does not match what was recorded. */
+export function describeChangedKey(check: HostKeyCheck, host: string): string {
+  return [
+    `HOST KEY CHANGED for ${host}.`,
+    "",
+    `Offered:  ${check.keyType} ${check.fingerprint}`,
+    `Recorded: ${check.knownFingerprints.join(", ")}`,
+    `In:       ${check.file}`,
+    "",
+    "This is what a machine-in-the-middle looks like. It is also what a",
+    "legitimately reinstalled server looks like. Do not connect until you know",
+    "which one it is: confirm the fingerprint out of band, then remove the old",
+    `line with: ssh-keygen -R ${host}`,
+  ].join("\n");
+}

package/src/tools/ssh-authorize.ts

@@ -0,0 +1,88 @@
+/**
+ * ssh_authorize tool -- Replace a password login with a key login.
+ */
+
+import { Type } from "typebox";
+import { resolveProfile } from "../config.ts";
+import { authorizeKey } from "../authorize.ts";
+import { formatAuthorizeResult } from "../formatting/formatters.ts";
+
+export const SshAuthorizeTool = {
+  name: "ssh_authorize",
+  label: "SSH Install Key",
+  description:
+    "Set up passwordless login: generate an SSH key if the profile has none, install its public key in the remote authorized_keys, point the profile at it, and verify that a key-only login works. This is what ssh-copy-id does, but it runs in process, so no ssh-keygen or ssh-copy-id has to be installed. Run it once after configuring a host with a password.",
+  parameters: Type.Object({
+    profile: Type.Optional(
+      Type.String({ description: "SSH profile to set up. Defaults to the active one." }),
+    ),
+    keyPath: Type.Optional(
+      Type.String({
+        description:
+          "Key to use or create. Default ~/.ssh/id_ed25519_pi_<profile>. An existing key at this path is reused, never overwritten.",
+      }),
+    ),
+    comment: Type.Optional(
+      Type.String({ description: "Comment for a newly generated key." }),
+    ),
+    authorizedKeysPath: Type.Optional(
+      Type.String({
+        description:
+          "Absolute path of authorized_keys on the remote host. Only needed when its sshd uses a non-standard AuthorizedKeysFile; by default the remote account's ~/.ssh/authorized_keys is used.",
+      }),
+    ),
+    removePassword: Type.Optional(
+      Type.Boolean({
+        description:
+          "Delete the stored password once the key login is proven to work. Default false, which keeps it as a fallback.",
+        default: false,
+      }),
+    ),
+    acceptNewHostKey: Type.Optional(
+      Type.Boolean({
+        description: "Record the host key if this host is not yet known.",
+        default: false,
+      }),
+    ),
+  }),
+
+  async execute(
+    _toolCallId: string,
+    params: {
+      profile?: string;
+      keyPath?: string;
+      comment?: string;
+      authorizedKeysPath?: string;
+      removePassword?: boolean;
+      acceptNewHostKey?: boolean;
+    },
+    signal: AbortSignal,
+  ) {
+    const { name, profile } = resolveProfile(params.profile);
+
+    const result = await authorizeKey({
+      profileName: name,
+      profile,
+      keyPath: params.keyPath,
+      comment: params.comment,
+      authorizedKeysPath: params.authorizedKeysPath,
+      removePassword: params.removePassword,
+      acceptNewHostKey: params.acceptNewHostKey,
+      signal,
+    });
+
+    const note =
+      result.verified && params.removePassword
+        ? "\n\nThe stored password has been removed from the profile."
+        : result.verified && profile.password
+          ? "\n\nThe password is still stored as a fallback. Re-run with removePassword: true to drop it."
+          : "";
+
+    return {
+      content: [
+        { type: "text" as const, text: `${formatAuthorizeResult(result)}${note}` },
+      ],
+      details: { ...result, passwordRemoved: Boolean(result.verified && params.removePassword) },
+    };
+  },
+};

package/src/tools/ssh-doctor.ts

@@ -0,0 +1,26 @@
+/**
+ * ssh_doctor tool -- Report what the environment can do and what it cannot.
+ */
+
+import { Type } from "typebox";
+import { formatChecks, runChecks } from "../doctor.ts";
+
+export const SshDoctorTool = {
+  name: "ssh_doctor",
+  label: "SSH Doctor",
+  description:
+    "Check whether this machine can use the SSH tools and report anything that needs fixing or installing. Run it when a connection fails for reasons that are not about the remote host, or when the user asks what they need to install. Nothing external is normally required.",
+  parameters: Type.Object({}),
+
+  execute(_toolCallId: string, _params: {}, _signal: AbortSignal) {
+    const checks = runChecks();
+    return {
+      content: [{ type: "text" as const, text: formatChecks(checks) }],
+      details: {
+        platform: process.platform,
+        problems: checks.filter((check) => check.status === "problem").map((c) => c.name),
+        checks: checks.map((check) => ({ name: check.name, status: check.status })),
+      },
+    };
+  },
+};

package/src/tools/ssh-download.ts

@@ -0,0 +1,51 @@
+/**
+ * ssh_download tool -- Copy a remote file to this machine over SFTP.
+ */
+
+import { Type } from "typebox";
+import { resolveProfile } from "../config.ts";
+import { downloadFile, withConnection } from "../clients/ssh-client.ts";
+import { formatTransfer } from "../formatting/formatters.ts";
+
+export const SshDownloadTool = {
+  name: "ssh_download",
+  label: "SSH Download File",
+  description:
+    "Copy a file from the remote host to this machine over SFTP. Missing local directories are created. Prefer this over cat-ing a file through ssh_exec: it handles binary content and does not pass the file through the model.",
+  parameters: Type.Object({
+    remotePath: Type.String({ description: "File on the remote host." }),
+    localPath: Type.String({
+      description: "Destination on this machine, including the file name.",
+    }),
+    profile: Type.Optional(
+      Type.String({ description: "SSH profile to use. Defaults to the active one." }),
+    ),
+    acceptNewHostKey: Type.Optional(
+      Type.Boolean({ description: "Record an unknown host key.", default: false }),
+    ),
+  }),
+
+  async execute(
+    _toolCallId: string,
+    params: {
+      remotePath: string;
+      localPath: string;
+      profile?: string;
+      acceptNewHostKey?: boolean;
+    },
+    signal: AbortSignal,
+  ) {
+    const { name, profile } = resolveProfile(params.profile);
+
+    const result = await withConnection(
+      profile,
+      { signal, acceptNewHostKey: params.acceptNewHostKey },
+      (connection) => downloadFile(connection, params.remotePath, params.localPath),
+    );
+
+    return {
+      content: [{ type: "text" as const, text: formatTransfer(result, "down") }],
+      details: { profile: name, ...result },
+    };
+  },
+};

package/src/tools/ssh-exec.ts

@@ -0,0 +1,76 @@
+/**
+ * ssh_exec tool -- Run a command on the remote host.
+ */
+
+import { Type } from "typebox";
+import { resolveProfile } from "../config.ts";
+import { execCommand, withConnection } from "../clients/ssh-client.ts";
+import { formatExecResult } from "../formatting/formatters.ts";
+
+export const SshExecTool = {
+  name: "ssh_exec",
+  label: "SSH Run Command",
+  description:
+    "Run a shell command on the configured remote host and return its output and exit code. The connection is opened for this command and closed again. Commands run non-interactively, so anything that expects input or a TTY (sudo with a password prompt, an editor, top) will hang until the timeout.",
+  parameters: Type.Object({
+    command: Type.String({ description: "The command line to run on the remote host." }),
+    cwd: Type.Optional(
+      Type.String({ description: "Directory to run it in. Default: the login directory." }),
+    ),
+    timeoutSeconds: Type.Optional(
+      Type.Number({ description: "Give up after this long. Default 120.", default: 120 }),
+    ),
+    profile: Type.Optional(
+      Type.String({ description: "SSH profile to use. Defaults to the active one." }),
+    ),
+    acceptNewHostKey: Type.Optional(
+      Type.Boolean({
+        description:
+          "Record the host key if this host is not yet known. Only pass this once the fingerprint has been checked.",
+        default: false,
+      }),
+    ),
+  }),
+
+  async execute(
+    _toolCallId: string,
+    params: {
+      command: string;
+      cwd?: string;
+      timeoutSeconds?: number;
+      profile?: string;
+      acceptNewHostKey?: boolean;
+    },
+    signal: AbortSignal,
+  ) {
+    if (!params.command?.trim()) throw new Error("command must not be empty.");
+
+    const { name, profile } = resolveProfile(params.profile);
+    const timeoutMs = Math.min(Math.max(params.timeoutSeconds ?? 120, 1), 3600) * 1000;
+
+    const result = await withConnection(
+      profile,
+      { signal, acceptNewHostKey: params.acceptNewHostKey },
+      (connection) =>
+        execCommand(connection, params.command, {
+          cwd: params.cwd,
+          timeoutMs,
+          signal,
+        }),
+    );
+
+    return {
+      content: [{ type: "text" as const, text: formatExecResult(result) }],
+      details: {
+        profile: name,
+        host: profile.host,
+        exitCode: result.code,
+        signal: result.signal,
+        durationMs: result.durationMs,
+        truncated: result.truncated,
+        stdoutBytes: result.stdout.length,
+        stderrBytes: result.stderr.length,
+      },
+    };
+  },
+};

package/src/tools/ssh-keygen.ts

@@ -0,0 +1,102 @@
+/**
+ * ssh_keygen tool -- Create an SSH key pair without ssh-keygen.
+ */
+
+import { Type } from "typebox";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { expandPath, getProfile, updateProfile } from "../config.ts";
+import { defaultKeyComment, generateKeyPair } from "../keys.ts";
+
+export const SshKeygenTool = {
+  name: "ssh_keygen",
+  label: "SSH Generate Key",
+  description:
+    "Create an ed25519 SSH key pair on this machine. Works on Windows, macOS and Linux alike because the key is generated in process -- ssh-keygen does not need to be installed. The result is a normal OpenSSH key that the ssh command can use too. To also install it on a host, use ssh_authorize instead.",
+  parameters: Type.Object({
+    path: Type.Optional(
+      Type.String({
+        description:
+          "Where to write the private key. Default ~/.ssh/id_ed25519_pi. The public key goes next to it with a .pub suffix.",
+      }),
+    ),
+    comment: Type.Optional(
+      Type.String({ description: "Comment stored in the key, e.g. an email or host name." }),
+    ),
+    profile: Type.Optional(
+      Type.String({
+        description: "Record the new key in this SSH profile so it is used for logins.",
+      }),
+    ),
+    overwrite: Type.Optional(
+      Type.Boolean({
+        description:
+          "Replace an existing key at that path. Default false: overwriting invalidates every host that already trusts the old key.",
+        default: false,
+      }),
+    ),
+  }),
+
+  execute(
+    _toolCallId: string,
+    params: { path?: string; comment?: string; profile?: string; overwrite?: boolean },
+    _signal: AbortSignal,
+  ) {
+    const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
+    const privateKeyPath = expandPath(
+      params.path ?? path.join(home, ".ssh", "id_ed25519_pi"),
+    );
+    const publicKeyPath = `${privateKeyPath}.pub`;
+
+    if (fs.existsSync(privateKeyPath) && !params.overwrite) {
+      throw new Error(
+        `A key already exists at ${privateKeyPath}. Pass overwrite: true to replace it, but note that every host trusting the old key will stop accepting it.`,
+      );
+    }
+
+    if (params.profile && !getProfile(params.profile)) {
+      throw new Error(`Profile "${params.profile}" does not exist.`);
+    }
+
+    const comment =
+      params.comment ?? defaultKeyComment(os.userInfo().username, os.hostname());
+    const pair = generateKeyPair(comment);
+
+    fs.mkdirSync(path.dirname(privateKeyPath), { recursive: true, mode: 0o700 });
+    fs.writeFileSync(privateKeyPath, pair.privateKey, { mode: 0o600 });
+    fs.chmodSync(privateKeyPath, 0o600);
+    fs.writeFileSync(publicKeyPath, `${pair.publicKey}\n`, { mode: 0o644 });
+
+    if (params.profile) {
+      updateProfile(params.profile, { privateKeyPath });
+    }
+
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: [
+            `Created an ed25519 key pair.`,
+            `Private: ${privateKeyPath} (owner only)`,
+            `Public:  ${publicKeyPath}`,
+            `Fingerprint: ${pair.fingerprint}`,
+            params.profile ? `Recorded in profile "${params.profile}".` : "",
+            "",
+            "Public key to install on a host:",
+            pair.publicKey,
+          ]
+            .filter(Boolean)
+            .join("\n"),
+        },
+      ],
+      details: {
+        privateKeyPath,
+        publicKeyPath,
+        fingerprint: pair.fingerprint,
+        publicKey: pair.publicKey,
+        profile: params.profile ?? null,
+      },
+    };
+  },
+};

package/src/tools/ssh-list.ts

@@ -0,0 +1,49 @@
+/**
+ * ssh_list tool -- List a directory on the remote host over SFTP.
+ */
+
+import { Type } from "typebox";
+import { resolveProfile } from "../config.ts";
+import { listDirectory, withConnection } from "../clients/ssh-client.ts";
+import { formatDirectory } from "../formatting/formatters.ts";
+
+export const SshListTool = {
+  name: "ssh_list",
+  label: "SSH List Directory",
+  description:
+    "List a directory on the remote host with sizes, permissions and dates, over SFTP. Use this instead of running ls, because the result is structured.",
+  parameters: Type.Object({
+    path: Type.String({ description: "Remote directory, e.g. /var/log or ." }),
+    profile: Type.Optional(
+      Type.String({ description: "SSH profile to use. Defaults to the active one." }),
+    ),
+    acceptNewHostKey: Type.Optional(
+      Type.Boolean({ description: "Record an unknown host key.", default: false }),
+    ),
+  }),
+
+  async execute(
+    _toolCallId: string,
+    params: { path: string; profile?: string; acceptNewHostKey?: boolean },
+    signal: AbortSignal,
+  ) {
+    const { name, profile } = resolveProfile(params.profile);
+    const remotePath = params.path?.trim() || ".";
+
+    const entries = await withConnection(
+      profile,
+      { signal, acceptNewHostKey: params.acceptNewHostKey },
+      (connection) => listDirectory(connection, remotePath),
+    );
+
+    return {
+      content: [{ type: "text" as const, text: formatDirectory(entries, remotePath) }],
+      details: {
+        profile: name,
+        path: remotePath,
+        count: entries.length,
+        directories: entries.filter((entry) => entry.type === "directory").length,
+      },
+    };
+  },
+};

package/src/tools/ssh-profile.ts

@@ -0,0 +1,77 @@
+/**
+ * ssh_profile tool -- List, switch or delete stored hosts.
+ */
+
+import { Type } from "typebox";
+import {
+  deleteProfile,
+  getActiveProfile,
+  getProfiles,
+  setActiveProfile,
+} from "../config.ts";
+import { formatProfileStatus } from "../formatting/formatters.ts";
+
+export const SshProfileTool = {
+  name: "ssh_profile",
+  label: "Manage SSH Profiles",
+  description:
+    "List configured SSH hosts, switch the active one, or delete one. Without arguments it lists them.",
+  parameters: Type.Object({
+    action: Type.Optional(
+      Type.String({ description: "One of: list, use, delete. Defaults to list." }),
+    ),
+    name: Type.Optional(
+      Type.String({ description: "Profile name for 'use' and 'delete'." }),
+    ),
+  }),
+
+  execute(
+    _toolCallId: string,
+    params: { action?: string; name?: string },
+    _signal: AbortSignal,
+  ) {
+    const action = (params.action || "list").toLowerCase();
+
+    if (action === "list") {
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: formatProfileStatus(getProfiles(), getActiveProfile()),
+          },
+        ],
+        details: {
+          profiles: Object.keys(getProfiles()),
+          activeProfile: getActiveProfile(),
+        },
+      };
+    }
+
+    if (!params.name) {
+      throw new Error(`The "${action}" action requires a profile name.`);
+    }
+
+    if (action === "use") {
+      setActiveProfile(params.name);
+      return {
+        content: [
+          { type: "text" as const, text: `Active SSH profile is now "${params.name}".` },
+        ],
+        details: { activeProfile: params.name },
+      };
+    }
+
+    if (action === "delete") {
+      const removed = deleteProfile(params.name);
+      const text = removed
+        ? `Profile "${params.name}" deleted. Active profile is now ${getActiveProfile() ? `"${getActiveProfile()}"` : "unset"}.`
+        : `No profile named "${params.name}".`;
+      return {
+        content: [{ type: "text" as const, text }],
+        details: { deleted: removed, activeProfile: getActiveProfile() },
+      };
+    }
+
+    throw new Error(`Unknown action "${params.action}". Use one of: list, use, delete.`);
+  },
+};