react-auth-gate 0.0.1

package/dist/react/PermissionsGate.js

@@ -0,0 +1,101 @@
+/**
+ * PermissionsGate Component
+ *
+ * Declarative permission boundary for your components.
+ * Automatically hides or disables children based on permission checks.
+ */
+import React, { cloneElement } from 'react';
+import { usePermission } from './usePermission';
+/**
+ * PermissionsGate Component
+ *
+ * Wraps components with permission-based access control.
+ *
+ * @example
+ * ```tsx
+ * // Hide button if user can't edit
+ * <PermissionsGate allow="user.edit" resource={user}>
+ *   <EditButton />
+ * </PermissionsGate>
+ *
+ * // Disable button instead of hiding
+ * <PermissionsGate allow="post.delete" resource={post} mode="disable">
+ *   <DeleteButton />
+ * </PermissionsGate>
+ *
+ * // Check multiple permissions (any)
+ * <PermissionsGate any={["admin", "moderator"]}>
+ *   <AdminPanel />
+ * </PermissionsGate>
+ *
+ * // Check multiple permissions (all)
+ * <PermissionsGate all={["post.edit", "post.publish"]}>
+ *   <PublishButton />
+ * </PermissionsGate>
+ *
+ * // Show fallback when denied
+ * <PermissionsGate allow="premium.feature" fallback={<UpgradePrompt />}>
+ *   <PremiumFeature />
+ * </PermissionsGate>
+ * ```
+ */
+export function PermissionsGate({ allow, any, all, resource, fallback, mode = 'hide', children, }) {
+    // Determine the permission check and evaluation mode
+    let check;
+    let evalMode = 'any';
+    if (allow !== undefined) {
+        check = allow;
+        evalMode = 'any';
+    }
+    else if (any !== undefined) {
+        check = any;
+        evalMode = 'any';
+    }
+    else if (all !== undefined) {
+        check = all;
+        evalMode = 'all';
+    }
+    else {
+        // No permission check specified - deny by default
+        console.warn('PermissionsGate: No permission check specified (allow, any, or all). Denying access.');
+        return fallback ? React.createElement(React.Fragment, null, fallback) : null;
+    }
+    const { allowed, loading } = usePermission(check, resource, evalMode);
+    // While loading, optionally show loading state
+    // For now, we treat loading as "not allowed" for security
+    if (loading) {
+        return mode === 'hide' ? null : React.createElement(React.Fragment, null, children);
+    }
+    // Permission denied
+    if (!allowed) {
+        if (mode === 'hide') {
+            return fallback ? React.createElement(React.Fragment, null, fallback) : null;
+        }
+        // mode === 'disable'
+        // Try to add disabled prop to children
+        return React.createElement(React.Fragment, null, disableChildren(children));
+    }
+    // Permission granted
+    return React.createElement(React.Fragment, null, children);
+}
+/**
+ * Helper function to add disabled prop to React elements
+ */
+function disableChildren(children) {
+    return React.Children.map(children, (child) => {
+        if (!React.isValidElement(child)) {
+            return child;
+        }
+        // Clone element with disabled prop
+        // This works for standard HTML elements and components that accept disabled prop
+        return cloneElement(child, {
+            disabled: true,
+            'aria-disabled': true,
+            style: {
+                ...(child.props.style || {}),
+                opacity: 0.5,
+                cursor: 'not-allowed',
+            },
+        });
+    });
+}

package/dist/react/PermissionsProvider.d.ts

@@ -0,0 +1,39 @@
+/**
+ * PermissionsProvider
+ *
+ * Root provider component that establishes permission context for the entire app.
+ * Manages user, roles, permissions, rules, and feature flags.
+ */
+import React, { ReactNode } from 'react';
+import type { PermissionsConfig, PermissionsContextValue, PermissionEvaluation } from '../core/types';
+/**
+ * Hook to access the permissions context
+ * Throws if used outside of PermissionsProvider
+ */
+export declare function usePermissionsContext<TUser = any>(): PermissionsContextValue<TUser>;
+interface PermissionsProviderProps<TUser = any> extends PermissionsConfig<TUser> {
+    children: ReactNode;
+    /** Internal: Dev tools registration callback */
+    onEvaluationRegister?: (evaluation: PermissionEvaluation) => void;
+}
+/**
+ * PermissionsProvider Component
+ *
+ * Wrap your app with this provider to enable permission checking throughout.
+ *
+ * @example
+ * ```tsx
+ * <PermissionsProvider
+ *   user={currentUser}
+ *   roles={['admin', 'editor']}
+ *   permissions={['post.edit', 'post.delete']}
+ *   rules={customRules}
+ *   flags={{ newUI: true }}
+ * >
+ *   <App />
+ * </PermissionsProvider>
+ * ```
+ */
+export declare function PermissionsProvider<TUser = any>({ user, roles, permissions, rules, flags, enableDevTools, children, onEvaluationRegister, }: PermissionsProviderProps<TUser>): React.JSX.Element;
+export {};
+//# sourceMappingURL=PermissionsProvider.d.ts.map

