@aooth/arbac-core 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,37 @@
+<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-core</h1>
+
+<p align="center">
+  Zero-dependency RBAC engine — role evaluation with resource/action pattern matching, scope merging, and a minimal public API for framework integrators.
+</p>
+
+<p align="center">
+  <a href="https://aooth.moost.org/arbac/"><strong>Documentation →</strong></a>
+</p>
+
+---
+
+## Install
+
+```bash
+pnpm add @aooth/arbac-core
+```
+
+Most apps want [`@aooth/arbac`](../arbac) (builder API, privilege factories, scope utilities) or [`@aooth/arbac-moost`](../arbac-moost) (Moost integration) instead of consuming the core engine directly.
+
+## Documentation
+
+Full docs and API reference: **https://aooth.moost.org/arbac/**
+
+- [Concepts](https://aooth.moost.org/arbac/concepts)
+- [Core engine](https://aooth.moost.org/arbac/core)
+- [API reference](https://aooth.moost.org/api/arbac-core)
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,124 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/utils.ts
+function arbacPatternToRegex(input) {
+	let pattern = input.replace(/[$()+\-./?[\\\]^{|}]/gu, "\\$&");
+	pattern = pattern.replace(/\*\*/gu, "⁑");
+	pattern = pattern.replace(/\*/gu, "[^.]*");
+	pattern = pattern.replace(/⁑/gu, ".*");
+	return new RegExp(`^${pattern}$`);
+}
+//#endregion
+//#region src/arbac.ts
+/**
+* Implements Advanced Role-Based Access Control (ARBAC) system.
+* This class allows registering roles and resources, and evaluating access permissions based on user attributes and roles.
+*
+* @template TUserAttrs The type of user attributes.
+* @template TScope The type of scope that access rules can define.
+*/
+var Arbac = class {
+	roles = {};
+	resources = {};
+	warnedRoles = /* @__PURE__ */ new Set();
+	/**
+	* Registers a new role with the ARBAC system.
+	*
+	* @param {TArbacRole<TUserAttrs, TScope>} role The role to register.
+	*/
+	registerRole(role) {
+		this.roles[role.id] = role;
+		for (const key of Object.keys(this.resources)) this.evalRoleForResource(role.id, key);
+		return this;
+	}
+	/**
+	* Registers a new resource in the ARBAC system. If the resource already exists, this method does nothing.
+	*
+	* @param {string} resource The resource to register.
+	*/
+	registerResource(resource) {
+		if (!this.resources[resource]) {
+			this.resources[resource] = {};
+			for (const key of Object.keys(this.roles)) this.evalRoleForResource(key, resource);
+		}
+		return this;
+	}
+	/**
+	* Evaluates the role for a specific resource, updating the internal state with allow/deny rules.
+	*
+	* @protected
+	* @param {string} roleId The ID of the role to evaluate.
+	* @param {string} resourceId The ID of the resource to evaluate against.
+	*/
+	evalRoleForResource(roleId, resourceId) {
+		const resource = this.resources[resourceId];
+		const role = this.roles[roleId];
+		resource[roleId] = {
+			id: roleId,
+			allow: [],
+			deny: []
+		};
+		const target = resource[roleId];
+		for (const rule of role.rules) {
+			let rg = rule._resourceRegex;
+			if (!rg) {
+				rg = arbacPatternToRegex(rule.resource);
+				rule._resourceRegex = rg;
+			}
+			const effect = rule.effect || "allow";
+			if (rg.test(resourceId)) {
+				let ag = rule._actionRegex;
+				if (!ag) {
+					ag = arbacPatternToRegex(rule.action);
+					rule._actionRegex = ag;
+				}
+				target[effect].push({
+					action: rule.action,
+					_actionRegex: ag,
+					scope: rule.scope
+				});
+			}
+		}
+		return this;
+	}
+	/**
+	* Evaluates whether a given action on a resource is allowed for a user with specified roles.
+	*
+	* @param {{
+	*   roleIds: string[];
+	*   userId: string;
+	*   resource: string;
+	*   action: string;
+	* }} res The options for the evaluation.
+	* @returns {Promise<TArbacEvalResult<TScope>>} The result of the evaluation, including whether the action is allowed and any applicable scopes.
+	*/
+	async evaluate(res, user) {
+		this.registerResource(res.resource);
+		const roles = user.roles.map((r) => {
+			const role = this.resources[res.resource][r];
+			if (!role && !this.roles[r] && !this.warnedRoles.has(r)) {
+				this.warnedRoles.add(r);
+				console.warn(`Role "${r}" assigned to user "${user.id}" does not exist.`);
+			}
+			return role;
+		}).filter(Boolean);
+		if (roles.length === 0) return { allowed: false };
+		for (const role of roles) for (const rule of role.deny) if (rule._actionRegex.test(res.action)) return { allowed: false };
+		let userAttrs;
+		const scopes = [];
+		let allowed = false;
+		for (const role of roles) for (const rule of role.allow) if (rule._actionRegex.test(res.action)) {
+			allowed = true;
+			if (rule.scope) {
+				if (!userAttrs) userAttrs = typeof user.attrs === "function" ? await user.attrs(user.id) : user.attrs;
+				scopes.push(rule.scope(userAttrs, String(user.id)));
+			} else scopes.push({});
+		}
+		return allowed ? {
+			allowed,
+			scopes
+		} : { allowed };
+	}
+};
+//#endregion
+exports.Arbac = Arbac;
+exports.arbacPatternToRegex = arbacPatternToRegex;

package/dist/index.d.cts

@@ -0,0 +1,88 @@
+//#region src/types.d.ts
+interface TArbacEvalResult<TScope> {
+  allowed: boolean;
+  scopes?: TScope[];
+}
+interface TArbacRole<TUserAttrs, TScope> {
+  id: string;
+  name?: string;
+  description?: string;
+  rules: Array<TArbacRule<TUserAttrs, TScope>>;
+}
+type TArbacCompiledRule<TUserAttrs, TScope> = Omit<TArbacRule<TUserAttrs, TScope>, "resource" | "effect" | "_resourceRegex"> & {
+  _actionRegex: RegExp;
+};
+interface TArbacRoleForResource<TUserAttrs, TScope> {
+  id: string;
+  allow: Array<TArbacCompiledRule<TUserAttrs, TScope>>;
+  deny: Array<TArbacCompiledRule<TUserAttrs, TScope>>;
+}
+type TArbacRule<TUserAttrs, TScope> = {
+  resource: string;
+  action: string;
+  scope?: (userAttrs: TUserAttrs, userId: string) => TScope;
+  effect?: never;
+} | {
+  resource: string;
+  action: string;
+  effect: "deny";
+  scope?: never;
+};
+//#endregion
+//#region src/arbac.d.ts
+/**
+ * Implements Advanced Role-Based Access Control (ARBAC) system.
+ * This class allows registering roles and resources, and evaluating access permissions based on user attributes and roles.
+ *
+ * @template TUserAttrs The type of user attributes.
+ * @template TScope The type of scope that access rules can define.
+ */
+declare class Arbac<TUserAttrs extends object, TScope extends object> {
+  protected roles: Record<string, TArbacRole<TUserAttrs, TScope> | undefined>;
+  protected resources: Record<string, Record<string, TArbacRoleForResource<TUserAttrs, TScope> | undefined> | undefined>;
+  private warnedRoles;
+  /**
+   * Registers a new role with the ARBAC system.
+   *
+   * @param {TArbacRole<TUserAttrs, TScope>} role The role to register.
+   */
+  registerRole(role: TArbacRole<TUserAttrs, TScope>): Arbac<TUserAttrs, TScope>;
+  /**
+   * Registers a new resource in the ARBAC system. If the resource already exists, this method does nothing.
+   *
+   * @param {string} resource The resource to register.
+   */
+  registerResource(resource: string): Arbac<TUserAttrs, TScope>;
+  /**
+   * Evaluates the role for a specific resource, updating the internal state with allow/deny rules.
+   *
+   * @protected
+   * @param {string} roleId The ID of the role to evaluate.
+   * @param {string} resourceId The ID of the resource to evaluate against.
+   */
+  protected evalRoleForResource(roleId: string, resourceId: string): Arbac<TUserAttrs, TScope>;
+  /**
+   * Evaluates whether a given action on a resource is allowed for a user with specified roles.
+   *
+   * @param {{
+   *   roleIds: string[];
+   *   userId: string;
+   *   resource: string;
+   *   action: string;
+   * }} res The options for the evaluation.
+   * @returns {Promise<TArbacEvalResult<TScope>>} The result of the evaluation, including whether the action is allowed and any applicable scopes.
+   */
+  evaluate<T extends string | undefined>(res: {
+    resource: string;
+    action: string;
+  }, user: {
+    id: T;
+    roles: string[];
+    attrs: TUserAttrs | ((userId: T) => TUserAttrs | Promise<TUserAttrs>);
+  }): Promise<TArbacEvalResult<TScope>>;
+}
+//#endregion
+//#region src/utils.d.ts
+declare function arbacPatternToRegex(input: string): RegExp;
+//#endregion
+export { Arbac, TArbacCompiledRule, TArbacEvalResult, TArbacRole, TArbacRoleForResource, TArbacRule, arbacPatternToRegex };

package/dist/index.d.mts

@@ -0,0 +1,88 @@
+//#region src/types.d.ts
+interface TArbacEvalResult<TScope> {
+  allowed: boolean;
+  scopes?: TScope[];
+}
+interface TArbacRole<TUserAttrs, TScope> {
+  id: string;
+  name?: string;
+  description?: string;
+  rules: Array<TArbacRule<TUserAttrs, TScope>>;
+}
+type TArbacCompiledRule<TUserAttrs, TScope> = Omit<TArbacRule<TUserAttrs, TScope>, "resource" | "effect" | "_resourceRegex"> & {
+  _actionRegex: RegExp;
+};
+interface TArbacRoleForResource<TUserAttrs, TScope> {
+  id: string;
+  allow: Array<TArbacCompiledRule<TUserAttrs, TScope>>;
+  deny: Array<TArbacCompiledRule<TUserAttrs, TScope>>;
+}
+type TArbacRule<TUserAttrs, TScope> = {
+  resource: string;
+  action: string;
+  scope?: (userAttrs: TUserAttrs, userId: string) => TScope;
+  effect?: never;
+} | {
+  resource: string;
+  action: string;
+  effect: "deny";
+  scope?: never;
+};
+//#endregion
+//#region src/arbac.d.ts
+/**
+ * Implements Advanced Role-Based Access Control (ARBAC) system.
+ * This class allows registering roles and resources, and evaluating access permissions based on user attributes and roles.
+ *
+ * @template TUserAttrs The type of user attributes.
+ * @template TScope The type of scope that access rules can define.
+ */
+declare class Arbac<TUserAttrs extends object, TScope extends object> {
+  protected roles: Record<string, TArbacRole<TUserAttrs, TScope> | undefined>;
+  protected resources: Record<string, Record<string, TArbacRoleForResource<TUserAttrs, TScope> | undefined> | undefined>;
+  private warnedRoles;
+  /**
+   * Registers a new role with the ARBAC system.
+   *
+   * @param {TArbacRole<TUserAttrs, TScope>} role The role to register.
+   */
+  registerRole(role: TArbacRole<TUserAttrs, TScope>): Arbac<TUserAttrs, TScope>;
+  /**
+   * Registers a new resource in the ARBAC system. If the resource already exists, this method does nothing.
+   *
+   * @param {string} resource The resource to register.
+   */
+  registerResource(resource: string): Arbac<TUserAttrs, TScope>;
+  /**
+   * Evaluates the role for a specific resource, updating the internal state with allow/deny rules.
+   *
+   * @protected
+   * @param {string} roleId The ID of the role to evaluate.
+   * @param {string} resourceId The ID of the resource to evaluate against.
+   */
+  protected evalRoleForResource(roleId: string, resourceId: string): Arbac<TUserAttrs, TScope>;
+  /**
+   * Evaluates whether a given action on a resource is allowed for a user with specified roles.
+   *
+   * @param {{
+   *   roleIds: string[];
+   *   userId: string;
+   *   resource: string;
+   *   action: string;
+   * }} res The options for the evaluation.
+   * @returns {Promise<TArbacEvalResult<TScope>>} The result of the evaluation, including whether the action is allowed and any applicable scopes.
+   */
+  evaluate<T extends string | undefined>(res: {
+    resource: string;
+    action: string;
+  }, user: {
+    id: T;
+    roles: string[];
+    attrs: TUserAttrs | ((userId: T) => TUserAttrs | Promise<TUserAttrs>);
+  }): Promise<TArbacEvalResult<TScope>>;
+}
+//#endregion
+//#region src/utils.d.ts
+declare function arbacPatternToRegex(input: string): RegExp;
+//#endregion
+export { Arbac, TArbacCompiledRule, TArbacEvalResult, TArbacRole, TArbacRoleForResource, TArbacRule, arbacPatternToRegex };

package/dist/index.mjs

@@ -0,0 +1,122 @@
+//#region src/utils.ts
+function arbacPatternToRegex(input) {
+	let pattern = input.replace(/[$()+\-./?[\\\]^{|}]/gu, "\\$&");
+	pattern = pattern.replace(/\*\*/gu, "⁑");
+	pattern = pattern.replace(/\*/gu, "[^.]*");
+	pattern = pattern.replace(/⁑/gu, ".*");
+	return new RegExp(`^${pattern}$`);
+}
+//#endregion
+//#region src/arbac.ts
+/**
+* Implements Advanced Role-Based Access Control (ARBAC) system.
+* This class allows registering roles and resources, and evaluating access permissions based on user attributes and roles.
+*
+* @template TUserAttrs The type of user attributes.
+* @template TScope The type of scope that access rules can define.
+*/
+var Arbac = class {
+	roles = {};
+	resources = {};
+	warnedRoles = /* @__PURE__ */ new Set();
+	/**
+	* Registers a new role with the ARBAC system.
+	*
+	* @param {TArbacRole<TUserAttrs, TScope>} role The role to register.
+	*/
+	registerRole(role) {
+		this.roles[role.id] = role;
+		for (const key of Object.keys(this.resources)) this.evalRoleForResource(role.id, key);
+		return this;
+	}
+	/**
+	* Registers a new resource in the ARBAC system. If the resource already exists, this method does nothing.
+	*
+	* @param {string} resource The resource to register.
+	*/
+	registerResource(resource) {
+		if (!this.resources[resource]) {
+			this.resources[resource] = {};
+			for (const key of Object.keys(this.roles)) this.evalRoleForResource(key, resource);
+		}
+		return this;
+	}
+	/**
+	* Evaluates the role for a specific resource, updating the internal state with allow/deny rules.
+	*
+	* @protected
+	* @param {string} roleId The ID of the role to evaluate.
+	* @param {string} resourceId The ID of the resource to evaluate against.
+	*/
+	evalRoleForResource(roleId, resourceId) {
+		const resource = this.resources[resourceId];
+		const role = this.roles[roleId];
+		resource[roleId] = {
+			id: roleId,
+			allow: [],
+			deny: []
+		};
+		const target = resource[roleId];
+		for (const rule of role.rules) {
+			let rg = rule._resourceRegex;
+			if (!rg) {
+				rg = arbacPatternToRegex(rule.resource);
+				rule._resourceRegex = rg;
+			}
+			const effect = rule.effect || "allow";
+			if (rg.test(resourceId)) {
+				let ag = rule._actionRegex;
+				if (!ag) {
+					ag = arbacPatternToRegex(rule.action);
+					rule._actionRegex = ag;
+				}
+				target[effect].push({
+					action: rule.action,
+					_actionRegex: ag,
+					scope: rule.scope
+				});
+			}
+		}
+		return this;
+	}
+	/**
+	* Evaluates whether a given action on a resource is allowed for a user with specified roles.
+	*
+	* @param {{
+	*   roleIds: string[];
+	*   userId: string;
+	*   resource: string;
+	*   action: string;
+	* }} res The options for the evaluation.
+	* @returns {Promise<TArbacEvalResult<TScope>>} The result of the evaluation, including whether the action is allowed and any applicable scopes.
+	*/
+	async evaluate(res, user) {
+		this.registerResource(res.resource);
+		const roles = user.roles.map((r) => {
+			const role = this.resources[res.resource][r];
+			if (!role && !this.roles[r] && !this.warnedRoles.has(r)) {
+				this.warnedRoles.add(r);
+				console.warn(`Role "${r}" assigned to user "${user.id}" does not exist.`);
+			}
+			return role;
+		}).filter(Boolean);
+		if (roles.length === 0) return { allowed: false };
+		for (const role of roles) for (const rule of role.deny) if (rule._actionRegex.test(res.action)) return { allowed: false };
+		let userAttrs;
+		const scopes = [];
+		let allowed = false;
+		for (const role of roles) for (const rule of role.allow) if (rule._actionRegex.test(res.action)) {
+			allowed = true;
+			if (rule.scope) {
+				if (!userAttrs) userAttrs = typeof user.attrs === "function" ? await user.attrs(user.id) : user.attrs;
+				scopes.push(rule.scope(userAttrs, String(user.id)));
+			} else scopes.push({});
+		}
+		return allowed ? {
+			allowed,
+			scopes
+		} : { allowed };
+	}
+};
+//#endregion
+export { Arbac, arbacPatternToRegex };

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@aooth/arbac-core",
+  "version": "0.1.1",
+  "description": "Advanced Role-Based Access Control (ARBAC) engine",
+  "keywords": [
+    "access-control",
+    "aoothjs",
+    "arbac",
+    "authorization",
+    "rbac"
+  ],
+  "homepage": "https://github.com/moostjs/aoothjs/tree/main/packages/arbac-core#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-core"
+  },
+  "files": [
+    "dist"
+  ],
+  "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"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test",
+    "check": "vp check"
+  }
+}