permdock 0.1.0 → 0.3.0

package/dist/{policy-ANp36PnI.js → policy-xyWg7QdR.js}

@@ -1,13 +1,15 @@
 import { n as isReadonlyArray, r as sole, t as compact } from "./compact-y6vfu2_f.js";
-import { n as freezeDeep } from "./freeze-y1_jQL4v.js";
-import { S as isForbiddenKey, d as isFieldRelation, f as isPermission, g as listPermissions, h as isSelfParented, i as findPermission, m as isRegistryTree, s as getRegistry, t as annotationsFor, w as ownKeys, x as assertSafeKey } from "./permissions-DC7GROPA.js";
-import { c as isConditionRef, l as isSqlFunctionField, n as isSubjectRef, o as isCondition, s as isConditionDate } from "./refs-ChLSxbST.js";
-import { n as isUserApprover, r as user, t as flattenApprovers } from "./approvers-aH0PJkmf.js";
-import { a as resolveScope, n as defineScopes } from "./scopes-cKVp_WTw.js";
-import { S as isRole, _ as roleScopeOf, a as authenticated, c as isGraphRelation, g as roleNameOf, m as relationStart, p as relationHops, r as asGrantee, s as flattenGrantee, w as listRoles } from "./grantee-Bv04_Vzf.js";
+import { n as freezeDeep } from "./freeze-CrU8nQeX.js";
+import { D as ownKeys, T as isForbiddenKey, _ as listPermissions, f as isFieldRelation, g as isSelfParented, h as isRegistryTree, i as findPermission, p as isPermission, s as getRegistry, t as annotationsFor, w as assertSafeKey } from "./permissions-DVoF6dMt.js";
+import { c as isConditionRef, l as isSqlFunctionField, n as isSubjectRef, o as isCondition, s as isConditionDate } from "./refs-KYb4ntaz.js";
+import { c as isUserApprover, i as flattenApprovers, l as user, o as isAnyOfInput, r as approverLeaves, s as isPermissionApprover } from "./approvers-DT4AVyIg.js";
+import { n as defineScopes, o as resolveScope } from "./scopes-CVdPrWN-.js";
 import { t as parseDuration } from "./duration-xK2jGFVc.js";
-import { g as sanitizeFields, l as relatesTo, n as normalizeValidity } from "./validity-D0uRmJKJ.js";
+import { E as listRoles, a as authenticated, g as relationStart, h as relationHops, l as inheritCondition, r as asGrantee, s as flattenGrantee, u as isGraphRelation, v as roleNameOf, w as isRole, y as roleScopeOf } from "./grantee-Cv5Sogfv.js";
+import { t as canonicalJson } from "./canonical-json-DemiK4Vp.js";
+import { i as sanitizeFields } from "./fields-BMl1RxoX.js";
 import { n as sha256, t as bytesToBase64Url } from "./sha256-BO0swRXL.js";
+import { f as relatesTo, h as scopeField, n as normalizeValidity, s as memberOfFields } from "./validity-uOp8UpYn.js";
 //#region src/conditions/opaque.ts
 function opaque(input) {
 	return freezeDeep({
@@ -151,6 +153,15 @@ function normalizeSqlFunction(input) {
 		twin
 	});
 }
+/** `{ session: … }` under `subject`; any other value is a comparison on a `subject` field. */
+function isSubjectCondition(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value) && Object.hasOwn(value, "session");
+}
+function subjectCondition(value) {
+	const session = value["session"];
+	if (ownKeys(value).length !== 1 || session === null || typeof session !== "object" || ownKeys(session).length !== 1 || Reflect.get(session, "live") !== true) throw new TypeError("PermDock: a subject condition is { subject: { session: { live: true } } }");
+	return freezeDeep({ op: "liveSession" });
+}
 function normalizeWhere(input) {
 	if (isCondition(input)) {
 		if (input.op === "sqlFunction") return collapse(normalizeSqlFunction(input));
@@ -187,6 +198,10 @@ function normalizeWhere(input) {
 			}));
 			continue;
 		}
+		if (key === "subject" && isSubjectCondition(value)) {
+			parts.push(subjectCondition(value));
+			continue;
+		}
 		parts.push(fieldCondition(key, value));
 	}
 	if (parts.length === 0) throw new Error("PermDock: empty condition");
@@ -413,15 +428,36 @@ function applyQuota(input) {
 }
 //#endregion
 //#region src/core/policy.ts
