@mason-data/cli 0.8.0 → 0.9.0

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

@@ -0,0 +1,299 @@
+/**
+ * `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? }          mason user add --json's shape (the run is up: its url)
+ *   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
+ *   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 { USER_NAME_RE } 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, 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] } : {}) } };
+        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;
+}
+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;
+    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, ...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 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 } : {}) };
+}
+/** 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 };
+}
+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
+/** 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", 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]));
+    const print = (value, next, text) => {
+        out(o.json ? jsonText(USER, 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(replicaText(r), 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"]] });
+            }
+            const next = onReplica(addedNext(added.user, true), r);
+            return print({ ...added }, next, () => addedReport(added, { roles: NO_ROLES, listener: null, 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));
+        }
+        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));
+        }
+        case "remove": {
+            const x = heldRemoved(a.json, o.name, secrets);
+            if (x === null)
+                return outside();
+            const next = onReplica(REMOVED_NEXT, r);
+            return print({ ...x }, next, () => removedReport(x, true, next, outStyle));
+        }
+    }
+}

package/dist/src/cli/user.js

@@ -11,7 +11,7 @@
  * called by the run's command server; so are `disableUser` and `enableUser`.
  */
 import * as path from "node:path";
-import { failed, jsonText, parseCommand, reportText, withEnd } from "./command.js";
+import { failed, jsonText, parseCommand, reportText, strict, withEnd } from "./command.js";
 import { reach } from "./state.js";
 import { callRun, RunUnreachable } from "./control.js";
 import { connectionUrl, listenerTips, postgresLink, psqlLine } from "./pg-url.js";
@@ -24,16 +24,18 @@ import { ATTRIBUTE_NAME_RE, ATTRIBUTE_NAME_RULE, whereAttributes, whereParts } f
 import { readSource, shownPath } from "./sources.js";
 import { readState } from "./commands.js";
 import { projectDatabase } from "./project.js";
