@mason-data/cli 0.9.0 → 0.11.0

package/dist/src/cli/ui.js

@@ -2,7 +2,8 @@
  * `mason ui` — THE WEB PAGE OF THE RUNNING MASON, IN THE BROWSER (src/web/, docs/WEB-UI.md): the Overview (what `mason
  * status` says), the Tables (`mason tables`, `add`, `remove`, `sync`), the Users (`mason user`) and Observability (`mason
  * logs`, `mason usage`), refreshed while the tab is seen. It prints the page's URL WITH the run's token (src/cli/security.ts: the first request trades it for an HttpOnly cookie and is redirected to a URL without
- * it) and opens the browser. The reader is the person at this terminal, whom `mason user add` already shows a
+ * it) and opens the browser when its stdout is a terminal (as `mason login` does: a pipe, a file or an agent's shell has
+ * no one at a browser, so it gets the address alone). The reader is the person at this terminal, whom `mason user add` already shows a
  * password once; the token is never written anywhere else — not in `mason start`'s output (its log is a file), not in
  * `mason status`, which prints the URL without it.
  *
@@ -12,6 +13,9 @@
  * `--ssh <user@server>` (src/cli/ui-ssh.ts, docs/WEB-UI.md "On a server") opens a server's page from this machine, through
  * the machine's own ssh, and stays in the foreground until Ctrl-C, as `mason share` does; it needs no project here. Its
  * URL carries a ticket for one use, never the run's token, which stays on the server. `--bridge` is what it runs there.
+ *
+ * `--replica <org>/<name>` (else `MASON_REPLICA`; src/cli/ui-hosted.ts, docs/HOSTED-API.md "A replica's page") opens a
+ * replica's page on a hosted Mason service: one request, whose one-use address is opened as this command opens a run's.
  */
 import { spawn } from "node:child_process";
 import { failed, jsonText, parseCommand, reportText } from "./command.js";
@@ -19,6 +23,9 @@ import { reach } from "./state.js";
 import { bridge, openSshTunnel, targetProblem } from "./ui-ssh.js";
 import { version } from "./version.js";
 import { RunUnreachable } from "./control.js";
+import { parseDuration } from "../lib/table-sync.js";
+import { replicaOf } from "./replica.js";
+import { hostedUi } from "./ui-hosted.js";
 const out = (m) => { process.stdout.write(`${m}\n`); };
 const say = (m) => { process.stderr.write(`${m}\n`); };
 const DEFAULT_TIMEOUT_S = 60;
