hazo_auth 5.1.37 → 5.1.40

package/SETUP_CHECKLIST.md

@@ -334,69 +334,179 @@ mkdir -p data
 
 The SQLite database will be created automatically on first use if using hazo_connect's SQLite adapter.
 
+**Recommended:** Run the canonical SQLite schema via the CLI. This is the single source of truth and creates ALL required tables (mirrors `src/lib/schema/sqlite_schema.ts`):
+
+```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)
+```
+
 **Manual creation (if needed):**
 ```bash
-# Create database with initial schema
+# Create database with the full v5.x schema (all tables, including scopes + relationships)
 cat << 'EOF' | sqlite3 data/hazo_auth.sqlite
+-- ============================================================
+-- hazo_auth canonical SQLite schema (v5.x)
+-- Mirrors src/lib/schema/sqlite_schema.ts
+-- ============================================================
+
+-- Users table (status enum + managed sub-profile support)
 CREATE TABLE IF NOT EXISTS hazo_users (
-    id TEXT PRIMARY KEY,
-    email_address TEXT NOT NULL UNIQUE,
-    password_hash TEXT,
-    name TEXT,
-    email_verified INTEGER NOT NULL DEFAULT 0,
-    status TEXT DEFAULT 'ACTIVE' CHECK(status IN ('PENDING', 'ACTIVE', 'BLOCKED')),
-    login_attempts INTEGER NOT NULL 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,
-    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 (also used for password reset / email verification 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 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'))
-);
+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);
 
+-- 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'))
+  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-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)
 );
 
-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 scopes table (hierarchical multi-tenancy with firm branding)
+-- v5.0+ replaces hazo_org and hazo_scopes_l1..l7 with a single self-referencing table
+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 assignments (membership model with scope-specific roles)
+-- NOTE: replaces the old hazo_user_roles table from v4.x
+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 (onboard new users into existing scopes)
+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 (parent/child accounts on shared devices)
+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')
 );
 EOF
 ```
@@ -404,82 +514,53 @@ EOF
 **Verify SQLite database:**
 ```bash
 sqlite3 data/hazo_auth.sqlite ".tables"
-# Expected: hazo_users hazo_refresh_tokens hazo_permissions hazo_roles hazo_role_permissions hazo_user_roles
+# Expected (9 tables):
+#   hazo_users hazo_refresh_tokens hazo_roles hazo_permissions hazo_role_permissions
+#   hazo_scopes hazo_user_scopes hazo_invitations hazo_user_relationships
 ```
 
+> **v4.x → v5.x:** the legacy `hazo_org`, `hazo_scopes_l1..l7`, and `hazo_user_roles` tables have been removed. Roles are now assigned per-scope via `hazo_user_scopes.role_id`. If upgrading, run `migrations/009_scope_consolidation.sql` first.
+
 ### Option B: PostgreSQL (Production)
 
-Run this SQL script in your PostgreSQL database:
+Run this SQL script in your PostgreSQL database. It creates the full v5.x schema, including the unified `hazo_scopes` model, `hazo_user_scopes`, `hazo_invitations`, and `hazo_user_relationships`.
 
