cmux-ssh-here 0.2.1 → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Viktor Silakov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -15,7 +15,9 @@ Output:
   https://cmux.com/deeplink/ssh?host=192.168.1.42&port=52968&user=wudUKicRFRw3&host-key-policy=accept-new&title=your-mac
 ```
 
-Open the link — cmux connects on its own. `Ctrl-C` in the terminal stops the server.
+Open the link — cmux connects on its own. The server terminal shows a live dashboard: the current link, a countdown until it regenerates, and the list of connected sessions. `Ctrl-C` stops the server.
+
+The link (and its token) is valid for **3 minutes**, then a fresh one is generated — already-connected sessions stay alive; only new connections need the new link.
 
 ## How it works
 
@@ -23,6 +25,7 @@ Open the link — cmux connects on its own. `Ctrl-C` in the terminal stops the s
 - The token is passed in the deep link's `user=`; the server only accepts the correct token.
 - cmux deep links deliberately carry no passwords or keys, so the secret is the token itself.
 - Full PTY shell via `node-pty`, with window-resize support.
+- Real exec channel (raw pipes) and a filesystem-backed SFTP server, so `scp`/`sftp` work — this is what lets `cmux ssh` upload and run its remote helper. A shell-only server is not enough for cmux.
 - When `tmux` is available, the interactive shell runs inside it: sessions persist and are shared across connections, and the session list (`choose-tree`) is shown on connect. Without `tmux`, it falls back to a plain login shell.
 
 ## Requirements
@@ -39,4 +42,5 @@ Open the link — cmux connects on its own. `Ctrl-C` in the terminal stops the s
 ## Options
 
 - `PORT=2222 npx cmux-ssh-here` — fixed port (random free port by default).
-- `CMUX_SSH_DEBUG=1 npx cmux-ssh-here` — log incoming auth/env/exec/shell requests to stderr (troubleshooting).
+- `CMUX_SSH_TTL=600 npx cmux-ssh-here` — link/token lifetime in seconds before regeneration (default 180).
+- `CMUX_SSH_DEBUG=1 npx cmux-ssh-here` — log incoming auth/env/exec/shell requests to stderr (disables the live dashboard).

package/bin.js

@@ -3,13 +3,21 @@
 // Spins up an ephemeral token-auth SSH server and prints a cmux deep link.
 // Anyone on the LAN who opens the link lands in a shell as the current user.
 // ponytail: the token is a bearer secret. Trusted LAN only, not the internet.
+//
+// This is a near-full SSH server (auth + pty/shell + exec + SFTP) on purpose:
+// cmux's `cmux ssh` flow scp-uploads a helper daemon (cmuxd-remote) and then
+// talks a binary protocol to it over an exec channel. A shell-only server is
+// not enough; SFTP (for scp) and raw-pipe exec (binary-clean) are required.
 import ssh2 from "ssh2"; // ponytail: ssh2 is CJS, no named exports
 const { Server } = ssh2;
+const { OPEN_MODE, STATUS_CODE } = ssh2.utils.sftp;
 import { generateKeyPairSync, randomBytes } from "node:crypto";
 import os from "node:os";
+import fs from "node:fs";
+import { spawn } from "node:child_process";
 import { chmodSync } from "node:fs";
 import { createRequire } from "node:module";
-import { dirname, join } from "node:path";
+import { dirname, join, resolve } from "node:path";
 
 // ponytail: node-pty's prebuilt spawn-helper sometimes unpacks without +x
 // (packaging bug) -> "posix_spawnp failed". Fix it before importing.
@@ -23,7 +31,18 @@ const { default: pty } = await import("node-pty");
 
 // ponytail: hex (not base64url) — cmux rejects a user that starts with "-",
 // and an ssh client treats a leading-dash username as a flag. Hex is URL/ssh-safe.
-const token = randomBytes(12).toString("hex"); // secret carried in user=<token>
+const TTL_SECONDS = Number(process.env.CMUX_SSH_TTL) || 180; // link/token lifetime before regeneration
+let token; // secret carried in user=<token>; rotated every TTL_SECONDS
+let remaining; // seconds until the next regeneration
+const regenerateToken = () => {
+  token = randomBytes(12).toString("hex");
+  remaining = TTL_SECONDS;
+};
+regenerateToken();
+
+// Active authenticated connections, shown live in the server terminal.
+const sessions = new Map();
+let nextSid = 0;
 const { privateKey } = generateKeyPairSync("rsa", {
   // ponytail: rsa PEM parses cleanly in ssh2 (ed25519 PKCS8 is hit-or-miss)
   modulusLength: 2048,
@@ -32,15 +51,24 @@ const { privateKey } = generateKeyPairSync("rsa", {
 });
 
 const shellPath = process.env.SHELL || "/bin/zsh";
+const debug = process.env.CMUX_SSH_DEBUG ? (...a) => console.error("[debug]", ...a) : () => {};
 
 const lanIP = () =>
   Object.values(os.networkInterfaces())
     .flat()
     .find((i) => i?.family === "IPv4" && !i.internal && !i.address.startsWith("169.254"))?.address;
 
-// Run a command in a PTY and bridge it to an ssh2 channel.
-function bridge(stream, args, term) {
-  const child = pty.spawn(shellPath, args, {
+// Interactive shell over a PTY (plain `ssh user@host` with no remote command).
+function startShell(stream, term) {
+  // ponytail: route the interactive shell through tmux so sessions persist and
+  // are shared across LAN connections; show the session list on connect.
+  // Falls back to a plain login shell when tmux is absent.
+  const start =
+    'if command -v tmux >/dev/null 2>&1; then ' +
+    'exec tmux new-session -A -s main \\; choose-tree -Zs; ' +
+    'else printf "[cmux-ssh-here] tmux not found; opening a plain shell\\n"; ' +
+    'exec "$SHELL" -l; fi';
+  const child = pty.spawn(shellPath, ["-lc", start], {
     name: term.term,
     cols: term.cols,
     rows: term.rows,
@@ -50,24 +78,189 @@ function bridge(stream, args, term) {
   child.onData((d) => stream.write(d));
   stream.on("data", (d) => child.write(d.toString()));
   child.onExit(({ exitCode }) => {
-    try {
-      stream.exit(exitCode ?? 0);
-    } catch {}
+    try { stream.exit(exitCode ?? 0); } catch {}
     stream.end();
   });
   return child;
 }
 
-const debug = process.env.CMUX_SSH_DEBUG ? (...a) => console.error("[debug]", ...a) : () => {};
+// exec channel: run a command with RAW pipes (no PTY) so binary protocols
+// (cmux's daemon stdio) stay byte-exact. Faithful to how sshd runs exec.
+function startExec(stream, command, env) {
+  const child = spawn(shellPath, ["-c", command], { cwd: os.homedir(), env: { ...process.env, ...env } });
+  child.stdout.on("data", (d) => stream.write(d));
+  child.stderr.on("data", (d) => stream.stderr.write(d));
+  stream.on("data", (d) => child.stdin.write(d));
+  stream.on("end", () => child.stdin.end());
+  child.on("close", (code) => {
+    try { stream.exit(code ?? 0); } catch {}
+    stream.end();
+  });
+  child.on("error", () => {
+    try { stream.exit(127); } catch {}
+    stream.end();
+  });
+  return child;
+}
+
+// Minimal real-filesystem SFTP server so `scp`/`sftp` work (cmux uploads its
+// daemon via scp, which uses the SFTP subsystem on modern OpenSSH).
+function attachSFTP(accept) {
+  const sftp = accept();
+  // ponytail: client half-closes (EOF) after its last request. A real sshd sends
+  // exit-status 0 then EOF/close for the sftp subsystem; without it scp/sftp
+  // report failure ("Exit status -1") even though the transfer succeeded.
+  // These are ssh2 internals (no public exit() on the SFTP wrapper), but stable.
+  sftp.on("end", () => {
+    try {
+      sftp._protocol.exitStatus(sftp.outgoing.id, 0);
+      sftp._protocol.channelEOF(sftp.outgoing.id);
+    } catch {}
+    sftp.end();
+  });
+  const handles = new Map();
+  let next = 0;
+  const open = (obj) => {
+    const id = next++;
+    handles.set(id, obj);
+    const b = Buffer.alloc(4);
+    b.writeUInt32BE(id, 0);
+    return b;
+  };
+  const get = (h) => (h.length === 4 ? handles.get(h.readUInt32BE(0)) : undefined);
+  const fail = (reqid, err) =>
+    sftp.status(
+      reqid,
+      err?.code === "ENOENT"
+        ? STATUS_CODE.NO_SUCH_FILE
+        : err?.code === "EACCES" || err?.code === "EPERM"
+          ? STATUS_CODE.PERMISSION_DENIED
+          : STATUS_CODE.FAILURE
+    );
+  const toAttrs = (st) => ({
+    mode: st.mode,
+    uid: st.uid,
+    gid: st.gid,
+    size: st.size,
+    atime: Math.floor(st.atimeMs / 1000),
+    mtime: Math.floor(st.mtimeMs / 1000),
+  });
+  const fsFlags = (flags) => {
+    const C = fs.constants;
+    let f = flags & OPEN_MODE.READ && flags & OPEN_MODE.WRITE ? C.O_RDWR : flags & OPEN_MODE.WRITE ? C.O_WRONLY : C.O_RDONLY;
+    if (flags & OPEN_MODE.APPEND) f |= C.O_APPEND;
+    if (flags & OPEN_MODE.CREAT) f |= C.O_CREAT;
+    if (flags & OPEN_MODE.TRUNC) f |= C.O_TRUNC;
+    if (flags & OPEN_MODE.EXCL) f |= C.O_EXCL;
+    return f;
+  };
+
+  sftp.on("REALPATH", (reqid, p) => {
+    let r;
+    try {
+      r = fs.realpathSync(p === "" ? "." : p);
+    } catch {
+      r = p.startsWith("/") ? resolve(p) : join(os.homedir(), p === "." ? "" : p);
+    }
+    sftp.name(reqid, [{ filename: r, longname: r, attrs: {} }]);
+  });
+  sftp.on("OPEN", (reqid, filename, flags, attrs) => {
+    fs.open(filename, fsFlags(flags), attrs?.mode ?? 0o644, (err, fd) => {
+      if (err) return fail(reqid, err);
+      sftp.handle(reqid, open({ fd, path: filename }));
+    });
+  });
+  sftp.on("WRITE", (reqid, handle, offset, data) => {
+    const h = get(handle);
+    if (!h || h.fd == null) return sftp.status(reqid, STATUS_CODE.FAILURE);
+    fs.write(h.fd, data, 0, data.length, offset, (err) => (err ? fail(reqid, err) : sftp.status(reqid, STATUS_CODE.OK)));
+  });
+  sftp.on("READ", (reqid, handle, offset, length) => {
+    const h = get(handle);
+    if (!h || h.fd == null) return sftp.status(reqid, STATUS_CODE.FAILURE);
+    const buf = Buffer.alloc(length);
+    fs.read(h.fd, buf, 0, length, offset, (err, bytes) => {
+      if (err) return fail(reqid, err);
+      if (!bytes) return sftp.status(reqid, STATUS_CODE.EOF);
+      sftp.data(reqid, buf.subarray(0, bytes));
+    });
+  });
+  sftp.on("FSTAT", (reqid, handle) => {
+    const h = get(handle);
+    if (!h || h.fd == null) return sftp.status(reqid, STATUS_CODE.FAILURE);
+    fs.fstat(h.fd, (err, st) => (err ? fail(reqid, err) : sftp.attrs(reqid, toAttrs(st))));
+  });
+  sftp.on("FSETSTAT", (reqid, handle, attrs) => {
+    const h = get(handle);
+    if (!h || h.fd == null) return sftp.status(reqid, STATUS_CODE.FAILURE);
+    if (attrs?.mode != null) {
+      try { fs.fchmodSync(h.fd, attrs.mode); } catch (e) { return fail(reqid, e); }
+    }
+    sftp.status(reqid, STATUS_CODE.OK);
+  });
+  sftp.on("CLOSE", (reqid, handle) => {
+    const h = get(handle);
+    if (h?.fd != null) try { fs.closeSync(h.fd); } catch {}
+    if (h) handles.delete(handle.readUInt32BE(0));
+    sftp.status(reqid, STATUS_CODE.OK);
+  });
+  const onStat = (reqid, p) => fs.stat(p, (err, st) => (err ? fail(reqid, err) : sftp.attrs(reqid, toAttrs(st))));
+  sftp.on("STAT", onStat);
+  sftp.on("LSTAT", (reqid, p) => fs.lstat(p, (err, st) => (err ? fail(reqid, err) : sftp.attrs(reqid, toAttrs(st)))));
+  sftp.on("SETSTAT", (reqid, p, attrs) => {
+    if (attrs?.mode != null) {
+      try { fs.chmodSync(p, attrs.mode); } catch (e) { return fail(reqid, e); }
+    }
+    sftp.status(reqid, STATUS_CODE.OK);
+  });
+  sftp.on("MKDIR", (reqid, p, attrs) =>
+    fs.mkdir(p, { mode: attrs?.mode ?? 0o755 }, (err) => (err ? fail(reqid, err) : sftp.status(reqid, STATUS_CODE.OK)))
+  );
+  sftp.on("RMDIR", (reqid, p) => fs.rmdir(p, (err) => (err ? fail(reqid, err) : sftp.status(reqid, STATUS_CODE.OK))));
+  sftp.on("REMOVE", (reqid, p) => fs.unlink(p, (err) => (err ? fail(reqid, err) : sftp.status(reqid, STATUS_CODE.OK))));
+  sftp.on("RENAME", (reqid, from, to) =>
+    fs.rename(from, to, (err) => (err ? fail(reqid, err) : sftp.status(reqid, STATUS_CODE.OK)))
+  );
+  sftp.on("OPENDIR", (reqid, p) => {
+    try {
+      sftp.handle(reqid, open({ dir: p, entries: fs.readdirSync(p), idx: 0 }));
+    } catch (e) {
+      fail(reqid, e);
+    }
+  });
+  sftp.on("READDIR", (reqid, handle) => {
+    const h = get(handle);
+    if (!h || !h.entries) return sftp.status(reqid, STATUS_CODE.FAILURE);
+    if (h.idx >= h.entries.length) return sftp.status(reqid, STATUS_CODE.EOF);
+    const names = h.entries.slice(h.idx).map((name) => {
+      let st;
+      try { st = fs.lstatSync(join(h.dir, name)); } catch {}
+      return { filename: name, longname: name, attrs: st ? toAttrs(st) : {} };
+    });
+    h.idx = h.entries.length;
+    sftp.name(reqid, names);
+  });
+}
 
-const server = new Server({ hostKeys: [privateKey] }, (client) => {
+const serverCfg = { hostKeys: [privateKey] };
+if (process.env.CMUX_SSH2_DEBUG) serverCfg.debug = (m) => { if (/SFTP|CHANNEL|EOF|CLOSE/.test(m)) console.error("[ssh2]", m); };
+let render = () => {}; // assigned once the server is listening (knows ip/port)
+const server = new Server(serverCfg, (client, info) => {
   client.on("authentication", (ctx) => {
     debug("auth", ctx.method, ctx.username);
     return ctx.username === token ? ctx.accept() : ctx.reject();
   });
+  client.on("ready", () => {
+    const id = nextSid++;
+    sessions.set(id, { ip: info?.ip || "?", since: Date.now() });
+    render();
+    client.on("close", () => {
+      sessions.delete(id);
+      render();
+    });
+  });
   client.on("session", (accept) => {
     const session = accept();
-    // Defaults; overwritten by pty/env requests before shell/exec.
     const term = { term: "xterm-256color", cols: 80, rows: 24, env: {} };
     let child;
 
@@ -84,32 +277,23 @@ const server = new Server({ hostKeys: [privateKey] }, (client) => {
       a?.();
     });
     session.on("window-change", (a, _r, info) => {
-      child?.resize(info.cols, info.rows);
+      child?.resize?.(info.cols, info.rows);
       a?.();
     });
     session.on("shell", (acc) => {
       debug("shell");
-      // ponytail: route the interactive shell through tmux so sessions persist
-      // and are shared across LAN connections; show the session list on connect.
-      // Falls back to a plain login shell when tmux is absent.
-      const start =
-        'if command -v tmux >/dev/null 2>&1; then ' +
-        'exec tmux new-session -A -s main \\; choose-tree -Zs; ' +
-        'else printf "[cmux-ssh-here] tmux not found; opening a plain shell (no server-side sessions)\\n"; ' +
-        'exec "$SHELL" -l; fi';
-      child = bridge(acc(), ["-lc", start], term);
+      child = startShell(acc(), term);
     });
     session.on("exec", (acc, _r, info) => {
       debug("exec", info.command);
-      // ponytail: login shell (-lc) so PATH includes things like homebrew tmux;
-      // cmux runs remote commands (tmux probes, tmux -CC) over this channel.
-      child = bridge(acc(), ["-lc", info.command], term);
+      child = startExec(acc(), info.command, term.env);
     });
-    session.on("subsystem", (_acc, rej, info) => {
-      debug("subsystem", info.name);
-      // ponytail: scp/sftp not supported; reject so the client fails fast
-      rej?.();
+    session.on("sftp", (acc) => {
+      debug("sftp");
+      attachSFTP(acc);
     });
+    // ponytail: no 'subsystem' handler — ssh2 auto-rejects non-sftp subsystems,
+    // and a handler here also intercepts the sftp request and kills the channel.
   });
 });
 
@@ -126,14 +310,54 @@ server.listen(PORT, "0.0.0.0", function () {
     process.exit(1);
   }
   const port = this.address().port;
-  const params = new URLSearchParams({
-    host: ip,
-    port: String(port),
-    user: token,
-    "host-key-policy": "accept-new",
-    title: os.hostname(),
-  });
-  console.log(`\n  Connect to this machine via cmux over the LAN`);
-  console.log(`  (shell as ${os.userInfo().username}; Ctrl-C here to stop):\n`);
-  console.log(`  https://cmux.com/deeplink/ssh?${params}\n`);
+  const user = os.userInfo().username;
+  const buildLink = () => {
+    const params = new URLSearchParams({
+      host: ip,
+      port: String(port),
+      user: token,
+      "host-key-policy": "accept-new",
+      title: os.hostname(),
+    });
+    return `https://cmux.com/deeplink/ssh?${params}`;
+  };
+
+  // ponytail: in debug mode skip the screen-clearing UI so logs stay readable;
+  // just print the link whenever it rotates.
+  const liveUI = !process.env.CMUX_SSH_DEBUG;
+  const ago = (since) => `${Math.floor((Date.now() - since) / 1000)}s`;
+
+  render = () => {
+    if (!liveUI) return;
+    const lines = [
+      "",
+      `  cmux-ssh-here — shell as ${user} over the LAN`,
+      "",
+      `  Open in cmux (regenerates in ${remaining}s):`,
+      `  ${buildLink()}`,
+      "",
+    ];
+    if (sessions.size) {
+      lines.push(`  Connected sessions (${sessions.size}):`);
+      for (const s of sessions.values()) lines.push(`    • ${s.ip}  connected ${ago(s.since)} ago`);
+    } else {
+      lines.push("  No active sessions yet.");
+    }
+    lines.push("", "  Ctrl-C to stop.", "");
+    // Clear screen + home, then redraw.
+    process.stdout.write(`\x1b[2J\x1b[3J\x1b[H${lines.join("\n")}\n`);
+  };
+
+  if (liveUI) render();
+  else console.log(`\n  Open in cmux (regenerates in ${remaining}s):\n  ${buildLink()}\n`);
+
+  // Tick once a second: count down, regenerate on expiry, refresh the UI.
+  setInterval(() => {
+    remaining--;
+    if (remaining <= 0) {
+      regenerateToken();
+      if (!liveUI) console.log(`\n  [link regenerated]\n  ${buildLink()}\n`);
+    }
+    render();
+  }, 1000);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cmux-ssh-here",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "Spin up a token-auth SSH server and print a cmux deep link to connect over LAN",
   "type": "module",
   "bin": {
@@ -18,6 +18,14 @@
     "remote"
   ],
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/viktor-silakov/cmux-ssh-here.git"
+  },
+  "homepage": "https://github.com/viktor-silakov/cmux-ssh-here#readme",
+  "bugs": {
+    "url": "https://github.com/viktor-silakov/cmux-ssh-here/issues"
+  },
   "engines": {
     "node": ">=18"
   },