hazo_auth 4.6.2 → 4.6.3

package/README.md

@@ -1102,6 +1102,9 @@ The `UserManagementLayout` component provides a comprehensive admin interface fo
 - `admin_user_management` - Access to Users tab
 - `admin_role_management` - Access to Roles tab
 - `admin_permission_management` - Access to Permissions tab
+- `admin_scope_hierarchy_management` - Access to Scope Hierarchy tab (HRBAC)
+- `admin_system` - Access to Scope Labels tab (HRBAC)
+- `admin_user_scope_assignment` - Access to User Scopes tab (HRBAC)
 
 **Required API Routes:**
 The `UserManagementLayout` component requires the following API routes to be created in your project:
@@ -1735,7 +1738,8 @@ Users assigned to a higher-level scope automatically have access to all descenda
 
 ### Required Permissions for Management
 
-- `admin_scope_hierarchy_management` - Manage scopes and scope labels
+- `admin_scope_hierarchy_management` - Manage scope hierarchy (create, edit, delete scopes)
+- `admin_system` - System-level administration (scope labels configuration)
 - `admin_user_scope_assignment` - Assign scopes to users
 - `admin_test_access` - Access the RBAC/HRBAC test tool
 
@@ -1743,15 +1747,19 @@ Add these to your `application_permission_list_defaults` in `hazo_auth_config.in
 
 ```ini
 [hazo_auth__user_management]
