hazo_auth 7.0.2 → 9.0.0

package/README.md

@@ -2,6 +2,40 @@
 
 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 v8.0.1 🔧
+
+**Auto-test and middleware bug fixes**
+
+- Fixed 307 redirects blocking OTP, strings, consent, and legal_docs API routes when hit without auth cookies — all four are now in `middleware.ts` `public_routes`.
+- Auto-test runner register calls now include `legal_accepted` hashes when legal docs are configured, fixing 24 test failures that cascaded from the initial registration step.
+
+### What's New in v8.0.0 ⚠️ BREAKING CHANGE
+
+**Legal Document Acceptance** — opt-in, INI-configured. Add `[hazo_auth__legal_docs]` to `hazo_auth_config.ini` to require users to accept terms before registering. Each doc is a markdown file; hazo_auth hashes it, tracks acceptance history, and blocks register until all current hashes are accepted.
+
+**Breaking:** Deprecated page-component wrappers removed (`LoginPage`, `RegisterPage`, `ForgotPasswordPage`, `ResetPasswordPage`, `VerifyEmailPage` from `hazo_auth/page_components/*`). Use `*Layout` components directly in a server component instead.
+
+Run these migrations (in order) to upgrade an existing database:
+- `017_legal_acceptance_column.sql`
+- `018_hazo_legal_acceptances.sql`
+- `019_hazo_legal_doc_versions.sql`
+
+**New exports** — `LegalAcceptanceGate`, `LegalDocDrawer`, `LegalDocCheckboxList`, `LegalDocCombinedView` from `hazo_auth/client`; `legalDocsGET`, `legalDocsAcceptPOST`, `legalDocsPublishPOST` from `hazo_auth/server/routes`; `LegalDoc`, `LegalAcceptanceRecord`, `LegalAcceptanceMap` types from `hazo_auth`.
+
+**New dependency** — `react-markdown` (markdown rendering for legal doc drawers).
+
+```ini
+# config/hazo_auth_config.ini
+[hazo_auth__legal_docs]
+display_mode = separate    # separate | combined
+doc_1_key    = tos
+doc_1_title  = Terms of Service
+doc_1_path   = legal/tos.md
+doc_2_key    = privacy
+doc_2_title  = Privacy Policy
+doc_2_path   = legal/privacy.md
+```
+
 ### What's New in v5.3.1 🔧
 
 **`get_client_ip(request)` exported from `hazo_auth/server-lib`** — extracts the client IP from `x-forwarded-for` (first element), falling back to `x-real-ip`, then `"unknown"`. Previously private to `hazo_get_auth.server.ts`. Useful for consumers that need consistent IP extraction across handlers (e.g., `hazo_feedback` audit logging).

package/SETUP_CHECKLIST.md

@@ -2,6 +2,37 @@
 
 This checklist provides step-by-step instructions for setting up the `hazo_auth` package in your Next.js project. AI assistants can follow this guide to ensure complete and correct setup.
 
+## v8.0.0 Migration (from v7.x)
+
+### Breaking changes
+
+Remove the deprecated page-component imports if you used them:
+
+```diff
+- import LoginPage from 'hazo_auth/page_components/login';
+- import RegisterPage from 'hazo_auth/page_components/register';
++ // Use the Layout components directly in a server component instead
++ import LoginLayout from 'hazo_auth/components/layouts/login';
++ import RegisterLayout from 'hazo_auth/components/layouts/register';
+```
+
+### New migrations (run in order)
+
+```bash
+npm run migrate migrations/017_legal_acceptance_column.sql
+npm run migrate migrations/018_hazo_legal_acceptances.sql
+npm run migrate migrations/019_hazo_legal_doc_versions.sql
+```
+
+### Legal docs setup (optional)
+
+1. Add `[hazo_auth__legal_docs]` to `config/hazo_auth_config.ini` (see commented sample at the bottom of that file)
+2. Create markdown files at the configured paths (e.g. `legal/tos.md`, `legal/privacy.md`)
+3. Wrap your app layout with `<LegalAcceptanceGate>` from `hazo_auth/client`
+4. Go to User Management → Legal Docs tab, click "Publish current version" per doc to activate gating for existing users
+
+---
+
 ## v5.3.0 Migration (from v5.2.x)
 
 If you are already on hazo_auth `5.2.x`, the only mandatory work is wiring up hazo_notify's template manager at boot. Apps that don't use the templated email path (only the plain `send_email`) keep working unchanged after bumping the peer dep.