-**Important:** Run the entire script in order. The enum type must be created before the table that uses it.
+**Important:** Run the entire script in order — enum types and parent tables must be created before tables that depend on them.
 
 ```sql
--- Ensure we're in the public schema (or your target schema)
+-- ============================================================
+-- hazo_auth canonical PostgreSQL schema (v5.x)
+-- Single source of truth for production deployments
+-- ============================================================
+
 SET search_path TO public;
 
--- Create enum types (drop first if they exist to avoid conflicts)
-DROP TYPE IF EXISTS hazo_enum_profile_source_enum CASCADE;
+-- 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');
 
-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
+-- 2. Users (status enum + managed sub-profile support)
 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
     name TEXT,
     email_verified BOOLEAN NOT NULL DEFAULT FALSE,
-    status TEXT NOT NULL DEFAULT 'ACTIVE',              -- 'PENDING', 'ACTIVE', or 'BLOCKED'
     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
-    app_user_data TEXT,                                 -- Custom JSON data for consuming apps
     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,
+    user_type TEXT,                                     -- Optional user categorization
+    app_user_data JSONB,                                -- Custom JSON data for consuming apps
+    status hazo_enum_user_status NOT NULL DEFAULT 'ACTIVE',
+    managed_by_user_id UUID REFERENCES hazo_users(id) ON DELETE SET NULL,  -- managed sub-profiles
+    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()
 );
@@ -487,71 +568,142 @@ 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);
+CREATE INDEX idx_hazo_users_managed_by ON hazo_users(managed_by_user_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
+-- 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',         -- 'refresh' | 'password_reset' | 'email_verification'
     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);
 
--- Create permissions table
-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()
 );
 
--- Create roles table
-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()
 );
 
--- Create role-permissions junction table
+-- 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)
 );
-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 user-roles junction table
-CREATE TABLE hazo_user_roles (
+-- 7. Unified scopes (hierarchical multi-tenancy with firm branding)
+--    v5.0+ replaces the old hazo_org and hazo_scopes_l1..l7 tables.
+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,
+    level TEXT NOT NULL,                                -- descriptive label e.g. 'HQ', 'Division', 'Team'
+    logo_url TEXT,
+    primary_color TEXT,
+    secondary_color TEXT,
+    tagline TEXT,
+    slug TEXT,
+    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_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, created_at, changed_at)
+VALUES ('00000000-0000-0000-0000-000000000000', NULL, 'Super Admin', 'system', NOW(), NOW())
+ON CONFLICT (id) DO NOTHING;
+
+INSERT INTO hazo_scopes (id, parent_id, name, level, created_at, changed_at)
+VALUES ('00000000-0000-0000-0000-000000000001', NULL, 'System', 'default', NOW(), NOW())
+ON CONFLICT (id) DO NOTHING;
+
+-- 8. User-scope assignments (membership model with scope-specific roles)
+--    Replaces the v4.x hazo_user_roles table.
+CREATE TABLE hazo_user_scopes (
     user_id UUID NOT NULL REFERENCES hazo_users(id) ON DELETE CASCADE,
+    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(),
-    PRIMARY KEY (user_id, role_id)
+    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);
+
+-- 9. Invitations (onboard new users into existing scopes)
+CREATE TABLE hazo_invitations (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    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()
+);
+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(),
+    UNIQUE (parent_user_id, child_user_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);
+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);
+
+-- 11. Built-in firm_admin role (used when a user creates their first firm)
+INSERT INTO hazo_roles (id, role_name, created_at, changed_at)
+VALUES (gen_random_uuid(), 'firm_admin', NOW(), NOW())
+ON CONFLICT (role_name) DO NOTHING;
 ```
 
+> **Migrating from v4.x?** The legacy `hazo_org`, `hazo_scopes_l1..l7`, and `hazo_user_roles` tables have been removed. Run `migrations/009_scope_consolidation.sql` against your existing database — it drops the old tables and creates the new schema in place.
+
 **Verify PostgreSQL tables:**
 ```sql
-SELECT table_name FROM information_schema.tables WHERE table_name LIKE 'hazo_%';
--- Expected: 6 tables listed
+SELECT table_name FROM information_schema.tables
+WHERE table_schema = 'public' AND table_name LIKE 'hazo_%'
+ORDER BY table_name;
+-- Expected (9 tables):
+--   hazo_invitations, hazo_permissions, hazo_refresh_tokens, hazo_role_permissions,
+--   hazo_roles, hazo_scopes, hazo_users, hazo_user_relationships, hazo_user_scopes
 ```
 
 **Grant access to admin user:**
@@ -565,16 +717,19 @@ GRANT USAGE ON SCHEMA public TO your_admin_user;
 -- Grant all privileges on all hazo_* tables
 GRANT ALL PRIVILEGES ON TABLE hazo_users TO your_admin_user;
 GRANT ALL PRIVILEGES ON TABLE hazo_refresh_tokens TO your_admin_user;
