hazo_auth 5.3.1 → 6.1.1

package/README.md

@@ -2,6 +2,154 @@
 
 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 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 });
+}
+
+// AFTER (v6.0)
+import { hazo_get_tenant_auth } from "hazo_auth/server-lib";
+import type { SelectedScope } from "hazo_auth";
+
+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.
+```
+
+> ⚠️ 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).
@@ -1644,7 +1792,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 with organization information.
+**New:** Tenant-aware authentication function that extracts scope context from request headers or cookies and returns enriched result including the currently selected scope.
 
 **Location:** `src/lib/auth/hazo_get_tenant_auth.server.ts`
 
@@ -1678,8 +1826,9 @@ type TenantAuthResult =
       permissions: string[];
       permission_ok: boolean;
       missing_permissions?: string[];
-      organization: TenantOrganization | null;  // NEW: Tenant context
-      user_scopes: ScopeDetails[];              // NEW: All user's scopes for switching
+      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
       scope_ok: boolean;
     }
   | {
@@ -1687,12 +1836,13 @@ type TenantAuthResult =
       user: null;
       permissions: [];
       permission_ok: false;
-      organization: null;
+      selected_scope: null;
+      selected_scope_id: null;
       user_scopes: [];
       scope_ok: false;
     };
 
-type TenantOrganization = {
+type SelectedScope = {
   id: string;
   name: string;
   slug: string | null;          // URL-friendly identifier
@@ -1734,10 +1884,10 @@ export async function GET(request: NextRequest) {
     return NextResponse.json({ error: "Authentication required" }, { status: 401 });
   }
 
-  if (!auth.organization) {
+  if (!auth.selected_scope) {
     return NextResponse.json(
       {
-        error: "No organization context",
+        error: "No tenant scope context",
         available_scopes: auth.user_scopes.map(s => ({ id: s.id, name: s.name }))
       },
       { status: 403 }
@@ -1745,10 +1895,10 @@ export async function GET(request: NextRequest) {
   }
 
   // Access tenant-specific data
-  const data = await getTenantData(auth.organization.id);
+  const data = await getTenantData(auth.selected_scope.id);
 
   return NextResponse.json({
-    organization: auth.organization,
+    selected_scope: auth.selected_scope,
     data,
     // Include available scopes for UI scope switcher
     available_scopes: auth.user_scopes,
@@ -1766,8 +1916,8 @@ export async function GET(request: NextRequest) {
       required_permissions: ["view_reports"],
     });
 
-    // auth.organization is guaranteed non-null here
-    const reports = await getReports(auth.organization.id);
+    // auth.selected_scope is guaranteed non-null here
+    const reports = await getReports(auth.selected_scope.id);
     return NextResponse.json({ reports });
   } catch (error) {
     if (error instanceof HazoAuthError) {
@@ -1817,16 +1967,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 `organization`
+**Returns:** `RequiredTenantAuthResult` with guaranteed non-null `selected_scope`
 
 **Example:**
 ```typescript
 export async function GET(request: NextRequest) {
   try {
-    // organization is guaranteed to exist
-    const { organization, user, permissions } = await require_tenant_auth(request);
+    // selected_scope is guaranteed to exist
+    const { selected_scope, user, permissions } = await require_tenant_auth(request);
 
-    const data = await getData(organization.id);
+    const data = await getData(selected_scope.id);
     return NextResponse.json(data);
   } catch (error) {
     if (error instanceof HazoAuthError) {
@@ -1879,10 +2029,10 @@ export const DELETE = withAuth<{ id: string }>(
   { required_permissions: ["admin_system"] }
 );
 
-// With tenant requirement (auth.organization guaranteed non-null)
+// With tenant requirement (auth.selected_scope guaranteed non-null)
 export const GET = withAuth<{ id: string }>(
   async (request, auth, { id }) => {
-    const data = await getData(auth.organization.id, id);
+    const data = await getData(auth.selected_scope.id, id);
     return NextResponse.json(data);
   },
   { require_tenant: true }

package/SETUP_CHECKLIST.md

@@ -1443,6 +1443,98 @@ 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 6: Verification Tests
 
 Run these tests to verify your setup is working correctly.
@@ -1924,10 +2016,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.organization) {
-    // auth.organization contains tenant details
+  if (auth.authenticated && auth.selected_scope) {
+    // auth.selected_scope contains the currently selected tenant/scope
     // auth.user_scopes contains all scopes user can access (for UI switcher)
-    const data = await getTenantData(auth.organization.id);
+    const data = await getTenantData(auth.selected_scope.id);
   }
 }
 ```
@@ -1939,8 +2031,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.organization is guaranteed non-null
-    return NextResponse.json(await getData(auth.organization.id));
+    // auth.selected_scope is guaranteed non-null
+    return NextResponse.json(await getData(auth.selected_scope.id));
   } catch (error) {
     if (error instanceof HazoAuthError) {
       return NextResponse.json(
@@ -1960,7 +2052,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.organization.id, id);
+    const data = await getData(auth.selected_scope.id, id);
     return NextResponse.json(data);
   },
   { require_tenant: true }
@@ -2009,7 +2101,7 @@ const auth = await hazo_get_tenant_auth(request);
 
 // Return available scopes to frontend
 return NextResponse.json({
-  current_scope: auth.organization,
+  current_scope: auth.selected_scope,
   available_scopes: auth.user_scopes.map(s => ({
     id: s.id,
     name: s.name,

package/cli-src/cli/generate.ts

@@ -127,11 +127,20 @@ ${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 ${page.component_name};
+export default function Page() {
+  return <${page.component_name} />;
+}
 `;
 }
 

package/cli-src/cli/validate.ts

@@ -64,6 +64,9 @@ 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
@@ -534,6 +537,7 @@ 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,4 +1,12 @@
 // 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
 
 /**
@@ -123,10 +131,11 @@ export type ScopeDetails = {
 };
 
 /**
- * Tenant/organization information returned in tenant auth results
- * Simplified view of scope for API responses
+ * 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.
  */
-export type TenantOrganization = {
+export type SelectedScope = {
   id: string;
   name: string;
   slug: string | null;
@@ -167,9 +176,9 @@ export type TenantAuthResult =
       permissions: string[];
       permission_ok: boolean;
       missing_permissions?: string[];
-      organization: TenantOrganization | null;
-      /** Shorthand for organization?.id - commonly used for DB query filters */
-      organization_id: string | null;
+      selected_scope: SelectedScope | null;
+      /** Shorthand for selected_scope?.id - commonly used for DB query filters. */
+      selected_scope_id: string | null;
       user_scopes: ScopeDetails[];
       scope_ok?: boolean;
       scope_access_via?: ScopeAccessInfo;
@@ -179,20 +188,20 @@ export type TenantAuthResult =
       user: null;
       permissions: [];
       permission_ok: false;
-      organization: null;
-      /** Shorthand for organization?.id - commonly used for DB query filters */
-      organization_id: null;
+      selected_scope: null;
+      /** Shorthand for selected_scope?.id - commonly used for DB query filters. */
+      selected_scope_id: null;
       user_scopes: [];
       scope_ok?: false;
     };
 
 /**
- * Guaranteed authenticated result with non-null organization
- * Returned by require_tenant_auth when validation passes
+ * Guaranteed authenticated result with non-null selected_scope.
+ * Returned by require_tenant_auth when validation passes.
  */
 export type RequiredTenantAuthResult = TenantAuthResult & {
   authenticated: true;
-  organization: TenantOrganization;
+  selected_scope: SelectedScope;
 };
 
 // section: tenant_error_classes

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

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