+import { replicaOf } from "./replica.js";
+import { hostedUser } from "./user-hosted.js";
 const out = (m) => { process.stdout.write(`${m}\n`); };
 export const USER = {
     needs: "project",
     name: "user",
     summary: "the users the Postgres API takes: a name and a password that does not expire, for a BI tool or an app",
-    usage: `usage: mason user add <name> [--role <role>] [--set <attribute>=<value> …] [--json]
-       mason user list [--json]
-       mason user disable <name> [--json]
-       mason user enable <name> [--json]
-       mason user remove <name> [--json]
+    usage: `usage: mason user add <name> [--role <role>] [--set <attribute>=<value> …] [--replica <org>/<name>] [--json]
+       mason user list [--replica <org>/<name>] [--json]
+       mason user disable <name> [--replica <org>/<name>] [--json]
+       mason user enable <name> [--replica <org>/<name>] [--json]
+       mason user remove <name> [--replica <org>/<name>] [--json]
 
   A user of this project's Postgres API: a name and a password, as a BI tool's datasource form asks for them
   (Metabase, Grafana, Superset, Power BI) or an app's DATABASE_URL carries them. Its password does not expire:
@@ -91,6 +93,14 @@ export const USER = {
     mason user enable metabase                 metabase connects again, with the same password
     mason user remove metabase                 metabase connects no more
     docker compose exec mason mason user add grafana   beside mason serve, in its data folder
+    mason user add metabase --replica acme/shop          a user of a replica on a hosted Mason service
+
+  --replica <org>/<name> manages the users of a replica on a hosted Mason service instead of this project's (else
+  MASON_REPLICA; each part lower case letters, digits and -): the same subcommands, --role and --set, the same
+  output and --json, the replica's Mason checking each as it does here. It needs no project here, and reads and writes
+  nothing of one. The login is MASON_TOKEN, else this machine's (mason login); the service is MASON_CLOUD_URL, else
+  the default. A refusal is the service's words, each one line, its code the CLI's own by the HTTP status (not_found,
+  refused, failed: never usage), exit 1.
 
   <name>    ${USER_NAME_RULE}
   --json    as data: add { user (the name), id, addedAt, password, database, role (the role it reads as: its own
@@ -106,7 +116,7 @@ export const USER = {
             before) }; enable { enabled: { name, id, addedAt }, already (it was not disabled) }; remove { removed: { name,
             id, addedAt, removedAt } }; next
 `,
-    options: { json: { type: "boolean", default: false }, role: { type: "string" }, set: { type: "string", multiple: true } },
+    options: { json: { type: "boolean", default: false }, role: { type: "string" }, set: { type: "string", multiple: true }, replica: { type: "string" } },
     json: ["user", "id", "addedAt", "password", "url", "psql", "host", "port", "database", "sslmode", "role", "attributes", "roleFrom", "readsNothing", "users", "disabled", "enabled", "already", "removed", "lastUsedNote", "urlNote", "requestLogDays", "next"],
 };
 /** The users of a project and why one is not live: added under an API key since rotated. */
@@ -194,6 +204,9 @@ export function attributesToAdd(name, role, sets, live) {
     return { values: out };
 }
 // ------------------------------------------------------------------ the role a user is added with
+/** Why `role` is not a role's name (a usage failure's message), or null: asked by `roleToAdd`, and by `mason user add
+ *  --role --replica` before a byte is sent. */
+export const roleNameProblem = (role) => ROLE_NAME_RE.test(role) ? null : `${JSON.stringify(role)} is not a role name: ${ROLE_NAME_RULE}`;
 /**
  * WHY `role` IS NOT ONE A USER CAN BE ADDED WITH, against the roles as they are now (`live`: the listener's while the
  * run is up, the file's otherwise): a name of another shape, a file that cannot be read as it is, no roles file at
@@ -202,8 +215,9 @@ export function attributesToAdd(name, role, sets, live) {
  * that reads nothing by mistake — one whose role is removed LATER is refused at its next statement (fail closed).
  */
 export function roleToAdd(role, live) {
-    if (!ROLE_NAME_RE.test(role))
-        return { message: `${JSON.stringify(role)} is not a role name: ${ROLE_NAME_RULE}`, code: "usage" };
+    const named = roleNameProblem(role);
+    if (named !== null)
+        return { message: named, code: "usage" };
     const file = live.file ?? `mason/${ROLES_FILE}`;
     if (live.problem !== null) {
         return { message: `${file} cannot be read as it is now, so no user can be added with a role: ${live.problem}`, code: "bad_roles",
@@ -484,6 +498,91 @@ export function enableUser(file, name) {
     const u = found;
     return { enabled: { name: u.name, id: u.id, addedAt: u.addedAt }, already: !Array.isArray(r) };
 }
+/** What to run after a list. */
+export const listNext = (users) => [["mason user add <name>", "a user for a tool: its password and URL, printed once"],
+    ...(users.some((u) => u.removedAt === null && u.disabledAt !== null) ? [["mason user enable <name>", "a disabled user connects again, with the same password"]] : []),
+    ...(users.some((u) => u.removedAt === null) ? [["mason user remove <name>", "that user connects no more"]] : [])];
+/** `mason user list` for a person: the users of `of` (the project's name, or the replica's), a line each, then its tips
+ *  and `next`. `roles`: the roles as a command beside them sees them (NO_ROLES where none can be read here). */
+export function listText(of, l, roles, next, s = styleOut()) {
+    const { users, lastUsedNote, requestLogDays } = l;
+    if (!users.length)
+        return strict(withEnd(`${s.bold(`No users yet for ${of}.`)}`, { next }, s), s);
+    const active = users.filter((u) => u.removedAt === null);
+    const gone = users.filter((u) => u.removedAt !== null);
+    const width = Math.max(...users.map((u) => u.name.length));
+    const rolesFileShown = roles.file ?? `mason/${ROLES_FILE}`;
+    // the last use in the words the web page's Users page says it too (lastUsedText): "last used" before a time or "unknown"
+    const used = (u) => { const t = lastUsedText(u.lastUsedAt, lastUsedNote, requestLogDays, u.addedAt); return t === "never" ? "never used" : t.startsWith("not used") ? t : `last used ${t}`; };
+    const lines = active.map((u) => `  ${s.cyan(u.name.padEnd(width))}   ${u.role !== undefined ? `role ${u.role}${u.roleFrom === "default" ? " (default)" : ""}${u.attributes !== undefined ? ` (${attributesText(u.attributes)})` : ""}   ` : ""}${s.dim(`id ${u.id} · added ${stamp(u.addedAt)} UTC · ${used(u)}`)}` +
+        (u.disabledAt !== null ? `   ${s.yellow(`${disabledText(u.disabledAt)}: does not connect until mason user enable ${u.name}`)}`
+            : u.live ? "" : `   ${s.yellow("does not connect: the API key was rotated since it was added")}`) +
+        (u.roleKnown === false ? `   ${s.yellow(`its role ${u.role} is not in the roles file: its statements are refused`)}` : "") +
+        (u.readsNothing === true ? `   ${s.yellow(`has no role, and ${rolesFileShown} names no default: its statements are refused`)}` : "") +
+        (u.missingAttributes !== undefined ? `   ${s.yellow(`has no value for ${u.missingAttributes.join(", ")}: its statements are refused`)}` : ""));
+    const disabled = active.filter((u) => u.disabledAt !== null);
+    const removedLines = gone.map((u) => `  ${s.dim(`${u.name.padEnd(width)}   id ${u.id} · added ${stamp(u.addedAt)} UTC · removed ${stamp(u.removedAt)} UTC`)}`);
+    const rotated = active.filter((u) => !u.live && u.disabledAt === null);
+    const orphan = active.find((u) => u.roleKnown === false);
+    const roleless = active.find((u) => u.readsNothing === true);
+    const unset = active.find((u) => u.missingAttributes !== undefined);
+    return strict(withEnd(`${s.bold(`${active.length} user${active.length === 1 ? "" : "s"} of ${of}${disabled.length ? `, ${disabled.length} disabled` : ""}${gone.length ? `, ${gone.length} removed` : ""}`)}\n${[...lines, ...removedLines].join("\n")}`, { tips: [...(rotated.length ? [`A user added under another API key does not connect: mason user remove ${rotated[0].name}, then mason user add ${rotated[0].name}.`] : []),
+            ...(orphan ? [`A role the roles file (mason/${ROLES_FILE}) does not name reads nothing: add ${orphan.role} to it, or mason user remove ${orphan.name}, then mason user add ${orphan.name} --role <role>.`] : []),
+            ...(unset ? [`A user without a value its role's rows are filtered by is refused at every statement: ${missingAttributesText({ name: unset.name, role: unset.role ?? "", missing: unset.missingAttributes })}.`] : []),
+            ...(roleless ? [`A user with no role reads nothing while ${rolesFileShown} names no default: ${noRoleWayOut(roleless.name, rolesFileShown, exampleRole(roles))}.`] : []),
+            ...(roles.problem !== null && active.length ? [rolesProblemText(rolesFileShown, roles.problem)] : []),
+            ...(lastUsedNote !== null ? [`Last used: ${lastUsedNote}.`] : [])], next }, s), s);
+}
+/** `mason user disable` for a person. `up`: Mason runs, so the sessions the user holds end at their next statement. */
+export const disabledReport = (r, up, next, s = styleOut()) => {
+    const d = r.disabled;
+    return reportText({ headline: r.already ? `The user ${d.name} is disabled already: nothing changed` : `The user ${d.name} disabled: it connects no more, until enabled`,
+        details: [["user", d.name], ["disabled", d.disabledAt], ...(r.already ? [] : [["sessions", up ? "those it holds end at their next statement" : "none: Mason is not running"]])],
+        tips: [disableEffect(d.name)], next }, s);
+};
+/** `mason user enable` for a person. */
+export const enabledReport = (r, next, s = styleOut()) => {
+    const e = r.enabled;
+    return reportText({ headline: r.already ? `The user ${e.name} is not disabled: nothing changed, it connects` : `The user ${e.name} enabled: it connects again, with the same password`,
+        details: [["user", e.name], ["added", e.addedAt]], next }, s);
+};
+/** `mason user remove` for a person. */
+export const removedReport = (r, up, next, s = styleOut()) => {
+    const gone = r.removed;
+    return reportText({ headline: `The user ${gone.name} removed: it connects no more`,
+        details: [["user", gone.name], ["added", gone.addedAt], ["sessions", up ? "those it holds end at their next statement" : "none: Mason is not running"]],
+        tips: [`Adding ${gone.name} again makes a new password: the old one never connects again.`], next }, s);
+};
+/**
+ * `mason user add` for a person: the password, printed this once, in the url, psql and password rows (and nowhere else).
+ * The url, psql, host, port and ssl mode rows are there when the answer has them (Mason runs, so where it listens is
+ * known). `roles`: the roles as a command beside them sees them (the file's name in the role row; NO_ROLES where none
+ * can be read here); `listener`: how this run listens (its tips), null where it is not known here.
+ */
+export function addedReport(r, o, s = styleOut()) {
+    const { roles } = o;
+    return reportText({
+        headline: `The user ${r.user} added${r.replaced === true ? " (in place of one the API key's rotation had removed)" : ""}: its password is printed this once`,
+        details: [
+            ...(r.url !== undefined && r.psql !== undefined ? [["url", r.url], ["psql", r.psql]] : []),
+            ["user", r.user], ["password", r.password], ["database", r.database],
+            ...(r.attributes !== undefined ? [["attributes", attributesText(r.attributes)]] : []),
+            ...(r.roleFrom === "file" ? [["role", `${r.role} (mason/${ROLES_FILE} names what it reads)`]]
+                : r.roleFrom === "default" ? [["role", `${r.role} (the file's default: ${roles.file ?? `mason/${ROLES_FILE}`})`]]
+                    : r.readsNothing === true ? [["role", `none, and ${roles.file ?? `mason/${ROLES_FILE}`} names no default: it reads nothing until one is written`]] : []),
+            ...(r.host !== undefined && r.port !== undefined ? [["host", r.host], ["port", String(r.port)], ...(r.sslmode !== undefined && r.sslmode !== "disable" ? [["ssl mode", r.sslmode]] : [])] : []),
+        ],
+        tips: [
+            "Paste it into the tool now: Mason keeps no copy of the password. Lost, remove the user and add it again.",
+            ...(r.readsNothing === true ? [`Its statements are refused until it has a role: ${noRoleWayOut(r.user, roles.file ?? `mason/${ROLES_FILE}`, exampleRole(roles))}.`] : []),
+            ...(r.url === undefined ? ["Mason is not running: mason start, then mason status says the host and port this user connects to."] : []),
+            ...listenerTips(o.listener),
+            "It never expires: mason user remove ends it, at once and for every session it holds.",
+            "Rotating the API key (apiKey in .mason/config.json, MASON_API_KEY under mason serve) removes every user at once.",
+        ],
+        next: o.next,
+    }, s);
+}
 // ------------------------------------------------------------------ the command
 export async function user(argv) {
     const f = parseCommand(USER, argv);
@@ -515,6 +614,17 @@ export async function user(argv) {
         if (problem !== null)
             return usage(problem);
     }
+    // A REPLICA ON A HOSTED MASON SERVICE (--replica, else MASON_REPLICA): its users, asked of the service with the same
+    // request the run's /api/users takes, printed by the renderers above; nothing of a project here is read or written
+    const replica = replicaOf(typeof f.values.replica === "string" ? f.values.replica : undefined, USER.usage);
+    if (replica !== null && "message" in replica)
+        return failed("user", replica, { json });
+    if (replica !== null) {
+        const named = role === undefined ? null : roleNameProblem(role);
+        if (named !== null)
+            return usage(named);
+        return hostedUser(replica, { verb: verb, name, role, sets, json });
+    }
     const w = await reach(USER, json);
     if (w === null || w.project === null)
         return 1;
@@ -551,42 +661,12 @@ export async function user(argv) {
             }
         }
         const urlNote = up !== null ? null : NOT_RUNNING_URL;
