secure-role-guard 1.0.0

package/dist/adapters/express.d.mts

@@ -0,0 +1,109 @@
+import { a as RoleRegistry, U as UserContext } from '../types-CSUpaGsY.mjs';
+
+/**
+ * Secure Role Guard - Express Adapter
+ *
+ * Thin middleware wrapper for Express.js applications.
+ * Delegates all authorization logic to the core permission engine.
+ *
+ * IMPORTANT: This adapter does NOT handle authentication.
+ * You must provide the user context from your auth middleware.
+ */
+
+/**
+ * Express-compatible Request type (minimal interface).
+ * We use a minimal interface to avoid requiring express as a dependency.
+ */
+interface ExpressRequest {
+    /** User context attached by your auth middleware */
+    user?: UserContext;
+}
+/**
+ * Express-compatible Response type (minimal interface).
+ */
+interface ExpressResponse {
+    status(code: number): ExpressResponse;
+    json(body: unknown): ExpressResponse;
+}
+/**
+ * Express-compatible NextFunction type.
+ */
+type ExpressNextFunction = (error?: unknown) => void;
+/**
+ * Express middleware signature.
+ */
+type ExpressMiddleware = (req: ExpressRequest, res: ExpressResponse, next: ExpressNextFunction) => void;
+/**
+ * Options for the permission middleware.
+ */
+type PermissionMiddlewareOptions = {
+    /** HTTP status code to return on denial (default: 403) */
+    readonly statusCode?: number;
+    /** Custom error message (default: 'Forbidden') */
+    readonly message?: string;
+    /** Custom function to extract user from request */
+    readonly getUser?: (req: ExpressRequest) => UserContext | null | undefined;
+};
+/**
+ * Creates Express middleware that requires a specific permission.
+ *
+ * SECURITY: Denies by default if user is missing or permission not granted.
+ *
+ * @param permission - Required permission
+ * @param registry - Role registry
+ * @param options - Optional configuration
+ * @returns Express middleware function
+ *
+ * @example
+ * ```ts
+ * import { defineRoles } from 'secure-role-guard/core';
+ * import { requirePermission } from 'secure-role-guard/adapters/express';
+ *
+ * const registry = defineRoles({ admin: ['user.update'] });
+ *
+ * app.put('/users/:id',
+ *   authMiddleware, // Your auth middleware sets req.user
+ *   requirePermission('user.update', registry),
+ *   updateUserHandler
+ * );
+ * ```
+ */
+declare function requirePermission(permission: string, registry: RoleRegistry, options?: PermissionMiddlewareOptions): ExpressMiddleware;
+/**
+ * Creates Express middleware that requires ALL specified permissions.
+ *
+ * @param permissions - Array of required permissions
+ * @param registry - Role registry
+ * @param options - Optional configuration
+ * @returns Express middleware function
+ *
+ * @example
+ * ```ts
+ * app.delete('/users/:id',
+ *   authMiddleware,
+ *   requireAllPermissions(['user.read', 'user.delete'], registry),
+ *   deleteUserHandler
+ * );
+ * ```
+ */
+declare function requireAllPermissions(permissions: readonly string[], registry: RoleRegistry, options?: PermissionMiddlewareOptions): ExpressMiddleware;
+/**
+ * Creates Express middleware that requires ANY of the specified permissions.
+ *
+ * @param permissions - Array of permissions (user needs at least one)
+ * @param registry - Role registry
+ * @param options - Optional configuration
+ * @returns Express middleware function
+ *
+ * @example
+ * ```ts
+ * app.get('/reports',
+ *   authMiddleware,
+ *   requireAnyPermission(['report.admin', 'report.viewer'], registry),
+ *   getReportsHandler
+ * );
+ * ```
+ */
+declare function requireAnyPermission(permissions: readonly string[], registry: RoleRegistry, options?: PermissionMiddlewareOptions): ExpressMiddleware;
+
+export { type ExpressMiddleware, type ExpressNextFunction, type ExpressRequest, type ExpressResponse, type PermissionMiddlewareOptions, requireAllPermissions, requireAnyPermission, requirePermission };

