@patimweb/pi-ssh 1.0.0

package/src/tools/ssh-setup.ts

@@ -0,0 +1,96 @@
+/**
+ * ssh_setup tool -- Store the details of a host.
+ *
+ * A profile is set active automatically if it is the first one. Credentials
+ * go to ~/.pi/ssh-config.json, readable only by the owner.
+ */
+
+import { Type } from "typebox";
+import { expandPath, saveProfile } from "../config.ts";
+import type { SetupParams, SshProfile } from "../types.ts";
+
+export const SshSetupTool = {
+  name: "ssh_setup",
+  label: "SSH Setup",
+  description:
+    "Store an SSH host: address, user, and either a password or the path to a private key. Call this before any other ssh tool. Credentials are saved to ~/.pi/ssh-config.json (owner-readable only). If you only have a password, ssh_authorize can turn that into key-based login afterwards.",
+  parameters: Type.Object({
+    name: Type.String({
+      description: "Profile name, e.g. 'staging', 'nas'. Short and memorable.",
+    }),
+    host: Type.String({ description: "Hostname or IP address." }),
+    user: Type.String({ description: "Login user on the remote host." }),
+    port: Type.Optional(Type.Number({ description: "SSH port. Default 22.", default: 22 })),
+    password: Type.Optional(
+      Type.String({
+        description:
+          "Password for this host. Stored in plaintext in the config file; prefer a key, or run ssh_authorize afterwards to switch to one.",
+      }),
+    ),
+    privateKeyPath: Type.Optional(
+      Type.String({
+        description: "Path to a private key on this machine, e.g. ~/.ssh/id_ed25519.",
+      }),
+    ),
+    passphrase: Type.Optional(
+      Type.String({ description: "Passphrase for that private key, if it has one." }),
+    ),
+    strictHostKey: Type.Optional(
+      Type.Boolean({
+        description:
+          "Refuse hosts whose key is not in known_hosts. Default true. Turning it off removes the only protection against a machine-in-the-middle.",
+        default: true,
+      }),
+    ),
+  }),
+
+  execute(_toolCallId: string, params: SetupParams, _signal: AbortSignal) {
+    if (!params.host?.trim()) throw new Error("host must not be empty.");
+    if (!params.user?.trim()) throw new Error("user must not be empty.");
+
+    const port = params.port ?? 22;
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+      throw new Error("port must be an integer between 1 and 65535.");
+    }
+    if (!params.password && !params.privateKeyPath) {
+      throw new Error(
+        "Give either a password or a privateKeyPath -- otherwise there is no way to log in.",
+      );
+    }
+
+    const profile: SshProfile = {
+      host: params.host.trim(),
+      user: params.user.trim(),
+      port,
+      ...(params.password ? { password: params.password } : {}),
+      ...(params.privateKeyPath
+        ? { privateKeyPath: expandPath(params.privateKeyPath) }
+        : {}),
+      ...(params.passphrase ? { passphrase: params.passphrase } : {}),
+      ...(params.strictHostKey === false ? { strictHostKey: false } : {}),
+    };
+
+    saveProfile(params.name, profile);
+
+    const advice = profile.password && !profile.privateKeyPath
+      ? "\n\nThis profile logs in with a password. Run ssh_authorize to generate a key, install it on the host, and stop needing the password."
+      : "";
+
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: `SSH profile "${params.name}" saved: ${profile.user}@${profile.host}:${profile.port}.${advice}`,
+        },
+      ],
+      details: {
+        profile: params.name,
+        host: profile.host,
+        port: profile.port,
+        user: profile.user,
+        hasPassword: Boolean(profile.password),
+        hasKey: Boolean(profile.privateKeyPath),
+      },
+    };
+  },
+};

package/src/tools/ssh-status.ts

@@ -0,0 +1,70 @@
+/**
+ * ssh_status tool -- Show configured hosts and optionally test one.
+ */
+
+import { Type } from "typebox";
+import { getActiveProfile, getProfiles, resolveProfile } from "../config.ts";
+import { withConnection } from "../clients/ssh-client.ts";
+import { formatIdentity, formatProfileStatus } from "../formatting/formatters.ts";
+
+export const SshStatusTool = {
+  name: "ssh_status",
+  label: "SSH Status",
+  description:
+    "List the configured SSH hosts and how each authenticates. With connect: true it also opens a connection to verify that the credentials and host key still work.",
+  parameters: Type.Object({
+    profile: Type.Optional(
+      Type.String({ description: "Profile to check. Defaults to the active one." }),
+    ),
+    connect: Type.Optional(
+      Type.Boolean({
+        description: "Actually connect to verify the host works. Default false.",
+        default: false,
+      }),
+    ),
+  }),
+
+  async execute(
+    _toolCallId: string,
+    params: { profile?: string; connect?: boolean },
+    signal: AbortSignal,
+  ) {
+    const profiles = getProfiles();
+    const overview = formatProfileStatus(profiles, getActiveProfile());
+
+    if (Object.keys(profiles).length === 0 || !params.connect) {
+      return {
+        content: [{ type: "text" as const, text: overview }],
+        details: {
+          count: Object.keys(profiles).length,
+          profiles: Object.keys(profiles),
+          activeProfile: getActiveProfile(),
+        },
+      };
+    }
+
+    const { name, profile } = resolveProfile(params.profile);
+    let connection: string;
+    let reachable = false;
+    try {
+      const identity = await withConnection(profile, { signal }, async (conn) =>
+        conn.identity,
+      );
+      connection = formatIdentity(identity);
+      reachable = true;
+    } catch (err) {
+      connection = `Connection to "${name}" failed:\n${(err as Error).message}`;
+    }
+
+    return {
+      content: [{ type: "text" as const, text: `${overview}\n\n${connection}` }],
+      details: {
+        count: Object.keys(profiles).length,
+        profiles: Object.keys(profiles),
+        activeProfile: getActiveProfile(),
+        checked: name,
+        reachable,
+      },
+    };
+  },
+};

