hazo_auth 1.0.5 → 1.1.0

package/README.md

@@ -50,6 +50,56 @@ Because `src/app/hazo_auth` (pages) and `src/app/api/hazo_auth` (API routes) nee
 
 > The package expects these routes to live at `src/app/api/hazo_auth` and `src/app/hazo_auth` inside the consumer project. Without copying or linking them, Next.js won’t mount the auth pages or APIs.
 
+### Choose the UI Shell (Test Sidebar vs Standalone)
+
+By default, the pages render inside the “test workspace” sidebar so you can quickly preview every flow. When you reuse the routes inside another project you’ll usually want a clean, standalone wrapper instead. Set this in `hazo_auth_config.ini`:
+
+```ini
+[hazo_auth__ui_shell]
+# Options: test_sidebar | standalone
+layout_mode = standalone 
+# Optional tweaks for the standalone header wrapper/classes:
+# standalone_heading = Welcome back
+# standalone_description = Your description here
+# standalone_wrapper_class = min-h-screen bg-background py-8
+# standalone_content_class = mx-auto w-full max-w-4xl rounded-2xl border bg-card
+```
+
+- `test_sidebar`: keeps the developer sidebar (perfect for the demo workspace or Storybook screenshots).
+- `standalone`: renders the page body directly so it inherits your own app shell, layout, and theme tokens.
+- The wrapper and content class overrides let you align spacing/borders with your design system without editing package code.
+
+Every route (`/hazo_auth/login`, `/hazo_auth/register`, etc.) automatically looks at this config, so switching modes is instant.
+
+### Using Just the Layout Components
+
+Prefer to drop the forms into your own routes without copying the provided pages? Import the layouts directly and feed them a `data_client` plus any label/button overrides:
+
+```tsx
+// app/(auth)/login/page.tsx in your project
+import login_layout from "hazo_auth/components/layouts/login";
+import { createLayoutDataClient } from "hazo_auth/components/layouts/shared/data/layout_data_client";
+import { create_sqlite_hazo_connect } from "hazo_auth/lib/hazo_connect_setup";
+
+export default async function LoginPage() {
+  const hazoConnect = create_sqlite_hazo_connect();
+  const dataClient = createLayoutDataClient(hazoConnect);
+  const LoginLayout = login_layout;
+
+  return (
+    <div className="my-app-shell">
+      <LoginLayout
+        image_src="/marketing/login-hero.svg"
+        data_client={dataClient}
+        redirectRoute="/dashboard"
+      />
+    </div>
+  );
+}
+```
+
+The same import pattern works for every layout under `components/layouts/*`, so you can mix-and-match pieces (profile picture dialog, password field, etc.) wherever you need them.
+
 ## Authentication Service
 
 The `hazo_auth` package provides a comprehensive authentication and authorization system with role-based access control (RBAC). The main authentication utility is `hazo_get_auth`, which provides user details, permissions, and permission checking with built-in caching and rate limiting.

package/hazo_auth_config.example.ini

@@ -7,6 +7,31 @@
 # Database type: sqlite, postgrest, supabase, or file
 type = sqlite
 
+# UI shell controls whether pages render inside the developer sidebar or a minimal wrapper.
+[hazo_auth__ui_shell]
+# layout_mode = test_sidebar
+# Options:
+#   - test_sidebar: keeps the demo sidebar for quick testing in the package workspace.
+#   - standalone: renders pages in a minimal wrapper so consumers inherit their own shell/theme.
+#
+# Heading shown above standalone layouts
+# standalone_heading = Welcome to hazo auth
+#
+# Description beneath the heading for standalone layouts
+# standalone_description = Reuse the packaged authentication flows while inheriting your existing app shell styles.
+#
+# Tailwind utility classes applied to the standalone wrapper div
+# standalone_wrapper_class = cls_standalone_shell flex min-h-screen w-full items-center justify-center bg-background px-4 py-10
+#
+# Tailwind utility classes applied to the standalone inner content div
+# standalone_content_class = cls_standalone_shell_content w-full max-w-5xl shadow-xl rounded-2xl border bg-card
+#
+# Show/hide heading in standalone mode (true/false, default: true)
+# standalone_show_heading = true
+#
+# Show/hide description in standalone mode (true/false, default: true)
+# standalone_show_description = true
+
 # SQLite database configuration
 # Path to SQLite database file (relative to process.cwd() or absolute)
 sqlite_path = ./data/hazo_auth.sqlite
