react-permission-gate 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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

@@ -0,0 +1,203 @@
+# react-permission-gate
+
+Flexible, type-safe permission management for React and React Router applications.
+
+## Features
+
+- **Pure TypeScript core** — use `PermissionChecker` anywhere, no React needed
+- **React integration** — `PermissionProvider`, `usePermissions` hook, `PermissionGate` component
+- **React Router integration** — `ProtectedRoute` with redirect support
+- **Admin bypass** — configurable admin role types that skip all checks
+- **Type-safe permission constants** — `createPermissions()` with literal types
+- **Tree-shakeable** — separate entry points, import only what you need
+
+## Installation
+
+```bash
+npm install react-permission-gate
+```
+
+## Quick Start
+
+### 1. Define your permissions (optional but recommended)
+
+```ts
+import { createPermissions } from "react-permission-gate";
+
+export const PERMISSIONS = createPermissions({
+  USERS: {
+    READ: "system.users.read",
+    CREATE: "system.users.create",
+    DELETE: "system.users.delete",
+  },
+  GROUPS: {
+    READ: "system.groups.read",
+  },
+});
+```
+
+### 2. Wrap your app with PermissionProvider
+
+```tsx
+import { PermissionProvider } from "react-permission-gate/react";
+
+function App() {
+  const { user, isLoading } = useAuth(); // your auth hook
+
+  return (
+    <PermissionProvider
+      permissions={user?.permissions ?? []}
+      userType={user?.role}
+      loading={isLoading}
+    >
+      <Router />
+    </PermissionProvider>
+  );
+}
+```
+
+### 3. Use PermissionGate in components
+
+```tsx
+import { PermissionGate } from "react-permission-gate/react";
+
+function UsersPage() {
+  return (
+    <div>
+      <h1>Users</h1>
+
+      <PermissionGate permission={PERMISSIONS.USERS.CREATE}>
+        <button>Create User</button>
+      </PermissionGate>
+
+      <PermissionGate
+        anyOf={[PERMISSIONS.USERS.CREATE, PERMISSIONS.USERS.DELETE]}
+        fallback={<span>No access</span>}
+      >
+        <AdminPanel />
+      </PermissionGate>
+    </div>
+  );
+}
+```
+
+### 4. Use usePermissions hook
+
+```tsx
+import { usePermissions } from "react-permission-gate/react";
+
+function UserActions() {
+  const { hasPermission, isAdmin } = usePermissions();
+
+  if (!hasPermission(PERMISSIONS.USERS.DELETE)) return null;
+
+  return <button>Delete User</button>;
+}
+```
+
+### 5. Protect routes
+
+```tsx
+import { ProtectedRoute } from "react-permission-gate/react-router";
+
+<Route
+  path="/users"
+  element={
+    <ProtectedRoute
+      permission={PERMISSIONS.USERS.READ}
+      redirectTo="/unauthorized"
+      loadingComponent={<Spinner />}
+    >
+      <UsersPage />
+    </ProtectedRoute>
+  }
+/>
+```
+
+## API Reference
+
+### Core (`react-permission-gate`)
+
+#### `PermissionChecker`
+
+Pure TypeScript permission checker class.
+
+```ts
+const checker = new PermissionChecker({
+  permissions: ["users.read", "users.create"],
+  userType: "USER",
+  adminTypes: ["ADMIN"],  // default: ["ADMIN"]
+  adminBypass: true,       // default: true
+});
+
+checker.hasPermission("users.read");     // true
+checker.hasAnyPermission(["a", "b"]);    // boolean
+checker.hasAllPermissions(["a", "b"]);   // boolean
+checker.check("users.read");             // { granted: true, reason: "permission_found" }
+checker.admin;                           // boolean
+```
+
+#### `createPermissions(definition)`
+
+Creates a deeply frozen, type-safe permission constants object.
+
+```ts
+const PERMS = createPermissions({
+  USERS: { READ: "users.read" },
+});
+// typeof PERMS.USERS.READ → "users.read" (literal type)
+```
+
+### React (`react-permission-gate/react`)
+
+#### `<PermissionProvider>`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `permissions` | `string[]` | required | User's permission strings |
+| `userType` | `string` | `""` | User's type/role |
+| `adminTypes` | `string[]` | `["ADMIN"]` | Types that bypass all checks |
+| `adminBypass` | `boolean` | `true` | Whether admin bypass is enabled |
+| `loading` | `boolean` | `false` | External loading state |
+
+#### `usePermissions()`
+
+Returns: `{ permissions, userType, isAdmin, isLoading, hasPermission, hasAnyPermission, hasAllPermissions, check }`
+
+#### `<PermissionGate>`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `permission` | `string` | - | Single required permission |
+| `anyOf` | `string[]` | - | Show if user has any |
+| `allOf` | `string[]` | - | Show if user has all |
+| `fallback` | `ReactNode` | `null` | Shown when denied |
+
+### React Router (`react-permission-gate/react-router`)
+
+#### `<ProtectedRoute>`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `permission` | `string` | - | Single required permission |
+| `anyOf` | `string[]` | - | Access if user has any |
+| `allOf` | `string[]` | - | Access if user has all |
+| `redirectTo` | `string` | `"/"` | Redirect on denied |
+| `loadingComponent` | `ReactNode` | `null` | Shown while loading |
+
+## Admin Bypass
+
+By default, users with `userType: "ADMIN"` bypass all permission checks. Configure via:
+
+```tsx
+<PermissionProvider
+  permissions={user.permissions}
+  userType={user.role}
+  adminTypes={["ADMIN", "SUPER_ADMIN"]}  // custom admin types
+  adminBypass={false}                      // disable bypass entirely
+>
+```
+
+## License
+
+MIT