package/dist/react/PermissionsProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PermissionsProvider.d.ts","sourceRoot":"","sources":["../../src/react/PermissionsProvider.tsx"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,EAAmD,SAAS,EAAE,MAAM,OAAO,CAAC;AAC1F,OAAO,KAAK,EACV,iBAAiB,EACjB,uBAAuB,EAEvB,oBAAoB,EACrB,MAAM,eAAe,CAAC;AASvB;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,GAAG,GAAG,KAAK,uBAAuB,CAAC,KAAK,CAAC,CAUnF;AAED,UAAU,wBAAwB,CAAC,KAAK,GAAG,GAAG,CAAE,SAAQ,iBAAiB,CAAC,KAAK,CAAC;IAC9E,QAAQ,EAAE,SAAS,CAAC;IACpB,gDAAgD;IAChD,oBAAoB,CAAC,EAAE,CAAC,UAAU,EAAE,oBAAoB,KAAK,IAAI,CAAC;CACnE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,GAAG,GAAG,EAAE,EAC/C,IAAI,EACJ,KAAU,EACV,WAAgB,EAChB,KAAU,EACV,KAAU,EACV,cAAc,EACd,QAAQ,EACR,oBAAoB,GACrB,EAAE,wBAAwB,CAAC,KAAK,CAAC,qBAiFjC"}

package/dist/react/PermissionsProvider.js

@@ -0,0 +1,93 @@
+/**
+ * PermissionsProvider
+ *
+ * Root provider component that establishes permission context for the entire app.
+ * Manages user, roles, permissions, rules, and feature flags.
+ */
+import React, { createContext, useContext, useMemo, useCallback } from 'react';
+import { evaluatePermission as evaluatePermissionCore, createPermissionContext, } from '../core/ruleEngine';
+// Create the context
+const PermissionsContext = createContext(null);
+/**
+ * Hook to access the permissions context
+ * Throws if used outside of PermissionsProvider
+ */
+export function usePermissionsContext() {
+    const context = useContext(PermissionsContext);
+    if (!context) {
+        throw new Error('usePermissionsContext must be used within a PermissionsProvider');
+    }
+    return context;
+}
+/**
+ * PermissionsProvider Component
+ *
+ * Wrap your app with this provider to enable permission checking throughout.
+ *
+ * @example
+ * ```tsx
+ * <PermissionsProvider
+ *   user={currentUser}
+ *   roles={['admin', 'editor']}
+ *   permissions={['post.edit', 'post.delete']}
+ *   rules={customRules}
+ *   flags={{ newUI: true }}
+ * >
+ *   <App />
+ * </PermissionsProvider>
+ * ```
+ */
+export function PermissionsProvider({ user, roles = [], permissions = [], rules = {}, flags = {}, enableDevTools, children, onEvaluationRegister, }) {
+    // Auto-enable dev tools in development unless explicitly disabled
+    const devToolsEnabled = useMemo(() => {
+        if (enableDevTools !== undefined) {
+            return enableDevTools;
+        }
+        // Check if we're in development mode
+        return process.env.NODE_ENV !== 'production';
+    }, [enableDevTools]);
+    /**
+     * Core permission evaluation function
+     * Used by all permission-checking components and hooks
+     */
+    const evaluatePermission = useCallback(async (check, resource, mode = 'any') => {
+        const context = createPermissionContext(user, resource, roles, permissions, flags);
+        const startTime = performance.now();
+        const result = await evaluatePermissionCore(check, context, rules, mode);
+        // Register with dev tools if enabled
+        if (devToolsEnabled && onEvaluationRegister) {
+            const evaluation = {
+                id: `eval-${Date.now()}-${Math.random()}`,
+                timestamp: Date.now(),
+                check: typeof check === 'function' ? 'inline' : check,
+                resource,
+                allowed: result.allowed,
+                ruleResults: result.ruleResults,
+                mode,
+            };
+            onEvaluationRegister(evaluation);
+        }
+        return result.allowed;
+    }, [user, roles, permissions, rules, flags, devToolsEnabled, onEvaluationRegister]);
+    // Memoize context value to prevent unnecessary re-renders
+    const contextValue = useMemo(() => ({
+        user,
+        roles,
+        permissions,
+        rules,
+        flags,
+        enableDevTools: devToolsEnabled,
+        evaluatePermission,
+        registerEvaluation: onEvaluationRegister,
+    }), [
+        user,
+        roles,
+        permissions,
+        rules,
+        flags,
+        devToolsEnabled,
+        evaluatePermission,
+        onEvaluationRegister,
+    ]);
+    return (React.createElement(PermissionsContext.Provider, { value: contextValue }, children));
+}

