secure-role-guard 1.0.0

package/dist/adapters/nextjs.d.ts

@@ -0,0 +1,140 @@
+import { U as UserContext, a as RoleRegistry } from '../types-CSUpaGsY.js';
+
+/**
+ * Secure Role Guard - Next.js Adapter
+ *
+ * Thin wrapper for Next.js API routes and Route Handlers.
+ * 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 system.
+ */
+
+/**
+ * Next.js Request type (minimal interface for App Router).
+ * Using minimal interface to avoid requiring next as a dependency.
+ */
+interface NextRequest {
+    /** Headers from the request */
+    headers: {
+        get(name: string): string | null;
+    };
+}
+/**
+ * Next.js Response helper for App Router.
+ */
+interface NextResponse {
+    json(body: unknown, init?: {
+        status?: number;
+    }): Response;
+}
+/**
+ * Result of a permission check in Next.js context.
+ */
+type PermissionResult = {
+    readonly allowed: boolean;
+    readonly user: UserContext | null;
+};
+/**
+ * Options for Next.js permission wrappers.
+ */
+type NextPermissionOptions = {
+    /** Function to extract user context from request */
+    readonly getUser: (request: NextRequest) => UserContext | null | Promise<UserContext | null>;
+    /** HTTP status code on denial (default: 403) */
+    readonly statusCode?: number;
+    /** Error message on denial (default: 'Forbidden') */
+    readonly message?: string;
+};
+/**
+ * Checks if a user has permission in a Next.js API context.
+ *
+ * This is a pure check function - you handle the response.
+ *
+ * @param user - User context
+ * @param permission - Required permission
+ * @param registry - Role registry
+ * @returns PermissionResult
+ *
+ * @example
+ * ```ts
+ * // app/api/users/route.ts
+ * import { defineRoles } from 'secure-role-guard/core';
+ * import { checkNextPermission } from 'secure-role-guard/adapters/nextjs';
+ *
+ * const registry = defineRoles({ admin: ['user.update'] });
+ *
+ * export async function PUT(request: NextRequest) {
+ *   const user = await getUser(request); // Your auth function
+ *   const result = checkNextPermission(user, 'user.update', registry);
+ *
+ *   if (!result.allowed) {
+ *     return NextResponse.json({ error: 'Forbidden' }, { status: 403 });
+ *   }
+ *
+ *   // Handle the request...
+ * }
+ * ```
+ */
+declare function checkNextPermission(user: UserContext | null | undefined, permission: string, registry: RoleRegistry): PermissionResult;
+/**
+ * Checks if a user has ALL specified permissions.
+ *
+ * @param user - User context
+ * @param permissions - Required permissions
+ * @param registry - Role registry
+ * @returns PermissionResult
+ */
+declare function checkNextPermissionAll(user: UserContext | null | undefined, permissions: readonly string[], registry: RoleRegistry): PermissionResult;
+/**
+ * Checks if a user has ANY of the specified permissions.
+ *
+ * @param user - User context
+ * @param permissions - Permissions to check
+ * @param registry - Role registry
+ * @returns PermissionResult
+ */
+declare function checkNextPermissionAny(user: UserContext | null | undefined, permissions: readonly string[], registry: RoleRegistry): PermissionResult;
+/**
+ * Higher-order function that wraps a Next.js Route Handler with permission check.
+ *
+ * @param permission - Required permission
+ * @param registry - Role registry
+ * @param options - Configuration options
+ * @param handler - The route handler to wrap
+ * @returns Wrapped route handler
+ *
+ * @example
+ * ```ts
+ * // app/api/admin/route.ts
+ * import { defineRoles } from 'secure-role-guard/core';
+ * import { withPermission } from 'secure-role-guard/adapters/nextjs';
+ *
+ * const registry = defineRoles({ admin: ['admin.access'] });
+ *
+ * async function getUser(req: NextRequest) {
+ *   // Your auth logic to extract user from session/token
+ *   return { roles: ['admin'] };
+ * }
+ *
+ * export const GET = withPermission(
+ *   'admin.access',
+ *   registry,
+ *   { getUser },
+ *   async (request, user) => {
+ *     return Response.json({ message: 'Welcome, admin!' });
+ *   }
+ * );
+ * ```
+ */
+declare function withPermission<T extends NextRequest>(permission: string, registry: RoleRegistry, options: NextPermissionOptions, handler: (request: T, user: UserContext) => Response | Promise<Response>): (request: T) => Promise<Response>;
+/**
+ * Higher-order function that wraps a handler requiring ALL permissions.
+ */
+declare function withAllPermissions<T extends NextRequest>(permissions: readonly string[], registry: RoleRegistry, options: NextPermissionOptions, handler: (request: T, user: UserContext) => Response | Promise<Response>): (request: T) => Promise<Response>;
+/**
+ * Higher-order function that wraps a handler requiring ANY permission.
+ */
+declare function withAnyPermission<T extends NextRequest>(permissions: readonly string[], registry: RoleRegistry, options: NextPermissionOptions, handler: (request: T, user: UserContext) => Response | Promise<Response>): (request: T) => Promise<Response>;
+
+export { type NextPermissionOptions, type NextRequest, type NextResponse, type PermissionResult, checkNextPermission, checkNextPermissionAll, checkNextPermissionAny, withAllPermissions, withAnyPermission, withPermission };