package/dist/core/index.cjs

@@ -0,0 +1,82 @@
+"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/core/index.ts
+var index_exports = {};
+__export(index_exports, {
+  PermissionChecker: () => PermissionChecker,
+  createPermissions: () => createPermissions
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/core/permission-checker.ts
+var PermissionChecker = class {
+  constructor(config) {
+    this.permissions = new Set(config.permissions);
+    const adminTypes = config.adminTypes ?? ["ADMIN"];
+    const bypass = config.adminBypass ?? true;
+    this.isAdmin = bypass && adminTypes.includes(config.userType ?? "");
+  }
+  /** Whether this checker was created with an admin-type user */
+  get admin() {
+    return this.isAdmin;
+  }
+  /** Check if user has a specific permission. Admins always return true. */
+  hasPermission(permission) {
+    if (this.isAdmin) return true;
+    return this.permissions.has(permission);
+  }
+  /** Check if user has ANY of the given permissions. Admins always return true. */
+  hasAnyPermission(permissionList) {
+    if (this.isAdmin) return true;
+    return permissionList.some((p) => this.permissions.has(p));
+  }
+  /** Check if user has ALL of the given permissions. Admins always return true. */
+  hasAllPermissions(permissionList) {
+    if (this.isAdmin) return true;
+    return permissionList.every((p) => this.permissions.has(p));
+  }
+  /** Detailed permission check with reason for the result */
+  check(permission) {
+    if (this.isAdmin) {
+      return { granted: true, reason: "admin_bypass" };
+    }
+    if (this.permissions.has(permission)) {
+      return { granted: true, reason: "permission_found" };
+    }
+    return { granted: false, reason: "permission_missing" };
+  }
+};
+
+// src/core/create-permissions.ts
+function createPermissions(definition) {
+  const frozen = { ...definition };
+  for (const key of Object.keys(frozen)) {
+    frozen[key] = Object.freeze(
+      frozen[key]
+    );
+  }
+  return Object.freeze(frozen);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PermissionChecker,
+  createPermissions
+});
+//# sourceMappingURL=index.cjs.map

package/dist/core/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/core/index.ts","../../src/core/permission-checker.ts","../../src/core/create-permissions.ts"],"sourcesContent":["export { PermissionChecker } from \"./permission-checker\";\nexport { createPermissions } from \"./create-permissions\";\nexport type { ExtractPermissions } from \"./create-permissions\";\nexport type {\n  PermissionConfig,\n  PermissionCheckResult,\n  PermissionCheckReason,\n  DeepReadonly,\n} from \"./types\";\n","import type { PermissionCheckResult, PermissionConfig } from \"./types\";\n\n/**\n * Pure TypeScript permission checker — no React dependency.\n *\n * @example\n * const checker = new PermissionChecker({\n *   permissions: [\"users.read\", \"users.create\"],\n *   userType: \"USER\",\n * });\n *\n * checker.hasPermission(\"users.read\"); // true\n * checker.hasPermission(\"users.delete\"); // false\n */\nexport class PermissionChecker {\n  private readonly permissions: Set<string>;\n  private readonly isAdmin: boolean;\n\n  constructor(config: PermissionConfig) {\n    this.permissions = new Set(config.permissions);\n    const adminTypes = config.adminTypes ?? [\"ADMIN\"];\n    const bypass = config.adminBypass ?? true;\n    this.isAdmin = bypass && adminTypes.includes(config.userType ?? \"\");\n  }\n\n  /** Whether this checker was created with an admin-type user */\n  get admin(): boolean {\n    return this.isAdmin;\n  }\n\n  /** Check if user has a specific permission. Admins always return true. */\n  hasPermission(permission: string): boolean {\n    if (this.isAdmin) return true;\n    return this.permissions.has(permission);\n  }\n\n  /** Check if user has ANY of the given permissions. Admins always return true. */\n  hasAnyPermission(permissionList: string[]): boolean {\n    if (this.isAdmin) return true;\n    return permissionList.some((p) => this.permissions.has(p));\n  }\n\n  /** Check if user has ALL of the given permissions. Admins always return true. */\n  hasAllPermissions(permissionList: string[]): boolean {\n    if (this.isAdmin) return true;\n    return permissionList.every((p) => this.permissions.has(p));\n  }\n\n  /** Detailed permission check with reason for the result */\n  check(permission: string): PermissionCheckResult {\n    if (this.isAdmin) {\n      return { granted: true, reason: \"admin_bypass\" };\n    }\n\n    if (this.permissions.has(permission)) {\n      return { granted: true, reason: \"permission_found\" };\n    }\n\n    return { granted: false, reason: \"permission_missing\" };\n  }\n}\n","import type { DeepReadonly } from \"./types\";\n\n/**\n * Type-safe helper to define permission constants with literal types.\n * Returns a deeply frozen, readonly object.\n *\n * @example\n * const PERMISSIONS = createPermissions({\n *   USERS: {\n *     READ: \"system.users.read\",\n *     CREATE: \"system.users.create\",\n *   },\n *   GROUPS: {\n *     READ: \"system.groups.read\",\n *   },\n * });\n *\n * // typeof PERMISSIONS.USERS.READ → \"system.users.read\" (literal type)\n */\nexport function createPermissions<\n  T extends Record<string, Record<string, string>>,\n>(definition: T): DeepReadonly<T> {\n  const frozen = { ...definition };\n\n  for (const key of Object.keys(frozen)) {\n    (frozen as Record<string, unknown>)[key] = Object.freeze(\n      (frozen as Record<string, Record<string, string>>)[key],\n    );\n  }\n\n  return Object.freeze(frozen) as DeepReadonly<T>;\n}\n\n/** Extracts all permission string values from a createPermissions() result */\nexport type ExtractPermissions<T> =\n  T extends Record<string, Record<string, infer V>> ? V : never;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACcO,IAAM,oBAAN,MAAwB;AAAA,EAI7B,YAAY,QAA0B;AACpC,SAAK,cAAc,IAAI,IAAI,OAAO,WAAW;AAC7C,UAAM,aAAa,OAAO,cAAc,CAAC,OAAO;AAChD,UAAM,SAAS,OAAO,eAAe;AACrC,SAAK,UAAU,UAAU,WAAW,SAAS,OAAO,YAAY,EAAE;AAAA,EACpE;AAAA;AAAA,EAGA,IAAI,QAAiB;AACnB,WAAO,KAAK;AAAA,EACd;AAAA;AAAA,EAGA,cAAc,YAA6B;AACzC,QAAI,KAAK,QAAS,QAAO;AACzB,WAAO,KAAK,YAAY,IAAI,UAAU;AAAA,EACxC;AAAA;AAAA,EAGA,iBAAiB,gBAAmC;AAClD,QAAI,KAAK,QAAS,QAAO;AACzB,WAAO,eAAe,KAAK,CAAC,MAAM,KAAK,YAAY,IAAI,CAAC,CAAC;AAAA,EAC3D;AAAA;AAAA,EAGA,kBAAkB,gBAAmC;AACnD,QAAI,KAAK,QAAS,QAAO;AACzB,WAAO,eAAe,MAAM,CAAC,MAAM,KAAK,YAAY,IAAI,CAAC,CAAC;AAAA,EAC5D;AAAA;AAAA,EAGA,MAAM,YAA2C;AAC/C,QAAI,KAAK,SAAS;AAChB,aAAO,EAAE,SAAS,MAAM,QAAQ,eAAe;AAAA,IACjD;AAEA,QAAI,KAAK,YAAY,IAAI,UAAU,GAAG;AACpC,aAAO,EAAE,SAAS,MAAM,QAAQ,mBAAmB;AAAA,IACrD;AAEA,WAAO,EAAE,SAAS,OAAO,QAAQ,qBAAqB;AAAA,EACxD;AACF;;;ACzCO,SAAS,kBAEd,YAAgC;AAChC,QAAM,SAAS,EAAE,GAAG,WAAW;AAE/B,aAAW,OAAO,OAAO,KAAK,MAAM,GAAG;AACrC,IAAC,OAAmC,GAAG,IAAI,OAAO;AAAA,MAC/C,OAAkD,GAAG;AAAA,IACxD;AAAA,EACF;AAEA,SAAO,OAAO,OAAO,MAAM;AAC7B;","names":[]}

