hazo_auth 4.6.2 → 5.1.0

package/README.md

@@ -2,7 +2,34 @@
 
 A reusable authentication UI component package powered by Next.js, TailwindCSS, and shadcn. It integrates `hazo_config` for configuration management and `hazo_connect` for data access, enabling future components to stay aligned with platform conventions.
 
-### What's New in v2.0 🚀
+### What's New in v5.0 🚀
+
+**BREAKING CHANGE: Scope-Based Multi-Tenancy** - Complete architectural redesign for simpler, more flexible multi-tenancy!
+
+- ✅ **Unified Scope System** - Single `hazo_scopes` table replaces 8 separate tables (1 org + 7 scope levels)
+- ✅ **Membership-Based** - Users assigned to scopes via `hazo_user_scopes` (not org_id on user record)
+- ✅ **Invitation System** - Built-in invitation flow for onboarding new users to existing scopes
+- ✅ **Create Firm Flow** - New users create their own firm (scope) after email verification
+- ✅ **Post-Verification Routing** - Smart routing after email verification: invitations → create firm → default redirect
+- ✅ **Unlimited Hierarchy** - Flexible parent-child relationships, no fixed depth limit
+- ✅ **Simpler Architecture** - Fewer tables, fewer joins, easier to understand
+- ✅ **New CLI Command** - `npx hazo_auth init-permissions` for flexible permission setup
+
+**Migrating from v4.x?** This is a breaking change. Run the migration:
+
+```bash
+# 1. Backup your database first!
+# 2. Run the scope consolidation migration
+npm run migrate migrations/009_scope_consolidation.sql
+
+# 3. Update configuration (remove org settings, add invitation/create firm settings)
+# 4. Update code (remove org-related API calls and components)
+# 5. Test thoroughly
+```
+
+See [CHANGE_LOG.md](./CHANGE_LOG.md) for detailed migration guide, rationale, and breaking changes.
+
+### What's New in v2.0
 
 **Zero-Config Server Components** - Authentication pages now work out-of-the-box with ZERO configuration required!
 
@@ -12,8 +39,6 @@ A reusable authentication UI component package powered by Next.js, TailwindCSS,
 - ✅ **Embeddable Components** - MySettings and UserManagement adapt to any layout
 - ✅ **Sensible Defaults** - INI files are now optional, defaults built-in
 