package/cli-src/lib/AGENTS.md

@@ -0,0 +1,26 @@
+# src/lib/ — AGENTS.md
+
+Server-side business logic, configuration loaders, and utilities.
+
+## Key subdirectories
+
+- `auth/` — Core auth logic: `hazo_get_auth.server.ts` (the main auth utility), session token validation, OAuth helpers, auth cache, scope cache, rate limiter.
+- `config/` — Config loaders: `config_loader.server.ts` (hazo_config-based, handles all 18+ INI sections), `hazo_auth_core_config.ts` (hazo_core loadConfig overlay for critical sections with Zod validation).
+- `services/` — Business logic: `login_service.ts`, `registration_service.ts`, `password_reset_service.ts`, `session_token_service.ts`, `scope_service.ts`, `invitation_service.ts`, `email_service.ts`, etc.
+- `auto_test/` — hazo_auth's internal test runner (server-side). This is the original test infrastructure that inspired `hazo_ui/test-harness`. Executes scenario definitions via API calls; the runner is invoked through `/api/hazo_auth/auto_test`.
+- `utils/` — Utilities: `api_route_helpers.ts` (re-exports `get_filename`/`get_line_number` from hazo_logs), `sanitize_error_for_user.ts`.
+- `legal/` — Legal docs management (acceptance tracking, versioned docs).
+- `schema/` — Zod schemas for request validation.
+
+## Error handling (Wave 2)
+
+Server-side `throw new Error(...)` replaced with `HazoError` subclasses from `hazo_core`:
+- `HazoAuthError(HAZO_AUTH_FORBIDDEN)` — authentication required or permission denied
+- `HazoAuthError(HAZO_AUTH_INVALID_TOKEN)` — invalid session token
+- `HazoNotFoundError(HAZO_AUTH_USER_NOT_FOUND)` — user not found
+- `HazoRateLimitError(HAZO_AUTH_RATE_LIMITED)` — rate limit exceeded
+- `HazoConfigError(HAZO_AUTH_CONFIG)` — missing/invalid config or env vars
+
+## Logging
+
+All logging via `create_app_logger()` from `app_logger.ts`, which returns `createLogger('hazo_auth')` from `hazo_core`. Log calls use structured format: `logger.info('event.name', { fields })`.

package/cli-src/lib/app_logger.ts

@@ -1,9 +1,6 @@
-// file_description: server-only wrapper for the main app logging service using hazo_logs
-// section: server-only-guard
-import "server-only";
-
+// file_description: server-only wrapper for the main app logging service using hazo_core
 // section: imports
-import { createLogger } from "hazo_logs";
+import { createLogger } from "hazo_core";
 
 // section: logger_instance
 // Create a singleton logger for the hazo_auth package
@@ -11,7 +8,6 @@ const logger = createLogger("hazo_auth");
 
 /**
  * Returns the hazo_auth logger instance
- * Uses hazo_logs for consistent logging across hazo packages
+ * Uses hazo_core for consistent logging across hazo packages
  */
 export const create_app_logger = () => logger;
-

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

@@ -1,5 +1,6 @@
 // file_description: Type definitions and error classes for hazo_get_auth utility
 // section: types