package/dist/core/index.d.cts

@@ -0,0 +1,73 @@
+/** Configuration for the permission checker */
+interface PermissionConfig {
+    /** List of permission strings the user has */
+    permissions: string[];
+    /** User's type/role identifier (e.g., "ADMIN", "USER") */
+    userType?: string;
+    /** User types that bypass all permission checks (default: ["ADMIN"]) */
+    adminTypes?: string[];
+    /** Whether admin types bypass checks (default: true) */
+    adminBypass?: boolean;
+}
+/** Reason for a permission check result */
+type PermissionCheckReason = "admin_bypass" | "permission_found" | "permission_missing" | "no_check";
+/** Result of a permission check with detailed reason */
+interface PermissionCheckResult {
+    granted: boolean;
+    reason: PermissionCheckReason;
+}
+/** Deep readonly utility type */
+type DeepReadonly<T> = {
+    readonly [K in keyof T]: T[K] extends Record<string, unknown> ? DeepReadonly<T[K]> : T[K];
+};
+
+/**
+ * Pure TypeScript permission checker — no React dependency.
+ *
+ * @example
+ * const checker = new PermissionChecker({
+ *   permissions: ["users.read", "users.create"],
+ *   userType: "USER",
+ * });
+ *
+ * checker.hasPermission("users.read"); // true
+ * checker.hasPermission("users.delete"); // false
+ */
+declare class PermissionChecker {
+    private readonly permissions;
+    private readonly isAdmin;
+    constructor(config: PermissionConfig);
+    /** Whether this checker was created with an admin-type user */
+    get admin(): boolean;
+    /** Check if user has a specific permission. Admins always return true. */
+    hasPermission(permission: string): boolean;
+    /** Check if user has ANY of the given permissions. Admins always return true. */
+    hasAnyPermission(permissionList: string[]): boolean;
+    /** Check if user has ALL of the given permissions. Admins always return true. */
+    hasAllPermissions(permissionList: string[]): boolean;
+    /** Detailed permission check with reason for the result */
+    check(permission: string): PermissionCheckResult;
+}
+
+/**
+ * Type-safe helper to define permission constants with literal types.
+ * Returns a deeply frozen, readonly object.
+ *
+ * @example
+ * const PERMISSIONS = createPermissions({
+ *   USERS: {
+ *     READ: "system.users.read",
+ *     CREATE: "system.users.create",
+ *   },
+ *   GROUPS: {
+ *     READ: "system.groups.read",
+ *   },
+ * });
+ *
+ * // typeof PERMISSIONS.USERS.READ → "system.users.read" (literal type)
+ */
+declare function createPermissions<T extends Record<string, Record<string, string>>>(definition: T): DeepReadonly<T>;
+/** Extracts all permission string values from a createPermissions() result */
+type ExtractPermissions<T> = T extends Record<string, Record<string, infer V>> ? V : never;
+
+export { type DeepReadonly, type ExtractPermissions, type PermissionCheckReason, type PermissionCheckResult, PermissionChecker, type PermissionConfig, createPermissions };

