@mason-data/cli 0.8.0 → 0.10.0

package/dist/src/cli/replica.js

@@ -0,0 +1,114 @@
+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, ONE RESOLVER FOR EVERY COMMAND THAT NAMES ONE (`mason deploy`, `mason user …
+ * --replica`, `mason token create`, `mason replica create | status`): the command's own argument where it takes one
+ * (`mason replica status acme/shop`), else `--replica`, else `MASON_REPLICA`; null when none names one, a Failure when
+ * it is not `<org>/<name>` (never repeated beyond 200 characters, made printable), or when the argument and `--replica`
+ * name two replicas. `usage`: the command's, said after a wrong line.
+ *
+ * WHEN THE ENVIRONMENT CHOSE THE TARGET IT IS SAID, on stderr (`say`): an agent inherits an environment it may never
+ * read, and `MASON_REPLICA` exported turns `mason user add` from this project's users to a replica's.
+ */
+export function replicaOf(flag, usage, env = process.env, o = {}) {
+    if (o.argument !== undefined) {
+        const r = replicaNamed(o.argument, "argument", usage);
+        if (flag === undefined || "message" in r)
+            return r;
+        const f = replicaNamed(flag, "--replica", usage);
+        if ("message" in f)
+            return f;
+        if (replicaText(f) === replicaText(r))
+            return r;
+        return { message: `the replica is named twice: ${replicaText(r)} and --replica ${replicaText(f)}`, code: "usage", fix: `name one: ${replicaText(r)}, or --replica ${replicaText(f)}`, usage };
+    }
+    const from = flag !== undefined ? "--replica" : env[REPLICA_ENV] !== undefined ? REPLICA_ENV : null;
+    if (from === null)
+        return null;
+    const r = replicaNamed((from === "--replica" ? flag : env[REPLICA_ENV]) ?? "", from, usage);
+    if (!("message" in r) && r.from === REPLICA_ENV)
+        (o.say ?? sayStderr)(envChoseText(r));
+    return r;
+}
+/** What is said on stderr when `MASON_REPLICA` chose the replica (a name `REPLICA_PART` holds: safe to print). */
+export const envChoseText = (r) => `using ${REPLICA_ENV}=${replicaText(r)} (--replica names another; unset ${REPLICA_ENV} for none)`;
+const sayStderr = (line) => { process.stderr.write(`${line}\n`); };
+/** The organisation the command means: its own argument (`mason replica list acme`), else `--org`; null when neither
+ *  names one, a wrong line's Failure when one is not a slug or the two differ. */
+export function orgOf(flag, argument, usage) {
+    const named = [argument, flag].filter((x) => x !== undefined).map((x) => orgNamed(x, usage));
+    const bad = named.find((x) => typeof x !== "string");
+    if (bad !== undefined)
+        return bad;
+    const [a, b] = named;
+    if (a === undefined)
+        return null;
+    if (b !== undefined && a !== b)
+        return { message: `the organisation is named twice: ${a} and --org ${b}`, code: "usage", fix: `name one: ${a}, or --org ${b}`, usage };
+    return a;
+}
+/** `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/replication-mode.js

@@ -165,6 +165,11 @@ export function dropStatements(o) {
     return `SELECT pg_drop_replication_slot('${o.slot}') FROM pg_replication_slots WHERE slot_name = '${o.slot}' AND NOT active;` +
         (o.owned ? ` DROP PUBLICATION IF EXISTS ${o.publication};` : "");
 }
+/** The statement that lists Mason's replication slots on a database (each named `mason_…`, `replicationNames`), for a
+ *  person to find the one to drop when its name is not known (a hosted replica's record of it could not be read). */
+export function listSlotsStatement() {
+    return "SELECT slot_name, database, active FROM pg_replication_slots WHERE left(slot_name, 6) = 'mason_';";
+}
 /**
  * WHAT THE RECORD NAMES THAT THIS START NO LONGER READS, to drop before the record names the new one (each holds what
  * Mason made on a database nothing would drop otherwise): a slot under another name (the sources file renamed) goes

package/dist/src/cli/request-filter.js

@@ -1,6 +1,7 @@
 import { OUTCOMES } from "../api/request-log.js";
 import { parseRequestCursor, requestCursor } from "../duck/requests.js";
 import { didYouMean } from "../lib/did-you-mean.js";
+import { parseDuration } from "../lib/table-sync.js";
 /** How many requests a read returns unless it says. */
 export const DEFAULT_REQUEST_LIMIT = 40;
 export const MAX_REQUEST_LIMIT = 10_000;
