permdock 0.3.1 → 0.5.0

package/dist/policy-DLZJ5gAp.js

@@ -0,0 +1,399 @@
+import { t as compact } from "./compact-CAf557ZB.js";
+import { n as freezeDeep } from "./freeze-CrU8nQeX.js";
+import { c as withGrantSchema, d as assertApprovalVersions, i as completeGrant, o as flattenGrants, p as normalizeWhere, s as flattenPermissions, u as assertApprovalRelations } from "./role-builder-CXbis5-X.js";
+import { c as listPermissions, i as getRegistry, m as annotationsFor, n as findPermission, s as isRegistryTree } from "./permission-registry-Br4jSNVi.js";
+import { d as isSelfParented, l as isFieldRelation } from "./resource-relations-D_jw0BFx.js";
+import { t as canonicalJson } from "./canonical-json-BC8_nMTw.js";
+import { r as sha256Digest } from "./sha256-D9ihqmvd.js";
+import { n as defineScopes, o as resolveScope } from "./scopes-CUPSjo9q.js";
+import { o as flattenGrantee, r as asGrantee, v as listRoles } from "./grantee-Cn1HyUsI.js";
+import { n as normalizeValidity } from "./validity-CZ7-y0Cj.js";
+import { a as relationStart, i as relationHops, n as isGraphRelation, t as inheritCondition } from "./grantee-conditions-CcXf8hMM.js";
+import { a as memberOfFields, p as scopeField, u as relatesTo } from "./tenancy-DN2QAx9z.js";
+import { t as byCodePoint } from "./compare-pfyVnBjE.js";
+//#region src/core/policy-assertions.ts
+function assertParentGraph(resources) {
+	for (const node of resources.values()) {
+		if (node.parent === void 0) continue;
+		if (!resources.has(node.parent.resource)) throw new Error(`PermDock: resource '${node.name}' parents unknown resource '${node.parent.resource}'`);
+	}
+}
+/**
+* Graph relation grantees must reach their resource: `through: 'parent'` from
+* the row to its parent resource or along its own self-parent, and never over
+* a `memberOf` relation, which is tenancy, not the object graph.
+*/
+function assertRelationGrants(grants, resources) {
+	for (const grant of grants) for (const item of flattenGrantee(grant.to)) {
+		if (item.kind !== "relation" || !isGraphRelation(item, resources)) continue;
+		const label = `grant ${grant.permission.key} relation '${item.relation}'`;
+		const target = resources.get(item.resource);
+		const spec = target?.relations[item.relation];
+		if (target === void 0 || spec === void 0) throw new Error(`PermDock: ${label}: ${item.resource} does not declare it`);
+		if (isFieldRelation(spec) && spec.memberOf !== void 0) throw new Error(`PermDock: ${label} is a memberOf relation; through walks the object graph, not scopes`);
+		const row = resources.get(grant.permission.resource);
+		if (Array.isArray(item.through)) {
+			if (relationHops(item, row, resources) === void 0) throw new Error(`PermDock: ${label}: the links [${item.through.join(", ")}] from ${grant.permission.resource} do not end on ${target.name}${(item.depth ?? 0) > 0 ? ` (or ${target.name} does not parent itself for depth)` : ""}`);
+			continue;
+		}
+		if (item.through === "parent" && target.name === row?.name && !isSelfParented(target)) throw new Error(`PermDock: ${label}: through: 'parent' needs ${target.name} to parent itself`);
+		if (relationStart(item, row, target) === void 0) throw new Error(item.through === void 0 ? `PermDock: ${label} is on ${target.name}, not ${grant.permission.resource}; add through: 'parent'` : `PermDock: ${label}: ${grant.permission.resource} has no parent on ${target.name}`);
+	}
+}
+function assertInheritGrants(grants, resources, tree) {
+	const keys = new Set(listPermissions(tree).map((leaf) => leaf.key));
+	const edges = /* @__PURE__ */ new Map();
+	for (const grant of grants) for (const item of flattenGrantee(grant.to)) {
+		if (item.kind !== "inherit") continue;
+		const label = `grant ${grant.permission.key} inherit '${item.permission}'`;
+		if (grant.effect !== "allow") throw new Error(`PermDock: ${label}: inherit() is allowed on an allow only`);
+		if (grant.permission.kind !== "instance") throw new Error(`PermDock: ${label}: inherit() needs an instance action; a collection action has no row to follow`);
+		if (!keys.has(item.permission)) throw new Error(`PermDock: ${label}: the policy does not declare it`);
+		if (inheritCondition(item, resources.get(grant.permission.resource), resources) === void 0) throw new Error(item.through === "parent" ? `PermDock: ${label}: ${grant.permission.resource} has no parent on ${item.resource}` : `PermDock: ${label}: the links [${item.through.join(", ")}] from ${grant.permission.resource} do not end on ${item.resource}`);
+		const next = edges.get(grant.permission.key) ?? /* @__PURE__ */ new Set();
+		next.add(item.permission);
+		edges.set(grant.permission.key, next);
+	}
+	const done = /* @__PURE__ */ new Set();
+	const visit = (key, path) => {
+		if (path.includes(key)) throw new Error(`PermDock: inherit() grants form a cycle: ${[...path.slice(path.indexOf(key)), key].join(" -> ")}`);
+		if (done.has(key)) return;
+		for (const target of edges.get(key) ?? []) visit(target, [...path, key]);
+		done.add(key);
+	};
+	for (const key of edges.keys()) visit(key, []);
+}
+function scopeOfGrant(scope, declared) {
+	if (typeof scope !== "string" || scope === "global") return scope;
+	const resolved = resolveScope(declared, scope);
+	if (resolved === void 0) throw new Error(`PermDock: definePolicy({ scopes }) must declare '${scope}' for on: '${scope}' roles`);
+	return resolved;
+}
+function rescopeGrantee(to, declared) {
+	const items = flattenGrantee(to);
+	if (!items.some((item) => item.kind === "role")) return to;
+	const mapped = items.map((item) => item.kind === "role" ? freezeDeep({
+		...item,
+		scope: scopeOfGrant(item.scope, declared)
+	}) : item);
+	if (Array.isArray(to)) return freezeDeep(mapped);
+	const [single] = mapped;
+	return single ?? to;
+}
+/** Resolves `tenant` / `team` aliases to declared names; an undeclared scope throws. */
+function rescopeGrant(grant, declared) {
+	const scope = scopeOfGrant(grant.scope, declared);
+	const to = rescopeGrantee(grant.to, declared);
+	if (scope === grant.scope && to === grant.to) return grant;
+	return freezeDeep({
+		...grant,
+		scope,
+		to
+	});
+}
+function rescopeBinding(binding, declared) {
+	const grants = binding.grants.map((grant) => rescopeGrant(grant, declared));
+	const on = typeof binding.on === "string" ? scopeOfGrant(binding.on, declared) : binding.on;
+	return freezeDeep(compact({
+		...binding,
+		grants,
+		on
+	}));
+}
+/**
+* No implicit cascade: a grant on scope S reaches a row only through the row's
+* own S key, so every resource an instance grant on S touches declares a
+* `memberOf: S` relation on that key. Without it `where()` and RLS could not
+* narrow the rows.
+*/
+function assertScopeKeys(grants, scopes, resources) {
+	for (const grant of grants) {
+		if (typeof grant.scope !== "string" || grant.scope === "global" || grant.permission.kind !== "instance") continue;
+		const key = scopes.find((scope) => scope.name === grant.scope)?.key;
+		const node = resources.get(grant.permission.resource);
+		if (key === void 0 || node === void 0) continue;
+		const fields = memberOfFields(node, grant.scope, scopes);
+		if (fields.length > 1 && !fields.includes(key)) throw new Error(`PermDock: resource '${node.name}' declares several memberOf relations to '${grant.scope}' (${fields.join(", ")}); name the one holding the instance with the scope's key '${key}'`);
+		const field = scopeField(node, grant.scope, scopes);
+		if (field !== void 0 && relatesTo(node, field, grant.scope, scopes)) continue;
+		throw new Error(`PermDock: resource '${node.name}' needs relations: { <name>: { field: '${key}', memberOf: '${grant.scope}' } } for ${grant.permission.key} on '${grant.scope}' roles`);
+	}
+}
+/** A `requires` names a permission the policy declares. */
+function assertRequires(grants, tree) {
+	const keys = new Set(listPermissions(tree).map((leaf) => leaf.key));
+	for (const grant of grants) for (const key of grant.requires ?? []) if (!keys.has(key)) throw new Error(`PermDock: '${grant.permission.key}' requires '${key}', which the policy does not declare`);
+}
+//#endregion
+//#region src/core/policy-delegation.ts
+function delegationTarget(to, index) {
+	if (typeof to === "string") return { kind: to };
+	if ("actor" in to) return { kind: to.actor };
+	const target = compact({
+		kind: to.kind,
+		id: to.id,
+		client: to.client
+	});
+	if (typeof target.kind !== "string" || target.kind === "") throw new Error(`PermDock: delegations[${index}].to needs an actor kind, such as actor('eve')`);
+	if (target.id !== void 0 && (typeof target.id !== "string" || target.id === "")) throw new Error(`PermDock: delegations[${index}].to.id must be a non-empty string`);
+	if (target.client !== void 0 && (typeof target.client !== "string" || target.client === "")) throw new Error(`PermDock: delegations[${index}].to.client must be a non-empty string`);
+	if (target.id !== void 0 && target.client !== void 0) throw new Error(`PermDock: delegations[${index}].to names both an id and a client; name one`);
+	return target;
+}
+function normalizeDelegation(input, index, tree) {
+	const label = `delegations[${index}]`;
+	const from = asGrantee(input.from);
+	const items = flattenGrantee(from);
+	if (items.length === 0) throw new Error(`PermDock: ${label}.from names nobody`);
+	if (items.some((item) => item.kind === "relation" || item.kind === "inherit")) throw new Error(`PermDock: ${label}.from names a relation or inherit(); a delegation is matched without a row, so name a role or another subject-only grantee`);
+	if (items.some((item) => item.kind === "actor")) throw new Error(`PermDock: ${label}.from names an actor; the principal hands over, the actor is \`to\``);
+	const leaves = /* @__PURE__ */ new Map();
+	for (const leaf of input.permissions.flatMap((item) => flattenPermissions(item))) {
+		if (findPermission(tree, leaf.key) === void 0) throw new Error(`PermDock: ${label} names unknown permission '${leaf.key}'`);
+		leaves.set(leaf.key, leaf);
+	}
+	const keys = [...leaves.keys()].toSorted();
+	if (keys.length === 0) throw new Error(`PermDock: ${label}.permissions is empty`);
+	return compact({
+		from,
+		to: delegationTarget(input.to, index),
+		permissions: keys,
+		readOnly: [...leaves.values()].filter((leaf) => annotationsFor(leaf).readOnlyHint).map((leaf) => leaf.key).toSorted(),
+		validity: normalizeValidity(input, label)
+	});
+}
+/** RFC 6749 section 3.3 `scope-token`: printable ASCII without space, `"` or `\`. */
+function isScopeToken(value) {
+	return /^[!#-[\]-~]+$/u.test(value);
+}
+function normalizeOAuthScopes(input, tree) {
+	if (input === void 0) return [];
+	const own = new Set(listPermissions(tree).map((leaf) => leaf.scope));
+	return Object.entries(input).map(([scope, items]) => {
+		if (!isScopeToken(scope)) throw new Error(`PermDock: oauthScopes key '${scope}' is not an OAuth scope token`);
+		if (own.has(scope)) throw new Error(`PermDock: oauthScopes key '${scope}' is a permission's own scope`);
+		const leaves = /* @__PURE__ */ new Map();
+		for (const leaf of (Array.isArray(items) ? items : []).flatMap((item) => flattenPermissions(item))) {
+			if (findPermission(tree, leaf.key) === void 0) throw new Error(`PermDock: oauthScopes '${scope}' names unknown permission '${leaf.key}'`);
+			leaves.set(leaf.key, leaf);
+		}
+		if (leaves.size === 0) throw new Error(`PermDock: oauthScopes '${scope}' covers no permission`);
+		const sorted = [...leaves.values()].toSorted((a, b) => byCodePoint(a.key, b.key));
+		return {
+			scope,
+			permissions: sorted.map((leaf) => leaf.key),
+			scopes: sorted.map((leaf) => leaf.scope)
+		};
+	});
+}
+//#endregion
+//#region src/core/policy-fingerprint.ts
+function canonicalPolicy(grants, delegations, levels) {
+	const payload = canonicalGrants(grants);
+	const withDelegations = delegations.length === 0 ? payload : `${payload}\n${JSON.stringify(delegations)}`;
+	return levels === void 0 ? withDelegations : `${withDelegations}\nlevels:${canonicalJson(levels)}`;
+}
+function canonicalGrants(grants) {
+	const payload = grants.map((grant) => ({
+		permission: grant.permission.key,
+		effect: grant.effect,
+		to: grant.to,
+		role: grant.role,
+		where: grant.where,
+		check: grant.check,
+		approval: grant.approval,
+		portable: grant.portable,
+		fields: grant.fields,
+		scope: grant.scope,
+		name: grant.name,
+		purpose: grant.purpose,
+		breakGlass: grant.breakGlass,
+		viaOnly: grant.viaOnly,
+		validity: grant.validity,
+		requires: grant.requires
+	}));
+	return JSON.stringify(payload);
+}
+const POLICY_X = Symbol.for("permdock.policy-x");
+/** The app data schemas of `policy`. */
+function policyX(policy) {
+	if (!Object.hasOwn(policy, POLICY_X)) return;
+	return Reflect.get(policy, POLICY_X);
+}
+//#endregion
+//#region src/core/policy.ts
+function indexPolicy(roles, grants, vocabulary) {
+	const declaredRoles = new Set(roles.map((item) => item.name));
+	for (const leaf of listRoles(vocabulary.roles)) declaredRoles.add(leaf.key);
+	const supports = roles.flatMap((binding) => binding.support === void 0 ? [] : [binding.support]);
+	const listed = grants.length > 0 ? grants : roles.flatMap((binding) => binding.grants);
+	const byKey = /* @__PURE__ */ new Map();
+	for (const grant of listed) {
+		const bucket = byKey.get(grant.permission.key);
+		if (bucket === void 0) byKey.set(grant.permission.key, [grant]);
+		else bucket.push(grant);
+	}
+	for (const bucket of byKey.values()) Object.freeze(bucket);
+	return freezeDeep({
+		declaredRoles,
+		supports,
+		grantsByKey: byKey
+	});
+}
+function normalizeLevels(resources) {
+	const out = {};
+	for (const node of resources.values()) {
+		const entries = Object.entries({ ...node.levels });
+		if (entries.length === 0) continue;
+		const levels = {};
+		for (const [name, input] of entries) try {
+			levels[name] = Object.keys(input).length === 0 ? {
+				op: "and",
+				conditions: []
+			} : normalizeWhere(input);
+		} catch (error) {
+			throw new Error(`PermDock: level '${name}' on '${node.name}' is not a valid condition`, { cause: error });
+		}
+		out[node.name] = levels;
+	}
+	return Object.keys(out).length === 0 ? void 0 : freezeDeep(out);
+}
+/** Declared levels of `resource` with their conditions, in declaration order. */
+function policyLevels(policy, resource) {
+	const levels = policy.levels;
+	return levels !== void 0 && Object.hasOwn(levels, resource) ? Object.entries({ ...levels[resource] }) : [];
+}
+/** The condition of `level` on `resource`, if the policy declares it. */
+function levelCondition(policy, resource, level) {
+	return policyLevels(policy, resource).find(([name]) => name === level)?.[1];
+}
+/** Declared level names of `resource`, in declaration order. */
+function levelNames(policy, resource) {
+	return policyLevels(policy, resource).map(([name]) => name);
+}
+function isVocabularyInput(value) {
+	return value !== null && typeof value === "object" && "permissions" in value && isRegistryTree(value.permissions);
+}
+function mergeBindings(items) {
+	const merged = /* @__PURE__ */ new Map();
+	for (const item of items) {
+		const existing = merged.get(item.name);
+		if (existing === void 0) {
+			merged.set(item.name, item);
+			continue;
+		}
+		merged.set(item.name, freezeDeep(compact({
+			name: item.name,
+			grants: [...existing.grants, ...item.grants],
+			on: existing.on,
+			assignable: existing.assignable,
+			exclusiveWith: existing.exclusiveWith ?? item.exclusiveWith,
+			min: existing.min ?? item.min,
+			max: existing.max ?? item.max,
+			transferOnly: existing.transferOnly ?? item.transferOnly,
+			assigns: existing.assigns ?? item.assigns,
+			for: existing.for ?? item.for,
+			meta: existing.meta ?? item.meta,
+			activation: existing.activation ?? item.activation,
+			support: existing.support ?? item.support
+		})));
+	}
+	return {
+		roles: [...merged.values()],
+		rolesByName: merged
+	};
+}
+function definePolicy(permissions, options) {
+	const vocabulary = isVocabularyInput(permissions) ? permissions : { permissions };
+	const tree = vocabulary.permissions;
+	const mapper = options.subject;
+	if (typeof mapper !== "function") throw new TypeError("PermDock: definePolicy requires a subject function");
+	const resources = getRegistry(tree);
+	assertParentGraph(resources);
+	const scopes = defineScopes(options.scopes);
+	const grantSchema = options.x?.grant;
+	const { roles, rolesByName } = mergeBindings((options.roles ?? []).map((binding) => {
+		const rescoped = rescopeBinding(binding, scopes);
+		const grants = rescoped.grants.map((grant) => withGrantSchema(grant, grantSchema));
+		return grants.every((grant, index) => grant === rescoped.grants[index]) ? rescoped : freezeDeep({
+			...rescoped,
+			grants
+		});
+	}));
+	const declared = new Set(roles.map((item) => item.name));
+	for (const leaf of listRoles(vocabulary.roles)) declared.add(leaf.key);
+	for (const binding of roles) for (const name of binding.assigns ?? []) if (!declared.has(name)) throw new Error(`PermDock: role '${binding.name}' names undeclared role '${name}'`);
+	const fromBindings = roles.flatMap((item) => item.grants);
+	const fromGrants = flattenGrants(options.grants ?? []).map(completeGrant).map((grant) => withGrantSchema(rescopeGrant(grant, scopes), grantSchema));
+	const grants = [...fromBindings, ...fromGrants];
+	assertScopeKeys(grants, scopes, resources);
+	assertApprovalVersions(grants, resources);
+	assertApprovalRelations(grants, resources);
+	assertRelationGrants(grants, resources);
+	assertRequires(grants, tree);
+	assertInheritGrants(grants, resources, tree);
+	const delegations = (options.delegations ?? []).map((item, index) => normalizeDelegation(item, index, tree));
+	const levels = normalizeLevels(resources);
+	const oauthScopes = normalizeOAuthScopes(options.oauthScopes, tree);
+	const fingerprint = sha256Digest(oauthScopes.length === 0 ? canonicalPolicy(grants, delegations, levels) : `${canonicalPolicy(grants, delegations, levels)}\noauthScopes:${canonicalJson(oauthScopes)}`);
+	const hostable = [...new Set((options.hostable ?? []).flatMap((item) => flattenPermissions(item).map((leaf) => leaf.key)))].toSorted();
+	const fresh = [...new Set((options.fresh ?? []).flatMap((item) => flattenPermissions(item).map((leaf) => leaf.key)))].toSorted();
+	return freezeDeep({
+		permissions: tree,
+		roles,
+		rolesByName,
+		grants,
+		vocabulary,
+		scopes,
+		principal: mapper,
+		subject: mapper,
+		context: options.context,
+		validate: options.validate ?? "boundary",
+		onDenied: options.onDenied,
+		fingerprint,
+		resources,
+		...options.x === void 0 ? {} : { [POLICY_X]: options.x },
+		providers: options.providers,
+		hostable,
+		fresh,
+		delegations: delegations.length === 0 ? void 0 : delegations,
+		levels,
+		oauthScopes: oauthScopes.length === 0 ? void 0 : oauthScopes,
+		index: indexPolicy(roles, grants, vocabulary)
+	});
+}
+function exclusivePairs(policy) {
+	const pairs = /* @__PURE__ */ new Map();
+	for (const binding of policy.roles) if (binding.exclusiveWith !== void 0) pairs.set(binding.name, binding.exclusiveWith);
+	return pairs;
+}
+function grantList(policy) {
+	if (policy.grants !== void 0 && policy.grants.length > 0) return policy.grants;
+	return policy.roles.flatMap((binding) => binding.grants);
+}
+function declaredRoleNames(policy) {
+	return policy.index.declaredRoles;
+}
+function separationConflicts(policy, memberships) {
+	const exclusive = exclusivePairs(policy);
+	const seen = /* @__PURE__ */ new Set();
+	const conflicts = [];
+	for (const membership of memberships) {
+		const held = new Set(membership.roles);
+		for (const name of held) for (const other of exclusive.get(name) ?? []) {
+			if (!held.has(other)) continue;
+			const pair = [name, other].toSorted();
+			const key = `${membership.principal ?? ""}:${membership.tenant ?? ""}:${pair.join("+")}`;
+			if (seen.has(key)) continue;
+			seen.add(key);
+			conflicts.push(compact({
+				principal: membership.principal ?? "",
+				tenant: membership.tenant,
+				roles: pair
+			}));
+		}
+	}
+	return conflicts;
+}
+//#endregion
+export { levelCondition as a, separationConflicts as c, indexPolicy as i, policyX as l, definePolicy as n, levelNames as o, grantList as r, policyLevels as s, declaredRoleNames as t, normalizeDelegation as u };