secure-role-guard 1.0.0

package/dist/core/index.d.ts

@@ -0,0 +1,100 @@
+import { R as RoleDefinition, a as RoleRegistry, U as UserContext, b as PermissionCheckResult } from '../types-CSUpaGsY.js';
+export { c as PermissionCheckOptions, P as PermissionEngineConfig } from '../types-CSUpaGsY.js';
+
+/**
+ * Secure Role Guard - Role Registry
+ *
+ * Creates an immutable registry of role definitions.
+ * Pure functions only, zero side effects.
+ */
+
+/**
+ * Creates an immutable role registry from role definitions.
+ *
+ * Security guarantees:
+ * - Returns a frozen, immutable object
+ * - No mutations possible after creation
+ * - Unknown roles return empty permissions (deny by default)
+ *
+ * @param definitions - Object mapping role names to permission arrays
+ * @returns Frozen RoleRegistry object
+ *
+ * @example
+ * const registry = defineRoles({
+ *   superadmin: ['*'],
+ *   admin: ['user.read', 'user.update'],
+ *   support: ['ticket.read', 'ticket.reply']
+ * });
+ *
+ * registry.getPermissions('admin'); // ['user.read', 'user.update']
+ * registry.getPermissions('unknown'); // []
+ */
+declare function defineRoles(definitions: RoleDefinition): RoleRegistry;
+/**
+ * Creates an empty role registry.
+ * Useful for testing or when no roles are defined.
+ *
+ * @returns Empty frozen RoleRegistry
+ */
+declare function createEmptyRegistry(): RoleRegistry;
+
+/**
+ * Secure Role Guard - Permission Engine
+ *
+ * Pure functions for permission checking.
+ * Zero side effects, zero dependencies, zero mutations.
+ */
+
+/**
+ * Checks if a user has a specific permission.
+ *
+ * SECURITY GUARANTEES:
+ * - Deny by default: undefined/null/empty always returns false
+ * - Pure function: no side effects, no mutations
+ * - Deterministic: same inputs always produce same output
+ *
+ * @param user - The user context to check
+ * @param permission - The permission required
+ * @param registry - The role registry for resolving roles
+ * @returns True if user has the permission, false otherwise
+ *
+ * @example
+ * const canEdit = canUser(currentUser, 'user.update', roleRegistry);
+ */
+declare function canUser(user: UserContext | null | undefined, permission: string, registry: RoleRegistry): boolean;
+/**
+ * Checks if a user has ALL of the specified permissions.
+ *
+ * @param user - The user context to check
+ * @param permissions - Array of permissions required
+ * @param registry - The role registry
+ * @returns True if user has ALL permissions
+ *
+ * @example
+ * const canManage = canUserAll(user, ['user.read', 'user.update'], registry);
+ */
+declare function canUserAll(user: UserContext | null | undefined, permissions: readonly string[], registry: RoleRegistry): boolean;
+/**
+ * Checks if a user has ANY of the specified permissions.
+ *
+ * @param user - The user context to check
+ * @param permissions - Array of permissions to check
+ * @param registry - The role registry
+ * @returns True if user has at least one permission
+ *
+ * @example
+ * const canView = canUserAny(user, ['report.view', 'report.admin'], registry);
+ */
+declare function canUserAny(user: UserContext | null | undefined, permissions: readonly string[], registry: RoleRegistry): boolean;
+/**
+ * Extended permission check with detailed result.
+ * Useful for debugging and logging.
+ *
+ * @param user - The user context
+ * @param permission - Permission to check
+ * @param registry - The role registry
+ * @returns PermissionCheckResult with allowed status and reason
+ */
+declare function checkPermission(user: UserContext | null | undefined, permission: string, registry: RoleRegistry): PermissionCheckResult;
+
+export { PermissionCheckResult, RoleDefinition, RoleRegistry, UserContext, canUser, canUserAll, canUserAny, checkPermission, createEmptyRegistry, defineRoles };

package/dist/core/index.js