-**Migrating from v1.x?** See [MIGRATION.md](./MIGRATION.md) for a complete upgrade guide.
-
 ### Also Includes (v1.6.6+)
 
 - **JWT Session Tokens for Edge-Compatible Authentication**: Secure Edge Runtime authentication in Next.js proxy/middleware files. See [Proxy/Middleware Authentication](#proxymiddleware-authentication) for details.
@@ -1102,6 +1127,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 +1763,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 +1772,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/cli/index.ts

@@ -7,6 +7,7 @@ import { run_validation } from "./validate.js";
 import { generate_routes, type GenerateOptions } from "./generate.js";
 import { handle_init } from "./init.js";
 import { handle_init_users, show_init_users_help } from "./init_users.js";
+import { handle_init_permissions, show_init_permissions_help } from "./init_permissions.js";
 
 // section: constants
 const VERSION = "1.6.0";
@@ -18,6 +19,7 @@ Usage: hazo_auth <command> [options]
 
 Commands:
   init               Initialize hazo_auth in your project (creates directories, copies config)
+  init-permissions   Create default permissions from config (no user required)
   init-users         Initialize permissions, roles, and super user from config
   validate           Check your hazo_auth setup and configuration
   generate-routes    Generate API route files and pages in your project
@@ -28,6 +30,7 @@ Options:
 
 Examples:
   npx hazo_auth init
+  npx hazo_auth init-permissions
   npx hazo_auth init-users
   npx hazo_auth validate
   npx hazo_auth generate-routes
@@ -154,6 +157,15 @@ Actions:
       handle_init();
       break;
 
+    case "init-permissions": {
+      if (help) {
+        show_init_permissions_help();
+        return;
+      }
+      await handle_init_permissions();
+      break;
+    }
+
     case "init-users": {
       if (help) {
         show_init_users_help();

package/cli-src/cli/init_permissions.ts

@@ -0,0 +1,164 @@
+// file_description: CLI command to initialize permissions from configuration
+// section: imports
+import { randomUUID } from "crypto";
+import { get_hazo_connect_instance } from "../lib/hazo_connect_instance.server.js";
+import { createCrudService } from "hazo_connect/server";
+import { get_user_management_config } from "../lib/user_management_config.server.js";
+import { create_app_logger } from "../lib/app_logger.js";
+
+// section: types
+type InitPermissionsSummary = {
+  inserted: string[];
+  existing: string[];
+};
+
+// section: helpers
+/**
+ * Prints a summary of what was inserted vs what already existed
+ */
+function print_summary(summary: InitPermissionsSummary): void {
+  console.log("=".repeat(60));
+  console.log("INITIALIZATION SUMMARY");
+  console.log("=".repeat(60));
+  console.log();
+
+  if (summary.inserted.length > 0) {
+    console.log(`✓ Inserted (${summary.inserted.length}):`);
+    summary.inserted.forEach((name) => console.log(`  - ${name}`));
+  }
+
+  if (summary.existing.length > 0) {
+    console.log(`⊙ Already existed (${summary.existing.length}):`);
+    summary.existing.forEach((name) => console.log(`  - ${name}`));
+  }
+
+  if (summary.inserted.length === 0 && summary.existing.length === 0) {
+    console.log("No permissions found in configuration.");
+  }
+
+  console.log();
+  console.log("=".repeat(60));
+}
+
+// section: main_function
+/**
+ * Initializes permissions from configuration
+ * This function reads from hazo_auth_config.ini and sets up permissions
+ * without requiring any users to exist.
+ */
+export async function handle_init_permissions(): Promise<void> {
+  const logger = create_app_logger();
+  const summary: InitPermissionsSummary = {
+    inserted: [],
+    existing: [],
+  };
+
+  try {
+    console.log("\n🐸 hazo_auth init-permissions\n");
+    console.log("Creating permissions from configuration...\n");
+
+    // Get hazo_connect instance
+    const hazoConnect = get_hazo_connect_instance();
+    const permissions_service = createCrudService(hazoConnect, "hazo_permissions");
+
+    // Get permissions from config
+    const config = get_user_management_config();
+    const permission_names = config.application_permission_list_defaults || [];
+
+    if (permission_names.length === 0) {
+      console.log("⚠ No permissions found in configuration.");
+      console.log("  Add permissions to [hazo_auth__user_management] application_permission_list_defaults\n");
+      return;
+    }
+
+    console.log(`Found ${permission_names.length} permission(s) in configuration:`);
+    permission_names.forEach((name) => console.log(`  - ${name}`));
+    console.log();
+
+    // Add permissions to hazo_permissions table
+    const now = new Date().toISOString();
+
+    for (const permission_name of permission_names) {
+      const trimmed_name = permission_name.trim();
+      if (!trimmed_name) continue;
+
+      // Check if permission already exists
+      const existing_permissions = await permissions_service.findBy({
+        permission_name: trimmed_name,
+      });
+
+      if (Array.isArray(existing_permissions) && existing_permissions.length > 0) {
+        const existing_permission = existing_permissions[0];
+        const perm_id = existing_permission.id as string;
+        summary.existing.push(trimmed_name);
+        console.log(`⊙ Permission already exists: ${trimmed_name} (ID: ${perm_id})`);
+      } else {
+        // Insert new permission with generated UUID
+        const perm_id = randomUUID();
+        await permissions_service.insert({
+          id: perm_id,
+          permission_name: trimmed_name,
+          description: `Permission for ${trimmed_name}`,
+          created_at: now,
+          changed_at: now,
+        });
+
+        summary.inserted.push(trimmed_name);
+        console.log(`✓ Inserted permission: ${trimmed_name} (ID: ${perm_id})`);
+      }
+    }
+
+    console.log();
+
+    // Print summary
+    print_summary(summary);
+
+    logger.info("init_permissions_completed", {
+      filename: "init_permissions.ts",
+      line_number: 0,
+      summary,
+    });
+  } catch (error) {
+    const error_message = error instanceof Error ? error.message : "Unknown error";
+    const error_stack = error instanceof Error ? error.stack : undefined;
+
+    console.error("\n✗ Error initializing permissions:");
+    console.error(`  ${error_message}`);
+    if (error_stack) {
+      console.error("\nStack trace:");
+      console.error(error_stack);
+    }
+
+    logger.error("init_permissions_failed", {
+      filename: "init_permissions.ts",
+      line_number: 0,
+      error_message,
+      error_stack,
+    });
+
+    process.exit(1);
+  }
+}
+
+// section: help
+/**
+ * Shows help for the init-permissions command
+ */
+export function show_init_permissions_help(): void {
+  console.log(`
+hazo_auth init-permissions
+
+Create default permissions from configuration.
+
+This command reads permissions from hazo_auth_config.ini and inserts them
+into the hazo_permissions table. Does not require any users to exist.
+
+Configuration required in hazo_auth_config.ini:
+
+  [hazo_auth__user_management]
+  application_permission_list_defaults = admin_user_management,admin_role_management,...
+
+Usage:
+  npx hazo_auth init-permissions
+`);
+}

package/cli-src/cli/init_users.ts

@@ -5,6 +5,7 @@ import { createCrudService } from "hazo_connect/server";
 import { get_user_management_config } from "../lib/user_management_config.server.js";
 import { get_config_value } from "../lib/config/config_loader.server.js";
 import { create_app_logger } from "../lib/app_logger.js";
+import { SUPER_ADMIN_SCOPE_ID } from "../lib/services/scope_service.js";
 
 // section: types
 type InitSummary = {
@@ -25,6 +26,14 @@ type InitSummary = {
     inserted: boolean;
     existing: boolean;
   };
+  super_admin_scope: {
+    inserted: boolean;
+    existing: boolean;
+  };
+  user_scope: {
+    inserted: boolean;
+    existing: boolean;
+  };
 };
 
 // section: helpers
@@ -79,6 +88,26 @@ function print_summary(summary: InitSummary): void {
   }
   console.log();
 
+  // Super admin scope summary
+  console.log("Super Admin Scope:");
+  if (summary.super_admin_scope.inserted) {
+    console.log(`  ✓ Inserted: Super Admin scope (ID: ${SUPER_ADMIN_SCOPE_ID})`);
+  }
+  if (summary.super_admin_scope.existing) {
+    console.log(`  ⊙ Already existed: Super Admin scope (ID: ${SUPER_ADMIN_SCOPE_ID})`);
+  }
+  console.log();
+
+  // User scope summary
+  console.log("User-Scope Assignment:");
+  if (summary.user_scope.inserted) {
+    console.log(`  ✓ Inserted: User assigned to Super Admin scope`);
+  }
+  if (summary.user_scope.existing) {
+    console.log(`  ⊙ Already existed: User already in Super Admin scope`);
+  }
+  console.log();
+
   console.log("=".repeat(60));
 }
 
@@ -116,6 +145,14 @@ export async function handle_init_users(options: InitUsersOptions = {}): Promise
       inserted: false,
       existing: false,
     },
+    super_admin_scope: {
+      inserted: false,
+      existing: false,
+    },
+    user_scope: {
+      inserted: false,
+      existing: false,
+    },
   };
 
   try {
@@ -129,6 +166,12 @@ export async function handle_init_users(options: InitUsersOptions = {}): Promise
     const role_permissions_service = createCrudService(hazoConnect, "hazo_role_permissions");
     const users_service = createCrudService(hazoConnect, "hazo_users");
     const user_roles_service = createCrudService(hazoConnect, "hazo_user_roles");
+    const scopes_service = createCrudService(hazoConnect, "hazo_scopes");
+    // hazo_user_scopes uses composite primary key (user_id, scope_id), no 'id' column
+    const user_scopes_service = createCrudService(hazoConnect, "hazo_user_scopes", {
+      primaryKeys: ["user_id", "scope_id"],
+      autoId: false,
+    });
 
     // 1. Get permissions from config
     const config = get_user_management_config();
@@ -307,7 +350,52 @@ export async function handle_init_users(options: InitUsersOptions = {}): Promise
 
     console.log();
 
-    // 8. Print summary
+    // 8. Ensure super admin scope exists
+    const existing_scopes = await scopes_service.findBy({ id: SUPER_ADMIN_SCOPE_ID });
+
+    if (Array.isArray(existing_scopes) && existing_scopes.length > 0) {
+      summary.super_admin_scope.existing = true;
+      console.log(`✓ Super Admin scope already exists (ID: ${SUPER_ADMIN_SCOPE_ID})`);
+    } else {
+      await scopes_service.insert({
+        id: SUPER_ADMIN_SCOPE_ID,
+        parent_id: null,
+        name: "Super Admin",
+        level: "system",
+        created_at: now,
+        changed_at: now,
+      });
+      summary.super_admin_scope.inserted = true;
+      console.log(`✓ Created Super Admin scope (ID: ${SUPER_ADMIN_SCOPE_ID})`);
+    }
+
+    console.log();
+
+    // 9. Assign user to super admin scope
+    const existing_user_scopes = await user_scopes_service.findBy({
+      user_id,
+      scope_id: SUPER_ADMIN_SCOPE_ID,
+    });
+
+    if (Array.isArray(existing_user_scopes) && existing_user_scopes.length > 0) {
+      summary.user_scope.existing = true;
+      console.log(`✓ User already assigned to Super Admin scope`);
+    } else {
+      await user_scopes_service.insert({
+        user_id,
+        scope_id: SUPER_ADMIN_SCOPE_ID,
+        root_scope_id: SUPER_ADMIN_SCOPE_ID,
+        role_id,
+        created_at: now,
+        changed_at: now,
+      });
+      summary.user_scope.inserted = true;
+      console.log(`✓ Assigned user to Super Admin scope`);
+    }
+
+    console.log();
+
+    // 10. Print summary
     print_summary(summary);
 
     logger.info("init_users_completed", {
@@ -345,7 +433,7 @@ export function show_init_users_help(): void {
   console.log(`
 hazo_auth init-users
 
-Initialize users, roles, and permissions from configuration.
+Initialize users, roles, permissions, and super admin scope from configuration.
 
 This command reads from hazo_auth_config.ini and:
   1. Creates permissions from [hazo_auth__user_management] application_permission_list_defaults
@@ -353,6 +441,8 @@ This command reads from hazo_auth_config.ini and:
   3. Assigns all permissions to the super user role
   4. Finds user by email (from --email parameter or config)
   5. Assigns the super user role to that user
+  6. Creates the Super Admin scope (${SUPER_ADMIN_SCOPE_ID})
+  7. Assigns the user to the Super Admin scope
 
 Options:
   --email=<email>    Email address of the user to assign super user role

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;
+}