@patimweb/pi-ssh 1.0.0 → 1.2.0

package/src/tools/ssh-setup.ts

@@ -35,6 +35,13 @@ export const SshSetupTool = {
     passphrase: Type.Optional(
       Type.String({ description: "Passphrase for that private key, if it has one." }),
     ),
+    autoKey: Type.Optional(
+      Type.Boolean({
+        description:
+          "On the first connection, install an SSH key on the host and replace the stored password with it. Default true. Set false to keep using the password.",
+        default: true,
+      }),
+    ),
     strictHostKey: Type.Optional(
       Type.Boolean({
         description:
@@ -67,14 +74,18 @@ export const SshSetupTool = {
         ? { privateKeyPath: expandPath(params.privateKeyPath) }
         : {}),
       ...(params.passphrase ? { passphrase: params.passphrase } : {}),
+      ...(params.autoKey === false ? { autoKey: false } : {}),
       ...(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."
-      : "";
+    const advice =
+      profile.password && !profile.privateKeyPath
+        ? params.autoKey === false
+          ? "\n\nThis profile logs in with a password and will keep doing so. Run ssh_authorize to switch to a key."
+          : "\n\nThis profile logs in with a password. On the first connection a key will be installed on the host and the password removed from the config; pass autoKey: false to prevent that."
+        : "";
 
     return {
       content: [

package/src/tools/ssh-status.ts

@@ -3,9 +3,11 @@
  */
 
 import { Type } from "typebox";
-import { getActiveProfile, getProfiles, resolveProfile } from "../config.ts";
+import { getActiveProfile, getProfiles } from "../config.ts";
+import { resolveForConnection, withNote } from "./shared.ts";
 import { withConnection } from "../clients/ssh-client.ts";
-import { formatIdentity, formatProfileStatus } from "../formatting/formatters.ts";
+import { formatIdentity, formatProfileStatus, formatTunnelList } from "../formatting/formatters.ts";
+import { listTunnels } from "../tunnels.ts";
 
 export const SshStatusTool = {
   name: "ssh_status",
@@ -30,7 +32,13 @@ export const SshStatusTool = {
     signal: AbortSignal,
   ) {
     const profiles = getProfiles();
-    const overview = formatProfileStatus(profiles, getActiveProfile());
+    const running = listTunnels();
+    // A tunnel outlives the call that opened it, so status is where it has to
+    // become visible again.
+    const overview = [
+      formatProfileStatus(profiles, getActiveProfile()),
+      ...(running.length > 0 ? ["", formatTunnelList(running, [])] : []),
+    ].join("\n");
 
     if (Object.keys(profiles).length === 0 || !params.connect) {
       return {
@@ -43,7 +51,7 @@ export const SshStatusTool = {
       };
     }
 
-    const { name, profile } = resolveProfile(params.profile);
+    const { name, profile, note } = await resolveForConnection(params.profile, { signal });
     let connection: string;
     let reachable = false;
     try {
@@ -57,7 +65,9 @@ export const SshStatusTool = {
     }
 
     return {
-      content: [{ type: "text" as const, text: `${overview}\n\n${connection}` }],
+      content: [
+        { type: "text" as const, text: withNote(`${overview}\n\n${connection}`, note) },
+      ],
       details: {
         count: Object.keys(profiles).length,
         profiles: Object.keys(profiles),

package/src/tools/ssh-tunnel.ts

@@ -0,0 +1,251 @@
+/**
+ * ssh_tunnel tool -- Port forwarding, and the named forwards a profile keeps.
+ *
+ * Both the running tunnels and their stored definitions live here because
+ * they are the same subject from a user's point of view: define a forward
+ * once, then start and stop it by name.
+ */
+
+import { Type } from "typebox";
+import { getProfiles, resolveProfile, updateProfile } from "../config.ts";
+import { resolveForConnection, withNote } from "./shared.ts";
+import {
+  listTunnels,
+  startTunnel,
+  stopAllTunnels,
+  stopTunnel,
+  validateDefinition,
+} from "../tunnels.ts";
+import { formatTunnelList, formatTunnelStarted } from "../formatting/formatters.ts";
+import type { TunnelDefinition } from "../types.ts";
+import { TunnelError } from "../types.ts";
+
+const ACTIONS = new Set(["start", "stop", "stop-all", "list", "define", "forget"]);
+
+function buildDefinition(params: {
+  kind?: string;
+  listenPort?: number;
+  bind?: string;
+  destHost?: string;
+  destPort?: number;
+  description?: string;
+}): TunnelDefinition {
+  const definition: TunnelDefinition = {
+    kind: (params.kind ?? "local") as TunnelDefinition["kind"],
+    listenPort: params.listenPort ?? 0,
+    destHost: params.destHost ?? "",
+    destPort: params.destPort ?? 0,
+    ...(params.bind ? { bind: params.bind } : {}),
+    ...(params.description ? { description: params.description } : {}),
+  };
+  validateDefinition(definition);
+  return definition;
+}
+
+export const SshTunnelTool = {
+  name: "ssh_tunnel",
+  label: "SSH Tunnel",
+  description:
+    "Open, close and list SSH port forwards, and store named ones in a profile. A local tunnel makes a service behind the server reachable on this machine (like ssh -L); a remote tunnel makes something on this machine reachable from the server (like ssh -R). Unlike the other tools, a tunnel keeps running after the call returns, until it is stopped, its time limit expires, or the pi session ends.",
+  parameters: Type.Object({
+    action: Type.Optional(
+      Type.String({
+        description:
+          "One of: start, stop, stop-all, list, define, forget. Defaults to list. 'define' stores a named tunnel in the profile; 'start' runs one, by name or from the ports given here.",
+        default: "list",
+      }),
+    ),
+    name: Type.Optional(
+      Type.String({
+        description:
+          "Name of the tunnel. Required for define, forget and stop; for start it selects a stored definition.",
+      }),
+    ),
+    kind: Type.Optional(
+      Type.String({
+        description:
+          "local (this machine listens, the server reaches the destination) or remote (the server listens, this machine reaches the destination). Default local.",
+        default: "local",
+      }),
+    ),
+    listenPort: Type.Optional(
+      Type.Number({
+        description:
+          "Port the tunnel accepts connections on: local to this machine for a local tunnel, on the server for a remote one. 0 picks a free port.",
+      }),
+    ),
+    bind: Type.Optional(
+      Type.String({
+        description:
+          "Interface that port binds to. Default 127.0.0.1. Using 0.0.0.0 exposes the forwarded service to the whole network, and for a remote tunnel the server also needs GatewayPorts enabled.",
+      }),
+    ),
+    destHost: Type.Optional(
+      Type.String({
+        description:
+          "Host the traffic is delivered to, resolved from the server for a local tunnel and from this machine for a remote one.",
+      }),
+    ),
+    destPort: Type.Optional(Type.Number({ description: "Port on destHost." })),
+    description: Type.Optional(
+      Type.String({ description: "What this tunnel is for, shown in listings." }),
+    ),
+    durationSeconds: Type.Optional(
+      Type.Number({
+        description: "Close the tunnel automatically after this long. Default: no limit.",
+      }),
+    ),
+    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: {
+      action?: string;
+      name?: string;
+      kind?: string;
+      listenPort?: number;
+      bind?: string;
+      destHost?: string;
+      destPort?: number;
+      description?: string;
+      durationSeconds?: number;
+      profile?: string;
+      acceptNewHostKey?: boolean;
+    },
+    signal: AbortSignal,
+  ) {
+    const action = (params.action ?? "list").toLowerCase();
+    if (!ACTIONS.has(action)) {
+      throw new TunnelError(
+        `Unknown action "${params.action}". Use start, stop, stop-all, list, define or forget.`,
+      );
+    }
+
+    if (action === "list") {
+      const running = listTunnels();
+      const defined = Object.entries(getProfiles()).flatMap(([profileName, profile]) =>
+        Object.entries(profile.tunnels ?? {}).map(([name, definition]) => ({
+          profile: profileName,
+          name,
+          definition,
+        })),
+      );
+      return {
+        content: [{ type: "text" as const, text: formatTunnelList(running, defined) }],
+        details: { running: running.length, defined: defined.length, tunnels: running },
+      };
+    }
+
+    if (action === "stop-all") {
+      const stopped = await stopAllTunnels();
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: stopped === 0 ? "No tunnels were running." : `Stopped ${stopped} tunnel(s).`,
+          },
+        ],
+        details: { stopped },
+      };
+    }
+
+    if (!params.name) {
+      throw new TunnelError(`The "${action}" action requires a tunnel name.`);
+    }
+
+    if (action === "define") {
+      const { name: profileName, profile } = resolveProfile(params.profile);
+      const definition = buildDefinition(params);
+      updateProfile(profileName, {
+        tunnels: { ...(profile.tunnels ?? {}), [params.name]: definition },
+      });
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `Tunnel "${params.name}" defined for profile "${profileName}". Start it with ssh_tunnel action start, name ${params.name}.`,
+          },
+        ],
+        details: { profile: profileName, name: params.name, definition },
+      };
+    }
+
+    if (action === "forget") {
+      const { name: profileName, profile } = resolveProfile(params.profile);
+      const tunnels = { ...(profile.tunnels ?? {}) };
+      const existed = params.name in tunnels;
+      delete tunnels[params.name];
+      updateProfile(profileName, { tunnels });
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: existed
+              ? `Tunnel "${params.name}" removed from profile "${profileName}".`
+              : `Profile "${profileName}" has no tunnel called "${params.name}".`,
+          },
+        ],
+        details: { profile: profileName, name: params.name, removed: existed },
+      };
+    }
+
+    if (action === "stop") {
+      const { name: profileName } = resolveProfile(params.profile);
+      const stopped = await stopTunnel(profileName, params.name);
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: stopped
+              ? `Tunnel "${params.name}" stopped.`
+              : `No running tunnel called "${params.name}" for profile "${profileName}".`,
+          },
+        ],
+        details: { profile: profileName, name: params.name, stopped },
+      };
+    }
+
+    // start
+    const { name: profileName, profile, note } = await resolveForConnection(params.profile, {
+      acceptNewHostKey: params.acceptNewHostKey,
+      signal,
+    });
+
+    const stored = profile.tunnels?.[params.name];
+    const definition =
+      params.destHost || params.destPort ? buildDefinition(params) : stored;
+
+    if (!definition) {
+      const available = Object.keys(profile.tunnels ?? {});
+      throw new TunnelError(
+        `No tunnel called "${params.name}" is defined for profile "${profileName}"${
+          available.length > 0 ? ` (available: ${available.join(", ")})` : ""
+        }, and no destHost/destPort were given to build one.`,
+      );
+    }
+    validateDefinition(definition);
+
+    const running = await startTunnel({
+      profileName,
+      profile,
+      name: params.name,
+      definition,
+      acceptNewHostKey: params.acceptNewHostKey,
+      durationSeconds: params.durationSeconds,
+      signal,
+    });
+
+    return {
+      content: [
+        { type: "text" as const, text: withNote(formatTunnelStarted(running, profile), note) },
+      ],
+      details: { profile: profileName, ...running },
+    };
+  },
+};

package/src/tools/ssh-upload.ts

@@ -3,7 +3,7 @@
  */
 
 import { Type } from "typebox";
-import { resolveProfile } from "../config.ts";
+import { resolveForConnection, withNote } from "./shared.ts";
 import { uploadFile, withConnection } from "../clients/ssh-client.ts";
 import { formatTransfer } from "../formatting/formatters.ts";
 
@@ -35,7 +35,10 @@ export const SshUploadTool = {
     },
     signal: AbortSignal,
   ) {
-    const { name, profile } = resolveProfile(params.profile);
+    const { name, profile, note } = await resolveForConnection(params.profile, {
+      acceptNewHostKey: params.acceptNewHostKey,
+      signal,
+    });
 
     const result = await withConnection(
       profile,
@@ -44,7 +47,7 @@ export const SshUploadTool = {
     );
 
     return {
-      content: [{ type: "text" as const, text: formatTransfer(result, "up") }],
+      content: [{ type: "text" as const, text: withNote(formatTransfer(result, "up"), note) }],
       details: { profile: name, ...result },
     };
   },

package/src/tunnels.ts

@@ -0,0 +1,340 @@
+/**
+ * Port forwarding.
+ *
+ * This is the one place where something deliberately outlives the tool call
+ * that created it: a tunnel is only useful while it is open, so it runs in the
+ * background and is stopped explicitly. Everything else about the design is
+ * there to keep that from becoming a leak -- every tunnel is in a registry
+ * that `ssh_tunnel list` and `ssh_status` show, each one can carry a time
+ * limit, and the extension closes all of them when the pi session ends.
+ *
+ * Each tunnel owns its own SSH connection. Sharing one would be tidier on the
+ * wire, but a single dropped connection would then take every tunnel with it.
+ */
+
+import * as net from "node:net";
+import type { Connection } from "./clients/ssh-client.ts";
+import { connect } from "./clients/ssh-client.ts";
+import type { RunningTunnel, SshProfile, TunnelDefinition } from "./types.ts";
+import { TunnelError } from "./types.ts";
+
+const DEFAULT_BIND = "127.0.0.1";
+
+interface TunnelHandle {
+  readonly id: string;
+  readonly profile: string;
+  readonly name: string;
+  readonly definition: TunnelDefinition;
+  readonly startedAt: Date;
+  listenAddress: string;
+  connections: number;
+  expiresAt?: Date;
+  stopped: boolean;
+  stop(): Promise<void>;
+}
+
+const running = new Map<string, TunnelHandle>();
+
+function tunnelId(profile: string, name: string): string {
+  return `${profile}:${name}`;
+}
+
+/** Reject a definition before anything is opened. */
+export function validateDefinition(definition: TunnelDefinition): void {
+  if (definition.kind !== "local" && definition.kind !== "remote") {
+    throw new TunnelError(`Unknown tunnel kind "${definition.kind}". Use local or remote.`);
+  }
+  for (const [label, port] of [
+    ["listenPort", definition.listenPort],
+    ["destPort", definition.destPort],
+  ] as const) {
+    // 0 is allowed for listenPort only: it means "pick a free one".
+    const min = label === "listenPort" ? 0 : 1;
+    if (!Number.isInteger(port) || port < min || port > 65535) {
+      throw new TunnelError(`${label} must be an integer between ${min} and 65535.`);
+    }
+  }
+  if (!definition.destHost?.trim()) {
+    throw new TunnelError("destHost must not be empty.");
+  }
+}
+
+/** Pipe two streams together and tear both down when either ends. */
+function join(a: NodeJS.ReadWriteStream & { destroy?: () => void }, b: NodeJS.ReadWriteStream & { destroy?: () => void }): void {
+  a.pipe(b);
+  b.pipe(a);
+
+  const close = () => {
+    try {
+      a.destroy?.();
+    } catch {
+      /* already gone */
+    }
+    try {
+      b.destroy?.();
+    } catch {
+      /* already gone */
+    }
+  };
+
+  a.on("error", close);
+  b.on("error", close);
+  a.on("close", close);
+  b.on("close", close);
+}
+
+/**
+ * ssh -L: listen here, let the server reach the destination.
+ */
+async function startLocal(
+  connection: Connection,
+  definition: TunnelDefinition,
+  handle: TunnelHandle,
+): Promise<string> {
+  const bind = definition.bind ?? DEFAULT_BIND;
+  const sockets = new Set<net.Socket>();
+
+  const server = net.createServer((socket) => {
+    sockets.add(socket);
+    socket.on("close", () => sockets.delete(socket));
+
+    connection.client.forwardOut(
+      socket.remoteAddress ?? "127.0.0.1",
+      socket.remotePort ?? 0,
+      definition.destHost,
+      definition.destPort,
+      (err, stream) => {
+        if (err) {
+          // The destination refused or does not resolve from the server. The
+          // tunnel itself stays up; only this connection fails.
+          socket.destroy();
+          return;
+        }
+        handle.connections += 1;
+        join(socket, stream);
+      },
+    );
+  });
+
+  const address = await new Promise<string>((resolve, reject) => {
+    server.once("error", (err: NodeJS.ErrnoException) => {
+      if (err.code === "EADDRINUSE") {
+        reject(
+          new TunnelError(
+            `Local port ${definition.listenPort} is already in use. Pick another listenPort, or 0 to let the system choose.`,
+          ),
+        );
+        return;
+      }
+      if (err.code === "EACCES") {
+        reject(
+          new TunnelError(
+            `Not allowed to listen on port ${definition.listenPort}. Ports below 1024 need elevated rights.`,
+          ),
+        );
+        return;
+      }
+      reject(err);
+    });
+    server.listen(definition.listenPort, bind, () => {
+      const info = server.address() as net.AddressInfo;
+      resolve(`${bind}:${info.port}`);
+    });
+  });
+
+  const originalStop = handle.stop;
+  handle.stop = async () => {
+    for (const socket of sockets) socket.destroy();
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+    await originalStop();
+  };
+
+  return address;
+}
+
+/**
+ * ssh -R: the server listens, and connections come back here.
+ */
+async function startRemote(
+  connection: Connection,
+  definition: TunnelDefinition,
+  handle: TunnelHandle,
+): Promise<string> {
+  const bind = definition.bind ?? DEFAULT_BIND;
+  const sockets = new Set<net.Socket>();
+
+  const boundPort = await new Promise<number>((resolve, reject) => {
+    connection.client.forwardIn(bind, definition.listenPort, (err, port) => {
+      if (err) {
+        reject(
+          new TunnelError(
+            [
+              `The server refused to listen on ${bind}:${definition.listenPort}: ${err.message}.`,
+              "Usually the port is taken, or sshd only allows loopback binds -- binding to anything other than 127.0.0.1 needs GatewayPorts in its sshd_config.",
+            ].join(" "),
+          ),
+        );
+        return;
+      }
+      resolve(definition.listenPort === 0 ? (port as number) : definition.listenPort);
+    });
+  });
+
+  connection.client.on("tcp connection", (details, accept, reject) => {
+    // One connection carries one tunnel, but the server still reports which
+    // binding a connection arrived on.
+    if (details.destPort !== boundPort) {
+      reject();
+      return;
+    }
+
+    const stream = accept();
+    handle.connections += 1;
+
+    const socket = net.connect(definition.destPort, definition.destHost, () => {
+      join(socket, stream);
+    });
+    sockets.add(socket);
+    socket.on("close", () => sockets.delete(socket));
+    socket.on("error", () => {
+      // Nothing is listening on our side; drop the forwarded connection.
+      stream.destroy();
+      socket.destroy();
+    });
+  });
+
+  const originalStop = handle.stop;
+  handle.stop = async () => {
+    for (const socket of sockets) socket.destroy();
+    await new Promise<void>((resolve) => {
+      try {
+        connection.client.unforwardIn(bind, boundPort, () => resolve());
+      } catch {
+        resolve();
+      }
+    });
+    await originalStop();
+  };
+
+  return `${bind}:${boundPort}`;
+}
+
+export interface StartTunnelOptions {
+  readonly profileName: string;
+  readonly profile: SshProfile;
+  readonly name: string;
+  readonly definition: TunnelDefinition;
+  readonly acceptNewHostKey?: boolean;
+  /** Close the tunnel automatically after this long. */
+  readonly durationSeconds?: number;
+  readonly signal?: AbortSignal;
+}
+
+export async function startTunnel(options: StartTunnelOptions): Promise<RunningTunnel> {
+  const { definition, name, profileName } = options;
+  validateDefinition(definition);
+
+  const id = tunnelId(profileName, name);
+  if (running.has(id)) {
+    throw new TunnelError(
+      `A tunnel called "${name}" is already running for profile "${profileName}". Stop it first, or give this one another name.`,
+    );
+  }
+
+  const connection = await connect(options.profile, {
+    acceptNewHostKey: options.acceptNewHostKey,
+    signal: options.signal,
+  });
+
+  const handle: TunnelHandle = {
+    id,
+    profile: profileName,
+    name,
+    definition,
+    startedAt: new Date(),
+    listenAddress: "",
+    connections: 0,
+    stopped: false,
+    stop: async () => {
+      connection.client.end();
+      running.delete(id);
+    },
+  };
+
+  try {
+    handle.listenAddress =
+      definition.kind === "local"
+        ? await startLocal(connection, definition, handle)
+        : await startRemote(connection, definition, handle);
+  } catch (err) {
+    connection.client.end();
+    throw err;
+  }
+
+  // A dropped SSH connection means the tunnel is dead. Removing it from the
+  // registry is not enough: the local listener would keep accepting
+  // connections that can no longer go anywhere, so it has to be torn down
+  // too.
+  connection.client.on("close", () => {
+    void teardown(handle);
+  });
+
+  if (options.durationSeconds && options.durationSeconds > 0) {
+    handle.expiresAt = new Date(Date.now() + options.durationSeconds * 1000);
+    const timer = setTimeout(() => {
+      void teardown(handle);
+    }, options.durationSeconds * 1000);
+    timer.unref?.();
+  }
+
+  running.set(id, handle);
+  return describe(handle);
+}
+
+/** Stop a tunnel once, whether the caller asked or the connection died. */
+async function teardown(handle: TunnelHandle): Promise<void> {
+  if (handle.stopped) return;
+  handle.stopped = true;
+  try {
+    await handle.stop();
+  } finally {
+    running.delete(handle.id);
+  }
+}
+
+function describe(handle: TunnelHandle): RunningTunnel {
+  return {
+    id: handle.id,
+    profile: handle.profile,
+    name: handle.name,
+    definition: handle.definition,
+    listenAddress: handle.listenAddress,
+    startedAt: handle.startedAt.toISOString(),
+    connections: handle.connections,
+    expiresAt: handle.expiresAt?.toISOString(),
+  };
+}
+
+export function listTunnels(): RunningTunnel[] {
+  return [...running.values()].map(describe).sort((a, b) => a.id.localeCompare(b.id));
+}
+
+export async function stopTunnel(profileName: string, name: string): Promise<boolean> {
+  const handle = running.get(tunnelId(profileName, name));
+  if (!handle) return false;
+  await teardown(handle);
+  return true;
+}
+
+/** Close everything. Called when the pi session ends. */
+export async function stopAllTunnels(): Promise<number> {
+  const handles = [...running.values()];
+  await Promise.all(handles.map((handle) => teardown(handle).catch(() => undefined)));
+  running.clear();
+  return handles.length;
+}
+
+/** @internal for tests */
+export function _runningCount(): number {
+  return running.size;
+}