secure-role-guard 1.0.0

package/dist/react/index.d.ts

@@ -0,0 +1,237 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { U as UserContext, a as RoleRegistry } from '../types-CSUpaGsY.js';
+
+/**
+ * Shape of the permission context value.
+ */
+type PermissionContextValue = {
+    /** Current user context */
+    readonly user: UserContext | null;
+    /** Role registry for permission lookups */
+    readonly registry: RoleRegistry;
+    /** Check if user has a specific permission */
+    readonly can: (permission: string) => boolean;
+    /** Check if user has ALL permissions */
+    readonly canAll: (permissions: readonly string[]) => boolean;
+    /** Check if user has ANY permission */
+    readonly canAny: (permissions: readonly string[]) => boolean;
+};
+/**
+ * React context for permissions.
+ * Default value denies all permissions (deny by default).
+ */
+declare const PermissionContext: react.Context<PermissionContextValue>;
+
+/**
+ * Secure Role Guard - React Provider
+ *
+ * Main provider component for permission management.
+ * Framework-agnostic: works with Next.js, Remix, Gatsby, CRA, Vite.
+ */
+
+/**
+ * Props for the PermissionProvider component.
+ */
+type PermissionProviderProps = {
+    /** Current user context (from your auth system) */
+    readonly user: UserContext | null;
+    /** Role registry created by defineRoles() */
+    readonly registry: RoleRegistry;
+    /** Child components */
+    readonly children: ReactNode;
+};
+/**
+ * Provides permission context to all child components.
+ *
+ * SECURITY: If user is null/undefined, all permission checks will deny by default.
+ *
+ * @example
+ * ```tsx
+ * import { defineRoles, PermissionProvider } from 'secure-role-guard';
+ *
+ * const roleRegistry = defineRoles({
+ *   admin: ['user.read', 'user.update'],
+ *   viewer: ['user.read']
+ * });
+ *
+ * function App() {
+ *   const user = { roles: ['admin'] }; // From your auth system
+ *
+ *   return (
+ *     <PermissionProvider user={user} registry={roleRegistry}>
+ *       <YourApp />
+ *     </PermissionProvider>
+ *   );
+ * }
+ * ```
+ */
+declare function PermissionProvider({ user, registry, children, }: PermissionProviderProps): ReactNode;
+
+/**
+ * Hook to access the full permission context.
+ *
+ * @returns Full PermissionContextValue
+ *
+ * @example
+ * ```tsx
+ * function UserProfile() {
+ *   const { user, can, canAll } = usePermissions();
+ *
+ *   if (can('user.read')) {
+ *     return <UserDetails />;
+ *   }
+ *   return <AccessDenied />;
+ * }
+ * ```
+ */
+declare function usePermissions(): PermissionContextValue;
+/**
+ * Hook to check a single permission.
+ *
+ * @param permission - The permission to check
+ * @returns True if user has the permission
+ *
+ * @example
+ * ```tsx
+ * function EditButton() {
+ *   const canEdit = useCan('user.update');
+ *
+ *   if (!canEdit) return null;
+ *   return <button>Edit User</button>;
+ * }
+ * ```
+ */
+declare function useCan(permission: string): boolean;
+/**
+ * Hook to check if user has ALL specified permissions.
+ *
+ * @param permissions - Array of permissions to check
+ * @returns True if user has all permissions
+ *
+ * @example
+ * ```tsx
+ * function AdminPanel() {
+ *   const canManage = useCanAll(['user.read', 'user.update', 'user.delete']);
+ *
+ *   if (!canManage) return <AccessDenied />;
+ *   return <AdminDashboard />;
+ * }
+ * ```
+ */
+declare function useCanAll(permissions: readonly string[]): boolean;
+/**
+ * Hook to check if user has ANY of the specified permissions.
+ *
+ * @param permissions - Array of permissions to check
+ * @returns True if user has at least one permission
+ *
+ * @example
+ * ```tsx
+ * function ViewReports() {
+ *   const canView = useCanAny(['report.admin', 'report.viewer']);
+ *
+ *   if (!canView) return null;
+ *   return <ReportList />;
+ * }
+ * ```
+ */
+declare function useCanAny(permissions: readonly string[]): boolean;
+/**
+ * Hook to get current user context.
+ *
+ * @returns Current UserContext or null
+ *
+ * @example
+ * ```tsx
+ * function UserInfo() {
+ *   const user = useUser();
+ *   return <span>User ID: {user?.userId ?? 'Anonymous'}</span>;
+ * }
+ * ```
+ */
+declare function useUser(): UserContext | null;
+
+/**
+ * Secure Role Guard - React Components
+ *
+ * Declarative components for conditional rendering based on permissions.
+ * Framework-agnostic: works with any React framework.
+ */
+
+/**
+ * Props for the Can component.
+ */
+type CanProps = {
+    /** Single permission to check */
+    readonly permission?: string;
+    /** Multiple permissions - user must have ALL (default behavior) */
+    readonly permissions?: readonly string[];
+    /** If true, user needs only ANY of the permissions */
+    readonly anyOf?: boolean;
+    /** Content to render if permission granted */
+    readonly children: ReactNode;
+    /** Optional fallback content if permission denied */
+    readonly fallback?: ReactNode;
+};
+/**
+ * Conditionally renders children based on user permissions.
+ *
+ * SECURITY: If no permission matches, nothing is rendered (deny by default).
+ *
+ * @example Single permission
+ * ```tsx
+ * <Can permission="user.update">
+ *   <EditButton />
+ * </Can>
+ * ```
+ *
+ * @example Multiple permissions (ALL required)
+ * ```tsx
+ * <Can permissions={['user.read', 'user.update']}>
+ *   <UserEditor />
+ * </Can>
+ * ```
+ *
+ * @example Multiple permissions (ANY required)
+ * ```tsx
+ * <Can permissions={['admin', 'moderator']} anyOf>
+ *   <ModPanel />
+ * </Can>
+ * ```
+ *
+ * @example With fallback
+ * ```tsx
+ * <Can permission="premium.access" fallback={<UpgradePrompt />}>
+ *   <PremiumContent />
+ * </Can>
+ * ```
+ */
+declare function Can({ permission, permissions, anyOf, children, fallback, }: CanProps): ReactNode;
+/**
+ * Props for the Cannot component.
+ */
+type CannotProps = {
+    /** Single permission to check */
+    readonly permission?: string;
+    /** Multiple permissions to check */
+    readonly permissions?: readonly string[];
+    /** If true, blocked when user has ANY permission */
+    readonly anyOf?: boolean;
+    /** Content to render if permission is NOT granted */
+    readonly children: ReactNode;
+};
+/**
+ * Inverse of Can - renders children when user does NOT have the permission.
+ * Useful for showing upgrade prompts, locked features, etc.
+ *
+ * @example
+ * ```tsx
+ * <Cannot permission="premium.access">
+ *   <UpgradePrompt />
+ * </Cannot>
+ * ```
+ */
+declare function Cannot({ permission, permissions, anyOf, children, }: CannotProps): ReactNode;
+
+export { Can, type CanProps, Cannot, type CannotProps, PermissionContext, type PermissionContextValue, PermissionProvider, type PermissionProviderProps, useCan, useCanAll, useCanAny, usePermissions, useUser };

package/dist/react/index.js