-/** Every approver a requirement names: `by`, each stage and `escalation.to`. */
+/** Every approver a requirement names: `by`, each stage and its escalation, and `escalation.to`, inside `anyOf` groups too. */
 function approversOf(requirement) {
 	return [
-		...flattenApprovers(requirement.by),
-		...(requirement.stages ?? []).flatMap((stage) => flattenApprovers(stage.by)),
-		...flattenApprovers(requirement.escalation?.to)
+		...approverLeaves(requirement.by),
+		...(requirement.stages ?? []).flatMap((stage) => approverLeaves(stage.by).concat(approverLeaves(stage.escalation?.to))),
+		...approverLeaves(requirement.escalation?.to)
 	];
 }
 function asApprover(input) {
+	if (isPermissionApprover(input)) {
+		if (typeof input.permission !== "string" || input.permission === "") throw new Error("PermDock: a permission approver needs a permission key");
+		return Object.freeze({
+			kind: "permission",
+			permission: input.permission
+		});
+	}
+	if (isAnyOfInput(input)) {
+		if (!Array.isArray(input.of) || input.of.length === 0) throw new Error("PermDock: anyOf() needs at least one approver");
+		const of = input.of.map((item) => {
+			const normalized = asApprover(item);
+			const items = flattenApprovers(normalized);
+			if (items.length === 0) throw new Error("PermDock: an anyOf() item names no approver");
+			const [first] = items;
+			return isReadonlyArray(normalized) || first === void 0 ? items : first;
+		});
+		return Object.freeze({
+			kind: "any-of",
+			of: Object.freeze(of)
+		});
+	}
 	if (isReadonlyArray(input)) {
 		const items = [];
 		for (const item of input) items.push(...flattenApprovers(asApprover(item)));
@@ -491,7 +527,8 @@ function normalizeStages(approval, mode, label) {
 		if (flattenApprovers(by).length === 0) throw new Error(`PermDock: approval.stages[${index}].by on '${label}' names no approver`);
 		return compact({
 			by,
-			quorum: stage.quorum
+			quorum: stage.quorum,
+			escalation: normalizeEscalation(stage.escalation, label)
 		});
 	});
 }
