permdock 0.0.0 → 0.2.0

package/dist/rls-verify-D8B7dOTh.js

@@ -0,0 +1,745 @@
+import { _ as listPermissions, d as isEdgeRelation, f as isFieldRelation, i as findPermission, m as isPrincipalRelation } from "./permissions-DVoF6dMt.js";
+import { a as hasConditionOp } from "./refs-KYb4ntaz.js";
+import { _ as memoryRoleSource } from "./src-CSbUiozF.js";
+import { d as scopeList } from "./scopes-CVdPrWN-.js";
+import { g as customRoleScope, t as createPermDock, v as membershipsClaim } from "./permdock-CzqXjCpU.js";
+import { t as memoryRelations } from "./relations-cjOL01hZ.js";
+import { i as describeError, o as usageResult } from "./errors-CWfoNg9N.js";
+import { o as jsonSchemaOf, s as policyRowConditionKeys } from "./catalog-doc-Dsc9y7sd.js";
+import { a as loadModule, n as asPolicy, o as pickNamed } from "./load-DhWEB9P1.js";
+import "./budget-NbEtbJC_.js";
+import "./sources-B0UvrJ21.js";
+import { G as quoteLiteral, K as quoteTable, W as quoteIdent, y as columnTypesOf } from "./rls-shared-aOQ4hGTO.js";
+import { p as commandFor, s as viewName, t as FIELD_VIEWS, w as connectPg } from "./rls-fields-BMasREhR.js";
+import { a as HELPER_TABLE_POLICIES_SQL, d as rowConditionMessage, n as graphPlan, u as helperTablePoliciesFromRows } from "./rls-graph-pc9fuXYm.js";
+import { n as fixtureSubject, r as loadFixtures, t as fixtureRow } from "./fixtures-ht28Cplr.js";
+import { resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+//#region src/cli/rls-verify-tree.ts
+const SUBJECTS = 3;
+function tableSql(name) {
+	return quoteTable(name.includes(".") ? name : `public.${name}`);
+}
+function idFactory(node) {
+	const type = columnTypesOf(jsonSchemaOf(node))[node.id];
+	let next = 9e5;
+	return type === "numeric" ? () => {
+		next += 1;
+		return next;
+	} : () => randomUUID();
+}
+/**
+* Two spines one level deeper than the walk depth, so the depth cap is
+* crossed; side branches under the first levels alternate restricted, and
+* the second spine is restricted two levels down.
+*/
+function generateTree(node, depth) {
+	const id = idFactory(node);
+	const nodes = [];
+	for (const spine of [0, 1]) {
+		let parent = null;
+		for (let level = 0; level <= depth + 1; level += 1) {
+			const current = id();
+			nodes.push({
+				id: current,
+				parent,
+				restricted: node.restricted !== void 0 && spine === 1 && level === 2
+			});
+			if (spine === 0 && level >= 1 && level <= 3) {
+				const side = id();
+				nodes.push({
+					id: side,
+					parent: current,
+					restricted: node.restricted !== void 0 && level % 2 === 1
+				});
+				nodes.push({
+					id: id(),
+					parent: side,
+					restricted: false
+				});
+			}
+			parent = current;
+		}
+	}
+	return nodes;
+}
+function insertSql(table, rows) {
+	const columns = Object.keys(rows[0] ?? {});
+	const values = [];
+	const tuples = rows.map((row) => `(${columns.map((column) => {
+		values.push(row[column]);
+		return `$${String(values.length)}`;
+	}).join(", ")})`);
+	return {
+		sql: `insert into ${tableSql(table)} (${columns.map(quoteIdent).join(", ")}) values ${tuples.join(", ")} returning *`,
+		values
+	};
+}
+const REQUIRED_COLUMNS_SQL = `select a.attname as name,
+  format_type(a.atttypid, a.atttypmod) as type,
+  k.confrelid::regclass::text as "refTable",
+  r.attname as "refColumn",
+  (select e.enumlabel from pg_enum e where e.enumtypid = a.atttypid order by e.enumsortorder limit 1) as "enumLabel",
+  array(
+    select pg_get_constraintdef(c.oid) from pg_constraint c
+    where c.conrelid = a.attrelid and c.contype = 'c' and c.conkey = array[a.attnum]
+    order by c.conname
+  ) as checks
+from pg_attribute a
+left join pg_constraint k
+  on k.conrelid = a.attrelid and k.contype = 'f' and k.conkey = array[a.attnum]
+left join pg_attribute r
+  on r.attrelid = k.confrelid and r.attnum = k.confkey[1]
+where a.attrelid = $1::regclass and a.attnum > 0 and not a.attisdropped
+  and a.attnotnull and not a.atthasdef
+  and a.attidentity = '' and a.attgenerated = ''`;
+const UNIQUE_COLUMNS_SQL = `select distinct a.attname as name
+from pg_index i
+join pg_attribute a on a.attrelid = i.indrelid
+where i.indrelid = $1::regclass and i.indisunique
+  and a.attnum > 0 and not a.attisdropped
+  and (
+    a.attnum = any(i.indkey)
+    or exists (
+      select 1 from pg_depend d
+      where d.classid = 'pg_class'::regclass and d.objid = i.indexrelid
+        and d.refclassid = 'pg_class'::regclass and d.refobjid = i.indrelid
+        and d.refobjsubid = a.attnum
+    )
+  )`;
+function checkedValue(checks) {
+	for (const check of checks) {
+		const literal = /'((?:[^']|'')*)'/u.exec(check);
+		if (literal?.[1] !== void 0 && /[=]|\bin\b/iu.test(check)) return literal[1].replaceAll("''", "'");
+		const bound = /(>=?)\s*\(?(-?\d+(?:\.\d+)?)/u.exec(check);
+		if (bound?.[1] !== void 0 && bound[2] !== void 0) {
+			const value = Number(bound[2]);
+			return bound[1] === ">" ? Math.floor(value) + 1 : value;
+		}
+	}
+}
+function placeholder(column) {
+	if (column.enumLabel !== null) return column.enumLabel;
+	const checked = checkedValue(column.checks);
+	if (checked !== void 0) return checked;
+	const type = column.type;
+	if (type === "uuid") return randomUUID();
+	if (type === "boolean") return false;
+	if (/^(smallint|integer|bigint|numeric|real|double precision)/u.test(type)) return 0;
+	if (type.startsWith("timestamp") || type === "date") return (/* @__PURE__ */ new Date()).toISOString();
+	if (type === "json" || type === "jsonb") return {};
+	return "permdock-tree";
+}
+function distinctPlaceholder(column, index) {
+	const value = placeholder(column);
+	if (column.enumLabel !== null) return value;
+	if (typeof value === "number") return value + index;
+	if (typeof value !== "string" || checkedValue(column.checks) !== void 0) return value;
+	if (column.type === "uuid") return value;
+	if (column.type.startsWith("timestamp") || column.type === "date") return new Date(Date.parse(value) + index * 864e5).toISOString();
+	return `${value}-${String(index + 1)}`;
+}
+function asRequiredColumn(row) {
+	const { name, type, refTable, refColumn, enumLabel, checks } = row;
+	if (typeof name !== "string" || typeof type !== "string") return;
+	return {
+		name,
+		type,
+		refTable: typeof refTable === "string" ? refTable : null,
+		refColumn: typeof refColumn === "string" ? refColumn : null,
+		enumLabel: typeof enumLabel === "string" ? enumLabel : null,
+		checks: Array.isArray(checks) ? checks.filter((check) => typeof check === "string") : []
+	};
+}
+/**
+* Values for the required columns a generated row leaves out, such as a
+* tenant column or a name: an existing value of the referenced table for a
+* foreign key, a placeholder of the column's type otherwise.
+*/
+async function requiredValues(query, table, set) {
+	const columns = (await query(REQUIRED_COLUMNS_SQL, [table])).rows.map(asRequiredColumn).filter((column) => column !== void 0 && !set.has(column.name));
+	const unique = new Set(columns.length === 0 ? [] : (await query(UNIQUE_COLUMNS_SQL, [table])).rows.map((row) => String(row["name"])));
+	const values = {};
+	const distinct = [];
+	for (const column of columns) if (column.refTable !== null && column.refColumn !== null) {
+		const existing = await query(`select ${quoteIdent(column.refColumn)} as value from ${column.refTable} limit 1`);
+		values[column.name] = existing.rows[0]?.["value"] ?? null;
+	} else if (unique.has(column.name)) distinct.push(column);
+	else values[column.name] = placeholder(column);
+	return (index) => {
+		const row = { ...values };
+		for (const column of distinct) row[column.name] = distinctPlaceholder(column, index);
+		return row;
+	};
+}
+/** Inserts `rows` after filling the required columns they leave out. */
+async function seedRows(query, table, rows, given = {}) {
+	const fill = await requiredValues(query, tableSql(table), /* @__PURE__ */ new Set([...Object.keys(rows[0] ?? {}), ...Object.keys(given)]));
+	const inserted = insertSql(table, rows.map((row, index) => ({
+		...fill(index),
+		...given,
+		...row
+	})));
+	return (await query(inserted.sql, inserted.values)).rows;
+}
+/**
+* Parity between `decide` and RLS on a generated object graph: for every
+* self-parented resource a graph grant walks, a tree with restricted
+* branches and a chain past the walk depth, child rows under it, and edges
+* for a few generated principals. Everything runs in one transaction that
+* is rolled back.
+*/
+async function verifyTree(input) {
+	const { policy, query } = input;
+	const tables = input.config.rls?.tables;
+	const treeValues = input.config.rls?.treeValues ?? {};
+	const seed = (table, list) => seedRows(query, table, list, treeValues[table] ?? {});
+	const walked = [...graphPlan(policy).values()].filter((entry) => entry.closure !== void 0);
+	if (walked.length === 0) return {
+		checked: 0,
+		granted: 0,
+		mismatches: [],
+		notes: ["no graph grant walks a self-parented resource"]
+	};
+	const subjects = Array.from({ length: SUBJECTS }, () => randomUUID());
+	const rows = {};
+	const edges = {};
+	const now = Date.now();
+	for (const entry of walked) {
+		const node = entry.node;
+		const parent = node.parent;
+		if (parent === void 0) continue;
+		const tree = generateTree(node, entry.closure ?? 0);
+		const seeded = tree.map((item, index) => {
+			const row = {
+				[node.id]: item.id,
+				[parent.field]: item.parent
+			};
+			if (node.restricted !== void 0) row[node.restricted] = item.restricted;
+			for (const name of entry.relations) {
+				const spec = node.relations[name];
+				const column = isFieldRelation(spec) ? spec.memberOf === void 0 ? spec.field : void 0 : isPrincipalRelation(spec) ? spec.principal : void 0;
+				if (column !== void 0 && column !== parent.field) row[column] = index % 4 === 0 ? subjects[index % SUBJECTS] : randomUUID();
+			}
+			return row;
+		});
+		if ([...entry.relations].some((name) => {
+			const spec = node.relations[name];
+			return isPrincipalRelation(spec) && spec.principal === parent.field || isFieldRelation(spec) && spec.field === parent.field;
+		})) subjects.push(...tree.filter((_, index) => index % 3 === 0).map((item) => String(item.id)));
+		rows[node.name] = [...await seed(tables?.[node.name] ?? node.name, seeded)];
+		for (const name of entry.relations) {
+			const spec = node.relations[name];
+			if (!isEdgeRelation(spec)) continue;
+			const object = spec.object ?? `${node.name}_id`;
+			const subject = spec.subject ?? "user_id";
+			const list = [];
+			const edgeRows = [];
+			for (const [index, item] of tree.entries()) {
+				const holder = subjects[index % SUBJECTS];
+				if (holder === void 0 || index % 5 !== 1) continue;
+				const expiresAt = spec.expiresAt !== void 0 && index % 10 === 6 ? /* @__PURE__ */ new Date(now - 864e5) : void 0;
+				edgeRows.push({
+					[object]: item.id,
+					[subject]: holder,
+					...spec.expiresAt === void 0 ? {} : { [spec.expiresAt]: expiresAt ?? null }
+				});
+				list.push({
+					id: String(item.id),
+					principal: holder,
+					...expiresAt === void 0 ? {} : { expiresAt: expiresAt.getTime() / 1e3 }
+				});
+			}
+			if (edgeRows.length > 0) await seed(spec.edge, edgeRows);
+			edges[node.name] = {
+				...edges[node.name],
+				[name]: list
+			};
+		}
+		for (const child of policy.resources.values()) {
+			if (child.name === node.name || child.parent?.resource !== node.name) continue;
+			const make = idFactory(child);
+			const childRows = tree.map((item, index) => {
+				const row = {
+					[child.id]: make(),
+					[child.parent?.field ?? ""]: item.id
+				};
+				if (child.restricted !== void 0) row[child.restricted] = index % 7 === 3;
+				return row;
+			});
+			rows[child.name] = [...await seed(tables?.[child.name] ?? child.name, childRows)];
+		}
+	}
+	const relations = memoryRelations(policy.permissions, {
+		rows,
+		edges
+	});
+	const mismatches = [];
+	let checked = 0;
+	let granted = 0;
+	const reads = listPermissions(policy.permissions).filter((leaf) => leaf.kind === "instance" && commandFor(leaf.action, input.config.rls?.actions) === "select" && rows[leaf.resource] !== void 0);
+	for (const subject of subjects) {
+		const permdock = await createPermDock(policy, {
+			principal: {
+				id: subject,
+				roles: []
+			},
+			context: {}
+		}, { relations });
+		await input.bind(subject);
+		for (const permission of reads) {
+			const node = policy.resources.get(permission.resource);
+			const list = rows[permission.resource] ?? [];
+			if (node === void 0 || list.length === 0) continue;
+			const ids = list.map((row) => String(row[node.id]));
+			const visible = await query(`select ${quoteIdent(node.id)}::text as id from ${tableSql(tables?.[node.name] ?? node.name)} where ${quoteIdent(node.id)} = any($1)`, [ids]);
+			const seen = new Set(visible.rows.map((row) => String(row["id"])));
+			for (const row of list) {
+				checked += 1;
+				const id = String(row[node.id]);
+				const allowed = permdock.can(permission, row);
+				if (allowed !== seen.has(id)) mismatches.push(`${permission.key} ${id}: in-process ${allowed ? "granted" : "denied"}, database ${seen.has(id) ? "allowed" : "filtered"}`);
+				else if (allowed) granted += 1;
+			}
+		}
+	}
+	return {
+		checked,
+		granted,
+		mismatches,
+		notes: []
+	};
+}
+//#endregion
+//#region src/cli/rls-verify.ts
+function isRecord(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/** A custom role's scope and pinned instance, as the `custom_role_*` tables store them. */
+function customRoleAt(role, scopes) {
+	return {
+		scope: customRoleScope(role, scopes),
+		id: role.scope === void 0 ? role.team : role.id
+	};
+}
+function canFixture(permdock, permission, row) {
+	if (permission.kind === "collection") return permdock.can(permission, row);
+	return permdock.can(permission, row);
+}
+function grantKind(policy, key) {
+	const grants = policy.grants.filter((grant) => grant.permission.key === key);
+	if (grants.some((grant) => hasConditionOp(grant.where, "opaque") || hasConditionOp(grant.check, "opaque"))) return "opaque";
+	if (grants.some((grant) => hasConditionOp(grant.where, "sqlFunction") || hasConditionOp(grant.check, "sqlFunction"))) return "sqlFunction";
+	return "portable";
+}
+function columnsOf(row) {
+	return isRecord(row) ? Object.entries(row).filter(([, value]) => value !== void 0 && typeof value !== "object") : [];
+}
+/**
+* The statement a fixture runs: `create` inserts the whole row, `update` writes
+* `newRow` when given. Each reads back only the key, so `--revoke-columns`
+* (which keeps only unrestricted columns readable) does not reject it.
+*/
+function statementFor(fixture, action, table) {
+	const quoted = quoteTable(table);
+	const id = quoteIdent("id");
+	const key = rowId(fixture.row);
+	switch (action) {
+		case "read":
+		case "list":
+		case "get": return {
+			sql: `select ${id} from ${quoted} where ${id} = $1`,
+			values: [key]
+		};
+		case "update": {
+			const next = columnsOf(fixture.newRow).filter(([name]) => name !== "id");
+			return {
+				sql: `update ${quoted} set ${next.length === 0 ? `${id} = ${id}` : next.map(([name], index) => `${quoteIdent(name)} = $${index + 2}`).join(", ")} where ${id} = $1 returning ${id}`,
+				values: [key, ...next.map(([, value]) => value)]
+			};
+		}
+		case "create": {
+			const cols = columnsOf(fixture.row);
+			if (cols.length === 0) return {
+				sql: `insert into ${quoted} (${id}) values ($1) returning ${id}`,
+				values: [key]
+			};
+			return {
+				sql: `insert into ${quoted} (${cols.map(([name]) => quoteIdent(name)).join(", ")}) values (${cols.map((_, index) => `$${index + 1}`).join(", ")}) returning ${id}`,
+				values: cols.map(([, value]) => value)
+			};
+		}
+		case "delete": return {
+			sql: `delete from ${quoted} where ${id} = $1 returning ${id}`,
+			values: [key]
+		};
+		default: return {
+			sql: `select ${id} from ${quoted} where ${id} = $1`,
+			values: [key]
+		};
+	}
+}
+function rowId(row) {
+	if (isRecord(row) && "id" in row) return row["id"];
+}
+/** A fixture value as a SQL literal; untyped, so it coerces to the column like a bound parameter. */
+function sqlValue(value) {
+	if (value === null || value === void 0) return "null";
+	return quoteLiteral(typeof value === "string" ? value : JSON.stringify(value));
+}
+function inlineStatement(statement) {
+	return statement.sql.replaceAll(/\$(\d+)/gu, (_, index) => sqlValue(statement.values[Number(index) - 1]));
+}
+const PGTAP_DECISION = "pg_temp.permdock_decision";
+const PGTAP_DECISION_SQL = `create function ${PGTAP_DECISION}(statement text) returns text
+language plpgsql
+as $$
+declare
+  affected bigint;
+begin
+  execute statement;
+  get diagnostics affected = row_count;
+  return case when affected > 0 then 'granted' else 'denied' end;
+exception
+  when others then
+    return 'denied';
+end;
+$$;`;
+function subjectOf(config, customRoles, scopes) {
+	return {
+		dialect: config.rls?.dialect ?? "supabase",
+		gucPrefix: config.rls?.gucPrefix ?? "app",
+		tenantClaim: config.rls?.tenantClaim ?? "tenant_id",
+		roleClaim: config.rls?.roleClaim ?? "user_role",
+		customRoles,
+		scopes
+	};
+}
+/** The settings that bind a fixture's subject: the GUCs, or the Supabase JWT claims. */
+function subjectSettings(fixture, subject) {
+	const roles = fixture.subject.roles ?? [];
+	const memberships = membershipsClaim(fixture.subject.memberships ?? [], subject.customRoles, subject.scopes);
+	if (subject.dialect === "guc") {
+		const settings = [
+			[`${subject.gucPrefix}.user_id`, fixture.subject.id],
+			[`${subject.gucPrefix}.${subject.roleClaim}`, roles.join(",")],
+			[`${subject.gucPrefix}.memberships`, JSON.stringify(memberships)]
+		];
+		if (fixture.subject.tenant !== void 0) settings.push([`${subject.gucPrefix}.${subject.tenantClaim}`, fixture.subject.tenant]);
+		return settings;
+	}
+	const claims = {
+		...fixture.subject.claims,
+		sub: fixture.subject.id,
+		role: "authenticated",
+		[subject.roleClaim]: roles.length === 1 ? roles[0] : roles,
+		[subject.tenantClaim]: fixture.subject.tenant,
+		memberships
+	};
+	return [["request.jwt.claims", JSON.stringify(claims)]];
+}
+/** The `custom_role_*` rows for the fixtures' custom roles; existing rows are kept. */
+function customRoleRows(schema, customRoles, scopes) {
+	const table = (name) => `${quoteIdent(schema)}.${quoteIdent(name)}`;
+	const rows = [];
+	for (const role of customRoles) {
+		const at = customRoleAt(role, scopes);
+		if (at.scope === void 0) continue;
+		for (const grant of role.grants ?? []) rows.push({
+			sql: grant.level === void 0 ? `insert into ${table("custom_role_permissions")} (tenant_id, scope, scope_id, role, permission, effect) values ($1, $2, $3, $4, $5, $6) on conflict do nothing` : `insert into ${table("custom_role_permissions")} (tenant_id, scope, scope_id, role, permission, effect, level) values ($1, $2, $3, $4, $5, $6, $7) on conflict do nothing`,
+			values: [
+				role.tenant ?? null,
+				at.scope,
+				at.id ?? null,
+				role.name,
+				grant.permission,
+				grant.effect ?? "allow",
+				...grant.level === void 0 ? [] : [grant.level]
+			]
+		});
+		for (const name of role.includes ?? []) rows.push({
+			sql: `insert into ${table("custom_role_includes")} (tenant_id, scope, scope_id, role, include_role) values ($1, $2, $3, $4, $5) on conflict do nothing`,
+			values: [
+				role.tenant ?? null,
+				at.scope,
+				at.id ?? null,
+				role.name,
+				name
+			]
+		});
+	}
+	return rows;
+}
+function seedsCustomRoleTables(config) {
+	const rls = config.rls;
+	return rls?.customRoles === true && (rls.authorize ?? rls.rbac?.authorize ?? "jwt") === "database";
+}
+function customRoleSchema(config) {
+	return config.rls?.schema ?? config.rls?.rbac?.schema ?? "permdock";
+}
+/**
+* A pgTAP script that runs each fixture's statement under the fixture's
+* subject and asserts the outcome `can()` gave in-process.
+*/
+function emitPgtap(input) {
+	const scopes = scopeList(input.policy.scopes);
+	const subject = subjectOf(input.config, input.customRoles, scopes);
+	const lines = [
+		"begin;",
+		`select plan(${String(input.fixtures.length)});`,
+		PGTAP_DECISION_SQL
+	];
+	if (seedsCustomRoleTables(input.config)) for (const row of customRoleRows(customRoleSchema(input.config), input.customRoles, scopes)) lines.push(`${inlineStatement(row)};`);
+	for (const [index, fixture] of input.fixtures.entries()) {
+		const permission = findPermission(input.policy.permissions, fixture.action);
+		const status = input.inProcess[index];
+		const label = `fixture ${String(index)} ${fixture.action}`;
+		if (permission === void 0 || status === void 0) continue;
+		if (status.kind === "opaque") {
+			lines.push(`select skip(${quoteLiteral(`${label}: opaque grant untestable app-side`)}, 1);`);
+			continue;
+		}
+		const outcome = status.granted ? "granted" : "denied";
+		const table = input.config.rls?.tables?.[permission.resource] ?? permission.resource;
+		const statement = inlineStatement(statementFor(fixture, permission.action, table));
+		lines.push(`-- ${label}`, "savepoint permdock_fixture;", "set local role \"authenticated\";", ...subjectSettings(fixture, subject).map(([name, value]) => `select set_config(${quoteLiteral(name)}, ${quoteLiteral(value)}, true);`), `select is(${PGTAP_DECISION}(${quoteLiteral(statement)}), ${quoteLiteral(outcome)}, ${quoteLiteral(`${label} ${outcome}`)});`, "rollback to savepoint permdock_fixture;");
+	}
+	lines.push("select * from finish();", "rollback;");
+	return `${lines.join("\n")}\n`;
+}
+/** Columns of `row` that hold a value; a masked column reads as null. */
+function valuedColumns(row) {
+	return isRecord(row) ? Object.keys(row).filter((name) => row[name] !== null && row[name] !== void 0).toSorted() : [];
+}
+/**
+* What a field view returns for a row: nothing for a denied row, otherwise
+* `pick`'s columns with a value plus the key, which always passes through.
+*/
+function expectedFields(granted, picked, key, row) {
+	if (!granted) return [];
+	const kept = new Set(valuedColumns(picked));
+	if (isRecord(row) && row[key] !== null && row[key] !== void 0) kept.add(key);
+	return [...kept].toSorted();
+}
+function fieldsMismatch(fixture, want, seen) {
+	const kept = want.join(", ");
+	if (typeof seen === "string") return [`${fixture.action}: field view read failed (${seen}), pick keeps [${kept}]`];
+	return seen.join(", ") === kept ? [] : [`${fixture.action} ${String(rowId(fixture.row))}: field view returns [${seen.join(", ")}], pick keeps [${kept}]`];
+}
+/** The field view's columns for the fixture's row: the view, or the table itself when no grant limits its fields. */
+async function viewFields(query, table, key) {
+	const view = quoteTable(viewName(table, FIELD_VIEWS.view));
+	const id = quoteIdent("id");
+	await query("savepoint permdock_fields");
+	const result = await query(`select * from ${view} where ${id} = $1`, [key]);
+	if (result.code === void 0) return valuedColumns(result.rows[0]);
+	await query("rollback to savepoint permdock_fields");
+	if (result.code !== "42P01") return result.code;
+	const base = await query(`select * from ${quoteTable(table)} where ${id} = $1`, [key]);
+	return base.code ?? valuedColumns(base.rows[0]);
+}
+/** Writes the custom roles into the `database`-mode tables; the fixture transaction rolls them back. */
+async function seedCustomRoles(query, schema, customRoles, scopes) {
+	for (const row of customRoleRows(schema, customRoles, scopes)) {
+		const result = await query(row.sql, row.values);
+		if (result.code !== void 0) throw new Error(`PermDock CLI: rls verify --db could not seed custom roles (${result.code}); connect as a role that owns the custom_role_* tables`);
+	}
+}
+async function bindSubject(query, fixture, subject) {
+	await query("set local role \"authenticated\"");
+	for (const [name, value] of subjectSettings(fixture, subject)) await query("select set_config($1, $2, true)", [name, value]);
+}
+async function verifyAgainstDatabase(input) {
+	const client = await input.connect(input.db);
+	const seedsTables = seedsCustomRoleTables(input.config);
+	const schema = customRoleSchema(input.config);
+	const scopes = scopeList(input.policy.scopes);
+	const subject = subjectOf(input.config, input.customRoles, scopes);
+	const query = async (sql, values) => {
+		try {
+			const result = await client.query(sql, values === void 0 ? [] : [...values]);
+			return {
+				rows: result.rows,
+				rowCount: result.rowCount ?? result.rows.length
+			};
+		} catch (cause) {
+			const code = cause !== null && typeof cause === "object" && "code" in cause && typeof cause.code === "string" ? cause.code : void 0;
+			return {
+				rows: [],
+				rowCount: 0,
+				...code === void 0 ? {} : { code }
+			};
+		}
+	};
+	const mismatches = [];
+	const notes = [];
+	try {
+		const conditioned = policyRowConditionKeys(input.policy);
+		for (const found of helperTablePoliciesFromRows((await query(HELPER_TABLE_POLICIES_SQL)).rows)) {
+			const keys = found.keys.filter((key) => conditioned.has(key));
+			if (keys.length > 0) mismatches.push(`PD037 ${rowConditionMessage(found, keys)}`);
+		}
+		for (const [index, fixture] of input.fixtures.entries()) {
+			const permission = findPermission(input.policy.permissions, fixture.action);
+			const status = input.inProcess[index];
+			if (permission === void 0 || status === void 0) continue;
+			if (status.kind === "opaque") {
+				notes.push(`${fixture.action}: opaque grant untestable app-side`);
+				continue;
+			}
+			const table = input.config.rls?.tables?.[permission.resource] ?? permission.resource;
+			await query("begin");
+			try {
+				if (seedsTables) await seedCustomRoles(query, schema, input.customRoles, scopes);
+				await bindSubject(query, fixture, subject);
+				const statement = statementFor(fixture, permission.action, table);
+				const result = await query(statement.sql, statement.values);
+				const count = result.rowCount ?? result.rows.length;
+				const database = result.code === "42501" ? "rejected" : count > 0 ? "allowed" : "filtered";
+				if (!(status.granted ? database === "allowed" : database === "filtered" || database === "rejected")) mismatches.push(`${fixture.action}: in-process ${status.granted ? "granted" : "denied"}, database ${database}`);
+				else if (status.kind === "sqlFunction") notes.push(`${fixture.action}: verified through twin`);
+				mismatches.push(...status.fields === void 0 ? [] : fieldsMismatch(fixture, status.fields, await viewFields(query, table, rowId(fixture.row))));
+			} finally {
+				await query("rollback");
+			}
+		}
+	} finally {
+		await client.end();
+	}
+	return {
+		mismatches,
+		notes
+	};
+}
+/** `--tree`: seeds a generated object graph in a rolled-back transaction and compares `can()` with RLS. */
+async function verifyTreeAgainstDatabase(db, policy, config, connect) {
+	const client = await connect(db);
+	const scopes = scopeList(policy.scopes);
+	const query = async (sql, values) => {
+		return { rows: (await client.query(sql, values === void 0 ? [] : [...values])).rows };
+	};
+	const loose = async (sql, values) => {
+		await query(sql, values);
+		return { rows: [] };
+	};
+	try {
+		await query("begin");
+		const result = await verifyTree({
+			policy,
+			config,
+			query,
+			bind: (subject) => bindSubject(loose, {
+				subject: { id: subject },
+				row: {},
+				action: "read"
+			}, subjectOf(config, [], scopes))
+		});
+		if (result.mismatches.length > 0) return {
+			code: 1,
+			output: [...result.mismatches, ...result.notes].join("\n")
+		};
+		const verified = `verified ${String(result.checked)} tree check(s) against the database (${String(result.granted)} granted)`;
+		return {
+			code: 0,
+			output: result.notes.length === 0 ? verified : `${verified}\n${result.notes.join("\n")}`
+		};
+	} catch (cause) {
+		return {
+			code: 2,
+			output: `PermDock CLI: rls verify --tree could not seed the tree (${describeError(cause)}); connect as a role that owns the tables and is a member of authenticated`
+		};
+	} finally {
+		await client.query("rollback", []).catch(() => void 0);
+		await client.end();
+	}
+}
+async function runRlsVerify(input) {
+	const connect = input.connect ?? ((db) => connectPg(db, "permdock rls verify --db"));
+	const policyPath = input.from ?? input.config.policy;
+	if (policyPath === void 0) return {
+		code: 2,
+		output: "PermDock CLI: rls verify needs policy in the config or --from"
+	};
+	const policy = asPolicy(pickNamed(await loadModule(resolve(input.cwd, policyPath)), ["policy"]));
+	if (input.tree === true) {
+		if (input.db === void 0) return {
+			code: 2,
+			output: "PermDock CLI: rls verify --tree needs --db"
+		};
+		try {
+			return await verifyTreeAgainstDatabase(input.db, policy, input.config, connect);
+		} catch (cause) {
+			return usageResult(cause);
+		}
+	}
+	const fixturesPath = input.fixtures ?? input.config.rls?.fixtures ?? "rls.fixtures.json";
+	const { fixtures, customRoles } = await loadFixtures(input.cwd, fixturesPath);
+	const mismatches = [];
+	const notes = [];
+	const inProcess = [];
+	const fieldsMode = input.config.rls?.fields === "views";
+	for (const fixture of fixtures) {
+		const permission = findPermission(policy.permissions, fixture.action);
+		if (permission === void 0) {
+			mismatches.push(`${fixture.action}: unknown permission`);
+			inProcess.push({
+				action: fixture.action,
+				granted: false,
+				kind: "portable"
+			});
+			continue;
+		}
+		const kind = grantKind(policy, fixture.action);
+		const permdock = await createPermDock(policy, fixtureSubject(fixture.subject), { customRoles: memoryRoleSource(customRoles) });
+		const granted = canFixture(permdock, permission, fixtureRow(fixture, permission.kind));
+		const outcome = granted ? "granted" : "denied";
+		if (fixture.expected !== void 0 && fixture.expected !== outcome) mismatches.push(`${fixture.action}: in-process ${outcome}, expected ${fixture.expected}`);
+		if (kind === "opaque") notes.push(`${fixture.action}: opaque grant untestable app-side`);
+		const fields = fieldsMode && permission.kind === "instance" && commandFor(permission.action, input.config.rls?.actions) === "select" ? expectedFields(granted, permdock.pick(permission, fixture.row), policy.resources.get(permission.resource)?.id ?? "id", fixture.row) : void 0;
+		inProcess.push({
+			action: fixture.action,
+			granted,
+			kind,
+			...fields === void 0 ? {} : { fields }
+		});
+	}
+	if (input.format === "pgtap") return mismatches.length > 0 ? {
+		code: 1,
+		output: mismatches.join("\n")
+	} : {
+		code: 0,
+		output: emitPgtap({
+			fixtures,
+			inProcess,
+			policy,
+			config: input.config,
+			customRoles
+		})
+	};
+	if (input.db !== void 0) try {
+		const database = await verifyAgainstDatabase({
+			db: input.db,
+			policy,
+			fixtures,
+			customRoles,
+			config: input.config,
+			inProcess,
+			connect
+		});
+		mismatches.push(...database.mismatches);
+		notes.push(...database.notes);
+	} catch (cause) {
+		return usageResult(cause);
+	}
+	if (mismatches.length > 0) return {
+		code: 1,
+		output: [...mismatches, ...notes].join("\n")
+	};
+	const verified = `verified ${String(fixtures.length)} fixture(s) ${input.db === void 0 ? "in-process" : "in-process and against the database"}`;
+	return {
+		code: 0,
+		output: notes.length === 0 ? verified : `${verified}\n${notes.join("\n")}`
+	};
+}
+//#endregion
+export { runRlsVerify as n, canFixture as t };