@iamjs/express

This package contains the express middleware for iamjs a library for easy role and permissions management for your express application.

Installation

npm install @iamjs/core @iamjs/express
# or
yarn add @iamjs/core @iamjs/express
# or
pnpm add @iamjs/core @iamjs/express
# or
bun add @iamjs/core @iamjs/express

Usage

Authorization

You can use the ExpressRoleManager to authorize a request in your express application by creating a new instance and using the check method.

Example:

import { Role, Schema } from '@iamjs/core';
import { ExpressRoleManager } from '@iamjs/express';
import express from 'express';

const role = new Role({
  name: 'role',
  config: {
    resource1: {
      base: 'crudl'
    },
    resource2: {
      base: 'cr-dl',
      custom: {
        'create a new user': false
      }
    }
  }
});

const schema = new Schema({
  roles: { role }
});

const roleManager = new ExpressRoleManager({
  schema: schema,
  onError(_err, _req, res, _next) {
    res.status(403).send('Forbidden');
  },
  onSucess(_req, res, _next) {
    res.status(200).send('Hello World from the success handler!');
  }
});

const app = express();

app.get(
  '/resource1',
  roleManager.check({
    resources: 'resource1',
    actions: ['create', 'update'],
    role: 'role',
    strict: true
  }),
  (_req, res) => {
    res.send('Hello World!');
  }
);

Advanced Usage

By using the construct option you can use the data from the request to build the role from its own permissions.

import { Role, Schema } from '@iamjs/core';
import { ExpressRoleManager } from '@iamjs/express';
import express from 'express';

const role = new Role({
  name: 'role',
  config: {
    resource1: {
      base: 'crudl'
    },
    resource2: {
      base: 'cr-dl',
      custom: {
        'create a new user': false
      }
    }
  }
});

const schema = new Schema({
  roles : { role }
});

const roleManager = new ExpressRoleManager({
  schema: schema,
  onError(_err, _req, res, _next) {
    res.status(403).send('Forbidden');
  },
  onSucess(_req, res, _next) {
    res.status(200).send('Hello World from the success handler!');
  }
});

const app = express();

const auth = async (req, res, next) => {
  req.permissions = role.toObject();
  next();
};

app.get(
  '/resource1',
  auth,
  roleManager.check({
    resources: 'resource1',
    actions: ['create', 'rupdate'],
    strict: true,
    construct: true,
    // get the role json or object from the request
    data: async (req) => {
      return req.permissions
    }
  }),
  (_req, res) => {
    res.send('Hello World!');
  }
);


app.listen(3000, () => {
  console.log('Example app listening at http://localhost:3000');
});

Success and Error Handling

You can pass onSuccess and onError handlers to the ExpressRoleManager constructor to handle the success and error cases.

Example:

import { Role } from '@iamjs/core';
import { ExpressRoleManager } from '@iamjs/express';
import express from 'express';

const app = express();

const role = new Role({
  name: 'role',
  config: {
    resource1: {
      base: 'crudl'
    },
    resource2: {
      base: 'cr-dl',
      custom: {
        'create a new user': false
      }
    }
  }
});

const schema = new Schema({
  roles : { role }
});

const roleManager = new ExpressRoleManager({
  schema: schema,
  onError(_err, _req, res, _next) {
    res.status(403).send('Forbidden');
  },
  onSucess(_req, res, _next) {
    res.status(200).send('Hello World from the success handler!');
  }
});


app.get(
  '/resource1',
  roleManager.check({
    resources: 'resource1',
    actions: ['create', 'update'],
    role: 'role',
    strict: true
  }),
  (_req, res) => {
    res.send('Hello World!');
  }
);

app.listen(3000, () => {
  console.log('Example app listening at http://localhost:3000');
});

Typescript Support

This package is written in typescript and has type definitions for all the exported types also the check method accepts a generic type which can be used to define the type of the request or response object.

Example:

import { Role } from '@iamjs/core';
import { ExpressRoleManager } from '@iamjs/express';
import express from 'express';

const app = express();

const role = new Role({
  name: 'role',
  config: {
    resource1: {
      base: 'crudl'
    },
    resource2: {
      base: 'cr-dl',
      custom: {
        'create a new user': false
      }
    }
  }
});

const schema = new Schema({
  roles : { role }
});

const roleManager = new ExpressRoleManager({
  schema: schema,
  onSuccess : <express.Request, express.Response>(req, res, next) => {
    res.send('Hello World!');
  },
  onError: <express.Request, express.Response>(err, req, res, next) => {
      console.error(err);
      res.status(403).send('Forbidden');
  },
});

const auth = async (req: express.Request, res: express.Response, next: express.NextFunction) => {
  req.permissions = user.toObject();
  next();
};

app.get('/post', 
  auth,
  roleManager.check<express.Request, express.Response>({
    resources: 'resource1',
    actions: ['create', 'rupdate'],
    strict: true,
    construct: true,
    // get the role json or object from the request
    data: async (req) => {
      return req.permissions
    }
  }), 
  (req, res) => {
  res.send('Hello World!');
});

app.listen(3000, () => {
  console.log('Example app listening at http://localhost:3000');
});

Save users activity

You can save user activity using the onActivity method on the ExpressRoleManager

import { Role } from "@iamjs/core";
import { ExpressRoleManager } from "@iamjs/express";
import express from "express";

const app = express();

const role = new Role({
  name: "role",
  config: {
    resource1: {
      base: "crudl",
    },
    resource2: {
      base: "cr-dl",
      custom: {
        "create a new user": false,
      },
    },
  },
});

const schema = new Schema({
  roles: { role },
});

const roleManager = new ExpressRoleManager({
  schema: schema,
  onError(_err, _req, res, _next) {
    res.status(403).send("Forbidden");
  },
  onSucess(_req, res, _next) {
    res.status(200).send("Hello World from the success handler!");
  },
  async onActivity(data) {
    console.log(data);
  },
});

app.get(
  "/resource1",
  roleManager.check({
    resources: "resource1",
    actions: ["create", "update"],
    role: "role",
    strict: true,
  }),
  (_req, res) => {
    res.send("Hello World!");
  }
);

app.listen(3000, () => {
  console.log("Example app listening at http://localhost:3000");
});

The data object contains:

Name	Description
actions?	The action or actions that are authorized to be executed on the resource
resources?	The resource or resources that are authorized to be accessed
role?	The role that is used to authorize the request
success?	The status of the request
req?	The request object