hazo_auth 7.0.1 → 8.0.1

package/README.md

@@ -2,176 +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 v7.0.0
+### What's New in v8.0.1 🔧
 
-**Themes, cookie consent, text overrides, and Facebook OAuth.**
+**Auto-test and middleware bug fixes**
 
-### Highlights
+- 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.
 
-- **Pluggable theme system** — `createTheme` + `<HazoAuthThemeProvider>` (zero FOUC, compiles to shadcn CSS variables). Use a preset or build from scratch.
-- **Facebook OAuth** — `<FacebookSignInButton>` and `handle_facebook_oauth_login` service. Strict linking by default (verified accounts only).
-- **Cookie consent banner** — `<CookieConsentBanner>` from `hazo_auth/consent`. GTM optional, 4 categories, theme-driven.
-- **Text override system** — `<HazoAuthStringsProvider>` and per-page `title`/`subtitle`/`ctaText`/`legalText` props. INI text keys removed.
-- **Preset themes** — `preset_neutral` (default look, no config needed) and `preset_indigo_sunset` from `hazo_auth/themes`.
+### What's New in v8.0.0 ⚠️ BREAKING CHANGE
 
-### Breaking Changes Summary
+**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.
 
-- Per-page `imageSrc`/`imageAlt`/`imageBackgroundColor` props removed — use `theme.brandPanel`.
-- INI text keys (`title`, `subtitle`, `cta_text`, `legal_text`) removed from layout sections — use `HazoAuthStringsProvider` or per-page props.
-- Facebook OAuth requires new env vars (`HAZO_AUTH_FACEBOOK_APP_ID`, `HAZO_AUTH_FACEBOOK_APP_SECRET`).
+**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.
 
