@patimweb/pi-ssh 1.0.0 → 1.1.0

package/README.md

@@ -31,7 +31,23 @@ ssh_exec:
   command: systemctl status nginx --no-pager
 ```
 
-After `ssh_authorize` the password is no longer needed. It stays in the profile as a fallback until you pass `removePassword: true`.
+The password is only used once. On the **first connection** the extension installs a key on the host and removes the password from the config — see below.
+
+## The password is not kept
+
+A password in a config file stays there for as long as the profile does. So the first time a password-only profile is actually used — the first `ssh_exec`, `ssh_list`, tunnel, anything that connects — the extension:
+
+1. generates an ed25519 key,
+2. installs its public key in the remote `~/.ssh/authorized_keys`,
+3. opens a second connection using **only** the key to prove it works,
+4. writes the key path into the profile and **deletes the stored password**,
+5. and then does what you actually asked for.
+
+The tool output says so when this happened, including the fingerprint and where the key was written.
+
+If the upgrade fails — a host with `PubkeyAuthentication no`, an unwritable home directory — the password is kept and the work continues, with the reason in the output. The upgrade is attempted, not enforced: a server that refuses keys would otherwise become unusable.
+
+To keep using a password, set `autoKey: false` in `ssh_setup`. `ssh_authorize` then remains available to do the switch by hand.
 
 ## Tools
 
@@ -47,6 +63,7 @@ After `ssh_authorize` the password is no longer needed. It stays in the profile
 | `ssh_keygen` | Create an ed25519 key pair in process. |
 | `ssh_authorize` | Install a key on a host and stop needing the password. |
 | `ssh_doctor` | Report what this machine can do and what needs fixing. |
+| `ssh_tunnel` | Open, close and list port forwards, and store named ones in a profile. |
 
 ### Passwordless login
 
@@ -87,6 +104,120 @@ ssh_upload:   { localPath: ./dist/app.tar.gz, remotePath: /tmp/app.tar.gz }
 
 Missing local directories are created on download. Prefer these over `cat` through `ssh_exec`: SFTP handles binary content and does not push the file through the model.
 
+### Tunnels
+
+A tunnel is the one thing here that keeps running after its tool call returns — that is what a tunnel is for. It stays up until it is stopped, its time limit expires, or the pi session ends, at which point all of them are closed.
+
+There are two directions, and the difference is whose machine each side refers to:
+
+| Kind | Who listens | Who reaches the destination | OpenSSH equivalent |
+|------|-------------|-----------------------------|--------------------|
+| `local` | this machine, on `bind:listenPort` | the server, to `destHost:destPort` | `ssh -L` |
+| `remote` | the server, on `bind:listenPort` | this machine, to `destHost:destPort` | `ssh -R` |
+
+**Local** is the common case: reach a database, admin interface or internal service that only the server can see.
+
+```yaml
+ssh_tunnel:
+  action: start
+  name: db
+  kind: local
+  listenPort: 5432          # 0 picks a free port
+  destHost: db.internal     # resolved from the server
+  destPort: 5432
+  # durationSeconds: 3600   # close automatically after an hour
+```
+
+Then connect to `127.0.0.1:5432` on this machine as if the database were local.
+
+**Remote** goes the other way: make something running here reachable from the server.
+
+```yaml
+ssh_tunnel:
+  action: start
+  name: preview
+  kind: remote
+  listenPort: 8080          # the server listens on this
+  destHost: 127.0.0.1       # resolved from this machine
+  destPort: 3000
+```
+
+#### Named tunnels in the profile
+
+Rather than repeating ports, store a tunnel under a name and start it by that name later. Definitions live in the profile in `~/.pi/ssh-config.json`.
+
+```yaml
+ssh_tunnel:
+  action: define
+  name: db
+  kind: local
+  listenPort: 5432
+  destHost: db.internal
+  destPort: 5432
+  description: production database, read replica
+```
+
+```yaml
+ssh_tunnel: { action: start, name: db }     # everything else comes from the profile
+ssh_tunnel: { action: stop,  name: db }
+ssh_tunnel: { action: forget, name: db }    # remove the definition
+```
+
+The stored form is plain JSON, so it can be written by hand too:
+
+```json
+{
+  "profiles": {
+    "staging": {
+      "host": "staging.example.com",
+      "port": 22,
+      "user": "deploy",
+      "privateKeyPath": "/home/pat/.ssh/id_ed25519_pi_staging",
+      "tunnels": {
+        "db": {
+          "kind": "local",
+          "listenPort": 5432,
+          "bind": "127.0.0.1",
+          "destHost": "db.internal",
+          "destPort": 5432,
+          "description": "production database, read replica"
+        },
+        "preview": {
+          "kind": "remote",
+          "listenPort": 8080,
+          "destHost": "127.0.0.1",
+          "destPort": 3000
+        }
+      }
+    }
+  },
+  "activeProfile": "staging"
+}
+```
+
+| Field | Meaning |
+|-------|---------|
+| `kind` | `local` or `remote`, per the table above. |
+| `listenPort` | Port the tunnel accepts connections on. `0` picks a free one. |
+| `bind` | Interface that port binds to. Defaults to `127.0.0.1`. |
+| `destHost` / `destPort` | Where traffic is delivered. |
+| `description` | Free text, shown in listings. |
+
+#### Seeing and stopping them
+
+```yaml
+ssh_tunnel: { action: list }        # running tunnels and stored definitions
+ssh_tunnel: { action: "stop-all" }
+```
+
+`ssh_status` also lists anything currently running, so a forgotten tunnel does not stay invisible.
+
+#### Binding to something other than loopback
+
+`bind` defaults to `127.0.0.1`, which means only this machine (or only the server, for a remote tunnel) can use the tunnel. Setting it to `0.0.0.0` publishes the forwarded service to the whole network — the tool output says so when you do. For a remote tunnel, binding anything but loopback additionally needs `GatewayPorts` enabled in the server's `sshd_config`; without it sshd silently binds loopback instead.
+
+Each tunnel owns its own SSH connection. Sharing one would be tidier on the wire, but a single dropped connection would take every tunnel down with it.
+
 ## Commands
 
 | Command | Description |
@@ -139,7 +270,7 @@ npm test
 npm run test:coverage
 ```
 