-GRANT ALL PRIVILEGES ON TABLE hazo_permissions TO your_admin_user;
 GRANT ALL PRIVILEGES ON TABLE hazo_roles TO your_admin_user;
+GRANT ALL PRIVILEGES ON TABLE hazo_permissions TO your_admin_user;
 GRANT ALL PRIVILEGES ON TABLE hazo_role_permissions TO your_admin_user;
-GRANT ALL PRIVILEGES ON TABLE hazo_user_roles TO your_admin_user;
+GRANT ALL PRIVILEGES ON TABLE hazo_scopes TO your_admin_user;
+GRANT ALL PRIVILEGES ON TABLE hazo_user_scopes TO your_admin_user;
+GRANT ALL PRIVILEGES ON TABLE hazo_invitations TO your_admin_user;
+GRANT ALL PRIVILEGES ON TABLE hazo_user_relationships TO your_admin_user;
 
--- Grant usage on the enum type
+-- Grant usage on enum types
 GRANT USAGE ON TYPE hazo_enum_profile_source_enum TO your_admin_user;
-
--- Grant privileges on sequences (if using SERIAL instead of UUID, though not needed for UUID)
--- GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA public TO your_admin_user;
+GRANT USAGE ON TYPE hazo_enum_user_status TO your_admin_user;
+GRANT USAGE ON TYPE hazo_enum_user_scope_status_type TO your_admin_user;
+GRANT USAGE ON TYPE hazo_enum_invitation_status TO your_admin_user;
 
 -- Optional: Grant privileges on future tables (if you plan to add more hazo_* tables)
 ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL PRIVILEGES ON TABLES TO your_admin_user;
@@ -598,7 +753,7 @@ GRANT SELECT ON TABLE hazo_users TO anon;
 GRANT SELECT ON TABLE hazo_permissions TO anon;
 GRANT SELECT ON TABLE hazo_roles TO anon;
 GRANT SELECT ON TABLE hazo_role_permissions TO anon;
-GRANT SELECT ON TABLE hazo_user_roles TO anon;
+GRANT SELECT ON TABLE hazo_scopes TO anon;
 
 -- Grant full access to authenticated users (adjust based on your RLS policies)
 GRANT ALL PRIVILEGES ON TABLE hazo_users TO authenticated;
@@ -606,30 +761,39 @@ GRANT ALL PRIVILEGES ON TABLE hazo_refresh_tokens TO authenticated;
 GRANT ALL PRIVILEGES ON TABLE hazo_permissions TO authenticated;
 GRANT ALL PRIVILEGES ON TABLE hazo_roles TO authenticated;
 GRANT ALL PRIVILEGES ON TABLE hazo_role_permissions TO authenticated;
-GRANT ALL PRIVILEGES ON TABLE hazo_user_roles TO authenticated;
+GRANT ALL PRIVILEGES ON TABLE hazo_scopes TO authenticated;
+GRANT ALL PRIVILEGES ON TABLE hazo_user_scopes TO authenticated;
+GRANT ALL PRIVILEGES ON TABLE hazo_invitations TO authenticated;
+GRANT ALL PRIVILEGES ON TABLE hazo_user_relationships TO authenticated;
 
--- Grant usage on enum type
+-- Grant usage on enum types
 GRANT USAGE ON TYPE hazo_enum_profile_source_enum TO anon, authenticated;