@@ -0,0 +1,132 @@
+'use strict';
+
+// src/core/role-registry.ts
+function defineRoles(definitions) {
+  const frozenDefinitions = {};
+  for (const role of Object.keys(definitions)) {
+    const permissions = definitions[role];
+    if (permissions !== void 0) {
+      frozenDefinitions[role] = Object.freeze([...permissions]);
+    }
+  }
+  Object.freeze(frozenDefinitions);
+  const registry = {
+    getPermissions(role) {
+      const permissions = frozenDefinitions[role];
+      return permissions !== void 0 ? permissions : Object.freeze([]);
+    },
+    hasRole(role) {
+      return Object.prototype.hasOwnProperty.call(frozenDefinitions, role);
+    },
+    getRoleNames() {
+      return Object.freeze(Object.keys(frozenDefinitions));
+    }
+  };
+  return Object.freeze(registry);
+}
+function createEmptyRegistry() {
+  return defineRoles({});
+}
+
+// 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 checkPermission(user, permission, registry) {
+  if (user === null || user === void 0) {
+    return Object.freeze({
+      allowed: false,
+      reason: "No user context provided"
+    });
+  }
+  if (permission === "" || permission.trim() === "") {
+    return Object.freeze({
+      allowed: false,
+      reason: "Empty permission requested"
+    });
+  }
+  const allowed = canUser(user, permission, registry);
+  return Object.freeze({
+    allowed,
+    reason: allowed ? `Permission "${permission}" granted` : `Permission "${permission}" denied`
+  });
+}
+
+exports.canUser = canUser;
+exports.canUserAll = canUserAll;
+exports.canUserAny = canUserAny;
+exports.checkPermission = checkPermission;
+exports.createEmptyRegistry = createEmptyRegistry;
+exports.defineRoles = defineRoles;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/core/role-registry.ts","../../src/core/permission-engine.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\r\n * Secure Role Guard - Role Registry\r\n *\r\n * Creates an immutable registry of role definitions.\r\n * Pure functions only, zero side effects.\r\n */\r\n\r\nimport type { RoleDefinition, RoleRegistry } from \"./types\";\r\n\r\n/**\r\n * Creates an immutable role registry from role definitions.\r\n *\r\n * Security guarantees:\r\n * - Returns a frozen, immutable object\r\n * - No mutations possible after creation\r\n * - Unknown roles return empty permissions (deny by default)\r\n *\r\n * @param definitions - Object mapping role names to permission arrays\r\n * @returns Frozen RoleRegistry object\r\n *\r\n * @example\r\n * const registry = defineRoles({\r\n *   superadmin: ['*'],\r\n *   admin: ['user.read', 'user.update'],\r\n *   support: ['ticket.read', 'ticket.reply']\r\n * });\r\n *\r\n * registry.getPermissions('admin'); // ['user.read', 'user.update']\r\n * registry.getPermissions('unknown'); // []\r\n */\r\nexport function defineRoles(definitions: RoleDefinition): RoleRegistry {\r\n  // Create a deep-frozen copy to prevent external mutations\r\n  const frozenDefinitions: Record<string, readonly string[]> = {};\r\n\r\n  for (const role of Object.keys(definitions)) {\r\n    const permissions = definitions[role];\r\n    if (permissions !== undefined) {\r\n      // Freeze the permissions array\r\n      frozenDefinitions[role] = Object.freeze([...permissions]);\r\n    }\r\n  }\r\n\r\n  // Freeze the definitions object itself\r\n  Object.freeze(frozenDefinitions);\r\n\r\n  const registry: RoleRegistry = {\r\n    getPermissions(role: string): readonly string[] {\r\n      const permissions = frozenDefinitions[role];\r\n      // Deny by default: unknown roles get empty permissions\r\n      return permissions !== undefined ? permissions : Object.freeze([]);\r\n    },\r\n\r\n    hasRole(role: string): boolean {\r\n      return Object.prototype.hasOwnProperty.call(frozenDefinitions, role);\r\n    },\r\n\r\n    getRoleNames(): readonly string[] {\r\n      return Object.freeze(Object.keys(frozenDefinitions));\r\n    },\r\n  };\r\n\r\n  // Freeze the registry object to prevent modifications\r\n  return Object.freeze(registry);\r\n}\r\n\r\n/**\r\n * Creates an empty role registry.\r\n * Useful for testing or when no roles are defined.\r\n *\r\n * @returns Empty frozen RoleRegistry\r\n */\r\nexport function createEmptyRegistry(): RoleRegistry {\r\n  return defineRoles({});\r\n}\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"]}

