hazo_auth 5.1.25 → 5.1.28

package/README.md

@@ -2,6 +2,38 @@
 
 A reusable authentication UI component package powered by Next.js, TailwindCSS, and shadcn. It integrates `hazo_config` for configuration management and `hazo_connect` for data access, enabling future components to stay aligned with platform conventions.
 
+### What's New in v5.1.28
+
+**Schema Validation, Permission Constants & DX Improvements**
+
+- **Schema validation** - `npx hazo_auth validate` now checks SQLite schema: required tables, TEXT ID types, `hazo_user_scopes` columns, admin permissions, and warns about v4 remnant tables
+- **Permission constants** - New `HAZO_AUTH_PERMISSIONS` and `ALL_ADMIN_PERMISSIONS` exports from both `hazo_auth` and `hazo_auth/client` for programmatic permission checks
+- **CLI fix** - CLI wrapper now sets `--conditions react-server` in NODE_OPTIONS, fixing "server-only" import errors when running `npx hazo_auth validate`, `init-permissions`, etc.
+- **Silent permission fix** - `hazo_get_auth` now applies `String()` normalization to role_id/permission_id comparisons, fixing empty permissions when SQLite returns INTEGER IDs
+- **DB-generated IDs** - `init-permissions` no longer generates UUIDs client-side; lets the database generate IDs (supports both TEXT UUID and INTEGER PK schemas)
+- **Dev debug info** - `withAuth` 403 responses and `UserManagementLayout` "Access Denied" view now include permission debug details in development mode
+- **Import cleanup** - Removed `.js` extensions from internal imports for better TypeScript/bundler compatibility
+
+### What's New in v5.1.27
+
+**Mandatory Cookie Prefix** - `cookie_prefix` is now required for all consuming apps.
+
+- **Breaking:** `get_cookies_config()` throws if `cookie_prefix` is not set in `[hazo_auth__cookies]` config section
+- **Breaking:** `get_cookie_prefix_edge()` throws if `HAZO_AUTH_COOKIE_PREFIX` env var is not set
+- **Validation:** `npx hazo_auth validate` now checks for cookie_prefix configuration
+- **Init:** `.env.local.example` template includes `HAZO_AUTH_COOKIE_PREFIX` as required
+- **Docs:** shadcn/ui components are bundled — consumers do NOT need to install them separately
+
+### What's New in v5.1.26
+
+**Consumer Setup Improvements** - Five fixes that improve the out-of-box experience for new consumers:
+
+- **Multi-tenancy bypass** - `enable_multi_tenancy = false` (the default) now correctly skips scope/invitation checks in OAuth and post-verification flows. No more redirect loops to `/hazo_auth/create_firm` for simple apps.
+- **Clear SQLite errors** - Missing `sqlite_path` in config now throws a clear error instead of silently falling back to a test fixture database. Unrecognized config keys produce warnings with typo suggestions.
+- **Auto-schema creation** - `npx hazo_auth init` now creates the SQLite database with all required tables automatically. Also available standalone via `npx hazo_auth init-db`. Use `npx hazo_auth schema` to print the canonical SQL.
+- **Auth page images** - `npx hazo_auth init` now copies default login/register/forgot-password images to `public/hazo_auth/images/`.
+- **Graceful image fallback** - Visual panels on auth pages fall back to a colored background instead of crashing when images are missing.
+
 ### What's New in v5.2.0 ⚠️ BREAKING CHANGE
 
 **Server/Client Module Separation** - Complete fix for "Module not found: Can't resolve 'fs'" errors.
@@ -117,9 +149,12 @@ See [CHANGE_LOG.md](./CHANGE_LOG.md) for detailed migration guide, rationale, an
 ## Installation
 
 ```bash
-npm install hazo_auth
+# Install hazo_auth and required peer dependencies
+npm install hazo_auth hazo_config hazo_connect hazo_logs
 ```
 
