@mason-data/cli 0.10.0 → 0.11.0

package/dist/src/cli/serve.js

@@ -19,6 +19,10 @@
  *
  *   - 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.
+ *     MASON_UI_SOCKET serves it on a Unix socket too, for a process on this machine (src/cli/ui-socket.ts): mode 0600, in
+ *     a folder only Mason's user can write, behind the same guard as `mason ui --ssh`'s requests. MASON_UI_RUN_FILE
+ *     writes the page's port and the run's token to a file for a supervisor on this machine (src/cli/ui-run-file.ts),
+ *     held to the same bar, once the run answers; /healthz says from the start where the page is served (`PageServed`).
  *
  * The commands beside it work as on a laptop, in the data folder: `docker compose exec mason mason add orders`.
  */
@@ -36,7 +40,10 @@ import { connectDatabase, DATABASE_SETTING, databaseNameProblem } from "../lib/d
 import { appEnvValue } from "../lib/dotenv.js";
 import { imagePinProblem, PIN_FILE } from "../lib/project-version.js";
 import { commandPinProblem } from "./pin.js";
+import { listenOnUiSocket, prepareUiSocket, uiSocketSetting } from "./ui-socket.js";
+import { prepareUiRunFile, uiRunFileSetting, UI_RUN_FILE_SETTING, writeUiRunFile } from "./ui-run-file.js";
 import { recordRefusal } from "./replication-mode.js";
+import { UI_READ_ONLY_SETTING, uiReadOnlySetting } from "./ui-read-only.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";
@@ -81,6 +88,18 @@ export const SERVE = {
     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_UI_SOCKET         a Unix socket the web page is served on too, for a process on this machine (a supervisor,
+                            a local reverse proxy): made mode 0600 in a folder only Mason's user can write (else the
+                            start is refused), a stale one replaced, removed on exit; a request on it passes the same
+                            guard as mason ui --ssh's (default unset: none)
+    MASON_UI_RUN_FILE       a file Mason writes once it answers, for a process on this machine that supervises it:
+                            { "port", "token" }, the web page's port and the run's token, which grants what the token
+                            grants — the commands' writes (mason add, mason sync, mason user) as well as a tunnel to
+                            the page; written whole, mode 0600, in a folder only Mason's user can write (else the
+                            start is refused), a stale one replaced, removed on exit (default unset: none)
+    MASON_UI_READ_ONLY      1 when the web page should only show: it offers no control that changes anything, and
+                            refuses every change it is sent, through mason ui --ssh or the socket alike; the mason
+                            commands beside it are unchanged (default 0)
     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
@@ -164,6 +183,19 @@ export function serveSettings(env, cwd) {
     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
+    const socket = uiSocketSetting(env, cwd);
+    if (socket !== null && typeof socket !== "string")
+        wrong.push(socket.problem);
+    // the run's file (src/cli/ui-run-file.ts): never the socket's own path
+    const runFile = uiRunFileSetting(env, cwd);
+    if (runFile !== null && typeof runFile !== "string")
+        wrong.push(runFile.problem);
+    else if (runFile !== null && runFile === socket)
+        wrong.push(`${UI_RUN_FILE_SETTING} names the path MASON_UI_SOCKET names: two paths`);
+    // the read-only page (src/cli/ui-read-only.ts): 1 or 0, anything else refused here, never read as off
+    const pageReadOnly = uiReadOnlySetting(env);
+    if (typeof pageReadOnly !== "boolean")
+        wrong.push(pageReadOnly.problem);
     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) {
@@ -176,7 +208,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 },
+        ui: { port: uiPort, named: !!env.MASON_UI_PORT, socket: typeof socket === "string" ? socket : null, runFile: typeof runFile === "string" ? runFile : null },
     };
 }
 /**
@@ -331,6 +363,7 @@ export function serveRecordRefusal(s, existing, env) {
         return null;
     return recordRefusal(existing.config, file, env, sourcesTop(path.dirname(s.project), s.project).shown, "mason serve");
 }
+export const NO_PAGE_SERVED = { socket: null, readOnly: false };
 /** seconds since the serve started: /healthz's `uptimeSeconds` and /metrics' `mason_uptime_seconds`, one number */
 const uptimeSeconds = (startedAt, now) => Math.floor((now - startedAt) / 1000);
 /**
@@ -338,8 +371,8 @@ const uptimeSeconds = (startedAt, now) => Math.floor((now - startedAt) / 1000);
  * leaves the rest served: the counts say it); 503 while it starts and stops. Counts only, never a table's name: the
  * endpoint takes no credential.
  */
