hazo_auth 4.5.5 → 4.5.7

package/README.md

@@ -94,6 +94,7 @@ export default function Page() {
 - ✅ Database connection initialized server-side via hazo_connect singleton
 - ✅ Configuration loaded from hazo_auth_config.ini (or uses sensible defaults)
 - ✅ All props automatically configured
+- ✅ Navbar automatically rendered based on config (no manual wrapping needed)
 - ✅ Page renders immediately - NO loading state!
 
 **Available zero-config pages:**
@@ -398,16 +399,44 @@ Run the following SQL scripts in your PostgreSQL database:
 ```sql
 -- Enum type for profile picture source
 CREATE TYPE hazo_enum_profile_source_enum AS ENUM ('gravatar', 'custom', 'predefined');
+
+-- Scope types enum (for HRBAC)
+CREATE TYPE hazo_enum_scope_types AS ENUM (
+    'hazo_scopes_l1', 'hazo_scopes_l2', 'hazo_scopes_l3',
+    'hazo_scopes_l4', 'hazo_scopes_l5', 'hazo_scopes_l6', 'hazo_scopes_l7'
+);
+```
+
+#### 2. Create the Organization Table (Multi-Tenancy)
+
+```sql
+-- Organization table for multi-tenancy (create before hazo_users)
+CREATE TABLE hazo_org (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    name TEXT NOT NULL,
+    parent_org_id UUID REFERENCES hazo_org(id) ON DELETE SET NULL,
+    root_org_id UUID REFERENCES hazo_org(id) ON DELETE SET NULL,
+    user_limit INTEGER NOT NULL DEFAULT 0,
+    active BOOLEAN NOT NULL DEFAULT TRUE,
+    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+    created_by UUID,  -- Will reference hazo_users after it's created
+    changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+    changed_by UUID
+);
+
+CREATE INDEX idx_hazo_org_parent_org_id ON hazo_org(parent_org_id);
+CREATE INDEX idx_hazo_org_root_org_id ON hazo_org(root_org_id);
+CREATE INDEX idx_hazo_org_active ON hazo_org(active);
 ```
 
-#### 2. Create the Users Table
+#### 3. Create the Users Table
 
 ```sql
 -- Main users table
 CREATE TABLE hazo_users (
     id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
     email_address TEXT NOT NULL UNIQUE,
-    password_hash TEXT NOT NULL,
+    password_hash TEXT,                                   -- NULL for OAuth-only users
     name TEXT,
     email_verified BOOLEAN NOT NULL DEFAULT FALSE,
     is_active BOOLEAN NOT NULL DEFAULT TRUE,
@@ -417,17 +446,32 @@ CREATE TABLE hazo_users (
     profile_source hazo_enum_profile_source_enum,
     mfa_secret TEXT,
     url_on_logon TEXT,
+    user_type TEXT,                                       -- Optional user categorization
+    google_id TEXT UNIQUE,                                -- Google OAuth ID
+    auth_providers TEXT DEFAULT 'email',                  -- 'email', 'google', or 'email,google'
+    org_id UUID REFERENCES hazo_org(id) ON DELETE SET NULL,
+    root_org_id UUID REFERENCES hazo_org(id) ON DELETE SET NULL,
     created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
     changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
 );
 
--- Index for email lookups
+-- Indexes
 CREATE INDEX idx_hazo_users_email ON hazo_users(email_address);
+CREATE INDEX idx_hazo_users_user_type ON hazo_users(user_type);
+CREATE UNIQUE INDEX idx_hazo_users_google_id ON hazo_users(google_id);
+CREATE INDEX idx_hazo_users_org_id ON hazo_users(org_id);
+CREATE INDEX idx_hazo_users_root_org_id ON hazo_users(root_org_id);
+
+-- Add FK constraints to hazo_org after hazo_users exists
+ALTER TABLE hazo_org ADD CONSTRAINT fk_hazo_org_created_by
+    FOREIGN KEY (created_by) REFERENCES hazo_users(id) ON DELETE SET NULL;
+ALTER TABLE hazo_org ADD CONSTRAINT fk_hazo_org_changed_by
+    FOREIGN KEY (changed_by) REFERENCES hazo_users(id) ON DELETE SET NULL;
 ```
 
 **Note:** The `url_on_logon` field is used to store a custom redirect URL for users after successful login. This allows per-user customization of post-login navigation.
 
-#### 3. Create the Refresh Tokens Table
+#### 4. Create the Refresh Tokens Table
 
 ```sql
 -- Refresh tokens table (used for password reset, email verification, etc.)
@@ -445,7 +489,7 @@ CREATE INDEX idx_hazo_refresh_tokens_user_id ON hazo_refresh_tokens(user_id);
 CREATE INDEX idx_hazo_refresh_tokens_token_type ON hazo_refresh_tokens(token_type);
 ```
 
-#### 4. Create the Permissions Table
+#### 5. Create the Permissions Table
 
 ```sql
 -- Permissions table for RBAC
@@ -458,7 +502,7 @@ CREATE TABLE hazo_permissions (
 );
 ```
 
-#### 5. Create the Roles Table
+#### 6. Create the Roles Table
 
 ```sql
 -- Roles table for RBAC
@@ -470,7 +514,7 @@ CREATE TABLE hazo_roles (
 );
 ```
 
-#### 6. Create the Role-Permissions Junction Table
+#### 7. Create the Role-Permissions Junction Table
 
 ```sql
 -- Junction table linking roles to permissions
@@ -487,7 +531,7 @@ CREATE INDEX idx_hazo_role_permissions_role_id ON hazo_role_permissions(role_id)
 CREATE INDEX idx_hazo_role_permissions_permission_id ON hazo_role_permissions(permission_id);
 ```
 
-#### 7. Create the User-Roles Junction Table
+#### 8. Create the User-Roles Junction Table
 
 ```sql
 -- Junction table linking users to roles
@@ -513,14 +557,35 @@ For convenience, here's the complete SQL script to create all tables at once:
 -- hazo_auth Database Setup Script (PostgreSQL)
 -- ============================================
 
--- 1. Create enum type
+-- 1. Create enum types
 CREATE TYPE hazo_enum_profile_source_enum AS ENUM ('gravatar', 'custom', 'predefined');
+CREATE TYPE hazo_enum_scope_types AS ENUM (
+    'hazo_scopes_l1', 'hazo_scopes_l2', 'hazo_scopes_l3',
+    'hazo_scopes_l4', 'hazo_scopes_l5', 'hazo_scopes_l6', 'hazo_scopes_l7'
+);
 
--- 2. Create users table
+-- 2. Create organization table (multi-tenancy)
+CREATE TABLE hazo_org (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    name TEXT NOT NULL,
+    parent_org_id UUID REFERENCES hazo_org(id) ON DELETE SET NULL,
+    root_org_id UUID REFERENCES hazo_org(id) ON DELETE SET NULL,
+    user_limit INTEGER NOT NULL DEFAULT 0,
+    active BOOLEAN NOT NULL DEFAULT TRUE,
+    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+    created_by UUID,
+    changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+    changed_by UUID
+);
+CREATE INDEX idx_hazo_org_parent_org_id ON hazo_org(parent_org_id);
+CREATE INDEX idx_hazo_org_root_org_id ON hazo_org(root_org_id);
+CREATE INDEX idx_hazo_org_active ON hazo_org(active);
+
+-- 3. Create users table
 CREATE TABLE hazo_users (
     id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
     email_address TEXT NOT NULL UNIQUE,
-    password_hash TEXT NOT NULL,
+    password_hash TEXT,
     name TEXT,
     email_verified BOOLEAN NOT NULL DEFAULT FALSE,
     is_active BOOLEAN NOT NULL DEFAULT TRUE,
@@ -530,12 +595,27 @@ CREATE TABLE hazo_users (
     profile_source hazo_enum_profile_source_enum,
     mfa_secret TEXT,
     url_on_logon TEXT,
+    user_type TEXT,
+    google_id TEXT UNIQUE,
+    auth_providers TEXT DEFAULT 'email',
+    org_id UUID REFERENCES hazo_org(id) ON DELETE SET NULL,
+    root_org_id UUID REFERENCES hazo_org(id) ON DELETE SET NULL,
     created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
     changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
 );
 CREATE INDEX idx_hazo_users_email ON hazo_users(email_address);
-
--- 3. Create refresh tokens table
+CREATE INDEX idx_hazo_users_user_type ON hazo_users(user_type);
+CREATE UNIQUE INDEX idx_hazo_users_google_id ON hazo_users(google_id);
+CREATE INDEX idx_hazo_users_org_id ON hazo_users(org_id);
+CREATE INDEX idx_hazo_users_root_org_id ON hazo_users(root_org_id);
+
+-- Add FK constraints to hazo_org after hazo_users exists
+ALTER TABLE hazo_org ADD CONSTRAINT fk_hazo_org_created_by
+    FOREIGN KEY (created_by) REFERENCES hazo_users(id) ON DELETE SET NULL;
+ALTER TABLE hazo_org ADD CONSTRAINT fk_hazo_org_changed_by
+    FOREIGN KEY (changed_by) REFERENCES hazo_users(id) ON DELETE SET NULL;
+
+-- 4. Create refresh tokens table
 CREATE TABLE hazo_refresh_tokens (
     id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
     user_id UUID NOT NULL REFERENCES hazo_users(id) ON DELETE CASCADE,
@@ -1101,6 +1181,8 @@ vertical_center = auto  # 'auto' enables vertical centering when navbar is prese
 
 ### Authentication Page Navbar
 
+**The navbar now works automatically** - zero-config server page components include the navbar based on configuration without manual wrapping.
+
 When using `layout_mode = standalone`, you can enable a configurable navbar that appears on all auth pages:
 
 ```ini
@@ -1120,7 +1202,17 @@ 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:**
+**Zero-config usage (recommended):**
+```typescript
+// app/hazo_auth/login/page.tsx
+import { LoginPage } from "hazo_auth/pages/login";
+
+export default function Page() {
+  return <LoginPage />;  // Navbar appears automatically if enabled in config
+}
+```
+
+**Customize via props (advanced):**
 ```typescript
 import { LoginLayout } from "hazo_auth/components/layouts/login";
 
@@ -1139,6 +1231,8 @@ export default function Page() {
 
 **Disable for specific pages:**
 ```typescript
+<LoginPage disableNavbar={true} />
+// OR for layout components:
 <LoginLayout navbar={{ enable_navbar: false }} />
 ```
 
@@ -1987,6 +2081,180 @@ For full documentation, see `CLAUDE.md` or `TECHDOC.md`.
 
 ---
 
+## App User Data (Custom User Metadata)
+
+hazo_auth provides a flexible JSON field for storing custom user-specific data without modifying the `hazo_users` table schema. This allows consuming applications to store user preferences, settings, and app-specific state.
+
+### Overview
+
+- **JSON Storage**: Single TEXT column stores JSON objects (no schema restrictions)
+- **Deep Merge Support**: PATCH endpoint merges new data with existing data
+- **Full Replace**: PUT endpoint replaces entire JSON object
+- **Clear Data**: DELETE endpoint sets field to NULL
+- **Type-Safe**: TypeScript service layer with validation
+- **Included in Auth Response**: Available in `/api/hazo_auth/me` response
+
+### Quick Start
+
+1. **Run database migration**:
+   ```bash
+   npm run migrate migrations/008_add_app_user_data_to_hazo_users.sql
+   ```
+
+2. **Create API route** (`app/api/hazo_auth/app_user_data/route.ts`):
+   ```typescript
+   export {
+     appUserDataGET as GET,
+     appUserDataPATCH as PATCH,
+     appUserDataPUT as PUT,
+     appUserDataDELETE as DELETE
+   } from "hazo_auth/server/routes";
+   ```
+
+   Or use CLI: `npx hazo_auth generate-routes`
+
+3. **Use in your app**:
+   ```typescript
+   // Store user preferences (deep merge)
+   PATCH /api/hazo_auth/app_user_data
+   {
+     data: {
+       theme: "dark",
+       language: "en-US",
+       sidebar_collapsed: true
+     }
+   }
+
+   // Access in client components
+   const { app_user_data } = use_hazo_auth();
+   console.log(app_user_data?.theme); // "dark"
+   ```
+
+### API Endpoints
+
+**GET `/api/hazo_auth/app_user_data`** - Get current user's data
+```typescript
+Response: { data: { theme: "dark", sidebar_collapsed: true } | null }
+```
+
+**PATCH `/api/hazo_auth/app_user_data`** - Merge with existing data (preserves other fields)
+```typescript
+Request: { data: { theme: "light" } }
+// If existing: { theme: "dark", sidebar_collapsed: true }
+// Result: { theme: "light", sidebar_collapsed: true }
+```
+
+**PUT `/api/hazo_auth/app_user_data`** - Replace entire object
+```typescript
+Request: { data: { theme: "light" } }
+// Result: { theme: "light" } (sidebar_collapsed removed)
+```
+
+**DELETE `/api/hazo_auth/app_user_data`** - Clear all data (sets to NULL)
+
+### Service Functions
+
+```typescript
+import {
+  get_app_user_data,
+  update_app_user_data,
+  clear_app_user_data
+} from "hazo_auth";
+
+// Get data
+const data = await get_app_user_data(adapter, user_id);
+
+// Update with merge (default)
+await update_app_user_data(adapter, user_id, { theme: "light" }, true);
+
+// Replace entirely
+await update_app_user_data(adapter, user_id, { theme: "light" }, false);
+
+// Clear data
+await clear_app_user_data(adapter, user_id);
+```
+
+### Access in `/api/hazo_auth/me`
+
+The `app_user_data` field is included in the authentication response:
+
+```typescript
+{
+  authenticated: true,
+  user: { ... },
+  permissions: [...],
+  app_user_data: { theme: "dark", sidebar_collapsed: true } | null
+}
+```
+
+### Use Cases
+
+**Store user preferences:**
+```typescript
+{
+  theme: "dark",
+  language: "en-US",
+  timezone: "America/New_York"
+}
+```
+
+**Store app-specific state:**
+```typescript
+{
+  dashboard_layout: "grid",
+  sidebar_collapsed: true,
+  recent_searches: ["tax forms", "invoices"]
+}
+```
+
+**Store nested configuration:**
+```typescript
+{
+  notifications: {
+    email: true,
+    sms: false,
+    push: true
+  },
+  privacy: {
+    profile_public: false,
+    show_email: false
+  }
+}
+```
+
+### Deep Merge Behavior
+
+```typescript
+// Existing data
+{ user: { name: "Alice", age: 30 }, theme: "dark" }
+
+// PATCH with
+{ user: { age: 31 }, sidebar: true }
+
+// Result (deep merge)
+{ user: { name: "Alice", age: 31 }, theme: "dark", sidebar: true }
+```
+
+### Test Page
+
+Visit `/hazo_auth/app_user_data_test` in your dev environment to test the API with an interactive UI:
+- View current data (live refresh)
+- Merge data (PATCH)
+- Replace data (PUT)
+- Clear data (DELETE)
+- JSON validation
+
+### Performance & Limits
+
+- **Recommended max size**: ~10KB per user (for preferences/settings)
+- **Storage**: JSON stored as TEXT (no compression)
+- **Caching**: Benefits from `hazo_get_auth()` LRU cache
+- **Large datasets**: Use separate tables for complex relational data
+
+For full documentation, see `CHANGE_LOG.md` and `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

@@ -312,15 +312,54 @@ Run this SQL script in your PostgreSQL database:
 -- Ensure we're in the public schema (or your target schema)
 SET search_path TO public;
 
--- Create enum type (drop first if it exists to avoid conflicts)
+-- Create enum types (drop first if they exist to avoid conflicts)
 DROP TYPE IF EXISTS hazo_enum_profile_source_enum CASCADE;
 CREATE TYPE hazo_enum_profile_source_enum AS ENUM ('gravatar', 'custom', 'predefined');
 
+DROP TYPE IF EXISTS hazo_enum_scope_types CASCADE;
+CREATE TYPE hazo_enum_scope_types AS ENUM (
+    'hazo_scopes_l1', 'hazo_scopes_l2', 'hazo_scopes_l3',
+    'hazo_scopes_l4', 'hazo_scopes_l5', 'hazo_scopes_l6', 'hazo_scopes_l7'
+);
+
+DROP TYPE IF EXISTS hazo_enum_notify_chain_status CASCADE;
+CREATE TYPE hazo_enum_notify_chain_status AS ENUM ('draft', 'published', 'inactive');
+
+DROP TYPE IF EXISTS hazo_enum_notify_email_type CASCADE;
+CREATE TYPE hazo_enum_notify_email_type AS ENUM ('system', 'user');
+
+DROP TYPE IF EXISTS hazo_enum_group_type CASCADE;
+CREATE TYPE hazo_enum_group_type AS ENUM ('support', 'peer', 'group');
+
+DROP TYPE IF EXISTS hazo_enum_group_role CASCADE;
+CREATE TYPE hazo_enum_group_role AS ENUM ('client', 'staff', 'owner', 'admin', 'member');
+
+DROP TYPE IF EXISTS hazo_enum_chat_type CASCADE;
+CREATE TYPE hazo_enum_chat_type AS ENUM ('chat', 'field', 'project', 'support', 'general');
+
+-- Create organization table (multi-tenancy) - MUST be created before hazo_users
+CREATE TABLE hazo_org (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    name TEXT NOT NULL,
+    parent_org_id UUID REFERENCES hazo_org(id) ON DELETE SET NULL,
+    root_org_id UUID REFERENCES hazo_org(id) ON DELETE SET NULL,
+    user_limit INTEGER NOT NULL DEFAULT 0,              -- 0 = unlimited
+    active BOOLEAN NOT NULL DEFAULT TRUE,
+    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+    created_by UUID,                                    -- FK added after hazo_users exists
+    changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+    changed_by UUID                                     -- FK added after hazo_users exists
+);
+CREATE INDEX idx_hazo_org_parent_org_id ON hazo_org(parent_org_id);
+CREATE INDEX idx_hazo_org_root_org_id ON hazo_org(root_org_id);
+CREATE INDEX idx_hazo_org_active ON hazo_org(active);
+CREATE INDEX idx_hazo_org_name ON hazo_org(name);
+
 -- Create users table
 CREATE TABLE hazo_users (
     id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
     email_address TEXT NOT NULL UNIQUE,
-    password_hash TEXT NOT NULL,
+    password_hash TEXT,                                 -- NULL for OAuth-only users
     name TEXT,
     email_verified BOOLEAN NOT NULL DEFAULT FALSE,
     is_active BOOLEAN NOT NULL DEFAULT TRUE,
@@ -330,10 +369,25 @@ CREATE TABLE hazo_users (
     profile_source hazo_enum_profile_source_enum,
     mfa_secret TEXT,
     url_on_logon TEXT,
+    user_type TEXT,                                     -- Optional user categorization
+    google_id TEXT UNIQUE,                              -- Google OAuth ID
+    auth_providers TEXT DEFAULT 'email',                -- 'email', 'google', or 'email,google'
+    org_id UUID REFERENCES hazo_org(id) ON DELETE SET NULL,
+    root_org_id UUID REFERENCES hazo_org(id) ON DELETE SET NULL,
     created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
     changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
 );
 CREATE INDEX idx_hazo_users_email ON hazo_users(email_address);
+CREATE INDEX idx_hazo_users_user_type ON hazo_users(user_type);
+CREATE UNIQUE INDEX idx_hazo_users_google_id ON hazo_users(google_id);
+CREATE INDEX idx_hazo_users_org_id ON hazo_users(org_id);
+CREATE INDEX idx_hazo_users_root_org_id ON hazo_users(root_org_id);
+
+-- Add FK constraints to hazo_org now that hazo_users exists
+ALTER TABLE hazo_org ADD CONSTRAINT fk_hazo_org_created_by
+    FOREIGN KEY (created_by) REFERENCES hazo_users(id) ON DELETE SET NULL;
+ALTER TABLE hazo_org ADD CONSTRAINT fk_hazo_org_changed_by
+    FOREIGN KEY (changed_by) REFERENCES hazo_users(id) ON DELETE SET NULL;
 
 -- Create refresh tokens table
 CREATE TABLE hazo_refresh_tokens (
@@ -453,7 +507,22 @@ GRANT USAGE ON TYPE hazo_enum_profile_source_enum TO anon, authenticated;
 
 **Checklist:**
 - [ ] Database created (SQLite file or PostgreSQL)
-- [ ] All 6 tables exist: `hazo_users`, `hazo_refresh_tokens`, `hazo_permissions`, `hazo_roles`, `hazo_role_permissions`, `hazo_user_roles`
+- [ ] All enum types created (PostgreSQL only):
+  - [ ] `hazo_enum_profile_source_enum`
+  - [ ] `hazo_enum_scope_types`
+  - [ ] `hazo_enum_notify_chain_status`
+  - [ ] `hazo_enum_notify_email_type`
+  - [ ] `hazo_enum_group_type`
+  - [ ] `hazo_enum_group_role`
+  - [ ] `hazo_enum_chat_type`
+- [ ] All core tables exist:
+  - [ ] `hazo_org` (multi-tenancy - must be created before hazo_users)
+  - [ ] `hazo_users` (with google_id, auth_providers, org_id, root_org_id, user_type fields)
+  - [ ] `hazo_refresh_tokens`
+  - [ ] `hazo_permissions`
+  - [ ] `hazo_roles`
+  - [ ] `hazo_role_permissions`
+  - [ ] `hazo_user_roles`
 
 ---
 
@@ -1244,25 +1313,29 @@ $$ LANGUAGE plpgsql;
 CREATE TABLE hazo_scopes_l1 (
     id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
     seq TEXT NOT NULL DEFAULT hazo_scope_id_generator('hazo_scopes_l1'),
-    org TEXT NOT NULL,
+    org_id UUID NOT NULL REFERENCES hazo_org(id) ON DELETE CASCADE,
+    root_org_id UUID NOT NULL REFERENCES hazo_org(id) ON DELETE CASCADE,
     name TEXT NOT NULL,
     created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
     changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
 );
-CREATE INDEX idx_hazo_scopes_l1_org ON hazo_scopes_l1(org);
+CREATE INDEX idx_hazo_scopes_l1_org_id ON hazo_scopes_l1(org_id);
+CREATE INDEX idx_hazo_scopes_l1_root_org_id ON hazo_scopes_l1(root_org_id);
 CREATE INDEX idx_hazo_scopes_l1_seq ON hazo_scopes_l1(seq);
 
 -- Level 2 (parent: L1)
 CREATE TABLE hazo_scopes_l2 (
     id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
     seq TEXT NOT NULL DEFAULT hazo_scope_id_generator('hazo_scopes_l2'),
-    org TEXT NOT NULL,
+    org_id UUID NOT NULL REFERENCES hazo_org(id) ON DELETE CASCADE,
+    root_org_id UUID NOT NULL REFERENCES hazo_org(id) ON DELETE CASCADE,
     name TEXT NOT NULL,
     parent_scope_id UUID REFERENCES hazo_scopes_l1(id) ON DELETE CASCADE,
     created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
     changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
 );
-CREATE INDEX idx_hazo_scopes_l2_org ON hazo_scopes_l2(org);
+CREATE INDEX idx_hazo_scopes_l2_org_id ON hazo_scopes_l2(org_id);
+CREATE INDEX idx_hazo_scopes_l2_root_org_id ON hazo_scopes_l2(root_org_id);
 CREATE INDEX idx_hazo_scopes_l2_seq ON hazo_scopes_l2(seq);
 CREATE INDEX idx_hazo_scopes_l2_parent ON hazo_scopes_l2(parent_scope_id);
 
@@ -1270,13 +1343,15 @@ CREATE INDEX idx_hazo_scopes_l2_parent ON hazo_scopes_l2(parent_scope_id);
 CREATE TABLE hazo_scopes_l3 (
     id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
     seq TEXT NOT NULL DEFAULT hazo_scope_id_generator('hazo_scopes_l3'),
-    org TEXT NOT NULL,
+    org_id UUID NOT NULL REFERENCES hazo_org(id) ON DELETE CASCADE,
+    root_org_id UUID NOT NULL REFERENCES hazo_org(id) ON DELETE CASCADE,
     name TEXT NOT NULL,
     parent_scope_id UUID REFERENCES hazo_scopes_l2(id) ON DELETE CASCADE,
     created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
     changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
 );
-CREATE INDEX idx_hazo_scopes_l3_org ON hazo_scopes_l3(org);
+CREATE INDEX idx_hazo_scopes_l3_org_id ON hazo_scopes_l3(org_id);
+CREATE INDEX idx_hazo_scopes_l3_root_org_id ON hazo_scopes_l3(root_org_id);
 CREATE INDEX idx_hazo_scopes_l3_seq ON hazo_scopes_l3(seq);
 CREATE INDEX idx_hazo_scopes_l3_parent ON hazo_scopes_l3(parent_scope_id);
 
@@ -1284,13 +1359,15 @@ CREATE INDEX idx_hazo_scopes_l3_parent ON hazo_scopes_l3(parent_scope_id);
 CREATE TABLE hazo_scopes_l4 (
     id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
     seq TEXT NOT NULL DEFAULT hazo_scope_id_generator('hazo_scopes_l4'),
-    org TEXT NOT NULL,
+    org_id UUID NOT NULL REFERENCES hazo_org(id) ON DELETE CASCADE,
+    root_org_id UUID NOT NULL REFERENCES hazo_org(id) ON DELETE CASCADE,
     name TEXT NOT NULL,
     parent_scope_id UUID REFERENCES hazo_scopes_l3(id) ON DELETE CASCADE,
     created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
     changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
 );
-CREATE INDEX idx_hazo_scopes_l4_org ON hazo_scopes_l4(org);
+CREATE INDEX idx_hazo_scopes_l4_org_id ON hazo_scopes_l4(org_id);
+CREATE INDEX idx_hazo_scopes_l4_root_org_id ON hazo_scopes_l4(root_org_id);
 CREATE INDEX idx_hazo_scopes_l4_seq ON hazo_scopes_l4(seq);
 CREATE INDEX idx_hazo_scopes_l4_parent ON hazo_scopes_l4(parent_scope_id);
 
@@ -1298,13 +1375,15 @@ CREATE INDEX idx_hazo_scopes_l4_parent ON hazo_scopes_l4(parent_scope_id);
 CREATE TABLE hazo_scopes_l5 (
     id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
     seq TEXT NOT NULL DEFAULT hazo_scope_id_generator('hazo_scopes_l5'),
-    org TEXT NOT NULL,
+    org_id UUID NOT NULL REFERENCES hazo_org(id) ON DELETE CASCADE,
+    root_org_id UUID NOT NULL REFERENCES hazo_org(id) ON DELETE CASCADE,
     name TEXT NOT NULL,
     parent_scope_id UUID REFERENCES hazo_scopes_l4(id) ON DELETE CASCADE,
     created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
     changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
 );
-CREATE INDEX idx_hazo_scopes_l5_org ON hazo_scopes_l5(org);
+CREATE INDEX idx_hazo_scopes_l5_org_id ON hazo_scopes_l5(org_id);
+CREATE INDEX idx_hazo_scopes_l5_root_org_id ON hazo_scopes_l5(root_org_id);
 CREATE INDEX idx_hazo_scopes_l5_seq ON hazo_scopes_l5(seq);
 CREATE INDEX idx_hazo_scopes_l5_parent ON hazo_scopes_l5(parent_scope_id);
 
@@ -1312,13 +1391,15 @@ CREATE INDEX idx_hazo_scopes_l5_parent ON hazo_scopes_l5(parent_scope_id);
 CREATE TABLE hazo_scopes_l6 (
     id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
     seq TEXT NOT NULL DEFAULT hazo_scope_id_generator('hazo_scopes_l6'),
-    org TEXT NOT NULL,
+    org_id UUID NOT NULL REFERENCES hazo_org(id) ON DELETE CASCADE,
+    root_org_id UUID NOT NULL REFERENCES hazo_org(id) ON DELETE CASCADE,
     name TEXT NOT NULL,
     parent_scope_id UUID REFERENCES hazo_scopes_l5(id) ON DELETE CASCADE,
     created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
     changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
 );
-CREATE INDEX idx_hazo_scopes_l6_org ON hazo_scopes_l6(org);
+CREATE INDEX idx_hazo_scopes_l6_org_id ON hazo_scopes_l6(org_id);
+CREATE INDEX idx_hazo_scopes_l6_root_org_id ON hazo_scopes_l6(root_org_id);
 CREATE INDEX idx_hazo_scopes_l6_seq ON hazo_scopes_l6(seq);
 CREATE INDEX idx_hazo_scopes_l6_parent ON hazo_scopes_l6(parent_scope_id);
 
@@ -1326,13 +1407,15 @@ CREATE INDEX idx_hazo_scopes_l6_parent ON hazo_scopes_l6(parent_scope_id);
 CREATE TABLE hazo_scopes_l7 (
     id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
     seq TEXT NOT NULL DEFAULT hazo_scope_id_generator('hazo_scopes_l7'),
-    org TEXT NOT NULL,
+    org_id UUID NOT NULL REFERENCES hazo_org(id) ON DELETE CASCADE,
+    root_org_id UUID NOT NULL REFERENCES hazo_org(id) ON DELETE CASCADE,
     name TEXT NOT NULL,
     parent_scope_id UUID REFERENCES hazo_scopes_l6(id) ON DELETE CASCADE,
     created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
     changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
 );
-CREATE INDEX idx_hazo_scopes_l7_org ON hazo_scopes_l7(org);
+CREATE INDEX idx_hazo_scopes_l7_org_id ON hazo_scopes_l7(org_id);
+CREATE INDEX idx_hazo_scopes_l7_root_org_id ON hazo_scopes_l7(root_org_id);
 CREATE INDEX idx_hazo_scopes_l7_seq ON hazo_scopes_l7(seq);
 CREATE INDEX idx_hazo_scopes_l7_parent ON hazo_scopes_l7(parent_scope_id);
 
@@ -1353,14 +1436,14 @@ CREATE INDEX idx_hazo_user_scopes_scope_type ON hazo_user_scopes(scope_type);
 -- 5. Create scope labels table
 CREATE TABLE hazo_scope_labels (
     id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-    org TEXT NOT NULL,
+    org_id UUID NOT NULL REFERENCES hazo_org(id) ON DELETE CASCADE,
     scope_type hazo_enum_scope_types NOT NULL,
     label TEXT NOT NULL,
     created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
     changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
-    UNIQUE(org, scope_type)
+    UNIQUE(org_id, scope_type)
 );
-CREATE INDEX idx_hazo_scope_labels_org ON hazo_scope_labels(org);
+CREATE INDEX idx_hazo_scope_labels_org_id ON hazo_scope_labels(org_id);
 ```
 
 #### PostgreSQL Grant Scripts
@@ -1522,7 +1605,11 @@ sqlite3 data/hazo_auth.sqlite ".tables" | grep -E "hazo_scopes|hazo_user_scopes|
 **HRBAC Checklist:**
 - [ ] `enable_hrbac = true` in config
 - [ ] HRBAC permissions added to defaults
-- [ ] All 9 HRBAC tables created
+- [ ] All 9 HRBAC tables created:
+  - [ ] `hazo_scopes_l1` through `hazo_scopes_l7` (with org_id, root_org_id FKs)
+  - [ ] `hazo_user_scopes` (junction table)
+  - [ ] `hazo_scope_labels` (custom labels per org)
+- [ ] Scope ID generator function created (PostgreSQL)
 - [ ] Grants applied (PostgreSQL)
 - [ ] HRBAC tabs visible in User Management
 - [ ] Scope test page works

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

@@ -10,6 +10,8 @@ export type HazoAuthUser = {
   email_address: string;
   is_active: boolean;
   profile_picture_url: string | null;
+  // App-specific user data (JSON object stored as TEXT in database)
+  app_user_data: Record<string, unknown> | null;
   // Multi-tenancy fields (only populated when multi-tenancy is enabled)
   org_id?: string | null;
   org_name?: string | null;