+GRANT USAGE ON TYPE hazo_enum_user_status TO anon, authenticated;
+GRANT USAGE ON TYPE hazo_enum_user_scope_status_type TO anon, authenticated;
+GRANT USAGE ON TYPE hazo_enum_invitation_status TO anon, authenticated;
 ```
 
 **Checklist:**
 - [ ] Database created (SQLite file or PostgreSQL)
 - [ ] 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 status, google_id, auth_providers, app_user_data, org_id, root_org_id, user_type fields)
+  - [ ] `hazo_enum_user_status`
+  - [ ] `hazo_enum_user_scope_status_type`
+  - [ ] `hazo_enum_invitation_status`
+- [ ] All core tables exist (9 total):
+  - [ ] `hazo_users` (with `status`, `google_id`, `auth_providers`, `app_user_data`, `user_type`, `managed_by_user_id`, `pin_hash` fields)
   - [ ] `hazo_refresh_tokens`
-  - [ ] `hazo_permissions`
   - [ ] `hazo_roles`
-  - [ ] `hazo_role_permissions`
-  - [ ] `hazo_user_roles`
+  - [ ] `hazo_permissions`
+  - [ ] `hazo_role_permissions` (composite PK, no `id` column)
+  - [ ] `hazo_scopes` (unified hierarchy with branding + `slug`)
+  - [ ] `hazo_user_scopes` (composite PK on `user_id`, `scope_id`)
+  - [ ] `hazo_invitations`
+  - [ ] `hazo_user_relationships` (managed sub-profile parent/child links)
+- [ ] Reserved system scopes inserted:
+  - [ ] `00000000-0000-0000-0000-000000000000` (Super Admin)
+  - [ ] `00000000-0000-0000-0000-000000000001` (System / non-multi-tenancy default)
+- [ ] `firm_admin` role inserted into `hazo_roles`
 
 ---
 
@@ -1439,7 +1603,9 @@ application_permission_list_defaults = admin_user_management,admin_role_manageme
 
 ### Step 7.3: Create HRBAC Database Tables
 
-**Recommended:** Run the scope consolidation migration which creates all required tables:
+> **Note (v5.0+):** `hazo_scopes`, `hazo_user_scopes`, and `hazo_invitations` are now part of the **core schema** in Phase 3. If you ran the canonical SQLite or PostgreSQL script there (or `npx hazo_auth init-db`), these tables already exist — you can skip ahead to Step 7.4. The scripts below are kept for upgrades from v4.x or for partial recovery.
+
+**Upgrading from v4.x?** Run the consolidation migration which drops the legacy tables (`hazo_org`, `hazo_scopes_l1..l7`, `hazo_user_roles`) and creates the new schema:
 
 ```bash
 npm run migrate migrations/009_scope_consolidation.sql

package/cli-src/lib/schema/sqlite_schema.ts

@@ -12,7 +12,7 @@ CREATE TABLE IF NOT EXISTS hazo_users (
   email_address TEXT NOT NULL UNIQUE,
   password_hash TEXT,
   name TEXT,
-  email_verified INTEGER DEFAULT 0,
+  email_verified BOOLEAN DEFAULT false,
   login_attempts INTEGER DEFAULT 0,
   last_logon TEXT,
   profile_picture_url TEXT,
@@ -35,10 +35,15 @@ 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);
 
 -- Refresh tokens table
+-- Note: runtime (token_service.ts) writes token_hash (argon2-hashed value) on
+-- insert and verifies via argon2.verify(token_hash, plaintext_token) on read.
+-- The plaintext "token" column is retained nullable for legacy compatibility
+-- but new writes only set token_hash.
 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 TEXT NOT NULL UNIQUE,
+  token TEXT UNIQUE,
+  token_hash TEXT,
   token_type TEXT DEFAULT 'refresh',
   expires_at TEXT NOT NULL,
   created_at TEXT NOT NULL DEFAULT (datetime('now'))
@@ -46,6 +51,7 @@ CREATE TABLE IF NOT EXISTS hazo_refresh_tokens (
 
 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);
+CREATE INDEX IF NOT EXISTS idx_hazo_refresh_tokens_token_hash ON hazo_refresh_tokens(token_hash);
 
 -- Roles table
 CREATE TABLE IF NOT EXISTS hazo_roles (
@@ -145,10 +151,10 @@ CREATE TABLE IF NOT EXISTS hazo_user_relationships (
   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,
+  can_view_progress BOOLEAN DEFAULT true,
+  can_edit_profile BOOLEAN DEFAULT true,
+  can_delete BOOLEAN DEFAULT false,
+  is_self BOOLEAN DEFAULT false,
   created_at TEXT NOT NULL DEFAULT (datetime('now')),
   UNIQUE(parent_user_id, child_user_id)
 );