Skip to content

Latest commit

 

History

History
327 lines (254 loc) · 11.7 KB

APIS.md

File metadata and controls

327 lines (254 loc) · 11.7 KB
Raw

Permission manager API's

cellajs.com · prerelease version · MIT license · Dutch Europe

Node.js · TypeScript

❗ The permission manager exposes more classes, interfaces, types, and functions than listed in this document. However, this document primarily focuses on the essential classes and interfaces required for integration. For a comprehensive understanding of all available features and functionalities, please explore the source code.

Contents

Classes:

Abstract classes:

Interfaces:

Context API

Type: Class (inherits from HierarchicalEntity)

Recognizable entities within the application that maintain roles which can be claimed by actors.

Constructor

Param Required Type Description
name Yes String The (unique) name of the context
roles Yes Array<String> These represent distinct role names available within a context
parents No Set<HierarchicalEntity> Parent entities

Usage

import { Context } from '@cellajs/permission-manager';

const rootEntity = new Context(
    'root', // name
    ['rootAdmin', 'rootMember'], // roles
);

const leaveEntity = new Context(
    'leave', // name
    ['leaveAdmin', 'leaveMember'], // roles
    new Set([rootEntity]), // parents
);

Extra info

  1. You don't need to specify the 'parents' parameter for a root entity in the hierarchical structure.
  2. You only need to specify the direct parent (excluding ancestors higher in the structure).
  3. Specifying multiple parents results in a polyhierarchical leaf node.

Product API

Type: Class (inherits from HierarchicalEntity)

The tangible entities within the application. Unlike contexts, products do not have roles to claim; they are entities that are accessed and manipulated by actors based on their assigned roles and permissions within the respective contexts.

Constructor

Param Required Type Description
name Yes String The (unique) name of the product
parents No Set<HierarchicalEntity> Parent entities

Usage

import { Product } from '@cellajs/permission-manager';

const product = new Product(
    'product', // name
    new Set([context]), // parents
);

Extra info

  1. It's recommended that products are always attached to at least one parent.

PermissionManager API

Type: Class

The permission manager evaluates user permissions based on the established hierarchical structure and configured access policies.

Constructor

Param Required Type Description
name Yes String The (unique) name of the permission manager

Methods

Method Returns Description
isPermissionAllowed Boolean Checks if a permission is allowed based on the provided memberships, action, and subject. Returns true if the action is allowed, false if not allowed.
getActorPolicies ActionPolicies Retrieves the action policies for an actor based on the provided memberships and subject.
accessPolicies.configureAccessPolicies - Configures access policies based on the provided function.

Methods.isPermissionAllowed

Param Required Type Description
memberships Yes Array<Any> The array of membership objects. The structure of each membership object may vary depending on the provided MembershipAdapter.
action Yes String The action for which permission is being checked.
subject Yes Any The subject object for which permission is being checked. The structure of the subject object may vary depending on the provided SubjectAdapter.

Methods.getActorPolicies

Param Required Type Description
memberships Yes Array<Any> The array of membership objects. The structure of each membership object may vary depending on the provided MembershipAdapter.
subject Yes Any The subject object for which permission is being checked. The structure of the subject object may vary depending on the provided SubjectAdapter.

Methods.accessPolicies.configureAccessPolicies

Param Required Type Description
fnc Yes Function The function to configure access policies. While be injected with AccessPolicyConfiguration.

Usage

import { PermissionManager, AccessPolicyConfiguration } from '@cellajs/permission-manager';

const permissionManager = new PermissionManager(
    'guard', // name
);

permissionManager.accessPolicies.configureAccessPolicies((accessPolicyConfiguration: AccessPolicyConfiguration) => {});

const isAllowed = permissionManager.isPermissionAllowed(Array<Membership>, action, Subject);
const canDo = permissionManager.getActorPolicies(Array<Membership>, Subject);

MembershipAdapter API

Type: Abstract class

The permission manager requires a specific format for memberships. To simplify this conversion process, you can configure the MembershipAdapter that automatically transform your memberships into the required format. This adapter is automatically utilized when instantiating an inherited class with an overridden adapt method.

Abstract methods

