Quick Start

Get started with Dashforge Access Control in under 5 minutes.

Setup

3 STEPS

Step 1: Install the package

npm install @dashforge/rbac

Step 2: Define your policy and wrap your app

Create a policy defining roles and permissions, then wrap your app with RbacProvider:

import { RbacProvider, type RbacPolicy } from '@dashforge/rbac';

const policy: RbacPolicy = {
  roles: [
    {
      name: 'admin',
      permissions: [
        { action: '*', resource: '*', effect: 'allow' }
      ]
    },
    {
      name: 'editor',
      permissions: [
        { action: 'edit', resource: 'booking', effect: 'allow' },
        { action: 'read', resource: 'booking', effect: 'allow' }
      ]
    },
    {
      name: 'viewer',
      permissions: [
        { action: 'read', resource: 'booking', effect: 'allow' }
      ]
    }
  ]
};

function App() {
  // In a real app, fetch this from your auth system
  const currentUser = {
    id: 'user-123',
    roles: ['editor']
  };

  return (
    <RbacProvider policy={policy} subject={currentUser}>
      {/* Your app content */}
    </RbacProvider>
  );
}

Step 3: Use RBAC in your components

Add access control to Dashforge components using the access prop:

import { TextField } from '@dashforge/ui';

function BookingForm() {
  return (
    <>
      {/* Field is readonly for editors, editable for admins */}
      <TextField
        name="customerName"
        label="Customer Name"
        access={{
          action: 'edit',
          resource: 'booking',
          onUnauthorized: 'readonly'
        }}
      />

      {/* Button hides if user can't delete */}
      <Button
        access={{
          action: 'delete',
          resource: 'booking',
          onUnauthorized: 'hide'
        }}
      >
        Delete Booking
      </Button>
    </>
  );
}

Complete Example

Full working implementation with policy, provider, and components

Here's a complete example showing how everything works together. This example demonstrates three user roles (admin, editor, viewer) with different permissions on a booking form:

import { RbacProvider, type RbacPolicy, type Subject } from '@dashforge/rbac';
import { DashForm } from '@dashforge/forms';
import { TextField, Select, Button } from '@dashforge/ui';

// 1. Define your RBAC policy
const policy: RbacPolicy = {
  roles: [
    {
      name: 'admin',
      permissions: [
        { action: '*', resource: '*', effect: 'allow' }
      ]
    },
    {
      name: 'editor',
      permissions: [
        { action: 'edit', resource: 'booking', effect: 'allow' },
        { action: 'read', resource: 'booking', effect: 'allow' }
      ]
    },
    {
      name: 'viewer',
      permissions: [
        { action: 'read', resource: 'booking', effect: 'allow' }
      ]
    }
  ]
};

// 2. Create your form with access-controlled fields
function BookingForm() {
  return (
    <DashForm
      defaultValues={{
        customerName: '',
        bookingDate: '',
        status: 'pending'
      }}
      onSubmit={(data) => console.log('Submit:', data)}
    >
      {/* Viewers: readonly | Editors: editable | Admins: editable */}
      <TextField
        name="customerName"
        label="Customer Name"
        access={{
          action: 'edit',
          resource: 'booking',
          onUnauthorized: 'readonly'
        }}
      />

      {/* Viewers: readonly | Editors: editable | Admins: editable */}
      <TextField
        name="bookingDate"
        label="Booking Date"
        type="date"
        access={{
          action: 'edit',
          resource: 'booking',
          onUnauthorized: 'readonly'
        }}
      />

      {/* Viewers: hidden | Editors: hidden | Admins: visible */}
      <Select
        name="status"
        label="Status"
        options={[
          { value: 'pending', label: 'Pending' },
          { value: 'confirmed', label: 'Confirmed' },
          { value: 'cancelled', label: 'Cancelled' }
        ]}
        access={{
          action: 'manage',
          resource: 'booking',
          onUnauthorized: 'hide'
        }}
      />

      {/* Viewers: hidden | Editors: hidden | Admins: visible */}
      <Button
        type="submit"
        access={{
          action: 'edit',
          resource: 'booking',
          onUnauthorized: 'hide'
        }}
      >
        Save Changes
      </Button>
    </DashForm>
  );
}

// 3. Wrap your app with RbacProvider
export function App() {
  // In production, get this from your auth system
  const currentUser: Subject = {
    id: 'user-456',
    roles: ['editor']  // Try changing to 'viewer' or 'admin'
  };

  return (
    <RbacProvider policy={policy} subject={currentUser}>
      <BookingForm />
    </RbacProvider>
  );
}

// With role 'editor':
//   - customerName: editable ✅
//   - bookingDate: editable ✅
//   - status: hidden ❌ (needs 'manage' permission)
//   - Save button: visible ✅

// With role 'viewer':
//   - customerName: readonly 👁️
//   - bookingDate: readonly 👁️
//   - status: hidden ❌
//   - Save button: hidden ❌

// With role 'admin':
//   - Everything visible and editable ✅✅✅✅

Key Concepts

Understanding the fundamentals

Subject

The user requesting access. Contains an ID and a list of roles. Passed to RbacProvider as the subject prop.

const subject: Subject = {
  id: 'user-123',
  roles: ['editor', 'viewer']
};

Policy

The complete RBAC configuration. Defines all roles and their permissions. Passed to RbacProvider as the policy prop.

const policy: RbacPolicy = {
  roles: [
    {
      name: 'admin',
      permissions: [
        { action: 'edit', resource: 'booking', effect: 'allow' }
      ]
    }
  ]
};

Access Requirement

Declares what permission is needed and what happens when access is denied. Used in the access prop on Dashforge components.

<TextField
  name="field"
  access={{
    action: 'edit',           // What action is needed
    resource: 'booking',      // On what resource
    onUnauthorized: 'readonly' // What to do if denied: hide | disable | readonly
  }}
/>

Three Unauthorized Behaviors

hide — Component does not render when access is denied (most secure, default)
disable — Component renders but is disabled (non-interactive)
readonly — Component renders but is read-only (visible, not editable)

Next Steps

Where to go from here

Now that you have RBAC running, explore these topics:

Core Concepts: Learn about role inheritance, allow/deny precedence, wildcards, and conditions (coming soon)
React Integration: Deep dive into hooks (useRbac, useCan) and the Can component (coming soon)
Dashforge Integration: Explore navigation filtering, route guards, and advanced form patterns (coming soon)
Playground: Experiment with different roles and see how components behave (coming soon)