hazo_auth 5.1.37 → 5.1.40

package/README.md

@@ -2,6 +2,16 @@
 
 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.39 🔧
+
+**Postgres-Compatibility Schema Alignment** — fixes two long-standing drifts between the canonical SQLite schema and what the runtime actually writes. SQLite consumers see no behaviour change; Postgres + PostgREST consumers can now sign-up users without bespoke schema patches.
+
+- **`hazo_refresh_tokens.token_hash`** — `token_service.ts` writes the argon2-hashed token, but the canonical schema only declared `token`. Added `token_hash TEXT` column and an index on it; relaxed the legacy plaintext `token` column to nullable. Runtime no longer writes plaintext, so this is purely additive for new installs.
+- **Boolean-typed columns** — `hazo_users.email_verified` and the four flags on `hazo_user_relationships` (`can_view_progress`, `can_edit_profile`, `can_delete`, `is_self`) are now declared `BOOLEAN` instead of `INTEGER`. SQLite tolerates `BOOLEAN` as a NUMERIC affinity (existing 0/1 data evaluates correctly). PostgreSQL via PostgREST was previously rejecting the runtime's `email_verified: false` payload with `400 — invalid input syntax for type integer: "false"`; now it accepts the boolean cleanly.
+- **Migration `014_align_schema_with_runtime.sql`** — applies the two changes above to existing deployments. SQLite version is active (additive `ADD COLUMN`); PostgreSQL ALTERs are commented blocks for consumers to opt in (with `NOTIFY pgrst, 'reload schema';` reminders).
+
+Reported by Kinstripe (Postgres + PostgREST consumer) during sign-up smoke tests on 2026-04-28.
+
 ### What's New in v5.1.28
 
 **Schema Validation, Permission Constants & DX Improvements**
@@ -547,347 +557,355 @@ cookie_domain = .example.com
 
 Before using `hazo_auth`, you need to create the required database tables. The package supports both **PostgreSQL** (for production) and **SQLite** (for local development/testing).
 
-### PostgreSQL Setup
+The v5.x schema consists of **9 tables**:
 
-Run the following SQL scripts in your PostgreSQL database:
+| Table | Purpose |
+|-------|---------|
+| `hazo_users` | User accounts and profile data |
+| `hazo_refresh_tokens` | Refresh, password-reset, and email-verification tokens |
+| `hazo_roles` | Role definitions (e.g. `super_user`, `firm_admin`) |
+| `hazo_permissions` | Permission definitions |
+| `hazo_role_permissions` | Role → permission assignments (composite PK) |
+| `hazo_scopes` | Unified hierarchical multi-tenancy with firm branding |
+| `hazo_user_scopes` | User → scope membership with scope-specific role (replaces `hazo_user_roles`) |
+| `hazo_invitations` | Invitations to onboard new users into existing scopes |
+| `hazo_user_relationships` | Managed sub-profile parent/child links (shared-device support) |
 
-#### 1. Create the Profile Source Enum Type
+> **Removed in v5.0:** the legacy `hazo_org` and `hazo_scopes_l1..l7` tables are gone. The unified `hazo_scopes` table replaces them with an arbitrary-depth `parent_id` hierarchy. The `hazo_user_roles` table is also gone — roles are now assigned per-scope on `hazo_user_scopes.role_id`.
 
-```sql
--- Enum type for profile picture source
-CREATE TYPE hazo_enum_profile_source_enum AS ENUM ('gravatar', 'custom', 'predefined');
+### Quickest path: use the CLI
 
--- Note: hazo_enum_scope_types was removed in v5.0
--- The unified hazo_scopes table uses a TEXT "level" column instead
+For SQLite development databases, the canonical schema (in `src/lib/schema/sqlite_schema.ts`) ships with the package and can be applied via the CLI:
+
+```bash
+npx hazo_auth init-db    # Create/recreate the SQLite database with full schema
+npx hazo_auth schema     # Print the canonical schema SQL (does not modify DB)
 ```
 
-#### 2. Create the Organization Table (Multi-Tenancy)
+For PostgreSQL or PostgREST deployments, run the script below.
+
+### PostgreSQL Setup
 
 ```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
-);
+-- ============================================================
+-- hazo_auth canonical PostgreSQL schema (v5.x)
+-- ============================================================
 