package/dist/core/index.d.ts

@@ -0,0 +1,73 @@
+/** Configuration for the permission checker */
+interface PermissionConfig {
+    /** List of permission strings the user has */
+    permissions: string[];
+    /** User's type/role identifier (e.g., "ADMIN", "USER") */
+    userType?: string;
+    /** User types that bypass all permission checks (default: ["ADMIN"]) */
+    adminTypes?: string[];
+    /** Whether admin types bypass checks (default: true) */
+    adminBypass?: boolean;
+}
+/** Reason for a permission check result */
+type PermissionCheckReason = "admin_bypass" | "permission_found" | "permission_missing" | "no_check";
+/** Result of a permission check with detailed reason */
+interface PermissionCheckResult {
+    granted: boolean;
+    reason: PermissionCheckReason;
+}
+/** Deep readonly utility type */
+type DeepReadonly<T> = {
+    readonly [K in keyof T]: T[K] extends Record<string, unknown> ? DeepReadonly<T[K]> : T[K];
+};
+
+/**
+ * Pure TypeScript permission checker — no React dependency.
+ *
+ * @example
+ * const checker = new PermissionChecker({
+ *   permissions: ["users.read", "users.create"],
+ *   userType: "USER",
+ * });
+ *
+ * checker.hasPermission("users.read"); // true
+ * checker.hasPermission("users.delete"); // false
+ */
+declare class PermissionChecker {
+    private readonly permissions;
+    private readonly isAdmin;
+    constructor(config: PermissionConfig);
+    /** Whether this checker was created with an admin-type user */
+    get admin(): boolean;
+    /** Check if user has a specific permission. Admins always return true. */
+    hasPermission(permission: string): boolean;
+    /** Check if user has ANY of the given permissions. Admins always return true. */
+    hasAnyPermission(permissionList: string[]): boolean;
+    /** Check if user has ALL of the given permissions. Admins always return true. */
+    hasAllPermissions(permissionList: string[]): boolean;
+    /** Detailed permission check with reason for the result */
+    check(permission: string): PermissionCheckResult;
+}
+
+/**
+ * Type-safe helper to define permission constants with literal types.
+ * Returns a deeply frozen, readonly object.
+ *
+ * @example
+ * const PERMISSIONS = createPermissions({
+ *   USERS: {
+ *     READ: "system.users.read",
+ *     CREATE: "system.users.create",
+ *   },
+ *   GROUPS: {
+ *     READ: "system.groups.read",
+ *   },
+ * });
+ *
+ * // typeof PERMISSIONS.USERS.READ → "system.users.read" (literal type)
+ */
+declare function createPermissions<T extends Record<string, Record<string, string>>>(definition: T): DeepReadonly<T>;
+/** Extracts all permission string values from a createPermissions() result */
+type ExtractPermissions<T> = T extends Record<string, Record<string, infer V>> ? V : never;
+
+export { type DeepReadonly, type ExtractPermissions, type PermissionCheckReason, type PermissionCheckResult, PermissionChecker, type PermissionConfig, createPermissions };

