hazo_auth 5.1.30 → 5.1.33

package/README.md

@@ -150,10 +150,21 @@ See [CHANGE_LOG.md](./CHANGE_LOG.md) for detailed migration guide, rationale, an
 
 ```bash
 # Install hazo_auth and required peer dependencies
-npm install hazo_auth hazo_config hazo_connect hazo_logs
+npm install hazo_auth hazo_config hazo_connect hazo_logs next react react-dom next-auth
+
+# UI peer dependencies (required if using hazo_auth UI components)
+npm install hazo_ui lucide-react sonner next-themes @radix-ui/react-accordion @radix-ui/react-alert-dialog @radix-ui/react-avatar @radix-ui/react-checkbox @radix-ui/react-dialog @radix-ui/react-dropdown-menu @radix-ui/react-hover-card @radix-ui/react-label @radix-ui/react-select @radix-ui/react-separator @radix-ui/react-slot @radix-ui/react-switch @radix-ui/react-tabs @radix-ui/react-tooltip
 ```
 
-**Note:** `hazo_config`, `hazo_connect`, and `hazo_logs` are required peer dependencies.
+**Note:** `next`, `react`, `react-dom`, `next-auth`, and UI packages are peer dependencies. Your consuming project controls the versions, preventing duplication and type conflicts.
+
+**Next.js config:** If using password features, add `argon2` to `serverExternalPackages` in your `next.config.mjs`:
+
+```javascript
+const nextConfig = {
+  serverExternalPackages: ['argon2'],
+};
+```
 
 ---
 
@@ -163,7 +174,7 @@ The fastest way to get started is using the CLI commands:
 
 ```bash
 # 1. Install the package and peer dependencies
-npm install hazo_auth hazo_config hazo_connect hazo_logs
+npm install hazo_auth hazo_config hazo_connect hazo_logs next react react-dom next-auth
 
 # 2. Initialize your project (directories, config, database, images)
 npx hazo_auth init
@@ -1153,6 +1164,12 @@ Google OAuth adds one new dependency:
 - Verify `/api/hazo_auth/oauth/google/callback` route exists
 - Check server logs for errors during session creation
 
+**OAuth redirect goes to localhost behind a reverse proxy (Cloudflare Tunnel, nginx):**
+- Set `NEXTAUTH_URL` to your public domain (e.g., `https://gotimer.org`)
+- hazo_auth automatically rewrites the request URL so NextAuth constructs the correct `redirect_uri`
+- Verify `AUTH_TRUST_HOST=true` is set in your environment
+- No `next.config` changes needed — the fix is built into `hazo_auth/server/routes`
+
 **404 after Google OAuth login (v5.1.16+ fix):**
 - If users get 404 after Google OAuth, the `hazo_invitations` table may be missing
 - **Option 1:** Run migration `009_scope_consolidation.sql` to create the table
@@ -2731,6 +2748,65 @@ For full documentation, see `CHANGE_LOG.md` and `TECHDOC.md`.
 
 ---
 
+## Relationship Accounts (Managed Sub-Profiles)
+
+hazo_auth supports managed sub-profiles where a parent user can create and manage child accounts that don't require email addresses. This is useful for apps like educational platforms (parent managing kids), classrooms (teacher managing students), or care facilities (caregiver managing patients).
+
+### Enabling
+
+The feature is opt-in. Add to your `hazo_auth_config.ini`:
+
+```ini
+[hazo_auth__relationships]
+enabled = true
+allowed_types = parent, teacher, manager, caregiver
+default_type = parent
+max_children_per_user = 10
+pin_min_length = 4
+pin_max_length = 6
+```
+
+Run the migration: `npm run migrate migrations/013_relationships.sql`
+
+### API Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/hazo_auth/relationships` | List managed child profiles |
+| POST | `/api/hazo_auth/relationships` | Create child profile (body: `{ name, pin?, relationship_type? }`) |
+| PATCH | `/api/hazo_auth/relationships` | Update relationship permissions |
+| DELETE | `/api/hazo_auth/relationships?relationship_id=X` | Delete relationship |
+| POST | `/api/hazo_auth/relationships/self` | Create self-relationship |
+| POST | `/api/hazo_auth/relationships/upgrade` | Upgrade managed user to standalone account |
+| POST | `/api/hazo_auth/pin-login` | PIN-based login for managed profiles |
+
+### PIN Login
+
+Managed profiles can authenticate via a simple PIN on shared devices:
+
+```typescript
+const res = await fetch("/api/hazo_auth/pin-login", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({
+    parent_user_id: "parent-uuid",
+    child_user_id: "child-uuid",
+    pin: "1234",
+  }),
+});
+// Response includes managed_by_user_id in the session
+```
+
+### Profile Picture Support
+
+Parents can manage child profile pictures via the existing upload routes by passing `?target_user_id=child-uuid`. The relationship's `can_edit_profile` permission is checked.
+
+### Feature Gating
+
+When `enabled = false` (default), all relationship routes return 404, email remains required for all users, and existing behavior is completely unchanged.
+
+---
+
 ## User Profile Service
 
 The `hazo_auth` package provides a batch user profile retrieval service for applications that need basic user information, such as chat applications or user lists.

