@mason-data/cli 0.8.0 → 0.10.0

package/dist/src/cli/secret-input.js

@@ -0,0 +1,193 @@
+/**
+ * A SECRET READ FROM THE PERSON OR THE PIPE, NEVER FROM A FLAG, AN ARGUMENT OR A FILE (`mason replica create`'s database
+ * URL, issue 720): on a terminal a hidden prompt, otherwise stdin read whole. Node's own TTY handling, no dependency.
+ *
+ *   - THE PROMPT (stdin a terminal): the question on stderr, stdin in raw mode, so the terminal echoes nothing and keeps
+ *     no line of it; each key is read here. Enter ends it; Ctrl-C, or Ctrl-D or Enter on an empty line, cancels; Backspace
+ *     and Ctrl-U edit; a terminal's escape sequences (a bracketed paste's markers, an arrow) are dropped. The terminal is
+ *     put back as it was on EVERY way out — the answer, a cancel, an error of the stream, its end, a signal (SIGINT,
+ *     SIGTERM, SIGHUP while raw mode keeps Ctrl-C from being one), and the process's exit.
+ *   - THE PIPE (stdin not a terminal): read whole, bounded at `max` bytes and by a time limit (a pipe left open and
+ *     silent never holds the command), one trailing newline (`\n` or `\r\n`) trimmed; more than one line is refused.
+ *
+ * Nothing read is ever written anywhere by this module: what went wrong is said by kind, never by value.
+ */
+import { StringDecoder } from "node:string_decoder";
+const SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
+/**
+ * THE HIDDEN PROMPT: `question` on `output` (stderr), a line read from `input` (a terminal) in raw mode, echoing nothing.
+ * At most `max` characters are kept; a longer line is read to its end (so nothing of it is left for the shell to echo)
+ * and refused.
+ */
+export function readHidden(input, output, question, max, signals = process) {
+    return new Promise((resolve, reject) => {
+        const wasRaw = input.isRaw === true;
+        const decoder = new StringDecoder("utf8");
+        let line = [];
+        let tooLong = false;
+        let escape = "";
+        let ended = false;
+        const restore = () => { if (!wasRaw)
+            input.setRawMode?.(false); };
+        const finish = (r) => {
+            if (ended)
+                return;
+            ended = true;
+            input.removeListener("data", onData);
+            input.removeListener("end", onEnd);
+            input.removeListener("close", onEnd);
+            input.removeListener("error", onError);
+            for (const s of SIGNALS)
+                signals.removeListener(s, onSignal);
+            signals.removeListener("exit", restore);
+            try {
+                restore();
+            }
+            finally {
+                input.pause();
+                // the person's Enter was not echoed: the next line starts on a line of its own
+                output.write("\n");
+                line = [];
+                if (r instanceof Error)
+                    reject(r);
+                else
+                    resolve(r);
+            }
+        };
+        const onSignal = () => finish({ none: "cancelled" });
+        const onEnd = () => finish({ none: line.length ? "closed" : "cancelled" });
+        const onError = (e) => finish(e);
+        const onData = (chunk) => {
+            const text = typeof chunk === "string" ? chunk : decoder.write(chunk);
+            for (const c of text) {
+                if (ended)
+                    return;
+                // a terminal's escape sequence (an arrow, a bracketed paste's markers, a title report): dropped whole
+                if (escape === "esc") {
+                    escape = c === "[" ? "csi" : c === "]" ? "osc" : "";
+                    continue;
+                }
+                if (escape === "csi") {
+                    if (c >= "@" && c <= "~")
+                        escape = "";
+                    continue;
+                }
+                if (escape === "osc") {
+                    if (c === "\x07" || c === "\x1b")
+                        escape = "";
+                    continue;
+                }
+                if (c === "\x1b") {
+                    escape = "esc";
+                    continue;
+                }
+                if (c === "\r" || c === "\n") {
+                    finish(tooLong ? { none: "too_long" } : line.length === 0 ? { none: "empty" } : { value: line.join("") });
+                    return;
+                }
+                if (c === "\x03") {
+                    finish({ none: "cancelled" });
+                    return;
+                }
+                if (c === "\x04") {
+                    if (line.length === 0 && !tooLong) {
+                        finish({ none: "cancelled" });
+                        return;
+                    }
+                    continue;
+                }
+                if (c === "\x7f" || c === "\b") {
+                    line.pop();
+                    continue;
+                }
+                if (c === "\x15") {
+                    line = [];
+                    tooLong = false;
+                    continue;
+                }
+                if (c < " ")
+                    continue;
+                if (line.length >= max) {
+                    tooLong = true;
+                    continue;
+                }
+                line.push(c);
+            }
+        };
+        try {
+            if (input.setRawMode === undefined)
+                throw new Error("stdin is a terminal that cannot turn its echo off");
+            // the question first, then echo off: nothing typed before it is shown as asked
+            output.write(question);
+            input.setRawMode(true);
+            for (const s of SIGNALS)
+                signals.on(s, onSignal);
+            signals.on("exit", restore);
+            input.on("data", onData);
+            input.on("end", onEnd);
+            input.on("close", onEnd);
+            input.on("error", onError);
+            input.resume();
+        }
+        catch (e) {
+            finish(e instanceof Error ? e : new Error(String(e)));
+        }
+    });
+}
+/**
+ * THE PIPE: `input` read whole, at most `max` bytes after one trailing newline is trimmed, within `timeoutMs`. Empty,
+ * more than one line, longer than `max`, or nothing by the time limit, each said by kind.
+ */
+export function readPiped(input, max, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let bytes = 0;
+        let ended = false;
+        const finish = (r) => {
+            if (ended)
+                return;
+            ended = true;
+            clearTimeout(timer);
+            input.removeListener("data", onData);
+            input.removeListener("end", onEnd);
+            input.removeListener("error", onError);
+            input.pause();
+            if (r instanceof Error)
+                reject(r);
+            else
+                resolve(r);
+        };
+        const timer = setTimeout(() => finish({ none: "timeout" }), timeoutMs);
+        // the newline a shell's echo or a file ends with is not the URL's: room for it, then the bound
+        const most = max + 2;
+        const onData = (chunk) => {
+            const b = typeof chunk === "string" ? Buffer.from(chunk, "utf8") : chunk;
+            bytes += b.length;
+            if (bytes > most) {
+                finish({ none: "too_long" });
+                return;
+            }
+            chunks.push(b);
+        };
+        const onEnd = () => {
+            let text = Buffer.concat(chunks).toString("utf8");
+            chunks.length = 0;
+            if (text.endsWith("\r\n"))
+                text = text.slice(0, -2);
+            else if (text.endsWith("\n"))
+                text = text.slice(0, -1);
+            if (text === "")
+                return finish({ none: "empty" });
+            if (/[\r\n]/.test(text))
+                return finish({ none: "lines" });
+            if (Buffer.byteLength(text, "utf8") > max)
+                return finish({ none: "too_long" });
+            finish({ value: text });
+        };
+        const onError = (e) => finish(e);
+        input.on("data", onData);
+        input.on("end", onEnd);
+        input.on("error", onError);
+        input.resume();
+    });
+}

