cmux-ssh-here 0.2.0 → 0.3.0

package/README.md

@@ -23,6 +23,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,3 +40,4 @@ 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).

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.
@@ -21,7 +29,9 @@ if (process.platform !== "win32") {
 }
 const { default: pty } = await import("node-pty");
 
-const token = randomBytes(9).toString("base64url"); // secret carried in user=<token>
+// 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 { privateKey } = generateKeyPairSync("rsa", {
   // ponytail: rsa PEM parses cleanly in ssh2 (ed25519 PKCS8 is hit-or-miss)
   modulusLength: 2048,
@@ -30,15 +40,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,
@@ -48,52 +67,212 @@ 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;
+}
+
+// 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;
 }
 
-const server = new Server({ hostKeys: [privateKey] }, (client) => {
-  client.on("authentication", (ctx) =>
-    ctx.username === token ? ctx.accept() : ctx.reject()
+// 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 serverCfg = { hostKeys: [privateKey] };
+if (process.env.CMUX_SSH2_DEBUG) serverCfg.debug = (m) => { if (/SFTP|CHANNEL|EOF|CLOSE/.test(m)) console.error("[ssh2]", m); };
+const server = new Server(serverCfg, (client) => {
+  client.on("authentication", (ctx) => {
+    debug("auth", ctx.method, ctx.username);
+    return ctx.username === token ? ctx.accept() : ctx.reject();
+  });
   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;
 
     session.on("pty", (a, _r, info) => {
+      debug("pty", info.term, info.cols, info.rows);
       term.term = info.term || term.term;
       term.cols = info.cols || term.cols;
       term.rows = info.rows || term.rows;
       a?.();
     });
     session.on("env", (a, _r, info) => {
+      debug("env", info.key, "=", info.val);
       term.env[info.key] = info.val;
       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) => {
-      // 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);
+      debug("shell");
+      child = startShell(acc(), term);
     });
     session.on("exec", (acc, _r, info) => {
-      child = bridge(acc(), ["-c", info.command], term);
+      debug("exec", info.command);
+      child = startExec(acc(), info.command, term.env);
+    });
+    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.
   });
 });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cmux-ssh-here",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Spin up a token-auth SSH server and print a cmux deep link to connect over LAN",
   "type": "module",
   "bin": {