@intentius/chant-lexicon-sql 0.124.30 → 0.124.32

package/dist/clickhouse/access.js

@@ -0,0 +1,722 @@
+/**
+ * ClickHouse access control as declarations (#3682): users, roles, row
+ * policies and grants, and quotas and settings profiles (#3911).
+ *
+ * Each is a statement the server keeps outside any table: `CREATE USER`,
+ * `CREATE ROLE`, `CREATE ROW POLICY`, `CREATE QUOTA`,
+ * `CREATE SETTINGS PROFILE` and `GRANT`. This module parses them
+ * (the tags in `./entities.ts`, the lint rule, the plan), reduces each to
+ * the fields a plan compares, and writes the statements that make a change.
+ *
+ * What a declaration owns and what the environment owns:
+ *
+ * - A password is the environment's. `IDENTIFIED BY` is refused in a
+ *   declaration (only `ssh_key BY KEY`, a public key, is taken), so no
+ *   secret is ever in a build. A user declared with no `IDENTIFIED` clause
+ *   is compared without it, and is not created by chant: create it with its
+ *   password, and the next apply manages the rest of it. A user declared
+ *   with a method that holds no secret (`ssl_certificate`, `ldap`,
+ *   `kerberos`, `http`, `ssh_key`, `no_password`) is created and kept so.
+ * - Grants are compared per grantee, for each grantee the build declares a
+ *   grant to: every grant declaration naming it adds up to its complete
+ *   list, and a grant made by hand to it is revoked. A grant another one
+ *   covers (`SELECT ON db.t` beside `SELECT ON db.*`) is folded away, as the
+ *   server folds it.
+ * - None of these objects has a comment, so none carries chant's ownership
+ *   marker. A plan reads only the ones the build declares; chant creates and
+ *   changes them, and never drops one.
+ */
+import { isTrivia, tokenizeText } from "./tokens.js";
+import { kw, SqlCursor } from "../core/cursor.js";
+import { unquote } from "./parser.js";
+/** A token that can stand where a name goes: a name may start with a digit (`02294_profile`). */
+const isName = (t) => t !== undefined && (t.kind === "ident" || t.kind === "qident" || t.kind === "ref" || (t.kind === "number" && /[A-Za-z_]/.test(t.text)));
+class AccessParser extends SqlCursor {
+    constructor() {
+        super(...arguments);
+        this.orReplace = false;
+        this.ifNotExists = false;
+    }
+    name(what) {
+        const t = this.next();
+        if (!isName(t))
+            this.fail(`expected ${what}`, t);
+        const i = this.idx(-1);
+        return { from: i, to: i + 1, refs: t.kind === "ref" ? [t.part] : [] };
+    }
+    /** `name` or `db.name`, a `*` in either place. */
+    qualified() {
+        const from = this.idx();
+        const refs = [];
+        const one = () => {
+            const t = this.next();
+            if (!(isName(t) || (t.kind === "op" && t.text === "*")))
+                this.fail("expected a name", t);
+            if (t.kind === "ref")
+                refs.push(t.part);
+        };
+        one();
+        while (this.isPunct(".")) {
+            this.p++;
+            one();
+        }
+        return this.span(from, refs);
+    }
+    /** `IF NOT EXISTS` or `OR REPLACE`, which ClickHouse takes after USER, ROLE and ROW POLICY. */
+    head() {
+        if (kw(this.peek(), "IF") && kw(this.peek(1), "NOT") && kw(this.peek(2), "EXISTS")) {
+            this.p += 3;
+            this.ifNotExists = true;
+        }
+        else if (kw(this.peek(), "OR") && kw(this.peek(1), "REPLACE")) {
+            this.p += 2;
+            this.orReplace = true;
+        }
+    }
+    onClusterClause() {
+        if (kw(this.peek(), "ON") && kw(this.peek(1), "CLUSTER")) {
+            this.p += 2;
+            const from = this.idx();
+            const t = this.next();
+            if (!isName(t) && t.kind !== "string")
+                this.fail("expected a cluster name", t);
+            return this.span(from, t.kind === "ref" ? [t.part] : []);
+        }
+        return undefined;
+    }
+    /**
+     * Clauses in any order: each starts with one of `starts` (a keyword
+     * sequence) and runs to the next clause. A key of `repeats` may follow
+     * itself (a quota's `FOR INTERVAL ..., FOR INTERVAL ...`): its span runs
+     * from the first to the last.
+     */
+    clauses(starts, node, repeats = []) {
+        const stopWords = [...new Set(Object.values(starts).map((w) => w[0]))];
+        let last;
+        for (;;) {
+            if (this.atEnd())
+                return;
+            const hit = Object.entries(starts).find(([, words]) => words.every((w, i) => kw(this.peek(i), w)));
+            if (!hit)
+                this.fail(`unexpected ${this.peek()?.text}: expected ${Object.values(starts).map((w) => w.join(" ")).join(", ")}`);
+            const [key, words] = hit;
+            const again = node.clauses[key];
+            if (again && !(repeats.includes(key) && last === key))
+                this.fail(`${words.join(" ")} is written twice`);
+            // A repeated clause keeps its keywords inside the span: `FOR INTERVAL 1 hour ..., FOR INTERVAL 1 day ...`.
+            const from = this.idx();
+            this.p += words.length;
+            // `NOT IDENTIFIED` and `NOT KEYED` have no value; every other clause has one.
+            const value = key === "notIdentified" || key === "notKeyed" ? { from: this.idx(-1), to: this.idx(-1) + 1, refs: [] } : this.expr(stopWords, false);
+            node.clauses[key] = repeats.includes(key) ? { from: again?.from ?? from, to: value.to, refs: [...(again?.refs ?? []), ...value.refs] } : value;
+            last = key;
+        }
+    }
+    parse() {
+        if (this.accept("GRANT"))
+            return this.grant(false);
+        if (this.accept("REVOKE"))
+            return this.grant(true);
+        this.expect("CREATE");
+        const node = (statement) => ({ statement, orReplace: this.orReplace, ifNotExists: this.ifNotExists, clauses: {}, items: [], grantees: [] });
+        if (this.accept("USER")) {
+            this.head();
+            const n = node("user");
+            n.name = this.name("a user name");
+            if (this.isPunct(","))
+                this.fail("declare one user per template");
+            n.onCluster = this.onClusterClause();
+            this.clauses({
+                notIdentified: ["NOT", "IDENTIFIED"],
+                identified: ["IDENTIFIED"],
+                host: ["HOST"],
+                validUntil: ["VALID", "UNTIL"],
+                in: ["IN"],
+                defaultRole: ["DEFAULT", "ROLE"],
+                defaultDatabase: ["DEFAULT", "DATABASE"],
+                grantees: ["GRANTEES"],
+                settings: ["SETTINGS"],
+            }, n);
+            refusePassword(this, this.tokens, n);
+            return n;
+        }
+        if (this.accept("ROLE")) {
+            this.head();
+            const n = node("role");
+            n.name = this.name("a role name");
+            if (this.isPunct(","))
+                this.fail("declare one role per template");
+            n.onCluster = this.onClusterClause();
+            this.clauses({ in: ["IN"], settings: ["SETTINGS"] }, n);
+            return n;
+        }
+        if (this.accept("QUOTA")) {
+            this.head();
+            const n = node("quota");
+            n.name = this.name("a quota name");
+            if (this.isPunct(","))
+                this.fail("declare one quota per template");
+            n.onCluster = this.onClusterClause();
+            this.clauses({ in: ["IN"], keyed: ["KEYED", "BY"], keyBy: ["KEY", "BY"], notKeyed: ["NOT", "KEYED"], for: ["FOR"], to: ["TO"] }, n, ["for"]);
+            // `KEY BY` is the server's other spelling of `KEYED BY`.
+            if (n.clauses.keyBy) {
+                if (n.clauses.keyed)
+                    this.fail("KEYED BY is written twice");
+                n.clauses.keyed = n.clauses.keyBy;
+                delete n.clauses.keyBy;
+            }
+            if (n.clauses.keyed && n.clauses.notKeyed)
+                this.fail("KEYED BY and NOT KEYED are both written");
+            return n;
+        }
+        if (this.acceptSeq("SETTINGS", "PROFILE") || this.accept("PROFILE")) {
+            this.head();
+            const n = node("settingsProfile");
+            n.name = this.name("a settings profile name");
+            if (this.isPunct(","))
+                this.fail("declare one settings profile per template");
+            n.onCluster = this.onClusterClause();
+            this.clauses({ in: ["IN"], settings: ["SETTINGS"], to: ["TO"] }, n);
+            return n;
+        }
+        if (this.accept("ROW"))
+            this.expect("POLICY");
+        else if (!this.accept("POLICY"))
+            this.fail("expected USER, ROLE, ROW POLICY, QUOTA or SETTINGS PROFILE");
+        this.head();
+        const n = node("rowPolicy");
+        n.name = this.name("a policy name");
+        n.onCluster = this.onClusterClause();
+        this.expect("ON");
+        n.table = this.qualified();
+        if (this.isPunct(","))
+            this.fail("declare one row policy, on one table, per template");
+        this.clauses({ as: ["AS"], for: ["FOR"], using: ["USING"], to: ["TO"] }, n);
+        if (!n.clauses.using)
+            this.fail("expected USING and the policy's condition");
+        return n;
+    }
+    grant(revoke) {
+        const n = { statement: "grant", orReplace: false, ifNotExists: false, clauses: {}, items: [], grantees: [], ...(revoke ? { revoke: true } : {}) };
+        n.onCluster = this.onClusterClause();
+        if (revoke && (this.acceptSeq("GRANT", "OPTION", "FOR") || this.acceptSeq("ADMIN", "OPTION", "FOR")))
+            this.fail("REVOKE ... OPTION FOR is not read");
+        if (kw(this.peek(), "CURRENT") && kw(this.peek(1), "GRANTS"))
+            this.fail("GRANT CURRENT GRANTS grants whatever the applying user holds; name the privileges");
+        const to = revoke ? "FROM" : "TO";
+        for (;;) {
+            n.items.push(this.expr(["ON", to]));
+            if (this.acceptPunct(","))
+                continue;
+            break;
+        }
+        if (this.accept("ON"))
+            n.target = this.qualified();
+        this.expect(to);
+        for (;;) {
+            n.grantees.push(this.expr(["WITH"]));
+            if (this.acceptPunct(","))
+                continue;
+            break;
+        }
+        if (this.accept("WITH")) {
+            if (this.acceptSeq("GRANT", "OPTION"))
+                n.withOption = "GRANT";
+            else if (this.acceptSeq("ADMIN", "OPTION"))
+                n.withOption = "ADMIN";
+            else if (kw(this.peek(), "REPLACE"))
+                this.fail("WITH REPLACE OPTION revokes whatever else the grantee holds; declare the complete list instead");
+            else
+                this.fail("expected GRANT OPTION or ADMIN OPTION");
+        }
+        if (!n.target && n.withOption === "GRANT")
+            this.fail("WITH GRANT OPTION is for privileges; a role takes WITH ADMIN OPTION");
+        this.acceptPunct(";");
+        if (this.peek() !== undefined)
+            this.fail("unexpected token after the grant");
+        return n;
+    }
+}
+/** The authentication methods that hold no secret: a user declared with one is created by chant. */
+export const SECRETLESS = new Set(["no_password", "ssl_certificate", "ldap", "kerberos", "http", "ssh_key"]);
+function refusePassword(p, tokens, node) {
+    const span = node.clauses.identified;
+    if (!span)
+        return;
+    const sig = tokens.slice(span.from, span.to).filter((t) => !isTrivia(t));
+    const words = sig.map((t) => t.text.toLowerCase());
+    const method = words[0] === "with" ? words[1] : undefined;
+    // `SHOW CREATE USER` prints a password's method without the password (`IDENTIFIED WITH sha256_password`): that much is read.
+    const secret = words.includes("by") || words.includes("hash");
+    if (secret && method !== "ssh_key") {
+        p.fail(method === undefined
+            ? "IDENTIFIED BY holds a password, which is the environment's: declare the user without IDENTIFIED, create it with its password, and chant manages the rest"
+            : `IDENTIFIED WITH ${method} holds a password or its hash, which is the environment's: declare the user without IDENTIFIED, create it with its password, and chant manages the rest`, sig[0]);
+    }
+}
+/** Parse one access statement. Throws `SqlSyntaxError` located in the statement. */
+export function parseAccess(tokens) {
+    return new AccessParser(tokens).parse();
+}
+/** Whether a statement's text is an access statement this module reads. */
+export function isAccessStatement(ddl) {
+    const words = ddl
+        .replace(/--[^\n]*\n/g, " ")
+        .trim()
+        .split(/\s+/, 4)
+        .map((w) => w.toUpperCase());
+    if (words[0] === "GRANT" || words[0] === "REVOKE")
+        return true;
+    if (words[0] !== "CREATE")
+        return false;
+    return ["USER", "ROLE", "ROW", "POLICY", "QUOTA", "PROFILE"].includes(words[1]) || (words[1] === "SETTINGS" && words[2] === "PROFILE");
+}
+// ── canonical forms ───────────────────────────────────────────────────
+const text = (tokens, span) => span && span.to > span.from
+    ? tokens
+        .slice(span.from, span.to)
+        .map((t) => t.text)
+        .join("")
+        .trim()
+    : undefined;
+const sigOf = (tokens, span) => tokens.slice(span.from, span.to).filter((t) => !isTrivia(t));
+/** Tokens joined by single spaces: identifiers unquoted, bare words as `word` says. */
+function join(sig, word) {
+    return sig.map((t) => (t.kind === "qident" ? unquote(t.text) : t.kind === "ident" ? word(t.text) : t.text)).join(" ");
+}
+/** A comma-separated list of names, sorted, with the words of `keywords` upper case: `DEFAULT ROLE b, a` and `TO ALL EXCEPT r`. */
+function nameList(tokens, span, keywords) {
+    const sig = sigOf(tokens, span);
+    const out = [];
+    let cur = [];
+    const flush = () => {
+        if (cur.length)
+            out.push(join(cur, (w) => (keywords.includes(w.toUpperCase()) ? w.toUpperCase() : w)));
+        cur = [];
+    };
+    for (const t of sig) {
+        if (t.kind === "punct" && t.text === ",")
+            flush();
+        else if (t.kind === "ident" && keywords.includes(t.text.toUpperCase()) && cur.length > 0 && !keywords.includes(cur[cur.length - 1].text.toUpperCase())) {
+            // `ALL EXCEPT a`: the keyword starts a new part.
+            flush();
+            cur.push(t);
+        }
+        else
+            cur.push(t);
+    }
+    flush();
+    const keys = out.filter((x) => keywords.includes(x.split(" ")[0]));
+    const names = out.filter((x) => !keywords.includes(x.split(" ")[0])).sort();
+    return [...keys, ...names].join(" , ");
+}
+/** A span's significant tokens split at its top-level commas. */
+function topLevelParts(sig) {
+    const parts = [[]];
+    let depth = 0;
+    for (const t of sig) {
+        if (t.text === "(")
+            depth++;
+        if (t.text === ")")
+            depth--;
+        if (depth === 0 && t.kind === "punct" && t.text === ",")
+            parts.push([]);
+        else
+            parts[parts.length - 1].push(t);
+    }
+    return parts.filter((p) => p.length > 0);
+}
+/**
+ * `SETTINGS a = 1 READONLY, b MIN 0 MAX 2, PROFILE 'base'`: each setting,
+ * sorted by name, `READONLY` as the server prints it (`CONST`), and a
+ * profile inherited as the server prints it (`INHERIT base`).
+ */
+function settingsList(tokens, span) {
+    const words = new Set(["MIN", "MAX", "CONST", "READONLY", "WRITABLE", "CHANGEABLE_IN_READONLY", "PROFILE", "INHERIT", "NONE"]);
+    return topLevelParts(sigOf(tokens, span))
+        .map((p) => {
+        const head = p[0].text.toUpperCase();
+        if ((head === "PROFILE" || head === "INHERIT") && p.length === 2 && p[0].kind === "ident")
+            return `INHERIT ${p[1].kind === "string" ? stringText(p[1].text) : unquote(p[1].text)}`;
+        // The first word is the setting's name (`readonly = 1`), never a key word.
+        return [join(p.slice(0, 1), (w) => w), join(p.slice(1), (w) => (words.has(w.toUpperCase()) ? w.toUpperCase() : w))].filter(Boolean).join(" ").replace(/\bREADONLY$/, "CONST");
+    })
+        .sort()
+        .join(" , ");
+}
+/** A `'quoted'` string's value. */
+const stringText = (s) => s.slice(1, -1).replace(/''/g, "'").replace(/\\(.)/g, "$1");
+/** The length of each interval unit a quota takes, in seconds, as the server counts it (a month is a twelfth of a year). */
+export const QUOTA_INTERVAL_SECONDS = {
+    SECOND: 1,
+    MINUTE: 60,
+    HOUR: 3600,
+    DAY: 86400,
+    WEEK: 604800,
+    MONTH: 2629746,
+    QUARTER: 7889238,
+    YEAR: 31556952,
+};
+/** A limit's number as the server prints it: `1e9` is `1000000000`, `1000.0` is `1000`. */
+function quotaNumber(text) {
+    if (/^\d+$/.test(text))
+        return text.replace(/^0+(?=\d)/, "");
+    const n = Number(text);
+    return Number.isFinite(n) ? (Number.isSafeInteger(n) || !Number.isInteger(n) ? String(n) : BigInt(Math.round(n)).toString()) : text;
+}
+/**
+ * A quota's intervals (`FOR [RANDOMIZED] INTERVAL n unit {MAX k = v, ... |
+ * NO LIMITS | TRACKING ONLY}`, each `FOR` to the next), keyed by the
+ * interval's length in seconds, each as the server keeps it: limits sorted
+ * by name, lower case, `MAX queries 5` as `queries = 5`. An interval with
+ * `NO LIMITS` is no interval; a second one of the same length replaces the
+ * first, as on the server.
+ */
+export function quotaIntervals(tokens, span) {
+    const sig = sigOf(tokens, span);
+    const groups = [];
+    for (const t of sig) {
+        if (t.kind === "ident" && t.text.toUpperCase() === "FOR")
+            groups.push([]);
+        else if (groups.length > 0)
+            groups[groups.length - 1].push(t);
+    }
+    const out = {};
+    for (const g of groups) {
+        const words = g.filter((t) => !(t.kind === "punct" && t.text === ","));
+        let i = 0;
+        const randomized = words[i]?.text.toUpperCase() === "RANDOMIZED";
+        if (randomized)
+            i++;
+        if (words[i]?.text.toUpperCase() !== "INTERVAL")
+            throw new Error(`a quota's FOR takes INTERVAL n unit: FOR ${g.map((t) => t.text).join(" ")}`);
+        const count = Number(words[i + 1]?.text);
+        const unit = QUOTA_INTERVAL_SECONDS[(words[i + 2]?.text ?? "").toUpperCase().replace(/S$/, "")];
+        if (!Number.isInteger(count) || unit === undefined)
+            throw new Error(`a quota's interval is a whole number and a unit (second to year): FOR ${g.map((t) => t.text).join(" ")}`);
+        const rest = words.slice(i + 3);
+        const head = rest.map((t) => t.text.toUpperCase()).slice(0, 2).join(" ");
+        const seconds = String(count * unit);
+        if (head === "NO LIMITS") {
+            delete out[seconds];
+            continue;
+        }
+        let limits;
+        if (head === "TRACKING ONLY")
+            limits = "TRACKING ONLY";
+        else {
+            if (rest[0]?.text.toUpperCase() !== "MAX")
+                throw new Error(`a quota's interval takes MAX, NO LIMITS or TRACKING ONLY: FOR ${g.map((t) => t.text).join(" ")}`);
+            // After MAX: `name = value` or `name value`, separated by commas (already left out).
+            const items = [];
+            const after = rest.slice(1);
+            for (let k = 0; k < after.length;) {
+                const name = after[k].text.toLowerCase();
+                k++;
+                if (after[k]?.text === "=" && after[k].kind !== "string")
+                    k++;
+                const value = after[k];
+                if (!value)
+                    throw new Error(`a quota's limit ${name} has no value`);
+                items.push(`${name} = ${quotaNumber(value.text)}`);
+                k++;
+            }
+            limits = `MAX ${items.sort().join(" , ")}`;
+        }
+        out[seconds] = `${randomized ? "RANDOMIZED " : ""}${limits}`;
+    }
+    return out;
+}
+/** `HOST LOCAL, IP '10.0.0.0/8'`: each host, sorted, the kind of each upper case. */
+function hostList(tokens, span) {
+    const words = new Set(["LOCAL", "ANY", "NONE", "IP", "NAME", "REGEXP", "LIKE"]);
+    const sig = sigOf(tokens, span);
+    const parts = [];
+    let cur = [];
+    for (const t of [...sig, undefined]) {
+        if (!t || (t.kind === "punct" && t.text === ",")) {
+            if (cur.length)
+                parts.push(join(cur, (w) => (words.has(w.toUpperCase()) ? w.toUpperCase() : w)));
+            cur = [];
+        }
+        else
+            cur.push(t);
+    }
+    return parts.sort().join(" , ");
+}
+/** `[db.]name` with a table's database filled in. */
+function qualifiedName(tokens, span, defaultDatabase) {
+    const parts = sigOf(tokens, span)
+        .filter((t) => !(t.kind === "punct" && t.text === "."))
+        .map((t) => unquote(t.text));
+    return parts.length >= 2 ? { database: parts[parts.length - 2], name: parts[parts.length - 1] } : { database: defaultDatabase, name: parts[0] ?? "" };
+}
+/**
+ * A user, role or row policy as a plan compares it. A field at the server's
+ * default is left out, so a declaration that leaves out `HOST ANY` and the
+ * server that does not print it agree. A user's `IDENTIFIED` is kept only
+ * when written; a plan compares it only when the declaration has one.
+ */
+export function accessCanonical(ddl, defaultDatabase = "default") {
+    const tokens = tokenizeText(ddl, 0);
+    const node = parseAccess(tokens);
+    if (node.statement === "grant")
+        throw new Error("a grant is compared as its grantee's grants (grantsCanonical)");
+    const name = unquote(text(tokens, node.name) ?? "");
+    const fields = {};
+    const put = (key, value, def) => {
+        if (value !== undefined && value !== "" && value !== def)
+            fields[key] = value;
+    };
+    const c = node.clauses;
+    if (node.statement === "user") {
+        if (c.notIdentified)
+            fields.identified = "no_password";
+        else if (c.identified) {
+            // `WITH method` lower case, as the server prints it; key words upper case; strings as written.
+            const sig = sigOf(tokens, c.identified);
+            const out = sig.map((t, i) => (t.kind === "ident" ? (i === 1 && sig[0].text.toUpperCase() === "WITH" ? t.text.toLowerCase() : t.text.toUpperCase()) : t.text));
+            fields.identified = out.join(" ").replace(/^WITH no_password$/, "no_password").replace(/^WITH /, "");
+        }
+        put("host", c.host && hostList(tokens, c.host), "ANY");
+        put("validUntil", text(tokens, c.validUntil));
+        put("defaultRole", c.defaultRole && nameList(tokens, c.defaultRole, ["ALL", "NONE", "EXCEPT"]), "ALL");
+        put("defaultDatabase", c.defaultDatabase && unquote(text(tokens, c.defaultDatabase) ?? ""), "NONE");
+        put("grantees", c.grantees && nameList(tokens, c.grantees, ["ANY", "NONE", "EXCEPT"]), "ANY");
+        put("settings", c.settings && settingsList(tokens, c.settings), "NONE");
+        return { kind: "user", name, fields };
+    }
+    if (node.statement === "role") {
+        put("settings", c.settings && settingsList(tokens, c.settings), "NONE");
+        return { kind: "role", name, fields };
+    }
+    if (node.statement === "settingsProfile") {
+        put("settings", c.settings && settingsList(tokens, c.settings), "NONE");
+        put("to", c.to && nameList(tokens, c.to, ["ALL", "NONE", "EXCEPT"]), "NONE");
+        return { kind: "settingsProfile", name, fields };
+    }
+    if (node.statement === "quota") {
+        // `KEYED BY 'user_name'`, `KEYED BY client_key, user_name`, `KEYED BY ip_address IPV6_PREFIX_BITS 64`: unquoted, lower case.
+        if (c.keyed) {
+            const keys = topLevelParts(sigOf(tokens, c.keyed)).map((p) => p.map((t) => (t.kind === "string" ? stringText(t.text) : unquote(t.text)).toLowerCase()).join(" "));
+            put("keyed", keys.join(" , "));
+        }
+        if (c.for)
+            for (const [seconds, limits] of Object.entries(quotaIntervals(tokens, c.for)))
+                fields[`interval.${seconds}`] = limits;
+        put("to", c.to && nameList(tokens, c.to, ["ALL", "NONE", "EXCEPT"]), "NONE");
+        return { kind: "quota", name, fields };
+    }
+    const table = qualifiedName(tokens, node.table, defaultDatabase);
+    put("as", c.as && text(tokens, c.as).toUpperCase(), "PERMISSIVE");
+    put("for", c.for && join(sigOf(tokens, c.for), (w) => w.toUpperCase()), "SELECT");
+    put("using", text(tokens, c.using));
+    put("to", c.to && nameList(tokens, c.to, ["ALL", "NONE", "EXCEPT"]), "NONE");
+    return { kind: "rowPolicy", name, database: table.database, table: table.name, fields };
+}
+/** An atom's key, which is also how a plan prints it: `SELECT(a) ON shop.t`, `ROLE reader WITH ADMIN OPTION`. */
+export function atomKey(a) {
+    if (a.role !== undefined)
+        return `ROLE ${a.role}${a.option ? " WITH ADMIN OPTION" : ""}`;
+    return `${a.revoke ? "REVOKE " : ""}${a.privilege}${a.column !== undefined ? `(${a.column})` : ""} ON ${a.target}${a.option ? " WITH GRANT OPTION" : ""}`;
+}
+function grantAtoms(ddl, defaultDatabase) {
+    const out = [];
+    for (const statement of splitLines(ddl)) {
+        const tokens = tokenizeText(statement, 0);
+        const node = parseAccess(tokens);
+        if (node.statement !== "grant")
+            throw new Error(`not a grant: ${statement}`);
+        const grantees = node.grantees.map((g) => unquote(text(tokens, g) ?? ""));
+        const atoms = [];
+        let target;
+        if (node.target) {
+            const parts = sigOf(tokens, node.target)
+                .filter((t) => !(t.kind === "punct" && t.text === "."))
+                .map((t) => unquote(t.text));
+            target = parts.length >= 2 ? `${parts[0]}.${parts[1]}` : parts[0] === "*" ? "*" : `${defaultDatabase}.${parts[0]}`;
+        }
+        for (const item of node.items) {
+            const sig = sigOf(tokens, item);
+            if (!target) {
+                atoms.push({ role: unquote(text(tokens, item) ?? ""), ...(node.withOption === "ADMIN" ? { option: true } : {}) });
+                continue;
+            }
+            const open = sig.findIndex((t) => t.text === "(");
+            const words = (open < 0 ? sig : sig.slice(0, open)).map((t) => t.text.toUpperCase()).join(" ");
+            const columns = open < 0
+                ? [undefined]
+                : sig
+                    .slice(open + 1, -1)
+                    .filter((t) => !(t.kind === "punct" && t.text === ","))
+                    .map((t) => unquote(t.text));
+            for (const column of columns) {
+                atoms.push({ privilege: words, ...(column !== undefined ? { column } : {}), target, ...(node.withOption === "GRANT" ? { option: true } : {}), ...(node.revoke ? { revoke: true } : {}) });
+            }
+        }
+        out.push({ grantees, atoms });
+    }
+    return out;
+}
+/** Statements on their own lines, or separated by `;`, as `SHOW GRANTS` prints them and a group of declarations is joined. */
+function splitLines(ddl) {
+    return ddl
+        .split(/;\s*\n|\n(?=\s*(?:GRANT|REVOKE)\b)/i)
+        .map((s) => s.trim().replace(/;$/, ""))
+        .filter((s) => s.length > 0 && !/^--/.test(s));
+}
+/** Whether `outer` covers `inner`'s target: the same table, its database's `*`, or `*.*`. */
+function covers(outer, inner) {
+    if (outer === inner)
+        return true;
+    if (outer === "*.*")
+        return true;
+    const [db] = inner.split(".");
+    return outer === `${db}.*` && inner !== outer;
+}
+/**
+ * The atoms a grantee holds, with each atom another covers left out, as the
+ * server folds them: a column's privilege under the table's, a table's under
+ * its database's, any under `*.*`, the same privilege, with a grant option at
+ * least as wide.
+ */
+export function foldAtoms(atoms) {
+    const keyed = new Map(atoms.map((a) => [atomKey(a), a]));
+    const all = [...keyed.values()];
+    return all.filter((a) => a.role !== undefined ||
+        a.revoke ||
+        !all.some((b) => b !== a &&
+            !b.revoke &&
+            b.role === undefined &&
+            b.privilege === a.privilege &&
+            b.column === undefined &&
+            (b.option ?? false) >= (a.option ?? false) &&
+            covers(b.target, a.target) &&
+            (a.column !== undefined || b.target !== a.target)));
+}
+/** A grantee's grants as a plan compares them: each atom's key, mapped to the atom. */
+export function grantsCanonical(ddl, grantee, defaultDatabase = "default") {
+    const atoms = grantAtoms(ddl, defaultDatabase)
+        .filter((g) => g.grantees.includes(grantee))
+        .flatMap((g) => g.atoms);
+    return Object.fromEntries(foldAtoms(atoms)
+        .map((a) => [atomKey(a), JSON.stringify(a)])
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+}
+/** Every grantee a grant statement names. */
+export function granteesOf(ddl) {
+    return [...new Set(grantAtoms(ddl, "default").flatMap((g) => g.grantees))];
+}
+// ── statements ────────────────────────────────────────────────────────
+const ident = (name) => `\`${name.replace(/`/g, "``")}\``;
+const targetSql = (target) => target === "*" || target === "*.*"
+    ? target
+    : target
+        .split(".")
+        .map((p) => (p === "*" ? p : ident(p)))
+        .join(".");
+/** The statement that gives `grantee` one atom. */
+export function grantStatement(atom, grantee) {
+    if (atom.role !== undefined)
+        return `GRANT ${ident(atom.role)} TO ${ident(grantee)}${atom.option ? " WITH ADMIN OPTION" : ""}`;
+    const priv = `${atom.privilege}${atom.column !== undefined ? `(${ident(atom.column)})` : ""}`;
+    // Undoing a partial revoke grants the privilege back.
+    return `GRANT ${priv} ON ${targetSql(atom.target)} TO ${ident(grantee)}${atom.option && !atom.revoke ? " WITH GRANT OPTION" : ""}`;
+}
+/** The statement that takes one atom from `grantee`. */
+export function revokeStatement(atom, grantee) {
+    if (atom.role !== undefined)
+        return `REVOKE ${ident(atom.role)} FROM ${ident(grantee)}`;
+    const priv = `${atom.privilege}${atom.column !== undefined ? `(${ident(atom.column)})` : ""}`;
+    return `REVOKE ${priv} ON ${targetSql(atom.target)} FROM ${ident(grantee)}`;
+}
+/**
+ * The `ALTER` that sets one field of a user or role to its declared value,
+ * or back to the server's default when the declaration leaves it out.
+ */
+export function alterAccessField(kind, name, field, declared, declaredText) {
+    const head = `ALTER ${kind === "user" ? "USER" : "ROLE"} ${ident(name)}`;
+    const value = declaredText[field];
+    switch (field) {
+        case "identified":
+            return value === undefined || value === "NOT IDENTIFIED" ? `${head} NOT IDENTIFIED` : `${head} IDENTIFIED ${value}`;
+        case "host":
+            return `${head} HOST ${value ?? "ANY"}`;
+        case "validUntil":
+            return `${head} VALID UNTIL ${value ?? "'infinity'"}`;
+        case "defaultRole":
+            return `${head} DEFAULT ROLE ${value ?? "ALL"}`;
+        case "defaultDatabase":
+            return `${head} DEFAULT DATABASE ${value ?? "NONE"}`;
+        case "grantees":
+            return `${head} GRANTEES ${value ?? "ANY"}`;
+        case "settings":
+            return `${head} SETTINGS ${value ?? "NONE"}`;
+        default:
+            throw new Error(`no ALTER for ${kind} field ${field}`);
+    }
+}
+/**
+ * The `ALTER` that sets one field of a quota or settings profile to its
+ * declared value, or back to the server's default when the declaration
+ * leaves it out. Never `CREATE ... OR REPLACE`: that makes a new object
+ * under the name, and a profile that inherits the old one, or a quota's
+ * usage, is cut off from it.
+ *
+ * A quota's interval is set whole (`ALTER QUOTA q FOR INTERVAL 3600 second
+ * MAX queries = 5` replaces that interval's limits), and taken away with
+ * `NO LIMITS`.
+ */
+export function alterQuotaOrProfileField(kind, name, field, declared, declaredText) {
+    const head = `ALTER ${kind === "quota" ? "QUOTA" : "SETTINGS PROFILE"} ${ident(name)}`;
+    const interval = /^interval\.(\d+)$/.exec(field);
+    if (kind === "quota" && interval) {
+        const value = declared[field];
+        if (value === undefined)
+            return `${head} FOR INTERVAL ${interval[1]} second NO LIMITS`;
+        const randomized = value.startsWith("RANDOMIZED ");
+        const limits = (randomized ? value.slice("RANDOMIZED ".length) : value).replace(/ , /g, ", ");
+        return `${head} FOR ${randomized ? "RANDOMIZED " : ""}INTERVAL ${interval[1]} second ${limits}`;
+    }
+    if (kind === "quota" && field === "keyed")
+        return declaredText.keyed === undefined ? `${head} NOT KEYED` : `${head} KEYED BY ${declaredText.keyed}`;
+    if (field === "to")
+        return `${head} TO ${declaredText.to ?? "NONE"}`;
+    if (kind === "settingsProfile" && field === "settings")
+        return `${head} SETTINGS ${declaredText.settings ?? "NONE"}`;
+    throw new Error(`no ALTER for ${kind} field ${field}`);
+}
+/** A user's or role's clauses as written, by field, for the `ALTER` that sets one. */
+export function accessClauseText(ddl) {
+    const tokens = tokenizeText(ddl, 0);
+    const node = parseAccess(tokens);
+    const out = {};
+    for (const [key, span] of Object.entries(node.clauses)) {
+        if (!span)
+            continue;
+        out[key === "notIdentified" ? "identified" : key] = key === "notIdentified" ? "NOT IDENTIFIED" : text(tokens, span);
+    }
+    return out;
+}
+/**
+ * The grant declarations of a build, one entry per grantee they name: the
+ * export names that grant to it, their statements on their own lines, and
+ * what they depend on. A plan compares each entry with what the server
+ * holds for that grantee.
+ */
+export function grantsByGrantee(objects) {
+    const by = new Map();
+    for (const o of objects) {
+        if (o.type !== "ClickHouse::Grant")
+            continue;
+        for (const grantee of granteesOf(o.ddl)) {
+            const entry = by.get(grantee) ?? { exports: [], statements: [], dependsOn: new Set() };
+            entry.exports.push(o.export);
+            entry.statements.push(o.ddl.trim().replace(/;$/, ""));
+            for (const d of o.dependsOn ?? [])
+                entry.dependsOn.add(d);
+            by.set(grantee, entry);
+        }
+    }
+    return [...by].map(([grantee, e]) => ({ grantee, exports: e.exports, ddl: e.statements.join(";\n"), dependsOn: [...e.dependsOn] }));
+}