+import type { LegalAcceptanceMap } from '../legal/legal_docs_types';
 
 /**
  * User data structure returned by hazo_get_auth
@@ -13,6 +14,8 @@ export type HazoAuthUser = {
   managed_by_user_id?: string | null;
   // App-specific user data (JSON object stored as TEXT in database)
   app_user_data: Record<string, unknown> | null;
+  // Legal document acceptance map (JSON object stored in database)
+  legal_acceptance: LegalAcceptanceMap | null;
 };
 
 /**

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

@@ -4,6 +4,7 @@ import "server-only";
 
 // section: imports
 import { NextRequest, NextResponse } from "next/server";
+import { HazoAuthError } from "hazo_core";
 import { get_hazo_connect_instance } from "../hazo_connect_instance.server.js";
 import { createCrudService } from "hazo_connect/server";
 import { map_db_source_to_ui } from "../services/profile_picture_source_mapper.js";
@@ -118,7 +119,7 @@ export async function require_auth(request: NextRequest): Promise<AuthUser> {
   const result = await get_authenticated_user(request);
   
   if (!result.authenticated) {
-    throw new Error("Authentication required");
+    throw new HazoAuthError({ code: 'HAZO_AUTH_FORBIDDEN', pkg: 'hazo_auth', message: 'Authentication required' });
   }
   
   return result;

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

@@ -24,6 +24,7 @@ import "server-only";
 // section: imports
 import { NextRequest } from "next/server";
 import { cookies } from "next/headers";
+import { generateRequestId } from "hazo_core";
 import {
   BASE_COOKIE_NAMES,
   get_cookie_name,
@@ -71,7 +72,7 @@ export async function ensure_anon_id(request: NextRequest): Promise<string> {
   }
 
   // Issue a new id and queue the Set-Cookie via the next/headers cookie store.
-  const new_id = crypto.randomUUID();
+  const new_id = generateRequestId().slice(4);
   const cookie_options = get_cookie_options({
     httpOnly: true,
     secure: process.env.NODE_ENV === "production",

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

@@ -4,6 +4,7 @@ import "server-only";
 
 // section: imports
 import { NextRequest } from "next/server";
+import { HazoNotFoundError, HazoAuthError, HazoRateLimitError, getCorrelationId } from "hazo_core";
 import { get_hazo_connect_instance } from "../hazo_connect_instance.server.js";
 import { createCrudService } from "hazo_connect/server";
 import { create_app_logger } from "../app_logger.js";
@@ -59,6 +60,24 @@ function parse_app_user_data(
   }
 }
 
+/**
+ * Parse raw legal_acceptance field from DB to LegalAcceptanceMap
+ * @param raw - Raw value from database (string or object)
+ * @returns Parsed LegalAcceptanceMap or null
+ */
+function parse_legal_acceptance(
+  raw: unknown,
+): import('../legal/legal_docs_types').LegalAcceptanceMap | null {
+  if (!raw) return null;
+  try {
+    const parsed = typeof raw === 'string' ? JSON.parse(raw) : raw;
+    if (typeof parsed !== 'object' || Array.isArray(parsed)) return null;
+    return parsed as import('../legal/legal_docs_types').LegalAcceptanceMap;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Gets client IP address from request
  * @param request - NextRequest object
@@ -165,14 +184,14 @@ async function fetch_user_data_from_db(user_id: string): Promise<{
   // Fetch user
   const users = await users_service.findBy({ id: user_id });
   if (!Array.isArray(users) || users.length === 0) {
-    throw new Error("User not found");
+    throw new HazoNotFoundError({ code: 'HAZO_AUTH_USER_NOT_FOUND', pkg: 'hazo_auth', message: 'User not found' });
   }
 
   const user_db = users[0];
 
   // Check if user is active (status must be 'ACTIVE')
   if (user_db.status !== "ACTIVE") {
-    throw new Error("User is inactive");
+    throw new HazoAuthError({ code: 'HAZO_AUTH_FORBIDDEN', pkg: 'hazo_auth', message: 'User account is inactive' });
   }
 
   // Build user object
@@ -185,6 +204,7 @@ async function fetch_user_data_from_db(user_id: string): Promise<{
       (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),
+    legal_acceptance: parse_legal_acceptance(user_db.legal_acceptance),
   };
 
   // v5.x: Fetch user's roles from hazo_user_scopes (scope-based role assignments)
@@ -422,6 +442,7 @@ export async function hazo_get_auth(
         line_number: get_line_number(),
         error: token_error_message,
         note: "Falling back to simple cookie check",
+        correlation_id: getCorrelationId(),
       });
     }
   }