package/dist/core/index.mjs

@@ -0,0 +1,125 @@
+// src/core/role-registry.ts
+function defineRoles(definitions) {
+  const frozenDefinitions = {};
+  for (const role of Object.keys(definitions)) {
+    const permissions = definitions[role];
+    if (permissions !== void 0) {
+      frozenDefinitions[role] = Object.freeze([...permissions]);
+    }
+  }
+  Object.freeze(frozenDefinitions);
+  const registry = {
+    getPermissions(role) {
+      const permissions = frozenDefinitions[role];
+      return permissions !== void 0 ? permissions : Object.freeze([]);
+    },
+    hasRole(role) {
+      return Object.prototype.hasOwnProperty.call(frozenDefinitions, role);
+    },
+    getRoleNames() {
+      return Object.freeze(Object.keys(frozenDefinitions));
+    }
+  };
+  return Object.freeze(registry);
+}
+function createEmptyRegistry() {
+  return defineRoles({});
+}
+
+// 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 checkPermission(user, permission, registry) {
+  if (user === null || user === void 0) {
+    return Object.freeze({
+      allowed: false,
+      reason: "No user context provided"
+    });
+  }
+  if (permission === "" || permission.trim() === "") {
+    return Object.freeze({
+      allowed: false,
+      reason: "Empty permission requested"
+    });
+  }
+  const allowed = canUser(user, permission, registry);
+  return Object.freeze({
+    allowed,
+    reason: allowed ? `Permission "${permission}" granted` : `Permission "${permission}" denied`
+  });
+}
+
+export { canUser, canUserAll, canUserAny, checkPermission, createEmptyRegistry, defineRoles };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/core/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/core/role-registry.ts","../../src/core/permission-engine.ts"],"names":[],"mappings":"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","file":"index.mjs","sourcesContent":["/**\r\n * Secure Role Guard - Role Registry\r\n *\r\n * Creates an immutable registry of role definitions.\r\n * Pure functions only, zero side effects.\r\n */\r\n\r\nimport type { RoleDefinition, RoleRegistry } from \"./types\";\r\n\r\n/**\r\n * Creates an immutable role registry from role definitions.\r\n *\r\n * Security guarantees:\r\n * - Returns a frozen, immutable object\r\n * - No mutations possible after creation\r\n * - Unknown roles return empty permissions (deny by default)\r\n *\r\n * @param definitions - Object mapping role names to permission arrays\r\n * @returns Frozen RoleRegistry object\r\n *\r\n * @example\r\n * const registry = defineRoles({\r\n *   superadmin: ['*'],\r\n *   admin: ['user.read', 'user.update'],\r\n *   support: ['ticket.read', 'ticket.reply']\r\n * });\r\n *\r\n * registry.getPermissions('admin'); // ['user.read', 'user.update']\r\n * registry.getPermissions('unknown'); // []\r\n */\r\nexport function defineRoles(definitions: RoleDefinition): RoleRegistry {\r\n  // Create a deep-frozen copy to prevent external mutations\r\n  const frozenDefinitions: Record<string, readonly string[]> = {};\r\n\r\n  for (const role of Object.keys(definitions)) {\r\n    const permissions = definitions[role];\r\n    if (permissions !== undefined) {\r\n      // Freeze the permissions array\r\n      frozenDefinitions[role] = Object.freeze([...permissions]);\r\n    }\r\n  }\r\n\r\n  // Freeze the definitions object itself\r\n  Object.freeze(frozenDefinitions);\r\n\r\n  const registry: RoleRegistry = {\r\n    getPermissions(role: string): readonly string[] {\r\n      const permissions = frozenDefinitions[role];\r\n      // Deny by default: unknown roles get empty permissions\r\n      return permissions !== undefined ? permissions : Object.freeze([]);\r\n    },\r\n\r\n    hasRole(role: string): boolean {\r\n      return Object.prototype.hasOwnProperty.call(frozenDefinitions, role);\r\n    },\r\n\r\n    getRoleNames(): readonly string[] {\r\n      return Object.freeze(Object.keys(frozenDefinitions));\r\n    },\r\n  };\r\n\r\n  // Freeze the registry object to prevent modifications\r\n  return Object.freeze(registry);\r\n}\r\n\r\n/**\r\n * Creates an empty role registry.\r\n * Useful for testing or when no roles are defined.\r\n *\r\n * @returns Empty frozen RoleRegistry\r\n */\r\nexport function createEmptyRegistry(): RoleRegistry {\r\n  return defineRoles({});\r\n}\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"]}