package/dist/core/index.js

@@ -0,0 +1,54 @@
+// src/core/permission-checker.ts
+var PermissionChecker = class {
+  constructor(config) {
+    this.permissions = new Set(config.permissions);
+    const adminTypes = config.adminTypes ?? ["ADMIN"];
+    const bypass = config.adminBypass ?? true;
+    this.isAdmin = bypass && adminTypes.includes(config.userType ?? "");
+  }
+  /** Whether this checker was created with an admin-type user */
+  get admin() {
+    return this.isAdmin;
+  }
+  /** Check if user has a specific permission. Admins always return true. */
+  hasPermission(permission) {
+    if (this.isAdmin) return true;
+    return this.permissions.has(permission);
+  }
+  /** Check if user has ANY of the given permissions. Admins always return true. */
+  hasAnyPermission(permissionList) {
+    if (this.isAdmin) return true;
+    return permissionList.some((p) => this.permissions.has(p));
+  }
+  /** Check if user has ALL of the given permissions. Admins always return true. */
+  hasAllPermissions(permissionList) {
+    if (this.isAdmin) return true;
+    return permissionList.every((p) => this.permissions.has(p));
+  }
+  /** Detailed permission check with reason for the result */
+  check(permission) {
+    if (this.isAdmin) {
+      return { granted: true, reason: "admin_bypass" };
+    }
+    if (this.permissions.has(permission)) {
+      return { granted: true, reason: "permission_found" };
+    }
+    return { granted: false, reason: "permission_missing" };
+  }
+};
+
+// src/core/create-permissions.ts
+function createPermissions(definition) {
+  const frozen = { ...definition };
+  for (const key of Object.keys(frozen)) {
+    frozen[key] = Object.freeze(
+      frozen[key]
+    );
+  }
+  return Object.freeze(frozen);
+}
+export {
+  PermissionChecker,
+  createPermissions
+};
+//# sourceMappingURL=index.js.map

