@iamjs/koa

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

Installation

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

Usage

Authorization

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

Example:

import { Role, Schema } from '@iamjs/core';
import { ExpressRoleManager } from '@iamjs/koa';
import Koa from 'koa';
import Router from 'koa-router';

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

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

const roleManager = new KoaRoleManager({
  schema,
  async onError(_err, ctx, next) {
    ctx.status = 403;
    ctx.body = 'Forbidden';
    await next();
  },
  async onSuccess(ctx, next) {
    ctx.status = 200;
    ctx.body = 'Hello World from the success handler!';
    await next();
  }
});

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

app.use(router.routes());

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/koa';
import Koa from 'koa';
import Router from 'koa-router';

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

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

const roleManager = new KoaRoleManager({
  schema,
  async onError(_err, ctx, next) {
    ctx.status = 403;
    ctx.body = 'Forbidden';
    await next();
  },
  async onSuccess(ctx, next) {
    ctx.status = 200;
    ctx.body = 'Hello World from the success handler!';
    await next();
  }
});

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

app.use(router.routes());

Success and Error Handling

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

Example:

import { Role, Schema } from '@iamjs/core';
import { ExpressRoleManager } from '@iamjs/koa';
import Koa from 'koa';
import Router from 'koa-router';

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

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

const roleManager = new KoaRoleManager({
  schema,
  async onError(_err, ctx, next) {
    ctx.status = 403;
    ctx.body = 'Forbidden';
    await next();
  },
  async onSuccess(ctx, next) {
    ctx.status = 200;
    ctx.body = 'Hello World from the success handler!';
    await next();
  }
});

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

app.use(router.routes());

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 context object.

Example:

import { Role, Schema } from '@iamjs/core';
import { ExpressRoleManager } from '@iamjs/koa';
import Koa from 'koa';
import Router from 'koa-router';

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

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

interface CustomContext extends Context {
  somekey: any
}

const roleManager = new KoaRoleManager({
  schema,
  async onError<CustomContext>(_err, ctx, next) {
    ctx.status = 403;
    ctx.body = 'Forbidden';
    await next();
  },
  async onSuccess<CustomContext>(ctx, next) {
    ctx.status = 200;
    ctx.body = 'Hello World from the success handler!';
    await next();
  }
});

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

app.use(router.routes());

Save users activity

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

import { Role, Schema } from "@iamjs/core";
import { ExpressRoleManager } from "@iamjs/koa";
import Koa from "koa";
import Router from "koa-router";

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

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

interface CustomContext extends Context {
  somekey: any;
}

const roleManager = new KoaRoleManager({
  schema,
  async onError<CustomContext>(_err, ctx, next) {
    ctx.status = 403;
    ctx.body = "Forbidden";
    await next();
  },
  async onSuccess<CustomContext>(ctx, next) {
    ctx.status = 200;
    ctx.body = "Hello World from the success handler!";
    await next();
  },
  async onActivity(data) {
    // save the activity object
  },
});

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

app.use(router.routes());

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 | | ctx? | The context object |