@aooth/arbac 0.1.1

package/dist/index.mjs

@@ -0,0 +1,455 @@
+export * from "@aooth/arbac-core";
+//#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
+export { allowTableAction, allowTableRead, allowTableWrite, definePrivilege, defineRole, extractResourceActions, generateResourceTypes, getProjectionMode, isFieldAllowed, mergeScopeFilters, restrictProjection, unionControlsPolicy, unionProjections };

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@aooth/arbac",
+  "version": "0.1.1",
+  "description": "Batteries-included RBAC: builder API, privilege factories, scope merge utilities",
+  "keywords": [
+    "access-control",
+    "aoothjs",
+    "arbac",
+    "authorization",
+    "builder",
+    "rbac"
+  ],
+  "homepage": "https://github.com/moostjs/aoothjs/tree/main/packages/arbac#readme",
+  "bugs": {
+    "url": "https://github.com/moostjs/aoothjs/issues"
+  },
+  "license": "MIT",
+  "author": "Artem Maltsev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/moostjs/aoothjs.git",
+    "directory": "packages/arbac"
+  },
+  "bin": {
+    "aoothjs-arbac-codegen": "./scripts/codegen.mjs"
+  },
+  "files": [
+    "dist",
+    "scripts"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@aooth/arbac-core": "0.1.1"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test",
+    "check": "vp check"
+  }
+}

package/scripts/codegen.mjs

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+// @aooth/arbac codegen CLI
+//
+// Generates TypeScript union types from a built array of @aooth/arbac roles.
+//
+// Usage:
+//   aoothjs-arbac-codegen --roles <path> --output <path> [--export-name <name>]
+//
+// Notes:
+//   * --roles must point to a JS/MJS module that node can import directly.
+//     The module must export either a default export or a named `roles` export
+//     containing an array of built roles (the result of `defineRole(...).build()`).
+//   * If you author roles in TypeScript, build them first with your existing
+//     toolchain and point --roles at the built JS output.
+
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, resolve } from "node:path";
+import { argv, cwd, exit, stderr, stdout } from "node:process";
+import { pathToFileURL } from "node:url";
+
+/**
+ * @typedef {{ rolesPath?: string; outputPath?: string; resourceTypeName?: string; actionTypeName?: string; help?: boolean }} TParsedArgs
+ */
+
+const HELP_TEXT = `aoothjs-arbac-codegen — generate TS resource/action union types
+
+Usage:
+  aoothjs-arbac-codegen --roles <path> --output <path> [options]
+
+Required:
+  --roles <path>            Path to a JS/MJS file that exports built roles
+                            (default export, or named export \`roles\`).
+  --output <path>           Path to write the generated .ts file.
+
+Options:
+  --resource-type <name>    Name of the resource union type. Default: Resource
+  --action-type <name>      Name of the action union type.   Default: Action
+  --export-name <name>      Alias for --resource-type (kept for compatibility).
+  -h, --help                Show this help.
+`;
+
+/**
+ * @param {string[]} args
+ * @returns {TParsedArgs}
+ */
+function parseArgs(args) {
+  /** @type {TParsedArgs} */
+  const out = {};
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    switch (a) {
+      case "-h":
+      case "--help":
+        out.help = true;
+        break;
+      case "--roles":
+        out.rolesPath = args[++i];
+        break;
+      case "--output":
+        out.outputPath = args[++i];
+        break;
+      case "--resource-type":
+      case "--export-name":
+        out.resourceTypeName = args[++i];
+        break;
+      case "--action-type":
+        out.actionTypeName = args[++i];
+        break;
+      default:
+        throw new Error(`Unknown argument: ${a}`);
+    }
+  }
+  return out;
+}
+
+/**
+ * Resolve a CLI path argument to an absolute path.
+ * @param {string} p
+ */
+function toAbsolute(p) {
+  return isAbsolute(p) ? p : resolve(cwd(), p);
+}
+
+/**
+ * Pick the roles array from a dynamically-imported module.
+ * Accepts: default export array, or named `roles` export array.
+ * @param {Record<string, unknown>} mod
+ * @param {string} importedFrom
+ */
+function pickRoles(mod, importedFrom) {
+  /** @type {unknown} */
+  let candidate = mod.default;
+  if (!Array.isArray(candidate)) {
+    candidate = mod.roles;
+  }
+  if (!Array.isArray(candidate)) {
+    throw new Error(
+      `Module at ${importedFrom} must export a default array or a named \`roles\` array of built roles.`,
+    );
+  }
+  return /** @type {import("@aooth/arbac-core").TArbacRole<unknown, unknown>[]} */ (candidate);
+}
+
+async function loadCodegenApi() {
+  // Prefer the built dist (works after `vp pack`); fall back to the source for
+  // dev workflows where dist hasn't been built yet.
+  try {
+    return await import("../dist/index.mjs");
+  } catch {
+    return await import("../src/index.ts");
+  }
+}
+
+async function main() {
+  /** @type {TParsedArgs} */
+  let parsed;
+  try {
+    parsed = parseArgs(argv.slice(2));
+  } catch (err) {
+    stderr.write(`${/** @type {Error} */ (err).message}\n\n${HELP_TEXT}`);
+    exit(2);
+    return;
+  }
+
+  if (parsed.help) {
+    stdout.write(HELP_TEXT);
+    return;
+  }
+
+  if (!parsed.rolesPath || !parsed.outputPath) {
+    stderr.write(`Both --roles and --output are required.\n\n${HELP_TEXT}`);
+    exit(2);
+    return;
+  }
+
+  const rolesAbs = toAbsolute(parsed.rolesPath);
+  const outAbs = toAbsolute(parsed.outputPath);
+
+  const mod = await import(pathToFileURL(rolesAbs).href);
+  const roles = pickRoles(/** @type {Record<string, unknown>} */ (mod), rolesAbs);
+
+  const { extractResourceActions, generateResourceTypes } = await loadCodegenApi();
+  const map = extractResourceActions(roles);
+  const source = generateResourceTypes(map, {
+    resourceTypeName: parsed.resourceTypeName,
+    actionTypeName: parsed.actionTypeName,
+  });
+
+  await mkdir(dirname(outAbs), { recursive: true });
+  await writeFile(outAbs, source, "utf8");
+  stdout.write(`aoothjs-arbac-codegen: wrote ${outAbs}\n`);
+}
+
+main().catch((err) => {
+  stderr.write(`aoothjs-arbac-codegen: ${err.stack || err.message || String(err)}\n`);
+  exit(1);
+});