@aooth/arbac 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 aoothjs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,38 @@
+<p align="center">
+  <a href="https://aooth.moost.org">
+    <img src="https://aooth.moost.org/logo.svg" alt="aoothjs" width="120" />
+  </a>
+</p>
+
+<h1 align="center">@aooth/arbac</h1>
+
+<p align="center">
+  Batteries-included RBAC — re-exports <code>@aooth/arbac-core</code> and adds a fluent role builder, reusable privilege factories, scope-merge utilities, and a codegen CLI for typed resource/action unions.
+</p>
+
+<p align="center">
+  <a href="https://aooth.moost.org/arbac/"><strong>Documentation →</strong></a>
+</p>
+
+---
+
+## Install
+
+```bash
+pnpm add @aooth/arbac
+```
+
+## Documentation
+
+Full docs, API reference, and recipes: **https://aooth.moost.org/arbac/**
+
+- [Concepts](https://aooth.moost.org/arbac/concepts)
+- [Role builder](https://aooth.moost.org/arbac/builder)
+- [Privilege factories](https://aooth.moost.org/arbac/privileges)
+- [Scope merging](https://aooth.moost.org/arbac/scopes)
+- [Codegen CLI](https://aooth.moost.org/arbac/codegen)
+- [API reference](https://aooth.moost.org/api/arbac)
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,476 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/define-role.ts
+var RoleBuilderImpl = class {
+	_id;
+	_name;
+	_description;
+	_rules = [];
+	id(id) {
+		this._id = id;
+		return this;
+	}
+	name(name) {
+		this._name = name;
+		return this;
+	}
+	describe(description) {
+		this._description = description;
+		return this;
+	}
+	allow(resource, action, scope) {
+		if (scope) this._rules.push({
+			resource,
+			action,
+			scope
+		});
+		else this._rules.push({
+			resource,
+			action
+		});
+		return this;
+	}
+	deny(resource, action) {
+		this._rules.push({
+			resource,
+			action,
+			effect: "deny"
+		});
+		return this;
+	}
+	use(...privileges) {
+		for (const priv of privileges) this._rules.push(...priv());
+		return this;
+	}
+	build() {
+		if (!this._id) throw new Error("Role id is required. Call .id() before .build().");
+		return {
+			id: this._id,
+			...this._name !== void 0 && { name: this._name },
+			...this._description !== void 0 && { description: this._description },
+			rules: [...this._rules]
+		};
+	}
+};
+/**
+* Start building a new role.
+*
+* @example
+* const editor = defineRole<MyAttrs, MyScope>()
+*   .id("editor")
+*   .name("Editor")
+*   .use(allowTableWrite("articles"))
+*   .deny("articles", "publish")
+*   .build();
+*/
+function defineRole() {
+	return new RoleBuilderImpl();
+}
+//#endregion
+//#region src/define-privilege.ts
+/**
+* Define a reusable privilege factory.
+*
+* Double-call pattern: first call pins TUserAttrs/TScope generics,
+* second call infers TArgs from the factory function.
+*
+* @example
+* const canManageUsers = definePrivilege<MyAttrs, MyScope>()(
+*   (scope: (attrs: MyAttrs, userId: string) => MyScope) => [
+*     { resource: "users", action: "read", scope },
+*     { resource: "users", action: "update", scope },
+*   ]
+* );
+*
+* defineRole<MyAttrs, MyScope>()
+*   .id("manager")
+*   .use(canManageUsers((attrs) => ({ dept: attrs.dept })))
+*   .build();
+*/
+function definePrivilege() {
+	return (factory) => {
+		return (...args) => () => factory(...args);
+	};
+}
+//#endregion
+//#region src/db-privileges.ts
+const TABLE_READ_ACTIONS = [
+	"query",
+	"pages",
+	"getOne",
+	"getOneComposite",
+	"meta",
+	"metaForm"
+];
+const TABLE_WRITE_ACTIONS = [
+	"insert",
+	"update",
+	"replace",
+	"remove",
+	"removeComposite"
+];
+function rulesFor(resource, actions, scope) {
+	return actions.map((action) => scope ? {
+		resource,
+		action,
+		scope
+	} : {
+		resource,
+		action
+	});
+}
+/** Read-side actions on an `AsDbController` table: `query`, `pages`, `getOne`, `getOneComposite`, `meta`, `metaForm`. */
+function allowTableRead(resource, opts) {
+	return () => rulesFor(resource, TABLE_READ_ACTIONS, opts?.scope);
+}
+/** All actions on an `AsDbController` table: read + `insert`, `update`, `replace`, `remove`, `removeComposite`. */
+function allowTableWrite(resource, opts) {
+	return () => rulesFor(resource, [...TABLE_READ_ACTIONS, ...TABLE_WRITE_ACTIONS], opts?.scope);
+}
+/** One or more declarative actions on the same table, sharing a scope. */
+function allowTableAction(resource, name, opts) {
+	const actions = typeof name === "string" ? [name] : name;
+	return () => rulesFor(resource, actions, opts?.scope);
+}
+//#endregion
+//#region src/scope/projection.ts
+/**
+* Determine whether a projection is in inclusion mode (all 1s),
+* exclusion mode (all 0s), or empty (`{}`, no restriction).
+*
+* @throws when a single projection mixes 0 and 1 values
+*/
+function getProjectionMode(proj) {
+	const values = Object.values(proj);
+	if (values.length === 0) return "empty";
+	const hasInclude = values.includes(1);
+	const hasExclude = values.includes(0);
+	if (hasInclude && hasExclude) throw new Error("Invalid projection: cannot mix include (1) and exclude (0) in a single projection");
+	return hasInclude ? "include" : "exclude";
+}
+/**
+* Check whether a dot-path field is allowed by a projection.
+*
+* Inclusion mode: a field is allowed if it, any of its parents, or any of its children
+*   is explicitly listed.
+* Exclusion mode: a field is allowed unless it or any of its parents is excluded.
+* Empty projection: every field is allowed.
+*/
+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;
+}
+/**
+* Combines projections from multiple RBAC role grants under additive semantics:
+* more roles = broader access. Each projection represents a set of allowed fields:
+* include-mode `{a:1}` allows `{a}`; exclude-mode `{a:0}` allows `universe \ {a}`;
+* empty `{}` allows the universe.
+*
+* A field is effectively allowed if any input grants it. Equivalently, a field
+* stays excluded only if (a) no include-mode role grants it explicitly, AND (b)
+* every exclude-mode role excludes it.
+*
+* Output mode:
+* - All-include input → include-mode result (union of include keys)
+* - At least one exclude-mode → exclude-mode result (or `{}` if no fields excluded)
+* - Empty input or any universal grant `{}` → `{}` (universe)
+*
+* Within a single projection, mixing 1 and 0 keys is an error (call sites should
+* normalize first). Across projections, mixing modes is supported and resolves
+* via the additive rule above.
+*
+* @throws when a single projection mixes 1 and 0 keys, or contains an invalid value
+*/
+function unionProjections(...projections) {
+	if (projections.length === 0) return {};
+	const includeKeys = /* @__PURE__ */ new Set();
+	const excludeKeys = [];
+	let hasUniverseGrant = false;
+	for (const p of projections) {
+		const entries = Object.entries(p);
+		if (entries.length === 0) {
+			hasUniverseGrant = true;
+			continue;
+		}
+		let mode = null;
+		const localExcludes = /* @__PURE__ */ new Set();
+		for (const [k, v] of entries) if (v === 1) {
+			if (mode === "exclude") throw new Error(`unionProjections: projection mixes 1 and 0 within itself: ${JSON.stringify(p)}`);
+			mode = "include";
+			includeKeys.add(k);
+		} else if (v === 0) {
+			if (mode === "include") throw new Error(`unionProjections: projection mixes 1 and 0 within itself: ${JSON.stringify(p)}`);
+			mode = "exclude";
+			localExcludes.add(k);
+		} else throw new Error(`unionProjections: invalid projection value ${String(v)} for key ${k} (must be 0 or 1)`);
+		if (mode === "exclude") excludeKeys.push(localExcludes);
+	}
+	if (hasUniverseGrant) return {};
+	if (excludeKeys.length === 0) {
+		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();
+	if (effectivelyExcluded.length === 0) return {};
+	return Object.fromEntries(effectivelyExcluded.map((k) => [k, 0]));
+}
+/**
+* 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.
+*
+* @param desired - the projection the caller asked for
+* @param accessControl - the projection allowed by RBAC
+*/
+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;
+}
+//#endregion
+//#region src/scope/filter.ts
+/**
+* Merge multiple scope filters into a single filter using `$or` semantics.
+*
+* In RBAC, if multiple roles grant access with different filters,
+* the user can see records matching ANY of them — hence `$or`.
+*
+* Behaviour:
+* - Empty input → `undefined` (no filter)
+* - Any empty filter → `undefined` (one role grants unrestricted access)
+* - Single filter → returned as-is
+* - All filters single-keyed on the same primitive field → `{ field: { $in: [...] } }`
+* - Otherwise → `{ $or: [...] }`
+*
+* @returns the merged filter, or `undefined` for unrestricted access
+*/
+function mergeScopeFilters(scopes) {
+	if (scopes.length === 0) return void 0;
+	if (scopes.some((s) => Object.keys(s).length === 0)) return void 0;
+	if (scopes.length === 1) return scopes[0];
+	if (canOptimizeToIn(scopes)) {
+		const key = Object.keys(scopes[0])[0];
+		const values = scopes.map((s) => s[key]);
+		return { [key]: { $in: values } };
+	}
+	return { $or: scopes };
+}
+function canOptimizeToIn(scopes) {
+	const firstKeys = Object.keys(scopes[0]);
+	if (firstKeys.length !== 1) return false;
+	const key = firstKeys[0];
+	for (const scope of scopes) {
+		const keys = Object.keys(scope);
+		if (keys.length !== 1 || keys[0] !== key) return false;
+		const value = scope[key];
+		if (value !== null && typeof value === "object") return false;
+	}
+	return true;
+}
+//#endregion
+//#region src/scope/controls.ts
+/**
+* Controls whose values can be sensibly whitelisted via `readonly string[]`.
+*
+* - `$with` — relation names; uniquery parses to `{ name, … }[]`.
+* - `$groupBy` — column names; the value already IS the array of names.
+*
+* Other controls only support boolean gates in v1; supplying a whitelist
+* for them throws from {@link unionControlsPolicy}.
+*/
+const WHITELISTABLE_CONTROLS = new Set(["$with", "$groupBy"]);
+/**
+* Union per-role `controls` policies. Additive RBAC semantics: more roles =
+* broader access, mirroring how `mergeScopeFilters` and `unionProjections`
+* combine other parts of an `ArbacDbScope`.
+*
+* Resolution per control key:
+*   1. Collect each scope's value for the key (including `undefined` for
+*      silent scopes — i.e., scopes that have a `controls` map but no entry
+*      for this key).
+*   2. If any value is `undefined` or `true` → return `true` (full allow).
+*      Silence and explicit allow both mean "this role has no objection".
+*   3. Else (every scope is `false` or `string[]`):
+*      - If all are `false` → return `false` (full deny).
+*      - Else collect every `string[]` into a single sorted, de-duplicated
+*        array; return that array. (Roles that say `false` don't contribute
+*        positively; roles with whitelists do.)
+*
+* Scopes that omit the `controls` map entirely are treated as silent on
+* EVERY key — i.e., they grant unrestricted control usage. As a result, if
+* even a single scope in the input lacks a `controls` map, the result is
+* always `{}` (no restrictions).
+*
+* Whitelist support is restricted to {@link WHITELISTABLE_CONTROLS}. Passing
+* a whitelist for any other control throws — the gate cannot be enforced
+* meaningfully in v1, so the misuse is rejected loudly at scope-merge time.
+*
+* @returns merged policy keyed by control name. Keys absent from the result
+*          mean "no opinion → fully allowed". The caller should treat a
+*          missing key the same as `true`.
+*
+* @throws when a non-whitelistable control is given a `readonly string[]` gate.
+*/
+function unionControlsPolicy(scopes) {
+	if (scopes.length === 0) return {};
+	if (scopes.some((s) => !s.controls)) return {};
+	const allKeys = /* @__PURE__ */ new Set();
+	for (const s of scopes) for (const k of Object.keys(s.controls)) allKeys.add(k);
+	const result = {};
+	for (const key of allKeys) {
+		let anyAllow = false;
+		const whitelistAcc = /* @__PURE__ */ new Set();
+		let hadWhitelist = false;
+		for (const s of scopes) {
+			const v = s.controls[key];
+			if (v === void 0 || v === true) {
+				anyAllow = true;
+				break;
+			}
+			if (v === false) continue;
+			if (Array.isArray(v)) {
+				if (!WHITELISTABLE_CONTROLS.has(key)) throw new Error(`unionControlsPolicy: control "${key}" only supports boolean gates; whitelist arrays not yet implemented`);
+				hadWhitelist = true;
+				for (const item of v) whitelistAcc.add(item);
+				continue;
+			}
+			throw new Error(`unionControlsPolicy: invalid gate value ${String(v)} for control "${key}" (must be boolean or string[])`);
+		}
+		if (anyAllow) continue;
+		if (hadWhitelist) {
+			result[key] = [...whitelistAcc].toSorted();
+			continue;
+		}
+		result[key] = false;
+	}
+	return result;
+}
+//#endregion
+//#region src/codegen/extract.ts
+function hasWildcard(s) {
+	return s.includes("*");
+}
+/**
+* Extract all resource and action strings from role definitions.
+*
+* @param roles - Array of built role definitions
+* @param options.includeWildcards - If false (default), skip entries containing `*` or `**`
+*/
+function extractResourceActions(roles, options) {
+	const includeWildcards = options?.includeWildcards ?? false;
+	const resources = /* @__PURE__ */ new Map();
+	const allResources = /* @__PURE__ */ new Set();
+	const allActions = /* @__PURE__ */ new Set();
+	for (const role of roles) for (const rule of role.rules) {
+		const skipResource = !includeWildcards && hasWildcard(rule.resource);
+		const skipAction = !includeWildcards && hasWildcard(rule.action);
+		if (!skipResource) {
+			allResources.add(rule.resource);
+			if (!skipAction) {
+				if (!resources.has(rule.resource)) resources.set(rule.resource, /* @__PURE__ */ new Set());
+				resources.get(rule.resource).add(rule.action);
+			}
+		}
+		if (!skipAction) allActions.add(rule.action);
+	}
+	return {
+		resources,
+		allResources,
+		allActions
+	};
+}
+//#endregion
+//#region src/codegen/generate.ts
+/**
+* Escape a string for safe embedding inside a TypeScript double-quoted literal.
+* Handles backslashes, double quotes, and control chars so resource/action
+* names containing these characters can't break the generated source.
+*/
+function escapeForTsString(value) {
+	return value.replace(/\\/gu, "\\\\").replace(/"/gu, "\\\"").replace(/\n/gu, "\\n").replace(/\r/gu, "\\r").replace(/\t/gu, "\\t");
+}
+function toUnion(values) {
+	const sorted = [...values].toSorted();
+	if (sorted.length === 0) return "never";
+	return sorted.map((v) => `"${escapeForTsString(v)}"`).join(" | ");
+}
+/**
+* Generate TypeScript source defining union types for resources and actions.
+*/
+function generateResourceTypes(map, options) {
+	const resourceType = options?.resourceTypeName ?? "Resource";
+	const actionType = options?.actionTypeName ?? "Action";
+	const includeMap = options?.resourceActionMap ?? true;
+	const header = options?.header ?? "// Auto-generated by @aooth/arbac codegen";
+	const lines = [];
+	if (header) lines.push(header, "");
+	lines.push(`export type ${resourceType} = ${toUnion(map.allResources)};`);
+	lines.push(`export type ${actionType} = ${toUnion(map.allActions)};`);
+	if (includeMap) {
+		lines.push("");
+		lines.push(`export type ${resourceType}ActionMap = {`);
+		const sorted = [...map.resources.entries()].toSorted(([a], [b]) => a.localeCompare(b));
+		for (const [resource, actions] of sorted) lines.push(`  "${escapeForTsString(resource)}": ${toUnion(actions)};`);
+		lines.push("};");
+	}
+	lines.push("");
+	return lines.join("\n");
+}
+//#endregion
+exports.allowTableAction = allowTableAction;
+exports.allowTableRead = allowTableRead;
+exports.allowTableWrite = allowTableWrite;
+exports.definePrivilege = definePrivilege;
+exports.defineRole = defineRole;
+exports.extractResourceActions = extractResourceActions;
+exports.generateResourceTypes = generateResourceTypes;
+exports.getProjectionMode = getProjectionMode;
+exports.isFieldAllowed = isFieldAllowed;
+exports.mergeScopeFilters = mergeScopeFilters;
+exports.restrictProjection = restrictProjection;
+exports.unionControlsPolicy = unionControlsPolicy;
+exports.unionProjections = unionProjections;
+var _aooth_arbac_core = require("@aooth/arbac-core");
+Object.keys(_aooth_arbac_core).forEach(function(k) {
+	if (k !== "default" && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
+		enumerable: true,
+		get: function() {
+			return _aooth_arbac_core[k];
+		}
+	});
+});