hazo_auth 7.0.1 → 7.0.2

package/SETUP_CHECKLIST.md

@@ -958,7 +958,27 @@ CREATE UNIQUE INDEX IF NOT EXISTS idx_hazo_users_google_id_unique ON hazo_users(
 CREATE INDEX IF NOT EXISTS idx_hazo_users_google_id ON hazo_users(google_id);
 ```
 
-### Step 3.2.4: Configure OAuth in hazo_auth_config.ini
+### Step 3.2.4 (Optional): Run Email OTP Migration
+
+Required only if you plan to enable `enable_email_otp = true` in `[hazo_auth__otp]`.
+
+```bash
+npx hazo_auth migrate migrations/015_email_otp.sql
+```
+
+Creates `hazo_email_otps` table for OTP codes and rate limiting.
+
+### Step 3.2.4b (Optional): Run Facebook OAuth Migration
+
+Required only if `enable_facebook_oauth = true` in `[hazo_auth__oauth]`.
+
+```bash
+npx hazo_auth migrate migrations/016_add_facebook_id_to_hazo_users.sql
+```
+
+Adds `facebook_id` column to `hazo_users`.
+
+### Step 3.2.5: Configure OAuth in hazo_auth_config.ini
 
 Add (or modify) the OAuth section:
 
@@ -1443,246 +1463,6 @@ export { POST } from "hazo_auth/server/routes/pin_login";
 
 ---
 
-## Phase 5.3: Email-OTP Sign-in Setup (Optional)
-
-Email-OTP sign-in lets users authenticate with a 6-digit code sent to their email — no password or Google OAuth required. Skip this phase if your app uses only password or OAuth authentication.
-
-### Step 5.3.1: Apply the OTP migration
-
-```bash
-npm run migrate migrations/015_email_otp.sql
-```
-
-This creates the `hazo_email_otps` table (stores hashed codes with expiry).
-
-**Verify the table exists:**
-```bash
-sqlite3 data/hazo_auth.sqlite ".tables" | tr ' ' '\n' | grep hazo_email_otps
-# Expected: hazo_email_otps
-```
-
-### Step 5.3.2: Add OTP config section
-
-Add to `config/hazo_auth_config.ini`:
-
-```ini
-[hazo_auth__otp]
-# Whether OTP sign-in is enabled
-enabled = true
-
-# Auto-register unknown emails on first successful verify (default: false)
-otp_auto_register = false
-
-# Code expiry in minutes (default: 10)
-code_expiry_minutes = 10
-```
-
-### Step 5.3.3: Create OTP API routes
-
-```bash
-npx hazo_auth generate-routes
-```
-
-Or manually:
-
-`app/api/hazo_auth/otp/request/route.ts`:
-```typescript
-export { otpRequestPOST as POST } from "hazo_auth/server/routes";
-```
-
-`app/api/hazo_auth/otp/verify/route.ts`:
-```typescript
-export { otpVerifyPOST as POST } from "hazo_auth/server/routes";
-```
-
-### Step 5.3.4: Create the OTP sign-in page
-
-`app/hazo_auth/otp/page.tsx`:
-```typescript
-export { default } from "hazo_auth/pages/otp";
-```
-
-### Step 5.3.5: Add OTP routes to middleware/proxy public_routes (REQUIRED)
-
-**This step is critical.** Unauthenticated users arrive at the OTP sign-in page before they have auth cookies. If the OTP routes are not in `public_routes`, your middleware will redirect them to `/login` in a loop.
-
-Edit your `middleware.ts` or `proxy.ts`:
-
-```typescript
-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
-];
-```
-
-### Step 5.3.6: Install optional peer dep (if using OTPVerifyForm)
-
-If you render `<OTPVerifyForm/>` directly (rather than using the zero-config page), install:
-
-```bash
-npm install input-otp
-```
-
-**OTP Setup Checklist:**
-- [ ] `hazo_email_otps` table created (`npm run migrate migrations/015_email_otp.sql`)
-- [ ] `[hazo_auth__otp]` section added to `hazo_auth_config.ini`
-- [ ] OTP API routes created (`/api/hazo_auth/otp/request` and `/api/hazo_auth/otp/verify`)
-- [ ] OTP page created (`/hazo_auth/otp`)
-- [ ] `/hazo_auth/otp` and `/api/hazo_auth/otp` added to middleware `public_routes`
-- [ ] `input-otp` installed (only if using `<OTPVerifyForm/>` directly)
-- [ ] Email delivery configured (`hazo_notify` + valid `ZEPTOMAIL_API_KEY`)
-
----
-
-## Phase 5.4: Theme Setup (v7.0.0+)
-
-### Step 5.4.1: Mount HazoAuthThemeProvider (Required for themed auth pages)
-
-Mount `<HazoAuthThemeProvider>` in `app/layout.tsx`. Use `preset_neutral` for the default look, or configure a custom theme.
-
-**Option A: Default look (no config needed)**
-```tsx
-import { HazoAuthThemeProvider } from "hazo_auth/theme";
-import { preset_neutral } from "hazo_auth/themes";
-
-export default function RootLayout({ children }) {
-  return (
-    <html>
-      <body>
-        <HazoAuthThemeProvider theme={preset_neutral}>
-          {children}
-        </HazoAuthThemeProvider>
-      </body>
-    </html>
-  );
-}
-```
-
-**Option B: Custom theme**
-```tsx
-import { createTheme, HazoAuthThemeProvider } from "hazo_auth/theme";
-
-const theme = createTheme({
-  colors: { primary: "#2563EB" },
-  layout: "split",
-  brandPanel: { logoSrc: "/logo.svg", tagline: "Welcome." },
-});
-
-<HazoAuthThemeProvider theme={theme}>{children}</HazoAuthThemeProvider>
-```
-
-**If using `preset_indigo_sunset` (custom fonts required):**
-
-Wire `next/font` in `app/layout.tsx` to expose `--font-display` and `--font-body` CSS variables. See [MIGRATION.md §3](./MIGRATION.md).
-
-```tsx
-import { Crimson_Pro, DM_Sans } from "next/font/google";
-const display = Crimson_Pro({ subsets: ["latin"], variable: "--font-display" });
-const body = DM_Sans({ subsets: ["latin"], variable: "--font-body" });
-
-export default function Layout({ children }) {
-  return <html className={`${display.variable} ${body.variable}`}>{children}</html>;
-}
-```
-
-**Checklist:**
-- [ ] `<HazoAuthThemeProvider>` mounted in `app/layout.tsx`
-- [ ] Preset or custom theme configured
-- [ ] If using `preset_indigo_sunset`: `next/font` wired for `--font-display` and `--font-body`
-
----
-
-## Phase 5.5: Facebook OAuth Setup (Optional, v7.0.0+)
-
-### Step 5.5.1: Get Facebook App credentials
-
-1. Go to [Meta Developers](https://developers.facebook.com/)
-2. Create or select an app
-3. Add the **Facebook Login** product
-4. Set authorized redirect URIs: `http://localhost:3000/api/auth/callback/facebook` (dev) and your production URL
-5. Copy **App ID** and **App Secret**
-
-### Step 5.5.2: Add Facebook OAuth environment variables
-
-Add to your `.env.local`:
-```env
-HAZO_AUTH_FACEBOOK_APP_ID=your_app_id
-HAZO_AUTH_FACEBOOK_APP_SECRET=your_app_secret
-```
-
-The Facebook sign-in button is hidden when these vars are not set.
-
-### Step 5.5.3: Enable Facebook in config
-
-Add to `config/hazo_auth_config.ini`:
-```ini
-[hazo_auth__oauth]
-enable_facebook = true
-
-; Facebook: default false — stricter security posture
-; Set true only if you want to auto-link to unverified email accounts
-auto_link_unverified_accounts_facebook = false
-```
-
-### Step 5.5.4: Apply Facebook migration
-
-```bash
-npm run migrate migrations/016_facebook_oauth.sql
-```
-
-### Step 5.5.5: Create Facebook OAuth callback route
-
-```typescript
-// app/api/hazo_auth/oauth/facebook/callback/route.ts
-export { GET } from "hazo_auth/server/routes/oauth_facebook_callback";
-```
-
-**Facebook OAuth Checklist:**
-- [ ] Facebook App credentials obtained
-- [ ] `HAZO_AUTH_FACEBOOK_APP_ID` and `HAZO_AUTH_FACEBOOK_APP_SECRET` set in `.env.local`
-- [ ] `enable_facebook = true` in `[hazo_auth__oauth]`
-- [ ] Migration `016_facebook_oauth.sql` applied
-- [ ] Facebook callback route created
-
----
-
-## Phase 5.6: Cookie Consent Setup (Optional, v7.0.0+)
-
-### Step 5.6.1: Mount CookieConsentBanner
-
-Mount `<CookieConsentBanner>` in your root layout:
-
-```tsx
-import { CookieConsentBanner } from "hazo_auth/consent";
-
-export default function RootLayout({ children }) {
-  return (
-    <html>
-      <body>
-        <HazoAuthThemeProvider theme={preset_neutral}>
-          {children}
-          <CookieConsentBanner />
-        </HazoAuthThemeProvider>
-      </body>
-    </html>
-  );
-}
-```
-
-**With GTM (optional):**
-```tsx
-<CookieConsentBanner enableGTM gtmContainerId="GTM-XXXX" />
-```
-
-See the README [Cookie Consent](#cookie-consent-v700) section for server-side `read_consent` usage.
-
-**Checklist:**
-- [ ] `<CookieConsentBanner>` mounted in root layout
-- [ ] GTM container ID configured (if using GTM)
-
----
-
 ## Phase 6: Verification Tests
 
 Run these tests to verify your setup is working correctly.
@@ -2164,10 +1944,10 @@ import { hazo_get_tenant_auth } from "hazo_auth/server-lib";
 export async function GET(request: NextRequest) {
   const auth = await hazo_get_tenant_auth(request);
 
-  if (auth.authenticated && auth.selected_scope) {
-    // auth.selected_scope contains the currently selected tenant/scope
+  if (auth.authenticated && auth.organization) {
+    // auth.organization contains tenant details
     // auth.user_scopes contains all scopes user can access (for UI switcher)
-    const data = await getTenantData(auth.selected_scope.id);
+    const data = await getTenantData(auth.organization.id);
   }
 }
 ```
@@ -2179,8 +1959,8 @@ import { require_tenant_auth, HazoAuthError } from "hazo_auth/server-lib";
 export async function GET(request: NextRequest) {
   try {
     const auth = await require_tenant_auth(request);
-    // auth.selected_scope is guaranteed non-null
-    return NextResponse.json(await getData(auth.selected_scope.id));
+    // auth.organization is guaranteed non-null
+    return NextResponse.json(await getData(auth.organization.id));
   } catch (error) {
     if (error instanceof HazoAuthError) {
       return NextResponse.json(
@@ -2200,7 +1980,7 @@ import { withAuth } from "hazo_auth/server-lib";
 // Auth + params + error handling all automatic
 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 }
@@ -2249,7 +2029,7 @@ const auth = await hazo_get_tenant_auth(request);
 
 // Return available scopes to frontend
 return NextResponse.json({
-  current_scope: auth.selected_scope,
+  current_scope: auth.organization,
   available_scopes: auth.user_scopes.map(s => ({
     id: s.id,
     name: s.name,

package/cli-src/cli/generate.ts

@@ -127,20 +127,11 @@ ${exports}
 }
 
 function generate_page_content(page: PageDefinition): string {
-  // Next 16 requires page default exports to satisfy `PageProps` (i.e. accept
-  // `{ params?, searchParams? }` and nothing else). Re-exporting the named
-  // component directly fails that check because the component carries custom
-  // props (image_src, layout, …). The wrapper below is a parameter-less
-  // function that returns the component — Next sees a `() => JSX` signature
-  // which trivially satisfies PageProps. Direct JSX consumers still use the
-  // named export from `hazo_auth/pages` and get the full custom-prop API.
   return `// Generated by hazo_auth - do not edit manually
 // Page: /${page.path}
 import { ${page.component_name} } from "hazo_auth/pages";
 
-export default function Page() {
-  return <${page.component_name} />;
-}
+export default ${page.component_name};
 `;
 }
 

package/cli-src/cli/validate.ts

@@ -64,9 +64,6 @@ const REQUIRED_API_ROUTES = [
   { path: "api/hazo_auth/user_management/users/roles", method: "GET" },
   { path: "api/hazo_auth/user_management/users/roles", method: "POST" },
   { path: "api/hazo_auth/user_management/users/roles", method: "PUT" },
-  // OTP routes
-  { path: "api/hazo_auth/otp/request", method: "POST" },
-  { path: "api/hazo_auth/otp/verify", method: "POST" },
 ];
 
 // section: helpers
@@ -537,7 +534,6 @@ const REQUIRED_TABLES = [
   "hazo_role_permissions",
   "hazo_invitations",
   "hazo_refresh_tokens",
-  "hazo_email_otps",
 ];
 
 const TEXT_ID_TABLES = [

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

@@ -1,12 +1,4 @@
 // file_description: Type definitions and error classes for hazo_get_auth utility
-//
-// Naming note (v6.0.0): the field previously called `organization` (and
-// `organization_id`) on `TenantAuthResult` was renamed to `selected_scope`
-// (and `selected_scope_id`), and the type `TenantOrganization` was renamed
-// to `SelectedScope`. The multi-tenancy model is scopes throughout; the
-// old name was a legacy synonym for "the currently selected scope" derived
-// from the scope-selection cookie/header. No deprecation shim is provided.
-//
 // section: types
 
 /**
@@ -131,11 +123,10 @@ export type ScopeDetails = {
 };
 
 /**
- * Currently selected scope information returned in tenant auth results.
- * Simplified view of the scope chosen via the scope-selection cookie or
- * `X-Hazo-Scope-Id` header.
+ * Tenant/organization information returned in tenant auth results
+ * Simplified view of scope for API responses
  */
-export type SelectedScope = {
+export type TenantOrganization = {
   id: string;
   name: string;
   slug: string | null;
@@ -176,9 +167,9 @@ export type TenantAuthResult =
       permissions: string[];
       permission_ok: boolean;
       missing_permissions?: string[];
-      selected_scope: SelectedScope | null;
-      /** Shorthand for selected_scope?.id - commonly used for DB query filters. */
-      selected_scope_id: string | null;
+      organization: TenantOrganization | null;
+      /** Shorthand for organization?.id - commonly used for DB query filters */
+      organization_id: string | null;
       user_scopes: ScopeDetails[];
       scope_ok?: boolean;
       scope_access_via?: ScopeAccessInfo;
@@ -188,20 +179,20 @@ export type TenantAuthResult =
       user: null;
       permissions: [];
       permission_ok: false;
-      selected_scope: null;
-      /** Shorthand for selected_scope?.id - commonly used for DB query filters. */
-      selected_scope_id: null;
+      organization: null;
+      /** Shorthand for organization?.id - commonly used for DB query filters */
+      organization_id: null;
       user_scopes: [];
       scope_ok?: false;
     };
 
 /**
- * Guaranteed authenticated result with non-null selected_scope.
- * Returned by require_tenant_auth when validation passes.
+ * Guaranteed authenticated result with non-null organization
+ * Returned by require_tenant_auth when validation passes
  */
 export type RequiredTenantAuthResult = TenantAuthResult & {
   authenticated: true;
-  selected_scope: SelectedScope;
+  organization: TenantOrganization;
 };
 
 // section: tenant_error_classes

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

@@ -14,7 +14,7 @@ import type {
   TenantAuthOptions,
   TenantAuthResult,
   RequiredTenantAuthResult,
-  SelectedScope,
+  TenantOrganization,
   ScopeDetails,
 } from "./auth_types";
 import {
@@ -62,15 +62,15 @@ export function extract_scope_id_from_request(
 }
 
 /**
- * Builds SelectedScope from scope details and access info.
+ * Builds TenantOrganization from scope details and access info
  * @param scope_details - Full scope details from cache
  * @param is_super_admin - Whether user is accessing as super admin
- * @returns SelectedScope object
+ * @returns TenantOrganization object
  */
-function build_selected_scope(
+function build_tenant_organization(
   scope_details: ScopeDetails,
   is_super_admin: boolean,
-): SelectedScope {
+): TenantOrganization {
   return {
     id: scope_details.id,
     name: scope_details.name,
@@ -96,21 +96,20 @@ function build_selected_scope(
  * Tenant-aware authentication function
  *
  * Extracts tenant/scope context from request headers or cookies,
- * validates access, and returns enriched result including the currently
- * selected scope.
+ * validates access, and returns enriched result with organization info.
  *
  * Header priority: X-Hazo-Scope-Id > Cookie
  *
  * @param request - NextRequest object
  * @param options - TenantAuthOptions for customization
- * @returns TenantAuthResult with user, permissions, selected_scope, and user_scopes
+ * @returns TenantAuthResult with user, permissions, organization, and user_scopes
  *
  * @example
  * ```typescript
  * const auth = await hazo_get_tenant_auth(request);
- * if (auth.authenticated && auth.selected_scope) {
+ * if (auth.authenticated && auth.organization) {
  *   // Access tenant-specific data
- *   const data = await getData(auth.selected_scope.id);
+ *   const data = await getData(auth.organization.id);
  * }
  * ```
  */
@@ -137,8 +136,8 @@ export async function hazo_get_tenant_auth(
       user: null,
       permissions: [],
       permission_ok: false,
-      selected_scope: null,
-      selected_scope_id: null,
+      organization: null,
+      organization_id: null,
       user_scopes: [],
       scope_ok: false,
     };
@@ -156,8 +155,8 @@ export async function hazo_get_tenant_auth(
   // User scopes from cache or empty array
   const user_scopes: ScopeDetails[] = cached?.scopes || [];
 
-  // Build selected_scope info if scope access was successful
-  let selected_scope: SelectedScope | null = null;
+  // Build organization info if scope access was successful
+  let organization: TenantOrganization | null = null;
 
   if (scope_id && auth_result.scope_ok && auth_result.scope_access_via) {
     // Find the scope in user's scopes that matches the access_via scope
@@ -166,7 +165,7 @@ export async function hazo_get_tenant_auth(
     );
 
     if (access_scope) {
-      selected_scope = build_selected_scope(
+      organization = build_tenant_organization(
         access_scope,
         auth_result.scope_access_via.is_super_admin || false,
       );
@@ -175,7 +174,7 @@ export async function hazo_get_tenant_auth(
       const hazoConnect = get_hazo_connect_instance();
       const scope_result = await get_scope_by_id(hazoConnect, scope_id);
       if (scope_result.success && scope_result.scope) {
-        selected_scope = {
+        organization = {
           id: scope_result.scope.id,
           name: scope_result.scope.name,
           slug: null, // Could fetch from scope if slug column exists
@@ -201,8 +200,8 @@ export async function hazo_get_tenant_auth(
     permissions: auth_result.permissions,
     permission_ok: auth_result.permission_ok,
     missing_permissions: auth_result.missing_permissions,
-    selected_scope,
-    selected_scope_id: selected_scope?.id || null,
+    organization,
+    organization_id: organization?.id || null,
     user_scopes,
     scope_ok: auth_result.scope_ok,
     scope_access_via: auth_result.scope_access_via,
@@ -219,15 +218,15 @@ export async function hazo_get_tenant_auth(
  *
  * @param request - NextRequest object
  * @param options - TenantAuthOptions for customization
- * @returns RequiredTenantAuthResult with guaranteed non-null selected_scope
+ * @returns RequiredTenantAuthResult with guaranteed non-null organization
  * @throws AuthenticationRequiredError, TenantRequiredError, TenantAccessDeniedError
  *
  * @example
  * ```typescript
  * try {
  *   const auth = await require_tenant_auth(request);
- *   // auth.selected_scope is guaranteed non-null here
- *   const data = await getData(auth.selected_scope.id);
+ *   // auth.organization is guaranteed non-null here
+ *   const data = await getData(auth.organization.id);
  * } catch (error) {
  *   if (error instanceof HazoAuthError) {
  *     return NextResponse.json(
@@ -258,14 +257,14 @@ export async function require_tenant_auth(
     throw new TenantAccessDeniedError(scope_id, result.user_scopes);
   }
 
-  // Check if scope context is required but missing
-  if (!result.selected_scope) {
+  // Check if organization context is required but missing
+  if (!result.organization) {
     throw new TenantRequiredError(
-      "No tenant scope context provided. Include X-Hazo-Scope-Id header or scope cookie.",
+      "No organization context provided. Include X-Hazo-Scope-Id header or scope cookie.",
       result.user_scopes,
     );
   }
 
-  // Type assertion: at this point we know selected_scope is non-null
+  // Type assertion: at this point we know organization is non-null
   return result as RequiredTenantAuthResult;
 }

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

@@ -22,7 +22,7 @@ export {
 } from "./hazo_get_tenant_auth.server.js";
 export type {
   ScopeDetails,
-  SelectedScope,
+  TenantOrganization,
   TenantAuthOptions,
   TenantAuthResult,
   RequiredTenantAuthResult,
@@ -50,7 +50,7 @@ export {
 } from "./with_auth.server.js";
 export type {
   AuthenticatedTenantAuth,
-  AuthenticatedTenantAuthWithSelectedScope,
+  AuthenticatedTenantAuthWithOrg,
   WithAuthOptions,
 } from "./with_auth.server";