@@ -57,6 +82,10 @@ enable_admin_ui = true
 # Show name field (true/false)
 # Note: This is now deprecated, use hazo_auth__user_fields section instead
 # show_name_field = false
+#
+# Sign in link shown below register button
+# sign_in_path = /hazo_auth/login
+# sign_in_label = Sign in
 
 [hazo_auth__user_fields]
 # Shared user fields configuration used by register and my_settings layouts
@@ -104,6 +133,12 @@ enable_admin_ui = true
 # Redirect on successful login (leave empty to show success message instead)
 # redirect_route_on_successful_login = /
 
+# Forgot password + sign up links shown under login button
+# forgot_password_path = /hazo_auth/forgot_password
+# forgot_password_label = Forgot password?
+# create_account_path = /hazo_auth/register
+# create_account_label = Create account
+
 # Success message (shown when no redirect route is provided)
 # success_message = Successfully logged in
 
@@ -263,6 +298,12 @@ enable_admin_ui = true
 # Example: application_permission_list_defaults = PERM_ONE,PERM_TWO,PERM_THREE
 # application_permission_list_defaults = 
 
+[hazo_auth__initial_setup]
+# Initial setup configuration for initializing users, roles, and permissions
+# Email address of the super user to assign the default_super_user_role
+# This user will receive all permissions from application_permission_list_defaults
+# default_super_user_email = admin@example.com
+
 [hazo_auth__auth_utility]
 # Authentication utility configuration
 

package/instrumentation.ts

