@lbstack/accessx 0.1.0 → 0.3.0

package/dist/src/core/access-control.d.ts

@@ -1,23 +1,42 @@
-import { ConditionFn, Resource } from "../types";
+import * as React from "react";
+import { Resource } from "../types";
 export declare function createAccess<const R extends readonly string[], const A extends readonly string[], const Res extends readonly Resource[]>(config: {
     roles: R;
     actions: A;
     resources: Res;
 }): {
+    useCan: (role: R[number] | R[number][], permission: string, context?: any) => boolean;
+    Can: ({ role, permission, context, children, }: {
+        role: R[number] | R[number][];
+        permission: string;
+        context?: any;
+        children: React.ReactNode;
+    }) => import("react/jsx-runtime").JSX.Element | null;
+    usePermissions: (source: R[number] | string[] | (() => Promise<string[]>)) => {
+        permissions: string[];
+        loading: boolean;
+        refresh: () => Promise<void>;
+    };
+    refresh: (role?: R[number] | undefined) => Promise<void>;
+    canDo: (granted: any[], permission: string, context?: any) => boolean;
     roles: R;
     actions: A;
     resources: Res;
     permissions: {
-        key: "*" | `${Res[number]["key"]}:${A[number]}` | `${Res[number]["key"]}:*`;
+        key: import("./engine").PermissionKey<Res, A>;
         resource: Resource;
         action: string;
     }[];
-    permissionKeys: ("*" | `${Res[number]["key"]}:${A[number]}` | `${Res[number]["key"]}:*`)[];
-    allow: (role: R[number], permission: ("*" | `${Res[number]["key"]}:${A[number]}` | `${Res[number]["key"]}:*`) | ("*" | `${Res[number]["key"]}:${A[number]}` | `${Res[number]["key"]}:*`)[], condition?: ConditionFn) => void;
-    can: (role: R[number], permission: "*" | `${Res[number]["key"]}:${A[number]}` | `${Res[number]["key"]}:*`, context?: any) => boolean;
-    hasPermission: (granted: ("*" | `${Res[number]["key"]}:${A[number]}` | `${Res[number]["key"]}:*`)[], required: "*" | `${Res[number]["key"]}:${A[number]}` | `${Res[number]["key"]}:*`, context?: any) => boolean;
-    resolvePermissions: (role: R[number]) => ("*" | `${Res[number]["key"]}:${A[number]}` | `${Res[number]["key"]}:*`)[];
-    normalizePermissions: (raw: string[]) => ("*" | `${Res[number]["key"]}:${A[number]}` | `${Res[number]["key"]}:*`)[];
-    assignPermissions: (role: R[number], perms: ("*" | `${Res[number]["key"]}:${A[number]}` | `${Res[number]["key"]}:*`) | ("*" | `${Res[number]["key"]}:${A[number]}` | `${Res[number]["key"]}:*`)[], condition?: ConditionFn) => void;
-    getRolePermissions: (role: R[number]) => ("*" | `${Res[number]["key"]}:${A[number]}` | `${Res[number]["key"]}:*`)[];
+    permissionKeys: import("./engine").PermissionKey<Res, A>[];
+    allow: (role: R[number], permission: import("./engine").PermissionKey<Res, A> | import("./engine").PermissionKey<Res, A>[], condition?: import("../types").ConditionFn) => void;
+    can: (role: R[number] | R[number][], permission: import("./engine").PermissionKey<Res, A>, context?: any) => boolean;
+    resolvePermissions: (role: R[number]) => import("./engine").PermissionKey<Res, A>[];
+    normalizePermissions: (raw: string[]) => import("./engine").PermissionKey<Res, A>[];
+    getRolePermissions: (role: R[number]) => import("./engine").PermissionKey<Res, A>[];
+    assignPermissions: (role: R[number], perms: import("./engine").PermissionKey<Res, A> | import("./engine").PermissionKey<Res, A>[] | (() => Promise<import("./engine").PermissionKey<Res, A> | import("./engine").PermissionKey<Res, A>[]>), options?: import("../types").ConditionFn | {
+        condition?: import("../types").ConditionFn;
+        invalidateKey?: string | (() => Promise<string>) | undefined;
+        interval?: number;
+    } | undefined) => Promise<void>;
+    subscribe: (cb: () => void) => () => void;
 };

