@unchainedshop/roles

Role-based access control (RBAC) system for the Unchained Engine. Provides fine-grained permission management for API operations.

Thanks to Nicolás López for the initial version of Roles: https://github.com/nicolaslopezj/roles

Installation

npm install @unchainedshop/roles

Usage

import { Roles, Role } from '@unchainedshop/roles';

// Create a new role
const editorRole = new Role('editor');

// Allow actions for the role
editorRole.allow('updateProduct', async (product, params, context) => {
  // Return true if allowed, false otherwise
  return context.userId != null;
});

// Check if a user has permission
const allowed = await Roles.userHasPermission(
  { userId: 'user-123', user: { roles: ['editor'] } },
  'updateProduct',
  [productObject, {}]
);

API Overview

Roles Singleton

| Method | Description | |--------|-------------| | Roles.registerAction | Register a new action name | | Roles.registerHelper | Register a new helper name | | Roles.getUserRoles | Get user roles including special roles | | Roles.allow | Check if any role allows an action | | Roles.userHasPermission | Check if user has permission for action |

Role Class

| Method | Description | |--------|-------------| | new Role(name) | Create and register a new role | | role.allow(action, fn) | Add allow rule for an action | | role.helper(name, fn) | Add helper function to role |

Built-in Roles

| Role | Description | |------|-------------| | Roles.adminRole | Admin role with elevated privileges | | Roles.loggedInRole | Applied to all logged-in users (__loggedIn__) | | Roles.allRole | Applied to all users (__all__) |

Special Internal Roles

| Role | Description | |------|-------------| | __all__ | Automatically assigned to everyone | | __loggedIn__ | Automatically assigned to authenticated users | | __notLoggedIn__ | Automatically assigned to anonymous users | | __notAdmin__ | Automatically assigned to non-admin users |

Utility Functions

| Export | Description | |--------|-------------| | has | Check if object has property | | isFunction | Check if value is a function | | permissions | Permission constants and helpers |

Types

| Export | Description | |--------|-------------| | RolesInterface | Interface for the Roles singleton | | RoleInterface | Interface for Role instances | | RoleInterfaceFactory | Factory type for Role class | | IRoleOptionConfig | Configuration options for roles | | CheckPermissionArgs | Arguments tuple for permission checks |

Configuration

import type { IRoleOptionConfig } from '@unchainedshop/roles';

const config: IRoleOptionConfig = {
  additionalRoles: {
    customRole: (roles, actions) => {
      const role = new Role('customRole');
      role.allow(actions.READ, () => true);
    },
  },
  additionalActions: ['CUSTOM_ACTION'],
};

License

EUPL-1.2