@mason-data/cli 0.7.0 → 0.9.0

package/dist/src/duck/users.js

@@ -11,10 +11,14 @@
  * statement of its session is attributed to that user, and rotating the API key removes every user at once (no MAC
  * verifies under the new key). It never collides with a token: a token's MAC is 43 base64url characters.
  *
- * THE LIST OF LIVE USERS is a FILE in the state folder (`.mason/users.json`), never a DuckDB table: `mason user …` runs
+ * THE LIST OF USERS is a FILE in the state folder (`.mason/users.json`), never a DuckDB table: `mason user …` runs
  * as a second process beside the run, which holds DuckDB's file lock. It holds each user's name, id, when it was added
  * and the API key's fingerprint at the time (`key`, a MAC of a constant: no secret, it says which key a user was added
- * under) — never a password. A change is made under a lock file (`users.json.lock`, O_EXCL) and written beside and
+ * under) — never a password. A removed user STAYS in it with `removedAt` (so a list can show who was removed, and when):
+ * only the entries without one are live, and the listener reads only those. A DISABLED user stays too, with
+ * `disabledAt` (`mason user disable`): its password still verifies, but its login is refused as Postgres refuses a role
+ * without LOGIN (28000, "is not permitted to log in") and its sessions end at their next statement, until `mason user
+ * enable` clears it — the same id, so the same password connects again. A change is made under a lock file (`users.json.lock`, O_EXCL) and written beside and
  * renamed, so a reader sees the old list or the new one, never half of either, and two `mason user add` at once cannot
  * both win a name. The listener RE-READS it (`LiveUsers`: a stat at every connection and before every statement of a
  * user's session, the file read again when its inode, size or mtime moved), so a removal refuses the next connection
@@ -24,13 +28,27 @@
 import * as crypto from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { ApiError } from "../api/error.js";
+import { ApiError, USER_DISABLED } from "../api/error.js";
 import { tokenProblem } from "./token.js";
+import { ATTRIBUTE_NAME_RE } from "./row-filter.js";
 export const USERS_FILE = "users.json";
 /** A user's name: what a BI tool's form calls the user (Postgres's NAMEDATALEN, 63), lower case so a form that
  *  capitalises it is told so, never another user. */
 export const USER_NAME_RE = /^[a-z0-9][a-z0-9_.-]{0,62}$/;
 export const USER_NAME_RULE = "1 to 63 lower case letters, digits, \"_\", \".\" or \"-\", starting with a letter or digit (e.g. metabase)";
+/** a user's attributes as the file keeps them: a name each, a string or a list of strings */
+function attributesValid(v) {
+    // a NUL ends the statement it is bound into, wherever it is: every statement of the user would fail as a syntax error
+    const value = (x) => typeof x === "string" && !x.includes("\0");
+    return typeof v === "object" && v !== null && !Array.isArray(v) &&
+        Object.entries(v).every(([k, x]) => ATTRIBUTE_NAME_RE.test(k) && (value(x) || (Array.isArray(x) && x.every(value))));
+}
+/** Whether a user has not been removed (it may still not connect: see `underKey`). */
+export const isActive = (u) => u.removedAt === undefined;
+/** Whether a user is disabled (`mason user disable`): kept, its password unchanged, its logins refused until enabled. */
+export const isDisabled = (u) => u.disabledAt !== undefined;
+/** A role's name as the users file may carry it (src/cli/roles.ts ROLE_NAME_RE, which the roles file holds it to). */
+const ROLE_RE = /^[a-z0-9][a-z0-9_-]{0,62}$/;
 const PASSWORD_RE = /^mason_([0-9a-f]{16})_([0-9a-f]{32})$/;
 const mac = (apiKey, name, id) => crypto.createHmac("sha256", apiKey).update(`mason-user:${name}:${id}`).digest("hex").slice(0, 32);
 /** Which API key a user was added under, without the key: a MAC of a constant, 16 hex digits. */
@@ -41,6 +59,8 @@ export const newUserId = () => crypto.randomBytes(8).toString("hex");
 export const userPassword = (apiKey, name, id) => `mason_${id}_${mac(apiKey, name, id)}`;
 /** Whether a password is a user's by its shape (else it is read as a token, src/duck/token.ts). */
 export const isUserPassword = (password) => PASSWORD_RE.test(password);
+/** What every `mason share` password begins with (src/cli/share-run.ts `newSharePassword`): no user's has it, `share` being no hex. */
+export const SHARE_PASSWORD_PREFIX = "mason_share_";
 /** Whether a user was added under this API key (one rotated since is no longer live). */
 export const underKey = (u, apiKey) => u.key === keyFingerprint(apiKey);
 /** The users the file lists; none when there is no file; why not, when it cannot be read — never an empty list then. */
@@ -71,10 +91,19 @@ function parseUsers(file, text) {
     for (const [i, u] of list.entries()) {
         const o = u;
         if (typeof o !== "object" || o === null || typeof o.name !== "string" || !USER_NAME_RE.test(o.name) || typeof o.id !== "string" || !/^[0-9a-f]{16}$/.test(o.id) ||
-            typeof o.addedAt !== "string" || typeof o.key !== "string") {
-            return { problem: `${file}: users[${i}] is not { name, id, addedAt, key } as mason user add writes it` };
+            typeof o.addedAt !== "string" || typeof o.key !== "string" || (o.role !== undefined && (typeof o.role !== "string" || !ROLE_RE.test(o.role))) ||
+            (o.attributes !== undefined && !attributesValid(o.attributes))) {
+            return { problem: `${file}: users[${i}] is not { name, id, addedAt, key, role?, attributes?[, removedAt][, disabledAt] } as mason user add writes it` };
+        }
+        if (o.removedAt !== undefined && typeof o.removedAt !== "string") {
+            return { problem: `${file}: users[${i}].removedAt is not a timestamp as mason user remove writes it` };
+        }
+        if (o.disabledAt !== undefined && typeof o.disabledAt !== "string") {
+            return { problem: `${file}: users[${i}].disabledAt is not a timestamp as mason user disable writes it` };
         }
-        users.push({ name: o.name, id: o.id, addedAt: o.addedAt, key: o.key });
+        users.push({ name: o.name, id: o.id, addedAt: o.addedAt, key: o.key, ...(typeof o.role === "string" ? { role: o.role } : {}),
+            ...(attributesValid(o.attributes) ? { attributes: o.attributes } : {}),
+            ...(o.removedAt !== undefined ? { removedAt: o.removedAt } : {}), ...(o.disabledAt !== undefined ? { disabledAt: o.disabledAt } : {}) });
     }
     return { users };
 }
@@ -140,8 +169,8 @@ export function changeUsers(file, change) {
 }
 // ------------------------------------------------------------------ the listener's view
 /** The ApiError a refused user login carries: the user it asked for, so the request log names who still tries. */
-function refusal(status, message, user) {
-    const e = new ApiError(status, message, status === 503 ? "users_unreadable" : "invalid_user");
+function refusal(status, message, user, code = status === 503 ? "users_unreadable" : "invalid_user") {
+    const e = new ApiError(status, message, code);
     e.userName = user;
     return e;
 }
@@ -156,7 +185,7 @@ export class LiveUsers {
     seen = null;
     read = { users: [] };
     constructor(file, apiKey) { this.file = file; this.apiKey = apiKey; }
-    /** the users now; why not, when the file cannot be read */
+    /** the users not removed now (disabled ones included: their login is refused by name); why not, when the file cannot be read */
     now() {
         let stamp;
         try {
@@ -169,7 +198,9 @@ export class LiveUsers {
             stamp = "none";
         }
         if (stamp !== this.seen || "problem" in this.read) {
-            this.read = readUsers(this.file);
+            const r = readUsers(this.file);
+            // a removed user is kept in the file for the list: it is no user to the listener
+            this.read = "problem" in r ? r : { users: r.users.filter(isActive) };
             this.seen = stamp;
         }
         return this.read;
@@ -197,35 +228,58 @@ export class LiveUsers {
         // is the login — to anyone holding only the password (found on the test server)
         if (found.name !== user)
             throw refusal(401, "not a password of this project's users: mason user list shows them", user);
-        return { filters: [], subject: undefined, user: found.name, jti: found.id };
+        // disabled: refused only once its password verified (so the state is told to the holder of the login alone), in
+        // Postgres's words for a role without LOGIN, 28000 (src/api/postgres/server.ts reads the code)
+        if (isDisabled(found))
+            throw refusal(401, disabledMessage(found.name), user, USER_DISABLED);
+        return { filters: [], subject: undefined, user: found.name, jti: found.id, ...(found.role !== undefined ? { role: found.role } : {}), ...attributesOf(found) };
     }
-    /** A held session's user, asked again before a statement: throws as `login` does when it is no longer live. */
+    /**
+     * A held session's user, asked again before a statement: throws as `login` does when it is no longer live; else the
+     * token as the file has the user NOW — its role as `mason user add --role` wrote it, so a role given or taken
+     * applies at the user's next statement, without a restart.
+     */
     recheck(token) {
         if (token.user === undefined)
-            return;
+            return token;
         const now = this.now();
         if ("problem" in now)
             throw refusal(503, `the list of users cannot be read: ${now.problem}`, token.user);
-        if (!now.users.some((u) => u.id === token.jti && u.name === token.user))
+        const found = now.users.find((u) => u.id === token.jti && u.name === token.user);
+        if (found === undefined)
             throw refusal(401, `the user "${token.user}" was removed`, token.user);
+        if (isDisabled(found))
+            throw refusal(401, `the user "${token.user}" was disabled`, token.user, USER_DISABLED);
+        if (found.role === token.role && JSON.stringify(found.attributes ?? null) === JSON.stringify(token.attributes ?? null))
+            return token;
+        const { role: _was, attributes: _had, ...rest } = token;
+        return { ...rest, ...(found.role !== undefined ? { role: found.role } : {}), ...attributesOf(found) };
     }
 }
+/** a user's attributes as its session's token carries them (src/api/postgres/server.ts PgToken) */
+const attributesOf = (u) => u.attributes !== undefined && Object.keys(u.attributes).length > 0 ? { attributes: u.attributes } : {};
+/** A disabled user's refused login: Postgres's sentence for a role without LOGIN, and it alone — why is its DETAIL,
+ *  the way out its HINT (src/api/postgres/server.ts), as Postgres splits them. */
+export const disabledMessage = (name) => `role "${name}" is not permitted to log in`;
 /**
  * HOW THE DUCKDB RUN'S LISTENER TAKES A PASSWORD (src/cli/dev.ts; the tests wire the same): a user's password (its shape)
  * is the users file's to judge, and its session is asked again before every statement (a stat); anything else is read as a
  * token, the kind `mason connect` minted before `mason user` (src/duck/token.ts: the API key used as a password is refused by name).
+ * A `mason share` password is refused by name too: it was never this port's, and making a user is not the way out.
  */
 export function listenerLogins(users, apiKey) {
     return {
         authenticate: (password, user) => {
             if (isUserPassword(password))
                 return users.login(user, password);
+            if (password.startsWith(SHARE_PASSWORD_PREFIX))
+                throw new Error("a mason share password logs in only at the address mason share printed, never on this port");
             const problem = tokenProblem(apiKey, password);
             if (problem !== null)
                 throw new Error(problem);
             return { filters: [], subject: undefined };
         },
-        recheck: async (t) => { users.recheck(t); },
+        recheck: async (t) => users.recheck(t),
         recheckMs: 0,
     };
 }