package/dist/src/cli/security.js

@@ -26,6 +26,16 @@
  * `mason_dev_<port>`): two runs on one machine each keep their own, and opening one's page never logs the other's out
  * (one name for every run did). A page of another run, or one the token does not match, is refused. Pure over the request's headers, so the refusals are unit-tested
  * (tests/cli-security.test.ts).
+ *
+ * THROUGH A TUNNEL (`mason ui --ssh`, src/cli/ui-ssh.ts): the browser is on another machine, on a local port of its own,
+ * so its Host is 127.0.0.1:<that port>. The guard never takes any other Host: a tunnel is a `PageTunnel`, opened by a
+ * process holding the run's token (`POST /api/ui/tunnel`) and gone with that process's connection, and only the loopback
+ * names at ITS port are added, for as long as it lasts. A DNS-rebinding page still names itself, and is refused by that
+ * name. The run's token never crosses: the laptop gets a TICKET, one use and minutes old, because the URL a browser is
+ * opened at is on a command line; the first request trades it for a cookie holding the tunnel's own SESSION, named for
+ * the laptop's port, which dies with the tunnel. So nothing that reaches the laptop outlives it. The tunnel itself is raw
+ * TCP to this server, so a client chooses its path by the Host it sends: Bearer is refused by a tunnel's Host, and by the
+ * server's own Host it is the commands' path, which needs the token, which never crosses.
  */
 import { randomBytes, timingSafeEqual } from "node:crypto";
 /** The cookie of the run whose server is on `port`: one per run, as a browser shares a host's cookies across ports. */
@@ -44,12 +54,55 @@ export function cookieOf(header, name) {
     }
     return null;
 }
