@mason-data/cli 0.8.0 → 0.9.0

package/dist/src/cli/replica.js

@@ -0,0 +1,76 @@
+import { environmentToken, readLogins, TOKEN_ENV } from "./credentials.js";
+import { isFailure, serviceText, whoAmI } from "./hosted.js";
+/** What one part of a replica's name may be: an organisation's slug, a replica's name. */
+export const REPLICA_PART = /^[a-z0-9][a-z0-9-]{0,62}$/;
+export const REPLICA_ENV = "MASON_REPLICA";
+export const replicaText = (r) => `${r.org}/${r.name}`;
+/** The replica the command means: `--replica`, else `MASON_REPLICA`; null when neither names one, a Failure when it is
+ *  not `<org>/<name>` (never repeated beyond 200 characters, made printable). `usage`: the command's, said after a wrong
+ *  `--replica`. */
+export function replicaOf(flag, usage, env = process.env) {
+    const from = flag !== undefined ? "--replica" : env[REPLICA_ENV] !== undefined ? REPLICA_ENV : null;
+    if (from === null)
+        return null;
+    return replicaNamed((from === "--replica" ? flag : env[REPLICA_ENV]) ?? "", from, usage);
+}
+/** `raw` as a replica's name, `<org>/<name>`, each part `REPLICA_PART`: the one grammar of `--replica`, `MASON_REPLICA`
+ *  and a command's own argument (`mason replica status <org>/<name>`); a Failure otherwise, a wrong line's (`usage`)
+ *  unless the environment named it. */
+export function replicaNamed(raw, from, usage) {
+    const parts = raw.split("/");
+    if (parts.length === 2 && REPLICA_PART.test(parts[0]) && REPLICA_PART.test(parts[1]))
+        return { org: parts[0], name: parts[1], from };
+    const named = from === "argument" ? "the replica" : from;
+    return { message: `${named} ${JSON.stringify(serviceText(raw, 200))} is not <org>/<name>`, code: from === REPLICA_ENV ? "refused" : "usage",
+        why: "an organisation's slug and a replica's name, each 1 to 63 lower case letters, digits and -, starting with a letter or digit",
+        fix: from === "--replica" ? "name it as the service lists it: --replica acme/shop" : from === "argument" ? "name it as the service lists it: acme/shop (mason replica list)"
+            : `set ${REPLICA_ENV}=<org>/<name> (acme/shop), or unset it and pass --replica`,
+        ...(from === REPLICA_ENV ? {} : { usage }) };
+}
+/** `raw` as an organisation's slug (`REPLICA_PART`: safe in a path as it is), or a wrong line's Failure. */
+export function orgNamed(raw, usage) {
+    if (REPLICA_PART.test(raw))
+        return raw;
+    return { message: `the organisation ${JSON.stringify(serviceText(raw, 200))} is not an organisation's slug`, code: "usage",
+        why: "an organisation's slug is 1 to 63 lower case letters, digits and -, starting with a letter or digit", fix: "name it as the service lists it: acme", usage };
+}
+/** How many organisations a command reads when none is named (`loginOrgs`): past it, it asks for one. */
+export const MAX_ORGS = 20;
+/**
+ * THE ORGANISATIONS A COMMAND ACTS IN WHEN NONE IS NAMED: the login's own, as `GET /v1/me` says them (src/cli/hosted.ts
+ * `whoAmI`, its answer held there), those where its role is one of `roles` (every role when absent), each slug held to
+ * `REPLICA_PART` before it is in a path. A Failure when the service cannot say (a CI token is no person: 403), when a
+ * slug is outside the grammar, or past `MAX_ORGS`; `again` is the command that names one.
+ */
+export async function loginOrgs(service, token, again, roles) {
+    const me = await whoAmI(service, token);
+    const name = [again, "name the organisation"];
+    if (isFailure(me))
+        return { ...me, next: [name, ...(me.next ?? [])] };
+    if (!me.orgs.every((o) => REPLICA_PART.test(o.slug)))
+        return { message: `${service.base} named an organisation whose slug is not one`, code: "failed",
+            why: "a slug is 1 to 63 lower case letters, digits and -: the answer is not the one docs/HOSTED-API.md documents", fix: `name the organisation: ${again}`, next: [name] };
+    const orgs = me.orgs.filter((o) => roles === undefined || roles.includes(o.role)).map((o) => ({ slug: o.slug, role: o.role }));
+    if (orgs.length > MAX_ORGS)
+        return { message: `this login is in ${orgs.length} organisations, more than the ${MAX_ORGS} a command reads when none is named`, code: "refused",
+            fix: `name the organisation: ${again}`, next: [name] };
+    return orgs;
+}
+/**
+ * The token a request to a replica is sent with: MASON_TOKEN, else this machine's login to the service; a Failure naming
+ * mason login. `asked`: what the command sends, in its words ("a deploy is sent"); `again`: the command to run once
+ * signed in ("mason deploy").
+ */
+export function tokenFor(service, o) {
+    const env = environmentToken();
+    if (env !== null)
+        return env;
+    const read = readLogins();
+    if (isFailure(read))
+        return read;
+    const saved = read.logins.logins[service.base];
+    if (saved !== undefined)
+        return saved.token;
+    return { message: `this machine is not signed in to ${service.base}`, code: "refused", why: `${o.asked} as a person signed in (mason login), or with a token in ${TOKEN_ENV} (CI)`,
+        fix: `run mason login, then ${o.again} again; in CI, set ${TOKEN_ENV} to a CI token`, next: [["mason login", `sign this machine in to ${service.base}`]] };
+}

