rbac-manager 0.0.0-stage → 1.0.0

package/src/core/context/PermissionContext.tsx

@@ -0,0 +1,232 @@
+import React, { createContext, useContext, useEffect, useState, useCallback, useMemo } from 'react';
+import { useRBACConfig } from './RBACConfigContext';
+import { StandardUser, StandardNavigationItem, LoginCredentials } from '../types';
+
+export interface PermissionContextValue {
+  user: StandardUser | null;
+  permissions: Set<string>;
+  navigation: StandardNavigationItem[];
+  isLoading: boolean;
+  isAuthenticated: boolean;
+  error: Error | null;
+  activeTenantId: string | number | null;
+  setTenantId: (id: string | number | null) => void;
+  hasPermission: (permissionKey: string) => boolean;
+  canNavigate: (routePath: string) => boolean;
+  login: (credentials: LoginCredentials) => Promise<any>;
+  logout: () => Promise<void>;
+  refresh: () => Promise<void>;
+}
+
+export interface PermissionProviderProps {
+  children: React.ReactNode;
+  autoFetch?: boolean;
+  // SSR Hydration Props to eliminate FOUC (Flash of Unauthorized Content)
+  initialUser?: StandardUser | null;
+  initialPermissions?: string[] | Set<string>;
+  initialNavigation?: StandardNavigationItem[];
+  initialTenantId?: string | number | null;
+}
+
+const PermissionContext = createContext<PermissionContextValue | null>(null);
+
+export const PermissionProvider: React.FC<PermissionProviderProps> = ({
+  children,
+  autoFetch = true,
+  initialUser = null,
+  initialPermissions,
+  initialNavigation = [],
+  initialTenantId = null,
+}) => {
+  const { config, http } = useRBACConfig();
+
+  const [user, setUser] = useState<StandardUser | null>(initialUser);
+  const [permissions, setPermissions] = useState<Set<string>>(() => {
+    if (!initialPermissions) return new Set();
+    return initialPermissions instanceof Set ? initialPermissions : new Set(initialPermissions);
+  });
+  const [routePaths, setRoutePaths] = useState<Set<string>>(new Set());
+  const [navigation, setNavigation] = useState<StandardNavigationItem[]>(initialNavigation);
+  const [activeTenantId, setActiveTenantId] = useState<string | number | null>(initialTenantId);
+
+  // If initial user or permissions are provided by SSR, start with isLoading = false!
+  const [isLoading, setIsLoading] = useState<boolean>(() => !initialUser && !initialPermissions && autoFetch);
+  const [error, setError] = useState<Error | null>(null);
+
+  const fetchAuthMe = useCallback(async () => {
+    setIsLoading(true);
+    setError(null);
+    try {
+      const raw = await http.get(config.endpoints.AUTH_ME);
+      const transformed = config.adapters.auth.transformAuthMeResponse(raw);
+
+      setUser(transformed.user);
+
+      const permKeys = new Set<string>();
+      const routes = new Set<string>();
+
+      transformed.permissions.forEach((p) => {
+        if (p.permissionKey) permKeys.add(p.permissionKey);
+        if (p.routePath) routes.add(p.routePath);
+      });
+
+      setPermissions(permKeys);
+      setRoutePaths(routes);
+      setNavigation(transformed.navigation);
+    } catch (err: any) {
+      setUser(null);
+      setPermissions(new Set());
+      setRoutePaths(new Set());
+      setNavigation([]);
+      setError(err instanceof Error ? err : new Error(String(err)));
+    } finally {
+      setIsLoading(false);
+    }
+  }, [config.adapters.auth, config.endpoints.AUTH_ME, http]);
+
+  useEffect(() => {
+    if (autoFetch && !initialUser) {
+      fetchAuthMe();
+    }
+  }, [autoFetch, fetchAuthMe, initialUser]);
+
+  const setTenantId = useCallback(
+    (newTenantId: string | number | null) => {
+      setActiveTenantId(newTenantId);
+      // Re-fetch permissions for the newly switched tenant
+      fetchAuthMe();
+    },
+    [fetchAuthMe]
+  );
+
+  const hasPermission = useCallback(
+    (permissionKey: string): boolean => {
+      if (!permissionKey) return true;
+      if (permissions.has('*') || permissions.has('all')) return true;
+
+      // 1. Direct match
+      if (permissions.has(permissionKey)) return true;
+
+      // 2. Check alias map from config (e.g. 'roles.add' -> 'roles.addition')
+      const aliasedKey = config.permissionAliases[permissionKey];
+      if (aliasedKey && permissions.has(aliasedKey)) return true;
+
+      // 3. Reverse alias check (if user passed 'roles.addition', check if 'roles.add' is in set)
+      for (const [standardKey, mappedKey] of Object.entries(config.permissionAliases)) {
+        if (mappedKey === permissionKey && permissions.has(standardKey)) return true;
+      }
+
+      // 4. Wildcard matching (e.g. "roles.*" or "department_master.*")
+      const parts = permissionKey.split(/[.:_]/);
+      if (parts.length > 1) {
+        const wildcardDot = `${parts[0]}.*`;
+        const wildcardColon = `${parts[0]}:*`;
+        if (permissions.has(wildcardDot) || permissions.has(wildcardColon)) return true;
+      }
+
+      return false;
+    },
+    [config.permissionAliases, permissions]
+  );
+
+  const canNavigate = useCallback(
+    (routePath: string): boolean => {
+      if (!routePath) return true;
+      if (permissions.has('*')) return true;
+      if (routePaths.has(routePath)) return true;
+
+      // Allow matching paths with dynamic parameters e.g. /masters/entity-master/edit/[id]
+      for (const allowedRoute of routePaths) {
+        if (allowedRoute === routePath) return true;
+        if (allowedRoute.includes('[') || allowedRoute.includes(':')) {
+          const regexStr = '^' + allowedRoute.replace(/\[\w+\]|:\w+/g, '[^/]+') + '$';
+          if (new RegExp(regexStr).test(routePath)) return true;
+        }
+      }
+      return false;
+    },
+    [permissions, routePaths]
+  );
+
+  const login = useCallback(
+    async (credentials: LoginCredentials) => {
+      setIsLoading(true);
+      try {
+        const payload = config.adapters.auth.transformLoginPayload(credentials);
+        const raw = await http.post(config.endpoints.AUTH_LOGIN, payload, { skipAuthRedirect: true });
+        const res = config.adapters.auth.transformLoginResponse(raw);
+
+        if (res.token && typeof window !== 'undefined') {
+          localStorage.setItem('token', res.token);
+        }
+
+        await fetchAuthMe();
+        return res;
+      } catch (err: any) {
+        setError(err);
+        throw err;
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    [config.adapters.auth, config.endpoints.AUTH_LOGIN, fetchAuthMe, http]
+  );
+
+  const logout = useCallback(async () => {
+    setIsLoading(true);
+    try {
+      await http.delete(config.endpoints.AUTH_LOGOUT).catch(() => {});
+      if (typeof window !== 'undefined') {
+        localStorage.removeItem('token');
+      }
+      setUser(null);
+      setPermissions(new Set());
+      setRoutePaths(new Set());
+      setNavigation([]);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [config.endpoints.AUTH_LOGOUT, http]);
+
+  const value = useMemo<PermissionContextValue>(
+    () => ({
+      user,
+      permissions,
+      navigation,
+      isLoading,
+      isAuthenticated: Boolean(user),
+      error,
+      activeTenantId,
+      setTenantId,
+      hasPermission,
+      canNavigate,
+      login,
+      logout,
+      refresh: fetchAuthMe,
+    }),
+    [
+      user,
+      permissions,
+      navigation,
+      isLoading,
+      error,
+      activeTenantId,
+      setTenantId,
+      hasPermission,
+      canNavigate,
+      login,
+      logout,
+      fetchAuthMe,
+    ]
+  );
+
+  return <PermissionContext.Provider value={value}>{children}</PermissionContext.Provider>;
+};
+
+export function usePermission(): PermissionContextValue {
+  const context = useContext(PermissionContext);
+  if (!context) {
+    throw new Error('usePermission must be used within a PermissionProvider');
+  }
+  return context;
+}

package/src/core/context/RBACConfigContext.tsx

@@ -0,0 +1,52 @@
+import React, { createContext, useContext, useMemo } from 'react';
+import { RBACConfig, defaultRBACConfig } from '../../config/rbac.config';
+import { HttpClient } from '../api/httpClient';
+import { ThemeProvider } from '../../theme/ThemeContext';
+
+interface RBACConfigContextValue {
+  config: RBACConfig;
+  http: HttpClient;
+}
+
+const RBACConfigContext = createContext<RBACConfigContextValue | null>(null);
+
+export interface RBACConfigProviderProps {
+  config?: RBACConfig;
+  children: React.ReactNode;
+}
+
+export const RBACConfigProvider: React.FC<RBACConfigProviderProps> = ({ config = defaultRBACConfig, children }) => {
+  const http = useMemo(() => {
+    return new HttpClient({
+      baseUrl: config.apiBaseUrl,
+      getToken: config.getToken,
+      getTenantId: config.getTenantId,
+      getCustomHeaders: config.getCustomHeaders,
+      refreshToken: config.refreshToken,
+      onUnauthorized: config.onUnauthorized,
+    });
+  }, [
+    config.apiBaseUrl,
+    config.getToken,
+    config.getTenantId,
+    config.getCustomHeaders,
+    config.refreshToken,
+    config.onUnauthorized,
+  ]);
+
+  const value = useMemo(() => ({ config, http }), [config, http]);
+
+  return (
+    <RBACConfigContext.Provider value={value}>
+      <ThemeProvider theme={config.theme}>{children}</ThemeProvider>
+    </RBACConfigContext.Provider>
+  );
+};
+
+export function useRBACConfig(): RBACConfigContextValue {
+  const context = useContext(RBACConfigContext);
+  if (!context) {
+    throw new Error('useRBACConfig must be used within an RBACConfigProvider');
+  }
+  return context;
+}

package/src/core/guards/Can.tsx

@@ -0,0 +1,98 @@
+import React from 'react';
+import { usePermission } from '../context/PermissionContext';
+import { useRBACConfig } from '../context/RBACConfigContext';
+import { resolvePermission } from '../utils/permissionResolver';
+
+export interface CanProps {
+  /**
+   * The permission key to check e.g. "roles.add", "entity_master.edit"
+   */
+  do?: string;
+  /**
+   * Alternatively specify module and action without hardcoding the slug format:
+   * e.g. <Can module="roles" action="add">
+   */
+  module?: string;
+  action?: string;
+  /**
+   * Check route permission
+   */
+  route?: string;
+  /**
+   * Multiple permissions check (all must be present)
+   */
+  all?: string[];
+  /**
+   * Multiple permissions check (any one is sufficient)
+   */
+  any?: string[];
+  /**
+   * Invert the check (render if user DOES NOT have permission)
+   */
+  not?: boolean;
+  /**
+   * Fallback UI if access denied
+   */
+  fallback?: React.ReactNode;
+  children: React.ReactNode;
+}
+
+export const Can: React.FC<CanProps> = ({
+  do: actionKey,
+  module: moduleKey,
+  action: moduleAction,
+  route,
+  all,
+  any,
+  not = false,
+  fallback = null,
+  children,
+}) => {
+  const { hasPermission, canNavigate } = usePermission();
+  const { config } = useRBACConfig();
+
+  let isAllowed = true;
+
+  // Resolve permission key if module and action are supplied or if 'do' has aliases
+  const targetPermission = resolvePermission(
+    { permissionKey: actionKey, module: moduleKey, action: moduleAction },
+    config.permissionResolver,
+    config.permissionAliases
+  );
+
+  if (targetPermission) {
+    isAllowed = isAllowed && hasPermission(targetPermission);
+  }
+
+  if (route) {
+    isAllowed = isAllowed && canNavigate(route);
+  }
+
+  if (all && all.length > 0) {
+    isAllowed =
+      isAllowed &&
+      all.every((k) =>
+        hasPermission(
+          resolvePermission({ permissionKey: k }, config.permissionResolver, config.permissionAliases)
+        )
+      );
+  }
+
+  if (any && any.length > 0) {
+    isAllowed =
+      isAllowed &&
+      any.some((k) =>
+        hasPermission(
+          resolvePermission({ permissionKey: k }, config.permissionResolver, config.permissionAliases)
+        )
+      );
+  }
+
+  const result = not ? !isAllowed : isAllowed;
+
+  if (!result) {
+    return <>{fallback}</>;
+  }
+
+  return <>{children}</>;
+};

package/src/core/guards/RouteGuard.tsx

@@ -0,0 +1,42 @@
+import React from 'react';
+import { usePermission } from '../context/PermissionContext';
+
+export interface RouteGuardProps {
+  routePath: string;
+  fallback?: React.ReactNode;
+  loadingFallback?: React.ReactNode;
+  children: React.ReactNode;
+}
+
+export const RouteGuard: React.FC<RouteGuardProps> = ({
+  routePath,
+  fallback = (
+    <div className="flex flex-col items-center justify-center min-h-[400px] p-6 text-center">
+      <div className="w-12 h-12 mb-4 text-red-500 rounded-full bg-red-50 flex items-center justify-center font-bold text-xl">
+        ✕
+      </div>
+      <h3 className="text-lg font-semibold text-gray-900">Access Denied</h3>
+      <p className="mt-1 text-sm text-gray-500 max-w-sm">
+        You do not have permission to access the route <code>{routePath}</code>.
+      </p>
+    </div>
+  ),
+  loadingFallback = (
+    <div className="flex min-h-[200px] items-center justify-center">
+      <div className="text-sm text-gray-500 animate-pulse">Checking permissions...</div>
+    </div>
+  ),
+  children,
+}) => {
+  const { canNavigate, isLoading } = usePermission();
+
+  if (isLoading) {
+    return <>{loadingFallback}</>;
+  }
+
+  if (!canNavigate(routePath)) {
+    return <>{fallback}</>;
+  }
+
+  return <>{children}</>;
+};

package/src/core/hooks/useMaster.ts

@@ -0,0 +1,99 @@
+import { useState, useCallback } from 'react';
+import { useRBACConfig } from '../context/RBACConfigContext';
+import { PaginatedResult } from '../types';
+import { buildPaginationQueryParams } from '../types/pagination.types';
+
+export interface UseMasterOptions<T> {
+  listEndpoint: string;
+  createEndpoint?: string;
+  editEndpoint?: string;
+  deleteEndpoint?: string;
+  transformer: (raw: any) => PaginatedResult<T>;
+  defaultLimit?: number;
+}
+
+export function useMaster<T extends { id: string | number }>(options: UseMasterOptions<T>) {
+  const { config, http } = useRBACConfig();
+  const [items, setItems] = useState<T[]>([]);
+  const [total, setTotal] = useState<number>(0);
+  const [page, setPage] = useState<number>(1);
+  const [limit, setLimit] = useState<number>(options.defaultLimit ?? 10);
+  const [isLoading, setIsLoading] = useState<boolean>(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const fetchItems = useCallback(
+    async (params?: { page?: number; limit?: number; search?: string; [key: string]: any }) => {
+      setIsLoading(true);
+      setError(null);
+      try {
+        const targetPage = params?.page ?? page;
+        const targetLimit = params?.limit ?? limit;
+
+        const pagParams = buildPaginationQueryParams(targetPage, targetLimit, config.pagination);
+        const query = {
+          ...pagParams,
+          ...(params || {}),
+        };
+        const raw = await http.get(options.listEndpoint, query);
+        const result = options.transformer(raw);
+
+        setItems(result.items);
+        setTotal(result.total);
+        setPage(result.page);
+        setLimit(result.limit);
+        return result;
+      } catch (err: any) {
+        setError(err);
+        throw err;
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    [config.pagination, http, limit, options, page]
+  );
+
+  const createItem = useCallback(
+    async (payload: any) => {
+      if (!options.createEndpoint) throw new Error('Create endpoint not configured for this master');
+      const raw = await http.post(options.createEndpoint, payload);
+      await fetchItems();
+      return raw;
+    },
+    [fetchItems, http, options.createEndpoint]
+  );
+
+  const editItem = useCallback(
+    async (id: string | number, payload: any) => {
+      if (!options.editEndpoint) throw new Error('Edit endpoint not configured for this master');
+      const url = options.editEndpoint.replace(':id', String(id));
+      const raw = await http.patch(url, payload);
+      await fetchItems();
+      return raw;
+    },
+    [fetchItems, http, options.editEndpoint]
+  );
+
+  const deleteItem = useCallback(
+    async (id: string | number) => {
+      if (!options.deleteEndpoint) throw new Error('Delete endpoint not configured for this master');
+      const url = options.deleteEndpoint.replace(':id', String(id));
+      const raw = await http.delete(url);
+      await fetchItems();
+      return raw;
+    },
+    [fetchItems, http, options.deleteEndpoint]
+  );
+
+  return {
+    items,
+    total,
+    page,
+    limit,
+    isLoading,
+    error,
+    fetchItems,
+    createItem,
+    editItem,
+    deleteItem,
+  };
+}

package/src/core/hooks/usePermissions.ts

@@ -0,0 +1,114 @@
+import { useState, useCallback } from 'react';
+import { useRBACConfig } from '../context/RBACConfigContext';
+import { StandardAction, StandardModuleWithActions, RolePermissionMatrixRow, StandardPermissionActionMapping } from '../types';
+
+export function usePermissions() {
+  const { config, http } = useRBACConfig();
+  const [actions, setActions] = useState<StandardAction[]>([]);
+  const [registryModules, setRegistryModules] = useState<StandardModuleWithActions[]>([]);
+  const [total, setTotal] = useState<number>(0);
+  const [page] = useState<number>(1);
+  const [limit] = useState<number>(50);
+  const [isLoading, setIsLoading] = useState<boolean>(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const fetchActions = useCallback(async () => {
+    try {
+      const raw = await http.get(config.endpoints.PERMISSIONS_ACTIONS);
+      const items = config.adapters.permissions.transformActionsListResponse(raw);
+      setActions(items);
+      return items;
+    } catch (err: any) {
+      console.warn('Failed to fetch actions list, using configured defaults', err);
+      return config.adapters.permissions.transformActionsListResponse([]);
+    }
+  }, [config.adapters.permissions, config.endpoints.PERMISSIONS_ACTIONS, http]);
+
+  const fetchRegistry = useCallback(
+    async (params?: { page?: number; limit?: number }) => {
+      setIsLoading(true);
+      setError(null);
+      try {
+        const queryParams = {
+          page: params?.page ?? page,
+          limit: params?.limit ?? limit,
+        };
+        const raw = await http.get(config.endpoints.PERMISSIONS_REGISTRY, queryParams);
+        const result = config.adapters.permissions.transformRegistryResponse(raw);
+        setRegistryModules(result.items);
+        setTotal(result.total);
+        return result;
+      } catch (err: any) {
+        setError(err);
+        throw err;
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    [config.adapters.permissions, config.endpoints.PERMISSIONS_REGISTRY, http, limit, page]
+  );
+
+  /**
+   * Transforms hierarchical modules into a flat matrix structure for the UI table
+   */
+  const buildMatrixRows = useCallback(
+    (
+      modules: StandardModuleWithActions[],
+      assignedActionIds: Set<string | number>,
+      availableActions: StandardAction[],
+      level = 0
+    ): RolePermissionMatrixRow[] => {
+      const rows: RolePermissionMatrixRow[] = [];
+
+      modules.forEach((mod) => {
+        // Map each available action to whether this module has it registered and assigned
+        const actionRow = availableActions.map((action) => {
+          const registered = mod.actions.find(
+            (pa: StandardPermissionActionMapping) =>
+              String(pa.actionId) === String(action.id) || pa.actionDetails?.key === action.key
+          );
+
+          const isAssigned = registered ? assignedActionIds.has(registered.permissionActionId) : false;
+
+          return {
+            actionKey: action.key,
+            actionName: action.name,
+            actionId: action.id,
+            permissionActionId: registered ? registered.permissionActionId : '',
+            permissionKey: registered ? registered.permissionKey : `${mod.slug}.${action.key}`,
+            isAssigned,
+          };
+        });
+
+        rows.push({
+          moduleId: mod.id,
+          moduleName: mod.name,
+          slug: mod.slug,
+          parentId: mod.parentId,
+          level,
+          actions: actionRow,
+        });
+
+        if (mod.children && mod.children.length > 0) {
+          rows.push(...buildMatrixRows(mod.children, assignedActionIds, availableActions, level + 1));
+        }
+      });
+
+      return rows;
+    },
+    []
+  );
+
+  return {
+    actions,
+    registryModules,
+    total,
+    page,
+    limit,
+    isLoading,
+    error,
+    fetchActions,
+    fetchRegistry,
+    buildMatrixRows,
+  };
+}