cmux-ssh-here 0.4.1 → 0.6.0

package/README.md

@@ -1,46 +1,75 @@
 # cmux-ssh-here
 
-One command spins up an ephemeral, token-authenticated SSH server on this machine and prints a [cmux SSH deep link](https://cmux.com/en/docs/ssh). Open the link in [cmux](https://cmux.com) and you instantly land in a shell as the current user over the local network — no `sshd` setup, no keys, no passwords.
+**Share a shell on this machine in one command — no SSH setup, no keys, no passwords.**
+
+[![npm](https://img.shields.io/npm/v/cmux-ssh-here.svg)](https://www.npmjs.com/package/cmux-ssh-here)
+[![CI](https://github.com/viktor-silakov/cmux-ssh-here/actions/workflows/ci.yml/badge.svg)](https://github.com/viktor-silakov/cmux-ssh-here/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/cmux-ssh-here.svg)](./LICENSE)
+
+`cmux-ssh-here` spins up a throwaway, token-authenticated SSH server and prints a [cmux](https://cmux.com) deep link. Send the link to any device on your LAN, open it in cmux, and you're instantly in a terminal on this machine. When you're done, hit `Ctrl-C` — the server, token, and host key vanish.
 
 ```bash
 npx cmux-ssh-here
 ```
 
-Output:
+That's it. No `sshd` to configure, no `~/.ssh/authorized_keys` to edit, no firewall dance.
 
-```
-  Connect to this machine via cmux over the LAN
-  (shell as you; Ctrl-C here to stop):
+---
 
-  https://cmux.com/deeplink/ssh?host=192.168.1.42&port=52968&user=wudUKicRFRw3&host-key-policy=accept-new&title=your-mac
-```
+The terminal turns into a live dashboard — the link, a countdown bar for its lifetime, and who's connected:
+
+![cmux-ssh-here dashboard](https://raw.githubusercontent.com/viktor-silakov/cmux-ssh-here/main/assets/dashboard.png)
+
+Open the link and cmux connects on its own — one click, straight into the shell:
+
+![Open in cmux](https://raw.githubusercontent.com/viktor-silakov/cmux-ssh-here/main/assets/open-in-cmux.png)
+
+## Why you'll like it
 
-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.
+- ⚡ **Zero setup** — one `npx` command, no SSH server administration.
+- 🔑 **No credentials to share** — auth is a one-time token baked into the link.
+- ⏳ **Self-expiring** — the link rotates every 3 minutes; leaked links go stale on their own. Live sessions stay connected.
+- 👀 **Live dashboard** — see the current link, a countdown bar, and every connected client at a glance.
+- 🧩 **Real SSH** — full PTY shell, `scp`/`sftp`, and the exec channel cmux needs to bootstrap remote workspaces.
+- 🪟 **Persistent sessions** — when `tmux` is present, sessions survive disconnects and are shared across connections.
 
-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.
+## Quick start
+
+```bash
+# on the machine you want to reach
+npx cmux-ssh-here
+```
+
+Then open the printed `https://cmux.com/deeplink/ssh?…` link in cmux on any device on the same network.
 
 ## How it works
 
 - Its own SSH server (`ssh2`) with an ephemeral host key and token — both live only while the process runs.
-- The token is passed in the deep link's `user=`; the server only accepts the correct token.
+- The token rides in the deep link's `user=`; the server accepts only that token, and rotates it every 3 minutes.
 - 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.
+- Full PTY shell via `node-pty`, a raw-pipe exec channel, and a filesystem-backed SFTP server — together they let `cmux ssh` upload and run its remote helper (a shell-only server isn't enough).
+- With `tmux` available, the interactive shell runs inside it: sessions persist, are shared across connections, and the session list (`choose-tree`) is shown on connect.
+
+## Compatibility
 
-## Requirements
+| Host running `npx cmux-ssh-here` | Supported |
+| --- | --- |
+| macOS | ✅ |
+| Linux | ✅ |
+| Windows | ❌ — needs a POSIX shell, and cmux's remote daemon has no Windows build |
 
-- Node 18+.
-- [cmux](https://cmux.com) on the device you open the link from.
-- macOS or Linux on the host sharing the shell. Windows host is not supported.
-- `tmux` (optional) for persistent, shared server-side sessions.
+The device you open the link from just needs [cmux](https://cmux.com) installed. Node 18+ is required on the host. `tmux` is optional (for persistent, shared sessions).
 
 ## Security
 
-⚠️ **The token in the link is a bearer secret that grants a shell as your user.** Trusted local network only. Don't publish the link or send it over untrusted channels. Close the terminal and the token and host key are gone.
+⚠️ **The token in the link is a bearer secret that grants a shell as your user.** Use it on a trusted local network only. Don't publish the link or send it over untrusted channels. Close the terminal and the token and host key are gone.
 
 ## Options
 
 - `PORT=2222 npx cmux-ssh-here` — fixed port (random free port by default).
 - `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).
+
+## License
+
+MIT

package/bin.js

@@ -19,6 +19,14 @@ import { chmodSync } from "node:fs";
 import { createRequire } from "node:module";
 import { dirname, join, resolve } from "node:path";
 
+// ponytail: the host side needs a POSIX shell + scp/exec semantics, and cmux's
+// own remote daemon only ships linux/darwin/freebsd builds — so a Windows host
+// can't serve `cmux ssh`. Fail fast with a clear message instead of crashing later.
+if (process.platform === "win32") {
+  console.error("cmux-ssh-here must run on a macOS or Linux host (POSIX shell required). Windows is not supported.");
+  process.exit(1);
+}
+
 // ponytail: node-pty's prebuilt spawn-helper sometimes unpacks without +x
 // (packaging bug) -> "posix_spawnp failed". Fix it before importing.
 if (process.platform !== "win32") {
@@ -33,10 +41,10 @@ const { default: pty } = await import("node-pty");
 // and an ssh client treats a leading-dash username as a flag. Hex is URL/ssh-safe.
 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
+let expiry; // epoch ms when the current token expires
 const regenerateToken = () => {
   token = randomBytes(12).toString("hex");
-  remaining = TTL_SECONDS;
+  expiry = Date.now() + TTL_SECONDS * 1000;
 };
 regenerateToken();
 
@@ -50,7 +58,9 @@ const { privateKey } = generateKeyPairSync("rsa", {
   publicKeyEncoding: { type: "spki", format: "pem" },
 });
 
-const shellPath = process.env.SHELL || "/bin/zsh";
+// ponytail: $SHELL is set on real logins; the fallback only matters in bare
+// envs — bash on Linux, zsh on macOS.
+const shellPath = process.env.SHELL || (process.platform === "darwin" ? "/bin/zsh" : "/bin/bash");
 const debug = process.env.CMUX_SSH_DEBUG ? (...a) => console.error("[debug]", ...a) : () => {};
 
 const lanIP = () =>
@@ -251,13 +261,11 @@ const server = new Server(serverCfg, (client, info) => {
     return ctx.username === token ? ctx.accept() : ctx.reject();
   });
   client.on("ready", () => {
+    // ponytail: just track the connection; the 5s timer redraws — no per-event
+    // repaint (that was the screen-churn that broke copying).
     const id = nextSid++;
     sessions.set(id, { ip: info?.ip || "?", since: Date.now() });
-    render();
-    client.on("close", () => {
-      sessions.delete(id);
-      render();
-    });
+    client.on("close", () => sessions.delete(id));
   });
   client.on("session", (accept) => {
     const session = accept();
@@ -324,16 +332,18 @@ server.listen(PORT, "0.0.0.0", function () {
 
   // ponytail: in debug mode skip the dashboard so logs stay readable.
   const liveUI = !process.env.CMUX_SSH_DEBUG;
+  const REFRESH_MS = 5000; // ponytail: 5s cadence — long enough to select & copy the link
   const ago = (since) => `${Math.floor((Date.now() - since) / 1000)}s`;
+  const remainingSec = () => Math.max(0, Math.ceil((expiry - Date.now()) / 1000));
 
-  // ponytail: never clear the whole screen (that wipes the user's selection and
-  // makes the link impossible to copy). Repaint the static block only on real
-  // events (link rotation, session add/remove); the per-second countdown rewrites
-  // just its own line via "\r", leaving the link above untouched and selectable.
-  const countdownLine = () => `  ↻ Link regenerates in ${remaining}s — copy it above. Ctrl-C to stop.`;
+  // Decreasing progress bar for the link's remaining lifetime.
+  const bar = (rem) => {
+    const W = 28;
+    const filled = Math.round((rem / TTL_SECONDS) * W);
+    return `[${"█".repeat(filled)}${"░".repeat(W - filled)}]`;
+  };
 
-  // Collapse the raw SSH connections (cmux opens several from one machine:
-  // ControlMaster, the daemon channel, short-lived probes) into one row per IP.
+  // Collapse cmux's several SSH connections from one machine into one row per IP.
   const sessionRows = () => {
     const byIp = new Map();
     for (const s of sessions.values()) {
@@ -346,7 +356,9 @@ server.listen(PORT, "0.0.0.0", function () {
     );
   };
 
-  const block = () => {
+  render = () => {
+    if (!liveUI) return;
+    const rem = remainingSec();
     const lines = [
       "",
       `  cmux-ssh-here — shell as ${user} over the LAN`,
@@ -354,33 +366,26 @@ server.listen(PORT, "0.0.0.0", function () {
       "  Open in cmux:",
       `  ${buildLink()}`,
       "",
+      `  Link valid  ${bar(rem)} ${rem}s`,
+      "",
     ];
     const rows = sessionRows();
     if (rows.length) lines.push(`  Connected (${rows.length}):`, ...rows);
     else lines.push("  No active sessions yet.");
-    lines.push("");
-    return lines.join("\n");
-  };
-
-  // Repaint the block, then leave the cursor parked on the countdown line.
-  render = () => {
-    if (!liveUI) return;
-    process.stdout.write(`\n${block()}\n${countdownLine()}`);
+    lines.push("", "  Updates every 5s · Ctrl-C to stop.", "");
+    // Home + clear-to-end (not full \x1b[2J): redraw in the same spot every 5s.
+    process.stdout.write(`\x1b[H\x1b[J${lines.join("\n")}\n`);
   };
 
   if (liveUI) render();
-  else console.log(`\n  Open in cmux (regenerates in ${remaining}s):\n  ${buildLink()}\n`);
+  else console.log(`\n  Open in cmux (regenerates in ${remainingSec()}s):\n  ${buildLink()}\n`);
 
+  // Refresh every 5s: regenerate the link when it expires, then redraw.
   setInterval(() => {
-    remaining--;
-    if (remaining <= 0) {
+    if (remainingSec() <= 0) {
       regenerateToken();
-      // Link changed: repaint the whole block (rare — once per TTL).
-      if (liveUI) render();
-      else console.log(`\n  [link regenerated]\n  ${buildLink()}\n`);
-      return;
+      if (!liveUI) console.log(`\n  [link regenerated]\n  ${buildLink()}\n`);
     }
-    // Common case: rewrite only the countdown line in place — no screen churn.
-    if (liveUI) process.stdout.write(`\r\x1b[2K${countdownLine()}`);
-  }, 1000);
+    render();
+  }, REFRESH_MS);
 });

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "cmux-ssh-here",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "Spin up a token-auth SSH server and print a cmux deep link to connect over LAN",
   "type": "module",
   "bin": {
     "cmux-ssh-here": "bin.js"
   },
+  "scripts": {
+    "test": "node --test"
+  },
   "files": [
     "bin.js",
     "README.md"