permdock 0.3.1 → 0.5.0

package/dist/role-builder-CXbis5-X.js

@@ -0,0 +1,623 @@
+import { a as sole, n as isReadonlyArray, t as compact } from "./compact-CAf557ZB.js";
+import { n as freezeDeep } from "./freeze-CrU8nQeX.js";
+import { i as ownKeys, n as isForbiddenKey, t as assertSafeKey } from "./paths-DXSHAMIa.js";
+import { c as isConditionRef, l as isSqlFunctionField, n as isSubjectRef, o as isCondition, s as isConditionDate } from "./refs-K6eWUJ0H.js";
+import { c as isUserApprover, i as flattenApprovers, l as user, o as isAnyOfInput, r as approverLeaves, s as isPermissionApprover } from "./approvers-CqPOLD-o.js";
+import { c as listPermissions, o as isPermission } from "./permission-registry-Br4jSNVi.js";
+import { n as assertMetaValue, r as parseAppData, t as assertAppData } from "./app-data-MuyzVqX8.js";
+import { d as isSelfParented } from "./resource-relations-D_jw0BFx.js";
+import { a as durationOf, r as assertDuration } from "./time-DkWjdL98.js";
+import { a as authenticated, d as roleScopeOf, g as isRole, o as flattenGrantee, r as asGrantee, u as roleNameOf } from "./grantee-Cn1HyUsI.js";
+import { c as sanitizeFields, n as normalizeValidity } from "./validity-CZ7-y0Cj.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
+	});
+}
+/** `{ 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));
+		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;
+		}
+		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");
+	const single = sole(parts);
+	if (single !== void 0) return single;
+	return collapse({
+		op: "and",
+		conditions: parts
+	});
+}
+//#endregion
+//#region src/core/approval-normalize.ts
+/** Every approver a requirement names: `by`, each stage and its escalation, and `escalation.to`, inside `anyOf` groups too. */
+function approversOf(requirement) {
+	return [
+		...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)));
+		return items;
+	}
+	if (isUserApprover(input)) return user(input.id);
+	return asGrantee(input);
+}
+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) assertDuration(approval.ttl, `approval.ttl on '${label}'`);
+	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,
+			escalation: normalizeEscalation(stage.escalation, label)
+		});
+	});
+}
+function normalizeEscalation(escalation, label) {
+	if (escalation === void 0) return;
+	assertDuration(escalation.after, `approval.escalation.after on '${label}'`);
+	return {
+		after: escalation.after,
+		to: asApprover(escalation.to)
+	};
+}
+/**
+* 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;
+}
+/**
+* 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;
+}
+//#endregion
+//#region src/core/limit-grants.ts
+/** 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 (durationOf(limit.per) === void 0) throw new Error(`PermDock: limit per on '${permissionKey}' must be a whole number of seconds above 0 (3600 for an hour), got ${JSON.stringify(limit.per)}`);
+	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 }
+	};
+}
+//#endregion
+//#region src/core/grant-builders.ts
+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)];
+}
+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 ? {
+		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;
+	const requires = requiredKey(condition?.requires, permission, effect);
+	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,
+		group: grantGroup(condition?.group, permission.key),
+		meta: grantMeta(condition?.meta, permission.key, void 0),
+		obligations: appObligations(condition?.obligations, permission.key, effect),
+		purpose,
+		validity: normalizeValidity(condition ?? {}, permission.key),
+		requires
+	});
+}
+/** Checks a grant's `meta`: plain JSON, string `description`, `x` through the schema when given. */
+function grantMeta(meta, key, schema) {
+	if (meta === void 0) return;
+	assertAppData(meta, `meta of a grant on ${key}`);
+	const { description, x } = meta;
+	if (description !== void 0 && typeof description !== "string") throw new TypeError(`PermDock: meta.description of a grant on ${key} must be a string`);
+	return freezeDeep(compact({
+		description,
+		x: x === void 0 ? void 0 : parseAppData(schema, x, `meta.x of a grant on ${key}`)
+	}));
+}
+function appObligations(input, key, effect) {
+	if (input === void 0) return;
+	if (effect !== "allow") throw new Error(`PermDock: obligations are allowed on an allow only; '${key}' is a deny`);
+	const list = input;
+	if (!Array.isArray(list)) throw new TypeError(`PermDock: obligations on '${key}' must be a list`);
+	const items = list;
+	const seen = /* @__PURE__ */ new Set();
+	const out = [];
+	for (const item of items) {
+		const entry = typeof item === "object" && item !== null ? item : void 0;
+		const name = typeof item === "string" ? item : entry === void 0 ? void 0 : Reflect.get(entry, "name");
+		if (typeof name !== "string" || !GROUP.test(name)) throw new Error(`PermDock: obligation '${String(name)}' on '${key}' must be lower case letters, digits, _ or -, starting with a letter`);
+		if (seen.has(name)) throw new Error(`PermDock: obligation '${name}' is listed twice on '${key}'`);
+		seen.add(name);
+		const detail = entry === void 0 ? void 0 : Reflect.get(entry, "detail");
+		if (detail === void 0) {
+			out.push({
+				kind: "app",
+				name
+			});
+			continue;
+		}
+		assertMetaValue(detail, `detail of obligation '${name}' on '${key}'`);
+		out.push({
+			kind: "app",
+			name,
+			detail
+		});
+	}
+	return out.length === 0 ? void 0 : freezeDeep(out);
+}
+/** Re-checks every grant's `meta.x` with the policy's grant schema, keeping the schema output. */
+function withGrantSchema(grant, schema) {
+	const meta = grant.meta;
+	if (schema === void 0 || meta?.x === void 0) return grant;
+	return freezeDeep({
+		...grant,
+		meta: grantMeta(meta, grant.permission.key, schema) ?? meta
+	});
+}
+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;
+}
+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 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)
+	});
+}
+//#endregion
+//#region src/core/role-builder.ts
+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 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
+	}));
+}
+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'`);
+	if (option.maxDuration !== void 0) assertDuration(option.maxDuration, `activation.maxDuration on role '${roleName}'`);
+	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)
+	});
+}
+//#endregion
+export { opaque as _, deny as a, withGrantSchema as c, assertApprovalVersions as d, normalizeApproval as f, assertSqlFunctionName as g, assertSqlFunctionArg as h, completeGrant as i, asApprover as l, assertPortableTwin as m, role as n, flattenGrants as o, normalizeWhere as p, allow as r, flattenPermissions as s, normalizeAssurance as t, assertApprovalRelations as u };

