perm-man v1.0.3

Perm-Man : A simple, yet fast and powerful permission manager for JS app

Perm-man is a simple, yet fast permission manager library for JavaScript web application, suitable to be used in a very high-traffic environment (e.g.: validate if a user has the permission to perform/access resources based on their assigned permissions)

This library uses simple string and number manipulation, plus heavy usage of map and Set object in order to achieve search speed in the order of O(1) - that's literally the fastest possible time a search operation can do.

Therefore, since this library heavily use Map and Set, it is advised for user to allocate the adequete amount of memory to accomodate the operation of this permission.

Usage

In Node.js:

For initial usage (in index.js)

const { PermissionManager, Permission } = require("perm-man");

// 1. Create a PermissionManager object

const userPermission = new PermissionManager(10); // Set this permission to hold 10 types of permission

/*
const adminPermission = ...
const merchantPermission = ...
const agentPermission = ...

Different class of user can be represented as different instance of PermissionManager

*/

// 2. Define all the possible permissions for this PermissionManager

userPermission.addDefinition({ key: "user.comment.view" });
userPermission.addDefinition({ key: "user.comment.edit" });
userPermission.addDefinition({ key: "user.comment.post" });
userPermission.addDefinition({ key: "user.comment.delete" });
userPermission.addDefinition({ key: "user.comment.share" });

// 3. Once all the permissions had been defined, you can issue a Permission object later in the application

// a. Either issue a blank Permission during registration:

const newUserPermission = userPermission.createBlankPermission({ allowAll: false });
newUserPermission.Code // <-- Save this property to the database

// b. Or, load from existing permission code from other source (i.e.: database) :

const user = ... // Get user during login
const { Code } = user; // Obtain the permission code from the user object
const permission = userPermission.fromCode(Code);

// `permission` object now contains the permission information of the loaded user

// You can now adjust the user's permission by simply doing so:
permission.setPermission("user.comment.view", true); // Allow the permission 'user.comment.view'
permission.setPermission("user.comment.share", false); // Do not allow the permission 'user.comment.view'. 

// By default, if the permission object was created with option { allowAll: false }, any permission that are not explicitly set to 'true' will be automatically treated as 'not allowed'

To perform permission checking:

const canComment = permission.hasPermission("user.comment.post"); // 'permission' is from loaded Permission object

if (!canComment) {
    throw new Error("This user cannot comment!");
}

In Express middleware:

const userPermission = ... // Load a PermissionManager from somewhere

const checkPermission = async (req, res, next) => {
    const userToken = req.headers["authorization"].replace("Bearer ", "").trim();
    const tokenObject = token.verify(userToken);
    const userPermissionCode = tokenObject.permissionCode; // Example on how to pass user's permission code across request.

    const permission = userPermission.fromCode(userPermissionCode);
    if (permission.hasPermission("...")) {
        next();
    }

    return res.status(401).json({ status: "notallowed" });
};

...
const commentRouter = require("express").Router();

commentRouter.post("/", checkPermission, async (req, res) => {
    ...
});

app.use(apiRouter, "/comment");

Changelog

1.0.3

• Added Universal Truth feature

  userPermission.addUniversalTruth("somecodehere", true);
  
  // Anyone that has it's permission code as 'somecodehere' will automatically be allowed to everything. This will override all the permissions that were set for the Permission instance.

1.0.1

• Initial version