package/dist/adapters/express.d.ts

@@ -0,0 +1,109 @@
+import { a as RoleRegistry, U as UserContext } from '../types-CSUpaGsY.js';
+
+/**
+ * Secure Role Guard - Express Adapter
+ *
+ * Thin middleware wrapper for Express.js applications.
+ * Delegates all authorization logic to the core permission engine.
+ *
+ * IMPORTANT: This adapter does NOT handle authentication.
+ * You must provide the user context from your auth middleware.
+ */
+
+/**
+ * Express-compatible Request type (minimal interface).
+ * We use a minimal interface to avoid requiring express as a dependency.
+ */
+interface ExpressRequest {
+    /** User context attached by your auth middleware */
+    user?: UserContext;
+}
+/**
+ * Express-compatible Response type (minimal interface).
+ */
+interface ExpressResponse {
+    status(code: number): ExpressResponse;
+    json(body: unknown): ExpressResponse;
+}
+/**
+ * Express-compatible NextFunction type.
+ */
+type ExpressNextFunction = (error?: unknown) => void;
+/**
+ * Express middleware signature.
+ */
+type ExpressMiddleware = (req: ExpressRequest, res: ExpressResponse, next: ExpressNextFunction) => void;
+/**
+ * Options for the permission middleware.
+ */
+type PermissionMiddlewareOptions = {
+    /** HTTP status code to return on denial (default: 403) */
+    readonly statusCode?: number;
+    /** Custom error message (default: 'Forbidden') */
+    readonly message?: string;
+    /** Custom function to extract user from request */
+    readonly getUser?: (req: ExpressRequest) => UserContext | null | undefined;
+};
+/**
+ * Creates Express middleware that requires a specific permission.
+ *
+ * SECURITY: Denies by default if user is missing or permission not granted.
+ *
+ * @param permission - Required permission
+ * @param registry - Role registry
+ * @param options - Optional configuration
+ * @returns Express middleware function
+ *
+ * @example
+ * ```ts
+ * import { defineRoles } from 'secure-role-guard/core';
+ * import { requirePermission } from 'secure-role-guard/adapters/express';
+ *
+ * const registry = defineRoles({ admin: ['user.update'] });
+ *
+ * app.put('/users/:id',
+ *   authMiddleware, // Your auth middleware sets req.user
+ *   requirePermission('user.update', registry),
+ *   updateUserHandler
+ * );
+ * ```
+ */
+declare function requirePermission(permission: string, registry: RoleRegistry, options?: PermissionMiddlewareOptions): ExpressMiddleware;
+/**
+ * Creates Express middleware that requires ALL specified permissions.
+ *
+ * @param permissions - Array of required permissions
+ * @param registry - Role registry
+ * @param options - Optional configuration
+ * @returns Express middleware function
+ *
+ * @example
+ * ```ts
+ * app.delete('/users/:id',
+ *   authMiddleware,
+ *   requireAllPermissions(['user.read', 'user.delete'], registry),
+ *   deleteUserHandler
+ * );
+ * ```
+ */
+declare function requireAllPermissions(permissions: readonly string[], registry: RoleRegistry, options?: PermissionMiddlewareOptions): ExpressMiddleware;
+/**
+ * Creates Express middleware that requires ANY of the specified permissions.
+ *
+ * @param permissions - Array of permissions (user needs at least one)
+ * @param registry - Role registry
+ * @param options - Optional configuration
+ * @returns Express middleware function
+ *
+ * @example
+ * ```ts
+ * app.get('/reports',
+ *   authMiddleware,
+ *   requireAnyPermission(['report.admin', 'report.viewer'], registry),
+ *   getReportsHandler
+ * );
+ * ```
+ */
+declare function requireAnyPermission(permissions: readonly string[], registry: RoleRegistry, options?: PermissionMiddlewareOptions): ExpressMiddleware;
+
+export { type ExpressMiddleware, type ExpressNextFunction, type ExpressRequest, type ExpressResponse, type PermissionMiddlewareOptions, requireAllPermissions, requireAnyPermission, requirePermission };

