@lbstack/accessx 0.1.0

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

@@ -0,0 +1,11 @@
+import * as React from "react";
+import { PermissionType } from "./types";
+export declare function createAccessUI(): {
+    useCan: (granted: PermissionType[], permission: PermissionType) => boolean;
+    Can: ({ permissions, permission, children, }: {
+        permissions: PermissionType[];
+        permission: PermissionType;
+        children: React.ReactNode;
+    }) => React.ReactNode;
+    canDo: (granted: PermissionType[], permission: PermissionType) => boolean;
+};

package/dist/access-control-ui.js

@@ -0,0 +1,23 @@
+import * as React from "react";
+export function createAccessUI() {
+    function useCan(granted, permission) {
+        return React.useMemo(() => canDo(granted, permission), [granted, permission]);
+    }
+    function Can({ permissions, permission, children, }) {
+        return canDo(permissions, permission) ? children : null;
+    }
+    // ✅ Function-level permission checker
+    function canDo(granted, permission) {
+        if (granted.includes("*")) {
+            console.warn(`Global '*' permission used: allowing all permissions!`);
+            return true;
+        }
+        if (granted.includes(permission))
+            return true;
+        const [resource] = permission.split(":");
+        if (granted.includes(`${resource}:*`))
+            return true;
+        return false;
+    }
+    return { useCan, Can, canDo };
+}

package/dist/access-control.d.ts

@@ -0,0 +1,23 @@
+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;
+}): {
+    roles: R;
+    actions: A;
+    resources: Res;
+    permissions: {
+        key: "*" | `${Res[number]["key"]}:${A[number]}` | `${Res[number]["key"]}:*`;
+        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"]}:*`)[]) => void;
+    can: (granted: ("*" | `${Res[number]["key"]}:${A[number]}` | `${Res[number]["key"]}:*`)[], required: "*" | `${Res[number]["key"]}:${A[number]}` | `${Res[number]["key"]}:*`) => 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"]}:*`)[]) => void;
+    getRolePermissions: (role: R[number]) => ("*" | `${Res[number]["key"]}:${A[number]}` | `${Res[number]["key"]}:*`)[];
+    hasPermission: (granted: ("*" | `${Res[number]["key"]}:${A[number]}` | `${Res[number]["key"]}:*`)[], required: "*" | `${Res[number]["key"]}:${A[number]}` | `${Res[number]["key"]}:*`) => boolean;
+};

package/dist/access-control.js

@@ -0,0 +1,54 @@
+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);
+    const rolePermissions = new Map();
+    function assignPermissions(role, perms) {
+        const list = Array.isArray(perms) ? perms : [perms];
+        if (!rolePermissions.has(role))
+            rolePermissions.set(role, new Set());
+        list.forEach((p) => rolePermissions.get(role).add(p));
+    }
+    function getRolePermissions(role) {
+        return Array.from(rolePermissions.get(role) ?? []);
+    }
+    function allow(role, permission) {
+        assignPermissions(role, permission);
+    }
+    function resolvePermissions(role) {
+        return getRolePermissions(role);
+    }
+    function hasPermission(granted, required) {
+        if (granted.includes("*")) {
+            console.warn("Global '*' permission used: allowing all permissions!");
+            return true;
+        }
+        if (granted.includes(required))
+            return true;
+        const [resource] = required.split(":");
+        if (granted.includes(`${resource}:*`))
+            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: hasPermission,
+        resolvePermissions,
+        normalizePermissions,
+        assignPermissions,
+        getRolePermissions,
+        hasPermission,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./src/core/access-control";
+export * from "./src/core/ui/access-control-ui";
+export * from "./src/types";

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from "./src/core/access-control";
+export * from "./src/core/ui/access-control-ui";
+export * from "./src/types";

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

@@ -0,0 +1,23 @@
+import { ConditionFn, 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;
+}): {
+    roles: R;
+    actions: A;
+    resources: Res;
+    permissions: {
+        key: "*" | `${Res[number]["key"]}:${A[number]}` | `${Res[number]["key"]}:*`;
+        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"]}:*`)[];
+};

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

@@ -0,0 +1,85 @@
+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)));
+    }
+    function getRolePermissions(role) {
+        const permsMap = rolePermissions.get(role);
+        return permsMap ? Array.from(permsMap.keys()) : [];
+    }
+    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));
+    }
+    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,
+    };
+}

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

