@mason-data/cli 0.0.0-stage → 0.7.0

package/dist/src/cli/pg-tls.js

@@ -0,0 +1,100 @@
+/**
+ * THE RUN'S POSTGRES LISTENER, REACHABLE FROM ANOTHER MACHINE (docs/POSTGRES-API.md "Connecting"). On
+ * a test server a hosted BI tool had to reach the run, which listened on 127.0.0.1 with no TLS, and a TLS proxy was
+ * written beside Mason for it. Now `mason start` reads where and how its listener listens with the one reader the
+ * ClickHouse stack's Query API used too (`pgListenerSettings`, src/api/postgres/listener.ts): `MASON_PG_HOST` (default
+ * 127.0.0.1), the port `mason start` chose (`MASON_PG_PORT`'s, or a free one), `MASON_PG_TLS_CERT` / `MASON_PG_TLS_KEY`, and the plain-listener rule
+ * (src/api/postgres/plain.ts): off loopback it needs TLS, or `MASON_PG_PLAIN=1` for a team that terminates TLS in a
+ * proxy of its own.
+ *
+ * `--self-signed-tls` (named for what the developer gets, in the variables' own word, TLS) is a certificate made for
+ * the project in its `.mason/` (0600), recorded in its config and reused by every later start with the flag; it is
+ * handed to the same reader through the same two variables, never a second path. With TLS the listener requires it of
+ * every client (src/api/postgres/server.ts: a plain startup is refused, 28000).
+ */
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { isLoopback } from "../api/postgres/plain.js";
+import { pgListenerSettings } from "../api/postgres/listener.js";
+import { selfSignedCertificate } from "./self-signed-cert.js";
+/** the self-signed certificate's files, in the project's `.mason/` */
+export const SELF_SIGNED_FILES = { cert: "postgres-tls.crt", key: "postgres-tls.key" };
+/**
+ * Where and how the run's listener listens: the shell's `MASON_PG_*` with the port `mason start` chose and, under
+ * `--self-signed-tls`, the project's own files as the certificate — or why not, as a Problem (what, why, the way out).
+ * Reads no file: `mason start` asks it before it spawns the run, and the run before it connects to the database.
+ */
+export function runListenerSettings(shell, o) {
+    if (o.selfSigned && (shell.MASON_PG_TLS_CERT || shell.MASON_PG_TLS_KEY)) {
+        return { problem: "--self-signed-tls makes a certificate, and MASON_PG_TLS_CERT / MASON_PG_TLS_KEY name one: one or the other", code: "usage",
+            fix: "drop --self-signed-tls to serve your certificate, or unset MASON_PG_TLS_CERT and MASON_PG_TLS_KEY to serve a self-signed one" };
+    }
+    const s = pgListenerSettings({
+        MASON_PG_HOST: shell.MASON_PG_HOST, MASON_PG_PORT: String(o.port), MASON_PG_PLAIN: shell.MASON_PG_PLAIN,
+        MASON_PG_TLS_CERT: o.selfSigned ? path.join(o.home, SELF_SIGNED_FILES.cert) : shell.MASON_PG_TLS_CERT,
+        MASON_PG_TLS_KEY: o.selfSigned ? path.join(o.home, SELF_SIGNED_FILES.key) : shell.MASON_PG_TLS_KEY,
+    }, "127.0.0.1");
+    if (!("problem" in s))
+        return s;
+    return { problem: s.problem, code: "refused", ...(s.why ? { why: s.why } : {}),
+        // the run makes a certificate where the service cannot: said beside the variables
+        ...(s.fix ? { fix: s.kind === "plain" ? `${s.fix}. Or mason start --self-signed-tls: a certificate made for this project in .mason/` : s.fix } : {}),
+        ...(s.kind === "plain" ? { next: [["mason start --self-signed-tls", "TLS from a certificate made in .mason/ (clients connect with sslmode=require)"]] } : {}) };
+}
+/**
+ * The project's self-signed certificate: the one in `.mason/` when it is still good (it parses, its key is its own, it
+ * has not expired), else a new one, both files 0600. `said` is why a new one was made, for the run to print.
+ */
+export function ensureSelfSigned(home, project, now = new Date()) {
+    const certFile = path.join(home, SELF_SIGNED_FILES.cert), keyFile = path.join(home, SELF_SIGNED_FILES.key);
+    const kept = keptCertificate(certFile, keyFile, now);
+    if ("fingerprint" in kept)
+        return { fingerprint: kept.fingerprint, said: null };
+    const made = selfSignedCertificate(`mason-${project}`, { now });
+    for (const [file, text] of [[keyFile, made.key], [certFile, made.cert]]) {
+        fs.writeFileSync(file, text, { mode: 0o600 });
+        fs.chmodSync(file, 0o600); // a file that was there keeps its mode through writeFileSync
+    }
+    return { fingerprint: new crypto.X509Certificate(made.cert).fingerprint256, said: kept.why };
+}
+function keptCertificate(certFile, keyFile, now) {
+    if (!fs.existsSync(certFile) || !fs.existsSync(keyFile))
+        return { why: `made a self-signed certificate: .mason/${SELF_SIGNED_FILES.cert}` };
+    try {
+        const x = new crypto.X509Certificate(fs.readFileSync(certFile));
+        if (!x.checkPrivateKey(crypto.createPrivateKey(fs.readFileSync(keyFile))))
+            return { why: `made a new self-signed certificate: .mason/${SELF_SIGNED_FILES.key} was not the key of .mason/${SELF_SIGNED_FILES.cert}` };
+        if (new Date(x.validTo).getTime() <= now.getTime())
+            return { why: `made a new self-signed certificate: the one in .mason/ expired ${x.validTo}` };
+        return { fingerprint: x.fingerprint256 };
+    }
+    catch (e) {
+        return { why: `made a new self-signed certificate: the one in .mason/ could not be read (${e.message})` };
+    }
+}
+/** The certificate's SHA-256 fingerprint, for a client that checks it by hand; or why it is no certificate. */
+export function certificateFingerprint(pem) {
+    try {
+        return new crypto.X509Certificate(pem).fingerprint256;
+    }
+    catch (e) {
+        return { problem: `MASON_PG_TLS_CERT is not a PEM certificate: ${e.message}` };
+    }
+}
+/** What the listener serves, one line: its address, then TLS (whose certificate) or plain (and on what network). */
+export function listenerText(l, port) {
+    const every = l.host === "0.0.0.0" || l.host === "::";
+    const address = `${l.host.includes(":") ? `[${l.host}]` : l.host}:${port}${every ? " (every address of this machine)" : ""}`;
+    if (l.tls !== null) {
+        return `${address}, TLS required: ${l.tls === "self-signed" ? `a self-signed certificate (.mason/${SELF_SIGNED_FILES.cert})` : "the certificate MASON_PG_TLS_CERT names"}` +
+            `${l.fingerprint ? `, SHA-256 ${l.fingerprint}` : ""}`;
+    }
+    return `${address}, ${isLoopback(l.host) ? "plain: this machine only" : "PLAIN under MASON_PG_PLAIN=1: a password travels in clear on that network"}`;
+}
+/** Where a tool on another machine reaches it, when the recorded URL's host is not that: every address is localhost here. */
+export function elsewhereTip(l) {
+    return l.host === "0.0.0.0" || l.host === "::"
+        ? "It listens on every address of this machine: from another machine, put this machine's address or name in place of localhost."
+        : null;
+}

