hazo_auth 4.6.3 → 5.1.1

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.

package/SETUP_CHECKLIST.md

@@ -18,9 +18,16 @@ npx hazo_auth generate-routes --pages
 
 # 4. Set up environment variables
 cp .env.local.example .env.local
-# Edit .env.local and add ZEPTOMAIL_API_KEY
+# Edit .env.local and add ZEPTOMAIL_API_KEY and JWT_SECRET
 
-# 5. Start dev server and test
+# 5. Configure navbar logo and company name (IMPORTANT)
+# Edit hazo_auth_config.ini and set:
+#   [hazo_auth__navbar]
+#   logo_path = /logo.png
+#   company_name = My Company
+# Note: Copy your logo to public/logo.png
+
+# 6. Start dev server and test
 npm run dev
 # Visit http://localhost:3000/hazo_auth/login
 ```
@@ -98,7 +105,48 @@ export default function RootLayout({ children }) {
 }
 ```
 
-### Step 1.4: Enable Dark Mode Support (Optional)
+### Step 1.4: Configure Navbar (Logo and Company Name)
+
+The navbar appears on all auth pages (login, register, etc.) when using standalone layout mode. **By default, the logo and company name are NOT displayed** - you must configure them.
+
+**Edit `hazo_auth_config.ini`:**
+```ini
+[hazo_auth__navbar]
+# Enable navbar (default: true)
+enable_navbar = true
+
+# Logo - place your logo in public folder and set the path
+logo_path = /logo.png
+
+# Logo size (default: 28x28 - fits slim 48px navbar)
+logo_width = 28
+logo_height = 28
+
+# Company name displayed next to logo
+company_name = My Company
+
+# Home link (right side of navbar)
+show_home_link = true
+home_path = /
+home_label = Home
+
+# Navbar height (default: 48px for slim appearance)
+height = 48
+```
+
+**Important:**
+- If `logo_path` is empty, no logo will be displayed
+- If `company_name` is empty, no company name will be displayed
+- The default navbar height is 48px (slim design)
+
+**Checklist:**
+- [ ] Logo file exists in `public/` folder (e.g., `public/logo.png`)
+- [ ] `logo_path` configured in `hazo_auth_config.ini`
+- [ ] `company_name` configured in `hazo_auth_config.ini`
+
+---
+
+### Step 1.5: Enable Dark Mode Support (Optional)
 
 hazo_auth components support dark mode via CSS custom properties. Add the CSS variables to your global styles:
 
@@ -1708,6 +1756,34 @@ sqlite3 data/hazo_auth.sqlite ".tables" | grep -E "hazo_scopes|hazo_user_scopes|
 2. Check cookies are being set (inspect browser devtools > Application > Cookies)
 3. Ensure API routes are on same domain (no CORS issues)
 
+### Issue: Navbar logo or company name not showing
+
+**Symptoms:** Navbar appears but logo and/or company name are missing.
+
+**Solutions:**
+1. **Configure logo and company name in `hazo_auth_config.ini`:**
+   ```ini
+   [hazo_auth__navbar]
+   logo_path = /logo.png
+   company_name = My Company
+   ```
+
+2. **Ensure logo file exists:**
+   - Place your logo in the `public/` folder
+   - The path should be relative to public (e.g., `/logo.png` for `public/logo.png`)
+
+3. **Verify config is being read:**
+   - Config file must be in project root (where `process.cwd()` points)
+   - Restart the dev server after changing config
+
+4. **Check if navbar is enabled:**
+   ```ini
+   [hazo_auth__navbar]
+   enable_navbar = true
+   ```
+
+**Note:** By default, `logo_path` and `company_name` are empty strings, so nothing displays until you configure them.
+
 ---
 
 ## Final Checklist
@@ -1715,7 +1791,8 @@ sqlite3 data/hazo_auth.sqlite ".tables" | grep -E "hazo_scopes|hazo_user_scopes|
 **Configuration:**
 - [ ] `hazo_auth_config.ini` configured
 - [ ] `hazo_notify_config.ini` configured
-- [ ] `.env.local` with all required variables
+- [ ] `.env.local` with all required variables (ZEPTOMAIL_API_KEY, JWT_SECRET)
+- [ ] Navbar configured with logo and company name (see Step 1.4)
 
 **Database:**
 - [ ] Database created and accessible
@@ -1728,6 +1805,7 @@ sqlite3 data/hazo_auth.sqlite ".tables" | grep -E "hazo_scopes|hazo_user_scopes|
 **Pages:**
 - [ ] All 6 auth pages created
 - [ ] Pages render without errors
+- [ ] Navbar displays with logo and company name
 
 **Features:**
 - [ ] Registration works

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