permdock 0.0.0 → 0.1.0

package/dist/policy-ANp36PnI.js

@@ -0,0 +1,971 @@
+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 { t as parseDuration } from "./duration-xK2jGFVc.js";
+import { g as sanitizeFields, l as relatesTo, n as normalizeValidity } from "./validity-D0uRmJKJ.js";
+import { n as sha256, t as bytesToBase64Url } from "./sha256-BO0swRXL.js";
+//#region src/conditions/opaque.ts
+function opaque(input) {
+	return freezeDeep({
+		op: "opaque",
+		sql: input.sql,
+		fingerprint: input.fingerprint
+	});
+}
+//#endregion
+//#region src/conditions/sql-function-assert.ts
+const IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/u;
+function assertSqlFunctionName(name) {
+	const parts = name.split(".");
+	if (parts.length === 0 || parts.length > 2) throw new Error(`PermDock: sqlFunction name '${name}' is not a SQL identifier`);
+	for (const part of parts) {
+		if (!IDENT.test(part)) throw new Error(`PermDock: sqlFunction name '${name}' is not a SQL identifier`);
+		assertSafeKey(part, "sqlFunction name");
+	}
+}
+function assertSqlFunctionArg(arg) {
+	if (isSqlFunctionField(arg)) assertSafeKey(arg.field, "sqlFunction argument field");
+}
+function assertPortableTwin(condition, depth = 0) {
+	/* v8 ignore next 3 */
+	if (depth > 32) throw new Error("PermDock: sqlFunction twin is nested too deeply");
+	switch (condition.op) {
+		case "opaque": throw new Error("PermDock: sqlFunction twin must not be opaque");
+		case "sqlFunction": throw new Error("PermDock: sqlFunction twin must not nest sqlFunction");
+		case "related": throw new Error("PermDock: sqlFunction twin must not read the relation graph");
+		case "and":
+		case "or":
+			for (const child of condition.conditions) assertPortableTwin(child, depth + 1);
+			break;
+		case "not": assertPortableTwin(condition.condition, depth + 1);
+	}
+}
+//#endregion
+//#region src/conditions/normalize.ts
+const FIELD_OPS = /* @__PURE__ */ new Set([
+	"eq",
+	"ne",
+	"gt",
+	"gte",
+	"lt",
+	"lte",
+	"contains",
+	"in",
+	"notIn",
+	"isNull"
+]);
+function toValue(raw) {
+	if (isSubjectRef(raw) || isConditionRef(raw)) return freezeDeep({ ref: raw.ref });
+	if (raw instanceof Date) return freezeDeep({ date: raw.toISOString() });
+	if (isConditionDate(raw)) return freezeDeep({ date: raw.date });
+	if (Array.isArray(raw)) return raw.map((item) => toValue(item));
+	if (raw === null || typeof raw === "string" || typeof raw === "number" || typeof raw === "boolean") return raw;
+	throw new Error("PermDock: unsupported condition value");
+}
+function flatten(op, conditions) {
+	const out = [];
+	for (const condition of conditions) if (condition.op === op) out.push(...condition.conditions);
+	else out.push(condition);
+	return out;
+}
+function collapse(condition) {
+	if (condition.op === "and" || condition.op === "or") {
+		const flat = flatten(condition.op, condition.conditions).map(collapse);
+		if (flat.length === 0) throw new Error(`PermDock: empty ${condition.op} condition`);
+		const single = sole(flat);
+		if (single !== void 0) return single;
+		return freezeDeep({
+			op: condition.op,
+			conditions: flat
+		});
+	}
+	if (condition.op === "not") return freezeDeep({
+		op: "not",
+		condition: collapse(condition.condition)
+	});
+	if (condition.op === "sqlFunction") return freezeDeep({
+		op: "sqlFunction",
+		name: condition.name,
+		args: condition.args,
+		twin: collapse(condition.twin)
+	});
+	return freezeDeep(condition);
+}
+function fieldCondition(field, raw) {
+	assertSafeKey(field, "condition field");
+	if (isCondition(raw) && (raw.op === "opaque" || raw.op === "sqlFunction")) return raw.op === "sqlFunction" ? normalizeSqlFunction(raw) : raw;
+	if (raw !== null && typeof raw === "object" && !isSubjectRef(raw) && !isConditionRef(raw) && !isConditionDate(raw) && !Array.isArray(raw) && !(raw instanceof Date)) {
+		const keys = ownKeys(raw);
+		if (keys.length === 1 && keys[0] !== void 0 && FIELD_OPS.has(keys[0])) {
+			const op = keys[0];
+			const value = raw[op];
+			if (op === "isNull") {
+				if (typeof value !== "boolean") throw new TypeError("PermDock: isNull requires a boolean");
+				return collapse({
+					op: "isNull",
+					field,
+					value
+				});
+			}
+			if (op === "in" || op === "notIn") {
+				if (isSubjectRef(value) || isConditionRef(value)) return collapse({
+					op,
+					field,
+					value: { ref: value.ref }
+				});
+				if (!Array.isArray(value)) throw new TypeError(`PermDock: ${op} requires an array or subject reference`);
+				return collapse({
+					op,
+					field,
+					value: value.map((item) => toValue(item))
+				});
+			}
+			return collapse({
+				op,
+				field,
+				value: toValue(value)
+			});
+		}
+	}
+	return collapse({
+		op: "eq",
+		field,
+		value: toValue(raw)
+	});
+}
+function normalizeSqlFunction(input) {
+	assertSqlFunctionName(input.name);
+	const args = input.args ?? [];
+	for (const arg of args) assertSqlFunctionArg(arg);
+	if (isCondition(input.twin) && input.twin.op === "sqlFunction") throw new Error("PermDock: sqlFunction twin must not nest sqlFunction");
+	const twin = isCondition(input.twin) ? collapse(input.twin) : normalizeWhere(input.twin);
+	assertPortableTwin(twin);
+	return freezeDeep({
+		op: "sqlFunction",
+		name: input.name,
+		args,
+		twin
+	});
+}
+function normalizeWhere(input) {
+	if (isCondition(input)) {
+		if (input.op === "sqlFunction") return collapse(normalizeSqlFunction(input));
+		return collapse(input);
+	}
+	if (input !== null && typeof input === "object" && "sql" in input && "fingerprint" in input && typeof input.sql === "string") return opaque({
+		sql: input.sql,
+		fingerprint: input.fingerprint
+	});
+	if (input === null || typeof input !== "object" || Array.isArray(input)) throw new Error("PermDock: condition must be an object");
+	const parts = [];
+	for (const key of Object.keys(input)) {
+		const value = input[key];
+		if (key === "and") {
+			if (!Array.isArray(value)) throw new TypeError("PermDock: and requires an array");
+			parts.push(collapse({
+				op: "and",
+				conditions: value.map(normalizeWhere)
+			}));
+			continue;
+		}
+		if (key === "or") {
+			if (!Array.isArray(value)) throw new TypeError("PermDock: or requires an array");
+			parts.push(collapse({
+				op: "or",
+				conditions: value.map(normalizeWhere)
+			}));
+			continue;
+		}
+		if (key === "not") {
+			parts.push(collapse({
+				op: "not",
+				condition: normalizeWhere(value)
+			}));
+			continue;
+		}
+		parts.push(fieldCondition(key, value));
+	}
+	if (parts.length === 0) throw new Error("PermDock: empty condition");
+	const single = sole(parts);
+	if (single !== void 0) return single;
+	return collapse({
+		op: "and",
+		conditions: parts
+	});
+}
+//#endregion
+//#region src/core/limits.ts
+const UNIT_SECONDS = {
+	s: 1,
+	sec: 1,
+	secs: 1,
+	second: 1,
+	seconds: 1,
+	m: 60,
+	min: 60,
+	mins: 60,
+	minute: 60,
+	minutes: 60,
+	h: 3600,
+	hr: 3600,
+	hrs: 3600,
+	hour: 3600,
+	hours: 3600,
+	d: 86400,
+	day: 86400,
+	days: 86400
+};
+function isThenable(value) {
+	return value !== null && typeof value === "object" && "then" in value && typeof value.then === "function";
+}
+const PER_PATTERN = /^(\d+)\s*(s|sec|secs|second|seconds|m|min|mins|minute|minutes|h|hr|hrs|hour|hours|d|day|days)$/u;
+/** The window length of `per` in seconds, or `undefined` when unrecognised. */
+function limitWindowSeconds(per) {
+	const trimmed = per.trim().toLowerCase();
+	const named = UNIT_SECONDS[trimmed];
+	if (named !== void 0) return named;
+	const match = PER_PATTERN.exec(trimmed);
+	if (match === null) return;
+	const amount = Number(match[1]);
+	const unit = UNIT_SECONDS[match[2] ?? ""];
+	return unit !== void 0 && Number.isSafeInteger(amount) && amount > 0 ? amount * unit : void 0;
+}
+/** Throws at definition time for a `limit` no store could count. */
+function assertLimit(limit, permissionKey) {
+	if (limit === void 0) return;
+	if (!Number.isSafeInteger(limit.count) || limit.count <= 0) throw new Error(`PermDock: limit count on '${permissionKey}' must be a positive integer`);
+	if (limitWindowSeconds(limit.per) === void 0) throw new Error(`PermDock: limit per '${limit.per}' on '${permissionKey}' is not a duration such as 'hour' or '15 min'`);
+	if (limit.mode !== void 0 && limit.mode !== "hard" && limit.mode !== "soft") throw new Error(`PermDock: limit mode on '${permissionKey}' must be 'hard' or 'soft'`);
+	if (limit.alertAt !== void 0 && (typeof limit.alertAt !== "number" || !(limit.alertAt > 0 && limit.alertAt <= 1))) throw new Error(`PermDock: limit alertAt on '${permissionKey}' must be a fraction above 0 and at most 1`);
+}
+/** The declared fields of a validated `limit`, so extra keys never reach the grant. */
+function normalizeLimit(limit) {
+	if (limit === void 0) return;
+	return {
+		count: limit.count,
+		per: limit.per,
+		...limit.mode === void 0 ? {} : { mode: limit.mode },
+		...limit.alertAt === void 0 ? {} : { alertAt: limit.alertAt }
+	};
+}
+function limitWindowId(per, now) {
+	const seconds = limitWindowSeconds(per);
+	return seconds === void 0 ? void 0 : String(Math.floor(now / seconds));
+}
+function limitCacheKey(input, now) {
+	const window = limitWindowId(input.per, now);
+	return window === void 0 ? void 0 : JSON.stringify([
+		input.tenant ?? null,
+		input.subjectId,
+		input.key,
+		input.per,
+		window
+	]);
+}
+function locate(input) {
+	const now = input.now ?? Date.now() / 1e3;
+	const seconds = limitWindowSeconds(input.per);
+	const id = limitCacheKey(input, now);
+	if (seconds === void 0 || id === void 0) return;
+	return {
+		id,
+		until: (Math.floor(now / seconds) + 1) * seconds,
+		now
+	};
+}
+function memoryLimitStore() {
+	const used = /* @__PURE__ */ new Map();
+	let earliest = Number.POSITIVE_INFINITY;
+	const sweep = (now) => {
+		if (now < earliest) return;
+		earliest = Number.POSITIVE_INFINITY;
+		for (const [id, entry] of used) if (entry.until <= now) used.delete(id);
+		else earliest = Math.min(earliest, entry.until);
+	};
+	return {
+		remaining(input) {
+			const cap = input.count;
+			const slot = locate(input);
+			if (!Number.isFinite(cap) || cap <= 0 || slot === void 0) return { remaining: -1 };
+			return { remaining: cap - (used.get(slot.id)?.count ?? 0) };
+		},
+		consume(input) {
+			const cap = input.count;
+			const slot = locate(input);
+			if (!Number.isFinite(cap) || cap <= 0 || slot === void 0) return { remaining: -1 };
+			sweep(slot.now);
+			const seen = used.get(slot.id)?.count ?? 0;
+			if (seen >= cap) return { remaining: -1 };
+			used.set(slot.id, {
+				count: seen + 1,
+				until: slot.until
+			});
+			earliest = Math.min(earliest, slot.until);
+			return { remaining: cap - seen - 1 };
+		},
+		size() {
+			return used.size;
+		}
+	};
+}
+/**
+* `left` is what remains once this call counts: the store's answer after
+* `consume`, or one less than `remaining` when only peeking. Below zero the
+* call is past the count.
+*/
+function verdictFor(limit, left, now) {
+	const seconds = limitWindowSeconds(limit.per);
+	if (seconds === void 0) return {
+		ok: false,
+		reason: "limit-unavailable"
+	};
+	const resetsAt = (Math.floor(now / seconds) + 1) * seconds;
+	if (left < 0) return limit.mode === "soft" ? {
+		ok: true,
+		quota: {
+			remaining: 0,
+			resetsAt
+		},
+		obligations: [{ kind: "over-limit" }]
+	} : {
+		ok: false,
+		reason: "limit",
+		detail: {
+			count: limit.count,
+			window: seconds,
+			resetsAt
+		}
+	};
+	return limit.alertAt !== void 0 && (limit.count - left) / limit.count >= limit.alertAt ? {
+		ok: true,
+		quota: {
+			remaining: left,
+			resetsAt
+		},
+		obligations: [{ kind: "near-limit" }]
+	} : {
+		ok: true,
+		quota: {
+			remaining: left,
+			resetsAt
+		}
+	};
+}
+function applyQuota(input) {
+	const limit = input.grant.limit;
+	if (limit === void 0) return { ok: true };
+	if (input.store === void 0) return {
+		ok: false,
+		reason: "limit-unavailable"
+	};
+	const payload = {
+		key: input.permissionKey,
+		subjectId: input.subjectId,
+		count: limit.count,
+		per: limit.per,
+		now: input.now,
+		...input.tenant === void 0 ? {} : { tenant: input.tenant }
+	};
+	const cacheKey = limitCacheKey(payload, input.now);
+	if (cacheKey === void 0) return {
+		ok: false,
+		reason: "limit-unavailable"
+	};
+	if (!input.consume) {
+		try {
+			const peeked = input.store.remaining(payload);
+			if (isThenable(peeked)) return {
+				ok: false,
+				reason: "limit-unavailable"
+			};
+			if (peeked !== void 0) return verdictFor(limit, peeked.remaining - 1, input.now);
+		} catch {
+			return {
+				ok: false,
+				reason: "limit-unavailable"
+			};
+		}
+		const cached = input.cache.get(cacheKey);
+		if (cached === void 0) return {
+			ok: false,
+			reason: "limit-unavailable"
+		};
+		return verdictFor(limit, cached - 1, input.now);
+	}
+	try {
+		const consumed = input.store.consume(payload);
+		if (isThenable(consumed)) return {
+			ok: false,
+			reason: "limit-unavailable"
+		};
+		input.cache.set(cacheKey, consumed.remaining);
+		return verdictFor(limit, consumed.remaining, input.now);
+	} catch {
+		return {
+			ok: false,
+			reason: "limit-unavailable"
+		};
+	}
+}
+//#endregion
+//#region src/core/policy.ts
+/** Every approver a requirement names: `by`, each stage and `escalation.to`. */
+function approversOf(requirement) {
+	return [
+		...flattenApprovers(requirement.by),
+		...(requirement.stages ?? []).flatMap((stage) => flattenApprovers(stage.by)),
+		...flattenApprovers(requirement.escalation?.to)
+	];
+}
+function asApprover(input) {
+	if (isReadonlyArray(input)) {
+		const items = [];
+		for (const item of input) items.push(...flattenApprovers(asApprover(item)));
+		return items;
+	}
+	if (isUserApprover(input)) return user(input.id);
+	return asGrantee(input);
+}
+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 normalizeApproval(approval, permission) {
+	if (approval === void 0) return;
+	if (approval === "human") return "human";
+	if (approval.staleOn !== void 0 && approval.staleOn !== "resource-change") throw new Error(`PermDock: approval staleOn must be 'resource-change', got '${String(approval.staleOn)}'`);
+	const label = permission ?? "a grant";
+	assertQuorum(approval.quorum, "approval.quorum", label);
+	if (approval.ttl !== void 0 && parseDuration(approval.ttl) === void 0) throw new Error(`PermDock: approval.ttl on '${label}' must be a duration such as '30m', got '${approval.ttl}'`);
+	const escalation = normalizeEscalation(approval.escalation, label);
+	const mode = approval.mode ?? "any";
+	if (mode !== "any") return compact({
+		mode,
+		stages: normalizeStages(approval, mode, label),
+		distinct: approval.distinct,
+		staleOn: approval.staleOn,
+		ttl: approval.ttl,
+		escalation
+	});
+	if (approval.stages !== void 0) throw new Error(`PermDock: approval.stages on '${label}' needs mode: 'all' or 'sequential'`);
+	const by = approval.by === void 0 ? void 0 : asApprover(approval.by);
+	if (by === void 0 && approval.distinct === void 0 && approval.staleOn === void 0 && approval.quorum === void 0 && approval.ttl === void 0 && escalation === void 0) return "human";
+	return compact({
+		by: by ?? authenticated(),
+		distinct: approval.distinct,
+		staleOn: approval.staleOn,
+		quorum: approval.quorum,
+		ttl: approval.ttl,
+		escalation
+	});
+}
+function assertQuorum(quorum, name, label) {
+	if (quorum !== void 0 && (!Number.isInteger(quorum) || quorum < 1)) throw new Error(`PermDock: ${name} on '${label}' must be an integer of at least 1, got ${String(quorum)}`);
+}
+function normalizeStages(approval, mode, label) {
+	if (mode !== "all" && mode !== "sequential") throw new Error(`PermDock: approval.mode on '${label}' must be 'any', 'all' or 'sequential', got '${mode}'`);
+	if (approval.by !== void 0 || approval.quorum !== void 0) throw new Error(`PermDock: approval on '${label}' sets mode '${mode}': put by and quorum on each stage`);
+	const stages = approval.stages ?? [];
+	if (stages.length === 0) throw new Error(`PermDock: approval mode '${mode}' on '${label}' needs at least one stage`);
+	return stages.map((stage, index) => {
+		assertQuorum(stage.quorum, `approval.stages[${index}].quorum`, label);
+		const by = asApprover(stage.by);
+		if (flattenApprovers(by).length === 0) throw new Error(`PermDock: approval.stages[${index}].by on '${label}' names no approver`);
+		return compact({
+			by,
+			quorum: stage.quorum
+		});
+	});
+}
+function normalizeEscalation(escalation, label) {
+	if (escalation === void 0) return;
+	if (parseDuration(escalation.after) === void 0) throw new Error(`PermDock: approval.escalation.after on '${label}' must be a duration such as '4h', got '${escalation.after}'`);
+	return {
+		after: escalation.after,
+		to: asApprover(escalation.to)
+	};
+}
+function isClosure(value) {
+	return typeof value === "function";
+}
+function flattenPermissions(input) {
+	if (isPermission(input)) return [input];
+	if (isReadonlyArray(input)) return input.flatMap((item) => flattenPermissions(item));
+	return [...listPermissions(input)];
+}
+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
+	});
+	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`);
+	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")) 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 === "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)
+	});
+}
+function resolveRoleScope(on) {
+	if (on === void 0) return "global";
+	if (typeof on === "string") {
+		if (on === "global" || on === "resource") throw new Error(`PermDock: role on: '${on}' is not a scope name`);
+		return on;
+	}
+	const permissions = flattenPermissions(on);
+	const names = new Set(permissions.map((permission) => permission.resource));
+	const [resource] = names;
+	if (names.size !== 1 || resource === void 0) throw new Error("PermDock: role on: resource must name exactly one resource");
+	return { resource };
+}
+function makeGrant(permission, effect, condition) {
+	const toInput = isClosure(condition) ? void 0 : condition?.to;
+	const to = toInput === void 0 ? {
+		kind: "role",
+		role: "",
+		scope: "global"
+	} : asGrantee(toInput);
+	if (isClosure(condition)) return {
+		permission,
+		effect,
+		to,
+		portable: false,
+		closure: condition
+	};
+	const whereInput = condition?.where;
+	const checkInput = condition?.check;
+	if (whereInput !== void 0 && permission.kind === "collection") throw new Error(`PermDock: where is not allowed on collection action '${permission.key}'`);
+	const where = whereInput === void 0 ? void 0 : normalizeWhere(whereInput);
+	const check = checkInput === void 0 ? void 0 : normalizeWhere(checkInput);
+	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;
+	return compact({
+		permission,
+		effect,
+		to,
+		where,
+		check,
+		approval: normalizeApproval(condition?.approval, permission.key),
+		portable,
+		limit: normalizeLimit(condition?.limit),
+		fields: sanitizeFields(condition?.fields),
+		name: condition?.name,
+		purpose,
+		validity: normalizeValidity(condition ?? {}, permission.key)
+	});
+}
+function allow(permission, condition) {
+	const grants = flattenPermissions(permission).map((leaf) => makeGrant(leaf, "allow", condition));
+	return sole(grants) ?? grants;
+}
+function deny(permission, condition) {
+	const grants = flattenPermissions(permission).map((leaf) => makeGrant(leaf, "deny", condition));
+	return sole(grants) ?? grants;
+}
+function flattenGrants(grants) {
+	const out = [];
+	for (const grant of grants) if (Array.isArray(grant)) out.push(...grant);
+	else out.push(grant);
+	return out;
+}
+function role(name, grants, options) {
+	if (options !== void 0 && Object.hasOwn(options, "restricted")) throw new Error(`PermDock: role option 'restricted' is reserved`);
+	const leaf = isRole(name) ? name : void 0;
+	const roleName = leaf?.key ?? name;
+	const scope = resolveRoleScope(options?.on ?? leaf?.on);
+	const assignable = options?.assignable ?? leaf?.assignable ?? scope !== "global";
+	const rules = roleRules(roleName, scope, options);
+	const activation = normalizeActivation(roleName, options?.activation);
+	const roleGrantee = asGrantee(freezeDeep({
+		kind: "role",
+		role: roleName,
+		scope
+	}));
+	const normalised = flattenGrants(grants).map((grant) => {
+		const items = flattenGrantee(grant.to);
+		const first = items[0];
+		const to = items.length === 1 && first?.kind === "role" ? roleGrantee : grant.to;
+		return freezeDeep({
+			...grant,
+			to,
+			role: roleName,
+			scope: roleScopeOf(to, scope)
+		});
+	});
+	return freezeDeep(compact({
+		name: roleName,
+		grants: normalised,
+		on: options?.on ?? leaf?.on,
+		assignable,
+		exclusiveWith: options?.exclusiveWith,
+		...rules,
+		meta: options?.meta ?? leaf?.meta,
+		activation
+	}));
+}
+/**
+* A role with `activation` is eligible-only: it needs a positive `maxDuration`
+* (Doctor PD033 warns without one). `justification` defaults to `'optional'`.
+*/
+function activationApproval(option, roleName) {
+	const label = `activation of '${roleName}'`;
+	const approval = normalizeApproval(option, label);
+	if (approval !== void 0 && approval !== "human" && approversOf(approval).some((item) => item.kind === "relation")) throw new Error(`PermDock: approval on ${label} names a relation; an activation has no row to read it on`);
+	return approval;
+}
+function normalizeActivation(roleName, option) {
+	if (option === void 0) return;
+	const justification = option.justification ?? "optional";
+	if (justification !== "required" && justification !== "optional") throw new Error(`PermDock: role '${roleName}' activation justification must be 'required' or 'optional'`);
+	return compact({
+		maxDuration: option.maxDuration,
+		justification,
+		approval: activationApproval(option.approval, roleName),
+		assurance: normalizeAssurance(option.assurance)
+	});
+}
+function normalizeAssurance(input) {
+	if (input === void 0) return;
+	const acr = input.acr === void 0 || input.acr.length === 0 ? void 0 : Object.freeze([...input.acr]);
+	const amr = input.amr === void 0 || input.amr.length === 0 ? void 0 : Object.freeze([...input.amr]);
+	const maxAge = typeof input.maxAge === "number" && input.maxAge >= 0 ? input.maxAge : void 0;
+	if (acr === void 0 && amr === void 0 && maxAge === void 0) return;
+	return compact({
+		maxAge,
+		acr,
+		amr
+	});
+}
+function nameList(roleName, option, value) {
+	if (value === void 0) return;
+	if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || item === "" || isForbiddenKey(item))) throw new Error(`PermDock: role '${roleName}' ${option} must be a list of names`);
+	return [...new Set(value)];
+}
+function holderCount(roleName, option, value) {
+	if (value === void 0) return;
+	if (typeof value !== "number" || !Number.isInteger(value) || value < 0) throw new Error(`PermDock: role '${roleName}' ${option} must be a whole number of holders`);
+	return value;
+}
+/** Ownership rules count holders per scope instance, so they need a named-scope role. */
+function roleRules(roleName, scope, options) {
+	const min = holderCount(roleName, "min", options?.min);
+	const max = holderCount(roleName, "max", options?.max);
+	const transferOnly = options?.transferOnly;
+	if (transferOnly !== void 0 && typeof transferOnly !== "boolean") throw new Error(`PermDock: role '${roleName}' transferOnly must be a boolean`);
+	if (max !== void 0 && max < 1) throw new Error(`PermDock: role '${roleName}' max must be at least 1`);
+	if (min !== void 0 && max !== void 0 && min > max) throw new Error(`PermDock: role '${roleName}' min must not exceed max`);
+	if ((min !== void 0 && min > 0 || max !== void 0 || transferOnly === true) && (typeof scope !== "string" || scope === "global")) throw new Error(`PermDock: role '${roleName}' min, max and transferOnly need on: '<scope>'`);
+	return compact({
+		min,
+		max,
+		transferOnly,
+		assigns: nameList(roleName, "assigns", options?.assigns),
+		for: nameList(roleName, "for", options?.for)
+	});
+}
+function canonicalPolicy(grants, delegations) {
+	const payload = canonicalGrants(grants);
+	if (delegations.length === 0) return payload;
+	return `${payload}\n${JSON.stringify(delegations)}`;
+}
+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
+	}));
+	return JSON.stringify(payload);
+}
+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 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 || relatesTo(node, key, 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 stale-on-change approval needs a row to version: an instance permission
+* whose resource declares `version`.
+*/
+function assertApprovalVersions(grants, resources) {
+	for (const grant of grants) {
+		const approval = grant.approval;
+		if (approval === void 0 || approval === "human" || approval.staleOn === void 0) continue;
+		if (grant.permission.kind !== "instance") throw new Error(`PermDock: approval staleOn on '${grant.permission.key}' needs an instance action; a collection action has no row to version`);
+		if (resources.get(grant.permission.resource)?.version === void 0) throw new Error(`PermDock: approval staleOn on '${grant.permission.key}' needs resource(..., { version: '<field>' }) on '${grant.permission.resource}'`);
+	}
+}
+/**
+* A relation approver is checked by id, from the requested row: the
+* relation lives on the permission's own resource (optionally up its parent
+* chain), or at the end of a list of links from it.
+*/
+function assertApprovalRelations(grants, resources) {
+	for (const grant of grants) {
+		const approval = grant.approval;
+		if (approval === void 0 || approval === "human") continue;
+		for (const item of approversOf(approval)) {
+			if (item.kind !== "relation") continue;
+			const label = `${grant.permission.key}: approver relation '${item.relation}'`;
+			if (grant.permission.kind !== "instance") throw new Error(`PermDock: ${label} needs an instance action; a collection action has no row to read it on`);
+			if (approverRelationResource(grant.permission.resource, item.through, resources) !== item.resource) throw new Error(`PermDock: ${label} must live on '${grant.permission.resource}' or at the end of its through links`);
+			if (resources.get(item.resource)?.relations[item.relation] === void 0) throw new Error(`PermDock: ${label} is not declared on '${item.resource}'`);
+		}
+	}
+}
+/** The resource a relation approver's `through` reaches from `start`, or `undefined`. */
+function approverRelationResource(start, through, resources) {
+	if (through === void 0) return start;
+	if (through === "parent") return isSelfParented(resources.get(start)) ? start : void 0;
+	let current = start;
+	for (const name of through) {
+		const node = current === void 0 ? void 0 : resources.get(current);
+		current = node !== void 0 && Object.hasOwn(node.links, name) ? node.links[name]?.resource : void 0;
+	}
+	return current;
+}
+function isVocabularyInput(value) {
+	return value !== null && typeof value === "object" && "permissions" in value && isRegistryTree(value.permissions);
+}
+function completeGrant(grant) {
+	const to = flattenGrantee(grant.to);
+	const first = to[0];
+	if (to.length === 1 && first?.kind === "role" && first.role === "") throw new Error("PermDock: grant is missing to");
+	return freezeDeep({
+		...grant,
+		role: roleNameOf(grant.to),
+		scope: roleScopeOf(grant.to)
+	});
+}
+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.principal ?? options.subject;
+	if (mapper === void 0) throw new Error("PermDock: definePolicy requires principal or subject");
+	const resources = getRegistry(tree);
+	assertParentGraph(resources);
+	const scopes = defineScopes(options.scopes);
+	const { roles, rolesByName } = mergeBindings((options.roles ?? []).map((binding) => rescopeBinding(binding, scopes)));
+	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) => rescopeGrant(grant, scopes));
+	const grants = [...fromBindings, ...fromGrants];
+	assertScopeKeys(grants, scopes, resources);
+	assertApprovalVersions(grants, resources);
+	assertApprovalRelations(grants, resources);
+	assertRelationGrants(grants, resources);
+	const delegations = (options.delegations ?? []).map((item, index) => normalizeDelegation(item, index, tree));
+	const fingerprint = bytesToBase64Url(sha256(canonicalPolicy(grants, delegations)));
+	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,
+		providers: options.providers,
+		hostable,
+		fresh,
+		delegations: delegations.length === 0 ? void 0 : delegations,
+		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 { 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 };