hazo_auth 3.0.4 → 4.1.0

package/README.md

@@ -198,11 +198,12 @@ import { MySettingsLayout } from "hazo_auth/components/layouts/my_settings";
 import { UserManagementLayout } from "hazo_auth/components/layouts/user_management";
 
 // Import shared components and hooks from barrel export
-import { 
-  ProfilePicMenu, 
+import {
+  ProfilePicMenu,
   ProfilePicMenuWrapper,
-  use_hazo_auth, 
-  use_auth_status 
+  ProfileStamp,
+  use_hazo_auth,
+  use_auth_status
 } from "hazo_auth/components/layouts/shared";
 
 // Import server-side utilities
@@ -258,11 +259,12 @@ For client components (browser-safe, no Node.js dependencies):
 
 ```typescript
 // Use hazo_auth/client for client components
-import { 
-  ProfilePicMenu, 
-  use_auth_status, 
+import {
+  ProfilePicMenu,
+  ProfileStamp,
+  use_auth_status,
   use_hazo_auth,
-  cn 
+  cn
 } from "hazo_auth/client";
 ```
 
@@ -706,6 +708,7 @@ import { ResetPasswordLayout } from "hazo_auth/components/layouts/reset_password
 import { EmailVerificationLayout } from "hazo_auth/components/layouts/email_verification";
 import { MySettingsLayout } from "hazo_auth/components/layouts/my_settings";
 import { UserManagementLayout } from "hazo_auth/components/layouts/user_management";
+import { RbacTestLayout } from "hazo_auth/components/layouts/rbac_test";
 
 // Shared layout components and hooks (barrel import - recommended)
 import { 
@@ -762,6 +765,7 @@ export default async function LoginPage() {
 - `EmailVerificationLayout` - Verify email address
 - `MySettingsLayout` - User profile and settings
 - `UserManagementLayout` - Admin user/role management (requires user_management API routes)
+- `RbacTestLayout` - RBAC/HRBAC permission and scope testing tool (requires admin_test_access permission)
 
 ### User Management Component
 
@@ -793,6 +797,7 @@ export { GET, POST, PUT } from "hazo_auth/server/routes";
 - **Users:** List users, deactivate users, send password reset emails
 - **Permissions:** List permissions (from DB and config), migrate config permissions to DB, create/update/delete permissions
 - **Roles:** List roles with permissions, create roles, update role-permission assignments
+  - **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
 
 **Example Usage:**
@@ -860,6 +865,10 @@ This is the **standardized endpoint** that ensures consistent response format ac
   last_logon: string | undefined,
   profile_picture_url: string | null,
   profile_source: "upload" | "library" | "gravatar" | "custom" | undefined,
+  // Profile picture aliases (for consuming app compatibility)
+  profile_image?: string,  // Alias for profile_picture_url
+  avatar_url?: string,     // Alias for profile_picture_url
+  image?: string,          // Alias for profile_picture_url
   // Permissions (always included)
   user: {
     id: string,
@@ -1229,6 +1238,217 @@ enable_friendly_error_messages = true
 
 ---
 
+## Hierarchical Role-Based Access Control (HRBAC)
+
+hazo_auth supports optional Hierarchical Role-Based Access Control (HRBAC) with 7 scope levels (L1-L7). HRBAC extends standard RBAC by allowing users to be assigned to scopes in a hierarchy, with automatic inheritance of access to child scopes.
+
+### Enabling HRBAC
+
+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
+scope_cache_ttl_minutes = 15
+scope_cache_max_entries = 5000
+
+# Optional: customize default labels for each scope level
+default_label_l1 = Company
+default_label_l2 = Division
+default_label_l3 = Department
+default_label_l4 = Team
+default_label_l5 = Project
+default_label_l6 = Sub-project
+default_label_l7 = Task
+```
+
+### Database Setup
+
+HRBAC requires additional database tables. See `SETUP_CHECKLIST.md` for full PostgreSQL and SQLite scripts, including:
+- `hazo_scopes_l1` through `hazo_scopes_l7` - Scope tables with parent_scope_id references
+- `hazo_user_scopes` - User-scope assignments
+- `hazo_scope_labels` - Custom labels per organization
+- `hazo_enum_scope_types` - Enum type for scope validation
+
+### Using hazo_get_auth with Scope Options
+
+When HRBAC is enabled, you can check scope access alongside permissions:
+
+```typescript
+import { hazo_get_auth } from "hazo_auth/lib/auth/hazo_get_auth.server";
+import { ScopeAccessError } from "hazo_auth/lib/auth/auth_types";
+
+export async function GET(request: NextRequest) {
+  try {
+    const authResult = await hazo_get_auth(request, {
+      required_permissions: ["view_reports"],
+      scope_type: "hazo_scopes_l3",  // Check access to Level 3 scope
+      scope_seq: "L3_001",           // Scope identifier (or use scope_id for UUID)
+      strict: true,                   // Throws ScopeAccessError if denied
+    });
+
+    if (!authResult.authenticated) {
+      return NextResponse.json({ error: "Authentication required" }, { status: 401 });
+    }
+
+    // Both permission_ok and scope_ok must be true for full access
+    if (authResult.scope_ok) {
+      // Access granted - scope_access_via shows how access was granted
+      console.log("Access via:", authResult.scope_access_via);
+    }
+
+    return NextResponse.json({ message: "Access granted" });
+  } catch (error) {
+    if (error instanceof ScopeAccessError) {
+      return NextResponse.json(
+        { error: "Scope access denied", scope: error.scope_identifier },
+        { status: 403 }
+      );
+    }
+    throw error;
+  }
+}
+```
+
+### Scope Access Inheritance
+
+Users assigned to a higher-level scope automatically have access to all descendant scopes:
+- User with L2 scope access can access all L3, L4, L5, L6, L7 scopes under that L2 scope
+- Direct assignments take precedence over inherited access
+- The `scope_access_via` field in the result shows which scope granted access
+
+### Required Permissions for Management
+
+- `admin_scope_hierarchy_management` - Manage scopes and scope labels
+- `admin_user_scope_assignment` - Assign scopes to users
+- `admin_test_access` - Access the RBAC/HRBAC test tool
+
+Add these to your `application_permission_list_defaults` in `hazo_auth_config.ini`:
+
+```ini
+[hazo_auth__user_management]
+application_permission_list_defaults = admin_user_management,admin_role_management,admin_permission_management,admin_scope_hierarchy_management,admin_user_scope_assignment,admin_test_access
+```
+
+### User Management UI
+
+When HRBAC is enabled and the user has appropriate permissions, three new tabs appear in the User Management layout:
+- **Scope Hierarchy** - Create, edit, and delete scopes at each level
+- **Scope Labels** - Customize labels for scope levels per organization
+- **User Scopes** - Assign and remove scope assignments for users
+
+### RBAC/HRBAC Test Tool
+
+The `RbacTestLayout` component provides a comprehensive testing interface for administrators to test RBAC permissions and HRBAC scope access for any user in the system.
+
+**Features:**
+- **User Selection**: Dropdown to select any user in the system
+- **User Info Display**: Shows selected user's current permissions and assigned scopes
+- **RBAC Test Tab**: Select permissions to test if the user has them
+- **HRBAC Test Tab**: Select a scope from a tree view and test if the user has access
+- **Results Display**: Clear pass/fail indicators with missing permissions and scope access details
+
+**Required Permission:** `admin_test_access`
+
+**Usage in Your App:**
+
+```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";
+
+export default function RbacTestPage() {
+  const hrbacEnabled = is_hrbac_enabled();
+  const defaultOrg = get_default_org();
+
+  return (
+    <RbacTestLayout
+      hrbacEnabled={hrbacEnabled}
+      defaultOrg={defaultOrg}
+    />
+  );
+}
+```
+
+**API Route Required:**
+The test tool uses the `/api/hazo_auth/rbac_test` endpoint which is included in the package. This route:
+- Accepts `test_user_id` parameter to test any user
+- Checks permissions and scope access for the specified user
+- Requires `admin_test_access` permission to call
+
+**Demo Page:** A test page is available at `/hazo_auth/rbac_test` in the demo app.
+
+---
+
+## ProfileStamp Component
+
+The `ProfileStamp` component is a drop-in widget that displays a circular profile picture with a hover card showing user details. Perfect for adding profile attribution to notes, comments, or any user-generated content.
+
+### Features
+
+- Displays user's profile picture or initials
+- Hover card with user name, email, and custom fields
+- Three sizes: sm (24px), default (32px), lg (40px)
+- Automatic loading state and unauthenticated fallback
+- Fully accessible with keyboard navigation
+
+### Usage
+
+```typescript
+import { ProfileStamp } from "hazo_auth/client";
+
+// Basic usage
+<ProfileStamp />
+
+// With custom size and fields
+<ProfileStamp
+  size="lg"
+  custom_fields={[
+    { label: "Role", value: "Admin" },
+    { label: "Department", value: "Engineering" }
+  ]}
+/>
+
+// Hide default fields, only show custom fields
+<ProfileStamp
+  show_name={false}
+  show_email={false}
+  custom_fields={[
+    { label: "Posted", value: "2 hours ago" }
+  ]}
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `size` | `"sm" \| "default" \| "lg"` | `"default"` | Avatar size (sm: 24px, default: 32px, lg: 40px) |
+| `custom_fields` | `ProfileStampCustomField[]` | `[]` | Custom fields to display in hover card |
+| `className` | `string` | `undefined` | Additional CSS classes |
+| `show_name` | `boolean` | `true` | Show user name in hover card |
+| `show_email` | `boolean` | `true` | Show email in hover card |
+
+### ProfileStampCustomField Type
+
+```typescript
+type ProfileStampCustomField = {
+  label: string;  // Field label (e.g., "Role", "Department")
+  value: string;  // Field value (e.g., "Admin", "Engineering")
+};
+```
+
+### Test Page
+
+Visit `/hazo_auth/profile_stamp_test` in your dev environment to see examples of ProfileStamp with various configurations:
+- Size variants
+- Custom fields
+- Display options (showing/hiding name and email)
+- Usage scenarios (notes, comments, activity feeds)
+
+---
+
 ## Profile Picture Menu Widget
 
 The Profile Picture Menu is a versatile component for navbar or sidebar that automatically displays:

package/SETUP_CHECKLIST.md

@@ -954,6 +954,376 @@ Visit each page and verify it loads:
 - [ ] `http://localhost:3000/hazo_auth/register` - Registration form displays
 - [ ] `http://localhost:3000/hazo_auth/forgot_password` - Forgot password form displays
 - [ ] `http://localhost:3000/hazo_auth/my_settings` - Settings page displays (after login)
+- [ ] `http://localhost:3000/hazo_auth/profile_stamp_test` - ProfileStamp component examples display
+
+---
+
+## Phase 7: HRBAC Setup (Optional)
+
+Hierarchical Role-Based Access Control (HRBAC) extends the standard RBAC with 7 hierarchical scope levels. This phase is optional - only complete it if you need scope-based access control.
+
+### Step 7.1: Enable HRBAC in Configuration
+
+Add to your `hazo_auth_config.ini`:
+
+```ini
+[hazo_auth__scope_hierarchy]
+enable_hrbac = true
+default_org = my_organization
+scope_cache_ttl_minutes = 15
+scope_cache_max_entries = 5000
+
+# Optional: customize default labels for each scope level
+default_label_l1 = Company
+default_label_l2 = Division
+default_label_l3 = Department
+default_label_l4 = Team
+default_label_l5 = Project
+default_label_l6 = Sub-project
+default_label_l7 = Task
+```
+
+### Step 7.2: Add HRBAC Permissions
+
+Add the HRBAC management permissions to your `application_permission_list_defaults`:
+
+```ini
+[hazo_auth__user_management]
+application_permission_list_defaults = admin_user_management,admin_role_management,admin_permission_management,admin_scope_hierarchy_management,admin_user_scope_assignment
+```
+
+### Step 7.3: Create HRBAC Database Tables
+
+#### PostgreSQL
+
+```sql
+-- =============================================
+-- HRBAC Database Setup Script (PostgreSQL)
+-- =============================================
+
+-- 1. Create scope types enum
+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 sequence generator function for scope IDs
+CREATE OR REPLACE FUNCTION hazo_scope_id_generator(table_name TEXT)
+RETURNS TEXT AS $$
+DECLARE
+    prefix TEXT;
+    next_num INTEGER;
+    result TEXT;
+BEGIN
+    -- Extract level number from table name (e.g., 'hazo_scopes_l3' -> '3')
+    prefix := 'L' || SUBSTRING(table_name FROM 'hazo_scopes_l([0-9]+)');
+
+    -- Get the next sequence number
+    EXECUTE format(
+        'SELECT COALESCE(MAX(CAST(SUBSTRING(seq FROM ''L[0-9]+_([0-9]+)'') AS INTEGER)), 0) + 1 FROM %I',
+        table_name
+    ) INTO next_num;
+
+    -- Format as L{level}_{padded_number}
+    result := prefix || '_' || LPAD(next_num::TEXT, 3, '0');
+
+    RETURN result;
+END;
+$$ LANGUAGE plpgsql;
+
+-- 3. Create scope tables (L1 through L7)
+
+-- Level 1 (top level - no parent)
+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,
+    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_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,
+    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_seq ON hazo_scopes_l2(seq);
+CREATE INDEX idx_hazo_scopes_l2_parent ON hazo_scopes_l2(parent_scope_id);
+
+-- Level 3 (parent: L2)
+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,
+    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_seq ON hazo_scopes_l3(seq);
+CREATE INDEX idx_hazo_scopes_l3_parent ON hazo_scopes_l3(parent_scope_id);
+
+-- Level 4 (parent: L3)
+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,
+    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_seq ON hazo_scopes_l4(seq);
+CREATE INDEX idx_hazo_scopes_l4_parent ON hazo_scopes_l4(parent_scope_id);
+
+-- Level 5 (parent: L4)
+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,
+    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_seq ON hazo_scopes_l5(seq);
+CREATE INDEX idx_hazo_scopes_l5_parent ON hazo_scopes_l5(parent_scope_id);
+
+-- Level 6 (parent: L5)
+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,
+    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_seq ON hazo_scopes_l6(seq);
+CREATE INDEX idx_hazo_scopes_l6_parent ON hazo_scopes_l6(parent_scope_id);
+
+-- Level 7 (parent: L6)
+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,
+    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_seq ON hazo_scopes_l7(seq);
+CREATE INDEX idx_hazo_scopes_l7_parent ON hazo_scopes_l7(parent_scope_id);
+
+-- 4. Create user scopes junction table
+CREATE TABLE hazo_user_scopes (
+    user_id UUID NOT NULL REFERENCES hazo_users(id) ON DELETE CASCADE,
+    scope_id UUID NOT NULL,
+    scope_seq TEXT NOT NULL,
+    scope_type hazo_enum_scope_types NOT NULL,
+    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+    changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+    PRIMARY KEY (user_id, scope_type, scope_id)
+);
+CREATE INDEX idx_hazo_user_scopes_user_id ON hazo_user_scopes(user_id);
+CREATE INDEX idx_hazo_user_scopes_scope_id ON hazo_user_scopes(scope_id);
+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,
+    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)
+);
+CREATE INDEX idx_hazo_scope_labels_org ON hazo_scope_labels(org);
+```
+
+#### PostgreSQL Grant Scripts
+
+After creating the tables, grant appropriate permissions:
+
+```sql
+-- Grant to your admin user (replace 'your_admin_user' with actual username)
+GRANT ALL PRIVILEGES ON TABLE hazo_scopes_l1 TO your_admin_user;
+GRANT ALL PRIVILEGES ON TABLE hazo_scopes_l2 TO your_admin_user;
+GRANT ALL PRIVILEGES ON TABLE hazo_scopes_l3 TO your_admin_user;
+GRANT ALL PRIVILEGES ON TABLE hazo_scopes_l4 TO your_admin_user;
+GRANT ALL PRIVILEGES ON TABLE hazo_scopes_l5 TO your_admin_user;
+GRANT ALL PRIVILEGES ON TABLE hazo_scopes_l6 TO your_admin_user;
+GRANT ALL PRIVILEGES ON TABLE hazo_scopes_l7 TO your_admin_user;
+GRANT ALL PRIVILEGES ON TABLE hazo_user_scopes TO your_admin_user;
+GRANT ALL PRIVILEGES ON TABLE hazo_scope_labels TO your_admin_user;
+GRANT USAGE ON TYPE hazo_enum_scope_types TO your_admin_user;
+GRANT EXECUTE ON FUNCTION hazo_scope_id_generator(TEXT) TO your_admin_user;
+
+-- For PostgREST authenticated role
+GRANT ALL PRIVILEGES ON TABLE hazo_scopes_l1 TO authenticated;
+GRANT ALL PRIVILEGES ON TABLE hazo_scopes_l2 TO authenticated;
+GRANT ALL PRIVILEGES ON TABLE hazo_scopes_l3 TO authenticated;
+GRANT ALL PRIVILEGES ON TABLE hazo_scopes_l4 TO authenticated;
+GRANT ALL PRIVILEGES ON TABLE hazo_scopes_l5 TO authenticated;
+GRANT ALL PRIVILEGES ON TABLE hazo_scopes_l6 TO authenticated;
+GRANT ALL PRIVILEGES ON TABLE hazo_scopes_l7 TO authenticated;
+GRANT ALL PRIVILEGES ON TABLE hazo_user_scopes TO authenticated;
+GRANT ALL PRIVILEGES ON TABLE hazo_scope_labels TO authenticated;
+GRANT USAGE ON TYPE hazo_enum_scope_types TO authenticated;
+GRANT EXECUTE ON FUNCTION hazo_scope_id_generator(TEXT) TO authenticated;
+```
+
+#### SQLite
+
+```sql
+-- =============================================
+-- HRBAC Database Setup Script (SQLite)
+-- =============================================
+
+-- Scope tables (L1 through L7)
+
+CREATE TABLE IF NOT EXISTS hazo_scopes_l1 (
+    id TEXT PRIMARY KEY,
+    seq TEXT NOT NULL,
+    org TEXT NOT NULL,
+    name TEXT NOT NULL,
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    changed_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE TABLE IF NOT EXISTS hazo_scopes_l2 (
+    id TEXT PRIMARY KEY,
+    seq TEXT NOT NULL,
+    org TEXT NOT NULL,
+    name TEXT NOT NULL,
+    parent_scope_id TEXT REFERENCES hazo_scopes_l1(id) ON DELETE CASCADE,
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    changed_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE TABLE IF NOT EXISTS hazo_scopes_l3 (
+    id TEXT PRIMARY KEY,
+    seq TEXT NOT NULL,
+    org TEXT NOT NULL,
+    name TEXT NOT NULL,
+    parent_scope_id TEXT REFERENCES hazo_scopes_l2(id) ON DELETE CASCADE,
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    changed_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE TABLE IF NOT EXISTS hazo_scopes_l4 (
+    id TEXT PRIMARY KEY,
+    seq TEXT NOT NULL,
+    org TEXT NOT NULL,
+    name TEXT NOT NULL,
+    parent_scope_id TEXT REFERENCES hazo_scopes_l3(id) ON DELETE CASCADE,
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    changed_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE TABLE IF NOT EXISTS hazo_scopes_l5 (
+    id TEXT PRIMARY KEY,
+    seq TEXT NOT NULL,
+    org TEXT NOT NULL,
+    name TEXT NOT NULL,
+    parent_scope_id TEXT REFERENCES hazo_scopes_l4(id) ON DELETE CASCADE,
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    changed_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE TABLE IF NOT EXISTS hazo_scopes_l6 (
+    id TEXT PRIMARY KEY,
+    seq TEXT NOT NULL,
+    org TEXT NOT NULL,
+    name TEXT NOT NULL,
+    parent_scope_id TEXT REFERENCES hazo_scopes_l5(id) ON DELETE CASCADE,
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    changed_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE TABLE IF NOT EXISTS hazo_scopes_l7 (
+    id TEXT PRIMARY KEY,
+    seq TEXT NOT NULL,
+    org TEXT NOT NULL,
+    name TEXT NOT NULL,
+    parent_scope_id TEXT REFERENCES hazo_scopes_l6(id) ON DELETE CASCADE,
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    changed_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+-- User scopes junction table
+CREATE TABLE IF NOT EXISTS hazo_user_scopes (
+    user_id TEXT NOT NULL REFERENCES hazo_users(id) ON DELETE CASCADE,
+    scope_id TEXT NOT NULL,
+    scope_seq TEXT NOT NULL,
+    scope_type TEXT NOT NULL CHECK(scope_type IN ('hazo_scopes_l1','hazo_scopes_l2','hazo_scopes_l3','hazo_scopes_l4','hazo_scopes_l5','hazo_scopes_l6','hazo_scopes_l7')),
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    changed_at TEXT NOT NULL DEFAULT (datetime('now')),
+    PRIMARY KEY (user_id, scope_type, scope_id)
+);
+
+-- Scope labels table
+CREATE TABLE IF NOT EXISTS hazo_scope_labels (
+    id TEXT PRIMARY KEY,
+    org TEXT NOT NULL,
+    scope_type TEXT NOT NULL CHECK(scope_type IN ('hazo_scopes_l1','hazo_scopes_l2','hazo_scopes_l3','hazo_scopes_l4','hazo_scopes_l5','hazo_scopes_l6','hazo_scopes_l7')),
+    label TEXT NOT NULL,
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    changed_at TEXT NOT NULL DEFAULT (datetime('now')),
+    UNIQUE(org, scope_type)
+);
+```
+
+### Step 7.4: Verify HRBAC Tables
+
+#### PostgreSQL
+```sql
+SELECT table_name FROM information_schema.tables
+WHERE table_name LIKE 'hazo_scopes_%'
+   OR table_name IN ('hazo_user_scopes', 'hazo_scope_labels');
+-- Expected: 9 tables (7 scope tables + user_scopes + scope_labels)
+```
+
+#### SQLite
+```bash
+sqlite3 data/hazo_auth.sqlite ".tables" | grep -E "hazo_scopes|hazo_user_scopes|hazo_scope_labels"
+```
+
+### Step 7.5: Test HRBAC
+
+1. Start your dev server: `npm run dev`
+2. Log in with a user that has `admin_scope_hierarchy_management` permission
+3. Visit `/hazo_auth/user_management`
+4. Verify the "Scope Hierarchy", "Scope Labels", and "User Scopes" tabs appear
+5. Visit `/hazo_auth/scope_test` to test scope access checking
+
+**HRBAC Checklist:**
+- [ ] `enable_hrbac = true` in config
+- [ ] HRBAC permissions added to defaults
+- [ ] All 9 HRBAC tables created
+- [ ] Grants applied (PostgreSQL)
+- [ ] HRBAC tabs visible in User Management
+- [ ] Scope test page works
 
 ---
 

package/dist/app/api/hazo_auth/me/route.d.ts

@@ -14,6 +14,9 @@ import { NextRequest, NextResponse } from "next/server";
  *   email_verified: boolean,
  *   last_logon: string | undefined,
  *   profile_picture_url: string | null,
+ *   profile_image: string | null,      // alias for profile_picture_url
+ *   avatar_url: string | null,         // alias for profile_picture_url
+ *   image: string | null,              // alias for profile_picture_url
  *   profile_source: "upload" | "library" | "gravatar" | "custom" | undefined,
  *   user: { id, email_address, name, is_active, profile_picture_url },
  *   permissions: string[],

package/dist/app/api/hazo_auth/me/route.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../../../../src/app/api/hazo_auth/me/route.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AASxD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,GAAG,CAAC,OAAO,EAAE,WAAW;;IA0E7C"}
+{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../../../../src/app/api/hazo_auth/me/route.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AASxD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAsB,GAAG,CAAC,OAAO,EAAE,WAAW;;IA+E7C"}