@mason-data/cli 0.8.0 → 0.10.0

package/dist/src/cli/user.js

@@ -11,11 +11,11 @@
  * 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, listFlag, 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";
-import { changeUsers, isActive, isDisabled, keyFingerprint, newUserId, readUsers, underKey, userPassword, USER_NAME_RE, USER_NAME_RULE, USERS_FILE } from "../duck/users.js";
+import { changeUsers, isActive, isDisabled, keyFingerprint, newUserId, readUsers, underKey, userPassword, userRanges, USER_NAME_RE, USER_NAME_RULE, USERS_FILE } from "../duck/users.js";
 import { didYouMean } from "../lib/did-you-mean.js";
 import { out as styleOut } from "./style.js";
 import { NO_ROLES } from "../duck/grants.js";
@@ -24,16 +24,19 @@ 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> …] [--from <range> …] [--replica <org>/<name>] [--json]
+       mason user from <name> <range> … | --any [--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:
@@ -42,6 +45,28 @@ export const USER = {
   The user name a tool sends must be the user's own. A user disabled is kept with its password: its logins are
   refused (as Postgres refuses a role without LOGIN) and its sessions end at their next statement, until enable.
 
+    mason user add metabase                    a user for Metabase: its password and the URL to paste
+    mason user add looker --from 203.0.113.0/24 --from 2001:db8:7::/48    connects from these alone
+    mason user from looker 198.51.100.0/24     its ranges replaced
+    mason user from looker --any               it connects from any address again
+    mason user add agent --role agent          a user held to the role agent
+    mason user add acme --role tenant --set tenant=42      the rows of tenant 42
+    mason user add emea --role region --set regions=eu --set regions=uk
+    mason user list
+    mason user disable metabase                metabase connects no more, until mason user enable metabase
+    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
+
+  <name>                      ${USER_NAME_RULE}
+  --role <role>               add: what the user reads, a role of mason/roles.yml (below)
+  --set <attribute>=<value>   add: its value of an attribute its role declares (below)
+  --from <range>              add: the addresses it connects from (below)
+  --any                       from: its ranges removed, so it connects from any address
+  --replica <org>/<name>      a replica's users on a hosted Mason service, not this project's (below)
+  --json                      as data: its shape is at the end
+
   The list is .mason/users.json (names and ids, no password), beside the running Mason, which reads it again by itself.
   A removed user stays in it, marked removed, so the list shows who was removed and when; its name can be added again.
   Rotating the API key (apiKey in .mason/config.json, MASON_API_KEY under mason serve) removes every user at once.
@@ -82,32 +107,42 @@ export const USER = {
   statement, never answered with no rows: add it again with the --set. Postgres refuses a where: it cannot read
   when the running Mason reads the file, at its key.
 
-    mason user add metabase                    a user for Metabase: its password and the URL to paste
-    mason user add agent --role agent          a user held to the role agent
-    mason user add acme --role tenant --set tenant=42      the rows of tenant 42
-    mason user add emea --role region --set regions=eu --set regions=uk
-    mason user list
-    mason user disable metabase                metabase connects no more, until mason user enable metabase
-    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
+  --from <range> limits the addresses the user connects from (repeat --from for each, or a comma list): an IPv4 or IPv6 range with its
+  prefix length (10.0.0.0/16, 2001:db8::/32) or one address (192.0.2.10). A connection from any other address is
+  refused before its password is checked, as Postgres refuses one no pg_hba.conf line takes (28000, no entry for host
+  …), and in the same words for a name that is no user while any user has ranges, so a user with ranges cannot be
+  told from a missing one (a user without ranges still answers a wrong password 28P01). An address that cannot be read (a public share's socket) is refused too. Behind a TCP proxy the address is
+  the client its PROXY header carries (MASON_PG_PROXY_FROM). A user added without --from connects from any address.
+  mason user from <name> <range> … replaces a user's ranges, and mason user from <name> --any removes them; the sessions
+  it holds from an address outside its new ranges end at their next statement.
+
+  --replica <org>/<name> manages the users of a replica on a hosted Mason service instead of this project's (else
+  MASON_REPLICA, said on stderr when it chose; each part lower case letters, digits and -): the same subcommands,
+  --role, --set and --from, the same output and --json, which names the replica in its headline and its replica key,
+  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
-            or the file's default; absent when none), attributes? ({ name: value, or [values] for a list }), roleFrom (file: its own --role; default: the file's default;
-            none), readsNothing (true: no role under a file with no default), and once Mason runs url, psql (the
-            psql line for url), host, port, sslmode }; list { users: [{ name, id, addedAt, removedAt (null for a user
-            not removed), disabledAt (null for a user not disabled), live (connects now), role?, attributes?,
-            missingAttributes? (the attributes its role's filters read that it lacks: refused until added again), roleFrom, readsNothing?,
-            roleKnown? (the roles file names its own role now), lastUsedAt (its newest statement, null when none within
-            requestLogDays), url (to paste, without the password; null for a removed user or when Mason is not running) }],
-            lastUsedNote (why lastUsedAt is unknown, else null), urlNote (why url is null, else null), requestLogDays
-            (null when unknown) }; disable { disabled: { name, id, addedAt, disabledAt }, already (it was disabled
-            before) }; enable { enabled: { name, id, addedAt }, already (it was not disabled) }; remove { removed: { name,
-            id, addedAt, removedAt } }; next
+  The --json answer: add { user (the name), id, addedAt, password, database, role (the role it reads as: its own
+    or the file's default; absent when none), attributes? ({ name: value, or [values] for a list }), roleFrom (file: its own --role; default: the file's default;
+    none), readsNothing (true: no role under a file with no default), from? (its address ranges, as given
+    to --from in their one form; absent: any address), and once Mason runs url, psql (the
+    psql line for url), host, port, sslmode }; list { users: [{ name, id, addedAt, removedAt (null for a user
+    not removed), disabledAt (null for a user not disabled), live (connects now), from (its address ranges;
+    null: any address), role?, attributes?,
+    missingAttributes? (the attributes its role's filters read that it lacks: refused until added again), roleFrom, readsNothing?,
+    roleKnown? (the roles file names its own role now), lastUsedAt (its newest statement, null when none within
+    requestLogDays), url (to paste, without the password; null for a removed user or when Mason is not running) }],
+    lastUsedNote (why lastUsedAt is unknown, else null), urlNote (why url is null, else null), requestLogDays
+    (null when unknown) }; disable { disabled: { name, id, addedAt, disabledAt }, already (it was disabled
+    before) }; enable { enabled: { name, id, addedAt }, already (it was not disabled) }; from { changed: { name, id,
+    addedAt, from (its ranges now; null: any address) }, already (they were these before) }; remove { removedUser: { name,
+    id, addedAt, removedAt }, removed (the same, kept until 1.0) }; next. With --replica (or MASON_REPLICA) every answer also has replica ("<org>/<name>":
+    the replica it acted on), and a project's never does
 `,
-    options: { json: { type: "boolean", default: false }, role: { type: "string" }, set: { type: "string", multiple: true } },
-    json: ["user", "id", "addedAt", "password", "url", "psql", "host", "port", "database", "sslmode", "role", "attributes", "roleFrom", "readsNothing", "users", "disabled", "enabled", "already", "removed", "lastUsedNote", "urlNote", "requestLogDays", "next"],
+    options: { json: { type: "boolean", default: false }, role: { type: "string" }, set: { type: "string", multiple: true }, from: { type: "string", multiple: true }, any: { type: "boolean", default: false }, replica: { type: "string" } },
+    json: ["replica", "user", "id", "addedAt", "password", "url", "psql", "host", "port", "database", "sslmode", "role", "attributes", "roleFrom", "readsNothing", "users", "disabled", "enabled", "already", "removedUser", "removed", "from", "changed", "lastUsedNote", "urlNote", "requestLogDays", "next"],
 };
 /** The users of a project and why one is not live: added under an API key since rotated. */
 const liveOf = (u, apiKey) => underKey(u, apiKey);
@@ -194,6 +229,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 +240,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",
@@ -325,7 +364,7 @@ export function listUsers(file, apiKey, link, roles = NO_ROLES) {
             fix: `repair ${file}, or move it aside, which removes every user` };
     // roleKnown only where the file can be read: under a problem the listener refuses every user held to it for the FILE
     return { users: r.users.map((u) => ({ name: u.name, id: u.id, addedAt: u.addedAt, removedAt: u.removedAt ?? null, disabledAt: u.disabledAt ?? null,
-            live: isActive(u) && !isDisabled(u) && liveOf(u, apiKey),
+            live: isActive(u) && !isDisabled(u) && liveOf(u, apiKey), from: u.from ?? null,
             lastUsedAt: null, url: link !== null && isActive(u) ? connectionUrl(link, u.name, null) : null,
             ...roleFields(u, roles), ...(u.attributes !== undefined ? { attributes: u.attributes } : {}),
             ...((m) => m === undefined ? {} : { missingAttributes: m.missing })(usersMissingAttributes([u], roles)[0]),
@@ -359,6 +398,9 @@ export function addUser(file, apiKey, name, o) {
     const usage = userNameProblem("add", name);
     if (usage !== null)
         return { message: usage, code: "usage" };
+    const ranges = o.from === undefined ? null : rangesToSet(o.from, `mason user add ${name}`);
+    if (ranges !== null && "message" in ranges)
+        return ranges;
     const fingerprint = keyFingerprint(apiKey);
     let added;
     let replaced = false;
@@ -372,7 +414,7 @@ export function addUser(file, apiKey, name, o) {
             replaced = was !== undefined;
             const now = new Date().toISOString();
             added = { name, id: newUserId(), addedAt: now, key: fingerprint, ...(o.role !== undefined ? { role: o.role } : {}),
-                ...(o.attributes !== undefined && Object.keys(o.attributes).length > 0 ? { attributes: o.attributes } : {}) };
+                ...(o.attributes !== undefined && Object.keys(o.attributes).length > 0 ? { attributes: o.attributes } : {}), ...(ranges !== null ? { from: ranges.from } : {}) };
             return [...users.map((u) => u === was ? { ...u, removedAt: now } : u), added];
         });
     }
@@ -390,8 +432,58 @@ export function addUser(file, apiKey, name, o) {
     const { link } = o;
     return { user: u.name, id: u.id, addedAt: u.addedAt, password, database: link?.database ?? o.database,
         ...(link !== null ? { url: connectionUrl(link, u.name, password), psql: psqlLine(connectionUrl(link, u.name, password)), host: link.host, port: link.port, sslmode: link.sslmode ?? "disable" } : {}),
-        ...roleFields(u, o.roles ?? NO_ROLES), ...(u.attributes !== undefined ? { attributes: u.attributes } : {}), replaced };
+        ...roleFields(u, o.roles ?? NO_ROLES), ...(u.attributes !== undefined ? { attributes: u.attributes } : {}), ...(u.from !== undefined ? { from: u.from } : {}), replaced };
+}
+/** Address ranges as `--from` (or `/api/users`' `from`) gives them, each read by the one grammar (src/duck/users.ts
+ *  `userRanges`) and in its one form; or a wrong line (`usage`), every entry that is not a range said, nothing written. */
+export function rangesToSet(given, line) {
+    const r = userRanges(given);
+    if ("problem" in r)
+        return { message: `${line}: ${r.problem}`, code: "usage", fix: "an IPv4 or IPv6 range with its prefix length (10.0.0.0/16, 2001:db8::/32) or one address (192.0.2.10), one --from each" };
+    return { from: r.from };
 }
+/**
+ * SET A USER'S ADDRESS RANGES in `file` under its lock, replacing those it had (`from`: the ranges as given; null: any
+ * address, its ranges removed). The listener reads them at the user's next connection and at each statement of a session
+ * it holds, so a session from outside the new ranges ends there. The same ranges as now are said so (`already`), nothing
+ * written. A range that is not one is a wrong line, nothing written.
+ */
+export function setUserFrom(file, name, from) {
+    const usage = userNameProblem("from", name);
+    if (usage !== null)
+        return { message: usage, code: "usage" };
+    const ranges = from === null ? null : rangesToSet(from, `mason user from ${name}`);
+    if (ranges !== null && "message" in ranges)
+        return ranges;
+    const next = ranges === null ? undefined : ranges.from;
+    let found;
+    let live = [];
+    let r;
+    try {
+        r = changeUsers(file, (users) => {
+            found = users.find((u) => u.name === name && isActive(u));
+            live = users.filter(isActive).map((u) => u.name);
+            if (found === undefined)
+                return { refused: "unknown" };
+            if (JSON.stringify(found.from ?? null) === JSON.stringify(next ?? null))
+                return { refused: "already" };
+            return users.map((u) => { if (u !== found)
+                return u; const { from: _, ...rest } = u; return next === undefined ? rest : { ...rest, from: next }; });
+        });
+    }
+    catch (e) {
+        return cantChange(file, e);
+    }
+    if (found === undefined)
+        return noSuchUser(name, live);
+    const u = found;
+    return { changed: { name: u.name, id: u.id, addedAt: u.addedAt, from: next ?? null }, already: !Array.isArray(r) };
+}
+/** a user's ranges as `mason user` says them: `10.0.0.0/16, 2001:db8::/32`, or any address */
+export const rangesText = (from) => from === null || from === undefined ? "any address" : from.join(", ");
+/** What to run after a `mason user from`. */
+export const fromNext = (name, from) => [["mason user list", "the users and the addresses each connects from"],
+    ...(from !== null ? [[`mason user from ${name} --any`, "it connects from any address again"]] : [])];
 /** REMOVE A USER from `file` under its lock: it connects no more. A name the file lacks is refused with the closest it has. */
 export function removeUser(file, name) {
     const usage = userNameProblem("remove", name);
@@ -484,6 +576,103 @@ 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)})` : ""}   ` : ""}${u.from !== null ? `from ${rangesText(u.from)}   ` : ""}${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);
+}
+/** A user in a headline: its name, and the replica it is a user of when the command acted on one (`on`), so the answer
+ *  says its target. */
+const userOn = (name, on) => on === undefined ? name : `${name} of the replica ${on}`;
+/** `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(), on) => {
+    const d = r.disabled, who = userOn(d.name, on);
+    return reportText({ headline: r.already ? `The user ${who} is disabled already: nothing changed` : `The user ${who} 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(), on) => {
+    const e = r.enabled, who = userOn(e.name, on);
+    return reportText({ headline: r.already ? `The user ${who} is not disabled: nothing changed, it connects` : `The user ${who} enabled: it connects again, with the same password`,
+        details: [["user", e.name], ["added", e.addedAt]], next }, s);
+};
+/** `mason user from` for a person. `up`: Mason runs, so a session from outside the new ranges ends at its next statement. */
+export const fromReport = (r, up, next, s = styleOut()) => {
+    const c = r.changed;
+    return reportText({ headline: r.already ? `The user ${c.name} connects from ${rangesText(c.from)} already: nothing changed`
+            : c.from === null ? `The user ${c.name} connects from any address now` : `The user ${c.name} connects from ${rangesText(c.from)} alone now`,
+        details: [["user", c.name], ["from", rangesText(c.from)], ...(r.already || c.from === null ? [] : [["sessions", up ? "those it holds from another address end at their next statement" : "none: Mason is not running"]])],
+        tips: c.from === null ? [] : ["A connection from any other address is refused before its password is checked (28000, no entry for host …)."], next }, s);
+};
+/** `mason user remove` for a person. */
+export const removedReport = (r, up, next, s = styleOut(), on) => {
+    const gone = r.removed;
+    return reportText({ headline: `The user ${userOn(gone.name, on)} 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 ${userOn(r.user, o.on)} 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.from !== undefined ? [["from", `${rangesText(r.from)} (it connects from these alone)`]] : []),
+            ...(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);
@@ -492,13 +681,26 @@ export async function user(argv) {
     const json = f.values.json === true;
     const usage = (message) => failed("user", { message, code: "usage", usage: USER.usage }, { json });
     const [verb, name, ...rest] = f.positionals;
-    const VERBS = ["add", "list", "disable", "enable", "remove"];
+    const VERBS = ["add", "list", "from", "disable", "enable", "remove"];
     if (verb === undefined)
-        return usage("add, list, disable, enable or remove: mason user add <name> makes a user");
+        return usage("add, list, from, disable, enable or remove: mason user add <name> makes a user");
     if (!VERBS.includes(verb))
-        return usage(`there is no mason user ${verb}: add, list, disable, enable or remove${didYouMean(verb, VERBS)}`);
-    if (verb === "list" ? name !== undefined : rest.length)
+        return usage(`there is no mason user ${verb}: add, list, from, disable, enable or remove${didYouMean(verb, VERBS)}`);
+    if (verb === "list" ? name !== undefined : verb !== "from" && rest.length)
         return usage(`mason user ${verb} takes ${verb === "list" ? "no name" : "one name"}: ${[name, ...rest].filter(Boolean).join(" ")} is too many`);
+    // the address ranges: --from on add, the positionals of from (or its --any); each read by the one grammar, a wrong one a
+    // wrong line before anything is read, written or sent
+    // a comma list or the flag repeated, the same (src/cli/command.ts listFlag): a range holds no comma
+    const fromList = listFlag(f.values.from);
+    const fromFlags = fromList === undefined ? [] : fromList.split(",");
+    if (fromFlags.length > 0 && verb !== "add")
+        return usage(`--from goes with mason user add: mason user add <name> --from ${fromFlags[0]}${verb === "from" ? `, or mason user from <name> ${fromFlags[0]}` : ""}`);
+    const any = f.values.any === true;
+    if (any && verb !== "from")
+        return usage("--any goes with mason user from: mason user from <name> --any removes its address ranges");
+    if (verb === "from" && any === (rest.length > 0))
+        return usage(any ? `mason user from ${name ?? "<name>"}: --any or ranges, not both` : `mason user from ${name ?? "<name>"}: which addresses — one or more ranges (10.0.0.0/16, 2001:db8::/32, 192.0.2.10), or --any`);
+    const given = verb === "add" ? (fromFlags.length > 0 ? fromFlags : null) : verb === "from" && !any ? rest : null;
     const role = typeof f.values.role === "string" ? f.values.role : undefined;
     if (role !== undefined && verb !== "add")
         return usage(`--role goes with mason user add: mason user add <name> --role ${role}`);
@@ -515,6 +717,20 @@ export async function user(argv) {
         if (problem !== null)
             return usage(problem);
     }
+    const ranges = given === null ? null : rangesToSet(given, `mason user ${verb} ${name}`);
+    if (ranges !== null && "message" in ranges)
+        return failed("user", { ...ranges, usage: USER.usage }, { json });
+    // 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, from: ranges?.from ?? null, json });
+    }
     const w = await reach(USER, json);
     if (w === null || w.project === null)
         return 1;
@@ -551,42 +767,24 @@ 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 }));
+        out(listText(project.config.name, { users, lastUsedNote, urlNote, requestLogDays }, roles, next));
+        return 0;
+    }
+    if (verb === "from") {
+        const r = setUserFrom(file, name, ranges?.from ?? null);
+        if ("message" in r)
+            return failed("user", r, { json });
+        const next = fromNext(r.changed.name, r.changed.from);
+        if (json) {
+            out(jsonText(USER, r, 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(fromReport(r, w.state === "up", next));
         return 0;
     }
     if (verb === "disable") {
@@ -598,10 +796,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 +808,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));
+            out(jsonText(USER, { removedUser: r.removed, ...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
@@ -651,35 +841,15 @@ export async function user(argv) {
     const attributes = attributesToAdd(name, role ?? userRole({}, roles).role, sets, roles);
     if ("refused" in attributes)
         return failed("user", attributes.refused, { json });
-    const r = addUser(file, apiKey, name, { link, database, roles, ...(role !== undefined ? { role } : {}), attributes: attributes.values });
+    const r = addUser(file, apiKey, name, { link, database, roles, ...(role !== undefined ? { role } : {}), attributes: attributes.values, ...(ranges !== null ? { from: ranges.from } : {}) });
     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;
 }

package/dist/src/demo/seed.js

@@ -48,6 +48,32 @@ export const DEMO_ADDED_TABLES = DEMO_TABLES.filter((t) => t !== DEMO_TABLE_TO_A
 /** how the demo's tables are kept current (the sources file's top `sync:`, src/lib/table-sync.ts): polled every 5 s,
  *  so the demo shows a copy keeping up with its writer — where a project `mason init` makes is `off` */
 export const DEMO_SYNC = { mode: "poll", every: "5s", seconds: 5 };
+/**
+ * THE GENERATED TABLE `mason init demo` WRITES (`mason/generated_tables/<file>`, src/cli/generated-files.ts reads it), so a
+ * person trying Mason meets a generated table without reading the docs: orders and revenue per day and status, kept
+ * current from the synced `orders`.
+ *   - It reads `orders` ALONE, a table init adds (`DEMO_ADDED_TABLES`), never `DEMO_TABLE_TO_ADD`: it is built at the
+ *     first start, and the person's first lesson (`mason add order_items`) stays the only one.
+ *   - It NAMES ITS ZONE (`AT TIME ZONE 'UTC'`): a generated table has no session, so a form reading the zone is refused.
+ *     The day is a `date`, the same in every client's TimeZone.
+ *   - `revenue` is the sum of a `numeric(12,2)`: its scale is fixed by the type, so it is stored exactly.
+ *   - `target_lag: 30s`: the writer adds an order every few seconds and the poll is 5 s, so it is seen re-running.
+ * Its name is the README's example's (`daily_orders.yml`), so the two read as one.
+ */
+export const DEMO_GENERATED = {
+    file: "daily_orders.yml",
+    table: "daily_orders",
+    text: `# A generated table: a SELECT over the synced tables, kept current by Mason. Yours to commit; mason help generated.
+kind: scheduled
+target_lag: 30s   # how far behind the synced orders it may be
+sql: |
+  SELECT (created_at AT TIME ZONE 'UTC')::date AS day, status, count(*) AS orders, sum(total) AS revenue
+  FROM orders
+  GROUP BY 1, 2
+order_by: day, status
+comment: Orders and revenue per day (UTC) and status, kept current from the synced orders.
+`,
+};
 /** an order's status moves along this path (`changeSql`); `cancelled` is a side exit */
 export const ORDER_STATUSES = ["pending", "paid", "shipped", "delivered"];
 const ROWS_PER_INSERT = 1_000;