@@ -12,21 +13,30 @@ export const MAX_SEARCH = 200;
 /** How many sync events a read returns unless it says, and the most it may. */
 export const DEFAULT_EVENT_LIMIT = 40;
 export const MAX_EVENT_LIMIT = MAX_REQUEST_LIMIT;
-const AGE = /^(\d+)(s|m|h|d)$/;
-const AGE_MS = { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 };
 /** a date, or a date and time with its zone (a time without one would be read in this machine's zone: refused) */
 const ISO = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d{1,6})?)?(Z|[+-]\d{2}:?\d{2}))?$/;
+/** The furthest a JavaScript Date reaches from 1970, either way (ECMA-262 21.4.1.1). */
+const MAX_TIME_MS = 8.64e15;
 const usage = (message, fix) => ({ message, code: "usage", ...(fix !== undefined ? { fix } : {}) });
 export const QUERY_NAMES = (k) => k;
 /**
  * THE TIME GRAMMAR, ONE FOR EVERY ENTRANCE (`--since` / `--until` of mason logs and mason usage, and the run's `since` and
  * `until` of /api/requests, /api/events, /api/usage and /api/logs): an ISO 8601 date or time with its zone, or an age
- * before `now` (30s, 30m, 2h, 7d), as an ISO time; a time with no zone is refused, as is anything else.
+ * before `now` (30s, 30m, 2h, 7d, 2 hours), read by the command line's one duration grammar (src/lib/table-sync.ts
+ * `parseDuration`) with its unit written, as an ISO time; a time with no zone is refused, as is anything else. A bare
+ * number is refused here, as it always was: as a TIME it reads as well as a Unix timestamp as an age in seconds.
  */
 export function timeOf(name, text, now) {
-    const age = AGE.exec(text.trim());
-    if (age !== null)
-        return new Date(now - Number(age[1]) * AGE_MS[age[2]]).toISOString();
+    const age = Number.isFinite(Number(text.trim())) ? null : parseDuration(text, { zero: true });
+    if (age !== null && !("problem" in age)) {
+        // an age past what a time can hold (Date's ±8.64e15 ms) is the command line's mistake, refused as one: never a throw,
+        // which the run's API would answer 500
+        const at = now - age.seconds * 1000;
+        if (!Number.isFinite(at) || Math.abs(at) > MAX_TIME_MS) {
+            return usage(`${name} ${JSON.stringify(text)} is further back than a time reaches`, "a shorter age (30m, 2h, 7d), or an ISO 8601 date or time with its zone (2026-10-28, 2026-10-28T09:00:00Z)");
+        }
+        return new Date(at).toISOString();
+    }
     const t = ISO.test(text.trim()) ? Date.parse(text.trim()) : NaN;
     if (Number.isNaN(t)) {
         return usage(`${name} ${JSON.stringify(text)} is not a time`, "an age (30m, 2h, 7d) or an ISO 8601 date or time with its zone (2026-10-28, 2026-10-28T09:00:00Z)");

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,17 +27,18 @@ 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";
 import { restartsFact } from "./supervise.js";
 import { withRestarts } from "../duck/events.js";
 import { NO_ROLES } from "../duck/grants.js";
-import { addedNext, addUser, attributesToAdd, disabledNext, disableUser, enabledNext, enableUser, listUsers, removeUser, REMOVED_NEXT, roleToAdd, withLastUsed } from "./user.js";
+import { addedNext, addUser, attributesToAdd, disabledNext, disableUser, enabledNext, enableUser, fromNext, listUsers, rangesText, removeUser, REMOVED_NEXT, roleToAdd, setUserFrom, withLastUsed } from "./user.js";
 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)));