@@ -27,7 +34,8 @@ export const UI = {
     name: "ui",
     summary: "the status, tables, users and statements, in your browser",
     usage: `usage: mason ui [--no-open] [--json]
-       mason ui --ssh <user@server> [--mason <command>] [--timeout <seconds>] [--no-open] [--json]
+       mason ui --ssh <user@server> [--mason <command>] [--timeout <duration>] [--no-open] [--json]
+       mason ui --replica <org>/<name> [--no-open] [--json]
 
   Opens the running Mason's web page in your browser, refreshed while the tab is open: the Overview (what mason status
   says: whether the synced data is ready, the database, the sync, the statements and the recent errors); the Tables (add,
@@ -35,38 +43,51 @@ export const UI = {
   the URL to paste, or remove one); and Observability: the statements running and that ran (mason logs --requests,
   cancel one), usage over time (mason usage), and the sync's events (mason logs --events).
 
-  The URL carries this run's token: the page trades it for a cookie at once and drops it from the address
-  bar. It is printed for you alone, like a user's password: paste it nowhere else. Every mason start makes a new
-  token, so after a restart run mason ui again.
-
-  --ssh opens a server's page (mason serve's) from this machine, with nothing public: it runs your ssh, so your
-  ~/.ssh/config, keys and SSO apply, starts mason there, and forwards a free local port to the page, which listens on the
-  server's loopback alone. It stays in the foreground: Ctrl-C closes the tunnel. It needs no project here. Its URL
-  carries a ticket for one use, never the run's token, which stays on the server. The server's Mason must be this
-  version or close to it, and must be a command ssh can run: --mason says how, for a container or a folder.
-
     mason ui
     mason ui --no-open        print the URL, open no browser
     mason ui --json
     mason ui --ssh deploy@mason.example.com
     mason ui --ssh deploy@mason.example.com --mason "docker exec -i mason-mason-1 mason"
     mason ui --ssh deploy@mason.example.com --mason "cd /var/lib/mason && mason" --timeout 120 --no-open
+    mason ui --replica acme/shop     a replica's page on a hosted Mason service
     mason ui --bridge --local-port 51000      what --ssh runs on the server; its stdout is a stream, not for reading
 
-  --no-open            print the URL only
+  --no-open            print the URL only (as when its output is not a terminal: a browser opens only for one)
   --ssh <target>       the server, as you give it to ssh: user@server, or a Host of your ssh config
   --mason <command>    how to run mason on the server (default mason); a shell's text, kept to ssh's command line
-  --timeout <s>        how long ssh and the server have to answer (default ${DEFAULT_TIMEOUT_S}): a passphrase or a touch counts
+  --timeout <duration> how long ssh and the server have to answer (default ${DEFAULT_TIMEOUT_S}s; a bare number is seconds;
+                       2m): a passphrase or a touch counts; past it, exit 124
   --bridge             the server's end of --ssh, on stdin and stdout
   --local-port <n>     the port the browser names, for --bridge: the laptop's
-  --json               as data: { url (with this run's token; with --ssh a ticket for one use; null when Ctrl-C came
-                       before the server answered, as port is, exit 0), port, server, project,
-                       version (with --ssh: the server's Mason, for what its answer may lack) }, next; it never opens a
-                       browser. With --ssh it then holds the tunnel: the end is on stderr, exit 0 for Ctrl-C or SIGTERM, 1 otherwise
+  --replica <org>/<name> a replica on a hosted Mason service, as the service lists it
+  --json               as data: its shape is at the end
+
+  The URL carries this run's token: the page trades it for a cookie at once and drops it from the address
+  bar. It is printed for you alone, like a user's password: paste it nowhere else. Every mason start makes a new
+  token, so after a restart run mason ui again.
+
+  --ssh opens a server's page (mason serve's) from this machine, with nothing public: it runs your ssh, so your
+  ~/.ssh/config, keys and SSO apply, starts mason there, and forwards a free local port to the page, which listens on the
+  server's loopback alone. It stays in the foreground: Ctrl-C closes the tunnel. It needs no project here. Its URL
+  carries a ticket for one use, never the run's token, which stays on the server. The server's Mason must be this
+  version or close to it, and must be a command ssh can run: --mason says how, for a container or a folder.
+
+  --replica opens the page of a replica on a hosted Mason service (else MASON_REPLICA, unless --ssh or --bridge names
+  the target), for the organisation's owner alone: the service answers an address that opens it once, for a few
+  minutes. The page is read-only: the service refuses changes through it, so add or remove users with mason user …
+  --replica. It needs no project here, and goes with --no-open and --json alone. Opened in your browser, the address is
+  not printed: run it again for another tab. A replica not ready yet is said, with when to try again.
+
+  The --json answer: { url (with this run's token; with --ssh a ticket for one use; null when Ctrl-C came
+    before the server answered, as port is, exit 0; with --replica the one-use address), port, server,
+    project, version (with --ssh: the server's Mason, for what its answer may lack), replica
+    (with --replica: "<org>/<name>"), expiresAt (with --replica: until when the address opens it)
+    }, next; it never opens a
+    browser. With --ssh it then holds the tunnel: the end is on stderr, exit 0 for Ctrl-C or SIGTERM, 1 otherwise
 `,
     options: { "no-open": { type: "boolean", default: false }, json: { type: "boolean", default: false }, ssh: { type: "string" }, mason: { type: "string" },
-        timeout: { type: "string" }, bridge: { type: "boolean", default: false }, "local-port": { type: "string" } },
-    json: ["url", "port", "server", "project", "version", "next"],
+        timeout: { type: "string" }, bridge: { type: "boolean", default: false }, "local-port": { type: "string" }, replica: { type: "string" } },
+    json: ["url", "port", "server", "project", "version", "replica", "expiresAt", "next"],
 };
 const NEXT = [["mason status", "the same, in this terminal"], ["mason user list", "the users"]];
 /** The command that opens a URL in the person's browser, by platform (macOS `open`, Windows `start`, else `xdg-open`). */
