@mason-data/cli 0.8.0 → 0.9.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, 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();
+            });
+        });
+    });
+}

package/dist/src/cli/ui.js

@@ -7,18 +7,27 @@
  * `mason status`, which prints the URL without it.
  *
  * Before it prints anything it ASKS the page (`GET /` with the run's token as the commands send it), so a run that serves
- * none (`mason serve`'s, or one from before the page) is said, never a URL that answers 404.
+ * none (one from before the page) is said, never a URL that answers 404.
+ *
+ * `--ssh <user@server>` (src/cli/ui-ssh.ts, docs/WEB-UI.md "On a server") opens a server's page from this machine, through
+ * the machine's own ssh, and stays in the foreground until Ctrl-C, as `mason share` does; it needs no project here. Its
+ * URL carries a ticket for one use, never the run's token, which stays on the server. `--bridge` is what it runs there.
  */
 import { spawn } from "node:child_process";
 import { failed, jsonText, parseCommand, reportText } from "./command.js";
 import { reach } from "./state.js";
+import { bridge, openSshTunnel, targetProblem } from "./ui-ssh.js";
+import { version } from "./version.js";
 import { RunUnreachable } from "./control.js";
 const out = (m) => { process.stdout.write(`${m}\n`); };
+const say = (m) => { process.stderr.write(`${m}\n`); };
+const DEFAULT_TIMEOUT_S = 60;
 export const UI = {
     needs: "run",
     name: "ui",
     summary: "the status, tables, users and statements, in your browser",
     usage: `usage: mason ui [--no-open] [--json]
+       mason ui --ssh <user@server> [--mason <command>] [--timeout <seconds>] [--no-open] [--json]
 
   Opens the running Mason's web page in your browser, refreshed while the tab is open: the Overview (what mason status
   says: whether the synced data is ready, the database, the sync, the statements and the recent errors); the Tables (add,
@@ -28,18 +37,36 @@ export const UI = {
 
   The URL carries this run's token: the page trades it for a cookie at once and drops it from the address
   bar. It is printed for you alone, like a user's password: paste it nowhere else. Every mason start makes a new
-  token, so after a restart run mason ui again. The page is mason start's: mason serve serves none (off this
-  machine it would need TLS and a login).
+  token, so after a restart run mason ui again.
+
+  --ssh opens a server's page (mason serve's) from this machine, with nothing public: it runs your ssh, so your
+  ~/.ssh/config, keys and SSO apply, starts mason there, and forwards a free local port to the page, which listens on the
+  server's loopback alone. It stays in the foreground: Ctrl-C closes the tunnel. It needs no project here. Its URL
+  carries a ticket for one use, never the run's token, which stays on the server. The server's Mason must be this
+  version or close to it, and must be a command ssh can run: --mason says how, for a container or a folder.
 
     mason ui
     mason ui --no-open        print the URL, open no browser
     mason ui --json
+    mason ui --ssh deploy@mason.example.com
+    mason ui --ssh deploy@mason.example.com --mason "docker exec -i mason-mason-1 mason"
+    mason ui --ssh deploy@mason.example.com --mason "cd /var/lib/mason && mason" --timeout 120 --no-open
+    mason ui --bridge --local-port 51000      what --ssh runs on the server; its stdout is a stream, not for reading
 
-  --no-open   print the URL only
-  --json      as data: { url (with this run's token), port }, next; it never opens a browser
+  --no-open            print the URL only
+  --ssh <target>       the server, as you give it to ssh: user@server, or a Host of your ssh config
+  --mason <command>    how to run mason on the server (default mason); a shell's text, kept to ssh's command line
+  --timeout <s>        how long ssh and the server have to answer (default ${DEFAULT_TIMEOUT_S}): a passphrase or a touch counts
+  --bridge             the server's end of --ssh, on stdin and stdout
+  --local-port <n>     the port the browser names, for --bridge: the laptop's
+  --json               as data: { url (with this run's token; with --ssh a ticket for one use; null when Ctrl-C came
+                       before the server answered, as port is, exit 0), port, server, project,
+                       version (with --ssh: the server's Mason, for what its answer may lack) }, next; it never opens a
+                       browser. With --ssh it then holds the tunnel: the end is on stderr, exit 0 for Ctrl-C or SIGTERM, 1 otherwise
 `,
-    options: { "no-open": { type: "boolean", default: false }, json: { type: "boolean", default: false } },
-    json: ["url", "port", "next"],
+    options: { "no-open": { type: "boolean", default: false }, json: { type: "boolean", default: false }, ssh: { type: "string" }, mason: { type: "string" },
+        timeout: { type: "string" }, bridge: { type: "boolean", default: false }, "local-port": { type: "string" } },
+    json: ["url", "port", "server", "project", "version", "next"],
 };
 const NEXT = [["mason status", "the same, in this terminal"], ["mason user list", "the users"]];
 /** The command that opens a URL in the person's browser, by platform (macOS `open`, Windows `start`, else `xdg-open`). */
@@ -52,7 +79,7 @@ export function openCommand(platform, url) {
     return ["xdg-open", [url]];
 }
 /** Open `url` in the browser: null once the opener started, else why it could not (the URL is printed either way). */
-function openBrowser(url) {
+export function openBrowser(url) {
     const [command, args] = openCommand(process.platform, url);
     return new Promise((resolve) => {
         const child = spawn(command, args, { detached: true, stdio: "ignore" });
@@ -72,21 +99,98 @@ async function servesPage(run) {
     await res.arrayBuffer();
     return res.status === 200 && /^text\/html/.test(res.headers.get("content-type") ?? "");
 }
+/**
+ * THE PAGE OF A SERVER (the header): the tunnel, the URL once, and held until Ctrl-C or until it drops. As `mason share`:
+ * what `--json` prints is one object, once, and everything after it is on stderr, so stdout stays one document. The
+ * signals are heard before ssh starts: a Ctrl-C at a passphrase ends both.
+ */
+async function overSsh(target, mason, timeoutMs, open, json) {
+    let signalled = null;
+    const signal = new Promise((resolve) => {
+        const heard = (s) => { signalled = s; resolve(s); };
+        process.once("SIGINT", heard);
+        process.once("SIGTERM", heard);
+    });
+    const t = await openSshTunnel({ target, mason, timeoutMs, interactive: !json && process.stdin.isTTY === true, stopped: signal });
+    const next = [[`mason ui --ssh ${target}`, "again, once this one is closed: a new port and a new ticket"]];
+    if ("message" in t) {
+        if (signalled === null)
+            return failed("ui", t, { json });
+        // stopped on purpose, exit 0: under --json still the one object every answer is, its url null as nothing opened
+        if (json)
+            out(jsonText(UI, { url: null, port: null, server: target }, next));
+        else
+            say(`stopped before ${target} answered: nothing was left open`);
+        return 0;
+    }
+    if (json)
+        out(jsonText(UI, { url: t.url, port: t.port, server: target, project: t.project, version: t.serverVersion }, next));
+    else {
+        const couldNot = open ? await openBrowser(t.url) : null;
+        out(reportText({
+            headline: open && couldNot === null ? `${t.project} on ${target}, opened in your browser` : `${t.project} on ${target}`,
+            details: [["url", t.url], ["server", target], ["project", t.project], ["version", t.serverVersion]],
+            tips: [
+                ...(couldNot !== null ? [`Could not open a browser (${couldNot}): open the URL yourself.`] : []),
+                ...(t.serverVersion !== version() ? [`This machine's Mason is ${version()}: the page is the server's.`] : []),
+                "The URL carries a ticket for one use, and works for 5 minutes. Ctrl-C closes the tunnel.",
+            ],
+            next,
+        }));
+    }
+    const how = await Promise.race([signal.then((s) => ({ signal: s })), t.ended.then((why) => ({ why }))]);
+    if ("signal" in how) {
+        await t.stop();
+        say(`the tunnel to ${target} is closed`);
+        return 0;
+    }
+    return failed("ui", { message: `the tunnel to ${target} dropped`, code: "failed", why: how.why, fix: "is the server up, and this machine online? The page in your browser stops answering until a new tunnel opens one", next }, { json: false });
+}
 export async function ui(argv) {
     const f = parseCommand(UI, argv);
     if (typeof f === "number")
         return f;
     const json = f.values.json === true;
+    const v = f.values;
+    const wrong = (message) => failed("ui", { message, code: "usage", usage: UI.usage }, { json });
     if (f.positionals.length)
-        return failed("ui", { message: `mason ui takes no argument: ${f.positionals.join(" ")}`, code: "usage", usage: UI.usage }, { json });
+        return wrong(`mason ui takes no argument: ${f.positionals.join(" ")}`);
+    if (v.bridge) {
+        if (v.ssh !== undefined || v.mason !== undefined || v.timeout !== undefined || json)
+            return wrong("--bridge is mason ui --ssh's own end on the server: it goes with --local-port alone");
+        const port = Number(v["local-port"]);
+        if (!Number.isInteger(port) || port < 1 || port > 65_535)
+            return wrong(`--bridge needs --local-port, a port number, not ${JSON.stringify(v["local-port"] ?? "")}`);
+        return bridge(port);
+    }
+    if (v["local-port"] !== undefined)
+        return wrong("--local-port goes with --bridge");
+    if (v.ssh === undefined && (v.mason !== undefined || v.timeout !== undefined))
+        return wrong(`${v.mason !== undefined ? "--mason" : "--timeout"} goes with --ssh <user@server>`);
+    if (v.ssh !== undefined) {
+        const problem = targetProblem(v.ssh);
+        if (problem !== null)
+            return wrong(`--ssh: ${problem}`);
+        if (v.mason !== undefined && (v.mason.trim() === "" || /[\r\n]/.test(v.mason)))
+            return wrong("--mason is one line of shell that runs mason on the server");
+        const seconds = v.timeout === undefined ? DEFAULT_TIMEOUT_S : Number(v.timeout);
+        if (!Number.isFinite(seconds) || seconds <= 0)
+            return wrong(`--timeout is a number of seconds, not ${JSON.stringify(v.timeout)}`);
+        return overSsh(v.ssh, v.mason ?? "mason", seconds * 1000, !v["no-open"], json);
+    }
     const w = await reach(UI, json);
     if (w === null || w.state !== "up")
         return 1;
     const run = w.run;
+    if (w.project.config.served === true) {
+        return failed("ui", { message: `Mason for ${run.name} runs on this server: its page is opened from your own machine`, code: "refused",
+            why: "the page listens on this machine's loopback alone, and a browser on a server has no one in front of it",
+            fix: "on your machine, mason ui --ssh <user@server> (mason ui --help: for a container, --mason)", next: [["mason status", "what it is doing, in this terminal"]] }, { json });
+    }
     if (!await servesPage(run)) {
         return failed("ui", { message: `Mason for ${run.name} serves no web page`, code: "refused",
-            why: "the page is mason start's: this is mason serve's run, or a run started by a Mason from before the page",
-            fix: "on your machine, mason stop && mason start runs it with the page; a server's Mason is read with mason status",
+            why: "this run was started by a Mason from before the page",
+            fix: "mason stop && mason start runs it with the page",
             next: [["mason status", "what it is doing, in this terminal"]] }, { json });
     }
     const url = `${run.control.url}/?token=${encodeURIComponent(run.control.token)}`;