package/SETUP_CHECKLIST.md

@@ -7,8 +7,8 @@ This checklist provides step-by-step instructions for setting up the `hazo_auth`
 The fastest way to set up hazo_auth:
 
 ```bash
-# 1. Install the package and peer dependencies
-npm install hazo_auth hazo_config hazo_connect hazo_logs
+# 1. Install the package and required peer dependencies
+npm install hazo_auth hazo_config hazo_connect hazo_logs next react react-dom next-auth
 
 # 2. Initialize project (creates directories, config files, database, images)
 npx hazo_auth init
@@ -69,10 +69,27 @@ node --version
 ### Step 1.1: Install the package and peer dependencies
 
 ```bash
-npm install hazo_auth hazo_config hazo_connect hazo_logs
+# Required peer dependencies
+npm install hazo_auth hazo_config hazo_connect hazo_logs next react react-dom next-auth
+
+# UI peer dependencies (required if using hazo_auth UI components)
+npm install hazo_ui lucide-react sonner next-themes @radix-ui/react-accordion @radix-ui/react-alert-dialog @radix-ui/react-avatar @radix-ui/react-checkbox @radix-ui/react-dialog @radix-ui/react-dropdown-menu @radix-ui/react-hover-card @radix-ui/react-label @radix-ui/react-select @radix-ui/react-separator @radix-ui/react-slot @radix-ui/react-switch @radix-ui/react-tabs @radix-ui/react-tooltip
+```
+
+**Note (v5.2.0+):** `next`, `react`, `react-dom`, `next-auth`, and UI packages are peer dependencies. You must install them in your consuming project. This ensures a single copy of each package is used, preventing version conflicts and bundle duplication.
+
+**Next.js config for server-only packages:**
+
+If using password features (login, register, password reset), add `argon2` to your `next.config.mjs`:
+
+```javascript
+const nextConfig = {
+  serverExternalPackages: ['argon2'],
+};
+export default nextConfig;
 ```
 
-**Note (v5.2.0+):** `hazo_config`, `hazo_connect`, and `hazo_logs` are now peer dependencies. You must install them in your project.
+This tells Next.js to load `argon2` at runtime instead of trying to bundle it.
 
 **Verify installation:**
 ```bash
@@ -750,6 +767,11 @@ auto_link_unverified_accounts = true
 google_button_text = Continue with Google
 oauth_divider_text = or
 
+# NextAuth page paths (v5.1.32+)
+# Consumers should set these to their actual login page routes
+# sign_in_page = /login
+# error_page = /login
+
 # Post-Login Redirect Configuration (v5.1.16+)
 # URL for users who need to create a firm (default: /hazo_auth/create_firm)
 # create_firm_url = /hazo_auth/create_firm