-The suite runs end-to-end against a real OpenSSH server: it starts `sshd` on a loopback port with a host key generated by this package, then exercises the handshake, host key verification (including a simulated key change), exit codes, SFTP, and the full key bootstrap. Those tests skip themselves on machines without `sshd` rather than failing.
+The suite runs end-to-end against a real OpenSSH server: it starts `sshd` on a loopback port with a host key generated by this package, then exercises the handshake, host key verification (including a simulated key change), exit codes, SFTP, the full key bootstrap, and both tunnel directions with real traffic flowing through them. Those tests skip themselves on machines without `sshd` rather than failing.
 
 ## License
 

package/index.ts

@@ -15,6 +15,7 @@
  *   - ssh_keygen: Create an ed25519 key pair in process
  *   - ssh_authorize: Install a key on a host and stop needing the password
  *   - ssh_doctor: Report what the environment can do and what needs fixing
+ *   - ssh_tunnel: Open, close and list port forwards, and store named ones
  *
  * Nothing here shells out: ssh2 is a pure JavaScript SSH implementation and
  * keys are generated with Node's own crypto, so Windows, macOS and Linux all
@@ -40,6 +41,8 @@ import { SshDownloadTool } from "./src/tools/ssh-download.ts";
 import { SshKeygenTool } from "./src/tools/ssh-keygen.ts";
 import { SshAuthorizeTool } from "./src/tools/ssh-authorize.ts";
 import { SshDoctorTool } from "./src/tools/ssh-doctor.ts";