package/dist/index.d.mts

@@ -0,0 +1,4 @@
+export { c as PermissionCheckOptions, b as PermissionCheckResult, P as PermissionEngineConfig, R as RoleDefinition, a as RoleRegistry, U as UserContext } from './types-CSUpaGsY.mjs';
+export { canUser, canUserAll, canUserAny, checkPermission, createEmptyRegistry, defineRoles } from './core/index.mjs';
+export { Can, CanProps, Cannot, CannotProps, PermissionContext, PermissionContextValue, PermissionProvider, PermissionProviderProps, useCan, useCanAll, useCanAny, usePermissions, useUser } from './react/index.mjs';
+import 'react';

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { c as PermissionCheckOptions, b as PermissionCheckResult, P as PermissionEngineConfig, R as RoleDefinition, a as RoleRegistry, U as UserContext } from './types-CSUpaGsY.js';
+export { canUser, canUserAll, canUserAny, checkPermission, createEmptyRegistry, defineRoles } from './core/index.js';
+export { Can, CanProps, Cannot, CannotProps, PermissionContext, PermissionContextValue, PermissionProvider, PermissionProviderProps, useCan, useCanAll, useCanAny, usePermissions, useUser } from './react/index.js';
+import 'react';

package/dist/index.js

@@ -0,0 +1,238 @@
+'use strict';
+
+var react = require('react');
+var jsxRuntime = require('react/jsx-runtime');
+
+// src/core/role-registry.ts
+function defineRoles(definitions) {
+  const frozenDefinitions = {};
+  for (const role of Object.keys(definitions)) {
+    const permissions = definitions[role];
+    if (permissions !== void 0) {
+      frozenDefinitions[role] = Object.freeze([...permissions]);
+    }
+  }
+  Object.freeze(frozenDefinitions);
+  const registry = {
+    getPermissions(role) {
+      const permissions = frozenDefinitions[role];
+      return permissions !== void 0 ? permissions : Object.freeze([]);
+    },
+    hasRole(role) {
+      return Object.prototype.hasOwnProperty.call(frozenDefinitions, role);
+    },
+    getRoleNames() {
+      return Object.freeze(Object.keys(frozenDefinitions));
+    }
+  };
+  return Object.freeze(registry);
+}
+function createEmptyRegistry() {
+  return defineRoles({});
+}
+
+// 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 checkPermission(user, permission, registry) {
+  if (user === null || user === void 0) {
+    return Object.freeze({
+      allowed: false,
+      reason: "No user context provided"
+    });
+  }
+  if (permission === "" || permission.trim() === "") {
+    return Object.freeze({
+      allowed: false,
+      reason: "Empty permission requested"
+    });
+  }
+  const allowed = canUser(user, permission, registry);
+  return Object.freeze({
+    allowed,
+    reason: allowed ? `Permission "${permission}" granted` : `Permission "${permission}" denied`
+  });
+}
+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";
+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;
+}
+/**
+ * Secure Role Guard
+ *
+ * Zero-vulnerability, framework-agnostic RBAC authorization library.
+ * Works with React, Next.js, Remix, Gatsby, and any React framework.
+ *
+ * @author Sohel Rahaman
+ * @license MIT
+ * @see https://github.com/sohelrahaman/secure-role-guard
+ */
+
+exports.Can = Can;
+exports.Cannot = Cannot;
+exports.PermissionContext = PermissionContext;
+exports.PermissionProvider = PermissionProvider;
+exports.canUser = canUser;
+exports.canUserAll = canUserAll;
+exports.canUserAny = canUserAny;
+exports.checkPermission = checkPermission;
+exports.createEmptyRegistry = createEmptyRegistry;
+exports.defineRoles = defineRoles;
+exports.useCan = useCan;
+exports.useCanAll = useCanAll;
+exports.useCanAny = useCanAny;
+exports.usePermissions = usePermissions;
+exports.useUser = useUser;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map