@patimweb/pi-ssh 1.0.0 → 1.2.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,133 @@ 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.
+
+#### How long it stays up
+
+A tunnel holds its own SSH connection open and keeps listening after the tool call returns. It ends when:
+
+- you stop it (`action: stop` or `stop-all`),
+- its `durationSeconds` expires,
+- the underlying SSH connection drops, or
+- 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 take every tunnel down with it.
+
+SSH-level keepalives are enabled (every 15s, four unanswered probes before giving up). ssh2 sends none by default, and without them an idle tunnel behind a NAT or a stateful firewall keeps looking alive long after the path has been dropped. With them, a dead connection is noticed within about a minute, the local listener is closed, and the tunnel disappears from `ssh_tunnel list` — rather than accepting connections that silently go nowhere.
+
+There is no automatic reconnect: a tunnel that dies stays dead and has to be started again.
+
 ## Commands
 
 | Command | Description |
@@ -131,6 +275,14 @@ Profiles live in `~/.pi/ssh-config.json`, written atomically with mode `0600` be
 
 Every tool also takes a one-off `profile` parameter, so several hosts can be used in one session without switching.
 
+## Platform support
+
+Windows, macOS and Linux behave the same. Nothing in this package spawns a process — SSH comes from [ssh2](https://github.com/mscdex/ssh2) in pure JavaScript, keys are generated with Node's crypto, and there are no POSIX-only paths. A test asserts all three, so a change that introduces one fails the suite rather than only failing on someone else's machine.
+
+One difference is real and worth knowing: **file permissions are not enforced on Windows.** The config file and private keys are written with mode `0600`, but Windows governs access through ACLs and `chmod` only toggles the read-only bit. `ssh_doctor` reports this as a note on Windows rather than staying quiet about it. The practical answer is the same as everywhere: let the first connection replace the stored password with a key, so the file stops holding a secret at all.
+
+The end-to-end tests need an `sshd` to run against and skip themselves where there is none, which includes Windows.
+
 ## Development
 
 ```bash
@@ -139,7 +291,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.2.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.
@@ -34,6 +49,11 @@ run `ssh_doctor` and show them the report rather than guessing.
 The keys produced are ordinary OpenSSH ed25519 keys, so `ssh -i` and any other
 SSH client can use the same file.
 
+On Windows there is one caveat worth passing on: the owner-only file modes
+this extension sets are not enforced there, because access is governed by
+ACLs. That makes replacing a stored password with a key more valuable, not
+less. `ssh_doctor` says so on that platform.
+
 ## Things worth getting right
 
 - **Never overwrite an existing key.** Every host that already trusts it would

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/clients/ssh-client.ts

@@ -40,6 +40,17 @@ import {
 import { expandPath } from "../config.ts";
 
 const DEFAULT_CONNECT_TIMEOUT_MS = 20_000;
+/**
+ * SSH-level keepalives.
+ *
+ * ssh2 sends none by default. A connection that carries a tunnel can sit idle
+ * for a long time, and anything doing NAT or stateful filtering in between
+ * will eventually drop an idle flow without telling either end -- the tunnel
+ * then looks alive and silently is not. Four unanswered probes at 15s means a
+ * dead connection is noticed within about a minute and closed properly.
+ */
+const KEEPALIVE_INTERVAL_MS = 15_000;
+const KEEPALIVE_COUNT_MAX = 4;
 const DEFAULT_EXEC_TIMEOUT_MS = 120_000;
 /** Enough to be useful, small enough not to swamp a context window. */
 const MAX_OUTPUT_CHARS = 200_000;
@@ -71,7 +82,7 @@ function readPrivateKey(profile: SshProfile): Buffer | null {
 }
 
 /** The authentication methods to offer, in the order they should be tried. */
-function buildAuthMethods(
+export function buildAuthMethods(
   profile: SshProfile,
   only: ConnectOptions["only"],
 ): Array<{ type: string; label: string; key?: Buffer; passphrase?: string; password?: string }> {
@@ -143,6 +154,8 @@ export function connect(
       port: profile.port,
       username: profile.user,
       readyTimeout: profile.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS,
+      keepaliveInterval: KEEPALIVE_INTERVAL_MS,
+      keepaliveCountMax: KEEPALIVE_COUNT_MAX,
 
       hostVerifier: (key: Buffer, verify: (ok: boolean) => void) => {
         const check = checkHostKey(profile.host, profile.port, key, knownHostsFile);

package/src/config.ts

@@ -18,7 +18,7 @@ let profiles: Record<string, SshProfile> = {};
 let activeProfile: string | null = null;
 
 function configPath(): string {
-  const home = process.env.HOME || process.env.USERPROFILE || "~";
+  const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
   return path.join(home, ".pi", "ssh-config.json");
 }
 

package/src/doctor.ts

@@ -25,6 +25,33 @@ export interface Check {
   readonly remedy?: string;
 }
 
+/**
+ * Whether file permissions mean anything on this platform.
+ *
+ * The config file can hold a password and the private keys are secrets, so
+ * they are written 0600. On Windows chmod only toggles the read-only bit and
+ * access is governed by ACLs instead, so those modes are not enforced. Saying
+ * nothing would be the wrong kind of quiet: the situation there is weaker,
+ * not stronger.
+ */
+export function describePermissionSupport(platform: string): Check {
+  if (platform !== "win32") {
+    return {
+      name: "File permissions",
+      status: "ok",
+      detail: "secrets are written owner-only (0600) and that is enforced",
+    };
+  }
+  return {
+    name: "File permissions",
+    status: "note",
+    detail:
+      "Windows ignores the owner-only modes this extension sets; access is governed by ACLs instead",
+    remedy:
+      "~/.pi/ssh-config.json can hold a password and ~/.ssh holds private keys. Make sure your user profile directory is not shared, or let ssh_authorize replace the password with a key.",
+  };
+}
+
 function checkNodeVersion(): Check {
   const major = Number.parseInt(process.versions.node.split(".")[0], 10);
   return major >= 20
@@ -189,6 +216,7 @@ export function runChecks(): Check[] {
     checkSsh2(),
     checkKeyGeneration(),
     checkOpenSshClient(),
+    describePermissionSupport(process.platform),
     checkSshDirectory(),
     checkKnownHosts(),
     checkConfigDirectory(),

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,