@@ -0,0 +1,12 @@
+import * as React from "react";
+import { PermissionType } from "../../types";
+export declare function createAccessUI(): {
+    useCan: (granted: PermissionType[], permission: PermissionType, context?: any) => boolean;
+    Can: ({ permissions, permission, context, children, }: {
+        permissions: PermissionType[];
+        permission: PermissionType;
+        context?: any;
+        children: React.ReactNode;
+    }) => React.ReactNode;
+    canDo: (granted: PermissionType[], permission: PermissionType, context?: any) => boolean;
+};

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

@@ -0,0 +1,23 @@
+import * as React from "react";
+export function createAccessUI() {
+    function useCan(granted, permission, context) {
+        return React.useMemo(() => canDo(granted, permission, context), [granted, permission, context]);
+    }
+    function Can({ permissions, permission, context, children, }) {
+        return canDo(permissions, permission, context) ? 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;
+        if (granted.includes(permission))
+            return true;
+        const [resource] = permission.split(":");
+        if (granted.includes(`${resource}:*`))
+            return true;
+        return false;
+    }
+    return { useCan, Can, canDo };
+}

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

@@ -0,0 +1,10 @@
+export type RoleType = string;
+export type ActionType = string;
+export type ResourceKeyType = string;
+export type PermissionType = `${ResourceKeyType}:${ActionType}` | `${ResourceKeyType}:*` | "*";
+export type ConditionFn<TContext = any> = (context: TContext) => boolean;
+export interface Resource {
+    name: string;
+    key: ResourceKeyType;
+    description?: string;
+}

package/dist/src/types/index.js

@@ -0,0 +1 @@
+export {};

package/dist/types.d.ts

@@ -0,0 +1,9 @@
+export type RoleType = string;
+export type ActionType = string;
+export type ResourceKeyType = string;
+export type PermissionType = `${ResourceKeyType}:${ActionType}` | `${ResourceKeyType}:*` | "*";
+export interface Resource {
+    name: string;
+    key: ResourceKeyType;
+    description?: string;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,30 @@
+{
+  "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"
+  }
+}

package/readme.md

