hazo_auth 5.1.10 → 5.1.12

package/README.md

@@ -1296,7 +1296,13 @@ export default function Page() {
 
 ## Authentication Service
 
-The `hazo_auth` package provides a comprehensive authentication and authorization system with role-based access control (RBAC). The main authentication utility is `hazo_get_auth`, which provides user details, permissions, and permission checking with built-in caching and rate limiting.
+The `hazo_auth` package provides a comprehensive authentication and authorization system with role-based access control (RBAC). The main authentication utilities are:
+
+- **`hazo_get_auth`** - Standard authentication with user details, permissions, and caching
+- **`hazo_get_tenant_auth`** - Tenant-aware authentication that extracts scope context from request headers or cookies
+- **`require_tenant_auth`** - Strict tenant authentication with typed error handling
+
+These utilities provide user details, permissions, and permission checking with built-in caching and rate limiting.
 
 ### Client-Side API Endpoint (Recommended)
 
@@ -1461,7 +1467,205 @@ export async function proxy(request: NextRequest) {
 
 ### Server-Side Functions
 
-#### `hazo_get_auth` (Recommended)
+#### `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.
+
+**Location:** `src/lib/auth/hazo_get_tenant_auth.server.ts`
+
+**Scope Context Extraction:**
+- **Header (priority):** `X-Hazo-Scope-Id` (configurable via `scope_header_name`)
+- **Cookie (fallback):** `hazo_auth_scope_id` (with prefix if configured)
+
+**Function Signature:**
+```typescript
+import { hazo_get_tenant_auth } from "hazo_auth";
+import type { TenantAuthResult, TenantAuthOptions } from "hazo_auth";
+
+async function hazo_get_tenant_auth(
+  request: NextRequest,
+  options?: TenantAuthOptions
+): Promise<TenantAuthResult>
+```
+
+**Options:**
+- `required_permissions?: string[]` - Array of permission names to check
+- `strict?: boolean` - If `true`, throws errors when checks fail (default: `false`)
+- `scope_header_name?: string` - Custom header name for scope ID (default: `"X-Hazo-Scope-Id"`)
+- `scope_cookie_name?: string` - Custom cookie name for scope ID (default: `"hazo_auth_scope_id"`)
+
+**Return Type:**
+```typescript
+type TenantAuthResult =
+  | {
+      authenticated: true;
+      user: HazoAuthUser;
+      permissions: string[];
+      permission_ok: boolean;
+      missing_permissions?: string[];
+      organization: TenantOrganization | null;  // NEW: Tenant context
+      user_scopes: ScopeDetails[];              // NEW: All user's scopes for switching
+      scope_ok: boolean;
+    }
+  | {
+      authenticated: false;
+      user: null;
+      permissions: [];
+      permission_ok: false;
+      organization: null;
+      user_scopes: [];
+      scope_ok: false;
+    };
+
+type TenantOrganization = {
+  id: string;
+  name: string;
+  slug: string | null;          // URL-friendly identifier
+  level: string;                // "Company", "Division", etc.
+  role_id: string;              // User's role in this scope
+  is_super_admin: boolean;
+  branding?: {
+    logo_url: string | null;
+    primary_color: string | null;
+    secondary_color: string | null;
+    tagline: string | null;
+  };
+};
+
+type ScopeDetails = {
+  id: string;
+  name: string;
+  slug: string | null;
+  level: string;
+  parent_id: string | null;
+  role_id: string;
+  logo_url: string | null;
+  primary_color: string | null;
+  secondary_color: string | null;
+  tagline: string | null;
+};
+```
+
+**Basic Usage Example:**
+```typescript
+// app/api/dashboard/route.ts
+import { NextRequest, NextResponse } from "next/server";
+import { hazo_get_tenant_auth } from "hazo_auth";
+
+export async function GET(request: NextRequest) {
+  const auth = await hazo_get_tenant_auth(request);
+
+  if (!auth.authenticated) {
+    return NextResponse.json({ error: "Authentication required" }, { status: 401 });
+  }
+
+  if (!auth.organization) {
+    return NextResponse.json(
+      {
+        error: "No organization context",
+        available_scopes: auth.user_scopes.map(s => ({ id: s.id, name: s.name }))
+      },
+      { status: 403 }
+    );
+  }
+
+  // Access tenant-specific data
+  const data = await getTenantData(auth.organization.id);
+
+  return NextResponse.json({
+    organization: auth.organization,
+    data,
+    // Include available scopes for UI scope switcher
+    available_scopes: auth.user_scopes,
+  });
+}
+```
+
+**Strict Mode with Error Handling:**
+```typescript
+import { require_tenant_auth, HazoAuthError } from "hazo_auth";
+
+export async function GET(request: NextRequest) {
+  try {
+    const auth = await require_tenant_auth(request, {
+      required_permissions: ["view_reports"],
+    });
+
+    // auth.organization is guaranteed non-null here
+    const reports = await getReports(auth.organization.id);
+    return NextResponse.json({ reports });
+  } catch (error) {
+    if (error instanceof HazoAuthError) {
+      return NextResponse.json(
+        {
+          error: error.message,
+          code: error.code,
+          // For TenantAccessDeniedError, includes available_scopes
+          available_scopes: error.available_scopes
+        },
+        { status: error.status_code }
+      );
+    }
+    throw error;
+  }
+}
+```
+
+**Frontend Integration:**
+```typescript
+// Client sets scope via header or cookie
+const response = await fetch("/api/dashboard", {
+  headers: {
+    "X-Hazo-Scope-Id": selectedScopeId,
+  },
+});
+
+// Or via cookie (set once during scope selection)
+document.cookie = `hazo_auth_scope_id=${selectedScopeId}; path=/`;
+```
+
+**Error Types:**
+```typescript
+import {
+  AuthenticationRequiredError,   // 401 - User not authenticated
+  TenantRequiredError,            // 403 - No tenant context provided
+  TenantAccessDeniedError,        // 403 - User lacks access to tenant
+} from "hazo_auth";
+```
+
+#### `require_tenant_auth` (Strict Tenant Auth)
+
+Helper function that wraps `hazo_get_tenant_auth` and throws typed errors for common failure cases.
+
+**Throws:**
+- `AuthenticationRequiredError` (401) - User not authenticated
+- `TenantRequiredError` (403) - No tenant context in request
+- `TenantAccessDeniedError` (403) - User lacks access to requested tenant
+
+**Returns:** `RequiredTenantAuthResult` with guaranteed non-null `organization`
+
+**Example:**
+```typescript
+export async function GET(request: NextRequest) {
+  try {
+    // organization is guaranteed to exist
+    const { organization, user, permissions } = await require_tenant_auth(request);
+
+    const data = await getData(organization.id);
+    return NextResponse.json(data);
+  } catch (error) {
+    if (error instanceof HazoAuthError) {
+      return NextResponse.json(
+        { error: error.message, code: error.code },
+        { status: error.status_code }
+      );
+    }
+    throw error;
+  }
+}
+```
+
+#### `hazo_get_auth` (Standard Auth)
 
 The primary authentication utility for server-side use in API routes. Returns user details, permissions, and optionally checks required permissions.
 

package/SETUP_CHECKLIST.md

@@ -1658,7 +1658,34 @@ WHERE table_name LIKE 'hazo_scopes_%'
 sqlite3 data/hazo_auth.sqlite ".tables" | grep -E "hazo_scopes|hazo_user_scopes|hazo_scope_labels"
 ```
 
-### Step 7.5: Test HRBAC
+### Step 7.5: Add Slug Column to hazo_scopes (Optional - for Tenant Auth)
+
+If you plan to use tenant-aware authentication with URL-friendly identifiers, add the `slug` column to the `hazo_scopes` table:
+
+```bash
+npm run migrate migrations/012_add_slug_to_hazo_scopes.sql
+```
+
+**Manual Migration (if needed):**
+
+**PostgreSQL:**
+```sql
+ALTER TABLE hazo_scopes ADD COLUMN slug TEXT;
+CREATE INDEX IF NOT EXISTS idx_hazo_scopes_slug ON hazo_scopes(slug);
+```
+
+**SQLite:**
+```sql
+ALTER TABLE hazo_scopes ADD COLUMN slug TEXT;
+CREATE INDEX IF NOT EXISTS idx_hazo_scopes_slug ON hazo_scopes(slug);
+```
+
+**What is slug?**
+- URL-friendly identifier for scopes (e.g., "acme-corp", "sales-division")
+- Enables tenant context via URL paths (e.g., `/org/:slug/dashboard`)
+- Not enforced as unique to allow flexibility
+
+### Step 7.6: Test HRBAC
 
 1. Start your dev server: `npm run dev`
 2. Log in with a user that has `admin_scope_hierarchy_management` permission
@@ -1675,11 +1702,185 @@ sqlite3 data/hazo_auth.sqlite ".tables" | grep -E "hazo_scopes|hazo_user_scopes|
   - [ ] `hazo_scope_labels` (custom labels per org)
 - [ ] Scope ID generator function created (PostgreSQL)
 - [ ] Grants applied (PostgreSQL)
+- [ ] `slug` column added to hazo_scopes (optional, for tenant auth)
 - [ ] HRBAC tabs visible in User Management
 - [ ] Scope test page works
 
 ---
 
+## Phase 8: Tenant-Aware Authentication Setup (Optional)
+
+Tenant-aware authentication adds scope context to authentication results, enabling multi-tenant applications where users can access multiple organizations/scopes.
+
+**Skip this phase if:**
+- Your app doesn't need multi-tenancy
+- Users don't switch between different scopes/organizations
+
+### Step 8.1: Ensure Slug Column Exists
+
+The tenant auth feature uses the `slug` column for URL-friendly scope identifiers. If you didn't complete Step 7.5, do so now:
+
+```bash
+npm run migrate migrations/012_add_slug_to_hazo_scopes.sql
+```
+
+### Step 8.2: Use Tenant Auth in API Routes
+
+Replace `hazo_get_auth` with `hazo_get_tenant_auth` in your API routes:
+
+**Before (standard auth):**
+```typescript
+import { hazo_get_auth } from "hazo_auth";
+
+export async function GET(request: NextRequest) {
+  const auth = await hazo_get_auth(request);
+  // No tenant context
+}
+```
+
+**After (tenant auth):**
+```typescript
+import { hazo_get_tenant_auth } from "hazo_auth";
+
+export async function GET(request: NextRequest) {
+  const auth = await hazo_get_tenant_auth(request);
+
+  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.organization.id);
+  }
+}
+```
+
+**Or use strict mode with error handling:**
+```typescript
+import { require_tenant_auth, HazoAuthError } from "hazo_auth";
+
+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));
+  } catch (error) {
+    if (error instanceof HazoAuthError) {
+      return NextResponse.json(
+        { error: error.message, code: error.code },
+        { status: error.status_code }
+      );
+    }
+    throw error;
+  }
+}
+```
+
+### Step 8.3: Set Scope Context from Frontend
+
+The frontend needs to send the current scope ID via header or cookie.
+
+**Option A: Header (recommended - per-request):**
+```typescript
+const response = await fetch("/api/dashboard", {
+  headers: {
+    "X-Hazo-Scope-Id": selectedScopeId,
+  },
+});
+```
+
+**Option B: Cookie (persistent - set once):**
+```typescript
+// Set cookie when user selects a scope
+document.cookie = `hazo_auth_scope_id=${selectedScopeId}; path=/`;
+
+// Then all requests include the scope automatically
+const response = await fetch("/api/dashboard");
+```
+
+**Custom Configuration (optional):**
+```typescript
+// Use custom header or cookie names
+const auth = await hazo_get_tenant_auth(request, {
+  scope_header_name: "X-Tenant-Id",         // Custom header
+  scope_cookie_name: "my_app_tenant_id",    // Custom cookie
+});
+```
+
+### Step 8.4: Build Scope Switcher UI (Optional)
+
+Use the `user_scopes` array to build a scope switcher dropdown:
+
+```typescript
+const auth = await hazo_get_tenant_auth(request);
+
+// Return available scopes to frontend
+return NextResponse.json({
+  current_scope: auth.organization,
+  available_scopes: auth.user_scopes.map(s => ({
+    id: s.id,
+    name: s.name,
+    slug: s.slug,
+    level: s.level,
+    branding: {
+      logo_url: s.logo_url,
+      primary_color: s.primary_color,
+    },
+  })),
+});
+```
+
+**Frontend Scope Switcher:**
+```tsx
+function ScopeSwitcher({ scopes, currentScopeId }) {
+  const handleScopeChange = (scopeId: string) => {
+    // Option 1: Set cookie
+    document.cookie = `hazo_auth_scope_id=${scopeId}; path=/`;
+    window.location.reload();
+
+    // Option 2: Update state and send header on all requests
+    setCurrentScope(scopeId);
+  };
+
+  return (
+    <select value={currentScopeId} onChange={e => handleScopeChange(e.target.value)}>
+      {scopes.map(scope => (
+        <option key={scope.id} value={scope.id}>
+          {scope.name} ({scope.level})
+        </option>
+      ))}
+    </select>
+  );
+}
+```
+
+### Step 8.5: Test Tenant Auth
+
+**Test with cURL:**
+```bash
+# No scope context - should return error or empty organization
+curl -H "Cookie: hazo_auth_session=YOUR_TOKEN" \
+  http://localhost:3000/api/dashboard | jq
+
+# With scope context via header
+curl -H "Cookie: hazo_auth_session=YOUR_TOKEN" \
+  -H "X-Hazo-Scope-Id: SCOPE_UUID" \
+  http://localhost:3000/api/dashboard | jq
+
+# With scope context via cookie
+curl -H "Cookie: hazo_auth_session=YOUR_TOKEN; hazo_auth_scope_id=SCOPE_UUID" \
+  http://localhost:3000/api/dashboard | jq
+```
+
+**Tenant Auth Checklist:**
+- [ ] `slug` column added to `hazo_scopes`
+- [ ] API routes updated to use `hazo_get_tenant_auth` or `require_tenant_auth`
+- [ ] Frontend sends scope context via header or cookie
+- [ ] Tenant auth returns organization details when scope is valid
+- [ ] Tenant auth returns user_scopes for building scope switcher
+- [ ] Error handling in place for missing/invalid scope context
+- [ ] Scope switcher UI built (optional but recommended)
+
+---
+
 ## Troubleshooting
 
 ### Issue: Email not sending

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

@@ -1,17 +1,19 @@
 // file_description: LRU cache implementation for hazo_get_auth with TTL and size limits
 // section: imports
-import type { HazoAuthUser } from "./auth_types";
+import type { HazoAuthUser, ScopeDetails } from "./auth_types";
 
 // section: types
 
 /**
  * Cache entry structure
  * v5.x: role_ids are now string UUIDs (from hazo_user_scopes)
+ * v5.2: Added scopes with full details for multi-tenancy support
  */
 type CacheEntry = {
   user: HazoAuthUser;
   permissions: string[];
   role_ids: string[];
+  scopes: ScopeDetails[]; // All user's scope assignments with full details
   timestamp: number; // Unix timestamp in milliseconds
   cache_version: number; // Version number for smart invalidation
 };
@@ -83,12 +85,14 @@ class AuthCache {
    * @param user - User data
    * @param permissions - User permissions
    * @param role_ids - User role IDs (v5.x: string UUIDs)
+   * @param scopes - User scope details with full information (v5.2+)
    */
   set(
     user_id: string,
     user: HazoAuthUser,
     permissions: string[],
     role_ids: string[],
+    scopes: ScopeDetails[] = [],
   ): void {
     // Evict LRU entries if cache is full
     while (this.cache.size >= this.max_size) {
@@ -107,6 +111,7 @@ class AuthCache {
       user,
       permissions,
       role_ids,
+      scopes,
       timestamp: Date.now(),
       cache_version,
     };
@@ -155,6 +160,24 @@ class AuthCache {
     this.cache.clear();
   }
 
+  /**
+   * Invalidates cache entries for users who have access to specific scopes
+   * Used when scope details change (name, branding, etc.)
+   * @param scope_ids - Array of scope IDs to invalidate
+   */
+  invalidate_by_scope_ids(scope_ids: string[]): void {
+    const entries_to_remove: string[] = [];
+    for (const [user_id, entry] of this.cache.entries()) {
+      const has_scope = entry.scopes.some((s) => scope_ids.includes(s.id));
+      if (has_scope) {
+        entries_to_remove.push(user_id);
+      }
+    }
+    for (const user_id of entries_to_remove) {
+      this.cache.delete(user_id);
+    }
+  }
+
   /**
    * Gets the maximum cache version for a set of roles
    * Used to determine if cache entry is stale

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

@@ -100,3 +100,145 @@ export class ScopeAccessError extends Error {
     this.name = "ScopeAccessError";
   }
 }
+
+// section: scope_details_types
+
+/**
+ * Full scope details with branding information
+ * Used in cache and tenant auth results for multi-tenancy support
+ */
+export type ScopeDetails = {
+  id: string;
+  name: string;
+  slug: string | null;
+  level: string;
+  parent_id: string | null;
+  role_id: string;
+  // Branding fields (from hazo_scopes table)
+  logo_url: string | null;
+  primary_color: string | null;
+  secondary_color: string | null;
+  tagline: string | null;
+};
+
+/**
+ * Tenant/organization information returned in tenant auth results
+ * Simplified view of scope for API responses
+ */
+export type TenantOrganization = {
+  id: string;
+  name: string;
+  slug: string | null;
+  level: string;
+  role_id: string;
+  is_super_admin: boolean;
+  branding?: {
+    logo_url: string | null;
+    primary_color: string | null;
+    secondary_color: string | null;
+    tagline: string | null;
+  };
+};
+
+/**
+ * Options for hazo_get_tenant_auth function
+ * Extends HazoAuthOptions with tenant-specific configuration
+ */
+export type TenantAuthOptions = HazoAuthOptions & {
+  /**
+   * Header name to check for scope ID (default: "X-Hazo-Scope-Id")
+   */
+  scope_header_name?: string;
+  /**
+   * Cookie name to check for scope ID (uses cookie prefix if not specified)
+   */
+  scope_cookie_name?: string;
+};
+
+/**
+ * Result type for hazo_get_tenant_auth function
+ * Extends HazoAuthResult with tenant-specific information
+ */
+export type TenantAuthResult =
+  | {
+      authenticated: true;
+      user: HazoAuthUser;
+      permissions: string[];
+      permission_ok: boolean;
+      missing_permissions?: string[];
+      organization: TenantOrganization | null;
+      user_scopes: ScopeDetails[];
+      scope_ok?: boolean;
+      scope_access_via?: ScopeAccessInfo;
+    }
+  | {
+      authenticated: false;
+      user: null;
+      permissions: [];
+      permission_ok: false;
+      organization: null;
+      user_scopes: [];
+      scope_ok?: false;
+    };
+
+/**
+ * Guaranteed authenticated result with non-null organization
+ * Returned by require_tenant_auth when validation passes
+ */
+export type RequiredTenantAuthResult = TenantAuthResult & {
+  authenticated: true;
+  organization: TenantOrganization;
+};
+
+// section: tenant_error_classes
+
+/**
+ * Base error class for all hazo_auth errors
+ * Provides error code and HTTP status code for API responses
+ */
+export class HazoAuthError extends Error {
+  constructor(
+    message: string,
+    public readonly code: string,
+    public readonly status_code: number,
+  ) {
+    super(message);
+    this.name = "HazoAuthError";
+  }
+}
+
+/**
+ * Error thrown when authentication is required but user is not authenticated
+ */
+export class AuthenticationRequiredError extends HazoAuthError {
+  constructor(message: string = "Authentication required") {
+    super(message, "AUTHENTICATION_REQUIRED", 401);
+    this.name = "AuthenticationRequiredError";
+  }
+}
+
+/**
+ * Error thrown when a tenant/scope context is required but not provided
+ */
+export class TenantRequiredError extends HazoAuthError {
+  constructor(
+    message: string = "Tenant context required",
+    public readonly user_scopes: ScopeDetails[] = [],
+  ) {
+    super(message, "TENANT_REQUIRED", 403);
+    this.name = "TenantRequiredError";
+  }
+}
+
+/**
+ * Error thrown when user lacks access to the requested tenant/scope
+ */
+export class TenantAccessDeniedError extends HazoAuthError {
+  constructor(
+    public readonly scope_id: string,
+    public readonly user_scopes: ScopeDetails[] = [],
+  ) {
+    super(`Access denied to scope: ${scope_id}`, "TENANT_ACCESS_DENIED", 403);
+    this.name = "TenantAccessDeniedError";
+  }
+}