@@ -9,13 +9,13 @@ export async function register() {
       const hazo_notify_module = await import("hazo_notify");
       
       // Step 2: Load hazo_notify emailer configuration
-      // This reads from hazo_notify_config.ini in the project root (same location as hazo_auth_config.ini)
+      // This reads from hazo_notify_config.ini in the ui_component directory (same location as hazo_auth_config.ini)
       const { load_emailer_config } = hazo_notify_module;
       const notify_config = load_emailer_config();
       
       // Step 3: Pass the initialized configuration to hazo_auth email service
       // This allows the email service to reuse the same configuration instance
-      const { set_hazo_notify_instance } = await import("@/lib/services/email_service");
+      const { set_hazo_notify_instance } = await import("./src/lib/services/email_service");
       set_hazo_notify_instance(notify_config);
       
       // Log successful initialization

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hazo_auth",
-  "version": "1.0.5",
+  "version": "1.1.0",
   "files": [
     "src/**/*",
     "public/file.svg",
@@ -31,6 +31,7 @@
     "build-storybook": "storybook build",
     "dev:server": "tsx src/server/index.ts",
     "migrate": "tsx scripts/apply_migration.ts",
+    "init-users": "tsx scripts/init_users.ts init_users",
     "test": "cross-env NODE_ENV=test POSTGREST_URL=http://209.38.26.241:4402 POSTGREST_API_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiYXBpX3VzZXIifQ.zBoUGymrxTUk1DNYIGUCtQU4HFaWEHlbE9_8Y3hUaTw jest --runInBand",
     "test:watch": "cross-env NODE_ENV=test POSTGREST_URL=http://209.38.26.241:4402 POSTGREST_API_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiYXBpX3VzZXIifQ.zBoUGymrxTUk1DNYIGUCtQU4HFaWEHlbE9_8Y3hUaTw jest --watch"
   },

package/scripts/init_users.ts

@@ -0,0 +1,378 @@
+// file_description: script to initialize users, roles, and permissions from configuration
+// Run with: npx tsx scripts/init_users.ts init_users
+// section: imports
+import { get_hazo_connect_instance } from "../src/lib/hazo_connect_instance.server";
+import { createCrudService } from "hazo_connect/server";
+import { get_user_management_config } from "../src/lib/user_management_config.server";
+import { get_config_value } from "../src/lib/config/config_loader.server";
+import { create_app_logger } from "../src/lib/app_logger";
+
+// section: types
+type InitSummary = {
+  permissions: {
+    inserted: string[];
+    existing: string[];
+  };
+  role: {
+    inserted: boolean;
+    existing: boolean;
+    role_id: number | null;
+  };
+  role_permissions: {
+    inserted: number;
+    existing: number;
+  };
+  user_role: {
+    inserted: boolean;
+    existing: boolean;
+  };
+};
+
+// section: helpers
+/**
+ * Displays help information for available commands
+ */
+function show_help(): void {
+  console.log(`
+hazo_auth CLI - User and Permission Management
+
+Usage: npx tsx scripts/init_users.ts <command>
+
+Available Commands:
+  init_users    Initialize users, roles, and permissions from configuration
+                - Reads permissions from hazo_auth_config.ini [hazo_auth__user_management] application_permission_list_defaults
+                - Creates default_super_user_role in hazo_roles
+                - Assigns all permissions to the super user role
+                - Finds user by email from hazo_auth_config.ini [hazo_auth__initial_setup] default_super_user_email
+                - Assigns super user role to the user
+                - Provides summary of what was inserted vs what already existed
+
+  help          Show this help message
+
+Configuration:
+  Add the following to hazo_auth_config.ini:
+
+  [hazo_auth__user_management]
+  application_permission_list_defaults = admin_user_management,admin_role_management,admin_permission_management
+
+  [hazo_auth__initial_setup]
+  default_super_user_email = admin@example.com
+
+Examples:
+  npx tsx scripts/init_users.ts init_users
+  npx tsx scripts/init_users.ts help
+`);
+}
+
+/**
+ * Initializes users, roles, and permissions from configuration
+ */
+async function init_users(): Promise<void> {
+  const logger = create_app_logger();
+  const summary: InitSummary = {
+    permissions: {
+      inserted: [],
+      existing: [],
+    },
+    role: {
+      inserted: false,
+      existing: false,
+      role_id: null,
+    },
+    role_permissions: {
+      inserted: 0,
+      existing: 0,
+    },
+    user_role: {
+      inserted: false,
+      existing: false,
+    },
+  };
+
+  try {
+    console.log("Initializing users, roles, and permissions from configuration...\n");
+
+    // Get hazo_connect instance
+    const hazoConnect = get_hazo_connect_instance();
+    const permissions_service = createCrudService(hazoConnect, "hazo_permissions");
+    const roles_service = createCrudService(hazoConnect, "hazo_roles");
+    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");
+
+    // 1. 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();
+
+    // 2. Add permissions to hazo_permissions table
+    const permission_id_map: Record<string, number> = {};
+    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 number;
+        permission_id_map[trimmed_name] = perm_id;
+        summary.permissions.existing.push(trimmed_name);
+        console.log(`✓ Permission already exists: ${trimmed_name} (ID: ${perm_id})`);
+      } else {
+        // Insert new permission
+        const new_permission = await permissions_service.insert({
+          permission_name: trimmed_name,
+          description: `Permission for ${trimmed_name}`,
+          created_at: now,
+          changed_at: now,
+        });
+
+        const perm_id = Array.isArray(new_permission)
+          ? (new_permission[0] as { id: number }).id
+          : (new_permission as { id: number }).id;
+        permission_id_map[trimmed_name] = perm_id;
+        summary.permissions.inserted.push(trimmed_name);
+        console.log(`✓ Inserted permission: ${trimmed_name} (ID: ${perm_id})`);
+      }
+    }
+
+    console.log();
+
+    // 3. Create or get default_super_user_role
+    const role_name = "default_super_user_role";
+    const existing_roles = await roles_service.findBy({
+      role_name,
+    });
+
+    let role_id: number;
+    if (Array.isArray(existing_roles) && existing_roles.length > 0) {
+      role_id = existing_roles[0].id as number;
+      summary.role.existing = true;
+      summary.role.role_id = role_id;
+      console.log(`✓ Role already exists: ${role_name} (ID: ${role_id})`);
+    } else {
+      const new_role = await roles_service.insert({
+        role_name,
+        created_at: now,
+        changed_at: now,
+      });
+
+      role_id = Array.isArray(new_role)
+        ? (new_role[0] as { id: number }).id
+        : (new_role as { id: number }).id;
+      summary.role.inserted = true;
+      summary.role.role_id = role_id;
+      console.log(`✓ Created role: ${role_name} (ID: ${role_id})`);
+    }
+
+    console.log();
+
+    // 4. Assign all permissions to the role
+    const permission_ids = Object.values(permission_id_map);
+
+    for (const permission_id of permission_ids) {
+      // Check if role-permission assignment already exists
+      const existing_assignments = await role_permissions_service.findBy({
+        role_id,
+        permission_id,
+      });
+
+      if (Array.isArray(existing_assignments) && existing_assignments.length > 0) {
+        summary.role_permissions.existing++;
+        const perm_name = Object.keys(permission_id_map).find(
+          (key) => permission_id_map[key] === permission_id,
+        );
+        console.log(`✓ Role-permission already exists: ${role_name} -> ${perm_name}`);
+      } else {
+        await role_permissions_service.insert({
+          role_id,
+          permission_id,
+          created_at: now,
+          changed_at: now,
+        });
+        summary.role_permissions.inserted++;
+        const perm_name = Object.keys(permission_id_map).find(
+          (key) => permission_id_map[key] === permission_id,
+        );
+        console.log(`✓ Assigned permission to role: ${role_name} -> ${perm_name}`);
+      }
+    }
+
+    console.log();
+
+    // 5. Get super user email from config
+    const super_user_email = get_config_value(
+      "hazo_auth__initial_setup",
+      "default_super_user_email",
+      "",
+    ).trim();
+
+    if (!super_user_email) {
+      console.log("⚠ No super user email found in configuration.");
+      console.log("  Add [hazo_auth__initial_setup] default_super_user_email to config\n");
+      print_summary(summary);
+      return;
+    }
+
+    console.log(`Looking up user with email: ${super_user_email}`);
+
+    // 6. Find user by email
+    const users = await users_service.findBy({
+      email_address: super_user_email,
+    });
+
+    if (!Array.isArray(users) || users.length === 0) {
+      console.log(`✗ User not found with email: ${super_user_email}`);
+      console.log("  Please ensure the user exists in the database before running this script.\n");
+      print_summary(summary);
+      return;
+    }
+
+    const user = users[0];
+    const user_id = user.id as string;
+    console.log(`✓ Found user: ${super_user_email} (ID: ${user_id})`);
+    console.log();
+
+    // 7. Assign role to user
+    const existing_user_roles = await user_roles_service.findBy({
+      user_id,
+      role_id,
+    });
+
+    if (Array.isArray(existing_user_roles) && existing_user_roles.length > 0) {
+      summary.user_role.existing = true;
+      console.log(`✓ User already has role assigned: ${user_id} -> ${role_name}`);
+    } else {
+      await user_roles_service.insert({
+        user_id,
+        role_id,
+        created_at: now,
+        changed_at: now,
+      });
+      summary.user_role.inserted = true;
+      console.log(`✓ Assigned role to user: ${user_id} -> ${role_name}`);
+    }
+
+    console.log();
+
+    // 8. Print summary
+    print_summary(summary);
+
+    logger.info("init_users_completed", {
+      filename: "init_users.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 users:");
+    console.error(`  ${error_message}`);
+    if (error_stack) {
+      console.error("\nStack trace:");
+      console.error(error_stack);
+    }
+
+    const logger = create_app_logger();
+    logger.error("init_users_failed", {
+      filename: "init_users.ts",
+      line_number: 0,
+      error_message,
+      error_stack,
+    });
+
+    process.exit(1);
+  }
+}
+
+/**
+ * Prints a summary of what was inserted vs what already existed
+ */
+function print_summary(summary: InitSummary): void {
+  console.log("=".repeat(60));
+  console.log("INITIALIZATION SUMMARY");
+  console.log("=".repeat(60));
+  console.log();
+
+  // Permissions summary
+  console.log("Permissions:");
+  if (summary.permissions.inserted.length > 0) {
+    console.log(`  ✓ Inserted (${summary.permissions.inserted.length}):`);
+    summary.permissions.inserted.forEach((name) => console.log(`    - ${name}`));
+  }
+  if (summary.permissions.existing.length > 0) {
+    console.log(`  ⊙ Already existed (${summary.permissions.existing.length}):`);
+    summary.permissions.existing.forEach((name) => console.log(`    - ${name}`));
+  }
+  console.log();
+
+  // Role summary
+  console.log("Role:");
+  if (summary.role.inserted) {
+    console.log(`  ✓ Inserted: default_super_user_role (ID: ${summary.role.role_id})`);
+  }
+  if (summary.role.existing) {
+    console.log(`  ⊙ Already existed: default_super_user_role (ID: ${summary.role.role_id})`);
+  }
+  console.log();
+
+  // Role permissions summary
+  console.log("Role-Permission Assignments:");
+  if (summary.role_permissions.inserted > 0) {
+    console.log(`  ✓ Inserted: ${summary.role_permissions.inserted} assignment(s)`);
+  }
+  if (summary.role_permissions.existing > 0) {
+    console.log(`  ⊙ Already existed: ${summary.role_permissions.existing} assignment(s)`);
+  }
+  console.log();
+
+  // User role summary
+  console.log("User-Role Assignment:");
+  if (summary.user_role.inserted) {
+    console.log(`  ✓ Inserted: Super user role assigned to user`);
+  }
+  if (summary.user_role.existing) {
+    console.log(`  ⊙ Already existed: User already has super user role`);
+  }
+  console.log();
+
+  console.log("=".repeat(60));
+}
+
+// section: main
+function main(): void {
+  const command = process.argv[2];
+
+  if (!command || command === "help" || command === "--help" || command === "-h") {
+    show_help();
+    return;
+  }
+
+  if (command === "init_users") {
+    void init_users();
+  } else {
+    console.error(`Unknown command: ${command}\n`);
+    show_help();
+    process.exit(1);
+  }
+}
+
+main();
+
+