-        const next = [["mason user add <name>", "a user for a tool: its password and URL, printed once"],
-            ...(users.some((u) => u.removedAt === null && u.disabledAt !== null) ? [["mason user enable <name>", "a disabled user connects again, with the same password"]] : []),
-            ...(users.some((u) => u.removedAt === null) ? [["mason user remove <name>", "that user connects no more"]] : [])];
+        const next = listNext(users);
         if (json) {
             out(jsonText(USER, { users, lastUsedNote, urlNote, requestLogDays }, next));
             return 0;
         }
-        const s = styleOut();
-        if (!users.length) {
-            out(withEnd(`${s.bold(`No users yet for ${project.config.name}.`)}`, { next }));
-            return 0;
-        }
-        const active = users.filter((u) => u.removedAt === null);
-        const gone = users.filter((u) => u.removedAt !== null);
-        const width = Math.max(...users.map((u) => u.name.length));
-        const rolesFileShown = roles.file ?? `mason/${ROLES_FILE}`;
-        // the last use in the words the web page's Users page says it too (lastUsedText): "last used" before a time or "unknown"
-        const used = (u) => { const t = lastUsedText(u.lastUsedAt, lastUsedNote, requestLogDays, u.addedAt); return t === "never" ? "never used" : t.startsWith("not used") ? t : `last used ${t}`; };
-        const lines = active.map((u) => `  ${s.cyan(u.name.padEnd(width))}   ${u.role !== undefined ? `role ${u.role}${u.roleFrom === "default" ? " (default)" : ""}${u.attributes !== undefined ? ` (${attributesText(u.attributes)})` : ""}   ` : ""}${s.dim(`id ${u.id} · added ${stamp(u.addedAt)} UTC · ${used(u)}`)}` +
-            (u.disabledAt !== null ? `   ${s.yellow(`${disabledText(u.disabledAt)}: does not connect until mason user enable ${u.name}`)}`
-                : u.live ? "" : `   ${s.yellow("does not connect: the API key was rotated since it was added")}`) +
-            (u.roleKnown === false ? `   ${s.yellow(`its role ${u.role} is not in the roles file: its statements are refused`)}` : "") +
-            (u.readsNothing === true ? `   ${s.yellow(`has no role, and ${rolesFileShown} names no default: its statements are refused`)}` : "") +
-            (u.missingAttributes !== undefined ? `   ${s.yellow(`has no value for ${u.missingAttributes.join(", ")}: its statements are refused`)}` : ""));
-        const disabled = active.filter((u) => u.disabledAt !== null);
-        const removedLines = gone.map((u) => `  ${s.dim(`${u.name.padEnd(width)}   id ${u.id} · added ${stamp(u.addedAt)} UTC · removed ${stamp(u.removedAt)} UTC`)}`);
-        const rotated = active.filter((u) => !u.live && u.disabledAt === null);
-        const orphan = active.find((u) => u.roleKnown === false);
-        const roleless = active.find((u) => u.readsNothing === true);
-        const unset = active.find((u) => u.missingAttributes !== undefined);
-        out(withEnd(`${s.bold(`${active.length} user${active.length === 1 ? "" : "s"} of ${project.config.name}${disabled.length ? `, ${disabled.length} disabled` : ""}${gone.length ? `, ${gone.length} removed` : ""}`)}\n${[...lines, ...removedLines].join("\n")}`, { tips: [...(rotated.length ? [`A user added under another API key does not connect: mason user remove ${rotated[0].name}, then mason user add ${rotated[0].name}.`] : []),
-                ...(orphan ? [`A role the roles file (mason/${ROLES_FILE}) does not name reads nothing: add ${orphan.role} to it, or mason user remove ${orphan.name}, then mason user add ${orphan.name} --role <role>.`] : []),
-                ...(unset ? [`A user without a value its role's rows are filtered by is refused at every statement: ${missingAttributesText({ name: unset.name, role: unset.role ?? "", missing: unset.missingAttributes })}.`] : []),
-                ...(roleless ? [`A user with no role reads nothing while ${rolesFileShown} names no default: ${noRoleWayOut(roleless.name, rolesFileShown, exampleRole(roles))}.`] : []),
-                ...(roles.problem !== null && active.length ? [rolesProblemText(rolesFileShown, roles.problem)] : []),
-                ...(lastUsedNote !== null ? [`Last used: ${lastUsedNote}.`] : [])], next }));
+        out(listText(project.config.name, { users, lastUsedNote, urlNote, requestLogDays }, roles, next));
         return 0;
     }
     if (verb === "disable") {
@@ -598,10 +678,7 @@ export async function user(argv) {
             out(jsonText(USER, r, next));
             return 0;
         }
-        const d = r.disabled;
-        out(reportText({ headline: r.already ? `The user ${d.name} is disabled already: nothing changed` : `The user ${d.name} disabled: it connects no more, until enabled`,
-            details: [["user", d.name], ["disabled", d.disabledAt], ...(r.already ? [] : [["sessions", w.state === "up" ? "those it holds end at their next statement" : "none: Mason is not running"]])],
-            tips: [disableEffect(d.name)], next }));
+        out(disabledReport(r, w.state === "up", next));
         return 0;
     }
     if (verb === "enable") {
@@ -613,24 +690,19 @@ export async function user(argv) {
             out(jsonText(USER, r, next));
             return 0;
         }
-        const e = r.enabled;
-        out(reportText({ headline: r.already ? `The user ${e.name} is not disabled: nothing changed, it connects` : `The user ${e.name} enabled: it connects again, with the same password`,
-            details: [["user", e.name], ["added", e.addedAt]], next }));
+        out(enabledReport(r, next));
         return 0;
     }
     if (verb === "remove") {
         const r = removeUser(file, name);
         if ("message" in r)
             return failed("user", r, { json });
-        const gone = r.removed;
         const next = REMOVED_NEXT;
         if (json) {
             out(jsonText(USER, r, next));
             return 0;
         }
-        out(reportText({ headline: `The user ${gone.name} removed: it connects no more`,
-            details: [["user", gone.name], ["added", gone.addedAt], ["sessions", w.state === "up" ? "those it holds end at their next statement" : "none: Mason is not running"]],
-            tips: [`Adding ${gone.name} again makes a new password: the old one never connects again.`], next }));
+        out(removedReport(r, w.state === "up", next));
         return 0;
     }
     // add