package/dist/react/ProtectedRoute.d.ts

@@ -0,0 +1,80 @@
+/**
+ * ProtectedRoute Component
+ *
+ * Wrapper for route protection based on permissions.
+ * Works with any routing library (React Router, Next.js, etc.)
+ */
+import React, { ReactNode } from 'react';
+import type { PermissionCheck } from '../core/types';
+export interface ProtectedRouteProps<TUser = any, TResource = any> {
+    /**
+     * Permission check required to access this route
+     */
+    allow: PermissionCheck<TUser, TResource>;
+    /**
+     * Resource to check permission against (optional)
+     */
+    resource?: TResource;
+    /**
+     * Content to render when permission is granted
+     */
+    children: ReactNode;
+    /**
+     * Content to render when permission is denied
+     * Typically a redirect or unauthorized message
+     */
+    fallback?: ReactNode;
+    /**
+     * Optional callback when access is denied
+     * Useful for analytics, logging, or custom redirects
+     */
+    onAccessDenied?: () => void;
+}
+/**
+ * ProtectedRoute Component
+ *
+ * Protects routes based on permissions.
+ * Framework-agnostic - works with any routing solution.
+ *
+ * @example
+ * ```tsx
+ * // With React Router
+ * <Route
+ *   path="/admin"
+ *   element={
+ *     <ProtectedRoute
+ *       allow="admin"
+ *       fallback={<Navigate to="/login" />}
+ *     >
+ *       <AdminDashboard />
+ *     </ProtectedRoute>
+ *   }
+ * />
+ *
+ * // With Next.js
+ * function AdminPage() {
+ *   const router = useRouter();
+ *
+ *   return (
+ *     <ProtectedRoute
+ *       allow="admin"
+ *       onAccessDenied={() => router.push('/login')}
+ *       fallback={<div>Redirecting...</div>}
+ *     >
+ *       <AdminPanel />
+ *     </ProtectedRoute>
+ *   );
+ * }
+ *
+ * // Resource-based protection
+ * <ProtectedRoute
+ *   allow="post.edit"
+ *   resource={post}
+ *   fallback={<Unauthorized />}
+ * >
+ *   <EditPost post={post} />
+ * </ProtectedRoute>
+ * ```
+ */
+export declare function ProtectedRoute<TUser = any, TResource = any>({ allow, resource, children, fallback, onAccessDenied, }: ProtectedRouteProps<TUser, TResource>): React.JSX.Element;
+//# sourceMappingURL=ProtectedRoute.d.ts.map

package/dist/react/ProtectedRoute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProtectedRoute.d.ts","sourceRoot":"","sources":["../../src/react/ProtectedRoute.tsx"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEzC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD,MAAM,WAAW,mBAAmB,CAAC,KAAK,GAAG,GAAG,EAAE,SAAS,GAAG,GAAG;IAC/D;;OAEG;IACH,KAAK,EAAE,eAAe,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;IAEzC;;OAEG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IAErB;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;IAEpB;;;OAGG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IAErB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,IAAI,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,wBAAgB,cAAc,CAAC,KAAK,GAAG,GAAG,EAAE,SAAS,GAAG,GAAG,EAAE,EAC3D,KAAK,EACL,QAAQ,EACR,QAAQ,EACR,QAAkC,EAClC,cAAc,GACf,EAAE,mBAAmB,CAAC,KAAK,EAAE,SAAS,CAAC,qBAsBvC"}