-application_permission_list_defaults = admin_user_management,admin_role_management,admin_permission_management,admin_scope_hierarchy_management,admin_user_scope_assignment,admin_test_access
+application_permission_list_defaults = admin_user_management,admin_role_management,admin_permission_management,admin_scope_hierarchy_management,admin_system,admin_user_scope_assignment,admin_test_access
 ```
 
 ### User Management UI
 
 When HRBAC is enabled and the user has appropriate permissions, three new tabs appear in the User Management layout:
-- **Scope Hierarchy** - Create, edit, and delete scopes at each level
-- **Scope Labels** - Customize labels for scope levels per organization
-- **User Scopes** - Assign and remove scope assignments for users
+- **Scope Hierarchy** - Create, edit, and delete scopes at each level (requires `admin_scope_hierarchy_management`)
+- **Scope Labels** - Customize labels for scope levels per organization (requires `admin_system`)
+- **User Scopes** - Assign and remove scope assignments for users (requires `admin_user_scope_assignment`)
+
+**Organization Assignment (when multi-tenancy enabled):**
+- **Global admins** (`hazo_org_global_admin` permission) can assign users to any organization
+- **Non-global admins** can only assign users to organizations within their own org tree (filtered by `root_org_id`)
 
 ### RBAC/HRBAC Test Tool
 

package/cli-src/lib/app_permissions_config.server.ts

@@ -0,0 +1,94 @@
+// file_description: server-only helper to read app permissions configuration from hazo_auth_config.ini
+// This allows consuming apps to declare their required permissions with descriptions for debugging
+// section: imports
+import { read_config_section } from "./config/config_loader.server.js";
+
+// section: types
+
+/**
+ * A single app permission declaration
+ */
+export type AppPermission = {
+  permission_name: string;
+  description: string;
+};
+
+/**
+ * App permissions configuration
+ */
+export type AppPermissionsConfig = {
+  permissions: AppPermission[];
+  permissions_map: Map<string, string>; // permission_name -> description
+};
+
+// section: helpers
+
+/**
+ * Reads app permissions configuration from hazo_auth_config.ini file
+ * Format in INI file:
+ *   [hazo_auth__app_permissions]
+ *   app_permission_1 = permission_name:Description for debugging
+ *   app_permission_2 = another_perm:Another description
+ *
+ * @returns App permissions configuration with list and map of permissions
+ */
+export function get_app_permissions_config(): AppPermissionsConfig {
+  const section = read_config_section("hazo_auth__app_permissions");
+  const permissions: AppPermission[] = [];
+  const permissions_map = new Map<string, string>();
+
+  if (section) {
+    // Iterate through all keys in section that start with "app_permission_"
+    for (const [key, value] of Object.entries(section)) {
+      if (key.startsWith("app_permission_") && typeof value === "string") {
+        const colonIndex = value.indexOf(":");
+        if (colonIndex > 0) {
+          const permission_name = value.substring(0, colonIndex).trim();
+          const description = value.substring(colonIndex + 1).trim();
+          if (permission_name && description) {
+            permissions.push({ permission_name, description });
+            permissions_map.set(permission_name, description);
+          }
+        }
+      }
+    }
+  }
+
+  return {
+    permissions,
+    permissions_map,
+  };
+}
+
+/**
+ * Gets the description for a specific permission
+ * @param permission_name - The permission name to look up
+ * @returns Description or undefined if not found in app permissions config
+ */
+export function get_app_permission_description(
+  permission_name: string,
+): string | undefined {
+  const config = get_app_permissions_config();
+  return config.permissions_map.get(permission_name);
+}
+
+/**
+ * Gets descriptions for multiple permissions
+ * @param permission_names - Array of permission names to look up
+ * @returns Map of permission names to descriptions (only includes found permissions)
+ */
+export function get_app_permission_descriptions(
+  permission_names: string[],
+): Map<string, string> {
+  const config = get_app_permissions_config();
+  const result = new Map<string, string>();
+
+  for (const name of permission_names) {
+    const description = config.permissions_map.get(name);
+    if (description) {
+      result.set(name, description);
+    }
+  }
+
+  return result;
+}

package/cli-src/lib/auth/auth_types.ts

@@ -100,6 +100,7 @@ export type HazoAuthOptions = {
 /**
  * Custom error class for permission denials
  * Includes technical and user-friendly error messages
+ * Optionally includes permission descriptions for debugging
  */
 export class PermissionError extends Error {
   constructor(
@@ -107,6 +108,7 @@ export class PermissionError extends Error {
     public user_permissions: string[],
     public required_permissions: string[],
     public user_friendly_message?: string,
+    public permission_descriptions?: Map<string, string>,
   ) {
     super(`Missing permissions: ${missing_permissions.join(", ")}`);
     this.name = "PermissionError";

package/cli-src/lib/auth/hazo_get_auth.server.ts

@@ -18,6 +18,7 @@ import { is_valid_scope_level, type ScopeLevel } from "../services/scope_service
 import { is_multi_tenancy_enabled, get_multi_tenancy_config } from "../multi_tenancy_config.server.js";
 import { get_org_cache, type OrgCacheEntry } from "./org_cache.js";
 import { get_cookie_name, BASE_COOKIE_NAMES } from "../cookies_config.server.js";
+import { get_app_permission_descriptions } from "../app_permissions_config.server.js";
 
 // section: helpers
 
@@ -544,12 +545,15 @@ export async function hazo_get_auth(
         missing_permissions,
         config,
       );
+      // Include permission descriptions for debugging
+      const permission_descriptions = get_app_permission_descriptions(missing_permissions);
 
       throw new PermissionError(
         missing_permissions,
         permissions,
         options.required_permissions,
         friendly_message,
+        permission_descriptions,
       );
     }
   }

package/dist/app/api/hazo_auth/user_management/users/route.d.ts

@@ -26,6 +26,7 @@ export declare function GET(request: NextRequest): Promise<NextResponse<{
         profile_picture_url: {} | null;
         profile_source: {} | null;
         user_type: string | null;
+        app_user_data: Record<string, unknown> | null;
         org_id: string | null | undefined;
         root_org_id: string | null | undefined;
     }[];

package/dist/app/api/hazo_auth/user_management/users/route.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../../../../../src/app/api/hazo_auth/user_management/users/route.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAsBxD,eAAO,MAAM,OAAO,kBAAkB,CAAC;AAGvC;;;GAGG;AACH,wBAAsB,GAAG,CAAC,OAAO,EAAE,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;IA+E7C;AAED;;GAEG;AACH,wBAAsB,KAAK,CAAC,OAAO,EAAE,WAAW;;;;IA2L/C;AAED;;GAEG;AACH,wBAAsB,IAAI,CAAC,OAAO,EAAE,WAAW;;;;IA2E9C"}
+{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../../../../../src/app/api/hazo_auth/user_management/users/route.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAsBxD,eAAO,MAAM,OAAO,kBAAkB,CAAC;AAGvC;;;GAGG;AACH,wBAAsB,GAAG,CAAC,OAAO,EAAE,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;IAgG7C;AAED;;GAEG;AACH,wBAAsB,KAAK,CAAC,OAAO,EAAE,WAAW;;;;IA2L/C;AAED;;GAEG;AACH,wBAAsB,IAAI,CAAC,OAAO,EAAE,WAAW;;;;IA2E9C"}

package/dist/app/api/hazo_auth/user_management/users/route.js

@@ -53,21 +53,39 @@ export async function GET(request) {
             user_types_enabled,
             available_user_types,
             multi_tenancy_enabled,
-            users: users.map((user) => ({
-                id: user.id,
-                name: user.name || null,
-                email_address: user.email_address,
-                email_verified: user.email_verified || false,
-                is_active: user.is_active !== false,
-                last_logon: user.last_logon || null,
-                created_at: user.created_at || null,
-                profile_picture_url: user.profile_picture_url || null,
-                profile_source: user.profile_source || null,
-                user_type: user.user_type || null,
-                // Include org info when multi-tenancy is enabled
-                org_id: multi_tenancy_enabled ? user.org_id || null : undefined,
-                root_org_id: multi_tenancy_enabled ? user.root_org_id || null : undefined,
-            })),
+            users: users.map((user) => {
+                // Parse app_user_data if it's a string (JSON stored as TEXT in DB)
+                let app_user_data = null;
+                if (user.app_user_data) {
+                    if (typeof user.app_user_data === "string") {
+                        try {
+                            app_user_data = JSON.parse(user.app_user_data);
+                        }
+                        catch (_a) {
+                            app_user_data = null;
+                        }
+                    }
+                    else {
+                        app_user_data = user.app_user_data;
+                    }
+                }
+                return {
+                    id: user.id,
+                    name: user.name || null,
+                    email_address: user.email_address,
+                    email_verified: user.email_verified || false,
+                    is_active: user.is_active !== false,
+                    last_logon: user.last_logon || null,
+                    created_at: user.created_at || null,
+                    profile_picture_url: user.profile_picture_url || null,
+                    profile_source: user.profile_source || null,
+                    user_type: user.user_type || null,
+                    app_user_data,
+                    // Include org info when multi-tenancy is enabled
+                    org_id: multi_tenancy_enabled ? user.org_id || null : undefined,
+                    root_org_id: multi_tenancy_enabled ? user.root_org_id || null : undefined,
+                };
+            }),
         }, { status: 200 });
     }
     catch (error) {

package/dist/components/layouts/shared/components/standalone_layout_wrapper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"standalone_layout_wrapper.d.ts","sourceRoot":"","sources":["../../../../../src/components/layouts/shared/components/standalone_layout_wrapper.tsx"],"names":[],"mappings":"AAMA,OAAO,EAAc,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAGjE,MAAM,MAAM,4BAA4B,GAAG;IACzC,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,yDAAyD;IACzD,MAAM,CAAC,EAAE,eAAe,GAAG,IAAI,CAAC;IAChC,2DAA2D;IAC3D,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,CAAC;AAGF,wBAAgB,uBAAuB,CAAC,EACtC,QAAQ,EACR,OAAqB,EACrB,WAA8E,EAC9E,gBAAgB,EAChB,gBAAgB,EAChB,WAAkB,EAClB,eAAsB,EACtB,MAAM,EACN,cAAqB,GACtB,EAAE,4BAA4B,2CAmD9B"}
+{"version":3,"file":"standalone_layout_wrapper.d.ts","sourceRoot":"","sources":["../../../../../src/components/layouts/shared/components/standalone_layout_wrapper.tsx"],"names":[],"mappings":"AAMA,OAAO,EAAc,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAGjE,MAAM,MAAM,4BAA4B,GAAG;IACzC,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,yDAAyD;IACzD,MAAM,CAAC,EAAE,eAAe,GAAG,IAAI,CAAC;IAChC,2DAA2D;IAC3D,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,CAAC;AAGF,wBAAgB,uBAAuB,CAAC,EACtC,QAAQ,EACR,OAAqB,EACrB,WAA8E,EAC9E,gBAAgB,EAChB,gBAAgB,EAChB,WAAkB,EAClB,eAAsB,EACtB,MAAM,EACN,cAAqB,GACtB,EAAE,4BAA4B,2CAyD9B"}

package/dist/components/layouts/shared/components/standalone_layout_wrapper.js

@@ -11,5 +11,8 @@ export function StandaloneLayoutWrapper({ children, heading = "hazo auth", descr
     const hasNavbar = navbar !== null && navbar !== undefined;
     // Calculate navbar height for vertical centering offset
     const navbarHeight = hasNavbar ? ((_a = navbar === null || navbar === void 0 ? void 0 : navbar.height) !== null && _a !== void 0 ? _a : 64) : 0;
-    return (_jsxs("div", { className: cn("cls_standalone_layout_wrapper flex min-h-screen w-full flex-col bg-background", wrapperClassName), children: [hasNavbar && _jsx(AuthNavbar, Object.assign({}, navbar)), _jsx("div", { className: cn("cls_standalone_layout_content_area flex-1", verticalCenter && "flex items-center justify-center"), style: verticalCenter ? { minHeight: `calc(100vh - ${navbarHeight}px)` } : undefined, children: _jsxs("div", { className: cn("cls_standalone_layout_content mx-auto flex w-full max-w-5xl flex-col gap-8 p-6", contentClassName), children: [(showHeading || showDescription) && (_jsxs("div", { className: "cls_standalone_layout_header text-center", children: [showHeading && (_jsx("h1", { className: "cls_standalone_layout_title text-2xl font-semibold tracking-tight text-foreground", children: heading })), showDescription && (_jsx("p", { className: "cls_standalone_layout_description mt-2 text-sm text-muted-foreground", children: description }))] })), _jsx("div", { className: "cls_standalone_layout_body", children: children })] }) })] }));
+    return (
+    // Outer wrapper: Consuming app's wrapperClassName applied here for theming/background
+    // This is isolated from the internal layout structure
+    _jsx("div", { className: cn("cls_standalone_layout_outer min-h-screen w-full bg-background", wrapperClassName), children: _jsxs("div", { className: "cls_standalone_layout_wrapper flex min-h-screen w-full flex-col", children: [hasNavbar && _jsx(AuthNavbar, Object.assign({}, navbar)), _jsx("div", { className: cn("cls_standalone_layout_content_area flex-1", verticalCenter && "flex items-center justify-center"), style: verticalCenter ? { minHeight: `calc(100vh - ${navbarHeight}px)` } : undefined, children: _jsxs("div", { className: cn("cls_standalone_layout_content mx-auto flex w-full max-w-5xl flex-col gap-8 p-6", contentClassName), children: [(showHeading || showDescription) && (_jsxs("div", { className: "cls_standalone_layout_header text-center", children: [showHeading && (_jsx("h1", { className: "cls_standalone_layout_title text-2xl font-semibold tracking-tight text-foreground", children: heading })), showDescription && (_jsx("p", { className: "cls_standalone_layout_description mt-2 text-sm text-muted-foreground", children: description }))] })), _jsx("div", { className: "cls_standalone_layout_body", children: children })] }) })] }) }));
 }

package/dist/components/layouts/user_management/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/components/layouts/user_management/index.tsx"],"names":[],"mappings":"AA2DA,4CAA4C;AAC5C,MAAM,MAAM,cAAc,GAAG;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oDAAoD;IACpD,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,4DAA4D;IAC5D,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,iEAAiE;IACjE,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,6DAA6D;IAC7D,kBAAkB,CAAC,EAAE,cAAc,EAAE,CAAC;CACvC,CAAC;AA+BF;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,SAAS,EAAE,YAAoB,EAAE,mBAA2B,EAAE,gBAAwB,EAAE,kBAAuB,EAAE,EAAE,yBAAyB,2CA+nDlL"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/components/layouts/user_management/index.tsx"],"names":[],"mappings":"AA2DA,4CAA4C;AAC5C,MAAM,MAAM,cAAc,GAAG;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oDAAoD;IACpD,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,4DAA4D;IAC5D,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,iEAAiE;IACjE,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,6DAA6D;IAC7D,kBAAkB,CAAC,EAAE,cAAc,EAAE,CAAC;CACvC,CAAC;AA+JF;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,SAAS,EAAE,YAAoB,EAAE,mBAA2B,EAAE,gBAAwB,EAAE,kBAAuB,EAAE,EAAE,yBAAyB,2CAwqDlL"}

package/dist/components/layouts/user_management/index.js

@@ -1,7 +1,7 @@
 // file_description: User Management layout component with tabs for managing users, roles, permissions, and HRBAC scopes
 // section: client_directive
 "use client";
-import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { jsxs as _jsxs, jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
 // section: imports
 import { useState, useEffect, useCallback } from "react";
 import { Tabs, TabsContent, TabsList, TabsTrigger } from "../../ui/tabs";
@@ -20,11 +20,42 @@ import { ScopeHierarchyTab } from "./components/scope_hierarchy_tab";
 import { ScopeLabelsTab } from "./components/scope_labels_tab";
 import { UserScopesTab } from "./components/user_scopes_tab";
 import { OrgHierarchyTab } from "./components/org_hierarchy_tab";
-import { UserX, KeyRound, Edit, Trash2, Loader2, CircleCheck, CircleX, Plus, UserPlus, Building2 } from "lucide-react";
+import { UserX, KeyRound, Edit, Trash2, Loader2, CircleCheck, CircleX, Plus, UserPlus, Building2, ChevronRight, ChevronDown } from "lucide-react";
 import { TreeView } from "../../ui/tree-view";
 import { toast } from "sonner";
 import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "../../ui/tooltip";
 import { useHazoAuthConfig } from "../../../contexts/hazo_auth_provider";
+// section: helper_components
+/**
+ * Recursive JSON tree node component for displaying app_user_data.
+ * Renders objects and arrays as expandable/collapsible nodes.
+ */
+function JsonTreeNode({ data, keyName, level = 0, defaultExpanded = true, }) {
+    const [isExpanded, setIsExpanded] = useState(defaultExpanded);
+    const indent = level * 16;
+    // Handle null/undefined
+    if (data === null || data === undefined) {
+        return (_jsxs("div", { className: "flex items-center py-0.5", style: { paddingLeft: indent }, children: [keyName && _jsxs("span", { className: "text-muted-foreground", children: [keyName, ":"] }), _jsx("span", { className: "ml-1 text-slate-500 italic", children: "null" })] }));
+    }
+    // Handle arrays
+    if (Array.isArray(data)) {
+        const hasChildren = data.length > 0;
+        return (_jsxs("div", { children: [_jsxs("div", { className: `flex items-center py-0.5 ${hasChildren ? "cursor-pointer hover:bg-muted/50 rounded" : ""}`, style: { paddingLeft: indent }, onClick: () => hasChildren && setIsExpanded(!isExpanded), children: [hasChildren ? (isExpanded ? (_jsx(ChevronDown, { className: "h-3 w-3 mr-1 text-muted-foreground shrink-0" })) : (_jsx(ChevronRight, { className: "h-3 w-3 mr-1 text-muted-foreground shrink-0" }))) : (_jsx("span", { className: "w-4 mr-1" })), keyName && _jsx("span", { className: "text-muted-foreground", children: keyName }), _jsxs("span", { className: "ml-1 text-slate-500", children: ["[", data.length, "]"] })] }), isExpanded && hasChildren && (_jsx("div", { className: "border-l border-slate-200 ml-2", style: { marginLeft: indent + 8 }, children: data.map((item, index) => (_jsx(JsonTreeNode, { data: item, keyName: `[${index}]`, level: 0, defaultExpanded: defaultExpanded }, index))) }))] }));
+    }
+    // Handle objects
+    if (typeof data === "object") {
+        const entries = Object.entries(data);
+        const hasChildren = entries.length > 0;
+        return (_jsxs("div", { children: [_jsxs("div", { className: `flex items-center py-0.5 ${hasChildren ? "cursor-pointer hover:bg-muted/50 rounded" : ""}`, style: { paddingLeft: indent }, onClick: () => hasChildren && setIsExpanded(!isExpanded), children: [hasChildren ? (isExpanded ? (_jsx(ChevronDown, { className: "h-3 w-3 mr-1 text-muted-foreground shrink-0" })) : (_jsx(ChevronRight, { className: "h-3 w-3 mr-1 text-muted-foreground shrink-0" }))) : (_jsx("span", { className: "w-4 mr-1" })), keyName && _jsx("span", { className: "text-muted-foreground", children: keyName }), keyName && _jsx("span", { className: "ml-1 text-slate-500", children: `{${entries.length}}` })] }), isExpanded && hasChildren && (_jsx("div", { className: "border-l border-slate-200 ml-2", style: { marginLeft: indent + 8 }, children: entries.map(([key, value]) => (_jsx(JsonTreeNode, { data: value, keyName: key, level: 0, defaultExpanded: defaultExpanded }, key))) }))] }));
+    }
+    // Handle primitives (string, number, boolean)
+    const valueStr = String(data);
+    const displayValue = valueStr.length > 80 ? valueStr.substring(0, 80) + "..." : valueStr;
+    const valueColor = typeof data === "number" ? "text-blue-600" :
+        typeof data === "boolean" ? "text-orange-600" :
+            "text-green-700";
+    return (_jsxs("div", { className: "flex items-center py-0.5", style: { paddingLeft: indent }, children: [_jsx("span", { className: "w-4 mr-1" }), keyName && _jsxs("span", { className: "text-muted-foreground", children: [keyName, ":"] }), _jsx("span", { className: `ml-1 ${valueColor}`, children: typeof data === "string" ? `"${displayValue}"` : displayValue })] }));
+}
 // section: component
 /**
  * User Management layout component with tabs for managing users, roles, permissions, and HRBAC scopes
@@ -55,12 +86,14 @@ export function UserManagementLayout({ className, hrbacEnabled = false, multiTen
         authResult.permissions.includes("hazo_perm_org_management");
     const hasOrgGlobalAdminPermission = authResult.authenticated &&
         authResult.permissions.includes("hazo_org_global_admin");
+    const hasSystemPermission = authResult.authenticated &&
+        authResult.permissions.includes("admin_system");
     // Determine which tabs to show
     const showUsersTab = hasUserManagementPermission;
     const showRolesTab = hasRoleManagementPermission;
     const showPermissionsTab = hasPermissionManagementPermission;
     const showScopeHierarchyTab = hrbacEnabled && hasScopeHierarchyPermission;
-    const showScopeLabelsTab = hrbacEnabled && hasScopeHierarchyPermission;
+    const showScopeLabelsTab = hrbacEnabled && hasSystemPermission;
     const showUserScopesTab = hrbacEnabled && hasUserScopeAssignmentPermission;
     const showOrgsTab = multiTenancyEnabled && hasOrgManagementPermission;
     const hasAnyPermission = showUsersTab || showRolesTab || showPermissionsTab || showScopeHierarchyTab || showScopeLabelsTab || showUserScopesTab || showOrgsTab;
@@ -121,13 +154,27 @@ export function UserManagementLayout({ className, hrbacEnabled = false, multiTen
         void loadUsers();
     }, [showUsersTab, loadUsers]);
     // Load organizations (only if multi-tenancy is enabled and user has permission)
+    // Non-global admins can only see orgs in their tree
     useEffect(() => {
         if (!multiTenancyEnabled || !showUsersTab) {
             return;
         }
         const loadOrgs = async () => {
+            var _a, _b;
             try {
-                const response = await fetch(`${apiBasePath}/org_management/orgs`);
+                const params = new URLSearchParams();
+                // Non-global admins can only see orgs in their tree
+                if (!hasOrgGlobalAdminPermission && authResult.authenticated) {
+                    const userRootOrgId = ((_a = authResult.user) === null || _a === void 0 ? void 0 : _a.root_org_id) || ((_b = authResult.user) === null || _b === void 0 ? void 0 : _b.org_id);
+                    if (userRootOrgId) {
+                        params.set("root_org_id", userRootOrgId);
+                    }
+                }
+                const queryString = params.toString();
+                const url = queryString
+                    ? `${apiBasePath}/org_management/orgs?${queryString}`
+                    : `${apiBasePath}/org_management/orgs`;
+                const response = await fetch(url);
                 const data = await response.json();
                 if (data.success && Array.isArray(data.orgs)) {
                     setAvailableOrgs(data.orgs.map((org) => ({
@@ -143,7 +190,7 @@ export function UserManagementLayout({ className, hrbacEnabled = false, multiTen
             }
         };
         void loadOrgs();
-    }, [multiTenancyEnabled, showUsersTab, apiBasePath]);
+    }, [multiTenancyEnabled, showUsersTab, apiBasePath, hasOrgGlobalAdminPermission, authResult]);
     // Load permissions (only if user has permission)
     useEffect(() => {
         if (!showPermissionsTab) {
@@ -700,7 +747,7 @@ export function UserManagementLayout({ className, hrbacEnabled = false, multiTen
                                                         minute: "2-digit",
                                                         second: "2-digit",
                                                         timeZoneName: "short",
-                                                    }) })) : (_jsx("span", { className: "text-muted-foreground", children: "-" })) })] }), userTypesEnabled && (_jsxs("div", { className: "cls_user_management_user_detail_field_user_type flex flex-col gap-2", children: [_jsx(Label, { className: "cls_user_management_user_detail_label font-semibold", children: "User Type" }), _jsxs("div", { className: "cls_user_management_user_detail_user_type_value flex items-center gap-2", children: [_jsxs(Select, { value: selectedUser.user_type || "__none__", onValueChange: (value) => handleUserTypeChange(value), disabled: userTypeUpdateLoading, children: [_jsx(SelectTrigger, { className: "w-48", children: _jsx(SelectValue, { placeholder: "Select user type" }) }), _jsxs(SelectContent, { children: [_jsx(SelectItem, { value: "__none__", children: "None" }), availableUserTypes.map((type) => (_jsx(SelectItem, { value: type.key, children: type.label }, type.key)))] })] }), userTypeUpdateLoading && (_jsx(Loader2, { className: "h-4 w-4 animate-spin text-muted-foreground" }))] })] })), multiTenancyEnabled && (_jsxs("div", { className: "cls_user_management_user_detail_field_org flex flex-col gap-2", children: [_jsx(Label, { className: "cls_user_management_user_detail_label font-semibold", children: "Organization" }), _jsxs("div", { className: "cls_user_management_user_detail_org_value flex items-center gap-2", children: [_jsxs(Select, { value: selectedUser.org_id || "__none__", onValueChange: (value) => handleOrgChange(value), disabled: orgUpdateLoading, children: [_jsx(SelectTrigger, { className: "w-64", children: _jsx(SelectValue, { placeholder: "Select organization" }) }), _jsxs(SelectContent, { children: [_jsx(SelectItem, { value: "__none__", children: "None" }), availableOrgs.map((org) => (_jsx(SelectItem, { value: org.id, children: org.name }, org.id)))] })] }), orgUpdateLoading && (_jsx(Loader2, { className: "h-4 w-4 animate-spin text-muted-foreground" }))] })] }))] })) }), _jsx(DialogFooter, { className: "cls_user_management_user_detail_dialog_footer", children: _jsx(Button, { onClick: () => setUserDetailDialogOpen(false), variant: "outline", className: "cls_user_management_user_detail_dialog_close", children: "Close" }) })] }) }), _jsx(Dialog, { open: assignRolesDialogOpen, onOpenChange: setAssignRolesDialogOpen, children: _jsxs(DialogContent, { className: "cls_user_management_assign_roles_dialog max-w-4xl max-h-[80vh] overflow-y-auto", children: [_jsxs(DialogHeader, { children: [_jsx(DialogTitle, { children: "Assign Roles to User" }), _jsxs(DialogDescription, { children: ["Select roles to assign to ", (selectedUser === null || selectedUser === void 0 ? void 0 : selectedUser.name) || (selectedUser === null || selectedUser === void 0 ? void 0 : selectedUser.email_address), ". Check the roles you want to assign, then click Save."] })] }), _jsx("div", { className: "cls_user_management_assign_roles_dialog_content py-4", children: _jsx(RolesMatrix, { add_button_enabled: false, role_name_selection_enabled: true, permissions_read_only: true, show_save_cancel: true, user_id: selectedUser === null || selectedUser === void 0 ? void 0 : selectedUser.id, onSave: (data) => {
+                                                    }) })) : (_jsx("span", { className: "text-muted-foreground", children: "-" })) })] }), userTypesEnabled && (_jsxs("div", { className: "cls_user_management_user_detail_field_user_type flex flex-col gap-2", children: [_jsx(Label, { className: "cls_user_management_user_detail_label font-semibold", children: "User Type" }), _jsxs("div", { className: "cls_user_management_user_detail_user_type_value flex items-center gap-2", children: [_jsxs(Select, { value: selectedUser.user_type || "__none__", onValueChange: (value) => handleUserTypeChange(value), disabled: userTypeUpdateLoading, children: [_jsx(SelectTrigger, { className: "w-48", children: _jsx(SelectValue, { placeholder: "Select user type" }) }), _jsxs(SelectContent, { children: [_jsx(SelectItem, { value: "__none__", children: "None" }), availableUserTypes.map((type) => (_jsx(SelectItem, { value: type.key, children: type.label }, type.key)))] })] }), userTypeUpdateLoading && (_jsx(Loader2, { className: "h-4 w-4 animate-spin text-muted-foreground" }))] })] })), multiTenancyEnabled && (_jsxs("div", { className: "cls_user_management_user_detail_field_org flex flex-col gap-2", children: [_jsx(Label, { className: "cls_user_management_user_detail_label font-semibold", children: "Organization" }), _jsxs("div", { className: "cls_user_management_user_detail_org_value flex items-center gap-2", children: [_jsxs(Select, { value: selectedUser.org_id || "__none__", onValueChange: (value) => handleOrgChange(value), disabled: orgUpdateLoading, children: [_jsx(SelectTrigger, { className: "w-64", children: _jsx(SelectValue, { placeholder: "Select organization" }) }), _jsxs(SelectContent, { children: [_jsx(SelectItem, { value: "__none__", children: "None" }), availableOrgs.map((org) => (_jsx(SelectItem, { value: org.id, children: org.name }, org.id)))] })] }), orgUpdateLoading && (_jsx(Loader2, { className: "h-4 w-4 animate-spin text-muted-foreground" }))] })] })), _jsxs("div", { className: "cls_user_management_user_detail_field_app_user_data flex flex-col gap-2", children: [_jsx(Label, { className: "cls_user_management_user_detail_label font-semibold", children: "App User Data" }), _jsx("div", { className: "cls_user_management_user_detail_app_user_data_value", children: selectedUser.app_user_data && Object.keys(selectedUser.app_user_data).length > 0 ? (_jsx("div", { className: "border rounded-lg max-h-[200px] overflow-y-auto p-2 bg-slate-50 text-sm font-mono", children: Object.entries(selectedUser.app_user_data).map(([key, value]) => (_jsx(JsonTreeNode, { data: value, keyName: key, level: 0, defaultExpanded: true }, key))) })) : (_jsx("span", { className: "text-muted-foreground text-sm", children: "No app user data" })) })] })] })) }), _jsx(DialogFooter, { className: "cls_user_management_user_detail_dialog_footer", children: _jsx(Button, { onClick: () => setUserDetailDialogOpen(false), variant: "outline", className: "cls_user_management_user_detail_dialog_close", children: "Close" }) })] }) }), _jsx(Dialog, { open: assignRolesDialogOpen, onOpenChange: setAssignRolesDialogOpen, children: _jsxs(DialogContent, { className: "cls_user_management_assign_roles_dialog max-w-4xl max-h-[80vh] overflow-y-auto", children: [_jsxs(DialogHeader, { children: [_jsx(DialogTitle, { children: "Assign Roles to User" }), _jsxs(DialogDescription, { children: ["Select roles to assign to ", (selectedUser === null || selectedUser === void 0 ? void 0 : selectedUser.name) || (selectedUser === null || selectedUser === void 0 ? void 0 : selectedUser.email_address), ". Check the roles you want to assign, then click Save."] })] }), _jsx("div", { className: "cls_user_management_assign_roles_dialog_content py-4", children: _jsx(RolesMatrix, { add_button_enabled: false, role_name_selection_enabled: true, permissions_read_only: true, show_save_cancel: true, user_id: selectedUser === null || selectedUser === void 0 ? void 0 : selectedUser.id, onSave: (data) => {
                                     // Data is already saved by RolesMatrix component
                                     console.log("User roles saved:", data);
                                     // Refresh users list to show updated roles

package/dist/lib/app_permissions_config.server.d.ts

@@ -0,0 +1,37 @@
+/**
+ * A single app permission declaration
+ */
+export type AppPermission = {
+    permission_name: string;
+    description: string;
+};
+/**
+ * App permissions configuration
+ */
+export type AppPermissionsConfig = {
+    permissions: AppPermission[];
+    permissions_map: Map<string, string>;
+};
+/**
+ * Reads app permissions configuration from hazo_auth_config.ini file
+ * Format in INI file:
+ *   [hazo_auth__app_permissions]
+ *   app_permission_1 = permission_name:Description for debugging
+ *   app_permission_2 = another_perm:Another description
+ *
+ * @returns App permissions configuration with list and map of permissions
+ */
+export declare function get_app_permissions_config(): AppPermissionsConfig;
+/**
+ * Gets the description for a specific permission
+ * @param permission_name - The permission name to look up
+ * @returns Description or undefined if not found in app permissions config
+ */
+export declare function get_app_permission_description(permission_name: string): string | undefined;
+/**
+ * Gets descriptions for multiple permissions
+ * @param permission_names - Array of permission names to look up
+ * @returns Map of permission names to descriptions (only includes found permissions)
+ */
+export declare function get_app_permission_descriptions(permission_names: string[]): Map<string, string>;
+//# sourceMappingURL=app_permissions_config.server.d.ts.map

package/dist/lib/app_permissions_config.server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app_permissions_config.server.d.ts","sourceRoot":"","sources":["../../src/lib/app_permissions_config.server.ts"],"names":[],"mappings":"AAOA;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,WAAW,EAAE,aAAa,EAAE,CAAC;IAC7B,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC,CAAC;AAIF;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,IAAI,oBAAoB,CA0BjE;AAED;;;;GAIG;AACH,wBAAgB,8BAA8B,CAC5C,eAAe,EAAE,MAAM,GACtB,MAAM,GAAG,SAAS,CAGpB;AAED;;;;GAIG;AACH,wBAAgB,+BAA+B,CAC7C,gBAAgB,EAAE,MAAM,EAAE,GACzB,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAYrB"}

package/dist/lib/app_permissions_config.server.js

@@ -0,0 +1,64 @@
+// file_description: server-only helper to read app permissions configuration from hazo_auth_config.ini
+// This allows consuming apps to declare their required permissions with descriptions for debugging
+// section: imports
+import { read_config_section } from "./config/config_loader.server";
+// section: helpers
+/**
+ * Reads app permissions configuration from hazo_auth_config.ini file
+ * Format in INI file:
+ *   [hazo_auth__app_permissions]
+ *   app_permission_1 = permission_name:Description for debugging
+ *   app_permission_2 = another_perm:Another description
+ *
+ * @returns App permissions configuration with list and map of permissions
+ */
+export function get_app_permissions_config() {
+    const section = read_config_section("hazo_auth__app_permissions");
+    const permissions = [];
+    const permissions_map = new Map();
+    if (section) {
+        // Iterate through all keys in section that start with "app_permission_"
+        for (const [key, value] of Object.entries(section)) {
+            if (key.startsWith("app_permission_") && typeof value === "string") {
+                const colonIndex = value.indexOf(":");
+                if (colonIndex > 0) {
+                    const permission_name = value.substring(0, colonIndex).trim();
+                    const description = value.substring(colonIndex + 1).trim();
+                    if (permission_name && description) {
+                        permissions.push({ permission_name, description });
+                        permissions_map.set(permission_name, description);
+                    }
+                }
+            }
+        }
+    }
+    return {
+        permissions,
+        permissions_map,
+    };
+}
+/**
+ * Gets the description for a specific permission
+ * @param permission_name - The permission name to look up
+ * @returns Description or undefined if not found in app permissions config
+ */
+export function get_app_permission_description(permission_name) {
+    const config = get_app_permissions_config();
+    return config.permissions_map.get(permission_name);
+}
+/**
+ * Gets descriptions for multiple permissions
+ * @param permission_names - Array of permission names to look up
+ * @returns Map of permission names to descriptions (only includes found permissions)
+ */
+export function get_app_permission_descriptions(permission_names) {
+    const config = get_app_permissions_config();
+    const result = new Map();
+    for (const name of permission_names) {
+        const description = config.permissions_map.get(name);
+        if (description) {
+            result.set(name, description);
+        }
+    }
+    return result;
+}

package/dist/lib/auth/auth_types.d.ts

@@ -85,13 +85,15 @@ export type HazoAuthOptions = {
 /**
  * Custom error class for permission denials
  * Includes technical and user-friendly error messages
+ * Optionally includes permission descriptions for debugging
  */
 export declare class PermissionError extends Error {
     missing_permissions: string[];
     user_permissions: string[];
     required_permissions: string[];
     user_friendly_message?: string | undefined;
-    constructor(missing_permissions: string[], user_permissions: string[], required_permissions: string[], user_friendly_message?: string | undefined);
+    permission_descriptions?: Map<string, string> | undefined;
+    constructor(missing_permissions: string[], user_permissions: string[], required_permissions: string[], user_friendly_message?: string | undefined, permission_descriptions?: Map<string, string> | undefined);
 }
 /**
  * Custom error class for scope access denials in HRBAC

package/dist/lib/auth/auth_types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth_types.d.ts","sourceRoot":"","sources":["../../../src/lib/auth/auth_types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"auth_types.d.ts","sourceRoot":"","sources":["../../../src/lib/auth/auth_types.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,OAAO,CAAC;IACnB,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IAEnC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAE9C,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GACtB;IACE,aAAa,EAAE,IAAI,CAAC;IACpB,IAAI,EAAE,YAAY,CAAC;IACnB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,aAAa,EAAE,OAAO,CAAC;IACvB,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAE/B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,gBAAgB,CAAC,EAAE,eAAe,CAAC;IAEnC,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,GACD;IACE,aAAa,EAAE,KAAK,CAAC;IACrB,IAAI,EAAE,IAAI,CAAC;IACX,WAAW,EAAE,EAAE,CAAC;IAChB,aAAa,EAAE,KAAK,CAAC;IACrB,QAAQ,CAAC,EAAE,KAAK,CAAC;IACjB,MAAM,CAAC,EAAE,KAAK,CAAC;CAChB,CAAC;AAEN;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B;;;OAGG;IACH,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAC;IAChC;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF;;;;GAIG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IAE/B,mBAAmB,EAAE,MAAM,EAAE;IAC7B,gBAAgB,EAAE,MAAM,EAAE;IAC1B,oBAAoB,EAAE,MAAM,EAAE;IAC9B,qBAAqB,CAAC,EAAE,MAAM;IAC9B,uBAAuB,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;gBAJ7C,mBAAmB,EAAE,MAAM,EAAE,EAC7B,gBAAgB,EAAE,MAAM,EAAE,EAC1B,oBAAoB,EAAE,MAAM,EAAE,EAC9B,qBAAqB,CAAC,EAAE,MAAM,YAAA,EAC9B,uBAAuB,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,YAAA;CAKvD;AAED;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IAEhC,UAAU,EAAE,MAAM;IAClB,gBAAgB,EAAE,MAAM;IACxB,WAAW,EAAE,KAAK,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;gBAF/E,UAAU,EAAE,MAAM,EAClB,gBAAgB,EAAE,MAAM,EACxB,WAAW,EAAE,KAAK,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;CAKzF;AAED;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACtB,OAAO,EAAE,MAAM;gBAAf,OAAO,EAAE,MAAM;CAInC"}

package/dist/lib/auth/auth_types.js

@@ -3,14 +3,16 @@
 /**
  * Custom error class for permission denials
  * Includes technical and user-friendly error messages
+ * Optionally includes permission descriptions for debugging
  */
 export class PermissionError extends Error {
-    constructor(missing_permissions, user_permissions, required_permissions, user_friendly_message) {
+    constructor(missing_permissions, user_permissions, required_permissions, user_friendly_message, permission_descriptions) {
         super(`Missing permissions: ${missing_permissions.join(", ")}`);
         this.missing_permissions = missing_permissions;
         this.user_permissions = user_permissions;
         this.required_permissions = required_permissions;
         this.user_friendly_message = user_friendly_message;
+        this.permission_descriptions = permission_descriptions;
         this.name = "PermissionError";
     }
 }

package/dist/lib/auth/hazo_get_auth.server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hazo_get_auth.server.d.ts","sourceRoot":"","sources":["../../../src/lib/auth/hazo_get_auth.server.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAK1C,OAAO,KAAK,EAAE,cAAc,EAAgB,eAAe,EAAmB,MAAM,cAAc,CAAC;AA4XnG;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,WAAW,EACpB,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,cAAc,CAAC,CAwOzB"}
+{"version":3,"file":"hazo_get_auth.server.d.ts","sourceRoot":"","sources":["../../../src/lib/auth/hazo_get_auth.server.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAK1C,OAAO,KAAK,EAAE,cAAc,EAAgB,eAAe,EAAmB,MAAM,cAAc,CAAC;AA6XnG;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,WAAW,EACpB,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,cAAc,CAAC,CA2OzB"}

package/dist/lib/auth/hazo_get_auth.server.js

@@ -14,6 +14,7 @@ import { is_valid_scope_level } from "../services/scope_service";
 import { is_multi_tenancy_enabled, get_multi_tenancy_config } from "../multi_tenancy_config.server";
 import { get_org_cache } from "./org_cache";
 import { get_cookie_name, BASE_COOKIE_NAMES } from "../cookies_config.server";
+import { get_app_permission_descriptions } from "../app_permissions_config.server";
 // section: helpers
 /**
  * Parse JSON string to object, returning null on failure
@@ -430,7 +431,9 @@ export async function hazo_get_auth(request, options) {
         // Throw error if strict mode
         if (!permission_ok && options.strict) {
             const friendly_message = get_friendly_error_message(missing_permissions, config);
-            throw new PermissionError(missing_permissions, permissions, options.required_permissions, friendly_message);
+            // Include permission descriptions for debugging
+            const permission_descriptions = get_app_permission_descriptions(missing_permissions);
+            throw new PermissionError(missing_permissions, permissions, options.required_permissions, friendly_message, permission_descriptions);
         }
     }
     // Check HRBAC scope access if enabled and scope options provided

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hazo_auth",
-  "version": "4.6.2",
+  "version": "4.6.3",
   "description": "Zero-config authentication UI components for Next.js with RBAC, OAuth, multi-tenancy, and hierarchical scopes",
   "keywords": [
     "authentication",