@mason-data/cli 0.7.0 → 0.9.0

package/dist/src/cli/tunnel.js

@@ -0,0 +1,200 @@
+/**
+ * THE TUNNEL OF `mason share`: a client of a free service that forwards raw TCP, run as a child process and pointed at the
+ * share's socket (src/cli/share-run.ts). What crosses is TLS between the BI tool and Mason, so a service that only
+ * forwards reads nothing; a hostile one could sit in the handshake (docs/POSTGRES-API.md says so). Which one is `--via`:
+ * Pinggy over the `ssh` every machine has, or `bore`, a binary to install. The address is the client's OUTPUT, a format
+ * Mason does not own, so reading it is held three ways: a time limit (`timeoutMs`), a shape it must have
+ * (`tunnelAddress`), and a probe of the address it gave (`probeShare`): the share's own certificate must answer there.
+ *
+ * `ssh` NEVER PROMPTS, because nothing stands behind a prompt (an agent, a pipe, a terminal that went on to something
+ * else): it runs in a session of its own with no terminal (`detached`), stdin a pipe this process holds. The first
+ * connection's host key is taken and kept in `.mason/share-known-hosts` (`accept-new`: a key that CHANGES later fails, said
+ * by the file's name), never the developer's own `~/.ssh`; their keys, agent and config are left out (`-F`, no
+ * `PubkeyAuthentication`), so nothing can ask for a passphrase or a touch and nothing of theirs is offered to a
+ * service. Pinggy's free route asks for a password that is empty (its docs: "just press enter"), so a password
+ * question is answered by `true`, which prints nothing (`SSH_ASKPASS`, forced): that is the one answer any question gets.
+ *
+ * A PINGGY TOKEN NEVER REACHES A COMMAND LINE: `ps` shows every process's arguments to every user, and the service takes the
+ * token as the ssh user. So the user is written in a config file of ours, 0600 in `.mason/`, named by `-F`, and
+ * removed as soon as the tunnel is up (ssh has read it), or when it fails. `MASON_PINGGY_TOKEN` is read from the
+ * shell or `.env`, never a flag, and is masked in whatever of the client's output a failure repeats.
+ */
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as net from "node:net";
+import * as path from "node:path";
+import * as tls from "node:tls";
+import { stripVTControlCharacters } from "node:util";
+export const TUNNELS = ["pinggy", "bore"];
+/** A free tunnel's limit where its client does not say one: Pinggy's, measured in docs/DESIGN.md "mason share". */
+const FREE_MINUTES = 60;
+/** How much of the client's output is kept to read an address from, and how many lines a failure repeats. */
+const KEPT_BYTES = 64 * 1024;
+const SAID_LINES = 3;
+const STOP_GRACE_MS = 2_000;
+/** How long the address is given to answer: long enough for a relay on another continent, short enough to wait for. */
+export const PROBE_MS = 8_000;
+/** The ssh user and host: a free tunnel, or a token's (`<token>+tcp@`, Pinggy's own form). */
+const pinggyTarget = (token) => token === null ? { user: "tcp", host: "free.pinggy.io" } : { user: `${token}+tcp`, host: "pro.pinggy.io" };
+/** A token as it may stand in a config file: anything else would be a line of it. */
+export const TOKEN_RE = /^[A-Za-z0-9._~-]+$/;
+const quoted = (file) => `"${file.replaceAll("%", "%%")}"`;
+/** The ssh config of a tunnel (the header says why each line): every option here, so the command line carries none. */
+export function pinggyConfig(o) {
+    const t = pinggyTarget(o.token);
+    return `Host mason-share
+  HostName ${t.host}
+  Port 443
+  User ${t.user}
+  StrictHostKeyChecking accept-new
+  UserKnownHostsFile ${quoted(o.knownHosts)}
+  GlobalKnownHostsFile none
+  PubkeyAuthentication no
+  IdentityAgent none
+  NumberOfPasswordPrompts 1
+  ExitOnForwardFailure yes
+  ServerAliveInterval 30
+  ServerAliveCountMax 3
+  ConnectTimeout 15
+  ConnectionAttempts 1
+  RequestTTY no
+  LogLevel ERROR
+`;
+}
+export function tunnelPlan(via, o) {
+    if (via === "bore") {
+        return { via, bin: "bore", args: ["local", String(o.port), "--local-host", "127.0.0.1", "--to", "bore.pub"], env: process.env, install: "cargo install bore-cli, or brew install bore-cli",
+            reconnects: false, free: false, token: null, file: null };
+    }
+    const file = path.join(o.home, `share-tunnel-${process.pid}.ssh`);
+    return { via, bin: "ssh", args: ["-F", file, "-T", `-R0:127.0.0.1:${o.port}`, "mason-share"],
+        env: { ...process.env, SSH_ASKPASS: "true", SSH_ASKPASS_REQUIRE: "force", DISPLAY: process.env.DISPLAY ?? ":0" }, install: "the OpenSSH client (it comes with macOS and most Linux; apt install openssh-client)",
+        reconnects: o.token !== null, free: o.token === null, token: o.token,
+        file: { path: file, text: pinggyConfig({ token: o.token, knownHosts: path.join(o.home, "share-known-hosts") }) } };
+}
+/** A `share-tunnel-<pid>.ssh` a `kill -9` left behind (it may hold a token): removed unless its process is alive. */
+export function sweepTunnelFiles(home, isAlive) {
+    for (const name of fs.readdirSync(home)) {
+        const m = /^share-tunnel-(\d+)\.ssh$/.exec(name);
+        if (m !== null && !isAlive(Number(m[1])))
+            fs.rmSync(path.join(home, name), { force: true });
+    }
+}
+const PINGGY_ADDRESS = /\btcp:\/\/([a-z0-9][a-z0-9.-]*):(\d{1,5})(?![\d.])/i;
+const BORE_ADDRESS = /\blistening at ([a-z0-9][a-z0-9.-]*):(\d{1,5})(?![\d.])/i;
+/** The public address in what a client printed so far, or null: a shape, and a real port. */
+export function tunnelAddress(via, output) {
+    const m = (via === "pinggy" ? PINGGY_ADDRESS : BORE_ADDRESS).exec(stripVTControlCharacters(output));
+    if (m === null)
+        return null;
+    const port = Number(m[2]);
+    return port >= 1 && port <= 65_535 ? { host: m[1].toLowerCase(), port } : null;
+}
+/** When a free tunnel ends: what its client says, else its known limit; null when it has none. */
+export function tunnelEnds(plan, output, now) {
+    if (!plan.free)
+        return null;
+    const said = /expires?\s+in\s+(\d+)\s*min/i.exec(stripVTControlCharacters(output));
+    return new Date(now + (said === null ? FREE_MINUTES : Number(said[1])) * 60_000).toISOString();
+}
+/** The last lines a client printed, on one line, its token masked: what a failure repeats. */
+export function lastLines(output, token) {
+    const lines = stripVTControlCharacters(output).split(/[\r\n]+/).map((l) => l.trim()).filter((l) => l !== "");
+    const text = lines.slice(-SAID_LINES).join(" / ");
+    return token === null ? text : text.replaceAll(token, "<token>");
+}
+/** Starts a tunnel client and reads its address: the tunnel, or why not. `onPid`: as soon as there is a process. */
+export function startTunnel(plan, o) {
+    return new Promise((resolve) => {
+        const forget = () => { if (plan.file !== null)
+            fs.rmSync(plan.file.path, { force: true }); };
+        if (plan.file !== null)
+            fs.writeFileSync(plan.file.path, plan.file.text, { mode: 0o600 });
+        // detached: a session of its own, so no terminal to prompt on, and Ctrl-C reaches this process alone, which ends it.
+        // stdin a pipe held open: the end of stdin would end the session the service prints on
+        const child = spawn(plan.bin, plan.args, { stdio: ["pipe", "pipe", "pipe"], env: plan.env, detached: true });
+        let output = "", settled = false, finished = () => undefined;
+        const ended = new Promise((r) => { finished = r; });
+        const stop = () => {
+            if (child.exitCode !== null || child.signalCode !== null)
+                return;
+            child.kill("SIGTERM");
+            setTimeout(() => { if (child.exitCode === null && child.signalCode === null)
+                child.kill("SIGKILL"); }, STOP_GRACE_MS).unref();
+        };
+        const settle = (v) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            forget();
+            resolve(v);
+        };
+        const timer = setTimeout(() => {
+            stop();
+            const said = lastLines(output, plan.token);
+            settle({ message: `the tunnel gave no address in ${Math.round(o.timeoutMs / 1000)} s`, code: "failed", why: said === "" ? `${plan.bin} printed nothing` : `${plan.bin} printed: ${said}`,
+                fix: `its output is the service's, and may have changed: this Mason cannot read it${plan.via === "pinggy" ? ", and --via bore is another tunnel" : ""}. Nothing was left open` });
+        }, o.timeoutMs);
+        const read = (b) => {
+            output = (output + b.toString("utf8")).slice(-KEPT_BYTES);
+            if (settled)
+                return;
+            const address = tunnelAddress(plan.via, output);
+            if (address === null)
+                return;
+            settle({ ...address, endsAt: tunnelEnds(plan, output, Date.now()), pid: child.pid, ended, stop });
+        };
+        child.stdout.on("data", read);
+        child.stderr.on("data", read);
+        // the end of stdin would be a command's end, and EPIPE from a client gone is that end, said by its exit
+        child.stdin.on("error", () => undefined);
+        child.on("spawn", () => o.onPid?.(child.pid));
+        child.on("error", (e) => {
+            if (e.code !== "ENOENT") {
+                settle({ message: `${plan.bin} could not be started: ${e.message}`, code: "failed" });
+                return;
+            }
+            settle({ message: `${plan.bin} is not on this machine's PATH, and --via ${plan.via} needs it`, code: "not_found", fix: `install ${plan.install}${plan.via === "pinggy" ? ", or use --via bore" : ", or use --via pinggy, which needs only ssh"}`,
+                next: [[`mason share --via ${plan.via === "pinggy" ? "bore" : "pinggy"}`, "the other tunnel"]] });
+        });
+        const over = (code, signal) => {
+            const said = lastLines(output, plan.token);
+            const how = signal !== null ? `it was ended (${signal})` : `${plan.bin} exited ${code}`;
+            finished(said === "" ? how : `${how}: ${said}`);
+            settle({ message: "the tunnel ended before it gave an address", code: "failed", why: said === "" ? how : `${how}: ${said}`,
+                fix: plan.via === "pinggy" && /REMOTE HOST IDENTIFICATION|Host key verification failed/i.test(said) ? "the service's host key changed: remove .mason/share-known-hosts if you expected that" : "is this machine online? Port 443 outbound is all it needs" });
+        };
+        // 'close' waits for its pipes, which a grandchild can hold for ever: 'exit' ends the wait
+        let code = null, signal = null;
+        child.on("exit", (c, s) => { code = c; signal = s; setTimeout(() => over(c, s), 200).unref(); });
+        child.on("close", () => over(code, signal));
+    });
+}
+/**
+ * WHETHER THE ADDRESS IS THIS SHARE: an SSLRequest and a handshake through the tunnel, its certificate read, no login.
+ * `other`: something else answered there, a wrong address or something in the way. `unknown`: nothing answered in time
+ * (a firewall may keep this machine from a port the BI tool can reach): no verdict, and said so.
+ */
+export function probeShare(address, fingerprint, timeoutMs = PROBE_MS) {
+    return new Promise((resolve) => {
+        const socket = net.connect(address.port, address.host);
+        let secure = null;
+        // the TLS socket owns the connection once it wraps it: destroying the one under it segfaults Node (measured, 24.18)
+        const answer = (v) => { clearTimeout(timer); (secure ?? socket).destroy(); resolve(v); };
+        const timer = setTimeout(() => answer("unknown"), timeoutMs);
+        socket.once("error", () => answer("unknown"));
+        socket.once("close", () => answer("unknown"));
+        socket.once("connect", () => socket.write(Buffer.from([0, 0, 0, 8, 0x04, 0xd2, 0x16, 0x2f])));
+        socket.once("data", (b) => {
+            if (b[0] !== 0x53 /* S */) {
+                answer("other");
+                return;
+            }
+            socket.removeAllListeners("close");
+            secure = tls.connect({ socket, rejectUnauthorized: false, ALPNProtocols: ["postgresql"] });
+            secure.once("error", () => answer("unknown"));
+            secure.once("secureConnect", () => answer(secure?.getPeerX509Certificate()?.fingerprint256 === fingerprint ? "same" : "other"));
+        });
+    });
+}

