permdock 0.0.0 → 0.1.0

package/dist/diff-x5Il8LVa.js

@@ -0,0 +1,418 @@
+import { i as findPermission } from "./permissions-DC7GROPA.js";
+import { m as memoryRoleSource } from "./src-CTNT-PBW.js";
+import { l as canonicalJson } from "./snapshot-DE8dE_hz.js";
+import { t as createPermDock } from "./permdock-yoZ7EjxX.js";
+import { t as buildCatalog } from "./catalog-doc-BSo_Q_-6.js";
+import { a as loadModule, n as asPolicy, o as pickNamed } from "./load-BZ24CpZP.js";
+import { t as parseCatalog } from "./parse-DPfIvFMU.js";
+import { a as usageResult } from "./errors-DSMnAVNa.js";
+import { n as fixtureSubject, r as loadFixtures, t as fixtureRow } from "./fixtures-Cvaw0gDG.js";
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+//#region src/cli/diff.ts
+const EMPTY_SCAN = {
+	roots: [],
+	definitionFiles: {},
+	usages: {},
+	unknown: [],
+	dynamic: [],
+	roleNames: [],
+	planNames: [],
+	allowKeys: [],
+	snapshots: []
+};
+async function loadSide(cwd, source, now) {
+	const abs = resolve(cwd, source);
+	if (!existsSync(abs)) throw new Error(`PermDock CLI: not found: ${source}`);
+	if (abs.endsWith(".json")) return {
+		source,
+		catalog: parseCatalog(readFileSync(abs, "utf8")),
+		policy: void 0
+	};
+	const policy = asPolicy(pickNamed(await loadModule(abs), ["policy"]));
+	return {
+		source,
+		policy,
+		catalog: buildCatalog(policy.permissions, EMPTY_SCAN, now.toISOString(), policy)
+	};
+}
+function setDiff(before, after) {
+	const a = new Set(before);
+	const b = new Set(after);
+	return {
+		added: after.filter((item) => !a.has(item)).toSorted(),
+		removed: before.filter((item) => !b.has(item)).toSorted()
+	};
+}
+/** What makes two grants "the same grant" across versions: everything but the body. */
+function grantIdentity(grant) {
+	return canonicalJson({
+		permission: grant.permission,
+		effect: grant.effect,
+		role: grant.role,
+		to: grant.to,
+		scope: grant.scope
+	});
+}
+function same(a, b) {
+	return canonicalJson(a ?? null) === canonicalJson(b ?? null);
+}
+/** The body differences between two grants with one identity, in a fixed order. */
+function grantChanges(before, after) {
+	const out = [];
+	if (!same(before.where, after.where)) out.push(before.where === void 0 ? "where added" : after.where === void 0 ? "where removed" : "where changed");
+	if (!same(before.check, after.check)) out.push(before.check === void 0 ? "check added" : after.check === void 0 ? "check removed" : "check changed");
+	if (!same(before.approval, after.approval)) out.push(before.approval === void 0 ? "approval added" : after.approval === void 0 ? "approval removed" : "approval changed");
+	if (!same(before.fields, after.fields)) out.push(fieldsChange(before.fields, after.fields));
+	if (!same(before.validity, after.validity)) out.push(validityChange(before.validity, after.validity));
+	if (!same(before.limit, after.limit)) out.push(before.limit === void 0 ? "limit added" : after.limit === void 0 ? "limit removed" : "limit changed");
+	if (!same(before.purpose, after.purpose)) out.push("purpose changed");
+	if (before.name !== after.name) out.push("name changed");
+	if (before.portable !== after.portable) out.push(after.portable === false ? "portable: false" : "portable");
+	return out;
+}
+function fieldsChange(before, after) {
+	if (before === void 0) return "fields narrowed";
+	if (after === void 0) return "fields widened";
+	const kept = new Set(after);
+	return before.every((field) => kept.has(field)) ? "fields widened" : "fields narrowed";
+}
+const validFrom = (value) => value?.from ?? Number.NEGATIVE_INFINITY;
+const validUntil = (value) => value?.until ?? Number.POSITIVE_INFINITY;
+/** Narrowed when the window starts later or ends earlier than before; a new window on an open grant narrows it. */
+function validityChange(before, after) {
+	return validFrom(after) > validFrom(before) || validUntil(after) < validUntil(before) ? "validity narrowed" : "validity widened";
+}
+const NARROWING = /* @__PURE__ */ new Set([
+	"where added",
+	"where changed",
+	"check added",
+	"check changed",
+	"approval added",
+	"approval changed",
+	"fields narrowed",
+	"validity narrowed",
+	"limit added",
+	"limit changed",
+	"purpose changed",
+	"portable: false"
+]);
+function describeGrant(grant) {
+	const role = grant.role === null ? "top-level" : `role ${grant.role}`;
+	const scope = grant.scope === "global" ? "" : typeof grant.scope === "string" ? ` in ${grant.scope}` : ` on ${grant.scope.resource}`;
+	return `${grant.effect} ${grant.permission} (${role}${scope})`;
+}
+function delegationIdentity(delegation) {
+	return canonicalJson({
+		from: delegation.from,
+		to: delegation.to
+	});
+}
+function describeDelegation(delegation) {
+	const to = delegation.to.id === void 0 ? delegation.to.kind : `${delegation.to.kind} ${delegation.to.id}`;
+	return `delegation ${canonicalJson(delegation.from)} → ${to} (${delegation.permissions.join(", ")})`;
+}
+function delegationChanges(before, after) {
+	const changes = [];
+	const lost = before.permissions.filter((key) => !after.permissions.includes(key));
+	const gained = after.permissions.filter((key) => !before.permissions.includes(key));
+	if (lost.length > 0) changes.push(`permissions removed: ${lost.join(", ")}`);
+	if (gained.length > 0) changes.push(`permissions added: ${gained.join(", ")}`);
+	if (!same(before.validity, after.validity)) changes.push(validityChange(before.validity, after.validity));
+	return changes;
+}
+function diffDelegations(a, b, breaking) {
+	const byIdentityA = new Map(a.map((item) => [delegationIdentity(item), item]));
+	const byIdentityB = new Map(b.map((item) => [delegationIdentity(item), item]));
+	const added = [];
+	const removed = [];
+	const changed = [];
+	for (const [identity, before] of byIdentityA) {
+		const after = byIdentityB.get(identity);
+		if (after === void 0) {
+			removed.push(before);
+			breaking.push({
+				kind: "delegation-removed",
+				detail: `${describeDelegation(before)} removed`
+			});
+			continue;
+		}
+		const changes = delegationChanges(before, after);
+		if (changes.length === 0) continue;
+		changed.push({
+			before,
+			after,
+			changes
+		});
+		const narrowing = changes.filter((item) => item.startsWith("permissions removed") || item === "validity narrowed");
+		if (narrowing.length > 0) breaking.push({
+			kind: "delegation-narrowed",
+			detail: `${describeDelegation(after)}: ${narrowing.join(", ")}`
+		});
+	}
+	for (const [identity, after] of byIdentityB) if (!byIdentityA.has(identity)) added.push(after);
+	return {
+		added,
+		removed,
+		changed
+	};
+}
+function roleEntries(catalog) {
+	return new Map((catalog.roles ?? []).map((role) => [role.key, canonicalJson(role)]));
+}
+function sideRef(side) {
+	return side.catalog.fingerprint === void 0 ? { source: side.source } : {
+		source: side.source,
+		fingerprint: side.catalog.fingerprint
+	};
+}
+/** Former key to current key, from each permission's `renamedFrom`. */
+function aliasesOf(catalog) {
+	return new Map(catalog.permissions.flatMap((item) => (item.renamedFrom ?? []).map((old) => [old, item.key])));
+}
+/** `a` with every key `b` renamed written as its new key, so grants compare by the current name. */
+function underNames(a, aliases) {
+	if (a.catalog.grants === void 0 || aliases.size === 0) return a;
+	return {
+		...a,
+		catalog: {
+			...a.catalog,
+			grants: a.catalog.grants.map((grant) => {
+				const to = aliases.get(grant.permission);
+				return to === void 0 ? grant : {
+					...grant,
+					permission: to
+				};
+			})
+		}
+	};
+}
+function diffCatalogs(original, b) {
+	const breaking = [];
+	const aliasesA = aliasesOf(original.catalog);
+	const aliasesB = aliasesOf(b.catalog);
+	const keysB = new Set(b.catalog.permissions.map((item) => item.key));
+	const a = underNames(original, aliasesB);
+	const keyDiff = setDiff(a.catalog.permissions.map((item) => item.key), b.catalog.permissions.map((item) => item.key));
+	const renamed = [];
+	const removedKeys = [];
+	for (const key of keyDiff.removed) {
+		const to = aliasesB.get(key);
+		if (to === void 0) removedKeys.push(key);
+		else renamed.push({
+			from: key,
+			to
+		});
+	}
+	const permissions = {
+		added: keyDiff.added,
+		removed: removedKeys,
+		renamed
+	};
+	for (const key of permissions.removed) breaking.push({
+		kind: "permission-removed",
+		permission: key,
+		detail: `${key} no longer exists`
+	});
+	for (const [old, to] of aliasesA) if (!aliasesB.has(old) && !keysB.has(old)) breaking.push({
+		kind: "alias-removed",
+		permission: to,
+		detail: `${old} no longer resolves to ${to}: stored custom roles, tokens and SQL that still name it now deny`
+	});
+	const scopes = setDiff((a.catalog.scopes ?? []).map((scope) => scope.name), (b.catalog.scopes ?? []).map((scope) => scope.name));
+	for (const name of scopes.removed) breaking.push({
+		kind: "scope-removed",
+		detail: `scope ${name} no longer exists`
+	});
+	const rolesA = roleEntries(a.catalog);
+	const rolesB = roleEntries(b.catalog);
+	const roleNames = setDiff([...rolesA.keys()], [...rolesB.keys()]);
+	const changedRoles = [...rolesA.keys()].filter((key) => rolesB.has(key) && rolesB.get(key) !== rolesA.get(key)).toSorted();
+	for (const name of roleNames.removed) breaking.push({
+		kind: "role-removed",
+		role: name,
+		detail: `role ${name} no longer exists`
+	});
+	const removedPermissions = new Set(permissions.removed);
+	const removedRoles = new Set(roleNames.removed);
+	let grants;
+	if (a.catalog.grants !== void 0 && b.catalog.grants !== void 0) {
+		const byIdentityA = new Map(a.catalog.grants.map((grant) => [grantIdentity(grant), grant]));
+		const byIdentityB = new Map(b.catalog.grants.map((grant) => [grantIdentity(grant), grant]));
+		const added = [];
+		const removed = [];
+		const changed = [];
+		for (const [identity, before] of byIdentityA) {
+			const after = byIdentityB.get(identity);
+			if (after === void 0) {
+				removed.push(before);
+				continue;
+			}
+			const changes = grantChanges(before, after);
+			if (changes.length > 0) changed.push({
+				before,
+				after,
+				changes
+			});
+		}
+		for (const [identity, after] of byIdentityB) if (!byIdentityA.has(identity)) added.push(after);
+		for (const grant of removed) {
+			if (grant.effect !== "allow") continue;
+			if (removedPermissions.has(grant.permission) || grant.role !== null && removedRoles.has(grant.role)) continue;
+			breaking.push({
+				kind: "allow-removed",
+				permission: grant.permission,
+				role: grant.role,
+				detail: `${describeGrant(grant)} removed`
+			});
+		}
+		for (const grant of added) if (grant.effect === "deny") breaking.push({
+			kind: "deny-added",
+			permission: grant.permission,
+			role: grant.role,
+			detail: `${describeGrant(grant)} added`
+		});
+		for (const change of changed) {
+			if (change.after.effect === "deny") {
+				breaking.push({
+					kind: "deny-changed",
+					permission: change.after.permission,
+					role: change.after.role,
+					detail: `${describeGrant(change.after)}: ${change.changes.join(", ")}`
+				});
+				continue;
+			}
+			const narrowing = change.changes.filter((item) => NARROWING.has(item));
+			if (narrowing.length > 0) breaking.push({
+				kind: "allow-narrowed",
+				permission: change.after.permission,
+				role: change.after.role,
+				detail: `${describeGrant(change.after)}: ${narrowing.join(", ")}`
+			});
+		}
+		grants = {
+			added,
+			removed,
+			changed
+		};
+	}
+	const delegations = grants === void 0 ? void 0 : diffDelegations(a.catalog.delegations ?? [], b.catalog.delegations ?? [], breaking);
+	return {
+		a: sideRef(a),
+		b: sideRef(b),
+		permissions,
+		scopes,
+		roles: {
+			...roleNames,
+			changed: changedRoles
+		},
+		...grants === void 0 ? {} : { grants },
+		...delegations === void 0 ? {} : { delegations },
+		breaking
+	};
+}
+async function impactOf(input) {
+	const { fixtures, customRoles } = await loadFixtures(input.cwd, input.fixtures);
+	const now = Math.floor(input.now.getTime() / 1e3);
+	const outcome = async (policy, fixture) => {
+		const permission = findPermission(policy.permissions, fixture.action);
+		if (permission === void 0) return "unknown";
+		const [decision] = (await createPermDock(policy, fixtureSubject(fixture.subject), { customRoles: memoryRoleSource(customRoles) })).simulate([[permission, fixtureRow(fixture, permission.kind)]], { now });
+		return decision?.outcome ?? "denied";
+	};
+	const rows = [];
+	const breaking = [];
+	for (const fixture of fixtures) {
+		const [before, after] = await Promise.all([outcome(input.a, fixture), outcome(input.b, fixture)]);
+		if (before === after) continue;
+		rows.push({
+			action: fixture.action,
+			subject: fixture.subject.id,
+			...fixture.subject.tenant === void 0 ? {} : { tenant: fixture.subject.tenant },
+			before,
+			after
+		});
+		if (before === "granted" && after !== "granted") breaking.push({
+			kind: "access-lost",
+			permission: fixture.action,
+			detail: `${fixture.subject.id} loses ${fixture.action}: ${before} → ${after}`
+		});
+	}
+	return {
+		rows,
+		breaking
+	};
+}
+function formatText(diff) {
+	const lines = [];
+	const section = (title, added, removed, changed = []) => {
+		if (added.length === 0 && removed.length === 0 && changed.length === 0) return;
+		lines.push(title);
+		for (const item of added) lines.push(`  + ${item}`);
+		for (const item of removed) lines.push(`  - ${item}`);
+		for (const item of changed) lines.push(`  ~ ${item}`);
+	};
+	section("permissions", diff.permissions.added, diff.permissions.removed, diff.permissions.renamed.map((rename) => `${rename.from} → ${rename.to} (renamed)`));
+	section("scopes", diff.scopes.added, diff.scopes.removed);
+	section("roles", diff.roles.added, diff.roles.removed, diff.roles.changed.map((name) => `${name}: declaration changed`));
+	if (diff.grants === void 0) lines.push("grants: not compared (a catalog was built without its policy; run `permdock collect` with `policy` configured)");
+	else section("grants", diff.grants.added.map(describeGrant), diff.grants.removed.map(describeGrant), diff.grants.changed.map((change) => `${describeGrant(change.after)}: ${change.changes.join(", ")}`));
+	if (diff.delegations !== void 0) section("delegations", diff.delegations.added.map(describeDelegation), diff.delegations.removed.map(describeDelegation), diff.delegations.changed.map((change) => `${describeDelegation(change.after)}: ${change.changes.join(", ")}`));
+	if (diff.impact !== void 0) {
+		lines.push(diff.impact.length === 0 ? "impact: no fixture changes outcome" : `impact (${String(diff.impact.length)} fixture(s) change outcome)`);
+		for (const row of diff.impact) {
+			const where = row.tenant === void 0 ? "" : ` in ${row.tenant}`;
+			lines.push(`  ${row.subject}${where} ${row.action}: ${row.before} → ${row.after}`);
+		}
+	}
+	if (lines.length === 0) lines.push("no changes");
+	if (diff.breaking.length > 0) {
+		lines.push(`breaking (${String(diff.breaking.length)})`);
+		for (const change of diff.breaking) lines.push(`  ${change.kind}: ${change.detail}`);
+	}
+	return `${lines.join("\n")}\n`;
+}
+async function runDiff(input) {
+	const [sourceA, sourceB, ...extra] = input.sources;
+	if (sourceA === void 0 || sourceB === void 0 || extra.length > 0) return {
+		code: 2,
+		output: "PermDock CLI: diff takes two inputs, each a permissions.catalog.json or a module exporting policy"
+	};
+	let a;
+	let b;
+	try {
+		[a, b] = await Promise.all([loadSide(input.cwd, sourceA, input.now), loadSide(input.cwd, sourceB, input.now)]);
+	} catch (error) {
+		return usageResult(error);
+	}
+	let diff = diffCatalogs(a, b);
+	if (input.impact) {
+		if (a.policy === void 0 || b.policy === void 0) return {
+			code: 2,
+			output: "PermDock CLI: diff --impact needs two policy modules; a catalog file cannot be evaluated"
+		};
+		const fixtures = input.fixtures ?? input.config.rls?.fixtures ?? "rls.fixtures.json";
+		try {
+			const impact = await impactOf({
+				cwd: input.cwd,
+				a: a.policy,
+				b: b.policy,
+				fixtures,
+				now: input.now
+			});
+			diff = {
+				...diff,
+				impact: impact.rows,
+				breaking: [...diff.breaking, ...impact.breaking]
+			};
+		} catch (error) {
+			return usageResult(error);
+		}
+	}
+	return {
+		code: diff.breaking.length > 0 ? 1 : 0,
+		output: input.json ? `${JSON.stringify(diff, null, 2)}\n` : formatText(diff)
+	};
+}
+//#endregion
+export { runDiff };