package/dist/{rpc-DL9Sqvb1.js → rpc-aPyNi6tA.js}

@@ -1,8 +1,8 @@
-import { t as compact } from "./compact-y6vfu2_f.js";
-import { o as requestFromContext } from "./http-SO7qGttf.js";
-import { n as tenantScope } from "./adapter-context-mlWsVGGg.js";
-import { t as adapterKernel } from "./bind-CuzGytRf.js";
-import { n as guardIterable } from "./stream-DDpvynSB.js";
+import { t as compact } from "./compact-CAf557ZB.js";
+import { s as requestFromContext } from "./http-BBoKefeS.js";
+import { n as tenantScope } from "./adapter-context-CRhqyzCk.js";
+import { t as adapterKernel } from "./bind-CZzhx-Vj.js";
+import { r as guardIterable } from "./stream-CvdUS9V1.js";
 //#region src/server/rpc.ts
 /** The tRPC and oRPC error code for a Problem Details status. */
 function rpcCode(status) {
@@ -58,6 +58,15 @@ function bindRpcKernel(policy, options, adapter, contextOf, path) {
 		const opts = optsByRequest.get(request);
 		return opts === void 0 ? { tenant: void 0 } : scopeOf(opts);
 	});
+	const guard = async (permission, data, opts, protectOptions) => {
+		const request = bind(opts);
+		const scope = await scopeOf(opts);
+		return {
+			request,
+			scope,
+			guard: await kernel.protect(permission, data === void 0 ? void 0 : () => data(opts), protectOptions)(request, scope)
+		};
+	};
 	const evaluate = (request, opts) => {
 		bind(opts);
 		return request.method === "GET" ? evaluations.GET(request) : evaluations.POST(request);
@@ -70,14 +79,15 @@ function bindRpcKernel(policy, options, adapter, contextOf, path) {
 		},
 		scopeOf,
 		connection,
-		evaluate
+		evaluate,
+		guard
 	};
 }
 /** Wraps a streamed result so revocation ends it and items the subscriber cannot read drop. */
-async function guardStream(source, open, permission, loadData, protectOptions, guard) {
+async function guardStream(source, open, permission, data, protectOptions, guard) {
 	const conn = await open(permission === null ? {} : compact({
 		permission,
-		data: loadData
+		data
 	}));
 	return guardIterable(source, conn, compact({
 		items: protectOptions?.items,

package/dist/run-CNsApDpd.js

@@ -0,0 +1 @@
+export { t as run } from "./run-DOfMtc9V.js";