hazo_auth 4.4.1 → 4.5.1

package/README.md

@@ -29,6 +29,7 @@ A reusable authentication UI component package powered by Next.js, TailwindCSS,
 - [Authentication Service](#authentication-service)
 - [Proxy/Middleware Authentication](#proxymiddleware-authentication)
 - [Profile Picture Menu Widget](#profile-picture-menu-widget)
+- [User Types (Optional Feature)](#user-types-optional-feature)
 - [User Profile Service](#user-profile-service)
 - [Local Development](#local-development)
 
@@ -1030,6 +1031,35 @@ export { GET, POST, PUT } from "hazo_auth/server/routes";
   - **UI Enhancement**: The Roles tab uses a tag-based UI for better readability. Each role displays permissions as inline tags/chips (showing up to 4, with "+N more" to expand). Edit permissions via an interactive dialog with Select All/Unselect All buttons.
 - **User Roles:** Get user roles, assign roles to users, bulk update user role assignments
 
+---
+
+### Organization Management Component
+
+The `OrgManagementLayout` component provides an admin interface for managing the organization hierarchy when multi-tenancy is enabled. It requires the org_management API routes to be set up in your project.
+
+**Required Permissions:**
+- `hazo_perm_org_management` - CRUD operations on organizations
+- `hazo_org_global_admin` - View/manage all organizations across the system (optional, for global admins)
+
+**Required API Routes:**
+The `OrgManagementLayout` component requires the following API route to be created in your project:
+
+```typescript
+// app/api/hazo_auth/org_management/orgs/route.ts
+export {
+  orgManagementOrgsGET as GET,
+  orgManagementOrgsPOST as POST,
+  orgManagementOrgsPATCH as PATCH,
+  orgManagementOrgsDELETE as DELETE
+} from "hazo_auth/server/routes";
+```
+
+**Note:** This route is automatically created when you run `npx hazo_auth generate-routes`. The route handles:
+- **GET:** List organizations (with `action=tree` query parameter for hierarchical tree structure)
+- **POST:** Create new organization
+- **PATCH:** Update existing organization (name, user_limit, active status)
+- **DELETE:** Soft delete organization (sets active=false, does not remove from database)
+
 **Example Usage:**
 
 ```tsx
@@ -1055,7 +1085,8 @@ By default, the pages render inside the "test workspace" sidebar so you can quic
 ```ini
 [hazo_auth__ui_shell]
 # Options: test_sidebar | standalone
-layout_mode = standalone 
+layout_mode = standalone
+vertical_center = auto  # 'auto' enables vertical centering when navbar is present
 # Optional tweaks for the standalone header wrapper/classes:
 # standalone_heading = Welcome back
 # standalone_description = Your description here
@@ -1065,8 +1096,52 @@ layout_mode = standalone
 
 - `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.
+- `vertical_center`: controls vertical centering of auth content (`auto` enables centering when navbar is present)
 - The wrapper and content class overrides let you align spacing/borders with your design system without editing package code.
 
+### Authentication Page Navbar
+
+When using `layout_mode = standalone`, you can enable a configurable navbar that appears on all auth pages:
+
+```ini
+[hazo_auth__navbar]
+enable_navbar = true              # Show navbar on auth pages
+logo_path = /logo.png             # Path to logo image
+logo_width = 32                   # Logo width in pixels
+logo_height = 32                  # Logo height in pixels
+company_name = My Company         # Company name (links to home)
+home_path = /                     # URL for logo and company name link
+home_label = Home                 # Label for home link
+show_home_link = true             # Show "Home" link on right side
+background_color =                # Custom background (optional)
+text_color =                      # Custom text color (optional)
+height = 64                       # Navbar height in pixels
+```
+
+The navbar provides consistent branding across authentication pages with your company logo, name, and optional home link. It automatically vertically centers auth content when enabled.
+
+**Customize via props:**
+```typescript
+import { LoginLayout } from "hazo_auth/components/layouts/login";
+
+export default function Page() {
+  return (
+    <LoginLayout
+      navbar={{
+        logo_path: "/custom-logo.svg",
+        company_name: "Acme Corp",
+        background_color: "#1a1a1a",
+      }}
+    />
+  );
+}
+```
+
+**Disable for specific pages:**
+```typescript
+<LoginLayout navbar={{ enable_navbar: false }} />
+```
+
 ---
 
 ## Authentication Service
@@ -1479,7 +1554,7 @@ Add the following to your `hazo_auth_config.ini`:
 ```ini
 [hazo_auth__scope_hierarchy]
 enable_hrbac = true
-default_org = my_organization  # Optional: default organization for single-tenant apps
+# Note: No default_org needed - org determined from user authentication
 scope_cache_ttl_minutes = 15
 scope_cache_max_entries = 5000
 
@@ -1586,16 +1661,14 @@ The `RbacTestLayout` component provides a comprehensive testing interface for ad
 ```typescript
 // app/admin/rbac-test/page.tsx
 import { RbacTestLayout } from "hazo_auth/components/layouts/rbac_test";
-import { is_hrbac_enabled, get_default_org } from "hazo_auth/lib/scope_hierarchy_config.server";
+import { is_hrbac_enabled } from "hazo_auth/lib/scope_hierarchy_config.server";
 
 export default function RbacTestPage() {
   const hrbacEnabled = is_hrbac_enabled();
-  const defaultOrg = get_default_org();
 
   return (
     <RbacTestLayout
       hrbacEnabled={hrbacEnabled}
-      defaultOrg={defaultOrg}
     />
   );
 }
@@ -1785,6 +1858,135 @@ custom_menu_items = info:Phone:+1234567890:3,separator:2,link:My Account:/accoun
 
 ---
 
+## User Types (Optional Feature)
+
+hazo_auth provides an optional user type categorization system for classifying users with visual badge indicators. This feature is useful for applications managing multiple user personas (e.g., "Client" vs "Tax Agent", "Internal" vs "External", "Premium" vs "Standard").
+
+### Overview
+
+- **Config-based**: Define types in `hazo_auth_config.ini` (no UI management needed)
+- **Single type per user**: Mutually exclusive categories (not tags)
+- **Visual badges**: Color-coded badges with preset or custom hex colors
+- **Zero impact when disabled**: Optional feature, disabled by default
+- **Separate from RBAC**: Types are labels, roles control permissions
+
+### Quick Start
+
+1. **Enable in configuration** (`hazo_auth_config.ini`):
+   ```ini
+   [hazo_auth__user_types]
+   enable_user_types = true
+   default_user_type = standard
+   user_type_1 = standard:Standard User:blue
+   user_type_2 = client:Client:green
+   user_type_3 = agent:Tax Agent:orange
+   ```
+
+2. **Run database migration**:
+   ```bash
+   npm run migrate migrations/007_add_user_type_to_hazo_users.sql
+   ```
+
+3. **Use in User Management**:
+   ```typescript
+   import { UserManagementLayout } from "hazo_auth/components/layouts/user_management";
+
+   <UserManagementLayout
+     userTypesEnabled={true}
+     availableUserTypes={[
+       { key: "standard", label: "Standard User", badge_color: "blue" },
+       { key: "client", label: "Client", badge_color: "green" }
+     ]}
+   />
+   ```
+
+### Configuration Format
+
+Each user type is defined as `key:label:badge_color`:
+- **key**: Unique identifier stored in database (e.g., "client")
+- **label**: Display name shown in UI (e.g., "Client")
+- **badge_color**: Preset color name (blue, green, red, yellow, purple, gray, orange, pink) or hex code (#4CAF50)
+
+### API Changes
+
+**`/api/hazo_auth/me` now includes user type info**:
+```typescript
+{
+  authenticated: true,
+  // ... existing fields
+  user_type: "client",        // User's type key
+  user_type_info: {           // Type details
+    key: "client",
+    label: "Client",
+    badge_color: "green"
+  }
+}
+```
+
+**New endpoint `/api/hazo_auth/user_management/user_types`** (GET):
+Returns user types configuration for populating dropdowns.
+
+### UserTypeBadge Component
+
+Display user types with color-coded badges:
+
+```typescript
+import { UserTypeBadge } from "hazo_auth/components/ui/user-type-badge";
+
+<UserTypeBadge
+  type="client"
+  label="Client"
+  badge_color="green"
+  variant="badge"  // or "text" for plain text
+/>
+```
+
+### Example Configurations
+
+**Simple Premium/Standard tiers**:
+```ini
+[hazo_auth__user_types]
+enable_user_types = true
+default_user_type = standard
+user_type_1 = standard:Standard:blue
+user_type_2 = premium:Premium:#FFD700
+```
+
+**Tax accounting personas**:
+```ini
+[hazo_auth__user_types]
+enable_user_types = true
+user_type_1 = client:Client:green
+user_type_2 = tax_agent:Tax Agent:orange
+user_type_3 = bookkeeper:Bookkeeper:blue
+```
+
+### Key Differences from RBAC
+
+| Feature | User Types | Roles |
+|---------|-----------|-------|
+| **Purpose** | Categorize/label users | Control permissions |
+| **Configuration** | INI file | Database + UI |
+| **Assignment** | One type per user | Multiple roles per user |
+| **Example** | "Client", "Agent" | "Admin", "Editor" |
+| **Use case** | Visual identification | Access control |
+
+A user can have type "Client" with role "Admin" - types and roles are independent.
+
+### Default Type Assignment
+
+New registrations automatically receive the `default_user_type` when configured:
+
+```ini
+[hazo_auth__user_types]
+enable_user_types = true
+default_user_type = standard  # New users get "standard" type
+```
+
+For full documentation, see `CLAUDE.md` or `TECHDOC.md`.
+
+---
+
 ## User Profile Service
 
 The `hazo_auth` package provides a batch user profile retrieval service for applications that need basic user information, such as chat applications or user lists.

package/SETUP_CHECKLIST.md

@@ -1171,7 +1171,7 @@ Add to your `hazo_auth_config.ini`:
 ```ini
 [hazo_auth__scope_hierarchy]
 enable_hrbac = true
-default_org = my_organization
+# Note: No default_org needed - org determined from user authentication
 scope_cache_ttl_minutes = 15
 scope_cache_max_entries = 5000
 

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

@@ -32,6 +32,7 @@ export type ScopeAccessInfo = {
  * Result type for hazo_get_auth function
  * Returns authenticated state with user data and permissions, or unauthenticated state
  * Optionally includes scope access information when HRBAC is used
+ * Optionally includes org_ok when require_org option is used
  */
 export type HazoAuthResult =
   | {
@@ -43,6 +44,8 @@ export type HazoAuthResult =
       // HRBAC scope access fields (only present when scope options are provided)
       scope_ok?: boolean;
       scope_access_via?: ScopeAccessInfo;
+      // Multi-tenancy org check (only present when require_org option is used)
+      org_ok?: boolean;
     }
   | {
       authenticated: false;
@@ -50,6 +53,7 @@ export type HazoAuthResult =
       permissions: [];
       permission_ok: false;
       scope_ok?: false;
+      org_ok?: false;
     };
 
 /**
@@ -82,6 +86,13 @@ export type HazoAuthOptions = {
    * Used if scope_id is not provided
    */
   scope_seq?: string;
+  // Multi-tenancy options
+  /**
+   * If true, throws OrgRequiredError when user has no org_id assigned
+   * Only checked when multi-tenancy is enabled
+   * If false or not set (default), org_id is optional and org fields may be null
+   */
+  require_org?: boolean;
 };
 
 /**
@@ -115,3 +126,14 @@ export class ScopeAccessError extends Error {
   }
 }
 
+/**
+ * Custom error class for missing organization assignment
+ * Thrown when require_org: true is set but user has no org_id assigned
+ */
+export class OrgRequiredError extends Error {
+  constructor(public user_id: string) {
+    super(`User ${user_id} is not assigned to an organization`);
+    this.name = "OrgRequiredError";
+  }
+}
+

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

@@ -6,7 +6,7 @@ import { createCrudService } from "hazo_connect/server";
 import { create_app_logger } from "../app_logger.js";
 import { get_filename, get_line_number } from "../utils/api_route_helpers.js";
 import type { HazoAuthResult, HazoAuthUser, HazoAuthOptions, ScopeAccessInfo } from "./auth_types";
-import { PermissionError, ScopeAccessError } from "./auth_types.js";
+import { PermissionError, ScopeAccessError, OrgRequiredError } from "./auth_types.js";
 import { get_auth_cache } from "./auth_cache.js";
 import { get_scope_cache, type UserScopeEntry } from "./scope_cache.js";
 import { get_rate_limiter } from "./auth_rate_limiter.js";
@@ -570,6 +570,29 @@ export async function hazo_get_auth(
     }
   }
 
+  // Check org requirement if specified (only when multi-tenancy is enabled)
+  let org_ok: boolean | undefined;
+
+  if (options?.require_org && is_multi_tenancy_enabled()) {
+    org_ok = !!user.org_id;
+
+    if (!org_ok) {
+      // Log org requirement failure if permission logging is enabled
+      if (config.log_permission_denials) {
+        const client_ip = get_client_ip(request);
+        logger.warn("auth_utility_org_required_missing", {
+          filename: get_filename(),
+          line_number: get_line_number(),
+          user_id: user.id,
+          ip: client_ip,
+        });
+      }
+
+      // Always throw error when org is required but missing
+      throw new OrgRequiredError(user.id);
+    }
+  }
+
   return {
     authenticated: true,
     user,
@@ -578,6 +601,7 @@ export async function hazo_get_auth(
     missing_permissions,
     scope_ok,
     scope_access_via,
+    org_ok,
   };
 }
 

package/cli-src/lib/auth/session_token_validator.edge.ts

@@ -93,3 +93,4 @@ export async function validate_session_cookie(
 
 
 
+

package/cli-src/lib/config/default_config.ts

@@ -177,6 +177,40 @@ export const DEFAULT_MULTI_TENANCY = {
   default_user_limit: 0,
 } as const;
 
+// section: navbar
+export const DEFAULT_NAVBAR = {
+  /** Enable navbar on auth pages */
+  enable_navbar: true,
+  /** Logo image path (default: /logo.png in public folder) */
+  logo_path: "/logo.png",
+  /** Logo width in pixels */
+  logo_width: 32,
+  /** Logo height in pixels */
+  logo_height: 32,
+  /** Company/application name displayed next to logo */
+  company_name: "",
+  /** Home link path */
+  home_path: "/",
+  /** Home link label */
+  home_label: "Home",
+  /** Show home link */
+  show_home_link: true,
+  /** Navbar background color (empty = transparent/inherit) */
+  background_color: "",
+  /** Navbar text color (empty = inherit) */
+  text_color: "",
+  /** Navbar height in pixels */
+  height: 64,
+} as const;
+
+// section: user_types
+export const DEFAULT_USER_TYPES = {
+  /** Enable user types feature (default: false) */
+  enable_user_types: false,
+  /** Default user type for new users (empty = no default) */
+  default_user_type: "",
+} as const;
+
 // section: dev_lock
 export const DEFAULT_DEV_LOCK = {
   /** Enable the development lock screen (also requires HAZO_AUTH_DEV_LOCK_ENABLED env var) */
@@ -234,6 +268,8 @@ export const HAZO_AUTH_DEFAULTS = {
   oauth: DEFAULT_OAUTH,
   devLock: DEFAULT_DEV_LOCK,
   multiTenancy: DEFAULT_MULTI_TENANCY,
+  navbar: DEFAULT_NAVBAR,
+  userTypes: DEFAULT_USER_TYPES,
 } as const;
 
 // section: types

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

@@ -0,0 +1,129 @@
+// file_description: server-only helper to read navbar configuration from hazo_auth_config.ini
+// section: imports
+import { get_config_value, get_config_boolean, get_config_number } from "./config/config_loader.server.js";
+import { DEFAULT_NAVBAR } from "./config/default_config.js";
+
+// section: types
+export type NavbarConfig = {
+  /** Enable navbar on auth pages */
+  enable_navbar: boolean;
+  /** Logo image path */
+  logo_path: string;
+  /** Logo width in pixels */
+  logo_width: number;
+  /** Logo height in pixels */
+  logo_height: number;
+  /** Company/application name displayed next to logo */
+  company_name: string;
+  /** Home link path */
+  home_path: string;
+  /** Home link label */
+  home_label: string;
+  /** Show home link */
+  show_home_link: boolean;
+  /** Navbar background color (empty = inherit) */
+  background_color: string;
+  /** Navbar text color (empty = inherit) */
+  text_color: string;
+  /** Navbar height in pixels */
+  height: number;
+};
+
+// section: constants
+const SECTION_NAME = "hazo_auth__navbar";
+
+// section: helpers
+/**
+ * Reads navbar configuration from hazo_auth_config.ini file
+ * Falls back to defaults if hazo_auth_config.ini is not found or section is missing
+ * @returns Navbar configuration options
+ */
+export function get_navbar_config(): NavbarConfig {
+  const enable_navbar = get_config_boolean(
+    SECTION_NAME,
+    "enable_navbar",
+    DEFAULT_NAVBAR.enable_navbar
+  );
+
+  const logo_path = get_config_value(
+    SECTION_NAME,
+    "logo_path",
+    DEFAULT_NAVBAR.logo_path
+  );
+
+  const logo_width = get_config_number(
+    SECTION_NAME,
+    "logo_width",
+    DEFAULT_NAVBAR.logo_width
+  );
+
+  const logo_height = get_config_number(
+    SECTION_NAME,
+    "logo_height",
+    DEFAULT_NAVBAR.logo_height
+  );
+
+  const company_name = get_config_value(
+    SECTION_NAME,
+    "company_name",
+    DEFAULT_NAVBAR.company_name
+  );
+
+  const home_path = get_config_value(
+    SECTION_NAME,
+    "home_path",
+    DEFAULT_NAVBAR.home_path
+  );
+
+  const home_label = get_config_value(
+    SECTION_NAME,
+    "home_label",
+    DEFAULT_NAVBAR.home_label
+  );
+
+  const show_home_link = get_config_boolean(
+    SECTION_NAME,
+    "show_home_link",
+    DEFAULT_NAVBAR.show_home_link
+  );
+
+  const background_color = get_config_value(
+    SECTION_NAME,
+    "background_color",
+    DEFAULT_NAVBAR.background_color
+  );
+
+  const text_color = get_config_value(
+    SECTION_NAME,
+    "text_color",
+    DEFAULT_NAVBAR.text_color
+  );
+
+  const height = get_config_number(
+    SECTION_NAME,
+    "height",
+    DEFAULT_NAVBAR.height
+  );
+
+  return {
+    enable_navbar,
+    logo_path,
+    logo_width,
+    logo_height,
+    company_name,
+    home_path,
+    home_label,
+    show_home_link,
+    background_color,
+    text_color,
+    height,
+  };
+}
+
+/**
+ * Helper to check if navbar is enabled in config
+ * @returns true if navbar is enabled
+ */
+export function is_navbar_enabled(): boolean {
+  return get_config_boolean(SECTION_NAME, "enable_navbar", DEFAULT_NAVBAR.enable_navbar);
+}

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

@@ -13,12 +13,12 @@ import { SCOPE_LEVELS } from "./services/scope_service.js";
 
 /**
  * Scope hierarchy configuration options for HRBAC
+ * Note: Scopes are now connected to organizations via org_id and root_org_id
+ * foreign keys referencing the hazo_org table.
  */
 export type ScopeHierarchyConfig = {
   /** Whether HRBAC is enabled (default: false) */
   enable_hrbac: boolean;
-  /** Default organization for single-tenant apps (optional) */
-  default_org: string;
   /** Cache TTL in minutes for scope lookups (default: 15) */
   scope_cache_ttl_minutes: number;
   /** Maximum entries in scope cache (default: 5000) */
@@ -88,15 +88,13 @@ function get_default_labels(): Record<ScopeLevel, string> {
 /**
  * Reads HRBAC scope hierarchy configuration from hazo_auth_config.ini file
  * Falls back to defaults if config file is not found or section is missing
+ * Note: Scopes are now connected to organizations via org_id/root_org_id FK references
  * @returns Scope hierarchy configuration options
  */
 export function get_scope_hierarchy_config(): ScopeHierarchyConfig {
   // Core HRBAC enablement
   const enable_hrbac = get_config_boolean(SECTION_NAME, "enable_hrbac", false);
 
-  // Default organization for single-tenant apps
-  const default_org = get_config_value(SECTION_NAME, "default_org", "");
-
   // Cache settings
   const scope_cache_ttl_minutes = get_config_number(
     SECTION_NAME,
@@ -118,7 +116,6 @@ export function get_scope_hierarchy_config(): ScopeHierarchyConfig {
 
   return {
     enable_hrbac,
-    default_org,
     scope_cache_ttl_minutes,
     scope_cache_max_entries,
     active_levels,
@@ -134,14 +131,6 @@ export function is_hrbac_enabled(): boolean {
   return get_config_boolean(SECTION_NAME, "enable_hrbac", false);
 }
 
-/**
- * Gets the default organization from config
- * Returns empty string if not configured (multi-tenant mode)
- */
-export function get_default_org(): string {
-  return get_config_value(SECTION_NAME, "default_org", "");
-}
-
 /**
  * Gets the default label for a scope level
  */

package/cli-src/lib/services/registration_service.ts

@@ -12,6 +12,10 @@ import { create_app_logger } from "../app_logger.js";
 import { send_template_email } from "./email_service.js";
 import { sanitize_error_for_user } from "../utils/error_sanitizer.js";
 import { get_filename, get_line_number } from "../utils/api_route_helpers.js";
+import {
+  is_user_types_enabled,
+  get_default_user_type,
+} from "../user_types_config.server.js";
 
 // section: types
 export type RegistrationData = {
@@ -100,6 +104,14 @@ export async function register_user(
       }
     }
 
+    // Set default user type if feature is enabled and default is configured
+    if (is_user_types_enabled()) {
+      const default_type = get_default_user_type();
+      if (default_type) {
+        insert_data.user_type = default_type;
+      }
+    }
+
     const inserted_users = await users_service.insert(insert_data);
 
     // Verify insertion was successful