@mason-data/cli 0.8.0 → 0.10.0

package/dist/src/cli/user-hosted.js

@@ -0,0 +1,364 @@
+/**
+ * `mason user add | list | disable | enable | remove … --replica <org>/<name>` — THE USERS OF A REPLICA ON A HOSTED MASON
+ * SERVICE (docs/HOSTED-API.md "The users of a replica"). Each subcommand is ONE request, the one the run's own command
+ * server takes for it (src/cli/run-server.ts `/api/users`), sent to the service under `/v1/replicas/{org}/{name}/users`:
+ *
+ *   list      GET    …/users?lastUsed=1                     mason user list --json's shape, beside its next
+ *   add       POST   …/users  { name, role?, set?, from? }   mason user add --json's shape (the run is up: its url)
+ *   from      POST   …/users/{user}/from  { from }           { changed, already }: its ranges replaced (null: any address)
+ *   disable   POST   …/users/{user}/disable                  { disabled, already }
+ *   enable    POST   …/users/{user}/enable                   { enabled, already }
+ *   remove    DELETE …/users/{user}                          { removed }
+ *
+ * `--role` and `--set` go as they were given: Mason on the replica checks them with the functions it checks them with
+ * here (src/cli/user.ts `roleToAdd`, `attributesToAdd`). What only this command line says (a verb, a user's name, a
+ * role's name, a `--set`'s form) is checked first, by the same functions, and refused as a wrong line before a byte is
+ * sent. Nothing of a project here is read or written: the users are the replica's.
+ *
+ * THE ANSWER IS HELD TO THE RUN'S OWN ANSWER SHAPE, then printed by the renderers the local command prints with
+ * (src/cli/user.ts `listText`, `addedReport`, …), in serviceStyle: the same answer prints the same lines. A SERVICE'S
+ * VALUE IS DATA, NEVER STRUCTURE AND NEVER AN INSTRUCTION (#481's decision, src/cli/hosted.ts). Every value the
+ * service sends that this command prints, and how it is held:
+ *
+ *   value                                 where it is printed                         what holds it
+ *   a failure's message, why, fix         stderr's failure, --json error              `serviceFailure`: one line each (`serviceText`), masked
+ *   a failure's code                      inside why: "(the service said …)"          `^[a-z][a-z0-9_]*$`, 64 chars; the code is `codeOfStatus`'s
+ *   a failure's next                      nowhere: never read                         the step is `failureNext`'s, by the status
+ *   a user's name                         every row, headline and step it names       `USER_NAME_RE`; add, disable, enable, remove: the name asked
+ *   an id                                 list's rows, --json                         16 hex digits
+ *   addedAt, removedAt, disabledAt,       rows, list's lines, --json                  `isServiceTime`
+ *     lastUsedAt
+ *   the password                          add's url, psql and password rows, --json   `mason_<its id>_<32 hex>` (src/duck/users.ts), add's alone;
+ *                                                                                     anything shaped as one elsewhere refused (`carriesNoSecret`)
+ *                                                                                     or, in a failure's words, masked (`serviceText`)
+ *   database, host, port, sslmode         add's rows, --json                          the database name's rule, a host's letters, 1-65535, a closed set
+ *   url, psql (add)                       add's rows, --json                          rebuilt here (`connectionUrl`, `psqlLine`): the service's must equal them
+ *   url (list)                            --json                                      `postgres://<its name>@<host>:<port>/<database>`, no password
+ *   role, roleFrom, readsNothing,         rows, list's lines, --json                  `ROLE_NAME_RE`; closed sets; booleans; each consistent with the others
+ *     roleKnown, live
+ *   attributes, missingAttributes         rows, list's lines, --json                  `ATTRIBUTE_NAME_RE` names; each value one line (`serviceText`), bounded
+ *   from (a user's address ranges)        rows, list's lines, add's row, --json       null, or 1 to MAX_RANGES ranges each in the one form
+ *                                                                                     src/duck/users.ts `userRanges` writes back (`heldRanges`);
+ *                                                                                     on add and from, exactly the ranges sent, else the answer
+ *                                                                                     is refused whole (`sameRanges`, `unconfirmed`: fail closed)
+ *   lastUsedNote, urlNote                 list's tip "Last used: …", --json           one line (`serviceText`), bounded
+ *   requestLogDays                        list's lines, --json                        a whole number, 1 to 36500
+ *   already                               the headline chosen, --json                 a boolean
+ *   an HTTP status                        a failure's why                             a number
+ *
+ * BEFORE ANY OF THESE, every string of the answer, its keys included, is put to the exact test (src/cli/hosted.ts
+ * `carriesNoSecret`, `carriesSecret` on each: an echo of the held token, `ECHO_RUN` of its body in a row in one string; a
+ * token's or a password's shape — add's own password, url and psql for the token alone): an answer that carries one
+ * anywhere is refused whole, so no grammar is ever the only thing between a secret and the output, and an honest answer
+ * is refused with a probability under 1 in a million whatever its size. A failure's code, printed inside why, is put to
+ * the same test (`failureShape`). The free text (the notes, a refusal's words) is masked too, by #591's quarter rule.
+ *
+ * An answer any of which does not hold is outside the contract: said by the request and its status, never its body.
+ * What to run next is the CLI's own (`onReplica`: the local command's steps, each `mason user …` naming the replica).
+ */
+import { failed, jsonText, serviceStyle } from "./command.js";
+import { call, carriesNoSecret, isFailure, isServiceTime, serviceFailure, serviceNext, serviceOf, serviceText, unexpected } from "./hosted.js";
+import { replicaText, tokenFor } from "./replica.js";
+import { holdOutput } from "./output-gate.js";
+import { err as styleErr, out as styleOut } from "./style.js";
+import { connectionUrl, psqlLine } from "./pg-url.js";
+import { MAX_RANGES, USER_NAME_RE, userRanges } from "../duck/users.js";
+import { ROLE_NAME_RE } from "./roles.js";
+import { ATTRIBUTE_NAME_RE } from "../duck/row-filter.js";
+import { databaseNameProblem } from "../lib/database-name.js";
+import { NO_ROLES } from "../duck/grants.js";
+import { addedNext, addedReport, disabledNext, disabledReport, enabledNext, enabledReport, fromNext, fromReport, listNext, listText, REMOVED_NEXT, removedReport, USER } from "./user.js";
+/** The bound of a list's answer (a replica's users, a row each), and of the number of users in it; every other answer
+ *  is `call`'s own 64 KiB. */
+export const MAX_LIST_BYTES = 1024 * 1024;
+export const MAX_USERS = 2000;
+const out = (m) => { process.stdout.write(`${m}\n`); };
+const obj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const ID = /^[0-9a-f]{16}$/;
+const HOST = /^(?:[A-Za-z0-9](?:[A-Za-z0-9-]{0,62})(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,62}))*\.?|[0-9A-Fa-f:.]{2,45})$/;
+const ROLE_FROM = ["file", "default", "none"];
+/** The local command's next steps, as a replica's: each `mason user …` names the replica, so it runs against it. */
+export const onReplica = (steps, r) => steps.map(([command, ...what]) => [command.startsWith("mason user ") ? `${command} --replica ${replicaText(r)}` : command, ...what]);
+/** What to run after the service refused a request about a replica's users: the CLI's own, by the status (never the
+ *  service's `next`): sign in again for a 401 or 403, else the replica's users. */
+export const failureNext = (status, r) => status === 401 || status === 403 ? serviceNext(status) : [[`mason user list --replica ${replicaText(r)}`, "the replica's users"]];
+/** The request a subcommand is: the run's own `/api/users` request, under the replica's path. */
+export function requestOf(r, o) {
+    const base = `/v1/replicas/${r.org}/${r.name}/users`;
+    // a user's name is USER_NAME_RE's (checked before this): letters, digits, `_`, `.` and `-`, safe in a path as it is
+    switch (o.verb) {
+        case "list": return { method: "GET", path: `${base}?lastUsed=1` };
+        case "add": return { method: "POST", path: base, json: { name: o.name, ...(o.role !== undefined ? { role: o.role } : {}), ...(o.sets.length ? { set: [...o.sets] } : {}),
+                ...(o.from !== undefined && o.from !== null ? { from: [...o.from] } : {}) } };
+        case "from": return { method: "POST", path: `${base}/${o.name}/from`, json: { from: o.from === undefined || o.from === null ? null : [...o.from] } };
+        case "disable":
+        case "enable": return { method: "POST", path: `${base}/${o.name}/${o.verb}` };
+        case "remove": return { method: "DELETE", path: `${base}/${o.name}` };
+    }
+}
+// ------------------------------------------------------------------ the answers, held to the run's own shapes
+/** A string the service sends, as one line: null when it is not a string. */
+const line = (v, max, secrets) => typeof v === "string" ? serviceText(v, max, secrets) : null;
+/** A user's role fields, each consistent with the others (src/cli/roles.ts userRole): a role for `file` and `default`,
+ *  none for `none`, `readsNothing` only where there is none. */
+function roleOf(u) {
+    if (typeof u.roleFrom !== "string" || !ROLE_FROM.includes(u.roleFrom))
+        return null;
+    const roleFrom = u.roleFrom;
+    if (u.role !== undefined && (typeof u.role !== "string" || !ROLE_NAME_RE.test(u.role)))
+        return null;
+    if ((roleFrom === "none") !== (u.role === undefined))
+        return null;
+    if (u.readsNothing !== undefined && (u.readsNothing !== true || roleFrom !== "none"))
+        return null;
+    return { ...(typeof u.role === "string" ? { role: u.role } : {}), roleFrom, ...(u.readsNothing === true ? { readsNothing: true } : {}) };
+}
+/** A user's attributes: at most 64 names, each a value (one line, bounded) or a list of 1 to 100 of them. A value is a
+ *  value (a tenant's id), put to the exact test with every string (`carriesNoSecret`), so it is made one line here
+ *  without the quarter rule of free text, which a thousand random ids would trip by chance (PR 609's review). */
+function attributesOf(v) {
+    if (!obj(v) || Object.keys(v).length > 64)
+        return null;
+    const outv = {};
+    for (const [k, x] of Object.entries(v)) {
+        if (!ATTRIBUTE_NAME_RE.test(k))
+            return null;
+        if (typeof x === "string")
+            outv[k] = serviceText(x, 1000);
+        else if (Array.isArray(x) && x.length >= 1 && x.length <= 100 && x.every((y) => typeof y === "string"))
+            outv[k] = x.map((y) => serviceText(y, 1000));
+        else
+            return null;
+    }
+    return outv;
+}
+/** A user's address ranges as the service sends them: null (any address), or 1 to MAX_RANGES ranges, each in the one form
+ *  the one grammar writes back (src/duck/users.ts `userRanges`); undefined when they are not that. */
+export function heldRanges(v) {
+    if (v === null)
+        return null;
+    if (!Array.isArray(v) || v.length < 1 || v.length > MAX_RANGES || !v.every((x) => typeof x === "string" && x.length <= 64))
+        return undefined;
+    const r = userRanges(v);
+    return "problem" in r || r.from.length !== v.length || r.from.some((x, i) => x !== v[i]) ? undefined : r.from;
+}
+const names = (v) => Array.isArray(v) && v.length >= 1 && v.length <= 64 && v.every((x) => typeof x === "string" && ATTRIBUTE_NAME_RE.test(x));
+const timeOrNull = (v) => v === null || isServiceTime(v);
+/** One row of a list, as `listUsers` makes it (src/cli/user.ts `UserRow`); null when it is not that shape. */
+function rowOf(v) {
+    if (!obj(v))
+        return null;
+    const u = v;
+    if (typeof u.name !== "string" || !USER_NAME_RE.test(u.name) || typeof u.id !== "string" || !ID.test(u.id) || !isServiceTime(u.addedAt)
+        || !timeOrNull(u.removedAt) || !timeOrNull(u.disabledAt) || !timeOrNull(u.lastUsedAt) || typeof u.live !== "boolean")
+        return null;
+    // the URL a tool pastes, WITHOUT the password: its own name, then where the replica listens
+    if (u.url !== null && !(typeof u.url === "string" && u.url.length <= 600 && u.url.startsWith(`postgres://${u.name}@`)
+        && /^postgres:\/\/[a-z0-9_.-]+@(?:[A-Za-z0-9.-]+|\[[0-9A-Fa-f:.]+\]):\d{1,5}\/[A-Za-z0-9%._~!*'()-]+(?:\?sslmode=require)?$/.test(u.url)))
+        return null;
+    const role = roleOf(u);
+    if (role === null)
+        return null;
+    // a replica's Mason before address ranges sends none: it has none, so any address
+    const from = u.from === undefined ? null : heldRanges(u.from);
+    if (from === undefined)
+        return null;
+    const attributes = u.attributes === undefined ? undefined : attributesOf(u.attributes);
+    if (attributes === null)
+        return null;
+    if (u.missingAttributes !== undefined && !names(u.missingAttributes))
+        return null;
+    if (u.roleKnown !== undefined && (typeof u.roleKnown !== "boolean" || role.roleFrom !== "file"))
+        return null;
+    return { name: u.name, id: u.id, addedAt: u.addedAt, removedAt: u.removedAt, disabledAt: u.disabledAt, live: u.live, lastUsedAt: u.lastUsedAt,
+        url: u.url, from, ...role, ...(attributes !== undefined ? { attributes } : {}),
+        ...(u.missingAttributes !== undefined ? { missingAttributes: u.missingAttributes } : {}),
+        ...(typeof u.roleKnown === "boolean" ? { roleKnown: u.roleKnown } : {}) };
+}
+/** `GET …/users?lastUsed=1`'s answer: mason user list --json's shape (its `next` never read); null when it is not it. */
+export function heldList(json, secrets) {
+    if (!obj(json) || !Array.isArray(json.users) || json.users.length > MAX_USERS || !carriesNoSecret(json, secrets))
+        return null;
+    const users = [];
+    for (const v of json.users) {
+        const u = rowOf(v);
+        if (u === null)
+            return null;
+        users.push(u);
+    }
+    const note = (v) => v === null ? null : line(v, 500, secrets) ?? undefined;
+    const lastUsedNote = note(json.lastUsedNote), urlNote = note(json.urlNote);
+    const days = json.requestLogDays;
+    if (lastUsedNote === undefined || urlNote === undefined || !(days === null || (Number.isInteger(days) && days >= 1 && days <= 36500)))
+        return null;
+    return { users, lastUsedNote, urlNote, requestLogDays: days };
+}
+/** `POST …/users`'s answer: mason user add --json's shape with Mason up — where it listens, the URL rebuilt here by the
+ *  one builder and equal to the service's —, for the name asked; null when it is not it. */
+export function heldAdded(json, asked, secrets) {
+    if (!obj(json) || !carriesNoSecret(json, secrets, ["password", "url", "psql"]))
+        return null;
+    const a = json;
+    if (a.user !== asked || typeof a.id !== "string" || !ID.test(a.id) || !isServiceTime(a.addedAt))
+        return null;
+    // the password is the user's, by its one grammar: its id, then its MAC
+    if (typeof a.password !== "string" || !new RegExp(`^mason_${a.id}_[0-9a-f]{32}$`).test(a.password))
+        return null;
+    if (typeof a.database !== "string" || databaseNameProblem(a.database) !== null || serviceText(a.database, 63) !== a.database)
+        return null;
+    if (typeof a.host !== "string" || !HOST.test(a.host) || !Number.isInteger(a.port) || a.port < 1 || a.port > 65535)
+        return null;
+    if (a.sslmode !== "require" && a.sslmode !== "disable")
+        return null;
+    const url = connectionUrl({ url: "", host: a.host, port: a.port, database: a.database, ...(a.sslmode === "require" ? { sslmode: "require" } : {}) }, asked, a.password);
+    if (a.url !== url || a.psql !== psqlLine(url))
+        return null;
+    const role = roleOf(a);
+    if (role === null)
+        return null;
+    const from = a.from === undefined ? undefined : heldRanges(a.from);
+    // null (any address) is read as no ranges, as a list's row reads it: an add that sent ranges then refuses it unconfirmed
+    if (from === undefined && a.from !== undefined)
+        return null;
+    const attributes = a.attributes === undefined ? undefined : attributesOf(a.attributes);
+    if (attributes === null)
+        return null;
+    return { user: asked, id: a.id, addedAt: a.addedAt, password: a.password, database: a.database, url, psql: psqlLine(url), host: a.host, port: a.port, sslmode: a.sslmode,
+        ...role, ...(attributes !== undefined ? { attributes } : {}), ...(from !== undefined && from !== null ? { from } : {}) };
+}
+/** A user as disable, enable and remove name it: the name asked, its id, when it was added, and `more` times. */
+function userOf(v, asked, more) {
+    if (!obj(v) || v.name !== asked || typeof v.id !== "string" || !ID.test(v.id) || !isServiceTime(v.addedAt) || !more.every((k) => isServiceTime(v[k])))
+        return null;
+    return { name: asked, id: v.id, addedAt: v.addedAt, ...Object.fromEntries(more.map((k) => [k, v[k]])) };
+}
+export function heldDisabled(json, asked, secrets) {
+    if (!obj(json) || typeof json.already !== "boolean" || !carriesNoSecret(json, secrets))
+        return null;
+    const d = userOf(json.disabled, asked, ["disabledAt"]);
+    return d === null ? null : { disabled: d, already: json.already };
+}
+export function heldEnabled(json, asked, secrets) {
+    if (!obj(json) || typeof json.already !== "boolean" || !carriesNoSecret(json, secrets))
+        return null;
+    const e = userOf(json.enabled, asked, []);
+    return e === null ? null : { enabled: e, already: json.already };
+}
+/** `POST …/users/{user}/from`'s answer: the user asked, its ranges now (null: any address), and `already`. */
+export function heldFrom(json, asked, secrets) {
+    if (!obj(json) || typeof json.already !== "boolean" || !carriesNoSecret(json, secrets))
+        return null;
+    const c = userOf(json.changed, asked, []);
+    const from = obj(json.changed) ? heldRanges(json.changed.from) : undefined;
+    return c === null || from === undefined ? null : { changed: { ...c, from }, already: json.already };
+}
+export function heldRemoved(json, asked, secrets) {
+    if (!obj(json) || !carriesNoSecret(json, secrets))
+        return null;
+    const r = userOf(json.removed, asked, ["removedAt"]);
+    return r === null ? null : { removed: r };
+}
+// ------------------------------------------------------------------ the command
+/** Whether the ranges an answer carries are exactly those sent (each in its one form, in order; null: any address). */
+export const sameRanges = (got, sent) => got !== undefined && JSON.stringify(got) === JSON.stringify(sent);
+/**
+ * AN ADDRESS LIMIT THE SERVICE DID NOT CONFIRM: its 200 does not carry the ranges sent (none, null, or others). The
+ * answer is refused whole, never printed (an add's password included): the user may now connect from more addresses
+ * than asked, which only the replica's list can say, and the way out removes it or sets the ranges again.
+ */
+export function unconfirmed(r, name, sent, verb) {
+    const on = `--replica ${replicaText(r)}`;
+    const asked = sent === null ? "any address" : sent.join(", ");
+    return { message: `the service did not confirm ${name}'s address limit: its answer does not carry the ranges sent (${asked})`, code: "failed",
+        why: verb === "add" ? `the replica may have added ${name} with no limit, so it would connect from any address, and its password was not shown`
+            : `the replica may have kept ${name}'s ranges as they were, or set others`,
+        fix: verb === "add" ? `mason user list ${on} says what ${name} has; if it was made without the limit, mason user remove ${name} ${on}`
+            : `mason user list ${on} says what ${name} has now; mason user from ${name} ${sent === null ? "--any" : sent.join(" ")} ${on} sets it again, or mason user remove ${name} ${on}`,
+        next: [[`mason user list ${on}`, "the replica's users and the addresses each connects from"], [`mason user remove ${name} ${on}`, "if it was made without the limit"]] };
+}
+/** What each subcommand asked, in the words of a failure outside the contract (`unexpected`). */
+const STEP = { list: "the replica's users were asked for", add: "a user was added", from: "a user's address ranges were set", disable: "a user was disabled", enable: "a user was enabled", remove: "a user was removed" };
+/** `mason user <verb> … --replica <org>/<name>`: one request, its answer held and printed as the local command prints it. */
+export async function hostedUser(r, o) {
+    const outStyle = serviceStyle(styleOut());
+    const fail = (f) => failed("user", f, { json: o.json, style: serviceStyle(styleErr()) });
+    const service = serviceOf();
+    if (isFailure(service))
+        return fail(service);
+    const token = tokenFor(service, { asked: "a replica's users are asked for", again: `mason user ${o.verb}` });
+    if (isFailure(token))
+        return fail(token);
+    // from here every byte written is put to the exact test against the token (src/cli/output-gate.ts); add prints the
+    // password it made, so a password's shape is its answer's there
+    holdOutput({ command: "user", json: o.json, secrets: [token], passwords: o.verb !== "add" });
+    const secrets = [token];
+    const req = requestOf(r, o);
+    const a = await call(service, req.method, req.path, { token, ...(req.json !== undefined ? { json: req.json } : {}), ...(o.verb === "list" ? { maxBytes: MAX_LIST_BYTES } : {}) });
+    if (isFailure(a))
+        return fail(a);
+    const refused = (x) => serviceFailure(x, secrets, (status) => failureNext(status, r)) ?? unexpected(service, x, STEP[o.verb]);
+    if (a.status !== 200)
+        return fail(refused(a));
+    const outside = () => fail(unexpected(service, a, STEP[o.verb]));
+    // the target in every answer: the replica's name in --json and in the headline
+    const on = replicaText(r);
+    const print = (value, next, text) => {
+        out(o.json ? jsonText(USER, { replica: on, ...value }, next) : text());
+        return 0;
+    };
+    switch (o.verb) {
+        case "list": {
+            const l = heldList(a.json, secrets);
+            if (l === null)
+                return outside();
+            const next = onReplica(listNext(l.users), r);
+            return print({ ...l }, next, () => listText(on, l, NO_ROLES, next, outStyle));
+        }
+        case "add": {
+            const added = heldAdded(a.json, o.name, secrets);
+            // the service answered 200: the replica may have made the user, whose password nobody has now been shown
+            if (added === null) {
+                const f = unexpected(service, a, STEP[o.verb]);
+                return fail({ ...f, why: `${f.why}; the replica may have added ${o.name} all the same, and its password was not shown`,
+                    fix: `mason user list --replica ${replicaText(r)} says whether it did; if so, mason user remove ${o.name} --replica ${replicaText(r)}, then add it again`,
+                    next: [[`mason user list --replica ${replicaText(r)}`, "the replica's users"]] });
+            }
+            // FAIL CLOSED: ranges sent must come back as sent, or the user may have been made with none (a service that does
+            // not know `from` would make it connect from any address), and its password is not shown
+            if (o.from !== undefined && o.from !== null && !sameRanges(added.from, o.from))
+                return fail(unconfirmed(r, o.name, o.from, "add"));
+            const next = onReplica(addedNext(added.user, true), r);
+            return print({ ...added }, next, () => addedReport(added, { roles: NO_ROLES, listener: null, next, on }, outStyle));
+        }
+        case "from": {
+            const c = heldFrom(a.json, o.name, secrets);
+            if (c === null)
+                return outside();
+            if (!sameRanges(c.changed.from, o.from ?? null))
+                return fail(unconfirmed(r, o.name, o.from ?? null, "from"));
+            const next = onReplica(fromNext(c.changed.name, c.changed.from), r);
+            return print({ ...c }, next, () => fromReport(c, true, next, outStyle));
+        }
+        case "disable": {
+            const d = heldDisabled(a.json, o.name, secrets);
+            if (d === null)
+                return outside();
+            const next = onReplica(disabledNext(d.disabled.name), r);
+            return print({ ...d }, next, () => disabledReport(d, true, next, outStyle, on));
+        }
+        case "enable": {
+            const e = heldEnabled(a.json, o.name, secrets);
+            if (e === null)
+                return outside();
+            const next = onReplica(enabledNext(e.enabled.name), r);
+            return print({ ...e }, next, () => enabledReport(e, next, outStyle, on));
+        }
+        case "remove": {
+            const x = heldRemoved(a.json, o.name, secrets);
+            if (x === null)
+                return outside();
+            const next = onReplica(REMOVED_NEXT, r);
+            return print({ removedUser: x.removed, ...x }, next, () => removedReport(x, true, next, outStyle, on));
+        }
+    }
+}