-> Full upgrade guide: [MIGRATION.md](./MIGRATION.md)
+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`
 
----
-
-## What's New in v6.1.0
-
-**Email-OTP sign-in** — a passwordless, OAuth-free way to sign in via a 6-digit code emailed to the user. Targeted at single-operator deployments that don't want to wire Google OAuth or manage passwords.
-
-### Highlights
-
-- **New routes** — `POST /api/hazo_auth/otp/request` and `POST /api/hazo_auth/otp/verify`
-- **New components** — `<OTPRequestForm/>` and `<OTPVerifyForm/>` exported from `hazo_auth/client`
-- **New page** — `/hazo_auth/otp` (zero-config) via `hazo_auth/pages/otp`
-- **Sliding 7-day session** — OTP sessions auto-extend on `/me` when within 24h of expiry. OAuth/password sessions keep their existing 30-day fixed behaviour.
-- **Auto-register (opt-in)** — set `otp_auto_register = true` to let unknown emails sign in on first successful /verify
-- **Rate limited** — 3 requests/email/15min, 20 requests/IP/hour; per-code attempts capped at 5
-
-### Consumer example
-
-Mount the routes:
-
-```ts
-// app/api/hazo_auth/otp/request/route.ts
-export { otpRequestPOST as POST } from "hazo_auth/server/routes";
-
-// app/api/hazo_auth/otp/verify/route.ts
-export { otpVerifyPOST as POST } from "hazo_auth/server/routes";
-```
-
-Render the zero-config page:
-
-```tsx
-// app/hazo_auth/otp/page.tsx
-export { default } from "hazo_auth/pages/otp";
-```
-
-Or compose components yourself:
-
-```tsx
-"use client";
-import { OTPRequestForm, OTPVerifyForm } from "hazo_auth/client";
-import { useState } from "react";
-
-export default function CustomOtp() {
-  const [sent_to, set_sent_to] = useState<string | null>(null);
-  return sent_to
-    ? <OTPVerifyForm email={sent_to} redirect_url="/" />
-    : <OTPRequestForm on_sent={set_sent_to} />;
-}
-```
-
-### Required setup
-
-1. Apply migration: `npm run migrate migrations/015_email_otp.sql`
-2. Add `[hazo_auth__otp]` section to `config/hazo_auth_config.ini` (template in `hazo_auth_config.example.ini`)
-3. `hazo_notify ^3.0.0` (existing peer dep) must be configured to deliver email
-4. New peer dep: `input-otp` (optional; required only if you render `<OTPVerifyForm/>`)
-5. **Add OTP routes to your middleware/proxy `public_routes`** — unauthenticated users land on the OTP page, so the page route and its API routes must bypass auth guards:
-
-```typescript
-// middleware.ts / proxy.ts  (in your consuming app)
-const public_routes = [
-  // ... existing entries ...
-  "/hazo_auth/otp",        // OTP sign-in page (public — users arrive unauthenticated)
-  "/api/hazo_auth/otp",    // OTP request + verify API routes
-];
-```
-
-Without this your middleware redirects unauthenticated users away from the sign-in page before they can authenticate.
-
-See `MIGRATION.md` "v6.0.x → v6.1" for the full upgrade walkthrough.
-
----
-
-### What's New in v6.0.0 🚨 BREAKING CHANGE
-
-**`TenantAuthResult.organization` / `.organization_id` renamed to `.selected_scope` / `.selected_scope_id`.**
-
-The multi-tenancy model has been scope-based for several releases — `auth.user_scopes`, `auth.scope_access_via`, `auth.scope_ok`, the `hazo_auth_scope_id` cookie, the `X-Hazo-Scope-Id` header. The only holdouts using the legacy "organization" name were two fields on `TenantAuthResult` that were always just *"the currently selected scope"* under the hood. This release eliminates the inconsistency.
-
-> 📖 **Full migration guide:** [MIGRATION.md → v5.x → v6.0](./MIGRATION.md#v5x--v60-organization--selected_scope)
-
-**No behavioral change.** `selected_scope_id` is derived from the same scope-selection cookie/header that `organization_id` was. Wire-format auth responses change field names, but the underlying scope lookup is identical.
-
-**No deprecation shim.** A clean find-replace is the upgrade path. If you absolutely need a transitional period, pin to `hazo_auth@^5.3` until you can do the rename in one shot.
-
-**What to replace (find ↔ replace, all in your app code):**
-
-| Find                                              | Replace with                                       |
-| ------------------------------------------------- | -------------------------------------------------- |
-| `auth.organization`                               | `auth.selected_scope`                              |
-| `auth.organization_id`                            | `auth.selected_scope_id`                           |
-| `import type { TenantOrganization }`              | `import type { SelectedScope }`                    |
-| `: TenantOrganization`                            | `: SelectedScope`                                  |
-| `AuthenticatedTenantAuthWithOrg`                  | `AuthenticatedTenantAuthWithSelectedScope`         |
-
-**Before / after example:**
-
-```typescript
-// BEFORE (v5.x)
-import { hazo_get_tenant_auth } from "hazo_auth/server-lib";
-import type { TenantOrganization } from "hazo_auth";
-
-export async function GET(request: NextRequest) {
-  const auth = await hazo_get_tenant_auth(request);
-  if (!auth.authenticated || !auth.organization) {
-    return NextResponse.json({ error: "no tenant" }, { status: 403 });
-  }
-  const data = await getData(auth.organization_id);  // or auth.organization.id
-  return NextResponse.json({ org: auth.organization, data });
-}
+**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`.
 
-// AFTER (v6.0)
-import { hazo_get_tenant_auth } from "hazo_auth/server-lib";
-import type { SelectedScope } from "hazo_auth";
+**New dependency** — `react-markdown` (markdown rendering for legal doc drawers).
 
-export async function GET(request: NextRequest) {
-  const auth = await hazo_get_tenant_auth(request);
-  if (!auth.authenticated || !auth.selected_scope) {
-    return NextResponse.json({ error: "no tenant scope" }, { status: 403 });
-  }
-  const data = await getData(auth.selected_scope_id);  // or auth.selected_scope.id
-  return NextResponse.json({ selected_scope: auth.selected_scope, data });
-}
-```
-
-**What did NOT change** (same names, same behavior, same wire format):
-- `auth.user_scopes` — array of all scopes the user has access to
-- `auth.scope_ok`, `auth.scope_access_via` — scope-access fields
-- `hazo_auth_scope_id` cookie name and `X-Hazo-Scope-Id` request header
-- All `Tenant*` type and class names: `TenantAuthResult`, `TenantAuthOptions`, `RequiredTenantAuthResult`, `TenantRequiredError`, `TenantAccessDeniedError`, `hazo_get_tenant_auth`, `require_tenant_auth`, `withAuth`'s `require_tenant` option
-- The error response `{ code: "TENANT_REQUIRED" }` shape — only the human-readable `error` string was rephrased ("Organization context required" → "Tenant scope context required")
-
-**One-liner upgrade for typical consumers:**
-
-```bash
-# Run from your app repo (NOT inside hazo_auth itself).
-# Update the path glob to match your code layout.
-git grep -l "organization\b\|TenantOrganization\|AuthenticatedTenantAuthWithOrg" -- 'src/**' 'app/**' 'lib/**' \
-  | xargs sed -i.bak '
-    s/auth\.organization_id\b/auth.selected_scope_id/g;
-    s/auth\.organization\b/auth.selected_scope/g;
-    s/\bTenantOrganization\b/SelectedScope/g;
-    s/\bAuthenticatedTenantAuthWithOrg\b/AuthenticatedTenantAuthWithSelectedScope/g;
-  '
-# Then: review the diff carefully — sed is blunt. Remove .bak files when satisfied.
+```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
 ```
 
-> ⚠️ The sed line is a starting point, not a blanket "trust me." It only catches `auth.organization*` and the type names. If you destructure (`const { organization } = auth`), aliased imports (`TenantOrganization as Org`), or reference `organization` for unrelated reasons (HTML autocomplete attribute, your own variables), the script either misses or wrongly rewrites them. **Always diff before committing.**
-
----
-
 ### 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).
@@ -472,30 +336,23 @@ export default function Page() {
 }
 ```
 