package/dist/adapters/nextjs.js

@@ -0,0 +1,138 @@
+'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/nextjs.ts
+function checkNextPermission(user, permission, registry) {
+  return {
+    allowed: canUser(user, permission, registry),
+    user: user ?? null
+  };
+}
+function checkNextPermissionAll(user, permissions, registry) {
+  return {
+    allowed: canUserAll(user, permissions, registry),
+    user: user ?? null
+  };
+}
+function checkNextPermissionAny(user, permissions, registry) {
+  return {
+    allowed: canUserAny(user, permissions, registry),
+    user: user ?? null
+  };
+}
+function withPermission(permission, registry, options, handler) {
+  const statusCode = options.statusCode ?? 403;
+  const message = options.message ?? "Forbidden";
+  return async (request) => {
+    const user = await options.getUser(request);
+    if (user === null || !canUser(user, permission, registry)) {
+      return Response.json({ error: message }, { status: statusCode });
+    }
+    return handler(request, user);
+  };
+}
+function withAllPermissions(permissions, registry, options, handler) {
+  const statusCode = options.statusCode ?? 403;
+  const message = options.message ?? "Forbidden";
+  return async (request) => {
+    const user = await options.getUser(request);
+    if (user === null || !canUserAll(user, permissions, registry)) {
+      return Response.json({ error: message }, { status: statusCode });
+    }
+    return handler(request, user);
+  };
+}
+function withAnyPermission(permissions, registry, options, handler) {
+  const statusCode = options.statusCode ?? 403;
+  const message = options.message ?? "Forbidden";
+  return async (request) => {
+    const user = await options.getUser(request);
+    if (user === null || !canUserAny(user, permissions, registry)) {
+      return Response.json({ error: message }, { status: statusCode });
+    }
+    return handler(request, user);
+  };
+}
+
+exports.checkNextPermission = checkNextPermission;
+exports.checkNextPermissionAll = checkNextPermissionAll;
+exports.checkNextPermissionAny = checkNextPermissionAny;
+exports.withAllPermissions = withAllPermissions;
+exports.withAnyPermission = withAnyPermission;
+exports.withPermission = withPermission;
+//# sourceMappingURL=nextjs.js.map
+//# sourceMappingURL=nextjs.js.map