package/dist/adapters/express.js

@@ -0,0 +1,122 @@
+'use strict';
+
+// 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;
+}
+
+// src/adapters/express.ts
+var DEFAULT_OPTIONS = {
+  statusCode: 403,
+  message: "Forbidden",
+  getUser: (req) => req.user
+};
+function requirePermission(permission, registry, options = {}) {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  return (req, res, next) => {
+    const user = opts.getUser(req);
+    if (canUser(user, permission, registry)) {
+      next();
+    } else {
+      res.status(opts.statusCode).json({ error: opts.message });
+    }
+  };
+}
+function requireAllPermissions(permissions, registry, options = {}) {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  return (req, res, next) => {
+    const user = opts.getUser(req);
+    if (canUserAll(user, permissions, registry)) {
+      next();
+    } else {
+      res.status(opts.statusCode).json({ error: opts.message });
+    }
+  };
+}
+function requireAnyPermission(permissions, registry, options = {}) {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  return (req, res, next) => {
+    const user = opts.getUser(req);
+    if (canUserAny(user, permissions, registry)) {
+      next();
+    } else {
+      res.status(opts.statusCode).json({ error: opts.message });
+    }
+  };
+}
+
+exports.requireAllPermissions = requireAllPermissions;
+exports.requireAnyPermission = requireAnyPermission;
+exports.requirePermission = requirePermission;
+//# sourceMappingURL=express.js.map
+//# sourceMappingURL=express.js.map