package/dist/react/ProtectedRoute.js

@@ -0,0 +1,92 @@
+/**
+ * ProtectedRoute Component
+ *
+ * Wrapper for route protection based on permissions.
+ * Works with any routing library (React Router, Next.js, etc.)
+ */
+import React from 'react';
+import { usePermission } from './usePermission';
+/**
+ * ProtectedRoute Component
+ *
+ * Protects routes based on permissions.
+ * Framework-agnostic - works with any routing solution.
+ *
+ * @example
+ * ```tsx
+ * // With React Router
+ * <Route
+ *   path="/admin"
+ *   element={
+ *     <ProtectedRoute
+ *       allow="admin"
+ *       fallback={<Navigate to="/login" />}
+ *     >
+ *       <AdminDashboard />
+ *     </ProtectedRoute>
+ *   }
+ * />
+ *
+ * // With Next.js
+ * function AdminPage() {
+ *   const router = useRouter();
+ *
+ *   return (
+ *     <ProtectedRoute
+ *       allow="admin"
+ *       onAccessDenied={() => router.push('/login')}
+ *       fallback={<div>Redirecting...</div>}
+ *     >
+ *       <AdminPanel />
+ *     </ProtectedRoute>
+ *   );
+ * }
+ *
+ * // Resource-based protection
+ * <ProtectedRoute
+ *   allow="post.edit"
+ *   resource={post}
+ *   fallback={<Unauthorized />}
+ * >
+ *   <EditPost post={post} />
+ * </ProtectedRoute>
+ * ```
+ */
+export function ProtectedRoute({ allow, resource, children, fallback = React.createElement(DefaultUnauthorized, null), onAccessDenied, }) {
+    const { allowed, loading } = usePermission(allow, resource);
+    // Call onAccessDenied when permission is denied (only once)
+    React.useEffect(() => {
+        if (!loading && !allowed && onAccessDenied) {
+            onAccessDenied();
+        }
+    }, [loading, allowed, onAccessDenied]);
+    // While loading, show nothing or a loading indicator
+    if (loading) {
+        return React.createElement(DefaultLoading, null);
+    }
+    // Permission denied
+    if (!allowed) {
+        return React.createElement(React.Fragment, null, fallback);
+    }
+    // Permission granted
+    return React.createElement(React.Fragment, null, children);
+}
+/**
+ * Default loading component
+ */
+function DefaultLoading() {
+    return (React.createElement("div", { style: { padding: '20px', textAlign: 'center' } }, "Loading..."));
+}
+/**
+ * Default unauthorized component
+ */
+function DefaultUnauthorized() {
+    return (React.createElement("div", { style: {
+            padding: '40px',
+            textAlign: 'center',
+            maxWidth: '600px',
+            margin: '0 auto',
+        } },
+        React.createElement("h1", null, "Access Denied"),
+        React.createElement("p", null, "You do not have permission to access this resource.")));
+}

package/dist/react/usePermission.d.ts

@@ -0,0 +1,50 @@
+/**
+ * usePermission Hook
+ *
+ * Check permissions programmatically in your components.
+ * Supports async rules and automatically re-evaluates when dependencies change.
+ */
+import type { PermissionCheck } from '../core/types';
+/**
+ * Hook to check if a permission is allowed
+ *
+ * @param check - Permission check (string, array, or function)
+ * @param resource - Optional resource to check against
+ * @param mode - Evaluation mode for arrays: 'any' (OR) or 'all' (AND)
+ * @returns Object with loading state and permission result
+ *
+ * @example
+ * ```tsx
+ * function EditButton({ user }) {
+ *   const { allowed, loading } = usePermission('user.edit', user);
+ *
+ *   if (loading) return <Spinner />;
+ *
+ *   return (
+ *     <button disabled={!allowed}>
+ *       Edit User
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+export declare function usePermission<TUser = any, TResource = any>(check: PermissionCheck<TUser, TResource>, resource?: TResource, mode?: 'any' | 'all'): {
+    allowed: boolean;
+    loading: boolean;
+};
+/**
+ * Simpler hook that only returns the boolean result
+ * Use when you don't need loading state
+ *
+ * @param check - Permission check
+ * @param resource - Optional resource
+ * @param mode - Evaluation mode
+ * @returns Boolean indicating if permission is allowed
+ *
+ * @example
+ * ```tsx
+ * const canEdit = usePermissionValue('user.edit', user);
+ * ```
+ */
+export declare function usePermissionValue<TUser = any, TResource = any>(check: PermissionCheck<TUser, TResource>, resource?: TResource, mode?: 'any' | 'all'): boolean;
+//# sourceMappingURL=usePermission.d.ts.map

