README.md

@kitbag/access

Type safe attribute-based access control flow

Getting Started

Get started with the documentation

Installation

# bun
bun add @kitbag/access
# yarn
yarn add @kitbag/access
# npm
npm install @kitbag/access

Define Rules

Each rule is comprised of a resource, action, and a callback that returns a boolean. Kitbag Access provides a createAccessRule utility that can be used to create a rule.

Argument	Type	Required
resource	string	Yes
action	string	Yes
callback	(context: any) => boolean | Promise<boolean>	No

import { createAccessRule } from '@kitbag/access'

const rules = [
  createAccessRule('task', 'create', () => true),
  createAccessRule('repository', 'fork', (user: User) => user.location === 'US'),
  createAccessRule('comment', 'delete', ({ user, comment }: { user: User, comment: Comment }) => {
    if(user.role === 'admin') {
      return true
    }

    return user.id === comment.authorId
  }),
] as const

Important

Using as const when defining rules is important as it ensures the types are correctly inferred.

Resource

The resource is the name of the resource that the rule is for. There are no restrictions on the value you use.

For example, if the application is a task management system, the resource could be task, project, user, etc.

Action

The action is the name of the action that the rule is for. Again, there are no restrictions on the value you use.

For example, if the application is a task management system, the action could be create, update, delete, etc.

Callback

The callback is where you define the business logic for the given resource and action. The callback must return a boolean (or Promise<boolean>). The callback can optionally have arguments, any arguments defined by your callback will be required by the access control check.

Applying Rules

Kitbag Access exports a singleton instance of AccessControl. This instance makes it easy to apply rules automatically and always those rules available anywhere in your codebase.

import { createAccessRule } from '@kitbag/access'
import access from '@kitbag/access'

const rules = [
  ...
] as const

access.register(rules)

Type Safety for Global Rules

When using the singleton, we're going to use declaration merging to update the Register interface, which will ensure type safety.

import { createAccessRule } from '@kitbag/access'
import access from '@kitbag/access'

const rules = [
  ...
] as const

access.register(rules)

declare module '@kitbag/access' {
  interface Register {
    rules: typeof rules
  }
}

Creating Access Control Instances

Alternatively, you can use createAccessControl to create a new instance of AccessControl.

import { createAccessRule } from '@kitbag/access'
import { createAccessControl } from '@kitbag/access'

const rules = [
  ...
] as const

const access = createAccessControl(rules)

Using the Access Control

Once you have an Access Control instance, you can use it to check access to resources. Any rules that have required arguments will expect those values to be passed in.

import access from '@kitbag/access'

access.can('task', 'create')
access.can('repository', 'fork', user)
access.can('comment', 'delete', { user, comment })