package/dist/adapters/nextjs.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/core/permission-engine.ts","../../src/adapters/nextjs.ts"],"names":[],"mappings":"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","file":"nextjs.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 - Next.js Adapter\r\n *\r\n * Thin wrapper for Next.js API routes and Route Handlers.\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 system.\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 * Next.js Request type (minimal interface for App Router).\r\n * Using minimal interface to avoid requiring next as a dependency.\r\n */\r\nexport interface NextRequest {\r\n  /** Headers from the request */\r\n  headers: {\r\n    get(name: string): string | null;\r\n  };\r\n}\r\n\r\n/**\r\n * Next.js Response helper for App Router.\r\n */\r\nexport interface NextResponse {\r\n  json(body: unknown, init?: { status?: number }): Response;\r\n}\r\n\r\n/**\r\n * Result of a permission check in Next.js context.\r\n */\r\nexport type PermissionResult = {\r\n  readonly allowed: boolean;\r\n  readonly user: UserContext | null;\r\n};\r\n\r\n/**\r\n * Options for Next.js permission wrappers.\r\n */\r\nexport type NextPermissionOptions = {\r\n  /** Function to extract user context from request */\r\n  readonly getUser: (\r\n    request: NextRequest\r\n  ) => UserContext | null | Promise<UserContext | null>;\r\n  /** HTTP status code on denial (default: 403) */\r\n  readonly statusCode?: number;\r\n  /** Error message on denial (default: 'Forbidden') */\r\n  readonly message?: string;\r\n};\r\n\r\n/**\r\n * Checks if a user has permission in a Next.js API context.\r\n *\r\n * This is a pure check function - you handle the response.\r\n *\r\n * @param user - User context\r\n * @param permission - Required permission\r\n * @param registry - Role registry\r\n * @returns PermissionResult\r\n *\r\n * @example\r\n * ```ts\r\n * // app/api/users/route.ts\r\n * import { defineRoles } from 'secure-role-guard/core';\r\n * import { checkNextPermission } from 'secure-role-guard/adapters/nextjs';\r\n *\r\n * const registry = defineRoles({ admin: ['user.update'] });\r\n *\r\n * export async function PUT(request: NextRequest) {\r\n *   const user = await getUser(request); // Your auth function\r\n *   const result = checkNextPermission(user, 'user.update', registry);\r\n *\r\n *   if (!result.allowed) {\r\n *     return NextResponse.json({ error: 'Forbidden' }, { status: 403 });\r\n *   }\r\n *\r\n *   // Handle the request...\r\n * }\r\n * ```\r\n */\r\nexport function checkNextPermission(\r\n  user: UserContext | null | undefined,\r\n  permission: string,\r\n  registry: RoleRegistry\r\n): PermissionResult {\r\n  return {\r\n    allowed: canUser(user, permission, registry),\r\n    user: user ?? null,\r\n  };\r\n}\r\n\r\n/**\r\n * Checks if a user has ALL specified permissions.\r\n *\r\n * @param user - User context\r\n * @param permissions - Required permissions\r\n * @param registry - Role registry\r\n * @returns PermissionResult\r\n */\r\nexport function checkNextPermissionAll(\r\n  user: UserContext | null | undefined,\r\n  permissions: readonly string[],\r\n  registry: RoleRegistry\r\n): PermissionResult {\r\n  return {\r\n    allowed: canUserAll(user, permissions, registry),\r\n    user: user ?? null,\r\n  };\r\n}\r\n\r\n/**\r\n * Checks if a user has ANY of the specified permissions.\r\n *\r\n * @param user - User context\r\n * @param permissions - Permissions to check\r\n * @param registry - Role registry\r\n * @returns PermissionResult\r\n */\r\nexport function checkNextPermissionAny(\r\n  user: UserContext | null | undefined,\r\n  permissions: readonly string[],\r\n  registry: RoleRegistry\r\n): PermissionResult {\r\n  return {\r\n    allowed: canUserAny(user, permissions, registry),\r\n    user: user ?? null,\r\n  };\r\n}\r\n\r\n/**\r\n * Higher-order function that wraps a Next.js Route Handler with permission check.\r\n *\r\n * @param permission - Required permission\r\n * @param registry - Role registry\r\n * @param options - Configuration options\r\n * @param handler - The route handler to wrap\r\n * @returns Wrapped route handler\r\n *\r\n * @example\r\n * ```ts\r\n * // app/api/admin/route.ts\r\n * import { defineRoles } from 'secure-role-guard/core';\r\n * import { withPermission } from 'secure-role-guard/adapters/nextjs';\r\n *\r\n * const registry = defineRoles({ admin: ['admin.access'] });\r\n *\r\n * async function getUser(req: NextRequest) {\r\n *   // Your auth logic to extract user from session/token\r\n *   return { roles: ['admin'] };\r\n * }\r\n *\r\n * export const GET = withPermission(\r\n *   'admin.access',\r\n *   registry,\r\n *   { getUser },\r\n *   async (request, user) => {\r\n *     return Response.json({ message: 'Welcome, admin!' });\r\n *   }\r\n * );\r\n * ```\r\n */\r\nexport function withPermission<T extends NextRequest>(\r\n  permission: string,\r\n  registry: RoleRegistry,\r\n  options: NextPermissionOptions,\r\n  handler: (request: T, user: UserContext) => Response | Promise<Response>\r\n): (request: T) => Promise<Response> {\r\n  const statusCode = options.statusCode ?? 403;\r\n  const message = options.message ?? \"Forbidden\";\r\n\r\n  return async (request: T): Promise<Response> => {\r\n    const user = await options.getUser(request);\r\n\r\n    if (user === null || !canUser(user, permission, registry)) {\r\n      return Response.json({ error: message }, { status: statusCode });\r\n    }\r\n\r\n    return handler(request, user);\r\n  };\r\n}\r\n\r\n/**\r\n * Higher-order function that wraps a handler requiring ALL permissions.\r\n */\r\nexport function withAllPermissions<T extends NextRequest>(\r\n  permissions: readonly string[],\r\n  registry: RoleRegistry,\r\n  options: NextPermissionOptions,\r\n  handler: (request: T, user: UserContext) => Response | Promise<Response>\r\n): (request: T) => Promise<Response> {\r\n  const statusCode = options.statusCode ?? 403;\r\n  const message = options.message ?? \"Forbidden\";\r\n\r\n  return async (request: T): Promise<Response> => {\r\n    const user = await options.getUser(request);\r\n\r\n    if (user === null || !canUserAll(user, permissions, registry)) {\r\n      return Response.json({ error: message }, { status: statusCode });\r\n    }\r\n\r\n    return handler(request, user);\r\n  };\r\n}\r\n\r\n/**\r\n * Higher-order function that wraps a handler requiring ANY permission.\r\n */\r\nexport function withAnyPermission<T extends NextRequest>(\r\n  permissions: readonly string[],\r\n  registry: RoleRegistry,\r\n  options: NextPermissionOptions,\r\n  handler: (request: T, user: UserContext) => Response | Promise<Response>\r\n): (request: T) => Promise<Response> {\r\n  const statusCode = options.statusCode ?? 403;\r\n  const message = options.message ?? \"Forbidden\";\r\n\r\n  return async (request: T): Promise<Response> => {\r\n    const user = await options.getUser(request);\r\n\r\n    if (user === null || !canUserAny(user, permissions, registry)) {\r\n      return Response.json({ error: message }, { status: statusCode });\r\n    }\r\n\r\n    return handler(request, user);\r\n  };\r\n}\r\n"]}