+**Note:** `hazo_config`, `hazo_connect`, and `hazo_logs` are required peer dependencies.
+
 ---
 
 ## Quick Start
@@ -127,20 +162,31 @@ npm install hazo_auth
 The fastest way to get started is using the CLI commands:
 
 ```bash
-# 1. Install the package
-npm install hazo_auth
+# 1. Install the package and peer dependencies
+npm install hazo_auth hazo_config hazo_connect hazo_logs
 
-# 2. Initialize your project (creates directories, copies config files)
+# 2. Initialize your project (directories, config, database, images)
 npx hazo_auth init
 
-# 3. Generate API routes and pages
-npx hazo_auth generate-routes --pages
+# 3. Configure cookie prefix (REQUIRED)
+# Edit config/hazo_auth_config.ini and set a unique prefix:
+#   [hazo_auth__cookies]
+#   cookie_prefix = myapp_
 
 # 4. Set up environment variables
 cp .env.local.example .env.local
-# Edit .env.local and add your ZEPTOMAIL_API_KEY
+# Edit .env.local and set:
+#   HAZO_AUTH_COOKIE_PREFIX=myapp_   (MUST match cookie_prefix above)
+#   JWT_SECRET=<your-secret>
+#   ZEPTOMAIL_API_KEY=<your-key>
+
+# 5. Initialize default permissions and roles
+npx hazo_auth init-users
 
-# 5. Start your dev server
+# 6. Generate API routes and pages
+npx hazo_auth generate-routes --pages
+
+# 7. Start your dev server
 npm run dev
 ```
 
@@ -309,22 +355,14 @@ import { hazo_get_auth } from "hazo_auth/lib/auth/hazo_get_auth.server";
 
 ## Required Dependencies
 
-**Note:** The `jose` package is now included as a dependency for Edge-compatible JWT operations. This is automatically installed when you run `npm install hazo_auth`.
-
-hazo_auth uses shadcn/ui components. Install the required dependencies in your project:
-
+**Peer Dependencies (Required):**
 ```bash
-# Required for all auth pages
-npx shadcn@latest add button input label
-
-# Required for My Settings page
-npx shadcn@latest add dialog tabs switch avatar dropdown-menu
-
-# Required for toast notifications
-npx shadcn@latest add sonner
+npm install hazo_config hazo_connect hazo_logs
 ```
 
-**Add Toaster to your app layout:**
+**UI Components:** All shadcn/ui components are bundled with hazo_auth. You do NOT need to install them separately.
+
+**Toast Notifications:** Add the Toaster component to your app layout:
 
 ```tsx
 // app/layout.tsx

package/SETUP_CHECKLIST.md

@@ -10,24 +10,35 @@ The fastest way to set up hazo_auth:
 # 1. Install the package and peer dependencies
 npm install hazo_auth hazo_config hazo_connect hazo_logs
 
-# 2. Initialize project (creates directories, copies config files)
+# 2. Initialize project (creates directories, config files, database, images)
 npx hazo_auth init
 
-# 3. Generate API routes and pages
-npx hazo_auth generate-routes --pages
+# 3. Configure cookie prefix (REQUIRED)
+# Edit config/hazo_auth_config.ini and set a unique prefix:
+#   [hazo_auth__cookies]
+#   cookie_prefix = myapp_
 
 # 4. Set up environment variables
 cp .env.local.example .env.local
-# Edit .env.local and add ZEPTOMAIL_API_KEY and JWT_SECRET
+# Edit .env.local and set:
+#   HAZO_AUTH_COOKIE_PREFIX=myapp_   (MUST match cookie_prefix above)
+#   JWT_SECRET=<generate with: openssl rand -base64 32>
+#   ZEPTOMAIL_API_KEY=your_key_here
+
+# 5. Initialize default permissions and roles
+npx hazo_auth init-users
 
-# 5. Configure navbar logo and company name (IMPORTANT)
-# Edit hazo_auth_config.ini and set:
+# 6. Generate API routes and pages
+npx hazo_auth generate-routes --pages
+
+# 7. Configure navbar logo and company name (IMPORTANT)
+# Edit config/hazo_auth_config.ini and set:
 #   [hazo_auth__navbar]
 #   logo_path = /logo.png
 #   company_name = My Company
 # Note: Copy your logo to public/logo.png
 
-# 6. Start dev server and test
+# 8. Start dev server and test
 npm run dev
 # Visit http://localhost:3000/hazo_auth/login
 ```