@@ -0,0 +1,315 @@
+# @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
+-   Admin permission management
+
+No manual permission strings.  
+No role leakage to frontend.  
+Full autocomplete everywhere.
+
+---
+
+## ✨ Key Features
+
+-   🔐 **Automatic permission generation**
+-   🧠 **Strong TypeScript inference & autocomplete**
+-   🏗️ **Single initialization – use everywhere**
+-   🖥️ Backend (Express / Nest / Hono)
+-   🎨 Frontend (React hooks & components)
+-   🗄️ Database-friendly permission keys
+-   📦 Package & framework agnostic
+
+---
+
+## 🧩 Core Concept
+
+You define:
+
+-   **Roles**
+-   **Actions**
+-   **Resources (modules)**
+
+The package automatically generates permissions in this format:
+
+RESOURCE_KEY:ACTION
+
+Example:
+
+BLOGS:CREATE
+BLOGS:READ
+USER:DELETE
+
+These permission keys are:
+
+-   Stored in DB
+-   Sent to frontend after login
+-   Used in UI & API checks
+-   Fully type-safe
+
+---
+
+## 📦 Installation
+
+```bash
+npm install @lbstack/accessx
+
+
+or
+
+pnpm add @lbstack/accessx
+
+🚀 Initialization (Single Source of Truth)
+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,
+});
+
+
+⚠️ as const is required for TypeScript autocomplete.
+
+🔑 Automatically Generated Permissions
+access.permissionKeys
+
+[
+  "USER:CREATE",
+  "USER:READ",
+  "USER:UPDATE",
+  "USER:DELETE",
+  "BLOGS:CREATE",
+  "BLOGS:READ",
+  "BLOGS:UPDATE",
+  "BLOGS:DELETE",
+]
+
+
+No permission strings are written manually.
+
+🗄️ Database Usage
+Seed permissions table
+await db.permissions.insertMany(access.permissions);
+
+
+Each permission contains metadata:
+
+{
+  key: "BLOGS:CREATE",
+  resource: { name, key, description },
+  action: "CREATE"
+}
+
+🔐 Backend Usage
+Assign permissions to roles
+access.allow("ADMIN", "USER:DELETE");
+access.allow("EDITOR", "BLOGS:CREATE");
+
+Check permission (Service / Controller)
+access.can(user.role, "BLOGS:UPDATE");
+
+Normalize permissions from DB
+const permissionsFromDb = ["BLOGS:READ", "USER:DELETE"];
+
+const permissions = access.normalizePermissions(permissionsFromDb);
+
+
+Ensures only valid generated permissions are used.
+
+Login Response
+res.json({
+  user,
+  permissions: access.resolvePermissions(user.role),
+});
+
+🎨 Frontend Usage (React)
+
+Frontend never uses roles.
+It only receives resolved permissions.
+
+useCan Hook
+const canEdit = access.useCan(
+  auth.permissions,
+  "BLOGS:UPDATE"
+);
+
+<button disabled={!canEdit}>Edit</button>
+
+<Can /> Component
+<access.Can
+  permissions={auth.permissions}
+  permission="USER:DELETE"
+>
+  <DeleteUserButton />
+</access.Can>
+
+🧠 Type Safety & Autocomplete
+
+Invalid permission → ❌ TypeScript error
+
+Invalid resource/action → ❌ TypeScript error
+
+IDE auto-suggests valid permissions everywhere
+
+// ❌ Invalid
+"BLOGS:PUBLISH"
+
+// ✅ Valid
+"BLOGS:CREATE"
+
+🏗️ API Reference
+Metadata
+access.roles
+access.actions
+access.resources
+access.permissions
+access.permissionKeys
+
+Backend
+access.allow(role, permission)
+access.can(role, permission)
+access.resolvePermissions(role)
+access.normalizePermissions(raw)
+
+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)
+
+
+This is complementary, not a replacement for Keycloak.
+
+🏆 Why Use @accessx/core?
+
+Zero manual permission creation
+
+DB, backend & frontend always in sync
+
+Enterprise-grade RBAC foundation for apps
+
+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).
+
+### 1. Define with Conditions
+```typescript
+access.allow("USER", "BLOG:UPDATE", (context: { user: any; post: any }) => {
+  return context.post.authorId === context.user.id;
+});
+```
+
+### 2. Check with Context
+The `can` method accepts an optional context object as the third argument.
+
+```typescript
+const canEdit = access.can("USER", "BLOG:UPDATE", { user, post });
+```
+
+### 3. Frontend Usage
+React components also support `context`.
+
+```tsx
+<Can permissions={myPermissions} permission="BLOG:UPDATE" context={{ user, post }}>
+  <button>Edit Post</button>
+</Can>
+```
+
+## 🧪 Testing
+
+The package includes a comprehensive test suite using Jest.
+
+```bash
+npm test
+```
+
+## 🛣️ Roadmap
+
+Wildcard permissions (BLOGS:*)
+
+Multi-role users
+
+Attribute-based access control (ABAC)
+
+Permission groups
+
+JWT permission compression
+
+CLI generator
+
+📄 License
+
+MIT
+
+💡 Inspiration
+
+Zanzibar (Google)
+
+Auth0 / Keycloak permission models
+
+CASL & OPA (simplified DX)
+
+One definition. One truth. Everywhere. 🔐✨