package/dist/adapters/express.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/core/permission-engine.ts","../../src/adapters/express.ts"],"names":[],"mappings":"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","file":"express.js","sourcesContent":["/**\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 - Express Adapter\r\n *\r\n * Thin middleware wrapper for Express.js applications.\r\n * Delegates all authorization logic to the core permission engine.\r\n *\r\n * IMPORTANT: This adapter does NOT handle authentication.\r\n * You must provide the user context from your auth middleware.\r\n */\r\n\r\nimport type { UserContext, RoleRegistry } from \"../core/types\";\r\nimport { canUser, canUserAll, canUserAny } from \"../core/permission-engine\";\r\n\r\n/**\r\n * Express-compatible Request type (minimal interface).\r\n * We use a minimal interface to avoid requiring express as a dependency.\r\n */\r\nexport interface ExpressRequest {\r\n  /** User context attached by your auth middleware */\r\n  user?: UserContext;\r\n}\r\n\r\n/**\r\n * Express-compatible Response type (minimal interface).\r\n */\r\nexport interface ExpressResponse {\r\n  status(code: number): ExpressResponse;\r\n  json(body: unknown): ExpressResponse;\r\n}\r\n\r\n/**\r\n * Express-compatible NextFunction type.\r\n */\r\nexport type ExpressNextFunction = (error?: unknown) => void;\r\n\r\n/**\r\n * Express middleware signature.\r\n */\r\nexport type ExpressMiddleware = (\r\n  req: ExpressRequest,\r\n  res: ExpressResponse,\r\n  next: ExpressNextFunction\r\n) => void;\r\n\r\n/**\r\n * Options for the permission middleware.\r\n */\r\nexport type PermissionMiddlewareOptions = {\r\n  /** HTTP status code to return on denial (default: 403) */\r\n  readonly statusCode?: number;\r\n  /** Custom error message (default: 'Forbidden') */\r\n  readonly message?: string;\r\n  /** Custom function to extract user from request */\r\n  readonly getUser?: (req: ExpressRequest) => UserContext | null | undefined;\r\n};\r\n\r\nconst DEFAULT_OPTIONS: Required<PermissionMiddlewareOptions> = {\r\n  statusCode: 403,\r\n  message: \"Forbidden\",\r\n  getUser: (req) => req.user,\r\n};\r\n\r\n/**\r\n * Creates Express middleware that requires a specific permission.\r\n *\r\n * SECURITY: Denies by default if user is missing or permission not granted.\r\n *\r\n * @param permission - Required permission\r\n * @param registry - Role registry\r\n * @param options - Optional configuration\r\n * @returns Express middleware function\r\n *\r\n * @example\r\n * ```ts\r\n * import { defineRoles } from 'secure-role-guard/core';\r\n * import { requirePermission } from 'secure-role-guard/adapters/express';\r\n *\r\n * const registry = defineRoles({ admin: ['user.update'] });\r\n *\r\n * app.put('/users/:id',\r\n *   authMiddleware, // Your auth middleware sets req.user\r\n *   requirePermission('user.update', registry),\r\n *   updateUserHandler\r\n * );\r\n * ```\r\n */\r\nexport function requirePermission(\r\n  permission: string,\r\n  registry: RoleRegistry,\r\n  options: PermissionMiddlewareOptions = {}\r\n): ExpressMiddleware {\r\n  const opts = { ...DEFAULT_OPTIONS, ...options };\r\n\r\n  return (req, res, next) => {\r\n    const user = opts.getUser(req);\r\n\r\n    if (canUser(user, permission, registry)) {\r\n      next();\r\n    } else {\r\n      res.status(opts.statusCode).json({ error: opts.message });\r\n    }\r\n  };\r\n}\r\n\r\n/**\r\n * Creates Express middleware that requires ALL specified permissions.\r\n *\r\n * @param permissions - Array of required permissions\r\n * @param registry - Role registry\r\n * @param options - Optional configuration\r\n * @returns Express middleware function\r\n *\r\n * @example\r\n * ```ts\r\n * app.delete('/users/:id',\r\n *   authMiddleware,\r\n *   requireAllPermissions(['user.read', 'user.delete'], registry),\r\n *   deleteUserHandler\r\n * );\r\n * ```\r\n */\r\nexport function requireAllPermissions(\r\n  permissions: readonly string[],\r\n  registry: RoleRegistry,\r\n  options: PermissionMiddlewareOptions = {}\r\n): ExpressMiddleware {\r\n  const opts = { ...DEFAULT_OPTIONS, ...options };\r\n\r\n  return (req, res, next) => {\r\n    const user = opts.getUser(req);\r\n\r\n    if (canUserAll(user, permissions, registry)) {\r\n      next();\r\n    } else {\r\n      res.status(opts.statusCode).json({ error: opts.message });\r\n    }\r\n  };\r\n}\r\n\r\n/**\r\n * Creates Express middleware that requires ANY of the specified permissions.\r\n *\r\n * @param permissions - Array of permissions (user needs at least one)\r\n * @param registry - Role registry\r\n * @param options - Optional configuration\r\n * @returns Express middleware function\r\n *\r\n * @example\r\n * ```ts\r\n * app.get('/reports',\r\n *   authMiddleware,\r\n *   requireAnyPermission(['report.admin', 'report.viewer'], registry),\r\n *   getReportsHandler\r\n * );\r\n * ```\r\n */\r\nexport function requireAnyPermission(\r\n  permissions: readonly string[],\r\n  registry: RoleRegistry,\r\n  options: PermissionMiddlewareOptions = {}\r\n): ExpressMiddleware {\r\n  const opts = { ...DEFAULT_OPTIONS, ...options };\r\n\r\n  return (req, res, next) => {\r\n    const user = opts.getUser(req);\r\n\r\n    if (canUserAny(user, permissions, registry)) {\r\n      next();\r\n    } else {\r\n      res.status(opts.statusCode).json({ error: opts.message });\r\n    }\r\n  };\r\n}\r\n"]}

package/dist/adapters/express.mjs