package/dist/react/usePermission.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePermission.d.ts","sourceRoot":"","sources":["../../src/react/usePermission.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,aAAa,CAAC,KAAK,GAAG,GAAG,EAAE,SAAS,GAAG,GAAG,EACxD,KAAK,EAAE,eAAe,CAAC,KAAK,EAAE,SAAS,CAAC,EACxC,QAAQ,CAAC,EAAE,SAAS,EACpB,IAAI,GAAE,KAAK,GAAG,KAAa,GAC1B;IACD,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;CAClB,CA0BA;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,GAAG,GAAG,EAAE,SAAS,GAAG,GAAG,EAC7D,KAAK,EAAE,eAAe,CAAC,KAAK,EAAE,SAAS,CAAC,EACxC,QAAQ,CAAC,EAAE,SAAS,EACpB,IAAI,GAAE,KAAK,GAAG,KAAa,GAC1B,OAAO,CAGT"}

package/dist/react/usePermission.js

@@ -0,0 +1,71 @@
+/**
+ * usePermission Hook
+ *
+ * Check permissions programmatically in your components.
+ * Supports async rules and automatically re-evaluates when dependencies change.
+ */
+import { useEffect, useState } from 'react';
+import { usePermissionsContext } from './PermissionsProvider';
+/**
+ * Hook to check if a permission is allowed
+ *
+ * @param check - Permission check (string, array, or function)
+ * @param resource - Optional resource to check against
+ * @param mode - Evaluation mode for arrays: 'any' (OR) or 'all' (AND)
+ * @returns Object with loading state and permission result
+ *
+ * @example
+ * ```tsx
+ * function EditButton({ user }) {
+ *   const { allowed, loading } = usePermission('user.edit', user);
+ *
+ *   if (loading) return <Spinner />;
+ *
+ *   return (
+ *     <button disabled={!allowed}>
+ *       Edit User
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+export function usePermission(check, resource, mode = 'any') {
+    const context = usePermissionsContext();
+    const [state, setState] = useState({
+        allowed: false,
+        loading: true,
+    });
+    useEffect(() => {
+        let cancelled = false;
+        // Start evaluation
+        setState({ allowed: false, loading: true });
+        context.evaluatePermission(check, resource, mode).then((allowed) => {
+            if (!cancelled) {
+                setState({ allowed, loading: false });
+            }
+        });
+        // Cleanup function to prevent state updates after unmount
+        return () => {
+            cancelled = true;
+        };
+    }, [context.evaluatePermission, context.roles, context.permissions, context.flags, check, resource, mode]);
+    return state;
+}
+/**
+ * Simpler hook that only returns the boolean result
+ * Use when you don't need loading state
+ *
+ * @param check - Permission check
+ * @param resource - Optional resource
+ * @param mode - Evaluation mode
+ * @returns Boolean indicating if permission is allowed
+ *
+ * @example
+ * ```tsx
+ * const canEdit = usePermissionValue('user.edit', user);
+ * ```
+ */
+export function usePermissionValue(check, resource, mode = 'any') {
+    const { allowed } = usePermission(check, resource, mode);
+    return allowed;
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "react-auth-gate",
+  "version": "0.0.1",
+  "description": "A production-grade React authorization framework for RBAC, PBAC, ABAC, feature flags, and async permission checks",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "react",
+    "permissions",
+    "authorization",
+    "rbac",
+    "pbac",
+    "abac",
+    "feature-flags",
+    "access-control"
+  ],
+  "author": "Klejdi 2K",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/klejdi94/react-auth-gate"
+  },
+  "peerDependencies": {
+    "react": ">=16.8.0",
+    "react-dom": ">=16.8.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.0",
+    "@types/react": "^18.2.0",
+    "@types/react-dom": "^18.2.0",
+    "jest": "^29.5.0",
+    "jest-environment-jsdom": "^29.5.0",
+    "ts-jest": "^29.1.0",
+    "typescript": "^5.3.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "prepublishOnly": "npm run build"
+  },
+  "sideEffects": false
+}