+/** How long a tunnel's ticket can be traded: a person with `--no-open` pastes it; nobody needs it longer. */
+export const TICKET_MS = 5 * 60_000;
+export function newTunnel(port, now = Date.now()) {
+    return { port, ticket: newToken(), ticketUntil: now + TICKET_MS, session: newToken() };
+}
 export function setCookieHeader(token, port) {
     return `${cookieName(port)}=${token}; HttpOnly; SameSite=Strict; Path=/`;
 }
-/** Whether `req` may be served by the server on `port` whose run token is `token`. */
-export function guard(req, port, token) {
-    const hosts = [`127.0.0.1:${port}`, `localhost:${port}`];
+/** The Host a browser may send for a loopback port: its two names, that port, and nothing else. */
+const loopbackHosts = (port) => [`127.0.0.1:${port}`, `localhost:${port}`];
+/** A change must come from the page at `hosts`: its Origin is one of them. */
+function foreignOrigin(req, hosts) {
+    if (req.method === "GET" || req.method === "HEAD")
+        return null;
+    if (req.origin && hosts.map((h) => `http://${h}`).includes(req.origin.toLowerCase()))
+        return null;
+    return { ok: false, status: 403, reason: `a change must come from this page (Origin ${JSON.stringify(req.origin ?? "")})` };
+}
+/** A request by the Host of a tunnel's port (the header says why it is its own path): a ticket, or the session's cookie. */
+function throughTunnel(req, tunnels, now) {
+    const port = tunnels[0].port;
+    if (req.authorization !== undefined)
+        return { ok: false, status: 403, reason: "a tunnel carries a browser, never a command: the run's token is not sent through one" };
+    const cookie = cookieOf(req.cookie, cookieName(port));
+    const held = cookie !== null && tunnels.some((t) => sameSecret(t.session, cookie));
+    const url = new URL(req.url, "http://tunnel");
+    const offered = url.searchParams.get("ticket");
+    if (offered !== null && (req.method === "GET" || req.method === "HEAD")) {
+        url.searchParams.delete("ticket");
+        const location = url.pathname + (url.search || "") + url.hash;
+        const t = tunnels.find((x) => x.ticket !== null && now < x.ticketUntil && sameSecret(x.ticket, offered));
+        if (t !== undefined) {
+            t.ticket = null;
+            return { ok: false, status: 303, location, setCookie: setCookieHeader(t.session, port) };
+        }
+        if (held)
+            return { ok: false, status: 303, location };
+        return { ok: false, status: 403, reason: "this ticket was used already, or is too old: mason ui --ssh gives a new one" };
+    }
+    if (!held)
+        return { ok: false, status: 403, reason: "this tunnel's page takes its ticket or its cookie: mason ui --ssh opens it" };
+    return foreignOrigin(req, loopbackHosts(port)) ?? { ok: true };
+}
+/** Whether `req` may be served by the server on `port` whose run token is `token`, `tunnels` the ones open now. */
+export function guard(req, port, token, tunnels = [], now = Date.now()) {
+    const hosts = loopbackHosts(port);
+    const through = tunnels.filter((t) => loopbackHosts(t.port).includes((req.host ?? "").toLowerCase()));
+    if (through.length > 0 && !hosts.includes((req.host ?? "").toLowerCase()))
+        return throughTunnel(req, through, now);
     if (!req.host || !hosts.includes(req.host.toLowerCase())) {
         return { ok: false, status: 421, reason: `this server answers only as ${hosts[0]} (the request named ${JSON.stringify(req.host ?? "")})` };
     }
@@ -70,13 +123,7 @@ export function guard(req, port, token) {
     if (cookie === null || !sameSecret(cookie, token)) {
         return { ok: false, status: 403, reason: "this is mason start's command server for the mason command: a request carries the run's token (Authorization: Bearer, from .mason/config.json)" };
     }
-    if (req.method !== "GET" && req.method !== "HEAD") {
-        const own = hosts.map((h) => `http://${h}`);
-        if (!req.origin || !own.includes(req.origin.toLowerCase())) {
-            return { ok: false, status: 403, reason: `a change must come from this page (Origin ${JSON.stringify(req.origin ?? "")})` };
-        }
-    }
-    return { ok: true };
+    return foreignOrigin(req, hosts) ?? { ok: true };
 }
 /** The headers every response of a guarded server carries. */
 export const SECURITY_HEADERS = {

package/dist/src/cli/serve.js

@@ -17,15 +17,20 @@
  *     (counts, lag, ages, sizes) for the same reason: never a table's, a user's or a host's name, never a statement.
  *   - A CLEAN STOP ON SIGTERM: the run's own stop (a copy in flight interrupted and rolled back, DuckDB closed).
  *
+ *   - ITS WEB PAGE ON LOOPBACK ALONE (src/cli/run-server.ts `listenOnLoopback`): the run's server, MASON_UI_PORT, reached
+ *     from a developer's machine with `mason ui --ssh`, never published. No setting moves it to another address.
+ *
  * The commands beside it work as on a laptop, in the data folder: `docker compose exec mason mason add orders`.
  */
 import * as fs from "node:fs";
 import * as http from "node:http";
 import * as path from "node:path";
 import { failed, parseCommand } from "./command.js";
+import { DEFAULT_UI_PORT, heldText, portHolder } from "./ports.js";
+import { pgListenerAddress } from "../api/postgres/listener.js";
 import { dev } from "./dev.js";
 import { parseSource } from "./preflight.js";
-import { NAME_RE, newConfig, readProject, STATE_DIR, writeConfig } from "./project.js";
+import { NAME_RE, newConfig, projectReadOnlySetting, projectWriteRefusal, readProject, STATE_DIR, writeConfig } from "./project.js";
 import { newSourceText, OLD_TABLES_DIR, parseSourceText, readSource, sourceFileNames, sourceNameFor, sourcesDir, sourcesTop, writtenDatabase } from "./sources.js";
 import { connectDatabase, DATABASE_SETTING, databaseNameProblem } from "../lib/database-name.js";
 import { appEnvValue } from "../lib/dotenv.js";
@@ -34,6 +39,8 @@ import { commandPinProblem } from "./pin.js";
 import { recordRefusal } from "./replication-mode.js";
 import { changesRetiredText, pollMsRetiredText } from "../lib/table-sync.js";
 import { historyDaysSetting, historyDaysWrongText } from "../duck/history.js";
+import { DEFAULT_MEMORY_RULE, memoryProblems, memoryProblemText, memorySize, MEMORY_FLOOR_BYTES } from "../duck/store.js";
+import { wrap } from "./style.js";
 import { runningVersion, version } from "./version.js";
 import { phaseCounts } from "./readiness.js";
 import { METRICS_CONTENT_TYPE, metricsText } from "./metrics.js";
@@ -47,11 +54,13 @@ export const SERVE = {
   GET /metrics for Prometheus (numbers only: no name, no statement), and a clean stop on SIGTERM. The tables it
   syncs are the ones the project folder's sources file names (sources/<name>.yml): make it with mason init and mason
   add on a laptop and commit it, or with mason add beside the running server. A project folder with no sources file
-  gets one, url: \${DATABASE_URL}, with no table yet.
+  gets one, url: \${DATABASE_URL}, with no table yet — unless MASON_PROJECT_READONLY=1, which writes none.
 
     DATABASE_URL=postgres://mason:…@db.internal:5432/app MASON_API_KEY=… mason serve
     docker compose exec mason mason add public.orders     beside it, in its container
 
+  --json   a refusal to start as data: { error, next }; once it serves, its output is its log
+
   Settings (the environment):
     DATABASE_URL            the database to sync from, as the sources file's url: \${DATABASE_URL} names it (the variable
                             the file names is required); read-only: SELECTs, or a replication slot
@@ -60,25 +69,36 @@ export const SERVE = {
                             this one), else this; default none: Mason makes its own
     MASON_API_KEY           what the users' passwords are made with (mason user add), at least 32 characters (required)
     MASON_PROJECT           the project folder: sources/, mason.yml (default ./mason)
+    MASON_PROJECT_READONLY  1 when the project folder is deployed as committed (CI, GitOps, a platform that deploys
+                            the folder): every edit of its files is refused — mason add and mason remove, beside it or
+                            on the web page — and says to edit the files and deploy them (default 0)
     MASON_DATA              the folder whose .mason/ holds the synced data and the state: the volume (default .)
     MASON_NAME              the project's name, which the replication slot is named for (default mason); renaming it
                             over the same synced data is refused
     MASON_PG_DATABASE       the database name a tool connects with, for a sources file with no database: (default mason;
                             the two must agree when both are set)
     MASON_HEALTH_PORT       /healthz's and /metrics' port (default 4140), on MASON_HEALTH_HOST (default 0.0.0.0)
+    MASON_UI_PORT           the web page's and the commands' port, on 127.0.0.1 alone: no setting moves the address, and
+                            mason ui --ssh <user@server> opens the page from your machine (default ${DEFAULT_UI_PORT}, or the next
+                            free one; a port named here is that port, or the start is refused)
     MASON_PG_HOST, MASON_PG_PORT   the Postgres API's address (default 127.0.0.1:5433)
     MASON_PG_TLS_CERT, MASON_PG_TLS_KEY   its certificate, required off loopback; or MASON_PG_SELF_SIGNED_TLS=1
                             for one made in .mason/, or MASON_PG_PLAIN=1 behind a TLS proxy of your own
-    MASON_DUCKDB_MEMORY     the engine's memory, 4GB or 512MiB (default half the container's memory limit, else half the
-                            machine's RAM; mason doctor says it); a statement past it fails alone with 53200
+    MASON_PG_PROXY_FROM     behind a TCP proxy or load balancer that sends the PROXY protocol v2: its own addresses,
+                            CIDRs comma-separated (10.0.0.0/16); a connection from one must begin with a header, whose
+                            client the request log names; a header from any other address is refused (default unset:
+                            none is read)
+    MASON_DUCKDB_MEMORY     ${wrap(`the engine's memory, 4GB or 512MiB (default ${DEFAULT_MEMORY_RULE}; mason doctor says it); a statement past it fails alone with 53200. Unset, under ${memorySize(MEMORY_FLOOR_BYTES)} Mason starts and warns: the system may stop it`, 120, 28)}
+    MASON_SPILL_LIMIT       what statements may spill to disk, 40GB or 512MiB (default half of what is free, followed as
+                            the disk fills; never past 90% of it); a statement past it fails alone with 53400
     MASON_STATEMENT_TIMEOUT   each statement's limit, as Postgres's statement_timeout (default 5min; 0 for none)
     MASON_HISTORY_DAYS      how many days Mason keeps its history: the request log, the sync's events, the usage
                             samples and the synced tables' sizes (default 7)
     MASON_STORE_JSON_PATHS  on (the default) stores the JSON paths statements keep reading as columns; off stores none
     MASON_COPY_PARALLEL     a first sync's chunks read at once, each a backend on the database (1 to 8, default 3)
     MASON_COPY_CHUNK_SECONDS   how long each chunk takes to read, at the rate measured (1 to 300, default 12)
-
-  --json   a refusal to start as data: { error, next }; once it serves, its output is its log
+    UV_THREADPOOL_SIZE      threads for running statements, one each, 1 to 1024 (default 32, lowered to fit a limit
+                            on threads; one that does not fit, or is no such number, refuses the start)
 
   Exit status: 0 stopped by SIGTERM or SIGINT; 1 it could not start (said); 2 a wrong command line.
 `,
@@ -86,6 +106,11 @@ export const SERVE = {
     json: ["next"],
 };
 const MIN_API_KEY = 32;
+/** The Postgres API's port as the settings say it; null while MASON_PG_PORT is wrong, which the run's own check says. */
+function pgPortOf(env) {
+    const a = pgListenerAddress(env, "127.0.0.1");
+    return "problem" in a ? null : a.port;
+}
 /** THE SETTINGS, OR EVERY ONE MISSING OR WRONG AT ONCE: a platform's deploy is slow, and one variable a deploy wastes it. */
 export function serveSettings(env, cwd) {
     const wrong = [];
@@ -116,6 +141,13 @@ export function serveSettings(env, cwd) {
     const days = historyDaysSetting(env);
     if (typeof days !== "number")
         wrong.push(historyDaysWrongText(days));
+    // MASON_DUCKDB_MEMORY not an amount (src/duck/store.ts memoryProblems), said here with the rest, before anything is
+    // written or connected; a container under the floor starts, and the run warns (memoryWarning)
+    wrong.push(...memoryProblems(env).map(memoryProblemText));
+    // the project's files deployed read-only (src/cli/project.ts projectWriteRefusal): 1 or 0, anything else refused here
+    const readOnly = projectReadOnlySetting(env);
+    if (typeof readOnly !== "boolean")
+        wrong.push(readOnly.problem);
     const selfSigned = env.MASON_PG_SELF_SIGNED_TLS || "0";
     if (selfSigned !== "0" && selfSigned !== "1")
         wrong.push(`MASON_PG_SELF_SIGNED_TLS=${JSON.stringify(selfSigned)}: 1, or 0 (the default)`);
@@ -123,6 +155,17 @@ export function serveSettings(env, cwd) {
     const port = Number(portText);
     if (!/^\d+$/.test(portText) || port < 1 || port > 65_535)
         wrong.push(`MASON_HEALTH_PORT=${JSON.stringify(portText)}: a port number, 1-65535`);
+    const uiText = env.MASON_UI_PORT || String(DEFAULT_UI_PORT);
+    const uiPort = Number(uiText);
+    if (!/^\d+$/.test(uiText) || uiPort < 1 || uiPort > 65_535)
+        wrong.push(`MASON_UI_PORT=${JSON.stringify(uiText)}: a port number, 1-65535`);
+    else if (env.MASON_UI_PORT && uiPort === port)
+        wrong.push(`MASON_UI_PORT=${uiText} is MASON_HEALTH_PORT too: two ports`);
+    else if (env.MASON_UI_PORT && uiPort === pgPortOf(env))
+        wrong.push(`MASON_UI_PORT=${uiText} is the Postgres API's port too (MASON_PG_PORT): two ports`);
+    // a host would only be believed: the page has no address but loopback, and running on while one is asked for would hide that
+    if (env.MASON_UI_HOST)
+        wrong.push("MASON_UI_HOST is set, and the web page has no address but 127.0.0.1: remove it (mason ui --ssh <user@server> opens the page from your machine)");
     if (wrong.length) {
         return { message: `${wrong.length === 1 ? "a setting is" : `${wrong.length} settings are`} missing or wrong: ${wrong.join("; ")}`, code: "bad_config",
             why: "mason serve reads its settings from the environment, and asks nothing",
@@ -133,6 +176,7 @@ export function serveSettings(env, cwd) {
         name, apiKey, selfSignedTls: selfSigned === "1",
         project, data,
         health: { host: env.MASON_HEALTH_HOST || "0.0.0.0", port },
+        ui: { port: uiPort, named: !!env.MASON_UI_PORT },
     };
 }
 /**
@@ -186,8 +230,8 @@ function urlSettingProblems(project, data, env) {
     const found = appEnvValue(data, variable, env, { shellFirst: true });
     if (found === null)
         return [`${variable} is not set: the database to sync from, as the sources file's url: \${${variable}} names it`];
-    const p = parseSource(found.value);
-    return "problem" in p ? [`${variable}: ${p.problem}`] : [];
+    const p = parseSource(found.value, variable);
+    return "problem" in p ? [p.problem] : [];
 }
 /**
  * THE CONFIG A SERVE RUNS ON, written from its settings at every start, over what the runs before recorded (the server
@@ -247,6 +291,14 @@ export function serveSource(s, env) {
                 fix: "set DATABASE_URL=postgres://user:password@host:5432/app (the sources file mason init writes names it), or mount the project folder with its sources/ (MASON_PROJECT)",
                 next: [["mason serve --help", "every setting, with its default"]] };
         }
+        // a deployed project's files are its commit's (src/cli/project.ts projectWriteRefusal: this serve's own environment
+        // decides, the config not written yet): a folder deployed without its sources file is said, never filled in
+        const readOnly = projectWriteRefusal(null, env);
+        if (readOnly !== null) {
+            return { ...readOnly, message: `the project folder (${s.project}) has no sources file, and ${readOnly.message}`,
+                fix: "edit the files and deploy them: mason init and mason add where the project is committed write its sources file; commit it, and deploy the folder with it",
+                next: [["mason serve --help", "every setting, with its default"]] };
+        }
         const p = parseSource(url);
         const file = path.join(sourcesDir(s.project), `${sourceNameFor("source" in p ? p.source.database : "")}.yml`);
         try {
@@ -365,6 +417,10 @@ export async function serve(argv) {
         return failed("serve", { message: `the state cannot be written to ${path.join(s.data, STATE_DIR)}: ${e.message}`, code: "refused",
             fix: "MASON_DATA names a folder this user can write: the volume's mount point" }, { json });
     }
+    // a port named is that port: said here, before anything listens, as the next free one would hide the setting
+    const held = s.ui.named ? await portHolder(s.ui.port) : null;
+    if (held !== null)
+        return failed("serve", { message: `MASON_UI_PORT: ${heldText(s.ui.port, held)}`, code: "refused", fix: "name another port, or leave MASON_UI_PORT unset for the next free one" }, { json });
     const startedAt = Date.now();
     let state = { phase: "starting" };
     const health = healthServer(() => state, startedAt);
@@ -388,7 +444,7 @@ export async function serve(argv) {
     process.chdir(s.data);
     let code;
     try {
-        code = await dev({ port: 4039, version: version(), selfSignedTls: s.selfSignedTls,
+        code = await dev({ port: s.ui.port, exactPort: s.ui.named, version: version(), selfSignedTls: s.selfSignedTls,
             serve: { log: say, ready: (run) => { state = { phase: "ready", tables: run.tables, metrics: run.metrics }; }, stopping: () => { state = { phase: "stopping" }; } } });
     }
     finally {

package/dist/src/cli/share-run.js

@@ -12,7 +12,8 @@
  * is enough: the password is 192 random bits, nothing to guess). It is no row of `.mason/users.json`, because that file
  * outlives a process and a share must not: a run that dies takes it along.
  * Only `authenticate` below reads this list, and only the share's socket asks it: the password is refused on the
- * run's own listener by nobody knowing it, and a `mason user` or a token here by the same.
+ * run's own listener by nobody knowing it, and a `mason user` or a token here by the same; each is told so by its shape,
+ * which names what was given and where it works, and decides nothing.
  *
  * A LOGIN REFUSED HERE IS LOGGED WITH NO SOURCE: every connection through a tunnel comes from 127.0.0.1, so naming
  * one would be naming the tunnel's client. The log is written once a minute at most (a scanner's rate is anyone's), with
@@ -23,12 +24,15 @@ import { execFile } from "node:child_process";
 import { ApiError } from "../api/error.js";
 import { didYouMean } from "../lib/did-you-mean.js";
 import { missingAttributes } from "../duck/row-filter.js";
+import { isToken } from "../duck/token.js";
+import { isUserPassword, SHARE_PASSWORD_PREFIX } from "../duck/users.js";
 import { ROLE_NAME_RE, ROLE_NAME_RULE, ROLES_FILE } from "./roles.js";
 import { sameSecret } from "./security.js";
 /** What the password is stored and sent as: its SHA-256, hex. */
 export const shareSecret = (password) => crypto.createHash("sha256").update(password).digest("hex");
-/** The new password `mason share` prints once: 192 random bits, in characters every form and URL takes. */
-export const newSharePassword = () => crypto.randomBytes(24).toString("hex");
+/** The new password `mason share` prints once: `mason_share_` and 192 random bits as 48 hex digits, in characters every
+ *  form and URL takes. Recognisably Mason's and apart from a user's (`isUserPassword`, src/duck/users.ts) and a token's. */
+export const newSharePassword = () => `${SHARE_PASSWORD_PREFIX}${crypto.randomBytes(24).toString("hex")}`;
 /** How often a refused login is written to the log, at most: the rest are counted. */
 const REFUSED_LOG_MS = 60_000;
 /** How many refused logins a minute are rows of the request log, at most: the rest are counted (`mason status`), so a
@@ -58,6 +62,11 @@ export function tunnelReport(body) {
     return { ...(via !== undefined ? { via } : {}), ...(host !== undefined ? { host } : {}), ...(port !== undefined ? { port } : {}),
         ...(endsAt !== undefined ? { endsAt } : {}), ...(state !== undefined ? { state } : {}), ...(pid !== undefined ? { pid } : {}) };
 }
+/** How each holder ends its share, as a refusal names it. */
+const HOW_TO_END = {
+    command: ["mason share", "Ctrl-C in the terminal running mason share ends it"],
+    page: ["the web page", "Stop sharing on the web page's Overview ends it (mason ui opens the page)"],
+};
 /** What a role reads, in a line. */
 function readsText(g) {
     if (g.all)
@@ -155,15 +164,24 @@ export class RunShares {
     dropped = 0;
     lastSaid = -Infinity;
     unsaid = 0;
+    lastEnded = null;
     constructor(deps) { this.deps = deps; }
     /** Opens a share: the socket when none is open, and a login of its own. Refused: the failure, with the choices when a role is what is missing. */
     async open(ask) {
+        const from = ask.from ?? "command";
+        const busy = this.busy(from);
+        if (busy !== null)
+            return { failure: busy };
         const role = shareRole(ask.role, await this.deps.listener.checkRoles());
         if ("failure" in role)
             return role;
+        // asked again after the wait: a share opened meanwhile is one too many
+        const raced = this.busy(from);
+        if (raced !== null)
+            return { failure: raced };
         const user = `share_${crypto.randomBytes(3).toString("hex")}`;
         // in the list before the first wait, so a share ending meanwhile does not close the socket under this one
-        this.held.set(user, { user, secret: ask.secret, role: role.role, reads: role.reads, openedAt: new Date().toISOString(), tunnel: { state: "opening" }, ended: null });
+        this.held.set(user, { user, from, secret: ask.secret, role: role.role, reads: role.reads, openedAt: new Date().toISOString(), tunnel: { state: "opening" }, ended: null });
         let socket, fingerprint;
         try {
             const made = this.socket ?? this.openSocket();
@@ -184,6 +202,29 @@ export class RunShares {
         this.deps.log(`share: ${user} opened, reading ${role.role === null ? "every synced table (no roles file)" : `as the role ${role.role}`}, TLS required on 127.0.0.1:${socket.port}`);
         return { user, port: socket.port, fingerprint, database: this.deps.database, role: role.role, reads: role.reads };
     }
+    /**
+     * ONE SHARE AT A TIME BETWEEN THE PAGE AND THE COMMAND: the page's share is refused while any share is open, and any
+     * share while the page's is (two `mason share`s still meet one socket, as before). The refusal names the share open
+     * and how its holder ends it. null: it may open.
+     */
+    busy(from) {
+        const open = [...this.held.values()].find((h) => from === "page" || h.from === "page");
+        if (open === undefined)
+            return null;
+        const [who, how] = HOW_TO_END[open.from];
+        return { message: `a share is open already: ${open.user}, opened by ${who}${open.tunnel.host !== undefined ? ` at ${open.tunnel.host}:${open.tunnel.port}` : ""}`, code: "refused",
+            why: "one share at a time between the web page and mason share: each is a public address someone must be watching", fix: `${how}, then share again`,
+            next: [["mason status", "the share open now"]] };
+    }
+    /** What a share with no role named reads (`shareRole`'s answer, the one authority): the web page asks it before it asks
+     *  the person, to offer the roles as `mason share` would. */
+    async choices() {
+        return shareRole(undefined, await this.deps.listener.checkRoles());
+    }
+    /** Who holds a share: null when none is open by that name. */
+    fromOf(user) { return this.held.get(user)?.from ?? null; }
+    /** The last share that ended, and why (`/api/state` `shareEnded`). */
+    get ended() { return this.lastEnded; }
     openSocket() {
         const cert = this.deps.certificate();
         if ("message" in cert)
@@ -199,10 +240,11 @@ export class RunShares {
         return { opening, fingerprint: cert.fingerprint };
     }
     authenticate(password, user) {
-        const given = shareSecret(password);
-        const found = [...this.held.values()].find((h) => sameSecret(h.secret, given));
+        const secret = shareSecret(password);
+        const found = [...this.held.values()].find((h) => sameSecret(h.secret, secret));
         if (found === undefined || found.user !== user) {
-            const refused = new ApiError(401, "not this share's password", "invalid_share");
+            const given = isUserPassword(password) ? "a mason user's password" : isToken(password) ? "an API token" : null;
+            const refused = new ApiError(401, given === null ? "not this share's password" : `that is ${given}: it logs in on the run's own port, never at a share's address`, "invalid_share");
             refused.userName = user;
             throw refused;
         }
@@ -253,6 +295,7 @@ export class RunShares {
         if (h === undefined)
             return;
         this.held.delete(user);
+        this.lastEnded = { user, from: h.from, why, at: new Date().toISOString() };
         const opening = this.socket?.opening;
         if (opening === undefined)
             return;
@@ -280,7 +323,7 @@ export class RunShares {
         if (this.socket === null || this.live === null)
             return null;
         return { port: this.live.port, fingerprint: this.socket.fingerprint, sessions: this.live.sessions, refusedLogins: this.refused, droppedConnections: this.dropped,
-            shares: [...this.held.values()].map((h) => ({ user: h.user, role: h.role, reads: h.reads, openedAt: h.openedAt, via: h.tunnel.via ?? null, host: h.tunnel.host ?? null, port: h.tunnel.port ?? null,
+            shares: [...this.held.values()].map((h) => ({ user: h.user, from: h.from, role: h.role, reads: h.reads, openedAt: h.openedAt, via: h.tunnel.via ?? null, host: h.tunnel.host ?? null, port: h.tunnel.port ?? null,
                 endsAt: h.tunnel.endsAt ?? null, state: h.tunnel.state ?? "opening" })) };
     }
 }