rbac-shield

v0.2.5

Published

7 days ago

A production-ready, type-safe Role-Based Access Control (RBAC) system for Next.js applications with multi-tenant support

0High
0Medium
0Low

devnuckles

rbac-shield rbac rbac-frontend role-based-access-control permissions permissions-management authorization nextjs react typescript multi-tenant access-control route-protection

🔐 RBAC Shield

The production-ready, type-safe Role-Based Access Control (RBAC) system for Next.js applications.

Built for modern web development with React 19, TypeScript 5, and Next.js App Router compatibility. RBAC Shield provides a seamless, multi-tenant permission system that supports both Role-based and Permission-based strategies.

✨ Features

🎯 Type-Safe Permissions: Typescript "Prettify" helpers ensure tooltips show exact prop shapes.
👑 First-Class Role Support: Check for Roles, Permissions, or Both.
🚀 High Performance: Optimized with React Context and memoization.
🏢 Multi-Tenant Native: Switch between organizations/roles instantly.
⚡ Zero Loading States: Instant hydration via server-side data injection.
🛡️ Route Protection: Declarative guards with auto-redirects.
🌍 Universal: Works in Client Components, Server Components, and Middleware.

📦 Installation

Option 1: Interactive CLI (Recommended)

This will set up your types and configuration file automatically.

npx rbac-shield init

Option 2: Manual Install

npm install rbac-shield
# or
yarn add rbac-shield

🚀 Quick Start

1. Define Schema

Create lib/rbac.ts to define your types and export your instances.

// lib/rbac.ts
"use client";
import { createRBAC } from "rbac-shield";

export type Resources = "projects" | "billing" | "users";
export type Actions = "view" | "create" | "edit" | "delete";

export const {
  RBACProvider,
  useRBAC,
  useHasRole,
  useHasPermission,
  useAccess, // Hook returning check function
  useActionMatch, // Dynamic role/permission matcher
  Can,
  ProtectedRoute,
  guard,
} = createRBAC<Resources, Actions>();

2. Wrap App

Wrap your root layout with the provider.

// app/layout.tsx
import { RBACProvider } from "@/lib/rbac";

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <RBACProvider>{children}</RBACProvider>
      </body>
    </html>
  );
}

3. Load Permissions

Initialize permissions. For async user data, wait for the user to load before setting auth.

Create the PermissionLoader Component

// components/PermissionLoader.tsx
"use client";
import { useEffect } from "react";
import { useRBAC } from "@/lib/rbac";
import { useUser } from "@/hooks/useUser";

export function PermissionLoader({ children }) {
  const { setAuth, switchTenant } = useRBAC();
  const { user, isLoading } = useUser();

  useEffect(() => {
    if (isLoading || !user) return;

    // Load Roles + Permissions
    setAuth([
      {
        tenantId: user.id || "default",
        roles: [user.role], // e.g. ["admin"]
        permissions: user.permissions, // e.g. ["projects:view"]
      },
    ]);

    switchTenant(user.id || "default");
  }, [user, isLoading]);

  if (isLoading || !user) return null; // Prevent render until authed
  return <>{children}</>;
}

Wrap Your App

// app/layout.tsx
import { RBACProvider } from "@/lib/rbac";
import { PermissionLoader } from "@/components/PermissionLoader";

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <RBACProvider>
          <PermissionLoader>{children}</PermissionLoader>
        </RBACProvider>
      </body>
    </html>
  );
}

4. Protect Routes

Use the components to guard access.

import { ProtectedRoute, Can, useHasRole, useAccess } from "@/lib/rbac";

export default function AdminDashboard() {
  const isSuperAdmin = useHasRole("super_admin");

  // Advanced: Get access checker function
  const hasAccess = useAccess();

  const canManage = hasAccess({
    roles: ["admin"],
    permissions: ["system:manage"],
  });

  return (
    <ProtectedRoute role={["admin", "super_admin"]} fallbackPath="/login">
      <h1>Admin Dashboard</h1>

      {/* Conditional Rendering */}
      <Can permission="billing:view">
        <BillingWidget />
      </Can>
    </ProtectedRoute>
  );
}

👑 Role Management & Logic

RBAC Shield uses a Unified Access Logic across all components.

Logic Matrix

Wildcards (`*`)

Roles: If user has role *, they pass ALL role checks.
Permissions: If user has permission *, they pass ALL permission checks.

Arrays (OR Logic)

Providing an array means "User must match ANY of these".

// Allow if user is 'admin' OR 'manager'
<ProtectedRoute role={["admin", "manager"]}>

� API Reference

Components

`<ProtectedRoute>`

Guards an entire route. Redirects if access denied.

role: string | string[]
permission: string | string[]
requireAll: boolean (Default: false - generally used for checking multiple permissions)
redirect: boolean (Default: true)
fallbackPath: string (Default: /)
fallback: ReactNode (Shown while redirecting)

`<Can>`

Conditionally renders children.

role: string | string[]
permission: string | string[]
fallback: ReactNode (Shown if denied)

Hooks

`useAccess({ roles?, permissions? })`

Returns boolean. Checks if user matches ANY of the roles OR ANY of the permissions.

Returns boolean. Checks for specific role (or wildcard).

Executes logic based on roles or permissions. Checks role handlers first, then permission handlers, then falls back to default.

const content = useActionMatch({
  role: {
    admin: () => <AdminDashboard />,
    manager: () => <ManagerDashboard />,
  },
  permission: {
    "reports:view": () => <ReportsView />,
  },
  default: () => <GuestView />,
});

Access raw state (isLoading, activeTenantId, etc.) and actions (setAuth).

🛡️ Best Practices

Server-Side Verification: Always verify permissions on the server (API Routes, Server Actions) using the checkPermission utility or guard wrapper. Client-side checks are for UX only.
Combine Checks: Use Roles for high-level page access, and Permissions for specific button visibility.