cmux-ssh-here 0.5.0 → 0.7.0

package/README.md

@@ -1,46 +1,78 @@
 # 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 scannable QR code, 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.
+- 📱 **Scan to connect** — a QR code in the terminal opens the link on a phone or tablet.
+- 🔑 **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.
+- 🎯 **One-time mode** — `--once` locks the link to the first device that connects and rejects everyone else.
+- 👀 **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
 
+- `npx cmux-ssh-here --once` — single-use link: locks to the first device that connects, rejects any other.
 - `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

@@ -18,6 +18,15 @@ import { spawn } from "node:child_process";
 import { chmodSync } from "node:fs";
 import { createRequire } from "node:module";
 import { dirname, join, resolve } from "node:path";
+import qrcodeTerminal from "qrcode-terminal";
+
+// 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.
@@ -40,6 +49,13 @@ const regenerateToken = () => {
 };
 regenerateToken();
 
+// --once: single-use link. After the first client connects, lock to its IP and
+// stop rotating — new machines are rejected, but that client's several
+// connections (cmux opens ControlMaster + daemon + probes) keep working.
+const ONCE = process.argv.includes("--once");
+let consumed = false;
+let lockedIp = null;
+
 // Active authenticated connections, shown live in the server terminal.
 const sessions = new Map();
 let nextSid = 0;
@@ -50,7 +66,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 = () =>
@@ -248,13 +266,19 @@ 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();
+    // Correct token, plus (in --once after consumption) only the locked-in IP.
+    const ok = ctx.username === token && (!consumed || info?.ip === lockedIp);
+    return ok ? 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() });
+    if (ONCE && !consumed) {
+      consumed = true;
+      lockedIp = info?.ip || "?";
+    }
     client.on("close", () => sessions.delete(id));
   });
   client.on("session", (accept) => {
@@ -333,6 +357,16 @@ server.listen(PORT, "0.0.0.0", function () {
     return `[${"█".repeat(filled)}${"░".repeat(W - filled)}]`;
   };
 
+  // ASCII QR of the current link — scan with a phone/tablet to open in cmux.
+  const qrFor = (text) => {
+    let out = "";
+    qrcodeTerminal.generate(text, { small: true }, (q) => (out = q));
+    return out
+      .split("\n")
+      .map((l) => "  " + l)
+      .join("\n");
+  };
+
   // Collapse cmux's several SSH connections from one machine into one row per IP.
   const sessionRows = () => {
     const byIp = new Map();
@@ -346,19 +380,25 @@ server.listen(PORT, "0.0.0.0", function () {
     );
   };
 
+  const mode = ONCE ? " (one-time link)" : "";
+
   render = () => {
     if (!liveUI) return;
     const rem = remainingSec();
+    const link = buildLink();
     const lines = [
       "",
-      `  cmux-ssh-here — shell as ${user} over the LAN`,
+      `  cmux-ssh-here — shell as ${user} over the LAN${mode}`,
       "",
-      "  Open in cmux:",
-      `  ${buildLink()}`,
+      "  Open in cmux (or scan to open on a phone/tablet):",
+      `  ${link}`,
       "",
-      `  Link valid  ${bar(rem)} ${rem}s`,
+      qrFor(link),
       "",
     ];
+    if (consumed) lines.push(`  🔒 One-time link used — locked to ${lockedIp}.`);
+    else lines.push(`  Link valid  ${bar(rem)} ${rem}s`);
+    lines.push("");
     const rows = sessionRows();
     if (rows.length) lines.push(`  Connected (${rows.length}):`, ...rows);
     else lines.push("  No active sessions yet.");
@@ -370,9 +410,10 @@ server.listen(PORT, "0.0.0.0", function () {
   if (liveUI) render();
   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.
+  // Refresh every 5s: regenerate the link when it expires (unless a one-time
+  // link has already been consumed — then it's frozen), then redraw.
   setInterval(() => {
-    if (remainingSec() <= 0) {
+    if (!consumed && remainingSec() <= 0) {
       regenerateToken();
       if (!liveUI) console.log(`\n  [link regenerated]\n  ${buildLink()}\n`);
     }

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "cmux-ssh-here",
-  "version": "0.5.0",
+  "version": "0.7.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"
@@ -31,6 +34,7 @@
   },
   "dependencies": {
     "node-pty": "^1.0.0",
+    "qrcode-terminal": "^0.12.0",
     "ssh2": "^1.16.0"
   }
 }