@@ -654,32 +726,12 @@ export async function user(argv) {
     const r = addUser(file, apiKey, name, { link, database, roles, ...(role !== undefined ? { role } : {}), attributes: attributes.values });
     if ("message" in r)
         return failed("user", r, { json });
-    const { replaced, ...added } = r;
+    const { replaced: _, ...added } = r;
     const next = addedNext(r.user, link !== null);
     if (json) {
         out(jsonText(USER, added, next));
         return 0;
     }
-    out(reportText({
-        headline: `The user ${r.user} added${replaced ? " (in place of one the API key's rotation had removed)" : ""}: its password is printed this once`,
-        details: [
-            ...(r.url !== undefined && r.psql !== undefined ? [["url", r.url], ["psql", r.psql]] : []),
-            ["user", r.user], ["password", r.password], ["database", r.database],
-            ...(r.attributes !== undefined ? [["attributes", attributesText(r.attributes)]] : []),
-            ...(r.roleFrom === "file" ? [["role", `${r.role} (mason/${ROLES_FILE} names what it reads)`]]
-                : r.roleFrom === "default" ? [["role", `${r.role} (the file's default: ${roles.file ?? `mason/${ROLES_FILE}`})`]]
-                    : r.readsNothing === true ? [["role", `none, and ${roles.file ?? `mason/${ROLES_FILE}`} names no default: it reads nothing until one is written`]] : []),
-            ...(link !== null ? [["host", link.host], ["port", String(link.port)], ...(link.sslmode ? [["ssl mode", link.sslmode]] : [])] : []),
-        ],
-        tips: [
-            "Paste it into the tool now: Mason keeps no copy of the password. Lost, remove the user and add it again.",
-            ...(r.readsNothing === true ? [`Its statements are refused until it has a role: ${noRoleWayOut(r.user, roles.file ?? `mason/${ROLES_FILE}`, exampleRole(roles))}.`] : []),
-            ...(link === null ? ["Mason is not running: mason start, then mason status says the host and port this user connects to."] : []),
-            ...listenerTips(run?.postgresListener ?? null),
-            "It never expires: mason user remove ends it, at once and for every session it holds.",
-            "Rotating the API key (apiKey in .mason/config.json, MASON_API_KEY under mason serve) removes every user at once.",
-        ],
-        next,
-    }));
+    out(addedReport(r, { roles, listener: run?.postgresListener ?? null, next }));
     return 0;
 }