-export function healthBody(state, startedAt, now = Date.now()) {
-    const base = { status: state.phase, version: version(), uptimeSeconds: uptimeSeconds(startedAt, now) };
+export function healthBody(state, startedAt, now = Date.now(), page = NO_PAGE_SERVED) {
+    const base = { status: state.phase, version: version(), uptimeSeconds: uptimeSeconds(startedAt, now), page: { socket: page.socket, readOnly: page.readOnly } };
     if (state.phase !== "ready")
         return { status: 503, body: base };
     return { status: 200, body: { ...base, tables: phaseCounts(state.tables()) } };
@@ -355,7 +388,7 @@ export async function metricsBody(state, startedAt, now = Date.now()) {
     return metricsText({ version: version(), run: { ...run, uptimeSeconds: uptimeSeconds(startedAt, now) } });
 }
 /** The health server: GET /healthz and GET /metrics, nothing else. `log` says a scrape whose numbers could not be read. */
-export function healthServer(state, startedAt, log = say) {
+export function healthServer(state, startedAt, log = say, page = NO_PAGE_SERVED) {
     return http.createServer((req, res) => {
         const url = new URL(req.url ?? "/", "http://health");
         if (url.pathname !== "/healthz" && url.pathname !== "/metrics") {
@@ -381,7 +414,7 @@ export function healthServer(state, startedAt, log = say) {
             });
             return;
         }
-        const h = healthBody(state(), startedAt);
+        const h = healthBody(state(), startedAt, Date.now(), page);
         res.writeHead(h.status, { "content-type": "application/json", "cache-control": "no-store" }).end(`${JSON.stringify(h.body)}\n`);
     });
 }
@@ -421,14 +454,57 @@ export async function serve(argv) {
     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 });
+    // the page's socket, before anything listens: its folder and its path held to the bar, a stale one replaced, then made
+    let page = null;
+    // what making it says, under the start's heading below
+    const socketSaid = [];
+    if (s.ui.socket !== null) {
+        const prepared = await prepareUiSocket(s.ui.socket, (l) => socketSaid.push(l));
+        if (prepared !== null)
+            return failed("serve", prepared, { json });
+        const opened = await listenOnUiSocket(s.ui.socket, (l) => say(`  ${l}`));
+        if ("message" in opened)
+            return failed("serve", opened, { json });
+        page = opened;
+    }
+    // the run's file: written once the run answers (asserted wide: they are set in the run's hooks, which the compiler
+    // does not follow)
+    let runFile = null;
+    let runFileFailed = null;
+    // a SIGTERM before the run has its own stop (the run file's check, the run still connecting) ends the process by its
+    // default action, which runs no finally: the socket is removed first, then the signal raised again as it was
+    const early = (signal) => {
+        if (process.listenerCount(signal) > 1)
+            return; // the run's stop is in place: it stops, and the finally removes it
+        page?.close();
+        runFile?.remove();
+        unhookEarly();
+        process.kill(process.pid, signal);
+    };
+    const unhookEarly = () => { process.removeListener("SIGTERM", early); process.removeListener("SIGINT", early); };
+    if (page !== null) {
+        process.on("SIGTERM", early);
+        process.on("SIGINT", early);
+    }
+    // its folder and its path held to the bar now, a stale one removed (its run asked, up to 2 s: the handler is in place)
+    if (s.ui.runFile !== null) {
+        const prepared = await prepareUiRunFile(s.ui.runFile, (l) => socketSaid.push(l));
+        if (prepared !== null) {
+            page?.close();
+            unhookEarly();
+            return failed("serve", prepared, { json });
+        }
+    }
     const startedAt = Date.now();
     let state = { phase: "starting" };
-    const health = healthServer(() => state, startedAt);
+    const health = healthServer(() => state, startedAt, say, { socket: page?.file ?? null, readOnly: uiReadOnlySetting(process.env) === true });
     const listening = await new Promise((resolve) => {
         health.once("error", resolve);
         health.listen(s.health.port, s.health.host, () => resolve(null));
     });
     if (listening !== null) {
+        page?.close();
+        unhookEarly();
         return failed("serve", { message: `the health endpoint cannot listen on ${s.health.host}:${s.health.port}: ${listening.message}`, code: "refused",
             fix: "MASON_HEALTH_PORT names a port free on this machine" }, { json });
     }
@@ -440,18 +516,52 @@ export async function serve(argv) {
     say(`  database  ${made.database}, what a tool connects with`);
     say(`  health    http://${s.health.host}:${s.health.port}/healthz`);
     say(`  metrics   http://${s.health.host}:${s.health.port}/metrics`);
+    for (const l of socketSaid)
+        say(`  ${l}`);
+    if (s.ui.runFile !== null)
+        say(`  run file  ${s.ui.runFile}: written once Mason answers (mode 0600; it holds the run's token)`);
+    if (page !== null)
+        say(`  web page  ${page.file} (a Unix socket, mode 0600: a request on it passes the same guard as mason ui --ssh's)`);
+    if (uiReadOnlySetting(process.env) === true)
+        say(`  web page  read-only (${UI_READ_ONLY_SETTING}=1): it refuses every change it is sent; the mason commands beside it are unchanged`);
     // the run reads the project of the folder it runs in (src/cli/project.ts): the data folder's
     process.chdir(s.data);
     let code;
     try {
         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" }; } } });
+            serve: { log: say,
+                ready: (run) => {
+                    // the run's file before /healthz says ready: a supervisor that sees ready finds it
+                    if (s.ui.runFile !== null) {
+                        const w = writeUiRunFile(s.ui.runFile, run.page, (l) => say(`  ${l}`));
+                        if ("message" in w) {
+                            // fail closed: a supervisor would wait on a file that never comes, so the run stops, never says it is
+                            // ready, records why, and the serve exits 1
+                            runFileFailed = w;
+                            say(`  ${w.message}: Mason stops (${w.fix})`);
+                            state = { phase: "stopping" };
+                            return `stopped: the run file (${UI_RUN_FILE_SETTING}) could not be written: ${w.message.slice(`${UI_RUN_FILE_SETTING}=`.length)}`;
+                        }
+                        runFile = w;
+                        say(`  run file  ${w.file} (the web page's port and the run's token, mode 0600)`);
+                    }
+                    state = { phase: "ready", tables: run.tables, metrics: run.metrics };
+                    return null;
+                },
+                stopping: () => { state = { phase: "stopping" }; page?.close(); runFile?.remove(); },
+                ...(page !== null ? { page: page.attach, socket: page.file } : {}) } });
     }
     finally {
+        // removed whatever ended the run: a stop, a crash of the engine's thread, or a start that failed
+        page?.close();
+        runFile?.remove();
+        unhookEarly();
         // a platform's health check may hold a keep-alive connection open, which close() alone would wait for
         health.closeAllConnections();
         await new Promise((resolve) => health.close(() => resolve()));
     }
+    if (runFileFailed !== null)
+        return failed("serve", runFileFailed, { json: false });
     if (code !== 0)
         return failed("serve", { message: "Mason did not start: what stopped it is said above", code: "failed",
             fix: "fix what it says, then start it again (a platform restarts it by itself)" }, { json: false });

package/dist/src/cli/ui-read-only.js

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

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

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