@@ -69,26 +80,11 @@ ls node_modules/hazo_auth/package.json
 # Expected: file exists
 ```
 
-### Step 1.2: Install Required shadcn/ui Components
-
-hazo_auth uses shadcn/ui components. Install the required dependencies:
-
-**For all auth pages (login, register, etc.):**
-```bash
-npx shadcn@latest add button input label
-```
-
-**For My Settings page:**
-```bash
-npx shadcn@latest add dialog tabs switch avatar dropdown-menu
-```
+### Step 1.2: Add Toast Notifications
 
-**For toast notifications:**
-```bash
-npx shadcn@latest add sonner
-```
+All shadcn/ui components are bundled with hazo_auth — you do NOT need to install them separately.
 
-**Add Toaster to your app layout:**
+**Add Toaster to your app layout** (required for toast notifications):
 
 Edit `app/layout.tsx` and add the Toaster component:
 
@@ -178,7 +174,18 @@ This command:
 - Creates `data/` directory (for SQLite database)
 - Copies `hazo_auth_config.ini` and `hazo_notify_config.ini`
 - Copies profile picture library images
+- Copies default auth page images (login, register, forgot password, etc.)
 - Creates `.env.local.example` template
+- Creates SQLite database with all required tables (if `better-sqlite3` is installed)
+
+**Additional CLI commands:**
+```bash
+# Create/recreate SQLite database with schema (standalone)
+npx hazo_auth init-db
+
+# Print the canonical SQLite schema SQL
+npx hazo_auth schema
+```
 
 ### Step 1.2b: Manual config setup (Alternative)
 
@@ -238,18 +245,20 @@ layout_mode = standalone
 Create `.env.local` in your project root:
 
 ```env
+# REQUIRED: Cookie prefix (MUST match cookie_prefix in hazo_auth_config.ini)
+# Each app using hazo_auth needs a unique prefix to prevent cookie conflicts
+HAZO_AUTH_COOKIE_PREFIX=myapp_
+
+# Required for JWT authentication
+JWT_SECRET=your_secure_random_string_at_least_32_characters
+
 # Required for email functionality (Zeptomail)
 ZEPTOMAIL_API_KEY=your_zeptomail_api_key_here
 
 # Required for PostgreSQL/PostgREST (if using)
 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_
+# Optional: Cookie domain (for cross-subdomain sharing)
 HAZO_AUTH_COOKIE_DOMAIN=
 ```
 
@@ -258,17 +267,25 @@ HAZO_AUTH_COOKIE_DOMAIN=
 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_`
+**Cookie Prefix (REQUIRED):**
+Every app using hazo_auth MUST set a unique cookie prefix. This prevents cookie conflicts between apps. The value must be set in TWO places:
 
-Also configure in `hazo_auth_config.ini`:
-```ini
-[hazo_auth__cookies]
-cookie_prefix = myapp_
-cookie_domain =
-```
+1. **Config file** (`config/hazo_auth_config.ini`):
+   ```ini
+   [hazo_auth__cookies]
+   cookie_prefix = myapp_
+   ```
+
+2. **Environment variable** (`.env.local`):
+   ```env
+   HAZO_AUTH_COOKIE_PREFIX=myapp_
+   ```
+
+Both values MUST match. The env var is needed because Edge runtime (middleware/proxy) cannot read config files.
+
+**Examples for multiple apps:**
+- App 1 (port 3000): `cookie_prefix = app1_` / `HAZO_AUTH_COOKIE_PREFIX=app1_`
+- App 2 (port 3001): `cookie_prefix = app2_` / `HAZO_AUTH_COOKIE_PREFIX=app2_`
 
 ### Step 2.2: Configure email settings
 