@@ -78,6 +99,9 @@ export function openCommand(platform, url) {
         return ["cmd", ["/c", "start", "", url]];
     return ["xdg-open", [url]];
 }
+/** An address Mason hands the browser by itself (a sign-in page, a replica's page): a plain https (or this machine's
+ *  http) URL, and none of the characters a shell or `cmd /c start` reads (the service's URL is not ours). */
+export const OPENABLE = /^https?:\/\/[A-Za-z0-9.:[\]-]+(?:\/[A-Za-z0-9._~/?=+-]*)?$/;
 /** Open `url` in the browser: null once the opener started, else why it could not (the URL is printed either way). */
 export function openBrowser(url) {
     const [command, args] = openCommand(process.platform, url);
@@ -87,6 +111,9 @@ export function openBrowser(url) {
         child.once("spawn", () => { child.unref(); resolve(null); });
     });
 }
+/** Whether to open a browser: asked for (no --no-open) and stdout a terminal, a person in front of it (never a pipe,
+ *  a file or a coding agent's shell, which get the address alone). */
+const opens = (noOpen) => !noOpen && process.stdout.isTTY === true;
 /** Whether the run serves the page: its `GET /` answered, with the token the commands send. */
 async function servesPage(run) {
     let res;
@@ -155,6 +182,12 @@ export async function ui(argv) {
     const wrong = (message) => failed("ui", { message, code: "usage", usage: UI.usage }, { json });
     if (f.positionals.length)
         return wrong(`mason ui takes no argument: ${f.positionals.join(" ")}`);
+    if (v.replica !== undefined) {
+        const beside = [["--ssh", v.ssh !== undefined], ["--bridge", v.bridge], ["--mason", v.mason !== undefined], ["--timeout", v.timeout !== undefined],
+            ["--local-port", v["local-port"] !== undefined]].filter(([, given]) => given).map(([name]) => name);
+        if (beside.length)
+            return wrong(`--replica opens a hosted replica's page: it goes with --no-open and --json alone, not ${beside.join(", ")}`);
+    }
     if (v.bridge) {
         if (v.ssh !== undefined || v.mason !== undefined || v.timeout !== undefined || json)
             return wrong("--bridge is mason ui --ssh's own end on the server: it goes with --local-port alone");
@@ -173,11 +206,18 @@ export async function ui(argv) {
             return wrong(`--ssh: ${problem}`);
         if (v.mason !== undefined && (v.mason.trim() === "" || /[\r\n]/.test(v.mason)))
             return wrong("--mason is one line of shell that runs mason on the server");
-        const seconds = v.timeout === undefined ? DEFAULT_TIMEOUT_S : Number(v.timeout);
-        if (!Number.isFinite(seconds) || seconds <= 0)
-            return wrong(`--timeout is a number of seconds, not ${JSON.stringify(v.timeout)}`);
-        return overSsh(v.ssh, v.mason ?? "mason", seconds * 1000, !v["no-open"], json);
+        const read = parseDuration(v.timeout ?? String(DEFAULT_TIMEOUT_S));
+        if ("problem" in read)
+            return wrong(`--timeout ${read.problem}`);
+        const seconds = read.seconds;
+        return overSsh(v.ssh, v.mason ?? "mason", seconds * 1000, opens(v["no-open"]), json);
     }
+    // a replica on a hosted service (--replica, else MASON_REPLICA): --ssh and --bridge name their own target, above
+    const replica = replicaOf(v.replica, UI.usage);
+    if (replica !== null && "message" in replica)
+        return failed("ui", replica, { json });
+    if (replica !== null)
+        return hostedUi(replica, { open: opens(v["no-open"]), json });
     const w = await reach(UI, json);
     if (w === null || w.state !== "up")
         return 1;
@@ -199,8 +239,9 @@ export async function ui(argv) {
         out(jsonText(UI, { url, port }, NEXT));
         return 0;
     }
-    const couldNot = f.values["no-open"] === true ? null : await openBrowser(url);
-    const opened = f.values["no-open"] !== true && couldNot === null;
+    const open = opens(v["no-open"]);
+    const couldNot = open ? await openBrowser(url) : null;
+    const opened = open && couldNot === null;
     out(reportText({
         headline: opened ? `Mason's web page, opened in your browser` : `Mason's web page`,
         details: [["url", url], ["project", run.name]],

package/dist/src/cli/usage.js

@@ -12,9 +12,10 @@ import { fileSize, guarded, runFailure } from "./commands.js";
 import { timeOf } from "./request-filter.js";
 import { duration, msText } from "./readiness.js";
 import { SIZE_EVERY_MS } from "../duck/usage.js";
+import { parseDuration } from "../lib/table-sync.js";
 const out = (m) => { process.stdout.write(`${m}\n`); };
 const n = (x) => x.toLocaleString("en-US");
-export const USAGE_USAGE = `usage: mason usage [--since <when>] [--until <when>] [--step <span>] [--json]
+export const USAGE_USAGE = `usage: mason usage [--since <when>] [--until <when>] [--step <duration>] [--json]
 
   What Mason was and did over time, from a sample it takes every minute and keeps MASON_HISTORY_DAYS days
   (default 7): a line each span — the statements of the Postgres API (how many, how many were refused, failed or
@@ -29,15 +30,18 @@ export const USAGE_USAGE = `usage: mason usage [--since <when>] [--until <when>]
 
   --since <when>   from when: an age (90s, 30m, 6h, 7d) or an ISO 8601 date or time with its zone; default 1h
   --until <when>   until when, the same way; default now
-  --step <span>    a line per span (1m to the days kept; default 5m), or 0 for every sample as it was taken
-  --json           as data: { since, until, stepSeconds (null: every sample), sampleSeconds, keptDays, samples: [{ at
-                   (with a step, the span's start), seconds, copyBytes, copyRows, tablesAdded, tablesCopied,
-                   tablesFailed, oldestSyncSeconds, statements, statementsRefused, statementsFailed, statementsCancelled,
-                   rowsSent, bytesSent, durationP50Ms, durationP95Ms, streamLagBytes, streamLagSeconds, rssBytes,
-                   heapUsedBytes, copyMemoryBytes, copyMemoryLimitBytes, slotWalHeldBytes (replication: the WAL the
-                   slot holds on the database), diskFreeBytes (free where the synced data is; with a step, the lowest),
-                   sessionsOpen (the Postgres API's sessions logged in) }],
-                   copySizes: [{ table, bytes, at }], next }
+  --step <duration>  a line per span (1m to the days kept; default 5m; a bare number is seconds), or 0 for every
+                   sample as it was taken
+  --json           as data: its shape is at the end
+
+  The --json answer: { since, until, stepSeconds (null: every sample), sampleSeconds, keptDays, samples: [{ at
+    (with a step, the span's start), seconds, copyBytes, copyRows, tablesAdded, tablesCopied,
+    tablesFailed, oldestSyncSeconds, statements, statementsRefused, statementsFailed, statementsCancelled,
+    rowsSent, bytesSent, durationP50Ms, durationP95Ms, streamLagBytes, streamLagSeconds, rssBytes,
+    heapUsedBytes, copyMemoryBytes, copyMemoryLimitBytes, slotWalHeldBytes (replication: the WAL the
+    slot holds on the database), diskFreeBytes (free where the synced data is; with a step, the lowest),
+    sessionsOpen (the Postgres API's sessions logged in) }],
+    copySizes: [{ table, bytes, at }], next }
 `;
 export const USAGE = {
     needs: "run",
@@ -47,13 +51,13 @@ export const USAGE = {
     options: { since: { type: "string" }, until: { type: "string" }, step: { type: "string" }, json: { type: "boolean" } },
     json: ["since", "until", "stepSeconds", "sampleSeconds", "keptDays", "samples", "copySizes", "next"],
 };
-const UNIT = { s: 1, m: 60, h: 3600, d: 86_400 };
-/** A span as the options write it (90s, 30m, 6h, 7d; 0), in seconds, or null when it is not one. */
+/** A span as the options write it (the command line's one duration grammar, src/lib/table-sync.ts `parseDuration`:
+ *  90s, 30m, 6h, 7d, a bare number of seconds; 0 for every sample), in whole seconds, or null when it is not one. */
 export function spanSeconds(text) {
     if (text.trim() === "0")
         return 0;
-    const m = /^\s*(\d+)\s*([smhd])\s*$/.exec(text);
-    return m ? Number(m[1]) * UNIT[m[2]] : null;
+    const d = parseDuration(text, { zero: true });
+    return "problem" in d || !Number.isInteger(d.seconds) ? null : d.seconds;
 }
 /** One sample on one line: the time, the statements, those refused, failed or cancelled, p95, rows sent, the copy, its rows, the stalest copy, the lag, the memory. */
 export function sampleLine(s, withLag) {
@@ -87,7 +91,7 @@ export async function usage(argv, now = Date.now()) {
             return failed("usage", { ...t, usage: USAGE_USAGE }, { json });
     const step = spanSeconds(v.step ?? "5m");
     if (step === null)
-        return failed("usage", { message: `--step is a span (1m, 5m, 1h, 1d) or 0 for every sample, not ${JSON.stringify(v.step)}`, code: "usage", usage: USAGE_USAGE }, { json });
+        return failed("usage", { message: `--step is a duration (300, 1m, 5m, 1h, 1d: a bare number is seconds) or 0 for every sample, not ${JSON.stringify(v.step)}`, code: "usage", usage: USAGE_USAGE }, { json });
     const w = await reach(USAGE, json);
     if (w === null || !("run" in w))
         return 1;

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

@@ -4,7 +4,8 @@
  * 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)
+ *   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 }
@@ -36,6 +37,10 @@
  *   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
@@ -57,12 +62,12 @@ 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 { 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, listNext, listText, REMOVED_NEXT, removedReport, USER } from "./user.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;
@@ -83,7 +88,9 @@ export function requestOf(r, o) {
     // 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 "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}` };
@@ -125,6 +132,16 @@ function attributesOf(v) {
     }
     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. */
@@ -142,6 +159,10 @@ function rowOf(v) {
     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;
@@ -150,7 +171,7 @@ function rowOf(v) {
     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 } : {}),
+        url: u.url, from, ...role, ...(attributes !== undefined ? { attributes } : {}),
         ...(u.missingAttributes !== undefined ? { missingAttributes: u.missingAttributes } : {}),
         ...(typeof u.roleKnown === "boolean" ? { roleKnown: u.roleKnown } : {}) };
 }
@@ -195,11 +216,15 @@ export function heldAdded(json, asked, secrets) {
     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 } : {}) };
+        ...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) {
@@ -219,6 +244,14 @@ export function heldEnabled(json, asked, secrets) {
     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;
@@ -226,8 +259,25 @@ export function heldRemoved(json, asked, secrets) {
     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", disable: "a user was disabled", enable: "a user was enabled", remove: "a user was removed" };
+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());
@@ -250,8 +300,10 @@ export async function hostedUser(r, o) {
     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, value, next) : text());
+        out(o.json ? jsonText(USER, { replica: on, ...value }, next) : text());
         return 0;
     };
     switch (o.verb) {
@@ -260,7 +312,7 @@ export async function hostedUser(r, o) {
             if (l === null)
                 return outside();
             const next = onReplica(listNext(l.users), r);
-            return print({ ...l }, next, () => listText(replicaText(r), l, NO_ROLES, next, outStyle));
+            return print({ ...l }, next, () => listText(on, l, NO_ROLES, next, outStyle));
         }
         case "add": {
             const added = heldAdded(a.json, o.name, secrets);
@@ -271,29 +323,42 @@ export async function hostedUser(r, o) {
                     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 }, outStyle));
+            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));
+            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));
+            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({ ...x }, next, () => removedReport(x, true, next, outStyle));
+            return print({ removedUser: x.removed, ...x }, next, () => removedReport(x, true, next, outStyle, on));
         }
     }
 }