Effortless Documentation

Incorporating role-based access control (RBAC) in your application is a critical part of securing your resources. However, understanding who has access to what and under what conditions can become complex as the number of roles and resources increases.

With role-baker, we simplify the documentation of your permissions by generating an automatically structured report. This report can be used to visualize which roles have access to which resources and actions. Furthermore, it also supports conditional permissions, where certain permissions depend on dynamic checks.

Automatic Documentation

The generatePermissionDocs function takes care of creating a detailed permission report from your resource configuration. This includes a breakdown of which users can perform specific actions and their corresponding permissions, like:

Allowed: The role is granted access to the action.
Denied: The role is not allowed to perform the action.
Conditional: A dynamic condition must be met for access.

Example Configuration

const { hasPermission, generatePermissionDocs } = bakeAuthorization<
  UserRoles,
  AuthUser,
  MyResourceConfig
>({
  userRoleMode: "singleRole",
  actionDocs: ACTIONS_DOC,
  permissionsConfig: {
    admin: {
      todos: { read: true, write: true, delete: true },
    },
    moderator: {
      todos: { read: true, write: false, delete: false },
    },
    user: {
      todos: {
        read: true,
        write: false,
        delete: {
          checkFunction: (authUser, todo) => todo?.authorId === authUser.userId,
          description: "Only the author can delete their own to-dos",
        },
      },
    },
    betaTester: {
      betaResource: { view: true },
    },
  },
});

Resource Configuration Example

export interface MyResourceConfig extends ResourceConfig {
  resources: {
    todos: {
      dataType: ToDoModel;
      action: "read" | "write" | "delete";
    };
    betaResource: {
      dataType: string;
      action: "view";
    };
  };
}

export const ACTIONS_DOC: ActionDescriptionConfig<MyResourceConfig> = {
  todos: {
    read: "Read to-dos",
    write: "Write to-dos",
    delete: "Delete to-dos",
  },
  betaResource: {
    view: "View beta resource",
  },
};

The Resulting Documentation

The generatePermissionDocs function returns a permission documentation report with the following structure:

export type PermissionDocumentationReport = {
  userRoleMode: RoleModeBase;
  report: Record<
    ResourceName,
    Record<ActionName, Record<string, ActionPermissionStatus>>
  >;
  reportHeader: Array<{
    columnName: string;
    isRole: boolean;
  }>;
  reportRows: Array<[string, string, string, ...ActionPermissionStatus[]]>;
};

export type ActionPermissionStatus =
  | "Allowed"
  | "Denied"
  | `Conditional: ${string}`;

This report contains the following key components:

Report Header: This defines the structure of the report, identifying the columns and whether they relate to a role.
Report Rows: This provides the actual data about permissions, such as "Allowed", "Denied", or "Conditional" permissions with specific descriptions.

Example Permission Documentation Report

Given the provided permissionsConfig and ACTIONS_DOC, the following table can be easley generated:

Report Header

resourceArea	permission	permissionDescription	admin	moderator	user	betaTester
todos	read	Read to-dos	Allowed	Allowed	Allowed	Denied
todos	write	Write to-dos	Allowed	Denied	Denied	Denied
todos	delete	Delete to-dos	Allowed	Denied	Conditional: Only the author can delete their own to-dos	Denied
betaResource	view	View beta resource	Denied	Denied	Denied	Allowed

Edit this page on GitHub

FrameworksOther Frameworks