+import { SshTunnelTool } from "./src/tools/ssh-tunnel.ts";
+import { stopAllTunnels } from "./src/tunnels.ts";
 
 export default function (pi: ExtensionAPI) {
   // Load saved hosts on startup
@@ -56,6 +59,13 @@ export default function (pi: ExtensionAPI) {
   pi.registerTool(SshKeygenTool);
   pi.registerTool(SshAuthorizeTool);
   pi.registerTool(SshDoctorTool);
+  pi.registerTool(SshTunnelTool);
+
+  // A tunnel is the one thing here that outlives its tool call, so it must
+  // not outlive the session that opened it.
+  pi.on("session_shutdown", async () => {
+    await stopAllTunnels();
+  });
 
   // Run something on the active host without spelling out the tool call
   pi.registerCommand("ssh", {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patimweb/pi-ssh",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "SSH client extension for the pi coding agent. Run commands, transfer files over SFTP, and set up key-based login on remote hosts.",
   "keywords": [
     "pi-package",

package/skills/ssh-key-setup/SKILL.md

@@ -9,7 +9,22 @@ allowed-tools: ssh_setup, ssh_status, ssh_keygen, ssh_authorize, ssh_exec, ssh_d
 A password in a config file is a password on disk, and typing one into every
 session is friction. A key fixes both. The whole switch is one tool call.
 
-## The normal path
+## It usually happens by itself
+
+A profile configured with only a password upgrades itself on first use: the
+first tool that connects installs a key, verifies it, and **removes the
+password from the config**. Nothing needs to be called for this, and the tool
+output reports it. Say so when relaying that output - the user should know
+their password is no longer stored and where the key went.
+
+If the upgrade failed, the note explains why and the password is still in
+place. That is worth surfacing rather than glossing over: it means the host
+refused key authentication, and the password is still on disk.
+
+`autoKey: false` on `ssh_setup` turns the automatic switch off for hosts where
+it is not wanted.
+
+## Doing it by hand
 
 1. `ssh_setup` with host, user and the password.
 2. `ssh_authorize` on that profile.

package/skills/ssh-remote-work/SKILL.md

@@ -74,6 +74,21 @@ The error usually says which layer failed. Work from it rather than retrying:
 - Something about the local environment - run `ssh_doctor`, which reports what
   is missing and what to do about it.
 
+## Tunnels
+
+`ssh_tunnel` is the one tool here whose effect outlives the call: a forward
+keeps running until stopped, its time limit expires, or the session ends.
+
+- Start one only when something actually needs it, and tell the user it is
+  running and how to reach it.
+- `ssh_tunnel action list`, and `ssh_status`, show what is open. Check there
+  before starting another one with the same purpose.
+- Stop tunnels when the work that needed them is done rather than leaving them
+  open for the rest of the session.
+- `bind` defaults to loopback. Do not set it to `0.0.0.0` unless the user asked
+  for the service to be reachable from other machines, and say plainly what
+  that exposes when you do.
+
 ## What to report back
 
 Give the user the command's actual output and its exit code. When a command

package/src/auto-key.ts

@@ -0,0 +1,83 @@
+/**
+ * First contact upgrades a password login to a key login.
+ *
+ * A password sitting in a config file is a password on disk, and it stays
+ * there for as long as the profile exists. So the first time a profile that
+ * has only a password is actually used, the key bootstrap runs first and the
+ * password is replaced by the key it just installed.
+ *
+ * The upgrade is attempted, not enforced: a host that refuses public key
+ * authentication entirely would otherwise become unusable. When it fails the
+ * password is kept and the caller is told, rather than the work being blocked.
+ */
+
+import type { SshProfile } from "./types.ts";
+import { authorizeKey } from "./authorize.ts";
+import { getProfile } from "./config.ts";
+
+export interface UpgradeOutcome {
+  /** The profile to actually connect with. */
+  readonly profile: SshProfile;
+  /** Set when an upgrade was attempted, whether or not it worked. */
+  readonly note?: string;
+  readonly upgraded: boolean;
+}
+
+/** Does this profile still log in with a password and nothing else? */
+export function needsKeyUpgrade(profile: SshProfile): boolean {
+  if (profile.autoKey === false) return false;
+  return Boolean(profile.password) && !profile.privateKeyPath;
+}
+
+export interface UpgradeOptions {
+  readonly acceptNewHostKey?: boolean;
+  readonly signal?: AbortSignal;
+}
+
+/**
+ * Install a key and drop the password, then return the profile to connect
+ * with. A profile that already has a key, or has opted out, is returned
+ * untouched without opening any connection.
+ */
+export async function ensureKeyAuthentication(
+  profileName: string,
+  profile: SshProfile,
+  options: UpgradeOptions = {},
+): Promise<UpgradeOutcome> {
+  if (!needsKeyUpgrade(profile)) {
+    return { profile, upgraded: false };
+  }
+
+  try {
+    const result = await authorizeKey({
+      profileName,
+      profile,
+      acceptNewHostKey: options.acceptNewHostKey,
+      signal: options.signal,
+      // The point of the upgrade is that the password stops being stored.
+      removePassword: true,
+    });
+
+    if (!result.verified) {
+      return {
+        profile,
+        upgraded: false,
+        note: `A key was installed on ${profile.host}, but a key-only login could not be verified, so the password is still being used. Fingerprint: ${result.fingerprint}`,
+      };
+    }
+
+    // authorizeKey rewrote the stored profile; use what is on disk now.
+    const updated = getProfile(profileName) ?? profile;
+    return {
+      profile: updated,
+      upgraded: true,
+      note: `First connection to ${profile.host}: installed a key (${result.fingerprint}) at ${result.keyPath} and removed the stored password. Logins from now on use the key.`,
+    };
+  } catch (err) {
+    return {
+      profile,
+      upgraded: false,
+      note: `Could not switch ${profile.host} to key authentication (${(err as Error).message}). Continuing with the password.`,
+    };
+  }
+}

package/src/formatting/formatters.ts

@@ -7,6 +7,8 @@
 
 import type {
   AuthorizeResult,
+  RunningTunnel,
+  TunnelDefinition,
   ExecResult,
   RemoteEntry,
   ServerIdentity,
@@ -131,3 +133,77 @@ export function formatAuthorizeResult(result: AuthorizeResult): string {
   ];
   return lines.join("\n");
 }
+
+/** One line describing where a forward starts and where it ends. */
+export function describeTunnel(definition: TunnelDefinition): string {
+  const bind = definition.bind ?? "127.0.0.1";
+  const listen = `${bind}:${definition.listenPort === 0 ? "(free port)" : definition.listenPort}`;
+  const dest = `${definition.destHost}:${definition.destPort}`;
+
+  return definition.kind === "local"
+    ? `local ${listen} -> ${dest} (reached from the server)`
+    : `remote ${listen} on the server -> ${dest} (reached from this machine)`;
+}
+
+export function formatTunnelStarted(
+  tunnel: RunningTunnel,
+  profile: SshProfile,
+): string {
+  const bind = tunnel.definition.bind ?? "127.0.0.1";
+  const lines = [
+    `Tunnel "${tunnel.name}" is up: ${describeTunnel(tunnel.definition)}`,
+    tunnel.definition.kind === "local"
+      ? `Connect to ${tunnel.listenAddress} on this machine.`
+      : `On ${profile.host}, connect to ${tunnel.listenAddress}.`,
+    "",
+    "It keeps running in the background until you stop it with ssh_tunnel action stop"
+      + (tunnel.expiresAt ? `, or automatically at ${tunnel.expiresAt.slice(11, 19)} UTC.` : ", or the pi session ends."),
+  ];
+
+  if (bind !== "127.0.0.1" && bind !== "localhost") {
+    lines.push(
+      "",
+      `Note: this binds ${bind}, not loopback, so anything that can reach that interface can use the tunnel.`,
+    );
+  }
+  return lines.join("\n");
+}
+
+export function formatTunnelList(
+  running: ReadonlyArray<RunningTunnel>,
+  defined: ReadonlyArray<{ profile: string; name: string; definition: TunnelDefinition }>,
+): string {
+  const sections: string[] = [];
+
+  if (running.length === 0) {
+    sections.push("No tunnels are running.");
+  } else {
+    sections.push(`Running tunnels (${running.length}):`);
+    for (const tunnel of running) {
+      sections.push(
+        `- ${tunnel.profile}/${tunnel.name}: ${describeTunnel(tunnel.definition)}`,
+        `  listening on ${tunnel.listenAddress}, ${tunnel.connections} connection(s) since ${tunnel.startedAt.slice(11, 19)} UTC`
+          + (tunnel.expiresAt ? `, closes at ${tunnel.expiresAt.slice(11, 19)} UTC` : ""),
+      );
+    }
+  }
+
+  if (defined.length > 0) {
+    const runningIds = new Set(running.map((tunnel) => `${tunnel.profile}:${tunnel.name}`));
+    sections.push("", `Defined in profiles (${defined.length}):`);
+    for (const entry of defined) {
+      const state = runningIds.has(`${entry.profile}:${entry.name}`) ? " [running]" : "";
+      const purpose = entry.definition.description ? ` -- ${entry.definition.description}` : "";
+      sections.push(
+        `- ${entry.profile}/${entry.name}${state}: ${describeTunnel(entry.definition)}${purpose}`,
+      );
+    }
+  } else if (running.length === 0) {
+    sections.push(
+      "",
+      "Define one with ssh_tunnel action define, so it can be started by name later.",
+    );
+  }
+
+  return sections.join("\n");
+}

package/src/tools/shared.ts

@@ -0,0 +1,33 @@
+/**
+ * What every tool that opens a connection does first.
+ *
+ * Resolving the profile and upgrading it to key authentication belong
+ * together: the upgrade has to happen before the connection the tool actually
+ * wants, and its outcome has to reach the user, so both are done in one place
+ * rather than repeated in each tool.
+ */
+
+import { resolveProfile } from "../config.ts";
+import { ensureKeyAuthentication } from "../auto-key.ts";
+import type { SshProfile } from "../types.ts";
+
+export interface ConnectionContext {
+  readonly name: string;
+  readonly profile: SshProfile;
+  /** Worth showing the user, e.g. that the password was just replaced. */
+  readonly note?: string;
+}
+
+export async function resolveForConnection(
+  profileName: string | undefined,
+  options: { acceptNewHostKey?: boolean; signal?: AbortSignal } = {},
+): Promise<ConnectionContext> {
+  const { name, profile } = resolveProfile(profileName);
+  const outcome = await ensureKeyAuthentication(name, profile, options);
+  return { name, profile: outcome.profile, note: outcome.note };
+}
+
+/** Append a note to a tool's text output, when there is one. */
+export function withNote(text: string, note?: string): string {
+  return note ? `${text}\n\n${note}` : text;
+}

package/src/tools/ssh-download.ts

@@ -3,7 +3,7 @@
  */
 
 import { Type } from "typebox";
-import { resolveProfile } from "../config.ts";
+import { resolveForConnection, withNote } from "./shared.ts";
 import { downloadFile, withConnection } from "../clients/ssh-client.ts";
 import { formatTransfer } from "../formatting/formatters.ts";
 
@@ -35,7 +35,10 @@ export const SshDownloadTool = {
     },
     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 SshDownloadTool = {
     );
 
     return {
-      content: [{ type: "text" as const, text: formatTransfer(result, "down") }],
+      content: [{ type: "text" as const, text: withNote(formatTransfer(result, "down"), note) }],
       details: { profile: name, ...result },
     };
   },

package/src/tools/ssh-exec.ts

@@ -3,7 +3,7 @@
  */
 
 import { Type } from "typebox";
-import { resolveProfile } from "../config.ts";
+import { resolveForConnection, withNote } from "./shared.ts";
 import { execCommand, withConnection } from "../clients/ssh-client.ts";
 import { formatExecResult } from "../formatting/formatters.ts";
 
@@ -45,7 +45,10 @@ export const SshExecTool = {
   ) {
     if (!params.command?.trim()) throw new Error("command must not be empty.");
 
-    const { name, profile } = resolveProfile(params.profile);
+    const { name, profile, note } = await resolveForConnection(params.profile, {
+      acceptNewHostKey: params.acceptNewHostKey,
+      signal,
+    });
     const timeoutMs = Math.min(Math.max(params.timeoutSeconds ?? 120, 1), 3600) * 1000;
 
     const result = await withConnection(
@@ -60,7 +63,7 @@ export const SshExecTool = {
     );
 
     return {
-      content: [{ type: "text" as const, text: formatExecResult(result) }],
+      content: [{ type: "text" as const, text: withNote(formatExecResult(result), note) }],
       details: {
         profile: name,
         host: profile.host,

package/src/tools/ssh-list.ts

@@ -3,7 +3,7 @@
  */
 
 import { Type } from "typebox";
-import { resolveProfile } from "../config.ts";
+import { resolveForConnection, withNote } from "./shared.ts";
 import { listDirectory, withConnection } from "../clients/ssh-client.ts";
 import { formatDirectory } from "../formatting/formatters.ts";
 
@@ -27,7 +27,10 @@ export const SshListTool = {
     params: { path: string; profile?: string; acceptNewHostKey?: boolean },
     signal: AbortSignal,
   ) {
-    const { name, profile } = resolveProfile(params.profile);
+    const { name, profile, note } = await resolveForConnection(params.profile, {
+      acceptNewHostKey: params.acceptNewHostKey,
+      signal,
+    });
     const remotePath = params.path?.trim() || ".";
 
     const entries = await withConnection(
@@ -37,7 +40,9 @@ export const SshListTool = {
     );
 
     return {
-      content: [{ type: "text" as const, text: formatDirectory(entries, remotePath) }],
+      content: [
+        { type: "text" as const, text: withNote(formatDirectory(entries, remotePath), note) },
+      ],
       details: {
         profile: name,
         path: remotePath,

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,326 @@
+/**
+ * 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;
+  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,
+    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; do not leave a stale
+  // entry claiming otherwise.
+  connection.client.on("close", () => {
+    running.delete(id);
+  });
+
+  if (options.durationSeconds && options.durationSeconds > 0) {
+    handle.expiresAt = new Date(Date.now() + options.durationSeconds * 1000);
+    const timer = setTimeout(() => {
+      void handle.stop();
+    }, options.durationSeconds * 1000);
+    timer.unref?.();
+  }
+
+  running.set(id, handle);
+  return describe(handle);
+}
+
+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 handle.stop();
+  running.delete(handle.id);
+  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) => handle.stop().catch(() => undefined)));
+  running.clear();
+  return handles.length;
+}
+
+/** @internal for tests */
+export function _runningCount(): number {
+  return running.size;
+}

package/src/types.ts

@@ -25,6 +25,53 @@ export interface SshProfile {
    */
   readonly strictHostKey?: boolean;
   readonly connectTimeoutMs?: number;
+  /**
+   * Upgrade this profile to key authentication on first use, replacing the
+   * stored password. On by default; set to false to keep using the password.
+   */
+  readonly autoKey?: boolean;
+  /** Named port forwards that ssh_tunnel can start by name. */
+  readonly tunnels?: Record<string, TunnelDefinition>;
+}
+
+/** A tunnel that is currently running. */
+export interface RunningTunnel {
+  readonly id: string;
+  readonly profile: string;
+  readonly name: string;
+  readonly definition: TunnelDefinition;
+  /** Where it actually listens, which matters when listenPort was 0. */
+  readonly listenAddress: string;
+  readonly startedAt: string;
+  readonly connections: number;
+  /** Set when the tunnel closes itself after a fixed time. */
+  readonly expiresAt?: string;
+}
+
+/**
+ * A port forward, stored by name in a profile.
+ *
+ * The same shape describes both directions, and `kind` decides whose machine
+ * each side refers to:
+ *
+ *   local  (ssh -L): this machine listens on bind:listenPort, and the server
+ *                    opens the connection to destHost:destPort.
+ *   remote (ssh -R): the server listens on bind:listenPort, and this machine
+ *                    opens the connection to destHost:destPort.
+ */
+export interface TunnelDefinition {
+  readonly kind: "local" | "remote";
+  /** Port the tunnel accepts connections on. */
+  readonly listenPort: number;
+  /**
+   * Interface to bind that port to. Defaults to 127.0.0.1: binding to
+   * 0.0.0.0 publishes the forwarded service to the whole network.
+   */
+  readonly bind?: string;
+  /** Where traffic is delivered. */
+  readonly destHost: string;
+  readonly destPort: number;
+  readonly description?: string;
 }
 
 export interface SshProfiles {
@@ -95,6 +142,7 @@ export interface SetupParams {
   readonly privateKeyPath?: string;
   readonly passphrase?: string;
   readonly strictHostKey?: boolean;
+  readonly autoKey?: boolean;
 }
 
 // Errors
@@ -133,6 +181,13 @@ export class SshAuthError extends Error {
   }
 }
 
+export class TunnelError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "TunnelError";
+  }
+}
+
 export class RemoteCommandError extends Error {
   readonly result: ExecResult;