@@ -445,8 +466,9 @@ export async function hazo_get_auth(
         filename: get_filename(),
         line_number: get_line_number(),
         ip: client_ip,
+        correlation_id: getCorrelationId(),
       });
-      throw new Error("Rate limit exceeded. Please try again later.");
+      throw new HazoRateLimitError({ code: 'HAZO_AUTH_RATE_LIMITED', pkg: 'hazo_auth', message: 'Rate limit exceeded. Please try again later.' });
     }
 
     return {
@@ -464,8 +486,9 @@ export async function hazo_get_auth(
       filename: get_filename(),
       line_number: get_line_number(),
       user_id,
+      correlation_id: getCorrelationId(),
     });
-    throw new Error("Rate limit exceeded. Please try again later.");
+    throw new HazoRateLimitError({ code: 'HAZO_AUTH_RATE_LIMITED', pkg: 'hazo_auth', message: 'Rate limit exceeded. Please try again later.' });
   }
 
   // Check cache
@@ -497,6 +520,7 @@ export async function hazo_get_auth(
         line_number: get_line_number(),
         user_id,
         error: error_message,
+        correlation_id: getCorrelationId(),
       });
 
       return {
@@ -531,6 +555,7 @@ export async function hazo_get_auth(
         missing_permissions,
         user_permissions: permissions,
         ip: client_ip,
+        correlation_id: getCorrelationId(),
       });
     }
 
@@ -580,6 +605,7 @@ export async function hazo_get_auth(
         scope_id: options.scope_id,
         user_scopes: scope_result.user_scopes,
         ip: client_ip,
+        correlation_id: getCorrelationId(),
       });
     }
 

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

@@ -0,0 +1,44 @@
+// file_description: Zod-validated config loader for hazo_auth core settings.
+// Covers server-critical sections ([hazo_auth__tokens], [hazo_auth__cookies], [hazo_auth__rate_limit], [log.overrides]).
+// UI sections (login_layout, register_layout, etc.) are still handled by config_loader.server.ts.
+import { z } from 'zod';
+import { loadConfig } from 'hazo_core';
+
+const HazoAuthCoreConfigSchema = z.object({
+  hazo_auth__tokens: z
+    .object({
+      access_token_ttl_seconds: z.string().optional().transform(v => v ? parseInt(v, 10) : 900),
+      refresh_token_ttl_seconds: z.string().optional().transform(v => v ? parseInt(v, 10) : 2592000),
+    })
+    .optional()
+    .transform(v => v ?? { access_token_ttl_seconds: 900, refresh_token_ttl_seconds: 2592000 }),
+  hazo_auth__cookies: z
+    .object({
+      cookie_prefix: z.string().optional().default(''),
+      cookie_domain: z.string().optional().default(''),
+    })
+    .optional()
+    .transform(v => v ?? { cookie_prefix: '', cookie_domain: '' }),
+  hazo_auth__rate_limit: z
+    .object({
+      max_attempts: z.string().optional().transform(v => v ? parseInt(v, 10) : 5),
+      window_minutes: z.string().optional().transform(v => v ? parseInt(v, 10) : 5),
+    })
+    .optional()
+    .transform(v => v ?? { max_attempts: 5, window_minutes: 5 }),
+  log: z
+    .object({
+      overrides: z.record(z.string(), z.string()).optional().default({}),
+    })
+    .optional()
+    .transform(v => v ?? { overrides: {} }),
+});
+
+export type HazoAuthCoreConfig = z.infer<typeof HazoAuthCoreConfigSchema>;
+
+export function getHazoAuthCoreConfig(): HazoAuthCoreConfig {
+  return loadConfig<HazoAuthCoreConfig>({
+    pkg: 'hazo_auth',
+    schema: HazoAuthCoreConfigSchema as never,
+  });
+}

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

