@mason-data/cli 0.7.0 → 0.8.0

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

@@ -0,0 +1,286 @@
+/**
+ * THE RUN'S SIDE OF `mason share` (src/cli/share.ts is the command's; docs/POSTGRES-API.md "From a cloud BI tool"): the
+ * second socket of the Postgres listener (src/api/postgres/server.ts `openShare`), and who may log in on it.
+ *
+ * A SHARE LASTS AS LONG AS THE COMMAND'S CONNECTION TO THE RUN (`POST /api/share`, src/cli/run-server.ts): the answer
+ * stays open, and when it goes, however it goes — Ctrl-C, the tunnel's end, a `kill -9` —, the login goes, its sessions
+ * end, its tunnel client is stopped, and with the last share the socket closes. A second `mason share` meets the same
+ * socket with a login of its own.
+ *
+ * THE LOGIN IS IN THIS PROCESS'S MEMORY ALONE, AND ONLY ITS HASH: the command makes the password and sends its SHA-256
+ * (`shareSecret`), so no state, log line or answer of the run can carry a password the run was never given (a fast hash
+ * is enough: the password is 192 random bits, nothing to guess). It is no row of `.mason/users.json`, because that file
+ * outlives a process and a share must not: a run that dies takes it along.
+ * Only `authenticate` below reads this list, and only the share's socket asks it: the password is refused on the
+ * run's own listener by nobody knowing it, and a `mason user` or a token here by the same.
+ *
+ * A LOGIN REFUSED HERE IS LOGGED WITH NO SOURCE: every connection through a tunnel comes from 127.0.0.1, so naming
+ * one would be naming the tunnel's client. The log is written once a minute at most (a scanner's rate is anyone's), with
+ * how many it stands for; the counts are `mason status`'s.
+ */
+import * as crypto from "node:crypto";
+import { execFile } from "node:child_process";
+import { ApiError } from "../api/error.js";
+import { didYouMean } from "../lib/did-you-mean.js";
+import { missingAttributes } from "../duck/row-filter.js";
+import { ROLE_NAME_RE, ROLE_NAME_RULE, ROLES_FILE } from "./roles.js";
+import { sameSecret } from "./security.js";
+/** What the password is stored and sent as: its SHA-256, hex. */
+export const shareSecret = (password) => crypto.createHash("sha256").update(password).digest("hex");
+/** The new password `mason share` prints once: 192 random bits, in characters every form and URL takes. */
+export const newSharePassword = () => crypto.randomBytes(24).toString("hex");
+/** How often a refused login is written to the log, at most: the rest are counted. */
+const REFUSED_LOG_MS = 60_000;
+/** How many refused logins a minute are rows of the request log, at most: the rest are counted (`mason status`), so a
+ *  stranger on a public address cannot set the log's growth. */
+const REFUSED_ROWS_A_MINUTE = 10;
+/** The tunnel of a share, as its command tells the run (`POST /api/share/<user>`). */
+/** What `POST /api/share/<user>` was sent, as a ShareTunnel, or null: its `pid` is a process the run may stop, so
+ *  what the run keeps is these fields, each its own type, never the body. */
+export function tunnelReport(body) {
+    if (typeof body !== "object" || body === null || Array.isArray(body))
+        return null;
+    const { via, host, port, endsAt, state, pid } = body;
+    const text = (x) => typeof x === "string" && x !== "" && x.length <= 255;
+    const whole = (x, max) => typeof x === "number" && Number.isInteger(x) && x >= 1 && x <= max;
+    if (via !== undefined && !text(via))
+        return null;
+    if (host !== undefined && !text(host))
+        return null;
+    if (port !== undefined && !whole(port, 65_535))
+        return null;
+    if (endsAt !== undefined && endsAt !== null && !(text(endsAt) && !Number.isNaN(Date.parse(endsAt))))
+        return null;
+    if (state !== undefined && state !== "opening" && state !== "up" && state !== "reconnecting")
+        return null;
+    if (pid !== undefined && !whole(pid, 2 ** 31 - 1))
+        return null;
+    return { ...(via !== undefined ? { via } : {}), ...(host !== undefined ? { host } : {}), ...(port !== undefined ? { port } : {}),
+        ...(endsAt !== undefined ? { endsAt } : {}), ...(state !== undefined ? { state } : {}), ...(pid !== undefined ? { pid } : {}) };
+}
+/** What a role reads, in a line. */
+function readsText(g) {
+    if (g.all)
+        return "every synced table";
+    const names = [...g.tables.keys()];
+    return `${names.length} synced table${names.length === 1 ? "" : "s"}: ${names.slice(0, 6).join(", ")}${names.length > 6 ? ` and ${names.length - 6} more` : ""}`;
+}
+/** The attributes a role's filters read, by the rule a session is refused by: a share's login is a password and no
+ *  values, so under such a role its every statement would be refused. */
+const attributesOf = (g) => g.filters === undefined ? [] : missingAttributes(g.filters.values(), {});
+/** The roles a share may read as, the file's default first. */
+function choicesOf(live) {
+    return [...live.grants.values()].filter((g) => attributesOf(g).length === 0).map((g) => ({ role: g.name, reads: readsText(g), default: g.name === live.default }))
+        .sort((a, b) => Number(b.default) - Number(a.default));
+}
+/** Why roles that read attributes cannot be shared: what each reads, the roles that can be, and the login that carries values. */
+function needsAttributes(message, roles, choices, file) {
+    const first = roles[0];
+    const sets = attributesOf(first).map((m) => `--set ${m.attr}=<value>`).join(" ");
+    return { message, code: "refused", why: roles.flatMap(attributesOf).map((m) => `${m.at} reads :${m.attr} (${m.where})`).join("; "),
+        fix: choices.length > 0 ? choices.map((c) => `--role ${c.role}: reads ${c.reads}`).join("\n") : `add a role to ${file} whose rows need no attribute, then mason share --role <role>`,
+        next: [...choices.map((c) => [`mason share --role ${c.role}`, `reads ${c.reads}`]),
+            [`mason user add <name> --role ${first.name} ${sets}`, "a login that carries the values, for a tool that can reach this machine"]] };
+}
+/**
+ * WHAT A SHARE READS: `--role`'s role; with none named, the one answer the project gives — no roles file, so every synced
+ * table, or a file of one role — and otherwise a refusal naming the choices. A file with a `default:` and other roles
+ * is refused too: a default says what a local user gets, and a public address is no moment to widen it silently.
+ * The refusal is a Failure with `choices` beside it: a person is asked (src/cli/share.ts), and an agent reads the lines.
+ */
+export function shareRole(asked, live) {
+    const file = live.file ?? `mason/${ROLES_FILE}`;
+    if (live.checkFailed === true) {
+        return { failure: { message: `nothing is shared: ${live.problem}`, code: "failed", why: `the file may be right: a share opens only on filters Postgres has read`, fix: "mason logs says why, then mason share again", next: [["mason logs", "the run's log"]] } };
+    }
+    if (live.problem !== null) {
+        return { failure: { message: `${file} cannot be read as it is now, so nothing is shared: ${live.problem}`, code: "bad_roles", why: "what a share reads is that file's", fix: `repair ${file}, then mason share` } };
+    }
+    const choices = choicesOf(live);
+    const left = [...live.grants.keys()].filter((r) => !choices.some((c) => c.role === r));
+    const lines = choices.map((c) => [`mason share --role ${c.role}`, `reads ${c.reads}`]);
+    if (asked !== undefined) {
+        if (!ROLE_NAME_RE.test(asked))
+            return { failure: { message: `${JSON.stringify(asked)} is not a role name: ${ROLE_NAME_RULE}`, code: "usage" } };
+        const g = live.grants.get(asked);
+        if (g !== undefined) {
+            if (attributesOf(g).length === 0)
+                return { role: asked, reads: readsText(g) };
+            return { failure: needsAttributes(`a share cannot read as the role ${asked}: its rows depend on ${attributesOf(g).map((m) => `:${m.attr}`).join(", ")}, and a share's login has no attributes`, [g], choices, file) };
+        }
+        if (live.file === null) {
+            return { failure: { message: `there is no role ${asked}: this project has no roles file`, code: "not_found", why: `a role is a key of ${file}, beside the sources file, naming the tables (and the columns of each) it may read`,
+                    fix: `write ${file}:\n  roles:\n    ${asked}:\n      tables:\n        <a synced table>: {}\nthen mason share --role ${asked}`, next: [["mason share", "or share every synced table: this project has no roles file"]] } };
+        }
+        const roles = [...choices.map((c) => c.role), ...left.map((r) => `${r} (its rows depend on an attribute, so a share cannot read as it)`)];
+        return { failure: { message: `there is no role ${asked} in ${file}${didYouMean(asked, [...live.grants.keys()])}`, code: "not_found", why: `the roles: ${roles.join(", ")}`, next: lines }, choices };
+    }
+    if (live.file === null)
+        return { role: null, reads: "every synced table" };
+    if (live.grants.size === 1 && choices.length === 1)
+        return { role: choices[0].role, reads: choices[0].reads };
+    if (choices.length === 0 && live.grants.size > 0) {
+        return { failure: needsAttributes(`no role of ${file} can be shared: the rows of each depend on an attribute, and a share's login has no attributes`, [...live.grants.values()], choices, file) };
+    }
+    if (choices.length === 0) {
+        return { failure: { message: `${file} names no role, so a share would read nothing`, code: "not_found", why: "what a share reads is one role of that file", fix: `add a role to ${file}, then mason share --role <role>` } };
+    }
+    return { failure: { message: `${file} names ${live.grants.size} roles: mason share needs to know which one this address reads as`, code: "usage",
+            why: "anyone with the address and password reads what that role reads", fix: [...choices.map((c) => `--role ${c.role}: reads ${c.reads}${c.default ? " (the file's default)" : ""}`), ...(left.length > 0 ? [`left out, because a share's login has no attributes: ${left.join(", ")}`] : [])].join("\n"), next: lines }, choices };
+}
+/** Stops a share's tunnel client once its command is gone: by its pid, and only while that pid is still a process
+ *  naming the share's port (a pid is reused; never kill by anything broader). */
+export function stopTunnelClient(pid, port, log) {
+    execFile("ps", ["-o", "command=", "-p", String(pid)], (err, stdout) => {
+        // ps exits 1 for a pid that is gone: its command ended it, the usual case
+        if (err !== null || !stdout.includes(String(port)))
+            return;
+        try {
+            process.kill(pid, "SIGTERM");
+        }
+        catch (e) {
+            log(`share: stopping its tunnel client (pid ${pid}) failed: ${e.message}`);
+        }
+    });
+}
+export class RunShares {
+    deps;
+    held = new Map();
+    socket = null;
+    /** the socket once it listens */
+    live = null;
+    refused = 0;
+    rowsFrom = -Infinity;
+    rows = 0;
+    dropped = 0;
+    lastSaid = -Infinity;
+    unsaid = 0;
+    constructor(deps) { this.deps = deps; }
+    /** Opens a share: the socket when none is open, and a login of its own. Refused: the failure, with the choices when a role is what is missing. */
+    async open(ask) {
+        const role = shareRole(ask.role, await this.deps.listener.checkRoles());
+        if ("failure" in role)
+            return role;
+        const user = `share_${crypto.randomBytes(3).toString("hex")}`;
+        // in the list before the first wait, so a share ending meanwhile does not close the socket under this one
+        this.held.set(user, { user, secret: ask.secret, role: role.role, reads: role.reads, openedAt: new Date().toISOString(), tunnel: { state: "opening" }, ended: null });
+        let socket, fingerprint;
+        try {
+            const made = this.socket ?? this.openSocket();
+            if ("message" in made) {
+                this.held.delete(user);
+                return { failure: made };
+            }
+            this.socket = made;
+            fingerprint = made.fingerprint;
+            socket = await made.opening;
+        }
+        catch (e) {
+            this.held.delete(user);
+            this.socket = null;
+            return { failure: { message: `the share's socket could not be opened: ${e.message}`, code: "failed", next: [["mason logs", "the run's log"]] } };
+        }
+        this.live = socket;
+        this.deps.log(`share: ${user} opened, reading ${role.role === null ? "every synced table (no roles file)" : `as the role ${role.role}`}, TLS required on 127.0.0.1:${socket.port}`);
+        return { user, port: socket.port, fingerprint, database: this.deps.database, role: role.role, reads: role.reads };
+    }
+    openSocket() {
+        const cert = this.deps.certificate();
+        if ("message" in cert)
+            return cert;
+        const opening = this.deps.listener.openShare({
+            tls: { cert: cert.cert, key: cert.key },
+            authenticate: (password, user) => this.authenticate(password, user),
+            recheck: (token) => this.recheck(token),
+            loginHint: "the password mason share printed: every run of it makes a new one",
+            refused: (user) => { this.refused++; this.note(`a login refused for the user ${JSON.stringify(user)}`); return this.rowFree(Date.now()); },
+            dropped: (why) => { this.dropped++; this.note(`a connection dropped before its login: it ${why}`); },
+        });
+        return { opening, fingerprint: cert.fingerprint };
+    }
+    authenticate(password, user) {
+        const given = shareSecret(password);
+        const found = [...this.held.values()].find((h) => sameSecret(h.secret, given));
+        if (found === undefined || found.user !== user) {
+            const refused = new ApiError(401, "not this share's password", "invalid_share");
+            refused.userName = user;
+            throw refused;
+        }
+        return { filters: [], subject: undefined, user: found.user, jti: found.user, ...(found.role !== null ? { role: found.role } : {}) };
+    }
+    /** a session's login, asked again before a statement: a share closed ends its sessions at once, and this is why none outlives it */
+    async recheck(token) {
+        if (token.jti === undefined || !this.held.has(token.jti))
+            throw new ApiError(401, "the share ended", "invalid_share");
+    }
+    /** whether a refused login at `now` is a row of the request log */
+    rowFree(now) {
+        if (now - this.rowsFrom >= 60_000) {
+            this.rowsFrom = now;
+            this.rows = 0;
+        }
+        return ++this.rows <= REFUSED_ROWS_A_MINUTE;
+    }
+    /** the log's line: at most one a minute, saying how many it stands for, with no source (the header says why) */
+    note(what) {
+        const now = Date.now();
+        if (now - this.lastSaid < REFUSED_LOG_MS) {
+            this.unsaid++;
+            return;
+        }
+        const more = this.unsaid > 0 ? ` (and ${this.unsaid} more before it)` : "";
+        this.lastSaid = now;
+        this.unsaid = 0;
+        this.deps.log(`share: ${what}${more}; who cannot be known: every connection through a tunnel comes from 127.0.0.1`);
+    }
+    /** What a share's command says of its tunnel; false: no such share open. */
+    update(user, tunnel) {
+        const h = this.held.get(user);
+        if (h === undefined)
+            return false;
+        h.tunnel = { ...h.tunnel, ...tunnel };
+        return true;
+    }
+    /** Called once when a share ends by anything but its command's connection (the run stopping). */
+    onEnd(user, ended) {
+        const h = this.held.get(user);
+        if (h !== undefined)
+            h.ended = ended;
+    }
+    /** Ends a share: its login gone first, then its sessions, its tunnel client, and with the last one the socket. */
+    async close(user, why) {
+        const h = this.held.get(user);
+        if (h === undefined)
+            return;
+        this.held.delete(user);
+        const opening = this.socket?.opening;
+        if (opening === undefined)
+            return;
+        const socket = await opening;
+        const ended = socket.endSessions(user, "the share ended");
+        if (h.tunnel.pid !== undefined)
+            (this.deps.stopTunnel ?? ((pid, port) => stopTunnelClient(pid, port, this.deps.log)))(h.tunnel.pid, socket.port);
+        this.deps.log(`share: ${user} closed: ${why}; ${ended} session${ended === 1 ? "" : "s"} ended`);
+        h.ended?.(why);
+        if (this.held.size > 0)
+            return;
+        this.socket = null;
+        this.live = null;
+        const counts = `${this.refused} login${this.refused === 1 ? "" : "s"} refused, ${this.dropped} connection${this.dropped === 1 ? "" : "s"} dropped before a login`;
+        this.refused = 0;
+        this.dropped = 0;
+        this.unsaid = 0;
+        this.lastSaid = -Infinity;
+        await socket.close();
+        this.deps.log(`share: the share's socket closed (${counts})`);
+    }
+    /** Every share ended (the run stopping). */
+    async closeAll(why) { await Promise.all([...this.held.keys()].map((u) => this.close(u, why))); }
+    state() {
+        if (this.socket === null || this.live === null)
+            return null;
+        return { port: this.live.port, fingerprint: this.socket.fingerprint, sessions: this.live.sessions, refusedLogins: this.refused, droppedConnections: this.dropped,
+            shares: [...this.held.values()].map((h) => ({ user: h.user, role: h.role, reads: h.reads, openedAt: h.openedAt, via: h.tunnel.via ?? null, host: h.tunnel.host ?? null, port: h.tunnel.port ?? null,
+                endsAt: h.tunnel.endsAt ?? null, state: h.tunnel.state ?? "opening" })) };
+    }
+}

