@lbstack/accessx 0.3.0 → 0.4.0

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

@@ -29,7 +29,7 @@ export declare function createAccess<const R extends readonly string[], const A
     }[];
     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;
+    can: (role: R[number] | R[number][], permission: import("./engine").PermissionKey<Res, A>, contextOrValidator?: any | (() => boolean)) => 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>[];

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

@@ -15,7 +15,7 @@ export declare function createEngine<const R extends readonly string[], const A
     }[];
     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;
+    can: (role: R[number] | R[number][], permission: PermissionKey<Res, A>, contextOrValidator?: any | (() => boolean)) => boolean;
     resolvePermissions: (role: R[number]) => PermissionKey<Res, A>[];
     normalizePermissions: (raw: string[]) => PermissionKey<Res, A>[];
     getRolePermissions: (role: R[number]) => PermissionKey<Res, A>[];

package/dist/src/core/engine.js

@@ -27,6 +27,11 @@ export function createEngine(config) {
             interval: interval,
             condition: condition,
         };
+        const updatePermissions = (list) => {
+            assignment.permissions.clear();
+            list.forEach((p) => assignment.permissions.set(p, assignment.condition || (() => true)));
+            notify();
+        };
         const updateFn = async (newKey) => {
             let list = [];
             if (typeof perms === "function") {
@@ -38,8 +43,7 @@ export function createEngine(config) {
             else {
                 list = Array.isArray(perms) ? perms : [perms];
             }
-            assignment.permissions.clear();
-            list.forEach((p) => assignment.permissions.set(p, assignment.condition || (() => true)));
+            updatePermissions(list);
             if (newKey !== undefined) {
                 assignment.lastInvalidateKey = newKey;
             }
@@ -49,12 +53,26 @@ export function createEngine(config) {
                         ? await assignment.invalidateKeyFetcher()
                         : assignment.invalidateKeyFetcher;
             }
-            notify();
         };
-        await updateFn();
+        // Immediate application for synchronous perms
+        if (typeof perms !== "function") {
+            const list = Array.isArray(perms) ? perms : [perms];
+            updatePermissions(list);
+            // Handle literal key synchronously
+            if (invalidateKey && typeof invalidateKey !== "function") {
+                assignment.lastInvalidateKey = invalidateKey;
+            }
+        }
         if (!roleAssignments.has(role))
             roleAssignments.set(role, []);
         roleAssignments.get(role).push(assignment);
+        // Still call updateFn to handle potential async invalidateKeyFetcher
+        // and initial perms fetch if it's a function.
+        const initialUpdate = updateFn();
+        if (typeof perms === "function" ||
+            typeof invalidateKey === "function") {
+            await initialUpdate;
+        }
         if (interval && interval > 0) {
             assignment.timer = setInterval(async () => {
                 const currentKey = assignment.invalidateKeyFetcher
@@ -122,34 +140,50 @@ export function createEngine(config) {
     function resolvePermissions(role) {
         return getRolePermissions(role);
     }
-    function can(role, permission, context) {
+    /**
+     * Check if a role has the specified permission.
+     * @param role The role or roles to check.
+     * @param permission The permission to check.
+     * @param contextOrValidator
+     *  - (Recommended) A callback function `() => boolean` that returns true if allowed.
+     *  - (Deprecated) A context object to be passed to the stored condition.
+     */
+    function can(role, permission, contextOrValidator) {
         const roles = Array.isArray(role) ? role : [role];
+        // If a validator function is provided, it MUST return true.
+        if (typeof contextOrValidator === "function") {
+            if (!contextOrValidator()) {
+                return false;
+            }
+        }
         return roles.some((r) => {
             const assignments = roleAssignments.get(r);
             if (!assignments)
                 return false;
             return assignments.some((assignment) => {
                 const permsMap = assignment.permissions;
+                // Helper to check a specific permission key in the map
+                const check = (key) => {
+                    if (permsMap.has(key)) {
+                        const storedCondition = permsMap.get(key);
+                        // pass the context (or function) to stored condition
+                        // If stored condition checks context, and we passed a function, it might fail/throw.
+                        // Ideally legacy stored conditions are used with legacy context objects.
+                        return storedCondition(contextOrValidator);
+                    }
+                    return false;
+                };
                 // 1. Global wildcard
-                if (permsMap.has("*")) {
-                    const condition = permsMap.get("*");
-                    if (condition(context))
-                        return true;
-                }
+                if (check("*"))
+                    return true;
                 // 2. Direct match
-                if (permsMap.has(permission)) {
-                    const condition = permsMap.get(permission);
-                    if (condition(context))
-                        return true;
-                }
+                if (check(permission))
+                    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;
-                }
+                if (check(resourceWildcard))
+                    return true;
                 return false;
             });
         });

package/llm.txt

@@ -0,0 +1,94 @@
+# @lbstack/accessx
+
+A **TypeScript-first RBAC permission engine** with **automatic permission generation**, designed to be the **single source of truth** for Backend authorization, Frontend UI access control, Database permission storage, and Admin permission management.
+
+## ✨ Key Features
+- 🔐 Automatic permission generation
+- 🧠 Strong TypeScript inference & autocomplete
+- 🏗️ Single initialization – use everywhere (Backend & Frontend)
+- 🗄️ Database-friendly permission keys
+- 📦 Package & framework agnostic
+
+## 🧩 Core Concept
+Define Roles, Actions, and Resources. The engine generates permissions as `RESOURCE_KEY:ACTION`.
+Example: `BLOGS:CREATE`, `USER:DELETE`.
+
+## 📦 Installation
+```bash
+npm install @lbstack/accessx
+# or
+pnpm add @lbstack/accessx
+```
+
+## 🚀 Initialization
+```typescript
+import { createAccess } from "@lbstack/accessx";
+
+export const access = createAccess({
+  roles: ["ADMIN", "EDITOR", "CUSTOMER"] as const,
+  actions: ["CREATE", "READ", "UPDATE", "DELETE"] as const,
+  resources: [
+    { name: "Users", key: "USER", description: "User management" },
+    { name: "Blogs", key: "BLOGS", description: "Blog posts" },
+  ] as const,
+});
+```
+
+## 🔑 Assigning Permissions
+
+### 1. Manual Assignment (Static)
+```typescript
+access.allow("ADMIN", "USER:DELETE");
+access.allow("EDITOR", ["BLOGS:CREATE", "BLOGS:READ"]);
+```
+
+### 2. Dynamic Assignment (Database + Cache)
+```typescript
+await access.assignPermissions("ADMIN", 
+  async () => {
+    const permissions = await db.query("SELECT key FROM permissions WHERE role = 'ADMIN'");
+    return permissions.map(p => p.key);
+  }, 
+  {
+    invalidateKey: async () => await redis.get("perms:admin:version"),
+    interval: 60000 
+  }
+);
+```
+
+## 🔄 Manual Refresh & Sync
+```typescript
+await access.refresh(); // Refresh all
+await access.refresh("ADMIN"); // Refresh specific role
+```
+
+## 🎨 Frontend Usage (React)
+
+### useCan Hook
+```tsx
+const canEdit = access.useCan("EDITOR", "BLOGS:UPDATE");
+```
+
+### usePermissions Hook
+```tsx
+const { permissions, loading, refresh } = access.usePermissions(async () => {
+  const res = await api.get("/my-permissions");
+  return res.data;
+});
+```
+
+### <Can /> Component
+```tsx
+<access.Can role="ADMIN" permission="USER:DELETE">
+  <DeleteButton />
+</access.Can>
+```
+
+## 🧠 ABAC (Attribute-Based Access Control)
+```typescript
+access.allow("USER", "BLOG:UPDATE", (context) => {
+  return context.post.authorId === context.user.id;
+});
+
+const canEdit = access.can("USER", "BLOG:UPDATE", { user, post });
+```

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@lbstack/accessx",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "A role & resource based access control system with end to end type safety.",
-  "license": "ISC",
+  "license": "MIT",
   "author": "@lbstack",
   "type": "module",
   "main": "./dist/index.js",
@@ -10,7 +10,8 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "llm.txt"
   ],
   "scripts": {
     "build": "tsc",
@@ -29,5 +30,15 @@
   },
   "peerDependencies": {
     "react": ">=16.8.0"
-  }
+  },
+  "keywords": [
+    "rbac",
+    "access-control",
+    "authorization",
+    "permissions",
+    "role-based",
+    "resource-based",
+    "typescript",
+    "react"
+  ]
 }

package/readme.md

@@ -1,5 +1,7 @@
 # @lbstack/accessx
 
+[📄 llm.txt (AI Friendly)](./llm.txt)
+
 A **TypeScript-first RBAC permission engine** with **automatic permission generation**, designed to be the **single source of truth** for:
 
 -   Backend authorization
@@ -296,24 +298,45 @@ Scales to ABAC, multi-role, multi-tenant systems
 
 ## 🧠 ABAC (Attribute-Based Access Control)
 
-You can define dynamic permissions based on context (e.g., user ID, ownership checking).
+You can define dynamic permissions based on context.
+
+### 1. Runtime Validation (Recommended) ✨
+
+Pass a validator function directly to `access.can`. This function is executed at runtime.
 
-### 1. Define with Conditions
 ```typescript
-access.allow("USER", "BLOG:UPDATE", (context: { user: any; post: any }) => {
+const isAllowed = access.can("USER", "BLOG:UPDATE", () => {
+    // Your logic here
+    return post.authorId === user.id;
+});
+```
+
+This approach allows you to keep your permissions stored as pure data (strings) in your database while keeping the complex validation logic in your application code.
+
+### 2. Stored Conditions (Deprecated ⚠️)
+
+> [!WARNING]
+> Defining conditions during assignment is deprecated and may be removed in future versions. Please use Runtime Validation instead.
+
+Defining conditions during assignment:
+
+```typescript
+// DEPRECATED
+access.allow("USER", "BLOG:UPDATE", (context) => {
   return context.post.authorId === context.user.id;
 });
 ```
 
-### 2. Check with Context
-The `can` method accepts an optional context object as the third argument.
+Checking with context object:
 
 ```typescript
+// DEPRECATED
 const canEdit = access.can("USER", "BLOG:UPDATE", { user, post });
 ```
 
 ### 3. Frontend Usage
-React components also support `context`.
+
+React components support the new pattern via the `validator` prop (requires update to React components, currently supports context object):
 
 ```tsx
 <Can permissions={myPermissions} permission="BLOG:UPDATE" context={{ user, post }}>