package/dist/src/core/access-control.js

@@ -1,85 +1,70 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import * as React from "react";
+import { createEngine } from "./engine";
+import { createAccessUI } from "./ui/access-control-ui";
 export function createAccess(config) {
-    const permissions = config.resources.flatMap((resource) => config.actions.map((action) => ({
-        key: `${resource.key}:${action}`,
-        resource,
-        action,
-    })));
-    const permissionKeys = permissions.map((p) => p.key);
-    // Store perms with optional conditions
-    const rolePermissions = new Map();
-    function assignPermissions(role, perms, condition) {
-        const list = Array.isArray(perms) ? perms : [perms];
-        if (!rolePermissions.has(role))
-            rolePermissions.set(role, new Map());
-        const permsMap = rolePermissions.get(role);
-        list.forEach((p) => permsMap.set(p, condition || (() => true)));
+    const engine = createEngine(config);
+    const { canDo } = createAccessUI();
+    /**
+     * Hook to manage permissions from various sources (static, dynamic, or engine-bound)
+     */
+    function usePermissions(source) {
+        const [perms, setPerms] = React.useState([]);
+        const [loading, setLoading] = React.useState(true);
+        const fetch = React.useCallback(async () => {
+            setLoading(true);
+            try {
+                if (typeof source === "function") {
+                    const res = await source();
+                    setPerms(res);
+                }
+                else if (Array.isArray(source)) {
+                    setPerms(source);
+                }
+                else {
+                    // Engine-bound role
+                    setPerms(engine.getRolePermissions(source));
+                }
+            }
+            finally {
+                setLoading(false);
+            }
+        }, [source]);
+        React.useEffect(() => {
+            fetch();
+            // If it's a role (string provided but not an array), subscribe to global refreshes
+            if (typeof source === "string" && !Array.isArray(source)) {
+                return engine.subscribe(() => {
+                    setPerms(engine.getRolePermissions(source));
+                });
+            }
+        }, [fetch, source]);
+        return { permissions: perms, loading, refresh: fetch };
     }
-    function getRolePermissions(role) {
-        const permsMap = rolePermissions.get(role);
-        return permsMap ? Array.from(permsMap.keys()) : [];
+    /**
+     * Pre-bound UI components
+     */
+    function useCan(role, permission, context) {
+        const [allowed, setAllowed] = React.useState(() => engine.can(role, permission, context));
+        React.useEffect(() => {
+            setAllowed(engine.can(role, permission, context));
+            return engine.subscribe(() => {
+                setAllowed(engine.can(role, permission, context));
+            });
+        }, [role, permission, context]);
+        return allowed;
     }
-    function allow(role, permission, condition) {
-        assignPermissions(role, permission, condition);
-    }
-    function resolvePermissions(role) {
-        return getRolePermissions(role);
-    }
-    function hasPermission(granted, required, context) {
-        // This is a static check for local lists.
-        // For ABAC, we need the actual definition with conditions.
-        // If 'granted' is just string[], we can't check conditions unless we have the role definition.
-        if (granted.includes("*"))
-            return true;
-        if (granted.includes(required))
-            return true;
-        const [resource] = required.split(":");
-        if (granted.includes(`${resource}:*`))
-            return true;
-        return false;
-    }
-    // New: Role-aware permission check (supports ABAC)
-    function can(role, permission, context) {
-        const permsMap = rolePermissions.get(role);
-        if (!permsMap)
-            return false;
-        // 1. Global wildcard
-        if (permsMap.has("*")) {
-            const condition = permsMap.get("*");
-            if (condition(context))
-                return true;
-        }
-        // 2. Direct match
-        if (permsMap.has(permission)) {
-            const condition = permsMap.get(permission);
-            if (condition(context))
-                return true;
-        }
-        // 3. Resource wildcard
-        const [resource] = permission.split(":");
-        const resourceWildcard = `${resource}:*`;
-        if (permsMap.has(resourceWildcard)) {
-            const condition = permsMap.get(resourceWildcard);
-            if (condition(context))
-                return true;
-        }
-        return false;
-    }
-    function normalizePermissions(raw) {
-        const valid = new Set(permissionKeys);
-        return raw.filter((p) => valid.has(p));
+    function Can({ role, permission, context, children, }) {
+        const allowed = useCan(role, permission, context);
+        return allowed ? _jsx(_Fragment, { children: children }) : null;
     }
     return {
-        roles: config.roles,
-        actions: config.actions,
-        resources: config.resources,
-        permissions,
-        permissionKeys,
-        allow,
-        can, // Role-based check (ABAC supported)
-        hasPermission, // Static list check (Legacy/Simple)
-        resolvePermissions,
-        normalizePermissions,
-        assignPermissions,
-        getRolePermissions,
+        ...engine,
+        useCan,
+        Can,
+        usePermissions,
+        refresh: engine.refresh,
+        // Keep legacy check just in case
+        canDo,
     };
 }

package/dist/src/core/engine.d.ts

@@ -0,0 +1,30 @@
+import { ConditionFn, Resource } from "../types";
+export type PermissionKey<Res extends readonly Resource[], A extends readonly string[]> = `${Res[number]["key"]}:${A[number]}` | `${Res[number]["key"]}:*` | "*";
+export declare function createEngine<const R extends readonly string[], const A extends readonly string[], const Res extends readonly Resource[]>(config: {
+    roles: R;
+    actions: A;
+    resources: Res;
+}): {
+    roles: R;
+    actions: A;
+    resources: Res;
+    permissions: {
+        key: PermissionKey<Res, A>;
+        resource: Resource;
+        action: string;
+    }[];
+    permissionKeys: PermissionKey<Res, A>[];
+    allow: (role: R[number], permission: PermissionKey<Res, A> | PermissionKey<Res, A>[], condition?: ConditionFn) => void;
+    can: (role: R[number] | R[number][], permission: PermissionKey<Res, A>, context?: any) => boolean;
+    resolvePermissions: (role: R[number]) => PermissionKey<Res, A>[];
+    normalizePermissions: (raw: string[]) => PermissionKey<Res, A>[];
+    getRolePermissions: (role: R[number]) => PermissionKey<Res, A>[];
+    assignPermissions: (role: R[number], perms: PermissionKey<Res, A> | PermissionKey<Res, A>[] | (() => Promise<PermissionKey<Res, A> | PermissionKey<Res, A>[]>), options?: ConditionFn | {
+        condition?: ConditionFn;
+        invalidateKey?: string | (() => Promise<string>);
+        interval?: number;
+    }) => Promise<void>;
+    refresh: (role?: R[number]) => Promise<void>;
+    subscribe: (cb: () => void) => () => void;
+};
+export type Engine = ReturnType<typeof createEngine>;

package/dist/src/core/engine.js

@@ -0,0 +1,176 @@
+export function createEngine(config) {
+    const roleAssignments = new Map();
+    const listeners = new Set();
+    function subscribe(cb) {
+        listeners.add(cb);
+        return () => {
+            listeners.delete(cb);
+        };
+    }
+    function notify() {
+        listeners.forEach((cb) => cb());
+    }
+    const permissions = config.resources.flatMap((resource) => config.actions.map((action) => ({
+        key: `${resource.key}:${action}`,
+        resource,
+        action,
+    })));
+    const permissionKeys = permissions.map((p) => p.key);
+    async function assignPermissions(role, perms, options) {
+        const condition = typeof options === "function" ? options : options?.condition;
+        const invalidateKey = typeof options === "object" ? options?.invalidateKey : undefined;
+        const interval = typeof options === "object" ? options?.interval : undefined;
+        const assignment = {
+            permissions: new Map(),
+            permsFetcher: typeof perms === "function" ? perms : undefined,
+            invalidateKeyFetcher: invalidateKey,
+            interval: interval,
+            condition: condition,
+        };
+        const updateFn = async (newKey) => {
+            let list = [];
+            if (typeof perms === "function") {
+                const _permissions = await perms();
+                list = Array.isArray(_permissions)
+                    ? _permissions
+                    : [_permissions];
+            }
+            else {
+                list = Array.isArray(perms) ? perms : [perms];
+            }
+            assignment.permissions.clear();
+            list.forEach((p) => assignment.permissions.set(p, assignment.condition || (() => true)));
+            if (newKey !== undefined) {
+                assignment.lastInvalidateKey = newKey;
+            }
+            else if (assignment.invalidateKeyFetcher) {
+                assignment.lastInvalidateKey =
+                    typeof assignment.invalidateKeyFetcher === "function"
+                        ? await assignment.invalidateKeyFetcher()
+                        : assignment.invalidateKeyFetcher;
+            }
+            notify();
+        };
+        await updateFn();
+        if (!roleAssignments.has(role))
+            roleAssignments.set(role, []);
+        roleAssignments.get(role).push(assignment);
+        if (interval && interval > 0) {
+            assignment.timer = setInterval(async () => {
+                const currentKey = assignment.invalidateKeyFetcher
+                    ? typeof assignment.invalidateKeyFetcher === "function"
+                        ? await assignment.invalidateKeyFetcher()
+                        : assignment.invalidateKeyFetcher
+                    : undefined;
+                if (!assignment.invalidateKeyFetcher ||
+                    currentKey !== assignment.lastInvalidateKey) {
+                    await updateFn(currentKey);
+                }
+            }, interval);
+        }
+    }
+    async function refresh(role) {
+        const roles = role ? [role] : Array.from(roleAssignments.keys());
+        for (const r of roles) {
+            const assignments = roleAssignments.get(r) || [];
+            for (const a of assignments) {
+                if (!a.permsFetcher)
+                    continue;
+                const localUpdate = async (newKey) => {
+                    const _permissions = await a.permsFetcher();
+                    const list = Array.isArray(_permissions)
+                        ? _permissions
+                        : [_permissions];
+                    a.permissions.clear();
+                    list.forEach((p) => a.permissions.set(p, a.condition || (() => true)));
+                    if (newKey !== undefined) {
+                        a.lastInvalidateKey = newKey;
+                    }
+                    else if (a.invalidateKeyFetcher) {
+                        a.lastInvalidateKey =
+                            typeof a.invalidateKeyFetcher === "function"
+                                ? await a.invalidateKeyFetcher()
+                                : a.invalidateKeyFetcher;
+                    }
+                    notify();
+                };
+                if (a.invalidateKeyFetcher) {
+                    const currentKey = typeof a.invalidateKeyFetcher === "function"
+                        ? await a.invalidateKeyFetcher()
+                        : a.invalidateKeyFetcher;
+                    if (currentKey !== a.lastInvalidateKey) {
+                        await localUpdate(currentKey);
+                    }
+                }
+                else {
+                    await localUpdate();
+                }
+            }
+        }
+    }
+    function getRolePermissions(role) {
+        const assignments = roleAssignments.get(role) || [];
+        const allPerms = new Set();
+        assignments.forEach((a) => {
+            Array.from(a.permissions.keys()).forEach((p) => allPerms.add(p));
+        });
+        return Array.from(allPerms);
+    }
+    function allow(role, permission, condition) {
+        assignPermissions(role, permission, condition);
+    }
+    function resolvePermissions(role) {
+        return getRolePermissions(role);
+    }
+    function can(role, permission, context) {
+        const roles = Array.isArray(role) ? role : [role];
+        return roles.some((r) => {
+            const assignments = roleAssignments.get(r);
+            if (!assignments)
+                return false;
+            return assignments.some((assignment) => {
+                const permsMap = assignment.permissions;
+                // 1. Global wildcard
+                if (permsMap.has("*")) {
+                    const condition = permsMap.get("*");
+                    if (condition(context))
+                        return true;
+                }
+                // 2. Direct match
+                if (permsMap.has(permission)) {
+                    const condition = permsMap.get(permission);
+                    if (condition(context))
+                        return true;
+                }
+                // 3. Resource wildcard
+                const [resource] = permission.split(":");
+                const resourceWildcard = `${resource}:*`;
+                if (permsMap.has(resourceWildcard)) {
+                    const condition = permsMap.get(resourceWildcard);
+                    if (condition(context))
+                        return true;
+                }
+                return false;
+            });
+        });
+    }
+    function normalizePermissions(raw) {
+        const valid = new Set(permissionKeys);
+        return raw.filter((p) => valid.has(p));
+    }
+    return {
+        roles: config.roles,
+        actions: config.actions,
+        resources: config.resources,
+        permissions,
+        permissionKeys,
+        allow,
+        can,
+        resolvePermissions,
+        normalizePermissions,
+        getRolePermissions,
+        assignPermissions,
+        refresh,
+        subscribe,
+    };
+}

package/dist/src/core/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./access-control";
+export * from "./engine";

package/dist/src/core/index.js

@@ -0,0 +1,2 @@
+export * from "./access-control";
+export * from "./engine";

package/dist/src/core/ui/access-control-ui.d.ts

@@ -1,12 +1,18 @@
 import * as React from "react";
-import { PermissionType } from "../../types";
-export declare function createAccessUI(): {
-    useCan: (granted: PermissionType[], permission: PermissionType, context?: any) => boolean;
+export interface CanProps {
+    permission: string;
+    context?: any;
+    children: React.ReactNode;
+}
+export declare function createAccessUI(engine?: {
+    can: (role: any, permission: any, context?: any) => boolean;
+}): {
+    useCan: (grantedOrPermission: any[] | string, permissionOrContext?: string | any, maybeContext?: any) => any;
     Can: ({ permissions, permission, context, children, }: {
-        permissions: PermissionType[];
-        permission: PermissionType;
+        permissions?: any[];
+        permission: string;
         context?: any;
         children: React.ReactNode;
-    }) => React.ReactNode;
-    canDo: (granted: PermissionType[], permission: PermissionType, context?: any) => boolean;
+    }) => import("react/jsx-runtime").JSX.Element | null;
+    canDo: (granted: any[], permission: string, context?: any) => boolean;
 };

package/dist/src/core/ui/access-control-ui.js

@@ -1,14 +1,30 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
 import * as React from "react";
-export function createAccessUI() {
-    function useCan(granted, permission, context) {
-        return React.useMemo(() => canDo(granted, permission, context), [granted, permission, context]);
+export function createAccessUI(engine) {
+    /**
+     * Hook to check permission.
+     * If engine is provided, it uses the engine (pre-bound).
+     * Otherwise, it requires granted permissions as first argument (legacy).
+     */
+    function useCan(grantedOrPermission, permissionOrContext, maybeContext) {
+        return React.useMemo(() => {
+            if (engine) {
+                // Pre-bound: useCan(permission, context)
+                // We don't have the role here, so we assume the engine instance
+                // is already bound to a role or we need to handle it differently.
+                // Actually, createAccess will wrap this.
+                return engine.can(grantedOrPermission, permissionOrContext);
+            }
+            // Legacy: useCan(granted, permission, context)
+            return canDo(grantedOrPermission, permissionOrContext, maybeContext);
+        }, [grantedOrPermission, permissionOrContext, maybeContext]);
     }
     function Can({ permissions, permission, context, children, }) {
-        return canDo(permissions, permission, context) ? children : null;
+        const allowed = engine
+            ? engine.can(permission, context)
+            : canDo(permissions || [], permission, context); // Fallback for legacy
+        return allowed ? _jsx(_Fragment, { children: children }) : null;
     }
-    // ✅ Function-level permission checker
-    // Note: This is a static list check. If conditions are needed on frontend,
-    // the frontend list should contain the logic or be checked against a role-aware engine.
     function canDo(granted, permission, context) {
         if (granted.includes("*"))
             return true;

package/package.json

@@ -1,30 +1,33 @@
-{
-  "name": "@lbstack/accessx",
-  "version": "0.1.0",
-  "description": "A role & resource based access control system with end to end type safety.",
-  "license": "ISC",
-  "author": "",
-  "type": "module",
-  "main": "./dist/index.js",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "files": [
-    "dist",
-    "README.md"
-  ],
-  "scripts": {
-    "build": "tsc",
-    "test": "jest",
-    "prepublishOnly": "npm run build"
-  },
-  "devDependencies": {
-    "@types/jest": "^29.5.11",
-    "@types/react": "^18.2.48",
-    "jest": "^29.7.0",
-    "ts-jest": "^29.1.1",
-    "typescript": "^5.3.3"
-  },
-  "peerDependencies": {
-    "react": ">=16.8.0"
-  }
-}
+{
+  "name": "@lbstack/accessx",
+  "version": "0.3.0",
+  "description": "A role & resource based access control system with end to end type safety.",
+  "license": "ISC",
+  "author": "@lbstack",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "prepublishOnly": "npm run build",
+    "release:patch": "npm version patch && npm publish",
+    "release:minor": "npm version minor && npm publish",
+    "release:major": "npm version major && npm publish"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.11",
+    "@types/react": "^18.2.48",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.1",
+    "typescript": "^5.3.3"
+  },
+  "peerDependencies": {
+    "react": ">=16.8.0"
+  }
+}

package/readme.md

@@ -133,32 +133,114 @@ const permissions = access.normalizePermissions(permissionsFromDb);
 
 Ensures only valid generated permissions are used.
 
-Login Response
 res.json({
   user,
   permissions: access.resolvePermissions(user.role),
 });
+```
+
+## 🔑 Assigning Permissions
+
+There are two ways to assign permissions to roles: **Manual (Static)** and **Dynamic (Database-linked)**.
+
+### 1. Manual Assignment (Static)
+Best for hardcoded defaults or simple applications. This is the standard, **non-mandatory** approach.
 
-🎨 Frontend Usage (React)
+```typescript
+// Single permission
+access.allow("ADMIN", "USER:DELETE");
 
-Frontend never uses roles.
-It only receives resolved permissions.
+// Multiple permissions
+access.allow("EDITOR", ["BLOGS:CREATE", "BLOGS:READ", "BLOGS:UPDATE"]);
 
-useCan Hook
-const canEdit = access.useCan(
-  auth.permissions,
-  "BLOGS:UPDATE"
+// With custom ABAC conditions
+access.allow("USER", "BLOG:UPDATE", (context) => {
+  return context.post.authorId === context.user.id;
+});
+```
+
+### 2. Dynamic Assignment (Database + Cache)
+Best for production apps where permissions are managed in a DB or Admin Panel. This is **optional** but provides powerful caching and auto-sync benefits.
+
+```typescript
+await access.assignPermissions("ADMIN", 
+  // 1. Fetcher: Returns the list of valid permissions from your DB
+  async () => {
+    const permissions = await db.query("SELECT key FROM permissions WHERE role = 'ADMIN'");
+    return permissions.map(p => p.key);
+  }, 
+  {
+    // OPTIONAL: A fast key-check (e.g., Redis version or DB timestamp)
+    // The engine only re-runs the Fetcher if this key changes.
+    invalidateKey: async () => await redis.get("perms:admin:version"),
+    
+    // OPTIONAL: Auto-check for updates every 60 seconds in the background
+    interval: 60000 
+  }
 );
+```
+
+> [!TIP]
+> **Extra Benefits**: By using `invalidateKey`, you avoid hitting your database for every permission check. The engine keeps permissions in an in-memory cache and only refetches when your "version" key in Redis/DB changes.
+
+## 🔄 Manual Refresh & Sync
+
+If you don't use the `interval` option, or if you need to force a sync after an admin update, use the `refresh` method.
+
+```typescript
+// Forces the engine to check invalidateKeys and re-fetch if they changed
+await access.refresh();
+
+// Refresh only a specific role
+await access.refresh("ADMIN");
+```
+
+## 🎨 Frontend Usage (React)
+
+Frontend components are reactive. When you call `access.refresh()` or when an `interval` triggers an update, all components using the hooks will automatically re-render.
+
+### 1. `useCan` Hook (Engine Bound)
+Automatically re-renders when the engine's permissions for the given role change.
+
+```tsx
+const canEdit = access.useCan("EDITOR", "BLOGS:UPDATE");
+```
+
+### 2. `usePermissions` Hook (Flexible Source)
+Manage permissions from any source (Static, Async, or Role). Provides `loading` state and a manual `refresh` trigger.
+
+```tsx
+const { permissions, loading, refresh } = access.usePermissions(async () => {
+  const res = await api.get("/my-permissions");
+  return res.data;
+});
 
-<button disabled={!canEdit}>Edit</button>
+if (loading) return <Spinner />;
 
-<Can /> Component
-<access.Can
-  permissions={auth.permissions}
-  permission="USER:DELETE"
->
-  <DeleteUserButton />
+return (
+  <div>
+    <button onClick={() => refresh()}>Sync Permissions</button>
+    <Can permissions={permissions} permission="BLOG:CREATE">
+      <CreatePost />
+    </Can>
+  </div>
+);
+```
+
+### 3. `<Can />` Component
+Works with both roles (engine-bound) and explicit permission arrays.
+
+```tsx
+// Role-based (Reactive)
+<access.Can role="ADMIN" permission="USER:DELETE">
+  <DeleteButton />
+</access.Can>
+
+// Permission-based
+<access.Can permissions={userPerms} permission="BLOGS:READ">
+  <PostList />
 </access.Can>
+```
 
 🧠 Type Safety & Autocomplete
 
@@ -184,62 +266,23 @@ access.permissionKeys
 
 Backend
 access.allow(role, permission)
+access.assignPermissions(role, perms, options) // Async: Supports fetchers & invalidation
 access.can(role, permission)
 access.resolvePermissions(role)
 access.normalizePermissions(raw)
+access.refresh(role?) // Async: Trigger key check and conditional refetch
 
 Frontend
 access.useCan(permissions, permission)
 <access.Can />
 
-🆚 Comparison with Keycloak
-
-This package is an application-level authorization engine, not a full IAM system.
-
-Area	@accessx/core	Keycloak
-Identity	❌	✅
-RBAC Core	✅	✅
-Type Safety	✅	❌
-Frontend Hooks	✅	❌
-Performance	✅	❌
-Admin UI	❌	✅
-Multi-App SSO	❌	✅
-Runtime Policy Change	❌	✅
-Enterprise Compliance	❌	✅
-Ops Overhead	Low	High
-Strengths
-
-Excellent developer experience (TypeScript-first)
-
-Frontend hooks and React components
-
-High performance and low latency
-
-Embedded, framework-agnostic, zero ops
-
-Weaknesses Compared to Keycloak
-
-No identity or login management
-
-No multi-application SSO
-
-No admin UI or delegation
-
-Permissions mostly static (redeploy needed for new resources/actions)
-
-No ABAC / advanced policy language
-
-No enterprise audit / compliance tooling
-
-Ideal Usage
-Keycloak (Authentication + Identity)
-        ↓
-JWT / Claims
-        ↓
-@accessx/core (Authorization + UI permissions)
+🔐 Multi-Permission Assignment
+Assign multiple permissions to a role at once:
+```typescript
+access.allow("EDITOR", ["BLOGS:CREATE", "BLOGS:READ", "BLOGS:UPDATE"]);
+```
 
 
-This is complementary, not a replacement for Keycloak.
 
 🏆 Why Use @accessx/core?
 
@@ -288,17 +331,10 @@ npm test
 
 ## 🛣️ Roadmap
 
-Wildcard permissions (BLOGS:*)
-
-Multi-role users
-
-Attribute-based access control (ABAC)
-
-Permission groups
-
-JWT permission compression
-
-CLI generator
+- [ ] Multi-role users
+- [ ] Permission groups
+- [ ] JWT permission compression
+- [ ] CLI generator
 
 📄 License