@@ -1161,6 +1183,56 @@ export async function proxy(request: NextRequest) {
 
 ---
 
+## Phase 5.2: Relationship Accounts Setup (Optional)
+
+If your app needs managed sub-profiles (parent managing children, teacher managing students):
+
+### Step 5.2.1: Enable in config
+
+Add to `config/hazo_auth_config.ini`:
+```ini
+[hazo_auth__relationships]
+enabled = true
+allowed_types = parent, teacher, manager, caregiver
+default_type = parent
+```
+
+### Step 5.2.2: Run migration
+
+```bash
+npm run migrate migrations/013_relationships.sql
+```
+
+### Step 5.2.3: Create API routes
+
+```bash
+npx hazo_auth generate-routes
+```
+
+Or manually create:
+
+`app/api/hazo_auth/relationships/route.ts`:
+```typescript
+export { GET, POST, PATCH, DELETE } from "hazo_auth/server/routes/relationships";
+```
+
+`app/api/hazo_auth/relationships/self/route.ts`:
+```typescript
+export { POST } from "hazo_auth/server/routes/relationship_self";
+```
+
+`app/api/hazo_auth/relationships/upgrade/route.ts`:
+```typescript
+export { POST } from "hazo_auth/server/routes/relationship_upgrade";
+```
+
+`app/api/hazo_auth/pin-login/route.ts`:
+```typescript
+export { POST } from "hazo_auth/server/routes/pin_login";
+```
+
+---
+
 ## Phase 6: Verification Tests
 
 Run these tests to verify your setup is working correctly.

package/cli-src/cli/init.ts

@@ -244,11 +244,38 @@ export async function handle_init(): Promise<void> {
     result.skipped.push("auth page images (source not found)");
   }
 
-  // Step 5: Create .gitkeep files for empty directories
+  // Step 5: Copy sql-wasm.wasm for SQLite WASM support
+  console.log("\n\x1b[1m📦 Copying sql-wasm.wasm...\x1b[0m\n");
+
+  const wasm_target = path.join(project_root, "public", "sql-wasm.wasm");
+  if (fs.existsSync(wasm_target)) {
+    console.log(`\x1b[33m[EXISTS]\x1b[0m public/sql-wasm.wasm`);
+    result.skipped.push("sql-wasm.wasm");
+  } else {
+    const wasm_search_paths = [
+      path.join(project_root, "node_modules", "sql.js", "dist", "sql-wasm.wasm"),
+      path.join(package_root, "..", "..", "node_modules", "sql.js", "dist", "sql-wasm.wasm"),
+      path.join(package_root, "node_modules", "sql.js", "dist", "sql-wasm.wasm"),
+    ];
+    const wasm_source = wasm_search_paths.find((p) => fs.existsSync(p));
+
+    if (wasm_source) {
+      ensure_dir(path.join(project_root, "public"));
+      fs.copyFileSync(wasm_source, wasm_target);
+      console.log(`\x1b[32m[COPY]\x1b[0m sql-wasm.wasm -> public/sql-wasm.wasm`);
+      result.files_copied.push("sql-wasm.wasm");
+    } else {
+      console.log(`\x1b[33m[SKIP]\x1b[0m sql-wasm.wasm not found — install sql.js or copy manually:`);
+      console.log(`       cp node_modules/sql.js/dist/sql-wasm.wasm public/`);
+      result.skipped.push("sql-wasm.wasm (sql.js not found)");
+    }
+  }
+
+  // Step 6: Create .gitkeep files for empty directories
   console.log("\n\x1b[1m📌 Creating .gitkeep files...\x1b[0m\n");
-  
+
   const empty_dirs = ["public/profile_pictures/uploads", "data"];
-  
+
   for (const dir of empty_dirs) {
     const full_path = path.join(project_root, dir);
     if (fs.existsSync(full_path)) {
@@ -256,10 +283,10 @@ export async function handle_init(): Promise<void> {
       console.log(`\x1b[32m[CREATE]\x1b[0m ${dir}/.gitkeep`);
     }
   }
-  
-  // Step 6: Create .env.local.example template
+
+  // Step 7: Create .env.local.example template
   console.log("\n\x1b[1m🔑 Creating environment template...\x1b[0m\n");
-  
+
   if (create_env_template(project_root)) {
     console.log(`\x1b[32m[CREATE]\x1b[0m .env.local.example`);
     result.files_copied.push(".env.local.example");
@@ -267,8 +294,8 @@ export async function handle_init(): Promise<void> {
     console.log(`\x1b[33m[EXISTS]\x1b[0m .env.local.example`);
     result.skipped.push(".env.local.example");
   }
-  
-  // Step 7: Create SQLite database with schema
+
+  // Step 8: Create SQLite database with schema
   console.log("\n\x1b[1m🗄️  Creating SQLite database...\x1b[0m\n");
 
   try {

package/cli-src/lib/auth/auth_types.ts

@@ -10,6 +10,7 @@ export type HazoAuthUser = {
   email_address: string;
   is_active: boolean; // Derived from status column: status === 'ACTIVE'
   profile_picture_url: string | null;
+  managed_by_user_id?: string | null;
   // App-specific user data (JSON object stored as TEXT in database)
   app_user_data: Record<string, unknown> | null;
 };

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

@@ -183,6 +183,7 @@ async function fetch_user_data_from_db(user_id: string): Promise<{
     is_active: user_db.status === "ACTIVE", // Derived from status column
     profile_picture_url:
       (user_db.profile_picture_url as string | null) || null,
+    managed_by_user_id: (user_db.managed_by_user_id as string | undefined) || null,
     app_user_data: parse_app_user_data(user_db.app_user_data),
   };
 

package/cli-src/lib/auth/nextauth_config.ts

@@ -70,9 +70,9 @@ export function get_nextauth_config(): AuthOptions {
   return {
     providers,
     pages: {
-      // Use hazo_auth login page for sign-in errors
-      signIn: "/hazo_auth/login",
-      error: "/hazo_auth/login",
+      // Configurable via [hazo_auth__oauth] sign_in_page / error_page in hazo_auth_config.ini
+      signIn: oauth_config.sign_in_page,
+      error: oauth_config.error_page,
     },
     callbacks: {
       /**

package/cli-src/lib/config/default_config.ts

@@ -165,6 +165,10 @@ export const DEFAULT_OAUTH = {
   google_button_text: "Continue with Google",
   /** Text displayed on the divider between OAuth and email/password form */
   oauth_divider_text: "or continue with email",
+  /** NextAuth signIn page path (default: /hazo_auth/login) */
+  sign_in_page: "/hazo_auth/login",
+  /** NextAuth error page path (default: /hazo_auth/login) */
+  error_page: "/hazo_auth/login",
   /** URL for users who need to create a firm (default: /hazo_auth/create_firm) */
   create_firm_url: "/hazo_auth/create_firm",
   /** Default redirect after OAuth login for users with scopes */
@@ -221,6 +225,22 @@ export const DEFAULT_MULTI_TENANCY = {
   default_user_limit: 0,
 } as const;
 
+// section: relationships
+export const DEFAULT_RELATIONSHIPS = {
+  /** Whether managed sub-profile/relationship accounts are enabled (default: false) */
+  enabled: false,
+  /** Comma-separated allowed relationship types (default: parent) */
+  allowed_types: "parent",
+  /** Default relationship type when not specified (default: parent) */
+  default_type: "parent",
+  /** Maximum number of managed profiles per user (default: 10) */
+  max_children_per_user: 10,
+  /** Minimum PIN length for managed profile auth (default: 4) */
+  pin_min_length: 4,
+  /** Maximum PIN length for managed profile auth (default: 6) */
+  pin_max_length: 6,
+} as const;
+
 // section: dev_lock
 export const DEFAULT_DEV_LOCK = {
   /** Enable the development lock screen (also requires HAZO_AUTH_DEV_LOCK_ENABLED env var) */
@@ -280,6 +300,7 @@ export const HAZO_AUTH_DEFAULTS = {
   navbar: DEFAULT_NAVBAR,
   userTypes: DEFAULT_USER_TYPES,
   multiTenancy: DEFAULT_MULTI_TENANCY,
+  relationships: DEFAULT_RELATIONSHIPS,
 } as const;
 
 // section: types

package/cli-src/lib/oauth_config.server.ts

@@ -18,6 +18,10 @@ export type OAuthConfig = {
   google_button_text: string;
   /** Text displayed on the divider between OAuth and email/password form */
   oauth_divider_text: string;
+  /** NextAuth signIn page path */
+  sign_in_page: string;
+  /** NextAuth error page path */
+  error_page: string;
   /** URL for users who need to create a firm (default: /hazo_auth/create_firm) */
   create_firm_url: string;
   /** Default redirect after OAuth login for users with scopes */
@@ -68,6 +72,18 @@ export function get_oauth_config(): OAuthConfig {
     DEFAULT_OAUTH.oauth_divider_text
   );
 
+  const sign_in_page = get_config_value(
+    SECTION_NAME,
+    "sign_in_page",
+    DEFAULT_OAUTH.sign_in_page
+  );
+
+  const error_page = get_config_value(
+    SECTION_NAME,
+    "error_page",
+    DEFAULT_OAUTH.error_page
+  );
+
   const create_firm_url = get_config_value(
     SECTION_NAME,
     "create_firm_url",
@@ -98,6 +114,8 @@ export function get_oauth_config(): OAuthConfig {
     auto_link_unverified_accounts,
     google_button_text,
     oauth_divider_text,
+    sign_in_page,
+    error_page,
     create_firm_url,
     default_redirect,
     skip_invitation_check,

package/cli-src/lib/relationships_config.server.ts

@@ -0,0 +1,47 @@
+// file_description: server-only helper to read relationship accounts configuration from hazo_auth_config.ini
+// section: server-only-guard
+import "server-only";
+
+// section: imports
+import { get_config_value, get_config_boolean, get_config_number } from "./config/config_loader.server.js";
+import { DEFAULT_RELATIONSHIPS } from "./config/default_config.js";
+
+// section: types
+export type RelationshipsConfig = {
+  /** Whether managed sub-profile/relationship accounts are enabled */
+  enabled: boolean;
+  /** Comma-separated allowed relationship types */
+  allowed_types: string;
+  /** Default relationship type when not specified */
+  default_type: string;
+  /** Maximum number of managed profiles per user */
+  max_children_per_user: number;
+  /** Minimum PIN length for managed profile auth */
+  pin_min_length: number;
+  /** Maximum PIN length for managed profile auth */
+  pin_max_length: number;
+};
+
+// section: constants
+const SECTION_NAME = "hazo_auth__relationships";
+
+// section: helpers
+export function get_relationships_config(): RelationshipsConfig {
+  return {
+    enabled: get_config_boolean(SECTION_NAME, "enabled", DEFAULT_RELATIONSHIPS.enabled),
+    allowed_types: get_config_value(SECTION_NAME, "allowed_types", DEFAULT_RELATIONSHIPS.allowed_types),
+    default_type: get_config_value(SECTION_NAME, "default_type", DEFAULT_RELATIONSHIPS.default_type),
+    max_children_per_user: get_config_number(SECTION_NAME, "max_children_per_user", DEFAULT_RELATIONSHIPS.max_children_per_user),
+    pin_min_length: get_config_number(SECTION_NAME, "pin_min_length", DEFAULT_RELATIONSHIPS.pin_min_length),
+    pin_max_length: get_config_number(SECTION_NAME, "pin_max_length", DEFAULT_RELATIONSHIPS.pin_max_length),
+  };
+}
+
+export function is_relationships_enabled(): boolean {
+  return get_config_boolean(SECTION_NAME, "enabled", DEFAULT_RELATIONSHIPS.enabled);
+}
+
+export function get_allowed_relationship_types(): string[] {
+  const types_str = get_config_value(SECTION_NAME, "allowed_types", DEFAULT_RELATIONSHIPS.allowed_types);
+  return types_str.split(",").map((t) => t.trim()).filter(Boolean);
+}

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

@@ -24,6 +24,8 @@ CREATE TABLE IF NOT EXISTS hazo_users (
   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'))
 );
@@ -135,6 +137,25 @@ CREATE INDEX IF NOT EXISTS idx_hazo_invitations_scope ON hazo_invitations(scope_
 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);
 
+CREATE INDEX IF NOT EXISTS idx_hazo_users_managed_by ON hazo_users(managed_by_user_id);
+
+-- Relationships table
+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);
+
 -- Firm admin role (for firm creators)
 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'));