@@ -516,10 +553,13 @@ function delegationTarget(to, index) {
 	if ("actor" in to) return { kind: to.actor };
 	const target = compact({
 		kind: to.kind,
-		id: to.id
+		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) {
@@ -527,7 +567,7 @@ function normalizeDelegation(input, index, tree) {
 	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")) throw new Error(`PermDock: ${label}.from names a relation; a delegation is matched without a row, so name a role or another subject-only grantee`);
+	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))) {
@@ -544,6 +584,30 @@ function normalizeDelegation(input, index, tree) {
 		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) => a.key.localeCompare(b.key));
+		return {
+			scope,
+			permissions: sorted.map((leaf) => leaf.key),
+			scopes: sorted.map((leaf) => leaf.scope)
+		};
+	});
+}
 function resolveRoleScope(on) {
 	if (on === void 0) return "global";
 	if (typeof on === "string") {
@@ -556,6 +620,12 @@ function resolveRoleScope(on) {
 	if (names.size !== 1 || resource === void 0) throw new Error("PermDock: role on: resource must name exactly one resource");
 	return { resource };
 }
+const GROUP = /^[a-z][a-z0-9_-]*$/u;
+function grantGroup(group, key) {
+	if (group === void 0) return;
+	if (typeof group !== "string" || !GROUP.test(group) || group === "break-glass") throw new Error(`PermDock: group '${String(group)}' on ${key} must be lower case letters, digits, _ or -, start with a letter, and not be break-glass`);
+	return group;
+}
 function makeGrant(permission, effect, condition) {
 	const toInput = isClosure(condition) ? void 0 : condition?.to;
 	const to = toInput === void 0 ? {
@@ -578,6 +648,7 @@ function makeGrant(permission, effect, condition) {
 	assertLimit(condition?.limit, permission.key);
 	const purpose = condition?.purpose === void 0 || condition.purpose.length === 0 ? void 0 : Object.freeze([...new Set(condition.purpose)]);
 	const portable = condition?.limit === void 0 && purpose === void 0;
+	const requires = requiredKey(condition?.requires, permission, effect);
 	return compact({
 		permission,
 		effect,
@@ -589,10 +660,20 @@ function makeGrant(permission, effect, condition) {
 		limit: normalizeLimit(condition?.limit),
 		fields: sanitizeFields(condition?.fields),
 		name: condition?.name,
+		group: grantGroup(condition?.group, permission.key),
 		purpose,
-		validity: normalizeValidity(condition ?? {}, permission.key)
+		validity: normalizeValidity(condition ?? {}, permission.key),
+		requires
 	});
 }
+function requiredKey(input, permission, effect) {
+	if (input === void 0) return;
+	if (effect !== "allow") throw new Error(`PermDock: requires is allowed on an allow only; '${permission.key}' is a deny`);
+	if (permission.kind !== "instance") throw new Error(`PermDock: requires on '${permission.key}' needs an instance action; a collection action has no row whose scope it can check`);
+	const list = Array.isArray(input) ? input : [input];
+	if (list.length === 0 || !list.every(isPermission)) throw new TypeError(`PermDock: requires on '${permission.key}' must be a permission leaf or a non-empty list of them`);
+	return Object.freeze([...new Set(list.map((leaf) => leaf.key))]);
+}
 function allow(permission, condition) {
 	const grants = flattenPermissions(permission).map((leaf) => makeGrant(leaf, "allow", condition));
 	return sole(grants) ?? grants;
@@ -702,10 +783,41 @@ function roleRules(roleName, scope, options) {
 		for: nameList(roleName, "for", options?.for)
 	});
 }
-function canonicalPolicy(grants, delegations) {
+function canonicalPolicy(grants, delegations, levels) {
 	const payload = canonicalGrants(grants);
-	if (delegations.length === 0) return payload;
-	return `${payload}\n${JSON.stringify(delegations)}`;
+	const withDelegations = delegations.length === 0 ? payload : `${payload}\n${JSON.stringify(delegations)}`;
+	return levels === void 0 ? withDelegations : `${withDelegations}\nlevels:${canonicalJson(levels)}`;
+}
+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 canonicalGrants(grants) {
 	const payload = grants.map((grant) => ({
@@ -723,7 +835,8 @@ function canonicalGrants(grants) {
 		purpose: grant.purpose,
 		breakGlass: grant.breakGlass,
 		viaOnly: grant.viaOnly,
-		validity: grant.validity
+		validity: grant.validity,
+		requires: grant.requires
 	}));
 	return JSON.stringify(payload);
 }
@@ -755,6 +868,29 @@ function assertRelationGrants(grants, resources) {
 		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);
@@ -803,10 +939,19 @@ function assertScopeKeys(grants, scopes, resources) {
 		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 || relatesTo(node, key, grant.scope, scopes)) continue;
+		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`);
+}
 /**
 * A stale-on-change approval needs a row to version: an instance permission
 * whose resource declares `version`.
@@ -909,8 +1054,12 @@ function definePolicy(permissions, options) {
 	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 fingerprint = bytesToBase64Url(sha256(canonicalPolicy(grants, delegations)));
+	const levels = normalizeLevels(resources);
+	const oauthScopes = normalizeOAuthScopes(options.oauthScopes, tree);
+	const fingerprint = bytesToBase64Url(sha256(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({
@@ -931,6 +1080,8 @@ function definePolicy(permissions, options) {
 		hostable,
 		fresh,
 		delegations: delegations.length === 0 ? void 0 : delegations,
+		levels,
+		oauthScopes: oauthScopes.length === 0 ? void 0 : oauthScopes,
 		index: indexPolicy(roles, grants, vocabulary)
 	});
 }
@@ -968,4 +1119,4 @@ function separationConflicts(policy, memberships) {
 	return conflicts;
 }
 //#endregion
-export { assertSqlFunctionArg as _, definePolicy as a, indexPolicy as c, role as d, separationConflicts as f, assertPortableTwin as g, normalizeWhere as h, declaredRoleNames as i, normalizeApproval as l, memoryLimitStore as m, assertApprovalRelations as n, deny as o, applyQuota as p, completeGrant as r, grantList as s, allow as t, normalizeAssurance as u, assertSqlFunctionName as v, opaque as y };
+export { opaque as S, memoryLimitStore as _, definePolicy as a, assertSqlFunctionArg as b, indexPolicy as c, normalizeApproval as d, normalizeAssurance as f, applyQuota as g, separationConflicts as h, declaredRoleNames as i, levelCondition as l, role as m, assertApprovalRelations as n, deny as o, policyLevels as p, completeGrant as r, grantList as s, allow as t, levelNames as u, normalizeWhere as v, assertSqlFunctionName as x, assertPortableTwin as y };