-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);
-```
+SET search_path TO public;
 
-#### 3. Create the Users Table
+-- 1. Enum types
+CREATE TYPE hazo_enum_profile_source_enum AS ENUM ('gravatar', 'custom', 'predefined');
+CREATE TYPE hazo_enum_user_status AS ENUM ('PENDING', 'ACTIVE', 'BLOCKED');
+CREATE TYPE hazo_enum_user_scope_status_type AS ENUM ('INVITED', 'ACTIVE', 'SUSPENDED', 'DEPARTED');
+CREATE TYPE hazo_enum_invitation_status AS ENUM ('PENDING', 'ACCEPTED', 'EXPIRED', 'REVOKED');
 
-```sql
--- Main users table
+-- 2. Users
 CREATE TABLE hazo_users (
     id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
     email_address TEXT NOT NULL UNIQUE,
-    password_hash TEXT,                                   -- NULL for OAuth-only users
+    password_hash TEXT,                                 -- NULL for OAuth-only users
     name TEXT,
     email_verified BOOLEAN NOT NULL DEFAULT FALSE,
-    is_active BOOLEAN NOT NULL DEFAULT TRUE,
     login_attempts INTEGER NOT NULL DEFAULT 0,
     last_logon TIMESTAMP WITH TIME ZONE,
     profile_picture_url TEXT,
     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,
+    url_on_logon TEXT,                                  -- per-user post-login redirect
+    google_id TEXT UNIQUE,                              -- Google OAuth ID
+    auth_providers TEXT DEFAULT 'email',                -- 'email', 'google', or 'email,google'
+    user_type TEXT,                                     -- optional categorisation
+    app_user_data JSONB,                                -- consumer-app JSON blob
+    status hazo_enum_user_status NOT NULL DEFAULT 'ACTIVE',
+    managed_by_user_id UUID REFERENCES hazo_users(id) ON DELETE SET NULL,
+    pin_hash TEXT,                                      -- simple PIN auth on shared devices
     created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
     changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
 );
-
--- Indexes
 CREATE INDEX idx_hazo_users_email ON hazo_users(email_address);
+CREATE INDEX idx_hazo_users_status ON hazo_users(status);
 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.
+CREATE INDEX idx_hazo_users_managed_by ON hazo_users(managed_by_user_id);
 
-#### 4. Create the Refresh Tokens Table
-
-```sql
--- Refresh tokens table (used for password reset, email verification, etc.)
+-- 3. Refresh tokens (also used for password reset / email verification)
 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,
     token_hash TEXT NOT NULL,
-    token_type TEXT NOT NULL,
+    token_type TEXT NOT NULL DEFAULT 'refresh',
     expires_at TIMESTAMP WITH TIME ZONE NOT NULL,
     created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
 );
-
--- Index for token lookups
 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);
-```
 
-#### 5. Create the Permissions Table
-
-```sql
--- Permissions table for RBAC
-CREATE TABLE hazo_permissions (
+-- 4. Roles
+CREATE TABLE hazo_roles (
     id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-    permission_name TEXT NOT NULL UNIQUE,
-    description TEXT,
+    role_name TEXT NOT NULL UNIQUE,
     created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
     changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
 );
-```
 
-#### 6. Create the Roles Table
-
-```sql
--- Roles table for RBAC
-CREATE TABLE hazo_roles (
+-- 5. Permissions
+CREATE TABLE hazo_permissions (
     id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-    role_name TEXT NOT NULL UNIQUE,
+    permission_name TEXT NOT NULL UNIQUE,
+    description TEXT,
     created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
     changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
 );
-```
-
-#### 7. Create the Role-Permissions Junction Table
 
