@lbstack/accessx

📄 llm.txt (AI Friendly)

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

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.

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.

// Single permission
access.allow("ADMIN", "USER:DELETE");

// Multiple permissions
access.allow("EDITOR", ["BLOGS:CREATE", "BLOGS:READ", "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.

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.

// 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.

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.

const { permissions, loading, refresh } = access.usePermissions(async () => {
  const res = await api.get("/my-permissions");
  return res.data;
});

if (loading) return <Spinner />;

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.

// 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

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.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 />

🔐 Multi-Permission Assignment Assign multiple permissions to a role at once:

access.allow("EDITOR", ["BLOGS:CREATE", "BLOGS:READ", "BLOGS:UPDATE"]);

🏆 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.

1. Runtime Validation (Recommended) ✨

Pass a validator function directly to access.can. This function is executed at runtime.

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:

// DEPRECATED
access.allow("USER", "BLOG:UPDATE", (context) => {
  return context.post.authorId === context.user.id;
});

Checking with context object:

// DEPRECATED
const canEdit = access.can("USER", "BLOG:UPDATE", { user, post });

3. Frontend Usage

React components support the new pattern via the validator prop (requires update to React components, currently supports context object):

<Can permissions={myPermissions} permission="BLOG:UPDATE" context={{ user, post }}>
  <button>Edit Post</button>
</Can>

🧪 Testing

The package includes a comprehensive test suite using Jest.

npm test

🛣️ Roadmap

• Multi-role users
• 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. 🔐✨