@@ -0,0 +1,177 @@
+'use strict';
+
+var react = require('react');
+var jsxRuntime = require('react/jsx-runtime');
+
+// src/react/context.tsx
+var defaultContextValue = {
+  user: null,
+  registry: {
+    getPermissions: () => Object.freeze([]),
+    hasRole: () => false,
+    getRoleNames: () => Object.freeze([])
+  },
+  can: () => false,
+  canAll: () => false,
+  canAny: () => false
+};
+var PermissionContext = react.createContext(defaultContextValue);
+PermissionContext.displayName = "PermissionContext";
+
+// src/core/permission-engine.ts
+var WILDCARD_PERMISSION = "*";
+function collectUserPermissions(user, registry) {
+  const permissions = /* @__PURE__ */ new Set();
+  if (user.permissions !== void 0) {
+    for (const permission of user.permissions) {
+      permissions.add(permission);
+    }
+  }
+  if (user.roles !== void 0) {
+    for (const role of user.roles) {
+      const rolePermissions = registry.getPermissions(role);
+      for (const permission of rolePermissions) {
+        permissions.add(permission);
+      }
+    }
+  }
+  return permissions;
+}
+function hasWildcardAccess(permissions, requested) {
+  if (permissions.has(WILDCARD_PERMISSION)) {
+    return true;
+  }
+  const parts = requested.split(".");
+  let namespace = "";
+  for (let i = 0; i < parts.length - 1; i++) {
+    const part = parts[i];
+    if (part !== void 0) {
+      namespace = namespace === "" ? part : `${namespace}.${part}`;
+      if (permissions.has(`${namespace}.*`)) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+function canUser(user, permission, registry) {
+  if (user === null || user === void 0) {
+    return false;
+  }
+  if (permission === "" || permission.trim() === "") {
+    return false;
+  }
+  const userPermissions = collectUserPermissions(user, registry);
+  if (userPermissions.has(permission)) {
+    return true;
+  }
+  if (hasWildcardAccess(userPermissions, permission)) {
+    return true;
+  }
+  return false;
+}
+function canUserAll(user, permissions, registry) {
+  if (permissions.length === 0) {
+    return false;
+  }
+  for (const permission of permissions) {
+    if (!canUser(user, permission, registry)) {
+      return false;
+    }
+  }
+  return true;
+}
+function canUserAny(user, permissions, registry) {
+  if (permissions.length === 0) {
+    return false;
+  }
+  for (const permission of permissions) {
+    if (canUser(user, permission, registry)) {
+      return true;
+    }
+  }
+  return false;
+}
+function PermissionProvider({
+  user,
+  registry,
+  children
+}) {
+  const contextValue = react.useMemo(
+    () => ({
+      user,
+      registry,
+      can: (permission) => canUser(user, permission, registry),
+      canAll: (permissions) => canUserAll(user, permissions, registry),
+      canAny: (permissions) => canUserAny(user, permissions, registry)
+    }),
+    [user, registry]
+  );
+  return /* @__PURE__ */ jsxRuntime.jsx(PermissionContext.Provider, { value: contextValue, children });
+}
+function usePermissions() {
+  return react.useContext(PermissionContext);
+}
+function useCan(permission) {
+  const { can } = react.useContext(PermissionContext);
+  return can(permission);
+}
+function useCanAll(permissions) {
+  const { canAll } = react.useContext(PermissionContext);
+  return canAll(permissions);
+}
+function useCanAny(permissions) {
+  const { canAny } = react.useContext(PermissionContext);
+  return canAny(permissions);
+}
+function useUser() {
+  const { user } = react.useContext(PermissionContext);
+  return user;
+}
+
+// src/react/components.tsx
+function Can({
+  permission,
+  permissions,
+  anyOf = false,
+  children,
+  fallback = null
+}) {
+  if (permission !== void 0) {
+    const allowed = useCan(permission);
+    return allowed ? children : fallback;
+  }
+  if (permissions !== void 0 && permissions.length > 0) {
+    const allowed = anyOf ? useCanAny(permissions) : useCanAll(permissions);
+    return allowed ? children : fallback;
+  }
+  return fallback;
+}
+function Cannot({
+  permission,
+  permissions,
+  anyOf = false,
+  children
+}) {
+  if (permission !== void 0) {
+    const allowed = useCan(permission);
+    return allowed ? null : children;
+  }
+  if (permissions !== void 0 && permissions.length > 0) {
+    const allowed = anyOf ? useCanAny(permissions) : useCanAll(permissions);
+    return allowed ? null : children;
+  }
+  return children;
+}
+
+exports.Can = Can;
+exports.Cannot = Cannot;
+exports.PermissionContext = PermissionContext;
+exports.PermissionProvider = PermissionProvider;
+exports.useCan = useCan;
+exports.useCanAll = useCanAll;
+exports.useCanAny = useCanAny;
+exports.usePermissions = usePermissions;
+exports.useUser = useUser;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/react/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/react/context.tsx","../../src/core/permission-engine.ts","../../src/react/provider.tsx","../../src/react/hooks.ts","../../src/react/components.tsx"],"names":["createContext","useMemo","useContext"],"mappings":"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","file":"index.js","sourcesContent":["/**\r\n * Secure Role Guard - React Context\r\n *\r\n * Framework-agnostic React context for permission management.\r\n * Works with Next.js, Remix, Gatsby, CRA, Vite, and any React framework.\r\n */\r\n\r\nimport { createContext } from \"react\";\r\nimport type { UserContext, RoleRegistry } from \"../core/types\";\r\n\r\n/**\r\n * Shape of the permission context value.\r\n */\r\nexport type PermissionContextValue = {\r\n  /** Current user context */\r\n  readonly user: UserContext | null;\r\n  /** Role registry for permission lookups */\r\n  readonly registry: RoleRegistry;\r\n  /** Check if user has a specific permission */\r\n  readonly can: (permission: string) => boolean;\r\n  /** Check if user has ALL permissions */\r\n  readonly canAll: (permissions: readonly string[]) => boolean;\r\n  /** Check if user has ANY permission */\r\n  readonly canAny: (permissions: readonly string[]) => boolean;\r\n};\r\n\r\n/**\r\n * Default context value (deny all).\r\n * Used when no provider is present.\r\n */\r\nconst defaultContextValue: PermissionContextValue = {\r\n  user: null,\r\n  registry: {\r\n    getPermissions: () => Object.freeze([]),\r\n    hasRole: () => false,\r\n    getRoleNames: () => Object.freeze([]),\r\n  },\r\n  can: () => false,\r\n  canAll: () => false,\r\n  canAny: () => false,\r\n};\r\n\r\n/**\r\n * React context for permissions.\r\n * Default value denies all permissions (deny by default).\r\n */\r\nexport const PermissionContext =\r\n  createContext<PermissionContextValue>(defaultContextValue);\r\n\r\n// Set display name for React DevTools\r\nPermissionContext.displayName = \"PermissionContext\";\r\n","/**\r\n * Secure Role Guard - Permission Engine\r\n *\r\n * Pure functions for permission checking.\r\n * Zero side effects, zero dependencies, zero mutations.\r\n */\r\n\r\nimport type { UserContext, RoleRegistry, PermissionCheckResult } from \"./types\";\r\n\r\n/** Wildcard permission that grants all access */\r\nconst WILDCARD_PERMISSION = \"*\";\r\n\r\n/**\r\n * Collects all permissions for a user from their roles and direct permissions.\r\n *\r\n * @param user - The user context\r\n * @param registry - The role registry to resolve role permissions\r\n * @returns Set of all permissions (for efficient lookup)\r\n */\r\nfunction collectUserPermissions(\r\n  user: UserContext,\r\n  registry: RoleRegistry\r\n): ReadonlySet<string> {\r\n  const permissions = new Set<string>();\r\n\r\n  // Add direct user permissions\r\n  if (user.permissions !== undefined) {\r\n    for (const permission of user.permissions) {\r\n      permissions.add(permission);\r\n    }\r\n  }\r\n\r\n  // Add permissions from all user roles\r\n  if (user.roles !== undefined) {\r\n    for (const role of user.roles) {\r\n      const rolePermissions = registry.getPermissions(role);\r\n      for (const permission of rolePermissions) {\r\n        permissions.add(permission);\r\n      }\r\n    }\r\n  }\r\n\r\n  return permissions;\r\n}\r\n\r\n/**\r\n * Checks if a permission set contains a wildcard that grants the requested permission.\r\n *\r\n * Supports:\r\n * - Exact wildcard (*) - grants everything\r\n * - Namespace wildcards (user.*) - grants all under namespace\r\n *\r\n * @param permissions - Set of permissions to check\r\n * @param requested - The permission being requested\r\n * @returns True if wildcard grants access\r\n */\r\nfunction hasWildcardAccess(\r\n  permissions: ReadonlySet<string>,\r\n  requested: string\r\n): boolean {\r\n  // Check for global wildcard\r\n  if (permissions.has(WILDCARD_PERMISSION)) {\r\n    return true;\r\n  }\r\n\r\n  // Check for namespace wildcards (e.g., user.* grants user.read)\r\n  const parts = requested.split(\".\");\r\n  let namespace = \"\";\r\n\r\n  for (let i = 0; i < parts.length - 1; i++) {\r\n    const part = parts[i];\r\n    if (part !== undefined) {\r\n      namespace = namespace === \"\" ? part : `${namespace}.${part}`;\r\n      if (permissions.has(`${namespace}.*`)) {\r\n        return true;\r\n      }\r\n    }\r\n  }\r\n\r\n  return false;\r\n}\r\n\r\n/**\r\n * Checks if a user has a specific permission.\r\n *\r\n * SECURITY GUARANTEES:\r\n * - Deny by default: undefined/null/empty always returns false\r\n * - Pure function: no side effects, no mutations\r\n * - Deterministic: same inputs always produce same output\r\n *\r\n * @param user - The user context to check\r\n * @param permission - The permission required\r\n * @param registry - The role registry for resolving roles\r\n * @returns True if user has the permission, false otherwise\r\n *\r\n * @example\r\n * const canEdit = canUser(currentUser, 'user.update', roleRegistry);\r\n */\r\nexport function canUser(\r\n  user: UserContext | null | undefined,\r\n  permission: string,\r\n  registry: RoleRegistry\r\n): boolean {\r\n  // DENY BY DEFAULT: No user context means no access\r\n  if (user === null || user === undefined) {\r\n    return false;\r\n  }\r\n\r\n  // DENY BY DEFAULT: Empty permission request is invalid\r\n  if (permission === \"\" || permission.trim() === \"\") {\r\n    return false;\r\n  }\r\n\r\n  const userPermissions = collectUserPermissions(user, registry);\r\n\r\n  // Check for exact permission match\r\n  if (userPermissions.has(permission)) {\r\n    return true;\r\n  }\r\n\r\n  // Check for wildcard access\r\n  if (hasWildcardAccess(userPermissions, permission)) {\r\n    return true;\r\n  }\r\n\r\n  // DENY BY DEFAULT\r\n  return false;\r\n}\r\n\r\n/**\r\n * Checks if a user has ALL of the specified permissions.\r\n *\r\n * @param user - The user context to check\r\n * @param permissions - Array of permissions required\r\n * @param registry - The role registry\r\n * @returns True if user has ALL permissions\r\n *\r\n * @example\r\n * const canManage = canUserAll(user, ['user.read', 'user.update'], registry);\r\n */\r\nexport function canUserAll(\r\n  user: UserContext | null | undefined,\r\n  permissions: readonly string[],\r\n  registry: RoleRegistry\r\n): boolean {\r\n  // DENY BY DEFAULT: Empty permissions array\r\n  if (permissions.length === 0) {\r\n    return false;\r\n  }\r\n\r\n  for (const permission of permissions) {\r\n    if (!canUser(user, permission, registry)) {\r\n      return false;\r\n    }\r\n  }\r\n\r\n  return true;\r\n}\r\n\r\n/**\r\n * Checks if a user has ANY of the specified permissions.\r\n *\r\n * @param user - The user context to check\r\n * @param permissions - Array of permissions to check\r\n * @param registry - The role registry\r\n * @returns True if user has at least one permission\r\n *\r\n * @example\r\n * const canView = canUserAny(user, ['report.view', 'report.admin'], registry);\r\n */\r\nexport function canUserAny(\r\n  user: UserContext | null | undefined,\r\n  permissions: readonly string[],\r\n  registry: RoleRegistry\r\n): boolean {\r\n  // DENY BY DEFAULT: Empty permissions array\r\n  if (permissions.length === 0) {\r\n    return false;\r\n  }\r\n\r\n  for (const permission of permissions) {\r\n    if (canUser(user, permission, registry)) {\r\n      return true;\r\n    }\r\n  }\r\n\r\n  return false;\r\n}\r\n\r\n/**\r\n * Extended permission check with detailed result.\r\n * Useful for debugging and logging.\r\n *\r\n * @param user - The user context\r\n * @param permission - Permission to check\r\n * @param registry - The role registry\r\n * @returns PermissionCheckResult with allowed status and reason\r\n */\r\nexport function checkPermission(\r\n  user: UserContext | null | undefined,\r\n  permission: string,\r\n  registry: RoleRegistry\r\n): PermissionCheckResult {\r\n  if (user === null || user === undefined) {\r\n    return Object.freeze({\r\n      allowed: false,\r\n      reason: \"No user context provided\",\r\n    });\r\n  }\r\n\r\n  if (permission === \"\" || permission.trim() === \"\") {\r\n    return Object.freeze({\r\n      allowed: false,\r\n      reason: \"Empty permission requested\",\r\n    });\r\n  }\r\n\r\n  const allowed = canUser(user, permission, registry);\r\n\r\n  return Object.freeze({\r\n    allowed,\r\n    reason: allowed\r\n      ? `Permission \"${permission}\" granted`\r\n      : `Permission \"${permission}\" denied`,\r\n  });\r\n}\r\n","/**\r\n * Secure Role Guard - React Provider\r\n *\r\n * Main provider component for permission management.\r\n * Framework-agnostic: works with Next.js, Remix, Gatsby, CRA, Vite.\r\n */\r\n\r\nimport { useMemo, type ReactNode } from \"react\";\r\nimport type { UserContext, RoleRegistry } from \"../core/types\";\r\nimport { canUser, canUserAll, canUserAny } from \"../core/permission-engine\";\r\nimport { PermissionContext, type PermissionContextValue } from \"./context\";\r\n\r\n/**\r\n * Props for the PermissionProvider component.\r\n */\r\nexport type PermissionProviderProps = {\r\n  /** Current user context (from your auth system) */\r\n  readonly user: UserContext | null;\r\n  /** Role registry created by defineRoles() */\r\n  readonly registry: RoleRegistry;\r\n  /** Child components */\r\n  readonly children: ReactNode;\r\n};\r\n\r\n/**\r\n * Provides permission context to all child components.\r\n *\r\n * SECURITY: If user is null/undefined, all permission checks will deny by default.\r\n *\r\n * @example\r\n * ```tsx\r\n * import { defineRoles, PermissionProvider } from 'secure-role-guard';\r\n *\r\n * const roleRegistry = defineRoles({\r\n *   admin: ['user.read', 'user.update'],\r\n *   viewer: ['user.read']\r\n * });\r\n *\r\n * function App() {\r\n *   const user = { roles: ['admin'] }; // From your auth system\r\n *\r\n *   return (\r\n *     <PermissionProvider user={user} registry={roleRegistry}>\r\n *       <YourApp />\r\n *     </PermissionProvider>\r\n *   );\r\n * }\r\n * ```\r\n */\r\nexport function PermissionProvider({\r\n  user,\r\n  registry,\r\n  children,\r\n}: PermissionProviderProps): ReactNode {\r\n  // Memoize context value to prevent unnecessary re-renders\r\n  const contextValue = useMemo<PermissionContextValue>(\r\n    () => ({\r\n      user,\r\n      registry,\r\n      can: (permission: string) => canUser(user, permission, registry),\r\n      canAll: (permissions: readonly string[]) =>\r\n        canUserAll(user, permissions, registry),\r\n      canAny: (permissions: readonly string[]) =>\r\n        canUserAny(user, permissions, registry),\r\n    }),\r\n    [user, registry]\r\n  );\r\n\r\n  return (\r\n    <PermissionContext.Provider value={contextValue}>\r\n      {children}\r\n    </PermissionContext.Provider>\r\n  );\r\n}\r\n","/**\r\n * Secure Role Guard - React Hooks\r\n *\r\n * Hooks for permission checking in React components.\r\n * Framework-agnostic: works with any React framework.\r\n */\r\n\r\nimport { useContext } from \"react\";\r\nimport { PermissionContext, type PermissionContextValue } from \"./context\";\r\n\r\n/**\r\n * Hook to access the full permission context.\r\n *\r\n * @returns Full PermissionContextValue\r\n *\r\n * @example\r\n * ```tsx\r\n * function UserProfile() {\r\n *   const { user, can, canAll } = usePermissions();\r\n *\r\n *   if (can('user.read')) {\r\n *     return <UserDetails />;\r\n *   }\r\n *   return <AccessDenied />;\r\n * }\r\n * ```\r\n */\r\nexport function usePermissions(): PermissionContextValue {\r\n  return useContext(PermissionContext);\r\n}\r\n\r\n/**\r\n * Hook to check a single permission.\r\n *\r\n * @param permission - The permission to check\r\n * @returns True if user has the permission\r\n *\r\n * @example\r\n * ```tsx\r\n * function EditButton() {\r\n *   const canEdit = useCan('user.update');\r\n *\r\n *   if (!canEdit) return null;\r\n *   return <button>Edit User</button>;\r\n * }\r\n * ```\r\n */\r\nexport function useCan(permission: string): boolean {\r\n  const { can } = useContext(PermissionContext);\r\n  return can(permission);\r\n}\r\n\r\n/**\r\n * Hook to check if user has ALL specified permissions.\r\n *\r\n * @param permissions - Array of permissions to check\r\n * @returns True if user has all permissions\r\n *\r\n * @example\r\n * ```tsx\r\n * function AdminPanel() {\r\n *   const canManage = useCanAll(['user.read', 'user.update', 'user.delete']);\r\n *\r\n *   if (!canManage) return <AccessDenied />;\r\n *   return <AdminDashboard />;\r\n * }\r\n * ```\r\n */\r\nexport function useCanAll(permissions: readonly string[]): boolean {\r\n  const { canAll } = useContext(PermissionContext);\r\n  return canAll(permissions);\r\n}\r\n\r\n/**\r\n * Hook to check if user has ANY of the specified permissions.\r\n *\r\n * @param permissions - Array of permissions to check\r\n * @returns True if user has at least one permission\r\n *\r\n * @example\r\n * ```tsx\r\n * function ViewReports() {\r\n *   const canView = useCanAny(['report.admin', 'report.viewer']);\r\n *\r\n *   if (!canView) return null;\r\n *   return <ReportList />;\r\n * }\r\n * ```\r\n */\r\nexport function useCanAny(permissions: readonly string[]): boolean {\r\n  const { canAny } = useContext(PermissionContext);\r\n  return canAny(permissions);\r\n}\r\n\r\n/**\r\n * Hook to get current user context.\r\n *\r\n * @returns Current UserContext or null\r\n *\r\n * @example\r\n * ```tsx\r\n * function UserInfo() {\r\n *   const user = useUser();\r\n *   return <span>User ID: {user?.userId ?? 'Anonymous'}</span>;\r\n * }\r\n * ```\r\n */\r\nexport function useUser() {\r\n  const { user } = useContext(PermissionContext);\r\n  return user;\r\n}\r\n","/**\r\n * Secure Role Guard - React Components\r\n *\r\n * Declarative components for conditional rendering based on permissions.\r\n * Framework-agnostic: works with any React framework.\r\n */\r\n\r\nimport type { ReactNode } from \"react\";\r\nimport { useCan, useCanAll, useCanAny } from \"./hooks\";\r\n\r\n/**\r\n * Props for the Can component.\r\n */\r\nexport type CanProps = {\r\n  /** Single permission to check */\r\n  readonly permission?: string;\r\n  /** Multiple permissions - user must have ALL (default behavior) */\r\n  readonly permissions?: readonly string[];\r\n  /** If true, user needs only ANY of the permissions */\r\n  readonly anyOf?: boolean;\r\n  /** Content to render if permission granted */\r\n  readonly children: ReactNode;\r\n  /** Optional fallback content if permission denied */\r\n  readonly fallback?: ReactNode;\r\n};\r\n\r\n/**\r\n * Conditionally renders children based on user permissions.\r\n *\r\n * SECURITY: If no permission matches, nothing is rendered (deny by default).\r\n *\r\n * @example Single permission\r\n * ```tsx\r\n * <Can permission=\"user.update\">\r\n *   <EditButton />\r\n * </Can>\r\n * ```\r\n *\r\n * @example Multiple permissions (ALL required)\r\n * ```tsx\r\n * <Can permissions={['user.read', 'user.update']}>\r\n *   <UserEditor />\r\n * </Can>\r\n * ```\r\n *\r\n * @example Multiple permissions (ANY required)\r\n * ```tsx\r\n * <Can permissions={['admin', 'moderator']} anyOf>\r\n *   <ModPanel />\r\n * </Can>\r\n * ```\r\n *\r\n * @example With fallback\r\n * ```tsx\r\n * <Can permission=\"premium.access\" fallback={<UpgradePrompt />}>\r\n *   <PremiumContent />\r\n * </Can>\r\n * ```\r\n */\r\nexport function Can({\r\n  permission,\r\n  permissions,\r\n  anyOf = false,\r\n  children,\r\n  fallback = null,\r\n}: CanProps): ReactNode {\r\n  // Single permission check\r\n  if (permission !== undefined) {\r\n    const allowed = useCan(permission);\r\n    return allowed ? children : fallback;\r\n  }\r\n\r\n  // Multiple permissions check\r\n  if (permissions !== undefined && permissions.length > 0) {\r\n    const allowed = anyOf ? useCanAny(permissions) : useCanAll(permissions);\r\n    return allowed ? children : fallback;\r\n  }\r\n\r\n  // No permissions specified - deny by default\r\n  return fallback;\r\n}\r\n\r\n/**\r\n * Props for the Cannot component.\r\n */\r\nexport type CannotProps = {\r\n  /** Single permission to check */\r\n  readonly permission?: string;\r\n  /** Multiple permissions to check */\r\n  readonly permissions?: readonly string[];\r\n  /** If true, blocked when user has ANY permission */\r\n  readonly anyOf?: boolean;\r\n  /** Content to render if permission is NOT granted */\r\n  readonly children: ReactNode;\r\n};\r\n\r\n/**\r\n * Inverse of Can - renders children when user does NOT have the permission.\r\n * Useful for showing upgrade prompts, locked features, etc.\r\n *\r\n * @example\r\n * ```tsx\r\n * <Cannot permission=\"premium.access\">\r\n *   <UpgradePrompt />\r\n * </Cannot>\r\n * ```\r\n */\r\nexport function Cannot({\r\n  permission,\r\n  permissions,\r\n  anyOf = false,\r\n  children,\r\n}: CannotProps): ReactNode {\r\n  // Single permission check\r\n  if (permission !== undefined) {\r\n    const allowed = useCan(permission);\r\n    return allowed ? null : children;\r\n  }\r\n\r\n  // Multiple permissions check\r\n  if (permissions !== undefined && permissions.length > 0) {\r\n    const allowed = anyOf ? useCanAny(permissions) : useCanAll(permissions);\r\n    return allowed ? null : children;\r\n  }\r\n\r\n  // No permissions specified - show children (inverse of deny by default)\r\n  return children;\r\n}\r\n"]}

package/dist/react/index.mjs

@@ -0,0 +1,167 @@
+import { createContext, useMemo, useContext } from 'react';
+import { jsx } from 'react/jsx-runtime';
+
+// src/react/context.tsx
+var defaultContextValue = {
+  user: null,
+  registry: {
+    getPermissions: () => Object.freeze([]),
+    hasRole: () => false,
+    getRoleNames: () => Object.freeze([])
+  },
+  can: () => false,
+  canAll: () => false,
+  canAny: () => false
+};
+var PermissionContext = createContext(defaultContextValue);
+PermissionContext.displayName = "PermissionContext";
+
+// src/core/permission-engine.ts
+var WILDCARD_PERMISSION = "*";
+function collectUserPermissions(user, registry) {
+  const permissions = /* @__PURE__ */ new Set();
+  if (user.permissions !== void 0) {
+    for (const permission of user.permissions) {
+      permissions.add(permission);
+    }
+  }
+  if (user.roles !== void 0) {
+    for (const role of user.roles) {
+      const rolePermissions = registry.getPermissions(role);
+      for (const permission of rolePermissions) {
+        permissions.add(permission);
+      }
+    }
+  }
+  return permissions;
+}
+function hasWildcardAccess(permissions, requested) {
+  if (permissions.has(WILDCARD_PERMISSION)) {
+    return true;
+  }
+  const parts = requested.split(".");
+  let namespace = "";
+  for (let i = 0; i < parts.length - 1; i++) {
+    const part = parts[i];
+    if (part !== void 0) {
+      namespace = namespace === "" ? part : `${namespace}.${part}`;
+      if (permissions.has(`${namespace}.*`)) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+function canUser(user, permission, registry) {
+  if (user === null || user === void 0) {
+    return false;
+  }
+  if (permission === "" || permission.trim() === "") {
+    return false;
+  }
+  const userPermissions = collectUserPermissions(user, registry);
+  if (userPermissions.has(permission)) {
+    return true;
+  }
+  if (hasWildcardAccess(userPermissions, permission)) {
+    return true;
+  }
+  return false;
+}
+function canUserAll(user, permissions, registry) {
+  if (permissions.length === 0) {
+    return false;
+  }
+  for (const permission of permissions) {
+    if (!canUser(user, permission, registry)) {
+      return false;
+    }
+  }
+  return true;
+}
+function canUserAny(user, permissions, registry) {
+  if (permissions.length === 0) {
+    return false;
+  }
+  for (const permission of permissions) {
+    if (canUser(user, permission, registry)) {
+      return true;
+    }
+  }
+  return false;
+}
+function PermissionProvider({
+  user,
+  registry,
+  children
+}) {
+  const contextValue = useMemo(
+    () => ({
+      user,
+      registry,
+      can: (permission) => canUser(user, permission, registry),
+      canAll: (permissions) => canUserAll(user, permissions, registry),
+      canAny: (permissions) => canUserAny(user, permissions, registry)
+    }),
+    [user, registry]
+  );
+  return /* @__PURE__ */ jsx(PermissionContext.Provider, { value: contextValue, children });
+}
+function usePermissions() {
+  return useContext(PermissionContext);
+}
+function useCan(permission) {
+  const { can } = useContext(PermissionContext);
+  return can(permission);
+}
+function useCanAll(permissions) {
+  const { canAll } = useContext(PermissionContext);
+  return canAll(permissions);
+}
+function useCanAny(permissions) {
+  const { canAny } = useContext(PermissionContext);
+  return canAny(permissions);
+}
+function useUser() {
+  const { user } = useContext(PermissionContext);
+  return user;
+}
+
+// src/react/components.tsx
+function Can({
+  permission,
+  permissions,
+  anyOf = false,
+  children,
+  fallback = null
+}) {
+  if (permission !== void 0) {
+    const allowed = useCan(permission);
+    return allowed ? children : fallback;
+  }
+  if (permissions !== void 0 && permissions.length > 0) {
+    const allowed = anyOf ? useCanAny(permissions) : useCanAll(permissions);
+    return allowed ? children : fallback;
+  }
+  return fallback;
+}
+function Cannot({
+  permission,
+  permissions,
+  anyOf = false,
+  children
+}) {
+  if (permission !== void 0) {
+    const allowed = useCan(permission);
+    return allowed ? null : children;
+  }
+  if (permissions !== void 0 && permissions.length > 0) {
+    const allowed = anyOf ? useCanAny(permissions) : useCanAll(permissions);
+    return allowed ? null : children;
+  }
+  return children;
+}
+
+export { Can, Cannot, PermissionContext, PermissionProvider, useCan, useCanAll, useCanAny, usePermissions, useUser };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/react/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/react/context.tsx","../../src/core/permission-engine.ts","../../src/react/provider.tsx","../../src/react/hooks.ts","../../src/react/components.tsx"],"names":[],"mappings":";;;;AA8BA,IAAM,mBAAA,GAA8C;AAAA,EAClD,IAAA,EAAM,IAAA;AAAA,EACN,QAAA,EAAU;AAAA,IACR,cAAA,EAAgB,MAAM,MAAA,CAAO,MAAA,CAAO,EAAE,CAAA;AAAA,IACtC,SAAS,MAAM,KAAA;AAAA,IACf,YAAA,EAAc,MAAM,MAAA,CAAO,MAAA,CAAO,EAAE;AAAA,GACtC;AAAA,EACA,KAAK,MAAM,KAAA;AAAA,EACX,QAAQ,MAAM,KAAA;AAAA,EACd,QAAQ,MAAM;AAChB,CAAA;AAMO,IAAM,iBAAA,GACX,cAAsC,mBAAmB;AAG3D,iBAAA,CAAkB,WAAA,GAAc,mBAAA;;;ACxChC,IAAM,mBAAA,GAAsB,GAAA;AAS5B,SAAS,sBAAA,CACP,MACA,QAAA,EACqB;AACrB,EAAA,MAAM,WAAA,uBAAkB,GAAA,EAAY;AAGpC,EAAA,IAAI,IAAA,CAAK,gBAAgB,MAAA,EAAW;AAClC,IAAA,KAAA,MAAW,UAAA,IAAc,KAAK,WAAA,EAAa;AACzC,MAAA,WAAA,CAAY,IAAI,UAAU,CAAA;AAAA,IAC5B;AAAA,EACF;AAGA,EAAA,IAAI,IAAA,CAAK,UAAU,MAAA,EAAW;AAC5B,IAAA,KAAA,MAAW,IAAA,IAAQ,KAAK,KAAA,EAAO;AAC7B,MAAA,MAAM,eAAA,GAAkB,QAAA,CAAS,cAAA,CAAe,IAAI,CAAA;AACpD,MAAA,KAAA,MAAW,cAAc,eAAA,EAAiB;AACxC,QAAA,WAAA,CAAY,IAAI,UAAU,CAAA;AAAA,MAC5B;AAAA,IACF;AAAA,EACF;AAEA,EAAA,OAAO,WAAA;AACT;AAaA,SAAS,iBAAA,CACP,aACA,SAAA,EACS;AAET,EAAA,IAAI,WAAA,CAAY,GAAA,CAAI,mBAAmB,CAAA,EAAG;AACxC,IAAA,OAAO,IAAA;AAAA,EACT;AAGA,EAAA,MAAM,KAAA,GAAQ,SAAA,CAAU,KAAA,CAAM,GAAG,CAAA;AACjC,EAAA,IAAI,SAAA,GAAY,EAAA;AAEhB,EAAA,KAAA,IAAS,IAAI,CAAA,EAAG,CAAA,GAAI,KAAA,CAAM,MAAA,GAAS,GAAG,CAAA,EAAA,EAAK;AACzC,IAAA,MAAM,IAAA,GAAO,MAAM,CAAC,CAAA;AACpB,IAAA,IAAI,SAAS,MAAA,EAAW;AACtB,MAAA,SAAA,GAAY,cAAc,EAAA,GAAK,IAAA,GAAO,CAAA,EAAG,SAAS,IAAI,IAAI,CAAA,CAAA;AAC1D,MAAA,IAAI,WAAA,CAAY,GAAA,CAAI,CAAA,EAAG,SAAS,IAAI,CAAA,EAAG;AACrC,QAAA,OAAO,IAAA;AAAA,MACT;AAAA,IACF;AAAA,EACF;AAEA,EAAA,OAAO,KAAA;AACT;AAkBO,SAAS,OAAA,CACd,IAAA,EACA,UAAA,EACA,QAAA,EACS;AAET,EAAA,IAAI,IAAA,KAAS,IAAA,IAAQ,IAAA,KAAS,MAAA,EAAW;AACvC,IAAA,OAAO,KAAA;AAAA,EACT;AAGA,EAAA,IAAI,UAAA,KAAe,EAAA,IAAM,UAAA,CAAW,IAAA,OAAW,EAAA,EAAI;AACjD,IAAA,OAAO,KAAA;AAAA,EACT;AAEA,EAAA,MAAM,eAAA,GAAkB,sBAAA,CAAuB,IAAA,EAAM,QAAQ,CAAA;AAG7D,EAAA,IAAI,eAAA,CAAgB,GAAA,CAAI,UAAU,CAAA,EAAG;AACnC,IAAA,OAAO,IAAA;AAAA,EACT;AAGA,EAAA,IAAI,iBAAA,CAAkB,eAAA,EAAiB,UAAU,CAAA,EAAG;AAClD,IAAA,OAAO,IAAA;AAAA,EACT;AAGA,EAAA,OAAO,KAAA;AACT;AAaO,SAAS,UAAA,CACd,IAAA,EACA,WAAA,EACA,QAAA,EACS;AAET,EAAA,IAAI,WAAA,CAAY,WAAW,CAAA,EAAG;AAC5B,IAAA,OAAO,KAAA;AAAA,EACT;AAEA,EAAA,KAAA,MAAW,cAAc,WAAA,EAAa;AACpC,IAAA,IAAI,CAAC,OAAA,CAAQ,IAAA,EAAM,UAAA,EAAY,QAAQ,CAAA,EAAG;AACxC,MAAA,OAAO,KAAA;AAAA,IACT;AAAA,EACF;AAEA,EAAA,OAAO,IAAA;AACT;AAaO,SAAS,UAAA,CACd,IAAA,EACA,WAAA,EACA,QAAA,EACS;AAET,EAAA,IAAI,WAAA,CAAY,WAAW,CAAA,EAAG;AAC5B,IAAA,OAAO,KAAA;AAAA,EACT;AAEA,EAAA,KAAA,MAAW,cAAc,WAAA,EAAa;AACpC,IAAA,IAAI,OAAA,CAAQ,IAAA,EAAM,UAAA,EAAY,QAAQ,CAAA,EAAG;AACvC,MAAA,OAAO,IAAA;AAAA,IACT;AAAA,EACF;AAEA,EAAA,OAAO,KAAA;AACT;AC1IO,SAAS,kBAAA,CAAmB;AAAA,EACjC,IAAA;AAAA,EACA,QAAA;AAAA,EACA;AACF,CAAA,EAAuC;AAErC,EAAA,MAAM,YAAA,GAAe,OAAA;AAAA,IACnB,OAAO;AAAA,MACL,IAAA;AAAA,MACA,QAAA;AAAA,MACA,KAAK,CAAC,UAAA,KAAuB,OAAA,CAAQ,IAAA,EAAM,YAAY,QAAQ,CAAA;AAAA,MAC/D,QAAQ,CAAC,WAAA,KACP,UAAA,CAAW,IAAA,EAAM,aAAa,QAAQ,CAAA;AAAA,MACxC,QAAQ,CAAC,WAAA,KACP,UAAA,CAAW,IAAA,EAAM,aAAa,QAAQ;AAAA,KAC1C,CAAA;AAAA,IACA,CAAC,MAAM,QAAQ;AAAA,GACjB;AAEA,EAAA,2BACG,iBAAA,CAAkB,QAAA,EAAlB,EAA2B,KAAA,EAAO,cAChC,QAAA,EACH,CAAA;AAEJ;AC9CO,SAAS,cAAA,GAAyC;AACvD,EAAA,OAAO,WAAW,iBAAiB,CAAA;AACrC;AAkBO,SAAS,OAAO,UAAA,EAA6B;AAClD,EAAA,MAAM,EAAE,GAAA,EAAI,GAAI,UAAA,CAAW,iBAAiB,CAAA;AAC5C,EAAA,OAAO,IAAI,UAAU,CAAA;AACvB;AAkBO,SAAS,UAAU,WAAA,EAAyC;AACjE,EAAA,MAAM,EAAE,MAAA,EAAO,GAAI,UAAA,CAAW,iBAAiB,CAAA;AAC/C,EAAA,OAAO,OAAO,WAAW,CAAA;AAC3B;AAkBO,SAAS,UAAU,WAAA,EAAyC;AACjE,EAAA,MAAM,EAAE,MAAA,EAAO,GAAI,UAAA,CAAW,iBAAiB,CAAA;AAC/C,EAAA,OAAO,OAAO,WAAW,CAAA;AAC3B;AAeO,SAAS,OAAA,GAAU;AACxB,EAAA,MAAM,EAAE,IAAA,EAAK,GAAI,UAAA,CAAW,iBAAiB,CAAA;AAC7C,EAAA,OAAO,IAAA;AACT;;;ACnDO,SAAS,GAAA,CAAI;AAAA,EAClB,UAAA;AAAA,EACA,WAAA;AAAA,EACA,KAAA,GAAQ,KAAA;AAAA,EACR,QAAA;AAAA,EACA,QAAA,GAAW;AACb,CAAA,EAAwB;AAEtB,EAAA,IAAI,eAAe,MAAA,EAAW;AAC5B,IAAA,MAAM,OAAA,GAAU,OAAO,UAAU,CAAA;AACjC,IAAA,OAAO,UAAU,QAAA,GAAW,QAAA;AAAA,EAC9B;AAGA,EAAA,IAAI,WAAA,KAAgB,MAAA,IAAa,WAAA,CAAY,MAAA,GAAS,CAAA,EAAG;AACvD,IAAA,MAAM,UAAU,KAAA,GAAQ,SAAA,CAAU,WAAW,CAAA,GAAI,UAAU,WAAW,CAAA;AACtE,IAAA,OAAO,UAAU,QAAA,GAAW,QAAA;AAAA,EAC9B;AAGA,EAAA,OAAO,QAAA;AACT;AA2BO,SAAS,MAAA,CAAO;AAAA,EACrB,UAAA;AAAA,EACA,WAAA;AAAA,EACA,KAAA,GAAQ,KAAA;AAAA,EACR;AACF,CAAA,EAA2B;AAEzB,EAAA,IAAI,eAAe,MAAA,EAAW;AAC5B,IAAA,MAAM,OAAA,GAAU,OAAO,UAAU,CAAA;AACjC,IAAA,OAAO,UAAU,IAAA,GAAO,QAAA;AAAA,EAC1B;AAGA,EAAA,IAAI,WAAA,KAAgB,MAAA,IAAa,WAAA,CAAY,MAAA,GAAS,CAAA,EAAG;AACvD,IAAA,MAAM,UAAU,KAAA,GAAQ,SAAA,CAAU,WAAW,CAAA,GAAI,UAAU,WAAW,CAAA;AACtE,IAAA,OAAO,UAAU,IAAA,GAAO,QAAA;AAAA,EAC1B;AAGA,EAAA,OAAO,QAAA;AACT","file":"index.mjs","sourcesContent":["/**\r\n * Secure Role Guard - React Context\r\n *\r\n * Framework-agnostic React context for permission management.\r\n * Works with Next.js, Remix, Gatsby, CRA, Vite, and any React framework.\r\n */\r\n\r\nimport { createContext } from \"react\";\r\nimport type { UserContext, RoleRegistry } from \"../core/types\";\r\n\r\n/**\r\n * Shape of the permission context value.\r\n */\r\nexport type PermissionContextValue = {\r\n  /** Current user context */\r\n  readonly user: UserContext | null;\r\n  /** Role registry for permission lookups */\r\n  readonly registry: RoleRegistry;\r\n  /** Check if user has a specific permission */\r\n  readonly can: (permission: string) => boolean;\r\n  /** Check if user has ALL permissions */\r\n  readonly canAll: (permissions: readonly string[]) => boolean;\r\n  /** Check if user has ANY permission */\r\n  readonly canAny: (permissions: readonly string[]) => boolean;\r\n};\r\n\r\n/**\r\n * Default context value (deny all).\r\n * Used when no provider is present.\r\n */\r\nconst defaultContextValue: PermissionContextValue = {\r\n  user: null,\r\n  registry: {\r\n    getPermissions: () => Object.freeze([]),\r\n    hasRole: () => false,\r\n    getRoleNames: () => Object.freeze([]),\r\n  },\r\n  can: () => false,\r\n  canAll: () => false,\r\n  canAny: () => false,\r\n};\r\n\r\n/**\r\n * React context for permissions.\r\n * Default value denies all permissions (deny by default).\r\n */\r\nexport const PermissionContext =\r\n  createContext<PermissionContextValue>(defaultContextValue);\r\n\r\n// Set display name for React DevTools\r\nPermissionContext.displayName = \"PermissionContext\";\r\n","/**\r\n * Secure Role Guard - Permission Engine\r\n *\r\n * Pure functions for permission checking.\r\n * Zero side effects, zero dependencies, zero mutations.\r\n */\r\n\r\nimport type { UserContext, RoleRegistry, PermissionCheckResult } from \"./types\";\r\n\r\n/** Wildcard permission that grants all access */\r\nconst WILDCARD_PERMISSION = \"*\";\r\n\r\n/**\r\n * Collects all permissions for a user from their roles and direct permissions.\r\n *\r\n * @param user - The user context\r\n * @param registry - The role registry to resolve role permissions\r\n * @returns Set of all permissions (for efficient lookup)\r\n */\r\nfunction collectUserPermissions(\r\n  user: UserContext,\r\n  registry: RoleRegistry\r\n): ReadonlySet<string> {\r\n  const permissions = new Set<string>();\r\n\r\n  // Add direct user permissions\r\n  if (user.permissions !== undefined) {\r\n    for (const permission of user.permissions) {\r\n      permissions.add(permission);\r\n    }\r\n  }\r\n\r\n  // Add permissions from all user roles\r\n  if (user.roles !== undefined) {\r\n    for (const role of user.roles) {\r\n      const rolePermissions = registry.getPermissions(role);\r\n      for (const permission of rolePermissions) {\r\n        permissions.add(permission);\r\n      }\r\n    }\r\n  }\r\n\r\n  return permissions;\r\n}\r\n\r\n/**\r\n * Checks if a permission set contains a wildcard that grants the requested permission.\r\n *\r\n * Supports:\r\n * - Exact wildcard (*) - grants everything\r\n * - Namespace wildcards (user.*) - grants all under namespace\r\n *\r\n * @param permissions - Set of permissions to check\r\n * @param requested - The permission being requested\r\n * @returns True if wildcard grants access\r\n */\r\nfunction hasWildcardAccess(\r\n  permissions: ReadonlySet<string>,\r\n  requested: string\r\n): boolean {\r\n  // Check for global wildcard\r\n  if (permissions.has(WILDCARD_PERMISSION)) {\r\n    return true;\r\n  }\r\n\r\n  // Check for namespace wildcards (e.g., user.* grants user.read)\r\n  const parts = requested.split(\".\");\r\n  let namespace = \"\";\r\n\r\n  for (let i = 0; i < parts.length - 1; i++) {\r\n    const part = parts[i];\r\n    if (part !== undefined) {\r\n      namespace = namespace === \"\" ? part : `${namespace}.${part}`;\r\n      if (permissions.has(`${namespace}.*`)) {\r\n        return true;\r\n      }\r\n    }\r\n  }\r\n\r\n  return false;\r\n}\r\n\r\n/**\r\n * Checks if a user has a specific permission.\r\n *\r\n * SECURITY GUARANTEES:\r\n * - Deny by default: undefined/null/empty always returns false\r\n * - Pure function: no side effects, no mutations\r\n * - Deterministic: same inputs always produce same output\r\n *\r\n * @param user - The user context to check\r\n * @param permission - The permission required\r\n * @param registry - The role registry for resolving roles\r\n * @returns True if user has the permission, false otherwise\r\n *\r\n * @example\r\n * const canEdit = canUser(currentUser, 'user.update', roleRegistry);\r\n */\r\nexport function canUser(\r\n  user: UserContext | null | undefined,\r\n  permission: string,\r\n  registry: RoleRegistry\r\n): boolean {\r\n  // DENY BY DEFAULT: No user context means no access\r\n  if (user === null || user === undefined) {\r\n    return false;\r\n  }\r\n\r\n  // DENY BY DEFAULT: Empty permission request is invalid\r\n  if (permission === \"\" || permission.trim() === \"\") {\r\n    return false;\r\n  }\r\n\r\n  const userPermissions = collectUserPermissions(user, registry);\r\n\r\n  // Check for exact permission match\r\n  if (userPermissions.has(permission)) {\r\n    return true;\r\n  }\r\n\r\n  // Check for wildcard access\r\n  if (hasWildcardAccess(userPermissions, permission)) {\r\n    return true;\r\n  }\r\n\r\n  // DENY BY DEFAULT\r\n  return false;\r\n}\r\n\r\n/**\r\n * Checks if a user has ALL of the specified permissions.\r\n *\r\n * @param user - The user context to check\r\n * @param permissions - Array of permissions required\r\n * @param registry - The role registry\r\n * @returns True if user has ALL permissions\r\n *\r\n * @example\r\n * const canManage = canUserAll(user, ['user.read', 'user.update'], registry);\r\n */\r\nexport function canUserAll(\r\n  user: UserContext | null | undefined,\r\n  permissions: readonly string[],\r\n  registry: RoleRegistry\r\n): boolean {\r\n  // DENY BY DEFAULT: Empty permissions array\r\n  if (permissions.length === 0) {\r\n    return false;\r\n  }\r\n\r\n  for (const permission of permissions) {\r\n    if (!canUser(user, permission, registry)) {\r\n      return false;\r\n    }\r\n  }\r\n\r\n  return true;\r\n}\r\n\r\n/**\r\n * Checks if a user has ANY of the specified permissions.\r\n *\r\n * @param user - The user context to check\r\n * @param permissions - Array of permissions to check\r\n * @param registry - The role registry\r\n * @returns True if user has at least one permission\r\n *\r\n * @example\r\n * const canView = canUserAny(user, ['report.view', 'report.admin'], registry);\r\n */\r\nexport function canUserAny(\r\n  user: UserContext | null | undefined,\r\n  permissions: readonly string[],\r\n  registry: RoleRegistry\r\n): boolean {\r\n  // DENY BY DEFAULT: Empty permissions array\r\n  if (permissions.length === 0) {\r\n    return false;\r\n  }\r\n\r\n  for (const permission of permissions) {\r\n    if (canUser(user, permission, registry)) {\r\n      return true;\r\n    }\r\n  }\r\n\r\n  return false;\r\n}\r\n\r\n/**\r\n * Extended permission check with detailed result.\r\n * Useful for debugging and logging.\r\n *\r\n * @param user - The user context\r\n * @param permission - Permission to check\r\n * @param registry - The role registry\r\n * @returns PermissionCheckResult with allowed status and reason\r\n */\r\nexport function checkPermission(\r\n  user: UserContext | null | undefined,\r\n  permission: string,\r\n  registry: RoleRegistry\r\n): PermissionCheckResult {\r\n  if (user === null || user === undefined) {\r\n    return Object.freeze({\r\n      allowed: false,\r\n      reason: \"No user context provided\",\r\n    });\r\n  }\r\n\r\n  if (permission === \"\" || permission.trim() === \"\") {\r\n    return Object.freeze({\r\n      allowed: false,\r\n      reason: \"Empty permission requested\",\r\n    });\r\n  }\r\n\r\n  const allowed = canUser(user, permission, registry);\r\n\r\n  return Object.freeze({\r\n    allowed,\r\n    reason: allowed\r\n      ? `Permission \"${permission}\" granted`\r\n      : `Permission \"${permission}\" denied`,\r\n  });\r\n}\r\n","/**\r\n * Secure Role Guard - React Provider\r\n *\r\n * Main provider component for permission management.\r\n * Framework-agnostic: works with Next.js, Remix, Gatsby, CRA, Vite.\r\n */\r\n\r\nimport { useMemo, type ReactNode } from \"react\";\r\nimport type { UserContext, RoleRegistry } from \"../core/types\";\r\nimport { canUser, canUserAll, canUserAny } from \"../core/permission-engine\";\r\nimport { PermissionContext, type PermissionContextValue } from \"./context\";\r\n\r\n/**\r\n * Props for the PermissionProvider component.\r\n */\r\nexport type PermissionProviderProps = {\r\n  /** Current user context (from your auth system) */\r\n  readonly user: UserContext | null;\r\n  /** Role registry created by defineRoles() */\r\n  readonly registry: RoleRegistry;\r\n  /** Child components */\r\n  readonly children: ReactNode;\r\n};\r\n\r\n/**\r\n * Provides permission context to all child components.\r\n *\r\n * SECURITY: If user is null/undefined, all permission checks will deny by default.\r\n *\r\n * @example\r\n * ```tsx\r\n * import { defineRoles, PermissionProvider } from 'secure-role-guard';\r\n *\r\n * const roleRegistry = defineRoles({\r\n *   admin: ['user.read', 'user.update'],\r\n *   viewer: ['user.read']\r\n * });\r\n *\r\n * function App() {\r\n *   const user = { roles: ['admin'] }; // From your auth system\r\n *\r\n *   return (\r\n *     <PermissionProvider user={user} registry={roleRegistry}>\r\n *       <YourApp />\r\n *     </PermissionProvider>\r\n *   );\r\n * }\r\n * ```\r\n */\r\nexport function PermissionProvider({\r\n  user,\r\n  registry,\r\n  children,\r\n}: PermissionProviderProps): ReactNode {\r\n  // Memoize context value to prevent unnecessary re-renders\r\n  const contextValue = useMemo<PermissionContextValue>(\r\n    () => ({\r\n      user,\r\n      registry,\r\n      can: (permission: string) => canUser(user, permission, registry),\r\n      canAll: (permissions: readonly string[]) =>\r\n        canUserAll(user, permissions, registry),\r\n      canAny: (permissions: readonly string[]) =>\r\n        canUserAny(user, permissions, registry),\r\n    }),\r\n    [user, registry]\r\n  );\r\n\r\n  return (\r\n    <PermissionContext.Provider value={contextValue}>\r\n      {children}\r\n    </PermissionContext.Provider>\r\n  );\r\n}\r\n","/**\r\n * Secure Role Guard - React Hooks\r\n *\r\n * Hooks for permission checking in React components.\r\n * Framework-agnostic: works with any React framework.\r\n */\r\n\r\nimport { useContext } from \"react\";\r\nimport { PermissionContext, type PermissionContextValue } from \"./context\";\r\n\r\n/**\r\n * Hook to access the full permission context.\r\n *\r\n * @returns Full PermissionContextValue\r\n *\r\n * @example\r\n * ```tsx\r\n * function UserProfile() {\r\n *   const { user, can, canAll } = usePermissions();\r\n *\r\n *   if (can('user.read')) {\r\n *     return <UserDetails />;\r\n *   }\r\n *   return <AccessDenied />;\r\n * }\r\n * ```\r\n */\r\nexport function usePermissions(): PermissionContextValue {\r\n  return useContext(PermissionContext);\r\n}\r\n\r\n/**\r\n * Hook to check a single permission.\r\n *\r\n * @param permission - The permission to check\r\n * @returns True if user has the permission\r\n *\r\n * @example\r\n * ```tsx\r\n * function EditButton() {\r\n *   const canEdit = useCan('user.update');\r\n *\r\n *   if (!canEdit) return null;\r\n *   return <button>Edit User</button>;\r\n * }\r\n * ```\r\n */\r\nexport function useCan(permission: string): boolean {\r\n  const { can } = useContext(PermissionContext);\r\n  return can(permission);\r\n}\r\n\r\n/**\r\n * Hook to check if user has ALL specified permissions.\r\n *\r\n * @param permissions - Array of permissions to check\r\n * @returns True if user has all permissions\r\n *\r\n * @example\r\n * ```tsx\r\n * function AdminPanel() {\r\n *   const canManage = useCanAll(['user.read', 'user.update', 'user.delete']);\r\n *\r\n *   if (!canManage) return <AccessDenied />;\r\n *   return <AdminDashboard />;\r\n * }\r\n * ```\r\n */\r\nexport function useCanAll(permissions: readonly string[]): boolean {\r\n  const { canAll } = useContext(PermissionContext);\r\n  return canAll(permissions);\r\n}\r\n\r\n/**\r\n * Hook to check if user has ANY of the specified permissions.\r\n *\r\n * @param permissions - Array of permissions to check\r\n * @returns True if user has at least one permission\r\n *\r\n * @example\r\n * ```tsx\r\n * function ViewReports() {\r\n *   const canView = useCanAny(['report.admin', 'report.viewer']);\r\n *\r\n *   if (!canView) return null;\r\n *   return <ReportList />;\r\n * }\r\n * ```\r\n */\r\nexport function useCanAny(permissions: readonly string[]): boolean {\r\n  const { canAny } = useContext(PermissionContext);\r\n  return canAny(permissions);\r\n}\r\n\r\n/**\r\n * Hook to get current user context.\r\n *\r\n * @returns Current UserContext or null\r\n *\r\n * @example\r\n * ```tsx\r\n * function UserInfo() {\r\n *   const user = useUser();\r\n *   return <span>User ID: {user?.userId ?? 'Anonymous'}</span>;\r\n * }\r\n * ```\r\n */\r\nexport function useUser() {\r\n  const { user } = useContext(PermissionContext);\r\n  return user;\r\n}\r\n","/**\r\n * Secure Role Guard - React Components\r\n *\r\n * Declarative components for conditional rendering based on permissions.\r\n * Framework-agnostic: works with any React framework.\r\n */\r\n\r\nimport type { ReactNode } from \"react\";\r\nimport { useCan, useCanAll, useCanAny } from \"./hooks\";\r\n\r\n/**\r\n * Props for the Can component.\r\n */\r\nexport type CanProps = {\r\n  /** Single permission to check */\r\n  readonly permission?: string;\r\n  /** Multiple permissions - user must have ALL (default behavior) */\r\n  readonly permissions?: readonly string[];\r\n  /** If true, user needs only ANY of the permissions */\r\n  readonly anyOf?: boolean;\r\n  /** Content to render if permission granted */\r\n  readonly children: ReactNode;\r\n  /** Optional fallback content if permission denied */\r\n  readonly fallback?: ReactNode;\r\n};\r\n\r\n/**\r\n * Conditionally renders children based on user permissions.\r\n *\r\n * SECURITY: If no permission matches, nothing is rendered (deny by default).\r\n *\r\n * @example Single permission\r\n * ```tsx\r\n * <Can permission=\"user.update\">\r\n *   <EditButton />\r\n * </Can>\r\n * ```\r\n *\r\n * @example Multiple permissions (ALL required)\r\n * ```tsx\r\n * <Can permissions={['user.read', 'user.update']}>\r\n *   <UserEditor />\r\n * </Can>\r\n * ```\r\n *\r\n * @example Multiple permissions (ANY required)\r\n * ```tsx\r\n * <Can permissions={['admin', 'moderator']} anyOf>\r\n *   <ModPanel />\r\n * </Can>\r\n * ```\r\n *\r\n * @example With fallback\r\n * ```tsx\r\n * <Can permission=\"premium.access\" fallback={<UpgradePrompt />}>\r\n *   <PremiumContent />\r\n * </Can>\r\n * ```\r\n */\r\nexport function Can({\r\n  permission,\r\n  permissions,\r\n  anyOf = false,\r\n  children,\r\n  fallback = null,\r\n}: CanProps): ReactNode {\r\n  // Single permission check\r\n  if (permission !== undefined) {\r\n    const allowed = useCan(permission);\r\n    return allowed ? children : fallback;\r\n  }\r\n\r\n  // Multiple permissions check\r\n  if (permissions !== undefined && permissions.length > 0) {\r\n    const allowed = anyOf ? useCanAny(permissions) : useCanAll(permissions);\r\n    return allowed ? children : fallback;\r\n  }\r\n\r\n  // No permissions specified - deny by default\r\n  return fallback;\r\n}\r\n\r\n/**\r\n * Props for the Cannot component.\r\n */\r\nexport type CannotProps = {\r\n  /** Single permission to check */\r\n  readonly permission?: string;\r\n  /** Multiple permissions to check */\r\n  readonly permissions?: readonly string[];\r\n  /** If true, blocked when user has ANY permission */\r\n  readonly anyOf?: boolean;\r\n  /** Content to render if permission is NOT granted */\r\n  readonly children: ReactNode;\r\n};\r\n\r\n/**\r\n * Inverse of Can - renders children when user does NOT have the permission.\r\n * Useful for showing upgrade prompts, locked features, etc.\r\n *\r\n * @example\r\n * ```tsx\r\n * <Cannot permission=\"premium.access\">\r\n *   <UpgradePrompt />\r\n * </Cannot>\r\n * ```\r\n */\r\nexport function Cannot({\r\n  permission,\r\n  permissions,\r\n  anyOf = false,\r\n  children,\r\n}: CannotProps): ReactNode {\r\n  // Single permission check\r\n  if (permission !== undefined) {\r\n    const allowed = useCan(permission);\r\n    return allowed ? null : children;\r\n  }\r\n\r\n  // Multiple permissions check\r\n  if (permissions !== undefined && permissions.length > 0) {\r\n    const allowed = anyOf ? useCanAny(permissions) : useCanAll(permissions);\r\n    return allowed ? null : children;\r\n  }\r\n\r\n  // No permissions specified - show children (inverse of deny by default)\r\n  return children;\r\n}\r\n"]}