package/dist/digest-B3kc_PgQ.d.ts

@@ -0,0 +1,19 @@
+//#region src/core/digest.d.ts
+/**
+ * What a PermDock error's `digest` says. React keeps `digest` when an error
+ * crosses from a Server Component to the client, where production builds
+ * redact the message, so a client error boundary can still tell a denial or
+ * an approval request from any other failure.
+ */
+type PermDockDigest = {
+  readonly outcome: "denied";
+  readonly permission: string;
+} | {
+  readonly outcome: "approval-required";
+  readonly permission: string;
+  readonly token: string;
+};
+/** Reads `error.digest`; anything that is not a PermDock digest is `null`. */
+declare function parsePermDockDigest(digest: unknown): PermDockDigest | null;
+//#endregion
+export { parsePermDockDigest as n, PermDockDigest as t };

package/dist/digest-BI-6aa6d.js

@@ -0,0 +1,27 @@
+//#region src/core/digest.ts
+const DENIED = "PERMDOCK_DENIED";
+const APPROVAL_REQUIRED = "PERMDOCK_APPROVAL_REQUIRED";
+function deniedDigest(permission) {
+	return `${DENIED};${permission}`;
+}
+function approvalDigest(permission, token) {
+	return `${APPROVAL_REQUIRED};${permission};${token}`;
+}
+/** Reads `error.digest`; anything that is not a PermDock digest is `null`. */
+function parsePermDockDigest(digest) {
+	if (typeof digest !== "string") return null;
+	const [kind, permission, token, ...rest] = digest.split(";");
+	if (rest.length > 0 || permission === void 0 || permission === "") return null;
+	if (kind === DENIED && token === void 0) return {
+		outcome: "denied",
+		permission
+	};
+	if (kind === APPROVAL_REQUIRED && token !== void 0 && token !== "") return {
+		outcome: "approval-required",
+		permission,
+		token
+	};
+	return null;
+}
+//#endregion
+export { deniedDigest as n, parsePermDockDigest as r, approvalDigest as t };