package/src/app/api/hazo_auth/login/route.ts

@@ -6,6 +6,7 @@ import { create_app_logger } from "../../../../lib/app_logger";
 import { authenticate_user } from "../../../../lib/services/login_service";
 import { createCrudService } from "hazo_connect/server";
 import { get_filename, get_line_number } from "../../../../lib/utils/api_route_helpers";
+import { get_login_config } from "../../../../lib/login_config.server";
 
 // section: api_handler
 export async function POST(request: NextRequest) {
@@ -13,7 +14,7 @@ export async function POST(request: NextRequest) {
 
   try {
     const body = await request.json();
-    const { email, password } = body;
+    const { email, password, url_on_logon } = body;
 
     // Validate input
     if (!email || !password) {
@@ -106,6 +107,30 @@ export async function POST(request: NextRequest) {
     const user = users && users.length > 0 ? users[0] : null;
     const user_name = user?.name as string | undefined;
 
+    // Determine redirect URL priority:
+    // 1. url_on_logon from request body (if valid)
+    // 2. stored_url_on_logon from database (if available)
+    // 3. redirect_route_on_successful_login from config
+    // 4. Default to "/"
+
+    let redirectUrl = "/";
+
+    // Check priority 1: Request body
+    if (url_on_logon && typeof url_on_logon === "string" && url_on_logon.startsWith("/") && !url_on_logon.startsWith("//")) {
+      redirectUrl = url_on_logon;
+    } 
+    // Check priority 2: Stored URL from DB
+    else if (result.stored_url_on_logon && typeof result.stored_url_on_logon === "string") {
+      redirectUrl = result.stored_url_on_logon;
+    } 
+    // Check priority 3: Config
+    else {
+      const loginConfig = get_login_config();
+      if (loginConfig.redirectRoute) {
+        redirectUrl = loginConfig.redirectRoute;
+      }
+    }
+
     // Create response with cookies
     const response = NextResponse.json(
       {
@@ -114,6 +139,7 @@ export async function POST(request: NextRequest) {
         user_id: user_id,
         email,
         name: user_name,
+        redirectUrl,
       },
       { status: 200 }
     );

package/src/app/api/hazo_auth/register/route.ts

@@ -5,6 +5,7 @@ import { get_hazo_connect_instance } from "../../../../lib/hazo_connect_instance
 import { create_app_logger } from "../../../../lib/app_logger";
 import { register_user } from "../../../../lib/services/registration_service";
 import { get_filename, get_line_number } from "../../../../lib/utils/api_route_helpers";
+import { sanitize_error_for_user } from "../../../../lib/utils/error_sanitizer";
 
 // section: api_handler
 export async function POST(request: NextRequest) {
@@ -12,7 +13,7 @@ export async function POST(request: NextRequest) {
 
   try {
     const body = await request.json();
-    const { name, email, password } = body;
+    const { name, email, password, url_on_logon } = body;
 
     // Validate input
     if (!email || !password) {
@@ -52,6 +53,7 @@ export async function POST(request: NextRequest) {
       email,
       password,
       name,
+      url_on_logon,
     });
 
     if (!result.success) {
@@ -87,18 +89,19 @@ export async function POST(request: NextRequest) {
       { status: 201 }
     );
   } catch (error) {
-    const error_message = error instanceof Error ? error.message : "Unknown error";
-    const error_stack = error instanceof Error ? error.stack : undefined;
-
-    logger.error("registration_error", {
-      filename: get_filename(),
-      line_number: get_line_number(),
-      error_message,
-      error_stack,
+    const user_friendly_error = sanitize_error_for_user(error, {
+      logToConsole: true,
+      logToLogger: true,
+      logger,
+      context: {
+        filename: get_filename(),
+        line_number: get_line_number(),
+        operation: "register_api_route",
+      },
     });
 
     return NextResponse.json(
-      { error: "Registration failed. Please try again." },
+      { error: user_friendly_error },
       { status: 500 }
     );
   }

package/src/app/hazo_auth/forgot_password/page.tsx

@@ -1,6 +1,6 @@
 // file_description: render the forgot password page shell and mount the forgot password layout component within sidebar
 // section: imports
-import { SidebarLayoutWrapper } from "../../../components/layouts/shared/components/sidebar_layout_wrapper";
+import { AuthPageShell } from "../../../components/layouts/shared/components/auth_page_shell";
 import { ForgotPasswordPageClient } from "./forgot_password_page_client";
 import { get_forgot_password_config } from "../../../lib/forgot_password_config.server";
 
@@ -10,7 +10,7 @@ export default function forgot_password_page() {
   const forgotPasswordConfig = get_forgot_password_config();
 
   return (
-    <SidebarLayoutWrapper>
+    <AuthPageShell>
       <ForgotPasswordPageClient
         alreadyLoggedInMessage={forgotPasswordConfig.alreadyLoggedInMessage}
         showLogoutButton={forgotPasswordConfig.showLogoutButton}
@@ -18,7 +18,7 @@ export default function forgot_password_page() {
         returnHomeButtonLabel={forgotPasswordConfig.returnHomeButtonLabel}
         returnHomePath={forgotPasswordConfig.returnHomePath}
       />
-    </SidebarLayoutWrapper>
+    </AuthPageShell>
   );
 }