secure-role-guard 1.0.0 → 1.0.2

package/README.md

@@ -1,9 +1,8 @@
 # secure-role-guard
 
-> Zero-vulnerability, framework-agnostic RBAC authorization library for React and Node.js applications.
+> Zero-dependency RBAC authorization for React & Node.js. Define roles once, use everywhere.
 
 [![npm version](https://img.shields.io/npm/v/secure-role-guard.svg)](https://www.npmjs.com/package/secure-role-guard)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
 [![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](https://www.npmjs.com/package/secure-role-guard)
 
@@ -11,73 +10,18 @@
 
 ---
 
-## Table of Contents
+## 🚀 Quick Overview
 
-- [What This Package Does](#what-this-package-does)
-- [What This Package Does NOT Do](#what-this-package-does-not-do)
-- [Security Guarantees](#security-guarantees)
-- [Installation](#installation)
-- [Quick Start](#quick-start)
-- [API Reference](#api-reference)
-- [Real-World Examples](#real-world-examples)
-- [Framework Compatibility](#framework-compatibility)
-- [Common Mistakes to Avoid](#common-mistakes-to-avoid)
-- [License](#license)
+| Custom Code (Without Package)       | With secure-role-guard      |
+| ----------------------------------- | --------------------------- |
+| Write permission logic everywhere   | Define once, use everywhere |
+| Handle null/undefined edge cases    | Built-in, tested            |
+| Different code for frontend/backend | Same API everywhere         |
+| 2-4 hours setup                     | 10 minutes setup            |
 
 ---
 
-## What This Package Does ✅
-
-| Feature                       | Description                                             |
-| ----------------------------- | ------------------------------------------------------- |
-| **Role-Based Access Control** | Define roles with granular permissions                  |
-| **Pure Permission Checking**  | Deterministic, side-effect-free authorization           |
-| **React Integration**         | Provider, hooks, and components for any React framework |
-| **Backend Adapters**          | Optional Express and Next.js middleware                 |
-| **Wildcard Support**          | Grant access with `*` (all) or `namespace.*` patterns   |
-| **TypeScript First**          | Full type safety with strict mode                       |
-| **Zero Dependencies**         | Core has zero runtime dependencies                      |
-| **Framework Agnostic**        | Works with Next.js, Remix, Gatsby, Astro, Vite, CRA     |
-
----
-
-## What This Package Does NOT Do ❌
-
-> **CRITICAL:** This package handles **AUTHORIZATION** only, **NOT AUTHENTICATION**.
-
-| This Package Does NOT | You Must Handle This                   |
-| --------------------- | -------------------------------------- |
-| Parse JWT tokens      | Use a JWT library (jsonwebtoken, jose) |
-| Verify authentication | Use Auth.js, Clerk, NextAuth, Passport |
-| Read cookies          | Use your framework's cookie API        |
-| Manage sessions       | Use express-session, iron-session      |
-| Make network requests | Fetch user data yourself               |
-| Access databases      | Query your DB to get user roles        |
-| Store global state    | Pass user context explicitly           |
-
-### Why?
-
-Authorization and authentication are **separate concerns**. Mixing them creates security vulnerabilities. This package focuses on **one job** and does it correctly.
-
----
-
-## Security Guarantees
-
-| Guarantee                | Implementation                                     |
-| ------------------------ | -------------------------------------------------- |
-| ✅ **Deny by default**   | Undefined permissions return `false`               |
-| ✅ **Immutable configs** | Role definitions are frozen with `Object.freeze()` |
-| ✅ **Pure functions**    | No side effects, no state mutations                |
-| ✅ **No eval/regex**     | Only strict string matching                        |
-| ✅ **Zero dependencies** | Core has zero runtime dependencies                 |
-| ✅ **TypeScript strict** | Full strict mode compilation                       |
-| ✅ **No global state**   | All state is passed explicitly                     |
-| ✅ **No network calls**  | Never makes HTTP requests                          |
-| ✅ **No file system**    | Never reads or writes files                        |
-
----
-
-## Installation
+## 📦 Installation
 
 ```bash
 npm install secure-role-guard
@@ -87,275 +31,122 @@ pnpm add secure-role-guard
 yarn add secure-role-guard
 ```
 
-**Peer Dependencies:**
+---
+
+## 📖 Usage Guide
+
+Choose your setup:
 
-- React ≥16.8.0 (optional, only needed for React features)
+| I want to use in...         | Jump to                         |
+| --------------------------- | ------------------------------- |
+| **React/Next.js only**      | [Frontend Only](#frontend-only) |
+| **Express/Node.js only**    | [Backend Only](#backend-only)   |
+| **Both Frontend + Backend** | [Full Stack](#full-stack)       |
 
 ---
 
-## Quick Start
+## Frontend Only
 
-### 1. Define Your Roles
+### Step 1: Define Roles
 
 ```typescript
-// roles.ts
+// lib/roles.ts
 import { defineRoles } from "secure-role-guard";
 
 export const roleRegistry = defineRoles({
-  superadmin: ["*"], // Full access
-  admin: ["user.read", "user.update", "user.delete", "report.view"],
-  manager: ["user.read", "report.*"], // Namespace wildcard
-  support: ["ticket.read", "ticket.reply"],
+  admin: ["user.create", "user.read", "user.update", "user.delete"],
+  manager: ["user.read", "user.update"],
   viewer: ["user.read"],
 });
 ```
 
-### 2. Check Permissions (Core - No React)
-
-```typescript
-import { canUser } from "secure-role-guard";
-import { roleRegistry } from "./roles";
-
-// Your user context (from your auth system)
-const user = {
-  userId: "user-123",
-  roles: ["admin"],
-  permissions: ["custom.feature"], // Direct permissions
-};
-
-// Simple checks
-canUser(user, "user.update", roleRegistry); // true
-canUser(user, "user.delete", roleRegistry); // true
-canUser(user, "billing.access", roleRegistry); // false (deny by default)
-```
-
-### 3. React Integration
+### Step 2: Setup Provider
 
 ```tsx
-import { PermissionProvider, Can, useCan } from "secure-role-guard";
-import { roleRegistry } from "./roles";
+// app/providers.tsx (Next.js App Router)
+// or src/App.tsx (Vite/CRA)
+"use client";
 
-// Wrap your app with the provider
-function App() {
-  const user = useAuth(); // YOUR auth hook (not from this package)
+import { PermissionProvider } from "secure-role-guard/react";
+import { roleRegistry } from "@/lib/roles";
 
+export function Providers({ children, user }) {
+  // user = { roles: ['admin'], permissions: [] } from your auth
   return (
     <PermissionProvider user={user} registry={roleRegistry}>
-      <Dashboard />
+      {children}
     </PermissionProvider>
   );
 }
+```
+
+### Step 3: Use in Components
+
+```tsx
+import { Can, useCan } from "secure-role-guard/react";
 
-// Use the Can component for declarative rendering
 function Dashboard() {
+  const canDelete = useCan("user.delete");
+
   return (
     <div>
+      {/* Method 1: Component */}
+      <Can permission="user.create">
+        <button>Add User</button>
+      </Can>
+
       <Can permission="user.update">
-        <EditUserButton />
+        <button>Edit User</button>
       </Can>
 
-      <Can permission="admin.access" fallback={<UpgradePrompt />}>
+      {/* Method 2: Hook */}
+      {canDelete && <button>Delete User</button>}
+
+      {/* With fallback */}
+      <Can permission="admin.access" fallback={<p>Access Denied</p>}>
         <AdminPanel />
       </Can>
 
-      <Can permissions={["report.view", "report.export"]} anyOf>
-        <ReportSection />
+      {/* Multiple permissions (ANY) */}
+      <Can permissions={["user.update", "user.delete"]} anyOf>
+        <UserActions />
       </Can>
     </div>
   );
 }
-
-// Or use hooks for programmatic checks
-function UserActions() {
-  const canEdit = useCan("user.update");
-  const canDelete = useCan("user.delete");
-
-  return (
-    <div>
-      {canEdit && <button>Edit</button>}
-      {canDelete && <button>Delete</button>}
-    </div>
-  );
-}
 ```
 
----
+**That's it for frontend!** ✅
 
-## API Reference
-
-### Core Functions
+---
 
-#### `defineRoles(definitions)`
+## Backend Only
 
-Creates an immutable role registry.
+### Step 1: Define Roles
 
 ```typescript
-const registry = defineRoles({
-  admin: ["user.read", "user.update"],
+// lib/roles.ts
+import { defineRoles } from "secure-role-guard/core";
+
+export const roleRegistry = defineRoles({
+  admin: ["user.create", "user.read", "user.update", "user.delete"],
+  manager: ["user.read", "user.update"],
   viewer: ["user.read"],
 });
 ```
 
-#### `canUser(user, permission, registry)`
-
-Checks if a user has a specific permission. Returns `boolean`.
-
-```typescript
-const allowed = canUser(user, "user.update", registry);
-```
-
-#### `canUserAll(user, permissions, registry)`
-
-Checks if a user has ALL specified permissions.
-
-```typescript
-const allowed = canUserAll(user, ["user.read", "user.update"], registry);
-```
-
-#### `canUserAny(user, permissions, registry)`
-
-Checks if a user has ANY of the specified permissions.
-
-```typescript
-const allowed = canUserAny(
-  user,
-  ["admin.access", "moderator.access"],
-  registry
-);
-```
-
-### React Components
-
-#### `<PermissionProvider>`
-
-Provides permission context to child components.
-
-```tsx
-<PermissionProvider user={user} registry={registry}>
-  {children}
-</PermissionProvider>
-```
-
-#### `<Can>`
-
-Conditionally renders children based on permissions.
-
-| Prop          | Type        | Description                           |
-| ------------- | ----------- | ------------------------------------- |
-| `permission`  | `string`    | Single permission to check            |
-| `permissions` | `string[]`  | Multiple permissions to check         |
-| `anyOf`       | `boolean`   | If true, ANY permission grants access |
-| `fallback`    | `ReactNode` | Content to show if denied             |
-| `children`    | `ReactNode` | Content to show if allowed            |
-
-#### `<Cannot>`
-
-Inverse of `<Can>` - renders when permission is NOT granted.
-
-### React Hooks
-
-| Hook                     | Returns                  | Description             |
-| ------------------------ | ------------------------ | ----------------------- |
-| `useCan(permission)`     | `boolean`                | Check single permission |
-| `useCanAll(permissions)` | `boolean`                | Check ALL permissions   |
-| `useCanAny(permissions)` | `boolean`                | Check ANY permission    |
-| `usePermissions()`       | `PermissionContextValue` | Full context access     |
-| `useUser()`              | `UserContext \| null`    | Current user            |
-
-### User Context Shape
-
-```typescript
-type UserContext = {
-  userId?: string; // Optional user identifier
-  roles?: string[]; // Array of role names
-  permissions?: string[]; // Direct permissions (bypass roles)
-  meta?: Record<string, unknown>; // Custom metadata (tenant, org, etc.)
-};
-```
-
-### Wildcard Permissions
-
-| Pattern          | Grants Access To                                 |
-| ---------------- | ------------------------------------------------ |
-| `*`              | Everything                                       |
-| `user.*`         | `user.read`, `user.update`, `user.delete`, etc.  |
-| `report.admin.*` | `report.admin.view`, `report.admin.export`, etc. |
-
----
-
-## Real-World Examples
-
-### Example 1: Next.js App with Express Backend
-
-**Frontend (Next.js App Router):**
-
-```tsx
-// app/providers.tsx
-"use client";
-
-import { PermissionProvider } from "secure-role-guard/react";
-import { roleRegistry } from "@/lib/roles";
-
-export function Providers({
-  children,
-  user,
-}: {
-  children: React.ReactNode;
-  user: UserContext;
-}) {
-  return (
-    <PermissionProvider user={user} registry={roleRegistry}>
-      {children}
-    </PermissionProvider>
-  );
-}
-
-// app/layout.tsx
-import { Providers } from "./providers";
-import { getUser } from "@/lib/auth"; // YOUR auth function
-
-export default async function RootLayout({ children }) {
-  const user = await getUser(); // Fetch from session/JWT
-
-  return (
-    <html>
-      <body>
-        <Providers user={user}>{children}</Providers>
-      </body>
-    </html>
-  );
-}
-
-// app/admin/page.tsx
-import { Can } from "secure-role-guard/react";
-
-export default function AdminPage() {
-  return (
-    <Can permission="admin.access" fallback={<p>Access Denied</p>}>
-      <h1>Admin Dashboard</h1>
-    </Can>
-  );
-}
-```
-
-**Backend (Express.js):**
+### Step 2: Use in Express
 
 ```typescript
 // server.ts
 import express from "express";
-import { defineRoles } from "secure-role-guard/core";
 import { requirePermission } from "secure-role-guard/adapters/express";
+import { roleRegistry } from "./lib/roles";
 
 const app = express();
 
-// Define roles (same as frontend)
-const roleRegistry = defineRoles({
-  admin: ["user.read", "user.update", "user.delete"],
-  viewer: ["user.read"],
-});
-
-// YOUR auth middleware (not from this package)
-app.use(authMiddleware); // Sets req.user
+// Your auth middleware (sets req.user)
+app.use(yourAuthMiddleware);
 
 // Protected routes
 app.get(
@@ -366,11 +157,11 @@ app.get(
   }
 );
 
-app.put(
-  "/api/users/:id",
-  requirePermission("user.update", roleRegistry),
+app.post(
+  "/api/users",
+  requirePermission("user.create", roleRegistry),
   (req, res) => {
-    res.json({ success: true });
+    res.json({ created: true });
   }
 );
 
@@ -381,433 +172,157 @@ app.delete(
     res.json({ deleted: true });
   }
 );
-
-app.listen(3000);
 ```
 
----
-
-### Example 2: React-Only App (Vite/CRA)
-
-```tsx
-// src/roles.ts
-import { defineRoles } from "secure-role-guard";
-
-export const roleRegistry = defineRoles({
-  admin: ["*"],
-  editor: ["post.read", "post.create", "post.update"],
-  viewer: ["post.read"],
-});
-
-// src/App.tsx
-import { PermissionProvider } from "secure-role-guard";
-import { roleRegistry } from "./roles";
-import { useAuth } from "./auth"; // YOUR auth hook
-
-function App() {
-  const { user, isLoading } = useAuth();
-
-  if (isLoading) return <div>Loading...</div>;
-
-  return (
-    <PermissionProvider user={user} registry={roleRegistry}>
-      <Router>
-        <Routes>
-          <Route path="/" element={<Home />} />
-          <Route path="/posts" element={<PostList />} />
-          <Route path="/admin" element={<AdminRoute />} />
-        </Routes>
-      </Router>
-    </PermissionProvider>
-  );
-}
-
-// src/components/AdminRoute.tsx
-import { useCan } from "secure-role-guard";
-import { Navigate } from "react-router-dom";
-
-function AdminRoute() {
-  const canAccess = useCan("admin.access");
-
-  if (!canAccess) {
-    return <Navigate to="/" replace />;
-  }
-
-  return <AdminPanel />;
-}
-
-// src/components/PostActions.tsx
-import { Can, Cannot } from "secure-role-guard";
-
-function PostActions({ postId }: { postId: string }) {
-  return (
-    <div>
-      <Can permission="post.update">
-        <button onClick={() => editPost(postId)}>Edit</button>
-      </Can>
-
-      <Can permission="post.delete">
-        <button onClick={() => deletePost(postId)}>Delete</button>
-      </Can>
-
-      <Cannot permission="post.update">
-        <span>View Only</span>
-      </Cannot>
-    </div>
-  );
-}
-```
-
----
-
-### Example 3: Astro with React
+### Manual Check (Without Middleware)
 
 ```typescript
-// src/lib/roles.ts
-import { defineRoles } from 'secure-role-guard';
+import { canUser } from "secure-role-guard/core";
 
-export const roleRegistry = defineRoles({
-  admin: ['page.edit', 'page.publish', 'settings.manage'],
-  editor: ['page.edit'],
-  viewer: [],
+app.put("/api/users/:id", (req, res) => {
+  if (!canUser(req.user, "user.update", roleRegistry)) {
+    return res.status(403).json({ error: "Forbidden" });
+  }
+  // ... your logic
 });
+```
 
-// src/components/AdminPanel.tsx (React component)
-import { PermissionProvider, Can, useCan } from 'secure-role-guard';
-import { roleRegistry } from '../lib/roles';
-
-interface Props {
-  user: { roles: string[] } | null;
-}
-
-export default function AdminPanel({ user }: Props) {
-  return (
-    <PermissionProvider user={user} registry={roleRegistry}>
-      <div className="admin-panel">
-        <Can permission="page.edit">
-          <PageEditor />
-        </Can>
-
-        <Can permission="settings.manage">
-          <SettingsPanel />
-        </Can>
-
-        <Can permission="page.publish" fallback={<p>Publishing not available</p>}>
-          <PublishButton />
-        </Can>
-      </div>
-    </PermissionProvider>
-  );
-}
-
-// src/pages/admin.astro
----
-import AdminPanel from '../components/AdminPanel';
-import { getUser } from '../lib/auth';
+**That's it for backend!** ✅
 
-const user = await getUser(Astro.request);
 ---
 
-<AdminPanel client:load user={user} />
-```
-
----
+## Full Stack
 
-### Example 4: Next.js API Routes (App Router)
+Use **same role definitions** for both:
 
 ```typescript
-// app/api/users/route.ts
-import { NextRequest, NextResponse } from "next/server";
-import { defineRoles, canUser } from "secure-role-guard/core";
-import { withPermission } from "secure-role-guard/adapters/nextjs";
-import { getUser } from "@/lib/auth";
-
-const roleRegistry = defineRoles({
-  admin: ["user.read", "user.update", "user.delete"],
-  viewer: ["user.read"],
-});
-
-// Option 1: Manual check
-export async function GET(request: NextRequest) {
-  const user = await getUser(request);
-
-  if (!canUser(user, "user.read", roleRegistry)) {
-    return NextResponse.json({ error: "Forbidden" }, { status: 403 });
-  }
-
-  const users = await fetchUsers();
-  return NextResponse.json(users);
-}
-
-// Option 2: Using wrapper
-export const PUT = withPermission(
-  "user.update",
-  roleRegistry,
-  { getUser: async (req) => getUser(req) },
-  async (request, user) => {
-    const body = await request.json();
-    const updated = await updateUser(body);
-    return NextResponse.json(updated);
-  }
-);
-```
-
----
-
-### Example 5: Multi-Tenant SaaS
+// shared/roles.ts (shared between frontend & backend)
+import { defineRoles } from "secure-role-guard";
 
-```typescript
-import { defineRoles, canUser } from "secure-role-guard";
-
-// Define roles for your multi-tenant application
-const roleRegistry = defineRoles({
-  org_owner: ["*"],
-  org_admin: ["user.*", "billing.view", "settings.update"],
-  org_member: ["user.read", "project.*"],
-  org_viewer: ["user.read", "project.read"],
+export const roleRegistry = defineRoles({
+  admin: ["*"], // Full access
+  manager: ["user.read", "user.update", "report.*"],
+  support: ["ticket.read", "ticket.reply"],
+  viewer: ["user.read"],
 });
-
-// User context with tenant metadata
-const currentUser = {
-  userId: "usr_abc123",
-  roles: ["org_admin"],
-  permissions: ["beta.feature"], // Direct permission for beta access
-  meta: {
-    tenantId: "tenant_xyz",
-    orgId: "org_456",
-    plan: "enterprise",
-  },
-};
-
-// Authorization check
-if (canUser(currentUser, "billing.view", roleRegistry)) {
-  // Show billing dashboard
-}
-
-// Access tenant metadata for additional business logic
-const tenantId = currentUser.meta?.tenantId;
-if (tenantId) {
-  // Filter data by tenant
-}
 ```
 
----
+**Frontend:** Follow [Frontend Only](#frontend-only) steps  
+**Backend:** Follow [Backend Only](#backend-only) steps
 
-## Framework Compatibility
-
-| Framework              | Status           | Import                               |
-| ---------------------- | ---------------- | ------------------------------------ |
-| Next.js (App Router)   | ✅ Full support  | `secure-role-guard`                  |
-| Next.js (Pages Router) | ✅ Full support  | `secure-role-guard`                  |
-| Remix                  | ✅ Full support  | `secure-role-guard`                  |
-| Gatsby                 | ✅ Full support  | `secure-role-guard`                  |
-| Astro (React)          | ✅ Full support  | `secure-role-guard`                  |
-| Vite + React           | ✅ Full support  | `secure-role-guard`                  |
-| Create React App       | ✅ Full support  | `secure-role-guard`                  |
-| Express.js             | ✅ Full support  | `secure-role-guard/adapters/express` |
-| Fastify                | 🔧 Adapter-ready | Use core directly                    |
-| Node HTTP              | ✅ Full support  | `secure-role-guard/core`             |
+> 💡 **Pro tip:** Keep roles in a shared package or copy to both projects.
 
 ---
 
-## Common Mistakes to Avoid
+## 📚 API Reference
 
-### ❌ DON'T: Parse JWT in this package
-
-```typescript
-// WRONG - This package doesn't handle authentication
-import { canUser } from "secure-role-guard";
+### Core Functions
 
-const token = req.headers.authorization;
-const decoded = jwt.verify(token, secret); // NOT our job
-```
+| Function                                  | Description             |
+| ----------------------------------------- | ----------------------- |
+| `defineRoles(roles)`                      | Create role registry    |
+| `canUser(user, permission, registry)`     | Check single permission |
+| `canUserAll(user, permissions, registry)` | Check ALL permissions   |
+| `canUserAny(user, permissions, registry)` | Check ANY permission    |
 
-### ✅ DO: Pass already-authenticated user context
+### React Components
 
-```typescript
-// CORRECT - You handle auth, we handle authorization
-import { canUser } from "secure-role-guard";
+| Component                   | Description         |
+| --------------------------- | ------------------- |
+| `<PermissionProvider>`      | Wrap your app       |
+| `<Can permission="...">`    | Show if allowed     |
+| `<Cannot permission="...">` | Show if NOT allowed |
 
-// Your auth middleware already verified and decoded the token
-const user = req.user; // Set by YOUR auth middleware
-const allowed = canUser(user, "admin.access", roleRegistry);
-```
+### React Hooks
 
----
+| Hook                     | Returns   |
+| ------------------------ | --------- |
+| `useCan(permission)`     | `boolean` |
+| `useCanAll(permissions)` | `boolean` |
+| `useCanAny(permissions)` | `boolean` |
 
-### ❌ DON'T: Store user in global state
+### User Context Shape
 
 ```typescript
-// WRONG - Global state is a security smell
-let currentUser = null; // Anti-pattern
+const user = {
+  userId: "user-123", // Optional
+  roles: ["admin", "manager"], // Role names
+  permissions: ["custom.perm"], // Direct permissions (bypass roles)
+  meta: { tenantId: "..." }, // Optional metadata
+};
 ```
 
-### ✅ DO: Pass user context explicitly
+### Wildcard Permissions
 
-```typescript
-// CORRECT - Explicit is better than implicit
-<PermissionProvider user={user} registry={roleRegistry}>
-  {children}
-</PermissionProvider>
-```
+| Pattern          | Grants                                           |
+| ---------------- | ------------------------------------------------ |
+| `*`              | Everything                                       |
+| `user.*`         | `user.read`, `user.update`, etc.                 |
+| `report.admin.*` | `report.admin.view`, `report.admin.export`, etc. |
 
 ---
 
-### ❌ DON'T: Use for authentication checks
+## 🔄 Dynamic Roles (From Database)
 
-```typescript
-// WRONG - This is authentication, not authorization
-if (canUser(user, "logged-in", registry)) {
-  // ...
-}
-```
-
-### ✅ DO: Check actual permissions
+If admin creates roles at runtime:
 
 ```typescript
-// CORRECT - This is authorization
-if (canUser(user, "user.update", registry)) {
-  // ...
-}
-```
+// Fetch roles from your database
+const rolesFromDB = await fetchRolesFromDB();
 
----
-
-### ❌ DON'T: Assume permissions exist
+// Transform to: { roleName: ['permission1', 'permission2'] }
+const roleDefinition = {};
+rolesFromDB.forEach((role) => {
+  roleDefinition[role.name] = role.permissions;
+});
 
-```typescript
-// WRONG - May throw or behave unexpectedly
-if (user.permissions.includes("admin")) {
-  // ...
-}
+// Create registry
+const registry = defineRoles(roleDefinition);
 ```
 
-### ✅ DO: Use the provided functions
-
-```typescript
-// CORRECT - Handles null/undefined safely (deny by default)
-if (canUser(user, "admin.access", registry)) {
-  // ...
-}
-```
+Works with **any database**: MongoDB, PostgreSQL, MySQL, SQLite, etc.
 
 ---
 
-## Backend Adapters
-
-### Express Middleware
-
-```typescript
-import {
-  requirePermission,
-  requireAllPermissions,
-  requireAnyPermission,
-} from "secure-role-guard/adapters/express";
-
-// Single permission
-app.get("/api/users", requirePermission("user.read", registry), handler);
-
-// All permissions required
-app.delete(
-  "/api/admin",
-  requireAllPermissions(["admin.access", "data.delete"], registry),
-  handler
-);
-
-// Any permission
-app.get(
-  "/api/reports",
-  requireAnyPermission(["report.view", "report.admin"], registry),
-  handler
-);
-
-// Custom options
-app.put(
-  "/api/settings",
-  requirePermission("settings.update", registry, {
-    statusCode: 401,
-    message: "Unauthorized",
-    getUser: (req) => req.session?.user,
-  }),
-  handler
-);
-```
+## ⚠️ Important Notes
 
-### Next.js Route Handlers
+### This Package Does NOT:
 
-```typescript
-import {
-  withPermission,
-  checkNextPermission,
-} from "secure-role-guard/adapters/nextjs";
-
-// Using wrapper
-export const POST = withPermission(
-  "post.create",
-  registry,
-  { getUser: async (req) => getUserFromSession(req) },
-  async (request, user) => {
-    return Response.json({ created: true });
-  }
-);
+- ❌ Handle authentication (JWT, sessions, cookies)
+- ❌ Make API/database calls
+- ❌ Store global state
 
-// Manual check
-export async function GET(request: NextRequest) {
-  const user = await getUser(request);
-  const result = checkNextPermission(user, "data.read", registry);
+**You provide:** User with roles → **We check:** Permissions
 
-  if (!result.allowed) {
-    return Response.json({ error: "Forbidden" }, { status: 403 });
-  }
+### Security
 
-  return Response.json({ data: [] });
-}
-```
+- ✅ Deny by default (undefined = false)
+- ✅ Zero dependencies in core
+- ✅ Immutable configurations
+- ✅ Pure functions (no side effects)
 
 ---
 
-## TypeScript Support
+## 🔒 Backward Compatibility
 
-This package is written in TypeScript with strict mode enabled:
+| Version       | Meaning                                    |
+| ------------- | ------------------------------------------ |
+| 1.0.x → 1.0.y | Bug fixes, safe to update                  |
+| 1.x.0 → 1.y.0 | New features, no breaking changes          |
+| 1.x.x → 2.0.0 | Breaking changes, migration guide provided |
 
-```typescript
-// tsconfig.json (package configuration)
-{
-  "compilerOptions": {
-    "strict": true,
-    "noImplicitAny": true,
-    "strictNullChecks": true,
-    "exactOptionalPropertyTypes": true
-  }
-}
-```
-
-All types are exported:
-
-```typescript
-import type {
-  UserContext,
-  RoleDefinition,
-  RoleRegistry,
-  PermissionCheckResult,
-} from "secure-role-guard";
-```
+**Promise:** v1.x APIs will never break. Update with confidence.
 
 ---
 
-## License
+## 📄 License
 
 MIT © [Sohel Rahaman](https://github.com/sohelrahaman)
 
 ---
 
-## Security Note
-
-This package is designed to be **boring, predictable, and auditable**. It intentionally avoids:
-
-- Magic behavior
-- Clever hacks
-- Hidden side effects
-- Runtime code generation
+## 🔗 Links
 
-If you find a security issue, please report it via [GitHub Issues](https://github.com/sohelrahaman/secure-role-guard/issues).
+- [GitHub Repository](https://github.com/Sohel-Rahaman-Developer/secure-role-guard)
+- [NPM Package](https://www.npmjs.com/package/secure-role-guard)
+- [Report Issues](https://github.com/Sohel-Rahaman-Developer/secure-role-guard/issues)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "secure-role-guard",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Zero-vulnerability, framework-agnostic RBAC authorization library for React applications",
   "author": "Sohel Rahaman",
   "license": "MIT",