@unchainedshop/roles 4.8.29 → 5.0.0-alpha.10

package/README.md

@@ -20,6 +20,8 @@ import { Roles, Role } from '@unchainedshop/roles';
 
 // Create a new role
 const editorRole = new Role('editor');
+Roles.addRole(editorRole);
+Roles.registerAction('updateProduct');
 
 // Allow actions for the role
 editorRole.allow('updateProduct', async (product, params, context) => {
@@ -42,6 +44,7 @@ const allowed = await Roles.userHasPermission(
 | Method | Description |
 |--------|-------------|
 | `Roles.registerAction` | Register a new action name |
+| `Roles.addRole` | Register a role instance |
 | `Roles.registerHelper` | Register a new helper name |
 | `Roles.getUserRoles` | Get user roles including special roles |
 | `Roles.allow` | Check if any role allows an action |
@@ -51,12 +54,14 @@ const allowed = await Roles.userHasPermission(
 
 | Method | Description |
 |--------|-------------|
-| `new Role(name)` | Create and register a new role |
+| `new Role(name)` | Create a role; register it with `roles.addRole()` |
 | `role.allow(action, fn)` | Add allow rule for an action |
 | `role.helper(name, fn)` | Add helper function to role |
 
 ### Built-in Roles
 
+`createRoles()` returns an empty role registry. Call `initDefaultRoles(registry)` to add the following roles, or use the API layer's `roles.configureRoles()` to configure the platform's permission rules.
+
 | Role | Description |
 |------|-------------|
 | `Roles.adminRole` | Admin role with elevated privileges |
@@ -70,7 +75,7 @@ const allowed = await Roles.userHasPermission(
 | `__all__` | Automatically assigned to everyone |
 | `__loggedIn__` | Automatically assigned to authenticated users |
 | `__notLoggedIn__` | Automatically assigned to anonymous users |
-| `__notAdmin__` | Automatically assigned to non-admin users |
+| `__notAdmin__` | Automatically assigned to authenticated non-admin users |
 
 ### Utility Functions
 
@@ -93,13 +98,13 @@ const allowed = await Roles.userHasPermission(
 ## Configuration
 
 ```typescript
-import type { IRoleOptionConfig } from '@unchainedshop/roles';
+import { Role, type IRoleOptionConfig } from '@unchainedshop/roles';
 
 const config: IRoleOptionConfig = {
   additionalRoles: {
     customRole: (roles, actions) => {
-      const role = new Role('customRole');
-      role.allow(actions.READ, () => true);
+      const role = roles.addRole(new Role('customRole'));
+      role.allow(actions.CUSTOM_ACTION, async () => true);
     },
   },
   additionalActions: ['CUSTOM_ACTION'],

package/lib/roles.d.ts

@@ -14,6 +14,7 @@ export interface RolesInterface {
     roles: Record<string, RoleInterface>;
     actions: string[];
     helpers: string[];
+    addRole(role: RoleInterface): RoleInterface;
     registerAction(name: string): void;
     registerHelper(name: string): void;
     getUserRoles(userId: string, roles: string[], includeSpecial: boolean): string[];
@@ -23,16 +24,11 @@ export interface RolesInterface {
     loggedInRole?: RoleInterface;
     allRole?: RoleInterface;
 }
-export interface RoleInterface {
-    name: string;
-    allowRules: Record<string, any>;
-    allow(action: string, fn: (root: any, props: any, context: RoleUserContext) => Promise<boolean>): void;
-    helpers: Record<string, unknown>;
-}
 export interface IRoleOptionConfig {
     additionalRoles?: Record<string, (role: RolesInterface, actions: Record<string, string>) => void>;
     additionalActions?: string[];
 }
+export declare function createRoles(): RolesInterface;
 export declare const Roles: RolesInterface;
 export declare class Role implements RoleInterface {
     name: string;
@@ -42,4 +38,5 @@ export declare class Role implements RoleInterface {
     helper(helper: string, func: any): void;
     allow(action: any, allow: any): void;
 }
+export declare function initDefaultRoles(roles?: RolesInterface): void;
 export {};

package/lib/roles.js

@@ -1,74 +1,81 @@
 import { has } from "./utils/has.js";
 import { isFunction } from "./utils/isFunction.js";
-export const Roles = {
-    roles: {},
-    actions: [],
-    helpers: [],
-    registerAction(name) {
-        if (!this.actions.includes(name)) {
-            this.actions.push(name);
-        }
-    },
-    registerHelper(name) {
-        if (!this.helpers.includes(name)) {
-            this.helpers.push(name);
-        }
-    },
-    getUserRoles(userId, roles, includeSpecial) {
-        const newRoles = [...(roles || [])];
-        if (includeSpecial) {
-            newRoles.push('__all__');
-            if (!userId) {
-                newRoles.push('__notLoggedIn__');
+export function createRoles() {
+    const instance = {
+        roles: {},
+        actions: [],
+        helpers: [],
+        addRole(role) {
+            if (has(this.roles, role.name)) {
+                throw new Error(`"${role.name}" role is already defined`);
             }
-            else {
-                newRoles.push('__loggedIn__');
-                if (!newRoles.includes('admin')) {
-                    newRoles.push('__notAdmin__');
-                }
+            this.roles[role.name] = role;
+            return role;
+        },
+        registerAction(name) {
+            if (!this.actions.includes(name)) {
+                this.actions.push(name);
             }
-        }
-        return newRoles;
-    },
-    async allow(context, roles, action, [obj, params]) {
-        const userRoles = Roles.getUserRoles(context.userId, roles, true);
-        return userRoles.reduce(async (roleIsAllowedPromise, role) => {
-            const roleIsAllowed = await roleIsAllowedPromise;
-            if (roleIsAllowed)
-                return true;
-            if (Roles.roles[role] && Roles.roles[role].allowRules && Roles.roles[role].allowRules[action]) {
-                return Roles.roles[role].allowRules[action].reduce(async (rulesIsAllowedPromise, allowFn) => {
-                    const ruleIsAllowed = await rulesIsAllowedPromise;
-                    if (ruleIsAllowed)
-                        return true;
-                    return allowFn(obj, params, context);
-                }, Promise.resolve(false));
+        },
+        registerHelper(name) {
+            if (!this.helpers.includes(name)) {
+                this.helpers.push(name);
+            }
+        },
+        getUserRoles(userId, roles, includeSpecial) {
+            const newRoles = [...(roles || [])];
+            if (includeSpecial) {
+                newRoles.push('__all__');
+                if (!userId) {
+                    newRoles.push('__notLoggedIn__');
+                }
+                else {
+                    newRoles.push('__loggedIn__');
+                    if (!newRoles.includes('admin')) {
+                        newRoles.push('__notAdmin__');
+                    }
+                }
             }
-            return roleIsAllowed;
-        }, Promise.resolve(false));
-    },
-    userHasPermission: async (context, action, args) => {
-        const roles = Array.isArray(context.user?.roles) ? context.user.roles : [];
-        const allows = await Roles.allow(context, roles, action, args);
-        return allows === true;
-    },
-};
+            return newRoles;
+        },
+        async allow(context, roles, action, [obj, params]) {
+            const userRoles = instance.getUserRoles(context.userId, roles, true);
+            return userRoles.reduce(async (roleIsAllowedPromise, role) => {
+                const roleIsAllowed = await roleIsAllowedPromise;
+                if (roleIsAllowed)
+                    return true;
+                if (instance.roles[role] &&
+                    instance.roles[role].allowRules &&
+                    instance.roles[role].allowRules[action]) {
+                    return instance.roles[role].allowRules[action].reduce(async (rulesIsAllowedPromise, allowFn) => {
+                        const ruleIsAllowed = await rulesIsAllowedPromise;
+                        if (ruleIsAllowed)
+                            return true;
+                        return allowFn(obj, params, context);
+                    }, Promise.resolve(false));
+                }
+                return roleIsAllowed;
+            }, Promise.resolve(false));
+        },
+        async userHasPermission(context, action, args) {
+            const roles = Array.isArray(context.user?.roles) ? context.user.roles : [];
+            const allows = await instance.allow(context, roles, action, args);
+            return allows === true;
+        },
+    };
+    return instance;
+}
+export const Roles = createRoles();
 export class Role {
     name;
     allowRules;
     helpers;
     constructor(name) {
-        if (has(Roles.roles, name))
-            throw new Error(`"${name}" role is already defined`);
         this.name = name;
         this.allowRules = {};
         this.helpers = {};
-        Roles.roles[name] = this;
     }
     helper(helper, func) {
-        if (!Roles.helpers.includes(helper)) {
-            Roles.registerHelper(helper);
-        }
         let helperFn = func;
         if (!isFunction(helperFn)) {
             const clonedValue = structuredClone(helperFn);
@@ -85,9 +92,6 @@ export class Role {
         if (!action) {
             throw new Error(`Action doesn't exist`);
         }
-        if (!Roles.actions.includes(action)) {
-            Roles.registerAction(action);
-        }
         let allowFn = allow;
         if (!isFunction(allowFn)) {
             const clonedValue = structuredClone(allowFn);
@@ -99,6 +103,10 @@ export class Role {
         this.allowRules[action].push(allowFn);
     }
 }
-Roles.adminRole = new Role('admin');
-Roles.loggedInRole = new Role('__loggedIn__');
-Roles.allRole = new Role('__all__');
+export function initDefaultRoles(roles = Roles) {
+    if (roles.adminRole)
+        return;
+    roles.adminRole = roles.addRole(new Role('admin'));
+    roles.loggedInRole = roles.addRole(new Role('__loggedIn__'));
+    roles.allRole = roles.addRole(new Role('__all__'));
+}

package/package.json

@@ -1,6 +1,9 @@
 {
   "name": "@unchainedshop/roles",
-  "version": "4.8.29",
+  "version": "5.0.0-alpha.10",
+  "files": [
+    "lib"
+  ],
   "description": "Role-based access control system for the Unchained Engine",
   "main": "lib/roles-index.js",
   "types": "lib/roles-index.d.ts",
@@ -35,6 +38,6 @@
   "homepage": "https://github.com/unchainedshop/unchained#readme",
   "devDependencies": {
     "@types/node": "^26.2.0",
-    "typescript": "^5.8.3"
+    "typescript": "^6.0.3"
   }
 }