permdock 0.6.0 → 0.8.0

package/dist/core-H-mbhpZc.js

@@ -0,0 +1,341 @@
+import { A as memoryCustomRoleSource } from "./src-DZ0l9UAg.js";
+import { c as listPermissions } from "./permission-registry-B8tYxPIt.js";
+import { f as scopeList } from "./scopes-0Up_UA2t.js";
+import { y as membershipsClaim } from "./evaluate-Dd8Ta0Ie.js";
+import { n as parseSnapshot } from "./snapshot-CXlzi69u.js";
+import { n as fromSnapshot } from "./from-snapshot-DCakWRsr.js";
+import { t as getPermDock } from "./permdock-L-_I_3zP.js";
+import { c as quoteSqlTable, n as defaultSqlCommand, o as quoteSqlIdent, t as SQL_IDENT } from "./sql-0WjxIp9g.js";
+import "./budget-BELja5A9.js";
+//#region src/testing/policy-matrix.ts
+function isOutcomeCell(value) {
+	return value === "granted" || value === "denied" || value === "approval-required" || value !== null && typeof value === "object" && ("denials" in value || "outcome" in value || "alternatives" in value || "obligations" in value || "deniedBy" in value);
+}
+function expectedOutcome(cell) {
+	return typeof cell === "string" ? cell : cell.outcome ?? "denied";
+}
+function same(left, right) {
+	return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function list(values) {
+	return `[${values.join(", ")}]`;
+}
+function decisionFailures(decision, cell) {
+	const expected = expectedOutcome(cell);
+	if (decision.outcome !== expected) return [`expected ${expected}, got ${decision.outcome}`];
+	if (typeof cell !== "object") return [];
+	const failures = [];
+	if (cell.denials !== void 0 && decision.outcome === "denied") {
+		for (const denial of cell.denials) if (!decision.denials.some((item) => item.reason === denial.reason && (denial.role === void 0 || item.role === denial.role))) failures.push(`no denial ${denial.reason}${denial.role === void 0 ? "" : ` for role ${String(denial.role)}`}; got ${list(decision.denials.map((item) => `${item.reason}${item.role === null ? "" : `@${item.role}`}`))}`);
+	}
+	if (cell.alternatives !== void 0 && decision.outcome === "denied") {
+		const actual = decision.alternatives.map((leaf) => leaf.key);
+		if (!same(actual, cell.alternatives)) failures.push(`alternatives: expected ${list(cell.alternatives)}, got ${list(actual)}`);
+	}
+	if (cell.obligations !== void 0 && decision.outcome === "granted") {
+		const actual = (decision.obligations ?? []).map((item) => item.kind);
+		if (!same(actual, cell.obligations)) failures.push(`obligations: expected ${list(cell.obligations)}, got ${list(actual)}`);
+	}
+	return failures;
+}
+/**
+* `deniedBy`, against the trace of a fresh `explain` call for the same
+* arguments.
+*/
+function deniedByFailures(instance, permission, data, cell) {
+	if (typeof cell !== "object" || cell.deniedBy === void 0) return [];
+	const explained = instance.explain(permission, data);
+	const winner = explained.trace.denies[0]?.name;
+	if (explained.outcome !== "denied" || winner !== cell.deniedBy) return [`deniedBy: expected ${cell.deniedBy}, explain answered ${explained.outcome}${winner === void 0 ? "" : ` by ${winner}`}`];
+	return [];
+}
+function snapshotFailures(instance, permission, data, cell) {
+	const outcome = expectedOutcome(cell);
+	if (outcome === "approval-required") return [];
+	return fromSnapshot(JSON.parse(JSON.stringify(instance.snapshot()))).can(permission, data) === (outcome === "granted") ? [] : ["snapshot client disagrees with the server"];
+}
+/** The cells `config.matrix` names, in matrix order, before any decision. */
+function pendingCells(policy, config) {
+	const cells = [];
+	for (const permission of listPermissions(policy.permissions)) {
+		const spec = config.matrix[permission.key];
+		if (spec === void 0) continue;
+		if (!Object.values(spec).some((value) => !isOutcomeCell(value))) {
+			const data = permission.kind === "instance" ? Object.values(config.fixtures ?? {})[0] : void 0;
+			for (const [subject, cell] of Object.entries(spec)) cells.push({
+				name: `${permission.key} / ${subject}`,
+				permission,
+				subject,
+				data,
+				expected: cell
+			});
+			continue;
+		}
+		for (const [fixture, row] of Object.entries(spec)) {
+			if (isOutcomeCell(row)) continue;
+			for (const [subject, cell] of Object.entries(row)) cells.push({
+				name: `${permission.key} / ${fixture} / ${subject}`,
+				permission,
+				subject,
+				fixture,
+				data: config.fixtures?.[fixture],
+				expected: cell
+			});
+		}
+	}
+	return cells;
+}
+/**
+* Where each cell sits, without deciding it: a test runner registers one test
+* per cell.
+*/
+function policyMatrixLayout(policy, config) {
+	return pendingCells(policy, config).map((cell) => cell.fixture === void 0 ? {
+		name: cell.name,
+		permission: cell.permission.key,
+		subject: cell.subject
+	} : {
+		name: cell.name,
+		permission: cell.permission.key,
+		subject: cell.subject,
+		fixture: cell.fixture
+	});
+}
+/**
+* Decides every cell of a policy matrix with no test runner: each cell lists
+* its `failures`, and `missing` names the permissions an exhaustive matrix
+* leaves out. `describePolicy` asserts the same report under Vitest.
+*/
+async function policyMatrix(policy, config) {
+	const instances = /* @__PURE__ */ new Map();
+	for (const [name, user] of Object.entries(config.subjects)) instances.set(name, await getPermDock(policy, user, config.options));
+	const cells = [];
+	for (const pending of pendingCells(policy, config)) {
+		const instance = instances.get(pending.subject) ?? await getPermDock(policy, config.subjects[pending.subject], config.options);
+		const decision = instance.decide(pending.permission, pending.data);
+		const failures = [
+			...decisionFailures(decision, pending.expected),
+			...deniedByFailures(instance, pending.permission, pending.data, pending.expected),
+			...config.snapshot === true ? snapshotFailures(instance, pending.permission, pending.data, pending.expected) : []
+		];
+		cells.push({
+			name: pending.name,
+			permission: pending.permission.key,
+			subject: pending.subject,
+			...pending.fixture === void 0 ? {} : { fixture: pending.fixture },
+			expected: pending.expected,
+			actual: decision.outcome,
+			decision,
+			failures
+		});
+	}
+	return {
+		cells,
+		missing: config.exhaustive === false ? [] : listPermissions(policy.permissions).map((permission) => permission.key).filter((key) => config.matrix[key] === void 0)
+	};
+}
+//#endregion
+//#region src/testing/rls-parity.ts
+function toSubject(input) {
+	return {
+		principal: {
+			id: input.id,
+			roles: input.roles ?? [],
+			...input.tenant === void 0 ? {} : { tenant: input.tenant },
+			memberships: input.memberships ?? [],
+			...input.claims === void 0 ? {} : { claims: input.claims }
+		},
+		context: {}
+	};
+}
+function rowId(row) {
+	return row["id"];
+}
+function setting(name, value) {
+	return {
+		sql: "select set_config($1, $2, true)",
+		values: [name, value]
+	};
+}
+/**
+* The session state the generated helpers read: JWT claims for `supabase`, GUCs
+* for `guc` (roles as a comma list, memberships as JSON).
+*/
+function subjectSettings(dialect, subject, gucPrefix, tenantClaim, roleClaim, customRoles, scopes) {
+	const roles = subject.roles ?? [];
+	const memberships = membershipsClaim(subject.memberships ?? [], customRoles, scopes);
+	if (dialect === "supabase" || dialect === "neon") {
+		const claims = {
+			...subject.claims,
+			sub: subject.id,
+			role: "authenticated",
+			[roleClaim]: roles.length === 1 ? roles[0] : roles,
+			[tenantClaim]: subject.tenant,
+			memberships
+		};
+		return [setting("request.jwt.claims", JSON.stringify(claims))];
+	}
+	const settings = [
+		...Object.entries(subject.claims ?? {}).map(([name, value]) => {
+			if (!SQL_IDENT.test(name)) throw new Error(`PermDock: unsafe claim name '${name}'`);
+			return setting(`${gucPrefix}.${name}`, typeof value === "string" ? value : JSON.stringify(value));
+		}),
+		setting(`${gucPrefix}.user_id`, subject.id),
+		setting(`${gucPrefix}.${roleClaim}`, roles.join(",")),
+		setting(`${gucPrefix}.memberships`, JSON.stringify(memberships))
+	];
+	return subject.tenant === void 0 ? settings : [...settings, setting(`${gucPrefix}.${tenantClaim}`, subject.tenant)];
+}
+/**
+* The statement a case runs. With field views it reads back only the key, so a
+* base table whose restricted columns are revoked does not reject it.
+*/
+function statementSql(action, table, keyOnly) {
+	const quoted = quoteSqlTable(table);
+	const id = quoteSqlIdent("id");
+	const back = keyOnly ? id : "*";
+	const command = defaultSqlCommand(action) ?? "select";
+	switch (command) {
+		case "select": return `select ${back} from ${quoted} where ${id} = $1`;
+		case "update": return `update ${quoted} set ${id} = ${id} where ${id} = $1 returning ${back}`;
+		case "insert": return `insert into ${quoted} (${id}) values ($1) returning ${back}`;
+		case "delete": return `delete from ${quoted} where ${id} = $1 returning ${back}`;
+		default: return command;
+	}
+}
+function valued(row) {
+	if (row === null || typeof row !== "object") return [];
+	const record = row;
+	return Object.keys(record).filter((name) => record[name] !== null && record[name] !== void 0).toSorted();
+}
+function isRead(action) {
+	return action === "read" || action === "get" || action === "list";
+}
+async function viewColumns(query, table, key) {
+	const id = quoteSqlIdent("id");
+	await query("savepoint permdock_fields");
+	const view = await query(`select * from ${quoteSqlTable(`${table}_visible`)} where ${id} = $1`, [key]);
+	if (view.code === void 0) return valued(view.rows[0]);
+	await query("rollback to savepoint permdock_fields");
+	if (view.code !== "42P01") return view.code;
+	const base = await query(`select * from ${quoteSqlTable(table)} where ${id} = $1`, [key]);
+	return base.code ?? valued(base.rows[0]);
+}
+function dbOutcome(result) {
+	if (result.code === "42501") return "rejected";
+	return (result.rowCount ?? result.rows.length) > 0 ? "allowed" : "filtered";
+}
+async function testRlsParity(policy, options) {
+	const dialect = options.dialect ?? "guc";
+	const gucPrefix = options.gucPrefix ?? "app";
+	const tenantClaim = options.tenantClaim ?? "tenant_id";
+	const roleClaim = options.roleClaim ?? "user_role";
+	const role = options.role ?? "authenticated";
+	const customRoles = options.customRoles ?? [];
+	const scopes = scopeList(policy.scopes);
+	async function runCase(fixture) {
+		const permdock = await getPermDock(policy, toSubject(fixture.subject), { customRoles: memoryCustomRoleSource(customRoles) });
+		const granted = fixture.permission.kind === "collection" ? permdock.can(fixture.permission, fixture.row) : permdock.can(fixture.permission, fixture.row);
+		let fromClient;
+		if (options.snapshot === true) {
+			const snapshot = permdock.snapshot();
+			if (typeof snapshot !== "object" || snapshot instanceof Promise) throw new TypeError("PermDock: testRlsParity needs an unsigned snapshot");
+			fromClient = fromSnapshot(parseSnapshot(JSON.stringify(snapshot))).can(fixture.permission, fixture.row);
+		}
+		await options.query("begin");
+		try {
+			await options.query(`set local role ${quoteSqlIdent(role === "anon" && dialect === "neon" ? "anonymous" : role)}`);
+			for (const item of subjectSettings(dialect, fixture.subject, gucPrefix, tenantClaim, roleClaim, customRoles, scopes)) await options.query(item.sql, item.values);
+			const database = dbOutcome(await options.query(statementSql(fixture.permission.action, fixture.table, options.fieldViews === true), [rowId(fixture.row)]));
+			const agrees = granted ? database === "allowed" : database === "filtered" || database === "rejected";
+			let fields;
+			if (options.fieldViews === true && fixture.permission.kind === "instance" && isRead(fixture.permission.action)) {
+				const key = policy.resources.get(fixture.permission.resource)?.id ?? "id";
+				const kept = new Set(granted ? valued(permdock.pick(fixture.permission, fixture.row)) : []);
+				if (granted && fixture.row[key] !== null && fixture.row[key] !== void 0) kept.add(key);
+				fields = {
+					app: [...kept].toSorted(),
+					database: await viewColumns(options.query, fixture.table, rowId(fixture.row))
+				};
+			}
+			const fieldsOk = fields === void 0 || typeof fields.database !== "string" && fields.database.join("\0") === fields.app.join("\0");
+			const ok = agrees && fieldsOk && (fromClient === void 0 || fromClient === granted);
+			return {
+				name: fixture.name,
+				granted,
+				database,
+				...fromClient === void 0 ? {} : { snapshot: fromClient },
+				...fields === void 0 ? {} : { fields },
+				ok
+			};
+		} finally {
+			await options.query("rollback");
+		}
+	}
+	async function runAll(remaining, acc) {
+		const [head, ...tail] = remaining;
+		if (head === void 0) return acc;
+		return runAll(tail, [...acc, await runCase(head)]);
+	}
+	const results = await runAll(options.fixtures, []);
+	return {
+		ok: results.every((item) => item.ok),
+		results
+	};
+}
+//#endregion
+//#region src/testing/orm-parity.ts
+function sortedIds(values) {
+	return values.map(String).toSorted();
+}
+function subsetOf(small, large) {
+	return small.every((value) => large.includes(value));
+}
+/**
+* ORM parity: for each scenario, the rows `permdock.filter()` keeps in memory
+* must be exactly the rows the database returns for
+* `toWhere(permdock.where())`. With a `relations` option, the graph is loaded
+* for the rows first, so the in-memory side walks the same graph the database
+* query does. A partial `where()` (a closure grant it cannot compile) may be
+* refused or return fewer rows, never more.
+*/
+async function testOrmParity(policy, scenarios, options) {
+	const idField = options.id ?? "id";
+	async function runCase(scenario) {
+		const permdock = await getPermDock(policy, scenario.user, scenario.options);
+		if (scenario.options?.relations !== void 0) await permdock.prefetchRelations(scenario.permission, scenario.rows);
+		const expected = sortedIds(permdock.filter(scenario.permission, scenario.rows).map((row) => row[idField]));
+		const where = permdock.where(scenario.permission);
+		try {
+			const actual = sortedIds(await options.run({
+				scenario,
+				where
+			}));
+			const ok = where.partial ? subsetOf(actual, expected) : actual.length === expected.length && subsetOf(actual, expected);
+			return {
+				name: scenario.name,
+				expected,
+				actual,
+				partial: where.partial,
+				ok
+			};
+		} catch (error) {
+			return {
+				name: scenario.name,
+				expected,
+				actual: [],
+				partial: where.partial,
+				error: error instanceof Error ? error.message : String(error),
+				ok: where.partial
+			};
+		}
+	}
+	const results = [];
+	for (const scenario of scenarios) results.push(await runCase(scenario));
+	return {
+		ok: results.every((item) => item.ok),
+		results
+	};
+}
+//#endregion
+export { policyMatrixLayout as i, testRlsParity as n, policyMatrix as r, testOrmParity as t };

package/dist/core-hWIARPDz.d.ts

@@ -0,0 +1,206 @@
+import { Ln as Decision, T as Policy, or as Membership, tr as CustomRole } from "./policy-types-CCiDRZBH.js";
+import { u as Permission } from "./permission-types-CAY-GU7e.js";
+import { f as WhereResult, o as PermDockOptions } from "./permdock-B6Sf4T_S.js";
+//#region src/testing/policy-matrix.d.ts
+type MatrixOutcome = "granted" | "denied" | "approval-required";
+type MatrixCell = MatrixOutcome | {
+  readonly outcome?: MatrixOutcome;
+  readonly denials?: readonly {
+    readonly role?: string | null;
+    readonly reason: string;
+  }[];
+  readonly alternatives?: readonly string[];
+  /**
+   * Obligation kinds a granted decision carries, in order; `[]` asserts
+   * none.
+   */
+  readonly obligations?: readonly string[];
+  /** The `name` of the deny grant `explain` reports as the one that won. */
+  readonly deniedBy?: string;
+};
+type DescribePolicyConfig<TSubject> = {
+  readonly subjects: Record<string, TSubject>;
+  readonly fixtures?: Record<string, unknown>;
+  readonly matrix: Record<string, Record<string, MatrixCell | Record<string, MatrixCell>>>;
+  readonly exhaustive?: boolean;
+  readonly options?: PermDockOptions;
+  /**
+   * Also assert every granted or denied cell against
+   * `fromSnapshot(permdock.snapshot())`, the client a Server Component hands
+   * down. Closures cannot cross a snapshot and deny on the client.
+   */
+  readonly snapshot?: boolean;
+};
+/** One cell of the matrix, decided. */
+type PolicyMatrixCell = {
+  /**
+   * `<permission> / <subject>`, or `<permission> / <fixture> / <subject>` for a
+   * nested row.
+   */
+  readonly name: string;
+  readonly permission: string;
+  readonly subject: string;
+  readonly fixture?: string;
+  readonly expected: MatrixCell;
+  readonly actual: MatrixOutcome;
+  readonly decision: Decision;
+  /** Each way the decision differs from `expected`; empty when the cell holds. */
+  readonly failures: readonly string[];
+};
+type PolicyMatrixReport = {
+  readonly cells: readonly PolicyMatrixCell[];
+  /** Permission keys the matrix has no row for; empty with `exhaustive: false`. */
+  readonly missing: readonly string[];
+};
+/**
+ * Decides every cell of a policy matrix with no test runner: each cell lists
+ * its `failures`, and `missing` names the permissions an exhaustive matrix
+ * leaves out. `describePolicy` asserts the same report under Vitest.
+ */
+declare function policyMatrix<TSubject>(policy: Policy, config: DescribePolicyConfig<TSubject>): Promise<PolicyMatrixReport>;
+//#endregion
+//#region src/testing/rls-parity.d.ts
+type RlsDbOutcome = "allowed" | "filtered" | "rejected";
+type RlsParitySubject = {
+  readonly id: string;
+  readonly roles?: readonly string[];
+  readonly tenant?: string;
+  readonly memberships?: readonly Membership[];
+  /**
+   * Extra token claims, read in memory as `principal.claims.*`. They join the
+   * JWT claims (`supabase`, `neon`); under `guc` each top-level claim is its
+   * own `<prefix>.<name>` setting, strings as is and anything else as JSON.
+   */
+  readonly claims?: Readonly<Record<string, unknown>>;
+};
+type RlsParityFixture = {
+  readonly name: string;
+  readonly subject: RlsParitySubject;
+  readonly permission: Permission;
+  readonly row: Readonly<Record<string, unknown>>;
+  readonly table: string;
+};
+type RlsQueryResult = {
+  readonly rows: readonly Record<string, unknown>[];
+  readonly rowCount?: number;
+  readonly code?: string;
+};
+type RlsQueryFn = (sql: string, values?: readonly unknown[]) => Promise<RlsQueryResult>;
+type RlsParityOptions = {
+  readonly query: RlsQueryFn;
+  readonly fixtures: readonly RlsParityFixture[];
+  /**
+   * `supabase` and `neon` set `request.jwt.claims`; a test database stubs
+   * `auth.jwt()` / `auth.uid()` or `auth.session()` / `auth.user_id()` over
+   * it.
+   */
+  readonly dialect?: "supabase" | "neon" | "guc";
+  readonly gucPrefix?: string;
+  readonly tenantClaim?: string;
+  /**
+   * Claim (or `guc` setting) the RLS helpers read global roles from. Default
+   * `user_role`.
+   */
+  readonly roleClaim?: string;
+  readonly role?: "authenticated" | "anon";
+  /**
+   * Tenant-defined roles the subjects' memberships may hold. `decide` resolves
+   * them through a `CustomRoleSource`; each membership's claim carries them as
+   * the compact `grants` map, which the helpers read in `jwt` mode. Seeding the
+   * `database`-mode tables is the caller's job.
+   */
+  readonly customRoles?: readonly CustomRole[];
+  /**
+   * Also decide each case from the subject's serialized snapshot
+   * (`fromSnapshot`); it must agree.
+   */
+  readonly snapshot?: boolean;
+  /**
+   * With `rls generate --fields views`: for each instance read, the row of
+   * `<table>_visible` must hold exactly the columns `pick` keeps (plus the key,
+   * which always passes through). A table with no view is read directly.
+   */
+  readonly fieldViews?: boolean;
+};
+/** Columns with a value in the view's row and in `pick`'s result, sorted. */
+type RlsFieldsOutcome = {
+  readonly app: readonly string[];
+  readonly database: readonly string[] | string;
+};
+type RlsParityCase = {
+  readonly name: string;
+  readonly granted: boolean;
+  readonly database: RlsDbOutcome;
+  /** The snapshot's decision, with `snapshot: true`. */
+  readonly snapshot?: boolean;
+  /**
+   * The field view check, with `fieldViews: true`; `database` is an error code
+   * when the read failed.
+   */
+  readonly fields?: RlsFieldsOutcome;
+  readonly ok: boolean;
+};
+type RlsParityReport = {
+  readonly ok: boolean;
+  readonly results: readonly RlsParityCase[];
+};
+declare function testRlsParity<TUser>(policy: Policy<TUser>, options: RlsParityOptions): Promise<RlsParityReport>;
+//#endregion
+//#region src/testing/orm-parity.d.ts
+type OrmParityScenario<TUser = unknown> = {
+  readonly name: string;
+  /**
+   * What the policy's `subject` mapper receives, as in `createPermDock(policy,
+   * user)`.
+   */
+  readonly user: TUser;
+  /**
+   * The active tenant and role sources, as in `createPermDock(policy, user,
+   * options)`.
+   */
+  readonly options?: PermDockOptions;
+  /** An instance permission; its `where()` filters the table. */
+  readonly permission: Permission<string, unknown, "instance">;
+  /** Every row of the table, exactly as the database holds them. */
+  readonly rows: readonly Readonly<Record<string, unknown>>[];
+};
+type OrmParityRunInput<TUser = unknown> = {
+  readonly scenario: OrmParityScenario<TUser>;
+  readonly where: WhereResult;
+};
+type OrmParityOptions<TUser = unknown> = {
+  /**
+   * Runs `toWhere(where)` against the database and returns the matching row
+   * ids.
+   */
+  readonly run: (input: OrmParityRunInput<TUser>) => Promise<readonly unknown[]>;
+  /** The row id field; default `id`. */
+  readonly id?: string;
+};
+type OrmParityCase = {
+  readonly name: string;
+  readonly expected: readonly string[];
+  readonly actual: readonly string[];
+  /**
+   * `where()` left out a non-portable grant. `toWhere` refusing it is
+   * fail-closed and passes; rows it does return must be a subset.
+   */
+  readonly partial: boolean;
+  readonly error?: string;
+  readonly ok: boolean;
+};
+type OrmParityReport = {
+  readonly ok: boolean;
+  readonly results: readonly OrmParityCase[];
+};
+/**
+ * ORM parity: for each scenario, the rows `permdock.filter()` keeps in memory
+ * must be exactly the rows the database returns for
+ * `toWhere(permdock.where())`. With a `relations` option, the graph is loaded
+ * for the rows first, so the in-memory side walks the same graph the database
+ * query does. A partial `where()` (a closure grant it cannot compile) may be
+ * refused or return fewer rows, never more.
+ */
+declare function testOrmParity<TUser>(policy: Policy<TUser>, scenarios: readonly OrmParityScenario<TUser>[], options: OrmParityOptions<TUser>): Promise<OrmParityReport>;
+//#endregion
+export { policyMatrix as S, DescribePolicyConfig as _, OrmParityScenario as a, PolicyMatrixCell as b, RlsFieldsOutcome as c, RlsParityOptions as d, RlsParityReport as f, testRlsParity as g, RlsQueryResult as h, OrmParityRunInput as i, RlsParityCase as l, RlsQueryFn as m, OrmParityOptions as n, testOrmParity as o, RlsParitySubject as p, OrmParityReport as r, RlsDbOutcome as s, OrmParityCase as t, RlsParityFixture as u, MatrixCell as v, PolicyMatrixReport as x, MatrixOutcome as y };