@mason-data/cli 0.8.0 → 0.10.0

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

@@ -0,0 +1,163 @@
+/**
+ * `mason ui --replica <org>/<name>` — A HOSTED REPLICA'S WEB PAGE, IN THE BROWSER OF THE ORGANISATION'S OWNER
+ * (docs/HOSTED-API.md "A replica's page"). ONE request, `POST /v1/replicas/{org}/{name}/ui`, whose answer is a one-use,
+ * short-lived address of the replica's page (on the service's origin, or on https at a subdomain of its host), read-only
+ * (the service refuses every write through it: changes go by `mason user … --replica`, which it audits); the CLI opens it as `mason ui` opens a run's
+ * page and `mason login` its sign-in page (`openBrowser`), or prints it (`--no-open`, `--json`, a browser that would not
+ * start). Who may ask (the owner's login alone), and the audit row of each page opened, are the service's: the CLI cannot
+ * write that row and never says it did.
+ *
+ * Every value of the answer, and how it is held (src/cli/hosted.ts's header: a service's value is data, never structure):
+ *
+ *   value                      where it is printed                     what holds it
+ *   every string, keys too     nowhere until held                      `carriesNoSecret`: an answer carrying a secret is refused whole
+ *   url                        opened; printed where it was not        `pageOrigin`, `pageUrl`: the service's origin or https at a
+ *                                                                      subdomain of its host, its port; no user, at most 2048, carries
+ *                              opened, and in --json                   no secret as printed; then `OPENABLE`: letters, digits and
+ *                                                                      `. : [ ] - _ ~ / ? = +` alone, so no shell reads it
+ *   expiresAt                  a row, --json                           `isServiceTime`
+ *   a failure's words          stderr's failure, --json error          `serviceFailure`: one line each, masked; the code by the status
+ *   a failure's next           nowhere: never read                     the step is `failureNext`'s, by the status
+ *   Retry-After                a next step's words                     `retryAfterOf`: 1 to 3600 seconds
+ *
+ * THE ADDRESS IS PRINTED ONLY WHERE THE PERSON NEEDS IT: opened in the browser, it is not printed (the browser used it,
+ * and it opens the page once); printed when it was not opened, and in `--json` for the agent that passes it on. It is
+ * never logged: this command writes no log. A 409 or a 503 (a replica not ready, its machine not connected) is said
+ * with the next step, never waited on: the person runs the command again.
+ */
+import { failed, jsonText, reportText, serviceStyle } from "./command.js";
+import { environmentToken, TOKEN_ENV } from "./credentials.js";
+import { call, carriesNoSecret, codeOfStatus, isFailure, isServiceTime, pageUrl, serviceFailure, serviceOf, unexpected } from "./hosted.js";
+import { holdOutput } from "./output-gate.js";
+import { replicaText, tokenFor } from "./replica.js";
+import { err as styleErr, out as styleOut } from "./style.js";
+import { OPENABLE, openBrowser, UI } from "./ui.js";
+const out = (m) => { process.stdout.write(`${m}\n`); };
+const obj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/** The request: the replica's page, asked of the service. Both parts are `REPLICA_PART`'s, safe in a path as they are. */
+export const pagePath = (r) => `/v1/replicas/${r.org}/${r.name}/ui`;
+const STEP = "a replica's page was asked for";
+/**
+ * THE ORIGIN A REPLICA'S PAGE MAY BE ON: the service's own, or an `https:` origin whose host is a subdomain of the
+ * service's host, on the service's port (a page of its own origin keeps the service's session cookie and its routes
+ * apart from Mason's page: `r-abc.ui.app.example` under `app.example`). A subdomain by its labels, never a suffix of the
+ * text (`evilapp.example` is not under `app.example`), and none under an IP address. The origin the page is held to,
+ * or null when `v` is on none of them (or is no URL).
+ */
+export function pageOrigin(service, v) {
+    if (typeof v !== "string")
+        return null;
+    let u, base;
+    try {
+        u = new URL(v);
+        base = new URL(service.base);
+    }
+    catch {
+        return null;
+    }
+    if (u.origin === service.base)
+        return service;
+    const ip = /^[\d.]+$/.test(base.hostname) || base.hostname.startsWith("[");
+    if (u.protocol !== "https:" || u.port !== base.port || ip || !u.hostname.endsWith(`.${base.hostname}`))
+        return null;
+    return { base: u.origin };
+}
+/**
+ * `POST …/ui`'s answer (200), held: every string of it, each key included, put to the exact test first
+ * (`carriesNoSecret`), then the address on an origin it may be on (`pageOrigin`; refused naming the origin when it is
+ * not), held there by `pageUrl` (no user or password, at most 2048, no secret as printed), of the characters a browser
+ * is handed (`OPENABLE`), and the time to its grammar. The page, or a Failure said by the status alone (or naming the
+ * other origin).
+ */
+export function heldPage(service, a, secrets) {
+    const j = a.json;
+    if (!obj(j) || !carriesNoSecret(j, secrets))
+        return unexpected(service, a, STEP);
+    const origin = pageOrigin(service, j.url);
+    // on an origin it may be on, `pageUrl` holds it as on the service's own; elsewhere, `pageUrl` says the origin safely
+    const page = pageUrl(origin ?? service, j.url, secrets);
+    if (page !== null && "elsewhere" in page) {
+        return { message: `${service.base} named a replica's page on another address: ${page.elsewhere}`, code: "refused",
+            why: `a replica's page is opened only on the service's own address, ${service.base}, or on https at a subdomain of its host: anything else would send you to an address nobody chose`,
+            fix: "check MASON_CLOUD_URL names the service you mean; if it does, the service is answering outside its documented API" };
+    }
+    if (page === null || !OPENABLE.test(page.href) || !isServiceTime(j.expiresAt))
+        return unexpected(service, a, STEP);
+    return { url: page.href, expiresAt: j.expiresAt };
+}
+/**
+ * WHAT TO RUN AFTER THE SERVICE REFUSED: the CLI's own, by the status (never the service's `next`). A 401 or 403 is a
+ * login that may not (only the organisation's owner opens a replica's page; a CI token never does), a 404 a replica the
+ * login does not see, a 409 or 503 a replica not ready or not connected: its state, and the command again when the
+ * service's `Retry-After` says.
+ */
+export function failureNext(status, r, retryAfter, env = process.env) {
+    const named = replicaText(r);
+    if (status === 401 || status === 403) {
+        return environmentToken(env) !== null
+            ? [[`env -u ${TOKEN_ENV} mason ui --replica ${named}`, `with your own login, not ${TOKEN_ENV}: a CI token never opens a page`]]
+            : [["mason login", "sign in as the organisation's owner: only an owner opens a replica's page"]];
+    }
+    if (status === 404)
+        return [[`mason replica list ${r.org}`, "the replicas this login sees"]];
+    if (status === 409 || status === 503) {
+        return [[`mason replica status ${named}`, "whether it is ready"],
+            [`mason ui --replica ${named}`, retryAfter !== null ? `again in ${retryAfter} s, as the service asks` : "again in a moment"]];
+    }
+    return [[`mason ui --replica ${named}`, "again in a moment"]];
+}
+/** A refusal said as the service worded it; a 409 or 503 it sent without its words is said in the CLI's. */
+export function refusalOf(service, a, r, secrets, env = process.env) {
+    const next = failureNext(a.status, r, a.retryAfter, env);
+    const notReady = a.status === 409 || a.status === 503;
+    const again = a.retryAfter !== null ? `try again in ${a.retryAfter} s` : "try again in a moment";
+    const said = serviceFailure(a, secrets, () => next);
+    if (said !== null)
+        return notReady && said.fix === undefined ? { ...said, fix: `${again}; mason replica status ${replicaText(r)} says whether it is ready` } : said;
+    if (notReady) {
+        return { message: `the replica ${replicaText(r)} is not ready to open its page (HTTP ${a.status})`, code: codeOfStatus(a.status),
+            why: a.status === 409 ? "it is not ready yet: being made, deleted, or failed" : "its machine is not connected to the service now",
+            fix: `${again}; mason replica status ${replicaText(r)} says whether it is ready`, next };
+    }
+    return unexpected(service, a, STEP);
+}
+/** `mason ui --replica <org>/<name>`: the page asked for, then opened, printed, or said as --json. */
+export async function hostedUi(r, o) {
+    const fail = (f) => failed("ui", f, { json: o.json, style: serviceStyle(styleErr()) });
+    const service = serviceOf();
+    if (isFailure(service))
+        return fail(service);
+    const token = tokenFor(service, { asked: "a replica's page is asked for", again: `mason ui --replica ${replicaText(r)}` });
+    if (isFailure(token))
+        return fail(token);
+    // from here every byte written is put to the exact test against the token (src/cli/output-gate.ts)
+    holdOutput({ command: "ui", json: o.json, secrets: [token] });
+    const secrets = [token];
+    const a = await call(service, "POST", pagePath(r), { token });
+    if (isFailure(a))
+        return fail(a);
+    if (a.status !== 200)
+        return fail(refusalOf(service, a, r, secrets));
+    const page = heldPage(service, a, secrets);
+    if (isFailure(page))
+        return fail(page);
+    const named = replicaText(r);
+    const next = [[`mason replica status ${named}`, "the replica's state, in this terminal"], [`mason ui --replica ${named}`, "a new address: each opens the page once"]];
+    if (o.json) {
+        out(jsonText(UI, { url: page.url, replica: named, expiresAt: page.expiresAt }, next));
+        return 0;
+    }
+    const couldNot = o.open ? await openBrowser(page.url) : null;
+    const opened = o.open && couldNot === null;
+    out(reportText({
+        headline: opened ? `The page of the replica ${named}, opened in your browser` : `The page of the replica ${named}`,
+        // opened, the address is not printed: the browser used it, and it opens the page once
+        details: [...(opened ? [] : [["url", page.url]]), ["replica", named], ["expires", page.expiresAt]],
+        tips: [
+            ...(couldNot !== null ? [`Could not open a browser (${couldNot}): open the URL yourself.`] : []),
+            opened ? "The address opens the page once: for another tab, run the command again." : "The URL opens the page once, for you alone, until it expires: paste it nowhere else.",
+        ],
+        next,
+    }, serviceStyle(styleOut())));
+    return 0;
+}

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, failureCode, 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: failureCode(h.error.code, "failed"), ...(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: "timeout", ...(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();
+            });
+        });
+    });
+}