factor-based-permissions 0.0.3 → 0.0.4

package/README.md

@@ -0,0 +1,439 @@
+# Factor-Based Permissions (TypeScript)
+
+A lightweight TypeScript library for **parsing and checking** factor-based permissions on the client side. Designed to work with permissions serialized by the [C# Factor-Based Permissions](../CSharp/README.md) library and embedded in JWT tokens.
+
+## Why This Library?
+
+When using factor-based permissions with JWTs:
+
+1. **Server** (C#) creates and serializes permissions into a compact string
+2. **JWT** carries this string in a claim (typically 30-50 characters)
+3. **Client** (TypeScript) parses and checks permissions for UI decisions
+
+This library handles step 3 — fast, dependency-free permission checking in the browser.
+
+## Installation
+
+```bash
+npm install factor-based-permissions
+```
+
+## Quick Start
+
+### 1. Extract Serialized Permissions from JWT
+
+```typescript
+import { FactorBasedPermissions } from "factor-based-permissions";
+
+// Assuming you've decoded your JWT and extracted the "ap" claim
+const serialized = decodedJwt.ap; // e.g., "!1,3#1+1&2+1,3"
+
+const permissions = new FactorBasedPermissions(serialized);
+```
+
+### 2. Check Permissions
+
+```typescript
+// Define your permission enum (matching server-side values)
+enum Permission {
+  ViewDashboard = 1,
+  DownloadReports = 2,
+  ManageApiKeys = 3,
+  AccessAdminPanel = 4,
+}
+
+// Check if permission is granted
+const canDownload = permissions.checkPermission(Permission.DownloadReports);
+
+if (canDownload === true) {
+  // Permission granted — all required factors satisfied
+  showDownloadButton();
+} else if (canDownload === false) {
+  // Permission exists but factors not satisfied
+  showDownloadButtonDisabled();
+} else {
+  // canDownload === null — permission not in policy
+  hideDownloadButton();
+}
+```
+
+### 3. Show Missing Requirements to User
+
+```typescript
+enum Factor {
+  EmailVerified = 1,
+  PhoneVerified = 2,
+  SubscriptionActive = 3,
+  TwoFactorEnabled = 4,
+}
+
+const missing = permissions.getMissingFactors(Permission.ManageApiKeys);
+
+if (missing.length > 0) {
+  // Show user what they need to do
+  const messages = missing.map((factor) => {
+    switch (factor) {
+      case Factor.EmailVerified:
+        return "Verify your email";
+      case Factor.TwoFactorEnabled:
+        return "Enable two-factor authentication";
+      default:
+        return "Complete verification";
+    }
+  });
+
+  showRequirementsDialog(messages);
+}
+```
+
+## API Reference
+
+### Constructor
+
+```typescript
+new FactorBasedPermissions<TFactor extends number, TPermission extends number>(
+  serialized?: string | null | undefined
+)
+```
+
+Creates a new instance. If `serialized` is provided, parses the permission data immediately.
+
+```typescript
+// With data
+const permissions = new FactorBasedPermissions("!1,3#1+1&2+1,3");
+
+// Empty instance (all checks return null)
+const empty = new FactorBasedPermissions();
+const alsoEmpty = new FactorBasedPermissions(null);
+```
+
+### checkPermission
+
+```typescript
+checkPermission(permission: TPermission): boolean | null
+```
+
+Check if a permission is granted.
+
+| Return Value | Meaning |
+|--------------|---------|
+| `true` | Permission exists and all required factors are satisfied |
+| `false` | Permission exists but some required factors are missing |
+| `null` | Permission is not defined in the policy |
+
+```typescript
+const result = permissions.checkPermission(Permission.DownloadReports);
+
+// Use in conditionals
+if (result === true) {
+  // Granted
+}
+
+// Truthy check (true only)
+if (result) {
+  // Granted
+}
+
+// Falsy check catches both false and null
+if (!result) {
+  // Not granted (either missing factors or not in policy)
+}
+```
+
+### getSatisfiedFactors
+
+```typescript
+getSatisfiedFactors(permission?: TPermission): TFactor[]
+```
+
+Get satisfied factors, optionally filtered by a specific permission.
+
+```typescript
+// All satisfied factors
+const allSatisfied = permissions.getSatisfiedFactors();
+// [1, 3] (Factor.EmailVerified, Factor.SubscriptionActive)
+
+// Satisfied factors relevant to a specific permission
+const satisfiedForDownload = permissions.getSatisfiedFactors(Permission.DownloadReports);
+// [1, 3] if permission requires factors 1 and 3, and both are satisfied
+```
+
+### getMissingFactors
+
+```typescript
+getMissingFactors(permission: TPermission): TFactor[]
+```
+
+Get factors that are required for a permission but not satisfied.
+
+```typescript
+const missing = permissions.getMissingFactors(Permission.ManageApiKeys);
+// [4] if ManageApiKeys requires factors 1 and 4, but only 1 is satisfied
+```
+
+### serialized
+
+```typescript
+get serialized(): string
+```
+
+Returns the original serialized string (useful for passing to other contexts).
+
+```typescript
+const original = permissions.serialized;
+// "!1,3#1+1&2+1,3"
+```
+
+## Serialization Format
+
+The format is identical to the C# library:
+
+```
+[!<satisfied_factors>][#<permission_groups>]
+```
+
+Both sections are **optional**:
+- If no factors are satisfied, the `!...` section is omitted
+- If no permissions are defined, the `#...` section is omitted
+- An empty policy serializes to an empty string `""`
+
+### Example
+
+```
+!1,3#1+1&2+1,3&3+1,4
+```
+
+Breakdown:
+- `!1,3` — Factors 1 and 3 are satisfied
+- `#1+1` — Permission 1 requires factor 1
+- `&2+1,3` — Permission 2 requires factors 1 and 3
+- `&3+1,4` — Permission 3 requires factors 1 and 4
+
+### Number Encoding
+
+Numbers are encoded in **Base32** (characters `0-9` and `a-v`):
+
+```typescript
+// The library handles this automatically via parseInt(value, 32)
+parseInt("v8", 32); // 1000
+parseInt("10", 32); // 32
+```
+
+## Usage Patterns
+
+### React Hook
+
+```typescript
+import { useMemo } from "react";
+import { FactorBasedPermissions } from "factor-based-permissions";
+
+function usePermissions(serialized: string | null) {
+  return useMemo(
+    () => new FactorBasedPermissions(serialized),
+    [serialized]
+  );
+}
+
+// In component
+function Dashboard() {
+  const { accessPolicies } = useAuth(); // Get from JWT/context
+  const permissions = usePermissions(accessPolicies);
+
+  return (
+    <div>
+      {permissions.checkPermission(Permission.ViewDashboard) && (
+        <DashboardContent />
+      )}
+      {permissions.checkPermission(Permission.DownloadReports) && (
+        <DownloadButton />
+      )}
+    </div>
+  );
+}
+```
+
+### Permission Guard Component
+
+```typescript
+interface PermissionGuardProps {
+  permission: Permission;
+  permissions: FactorBasedPermissions<Factor, Permission>;
+  children: React.ReactNode;
+  fallback?: React.ReactNode;
+  onMissingFactors?: (factors: Factor[]) => void;
+}
+
+function PermissionGuard({
+  permission,
+  permissions,
+  children,
+  fallback = null,
+  onMissingFactors,
+}: PermissionGuardProps) {
+  const result = permissions.checkPermission(permission);
+
+  if (result === true) {
+    return <>{children}</>;
+  }
+
+  if (result === false && onMissingFactors) {
+    const missing = permissions.getMissingFactors(permission);
+    onMissingFactors(missing);
+  }
+
+  return <>{fallback}</>;
+}
+
+// Usage
+<PermissionGuard
+  permission={Permission.ManageApiKeys}
+  permissions={permissions}
+  fallback={<UpgradePrompt />}
+  onMissingFactors={(factors) => trackMissingFactors(factors)}
+>
+  <ApiKeysManager />
+</PermissionGuard>
+```
+
+### Vue Composable
+
+```typescript
+import { computed, type Ref } from "vue";
+import { FactorBasedPermissions } from "factor-based-permissions";
+
+export function usePermissions(serialized: Ref<string | null>) {
+  const permissions = computed(
+    () => new FactorBasedPermissions(serialized.value)
+  );
+
+  const can = (permission: Permission) =>
+    permissions.value.checkPermission(permission) === true;
+
+  const cannot = (permission: Permission) =>
+    permissions.value.checkPermission(permission) !== true;
+
+  const missingFor = (permission: Permission) =>
+    permissions.value.getMissingFactors(permission);
+
+  return { permissions, can, cannot, missingFor };
+}
+```
+
+### Utility Functions
+
+```typescript
+// Check multiple permissions at once
+function hasAllPermissions(
+  permissions: FactorBasedPermissions<Factor, Permission>,
+  required: Permission[]
+): boolean {
+  return required.every((p) => permissions.checkPermission(p) === true);
+}
+
+// Check if any permission is granted
+function hasAnyPermission(
+  permissions: FactorBasedPermissions<Factor, Permission>,
+  required: Permission[]
+): boolean {
+  return required.some((p) => permissions.checkPermission(p) === true);
+}
+
+// Get all granted permissions from a list
+function getGrantedPermissions(
+  permissions: FactorBasedPermissions<Factor, Permission>,
+  toCheck: Permission[]
+): Permission[] {
+  return toCheck.filter((p) => permissions.checkPermission(p) === true);
+}
+```
+
+## Type Safety
+
+The library uses generics for type-safe factor and permission IDs:
+
+```typescript
+// Define your enums
+enum Factor {
+  EmailVerified = 1,
+  SubscriptionActive = 3,
+}
+
+enum Permission {
+  ViewDashboard = 1,
+  DownloadReports = 2,
+}
+
+// Type-safe usage
+const permissions = new FactorBasedPermissions<Factor, Permission>(serialized);
+
+// TypeScript knows these return Factor[]
+const satisfied: Factor[] = permissions.getSatisfiedFactors();
+const missing: Factor[] = permissions.getMissingFactors(Permission.DownloadReports);
+
+// TypeScript enforces Permission type
+permissions.checkPermission(Permission.ViewDashboard); // OK
+permissions.checkPermission(999); // OK (number), but semantically wrong
+```
+
+## Caching
+
+The library automatically caches permission check results:
+
+```typescript
+const permissions = new FactorBasedPermissions(serialized);
+
+// First call: computes and caches result
+permissions.checkPermission(Permission.ViewDashboard);
+
+// Subsequent calls: returns cached result (O(1))
+permissions.checkPermission(Permission.ViewDashboard);
+permissions.checkPermission(Permission.ViewDashboard);
+```
+
+## Important Notes
+
+### This Library Does NOT Serialize
+
+This is a **read-only** library. It parses and checks permissions but cannot create or modify them. Serialization should only happen on the server (C#) where the source of truth for factors and permissions resides.
+
+```typescript
+// ❌ Not supported
+permissions.addFactor(Factor.EmailVerified);
+permissions.serialize();
+
+// ✅ Correct pattern
+// 1. Client requests server to perform action
+// 2. Server updates factors, creates new permissions
+// 3. Server issues new JWT with updated "ap" claim
+// 4. Client receives new JWT and re-creates FactorBasedPermissions
+```
+
+### Always Validate on Server
+
+Client-side permission checks are for **UI purposes only**. Always validate permissions on the server before performing sensitive operations:
+
+```typescript
+// Client: Show/hide UI based on permissions
+if (permissions.checkPermission(Permission.DeleteUser)) {
+  showDeleteButton();
+}
+
+// Server: ALWAYS verify before actually deleting
+app.delete("/users/:id", authorize(Permission.DeleteUser), (req, res) => {
+  // Server-side check happens in authorize middleware
+  deleteUser(req.params.id);
+});
+```
+
+## Browser Support
+
+- All modern browsers (ES2015+)
+- Node.js 14+
+
+## Bundle Size
+
+~1KB minified (no dependencies)
+
+## License
+
+MIT

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAmBA,qBAAa,sBAAsB,CAAC,OAAO,SAAS,MAAM,EAAE,WAAW,SAAS,MAAM;IACpF,OAAO,CAAC,iBAAiB,CAAsB;IAC/C,OAAO,CAAC,kBAAkB,CAAqC;IAC/D,OAAO,CAAC,sBAAsB,CAA0C;IACxE,OAAO,CAAC,WAAW,CAAM;gBAEN,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS;IASzD,OAAO,CAAC,sBAAsB;IAU9B,OAAO,CAAC,iBAAiB;IAclB,eAAe,CAAC,UAAU,EAAE,WAAW;IAuBvC,mBAAmB,CAAC,UAAU,CAAC,EAAE,WAAW;IAa5C,iBAAiB,CAAC,UAAU,EAAE,WAAW;IAUhD,IAAW,UAAU,WAEpB;CACF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAmBA,qBAAa,sBAAsB,CAAC,OAAO,SAAS,MAAM,EAAE,WAAW,SAAS,MAAM;IACpF,OAAO,CAAC,iBAAiB,CAAsB;IAC/C,OAAO,CAAC,kBAAkB,CAAqC;IAC/D,OAAO,CAAC,sBAAsB,CAA0C;IACxE,OAAO,CAAC,WAAW,CAAM;gBAEN,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS;IASzD,OAAO,CAAC,sBAAsB;IAU9B,OAAO,CAAC,iBAAiB;IAgBlB,eAAe,CAAC,UAAU,EAAE,WAAW;IAuBvC,mBAAmB,CAAC,UAAU,CAAC,EAAE,WAAW;IAa5C,iBAAiB,CAAC,UAAU,EAAE,WAAW;IAUhD,IAAW,UAAU,WAEpB;CACF"}

package/dist/index.js

@@ -40,7 +40,9 @@ export class FactorBasedPermissions {
         for (const permissionGroup of permissionGroupsGroup.split(GROUP_DELIM)) {
             const [permissionsRaw, requiredFactorsRaw] = permissionGroup.split(REQUIRED_FACTORS_DELIM);
             const permissions = permissionsRaw?.split(ITEMS_DELIM)?.map((parseNumeric)) ?? [];
-            const requiredFactors = requiredFactorsRaw?.split(ITEMS_DELIM)?.map((parseNumeric)) ?? [];
+            const requiredFactors = requiredFactorsRaw
+                ? requiredFactorsRaw.split(ITEMS_DELIM).map((parseNumeric))
+                : [];
             for (const permission of permissions)
                 this._permissionsLookup.set(permission, requiredFactors);
         }
@@ -63,7 +65,7 @@ export class FactorBasedPermissions {
         return true;
     }
     getSatisfiedFactors(permission) {
-        if (!permission)
+        if (permission === undefined)
             return [...this._satisfiedFactors];
         const cachedResult = this._permissionCheckLookup.get(permission);
         const requiredFactors = this._permissionsLookup.get(permission) ?? [];

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,MAAM,wBAAwB,GAAG,GAAG,CAAC;AACrC,MAAM,kBAAkB,GAAG,GAAG,CAAC;AAC/B,MAAM,WAAW,GAAG,GAAG,CAAC;AACxB,MAAM,WAAW,GAAG,GAAG,CAAC;AACxB,MAAM,sBAAsB,GAAG,GAAG,CAAC;AAEnC,MAAM,WAAW,GAAG,gBAAgB,EAAE,CAAC;AAEvC,SAAS,gBAAgB;IACvB,MAAM,aAAa,GAAG,wBAAwB,GAAG,kBAAkB,CAAC;IACpE,MAAM,qBAAqB,GAAG,MAAM,wBAAwB,MAAM,aAAa,OAAO,CAAC;IACvF,MAAM,qBAAqB,GAAG,MAAM,kBAAkB,MAAM,aAAa,OAAO,CAAC;IACjF,OAAO,IAAI,MAAM,CAAC,qBAAqB,GAAG,qBAAqB,CAAC,CAAC;AACnE,CAAC;AAED,SAAS,YAAY,CAAmB,KAAa;IACnD,OAAO,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAM,CAAC;AAClC,CAAC;AAED,MAAM,OAAO,sBAAsB;IACzB,iBAAiB,GAAG,IAAI,GAAG,EAAW,CAAC;IACvC,kBAAkB,GAAG,IAAI,GAAG,EAA0B,CAAC;IACvD,sBAAsB,GAAG,IAAI,GAAG,EAA+B,CAAC;IAChE,WAAW,GAAG,EAAE,CAAC;IAEzB,YAAmB,UAAsC;QACvD,IAAI,OAAO,UAAU,KAAK,QAAQ,EAAE,CAAC;YACnC,MAAM,OAAO,GAAG,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YAC7C,IAAI,CAAC,sBAAsB,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC;YAClD,IAAI,CAAC,iBAAiB,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC;YAC7C,IAAI,CAAC,WAAW,GAAG,UAAU,CAAC;QAChC,CAAC;IACH,CAAC;IAEO,sBAAsB,CAAC,qBAAoC;QACjE,IAAI,CAAC,qBAAqB;YACxB,OAAO;QAET,KAAK,MAAM,MAAM,IAAI,qBAAqB,CAAC,KAAK,CAAC,WAAW,CAAC,EAAE,CAAC;YAC9D,MAAM,aAAa,GAAG,YAAY,CAAU,MAAM,CAAC,CAAC;YACpD,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;QAC5C,CAAC;IACH,CAAC;IAEO,iBAAiB,CAAC,qBAAoC;QAC5D,IAAI,CAAC,qBAAqB;YACxB,OAAO;QAET,KAAK,MAAM,eAAe,IAAI,qBAAqB,CAAC,KAAK,CAAC,WAAW,CAAC,EAAE,CAAC;YACvE,MAAM,CAAC,cAAc,EAAE,kBAAkB,CAAC,GAAG,eAAe,CAAC,KAAK,CAAC,sBAAsB,CAAC,CAAC;YAC3F,MAAM,WAAW,GAAG,cAAc,EAAE,KAAK,CAAC,WAAW,CAAC,EAAE,GAAG,CAAC,CAAA,YAAyB,CAAA,CAAC,IAAI,EAAE,CAAC;YAC7F,MAAM,eAAe,GAAG,kBAAkB;gBACxC,CAAC,CAAC,kBAAkB,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,GAAG,CAAC,CAAA,YAAqB,CAAA,CAAC;gBAClE,CAAC,CAAC,EAAE,CAAC;YAEP,KAAK,MAAM,UAAU,IAAI,WAAW;gBAClC,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,UAAU,EAAE,eAAe,CAAC,CAAC;QAC7D,CAAC;IACH,CAAC;IAEM,eAAe,CAAC,UAAuB;QAC5C,MAAM,YAAY,GAAG,IAAI,CAAC,sBAAsB,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QAEjE,IAAI,YAAY,KAAK,SAAS;YAC5B,OAAO,YAAY,CAAC;QAEtB,MAAM,eAAe,GAAG,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QAEhE,IAAI,CAAC,eAAe,EAAE,CAAC;YACrB,IAAI,CAAC,sBAAsB,CAAC,GAAG,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;YAClD,OAAO,IAAI,CAAC;QACd,CAAC;QAED,KAAK,MAAM,cAAc,IAAI,eAAe;YAC1C,IAAI,CAAC,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,cAAc,CAAC,EAAE,CAAC;gBAChD,IAAI,CAAC,sBAAsB,CAAC,GAAG,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;gBACnD,OAAO,KAAK,CAAC;YACf,CAAC;QAEH,IAAI,CAAC,sBAAsB,CAAC,GAAG,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;QAClD,OAAO,IAAI,CAAC;IACd,CAAC;IAEM,mBAAmB,CAAC,UAAwB;QACjD,IAAI,UAAU,KAAK,SAAS;YAC1B,OAAO,CAAC,GAAG,IAAI,CAAC,iBAAiB,CAAC,CAAC;QAErC,MAAM,YAAY,GAAG,IAAI,CAAC,sBAAsB,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QACjE,MAAM,eAAe,GAAG,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC;QAEtE,IAAI,YAAY,KAAK,IAAI;YACvB,OAAO,eAAe,CAAC;QAEzB,OAAO,eAAe,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;IAChF,CAAC;IAEM,iBAAiB,CAAC,UAAuB;QAC9C,MAAM,YAAY,GAAG,IAAI,CAAC,sBAAsB,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QAEjE,IAAI,YAAY,KAAK,IAAI;YACvB,OAAO,EAAE,CAAC;QAEZ,MAAM,eAAe,GAAG,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC;QACtE,OAAO,eAAe,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;IACjF,CAAC;IAED,IAAW,UAAU;QACnB,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;CACF"}

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "factor-based-permissions",
-  "version": "0.0.3",
-  "description": "",
+  "version": "0.0.4",
+  "description": "Lightweight library for parsing and checking factor-based permissions from JWT tokens",
   "license": "MIT",
   "author": "0x2E757",
   "type": "module",
   "files": [
+    "src",
     "dist"
   ],
   "main": "dist/index.js",

package/src/index.ts

@@ -0,0 +1,110 @@
+const SATISFIED_FACTORS_PREFIX = "!";
+const PERMISSIONS_PREFIX = "#";
+const ITEMS_DELIM = ",";
+const GROUP_DELIM = "&";
+const REQUIRED_FACTORS_DELIM = "+";
+
+const groupsRegex = buildGroupsRegex();
+
+function buildGroupsRegex() {
+  const groupPrefixes = SATISFIED_FACTORS_PREFIX + PERMISSIONS_PREFIX;
+  const satisfiedFactorsGroup = `(?:${SATISFIED_FACTORS_PREFIX}([^${groupPrefixes}]*))?`;
+  const permissionGroupsGroup = `(?:${PERMISSIONS_PREFIX}([^${groupPrefixes}]*))?`;
+  return new RegExp(satisfiedFactorsGroup + permissionGroupsGroup);
+}
+
+function parseNumeric<T extends number>(value: string) {
+  return parseInt(value, 32) as T;
+}
+
+export class FactorBasedPermissions<TFactor extends number, TPermission extends number> {
+  private _satisfiedFactors = new Set<TFactor>();
+  private _permissionsLookup = new Map<TPermission, TFactor[]>();
+  private _permissionCheckLookup = new Map<TPermission, boolean | null>();
+  private _serialized = "";
+
+  public constructor(serialized?: string | null | undefined) {
+    if (typeof serialized === "string") {
+      const matches = groupsRegex.exec(serialized);
+      this._parseSatisfiedFactors(matches?.[1] ?? null);
+      this._parsePermissions(matches?.[2] ?? null);
+      this._serialized = serialized;
+    }
+  }
+
+  private _parseSatisfiedFactors(satisfiedFactorsGroup: string | null) {
+    if (!satisfiedFactorsGroup)
+      return;
+
+    for (const factor of satisfiedFactorsGroup.split(ITEMS_DELIM)) {
+      const factorNumeric = parseNumeric<TFactor>(factor);
+      this._satisfiedFactors.add(factorNumeric);
+    }
+  }
+
+  private _parsePermissions(permissionGroupsGroup: string | null) {
+    if (!permissionGroupsGroup)
+      return;
+
+    for (const permissionGroup of permissionGroupsGroup.split(GROUP_DELIM)) {
+      const [permissionsRaw, requiredFactorsRaw] = permissionGroup.split(REQUIRED_FACTORS_DELIM);
+      const permissions = permissionsRaw?.split(ITEMS_DELIM)?.map(parseNumeric<TPermission>) ?? [];
+      const requiredFactors = requiredFactorsRaw
+        ? requiredFactorsRaw.split(ITEMS_DELIM).map(parseNumeric<TFactor>)
+        : [];
+
+      for (const permission of permissions)
+        this._permissionsLookup.set(permission, requiredFactors);
+    }
+  }
+
+  public checkPermission(permission: TPermission) {
+    const cachedResult = this._permissionCheckLookup.get(permission);
+
+    if (cachedResult !== undefined)
+      return cachedResult;
+
+    const requiredFactors = this._permissionsLookup.get(permission);
+
+    if (!requiredFactors) {
+      this._permissionCheckLookup.set(permission, null);
+      return null;
+    }
+
+    for (const requiredFactor of requiredFactors)
+      if (!this._satisfiedFactors.has(requiredFactor)) {
+        this._permissionCheckLookup.set(permission, false);
+        return false;
+      }
+
+    this._permissionCheckLookup.set(permission, true);
+    return true;
+  }
+
+  public getSatisfiedFactors(permission?: TPermission) {
+    if (permission === undefined)
+      return [...this._satisfiedFactors];
+
+    const cachedResult = this._permissionCheckLookup.get(permission);
+    const requiredFactors = this._permissionsLookup.get(permission) ?? [];
+
+    if (cachedResult === true)
+      return requiredFactors;
+
+    return requiredFactors.filter((factor) => this._satisfiedFactors.has(factor));
+  }
+
+  public getMissingFactors(permission: TPermission) {
+    const cachedResult = this._permissionCheckLookup.get(permission);
+
+    if (cachedResult === true)
+      return [];
+
+    const requiredFactors = this._permissionsLookup.get(permission) ?? [];
+    return requiredFactors.filter((factor) => !this._satisfiedFactors.has(factor));
+  }
+
+  public get serialized() {
+    return this._serialized;
+  }
+}