Package Exports

exguard-client

Readme

exguard-client

ExGuard RBAC (Role-Based Access Control) client library with realtime WebSocket support for EmpowerX applications.

Features

🔐 RBAC Authentication: Token verification and user access management
🔄 Realtime Updates: WebSocket-based real-time RBAC changes
🎯 Permission Guards: React components for route and feature protection
🪝 React Hooks: Easy-to-use hooks for permission checking
📦 TypeScript: Full type safety with TypeScript definitions
⚡ Lightweight: Minimal bundle size with tree-shaking support

Installation

pnpm add exguard-client

Peer Dependencies

Make sure you have the required peer dependencies installed:

pnpm add react react-dom react-router axios socket.io-client

Scaffold ExGuard Module (Recommended)

After installation, run the setup script to create the exguard module structure in your project:

npx exguard-setup
# or
pnpm exguard-setup

This will create:

src/features/exguard/
├── index.ts              # Re-exports from package (use this for imports)
├── README.md            # Module documentation
└── config/
    └── exguard.config.ts # Optional configuration

Now you can import from your local module:

import { PermissionGuard, useUserAccess } from '@/features/exguard';

Or import directly from the package:

import { PermissionGuard, useUserAccess } from 'exguard-client';

Quick Start

1. Install the Package

pnpm add exguard-client

2. Generate ExGuard Module (Recommended)

Run the setup command to create the exguard module structure:

pnpm exguard-setup
# or for npm users
npx exguard-setup

This creates:

src/features/exguard/
├── index.ts              # Re-exports from package
├── README.md            # Module documentation
└── config/
    └── exguard.config.ts # Optional configuration

3. Configure ExGuard

In your main.tsx or app entry point:

import { ExGuardRealtimeProvider, setExGuardConfig } from '@/features/exguard';

// Configure the ExGuard API URL
setExGuardConfig({
  apiUrl: import.meta.env.VITE_GUARD_APP_URL,
});

// Wrap your app
<ExGuardRealtimeProvider>
  <App />
</ExGuardRealtimeProvider>

4. Use ExGuard Components

import { PermissionGuard, useUserAccess } from '@/features/exguard';

// Route protection
<PermissionGuard module="EXID">
  <ProfilesPage />
</PermissionGuard>

// Permission checking
function MyComponent() {
  const { hasModuleAccess, hasPermission } = useUserAccess();
  
  return (
    <div>
      {hasModuleAccess('EXID') && <div>EXID Module</div>}
      {hasPermission('EXID', 'profile:create') && <button>Create</button>}
    </div>
  );
}

API Reference

Configuration

`setExGuardConfig(config)`

Configure the ExGuard API URL and other settings.

import { setExGuardConfig } from 'exguard-client';

setExGuardConfig({
  apiUrl: 'https://your-exguard-api.com',
  withCredentials: true, // default: true
});

Components

`ExGuardRealtimeProvider`

Provider component that manages WebSocket connections and RBAC state.

<ExGuardRealtimeProvider>
  {/* Your app */}
</ExGuardRealtimeProvider>

`PermissionGuard`

Route guard component for RBAC permission checking.

<PermissionGuard
  module="EXID"                    // Required: Module key
  permission="profile:create"      // Optional: Specific permission
  requireModule={true}             // Optional: Require module access (default: true)
  requirePermission={true}         // Optional: Require permission (default: true if permission provided)
  fallbackPath="/unauthorized"     // Optional: Redirect path on access denied
>
  <YourProtectedComponent />
</PermissionGuard>

Hooks

`useUserAccess(options?)`

Hook to fetch and manage user access data with RBAC.

const {
  userAccess,        // Full user access data
  isLoading,         // Loading state
  error,             // Error state
  hasModuleAccess,   // Function to check module access
  hasPermission,     // Function to check specific permission
} = useUserAccess({
  enabled: true,           // Optional: Enable/disable fetching (default: true)
  refetchInterval: 30000,  // Optional: Refetch interval in ms (default: 0)
});

Methods:

hasModuleAccess(moduleKey: string): boolean - Check if user has access to a module
hasPermission(moduleKey: string, permission: string): boolean - Check if user has a specific permission

`useExGuardRealtime()`

Hook to access the ExGuard realtime context.

const {
  isConnected,                   // WebSocket connection state
  registerRbacRefreshCallback,   // Register callback for RBAC updates
} = useExGuardRealtime();

`useExGuardRealtimeSubscription(eventType, handler)`

Hook to subscribe to specific realtime events.

import { useExGuardRealtimeSubscription, EXGUARD_RBAC_EVENTS } from 'exguard-client';

useExGuardRealtimeSubscription(
  EXGUARD_RBAC_EVENTS.RBAC_PERMISSIONS_UPDATED,
  (payload) => {
    console.log('Permissions updated:', payload);
    // Handle the event
  }
);

API Functions

`verifyToken()`

Verify the current ID token with the ExGuard backend.

import { verifyToken } from 'exguard-client';

const result = await verifyToken();
if (result.isValid && result.user) {
  console.log('User:', result.user);
}

`getUserAccess()`

Fetch the current user's access data (roles, permissions, modules).

import { getUserAccess } from 'exguard-client';

const userAccess = await getUserAccess();
console.log('Modules:', userAccess.modules);
console.log('Roles:', userAccess.roles);

Constants

`EXGUARD_RBAC_EVENTS`

Constants for ExGuard RBAC event types.

import { EXGUARD_RBAC_EVENTS } from 'exguard-client';

// Available events:
EXGUARD_RBAC_EVENTS.ROLE_CREATED
EXGUARD_RBAC_EVENTS.ROLE_UPDATED
EXGUARD_RBAC_EVENTS.ROLE_DELETED
EXGUARD_RBAC_EVENTS.PERMISSION_CREATED
EXGUARD_RBAC_EVENTS.PERMISSION_UPDATED
EXGUARD_RBAC_EVENTS.PERMISSION_DELETED
EXGUARD_RBAC_EVENTS.USER_ROLES_UPDATED
EXGUARD_RBAC_EVENTS.USER_PERMISSIONS_CHANGED
EXGUARD_RBAC_EVENTS.USER_ACCESS_CHANGED
EXGUARD_RBAC_EVENTS.RBAC_PERMISSIONS_UPDATED
// ... and more

`EXGUARD_STORAGE_KEYS`

Constants for localStorage keys used by ExGuard.

import { EXGUARD_STORAGE_KEYS } from 'exguard-client';

// Available keys:
EXGUARD_STORAGE_KEYS.ACCESS_TOKEN
EXGUARD_STORAGE_KEYS.ID_TOKEN
EXGUARD_STORAGE_KEYS.REFRESH_TOKEN

Types

The package exports all necessary TypeScript types:

import type {
  UserAccessData,
  ModulePermissions,
  UserDetails,
  VerifyTokenResponse,
  RealtimeEventType,
  RealtimeEventPayload,
  ExGuardConfig,
} from 'exguard-client';

Environment Variables

The package automatically detects environment variables in consuming applications:

Vite

VITE_GUARD_APP_URL=https://your-exguard-api.com

Next.js

NEXT_PUBLIC_GUARD_APP_URL=https://your-exguard-api.com

Or set it programmatically using setExGuardConfig().

Storage

ExGuard uses localStorage for token management:

access_token - Access token for API authentication
id_token - ID token for user verification
refresh_token - Refresh token for token renewal

License

MIT

Support

For issues or questions, please contact the EmpowerX development team.