package/dist/src/cli/ui-ssh.js

@@ -0,0 +1,460 @@
+/**
+ * `mason ui --ssh <user@server>`: A SERVER'S WEB PAGE IN THE DEVELOPER'S BROWSER, WITH NOTHING PUBLIC (docs/WEB-UI.md "On
+ * a server"). Two processes, one on each end of the machine's own `ssh` (never a library: `~/.ssh/config`, keys, SSO,
+ * hardware tokens and a cloud's private route are then the person's, and Mason knows none of them):
+ *
+ *   browser ── 127.0.0.1:<free port> ── mason ui --ssh ══ ssh, its stdin and stdout ══ mason ui --bridge ── the run's page
+ *              on the laptop                                                           on the server, or in its container
+ *
+ * THE BRIDGE RUNS WHERE THE RUN RUNS, AND THE TUNNEL IS ITS STDIO, NOT `ssh -L`. The page listens on loopback alone, by
+ * construction (src/cli/run-server.ts `listenOnLoopback`), and a container's loopback is not its host's: `-L` from the
+ * host reaches a port Docker publishes, and Docker publishes to the container's own network address, so `-L` would need
+ * the page off loopback. A process inside the container reaches it as it is, so ONE route serves a host and a container,
+ * and needs no `AllowTcpForwarding` on the server and no port published or even known.
+ *
+ * ONE SSH CONNECTION CARRIES EVERY BROWSER CONNECTION (`FrameLink`): a page opens six at once, and a connection per one
+ * would mean a touch of a hardware token per one. After the hello line the two ends speak frames: 1 byte type, 4 bytes
+ * connection, 4 bytes length, then that many bytes.
+ *
+ * THE TOKEN STAYS ON THE SERVER: the bridge reads it from the run's config, as every command does, opens the tunnel
+ * with it (`POST /api/ui/tunnel`, its connection IS the tunnel) and sends the laptop a ticket (src/cli/security.ts). The
+ * hello line is what crosses: nothing secret is on a command line, in the laptop's output or in a log.
+ *
+ * THE BRIDGE ENDS A BOUND AFTER ITS STDIN DOES, WHATEVER ITS MAIN THREAD IS DOING: stdin is read on a worker thread
+ * (src/cli/bridge-stdin.ts), whose own event loop hears the end and ends the process `BRIDGE_EXIT_MS` later if it is
+ * still there, so a blocked main loop cannot keep the run's tunnel open once the laptop's ssh is gone.
+ *
+ * WHAT `ssh` PRINTS IS NOT OURS: stdout is scanned for the hello line, as a server's shell may print before it; stderr
+ * is passed on as it comes, because a person may be asked for a passphrase or a touch there.
+ */
+import { spawn } from "node:child_process";
+import * as net from "node:net";
+import { fileURLToPath } from "node:url";
+import { Worker } from "node:worker_threads";
+import { runnable } from "../lib/runnable.js";
+import { errorJson, nextJson } from "./command.js";
+import { holdRun, RunUnreachable } from "./control.js";
+import { whereIs } from "./state.js";
+import { lastLines } from "./tunnel.js";
+import { version } from "./version.js";
+/** What the laptop looks for on the bridge's stdout: this, a space, then one line of JSON. */
+export const HELLO = "MASON-UI-BRIDGE";
+/** The frames' version: two ends of another say so, whatever their Mason versions. */
+export const BRIDGE_PROTOCOL = 1;
+const OPEN = 1, DATA = 2, CLOSE = 3;
+const HEADER = 9;
+/** No end sends more than a socket's read at once: a length past this is not a frame, it is a broken stream. */
+const MAX_FRAME = 1024 * 1024;
+const STOP_GRACE_MS = 2_000;
+/** How long after ssh exits the end is read: a Ctrl-C reaches ssh and this process together. */
+const SETTLE_MS = 200;
+/** Why a `--ssh` target cannot be given to ssh, or null: a target opening with `-` would be read as ssh's own option. */
+export function targetProblem(target) {
+    return /^[A-Za-z0-9_][A-Za-z0-9._@%+:[\]-]*$/.test(target) ? null : `${JSON.stringify(target)} is not user@server or a Host of your ssh config`;
+}
+/** The server-side command: `mason`, as `--mason` says to run it there. */
+export const bridgeCommand = (mason, localPort) => `${mason} ui --bridge --local-port ${localPort}`;
+/**
+ * THE `ssh` LINE. No secret in it: `ps` shows it. `BatchMode` where nobody can answer a prompt, so ssh fails rather
+ * than waits. A shared connection (`ControlPath`) is left out: a master that persists would be an ssh process left
+ * behind by Ctrl-C. Forwards from the person's config are cleared: a tunnel of ours must not fail on theirs.
+ */
+export function sshArgs(target, remote, interactive) {
+    const options = ["ConnectTimeout=15", "ServerAliveInterval=15", "ServerAliveCountMax=3", "ControlMaster=no", "ControlPath=none", "ClearAllForwardings=yes", "ForwardAgent=no", "ForwardX11=no",
+        ...(interactive ? [] : ["BatchMode=yes"])];
+    return ["-T", "-e", "none", ...options.flatMap((o) => ["-o", o]), "--", target, remote];
+}
+function frame(type, id, payload = Buffer.alloc(0)) {
+    const head = Buffer.alloc(HEADER);
+    head.writeUInt8(type, 0);
+    head.writeUInt32BE(id, 1);
+    head.writeUInt32BE(payload.length, 5);
+    return Buffer.concat([head, payload]);
+}
+/**
+ * ONE END OF THE STREAM: many sockets over one pipe each way. `connect` is the bridge's, which dials the page when the
+ * laptop opens a connection; the laptop has none and calls `open`. Backpressure is the pipe's: a socket that cannot take
+ * more pauses the pipe, and a pipe that cannot take more pauses the sockets, so memory stays bounded and a browser's
+ * slow tab can hold the others back a moment, which a page of small JSON answers does not notice.
+ */
+export class FrameLink {
+    sockets = new Map();
+    input;
+    output;
+    connect;
+    broken;
+    kept = Buffer.alloc(0);
+    next = 1;
+    waiting = false;
+    constructor(o) {
+        this.input = o.input;
+        this.output = o.output;
+        this.connect = o.connect ?? null;
+        this.broken = o.broken;
+    }
+    /** A connection from this end: the laptop's, one per browser connection. */
+    open(socket) {
+        const id = this.next++;
+        this.send(frame(OPEN, id));
+        this.attach(id, socket);
+    }
+    /** Bytes from the pipe. */
+    read(chunk) {
+        this.kept = this.kept.length === 0 ? chunk : Buffer.concat([this.kept, chunk]);
+        while (this.kept.length >= HEADER) {
+            const type = this.kept.readUInt8(0), id = this.kept.readUInt32BE(1), length = this.kept.readUInt32BE(5);
+            if (length > MAX_FRAME || type < OPEN || type > CLOSE) {
+                this.broken(`a frame of type ${type} and ${length} bytes: this is not the bridge's stream`);
+                return;
+            }
+            if (this.kept.length < HEADER + length)
+                return;
+            this.frameIn(type, id, this.kept.subarray(HEADER, HEADER + length));
+            this.kept = this.kept.subarray(HEADER + length);
+        }
+    }
+    /** Every connection dropped: the tunnel is gone. */
+    end() { for (const s of [...this.sockets.values()])
+        s.destroy(); this.sockets.clear(); }
+    frameIn(type, id, payload) {
+        if (type === OPEN) {
+            if (this.connect !== null)
+                this.attach(id, this.connect());
+            return;
+        }
+        const socket = this.sockets.get(id);
+        // the other end closed it while this frame crossed
+        if (socket === undefined)
+            return;
+        if (type === CLOSE) {
+            this.sockets.delete(id);
+            socket.destroySoon();
+            return;
+        }
+        if (socket.write(Buffer.from(payload)))
+            return;
+        this.input.pause();
+        const go = () => { socket.off("drain", go); socket.off("close", go); this.input.resume(); };
+        socket.once("drain", go);
+        socket.once("close", go);
+    }
+    attach(id, socket) {
+        this.sockets.set(id, socket);
+        socket.on("data", (b) => { this.send(frame(DATA, id, b)); });
+        // a browser or the page dropping a connection is an ordinary end, said to the other side by the close below
+        socket.on("error", () => undefined);
+        socket.on("close", () => { if (this.sockets.delete(id))
+            this.send(frame(CLOSE, id)); });
+    }
+    send(b) {
+        if (this.output.write(b) || this.waiting)
+            return;
+        this.waiting = true;
+        for (const s of this.sockets.values())
+            s.pause();
+        this.output.once("drain", () => { this.waiting = false; for (const s of this.sockets.values())
+            s.resume(); });
+    }
+}
+// ------------------------------------------------------------------ the server's end: mason ui --bridge
+/**
+ * How long the bridge may take to end by itself once its stdin has ended, before its watchdog ends it (SIGKILL), and
+ * how long its main thread may be silent with stdin's window full before it is taken for stuck. An ordinary end takes
+ * milliseconds: the tunnel's hold closed, its sockets destroyed, the output flushed or found gone.
+ */
+export const BRIDGE_EXIT_MS = 5_000;
+/**
+ * What the stdin thread hands the main thread before it is acknowledged: the most of the laptop's bytes the bridge
+ * holds between the pipe and FrameLink, whatever its main thread does. Past it the pipe fills and the laptop waits.
+ */
+export const STDIN_WINDOW_BYTES = 1024 * 1024;
+/** How often the main thread tells the stdin thread it is alive: well inside BRIDGE_EXIT_MS. */
+const BEAT_MS = 1_000;
+/**
+ * The bridge's stdin, as its thread forwards it (src/cli/bridge-stdin.ts), by credit: each chunk is acknowledged once
+ * FrameLink has read it and is not paused, so the thread's window is what has not reached a page's socket yet. Started
+ * first, so the watchdog bounds the whole bridge, the run's lookup included; what arrives before `attach` is kept for
+ * it, unacknowledged, so that too is inside the window.
+ */
+class StdinByWorker {
+    worker;
+    kept = [];
+    end = null;
+    read = null;
+    ended = null;
+    paused = false;
+    /** Bytes read while paused: acknowledged on resume. */
+    unacked = 0;
+    broken = false;
+    constructor() {
+        // execArgv [] as the other workers here: the main thread's flags (a test's --import) are not the reader's
+        this.worker = new Worker(runnable(fileURLToPath(new URL("./bridge-stdin.ts", import.meta.url))), { workerData: { exitMs: BRIDGE_EXIT_MS, windowBytes: STDIN_WINDOW_BYTES }, execArgv: [], argv: [] });
+        // the process ends when the bridge does: the thread never holds it, and dies with it
+        this.worker.unref();
+        this.worker.on("message", (m) => {
+            if ("data" in m) {
+                if (this.broken)
+                    return;
+                const b = Buffer.from(m.data.buffer, m.data.byteOffset, m.data.byteLength);
+                if (this.read === null)
+                    this.kept.push(b);
+                else
+                    this.consume(b);
+                return;
+            }
+            if ("dropped" in m) {
+                // the thread took this one for stuck and read on past what it handed over: the stream has a hole, never read on
+                this.broken = true;
+                this.over(1, `its main thread was stuck for ${BRIDGE_EXIT_MS / 1000} s with ${m.dropped} bytes unread, and what the laptop sent since was dropped: the tunnel is broken, run mason ui --ssh again`);
+                return;
+            }
+            this.over(m.failed ? 1 : 0, m.failed ? m.end : null);
+        });
+        // a stdin nobody reads is a bridge that cannot work: said, and the bridge ends, never left without its end
+        this.worker.on("error", (e) => { this.over(1, `its stdin cannot be read: ${e.message}`); });
+        this.worker.on("exit", (code) => { this.over(1, `its stdin's reader stopped (exit ${code})`); });
+        // a main thread that is waiting, not stuck, says so; one that is stuck cannot
+        setInterval(() => { this.worker.postMessage({ beat: true }); }, BEAT_MS).unref();
+    }
+    /** From now on, bytes to `read` and the end to `ended`: what came before first. */
+    attach(read, ended) {
+        this.read = read;
+        for (const b of this.kept)
+            this.consume(b);
+        this.kept = [];
+        this.ended = ended;
+        if (this.end !== null)
+            this.say(this.end);
+    }
+    /** FrameLink's backpressure: a page's socket is full, so what is read now is acknowledged only when it drains. */
+    pause() { this.paused = true; }
+    resume() {
+        this.paused = false;
+        if (this.unacked > 0) {
+            this.worker.postMessage({ ack: this.unacked });
+            this.unacked = 0;
+        }
+    }
+    consume(b) {
+        this.read?.(b);
+        if (this.paused)
+            this.unacked += b.length;
+        else
+            this.worker.postMessage({ ack: b.length });
+    }
+    over(code, why) {
+        if (this.end !== null)
+            return;
+        this.end = { code, why };
+        if (this.ended !== null)
+            this.say(this.end);
+    }
+    say(e) {
+        if (e.why !== null)
+            process.stderr.write(`mason ui --bridge: ${e.why}\n`);
+        this.ended?.(e.code);
+    }
+}
+/**
+ * `mason ui --bridge`: the hello line, then the frames, until the laptop's end goes (stdin closes), or the run ends the
+ * tunnel. A failure is the hello, in the shape the laptop says; what it prints on stderr reaches the laptop through ssh.
+ */
+export async function bridge(localPort) {
+    const stdin = new StdinByWorker();
+    const hello = (h) => { process.stdout.write(`${HELLO} ${JSON.stringify(h)}\n`); };
+    const refuse = (f) => { hello({ protocol: BRIDGE_PROTOCOL, version: version(), error: errorJson(f), next: nextJson(f.next) }); return 1; };
+    const w = await whereIs();
+    if (w.state !== "up")
+        return refuse({ ...w.problem, message: w.problem.problem });
+    const { run } = w;
+    let held;
+    try {
+        held = await holdRun(run, "/api/ui/tunnel", { port: localPort });
+    }
+    catch (e) {
+        if (e instanceof RunUnreachable)
+            return refuse({ message: e.message, code: "unreachable", next: [["mason logs", "the run's log"]] });
+        throw e;
+    }
+    if (!("first" in held)) {
+        if (held.status === 404) {
+            return refuse({ message: `Mason for ${run.name} serves no web page through a tunnel`, code: "refused", why: "the run was started by a Mason from before mason ui --ssh",
+                fix: "restart it on this Mason's version: mason serve's page needs no other setting" });
+        }
+        const f = held.body.failure;
+        return refuse(f ?? { message: String(held.body.error ?? `HTTP ${held.status}`), code: "failed" });
+    }
+    const { first, ended, close } = held;
+    hello({ protocol: BRIDGE_PROTOCOL, version: version(), project: run.name, ticket: String(first.ticket) });
+    const page = new URL(run.control.url);
+    return await new Promise((resolve) => {
+        let over = false;
+        const done = (code) => { over = true; close(); link.end(); resolve(code); };
+        const link = new FrameLink({ input: stdin, output: process.stdout, connect: () => net.connect(Number(page.port), "127.0.0.1"),
+            broken: (why) => { process.stderr.write(`mason ui --bridge: ${why}\n`); done(1); } });
+        stdin.attach((b) => { link.read(b); }, (code) => { done(code); });
+        // the laptop's end gone with bytes still to write: the same end as stdin's, which says it
+        process.stdout.on("error", () => { done(0); });
+        // settles on this end's own close too, which is no news
+        void ended.then(() => { if (over)
+            return; process.stderr.write(`mason ui --bridge: Mason for ${run.name} ended the tunnel: it stopped or restarted\n`); done(1); });
+    });
+}
+/** What a Mason that lacks `--bridge` prints: its parser's refusal of the flag, or its usage. */
+const OLDER_MASON = /unknown option\b.*--bridge|^usage: mason ui\b/im;
+/** The report for an ssh that exited before the bridge said hello, by what its exit means. */
+export function exitFailure(o) {
+    const { target, mason, code, signal, said, stderr } = o;
+    const how = signal !== null ? `ssh was ended (${signal})` : `ssh exited ${code}`;
+    const why = said === "" ? how : `${how}: ${said}`;
+    const here = [`ssh ${target} true`, "whether ssh reaches it on its own"];
+    // 127 is a shell's "command not found", and ssh hands on the remote command's exit
+    if (code === 127) {
+        return { message: `${JSON.stringify(mason)} is not a command on ${target}`, code: "not_found", why,
+            fix: `--mason says how to run Mason there: --mason "docker exec -i <container> mason" for a container (docker ps names it), or --mason "/path/to/mason" where a shell ssh opens lacks it on its PATH`, next: [here] };
+    }
+    // 2 alone proves nothing (a shell exits 2 when its cd fails): an older Mason says so in its own words, read from the
+    // whole of stderr, as what it prints after that line pushes it out of `said`
+    if (code === 2 && OLDER_MASON.test(stderr)) {
+        return { message: `the Mason on ${target} does not know mason ui --bridge`, code: "refused", why, fix: "it is older than mason ui --ssh: upgrade the server's Mason to this one's version", next: [["mason --version", "this machine's"]] };
+    }
+    if (code === 255 && /host key|host identification/i.test(stderr)) {
+        return { message: `ssh does not trust the host key of ${target}`, code: "failed", why,
+            fix: `run ssh ${target} on its own and check the key before you accept it: mason ui --ssh never answers that question for you`, next: [here] };
+    }
+    if (code === 255) {
+        return { message: `ssh could not reach ${target}`, code: "failed", why,
+            fix: `run ssh ${target} on its own: this uses your ~/.ssh/config, as that does. A firewall rule that names your old IP address is the common cause`, next: [here] };
+    }
+    return { message: `the bridge on ${target} ended before it answered`, code: "failed", why, fix: `run ${bridgeCommand(mason, 1)} there to see why`, next: [here] };
+}
+/** A hello's refusal, in the words of who reads it: on this machine, about that one. */
+function refusal(h, target) {
+    const lost = h.error.code === "no_project", stopped = h.error.code === "not_running";
+    const fix = lost ? `ssh lands in a folder with no Mason project. --mason says where it is: --mason "cd <MASON_DATA> && mason", or --mason "docker exec -i <container> mason"`
+        : stopped ? `start mason serve on ${target}: its service or container` : h.error.fix;
+    // these two say mason init and mason start, words for a person at that machine: run here they would do the wrong thing
+    const next = lost || stopped ? [] : h.next.map((n) => n.what === undefined ? [n.command] : [n.command, n.what]);
+    return { message: `on ${target}: ${h.error.message}`, code: h.error.code, ...(h.error.why ? { why: h.error.why } : {}), ...(fix ? { fix } : {}), next };
+}
+/** Starts ssh and the bridge, with a free loopback port before them: the tunnel, or why not. */
+export function openSshTunnel(o) {
+    return new Promise((resolve) => {
+        let link = null;
+        // no link yet: nothing was handed out that names this port, so nothing that connects is ours
+        const local = net.createServer((socket) => { if (link === null)
+            socket.destroy();
+        else
+            link.open(socket); });
+        local.once("error", (e) => { resolve({ message: `no local port could be opened: ${e.message}`, code: "failed" }); });
+        local.listen(0, "127.0.0.1", () => {
+            const port = local.address().port;
+            const child = spawn("ssh", sshArgs(o.target, bridgeCommand(o.mason, port), o.interactive), { stdio: ["pipe", "pipe", "pipe"] });
+            let output = Buffer.alloc(0), said = "", settled = false, stopping = false, finish = () => undefined;
+            const ended = new Promise((r) => { finish = r; });
+            let gone = () => undefined;
+            const exited = new Promise((r) => { gone = r; });
+            const stop = () => {
+                stopping = true;
+                link?.end();
+                if (child.exitCode === null && child.signalCode === null) {
+                    child.kill("SIGTERM");
+                    setTimeout(() => { if (child.exitCode === null && child.signalCode === null)
+                        child.kill("SIGKILL"); }, STOP_GRACE_MS).unref();
+                }
+                return Promise.all([exited, new Promise((r) => { local.close(() => r()); })]).then(() => undefined);
+            };
+            const settle = (v) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                resolve(v);
+            };
+            // said only once ssh is gone: the command exits on this answer, and the timer that kills an ssh ignoring SIGTERM dies with it
+            const fail = (f) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                void stop().then(() => { resolve(f); });
+            };
+            const timer = setTimeout(() => {
+                const last = lastLines(said, null);
+                fail({ message: `no answer from ${o.target} in ${Math.round(o.timeoutMs / 1000)} s`, code: "failed", ...(last === "" ? {} : { why: `ssh printed: ${last}` }),
+                    fix: `run ssh ${o.target} on its own to see where it waits; --timeout gives it longer`, next: [[`ssh ${o.target} true`, "whether ssh reaches it on its own"]] });
+            }, o.timeoutMs);
+            // Ctrl-C before an answer: ssh goes too, a process signalled alone included
+            void o.stopped.then(() => { fail({ message: "stopped before the server answered", code: "failed" }); });
+            const helloIn = (h) => {
+                if ("error" in h) {
+                    fail(refusal(h, o.target));
+                    return;
+                }
+                if (h.protocol !== BRIDGE_PROTOCOL) {
+                    fail({ message: `the Mason on ${o.target} (${h.version}) and this one (${version()}) speak different bridges`, code: "refused", why: `its bridge is version ${h.protocol}, this one's ${BRIDGE_PROTOCOL}`,
+                        fix: "run the same Mason version on both ends", next: [["mason --version", "this machine's"]] });
+                    return;
+                }
+                // what a later drop repeats is what ssh says from here on, never the login's banner
+                said = "";
+                settle({ url: `http://127.0.0.1:${port}/?ticket=${encodeURIComponent(h.ticket)}`, port, project: h.project, serverVersion: h.version, ended, stop });
+            };
+            child.stdout.on("data", (b) => {
+                if (link !== null) {
+                    link.read(b);
+                    return;
+                }
+                output = Buffer.concat([output, b]);
+                const at = output.indexOf(`${HELLO} `);
+                const eol = at < 0 ? -1 : output.indexOf("\n", at);
+                if (eol < 0) {
+                    if (output.length > MAX_FRAME)
+                        output = output.subarray(-MAX_FRAME);
+                    return;
+                }
+                const rest = output.subarray(eol + 1);
+                let h;
+                try {
+                    h = JSON.parse(output.subarray(at + HELLO.length + 1, eol).toString("utf8"));
+                }
+                catch (e) {
+                    fail({ message: `the bridge on ${o.target} said something that is not its hello`, code: "failed", why: e.message, fix: "run the same Mason version on both ends" });
+                    return;
+                }
+                link = new FrameLink({ input: child.stdout, output: child.stdin, broken: (why) => { void stop().then(() => { finish(why); }); } });
+                helloIn(h);
+                if (rest.length > 0)
+                    link.read(rest);
+            });
+            child.stderr.on("data", (b) => { said = (said + b.toString("utf8")).slice(-16 * 1024); process.stderr.write(b); });
+            // ssh gone with bytes still to write: said by its exit
+            child.stdin.on("error", () => undefined);
+            child.on("error", (e) => {
+                if (e.code === "ENOENT") {
+                    fail({ message: "ssh is not on this machine's PATH, and mason ui --ssh runs it", code: "not_found", fix: "install the OpenSSH client (it comes with macOS, Windows 10 and later, and most Linux; apt install openssh-client)" });
+                    gone();
+                    return;
+                }
+                fail({ message: `ssh could not be started: ${e.message}`, code: "failed" });
+                gone();
+            });
+            child.on("exit", (code, signal) => {
+                gone();
+                // read after a moment: a Ctrl-C reaches ssh and this process together, and `stop` says which end it was
+                setTimeout(() => {
+                    const last = lastLines(said, null);
+                    if (!settled) {
+                        fail(exitFailure({ target: o.target, mason: o.mason, code, signal, said: last, stderr: said }));
+                        return;
+                    }
+                    if (stopping)
+                        return;
+                    link?.end();
+                    local.close();
+                    finish(last === "" ? `ssh exited ${code ?? signal}` : `ssh exited ${code ?? signal}: ${last}`);
+                }, SETTLE_MS).unref();
+            });
+        });
+    });
+}