@authup/access 1.0.0-beta.49 → 1.0.0-beta.51

package/dist/index.mjs

@@ -1,5 +1,6 @@
 import { AuthupError, ErrorCode, hasInstanceof, isAuthupError, markInstanceof } from "@authup/errors";
 import { DecisionStrategy, flattenObject, hasOwnProperty, isObject } from "@authup/kit";
+import { isEqual } from "smob";
 import { Container, defineIssueGroup, defineIssueItem } from "validup";
 import { createValidator } from "@validup/zod";
 import { z } from "zod";
@@ -58,12 +59,102 @@ function isPermissionError(input) {
 	return input.code === ErrorCode.PERMISSION_NOT_FOUND || input.code === ErrorCode.PERMISSION_DENIED || input.code === ErrorCode.PERMISSION_EVALUATION_FAILED;
 }
 //#endregion
-//#region src/permission/helpers/equal.ts
-function isPermissionPolicyBindingEqual(a, b) {
-	if (a.permission.name !== b.permission.name) return false;
-	if ((a.permission.realm_id ?? null) !== (b.permission.realm_id ?? null)) return false;
-	if ((a.permission.client_id ?? null) !== (b.permission.client_id ?? null)) return false;
-	return true;
+//#region src/permission/realm-scope/constants.ts
+/**
+* Actor-relative realm reach of a permission grant.
+*
+* Total order (least -> most permissive): none < own < ownOrNull < any.
+* A missing/unknown column coerces to `own` (fail-closed); `none` is only ever an
+* explicit value (the grant reaches no realm at all).
+*/
+let RealmScope = /* @__PURE__ */ function(RealmScope) {
+	/** No reach — the grant matches no resource realm. */
+	RealmScope["NONE"] = "none";
+	/** Own realm only — resource realm must equal the actor's realm. */
+	RealmScope["OWN"] = "own";
+	/** Own realm or null/global resources (realm_id === null). */
+	RealmScope["OWN_OR_NULL"] = "ownOrNull";
+	/** Any realm, including null/global. */
+	RealmScope["ANY"] = "any";
+	return RealmScope;
+}({});
+/** Numeric restrictiveness order — internal to the fold/compare helpers. */
+const REALM_SCOPE_ORDER = {
+	["none"]: 0,
+	["own"]: 1,
+	["ownOrNull"]: 2,
+	["any"]: 3
+};
+//#endregion
+//#region src/permission/realm-scope/helpers.ts
+/**
+* Coerce an arbitrary value to a RealmScope, defaulting to `own` for missing /
+* null / unknown input (fail-closed). `none` is honoured only when explicit.
+*/
+function normalizeRealmScope(value) {
+	return value === "any" || value === "ownOrNull" || value === "none" ? value : "own";
+}
+/**
+* Numeric comparison of two realm scopes by restrictiveness.
+* Negative when `a` is more restrictive than `b`, positive when less.
+*/
+function compareRealmScope(a, b) {
+	return REALM_SCOPE_ORDER[normalizeRealmScope(a)] - REALM_SCOPE_ORDER[normalizeRealmScope(b)];
+}
+/** Fold scopes to the MOST permissive (ordered max). Empty folds to `own`. */
+function maxRealmScope(values) {
+	let max = "none";
+	let seen = false;
+	for (const value of values) {
+		seen = true;
+		const scope = normalizeRealmScope(value);
+		if (REALM_SCOPE_ORDER[scope] > REALM_SCOPE_ORDER[max]) max = scope;
+	}
+	return seen ? max : "own";
+}
+/** Fold scopes to the MORE restrictive (ordered min) — used to CAP a grant. Empty folds to `own`. */
+function minRealmScope(values) {
+	let min = "any";
+	let seen = false;
+	for (const value of values) {
+		seen = true;
+		const scope = normalizeRealmScope(value);
+		if (REALM_SCOPE_ORDER[scope] < REALM_SCOPE_ORDER[min]) min = scope;
+	}
+	return seen ? min : "own";
+}
+/**
+* Whether `scope` reaches a single resource realm `resourceRealmId` for an actor whose
+* realm is `identityRealmId`/`identityRealmName`.
+*
+* - `any`         -> always.
+* - `none`        -> never.
+* - realm-less actor (no realmId and no realmName) -> never `own`/`ownOrNull`.
+* - resource realm `null` (global) -> only `ownOrNull`.
+* - concrete resource realm -> must equal the actor's own realm (by id or name).
+*/
+function matchesSingle(normalized, resourceRealmId, identityRealmId, identityRealmName) {
+	if (resourceRealmId === null) return normalized === "ownOrNull";
+	return resourceRealmId === identityRealmId || resourceRealmId === identityRealmName;
+}
+/**
+* Whether `scope` reaches the resource. The resource realm may be presented as a single
+* id, `null` (global), or an array of realm ids — the array form (a resource that spans
+* multiple realms) requires the scope to reach EVERY listed realm (unanimous, fail-closed),
+* so any app/entity can express its realm via one or many keys under the canonical contract.
+*/
+function realmScopeMatches(scope, resourceRealmId, identityRealmId, identityRealmName) {
+	const normalized = normalizeRealmScope(scope);
+	if (normalized === "any") return true;
+	if (normalized === "none") return false;
+	const realmId = identityRealmId ?? null;
+	const realmName = identityRealmName ?? null;
+	if (realmId === null && realmName === null) return false;
+	if (Array.isArray(resourceRealmId)) {
+		if (resourceRealmId.length === 0) return false;
+		return resourceRealmId.every((id) => matchesSingle(normalized, id ?? null, realmId, realmName));
+	}
+	return matchesSingle(normalized, resourceRealmId ?? null, realmId, realmName);
 }
 //#endregion
 //#region src/permission/helpers/key.ts
@@ -74,8 +165,34 @@ function buildPermissionKey(input) {
 	return `${formatKeySegment(input.realm_id)}/${formatKeySegment(input.client_id)}/${input.name}`;
 }
 //#endregion
-//#region src/permission/helpers/merge.ts
-function mergePermissionPolicyBindings(input) {
+//#region src/permission/helpers/aggregate.ts
+/**
+* One disjunction term per raw binding: the grant's realm reach (fail-closed `own` default)
+* paired with its policy — the raw single policy (its `id` preserved for junction propagation),
+* a composite over multiple policies (Layer-1 permission policies, combined under the
+* permission's decision_strategy), or `undefined` when the grant is unrestricted.
+*/
+function buildGrant(binding) {
+	let policy;
+	if (binding.policies && binding.policies.length === 1) policy = binding.policies[0];
+	else if (binding.policies && binding.policies.length > 1) policy = {
+		type: "composite",
+		decision_strategy: binding.permission.decision_strategy || DecisionStrategy.UNANIMOUS,
+		children: binding.policies
+	};
+	return {
+		realm_scope: normalizeRealmScope(binding.realm_scope),
+		policy
+	};
+}
+/**
+* Group raw permission-policy bindings by permission key into the actor's disjunction of
+* `(realm_scope, policy)` grants per permission — with NO lossy collapse. Every consumer
+* (the binding evaluator, isSuperset, junction propagation, the memory provider) evaluates the
+* grant disjunction directly, so each grant's realm reach stays paired with the policy that
+* gates it.
+*/
+function aggregatePermissionPolicyBindings(input) {
 	const grouped = input.reduce((previous, current) => {
 		const key = buildPermissionKey(current.permission);
 		if (!previous[key]) previous[key] = [];
@@ -83,41 +200,115 @@ function mergePermissionPolicyBindings(input) {
 		return previous;
 	}, {});
 	const output = [];
-	const keys = Object.keys(grouped);
-	for (const key of keys) {
+	for (const key of Object.keys(grouped)) {
 		const group = grouped[key];
-		const first = group[0];
-		if (group.length === 1) {
-			output.push(first);
-			continue;
-		}
-		const children = [];
-		for (const element of group) {
-			if (!element.policies || element.policies.length === 0) continue;
-			const policy = {
-				type: "composite",
-				decision_strategy: element.permission.decision_strategy || DecisionStrategy.UNANIMOUS,
-				children: element.policies
-			};
-			children.push(policy);
-		}
-		let mergedPolicies;
-		if (children.length > 0 && children.length === group.length) mergedPolicies = [{
-			type: "composite",
-			decision_strategy: DecisionStrategy.AFFIRMATIVE,
-			children
-		}];
 		output.push({
-			permission: {
-				...first.permission,
-				decision_strategy: DecisionStrategy.AFFIRMATIVE
-			},
-			policies: mergedPolicies
+			permission: group[0].permission,
+			grants: group.map(buildGrant)
 		});
 	}
 	return output;
 }
 //#endregion
+//#region src/permission/helpers/equal.ts
+function isPermissionPolicyBindingEqual(a, b) {
+	if (a.permission.name !== b.permission.name) return false;
+	if ((a.permission.realm_id ?? null) !== (b.permission.realm_id ?? null)) return false;
+	if ((a.permission.client_id ?? null) !== (b.permission.client_id ?? null)) return false;
+	return true;
+}
+//#endregion
+//#region src/permission/helpers/grant.ts
+/**
+* Policy fields that do NOT affect evaluation — persisted identity, audit and label columns plus
+* the loaded `parent` / `realm` relation objects. They are stripped before the structural compare
+* in isPolicyEquivalent so two DISTINCT rows with identical configuration still match. Verified
+* against every built-in evaluator, which read only `type`, `invert`, `decision_strategy`,
+* `children` and the type-specific config (query / names / types / start / end / interval /
+* day_of_* / attribute_name* / scope). `parent` is additionally a circular back-reference and
+* `realm` a nested object with its own id, so leaving either in would break the deep compare.
+*
+* SECURITY INVARIANT: every key here MUST stay non-evaluation-affecting. Adding an
+* evaluation-relevant field would silently widen equivalence into an over-permit. New *config*
+* fields need NOT be added — they are compared by default, which is the fail-closed direction.
+*/
+const NON_SEMANTIC_POLICY_KEYS = /* @__PURE__ */ new Set([
+	"id",
+	"built_in",
+	"name",
+	"display_name",
+	"description",
+	"parent_id",
+	"parent",
+	"realm_id",
+	"realm",
+	"created_at",
+	"updated_at"
+]);
+/**
+* Project a policy node onto its evaluation-relevant configuration: drop the non-semantic keys
+* and recurse through `children` (the only field that carries nested policy nodes). Config values
+* (e.g. an `attributes` `query`) are left untouched, so a semantic `id` / `name` key *inside* a
+* query is never mistaken for the policy's own identity column.
+*/
+function normalizePolicyForEquality(policy) {
+	const result = {};
+	for (const key of Object.keys(policy)) {
+		if (NON_SEMANTIC_POLICY_KEYS.has(key)) continue;
+		const value = policy[key];
+		if (key === "children" && Array.isArray(value)) {
+			result[key] = value.map((child) => normalizePolicyForEquality(child));
+			continue;
+		}
+		result[key] = value;
+	}
+	return result;
+}
+/**
+* Whether two restriction policies are provably the SAME policy for domination purposes — by
+* persisted identity OR by identical configuration, never by evaluated effect. Fast path: equal
+* primary-key `id` means the same persisted row (the `typeof … === 'string'` guards keep an
+* id-less / missing-id policy out of it — never `undefined === undefined`). Otherwise fall back to
+* a structural value-compare of the configuration (`normalizePolicyForEquality` strips the
+* non-semantic identity / audit / relation columns, `isEqual` deep-compares the rest), so two
+* distinct rows with identical config — the same predicate — still dominate. Comparing by
+* *effect* is undecidable (a policy is a predicate over PolicyData), so we accept ONLY provable
+* identity or provable structural equality; a genuinely different configuration is treated as
+* distinct (fail-closed) — isSuperset must never assume one restriction covers a different one.
+*/
+function isPolicyEquivalent(parent, child) {
+	const parentId = parent.id;
+	const childId = child.id;
+	if (typeof parentId === "string" && typeof childId === "string" && parentId === childId) return true;
+	return isEqual(normalizePolicyForEquality(parent), normalizePolicyForEquality(child));
+}
+/**
+* Whether the actor's `parent` policy provably covers the target's `child` policy on a shared
+* permission. Conservative / fail-closed:
+*  - an unrestricted parent (no policy) covers any child;
+*  - a restricted parent NEVER covers an unrestricted child — it cannot confer the wider,
+*    policy-free reach it does not itself hold;
+*  - two restricted grants cover one another only when their policies are provably equivalent.
+*    A DIFFERENT policy is NOT assumed to be a subset (#3159: the predecessor treated any two
+*    policy-bound grants as mutually dominating, a latent over-permit across disjoint policy
+*    scopes — e.g. an actor restricted to `department=X` conferring a `department=Y` grant).
+*/
+function policyDominates(parent, child) {
+	if (!parent) return true;
+	if (!child) return false;
+	return isPolicyEquivalent(parent, child);
+}
+/**
+* Whether the actor's `parent` grant covers the target's `child` grant: it reaches at least as
+* far (ordered none < own < ownOrNull < any) AND its policy provably covers the child's
+* (see `policyDominates`). Used per grant by `isSuperset` over the aggregated disjunction —
+* every child grant must be dominated by SOME parent grant.
+*/
+function grantDominates(parent, child) {
+	if (compareRealmScope(parent.realm_scope, child.realm_scope) < 0) return false;
+	return policyDominates(parent.policy, child.policy);
+}
+//#endregion
 //#region src/permission/provider/memory.ts
 var PermissionMemoryProvider = class {
 	items = {};
@@ -135,7 +326,7 @@ var PermissionMemoryProvider = class {
 		return null;
 	}
 	setMany(input) {
-		this.items = mergePermissionPolicyBindings(input).reduce((prev, current) => {
+		this.items = aggregatePermissionPolicyBindings(input).reduce((prev, current) => {
 			const key = buildPermissionKey(current.permission);
 			prev[key] = current;
 			return prev;
@@ -402,8 +593,6 @@ const SystemPolicyName = {
 	IDENTITY: "system.identity",
 	PERMISSION_BINDING: "system.permission-binding",
 	REALM_MATCH: "system.realm-match",
-	REALM_BOUND: "system.realm-bound",
-	REALM_OR_GLOBAL: "system.realm-or-global",
 	CLIENT_NAMES_SELF_MANAGE: "system.client-names-self-manage",
 	ROBOT_NAMES_SELF_MANAGE: "system.robot-names-self-manage",
 	USER_NAMES_SELF_MANAGE: "system.user-names-self-manage"
@@ -708,7 +897,7 @@ var RealmMatchPolicyValidator = class extends Container {
 		this.mount("attribute_name", createValidator(z.string().min(3).or(z.array(z.string().min(3))).or(z.null()).or(z.undefined()).optional()));
 		this.mount("attribute_name_strict", createValidator(z.boolean().or(z.null()).or(z.undefined()).optional()));
 		this.mount("attribute_null_match_all", createValidator(z.boolean().or(z.null()).or(z.undefined()).optional()));
-		this.mount("identity_master_match_all", createValidator(z.boolean().or(z.null()).or(z.undefined()).optional()));
+		this.mount("scope", createValidator(z.enum(RealmScope).or(z.null()).or(z.undefined()).optional()));
 		this.mount("invert", createValidator(z.boolean().or(z.null()).or(z.undefined()).optional()));
 	}
 };
@@ -734,6 +923,11 @@ var RealmMatchPolicyEvaluator = class {
 				path: ctx.path
 			})]
 		};
+		if (policy.scope) {
+			if (!ctx.data || !ctx.data.has("realmMatch")) return { success: true };
+			const resourceRealm = ctx.data.get("realmMatch");
+			return { success: maybeInvertPolicyOutcome(realmScopeMatches(policy.scope, resourceRealm ?? null, identity.realmId, identity.realmName), policy.invert) };
+		}
 		const attributes = await this.attributesEvaluator.accessData(ctx);
 		if (!attributes) return {
 			success: false,
@@ -743,7 +937,6 @@ var RealmMatchPolicyEvaluator = class {
 				path: ctx.path
 			})]
 		};
-		if ((policy.identity_master_match_all ?? true) && identity.realmName && identity.realmName === "master") return { success: true };
 		let keys;
 		if (policy.attribute_name) if (Array.isArray(policy.attribute_name)) keys = policy.attribute_name;
 		else keys = [policy.attribute_name];
@@ -910,6 +1103,18 @@ const PolicyDefaultEvaluators = {
 	["time"]: new TimePolicyEvaluator()
 };
 //#endregion
+//#region src/policy/input.ts
+/**
+* Build a {@link PolicyData} bag from a typed {@link PolicyInput} seed. Well-known keys
+* (identity / attributes / realmMatch) are type-checked; unknown keys are accepted as-is.
+*
+* Prefer this over `new PolicyData({ ... })` at construction sites so the key vocabulary and
+* per-key value types live in one place.
+*/
+function definePolicyData(input = {}) {
+	return new PolicyData(input);
+}
+//#endregion
 //#region src/permission/evaluator/module.ts
 var PermissionEvaluator = class {
 	provider;
@@ -942,7 +1147,7 @@ var PermissionEvaluator = class {
 		const decisionStrategy = options.decisionStrategy ?? DecisionStrategy.UNANIMOUS;
 		const issues = [];
 		let count = 0;
-		const dataBase = ctx.input || new PolicyData();
+		const dataBase = ctx.data || new PolicyData();
 		for (const name of ctx.name) {
 			const binding = await this.findOne(name, {
 				realmId: ctx.realmId,
@@ -961,8 +1166,8 @@ var PermissionEvaluator = class {
 				}
 				continue;
 			}
-			const policies = binding.policies ?? [];
-			if (policies.length === 0) {
+			const grantPolicies = binding.grants.map((grant) => grant.policy).filter((grantPolicy) => !!grantPolicy);
+			if (grantPolicies.length < binding.grants.length) {
 				if (decisionStrategy === DecisionStrategy.AFFIRMATIVE) return;
 				count++;
 				continue;
@@ -971,8 +1176,8 @@ var PermissionEvaluator = class {
 			data.set("permissionBinding", binding);
 			const compositePolicy = {
 				type: "composite",
-				decision_strategy: binding.permission.decision_strategy ?? DecisionStrategy.UNANIMOUS,
-				children: policies
+				decision_strategy: DecisionStrategy.AFFIRMATIVE,
+				children: grantPolicies
 			};
 			const evaluationResult = await this.policyEngine.evaluate(compositePolicy, definePolicyEvaluationContext({
 				include: options.policiesIncluded,
@@ -1038,6 +1243,6 @@ var PermissionEvaluator = class {
 	}
 };
 //#endregion
-export { AttributeNamesPolicyEvaluator, AttributeNamesPolicyValidator, AttributesPolicyEvaluator, AttributesPolicyValidator, BuiltInPolicyType, CompositePolicyEvaluator, CompositePolicyValidator, DatePolicyEvaluator, DatePolicyValidator, IdentityPolicyEvaluator, IdentityPolicyValidator, PERMISSION_ERROR_INSTANCE, POLICY_ERROR_INSTANCE, PermissionBindingPolicyEvaluator, PermissionBindingPolicyValidator, PermissionError, PermissionEvaluator, PermissionMemoryProvider, PolicyData, PolicyDefaultEvaluators, PolicyEngine, PolicyError, PolicyIssueCode, PolicyIssueSeverity, RealmMatchPolicyEvaluator, RealmMatchPolicyValidator, SystemPolicyName, TimePolicyEvaluator, TimePolicyInterval, TimePolicyValidator, buildPermissionKey, defineAttributesPolicy, definePolicyEvaluationContext, definePolicyIssueGroup, definePolicyIssueItem, definePolicyWithType, isCompositePolicy, isIntervalForDayOfMonth, isIntervalForDayOfWeek, isIntervalForDayOfYear, isPermissionError, isPermissionPolicyBindingEqual, isPolicyError, maybeInvertPolicyOutcome, mergePermissionPolicyBindings };
+export { AttributeNamesPolicyEvaluator, AttributeNamesPolicyValidator, AttributesPolicyEvaluator, AttributesPolicyValidator, BuiltInPolicyType, CompositePolicyEvaluator, CompositePolicyValidator, DatePolicyEvaluator, DatePolicyValidator, IdentityPolicyEvaluator, IdentityPolicyValidator, PERMISSION_ERROR_INSTANCE, POLICY_ERROR_INSTANCE, PermissionBindingPolicyEvaluator, PermissionBindingPolicyValidator, PermissionError, PermissionEvaluator, PermissionMemoryProvider, PolicyData, PolicyDefaultEvaluators, PolicyEngine, PolicyError, PolicyIssueCode, PolicyIssueSeverity, REALM_SCOPE_ORDER, RealmMatchPolicyEvaluator, RealmMatchPolicyValidator, RealmScope, SystemPolicyName, TimePolicyEvaluator, TimePolicyInterval, TimePolicyValidator, aggregatePermissionPolicyBindings, buildPermissionKey, compareRealmScope, defineAttributesPolicy, definePolicyData, definePolicyEvaluationContext, definePolicyIssueGroup, definePolicyIssueItem, definePolicyWithType, grantDominates, isCompositePolicy, isIntervalForDayOfMonth, isIntervalForDayOfWeek, isIntervalForDayOfYear, isPermissionError, isPermissionPolicyBindingEqual, isPolicyError, maxRealmScope, maybeInvertPolicyOutcome, minRealmScope, normalizeRealmScope, realmScopeMatches };
 
 //# sourceMappingURL=index.mjs.map