@aooth/arbac 0.1.66 → 0.1.68

package/dist/index.cjs

@@ -158,17 +158,8 @@ function getProjectionMode(proj) {
 function isFieldAllowed(field, projection) {
 	const mode = getProjectionMode(projection);
 	if (mode === "empty") return true;
-	if (mode === "include") {
-		if (projection[field] === 1) return true;
-		const parts = field.split(".");
-		for (let i = 1; i < parts.length; i++) if (projection[parts.slice(0, i).join(".")] === 1) return true;
-		for (const key of Object.keys(projection)) if (key.startsWith(`${field}.`)) return true;
-		return false;
-	}
-	if (projection[field] === 0) return false;
-	const parts = field.split(".");
-	for (let i = 1; i < parts.length; i++) if (projection[parts.slice(0, i).join(".")] === 0) return false;
-	return true;
+	if (mode === "exclude") return !coversPath(projection, field);
+	return coversPath(projection, field) || descendantKeys(Object.keys(projection), field).length > 0;
 }
 /**
 * Combines projections from multiple RBAC role grants under additive semantics:
@@ -220,51 +211,132 @@ function unionProjections(...projections) {
 		if (includeKeys.size === 0) return {};
 		return Object.fromEntries([...includeKeys].toSorted().map((k) => [k, 1]));
 	}
-	let denyAcc = new Set(excludeKeys[0]);
-	for (let i = 1; i < excludeKeys.length; i++) denyAcc = new Set([...denyAcc].filter((k) => excludeKeys[i].has(k)));
-	const effectivelyExcluded = [...denyAcc].filter((k) => !includeKeys.has(k)).toSorted();
+	const candidates = /* @__PURE__ */ new Set();
+	for (const set of excludeKeys) for (const k of set) candidates.add(k);
+	const effectivelyExcluded = [...candidates].filter((k) => excludeKeys.every((set) => coversPath(set, k))).filter((k) => !coversPath(includeKeys, k)).toSorted();
 	if (effectivelyExcluded.length === 0) return {};
 	return Object.fromEntries(effectivelyExcluded.map((k) => [k, 0]));
 }