@@ -282,8 +299,9 @@ from_name = Your App Name
 
 **Checklist:**
 - [ ] `.env.local` file created
+- [ ] `HAZO_AUTH_COOKIE_PREFIX` set (REQUIRED - must match config file)
+- [ ] `JWT_SECRET` set (required for JWT session tokens)
 - [ ] `ZEPTOMAIL_API_KEY` set (or email will not work)
-- [ ] `JWT_SECRET` set (required for JWT session tokens - Edge-compatible proxy/middleware authentication)
 - [ ] `from_email` configured in `hazo_notify_config.ini`
 
 ---
@@ -1108,20 +1126,23 @@ If you prefer a simpler approach without JWT validation:
 import { NextResponse } from "next/server";
 import type { NextRequest } from "next/server";
 
+// Cookie prefix must match HAZO_AUTH_COOKIE_PREFIX env var
+const COOKIE_PREFIX = process.env.HAZO_AUTH_COOKIE_PREFIX || "";
+
 export async function proxy(request: NextRequest) {
   const { pathname } = request.nextUrl;
-  
+
   if (pathname.startsWith("/members")) {
-    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(`${COOKIE_PREFIX}hazo_auth_user_id`)?.value;
+    const user_email = request.cookies.get(`${COOKIE_PREFIX}hazo_auth_user_email`)?.value;
+
     if (!user_id || !user_email) {
       const login_url = new URL("/hazo_auth/login", request.url);
       login_url.searchParams.set("redirect", pathname);
       return NextResponse.redirect(login_url);
     }
   }
-  
+
   return NextResponse.next();
 }
 ```
@@ -1944,14 +1965,104 @@ curl -H "Cookie: hazo_auth_session=YOUR_TOKEN; hazo_auth_scope_id=SCOPE_UUID" \
 
 **Note:** By default, `logo_path` and `company_name` are empty strings, so nothing displays until you configure them.
 
+### Issue: Migrating from v4 to v5 schema
+
+**Symptoms:** Permissions resolve to `[]`, "Access Denied" on all admin pages, 403 responses from withAuth, despite user having roles assigned.
+
+**Cause:** v5 replaced `hazo_user_roles` with `hazo_user_scopes` (scope-based role assignments) and requires several new tables. If your database still has v4 schema, the permission lookup finds no role assignments.
+
+**Key schema differences (v4 vs v5):**
+- `hazo_user_roles` replaced by `hazo_user_scopes` (with `root_scope_id` and `role_id` columns)
+- `hazo_org` replaced by `hazo_scopes` (unified hierarchical scope model)
+- All ID columns must be TEXT (UUID), not INTEGER
+- `hazo_role_permissions` uses composite PK `(role_id, permission_id)` with no `id` column
+
+**Solution:**
+1. Run `npx hazo_auth validate` to identify schema issues
+2. Run migration 009: `npm run migrate migrations/009_scope_consolidation.sql`
+3. Migrate existing role assignments:
+   ```sql
+   -- Example: migrate hazo_user_roles data to hazo_user_scopes
+   INSERT INTO hazo_user_scopes (user_id, scope_id, root_scope_id, role_id, status)
+   SELECT
+     ur.user_id,
+     '00000000-0000-0000-0000-000000000001',  -- default system scope
+     '00000000-0000-0000-0000-000000000001',  -- default system scope
+     ur.role_id,
+     'ACTIVE'
+   FROM hazo_user_roles ur;
+   ```
+4. Run `npx hazo_auth init-permissions` to ensure all admin permissions exist
+
+### Issue: Understanding permission configuration
+
+**Symptoms:** Confusion about which config sections control permissions and how they relate.
+
+**Explanation:** Permissions are configured in three related places:
+
+1. **`[hazo_auth__app_permissions]`** - Declares app-level permission names with descriptions (for documentation/UI display):
+   ```ini
+   app_permission_1 = can_view_reports:View analytical reports
+   app_permission_2 = can_export_data:Export data to CSV
+   ```
+
+2. **`[hazo_auth__user_management] application_permission_list_defaults`** - Comma-separated list of permission names to create in the DB when running `npx hazo_auth init-permissions`:
+   ```ini
+   application_permission_list_defaults = admin_user_management,admin_role_management,admin_permission_management,can_view_reports,can_export_data
+   ```
+
+3. **Built-in admin permissions** (required by `UserManagementLayout` component): `admin_user_management`, `admin_role_management`, `admin_permission_management`, `admin_scope_hierarchy_management`, `admin_user_scope_assignment`, `admin_system`, `admin_test_access`. These are available programmatically via:
+   ```typescript
+   import { HAZO_AUTH_PERMISSIONS, ALL_ADMIN_PERMISSIONS } from "hazo_auth/client";
+   ```
+
+### Issue: Database ID type mismatches (silent permission failures)
+
+**Symptoms:** User is authenticated but permissions array is always empty. No errors in console. `hazo_get_auth` returns `permissions: []` even though roles and permissions exist in the database.
+
+**Cause:** SQLite drivers may return numeric values for columns defined as `INTEGER PRIMARY KEY`. v5 uses strict string comparison for role_id and permission_id matching. If the DB returns `role_id: 1` (number) but the code expects `"1"` (string), the comparison fails silently.
+
+**Solutions:**
+1. **Ensure all ID columns are TEXT type** in your schema. v5 requires TEXT (UUID) IDs:
+   ```sql
+   -- CORRECT (v5)
+   CREATE TABLE hazo_roles (id TEXT PRIMARY KEY, ...);
+
+   -- WRONG (v4 legacy)
+   CREATE TABLE hazo_roles (id INTEGER PRIMARY KEY, ...);
+   ```
+2. Run `npx hazo_auth validate` — the schema check will flag INTEGER ID columns
+3. If you cannot change the schema, v5.1.28+ applies `String()` normalization to role_id and permission_id comparisons, which handles mixed types
+
+**Note for PostgreSQL users:** PostgREST typically returns UUID values as strings, so this issue primarily affects SQLite with INTEGER PKs.
+
+### Issue: CLI commands fail with "server-only" import error
+
+**Symptoms:** Running `npx hazo_auth validate`, `npx hazo_auth init-permissions`, etc. throws:
+```
+Error: This module cannot be imported from a Client Component module.
+It should only be used from a Server Component.
+```
+
+**Cause:** The `server-only` package throws when imported outside a React Server Component context. CLI commands run in plain Node.js.
+
+**Solution (v5.1.28+):** Fixed automatically — the CLI wrapper now sets `--conditions react-server` in NODE_OPTIONS.
+
+**Workaround for older versions:** Set the condition manually:
+```bash
+NODE_OPTIONS='--conditions react-server' npx hazo_auth validate
+```
+
 ---
 
 ## Final Checklist
 
 **Configuration:**
 - [ ] `hazo_auth_config.ini` configured
+- [ ] `cookie_prefix` set in `[hazo_auth__cookies]` section (REQUIRED)
+- [ ] `HAZO_AUTH_COOKIE_PREFIX` env var matches `cookie_prefix` (REQUIRED)
 - [ ] `hazo_notify_config.ini` configured
-- [ ] `.env.local` with all required variables (ZEPTOMAIL_API_KEY, JWT_SECRET)
+- [ ] `.env.local` with all required variables (HAZO_AUTH_COOKIE_PREFIX, JWT_SECRET, ZEPTOMAIL_API_KEY)
 - [ ] Navbar configured with logo and company name (see Step 1.4)
 
 **Database:**

package/bin/hazo_auth.mjs

@@ -18,10 +18,17 @@ const args = process.argv.slice(2);
 // Use tsx to run the TypeScript source directly
 // This avoids ESM module resolution issues with compiled JS
 // tsx is a dependency of hazo_auth so it should be available
+const existingNodeOptions = process.env.NODE_OPTIONS || '';
+const reactServerCondition = '--conditions react-server';
+const nodeOptions = existingNodeOptions.includes(reactServerCondition)
+  ? existingNodeOptions
+  : `${existingNodeOptions} ${reactServerCondition}`.trim();
+
 const child = spawn('npx', ['tsx', cliPath, ...args], {
   stdio: 'inherit',
   cwd: process.cwd(),
-  shell: true
+  shell: true,
+  env: { ...process.env, NODE_OPTIONS: nodeOptions },
 });
 
 child.on('exit', (code) => {

package/cli-src/cli/index.ts

@@ -7,6 +7,7 @@ import { run_validation } from "./validate.js";
 import { generate_routes, type GenerateOptions } from "./generate.js";
 import { handle_init } from "./init.js";
 import { handle_init_users, show_init_users_help } from "./init_users.js";
+import { handle_init_db } from "./init_db.js";
 import { handle_init_permissions, show_init_permissions_help } from "./init_permissions.js";
 
 // section: constants
@@ -18,11 +19,13 @@ const HELP_TEXT = `
 Usage: hazo_auth <command> [options]
 
 Commands:
-  init               Initialize hazo_auth in your project (creates directories, copies config)
+  init               Initialize hazo_auth in your project (creates directories, copies config, DB)
+  init-db            Create SQLite database with hazo_auth schema (standalone)
   init-permissions   Create default permissions from config (no user required)
   init-users         Initialize permissions, roles, and super user from config
   validate           Check your hazo_auth setup and configuration
   generate-routes    Generate API route files and pages in your project
+  schema             Print the canonical SQLite schema SQL
 
 Options:
   --help, -h         Show this help message
@@ -30,12 +33,14 @@ Options:
 
 Examples:
   npx hazo_auth init
+  npx hazo_auth init-db
   npx hazo_auth init-permissions
   npx hazo_auth init-users
   npx hazo_auth validate
   npx hazo_auth generate-routes
   npx hazo_auth generate-routes --pages
   npx hazo_auth generate-routes --all --dir=src/app
+  npx hazo_auth schema
 
 Documentation:
   https://github.com/your-repo/hazo_auth/blob/main/SETUP_CHECKLIST.md
@@ -150,13 +155,42 @@ Actions:
   - Creates data/ directory (for SQLite)
   - Copies hazo_auth_config.ini and hazo_notify_config.ini
   - Copies profile picture library images
+  - Copies default auth page images (login, register, etc.)
   - Creates .env.local.example template
+  - Creates SQLite database with schema (if better-sqlite3 is installed)
 `);
         return;
       }
-      handle_init();
+      await handle_init();
       break;
 
+    case "init-db":
+      if (help) {
+        console.log(`
+hazo_auth init-db
+
+Create SQLite database with the hazo_auth schema.
+
+This command:
+  - Reads sqlite_path from config/hazo_auth_config.ini (default: ./data/hazo_auth.sqlite)
+  - Creates the database file if it doesn't exist
+  - Creates all required tables (hazo_users, hazo_roles, hazo_scopes, etc.)
+  - Skips if tables already exist
+
+Requires: better-sqlite3 (npm install better-sqlite3)
+`);
+        return;
+      }
+      handle_init_db();
+      break;
+
+    case "schema": {
+      // Dynamic import to avoid bundling the schema in the main CLI entry
+      const { SQLITE_SCHEMA } = await import("../lib/schema/sqlite_schema.js");
+      console.log(SQLITE_SCHEMA);
+      break;
+    }
+
     case "init-permissions": {
       if (help) {
         show_init_permissions_help();