package/dist/adapters/nextjs.mjs

@@ -0,0 +1,131 @@
+// 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/nextjs.ts
+function checkNextPermission(user, permission, registry) {
+  return {
+    allowed: canUser(user, permission, registry),
+    user: user ?? null
+  };
+}
+function checkNextPermissionAll(user, permissions, registry) {
+  return {
+    allowed: canUserAll(user, permissions, registry),
+    user: user ?? null
+  };
+}
+function checkNextPermissionAny(user, permissions, registry) {
+  return {
+    allowed: canUserAny(user, permissions, registry),
+    user: user ?? null
+  };
+}
+function withPermission(permission, registry, options, handler) {
+  const statusCode = options.statusCode ?? 403;
+  const message = options.message ?? "Forbidden";
+  return async (request) => {
+    const user = await options.getUser(request);
+    if (user === null || !canUser(user, permission, registry)) {
+      return Response.json({ error: message }, { status: statusCode });
+    }
+    return handler(request, user);
+  };
+}
+function withAllPermissions(permissions, registry, options, handler) {
+  const statusCode = options.statusCode ?? 403;
+  const message = options.message ?? "Forbidden";
+  return async (request) => {
+    const user = await options.getUser(request);
+    if (user === null || !canUserAll(user, permissions, registry)) {
+      return Response.json({ error: message }, { status: statusCode });
+    }
+    return handler(request, user);
+  };
+}
+function withAnyPermission(permissions, registry, options, handler) {
+  const statusCode = options.statusCode ?? 403;
+  const message = options.message ?? "Forbidden";
+  return async (request) => {
+    const user = await options.getUser(request);
+    if (user === null || !canUserAny(user, permissions, registry)) {
+      return Response.json({ error: message }, { status: statusCode });
+    }
+    return handler(request, user);
+  };
+}
+
+export { checkNextPermission, checkNextPermissionAll, checkNextPermissionAny, withAllPermissions, withAnyPermission, withPermission };
+//# sourceMappingURL=nextjs.mjs.map
+//# sourceMappingURL=nextjs.mjs.map