@@ -0,0 +1,118 @@
+// 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;
+}
+
+// src/adapters/express.ts
+var DEFAULT_OPTIONS = {
+  statusCode: 403,
+  message: "Forbidden",
+  getUser: (req) => req.user
+};
+function requirePermission(permission, registry, options = {}) {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  return (req, res, next) => {
+    const user = opts.getUser(req);
+    if (canUser(user, permission, registry)) {
+      next();
+    } else {
+      res.status(opts.statusCode).json({ error: opts.message });
+    }
+  };
+}
+function requireAllPermissions(permissions, registry, options = {}) {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  return (req, res, next) => {
+    const user = opts.getUser(req);
+    if (canUserAll(user, permissions, registry)) {
+      next();
+    } else {
+      res.status(opts.statusCode).json({ error: opts.message });
+    }
+  };
+}
+function requireAnyPermission(permissions, registry, options = {}) {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  return (req, res, next) => {
+    const user = opts.getUser(req);
+    if (canUserAny(user, permissions, registry)) {
+      next();
+    } else {
+      res.status(opts.statusCode).json({ error: opts.message });
+    }
+  };
+}
+
+export { requireAllPermissions, requireAnyPermission, requirePermission };
+//# sourceMappingURL=express.mjs.map
+//# sourceMappingURL=express.mjs.map