package/dist/src/cli/roles.js

@@ -371,7 +371,8 @@ export function roleProblems(roles, copied) {
                 if (typeof th === "string")
                     problems.push(th);
             }
-            if (c.columns === null)
+            // a generated table not built yet: its columns are not known, and the role reads nothing of it until they are
+            if (c.columns === null || c.pending === true)
                 continue;
             const have = c.columns.map((x) => x.name);
             for (const [key, list] of [["columns", t.columns ?? []], ["exclude", t.exclude]]) {

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

@@ -15,7 +15,11 @@
  * THE WEB PAGE (src/web/, `mason ui`, docs/WEB-UI.md): under `mason start` it also serves one page and its files (the
  * shell, its pages' modules, the stylesheet), from an allowlist read when it starts (`pageFiles`), and the users the
  * page manages (`/api/users`, the functions `mason user` calls). The page reads the same JSON the commands read; a refusal carries `failure`, the CLI's Failure
- * shape (message, why, fix, next), so the page says it as the command would. `mason serve`'s run serves no page.
+ * shape (message, why, fix, next), so the page says it as the command would. Under `mason serve` it serves the same page,
+ * on loopback alone, to a browser on another machine through `mason ui --ssh` (src/cli/ui-ssh.ts, `openTunnel` below).
+ *
+ * LOOPBACK BY CONSTRUCTION: `listenOnLoopback` is how this server listens, and it takes no address. No setting names
+ * one, and a container's page is reached from inside the container, never published (docs/WEB-UI.md).
  */
 import * as fs from "node:fs";
 import * as http from "node:http";
@@ -23,7 +27,7 @@ import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { readBody, sendJson } from "../lib/http-json.js";
 import { projectFingerprint } from "../lib/project-files.js";
-import { guard, SECURITY_HEADERS } from "./security.js";
+import { guard, newTunnel, SECURITY_HEADERS } from "./security.js";
 import { maskedUrl } from "./preflight.js";
 import { errorJson, nextJson } from "./command.js";
 import { phaseCounts, readiness, syncTotals, tableSync } from "./readiness.js";
@@ -34,6 +38,7 @@ import { addedNext, addUser, attributesToAdd, disabledNext, disableUser, enabled
 import { userRole } from "./roles.js";
 import { postgresFacts, postgresLink } from "./pg-url.js";
 import { catalogTable, parseSourceText, shownPath } from "./sources.js";
+import { projectWriteRefusal } from "./project.js";
 import { addEntry, Refusal, removeEntries, sourceToEdit } from "./source-edit.js";
 import { PollRefused } from "../duck/sync.js";
 import { DEFAULT_SYNC, parseSync, syncText } from "../lib/table-sync.js";
@@ -73,7 +78,9 @@ export function runState(ctx, copies, stream, now = Date.now(), { columns = fals
                 // copyProgressNow), so mason wait and status move between two commits
                 ...(c.phase === "copying" && c.progress !== undefined ? { progress: c.progress } : {}),
                 ...(c.phase === "copied" && c.retired !== undefined ? { retired: c.retired } : {}) } : null,
-            error: c?.phase === "failed" ? c.error : null,
+            // its sync's error, whatever its phase: a copied table whose poll, catch-up, stream or publication check failed
+            // carries it on its own row, as its sync's state says failed (issue 100)
+            error: c?.error ?? null,
             // how the run keeps the copy current NOW, as the sync derives it once (src/duck/sync.ts KeptCurrent, `keptOf`): its
             // sync and when it was last synced, what mason status and the stream's tables say, and EXPLAIN says over the wire
             ...(c?.kept ? { kept: c.kept } : {}),
@@ -87,12 +94,18 @@ export function runState(ctx, copies, stream, now = Date.now(), { columns = fals
         // what mason wait waits on and mason status prints last (src/cli/readiness.ts): said by the run, so the page and the
         // commands say one thing
         readiness: readiness({ tables }),
-        // the run serves the web page (mason ui): mason status prints its URL
+        // the run serves the web page (mason ui): mason status prints its URL, or on a server how it is opened
         ui: ctx.page,
+        // mason serve's run: the page's words for a tunnel that closed, and for the Postgres URL's host, follow from it
+        served: ctx.served === true,
+        // why the page offers no Add or Remove, or null: the project's files deployed read-only (MASON_PROJECT_READONLY), or
+        // a server's project folder mounted read-only — a control that can only fail is not offered
+        sourcesReadOnly: sourcesReadOnly(ctx, sources.file?.file ?? null),
         source: { url: maskedUrl(ctx.source.url), host: ctx.source.host, database: ctx.source.database, remote: ctx.source.remote, demo: ctx.demo === true,
             // `replication` while a table's sync is replication (the run streams), else `poll`: each table's own is its kept
             version: facts.versionText, standby: facts.standby, changes: repl !== null ? "replication" : "poll", name: sources.file?.name ?? null, file: sources.file?.file ?? null,
             shownFile: sources.file ? shownPath(ctx.root, sources.file.file) : null,
+            ...(ctx.textOrder ? { textOrder: ctx.textOrder } : {}),
             // every table's sync unless its entry says its own: the file's top `sync:`, or the default when it writes none
             sync: { default: syncText(sources.file?.sync ?? DEFAULT_SYNC), written: sources.file?.sync != null },
             ...(repl !== null ? { replication: { slot: repl.slot, publication: repl.publication, owned: repl.owned } } : {}) },
@@ -117,15 +130,38 @@ export function runState(ctx, copies, stream, now = Date.now(), { columns = fals
         sessions: ctx.listener.openSessions(),
         disk: { path: disk.path, freeBytes: disk.freeBytes, copyBytes: bytes, projectedBytes: disk.projectedBytes, ...(disk.error !== undefined ? { error: disk.error } : {}) },
         jsonPaths: ctx.duck.jsonPaths?.() ?? [],
+        generatedTables: ctx.duck.generated?.() ?? [],
         // the roles file as the listener reads it now: its roles by name, and what is wrong with it (every statement of a
         // session with a role is refused while there is)
         ...(ctx.roles ? { roles: rolesState(ctx.roles()) } : {}),
         // the share open now (mason share): where, who, and what was refused there; nothing in it logs anyone in
         share: ctx.shares?.state() ?? null,
+        // the last share that ended and why: a page that held it says so (null before any, and on a server)
+        shareEnded: ctx.shares?.ended ?? null,
         // replication mode: where the stream is, its lag and what it applied (mason status and wait render it, streamLines)
         ...(stream !== null ? { stream } : {}),
     };
 }
+/**
+ * Why the run could not write its sources file now, or null — ONE fact for the page and `mason status --json`, computed
+ * here: first the project's own word (src/cli/project.ts `projectWriteRefusal`, the authority every edit asks, so the page
+ * offers no Add or Remove exactly when `/api/pick` and `/api/remove` would refuse them); then, on a server, a file it
+ * cannot write (a folder mounted read-only). `mason start`'s file is the developer's, and never asked of the disk.
+ */
+function sourcesReadOnly(ctx, file) {
+    const readOnly = projectWriteRefusal(ctx.root, process.env);
+    if (readOnly !== null)
+        return `${readOnly.message}; ${readOnly.fix}`;
+    if (ctx.served !== true || file === null)
+        return null;
+    try {
+        fs.accessSync(file, fs.constants.W_OK);
+        return null;
+    }
+    catch (e) {
+        return `the sources file cannot be written on this server (${e.code ?? e.message}): commit a change to it, and deploy`;
+    }
+}
 /** a file's size, or null where it cannot be read (the run's own DuckDB file: it exists while the run does) */
 function fileBytes(file) {
     try {
@@ -412,6 +448,10 @@ async function openShare(ctx, req, res) {
     }
     const shares = ctx.shares;
     const body = JSON.parse(await readBody(req, 64 * 1024));
+    if (body.from === "page") {
+        await openPageShare(ctx, body, res);
+        return;
+    }
     if (typeof body.secret !== "string" || !/^[0-9a-f]{64}$/.test(body.secret))
         throw new Refusal(400, "send { secret, role? }: the password's SHA-256 in hex");
     if (body.role !== undefined && typeof body.role !== "string")
@@ -434,19 +474,83 @@ async function openShare(ctx, req, res) {
     res.writeHead(200, { "Content-Type": "application/x-ndjson" });
     res.write(`${JSON.stringify(opened)}\n`);
 }
+/** The refusal of a page's share where there is none to open (`mason serve`): the command's own words. */
+const SERVED_SHARE = { message: "this run is on a server, and has an address of its own: mason share is for a run on a laptop", code: "refused", next: [["mason help production", "reaching a server's Postgres API"]] };
+/**
+ * `POST /api/share` { from: "page", confirmed: true, role? }: the web page's Connect from anywhere (src/cli/page-share.ts),
+ * answered ONCE with the share and its password, which nothing here keeps; the page's beats hold it from then on.
+ * `confirmed` is the person's yes to a public address, which the page asks for: a body without it opens nothing.
+ */
+async function openPageShare(ctx, body, res) {
+    if (ctx.pageShares === undefined) {
+        sendFailure(res, 409, SERVED_SHARE);
+        return;
+    }
+    if (body.confirmed !== true) {
+        sendFailure(res, 400, { message: "nothing was shared: a temporary public address is opened only once the person said yes to it", code: "usage", fix: "send { from: \"page\", confirmed: true, role? }: the page's Connect from anywhere asks first" });
+        return;
+    }
+    if (body.role !== undefined && typeof body.role !== "string")
+        throw new Refusal(400, "role is a role's name, or left out");
+    const r = await ctx.pageShares.open({ role: body.role });
+    if ("failure" in r) {
+        sendFailure(res, statusOf(r.failure), r.failure, r.choices ? { choices: r.choices } : {});
+        return;
+    }
+    sendJson(res, 200, r);
+}
+/**
+ * `POST /api/ui/tunnel` { port }: a tunnel to the page (src/cli/security.ts, src/cli/ui-ssh.ts), its ticket in the first
+ * line of JSON and THE ANSWER LEFT OPEN, as a share's is: the connection is the tunnel, so its bridge gone by any means
+ * takes the Host, the ticket and the cookie with it. A process holding the run's token asks; a page's cookie cannot.
+ */
+async function openTunnel(ctx, tunnels, req, res) {
+    if (req.headers.authorization === undefined) {
+        sendFailure(res, 403, { message: "a tunnel is asked for with the run's token: mason ui --ssh does", code: "refused" });
+        return;
+    }
+    if (!ctx.page) {
+        sendFailure(res, 404, { message: "this Mason serves no web page", code: "not_found" });
+        return;
+    }
+    const body = JSON.parse(await readBody(req, 1024));
+    const port = body.port;
+    if (typeof port !== "number" || !Number.isInteger(port) || port < 1 || port > 65_535)
+        throw new Refusal(400, "send { port }: the local port the browser names");
+    // its Host would be this server's own, whose cookie is the run's token: rare, and a new local port is one run away
+    if (port === ctx.port) {
+        sendFailure(res, 409, { message: `local port ${port} is this server's own port on the server`, code: "refused", fix: "run it again: another local port is chosen" });
+        return;
+    }
+    const tunnel = newTunnel(port);
+    tunnels.push(tunnel);
+    res.once("close", () => {
+        tunnels.splice(tunnels.indexOf(tunnel), 1);
+        ctx.log(`web page: the tunnel from local port ${port} closed`);
+    });
+    ctx.log(`web page: a tunnel opened from local port ${port}`);
+    res.writeHead(200, { "Content-Type": "application/x-ndjson" });
+    res.write(`${JSON.stringify({ ticket: tunnel.ticket })}\n`);
+}
+/** How the run's server listens: on 127.0.0.1, and there is no other way (the header says why). */
+export function listenOnLoopback(server, port) {
+    return new Promise((resolve) => server.listen(port, "127.0.0.1", resolve));
+}
 export function createRunServer(ctx) {
     const saidErrors = new Set();
     // the last day's and week's statements, read at most once every SUMMARY_TTL_MS for every page and command that asks
     const summary = timedCache(() => ctx.duck.requests.summary(), SUMMARY_TTL_MS);
-    // read once, here: nothing a request names is ever read from disk (mason serve's run serves no page)
+    // the tunnels open now (`openTunnel`): the only Hosts the guard takes beside this server's own
+    const tunnels = [];
+    // read once, here: nothing a request names is ever read from disk
     const page = ctx.page ? pageFiles() : new Map();
     return http.createServer((req, res) => {
         for (const [k, v] of Object.entries(SECURITY_HEADERS))
             res.setHeader(k, v);
-        const v = guard({ method: req.method ?? "GET", url: req.url ?? "/", host: req.headers.host, origin: req.headers.origin, cookie: req.headers.cookie, authorization: req.headers.authorization }, ctx.port, ctx.token);
+        const v = guard({ method: req.method ?? "GET", url: req.url ?? "/", host: req.headers.host, origin: req.headers.origin, cookie: req.headers.cookie, authorization: req.headers.authorization }, ctx.port, ctx.token, tunnels);
         if (!v.ok) {
             if (v.status === 303) {
-                res.writeHead(303, { Location: v.location, "Set-Cookie": v.setCookie }).end();
+                res.writeHead(303, { Location: v.location, ...(v.setCookie !== undefined ? { "Set-Cookie": v.setCookie } : {}) }).end();
                 return;
             }
             res.writeHead(v.status, { "Content-Type": "text/plain; charset=utf-8" }).end(`${v.reason}\n`);
@@ -593,9 +697,52 @@ export function createRunServer(ctx) {
                         sendJson(res, 200, { ...r, state: await state(ctx) });
                     }
                 }
+                else if (req.method === "POST" && url.pathname === "/api/ui/tunnel") {
+                    await openTunnel(ctx, tunnels, req, res);
+                }
                 else if (req.method === "POST" && url.pathname === "/api/share") {
                     await openShare(ctx, req, res);
                 }
+                else if (req.method === "GET" && url.pathname === "/api/share/choices") {
+                    // what a share with no role named reads, or the roles to choose from: the page asks before it asks the person
+                    if (ctx.pageShares === undefined) {
+                        sendFailure(res, 409, SERVED_SHARE);
+                        return;
+                    }
+                    const r = await ctx.pageShares.choices();
+                    if ("failure" in r && r.choices === undefined) {
+                        sendFailure(res, statusOf(r.failure), r.failure);
+                        return;
+                    }
+                    sendJson(res, 200, "failure" in r ? { choices: r.choices } : { choices: [], role: r.role, reads: r.reads });
+                }
+                else if ((req.method === "POST" && /^\/api\/share\/[^/]+\/beat$/.test(url.pathname)) || (req.method === "DELETE" && /^\/api\/share\/[^/]+$/.test(url.pathname))) {
+                    // the page's share: a beat holds it, a DELETE is Stop sharing; a share of mason share's is its command's to end
+                    if (ctx.pageShares === undefined || ctx.shares === undefined) {
+                        sendFailure(res, 409, SERVED_SHARE);
+                        return;
+                    }
+                    let user;
+                    try {
+                        user = decodeURIComponent(url.pathname.split("/")[3]);
+                    }
+                    catch {
+                        throw new Refusal(400, `${url.pathname} does not name a share`);
+                    }
+                    const from = ctx.shares.fromOf(user);
+                    if (from === "command") {
+                        sendFailure(res, 409, { message: `the share ${user} is mason share's: Ctrl-C in its terminal ends it`, code: "refused" });
+                        return;
+                    }
+                    const ended = ctx.shares.ended;
+                    const why = ended?.user === user ? `: ${ended.why}` : "";
+                    const ok = req.method === "DELETE" ? await ctx.pageShares.stop(user) : ctx.pageShares.beat(user);
+                    if (!ok) {
+                        sendFailure(res, 404, { message: `the share ${user} is not open${why === "" ? "" : `; it ended${why}`}`, code: "not_found", fix: "Connect from anywhere opens a new one, with a new address and password" });
+                        return;
+                    }
+                    sendJson(res, 200, { ok: true });
+                }
                 else if (req.method === "POST" && /^\/api\/share\/[^/]+$/.test(url.pathname)) {
                     // what the command knows of its tunnel, as it knows it: mason status says it, and the run stops the client
                     const body = tunnelReport(JSON.parse(await readBody(req, 64 * 1024)));

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,7 +54,7 @@ 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
@@ -60,23 +67,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)
+    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)
 
   --json   a refusal to start as data: { error, next }; once it serves, its output is its log
 
@@ -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 {