Method Returns Description
adapt Membership Transforms memberships from a custom format to the expected format for Membership.

Abstract methods.adapt

Param Required Type Description
memberships Yes Array<Any> The array of membership objects in custom format.

Usage

import { MembershipAdapter, Membership } from '@cellajs/permission-manager';

class AdaptedMembershipAdapter extends MembershipAdapter {
    adapt(memberships: any[]): Membership[] {
        return memberships.map((m) => ({
            contextName: m.type,
            contextKey: m.key,
            roleName: m.role,
            ancestors: m.ancestors || {}
        }));
    }
}

new AdaptedMembershipAdapter();

SubjectAdapter API

Type: Abstract class

The permission manager requires a specific format for subjects. To simplify this conversion process, you can configure the SubjectAdapter to automatically transform your subjects into the required format. This adapter is automatically utilized when instantiating an inherited class with an overridden adapt method.

Abstract methods

Method Returns Description
adapt Subject Transforms subjects from a custom format to the expected format for Subject.

Abstract methods.adapt

Param Required Type Description
subject Yes Any The subject in custom format.

Usage

import { SubjectAdapter, Subject } from '@cellajs/permission-manager';

class AdaptedSubjectAdapter extends SubjectAdapter {
    adapt(s: any): Subject {
        return {
            name: s.type,
            key: s.key,
            ancestors: s.ancestors || {}
        };
    }
}

new AdaptedSubjectAdapter();

Membership API

Type: Interface

The required format for memberships used by the Permission Manager. This interface is utilized to configure the MembershipAdapter.

Attributes

Property Type Description
contextName String The name of the associated context
contextKey String The unique key of the associated context
roleName String or Null The associated role name
ancestors Object An object mapping ancestor names to unique keys in String format

Example

{
  contextName: 'context',
  contextKey: '661fc4ead271ca753b45ac34',
  roleName: 'role',
  ancestors: {
      ancestorA: '661fc4ff448bf34ef2c8e95a',
      ancestorB: '661fc5020cff1878adc12001',
      ancestorC: '661fc5059e22bf1571c79aad',
  }
};

Subject API

Type: Interface

The required format for subjects used by the Permission Manager. This interface is utilized to configure the SubjectAdapter.

Attributes

Property Type Description
name String The name of the subject
key String The unique key of the subject
ancestors Object An object mapping ancestor names to unique keys in String format

Example

{
  name: 'subject',
  key: '661fc31d1a90378c89d1636e',
  ancestors: {
      ancestorA: '661fc3297042f4a2ecc3b3fe',
      ancestorB: '661fc33969a82035df3ef943',
      ancestorC: '661fc344f649525f2fc8bb7b',
  },
};

AccessPolicyConfiguration API

Type: Interface

When configuring access policies through the configureAccessPolicies method exposed by the PermissionManager, a callback function will be injected with an AccessPolicyConfiguration instance. This AccessPolicyConfiguration refers to the current access policy within the many-to-many relationship between different contexts and their corresponding roles."

Attributes

Property Type Description
subject HierarchicalEntity An instance of a HierarchicalEntity
contexts Object An object mapping context names to objects representing configurable roles as Function

Attributes.contexts.

Param Required Type Description
policy Yes ActionPolicies The access policy object.

Example

{
  subject: {
      name: 'subject',
  },
  contexts: {
      contextA: {
          'admin': /*AccessPolicyFunction*/ Function,
          'follower': /*AccessPolicyFunction*/ Function,
      },
      contextB: {
          'contributor': /*AccessPolicyFunction*/ Function,          
          'sponsor': /*AccessPolicyFunction*/ Function,          
      },
  },
};

ActionPolicies API

Type: Interface

The getActorPolicies method from the PermissionManager returns an object of ActionPolicies. During the configuration of access policies using the configureAccessPolicies method exposed by the PermissionManager, the configurable role functions will expect an ActionPolicies object. This object maps actions to allowances in a Boolean format.

Attributes

Property Type Description
<action> Boolean An action in String format mapped to allowances in a Boolean format.

Example

{
  create: true,
  read: true,
  update: true,
  delete: false,  
};