package/dist/adapters/nextjs.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/core/permission-engine.ts","../../src/adapters/nextjs.ts"],"names":[],"mappings":"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","file":"nextjs.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 - Next.js Adapter\r\n *\r\n * Thin wrapper for Next.js API routes and Route Handlers.\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 system.\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 * Next.js Request type (minimal interface for App Router).\r\n * Using minimal interface to avoid requiring next as a dependency.\r\n */\r\nexport interface NextRequest {\r\n  /** Headers from the request */\r\n  headers: {\r\n    get(name: string): string | null;\r\n  };\r\n}\r\n\r\n/**\r\n * Next.js Response helper for App Router.\r\n */\r\nexport interface NextResponse {\r\n  json(body: unknown, init?: { status?: number }): Response;\r\n}\r\n\r\n/**\r\n * Result of a permission check in Next.js context.\r\n */\r\nexport type PermissionResult = {\r\n  readonly allowed: boolean;\r\n  readonly user: UserContext | null;\r\n};\r\n\r\n/**\r\n * Options for Next.js permission wrappers.\r\n */\r\nexport type NextPermissionOptions = {\r\n  /** Function to extract user context from request */\r\n  readonly getUser: (\r\n    request: NextRequest\r\n  ) => UserContext | null | Promise<UserContext | null>;\r\n  /** HTTP status code on denial (default: 403) */\r\n  readonly statusCode?: number;\r\n  /** Error message on denial (default: 'Forbidden') */\r\n  readonly message?: string;\r\n};\r\n\r\n/**\r\n * Checks if a user has permission in a Next.js API context.\r\n *\r\n * This is a pure check function - you handle the response.\r\n *\r\n * @param user - User context\r\n * @param permission - Required permission\r\n * @param registry - Role registry\r\n * @returns PermissionResult\r\n *\r\n * @example\r\n * ```ts\r\n * // app/api/users/route.ts\r\n * import { defineRoles } from 'secure-role-guard/core';\r\n * import { checkNextPermission } from 'secure-role-guard/adapters/nextjs';\r\n *\r\n * const registry = defineRoles({ admin: ['user.update'] });\r\n *\r\n * export async function PUT(request: NextRequest) {\r\n *   const user = await getUser(request); // Your auth function\r\n *   const result = checkNextPermission(user, 'user.update', registry);\r\n *\r\n *   if (!result.allowed) {\r\n *     return NextResponse.json({ error: 'Forbidden' }, { status: 403 });\r\n *   }\r\n *\r\n *   // Handle the request...\r\n * }\r\n * ```\r\n */\r\nexport function checkNextPermission(\r\n  user: UserContext | null | undefined,\r\n  permission: string,\r\n  registry: RoleRegistry\r\n): PermissionResult {\r\n  return {\r\n    allowed: canUser(user, permission, registry),\r\n    user: user ?? null,\r\n  };\r\n}\r\n\r\n/**\r\n * Checks if a user has ALL specified permissions.\r\n *\r\n * @param user - User context\r\n * @param permissions - Required permissions\r\n * @param registry - Role registry\r\n * @returns PermissionResult\r\n */\r\nexport function checkNextPermissionAll(\r\n  user: UserContext | null | undefined,\r\n  permissions: readonly string[],\r\n  registry: RoleRegistry\r\n): PermissionResult {\r\n  return {\r\n    allowed: canUserAll(user, permissions, registry),\r\n    user: user ?? null,\r\n  };\r\n}\r\n\r\n/**\r\n * Checks if a user has ANY of the specified permissions.\r\n *\r\n * @param user - User context\r\n * @param permissions - Permissions to check\r\n * @param registry - Role registry\r\n * @returns PermissionResult\r\n */\r\nexport function checkNextPermissionAny(\r\n  user: UserContext | null | undefined,\r\n  permissions: readonly string[],\r\n  registry: RoleRegistry\r\n): PermissionResult {\r\n  return {\r\n    allowed: canUserAny(user, permissions, registry),\r\n    user: user ?? null,\r\n  };\r\n}\r\n\r\n/**\r\n * Higher-order function that wraps a Next.js Route Handler with permission check.\r\n *\r\n * @param permission - Required permission\r\n * @param registry - Role registry\r\n * @param options - Configuration options\r\n * @param handler - The route handler to wrap\r\n * @returns Wrapped route handler\r\n *\r\n * @example\r\n * ```ts\r\n * // app/api/admin/route.ts\r\n * import { defineRoles } from 'secure-role-guard/core';\r\n * import { withPermission } from 'secure-role-guard/adapters/nextjs';\r\n *\r\n * const registry = defineRoles({ admin: ['admin.access'] });\r\n *\r\n * async function getUser(req: NextRequest) {\r\n *   // Your auth logic to extract user from session/token\r\n *   return { roles: ['admin'] };\r\n * }\r\n *\r\n * export const GET = withPermission(\r\n *   'admin.access',\r\n *   registry,\r\n *   { getUser },\r\n *   async (request, user) => {\r\n *     return Response.json({ message: 'Welcome, admin!' });\r\n *   }\r\n * );\r\n * ```\r\n */\r\nexport function withPermission<T extends NextRequest>(\r\n  permission: string,\r\n  registry: RoleRegistry,\r\n  options: NextPermissionOptions,\r\n  handler: (request: T, user: UserContext) => Response | Promise<Response>\r\n): (request: T) => Promise<Response> {\r\n  const statusCode = options.statusCode ?? 403;\r\n  const message = options.message ?? \"Forbidden\";\r\n\r\n  return async (request: T): Promise<Response> => {\r\n    const user = await options.getUser(request);\r\n\r\n    if (user === null || !canUser(user, permission, registry)) {\r\n      return Response.json({ error: message }, { status: statusCode });\r\n    }\r\n\r\n    return handler(request, user);\r\n  };\r\n}\r\n\r\n/**\r\n * Higher-order function that wraps a handler requiring ALL permissions.\r\n */\r\nexport function withAllPermissions<T extends NextRequest>(\r\n  permissions: readonly string[],\r\n  registry: RoleRegistry,\r\n  options: NextPermissionOptions,\r\n  handler: (request: T, user: UserContext) => Response | Promise<Response>\r\n): (request: T) => Promise<Response> {\r\n  const statusCode = options.statusCode ?? 403;\r\n  const message = options.message ?? \"Forbidden\";\r\n\r\n  return async (request: T): Promise<Response> => {\r\n    const user = await options.getUser(request);\r\n\r\n    if (user === null || !canUserAll(user, permissions, registry)) {\r\n      return Response.json({ error: message }, { status: statusCode });\r\n    }\r\n\r\n    return handler(request, user);\r\n  };\r\n}\r\n\r\n/**\r\n * Higher-order function that wraps a handler requiring ANY permission.\r\n */\r\nexport function withAnyPermission<T extends NextRequest>(\r\n  permissions: readonly string[],\r\n  registry: RoleRegistry,\r\n  options: NextPermissionOptions,\r\n  handler: (request: T, user: UserContext) => Response | Promise<Response>\r\n): (request: T) => Promise<Response> {\r\n  const statusCode = options.statusCode ?? 403;\r\n  const message = options.message ?? \"Forbidden\";\r\n\r\n  return async (request: T): Promise<Response> => {\r\n    const user = await options.getUser(request);\r\n\r\n    if (user === null || !canUserAny(user, permissions, registry)) {\r\n      return Response.json({ error: message }, { status: statusCode });\r\n    }\r\n\r\n    return handler(request, user);\r\n  };\r\n}\r\n"]}

package/dist/core/index.d.mts

@@ -0,0 +1,100 @@
+import { R as RoleDefinition, a as RoleRegistry, U as UserContext, b as PermissionCheckResult } from '../types-CSUpaGsY.mjs';
+export { c as PermissionCheckOptions, P as PermissionEngineConfig } from '../types-CSUpaGsY.mjs';
+
+/**
+ * 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 };