@@ -2,7 +2,7 @@
 // section: server-only-guard
 import "server-only";
 
-
+import { HazoConfigError } from "hazo_core";
 import { read_config_section } from "./config/config_loader.server.js";
 
 // section: types
@@ -44,15 +44,18 @@ export function get_cookies_config(): CookiesConfig {
   const cookie_prefix = section?.cookie_prefix || "";
 
   if (!cookie_prefix) {
-    throw new Error(
-      "[hazo_auth] cookie_prefix is required but not configured.\n" +
-      "Set cookie_prefix in [hazo_auth__cookies] section of config/hazo_auth_config.ini:\n\n" +
-      "  [hazo_auth__cookies]\n" +
-      "  cookie_prefix = myapp_\n\n" +
-      "Also set the matching environment variable for Edge runtime (middleware):\n" +
-      "  HAZO_AUTH_COOKIE_PREFIX=myapp_\n\n" +
-      "This prevents cookie conflicts between apps using hazo_auth."
-    );
+    throw new HazoConfigError({
+      code: 'HAZO_AUTH_CONFIG',
+      pkg: 'hazo_auth',
+      message:
+        "[hazo_auth] cookie_prefix is required but not configured.\n" +
+        "Set cookie_prefix in [hazo_auth__cookies] section of config/hazo_auth_config.ini:\n\n" +
+        "  [hazo_auth__cookies]\n" +
+        "  cookie_prefix = myapp_\n\n" +
+        "Also set the matching environment variable for Edge runtime (middleware):\n" +
+        "  HAZO_AUTH_COOKIE_PREFIX=myapp_\n\n" +
+        "This prevents cookie conflicts between apps using hazo_auth.",
+    });
   }
 
   return {

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

@@ -7,6 +7,7 @@ import "server-only";
 // section: imports
 import { createHazoConnect } from "hazo_connect/server";
 import { HazoConfig } from "hazo_config/server";
+import { HazoConfigError } from "hazo_core";
 import path from "path";
 import fs from "fs";
 import { create_app_logger } from "./app_logger.js";
@@ -79,10 +80,13 @@ function get_hazo_connect_config(): {
       );
       sqlite_path = path.normalize(fallback_sqlite_path);
     } else {
-      throw new Error(
-        "[hazo_auth] sqlite_path not configured. Set sqlite_path in [hazo_connect] section of config/hazo_auth_config.ini, " +
-        "or set HAZO_CONNECT_SQLITE_PATH environment variable."
-      );
+      throw new HazoConfigError({
+        code: 'HAZO_AUTH_CONFIG',
+        pkg: 'hazo_auth',
+        message:
+          "[hazo_auth] sqlite_path not configured. Set sqlite_path in [hazo_connect] section of config/hazo_auth_config.ini, " +
+          "or set HAZO_CONNECT_SQLITE_PATH environment variable.",
+      });
     }
 
     // Validate config keys for typos
@@ -132,9 +136,11 @@ function get_hazo_connect_config(): {
       process.env.POSTGREST_API_KEY;
 
     if (!postgrest_url) {
-      throw new Error(
-        "PostgREST URL is required. Set postgrest_url in [hazo_connect] section of hazo_auth_config.ini or HAZO_CONNECT_POSTGREST_URL environment variable."
-      );
+      throw new HazoConfigError({
+        code: 'HAZO_AUTH_CONFIG',
+        pkg: 'hazo_auth',
+        message: 'PostgREST URL is required. Set postgrest_url in [hazo_connect] section of hazo_auth_config.ini or HAZO_CONNECT_POSTGREST_URL environment variable.',
+      });
     }
 
     return {
@@ -145,9 +151,11 @@ function get_hazo_connect_config(): {
     };
   }
 
-  throw new Error(
-    `Unsupported HAZO_CONNECT_TYPE: ${type}. Supported types: sqlite, postgrest`
-  );
+  throw new HazoConfigError({
+    code: 'HAZO_AUTH_CONFIG',
+    pkg: 'hazo_auth',
+    message: `Unsupported HAZO_CONNECT_TYPE: ${type}. Supported types: sqlite, postgrest`,
+  });
 }
 
 /**
@@ -177,7 +185,7 @@ export function create_sqlite_hazo_connect_server() {
     });
   }
 
-  throw new Error(`Unsupported database type: ${config.type}`);
+  throw new HazoConfigError({ code: 'HAZO_AUTH_CONFIG', pkg: 'hazo_auth', message: `Unsupported database type: ${config.type}` });
 }
 
 /**

package/cli-src/lib/legal/legal_docs_config.server.ts

@@ -0,0 +1,61 @@
+// file_description: server-only helper to read legal docs configuration from hazo_auth_config.ini
+// section: server-only-guard
+import 'server-only';
+
+// section: imports
+import { read_config_section } from '../config/config_loader.server.js';
+import type { LegalDocConfig, LegalDocsConfig } from './legal_docs_types';
+
+// section: constants
+const SECTION_NAME = 'hazo_auth__legal_docs';
+
+// section: cache
+// Cached after first load — INI changes require server restart anyway
+let _cached: LegalDocsConfig | null = null;
+
+// section: exports
+
+/**
+ * Reads legal docs configuration from hazo_auth_config.ini.
+ * Returns an empty docs array if the section is absent (legal docs disabled).
+ *
+ * Expected INI shape:
+ *   [hazo_auth__legal_docs]
+ *   display_mode = separate   ; or: combined
+ *   doc_1_key   = terms
+ *   doc_1_title = Terms of Service
+ *   doc_1_path  = legal/terms.md
+ *   doc_2_key   = privacy
+ *   doc_2_title = Privacy Policy
+ *   doc_2_path  = legal/privacy.md
+ */
+export function get_legal_docs_config(): LegalDocsConfig {
+  if (_cached) return _cached;
+
+  const section = read_config_section(SECTION_NAME) ?? {};
+
+  const docs: LegalDocConfig[] = [];
+  let i = 1;
+  while (section[`doc_${i}_key`]) {
+    docs.push({
+      key: section[`doc_${i}_key`],
+      title: section[`doc_${i}_title`] ?? section[`doc_${i}_key`],
+      path: section[`doc_${i}_path`],
+    });
+    i++;
+  }
+
+  _cached = {
+    docs,
+    display_mode: section['display_mode'] === 'combined' ? 'combined' : 'separate',
+  };
+
+  return _cached;
+}
+
+/**
+ * Call this in tests to clear the cache between runs.
+ */
+export function _reset_legal_docs_config_cache(): void {
+  _cached = null;
+}

package/cli-src/lib/legal/legal_docs_reader.server.ts

@@ -0,0 +1,36 @@
+// file_description: server-only utility that reads a legal document from disk and returns its content + SHA-256 hash
+// section: server-only-guard
+import 'server-only';
+
+// section: imports
+import * as fs from 'fs';
+import * as path from 'path';
+import { createHash } from 'crypto';
+
+// section: types
+
+export interface ReadDocResult {
+  content: string;
+  hash: string; // "sha256:<hex>"
+}
+
+// section: exports
+
+/**
+ * Reads a legal document from the filesystem and returns its text content
+ * together with a deterministic SHA-256 hash of that content.
+ *
+ * @param doc_path - Absolute path, or a path relative to process.cwd().
+ * @returns { content, hash } where hash is formatted as "sha256:<hex>".
+ * @throws If the file cannot be read.
+ */
+export function read_legal_doc(doc_path: string): ReadDocResult {
+  const abs_path = path.isAbsolute(doc_path)
+    ? doc_path
+    : path.join(process.cwd(), doc_path);
+
+  const content = fs.readFileSync(abs_path, 'utf-8');
+  const hex = createHash('sha256').update(content).digest('hex');
+
+  return { content, hash: `sha256:${hex}` };
+}