@mason-data/cli 0.9.0 → 0.11.0

package/dist/src/cli/tunnel.js

@@ -133,7 +133,7 @@ export function startTunnel(plan, o) {
         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}`,
+            settle({ message: `the tunnel gave no address in ${Math.round(o.timeoutMs / 1000)} s`, code: "timeout", 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) => {

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-read-only.js

@@ -0,0 +1,23 @@
+export const UI_READ_ONLY_SETTING = "MASON_UI_READ_ONLY";
+/** MASON_UI_READ_ONLY as the environment says it: 1 true, 0 or unset false, anything else what is wrong with it. */
+export function uiReadOnlySetting(env) {
+    const v = env[UI_READ_ONLY_SETTING];
+    if (v === undefined || v === "" || v === "0")
+        return false;
+    if (v === "1")
+        return true;
+    return { problem: `${UI_READ_ONLY_SETTING}=${JSON.stringify(v)}: 1 (the web page only shows, and changes nothing) or 0 (the default)` };
+}
+/** Why the page offers no control that changes anything: `/api/state` `pageReadOnly`, the page's words. */
+export const PAGE_READ_ONLY_WHY = `the web page is read-only here (${UI_READ_ONLY_SETTING}=1)`;
+/** The answer to every change the page asks for under the setting. */
+export const PAGE_READ_ONLY = {
+    message: `${PAGE_READ_ONLY_WHY}: it shows what Mason syncs, and changes nothing`, code: "refused",
+    why: `Mason was started with ${UI_READ_ONLY_SETTING}=1, so the page refuses every change, whatever it asks`,
+    fix: "make the change with the mason command where Mason runs, or ask whoever runs it",
+};
+/**
+ * Whether a request the guard let in is a change the page asks for: anything but a GET or a HEAD, sent without the
+ * run's token (a request with it is the commands', and the guard has checked that the token is the run's).
+ */
+export const pageWrite = (method, authorization) => method !== "GET" && method !== "HEAD" && authorization === undefined;

package/dist/src/cli/ui-run-file.js

@@ -0,0 +1,247 @@
+/**
+ * `MASON_UI_RUN_FILE` (mason serve): THE RUN'S PAGE PORT AND TOKEN IN A FILE THE OPERATOR NAMES, for a process on the
+ * same machine that supervises the run (a supervisor, a local reverse proxy beside MASON_UI_SOCKET) and opens a tunnel
+ * (`POST /api/ui/tunnel`) without reading `.mason/config.json`, which is the run's own and holds more.
+ *
+ * WHAT IT HOLDS: `{ "port", "token" }` and nothing else. The token is the run's: it grants the commands' writes (mason
+ * add, mason sync, mason cancel, the users) as well as a tunnel, so the file is held to the bar the page's socket is
+ * (src/cli/ui-socket.ts): in a folder only Mason's user can write (`ownFolderProblem`), mode 0600 from the moment it
+ * exists, never through a symbolic link. The socket's path is not in it: whoever reads the file named the socket, and
+ * /healthz says it.
+ *
+ * WRITTEN WHOLE, ONCE THE RUN ANSWERS: a 0600 file beside it, written and flushed, then linked to the path (a link
+ * never replaces what is there), so a reader finds no file or the whole of it. It is removed when the run stops, and only
+ * when it is still the one written. A file already at the path is replaced only when it is a run file of Mason's user
+ * (a regular file, 0600, of exactly those two keys) whose run does not answer with its token; anything else — a link,
+ * a folder, another user's file, a file of other content, a run that answers — refuses the start and is left as it is.
+ */
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { octal, ownFolderProblem } from "./ui-socket.js";
+export const UI_RUN_FILE_SETTING = "MASON_UI_RUN_FILE";
+/** How long the run a stale file names has to answer before whether it runs is taken as unknown. */
+const PROBE_MS = 2_000;
+/** The file MASON_UI_RUN_FILE names, absolute; null when it is unset (or set empty); or what is wrong with it. */
+export function uiRunFileSetting(env, cwd, platform = process.platform) {
+    const set = env[UI_RUN_FILE_SETTING];
+    if (!set)
+        return null;
+    // a file mode is how the token is kept to Mason's user, and Windows keeps none
+    if (platform === "win32")
+        return { problem: `${UI_RUN_FILE_SETTING} is set, and on Windows a file cannot be kept to Mason's user by its mode: unset it` };
+    return path.resolve(cwd, set);
+}
+const refused = (file, problem, fix) => ({ message: `${UI_RUN_FILE_SETTING}=${file}: ${problem}`, code: "refused", why: "the file holds the run's token, which grants the commands' writes as well as a tunnel to the page, so only Mason's user may make or replace it", fix });
+/** The content of a run file Mason wrote, or null when `text` is anything else. */
+function runFileContent(text) {
+    let v;
+    try {
+        v = JSON.parse(text);
+    }
+    catch {
+        return null;
+    } // not JSON: not a run file, which the caller refuses
+    if (typeof v !== "object" || v === null || Array.isArray(v))
+        return null;
+    const o = v;
+    if (Object.keys(o).sort().join(",") !== "port,token")
+        return null;
+    if (typeof o.port !== "number" || !Number.isInteger(o.port) || o.port < 1 || o.port > 65_535 || typeof o.token !== "string")
+        return null;
+    return { port: o.port, token: o.token };
+}
+/** Whether the run a file names answers with its token: true, false (nothing that is that run), or the error that left it unknown. */
+async function runAnswers(c) {
+    try {
+        const res = await fetch(`http://127.0.0.1:${c.port}/api/ping`, { headers: { Authorization: `Bearer ${c.token}` }, signal: AbortSignal.timeout(PROBE_MS) });
+        if (res.status !== 200) {
+            await res.body?.cancel();
+            return false;
+        }
+        let body;
+        try {
+            body = await res.json();
+        }
+        catch (e) {
+            // a 200 whose body is not JSON is no run's ping (a body cut off midway is not knowing, said as such)
+            if (e instanceof SyntaxError)
+                return false;
+            throw e;
+        }
+        return typeof body?.pid === "number";
+    }
+    catch (e) {
+        const code = e.cause?.code;
+        if (code === "ECONNREFUSED")
+            return false;
+        return e instanceof Error ? e : new Error(String(e));
+    }
+}
+/**
+ * The folder and the path held to the bar (the header): null when the file may be written, after a stale one is
+ * removed (`said` is told), or the refusal. Fails closed: a fact it cannot read refuses.
+ */
+export async function prepareUiRunFile(file, said, uid = process.getuid()) {
+    const folder = ownFolderProblem(file, "run file", uid);
+    if (folder !== null)
+        return refused(file, folder.problem, folder.fix);
+    let f;
+    try {
+        f = fs.lstatSync(file);
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return null;
+        return refused(file, `it cannot be read: ${e.message}`, "name another path");
+    }
+    const notMine = "remove it yourself if it is not needed, or name another path";
+    if (f.isSymbolicLink())
+        return refused(file, "it is a symbolic link, and Mason never replaces one", notMine);
+    if (!f.isFile())
+        return refused(file, `it is ${f.isDirectory() ? "a folder" : "not a regular file"}, and Mason replaces only a run file a run of its own left`, notMine);
+    if (f.uid !== uid)
+        return refused(file, `it is a file of uid ${f.uid}, not of Mason's user (uid ${uid})`, notMine);
+    if ((f.mode & 0o777) !== 0o600)
+        return refused(file, `it is a file of mode ${octal(f.mode)}, and a run file Mason writes is 0600`, notMine);
+    let text;
+    try {
+        // never through a link that appeared since: O_NOFOLLOW
+        const fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+        try {
+            text = f.size > 4096 ? "" : fs.readFileSync(fd, "utf8");
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    catch (e) {
+        return refused(file, `it cannot be read: ${e.message}`, notMine);
+    }
+    const content = runFileContent(text);
+    if (content === null)
+        return refused(file, "it is a file of other content than a run file Mason writes ({ port, token })", notMine);
+    const live = await runAnswers(content);
+    if (live === true)
+        return refused(file, "the run it names answers with its token: another Mason writes it now", "stop that Mason, or name another path");
+    if (live instanceof Error)
+        return refused(file, `whether the run it names still runs could not be told (${live.message})`, notMine);
+    try {
+        fs.unlinkSync(file);
+    }
+    catch (e) {
+        return refused(file, `the stale run file could not be removed: ${e.message}`, notMine);
+    }
+    said(`replaced the run file a run that did not stop left at ${file}`);
+    return null;
+}
+/** Whether `file` holds `text`, read never through a link. */
+function readsAs(file, text) {
+    let fd;
+    try {
+        fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+    }
+    catch {
+        return false;
+    } // gone, or a link since: not the file written, which the caller leaves
+    try {
+        return fs.readFileSync(fd, "utf8") === text;
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/**
+ * Writes `content` to `file` whole (the header): a 0600 file beside it, written and flushed, linked to the path, which
+ * fails when anything is there, then checked. `said` is told of a removal that failed.
+ */
+export function writeUiRunFile(file, content, said, uid = process.getuid()) {
+    const folder = ownFolderProblem(file, "run file", uid);
+    if (folder !== null)
+        return refused(file, folder.problem, folder.fix);
+    const temp = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.${crypto.randomBytes(6).toString("hex")}`);
+    const text = `${JSON.stringify({ port: content.port, token: content.token })}\n`;
+    let fd = null;
+    let linked = false;
+    const cleanUp = () => {
+        if (fd !== null) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch (e) {
+                said(`the run file's descriptor could not be closed: ${e.message}`);
+            }
+        }
+        try {
+            fs.unlinkSync(temp);
+        }
+        catch (e) {
+            if (e.code !== "ENOENT")
+                said(`the run file's temporary ${temp} could not be removed: ${e.message}`);
+        }
+    };
+    let made;
+    try {
+        // made 0600 by open itself (O_EXCL: never a file that was there; O_NOFOLLOW: never through a link), then set
+        // exactly 0600 whatever the umask, before a byte is written
+        fd = fs.openSync(temp, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_NOFOLLOW, 0o600);
+        fs.fchmodSync(fd, 0o600);
+        fs.writeFileSync(fd, text);
+        fs.fsyncSync(fd);
+        made = fs.fstatSync(fd);
+        fs.closeSync(fd);
+        fd = null;
+        // a link never replaces what is at the path: EEXIST when something appeared there since the start checked it
+        fs.linkSync(temp, file);
+        linked = true;
+    }
+    catch (e) {
+        cleanUp();
+        const code = e.code;
+        return refused(file, code === "EEXIST" && !linked ? "something was put at the path after the start checked it, and Mason writes over nothing" : `it cannot be written: ${e.message}`, code === "EEXIST" ? "remove it yourself if it is not needed, or name another path" : "name a path in a folder only Mason's user can write, on a file system that keeps hard links");
+    }
+    cleanUp();
+    let now;
+    try {
+        now = fs.lstatSync(file);
+    }
+    catch (e) {
+        return refused(file, `it cannot be read once written: ${e.message}`, "name a path in a folder only Mason's user can write");
+    }
+    // the file written: its inode, and its text too, since a file made at the path after it was removed may be handed
+    // the same inode number
+    const same = (s) => s.isFile() && s.ino === made.ino && s.dev === made.dev && s.size === Buffer.byteLength(text) && readsAs(file, text);
+    if (!same(now) || now.uid !== uid || (now.mode & 0o777) !== 0o600) {
+        if (same(now)) {
+            try {
+                fs.unlinkSync(file);
+            }
+            catch (e) {
+                said(`the run file ${file} could not be removed: ${e.message}`);
+            }
+        }
+        return refused(file, `it is not Mason's alone once written (mode ${octal(now.mode)}, uid ${now.uid})`, "name a path in a folder only Mason's user can write");
+    }
+    let removed = false;
+    return {
+        file,
+        remove: () => {
+            if (removed)
+                return;
+            removed = true;
+            // removed only while it is the file written: another's at the path since is left as it is
+            try {
+                if (same(fs.lstatSync(file)))
+                    fs.unlinkSync(file);
+                else
+                    return;
+            }
+            catch (e) {
+                if (e.code !== "ENOENT")
+                    said(`the run file ${file} could not be removed: ${e.message}`);
+                return;
+            }
+            said(`removed the run file ${file}`);
+        },
+    };
+}

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

@@ -0,0 +1,183 @@
+/**
+ * `MASON_UI_SOCKET` (mason serve): THE WEB PAGE ON A UNIX SOCKET THE OPERATOR NAMES, beside its loopback port, for a
+ * process on the same machine (a supervisor, a local reverse proxy) that should reach the page without a port published
+ * or a `docker exec` per request.
+ *
+ * WHO CAN CONNECT is who can write the socket, so the socket is made mode 0600 in a folder only Mason's user can write
+ * (owned by it, no group or other write), never through a symbolic link: anything else refuses the start, with the way
+ * out. A path that is already there is replaced only when it is a socket of Mason's user that nobody answers on (a run
+ * that crashed left it); a file of any other kind, a link, another user's socket, or one a process answers on is never
+ * removed. The socket is removed when the run stops.
+ *
+ * WHAT A REQUEST ON IT IS TRUSTED WITH: exactly what one through `mason ui --bridge` is, because it reaches the run's own
+ * request handler (src/cli/run-server.ts), behind the same guard (src/cli/security.ts): its Host, the run's token or a
+ * tunnel's ticket and cookie, its Origin. Arriving on the socket proves nothing: no request is taken for a local
+ * browser, or let in at all, for where it came from.
+ */
+import * as fs from "node:fs";
+import * as http from "node:http";
+import * as net from "node:net";
+import * as path from "node:path";
+export const UI_SOCKET_SETTING = "MASON_UI_SOCKET";
+/** The longest path a Unix socket may have: `sun_path` holds 108 bytes on Linux, 104 on macOS, each with its NUL. */
+const maxSocketBytes = (platform) => platform === "darwin" ? 103 : 107;
+/** How long a socket at the path has to answer before it is taken for one nobody serves: a live run answers at once. */
+const PROBE_MS = 1_000;
+/** The socket MASON_UI_SOCKET names, absolute; null when it is unset (or set empty); or what is wrong with it. */
+export function uiSocketSetting(env, cwd, platform = process.platform) {
+    const set = env[UI_SOCKET_SETTING];
+    if (!set)
+        return null;
+    if (platform === "win32")
+        return { problem: `${UI_SOCKET_SETTING} is set, and Windows has no Unix socket for the page: unset it (mason ui --ssh <user@server> opens the page from your machine)` };
+    const file = path.resolve(cwd, set);
+    const bytes = Buffer.byteLength(file);
+    if (bytes > maxSocketBytes(platform))
+        return { problem: `${UI_SOCKET_SETTING}=${JSON.stringify(set)} is ${bytes} bytes as a full path, and a Unix socket's path is at most ${maxSocketBytes(platform)}: name a shorter one` };
+    return file;
+}
+const refused = (file, problem, fix) => ({ message: `${UI_SOCKET_SETTING}=${file}: ${problem}`, code: "refused", why: "the socket is how a process on this machine reaches the web page, so only Mason's user may make or replace it", fix });
+export const octal = (mode) => `0${(mode & 0o777).toString(8)}`;
+/** Whether a process answers on the socket at `file`: true, false (nothing listens), or the error that left it unknown. */
+function answers(file) {
+    return new Promise((resolve) => {
+        const c = net.connect(file);
+        const timer = setTimeout(() => { c.destroy(); resolve(new Error(`it neither accepted nor refused a connection in ${PROBE_MS} ms`)); }, PROBE_MS);
+        c.once("connect", () => { clearTimeout(timer); c.destroy(); resolve(true); });
+        c.once("error", (e) => { clearTimeout(timer); resolve(e.code === "ECONNREFUSED" ? false : e); });
+    });
+}
+/**
+ * THE FOLDER OF A FILE ONLY MASON'S USER MAY MAKE (the page's socket, the run's file, src/cli/ui-run-file.ts): a folder,
+ * not a link to one, owned by Mason's user, which no group or other can write; null, or what is wrong and the way out.
+ * Fails closed: a folder it cannot read is refused. `what` names the file in the way out ("socket", "run file").
+ */
+export function ownFolderProblem(file, what, uid) {
+    const dir = path.dirname(file);
+    const ownFolder = `mkdir -m 700 ${dir} as Mason's user, or name a ${what} in a folder that is only its own (the data folder's .mason/ is)`;
+    let d;
+    try {
+        d = fs.lstatSync(dir);
+    }
+    catch (e) {
+        return { problem: `its folder ${dir} cannot be read: ${e.code === "ENOENT" ? "it does not exist" : e.message}`, fix: ownFolder };
+    }
+    if (d.isSymbolicLink()) {
+        let real;
+        try {
+            real = fs.realpathSync(dir);
+        }
+        catch (e) {
+            real = `it names nothing that can be read: ${e.message}`;
+        }
+        return { problem: `its folder ${dir} is a symbolic link`, fix: `name the ${what} in the folder itself (${real}), not through a link to it` };
+    }
+    if (!d.isDirectory())
+        return { problem: `${dir} is not a folder`, fix: ownFolder };
+    if (d.uid !== uid)
+        return { problem: `its folder ${dir} is owned by uid ${d.uid}, not Mason's user (uid ${uid})`, fix: ownFolder };
+    if ((d.mode & 0o022) !== 0)
+        return { problem: `its folder ${dir} can be written by others than Mason's user (mode ${octal(d.mode)})`, fix: `chmod go-w ${dir}, or ${ownFolder}` };
+    return null;
+}
+/**
+ * The folder and the path held to the bar (the header): null when the socket may be made, after a stale one is removed
+ * (`said` is told), or the refusal. Fails closed: a fact it cannot read refuses.
+ */
+export async function prepareUiSocket(file, said, uid = process.getuid()) {
+    const folder = ownFolderProblem(file, "socket", uid);
+    if (folder !== null)
+        return refused(file, folder.problem, folder.fix);
+    let f;
+    try {
+        f = fs.lstatSync(file);
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return null;
+        return refused(file, `it cannot be read: ${e.message}`, "name another path");
+    }
+    const notMine = "remove it yourself if it is not needed, or name another path";
+    if (f.isSymbolicLink())
+        return refused(file, "it is a symbolic link, and Mason never replaces one", notMine);
+    if (!f.isSocket())
+        return refused(file, `it is ${f.isDirectory() ? "a folder" : "a file"}, not a socket, and Mason removes only a socket a run of its own left`, notMine);
+    if (f.uid !== uid)
+        return refused(file, `it is a socket of uid ${f.uid}, not of Mason's user (uid ${uid})`, notMine);
+    const live = await answers(file);
+    if (live === true)
+        return refused(file, "a process answers on it: another Mason, or something else, serves it now", "stop that process, or name another path");
+    if (live instanceof Error)
+        return refused(file, `whether a process answers on it could not be told (${live.message})`, notMine);
+    try {
+        fs.unlinkSync(file);
+    }
+    catch (e) {
+        return refused(file, `the stale socket could not be removed: ${e.message}`, notMine);
+    }
+    said(`replaced the socket a run that did not stop left at ${file}`);
+    return null;
+}
+/**
+ * Listens on `file` (`prepareUiSocket` first) with mode 0600 from the moment it exists (the umask around the bind),
+ * checked after. Until `attach`, a request is answered 503, as /healthz says starting; then each one is the run's
+ * server's own request, behind its guard.
+ */
+export async function listenOnUiSocket(file, said, uid = process.getuid()) {
+    let run = null;
+    const server = http.createServer((req, res) => {
+        if (run !== null) {
+            run.emit("request", req, res);
+            return;
+        }
+        res.writeHead(503, { "Content-Type": "text/plain; charset=utf-8", "Cache-Control": "no-store" }).end("Mason is starting: the page answers once it does\n");
+    });
+    const before = process.umask(0o177);
+    let listening;
+    try {
+        listening = new Promise((resolve) => { server.once("error", resolve); server.listen(file, () => resolve(null)); });
+    }
+    finally {
+        process.umask(before);
+    }
+    const err = await listening;
+    if (err !== null)
+        return refused(file, `the socket cannot be made: ${err.message}`, "name a path in a folder only Mason's user can write");
+    let made;
+    try {
+        fs.chmodSync(file, 0o600);
+        made = fs.lstatSync(file);
+    }
+    catch (e) {
+        server.close();
+        return refused(file, `the socket's mode cannot be set: ${e.message}`, "name a path in a folder only Mason's user can write");
+    }
+    if (!made.isSocket() || made.uid !== uid || (made.mode & 0o777) !== 0o600) {
+        server.close();
+        return refused(file, `the socket is not Mason's alone once made (mode ${octal(made.mode)}, uid ${made.uid})`, "name a path in a folder only Mason's user can write");
+    }
+    let closed = false;
+    return {
+        file,
+        attach: (r) => { run = r; },
+        close: () => {
+            if (closed)
+                return;
+            closed = true;
+            server.close();
+            server.closeAllConnections();
+            // the listening socket is unlinked as it closes; whatever is still at the path is removed only when it is this one
+            try {
+                const now = fs.lstatSync(file);
+                if (now.isSocket() && now.ino === made.ino && now.dev === made.dev)
+                    fs.unlinkSync(file);
+            }
+            catch (e) {
+                if (e.code !== "ENOENT")
+                    said(`the web page's socket ${file} could not be removed: ${e.message}`);
+                return;
+            }
+            said(`removed the web page's socket ${file}`);
+        },
+    };
+}

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

@@ -32,7 +32,7 @@ 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 { errorJson, failureCode, nextJson } from "./command.js";
 import { holdRun, RunUnreachable } from "./control.js";
 import { whereIs } from "./state.js";
 import { lastLines } from "./tunnel.js";
@@ -335,7 +335,7 @@ function refusal(h, target) {
         : 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 };
+    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) {
@@ -381,7 +381,7 @@ export function openSshTunnel(o) {
             };
             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}` }),
+                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