+/** `path` itself or one of its ancestors is a key of `keys` (own keys only). */
+function coversPath(keys, path) {
+	const has = keys instanceof Set ? (k) => keys.has(k) : (k) => Object.hasOwn(keys, k);
+	if (has(path)) return true;
+	let pos = path.length;
+	while ((pos = path.lastIndexOf(".", pos - 1)) !== -1) if (has(path.slice(0, pos))) return true;
+	return false;
+}
+/** The `keys` strictly below `path` (`a` → `a.b`, `a.b.c`). */
+function descendantKeys(keys, path) {
+	const prefix = `${path}.`;
+	return keys.filter((k) => k.startsWith(prefix));
+}
+/** Schema recursion bound — a guard against a cyclic `childrenOf`. */
+const MAX_SCHEMA_DEPTH = 32;
+/**
+* Depth-first walk from `root` through its schema children. `visit` gets each
+* path with its children (`[]` for a leaf, an unknown schema, or past
+* {@link MAX_SCHEMA_DEPTH}) and returns whether to descend into them.
+*/
+function walkSchema(root, childrenOf, visit) {
+	const go = (path, depth) => {
+		const children = depth < MAX_SCHEMA_DEPTH ? childrenOf?.(path) ?? [] : [];
+		if (visit(path, children)) for (const child of children) go(child, depth + 1);
+	};
+	go(root, 0);
+}
+/** Include-mode `inc` minus exclude-mode `exc`, by path. */
+function includeMinusExclude(inc, exc, childrenOf) {
+	const excKeys = Object.keys(exc);
+	const out = {};
+	for (const key of Object.keys(inc)) walkSchema(key, childrenOf, (path) => {
+		if (coversPath(exc, path)) return false;
+		if (descendantKeys(excKeys, path).length === 0) {
+			out[path] = 1;
+			return false;
+		}
+		return true;
+	});
+	return out;
+}
+/**
+* Rewrite an exclusion projection so every excluded nested-object parent is
+* named by its LEAF paths (`{ a: 0 }` → `{ "a.b": 0, "a.c": 0 }`), via the
+* schema. Flattening storage adapters invert an exclusion against their leaf
+* columns, so a parent key alone would strip nothing. Without `childrenOf`,
+* or for an inclusion / empty projection, the input is returned unchanged.
+*/
+function expandExcludeToLeaves(projection, childrenOf) {
+	if (!childrenOf || getProjectionMode(projection) !== "exclude") return projection;
+	const out = {};
+	for (const key of Object.keys(projection)) walkSchema(key, childrenOf, (path, children) => {
+		if (children.length === 0) out[path] = 0;
+		return children.length > 0;
+	});
+	return out;
+}
+/**
+* The exact field intersection of two projections, by PATH — never wider than
+* either side. Returns `null` when no field survives (a disjoint pair, or
+* `{a:1}` ∩ `{a:0}`); `{}` only when BOTH sides are unrestricted.
+*
+* - include ∩ include: a key survives when the other side includes it or an
+*   ancestor; when the other side only includes DESCENDANTS of it, those
+*   descendants survive instead (`{a:1}` ∩ `{"a.b":1}` → `{"a.b":1}`).
+* - include ∩ exclude: include keys minus excluded paths. An include key with
+*   an excluded DESCENDANT (`{a:1}` ∩ `{"a.c":0}`) is split via `childrenOf`
+*   (→ `{"a.b":1}`); without a schema it is dropped (fail closed).
+* - exclude ∩ exclude: union of the excluded keys.
+*
+* @param childrenOf - optional schema lookup for exact nested subtraction
+*/
+function intersectProjections(a, b, childrenOf) {
+	const aMode = getProjectionMode(a);
+	const bMode = getProjectionMode(b);
+	if (aMode === "empty") return { ...b };
+	if (bMode === "empty") return { ...a };
+	let out;
+	if (aMode === "include" && bMode === "include") {
+		out = {};
+		const bKeys = Object.keys(b);
+		for (const key of Object.keys(a)) if (coversPath(b, key)) out[key] = 1;
+		else for (const d of descendantKeys(bKeys, key)) out[d] = 1;
+	} else if (aMode === "exclude" && bMode === "exclude") {
+		out = {};
+		for (const key of [...Object.keys(a), ...Object.keys(b)]) out[key] = 0;
+	} else if (aMode === "include") out = includeMinusExclude(a, b, childrenOf);
+	else out = includeMinusExclude(b, a, childrenOf);
+	return Object.keys(out).length > 0 ? out : null;
+}
 /**
 * Restrict a desired projection to only fields allowed by an access-control projection.
 *
-* The result is the intersection of the two projections: only fields that pass both
-* `desired` and `accessControl` survive. Either side may be empty (unrestricted), in
-* which case the other side is returned. Mixed include/exclude modes are normalized
-* to a single result projection.
+* The result is the path-wise intersection ({@link intersectProjections}):
+* only fields that pass both `desired` and `accessControl` survive, and a
+* requested parent narrows to the access-controlled descendants
+* (`{a:1}` against `{"a.b":1}` → `{"a.b":1}`). Either side may be empty
+* (unrestricted), in which case the other side is returned.
+*
+* When NO field survives, the result is `accessControl` itself — never the
+* empty (universe) projection. That fallback is safe only because
+* `accessControl` is the ceiling; to conjoin two ceilings (attenuation), use
+* {@link intersectProjections} and handle its `null`.
 *
 * @param desired - the projection the caller asked for
 * @param accessControl - the projection allowed by RBAC
+* @param childrenOf - optional schema lookup for exact nested subtraction
 */