-```sql
--- Junction table linking roles to permissions
+-- 6. Role-permission assignments (composite PK, no id column)
 CREATE TABLE hazo_role_permissions (
     role_id UUID NOT NULL REFERENCES hazo_roles(id) ON DELETE CASCADE,
     permission_id UUID NOT NULL REFERENCES hazo_permissions(id) ON DELETE CASCADE,
     created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
-    changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
     PRIMARY KEY (role_id, permission_id)
 );
 
--- Indexes for lookups
-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);
-```
-
-#### 8. Create the User-Roles Junction Table
-
-```sql
--- Junction table linking users to roles
-CREATE TABLE hazo_user_roles (
-    user_id UUID NOT NULL REFERENCES hazo_users(id) ON DELETE CASCADE,
-    role_id UUID NOT NULL REFERENCES hazo_roles(id) ON DELETE CASCADE,
-    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
-    changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
-    PRIMARY KEY (user_id, role_id)
-);
-
--- Indexes for lookups
-CREATE INDEX idx_hazo_user_roles_user_id ON hazo_user_roles(user_id);
-CREATE INDEX idx_hazo_user_roles_role_id ON hazo_user_roles(role_id);
-```
-
-### Complete PostgreSQL Setup Script
-
-For convenience, here's the complete SQL script to create all tables at once:
-
-```sql
--- ============================================
--- hazo_auth Database Setup Script (PostgreSQL)
--- ============================================
-
--- 1. Create enum types
-CREATE TYPE hazo_enum_profile_source_enum AS ENUM ('gravatar', 'custom', 'predefined');
--- Note: hazo_enum_scope_types was removed in v5.0 (uses unified hazo_scopes table)
-
--- 2. Create organization table (multi-tenancy)
-CREATE TABLE hazo_org (
+-- 7. Unified scope hierarchy (firms, divisions, departments, ... with branding)
+CREATE TABLE hazo_scopes (
     id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    parent_id UUID REFERENCES hazo_scopes(id) ON DELETE CASCADE,
     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,
-    name TEXT,
-    email_verified BOOLEAN NOT NULL DEFAULT FALSE,
-    is_active BOOLEAN NOT NULL DEFAULT TRUE,
-    login_attempts INTEGER NOT NULL DEFAULT 0,
-    last_logon TIMESTAMP WITH TIME ZONE,
-    profile_picture_url TEXT,
-    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,
+    level TEXT NOT NULL,                                -- descriptive label e.g. 'HQ', 'Division'
+    logo_url TEXT,
+    primary_color TEXT,
+    secondary_color TEXT,
+    tagline TEXT,
+    slug TEXT,                                          -- URL-friendly identifier
     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 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(),
+CREATE INDEX idx_hazo_scopes_parent ON hazo_scopes(parent_id);
+CREATE INDEX idx_hazo_scopes_level ON hazo_scopes(level);
+CREATE INDEX idx_hazo_scopes_slug ON hazo_scopes(slug);
+
+-- 7a. Reserved system scopes
+INSERT INTO hazo_scopes (id, parent_id, name, level)
+VALUES ('00000000-0000-0000-0000-000000000000', NULL, 'Super Admin', 'system')
+ON CONFLICT (id) DO NOTHING;
+INSERT INTO hazo_scopes (id, parent_id, name, level)
+VALUES ('00000000-0000-0000-0000-000000000001', NULL, 'System', 'default')
+ON CONFLICT (id) DO NOTHING;
+
+-- 8. User-scope membership (replaces v4.x hazo_user_roles)
+CREATE TABLE hazo_user_scopes (
     user_id UUID NOT NULL REFERENCES hazo_users(id) ON DELETE CASCADE,
-    token_hash TEXT NOT NULL,
-    token_type TEXT NOT NULL,
-    expires_at TIMESTAMP WITH TIME ZONE NOT NULL,
-    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
-);
-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 permissions table
-CREATE TABLE hazo_permissions (
-    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-    permission_name TEXT NOT NULL UNIQUE,
-    description TEXT,
+    scope_id UUID NOT NULL REFERENCES hazo_scopes(id) ON DELETE CASCADE,
+    root_scope_id UUID NOT NULL REFERENCES hazo_scopes(id) ON DELETE CASCADE,
+    role_id UUID NOT NULL REFERENCES hazo_roles(id) ON DELETE CASCADE,
+    status hazo_enum_user_scope_status_type NOT NULL DEFAULT 'ACTIVE',
     created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
-    changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
+    changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+    PRIMARY KEY (user_id, scope_id)
 );
+CREATE INDEX idx_hazo_user_scopes_scope ON hazo_user_scopes(scope_id);
+CREATE INDEX idx_hazo_user_scopes_root ON hazo_user_scopes(root_scope_id);
+CREATE INDEX idx_hazo_user_scopes_role ON hazo_user_scopes(role_id);
 
--- 5. Create roles table
-CREATE TABLE hazo_roles (
+-- 9. Invitations
+CREATE TABLE hazo_invitations (
     id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-    role_name TEXT NOT NULL UNIQUE,
+    email_address TEXT NOT NULL,
+    token TEXT NOT NULL UNIQUE,
+    scope_id UUID NOT NULL REFERENCES hazo_scopes(id) ON DELETE CASCADE,
+    root_scope_id UUID NOT NULL REFERENCES hazo_scopes(id) ON DELETE CASCADE,
+    role_id UUID NOT NULL REFERENCES hazo_roles(id) ON DELETE CASCADE,
+    invited_by UUID REFERENCES hazo_users(id) ON DELETE SET NULL,
+    status hazo_enum_invitation_status NOT NULL DEFAULT 'PENDING',
+    expires_at TIMESTAMP WITH TIME ZONE NOT NULL,
+    accepted_at TIMESTAMP WITH TIME ZONE,
     created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
     changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
 );
-
--- 6. Create role-permissions junction table
-CREATE TABLE hazo_role_permissions (
-    role_id UUID NOT NULL REFERENCES hazo_roles(id) ON DELETE CASCADE,
-    permission_id UUID NOT NULL REFERENCES hazo_permissions(id) ON DELETE CASCADE,
+CREATE INDEX idx_hazo_invitations_email ON hazo_invitations(email_address);
+CREATE INDEX idx_hazo_invitations_token ON hazo_invitations(token);
+CREATE INDEX idx_hazo_invitations_scope ON hazo_invitations(scope_id);
+CREATE INDEX idx_hazo_invitations_status ON hazo_invitations(status);
+CREATE INDEX idx_hazo_invitations_expires ON hazo_invitations(expires_at);
+
+-- 10. Managed sub-profile relationships (parent/child accounts on shared devices)
+CREATE TABLE hazo_user_relationships (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    parent_user_id UUID NOT NULL REFERENCES hazo_users(id) ON DELETE CASCADE,
+    child_user_id UUID NOT NULL REFERENCES hazo_users(id) ON DELETE CASCADE,
+    relationship_type TEXT NOT NULL DEFAULT 'parent',
+    can_view_progress BOOLEAN NOT NULL DEFAULT TRUE,
+    can_edit_profile BOOLEAN NOT NULL DEFAULT TRUE,
+    can_delete BOOLEAN NOT NULL DEFAULT FALSE,
+    is_self BOOLEAN NOT NULL DEFAULT FALSE,
     created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
-    changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
-    PRIMARY KEY (role_id, permission_id)
+    UNIQUE (parent_user_id, child_user_id)
 );
-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);
+CREATE INDEX idx_hazo_user_relationships_parent ON hazo_user_relationships(parent_user_id);
+CREATE INDEX idx_hazo_user_relationships_child ON hazo_user_relationships(child_user_id);
 
--- 7. Create user-roles junction table
-CREATE TABLE hazo_user_roles (
-    user_id UUID NOT NULL REFERENCES hazo_users(id) ON DELETE CASCADE,
-    role_id UUID NOT NULL REFERENCES hazo_roles(id) ON DELETE CASCADE,
-    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
-    changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
-    PRIMARY KEY (user_id, role_id)
-);
-CREATE INDEX idx_hazo_user_roles_user_id ON hazo_user_roles(user_id);
-CREATE INDEX idx_hazo_user_roles_role_id ON hazo_user_roles(role_id);
+-- 11. Built-in firm_admin role (used when a user creates their first firm)
+INSERT INTO hazo_roles (id, role_name)
+VALUES (gen_random_uuid(), 'firm_admin')
+ON CONFLICT (role_name) DO NOTHING;
 ```
 
 ### SQLite Setup (for local development)
 
