@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

``bash
npm install @unchainedshop/roles
`

Usage

`typescript
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

$3

| 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 |

$3

| 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 |

$3

| 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__) |

$3

| 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 |

$3

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

$3

| 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

`typescript
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