@ahmed109/gatekeeper-core 0.2.0 → 0.3.0

package/dist/index.cjs

@@ -25,15 +25,19 @@ __export(index_exports, {
   canAll: () => canAll,
   canAny: () => canAny,
   createSubject: () => createSubject,
+  defineRoleHierarchy: () => defineRoleHierarchy,
   defineRolePermissions: () => defineRolePermissions,
   evaluatePermission: () => evaluatePermission,
+  explain: () => explain,
   fromJwtClaims: () => fromJwtClaims,
   fromPermissions: () => fromPermissions,
   fromRoles: () => fromRoles,
   getUserEffectivePermissions: () => getUserEffectivePermissions,
   isFeatureEnabled: () => isFeatureEnabled,
   normalizeFeatureFlags: () => normalizeFeatureFlags,
-  parseEvaluateOptions: () => parseEvaluateOptions
+  parseEvaluateOptions: () => parseEvaluateOptions,
+  permissionMatches: () => permissionMatches,
+  resolveInheritedRoles: () => resolveInheritedRoles
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -55,13 +59,28 @@ function defineRolePermissions(customMap, baseMap = DEFAULT_ROLE_PERMISSIONS) {
   }
   return merged;
 }
+function defineRoleHierarchy(hierarchy) {
+  return Object.fromEntries(
+    Object.entries(hierarchy).map(([role, parents]) => [role, [...parents]])
+  );
+}
+function resolveInheritedRoles(roles, hierarchy) {
+  const resolved = /* @__PURE__ */ new Set();
+  const visit = (role) => {
+    if (resolved.has(role)) return;
+    resolved.add(role);
+    for (const parent of hierarchy?.[role] ?? []) visit(parent);
+  };
+  for (const role of roles) visit(role);
+  return [...resolved];
+}
 
 // src/evaluator.ts
 function parseEvaluateOptions(options) {
   if (!options || typeof options !== "object") {
     return {};
   }
-  if ("roleMap" in options || "context" in options || "policy" in options) {
+  if ("roleMap" in options || "roleHierarchy" in options || "context" in options || "policy" in options) {
     return options;
   }
   const values = Object.values(options);
@@ -86,7 +105,7 @@ function getUserEffectivePermissions(subject, roleMapOrOptions) {
   if (subject.role) {
     rolesToEvaluate.add(subject.role);
   }
-  for (const role of rolesToEvaluate) {
+  for (const role of resolveInheritedRoles(rolesToEvaluate, opts.roleHierarchy)) {
     const rolePerms = roleMap[role];
     if (rolePerms && Array.isArray(rolePerms)) {
       for (const perm of rolePerms) {
@@ -101,6 +120,9 @@ function getUserEffectivePermissions(subject, roleMapOrOptions) {
   }
   return permissions;
 }
+function permissionMatches(granted, requested) {
+  return granted === requested || granted.endsWith(".*") && requested.startsWith(granted.slice(0, -1));
+}
 function can(subject, permission, options) {
   if (!subject || !permission) {
     return false;
@@ -113,7 +135,7 @@ function can(subject, permission, options) {
     }
   }
   const effective = getUserEffectivePermissions(subject, options !== void 0 ? opts : void 0);
-  return effective.has(permission);
+  return [...effective].some((granted) => permissionMatches(granted, permission));
 }
 function canAll(subject, permissions, options) {
   if (!subject || !permissions.length) {
@@ -147,20 +169,33 @@ function evaluatePermission(subject, permission, options) {
     }
   }
   const effective = getUserEffectivePermissions(subject, options !== void 0 ? opts : void 0);
-  const allowed = effective.has(permission);
+  const matchedPermission = [...effective].find((granted) => permissionMatches(granted, permission));
+  const allowed = matchedPermission !== void 0;
   if (allowed) {
     return {
       allowed: true,
-      reason: "Permission granted."
+      reason: "Permission granted.",
+      matchedPermission,
+      source: subject.permissions?.includes(matchedPermission) ? "direct-permission" : "role-permission",
+      evaluatedRoles: resolveInheritedRoles(
+        [...subject.roles ?? [], ...subject.role ? [subject.role] : []],
+        opts.roleHierarchy
+      )
     };
   }
   const roleDesc = subject.role ?? (subject.roles?.length ? subject.roles.join(", ") : "none");
   return {
     allowed: false,
     reason: `User with role '${roleDesc}' lacks required permission '${permission}'.`,
-    missingPermissions: [permission]
+    missingPermissions: [permission],
+    source: "none",
+    evaluatedRoles: resolveInheritedRoles(
+      [...subject.roles ?? [], ...subject.role ? [subject.role] : []],
+      opts.roleHierarchy
+    )
   };
 }
+var explain = evaluatePermission;
 function normalizeFeatureFlags(flags) {
   if (!flags) {
     return {};
@@ -366,13 +401,17 @@ function createSubject(source, mapping) {
   canAll,
   canAny,
   createSubject,
+  defineRoleHierarchy,
   defineRolePermissions,
   evaluatePermission,
+  explain,
   fromJwtClaims,
   fromPermissions,
   fromRoles,
   getUserEffectivePermissions,
   isFeatureEnabled,
   normalizeFeatureFlags,
-  parseEvaluateOptions
+  parseEvaluateOptions,
+  permissionMatches,
+  resolveInheritedRoles
 });

package/dist/index.d.cts

@@ -45,6 +45,8 @@ type AuthorizationPolicy = (subject: AuthorizationSubject, permission: Permissio
  */
 interface EvaluateOptions {
     roleMap?: RolePermissionsMap;
+    /** A role can inherit permissions from one or more parent roles. */
+    roleHierarchy?: RoleHierarchy;
     context?: Record<string, unknown>;
     policy?: AuthorizationPolicy;
 }
@@ -65,11 +67,18 @@ interface AuthorizationResult {
     allowed: boolean;
     reason?: string;
     missingPermissions?: Permission[];
+    /** Roles considered after resolving inheritance. */
+    evaluatedRoles?: Role[];
+    /** How the decision was reached. */
+    source?: 'policy' | 'direct-permission' | 'role-permission' | 'none';
+    matchedPermission?: Permission;
 }
 /**
  * Mapping from roles to their granted permissions.
  */
 type RolePermissionsMap = Record<Role, readonly Permission[] | Permission[]>;
+/** Maps a role to the roles whose permissions it inherits. */
+type RoleHierarchy = Record<Role, readonly Role[] | Role[]>;
 
 /**
  * Default role-to-permissions map for Gatekeeper.
@@ -83,6 +92,10 @@ declare const DEFAULT_ROLE_PERMISSIONS: RolePermissionsMap;
  * Creates a merged role-to-permissions map by extending or overriding the defaults.
  */
 declare function defineRolePermissions(customMap?: Partial<RolePermissionsMap>, baseMap?: RolePermissionsMap): RolePermissionsMap;
+/** Creates a defensive copy of role inheritance declarations. */
+declare function defineRoleHierarchy(hierarchy: RoleHierarchy): RoleHierarchy;
+/** Resolves all inherited roles safely, including cyclic declarations. */
+declare function resolveInheritedRoles(roles: Iterable<Role>, hierarchy?: RoleHierarchy): Role[];
 
 /**
  * Normalizes either a legacy RolePermissionsMap or a modern EvaluateOptions object.
@@ -97,6 +110,8 @@ declare function parseEvaluateOptions(options?: RoleMapOrOptions): EvaluateOptio
  * Deduplicates permissions and denies safely if no roles or permissions exist.
  */
 declare function getUserEffectivePermissions(subject: AuthorizationSubject | null | undefined, roleMapOrOptions?: RoleMapOrOptions): Set<Permission>;
+/** Supports exact permissions and namespace wildcards such as `billing.*`. */
+declare function permissionMatches(granted: Permission, requested: Permission): boolean;
 /**
  * Evaluates whether a subject has a specific permission.
  * Supports scoped policy checks and legacy roleMap options.
@@ -119,6 +134,8 @@ declare function canAny(subject: AuthorizationSubject | null | undefined, permis
  * Evaluates access with detailed diagnostic reasons.
  */
 declare function evaluatePermission(subject: AuthorizationSubject | null | undefined, permission: Permission, options?: RoleMapOrOptions): AuthorizationResult;
+/** Alias for evaluatePermission, optimized for audit/debug UI naming. */
+declare const explain: typeof evaluatePermission;
 /**
  * Normalizes feature flag inputs (either an array of FeatureFlag or a record of boolean flags)
  * into a standard Record<string, boolean>.
@@ -239,4 +256,4 @@ interface SubjectMappingConfig<TSource> {
  */
 declare function createSubject<TSource>(source: TSource, mapping: SubjectMappingConfig<TSource> | ((source: TSource) => AuthorizationSubject)): AuthorizationSubject;
 
-export { type AuthorizationPolicy, type AuthorizationResult, type AuthorizationSubject, DEFAULT_ROLE_PERMISSIONS, type EvaluateOptions, type FeatureFlag, type FromPermissionsInput, type FromRolesInput, type GatekeeperUser, type JwtClaimsOptions, type Permission, type Role, type RoleMapOrOptions, type RolePermissionsMap, type StandardPermission, type StandardRole, type SubjectMappingConfig, can, canAll, canAny, createSubject, defineRolePermissions, evaluatePermission, fromJwtClaims, fromPermissions, fromRoles, getUserEffectivePermissions, isFeatureEnabled, normalizeFeatureFlags, parseEvaluateOptions };
+export { type AuthorizationPolicy, type AuthorizationResult, type AuthorizationSubject, DEFAULT_ROLE_PERMISSIONS, type EvaluateOptions, type FeatureFlag, type FromPermissionsInput, type FromRolesInput, type GatekeeperUser, type JwtClaimsOptions, type Permission, type Role, type RoleHierarchy, type RoleMapOrOptions, type RolePermissionsMap, type StandardPermission, type StandardRole, type SubjectMappingConfig, can, canAll, canAny, createSubject, defineRoleHierarchy, defineRolePermissions, evaluatePermission, explain, fromJwtClaims, fromPermissions, fromRoles, getUserEffectivePermissions, isFeatureEnabled, normalizeFeatureFlags, parseEvaluateOptions, permissionMatches, resolveInheritedRoles };

package/dist/index.d.ts

@@ -45,6 +45,8 @@ type AuthorizationPolicy = (subject: AuthorizationSubject, permission: Permissio
  */
 interface EvaluateOptions {
     roleMap?: RolePermissionsMap;
+    /** A role can inherit permissions from one or more parent roles. */
+    roleHierarchy?: RoleHierarchy;
     context?: Record<string, unknown>;
     policy?: AuthorizationPolicy;
 }
@@ -65,11 +67,18 @@ interface AuthorizationResult {
     allowed: boolean;
     reason?: string;
     missingPermissions?: Permission[];
+    /** Roles considered after resolving inheritance. */
+    evaluatedRoles?: Role[];
+    /** How the decision was reached. */
+    source?: 'policy' | 'direct-permission' | 'role-permission' | 'none';
+    matchedPermission?: Permission;
 }
 /**
  * Mapping from roles to their granted permissions.
  */
 type RolePermissionsMap = Record<Role, readonly Permission[] | Permission[]>;
+/** Maps a role to the roles whose permissions it inherits. */
+type RoleHierarchy = Record<Role, readonly Role[] | Role[]>;
 
 /**
  * Default role-to-permissions map for Gatekeeper.
@@ -83,6 +92,10 @@ declare const DEFAULT_ROLE_PERMISSIONS: RolePermissionsMap;
  * Creates a merged role-to-permissions map by extending or overriding the defaults.
  */
 declare function defineRolePermissions(customMap?: Partial<RolePermissionsMap>, baseMap?: RolePermissionsMap): RolePermissionsMap;
+/** Creates a defensive copy of role inheritance declarations. */
+declare function defineRoleHierarchy(hierarchy: RoleHierarchy): RoleHierarchy;
+/** Resolves all inherited roles safely, including cyclic declarations. */
+declare function resolveInheritedRoles(roles: Iterable<Role>, hierarchy?: RoleHierarchy): Role[];
 
 /**
  * Normalizes either a legacy RolePermissionsMap or a modern EvaluateOptions object.
@@ -97,6 +110,8 @@ declare function parseEvaluateOptions(options?: RoleMapOrOptions): EvaluateOptio
  * Deduplicates permissions and denies safely if no roles or permissions exist.
  */
 declare function getUserEffectivePermissions(subject: AuthorizationSubject | null | undefined, roleMapOrOptions?: RoleMapOrOptions): Set<Permission>;
+/** Supports exact permissions and namespace wildcards such as `billing.*`. */
+declare function permissionMatches(granted: Permission, requested: Permission): boolean;
 /**
  * Evaluates whether a subject has a specific permission.
  * Supports scoped policy checks and legacy roleMap options.
@@ -119,6 +134,8 @@ declare function canAny(subject: AuthorizationSubject | null | undefined, permis
  * Evaluates access with detailed diagnostic reasons.
  */
 declare function evaluatePermission(subject: AuthorizationSubject | null | undefined, permission: Permission, options?: RoleMapOrOptions): AuthorizationResult;
+/** Alias for evaluatePermission, optimized for audit/debug UI naming. */
+declare const explain: typeof evaluatePermission;
 /**
  * Normalizes feature flag inputs (either an array of FeatureFlag or a record of boolean flags)
  * into a standard Record<string, boolean>.
@@ -239,4 +256,4 @@ interface SubjectMappingConfig<TSource> {
  */
 declare function createSubject<TSource>(source: TSource, mapping: SubjectMappingConfig<TSource> | ((source: TSource) => AuthorizationSubject)): AuthorizationSubject;
 
-export { type AuthorizationPolicy, type AuthorizationResult, type AuthorizationSubject, DEFAULT_ROLE_PERMISSIONS, type EvaluateOptions, type FeatureFlag, type FromPermissionsInput, type FromRolesInput, type GatekeeperUser, type JwtClaimsOptions, type Permission, type Role, type RoleMapOrOptions, type RolePermissionsMap, type StandardPermission, type StandardRole, type SubjectMappingConfig, can, canAll, canAny, createSubject, defineRolePermissions, evaluatePermission, fromJwtClaims, fromPermissions, fromRoles, getUserEffectivePermissions, isFeatureEnabled, normalizeFeatureFlags, parseEvaluateOptions };
+export { type AuthorizationPolicy, type AuthorizationResult, type AuthorizationSubject, DEFAULT_ROLE_PERMISSIONS, type EvaluateOptions, type FeatureFlag, type FromPermissionsInput, type FromRolesInput, type GatekeeperUser, type JwtClaimsOptions, type Permission, type Role, type RoleHierarchy, type RoleMapOrOptions, type RolePermissionsMap, type StandardPermission, type StandardRole, type SubjectMappingConfig, can, canAll, canAny, createSubject, defineRoleHierarchy, defineRolePermissions, evaluatePermission, explain, fromJwtClaims, fromPermissions, fromRoles, getUserEffectivePermissions, isFeatureEnabled, normalizeFeatureFlags, parseEvaluateOptions, permissionMatches, resolveInheritedRoles };

package/dist/index.js

@@ -16,13 +16,28 @@ function defineRolePermissions(customMap, baseMap = DEFAULT_ROLE_PERMISSIONS) {
   }
   return merged;
 }
+function defineRoleHierarchy(hierarchy) {
+  return Object.fromEntries(
+    Object.entries(hierarchy).map(([role, parents]) => [role, [...parents]])
+  );
+}
+function resolveInheritedRoles(roles, hierarchy) {
+  const resolved = /* @__PURE__ */ new Set();
+  const visit = (role) => {
+    if (resolved.has(role)) return;
+    resolved.add(role);
+    for (const parent of hierarchy?.[role] ?? []) visit(parent);
+  };
+  for (const role of roles) visit(role);
+  return [...resolved];
+}
 
 // src/evaluator.ts
 function parseEvaluateOptions(options) {
   if (!options || typeof options !== "object") {
     return {};
   }
-  if ("roleMap" in options || "context" in options || "policy" in options) {
+  if ("roleMap" in options || "roleHierarchy" in options || "context" in options || "policy" in options) {
     return options;
   }
   const values = Object.values(options);
@@ -47,7 +62,7 @@ function getUserEffectivePermissions(subject, roleMapOrOptions) {
   if (subject.role) {
     rolesToEvaluate.add(subject.role);
   }
-  for (const role of rolesToEvaluate) {
+  for (const role of resolveInheritedRoles(rolesToEvaluate, opts.roleHierarchy)) {
     const rolePerms = roleMap[role];
     if (rolePerms && Array.isArray(rolePerms)) {
       for (const perm of rolePerms) {
@@ -62,6 +77,9 @@ function getUserEffectivePermissions(subject, roleMapOrOptions) {
   }
   return permissions;
 }
+function permissionMatches(granted, requested) {
+  return granted === requested || granted.endsWith(".*") && requested.startsWith(granted.slice(0, -1));
+}
 function can(subject, permission, options) {
   if (!subject || !permission) {
     return false;
@@ -74,7 +92,7 @@ function can(subject, permission, options) {
     }
   }
   const effective = getUserEffectivePermissions(subject, options !== void 0 ? opts : void 0);
-  return effective.has(permission);
+  return [...effective].some((granted) => permissionMatches(granted, permission));
 }
 function canAll(subject, permissions, options) {
   if (!subject || !permissions.length) {
@@ -108,20 +126,33 @@ function evaluatePermission(subject, permission, options) {
     }
   }
   const effective = getUserEffectivePermissions(subject, options !== void 0 ? opts : void 0);
-  const allowed = effective.has(permission);
+  const matchedPermission = [...effective].find((granted) => permissionMatches(granted, permission));
+  const allowed = matchedPermission !== void 0;
   if (allowed) {
     return {
       allowed: true,
-      reason: "Permission granted."
+      reason: "Permission granted.",
+      matchedPermission,
+      source: subject.permissions?.includes(matchedPermission) ? "direct-permission" : "role-permission",
+      evaluatedRoles: resolveInheritedRoles(
+        [...subject.roles ?? [], ...subject.role ? [subject.role] : []],
+        opts.roleHierarchy
+      )
     };
   }
   const roleDesc = subject.role ?? (subject.roles?.length ? subject.roles.join(", ") : "none");
   return {
     allowed: false,
     reason: `User with role '${roleDesc}' lacks required permission '${permission}'.`,
-    missingPermissions: [permission]
+    missingPermissions: [permission],
+    source: "none",
+    evaluatedRoles: resolveInheritedRoles(
+      [...subject.roles ?? [], ...subject.role ? [subject.role] : []],
+      opts.roleHierarchy
+    )
   };
 }
+var explain = evaluatePermission;
 function normalizeFeatureFlags(flags) {
   if (!flags) {
     return {};
@@ -326,13 +357,17 @@ export {
   canAll,
   canAny,
   createSubject,
+  defineRoleHierarchy,
   defineRolePermissions,
   evaluatePermission,
+  explain,
   fromJwtClaims,
   fromPermissions,
   fromRoles,
   getUserEffectivePermissions,
   isFeatureEnabled,
   normalizeFeatureFlags,
-  parseEvaluateOptions
+  parseEvaluateOptions,
+  permissionMatches,
+  resolveInheritedRoles
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahmed109/gatekeeper-core",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Pure framework-independent authorization and feature-flag evaluator for TypeScript",
   "keywords": [
     "authorization",