@patimweb/pi-ssh 1.1.0 → 1.2.0

package/README.md

@@ -216,8 +216,21 @@ ssh_tunnel: { action: "stop-all" }
 
 `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 |
@@ -262,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patimweb/pi-ssh",
-  "version": "1.1.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

@@ -49,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/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/tunnels.ts

@@ -29,6 +29,7 @@ interface TunnelHandle {
   listenAddress: string;
   connections: number;
   expiresAt?: Date;
+  stopped: boolean;
   stop(): Promise<void>;
 }
 
@@ -253,6 +254,7 @@ export async function startTunnel(options: StartTunnelOptions): Promise<RunningT
     startedAt: new Date(),
     listenAddress: "",
     connections: 0,
+    stopped: false,
     stop: async () => {
       connection.client.end();
       running.delete(id);
@@ -269,16 +271,18 @@ export async function startTunnel(options: StartTunnelOptions): Promise<RunningT
     throw err;
   }
 
-  // A dropped SSH connection means the tunnel is dead; do not leave a stale
-  // entry claiming otherwise.
+  // 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", () => {
-    running.delete(id);
+    void teardown(handle);
   });
 
   if (options.durationSeconds && options.durationSeconds > 0) {
     handle.expiresAt = new Date(Date.now() + options.durationSeconds * 1000);
     const timer = setTimeout(() => {
-      void handle.stop();
+      void teardown(handle);
     }, options.durationSeconds * 1000);
     timer.unref?.();
   }
@@ -287,6 +291,17 @@ export async function startTunnel(options: StartTunnelOptions): Promise<RunningT
   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,
@@ -307,15 +322,14 @@ export function listTunnels(): RunningTunnel[] {
 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);
+  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) => handle.stop().catch(() => undefined)));
+  await Promise.all(handles.map((handle) => teardown(handle).catch(() => undefined)));
   running.clear();
   return handles.length;
 }