package/dist/src/cli/share.js

@@ -0,0 +1,286 @@
+/**
+ * `mason share`: a run on a laptop reached by a tool in the cloud, through a free tunnel service, with TLS end to end
+ * between that tool and Mason (docs/POSTGRES-API.md "From a cloud BI tool"). This is the command's side: it makes the
+ * password, asks the run for a socket that requires TLS (`POST /api/share`, src/cli/share-run.ts), starts the tunnel's
+ * client (src/cli/tunnel.ts) pointed at that socket, prints what to type into the tool, and holds all of it in the
+ * foreground: the address is temporary by nature, and a share nobody is watching is a public login nobody is watching.
+ *
+ * ITS CONNECTION TO THE RUN IS THE SHARE: however this process ends the run closes the share, a `kill -9` included.
+ *
+ * A FREE TUNNEL ENDS THE SHARE WHEN IT ENDS: there is no reconnect, because a new tunnel is a new address the person would
+ * have to copy anyway; this says so and exits 1 with what to run next, and the next run gives a new address and a new
+ * password. WITH A PAID TOKEN the address survives, so the client is opened again, the password unchanged, and it is said.
+ *
+ * WHAT `--json` PRINTS IS ONE OBJECT, ONCE, when the address is known; everything after it (a reconnect, the end and
+ * why) is on stderr with the exit code, so stdout stays one document.
+ */
+import { once } from "node:events";
+import { createInterface } from "node:readline/promises";
+import { failed, jsonText, parseCommand, reportText } from "./command.js";
+import { guarded, runFailure } from "./commands.js";
+import { callRun, holdRun } from "./control.js";
+import { reach } from "./state.js";
+import { err as styleErr, out as styleOut, stepRenderer } from "./style.js";
+import { alive } from "./runs.js";
+import { appEnvValue } from "../lib/dotenv.js";
+import { newSharePassword, shareSecret } from "./share-run.js";
+import { probeShare, startTunnel, sweepTunnelFiles, TOKEN_RE, TUNNELS, tunnelPlan } from "./tunnel.js";
+const out = (m) => { process.stdout.write(`${m}\n`); };
+const say = (m) => { process.stderr.write(`${m}\n`); };
+const DEFAULT_TIMEOUT_S = 30;
+/** The first wait before a dropped tunnel is opened again, and the longest. */
+const RECONNECT_FIRST_MS = 1_000;
+const RECONNECT_MAX_MS = 30_000;
+export const SHARE = {
+    needs: "run",
+    name: "share",
+    summary: "share the synced data with a tool outside this machine: a temporary address, TLS end to end, a password for this run",
+    usage: `usage: mason share [--role <role>] [--via pinggy|bore] [--timeout <seconds>] [--json]
+
+  For a BI tool in the cloud, which cannot reach 127.0.0.1: opens a temporary public address for this project's Postgres
+  API, through a free tunnel service, and prints what to type into the tool. It stays in the foreground: Ctrl-C ends
+  the share. Your local tools notice nothing: the share has a socket of its own, and no session is dropped.
+
+  The socket requires TLS of every connection, so a service that forwards bytes cannot read them. The certificate is
+  self-signed (the tool connects with sslmode=require, and checks no certificate), so a malicious service could sit in
+  the middle of the handshake: this is for trying Mason, on data you may send that way. mason serve on a host is the
+  way to keep a dashboard running.
+
+  The password is made here, printed once and good for this run alone: it is kept nowhere, works on this address only,
+  and is gone when the share ends. A mason user's password and an API token are refused here. What the share reads is
+  one role of mason/roles.yml: --role names it; with one role in the file that one is used, and with several you are
+  asked, or with --json refused with the line to run. With no roles file it reads every synced table, and says so.
+
+  --via pinggy (the default) needs only ssh; a free tunnel ends after about an hour, and the share with it: run mason
+  share again for a new address and a new password. MASON_PINGGY_TOKEN (the shell or .env, never a flag: a command
+  line is visible to every user of the machine), a paid Pinggy token, keeps the address, so a tunnel that drops is opened
+  again by itself, the password unchanged. --via bore needs bore (cargo install bore-cli).
+
+    mason share
+    mason share --role sales
+    mason share --via bore
+
+  --role <role>       what it reads: a role of mason/roles.yml
+  --via <tunnel>      pinggy (default) or bore
+  --timeout <s>       how long the tunnel has to give its address (default ${DEFAULT_TIMEOUT_S})
+  --json              as data, once the address is known: { share: { host, port, database, user, password, sslmode,
+                      fingerprint, role, reads, via, endsAt (ISO 8601, or null), verified (the address answered with this
+                      share's certificate; false: it could not be reached from this machine) }, next }; the command
+                      then holds the share: the end is on stderr, exit 0 for Ctrl-C or SIGTERM, 1 otherwise
+`,
+    options: { role: { type: "string" }, via: { type: "string" }, timeout: { type: "string" }, json: { type: "boolean", default: false } },
+    json: ["share", "next"],
+};
+/** A role from what a person typed: a choice's number or its name; null for anything else. */
+export function chosenRole(answer, choices) {
+    const a = answer.trim();
+    const byNumber = /^\d+$/.test(a) ? choices[Number(a) - 1] : undefined;
+    return byNumber?.role ?? choices.find((c) => c.role === a)?.role ?? null;
+}
+/** Whether a person is there to ask: a terminal both ways, and no --json (never an environment variable). */
+const canAsk = (json) => !json && process.stdin.isTTY === true && process.stderr.isTTY === true;
+/** Asks a person which role: the answer, or null for an empty line, an end of input or something that is no choice. */
+async function askRole(choices) {
+    say("Which role does this share read as? Anyone with its address and password reads what it reads.");
+    choices.forEach((c, i) => say(`  ${i + 1}. ${c.role}: ${c.reads}${c.default ? " (the file's default)" : ""}`));
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    const closed = once(rl, "close").then(() => null);
+    const answer = await Promise.race([rl.question("Role (a number or a name): "), closed]);
+    rl.close();
+    return answer === null ? null : chosenRole(answer, choices);
+}
+/** The run's refusal with its own next steps (`failure.next`, src/cli/run-server.ts sendFailure). */
+function refusalOf(reply) {
+    const next = reply.body.failure?.next ?? [];
+    return runFailure(reply, next.map((n) => n.what === undefined ? [n.command] : [n.command, n.what]));
+}
+/** The share opened by the run: asked once, and again with what a person chose. */
+async function openOnRun(run, secret, role, json) {
+    const asked = await holdRun(run, "/api/share", { secret, ...(role !== undefined ? { role } : {}) });
+    if ("first" in asked)
+        return asked;
+    const choices = asked.body.choices;
+    if (choices === undefined || role !== undefined || !canAsk(json))
+        return refusalOf(asked);
+    const chosen = await askRole(choices);
+    if (chosen === null)
+        return refusalOf(asked);
+    const again = await holdRun(run, "/api/share", { secret, role: chosen });
+    return "first" in again ? again : refusalOf(again);
+}
+/** `mason status`'s and the report's words for when it ends. */
+function endsText(endsAt, now) {
+    if (endsAt === null)
+        return "when this command ends (Ctrl-C)";
+    const minutes = Math.max(0, Math.round((Date.parse(endsAt) - now) / 60_000));
+    return `in about ${minutes} minutes, at ${new Date(endsAt).toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" })}: the free tunnel's limit (mason share again gives a new address and a new password)`;
+}
+/** What a tunnel's address is checked to be, once the client gave it: the Failure when something else answers there. */
+async function verified(t, fingerprint) {
+    const probe = await probeShare(t, fingerprint);
+    if (probe === "other") {
+        return { message: `${t.host}:${t.port} is not this share: something else answers there`, code: "failed", why: "the tunnel printed that address, and the certificate there is not this share's: its output may have changed, or something stands in the way",
+            fix: "nothing was left open. Do not connect a tool to that address", next: [["mason share --via bore", "another tunnel"]] };
+    }
+    return probe === "same";
+}
+export async function share(argv) {
+    const f = parseCommand(SHARE, argv);
+    if (typeof f === "number")
+        return f;
+    const v = f.values;
+    const json = v.json;
+    if (f.positionals.length)
+        return failed("share", { message: "it takes no argument: --role names what it reads", code: "usage", usage: SHARE.usage }, { json });
+    const via = (v.via ?? "pinggy");
+    if (!TUNNELS.includes(via))
+        return failed("share", { message: `--via must be ${TUNNELS.join(" or ")}, not ${JSON.stringify(v.via)}`, code: "usage", usage: SHARE.usage }, { json });
+    const timeoutS = v.timeout === undefined ? DEFAULT_TIMEOUT_S : Number(v.timeout);
+    if (!Number.isFinite(timeoutS) || timeoutS <= 0)
+        return failed("share", { message: `--timeout is a number of seconds, not ${JSON.stringify(v.timeout)}`, code: "usage" }, { json });
+    const w = await reach(SHARE, json);
+    if (w === null || !("run" in w))
+        return 1;
+    const { run, project } = w;
+    const token = via === "pinggy" ? appEnvValue(project.root, "MASON_PINGGY_TOKEN")?.value ?? null : null;
+    if (token !== null && !TOKEN_RE.test(token)) {
+        return failed("share", { message: "MASON_PINGGY_TOKEN is not a token: it holds a character no Pinggy token has", code: "usage", fix: "set it to the token as the Pinggy dashboard shows it" }, { json });
+    }
+    return guarded("share", json, async () => {
+        sweepTunnelFiles(project.dir, alive);
+        const password = newSharePassword();
+        const held = await openOnRun(run, shareSecret(password), v.role, json);
+        if ("message" in held)
+            return failed("share", held, { json });
+        const opened = held.first;
+        return holding({ run, held, opened, password, json, plan: () => tunnelPlan(via, { port: opened.port, home: project.dir, token }), timeoutMs: timeoutS * 1000 });
+    });
+}
+/** The share from its socket on: the tunnel, the report, and the wait for its end. Everything is left closed on every way out. */
+/** `send`, each call begun once the one before ended: an "up" must never be overtaken and set back by its "opening". */
+export function inOrder(send) {
+    let last = Promise.resolve();
+    return (t) => (last = last.then(() => send(t)));
+}
+async function holding(h) {
+    const { run, held, opened, password, json } = h;
+    const tell = inOrder(async (t) => {
+        // what mason status shows, and the run's way to stop the client: the run gone is said by `held.ended`, the share's end
+        await callRun(run, "POST", `/api/share/${encodeURIComponent(opened.user)}`, t).catch((e) => say(`  the run was not told of the tunnel: ${e.message}`));
+    });
+    const stop = new Promise((resolve) => { process.once("SIGINT", () => resolve("SIGINT")); process.once("SIGTERM", () => resolve("SIGTERM")); });
+    const runEnded = held.ended.then((why) => ({ runEnded: why ?? "the connection to Mason was lost" }));
+    const steps = stepRenderer({ line: (t) => { if (!json)
+            say(t); }, live: !json && process.stderr.isTTY ? { write: (t) => { process.stderr.write(t); } } : null, style: styleErr() });
+    steps.done(`A socket of its own for the share, TLS required (127.0.0.1:${opened.port})`);
+    const open = async () => {
+        const plan = h.plan();
+        const t = await startTunnel(plan, { timeoutMs: h.timeoutMs, onPid: (pid) => { void tell({ pid, via: plan.via, state: "opening" }); } });
+        if ("message" in t)
+            return t;
+        const checked = await verified(t, opened.fingerprint);
+        if (typeof checked !== "boolean") {
+            t.stop();
+            return checked;
+        }
+        return { tunnel: t, verified: checked };
+    };
+    const plan = h.plan();
+    steps.begin(`Opening a tunnel (${plan.via})`);
+    const opening = open();
+    const first = await Promise.race([opening, stop, runEnded]);
+    if (typeof first === "string" || "runEnded" in first) {
+        // ended while it opened: the tunnel, if it comes, goes at once
+        void opening.then((o) => { if ("tunnel" in o)
+            o.tunnel.stop(); }).catch((e) => say(`  the tunnel: ${e.message}`));
+        steps.fail();
+        held.close();
+        return typeof first === "string" ? 0 : failed("share", ended(first.runEnded), { json });
+    }
+    if ("message" in first) {
+        steps.fail();
+        held.close();
+        return failed("share", first, { json });
+    }
+    let tunnel = first.tunnel;
+    steps.done(`Tunnel open: ${tunnel.host}:${tunnel.port}`);
+    await tell({ host: tunnel.host, port: tunnel.port, endsAt: tunnel.endsAt, state: "up", pid: tunnel.pid });
+    const next = [["mason status", "the share, its sessions and the logins refused"], ["mason logs --requests", "what the tool asks"]];
+    if (json) {
+        out(jsonText(SHARE, { share: { host: tunnel.host, port: tunnel.port, database: opened.database, user: opened.user, password, sslmode: "require", fingerprint: opened.fingerprint,
+                role: opened.role, reads: opened.reads, via: plan.via, endsAt: tunnel.endsAt, verified: first.verified } }, next));
+    }
+    else {
+        const st = styleOut();
+        out(reportText({
+            headline: "Sharing the synced data with a tool outside this machine",
+            details: [["host", tunnel.host], ["port", String(tunnel.port)], ["database", opened.database], ["user", opened.user], ["password", password], ["sslmode", "require"],
+                ["certificate", `SHA-256 ${opened.fingerprint}`], ["reads", opened.role === null ? `${opened.reads} (this project has no roles file)` : `the role ${opened.role}: ${opened.reads}`],
+                ["via", plan.via], ["ends", endsText(tunnel.endsAt, Date.now())]],
+            tips: [
+                "Paste it into the tool now: the password is printed this once, is kept nowhere, and ends with this command.",
+                ...(opened.role === null ? ["With no roles file, anyone with this address and password reads every synced table: mason/roles.yml narrows it."] : []),
+                ...(first.verified ? [] : [`${tunnel.host}:${tunnel.port} could not be reached from this machine, so it is not verified: a firewall here may be why, and a tool elsewhere may reach it.`]),
+                "A self-signed certificate: a service that forwards bytes cannot read them, a malicious one could sit in the middle. For anything lasting: mason help production.",
+            ],
+            next,
+        }, st));
+        say("Holding the share: Ctrl-C ends it.");
+    }
+    // THE WAIT: the signal, the run, or the tunnel; a tunnel that keeps its address is opened again
+    for (;;) {
+        const end = await Promise.race([stop, runEnded, tunnel.ended.then((why) => ({ tunnelEnded: why }))]);
+        if (typeof end === "string") {
+            tunnel.stop();
+            await Promise.race([tunnel.ended, new Promise((r) => setTimeout(r, 2_500).unref())]);
+            held.close();
+            if (json)
+                say("The share ended.");
+            else
+                out(reportText({ headline: "The share ended: its address no longer answers, and its password no longer works", next: [["mason share", "a new address and a new password"]] }));
+            return 0;
+        }
+        if ("runEnded" in end) {
+            tunnel.stop();
+            held.close();
+            return failed("share", ended(end.runEnded), { json: false });
+        }
+        if (!plan.reconnects) {
+            held.close();
+            return failed("share", { ...ended(`its tunnel closed (${end.tunnelEnded})`), fix: "a free tunnel lasts about an hour: the address is gone, and the password no longer works" }, { json: false });
+        }
+        const again = await reconnect({ open, tell, why: end.tunnelEnded, stop, runEnded, was: tunnel });
+        if (again === null)
+            continue; // a signal or the run's end: the next turn of the loop reads it
+        tunnel = again;
+    }
+}
+/** The share's end as a failure: what ended it, and the one way on. */
+const ended = (why) => ({ message: `the share ended: ${why}`, code: "failed", next: [["mason share", "a new address and a new password"]] });
+/** Opens a dropped tunnel again until it is up, saying so each time; null when a signal or the run's end came first. */
+async function reconnect(o) {
+    say(`The tunnel dropped (${o.why}): opening it again; the password stays the same.`);
+    await o.tell({ state: "reconnecting" });
+    let waitMs = RECONNECT_FIRST_MS;
+    for (;;) {
+        const waited = await Promise.race([new Promise((r) => setTimeout(() => r("waited"), waitMs).unref()), o.stop.then(() => "ended"), o.runEnded.then(() => "ended")]);
+        if (waited === "ended")
+            return null;
+        const opening = o.open();
+        const got = await Promise.race([opening, o.stop.then(() => null), o.runEnded.then(() => null)]);
+        if (got === null) {
+            void opening.then((a) => { if ("tunnel" in a)
+                a.tunnel.stop(); }).catch((e) => say(`  the tunnel: ${e.message}`));
+            return null;
+        }
+        if ("tunnel" in got) {
+            const t = got.tunnel;
+            const moved = t.host !== o.was.host || t.port !== o.was.port;
+            say(moved ? `Reconnected, at a NEW address: host ${t.host}, port ${t.port}. The password is the same; the tool needs the new host and port.` : `Reconnected: ${t.host}:${t.port}, the same address and password.`);
+            await o.tell({ host: t.host, port: t.port, endsAt: t.endsAt, state: "up", pid: t.pid });
+            return t;
+        }
+        say(`  not yet: ${got.message}${got.why ? ` (${got.why})` : ""}; trying again in ${waitMs / 1000} s`);
+        waitMs = Math.min(waitMs * 2, RECONNECT_MAX_MS);
+    }
+}