rbac-shield 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RBAC Shield Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,299 @@
+# 🔐 RBAC Shield
+
+[![npm version](https://img.shields.io/npm/v/rbac-shield.svg)](https://www.npmjs.com/package/rbac-shield)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
+[![Downloads](https://img.shields.io/npm/dt/rbac-shield.svg)](https://www.npmjs.com/package/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 just works.
+
+---
+
+## 📑 Table of Contents
+
+- [Features](#-features)
+- [Quick Setup (CLI)](#-quick-setup-recommended)
+- [Manual Installation](#-manual-installation)
+- [Quick Start](#-quick-start)
+- [API Reference](#-api-reference)
+- [Advanced Usage](#-advanced-usage)
+- [Security & Best Practices](#-security--best-practices)
+- [Troubleshooting](#-troubleshooting)
+
+---
+
+## ✨ Features
+
+- 🎯 **Type-Safe Permissions**: Full TypeScript support with intelligent autocomplete for your specific resources and actions.
+- 🚀 **High Performance**: Optimized with React Context and memoization. Permission checks are < 1ms.
+- 🏢 **Multi-Tenant Native**: Switch between multiple organizations/roles instantly without page reloads.
+- 🛡️ **Route Protection**: Declarative client-side guards with automatic handling of loading states and redirects.
+- 🔄 **SSR & Hydration Safe**: Built from the ground up for Next.js App Router—no hydration mismatches.
+- 🌍 **Universal Support**: Works seamlessly in **Client Components**, **Server Components**, and **Middleware**.
+- 📦 **Zero Dependencies**: Lightweight (~35KB) and built entirely on standard React APIs.
+
+---
+
+## 🚀 Quick Setup (Recommended)
+
+The fastest way to integrate RBAC Shield is with our interactive CLI. It initializes your configuration and handles all boilerplate.
+
+```bash
+npx rbac-shield init
+```
+
+The CLI will:
+
+1. Detect your project type (Next.js/React, TS/JS)
+2. Help you define your resources (e.g., `projects`) and actions (e.g., `create`)
+3. Generate a clean, type-safe `lib/rbac.ts` file configured for your app
+
+---
+
+## 📦 Manual Installation
+
+If you prefer to set things up yourself:
+
+```bash
+npm install rbac-shield
+# or
+yarn add rbac-shield
+# or
+pnpm add rbac-shield
+# or
+bun add rbac-shield
+```
+
+**Peer Dependencies:**
+Ensure you have peer dependencies installed (standard in Next.js apps):
+`react >= 18.0.0`, `react-dom >= 18.0.0`, `next >= 13.0.0`
+
+---
+
+## 🚀 Quick Start
+
+### 1. Define Your Schema
+
+Create a single source of truth for your permissions in `lib/rbac.ts` (or `config/rbac.ts`).
+
+```typescript
+// lib/rbac.ts
+import { createRBAC } from "rbac-shield";
+
+// 1. Define resources (things you secure)
+export type Resources = "projects" | "billing" | "users" | "marketing";
+
+// 2. Define actions (what users can do)
+export type Actions = "view" | "create" | "edit" | "delete" | "export";
+
+// 3. Create your instances
+export const {
+  RBACProvider,
+  useStore,
+  useHasPermission,
+  useHasAnyPermission,
+  useHasAllPermissions,
+  usePermissions,
+  Can,
+  ProtectedRoute,
+} = createRBAC<Resources, Actions>();
+```
+
+### 2. Wrap Your App
+
+Add the provider to your root layout to enable state management.
+
+```tsx
+// app/layout.tsx
+import { RBACProvider } from "@/lib/rbac";
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en">
+      <body>
+        <RBACProvider>{children}</RBACProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+### 3. Load Permissions
+
+Initialize the system with data from your backend (e.g., after login).
+
+```tsx
+// components/AuthProvider.tsx
+"use client";
+import { useEffect } from "react";
+import { useStore } from "@/lib/rbac";
+
+export function AuthProvider({
+  user,
+  children,
+}: {
+  user: any;
+  children: React.ReactNode;
+}) {
+  const { setAuth, switchTenant } = useStore();
+
+  useEffect(() => {
+    if (user) {
+      // Load permissions into RBAC Shield
+      setAuth([
+        {
+          tenantId: "team-123",
+          permissions: ["projects:view", "projects:edit"],
+        },
+      ]);
+      // Activate the context
+      switchTenant("team-123");
+    }
+  }, [user, setAuth, switchTenant]);
+
+  return <>{children}</>;
+}
+```
+
+### 4. Secure Your App
+
+Use the generated hooks and components anywhere.
+
+```tsx
+import { ProtectedRoute, Can, useHasPermission } from "@/lib/rbac";
+
+export default function ProjectSettings() {
+  const canDelete = useHasPermission("projects:delete");
+
+  return (
+    // 1. Protect Example: Redirects to / if missing permission
+    <ProtectedRoute requiredPermission="projects:edit" fallbackPath="/">
+      <h1>Project Settings</h1>
+
+      {/* 2. Conditional Render Example */}
+      <Can permission="billing:view" fallback={<p>Upgrade to see billing</p>}>
+        <BillingWidget />
+      </Can>
+
+      {/* 3. Hook Logic Example */}
+      <button disabled={!canDelete}>Delete Project</button>
+    </ProtectedRoute>
+  );
+}
+```
+
+---
+
+## 📚 API Reference
+
+### `<ProtectedRoute>`
+
+A wrapper component that guards an entire route or section.
+
+- **requiredPermission**: `Resources:Actions` string (e.g., `billing:view`).
+- **fallbackPath**: (Optional) URL to redirect to if unauthorized. Default: `/`.
+- **fallback**: (Optional) React Node to render instead of redirecting.
+
+### `<Can>`
+
+A structural component for showing/hiding UI elements.
+
+- **permission**: The required permission string.
+- **fallback**: (Optional) UI to show when permission is denied.
+
+### `useHasPermission(permission)`
+
+Returns `boolean`. Checks for exact permission match or wildcard `*`.
+
+### `useHasAnyPermission([perm1, perm2])`
+
+Returns `boolean`. True if user has **at least one** of the listed permissions.
+
+### `useHasAllPermissions([perm1, perm2])`
+
+Returns `boolean`. True only if user has **every single** listed permission.
+
+### `useStore()`
+
+Access raw state and actions:
+
+- `isLoading`: `boolean`
+- `activeTenantId`: `string | null`
+- `switchTenant(id)`: Change active context
+- `setAuth(authData)`: Load permission data
+
+---
+
+## � Security & Best Practices
+
+> [!IMPORTANT] > **Client-side checks are for User Experience (UX) only.**
+
+RBAC Shield controls what the user _sees_ in the browser, but it cannot stop a determined attacker from crafting API requests manually.
+
+### 1. Server-Side Verification (Universal)
+
+Use the universal `checkPermission` helper in Middleware, Server Actions, or API Routes:
+
+```tsx
+import { checkPermission } from "rbac-shield";
+// 1. Middleware Example
+export function middleware(req) {
+  const permissions = getPermissionsFromCookie(req);
+  if (!checkPermission(permissions, "admin:access")) {
+    return NextResponse.redirect(new URL("/403", req.url));
+  }
+}
+
+// 2. Server Action Example
+export async function deleteProject() {
+  const user = await getCurrentUser();
+  if (!checkPermission(user.permissions, "projects:delete")) {
+    throw new Error("Unauthorized");
+  }
+}
+```
+
+### 2. Debug Mode
+
+Troubleshooting permissions is easier with debug mode enabled.
+
+```tsx
+<RBACProvider debug={true}>{children}</RBACProvider>
+```
+
+This logs helpful messages to the console:
+
+- `[RBAC Shield] Permissions loaded for tenants: ['org_1']`
+- `[RBAC Shield] Denied: Required 'billing:edit', User has ['projects:view']`
+
+### 3. Production Checklist
+
+1.  **API Validation**: Every API route and Server Action MUST verify permissions independently on the server using `checkPermission()`.
+2.  **Middleware**: Use Next.js Middleware to protect route segments (`/admin/*`) before they even render.
+3.  **RBAC Shield**: Use this library's components (Client-Side) to hide UI elements for a smooth experience.
+
+---
+
+## 🐛 Troubleshooting
+
+| Issue                  | Solution                                                                                                       |
+| ---------------------- | -------------------------------------------------------------------------------------------------------------- |
+| **Infinite Loading**   | Ensure `RBACProvider` wraps your app and `setAuth` is called with valid data.                                  |
+| **Type Errors**        | Verify your `Resources` and `Actions` types in `lib/rbac.ts` are exported.                                     |
+| **Hydration Mismatch** | `ProtectedRoute` and `Can` are client components; ensure they are used in client contexts or wrapped properly. |
+
+---
+
+## 🤝 Contributing
+
+We welcome contributions! Please open an issue or submit a PR on our [GitHub repository](https://github.com/your-repo/rbac-shield).
+
+## 📄 License
+
+MIT © [Arif Hossain Roman](https://github.com/your-username)

package/bin/cli.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+
+const { program } = require('commander');
+const chalk = require('chalk');
+const packageJson = require('../package.json');
+
+program
+  .name('rbac-shield')
+  .description('Interactive CLI for RBAC Shield setup')
+  .version(packageJson.version);
+
+program
+  .command('init')
+  .description('Initialize RBAC Shield in your project')
+  .action(async () => {
+    try {
+      const init = require('./init');
+      await init();
+    } catch (error) {
+      console.error(chalk.red('Error:'), error.message);
+      process.exit(1);
+    }
+  });
+
+// Show help if no command provided
+if (!process.argv.slice(2).length) {
+  program.outputHelp();
+}
+
+program.parse(process.argv);

package/bin/init.js

@@ -0,0 +1,176 @@
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const prompts = require('prompts');
+const chalk = require('chalk');
+const { getTemplate, TEMPLATES } = require('./templates');
+const { 
+  detectFramework, 
+  isTypeScriptProject, 
+  ensureDirectory, 
+  fileExists,
+  showNextSteps 
+} = require('./utils');
+
+async function init() {
+  console.log(chalk.cyan.bold('\n🔐 RBAC Shield - Interactive Setup'));
+  console.log(chalk.cyan('━'.repeat(40)) + '\n');
+
+  // Detect project type
+  const framework = detectFramework();
+  const hasTypeScript = isTypeScriptProject();
+
+  if (framework) {
+    console.log(chalk.green(`✓ Detected ${framework} project\n`));
+  }
+
+  // Check if rbac-shield is already installed
+  const isInstalled = fileExists(path.join(process.cwd(), 'node_modules', 'rbac-shield'));
+
+  // Prompt for language
+  const { language } = await prompts({
+    type: 'select',
+    name: 'language',
+    message: 'Use TypeScript or JavaScript?',
+    choices: [
+      { title: 'TypeScript', value: 'typescript', selected: hasTypeScript },
+      { title: 'JavaScript', value: 'javascript' }
+    ],
+    initial: hasTypeScript ? 0 : 1
+  });
+
+  if (!language) {
+    console.log(chalk.yellow('\n✖ Setup cancelled'));
+    process.exit(0);
+  }
+
+  // Prompt for template
+  const { template } = await prompts({
+    type: 'select',
+    name: 'template',
+    message: 'Choose a template:',
+    choices: [
+      { 
+        title: 'Basic (projects, users, settings)', 
+        value: 'basic',
+        description: 'General purpose RBAC setup'
+      },
+      { 
+        title: 'E-commerce (products, orders, customers)', 
+        value: 'ecommerce',
+        description: 'For online stores and marketplaces'
+      },
+      { 
+        title: 'SaaS (workspaces, billing, teams)', 
+        value: 'saas',
+        description: 'For multi-tenant SaaS applications'
+      },
+      { 
+        title: 'Custom (define your own)', 
+        value: 'custom',
+        description: 'Specify your own resources and actions'
+      }
+    ],
+    initial: 0
+  });
+
+  if (!template) {
+    console.log(chalk.yellow('\n✖ Setup cancelled'));
+    process.exit(0);
+  }
+
+  let resources, actions;
+
+  if (template === 'custom') {
+    // Prompt for custom resources and actions
+    const customConfig = await prompts([
+      {
+        type: 'text',
+        name: 'resources',
+        message: 'Enter resource types (comma-separated):',
+        initial: 'projects, users, settings',
+        validate: value => value.trim().length > 0 || 'Please enter at least one resource'
+      },
+      {
+        type: 'text',
+        name: 'actions',
+        message: 'Enter action types (comma-separated):',
+        initial: 'view, create, edit, delete',
+        validate: value => value.trim().length > 0 || 'Please enter at least one action'
+      }
+    ]);
+
+    if (!customConfig.resources || !customConfig.actions) {
+      console.log(chalk.yellow('\n✖ Setup cancelled'));
+      process.exit(0);
+    }
+
+    resources = customConfig.resources.split(',').map(r => r.trim()).filter(Boolean);
+    actions = customConfig.actions.split(',').map(a => a.trim()).filter(Boolean);
+  } else {
+    const templateData = TEMPLATES[template];
+    resources = templateData.resources;
+    actions = templateData.actions;
+
+    // Confirm template
+    const { confirmed } = await prompts({
+      type: 'confirm',
+      name: 'confirmed',
+      message: `Use resources: ${resources.join(', ')} and actions: ${actions.join(', ')}?`,
+      initial: true
+    });
+
+    if (!confirmed) {
+      console.log(chalk.yellow('\n✖ Setup cancelled'));
+      process.exit(0);
+    }
+  }
+
+  console.log('');
+
+  // Install rbac-shield if not installed
+  if (!isInstalled) {
+    console.log(chalk.blue('📦 Installing rbac-shield...'));
+    try {
+      execSync('npm install rbac-shield', { stdio: 'inherit' });
+      console.log(chalk.green('✓ rbac-shield installed\n'));
+    } catch (error) {
+      console.error(chalk.red('✖ Failed to install rbac-shield'));
+      console.error(chalk.yellow('Please install manually: npm install rbac-shield'));
+      process.exit(1);
+    }
+  }
+
+  // Create lib directory
+  const libDir = path.join(process.cwd(), 'lib');
+  ensureDirectory(libDir);
+
+  // Generate config file
+  const ext = language === 'typescript' ? 'ts' : 'js';
+  const configPath = path.join(libDir, `rbac.${ext}`);
+
+  if (fileExists(configPath)) {
+    const { overwrite } = await prompts({
+      type: 'confirm',
+      name: 'overwrite',
+      message: `${configPath} already exists. Overwrite?`,
+      initial: false
+    });
+
+    if (!overwrite) {
+      console.log(chalk.yellow('\n✖ Setup cancelled'));
+      process.exit(0);
+    }
+  }
+
+  const configContent = getTemplate(template, language, resources, actions);
+  fs.writeFileSync(configPath, configContent, 'utf8');
+
+  console.log(chalk.green(`✓ Created lib/rbac.${ext}`));
+  console.log(chalk.green('✓ Setup complete!\n'));
+
+  // Show next steps
+  showNextSteps(framework, language);
+}
+
+module.exports = init;

package/bin/templates.js

@@ -0,0 +1,68 @@
+const TEMPLATES = {
+  basic: {
+    resources: ['projects', 'users', 'settings'],
+    actions: ['view', 'create', 'edit', 'delete']
+  },
+  ecommerce: {
+    resources: ['products', 'orders', 'customers', 'inventory'],
+    actions: ['view', 'create', 'edit', 'delete', 'manage']
+  },
+  saas: {
+    resources: ['workspaces', 'billing', 'teams', 'api-keys'],
+    actions: ['view', 'create', 'edit', 'delete', 'manage']
+  }
+};
+
+function getTemplate(templateName, language, resources, actions) {
+  const isTypeScript = language === 'typescript';
+  
+  const resourcesType = resources.map(r => `'${r}'`).join(' | ');
+  const actionsType = actions.map(a => `'${a}'`).join(' | ');
+
+  if (isTypeScript) {
+    return `import { createRBAC } from 'rbac-shield';
+
+// Define your application's resources
+export type Resources = ${resourcesType};
+
+// Define your application's actions
+export type Actions = ${actionsType};
+
+// Initialize RBAC with your types
+export const { 
+  RBACProvider,
+  useStore, 
+  useHasPermission, 
+  useHasAnyPermission,
+  useHasAllPermissions,
+  usePermissions,
+  Can,
+  RBACErrorBoundary,
+  ProtectedRoute,
+} = createRBAC<Resources, Actions>();
+`;
+  } else {
+    return `import { createRBAC } from 'rbac-shield';
+
+// Initialize RBAC
+// Resources: ${resources.join(', ')}
+// Actions: ${actions.join(', ')}
+export const { 
+  RBACProvider,
+  useStore, 
+  useHasPermission, 
+  useHasAnyPermission,
+  useHasAllPermissions,
+  usePermissions,
+  Can,
+  RBACErrorBoundary,
+  ProtectedRoute,
+} = createRBAC();
+`;
+  }
+}
+
+module.exports = {
+  TEMPLATES,
+  getTemplate
+};