package/dist/adapters/express.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/core/permission-engine.ts","../../src/adapters/express.ts"],"names":[],"mappings":"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","file":"express.mjs","sourcesContent":["/**\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 - Express Adapter\r\n *\r\n * Thin middleware wrapper for Express.js applications.\r\n * Delegates all authorization logic to the core permission engine.\r\n *\r\n * IMPORTANT: This adapter does NOT handle authentication.\r\n * You must provide the user context from your auth middleware.\r\n */\r\n\r\nimport type { UserContext, RoleRegistry } from \"../core/types\";\r\nimport { canUser, canUserAll, canUserAny } from \"../core/permission-engine\";\r\n\r\n/**\r\n * Express-compatible Request type (minimal interface).\r\n * We use a minimal interface to avoid requiring express as a dependency.\r\n */\r\nexport interface ExpressRequest {\r\n  /** User context attached by your auth middleware */\r\n  user?: UserContext;\r\n}\r\n\r\n/**\r\n * Express-compatible Response type (minimal interface).\r\n */\r\nexport interface ExpressResponse {\r\n  status(code: number): ExpressResponse;\r\n  json(body: unknown): ExpressResponse;\r\n}\r\n\r\n/**\r\n * Express-compatible NextFunction type.\r\n */\r\nexport type ExpressNextFunction = (error?: unknown) => void;\r\n\r\n/**\r\n * Express middleware signature.\r\n */\r\nexport type ExpressMiddleware = (\r\n  req: ExpressRequest,\r\n  res: ExpressResponse,\r\n  next: ExpressNextFunction\r\n) => void;\r\n\r\n/**\r\n * Options for the permission middleware.\r\n */\r\nexport type PermissionMiddlewareOptions = {\r\n  /** HTTP status code to return on denial (default: 403) */\r\n  readonly statusCode?: number;\r\n  /** Custom error message (default: 'Forbidden') */\r\n  readonly message?: string;\r\n  /** Custom function to extract user from request */\r\n  readonly getUser?: (req: ExpressRequest) => UserContext | null | undefined;\r\n};\r\n\r\nconst DEFAULT_OPTIONS: Required<PermissionMiddlewareOptions> = {\r\n  statusCode: 403,\r\n  message: \"Forbidden\",\r\n  getUser: (req) => req.user,\r\n};\r\n\r\n/**\r\n * Creates Express middleware that requires a specific permission.\r\n *\r\n * SECURITY: Denies by default if user is missing or permission not granted.\r\n *\r\n * @param permission - Required permission\r\n * @param registry - Role registry\r\n * @param options - Optional configuration\r\n * @returns Express middleware function\r\n *\r\n * @example\r\n * ```ts\r\n * import { defineRoles } from 'secure-role-guard/core';\r\n * import { requirePermission } from 'secure-role-guard/adapters/express';\r\n *\r\n * const registry = defineRoles({ admin: ['user.update'] });\r\n *\r\n * app.put('/users/:id',\r\n *   authMiddleware, // Your auth middleware sets req.user\r\n *   requirePermission('user.update', registry),\r\n *   updateUserHandler\r\n * );\r\n * ```\r\n */\r\nexport function requirePermission(\r\n  permission: string,\r\n  registry: RoleRegistry,\r\n  options: PermissionMiddlewareOptions = {}\r\n): ExpressMiddleware {\r\n  const opts = { ...DEFAULT_OPTIONS, ...options };\r\n\r\n  return (req, res, next) => {\r\n    const user = opts.getUser(req);\r\n\r\n    if (canUser(user, permission, registry)) {\r\n      next();\r\n    } else {\r\n      res.status(opts.statusCode).json({ error: opts.message });\r\n    }\r\n  };\r\n}\r\n\r\n/**\r\n * Creates Express middleware that requires ALL specified permissions.\r\n *\r\n * @param permissions - Array of required permissions\r\n * @param registry - Role registry\r\n * @param options - Optional configuration\r\n * @returns Express middleware function\r\n *\r\n * @example\r\n * ```ts\r\n * app.delete('/users/:id',\r\n *   authMiddleware,\r\n *   requireAllPermissions(['user.read', 'user.delete'], registry),\r\n *   deleteUserHandler\r\n * );\r\n * ```\r\n */\r\nexport function requireAllPermissions(\r\n  permissions: readonly string[],\r\n  registry: RoleRegistry,\r\n  options: PermissionMiddlewareOptions = {}\r\n): ExpressMiddleware {\r\n  const opts = { ...DEFAULT_OPTIONS, ...options };\r\n\r\n  return (req, res, next) => {\r\n    const user = opts.getUser(req);\r\n\r\n    if (canUserAll(user, permissions, registry)) {\r\n      next();\r\n    } else {\r\n      res.status(opts.statusCode).json({ error: opts.message });\r\n    }\r\n  };\r\n}\r\n\r\n/**\r\n * Creates Express middleware that requires ANY of the specified permissions.\r\n *\r\n * @param permissions - Array of permissions (user needs at least one)\r\n * @param registry - Role registry\r\n * @param options - Optional configuration\r\n * @returns Express middleware function\r\n *\r\n * @example\r\n * ```ts\r\n * app.get('/reports',\r\n *   authMiddleware,\r\n *   requireAnyPermission(['report.admin', 'report.viewer'], registry),\r\n *   getReportsHandler\r\n * );\r\n * ```\r\n */\r\nexport function requireAnyPermission(\r\n  permissions: readonly string[],\r\n  registry: RoleRegistry,\r\n  options: PermissionMiddlewareOptions = {}\r\n): ExpressMiddleware {\r\n  const opts = { ...DEFAULT_OPTIONS, ...options };\r\n\r\n  return (req, res, next) => {\r\n    const user = opts.getUser(req);\r\n\r\n    if (canUserAny(user, permissions, registry)) {\r\n      next();\r\n    } else {\r\n      res.status(opts.statusCode).json({ error: opts.message });\r\n    }\r\n  };\r\n}\r\n"]}

package/dist/adapters/index.d.mts

@@ -0,0 +1,3 @@
+export { ExpressMiddleware, ExpressNextFunction, ExpressRequest, ExpressResponse, PermissionMiddlewareOptions, requireAllPermissions, requireAnyPermission, requirePermission } from './express.mjs';
+export { NextPermissionOptions, NextRequest, NextResponse, PermissionResult, checkNextPermission, checkNextPermissionAll, checkNextPermissionAny, withAllPermissions, withAnyPermission, withPermission } from './nextjs.mjs';
+import '../types-CSUpaGsY.mjs';

package/dist/adapters/index.d.ts

@@ -0,0 +1,3 @@
+export { ExpressMiddleware, ExpressNextFunction, ExpressRequest, ExpressResponse, PermissionMiddlewareOptions, requireAllPermissions, requireAnyPermission, requirePermission } from './express.js';
+export { NextPermissionOptions, NextRequest, NextResponse, PermissionResult, checkNextPermission, checkNextPermissionAll, checkNextPermissionAny, withAllPermissions, withAnyPermission, withPermission } from './nextjs.js';
+import '../types-CSUpaGsY.js';