package/dist/src/cli/pg-url.js

@@ -0,0 +1,52 @@
+/**
+ * THE POSTGRES API'S URL, as the commands print it (`mason connect`'s helpers before it went: `mason user` is the one
+ * credential). A run records where its listener is as `postgresql://<host>:<port>/<database>` with no credential
+ * (src/cli/dev.ts); `mason user add` prints the URL a tool pastes, with the user and its password in it; `mason start`
+ * and `mason status` print it with the credential's PLACE shown, never a credential. WHAT A PERSON SEES BEGINS
+ * `postgres://` (a printed `postgresql://` read as inconsistent with everything else the CLI shows): the scheme every
+ * example, usage line and `mason init` uses; the recorded form keeps `postgresql://` (both are libpq's), and
+ * `withoutPlaceholders` maps the shown form back to it.
+ */
+import { shellWord } from "../lib/shell-word.js";
+import { elsewhereTip } from "./pg-tls.js";
+/** The parts of a recorded `postgresql://<host>:<port>/<database>`. A URL that is not one is a bug in what wrote it, said so. */
+export function postgresLink(recorded) {
+    let u;
+    try {
+        u = new URL(recorded);
+    }
+    catch {
+        throw new Error(`the recorded Postgres API ${JSON.stringify(recorded)} is not a URL`);
+    }
+    if (u.protocol !== "postgresql:" || !u.port || u.pathname.length < 2)
+        throw new Error(`the recorded Postgres API ${JSON.stringify(recorded)} is not postgresql://<host>:<port>/<database>`);
+    // a bracketed IPv6 host is spelled as the driver takes it
+    const sslmode = u.searchParams.get("sslmode");
+    if (sslmode !== null && sslmode !== "require")
+        throw new Error(`the recorded Postgres API ${JSON.stringify(recorded)} has sslmode=${sslmode}: a run records require or none`);
+    return { url: recorded, host: u.hostname.replace(/^\[|\]$/g, ""), port: Number(u.port), database: decodeURIComponent(u.pathname.slice(1)), ...(sslmode ? { sslmode } : {}) };
+}
+/** The connection URL a tool takes: the link with a user and its password, each escaped for a URL; with `password`
+ *  null, the user alone (psql takes the password from PGPASSWORD). */
+export function connectionUrl(link, user, password) {
+    const host = link.host.includes(":") ? `[${link.host}]` : link.host;
+    return `postgres://${encodeURIComponent(user)}${password === null ? "" : `:${encodeURIComponent(password)}`}@${host}:${link.port}/${encodeURIComponent(link.database)}` +
+        (link.sslmode ? `?sslmode=${link.sslmode}` : "");
+}
+/** The recorded URL with the credentials' PLACE shown — `postgres://<user>:<password>@host:port/db` — for a line that
+ *  must never carry a credential (mason start, mason status). */
+export const withPlaceholders = (recorded) => recorded.replace(/^postgresql:\/\//, "postgres://<user>:<password>@");
+/** The recorded URL back from its placeholder form (mason start's relay reads its own line). */
+export const withoutPlaceholders = (shown) => shown.replace(/^postgres:\/\/<user>:<password>@/, "postgresql://");
+/** The psql line for a URL, quoted for a shell. */
+export const psqlLine = (url) => `psql ${shellWord(url)}`;
+/** What a tool connecting to the listener should know: it listens on every address; its certificate is self-signed. */
+export function listenerTips(l) {
+    if (l === null)
+        return [];
+    const elsewhere = elsewhereTip(l);
+    return [
+        ...(elsewhere ? [elsewhere] : []),
+        ...(l.tls === "self-signed" ? [`The certificate is self-signed: sslmode=require encrypts and checks no certificate; to check it by hand, its SHA-256 is ${l.fingerprint ?? "in mason status"}.`] : []),
+    ];
+}

package/dist/src/cli/pin.js

@@ -0,0 +1,36 @@
+/**
+ * THE PROJECT'S VERSION PIN, as the mason command holds it (src/lib/project-version.ts has the rule and the image's
+ * side): `mason init` writes `mason.yml` with this command's version, `mason start` writes it into a project made
+ * before there was one, and `mason init` and `mason start` refuse a command of another release line — what the
+ * developer runs is then what production's image is held to.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { parseVersion, pinFileText, pinProblem, readPin, versionText, PIN_FILE } from "../lib/project-version.js";
+/** Why this mason command may not run the project in `folder`, or null (a checkout's `dev` checks nothing). */
+export function cliPinProblem(folder, cliVersion) {
+    const running = parseVersion(cliVersion);
+    if (running === null)
+        return null;
+    const read = readPin(folder);
+    if ("problem" in read)
+        return read.problem;
+    if (read.pin === null)
+        return null;
+    const p = versionText(read.pin);
+    return pinProblem(read.pin, running, read.file, "this mason command", `Run the mason command it names: npm i -g @mason-data/cli@${p} (or npx @mason-data/cli@${p} …).`);
+}
+/**
+ * Write `folder`'s mason.yml with this command's version when it has none; the file written, or null when there was one
+ * already (or this is a checkout's `dev`, which has no version to write).
+ */
+export function ensurePin(folder, cliVersion) {
+    if (parseVersion(cliVersion) === null)
+        return null;
+    const file = path.join(folder, PIN_FILE);
+    if (fs.existsSync(file))
+        return null;
+    fs.mkdirSync(folder, { recursive: true });
+    fs.writeFileSync(file, pinFileText(cliVersion));
+    return file;
+}

package/dist/src/cli/ports.js

@@ -0,0 +1,118 @@
+/**
+ * WHETHER A PORT IS FREE, DECIDED IN ONE PLACE (#499 finding 5): `mason start` picks its ports here and
+ * `mason doctor` reports them from here, so the two cannot disagree.
+ *
+ * A port is free only when no address a client may use is held. A probe of 127.0.0.1 alone binds beside a process on
+ * the wildcard (macOS allows it; OrbStack publishes a container's port on *:5433), and `::` (v6only) binds beside one on
+ * ::1 alone (macOS again: Node binds `localhost` there) — so 127.0.0.1:5433 reached Mason while a container, or a driver
+ * trying ::1 first, reached another server. An address family the machine lacks (no IPv6) holds nothing.
+ *
+ * A probe binds and lets go: it says who holds a port NOW, never that it stays free until the service listens on it.
+ */
+import * as net from "node:net";
+import { DEFAULT_PG_PORT, pgListenerAddress } from "../api/postgres/listener.js";
+export const PROBE_ADDRESSES = ["127.0.0.1", "0.0.0.0", "::", "::1"];
+/** The address that holds `port`, or null when every address binds. */
+export async function portHolder(port) {
+    for (const address of PROBE_ADDRESSES) {
+        const code = await new Promise((resolve) => {
+            const srv = net.createServer();
+            srv.once("error", (e) => resolve(e.code ?? "ERROR"));
+            srv.listen({ port, host: address, ipv6Only: address === "::" }, () => srv.close(() => resolve(null)));
+        });
+        if (code === null || code === "EADDRNOTAVAIL" || code === "EAFNOSUPPORT")
+            continue;
+        return { address, code };
+    }
+    return null;
+}
+/** Why a held port cannot be listened on, in a developer's words. */
+export function heldText(port, held) {
+    return held.code === "EACCES"
+        ? `port ${port} needs root here (a bind on ${held.address} answered EACCES): a port below 1024 is the system's`
+        : `something holds port ${port} on ${held.address} (${held.code})`;
+}
+/**
+ * A port free on every address, preferring `want`; `avoid` are ports already chosen for another listener of the same
+ * start (probed and let go, so a probe would call them free). `skipped` says who held `want` when another was chosen.
+ */
+export async function pickPort(want, avoid = new Set()) {
+    const held = avoid.has(want) ? { address: "this mason start", code: "chosen for another listener" } : await portHolder(want);
+    if (!held)
+        return { port: want };
+    for (let attempt = 0; attempt < 20; attempt++) {
+        // the OS picks on the wildcard, so the port it returns is free there; the probe then checks the other addresses
+        const port = await new Promise((resolve, reject) => {
+            const srv = net.createServer();
+            srv.once("error", reject);
+            srv.listen(0, "0.0.0.0", () => { const a = srv.address(); srv.close(() => resolve(a.port)); });
+        });
+        if (!avoid.has(port) && !(await portHolder(port)))
+            return { port, skipped: held };
+    }
+    throw new Error(`no free TCP port found on this machine after 20 tries (${heldText(want, held)}). Free some ports, then run mason start again`);
+}
+/** A free port, preferring `want` (`pickPort`). */
+export async function freePort(want, avoid) {
+    return (await pickPort(want, avoid)).port;
+}
+const PG_PORT_WAY_OUT = "set another MASON_PG_PORT (1024-65535), or unset it and mason start picks a free port";
+/** `MASON_PG_PORT` as the shell gives it, before any probe: a port to listen on, or why it is not one. */
+export function namedPgPort(named) {
+    const parsed = pgListenerAddress({ MASON_PG_PORT: named }, "127.0.0.1");
+    if ("problem" in parsed)
+        return { problem: parsed.problem, code: "refused", fix: PG_PORT_WAY_OUT };
+    if (parsed.port === 0)
+        return { problem: "MASON_PG_PORT=0 is not a port the Postgres API can be reached on", code: "refused",
+            why: "0 asks the system for any free port, and mason start would record port 0", fix: PG_PORT_WAY_OUT };
+    return { port: parsed.port };
+}
+/** The refusal for a named `MASON_PG_PORT` that is held: what, why (who holds it), the way out. */
+export function heldPgPort(port, held) {
+    return held.code === "EACCES"
+        ? { problem: `MASON_PG_PORT=${port} needs root`, code: "refused", why: heldText(port, held), fix: PG_PORT_WAY_OUT }
+        : { problem: `MASON_PG_PORT=${port} is in use`, code: "refused", why: `${heldText(port, held)}, so the Postgres API cannot listen there`,
+            fix: `stop what holds it (lsof -nP -iTCP:${port} -sTCP:LISTEN names it), or ${PG_PORT_WAY_OUT}` };
+}
+/** The refusal for the PROJECT'S recorded port that is held: it is never swapped, because every tool's saved connection names it. */
+export function heldProjectPort(port, held) {
+    const moved = `MASON_PG_PORT=<n> mason start moves this project to another port (every tool's saved connection must change with it)`;
+    return held.code === "EACCES"
+        ? { problem: `this project's Postgres API port ${port} needs root`, code: "refused", why: heldText(port, held), fix: moved }
+        : { problem: `this project's Postgres API port ${port} is in use`, code: "refused",
+            why: `${heldText(port, held)}, so the Postgres API cannot listen there; the port is the project's since its first start, so a tool's saved connection keeps working`,
+            fix: `stop what holds it (lsof -nP -iTCP:${port} -sTCP:LISTEN names it), or ${moved}` };
+}
+/**
+ * THE POSTGRES API'S PORT, THE PROJECT'S OWN (it must not change at every restart, even on a laptop, or every BI
+ * tool's saved credentials need updating each time). `recorded` is
+ * the port the project's first start chose (`ProjectConfig.pgPort`): every later start uses it, or is REFUSED by name
+ * when it is held (`heldProjectPort`), never moved to another port by itself. `MASON_PG_PORT` set in the shell is the
+ * developer naming it, or moving the project to it: used if free on every address, else REFUSED by name, and said as a
+ * move when it differs from the recorded one. With neither, 5433 is preferred and the next free port taken, and `said`
+ * names the address that held 5433 (often a second Postgres: an application's own stack); the caller records the choice.
+ * `avoid`: ports this start has already chosen. Free at the probe, not reserved (above): a later holder is the
+ * service's EADDRINUSE to say.
+ */
+export async function choosePgPort(named, avoid = new Set(), recorded = null) {
+    if (named !== undefined && named !== "") {
+        const n = namedPgPort(named);
+        if ("problem" in n)
+            return n;
+        const held = avoid.has(n.port) ? { address: "this mason start", code: "chosen for another listener" } : await portHolder(n.port);
+        if (held)
+            return heldPgPort(n.port, held);
+        const moved = recorded !== null && recorded !== n.port ? `, moved from ${recorded}: every tool's saved connection must change to it` : "";
+        return { port: n.port, said: `Postgres API: port ${n.port} (from MASON_PG_PORT)${moved}` };
+    }
+    if (recorded !== null) {
+        const held = avoid.has(recorded) ? { address: "this mason start", code: "chosen for another listener" } : await portHolder(recorded);
+        if (held)
+            return heldProjectPort(recorded, held);
+        return { port: recorded };
+    }
+    const { port, skipped } = await pickPort(DEFAULT_PG_PORT, avoid);
+    return skipped
+        ? { port, said: `Postgres API: ${heldText(DEFAULT_PG_PORT, skipped)}, often another Postgres, so using ${port}, this project's port from now on (MASON_PG_PORT=<n> mason start moves it)` }
+        : { port };
+}