@@ -629,6 +776,8 @@ export function createRunServer(ctx) {
                         throw new Refusal(400, "send { name, role }: the role's name, a string");
                     if (body.set !== undefined && !(Array.isArray(body.set) && body.set.every((x) => typeof x === "string")))
                         throw new Refusal(400, "send { name, role, set }: set is a list of \"attribute=value\" strings, as mason user add --set takes them");
+                    if (body.from !== undefined && !(Array.isArray(body.from) && body.from.every((x) => typeof x === "string")))
+                        throw new Refusal(400, "send { name, from }: from is a list of address ranges (\"10.0.0.0/16\"), as mason user add --from takes them");
                     // the role must be one the roles file names NOW (src/cli/user.ts roleToAdd): refused before anything is written
                     const roleProblem = body.role === undefined ? null : roleToAdd(body.role, ctx.roles?.() ?? NO_ROLES);
                     if (roleProblem !== null) {
@@ -644,7 +793,7 @@ export function createRunServer(ctx) {
                     }
                     // mason user add --json's shape: its password, once, and the URL to paste (this run is up, so it has one)
                     const r = addUser(ctx.users.file, ctx.users.apiKey, body.name, { link: postgresLink(ctx.users.postgresUrl), database: ctx.users.database, roles: ctx.roles?.() ?? NO_ROLES,
-                        ...(typeof body.role === "string" ? { role: body.role } : {}), attributes: attributes.values });
+                        ...(typeof body.role === "string" ? { role: body.role } : {}), attributes: attributes.values, ...(Array.isArray(body.from) ? { from: body.from } : {}) });
                     if ("message" in r) {
                         sendFailure(res, statusOf(r), r);
                         return;
@@ -653,6 +802,27 @@ export function createRunServer(ctx) {
                     ctx.log(`user ${added.user} added${replaced ? " (in place of one the API key's rotation had removed)" : ""}`);
                     sendJson(res, 200, { ...added, next: nextJson(addedNext(added.user, true)) });
                 }
+                else if (req.method === "POST" && /^\/api\/users\/[^/]+\/from$/.test(url.pathname)) {
+                    // mason user from --json's shape, through its own function: the user's address ranges replaced (null: any address)
+                    let name;
+                    try {
+                        name = decodeURIComponent(url.pathname.split("/")[3]);
+                    }
+                    catch {
+                        throw new Refusal(400, `${url.pathname} does not name a user: POST /api/users/<name>/from`);
+                    }
+                    const body = JSON.parse(await readBody(req, 64 * 1024));
+                    if (!(body.from === null || (Array.isArray(body.from) && body.from.every((x) => typeof x === "string"))))
+                        throw new Refusal(400, "send { from }: a list of address ranges (\"10.0.0.0/16\"), or null for any address");
+                    const r = setUserFrom(ctx.users.file, name, body.from);
+                    if ("message" in r) {
+                        sendFailure(res, statusOf(r), r);
+                        return;
+                    }
+                    if (!r.already)
+                        ctx.log(`user ${r.changed.name} connects from ${rangesText(r.changed.from)}`);
+                    sendJson(res, 200, { ...r, next: nextJson(fromNext(r.changed.name, r.changed.from)) });
+                }
                 else if (req.method === "POST" && /^\/api\/users\/[^/]+\/(disable|enable)$/.test(url.pathname)) {
                     // mason user disable|enable --json's shape, through its own functions: kept, its password unchanged
                     const [, , , encoded, verb] = url.pathname.split("/");