package/src/tools/ssh-upload.ts

@@ -0,0 +1,51 @@
+/**
+ * ssh_upload tool -- Copy a local file to the remote host over SFTP.
+ */
+
+import { Type } from "typebox";
+import { resolveProfile } from "../config.ts";
+import { uploadFile, withConnection } from "../clients/ssh-client.ts";
+import { formatTransfer } from "../formatting/formatters.ts";
+
+export const SshUploadTool = {
+  name: "ssh_upload",
+  label: "SSH Upload File",
+  description:
+    "Copy a file from this machine to the remote host over SFTP. The remote path must include the file name; an existing file at that path is overwritten.",
+  parameters: Type.Object({
+    localPath: Type.String({ description: "File on this machine. Absolute paths are safest." }),
+    remotePath: Type.String({
+      description: "Destination path on the remote host, 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: {
+      localPath: string;
+      remotePath: string;
+      profile?: string;
+      acceptNewHostKey?: boolean;
+    },
+    signal: AbortSignal,
+  ) {
+    const { name, profile } = resolveProfile(params.profile);
+
+    const result = await withConnection(
+      profile,
+      { signal, acceptNewHostKey: params.acceptNewHostKey },
+      (connection) => uploadFile(connection, params.localPath, params.remotePath),
+    );
+
+    return {
+      content: [{ type: "text" as const, text: formatTransfer(result, "up") }],
+      details: { profile: name, ...result },
+    };
+  },
+};

package/src/types.ts

@@ -0,0 +1,144 @@
+/**
+ * Data types for the pi SSH extension.
+ *
+ * All domain data is represented as plain immutable-shaped interfaces.
+ * No behavior, no classes, no inheritance -- just data (errors excepted).
+ */
+
+// Configuration
+
+export interface SshProfile {
+  readonly host: string;
+  readonly port: number;
+  readonly user: string;
+  /** Password auth. Stored in plaintext, so the file is 0600. */
+  readonly password?: string;
+  /** Path to a private key on this machine. The key itself is not copied. */
+  readonly privateKeyPath?: string;
+  /** Passphrase for that key, when it has one. */
+  readonly passphrase?: string;
+  /** Override the known_hosts file for this profile. */
+  readonly knownHostsFile?: string;
+  /**
+   * Refuse to connect to a host whose key is not on record. On by default:
+   * turning it off removes the only defence against a machine-in-the-middle.
+   */
+  readonly strictHostKey?: boolean;
+  readonly connectTimeoutMs?: number;
+}
+
+export interface SshProfiles {
+  readonly profiles: Record<string, SshProfile>;
+  readonly activeProfile: string | null;
+}
+
+// Domain
+
+export interface ExecResult {
+  readonly command: string;
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly code: number | null;
+  /** Set when the command was killed by a signal rather than exiting. */
+  readonly signal?: string;
+  readonly durationMs: number;
+  /** True when output was cut off at the configured limit. */
+  readonly truncated: boolean;
+}
+
+export interface RemoteEntry {
+  readonly name: string;
+  readonly type: "file" | "directory" | "symlink" | "other";
+  readonly size: number;
+  readonly modified?: string;
+  readonly mode: string;
+}
+
+export interface TransferResult {
+  readonly localPath: string;
+  readonly remotePath: string;
+  readonly size: number;
+}
+
+export interface ServerIdentity {
+  readonly host: string;
+  readonly port: number;
+  readonly user: string;
+  readonly fingerprint: string;
+  readonly keyType: string;
+  /** How the host key compared to known_hosts. */
+  readonly hostKeyVerdict: string;
+  /** Which authentication method actually succeeded. */
+  readonly authMethod: string;
+}
+
+export interface AuthorizeResult {
+  readonly profile: string;
+  readonly keyPath: string;
+  readonly publicKeyPath: string;
+  readonly fingerprint: string;
+  /** False when the key was already present in authorized_keys. */
+  readonly installed: boolean;
+  /** True when a passwordless login was confirmed afterwards. */
+  readonly verified: boolean;
+  readonly authorizedKeysPath: string;
+}
+
+// Tool parameter shapes
+
+export interface SetupParams {
+  readonly name: string;
+  readonly host: string;
+  readonly user: string;
+  readonly port?: number;
+  readonly password?: string;
+  readonly privateKeyPath?: string;
+  readonly passphrase?: string;
+  readonly strictHostKey?: boolean;
+}
+
+// Errors
+
+export class SshNotConfiguredError extends Error {
+  constructor() {
+    super("No SSH host configured. Use the ssh_setup tool first (host, user, and a password or key).");
+    this.name = "SshNotConfiguredError";
+  }
+}
+
+export class HostKeyChangedError extends Error {
+  readonly fingerprint: string;
+
+  constructor(message: string, fingerprint: string) {
+    super(message);
+    this.name = "HostKeyChangedError";
+    this.fingerprint = fingerprint;
+  }
+}
+
+export class UnknownHostKeyError extends Error {
+  readonly fingerprint: string;
+
+  constructor(message: string, fingerprint: string) {
+    super(message);
+    this.name = "UnknownHostKeyError";
+    this.fingerprint = fingerprint;
+  }
+}
+
+export class SshAuthError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "SshAuthError";
+  }
+}
+
+export class RemoteCommandError extends Error {
+  readonly result: ExecResult;
+
+  constructor(message: string, result: ExecResult) {
+    super(message);
+    this.name = "RemoteCommandError";
+    this.result = result;
+  }
+}