hazo_auth 4.5.6 → 4.6.0

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:**
@@ -381,6 +382,22 @@ HAZO_AUTH_GOOGLE_CLIENT_SECRET=your_google_client_secret
 
 See [Google OAuth Setup](#google-oauth-setup) for detailed instructions.
 
+**For Cookie Customization (optional):**
+```env
+# Cookie prefix (prevents conflicts when running multiple apps on localhost)
+HAZO_AUTH_COOKIE_PREFIX=myapp_
+
+# Cookie domain (optional, for cross-subdomain sharing)
+HAZO_AUTH_COOKIE_DOMAIN=.example.com
+```
+
+These environment variables are required for Edge Runtime (middleware) when using cookie customization. Also set in `hazo_auth_config.ini`:
+```ini
+[hazo_auth__cookies]
+cookie_prefix = myapp_
+cookie_domain = .example.com
+```
+
 **Important:** The configuration files must be located in your project root directory (where `process.cwd()` points to), not inside `node_modules`. The package reads configuration from `process.cwd()` at runtime, so storing them elsewhere (including `node_modules/hazo_auth`) will break runtime access.
 
 ---
@@ -1180,6 +1197,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
@@ -1199,7 +1218,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";
 
@@ -1218,6 +1247,8 @@ export default function Page() {
 
 **Disable for specific pages:**
 ```typescript
+<LoginPage disableNavbar={true} />
+// OR for layout components:
 <LoginLayout navbar={{ enable_navbar: false }} />
 ```
 
@@ -2066,6 +2097,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

@@ -197,6 +197,10 @@ HAZO_CONNECT_POSTGREST_API_KEY=your_postgrest_api_key_here
 # Required for JWT authentication
 JWT_SECRET=your_secure_random_string_at_least_32_characters
 # Note: JWT_SECRET is required for JWT session token functionality (Edge-compatible proxy/middleware authentication)
+
+# Optional: Cookie customization (prevents conflicts when running multiple apps)
+HAZO_AUTH_COOKIE_PREFIX=myapp_
+HAZO_AUTH_COOKIE_DOMAIN=
 ```
 
 **Generate a secure JWT secret:**
@@ -204,6 +208,18 @@ JWT_SECRET=your_secure_random_string_at_least_32_characters
 openssl rand -base64 32
 ```
 
+**Cookie Customization (Optional):**
+If you're running multiple apps that use hazo_auth on localhost (different ports), set `HAZO_AUTH_COOKIE_PREFIX` to prevent cookie conflicts. For example:
+- App 1 (port 3000): `HAZO_AUTH_COOKIE_PREFIX=app1_`
+- App 2 (port 3001): `HAZO_AUTH_COOKIE_PREFIX=app2_`
+
+Also configure in `hazo_auth_config.ini`:
+```ini
+[hazo_auth__cookies]
+cookie_prefix = myapp_
+cookie_domain =
+```
+
 ### Step 2.2: Configure email settings
 
 Edit `hazo_notify_config.ini`:
@@ -312,15 +328,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 +385,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 +523,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 +1329,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 +1359,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 +1375,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 +1391,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 +1407,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 +1423,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 +1452,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 +1621,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;

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

@@ -4,6 +4,7 @@ import { NextRequest, NextResponse } from "next/server";
 import { get_hazo_connect_instance } from "../hazo_connect_instance.server.js";
 import { createCrudService } from "hazo_connect/server";
 import { map_db_source_to_ui } from "../services/profile_picture_source_mapper.js";
+import { get_cookie_name, get_cookie_options, BASE_COOKIE_NAMES } from "../cookies_config.server.js";
 
 // section: types
 export type AuthUser = {
@@ -24,19 +25,17 @@ export type AuthResult =
 
 // section: helpers
 /**
- * Clears authentication cookies from response
+ * Clears authentication cookies from response (with configurable prefix and domain)
  * @param response - NextResponse object to clear cookies from
  * @returns The response with cleared cookies
  */
 function clear_auth_cookies(response: NextResponse): NextResponse {
-  response.cookies.set("hazo_auth_user_email", "", {
-    expires: new Date(0),
-    path: "/",
-  });
-  response.cookies.set("hazo_auth_user_id", "", {
+  const clear_cookie_options = get_cookie_options({
     expires: new Date(0),
     path: "/",
   });
+  response.cookies.set(get_cookie_name(BASE_COOKIE_NAMES.USER_EMAIL), "", clear_cookie_options);
+  response.cookies.set(get_cookie_name(BASE_COOKIE_NAMES.USER_ID), "", clear_cookie_options);
   return response;
 }
 
@@ -48,8 +47,8 @@ function clear_auth_cookies(response: NextResponse): NextResponse {
  * @returns AuthResult with user info or authenticated: false
  */
 export async function get_authenticated_user(request: NextRequest): Promise<AuthResult> {
-  const user_id = request.cookies.get("hazo_auth_user_id")?.value;
-  const user_email = request.cookies.get("hazo_auth_user_email")?.value;
+  const user_id = request.cookies.get(get_cookie_name(BASE_COOKIE_NAMES.USER_ID))?.value;
+  const user_email = request.cookies.get(get_cookie_name(BASE_COOKIE_NAMES.USER_EMAIL))?.value;
 
   if (!user_id || !user_email) {
     return { authenticated: false };
@@ -132,8 +131,8 @@ export async function get_authenticated_user_with_response(request: NextRequest)
   auth_result: AuthResult;
   response?: NextResponse;
 }> {
-  const user_id = request.cookies.get("hazo_auth_user_id")?.value;
-  const user_email = request.cookies.get("hazo_auth_user_email")?.value;
+  const user_id = request.cookies.get(get_cookie_name(BASE_COOKIE_NAMES.USER_ID))?.value;
+  const user_email = request.cookies.get(get_cookie_name(BASE_COOKIE_NAMES.USER_EMAIL))?.value;
 
   if (!user_id || !user_email) {
     return { auth_result: { authenticated: false } };

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

@@ -2,9 +2,9 @@
 // Uses Web Crypto API which works in Edge Runtime (no Node.js crypto module)
 // section: imports
 import type { NextRequest } from "next/server";
+import { get_cookie_name_edge, BASE_COOKIE_NAMES } from "../cookies_config.edge.js";
 
 // section: constants
-const COOKIE_NAME = "hazo_auth_dev_lock";
 const SEPARATOR = "|";
 
 // section: types
@@ -105,7 +105,7 @@ export async function validate_dev_lock_cookie(
     return { valid: false };
   }
 
-  const cookie = request.cookies.get(COOKIE_NAME)?.value;
+  const cookie = request.cookies.get(get_cookie_name_edge(BASE_COOKIE_NAMES.DEV_LOCK))?.value;
 
   if (!cookie) {
     return { valid: false };
@@ -162,10 +162,11 @@ export function validate_dev_lock_password(password: string): boolean {
 }
 
 /**
- * Gets the dev lock cookie name
+ * Gets the dev lock cookie name (with configurable prefix)
  * Exported for use in API routes when setting the cookie
+ * Uses HAZO_AUTH_COOKIE_PREFIX env var for configurable prefix
  * @returns Cookie name string
  */
 export function get_dev_lock_cookie_name(): string {
-  return COOKIE_NAME;
+  return get_cookie_name_edge(BASE_COOKIE_NAMES.DEV_LOCK);
 }