Package Exports

@fire-shield/react
@fire-shield/react/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@fire-shield/react) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

🛡️ Fire Shield - React Adapter

React integration for Fire Shield RBAC authorization with hooks, components, and route guards.

Features

✅ React Hooks - usePermission, useRole, useRBAC, useAuthorize
✅ Conditional Components - <Can>, <Cannot>
✅ Route Protection - <ProtectedRoute> (requires React Router)
✅ TypeScript Support - Full type safety
✅ Framework Agnostic - Works with any React app

Installation

pnpm add @fire-shield/react @fire-shield/core

# If using ProtectedRoute component, also install:
pnpm add react-router-dom

Quick Start

1. Setup RBAC Provider

// App.tsx
import { BrowserRouter } from 'react-router-dom';
import { RBAC } from '@fire-shield/core';
import { RBACProvider } from '@fire-shield/react';

const rbac = new RBAC();
rbac.createRole('admin', ['user:*', 'post:*']);
rbac.createRole('editor', ['post:read', 'post:write']);

function App() {
  const user = useAuth(); // Your auth hook

  return (
    <BrowserRouter>
      <RBACProvider rbac={rbac} user={user}>
        <Routes>
          {/* Your routes */}
        </Routes>
      </RBACProvider>
    </BrowserRouter>
  );
}

2. Protect Routes

Note: ProtectedRoute requires react-router-dom to be installed.

// routes.tsx
import { ProtectedRoute } from '@fire-shield/react';

function AppRoutes() {
  return (
    <Routes>
      {/* Public route */}
      <Route path="/" element={<Home />} />

      {/* Protected by permission */}
      <Route
        path="/admin"
        element={
          <ProtectedRoute permission="admin:access">
            <AdminDashboard />
          </ProtectedRoute>
        }
      />

      {/* Protected by role */}
      <Route
        path="/editor"
        element={
          <ProtectedRoute role="editor">
            <EditorPanel />
          </ProtectedRoute>
        }
      />

      {/* Custom unauthorized component */}
      <Route
        path="/users"
        element={
          <ProtectedRoute
            permission="user:read"
            fallback={<NoAccess />}
          >
            <UserList />
          </ProtectedRoute>
        }
      />
    </Routes>
  );
}

3. Use Hooks in Components

// components/CreatePostButton.tsx
import { usePermission, useRole } from '@fire-shield/react';

function CreatePostButton() {
  const canCreate = usePermission('post:write');
  const isEditor = useRole('editor');

  if (!canCreate) {
    return null; // Hide button
  }

  return (
    <button onClick={createPost}>
      {isEditor ? 'Create & Publish' : 'Create Draft'}
    </button>
  );
}

API

Components

`<RBACProvider>`

Provides RBAC context to child components.

<RBACProvider rbac={rbac} user={user}>
  {children}
</RBACProvider>

Props:

rbac: RBAC - RBAC instance
user: RBACUser - Current user
children: ReactNode - Child components

`<ProtectedRoute>`

Protects routes with permission or role checks.

<ProtectedRoute
  permission="admin:access"
  role="admin"
  fallback={<Unauthorized />}
  redirectTo="/login"
>
  {children}
</ProtectedRoute>

Props:

permission?: string - Required permission
role?: string - Required role
fallback?: ReactNode - Component to show if unauthorized
redirectTo?: string - Path to redirect if unauthorized
children: ReactNode - Protected content

`<Can>`

Conditionally render based on permissions.

<Can permission="post:write">
  <CreatePostButton />
</Can>

<Can role="admin">
  <AdminPanel />
</Can>

`<Cannot>`

Conditionally render when user lacks permission.

<Cannot permission="post:write">
  <UpgradePrompt />
</Cannot>

Hooks

`useRBAC()`

Returns RBAC instance from context.

const rbac = useRBAC();

// Use RBAC methods
const canDelete = rbac.hasPermission(user, 'post:delete');

`usePermission(permission)`

Check if current user has permission.

const canWrite = usePermission('post:write');

if (canWrite) {
  // Show editor
}

`useRole(role)`

Check if current user has role.

const isAdmin = useRole('admin');

if (isAdmin) {
  // Show admin features
}

`useAuthorize(permission)`

Get full authorization result.

const result = useAuthorize('admin:delete');

if (!result.allowed) {
  console.log('Denied:', result.reason);
}

`useUser()`

Get current user from context.

const user = useUser();
console.log(user.id, user.roles);

Examples

Nested Route Protection

function AdminRoutes() {
  return (
    <ProtectedRoute permission="admin:access">
      <Routes>
        <Route path="/" element={<AdminDashboard />} />

        <Route
          path="/users"
          element={
            <ProtectedRoute permission="user:manage">
              <UserManagement />
            </ProtectedRoute>
          }
        />

        <Route
          path="/settings"
          element={
            <ProtectedRoute permission="settings:manage">
              <Settings />
            </ProtectedRoute>
          }
        />
      </Routes>
    </ProtectedRoute>
  );
}

function Navigation() {
  const canManageUsers = usePermission('user:manage');
  const canManagePosts = usePermission('post:manage');
  const isAdmin = useRole('admin');

  return (
    <nav>
      <Link to="/">Home</Link>

      {canManagePosts && (
        <Link to="/posts">Posts</Link>
      )}

      {canManageUsers && (
        <Link to="/users">Users</Link>
      )}

      {isAdmin && (
        <Link to="/admin">Admin</Link>
      )}
    </nav>
  );
}

Action Buttons

function PostActions({ post }: { post: Post }) {
  const canEdit = usePermission('post:edit');
  const canDelete = usePermission('post:delete');
  const canPublish = usePermission('post:publish');

  return (
    <div>
      {canEdit && (
        <button onClick={() => editPost(post.id)}>
          Edit
        </button>
      )}

      {canPublish && !post.published && (
        <button onClick={() => publishPost(post.id)}>
          Publish
        </button>
      )}

      {canDelete && (
        <button onClick={() => deletePost(post.id)}>
          Delete
        </button>
      )}
    </div>
  );
}

Form Field Protection

function UserForm() {
  const canEditEmail = usePermission('user:edit:email');
  const canEditRole = usePermission('user:edit:role');
  const canSetAdmin = useRole('admin');

  return (
    <form>
      <input name="name" />

      {canEditEmail && (
        <input name="email" type="email" />
      )}

      {canEditRole && (
        <select name="role">
          <option value="user">User</option>
          <option value="editor">Editor</option>
          {canSetAdmin && (
            <option value="admin">Admin</option>
          )}
        </select>
      )}
    </form>
  );
}

Loading States

function ProtectedDashboard() {
  const user = useUser();

  if (!user) {
    return <div>Loading...</div>;
  }

  return (
    <ProtectedRoute
      permission="dashboard:access"
      fallback={<Unauthorized />}
    >
      <Dashboard />
    </ProtectedRoute>
  );
}

TypeScript Support

import type { RBACUser } from '@fire-shield/core';

interface User extends RBACUser {
  email: string;
  name: string;
}

function App() {
  const user: User = useAuth();

  return (
    <RBACProvider<User> rbac={rbac} user={user}>
      {/* Fully typed */}
    </RBACProvider>
  );
}

JSPM