-**Customizing Visual Appearance (v7.0+):**
-
-Use `HazoAuthThemeProvider` instead of per-page image props (which were removed in v7.0):
+**Customizing Visual Appearance (Optional):**
 
-```tsx
-import { createTheme, HazoAuthThemeProvider } from "hazo_auth/theme";
+```typescript
+// All pages accept optional visual props
 import { LoginPage } from "hazo_auth/pages/login";
 
-const theme = createTheme({
-  layout: "split",
-  brandPanel: { logoSrc: "/logo.svg", tagline: "Welcome.", backgroundGradient: "linear-gradient(135deg, #3730A3, #F59E0B)" },
-});
-
 export default function Page() {
   return (
-    <HazoAuthThemeProvider theme={theme}>
-      <LoginPage theme={theme} />
-    </HazoAuthThemeProvider>
+    <LoginPage
+      image_src="/custom-login-image.jpg"
+      image_alt="My company logo"
+      image_background_color="#f0f0f0"
+    />
   );
 }
 ```
 
-See the [Theming](#theming-v700) section for all options.
-
 **Embedding MySettings in Your Dashboard:**
 
 ```typescript
@@ -685,132 +542,6 @@ The dark class is typically added by next-themes or similar theme providers.
 
 ---
 
-## Theming (v7.0.0+)
-
-hazo_auth v7 ships a pluggable theme system. `<HazoAuthThemeProvider>` is a Server Component that injects CSS variables at `:root` with zero FOUC.
-
-### Option 1: Use a preset directly
-
-```tsx
-import { HazoAuthThemeProvider } from "hazo_auth/theme";
-import { preset_indigo_sunset } from "hazo_auth/themes";
-
-// app/layout.tsx
-export default function RootLayout({ children }) {
-  return (
-    <html>
-      <body>
-        <HazoAuthThemeProvider theme={preset_indigo_sunset}>
-          {children}
-        </HazoAuthThemeProvider>
-      </body>
-    </html>
-  );
-}
-```
-
-`preset_neutral` is the default look (slate-700 palette, centered layout). Auth pages render acceptably with no theme configuration at all.
-
-### Option 2: Customize a preset
-
-```tsx
-import { createTheme, HazoAuthThemeProvider } from "hazo_auth/theme";
-import { preset_indigo_sunset } from "hazo_auth/themes";
-
-const theme = createTheme({
-  ...preset_indigo_sunset,
-  brandPanel: { logoSrc: "/logo.svg", tagline: "Welcome." },
-});
-
-<HazoAuthThemeProvider theme={theme}>{children}</HazoAuthThemeProvider>
-```
-
-### Option 3: Build from scratch
-
-```tsx
-import { createTheme, HazoAuthThemeProvider } from "hazo_auth/theme";
-
-const theme = createTheme({
-  colors: { primary: "#2563EB", primaryForeground: "#ffffff" },
-  layout: "split",
-  brandPanel: {
-    logoSrc: "/logo.svg",
-    tagline: "Welcome to MyApp.",
-    backgroundGradient: "linear-gradient(135deg, #2563EB, #7C3AED)",
-  },
-});
-
-<HazoAuthThemeProvider theme={theme}>{children}</HazoAuthThemeProvider>
-```
-
-**Note:** `preset_indigo_sunset` uses `var(--font-display)` and `var(--font-body)`. Wire these in `app/layout.tsx` using `next/font`. See [MIGRATION.md §3](./MIGRATION.md).
-
----
-
-## Cookie Consent (v7.0.0+)
-
-```tsx
-import { CookieConsentBanner } from "hazo_auth/consent";
-
-// In your root layout or a page:
-<CookieConsentBanner />
-
-// With GTM:
-<CookieConsentBanner enableGTM gtmContainerId="GTM-XXXX" />
-```
-
-Read consent server-side:
-
-```tsx
-import { read_consent } from "hazo_auth/consent";
-
-export async function GET(request: NextRequest) {
-  const consent = read_consent(request.headers);
-  if (consent.analytics) {
-    // Track event
-  }
-}
-```
-
-Use the `useConsent` hook client-side:
-
-```tsx
-"use client";
-import { useConsent } from "hazo_auth/consent";
-
-export function MyComponent() {
-  const { analytics, marketing } = useConsent();
-  // Syncs across tabs via custom event
-}
-```
-
----
-
-## Strings & Text Overrides (v7.0.0+)
-
-INI text keys (`title`, `subtitle`, `cta_text`, `legal_text`) are removed in v7. Use `<HazoAuthStringsProvider>` or per-page props instead.
-
-### Global overrides (app/layout.tsx)
-
-```tsx
-import { HazoAuthStringsProvider } from "hazo_auth/strings";
-
-<HazoAuthStringsProvider strings={{ login: { title: "Sign in to MyApp" } }}>
-  {children}
-</HazoAuthStringsProvider>
-```
-
-### Per-page overrides
-
-```tsx
-<LoginPage title="Sign in to MyApp" subtitle="Access your workspace" />
-<RegisterPage title="Create your account" ctaText="Get started" />
-```
-
-`DEFAULT_STRINGS` is exported from `hazo_auth/strings` for reference.
-
----
-
 ## Configuration Setup
 
 After installing the package, you need to set up configuration files in your project root:
@@ -1947,7 +1678,7 @@ export async function proxy(request: NextRequest) {
 
 #### `hazo_get_tenant_auth` (Recommended for Multi-Tenant Apps)
 
-**New:** Tenant-aware authentication function that extracts scope context from request headers or cookies and returns enriched result including the currently selected scope.
+**New:** Tenant-aware authentication function that extracts scope context from request headers or cookies and returns enriched result with organization information.
 
 **Location:** `src/lib/auth/hazo_get_tenant_auth.server.ts`
 
@@ -1981,9 +1712,8 @@ type TenantAuthResult =
       permissions: string[];
       permission_ok: boolean;
       missing_permissions?: string[];
-      selected_scope: SelectedScope | null;     // Currently selected tenant/scope
-      selected_scope_id: string | null;         // Shorthand for selected_scope?.id
-      user_scopes: ScopeDetails[];              // All user's scopes for switching
+      organization: TenantOrganization | null;  // NEW: Tenant context
+      user_scopes: ScopeDetails[];              // NEW: All user's scopes for switching
       scope_ok: boolean;
     }
   | {
@@ -1991,13 +1721,12 @@ type TenantAuthResult =
       user: null;
       permissions: [];
       permission_ok: false;
-      selected_scope: null;
-      selected_scope_id: null;
+      organization: null;
       user_scopes: [];
       scope_ok: false;
     };
 
