@ahmed109/gatekeeper-core 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ahmed Tamer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,60 @@
-# Temporary Holding Version
+# @ahmed109/gatekeeper-core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> Pure, framework-independent authorization and feature-flag evaluator for TypeScript.
+
+Part of the **Gatekeeper** toolkit. Zero runtime dependencies, deterministic evaluation, and full TypeScript type safety for role-based (RBAC) and attribute-based (ABAC) access control.
+
+## Installation
+
+`ash
+npm install @ahmed109/gatekeeper-core
+
+# or
+
+pnpm add @ahmed109/gatekeeper-core
+
+# or
+
+yarn add @ahmed109/gatekeeper-core
+`
+
+## Features
+
+- **Zero runtime dependencies**: Pure functional logic running identically in Node.js, browsers, Edge runtimes, and Cloudflare Workers.
+- **Layered Privilege Model**: Evaluates base role permissions (dmin, manager, member, or custom) combined with explicit user-level direct grants.
+- **Feature Flag Engine**: Side-by-side authorization and feature-flag evaluation.
+- **Compound Checks**: Built-in support for can(), canAll(), and canAny().
+
+## Quickstart
+
+` ypescript
+import { can, canAll, isFeatureEnabled, type GatekeeperUser } from '@ahmed109/gatekeeper-core';
+
+const user: GatekeeperUser = {
+id: 'usr_123',
+name: 'Alice Admin',
+email: 'alice@example.com',
+role: 'admin',
+permissions: ['custom.override'],
+};
+
+// Check single permission
+if (can(user, 'users.delete')) {
+console.log('User can delete users');
+}
+
+// Check multiple permissions
+if (canAll(user, ['users.read', 'settings.manage'])) {
+console.log('User possesses all required permissions');
+}
+
+// Evaluate feature flags
+const flags = { 'new-dashboard': true, 'beta-analytics': false };
+if (isFeatureEnabled('new-dashboard', flags)) {
+console.log('Feature is enabled');
+}
+`
+
+## License
+
+MIT © [Ahmed Tamer](https://github.com/Ahmed1092002)

package/dist/index.cjs

@@ -0,0 +1,417 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  DEFAULT_ROLE_PERMISSIONS: () => DEFAULT_ROLE_PERMISSIONS,
+  can: () => can,
+  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,
+  permissionMatches: () => permissionMatches,
+  resolveInheritedRoles: () => resolveInheritedRoles
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/roles.ts
+var DEFAULT_ROLE_PERMISSIONS = {
+  admin: ["users.read", "users.create", "users.delete", "reports.view", "settings.manage"],
+  manager: ["users.read", "reports.view"],
+  member: ["reports.view"]
+};
+function defineRolePermissions(customMap, baseMap = DEFAULT_ROLE_PERMISSIONS) {
+  if (!customMap) {
+    return { ...baseMap };
+  }
+  const merged = { ...baseMap };
+  for (const [role, perms] of Object.entries(customMap)) {
+    if (perms) {
+      merged[role] = [...perms];
+    }
+  }
+  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 || "roleHierarchy" in options || "context" in options || "policy" in options) {
+    return options;
+  }
+  const values = Object.values(options);
+  if (values.length === 0 || values.every((v) => Array.isArray(v))) {
+    return { roleMap: options };
+  }
+  return options;
+}
+function getUserEffectivePermissions(subject, roleMapOrOptions) {
+  const permissions = /* @__PURE__ */ new Set();
+  if (!subject) {
+    return permissions;
+  }
+  const opts = parseEvaluateOptions(roleMapOrOptions);
+  const roleMap = opts.roleMap ?? DEFAULT_ROLE_PERMISSIONS;
+  const rolesToEvaluate = /* @__PURE__ */ new Set();
+  if (Array.isArray(subject.roles)) {
+    for (const r of subject.roles) {
+      if (r) rolesToEvaluate.add(r);
+    }
+  }
+  if (subject.role) {
+    rolesToEvaluate.add(subject.role);
+  }
+  for (const role of resolveInheritedRoles(rolesToEvaluate, opts.roleHierarchy)) {
+    const rolePerms = roleMap[role];
+    if (rolePerms && Array.isArray(rolePerms)) {
+      for (const perm of rolePerms) {
+        permissions.add(perm);
+      }
+    }
+  }
+  if (Array.isArray(subject.permissions)) {
+    for (const perm of subject.permissions) {
+      if (perm) permissions.add(perm);
+    }
+  }
+  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;
+  }
+  const opts = parseEvaluateOptions(options);
+  if (opts.policy) {
+    const decision = opts.policy(subject, permission, opts.context);
+    if (typeof decision === "boolean") {
+      return decision;
+    }
+  }
+  const effective = getUserEffectivePermissions(subject, options !== void 0 ? opts : void 0);
+  return [...effective].some((granted) => permissionMatches(granted, permission));
+}
+function canAll(subject, permissions, options) {
+  if (!subject || !permissions.length) {
+    return false;
+  }
+  return permissions.every((p) => can(subject, p, options));
+}
+function canAny(subject, permissions, options) {
+  if (!subject || !permissions.length) {
+    return false;
+  }
+  return permissions.some((p) => can(subject, p, options));
+}
+function evaluatePermission(subject, permission, options) {
+  if (!subject) {
+    return {
+      allowed: false,
+      reason: "No authenticated user provided.",
+      missingPermissions: [permission]
+    };
+  }
+  const opts = parseEvaluateOptions(options);
+  if (opts.policy) {
+    const decision = opts.policy(subject, permission, opts.context);
+    if (typeof decision === "boolean") {
+      return {
+        allowed: decision,
+        reason: decision ? "Permission granted by policy." : "Permission denied by policy.",
+        missingPermissions: decision ? void 0 : [permission]
+      };
+    }
+  }
+  const effective = getUserEffectivePermissions(subject, options !== void 0 ? opts : void 0);
+  const matchedPermission = [...effective].find((granted) => permissionMatches(granted, permission));
+  const allowed = matchedPermission !== void 0;
+  if (allowed) {
+    return {
+      allowed: true,
+      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],
+    source: "none",
+    evaluatedRoles: resolveInheritedRoles(
+      [...subject.roles ?? [], ...subject.role ? [subject.role] : []],
+      opts.roleHierarchy
+    )
+  };
+}
+var explain = evaluatePermission;
+function normalizeFeatureFlags(flags) {
+  if (!flags) {
+    return {};
+  }
+  if (Array.isArray(flags)) {
+    const result = {};
+    for (const flag of flags) {
+      result[flag.key] = flag.enabled;
+    }
+    return result;
+  }
+  return { ...flags };
+}
+function isFeatureEnabled(flags, flagKey) {
+  if (!flags || !flagKey) {
+    return false;
+  }
+  if (Array.isArray(flags)) {
+    const found = flags.find((f) => f.key === flagKey);
+    return Boolean(found?.enabled);
+  }
+  return Boolean(flags[flagKey]);
+}
+
+// src/adapters.ts
+function fromRoles(idOrInput, roles, attributes) {
+  if (typeof idOrInput === "object" && idOrInput !== null) {
+    const rolesList2 = [];
+    if (Array.isArray(idOrInput.roles)) {
+      rolesList2.push(...idOrInput.roles);
+    } else if (idOrInput.roles) {
+      rolesList2.push(idOrInput.roles);
+    }
+    if (idOrInput.role && !rolesList2.includes(idOrInput.role)) {
+      rolesList2.push(idOrInput.role);
+    }
+    return {
+      id: String(idOrInput.id),
+      roles: rolesList2,
+      role: idOrInput.role ?? rolesList2[0],
+      ...idOrInput.permissions ? { permissions: idOrInput.permissions } : {},
+      ...idOrInput.attributes ? { attributes: idOrInput.attributes } : {},
+      ...idOrInput.name ? { name: idOrInput.name } : {},
+      ...idOrInput.email ? { email: idOrInput.email } : {}
+    };
+  }
+  const rolesList = [];
+  if (Array.isArray(roles)) {
+    rolesList.push(...roles);
+  } else if (roles) {
+    rolesList.push(roles);
+  }
+  return {
+    id: String(idOrInput),
+    roles: rolesList,
+    role: rolesList[0],
+    ...attributes ? { attributes } : {}
+  };
+}
+function fromPermissions(idOrInput, permissions, attributes) {
+  if (typeof idOrInput === "object" && idOrInput !== null) {
+    return {
+      id: String(idOrInput.id),
+      roles: [],
+      permissions: Array.isArray(idOrInput.permissions) ? [...idOrInput.permissions] : [],
+      ...idOrInput.attributes ? { attributes: idOrInput.attributes } : {},
+      ...idOrInput.name ? { name: idOrInput.name } : {},
+      ...idOrInput.email ? { email: idOrInput.email } : {}
+    };
+  }
+  return {
+    id: String(idOrInput),
+    roles: [],
+    permissions: Array.isArray(permissions) ? [...permissions] : [],
+    ...attributes ? { attributes } : {}
+  };
+}
+function getByPath(obj, path) {
+  const parts = path.split(".");
+  let current = obj;
+  for (const part of parts) {
+    if (current && typeof current === "object" && part in current) {
+      current = current[part];
+    } else {
+      return void 0;
+    }
+  }
+  return current;
+}
+function fromJwtClaims(claims, options = {}) {
+  if (!claims || typeof claims !== "object") {
+    return { id: "", roles: [], permissions: [] };
+  }
+  const idFields = options.idField ? Array.isArray(options.idField) ? options.idField : [options.idField] : ["sub", "id"];
+  let resolvedId = "";
+  for (const field of idFields) {
+    const val = getByPath(claims, field);
+    if (val !== void 0 && val !== null && String(val).trim()) {
+      resolvedId = String(val);
+      break;
+    }
+  }
+  const rolesFields = options.rolesField ? Array.isArray(options.rolesField) ? options.rolesField : [options.rolesField] : ["roles", "role", "realm_access.roles"];
+  const resolvedRoles = [];
+  for (const field of rolesFields) {
+    const val = getByPath(claims, field);
+    if (Array.isArray(val)) {
+      for (const item of val) {
+        if (typeof item === "string") {
+          resolvedRoles.push(item);
+        }
+      }
+      if (resolvedRoles.length > 0) break;
+    } else if (typeof val === "string" && val.trim()) {
+      resolvedRoles.push(val);
+      break;
+    }
+  }
+  const permFields = options.permissionsField ? Array.isArray(options.permissionsField) ? options.permissionsField : [options.permissionsField] : ["permissions", "perms"];
+  const resolvedPerms = [];
+  for (const field of permFields) {
+    const val = getByPath(claims, field);
+    if (Array.isArray(val)) {
+      for (const item of val) {
+        if (typeof item === "string") {
+          resolvedPerms.push(item);
+        }
+      }
+      if (resolvedPerms.length > 0) break;
+    } else if (typeof val === "string" && val.trim()) {
+      resolvedPerms.push(val);
+      break;
+    }
+  }
+  const attributes = {};
+  if (options.attributesFields && Array.isArray(options.attributesFields)) {
+    for (const attrField of options.attributesFields) {
+      const val = getByPath(claims, attrField);
+      if (val !== void 0) {
+        attributes[attrField] = val;
+      }
+    }
+  } else {
+    const excludedKeys = /* @__PURE__ */ new Set([
+      "sub",
+      "id",
+      "roles",
+      "role",
+      "realm_access",
+      "permissions",
+      "perms"
+    ]);
+    for (const [k, v] of Object.entries(claims)) {
+      if (!excludedKeys.has(k) && v !== void 0) {
+        attributes[k] = v;
+      }
+    }
+  }
+  const email = typeof claims.email === "string" ? claims.email : void 0;
+  const name = typeof claims.name === "string" ? claims.name : typeof claims.preferred_username === "string" ? claims.preferred_username : void 0;
+  return {
+    id: resolvedId,
+    roles: resolvedRoles,
+    role: resolvedRoles[0],
+    permissions: resolvedPerms,
+    attributes,
+    ...name ? { name } : {},
+    ...email ? { email } : {}
+  };
+}
+function createSubject(source, mapping) {
+  if (typeof mapping === "function") {
+    return mapping(source);
+  }
+  const rawRoles = mapping.getRoles ? mapping.getRoles(source) : void 0;
+  const rolesList = [];
+  if (Array.isArray(rawRoles)) {
+    for (const r of rawRoles) {
+      if (r) rolesList.push(r);
+    }
+  } else if (rawRoles) {
+    rolesList.push(rawRoles);
+  }
+  const rawPerms = mapping.getPermissions ? mapping.getPermissions(source) : void 0;
+  const permsList = Array.isArray(rawPerms) ? [...rawPerms] : [];
+  const attributes = mapping.getAttributes ? mapping.getAttributes(source) : void 0;
+  const name = mapping.getName ? mapping.getName(source) : void 0;
+  const email = mapping.getEmail ? mapping.getEmail(source) : void 0;
+  return {
+    id: mapping.getId(source),
+    roles: rolesList,
+    role: rolesList[0],
+    permissions: permsList,
+    ...attributes ? { attributes } : {},
+    ...name ? { name } : {},
+    ...email ? { email } : {}
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_ROLE_PERMISSIONS,
+  can,
+  canAll,
+  canAny,
+  createSubject,
+  defineRoleHierarchy,
+  defineRolePermissions,
+  evaluatePermission,
+  explain,
+  fromJwtClaims,
+  fromPermissions,
+  fromRoles,
+  getUserEffectivePermissions,
+  isFeatureEnabled,
+  normalizeFeatureFlags,
+  parseEvaluateOptions,
+  permissionMatches,
+  resolveInheritedRoles
+});