package/dist/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/core/permission-checker.ts","../../src/core/create-permissions.ts"],"sourcesContent":["import type { PermissionCheckResult, PermissionConfig } from \"./types\";\n\n/**\n * Pure TypeScript permission checker — no React dependency.\n *\n * @example\n * const checker = new PermissionChecker({\n *   permissions: [\"users.read\", \"users.create\"],\n *   userType: \"USER\",\n * });\n *\n * checker.hasPermission(\"users.read\"); // true\n * checker.hasPermission(\"users.delete\"); // false\n */\nexport class PermissionChecker {\n  private readonly permissions: Set<string>;\n  private readonly isAdmin: boolean;\n\n  constructor(config: PermissionConfig) {\n    this.permissions = new Set(config.permissions);\n    const adminTypes = config.adminTypes ?? [\"ADMIN\"];\n    const bypass = config.adminBypass ?? true;\n    this.isAdmin = bypass && adminTypes.includes(config.userType ?? \"\");\n  }\n\n  /** Whether this checker was created with an admin-type user */\n  get admin(): boolean {\n    return this.isAdmin;\n  }\n\n  /** Check if user has a specific permission. Admins always return true. */\n  hasPermission(permission: string): boolean {\n    if (this.isAdmin) return true;\n    return this.permissions.has(permission);\n  }\n\n  /** Check if user has ANY of the given permissions. Admins always return true. */\n  hasAnyPermission(permissionList: string[]): boolean {\n    if (this.isAdmin) return true;\n    return permissionList.some((p) => this.permissions.has(p));\n  }\n\n  /** Check if user has ALL of the given permissions. Admins always return true. */\n  hasAllPermissions(permissionList: string[]): boolean {\n    if (this.isAdmin) return true;\n    return permissionList.every((p) => this.permissions.has(p));\n  }\n\n  /** Detailed permission check with reason for the result */\n  check(permission: string): PermissionCheckResult {\n    if (this.isAdmin) {\n      return { granted: true, reason: \"admin_bypass\" };\n    }\n\n    if (this.permissions.has(permission)) {\n      return { granted: true, reason: \"permission_found\" };\n    }\n\n    return { granted: false, reason: \"permission_missing\" };\n  }\n}\n","import type { DeepReadonly } from \"./types\";\n\n/**\n * Type-safe helper to define permission constants with literal types.\n * Returns a deeply frozen, readonly object.\n *\n * @example\n * const PERMISSIONS = createPermissions({\n *   USERS: {\n *     READ: \"system.users.read\",\n *     CREATE: \"system.users.create\",\n *   },\n *   GROUPS: {\n *     READ: \"system.groups.read\",\n *   },\n * });\n *\n * // typeof PERMISSIONS.USERS.READ → \"system.users.read\" (literal type)\n */\nexport function createPermissions<\n  T extends Record<string, Record<string, string>>,\n>(definition: T): DeepReadonly<T> {\n  const frozen = { ...definition };\n\n  for (const key of Object.keys(frozen)) {\n    (frozen as Record<string, unknown>)[key] = Object.freeze(\n      (frozen as Record<string, Record<string, string>>)[key],\n    );\n  }\n\n  return Object.freeze(frozen) as DeepReadonly<T>;\n}\n\n/** Extracts all permission string values from a createPermissions() result */\nexport type ExtractPermissions<T> =\n  T extends Record<string, Record<string, infer V>> ? V : never;\n"],"mappings":";AAcO,IAAM,oBAAN,MAAwB;AAAA,EAI7B,YAAY,QAA0B;AACpC,SAAK,cAAc,IAAI,IAAI,OAAO,WAAW;AAC7C,UAAM,aAAa,OAAO,cAAc,CAAC,OAAO;AAChD,UAAM,SAAS,OAAO,eAAe;AACrC,SAAK,UAAU,UAAU,WAAW,SAAS,OAAO,YAAY,EAAE;AAAA,EACpE;AAAA;AAAA,EAGA,IAAI,QAAiB;AACnB,WAAO,KAAK;AAAA,EACd;AAAA;AAAA,EAGA,cAAc,YAA6B;AACzC,QAAI,KAAK,QAAS,QAAO;AACzB,WAAO,KAAK,YAAY,IAAI,UAAU;AAAA,EACxC;AAAA;AAAA,EAGA,iBAAiB,gBAAmC;AAClD,QAAI,KAAK,QAAS,QAAO;AACzB,WAAO,eAAe,KAAK,CAAC,MAAM,KAAK,YAAY,IAAI,CAAC,CAAC;AAAA,EAC3D;AAAA;AAAA,EAGA,kBAAkB,gBAAmC;AACnD,QAAI,KAAK,QAAS,QAAO;AACzB,WAAO,eAAe,MAAM,CAAC,MAAM,KAAK,YAAY,IAAI,CAAC,CAAC;AAAA,EAC5D;AAAA;AAAA,EAGA,MAAM,YAA2C;AAC/C,QAAI,KAAK,SAAS;AAChB,aAAO,EAAE,SAAS,MAAM,QAAQ,eAAe;AAAA,IACjD;AAEA,QAAI,KAAK,YAAY,IAAI,UAAU,GAAG;AACpC,aAAO,EAAE,SAAS,MAAM,QAAQ,mBAAmB;AAAA,IACrD;AAEA,WAAO,EAAE,SAAS,OAAO,QAAQ,qBAAqB;AAAA,EACxD;AACF;;;ACzCO,SAAS,kBAEd,YAAgC;AAChC,QAAM,SAAS,EAAE,GAAG,WAAW;AAE/B,aAAW,OAAO,OAAO,KAAK,MAAM,GAAG;AACrC,IAAC,OAAmC,GAAG,IAAI,OAAO;AAAA,MAC/C,OAAkD,GAAG;AAAA,IACxD;AAAA,EACF;AAEA,SAAO,OAAO,OAAO,MAAM;AAC7B;","names":[]}