-type SelectedScope = {
+type TenantOrganization = {
   id: string;
   name: string;
   slug: string | null;          // URL-friendly identifier
@@ -2039,10 +1768,10 @@ export async function GET(request: NextRequest) {
     return NextResponse.json({ error: "Authentication required" }, { status: 401 });
   }
 
-  if (!auth.selected_scope) {
+  if (!auth.organization) {
     return NextResponse.json(
       {
-        error: "No tenant scope context",
+        error: "No organization context",
         available_scopes: auth.user_scopes.map(s => ({ id: s.id, name: s.name }))
       },
       { status: 403 }
@@ -2050,10 +1779,10 @@ export async function GET(request: NextRequest) {
   }
 
   // Access tenant-specific data
-  const data = await getTenantData(auth.selected_scope.id);
+  const data = await getTenantData(auth.organization.id);
 
   return NextResponse.json({
-    selected_scope: auth.selected_scope,
+    organization: auth.organization,
     data,
     // Include available scopes for UI scope switcher
     available_scopes: auth.user_scopes,
@@ -2071,8 +1800,8 @@ export async function GET(request: NextRequest) {
       required_permissions: ["view_reports"],
     });
 
-    // auth.selected_scope is guaranteed non-null here
-    const reports = await getReports(auth.selected_scope.id);
+    // auth.organization is guaranteed non-null here
+    const reports = await getReports(auth.organization.id);
     return NextResponse.json({ reports });
   } catch (error) {
     if (error instanceof HazoAuthError) {
@@ -2122,16 +1851,16 @@ Helper function that wraps `hazo_get_tenant_auth` and throws typed errors for co
 - `TenantRequiredError` (403) - No tenant context in request
 - `TenantAccessDeniedError` (403) - User lacks access to requested tenant
 
-**Returns:** `RequiredTenantAuthResult` with guaranteed non-null `selected_scope`
+**Returns:** `RequiredTenantAuthResult` with guaranteed non-null `organization`
 
 **Example:**
 ```typescript
 export async function GET(request: NextRequest) {
   try {
-    // selected_scope is guaranteed to exist
-    const { selected_scope, user, permissions } = await require_tenant_auth(request);
+    // organization is guaranteed to exist
+    const { organization, user, permissions } = await require_tenant_auth(request);
 
-    const data = await getData(selected_scope.id);
+    const data = await getData(organization.id);
     return NextResponse.json(data);
   } catch (error) {
     if (error instanceof HazoAuthError) {
@@ -2184,10 +1913,10 @@ export const DELETE = withAuth<{ id: string }>(
   { required_permissions: ["admin_system"] }
 );
 
-// With tenant requirement (auth.selected_scope guaranteed non-null)
+// With tenant requirement (auth.organization guaranteed non-null)
 export const GET = withAuth<{ id: string }>(
   async (request, auth, { id }) => {
-    const data = await getData(auth.selected_scope.id, id);
+    const data = await getData(auth.organization.id, id);
     return NextResponse.json(data);
   },
   { require_tenant: true }
@@ -3283,3 +3012,51 @@ The `package.json` exports field defines the public API:
 - Use `npx shadcn@latest add <component>` to scaffold new UI primitives.
 - Centralize configurable values through `hazo_config`.
 - Access backend resources exclusively via `hazo_connect`.
+
+## Email OTP sign-in
+
+```tsx
+// app/(auth)/otp/page.tsx
+import { OTPPage } from "hazo_auth/pages/otp";
+export default function Page(props) { return <OTPPage {...props} />; }
+```
+
+Enable in config: `[hazo_auth__otp] enable_email_otp = true`. Run `npx hazo_auth migrate migrations/015_email_otp.sql`.
+
+## Theming
+
+```tsx
+import { HazoAuthThemeProvider, createTheme } from "hazo_auth/theme";
+
+const my_theme = createTheme({
+  colors: { primary: "#1D4ED8" },
+  layout: "split",
+  brandPanel: { logoSrc: "/logo.svg", tagline: "Welcome." },
+});
+
+<HazoAuthThemeProvider theme={my_theme}>
+  <LoginPage />
+</HazoAuthThemeProvider>
+```
+
+Theme is auth-page scoped. Does not affect `:root`.
+
+## Cookie Consent
+
+```tsx
+import { CookieConsentBanner } from "hazo_auth/consent";
+// Place in your root layout:
+<CookieConsentBanner />
+```
+
+Server-side consent check: `GET /api/hazo_auth/consent/me` returns `ConsentState`.
+
+## String overrides
+
+```tsx
+import { HazoAuthStringsProvider } from "hazo_auth/strings";
+
+<HazoAuthStringsProvider strings={{ login: { title: "Welcome back" } }}>
+  <LoginPage />
+</HazoAuthStringsProvider>
+```