-For local development and testing, you can use SQLite. The SQLite schema is slightly different (no UUID type, TEXT used instead):
+The SQLite version of the schema. Equivalent to running `npx hazo_auth init-db` and identical to `src/lib/schema/sqlite_schema.ts`.
 
 ```sql
--- ============================================
--- hazo_auth Database Setup Script (SQLite)
--- ============================================
+-- ============================================================
+-- hazo_auth canonical SQLite schema (v5.x)
+-- ============================================================
 
--- Users table
+-- Users
 CREATE TABLE IF NOT EXISTS hazo_users (
-    id TEXT PRIMARY KEY,
-    email_address TEXT NOT NULL UNIQUE,
-    password_hash TEXT NOT NULL,
-    name TEXT,
-    email_verified INTEGER NOT NULL DEFAULT 0,
-    is_active INTEGER NOT NULL DEFAULT 1,
-    login_attempts INTEGER NOT NULL DEFAULT 0,
-    last_logon TEXT,
-    profile_picture_url TEXT,
-    profile_source TEXT,
-    mfa_secret TEXT,
-    url_on_logon TEXT,
-    created_at TEXT NOT NULL DEFAULT (datetime('now')),
-    changed_at TEXT NOT NULL DEFAULT (datetime('now'))
+  id TEXT PRIMARY KEY,
+  email_address TEXT NOT NULL UNIQUE,
+  password_hash TEXT,
+  name TEXT,
+  email_verified INTEGER DEFAULT 0,
+  login_attempts INTEGER DEFAULT 0,
+  last_logon TEXT,
+  profile_picture_url TEXT,
+  profile_source TEXT CHECK(profile_source IN ('gravatar', 'custom', 'predefined')),
+  mfa_secret TEXT,
+  url_on_logon TEXT,
+  google_id TEXT UNIQUE,
+  auth_providers TEXT DEFAULT 'email',
+  user_type TEXT,
+  app_user_data TEXT,
+  status TEXT DEFAULT 'ACTIVE' CHECK(status IN ('PENDING', 'ACTIVE', 'BLOCKED')),
+  managed_by_user_id TEXT REFERENCES hazo_users(id) ON DELETE SET NULL,
+  pin_hash TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  changed_at TEXT NOT NULL DEFAULT (datetime('now'))
 );
+CREATE INDEX IF NOT EXISTS idx_hazo_users_email ON hazo_users(email_address);
+CREATE INDEX IF NOT EXISTS idx_hazo_users_google_id ON hazo_users(google_id);
+CREATE INDEX IF NOT EXISTS idx_hazo_users_status ON hazo_users(status);
+CREATE INDEX IF NOT EXISTS idx_hazo_users_managed_by ON hazo_users(managed_by_user_id);
 
--- Refresh tokens table
+-- Refresh tokens
 CREATE TABLE IF NOT EXISTS hazo_refresh_tokens (
-    id TEXT PRIMARY KEY,
-    user_id TEXT NOT NULL REFERENCES hazo_users(id) ON DELETE CASCADE,
-    token_hash TEXT NOT NULL,
-    token_type TEXT NOT NULL,
-    expires_at TEXT NOT NULL,
-    created_at TEXT NOT NULL DEFAULT (datetime('now'))
+  id TEXT PRIMARY KEY,
+  user_id TEXT NOT NULL REFERENCES hazo_users(id) ON DELETE CASCADE,
+  token TEXT NOT NULL UNIQUE,
+  token_type TEXT DEFAULT 'refresh',
+  expires_at TEXT NOT NULL,
+  created_at TEXT NOT NULL DEFAULT (datetime('now'))
 );
+CREATE INDEX IF NOT EXISTS idx_hazo_refresh_tokens_user ON hazo_refresh_tokens(user_id);
+CREATE INDEX IF NOT EXISTS idx_hazo_refresh_tokens_token ON hazo_refresh_tokens(token);
 
--- Permissions table
-CREATE TABLE IF NOT EXISTS hazo_permissions (
-    id TEXT PRIMARY KEY,
-    permission_name TEXT NOT NULL UNIQUE,
-    description TEXT,
-    created_at TEXT NOT NULL DEFAULT (datetime('now')),
-    changed_at TEXT NOT NULL DEFAULT (datetime('now'))
+-- Roles
+CREATE TABLE IF NOT EXISTS hazo_roles (
+  id TEXT PRIMARY KEY,
+  role_name TEXT NOT NULL UNIQUE,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  changed_at TEXT NOT NULL DEFAULT (datetime('now'))
 );
 
--- Roles table
-CREATE TABLE IF NOT EXISTS hazo_roles (
-    id TEXT PRIMARY KEY,
-    role_name TEXT NOT NULL UNIQUE,
-    created_at TEXT NOT NULL DEFAULT (datetime('now')),
-    changed_at TEXT NOT NULL DEFAULT (datetime('now'))
+-- Permissions
+CREATE TABLE IF NOT EXISTS hazo_permissions (
+  id TEXT PRIMARY KEY,
+  permission_name TEXT NOT NULL UNIQUE,
+  description TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  changed_at TEXT NOT NULL DEFAULT (datetime('now'))
 );
 
--- Role-permissions junction table
+-- Role-permission assignments (composite PK, no id column)
 CREATE TABLE IF NOT EXISTS hazo_role_permissions (
-    role_id TEXT NOT NULL REFERENCES hazo_roles(id) ON DELETE CASCADE,
-    permission_id TEXT NOT NULL REFERENCES hazo_permissions(id) ON DELETE CASCADE,
-    created_at TEXT NOT NULL DEFAULT (datetime('now')),
-    changed_at TEXT NOT NULL DEFAULT (datetime('now')),
-    PRIMARY KEY (role_id, permission_id)
+  role_id TEXT NOT NULL REFERENCES hazo_roles(id) ON DELETE CASCADE,
+  permission_id TEXT NOT NULL REFERENCES hazo_permissions(id) ON DELETE CASCADE,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  PRIMARY KEY (role_id, permission_id)
 );
 
--- User-roles junction table
-CREATE TABLE IF NOT EXISTS hazo_user_roles (
-    user_id TEXT NOT NULL REFERENCES hazo_users(id) ON DELETE CASCADE,
-    role_id TEXT NOT NULL REFERENCES hazo_roles(id) ON DELETE CASCADE,
-    created_at TEXT NOT NULL DEFAULT (datetime('now')),
-    changed_at TEXT NOT NULL DEFAULT (datetime('now')),
-    PRIMARY KEY (user_id, role_id)
+-- Unified scope hierarchy (firms, divisions, departments, ... with branding)
+CREATE TABLE IF NOT EXISTS hazo_scopes (
+  id TEXT PRIMARY KEY,
+  parent_id TEXT REFERENCES hazo_scopes(id) ON DELETE CASCADE,
+  name TEXT NOT NULL,
+  level TEXT NOT NULL,
+  logo_url TEXT,
+  primary_color TEXT,
+  secondary_color TEXT,
+  tagline TEXT,
+  slug TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  changed_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+CREATE INDEX IF NOT EXISTS idx_hazo_scopes_parent ON hazo_scopes(parent_id);
+CREATE INDEX IF NOT EXISTS idx_hazo_scopes_level ON hazo_scopes(level);
+CREATE INDEX IF NOT EXISTS idx_hazo_scopes_slug ON hazo_scopes(slug);
+
+-- Reserved system scopes
+INSERT OR IGNORE INTO hazo_scopes (id, parent_id, name, level, created_at, changed_at)
+VALUES ('00000000-0000-0000-0000-000000000000', NULL, 'Super Admin', 'system', datetime('now'), datetime('now'));
+INSERT OR IGNORE INTO hazo_scopes (id, parent_id, name, level, created_at, changed_at)
+VALUES ('00000000-0000-0000-0000-000000000001', NULL, 'System', 'default', datetime('now'), datetime('now'));
+
+-- User-scope membership (replaces v4.x hazo_user_roles)
+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 REFERENCES hazo_scopes(id) ON DELETE CASCADE,
+  root_scope_id TEXT NOT NULL REFERENCES hazo_scopes(id) ON DELETE CASCADE,
+  role_id TEXT NOT NULL REFERENCES hazo_roles(id) ON DELETE CASCADE,
+  status TEXT DEFAULT 'ACTIVE' CHECK (status IN ('INVITED', 'ACTIVE', 'SUSPENDED', 'DEPARTED')),
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  changed_at TEXT NOT NULL DEFAULT (datetime('now')),
+  PRIMARY KEY (user_id, scope_id)
+);
+CREATE INDEX IF NOT EXISTS idx_hazo_user_scopes_scope ON hazo_user_scopes(scope_id);
+CREATE INDEX IF NOT EXISTS idx_hazo_user_scopes_root ON hazo_user_scopes(root_scope_id);
+CREATE INDEX IF NOT EXISTS idx_hazo_user_scopes_role ON hazo_user_scopes(role_id);
+
+-- Invitations
+CREATE TABLE IF NOT EXISTS hazo_invitations (
+  id TEXT PRIMARY KEY,
+  email_address TEXT NOT NULL,
+  token TEXT NOT NULL UNIQUE,
+  scope_id TEXT NOT NULL REFERENCES hazo_scopes(id) ON DELETE CASCADE,
+  root_scope_id TEXT NOT NULL REFERENCES hazo_scopes(id) ON DELETE CASCADE,
+  role_id TEXT NOT NULL REFERENCES hazo_roles(id) ON DELETE CASCADE,
+  invited_by TEXT REFERENCES hazo_users(id) ON DELETE SET NULL,
+  status TEXT NOT NULL DEFAULT 'PENDING' CHECK(status IN ('PENDING', 'ACCEPTED', 'EXPIRED', 'REVOKED')),
+  expires_at TEXT NOT NULL,
+  accepted_at TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  changed_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+CREATE INDEX IF NOT EXISTS idx_hazo_invitations_email ON hazo_invitations(email_address);
+CREATE INDEX IF NOT EXISTS idx_hazo_invitations_token ON hazo_invitations(token);
+CREATE INDEX IF NOT EXISTS idx_hazo_invitations_scope ON hazo_invitations(scope_id);
+CREATE INDEX IF NOT EXISTS idx_hazo_invitations_status ON hazo_invitations(status);
+CREATE INDEX IF NOT EXISTS idx_hazo_invitations_expires ON hazo_invitations(expires_at);
+
+-- Managed sub-profile relationships
+CREATE TABLE IF NOT EXISTS hazo_user_relationships (
+  id TEXT PRIMARY KEY,
+  parent_user_id TEXT NOT NULL REFERENCES hazo_users(id) ON DELETE CASCADE,
+  child_user_id TEXT NOT NULL REFERENCES hazo_users(id) ON DELETE CASCADE,
+  relationship_type TEXT NOT NULL DEFAULT 'parent',
+  can_view_progress INTEGER DEFAULT 1,
+  can_edit_profile INTEGER DEFAULT 1,
+  can_delete INTEGER DEFAULT 0,
+  is_self INTEGER DEFAULT 0,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  UNIQUE(parent_user_id, child_user_id)
+);
+CREATE INDEX IF NOT EXISTS idx_hazo_user_relationships_parent ON hazo_user_relationships(parent_user_id);
+CREATE INDEX IF NOT EXISTS idx_hazo_user_relationships_child ON hazo_user_relationships(child_user_id);
+
+-- Built-in firm_admin role (used when a user creates their first firm)
+INSERT OR IGNORE INTO hazo_roles (id, role_name, created_at, changed_at)
+VALUES (
+  lower(hex(randomblob(4)) || '-' || hex(randomblob(2)) || '-4' || substr(hex(randomblob(2)),2) || '-' || substr('89ab',abs(random()) % 4 + 1, 1) || substr(hex(randomblob(2)),2) || '-' || hex(randomblob(6))),
+  'firm_admin',
+  datetime('now'),
+  datetime('now')
 );
 ```
 
@@ -2147,19 +2165,14 @@ scope_cache_max_entries = 5000
 
 ### Database Setup
 
-HRBAC requires additional database tables. Run the scope consolidation migration:
+As of v5.0, the HRBAC tables — `hazo_scopes`, `hazo_user_scopes`, and `hazo_invitations` — are part of the **core schema** in [Database Setup](#database-setup), so if you ran the canonical PostgreSQL/SQLite script (or `npx hazo_auth init-db`) they already exist. No additional setup is required to enable HRBAC at the database level.
+
+If you're upgrading from v4.x, run the consolidation migration to drop the legacy `hazo_org`, `hazo_scopes_l1..l7`, and `hazo_user_roles` tables and create the new schema in place:
 
 ```bash
 npm run migrate migrations/009_scope_consolidation.sql
 ```
 
-This creates:
-- `hazo_scopes` - Unified scope hierarchy with branding support
-- `hazo_user_scopes` - User-scope-role assignments
-- `hazo_invitations` - User invitation flow
-
-See `SETUP_CHECKLIST.md` for full PostgreSQL and SQLite scripts.
-
 ### Using hazo_get_auth with Scope Options
 
 When HRBAC is enabled, you can check scope access alongside permissions: