@w3cj/fwd 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,100 @@
-# Temporary Holding Version
+# fwd
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A dead simple zero dependency SSH port forward manager. No extra background processes, uses OpenSSH ControlMaster.
+
+```bash
+fwd add 5173            # localhost:5173 -> vm:5173
+fwd add 8080:3000       # localhost:8080 -> vm:3000
+fwd add 3000 --reverse  # vm:3000 -> localhost:3000
+fwd ls
+fwd rm 5173
+```
+
+One OpenSSH [ControlMaster](https://man.openbsd.org/ssh_config#ControlMaster) process holds the connection, and `fwd` asks it to add or cancel forwards with `ssh -O forward` / `ssh -O cancel`. OpenSSH does all the networking; `fwd` remembers what you asked for, so it can show status and restore forwards after a reboot or VM restart.
+
+## Install
+
+Requires Node 20+ and OpenSSH on macOS or Linux. Windows isn't supported, because its OpenSSH doesn't support ControlMaster. There are no runtime dependencies.
+
+```bash
+npm install -g @w3cj/fwd
+```
+
+## Setup
+
+Point `fwd` at an alias in `~/.ssh/config`, so keys, user and IP all come from your normal SSH setup:
+
+```
+Host vm
+  HostName 192.168.64.7
+  User cj
+```
+
+```bash
+fwd config set host vm
+```
+
+Check that it works with `ssh vm` first. Passphrase and host-key prompts still work when `fwd` starts the connection.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `fwd add <local>[:<remote>] [--reverse] [--to <addr>]` | Forward `localhost:<local>` to `<remote>` on the host (same port by default). Starts the master if needed. `--to` connects to another address as seen from the host, e.g. `fwd add 5432 --to db`. |
+| `fwd rm <port> [--reverse]` / `fwd rm --all` | Cancel a forward and forget it. `<port>` is the listening port. |
+| `fwd ls [--json] [--all-hosts]` | List saved forwards with their status: `active`, `down` (master not running) or `broken` (master up, port not listening). `--all-hosts` lists every host. |
+| `fwd up` | Start the master and re-apply every saved forward. Use it after a reboot, VM restart or network drop. |
+| `fwd down` | Stop the master. Saved forwards are kept for `fwd up`. |
+| `fwd status` | Show the host, control socket, master PID and log file. |
+| `fwd watch [--interval <s>] [--all-hosts]` | Stay in the foreground and reconnect and restore forwards whenever the connection drops. |
+| `fwd completion bash\|zsh\|fish` | Print a shell completion script. |
+| `fwd config set\|get\|unset host` | Manage the default host. |
+
+Every command accepts `--host <host>`, so several hosts can be used side by side, with one master each. `fwd <command> --help` shows details.
+
+## Reverse forwards
+
+`--reverse` makes the host listen and forward back to this machine (`ssh -R`). That's useful when something in the VM needs to reach a service on your laptop:
+
+```bash
+fwd add 3000 --reverse                 # vm:3000 -> localhost:3000
+fwd add 3000:8000 --reverse            # vm:8000 -> localhost:3000
+fwd add 5432 --reverse --to 10.0.0.5   # vm:5432 -> 10.0.0.5:5432, reached from this machine
+fwd rm 8000 --reverse
+```
+
+The spec is always `<local>:<remote>`; `--reverse` only changes which side listens. The host listens on its loopback interface unless its sshd sets `GatewayPorts`. `fwd ls` can't check reverse forwards individually, so it shows them as `active` whenever the master is up.
+
+## Staying connected
+
+`fwd watch` checks every 5 seconds (`--interval` changes that). If the master has died because the VM restarted, slept or changed network, `watch` reconnects and restores your saved forwards. If a local forward stopped listening, it's re-applied. Forwards you add or remove while it runs are picked up. Stop it with Ctrl+C; the master keeps running.
+
+## Shell completion
+
+Completion covers commands, options, saved hosts for `--host`, and saved ports for `fwd rm`:
+
+```bash
+fwd completion bash > ~/.local/share/bash-completion/completions/fwd
+fwd completion zsh > "${fpath[1]}/_fwd"      # or: source <(fwd completion zsh) in ~/.zshrc
+fwd completion fish > ~/.config/fish/completions/fwd.fish
+```
+
+## Notes
+
+- Local ports below 1024 are rejected. Use a higher local port, e.g. `fwd add 8080:80`.
+- `active` means the local end of the forward is listening. It doesn't check that anything is running on the remote port. `ls` checks by briefly connecting to each local port, which ssh passes through, so the remote service sees a short connection.
+- `LocalForward` and `RemoteForward` lines in your ssh config are ignored for `fwd`'s connection; `fwd` only opens the forwards you add.
+- Connecting gives up after 10 seconds if the host doesn't respond.
+- Commands that change state take a lock in the config directory, so running several `fwd` commands at once is safe.
+- If the connection drops (the VM sleeps, the network changes), the master exits within about 45 seconds. The next `fwd add` or `fwd up` reconnects and restores forwards.
+- Cancelling a forward stops new connections; connections that are already open stay open until they close.
+- State, control sockets and the master's log live in `$XDG_CONFIG_HOME/fwd` (default `~/.config/fwd`).
+
+## Development
+
+```bash
+npm test            # unit tests, plus end-to-end tests against a throwaway local sshd
+npm run typecheck   # tsc over the JSDoc types; there's no build step
+```
+
+The end-to-end tests start `sshd` as your user on a random localhost port. They're skipped if `sshd` isn't installed, or if `FWD_SKIP_INTEGRATION=1` is set.

package/bin/fwd.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { resolveHost } from '../src/commands/common.js';
+import { findCommand, optionsFor } from '../src/commands/index.js';
+import { FwdError } from '../src/errors.js';
+import { commandHelp, mainHelp, version } from '../src/help.js';
+import { withLock } from '../src/lock.js';
+import { loadState } from '../src/state.js';
+
+/** @typedef {import('../src/commands/common.js').Command} Command */
+
+/**
+ * @param {Command} cmd
+ * @param {string[]} argv
+ */
+function parse(cmd, argv) {
+  const options = Object.fromEntries(
+    Object.entries(optionsFor(cmd)).map(([name, { type, short }]) => [name, short ? { type, short } : { type }]),
+  );
+  try {
+    return parseArgs({ args: argv, options, allowPositionals: true, strict: true });
+  } catch (err) {
+    // Drop Node's advice about "--" that follows unknown-option errors.
+    const message = /** @type {Error} */ (err).message.replace(/\. To specify a positional.*$/s, '.');
+    throw new FwdError(`${message}\nRun \`fwd ${cmd.name} --help\` for usage.`);
+  }
+}
+
+/**
+ * @param {string[]} argv
+ * @returns {Promise<number>}
+ */
+async function main([name, ...rest]) {
+  if (name === undefined || name === '-h' || name === '--help') {
+    console.log(mainHelp());
+    return 0;
+  }
+  if (name === '-v' || name === '--version') {
+    console.log(version);
+    return 0;
+  }
+
+  const cmd = findCommand(name);
+  const { values: flags, positionals: args } = parse(cmd, rest);
+  if (flags.help) {
+    console.log(commandHelp(cmd));
+    return 0;
+  }
+  const [min, max] = cmd.args;
+  if (args.length > max) {
+    throw new FwdError(`Unexpected argument "${args[max]}". Run \`fwd ${name} --help\` for usage.`);
+  }
+  if (args.length < min) {
+    throw new FwdError(`Missing argument. Usage: ${cmd.usage.join(' | ')}`);
+  }
+
+  const run = async () => {
+    const state = await loadState();
+    const host = cmd.host ? '' : resolveHost(state, flags.host);
+    return (await cmd.run({ args, flags, state, host })) ?? 0;
+  };
+  return cmd.readonly ? run() : withLock(run);
+}
+
+try {
+  process.exitCode = await main(process.argv.slice(2));
+} catch (err) {
+  console.error(err instanceof FwdError ? `fwd: ${err.message}` : err);
+  process.exitCode = 1;
+}

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@w3cj/fwd",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "A dead simple zero dependency SSH port forward manager.",
+  "type": "module",
+  "bin": {
+    "fwd": "./bin/fwd.js"
+  },
+  "files": [
+    "README.md",
+    "bin",
+    "src"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "typecheck": "tsc",
+    "prepublishOnly": "npm run typecheck && npm test"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "os": [
+    "!win32"
+  ],
+  "keywords": [
+    "ssh",
+    "port-forward",
+    "tunnel",
+    "controlmaster",
+    "cli"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.43",
+    "typescript": "^7.0.2"
+  }
+}

package/src/commands/add.js

@@ -0,0 +1,56 @@
+import { FwdError } from '../errors.js';
+import { describe, keyOf, listenPort, parseSpec, sameTarget } from '../spec.js';
+import { findForward, getForwards, putForward, saveState } from '../state.js';
+import { applyForward, bringUp, printResults } from './common.js';
+
+/** @type {import('./common.js').Command} */
+export default {
+  name: 'add',
+  summary: 'Forward a port to (or, with --reverse, from) the host',
+  usage: ['fwd add <local>[:<remote>] [--reverse] [--to <addr>] [--host <host>]'],
+  description: [
+    'Forwards localhost:<local> to <remote> on the host (defaults to the same port).',
+    'With --reverse, the host listens on <remote> and forwards to localhost:<local>.',
+    'Starts the SSH master if it is not running and restores saved forwards.',
+    '',
+    'Examples:',
+    '  fwd add 5173                  localhost:5173 -> host:5173',
+    '  fwd add 8080:3000             localhost:8080 -> host:3000',
+    '  fwd add 5432 --to db          localhost:5432 -> db:5432, as reached from the host',
+    '  fwd add 3000 --reverse        host:3000 -> localhost:3000',
+    '  fwd add 3000:8000 --reverse   host:8000 -> localhost:3000',
+  ].join('\n'),
+  args: [1, 1],
+  options: {
+    reverse: { type: 'boolean', help: 'Listen on the host and forward to this machine (ssh -R)' },
+    to: { type: 'string', value: 'addr', help: 'Address to connect to from the other side (default 127.0.0.1)' },
+  },
+
+  async run({ args, flags, state, host }) {
+    const fwd = parseSpec(args[0], {
+      to: typeof flags.to === 'string' ? flags.to : undefined,
+      reverse: Boolean(flags.reverse),
+    });
+
+    // Local listeners share this machine, so they clash across hosts; remote
+    // listeners only clash on the same host.
+    const key = keyOf(fwd);
+    for (const savedHost of fwd.direction === 'local' ? Object.keys(state.hosts) : [host]) {
+      const other = findForward(state, savedHost, key);
+      if (other && !(savedHost === host && sameTarget(other, fwd))) {
+        const rm = `fwd rm ${listenPort(other)}${other.direction === 'remote' ? ' --reverse' : ''} --host ${savedHost}`;
+        throw new FwdError(`That port is already used by ${describe(other, savedHost)}. Run \`${rm}\` first.`);
+      }
+    }
+
+    const saved = findForward(state, host, key);
+    const others = getForwards(state, host).filter((f) => f !== saved);
+    const { started, results } = await bringUp(host, others);
+    printResults(host, results.filter((r) => r.result !== 'active'));
+
+    const result = await applyForward(host, fwd, { ours: !started && saved !== undefined });
+    putForward(state, host, { ...fwd, addedAt: saved?.addedAt ?? new Date().toISOString() });
+    await saveState(state);
+    console.log(`${result === 'active' ? 'Already forwarding' : 'Forwarding'} ${describe(fwd, host)}`);
+  },
+};

package/src/commands/common.js

@@ -0,0 +1,173 @@
+import { FwdError } from '../errors.js';
+import { isPortFree, isPortListening } from '../ports.js';
+import { describe } from '../spec.js';
+import { addForward, checkMaster, removeSocket, startMaster } from '../ssh.js';
+
+/** @typedef {import('../spec.js').Forward} Forward */
+/** @typedef {import('../state.js').State} State */
+
+/**
+ * @typedef {object} Option
+ * @property {'string' | 'boolean'} type
+ * @property {string} help
+ * @property {string} [short]
+ * @property {string} [value] Placeholder shown in help, e.g. "addr" for --to <addr>.
+ * @property {Completion} [complete] How shells complete the option's value.
+ */
+
+/**
+ * What shell completion offers for an argument: fixed words, command names,
+ * saved hosts, or the saved listen ports for the host.
+ * @typedef {string[] | 'commands' | 'hosts' | 'ports'} Completion
+ */
+
+/** @typedef {(message: string) => void} Log */
+
+/**
+ * @typedef {object} Context
+ * @property {string[]} args
+ * @property {Record<string, string | boolean | undefined>} flags
+ * @property {State} state
+ * @property {string} host The resolved host; empty unless `Command.host` is unset.
+ */
+
+/**
+ * @typedef {object} Command
+ * @property {string} name
+ * @property {string} summary
+ * @property {string[]} usage
+ * @property {string} [description]
+ * @property {[min: number, max: number]} args Allowed number of positional arguments.
+ * @property {'none' | 'self'} [host] By default the host is resolved for the command.
+ *   'self': --host is accepted but the command resolves it. 'none': no host at all.
+ * @property {true} [readonly] Doesn't change state or the master, so skips the lock.
+ * @property {true} [hidden] Left out of help and shell completion.
+ * @property {Completion[]} [positionals] Shell completion for each positional argument.
+ * @property {Record<string, Option>} [options]
+ * @property {(ctx: Context) => Promise<number | void>} run
+ */
+
+/** @param {string} host */
+export function validateHost(host) {
+  if (!host || host.startsWith('-') || /\s/.test(host)) {
+    throw new FwdError(`Invalid host "${host}".`);
+  }
+}
+
+/**
+ * @param {State} state
+ * @param {string | boolean | undefined} flag
+ */
+export function resolveHost(state, flag) {
+  const host = typeof flag === 'string' ? flag : state.defaultHost;
+  if (!host) {
+    throw new FwdError('No host set. Run `fwd config set host <host>` or pass --host <host>.');
+  }
+  validateHost(host);
+  return host;
+}
+
+/** @param {number | null | undefined} pid */
+export function pidSuffix(pid) {
+  return pid ? ` (pid ${pid})` : '';
+}
+
+/**
+ * Make sure a master is running for host, replacing a stale socket if the
+ * previous one died uncleanly. `started` means no forwards are active yet.
+ * @param {string} host
+ * @returns {Promise<{ started: boolean, pid: number | null }>}
+ */
+async function ensureMaster(host) {
+  const status = await checkMaster(host);
+  if (status.alive) return { started: false, pid: status.pid };
+
+  await removeSocket(host);
+  await startMaster(host);
+
+  // -f returns once the master is set up, but give it a moment just in case.
+  for (let i = 0; i < 10; i++) {
+    const check = await checkMaster(host);
+    if (check.alive) return { started: true, pid: check.pid };
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  throw new FwdError(`Started ssh for ${host}, but its control socket isn't responding.`);
+}
+
+/**
+ * Send a forward to the master unless it's already active. `ours` says
+ * whether the master may already have it: then a listener on a local port is
+ * taken to be the forward; otherwise it belongs to another process.
+ *
+ * Remote ports can't be probed from here, but the master accepts a repeated
+ * request for a forward it already has, so they're always (re)sent.
+ * @param {string} host
+ * @param {Forward} fwd
+ * @param {{ ours: boolean }} options
+ * @returns {Promise<'active' | 'added'>}
+ */
+export async function applyForward(host, fwd, { ours }) {
+  if (fwd.direction === 'local') {
+    if (ours && (await isPortListening(fwd.local))) return 'active';
+    if (!(await isPortFree(fwd.local))) {
+      throw new FwdError(`Local port ${fwd.local} is already in use by another process.`);
+    }
+  }
+  await addForward(host, fwd);
+  return ours && fwd.direction === 'remote' ? 'active' : 'added';
+}
+
+/**
+ * 'down' if the master isn't running, 'broken' if a local forward's port isn't
+ * listening, else 'active'. Remote forwards can't be checked individually.
+ * @param {Forward} fwd
+ * @param {boolean} masterAlive
+ * @returns {Promise<'active' | 'down' | 'broken'>}
+ */
+export async function forwardStatus(fwd, masterAlive) {
+  if (!masterAlive) return 'down';
+  if (fwd.direction === 'remote') return 'active';
+  return (await isPortListening(fwd.local)) ? 'active' : 'broken';
+}
+
+/**
+ * @typedef {object} ForwardResult
+ * @property {Forward} fwd
+ * @property {'active' | 'added'} [result]
+ * @property {Error} [error]
+ */
+
+/**
+ * Start the master if needed, then apply each forward, collecting failures
+ * instead of stopping at the first.
+ * @param {string} host
+ * @param {Forward[]} forwards
+ * @param {Log} [log]
+ */
+export async function bringUp(host, forwards, log = console.log) {
+  const master = await ensureMaster(host);
+  if (master.started) log(`Started SSH master for ${host}${pidSuffix(master.pid)}`);
+
+  /** @type {ForwardResult[]} */
+  const results = [];
+  for (const fwd of forwards) {
+    try {
+      results.push({ fwd, result: await applyForward(host, fwd, { ours: !master.started }) });
+    } catch (err) {
+      results.push({ fwd, error: /** @type {Error} */ (err) });
+    }
+  }
+  return { ...master, results };
+}
+
+/**
+ * @param {string} host
+ * @param {ForwardResult[]} results
+ * @param {Log} [log]
+ */
+export function printResults(host, results, log = console.log) {
+  for (const { fwd, result, error } of results) {
+    const label = (error ? 'failed' : result ?? '').padEnd(6);
+    log(`  ${label}  ${describe(fwd, host)}${error ? `: ${error.message}` : ''}`);
+  }
+}

package/src/commands/complete.js

@@ -0,0 +1,29 @@
+import { listenPort } from '../spec.js';
+import { getForwards } from '../state.js';
+
+// Called by the completion scripts for values that depend on saved state.
+/** @type {import('./common.js').Command} */
+export default {
+  name: '__complete',
+  summary: 'Print completion candidates',
+  usage: ['fwd __complete hosts|ports [--host <host>]'],
+  args: [1, 1],
+  host: 'self',
+  readonly: true,
+  hidden: true,
+
+  async run({ args: [what], flags, state }) {
+    /** @type {(string | number)[]} */
+    let values = [];
+    if (what === 'hosts') {
+      values = [state.defaultHost ?? '', ...Object.keys(state.hosts)];
+    } else if (what === 'ports') {
+      const host = typeof flags.host === 'string' ? flags.host : state.defaultHost;
+      values = host ? getForwards(state, host).map(listenPort) : [];
+    }
+    // Write strings, not console.log(number): numbers get ANSI colours when
+    // FORCE_COLOR is set, which would end up in the completions.
+    const lines = [...new Set(values.map(String))].filter(Boolean);
+    if (lines.length) process.stdout.write(`${lines.join('\n')}\n`);
+  },
+};