-function restrictProjection(desired, accessControl) {
-	const desiredMode = getProjectionMode(desired);
-	const acMode = getProjectionMode(accessControl);
-	if (acMode === "empty") return { ...desired };
-	if (desiredMode === "empty") return { ...accessControl };
-	if (desiredMode === "include" && acMode === "include") {
-		const result = {};
-		for (const key of Object.keys(desired)) if (isFieldAllowed(key, accessControl)) result[key] = 1;
-		return result;
-	}
-	if (desiredMode === "exclude" && acMode === "exclude") {
-		const result = {};
-		for (const key of Object.keys(desired)) result[key] = 0;
-		for (const key of Object.keys(accessControl)) result[key] = 0;
-		return result;
-	}
-	if (desiredMode === "include" && acMode === "exclude") {
-		const result = {};
-		for (const key of Object.keys(desired)) if (isFieldAllowed(key, accessControl)) result[key] = 1;
-		return result;
-	}
-	const result = {};
-	for (const key of Object.keys(accessControl)) if (isFieldAllowed(key, desired)) result[key] = 1;
-	return result;
+function restrictProjection(desired, accessControl, childrenOf) {
+	return intersectProjections(desired, accessControl, childrenOf) ?? { ...accessControl };
 }
 //#endregion
 //#region src/scope/filter.ts
 /**
+* A filter that matches no rows (`{ $or: [] }`) — what a denied read, or a
+* conjunction whose field intersection is empty, filters by. Shared; never
+* mutate it.
+*/
+const DENY_FILTER = { $or: [] };
+/**
 * Merge multiple scope filters into a single filter using `$or` semantics.
 *
 * In RBAC, if multiple roles grant access with different filters,
@@ -521,16 +593,19 @@ function generateResourceTypes(map, options) {
 	return lines.join("\n");
 }
 //#endregion
+exports.DENY_FILTER = DENY_FILTER;
 exports.allowTableAction = allowTableAction;
 exports.allowTableRead = allowTableRead;
 exports.allowTableWrite = allowTableWrite;
 exports.conjoinScopeFilters = conjoinScopeFilters;
 exports.definePrivilege = definePrivilege;
 exports.defineRole = defineRole;
+exports.expandExcludeToLeaves = expandExcludeToLeaves;
 exports.extractResourceActions = extractResourceActions;
 exports.generateResourceTypes = generateResourceTypes;
 exports.getProjectionMode = getProjectionMode;
 exports.intersectControlsPolicy = intersectControlsPolicy;
+exports.intersectProjections = intersectProjections;
 exports.isFieldAllowed = isFieldAllowed;
 exports.mergeScopeFilters = mergeScopeFilters;
 exports.restrictProjection = restrictProjection;

package/dist/index.d.cts

@@ -175,20 +175,63 @@ declare function isFieldAllowed(field: string, projection: TProjection): boolean
  * @throws when a single projection mixes 1 and 0 keys, or contains an invalid value
  */
 declare function unionProjections(...projections: TProjection[]): TProjection;
+/**
+ * Direct child field paths of a nested-object path (`a` → `["a.b", "a.c"]`),
+ * from the model schema; `[]` for a leaf. Lets a projection intersection
+ * subtract a nested exclusion from an included parent exactly.
+ */
+type TProjectionChildren = (path: string) => readonly string[];
+/**
+ * Rewrite an exclusion projection so every excluded nested-object parent is
+ * named by its LEAF paths (`{ a: 0 }` → `{ "a.b": 0, "a.c": 0 }`), via the
+ * schema. Flattening storage adapters invert an exclusion against their leaf
+ * columns, so a parent key alone would strip nothing. Without `childrenOf`,
+ * or for an inclusion / empty projection, the input is returned unchanged.
+ */
+declare function expandExcludeToLeaves(projection: TProjection, childrenOf: TProjectionChildren | undefined): TProjection;
+/**
+ * The exact field intersection of two projections, by PATH — never wider than
+ * either side. Returns `null` when no field survives (a disjoint pair, or
+ * `{a:1}` ∩ `{a:0}`); `{}` only when BOTH sides are unrestricted.
+ *
+ * - include ∩ include: a key survives when the other side includes it or an
+ *   ancestor; when the other side only includes DESCENDANTS of it, those
+ *   descendants survive instead (`{a:1}` ∩ `{"a.b":1}` → `{"a.b":1}`).
+ * - include ∩ exclude: include keys minus excluded paths. An include key with
+ *   an excluded DESCENDANT (`{a:1}` ∩ `{"a.c":0}`) is split via `childrenOf`
+ *   (→ `{"a.b":1}`); without a schema it is dropped (fail closed).
+ * - exclude ∩ exclude: union of the excluded keys.
+ *
+ * @param childrenOf - optional schema lookup for exact nested subtraction
+ */
+declare function intersectProjections(a: TProjection, b: TProjection, childrenOf?: TProjectionChildren): TProjection | null;
 /**
  * Restrict a desired projection to only fields allowed by an access-control projection.
  *
- * The result is the intersection of the two projections: only fields that pass both
- * `desired` and `accessControl` survive. Either side may be empty (unrestricted), in
- * which case the other side is returned. Mixed include/exclude modes are normalized
- * to a single result projection.
+ * The result is the path-wise intersection ({@link intersectProjections}):
+ * only fields that pass both `desired` and `accessControl` survive, and a
+ * requested parent narrows to the access-controlled descendants
+ * (`{a:1}` against `{"a.b":1}` → `{"a.b":1}`). Either side may be empty
+ * (unrestricted), in which case the other side is returned.
+ *
+ * When NO field survives, the result is `accessControl` itself — never the
+ * empty (universe) projection. That fallback is safe only because
+ * `accessControl` is the ceiling; to conjoin two ceilings (attenuation), use
+ * {@link intersectProjections} and handle its `null`.
  *
  * @param desired - the projection the caller asked for
  * @param accessControl - the projection allowed by RBAC
+ * @param childrenOf - optional schema lookup for exact nested subtraction
  */
-declare function restrictProjection(desired: TProjection, accessControl: TProjection): TProjection;
+declare function restrictProjection(desired: TProjection, accessControl: TProjection, childrenOf?: TProjectionChildren): TProjection;
 //#endregion
 //#region src/scope/filter.d.ts
+/**
+ * A filter that matches no rows (`{ $or: [] }`) — what a denied read, or a
+ * conjunction whose field intersection is empty, filters by. Shared; never
+ * mutate it.
+ */
+declare const DENY_FILTER: Readonly<TScopeFilter>;
 /**
  * Merge multiple scope filters into a single filter using `$or` semantics.
  *
@@ -318,4 +361,4 @@ interface TCodegenOptions {
  */
 declare function generateResourceTypes(map: TResourceActionMap, options?: TCodegenOptions): string;
 //#endregion
-export { type ControlGate, type RoleBuilder, type TCodegenOptions, type TPrivilegeFunction, type TProjection, type TProjectionMode, type TResourceActionMap, type TScopeFilter, allowTableAction, allowTableRead, allowTableWrite, conjoinScopeFilters, definePrivilege, defineRole, extractResourceActions, generateResourceTypes, getProjectionMode, intersectControlsPolicy, isFieldAllowed, mergeScopeFilters, restrictProjection, unionControlsPolicy, unionProjections };
+export { type ControlGate, DENY_FILTER, type RoleBuilder, type TCodegenOptions, type TPrivilegeFunction, type TProjection, type TProjectionChildren, type TProjectionMode, type TResourceActionMap, type TScopeFilter, allowTableAction, allowTableRead, allowTableWrite, conjoinScopeFilters, definePrivilege, defineRole, expandExcludeToLeaves, extractResourceActions, generateResourceTypes, getProjectionMode, intersectControlsPolicy, intersectProjections, isFieldAllowed, mergeScopeFilters, restrictProjection, unionControlsPolicy, unionProjections };

package/dist/index.d.mts

@@ -175,20 +175,63 @@ declare function isFieldAllowed(field: string, projection: TProjection): boolean
  * @throws when a single projection mixes 1 and 0 keys, or contains an invalid value
  */
 declare function unionProjections(...projections: TProjection[]): TProjection;
+/**
+ * Direct child field paths of a nested-object path (`a` → `["a.b", "a.c"]`),
+ * from the model schema; `[]` for a leaf. Lets a projection intersection
+ * subtract a nested exclusion from an included parent exactly.
+ */
+type TProjectionChildren = (path: string) => readonly string[];
+/**
+ * Rewrite an exclusion projection so every excluded nested-object parent is
+ * named by its LEAF paths (`{ a: 0 }` → `{ "a.b": 0, "a.c": 0 }`), via the
+ * schema. Flattening storage adapters invert an exclusion against their leaf
+ * columns, so a parent key alone would strip nothing. Without `childrenOf`,
+ * or for an inclusion / empty projection, the input is returned unchanged.
+ */
+declare function expandExcludeToLeaves(projection: TProjection, childrenOf: TProjectionChildren | undefined): TProjection;
+/**
+ * The exact field intersection of two projections, by PATH — never wider than
+ * either side. Returns `null` when no field survives (a disjoint pair, or
+ * `{a:1}` ∩ `{a:0}`); `{}` only when BOTH sides are unrestricted.
+ *
+ * - include ∩ include: a key survives when the other side includes it or an
+ *   ancestor; when the other side only includes DESCENDANTS of it, those
+ *   descendants survive instead (`{a:1}` ∩ `{"a.b":1}` → `{"a.b":1}`).
+ * - include ∩ exclude: include keys minus excluded paths. An include key with
+ *   an excluded DESCENDANT (`{a:1}` ∩ `{"a.c":0}`) is split via `childrenOf`
+ *   (→ `{"a.b":1}`); without a schema it is dropped (fail closed).
+ * - exclude ∩ exclude: union of the excluded keys.
+ *
+ * @param childrenOf - optional schema lookup for exact nested subtraction
+ */
+declare function intersectProjections(a: TProjection, b: TProjection, childrenOf?: TProjectionChildren): TProjection | null;
 /**
  * Restrict a desired projection to only fields allowed by an access-control projection.
  *
- * The result is the intersection of the two projections: only fields that pass both
- * `desired` and `accessControl` survive. Either side may be empty (unrestricted), in
- * which case the other side is returned. Mixed include/exclude modes are normalized
- * to a single result projection.
+ * The result is the path-wise intersection ({@link intersectProjections}):
+ * only fields that pass both `desired` and `accessControl` survive, and a
+ * requested parent narrows to the access-controlled descendants
+ * (`{a:1}` against `{"a.b":1}` → `{"a.b":1}`). Either side may be empty
+ * (unrestricted), in which case the other side is returned.
+ *
+ * When NO field survives, the result is `accessControl` itself — never the
+ * empty (universe) projection. That fallback is safe only because
+ * `accessControl` is the ceiling; to conjoin two ceilings (attenuation), use
+ * {@link intersectProjections} and handle its `null`.
  *
  * @param desired - the projection the caller asked for
  * @param accessControl - the projection allowed by RBAC
+ * @param childrenOf - optional schema lookup for exact nested subtraction
  */
-declare function restrictProjection(desired: TProjection, accessControl: TProjection): TProjection;
+declare function restrictProjection(desired: TProjection, accessControl: TProjection, childrenOf?: TProjectionChildren): TProjection;
 //#endregion
 //#region src/scope/filter.d.ts
+/**
+ * A filter that matches no rows (`{ $or: [] }`) — what a denied read, or a
+ * conjunction whose field intersection is empty, filters by. Shared; never
+ * mutate it.
+ */
+declare const DENY_FILTER: Readonly<TScopeFilter>;
 /**
  * Merge multiple scope filters into a single filter using `$or` semantics.
  *
@@ -318,4 +361,4 @@ interface TCodegenOptions {
  */
 declare function generateResourceTypes(map: TResourceActionMap, options?: TCodegenOptions): string;
 //#endregion
-export { type ControlGate, type RoleBuilder, type TCodegenOptions, type TPrivilegeFunction, type TProjection, type TProjectionMode, type TResourceActionMap, type TScopeFilter, allowTableAction, allowTableRead, allowTableWrite, conjoinScopeFilters, definePrivilege, defineRole, extractResourceActions, generateResourceTypes, getProjectionMode, intersectControlsPolicy, isFieldAllowed, mergeScopeFilters, restrictProjection, unionControlsPolicy, unionProjections };
+export { type ControlGate, DENY_FILTER, type RoleBuilder, type TCodegenOptions, type TPrivilegeFunction, type TProjection, type TProjectionChildren, type TProjectionMode, type TResourceActionMap, type TScopeFilter, allowTableAction, allowTableRead, allowTableWrite, conjoinScopeFilters, definePrivilege, defineRole, expandExcludeToLeaves, extractResourceActions, generateResourceTypes, getProjectionMode, intersectControlsPolicy, intersectProjections, isFieldAllowed, mergeScopeFilters, restrictProjection, unionControlsPolicy, unionProjections };

package/dist/index.mjs

@@ -158,17 +158,8 @@ function getProjectionMode(proj) {
 function isFieldAllowed(field, projection) {
 	const mode = getProjectionMode(projection);
 	if (mode === "empty") return true;
-	if (mode === "include") {
-		if (projection[field] === 1) return true;
-		const parts = field.split(".");
-		for (let i = 1; i < parts.length; i++) if (projection[parts.slice(0, i).join(".")] === 1) return true;
-		for (const key of Object.keys(projection)) if (key.startsWith(`${field}.`)) return true;
-		return false;
-	}
-	if (projection[field] === 0) return false;
-	const parts = field.split(".");
-	for (let i = 1; i < parts.length; i++) if (projection[parts.slice(0, i).join(".")] === 0) return false;
-	return true;
+	if (mode === "exclude") return !coversPath(projection, field);
+	return coversPath(projection, field) || descendantKeys(Object.keys(projection), field).length > 0;
 }
 /**
 * Combines projections from multiple RBAC role grants under additive semantics:
@@ -220,51 +211,132 @@ function unionProjections(...projections) {
 		if (includeKeys.size === 0) return {};
 		return Object.fromEntries([...includeKeys].toSorted().map((k) => [k, 1]));
 	}
-	let denyAcc = new Set(excludeKeys[0]);
-	for (let i = 1; i < excludeKeys.length; i++) denyAcc = new Set([...denyAcc].filter((k) => excludeKeys[i].has(k)));
-	const effectivelyExcluded = [...denyAcc].filter((k) => !includeKeys.has(k)).toSorted();
+	const candidates = /* @__PURE__ */ new Set();
+	for (const set of excludeKeys) for (const k of set) candidates.add(k);
+	const effectivelyExcluded = [...candidates].filter((k) => excludeKeys.every((set) => coversPath(set, k))).filter((k) => !coversPath(includeKeys, k)).toSorted();
 	if (effectivelyExcluded.length === 0) return {};
 	return Object.fromEntries(effectivelyExcluded.map((k) => [k, 0]));
 }
+/** `path` itself or one of its ancestors is a key of `keys` (own keys only). */
+function coversPath(keys, path) {
+	const has = keys instanceof Set ? (k) => keys.has(k) : (k) => Object.hasOwn(keys, k);
+	if (has(path)) return true;
+	let pos = path.length;
+	while ((pos = path.lastIndexOf(".", pos - 1)) !== -1) if (has(path.slice(0, pos))) return true;
+	return false;
+}
+/** The `keys` strictly below `path` (`a` → `a.b`, `a.b.c`). */
+function descendantKeys(keys, path) {
+	const prefix = `${path}.`;
+	return keys.filter((k) => k.startsWith(prefix));
+}
+/** Schema recursion bound — a guard against a cyclic `childrenOf`. */
+const MAX_SCHEMA_DEPTH = 32;
+/**
+* Depth-first walk from `root` through its schema children. `visit` gets each
+* path with its children (`[]` for a leaf, an unknown schema, or past
+* {@link MAX_SCHEMA_DEPTH}) and returns whether to descend into them.
+*/
+function walkSchema(root, childrenOf, visit) {
+	const go = (path, depth) => {
+		const children = depth < MAX_SCHEMA_DEPTH ? childrenOf?.(path) ?? [] : [];
+		if (visit(path, children)) for (const child of children) go(child, depth + 1);
+	};
+	go(root, 0);
+}
+/** Include-mode `inc` minus exclude-mode `exc`, by path. */
+function includeMinusExclude(inc, exc, childrenOf) {
+	const excKeys = Object.keys(exc);
+	const out = {};
+	for (const key of Object.keys(inc)) walkSchema(key, childrenOf, (path) => {
+		if (coversPath(exc, path)) return false;
+		if (descendantKeys(excKeys, path).length === 0) {
+			out[path] = 1;
+			return false;
+		}
+		return true;
+	});
+	return out;
+}
+/**
+* Rewrite an exclusion projection so every excluded nested-object parent is
+* named by its LEAF paths (`{ a: 0 }` → `{ "a.b": 0, "a.c": 0 }`), via the
+* schema. Flattening storage adapters invert an exclusion against their leaf
+* columns, so a parent key alone would strip nothing. Without `childrenOf`,
+* or for an inclusion / empty projection, the input is returned unchanged.
+*/
+function expandExcludeToLeaves(projection, childrenOf) {
+	if (!childrenOf || getProjectionMode(projection) !== "exclude") return projection;
+	const out = {};
+	for (const key of Object.keys(projection)) walkSchema(key, childrenOf, (path, children) => {
+		if (children.length === 0) out[path] = 0;
+		return children.length > 0;
+	});
+	return out;
+}
+/**
+* The exact field intersection of two projections, by PATH — never wider than
+* either side. Returns `null` when no field survives (a disjoint pair, or
+* `{a:1}` ∩ `{a:0}`); `{}` only when BOTH sides are unrestricted.
+*
+* - include ∩ include: a key survives when the other side includes it or an
+*   ancestor; when the other side only includes DESCENDANTS of it, those
+*   descendants survive instead (`{a:1}` ∩ `{"a.b":1}` → `{"a.b":1}`).
+* - include ∩ exclude: include keys minus excluded paths. An include key with
+*   an excluded DESCENDANT (`{a:1}` ∩ `{"a.c":0}`) is split via `childrenOf`
+*   (→ `{"a.b":1}`); without a schema it is dropped (fail closed).
+* - exclude ∩ exclude: union of the excluded keys.
+*
+* @param childrenOf - optional schema lookup for exact nested subtraction
+*/
+function intersectProjections(a, b, childrenOf) {
+	const aMode = getProjectionMode(a);
+	const bMode = getProjectionMode(b);
+	if (aMode === "empty") return { ...b };
+	if (bMode === "empty") return { ...a };
+	let out;
+	if (aMode === "include" && bMode === "include") {
+		out = {};
+		const bKeys = Object.keys(b);
+		for (const key of Object.keys(a)) if (coversPath(b, key)) out[key] = 1;
+		else for (const d of descendantKeys(bKeys, key)) out[d] = 1;
+	} else if (aMode === "exclude" && bMode === "exclude") {
+		out = {};
+		for (const key of [...Object.keys(a), ...Object.keys(b)]) out[key] = 0;
+	} else if (aMode === "include") out = includeMinusExclude(a, b, childrenOf);
+	else out = includeMinusExclude(b, a, childrenOf);
+	return Object.keys(out).length > 0 ? out : null;
+}
 /**
 * Restrict a desired projection to only fields allowed by an access-control projection.
 *
-* The result is the intersection of the two projections: only fields that pass both
-* `desired` and `accessControl` survive. Either side may be empty (unrestricted), in
-* which case the other side is returned. Mixed include/exclude modes are normalized
-* to a single result projection.
+* The result is the path-wise intersection ({@link intersectProjections}):
+* only fields that pass both `desired` and `accessControl` survive, and a
+* requested parent narrows to the access-controlled descendants
+* (`{a:1}` against `{"a.b":1}` → `{"a.b":1}`). Either side may be empty
+* (unrestricted), in which case the other side is returned.
+*
+* When NO field survives, the result is `accessControl` itself — never the
+* empty (universe) projection. That fallback is safe only because
+* `accessControl` is the ceiling; to conjoin two ceilings (attenuation), use
+* {@link intersectProjections} and handle its `null`.
 *
 * @param desired - the projection the caller asked for
 * @param accessControl - the projection allowed by RBAC
+* @param childrenOf - optional schema lookup for exact nested subtraction
 */
-function restrictProjection(desired, accessControl) {
-	const desiredMode = getProjectionMode(desired);
-	const acMode = getProjectionMode(accessControl);
-	if (acMode === "empty") return { ...desired };
-	if (desiredMode === "empty") return { ...accessControl };
-	if (desiredMode === "include" && acMode === "include") {
-		const result = {};
-		for (const key of Object.keys(desired)) if (isFieldAllowed(key, accessControl)) result[key] = 1;
-		return result;
-	}
-	if (desiredMode === "exclude" && acMode === "exclude") {
-		const result = {};
-		for (const key of Object.keys(desired)) result[key] = 0;
-		for (const key of Object.keys(accessControl)) result[key] = 0;
-		return result;
-	}
-	if (desiredMode === "include" && acMode === "exclude") {
-		const result = {};
-		for (const key of Object.keys(desired)) if (isFieldAllowed(key, accessControl)) result[key] = 1;
-		return result;
-	}
-	const result = {};
-	for (const key of Object.keys(accessControl)) if (isFieldAllowed(key, desired)) result[key] = 1;
-	return result;
+function restrictProjection(desired, accessControl, childrenOf) {
+	return intersectProjections(desired, accessControl, childrenOf) ?? { ...accessControl };
 }
 //#endregion
 //#region src/scope/filter.ts
 /**
+* A filter that matches no rows (`{ $or: [] }`) — what a denied read, or a
+* conjunction whose field intersection is empty, filters by. Shared; never
+* mutate it.
+*/
+const DENY_FILTER = { $or: [] };
+/**
 * Merge multiple scope filters into a single filter using `$or` semantics.
 *
 * In RBAC, if multiple roles grant access with different filters,
@@ -521,4 +593,4 @@ function generateResourceTypes(map, options) {
 	return lines.join("\n");
 }
 //#endregion
-export { allowTableAction, allowTableRead, allowTableWrite, conjoinScopeFilters, definePrivilege, defineRole, extractResourceActions, generateResourceTypes, getProjectionMode, intersectControlsPolicy, isFieldAllowed, mergeScopeFilters, restrictProjection, unionControlsPolicy, unionProjections };
+export { DENY_FILTER, allowTableAction, allowTableRead, allowTableWrite, conjoinScopeFilters, definePrivilege, defineRole, expandExcludeToLeaves, extractResourceActions, generateResourceTypes, getProjectionMode, intersectControlsPolicy, intersectProjections, isFieldAllowed, mergeScopeFilters, restrictProjection, unionControlsPolicy, unionProjections };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aooth/arbac",
-  "version": "0.1.66",
+  "version": "0.1.68",
   "description": "Batteries-included RBAC: builder API, privilege factories, scope merge utilities",
   "keywords": [
     "access-control",
@@ -45,7 +45,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@aooth/arbac-core": "0.1.66"
+    "@aooth/arbac-core": "0.1.68"
   },
   "scripts": {
     "build": "vp pack",