hazo_auth 5.1.10 → 5.1.12

package/dist/lib/auth/auth_types.d.ts

@@ -85,4 +85,113 @@ export declare class ScopeAccessError extends Error {
         scope_name?: string;
     }>);
 }
+/**
+ * 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;
+    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;
+};
+/**
+ * Base error class for all hazo_auth errors
+ * Provides error code and HTTP status code for API responses
+ */
+export declare class HazoAuthError extends Error {
+    readonly code: string;
+    readonly status_code: number;
+    constructor(message: string, code: string, status_code: number);
+}
+/**
+ * Error thrown when authentication is required but user is not authenticated
+ */
+export declare class AuthenticationRequiredError extends HazoAuthError {
+    constructor(message?: string);
+}
+/**
+ * Error thrown when a tenant/scope context is required but not provided
+ */
+export declare class TenantRequiredError extends HazoAuthError {
+    readonly user_scopes: ScopeDetails[];
+    constructor(message?: string, user_scopes?: ScopeDetails[]);
+}
+/**
+ * Error thrown when user lacks access to the requested tenant/scope
+ */
+export declare class TenantAccessDeniedError extends HazoAuthError {
+    readonly scope_id: string;
+    readonly user_scopes: ScopeDetails[];
+    constructor(scope_id: string, user_scopes?: ScopeDetails[]);
+}
 //# sourceMappingURL=auth_types.d.ts.map

package/dist/lib/auth/auth_types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth_types.d.ts","sourceRoot":"","sources":["../../../src/lib/auth/auth_types.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,OAAO,CAAC;IACnB,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IAEnC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC/C,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,cAAc,GACtB;IACE,aAAa,EAAE,IAAI,CAAC;IACpB,IAAI,EAAE,YAAY,CAAC;IACnB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,aAAa,EAAE,OAAO,CAAC;IACvB,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAE/B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,gBAAgB,CAAC,EAAE,eAAe,CAAC;CACpC,GACD;IACE,aAAa,EAAE,KAAK,CAAC;IACrB,IAAI,EAAE,IAAI,CAAC;IACX,WAAW,EAAE,EAAE,CAAC;IAChB,aAAa,EAAE,KAAK,CAAC;IACrB,QAAQ,CAAC,EAAE,KAAK,CAAC;CAClB,CAAC;AAEN;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B;;;OAGG;IACH,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAC;IAChC;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;;;GAIG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IAE/B,mBAAmB,EAAE,MAAM,EAAE;IAC7B,gBAAgB,EAAE,MAAM,EAAE;IAC1B,oBAAoB,EAAE,MAAM,EAAE;IAC9B,qBAAqB,CAAC,EAAE,MAAM;IAC9B,uBAAuB,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;gBAJ7C,mBAAmB,EAAE,MAAM,EAAE,EAC7B,gBAAgB,EAAE,MAAM,EAAE,EAC1B,oBAAoB,EAAE,MAAM,EAAE,EAC9B,qBAAqB,CAAC,EAAE,MAAM,YAAA,EAC9B,uBAAuB,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,YAAA;CAKvD;AAED;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IAEhC,QAAQ,EAAE,MAAM;IAChB,WAAW,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;gBAD7D,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAKvE"}
+{"version":3,"file":"auth_types.d.ts","sourceRoot":"","sources":["../../../src/lib/auth/auth_types.ts"],"names":[],"mappings":"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"}

package/dist/lib/auth/auth_types.js

@@ -28,3 +28,46 @@ export class ScopeAccessError extends Error {
         this.name = "ScopeAccessError";
     }
 }
+// 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, code, status_code) {
+        super(message);
+        this.code = code;
+        this.status_code = status_code;
+        this.name = "HazoAuthError";
+    }
+}
+/**
+ * Error thrown when authentication is required but user is not authenticated
+ */
+export class AuthenticationRequiredError extends HazoAuthError {
+    constructor(message = "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 = "Tenant context required", user_scopes = []) {
+        super(message, "TENANT_REQUIRED", 403);
+        this.user_scopes = user_scopes;
+        this.name = "TenantRequiredError";
+    }
+}
+/**
+ * Error thrown when user lacks access to the requested tenant/scope
+ */
+export class TenantAccessDeniedError extends HazoAuthError {
+    constructor(scope_id, user_scopes = []) {
+        super(`Access denied to scope: ${scope_id}`, "TENANT_ACCESS_DENIED", 403);
+        this.scope_id = scope_id;
+        this.user_scopes = user_scopes;
+        this.name = "TenantAccessDeniedError";
+    }
+}

package/dist/lib/auth/hazo_get_auth.server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hazo_get_auth.server.d.ts","sourceRoot":"","sources":["../../../src/lib/auth/hazo_get_auth.server.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAK1C,OAAO,KAAK,EACV,cAAc,EAEd,eAAe,EAEhB,MAAM,cAAc,CAAC;AAmTtB;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,WAAW,EACpB,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,cAAc,CAAC,CAmNzB"}
+{"version":3,"file":"hazo_get_auth.server.d.ts","sourceRoot":"","sources":["../../../src/lib/auth/hazo_get_auth.server.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAK1C,OAAO,KAAK,EACV,cAAc,EAEd,eAAe,EAGhB,MAAM,cAAc,CAAC;AAsWtB;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,WAAW,EACpB,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,cAAc,CAAC,CAmNzB"}

package/dist/lib/auth/hazo_get_auth.server.js

@@ -52,11 +52,6 @@ function get_client_ip(request) {
     }
     return "unknown";
 }
-/**
- * Fetches user data and permissions from database
- * @param user_id - User ID
- * @returns Object with user, permissions, and role_ids
- */
 /**
  * CRUD service options for hazo_user_scopes table
  * This table uses a composite primary key (user_id, scope_id) and no 'id' column
@@ -65,6 +60,48 @@ const USER_SCOPES_CRUD_OPTIONS = {
     primaryKeys: ["user_id", "scope_id"],
     autoId: false,
 };
+/**
+ * Fetches full scope details for user's scope assignments
+ * Joins hazo_user_scopes with hazo_scopes to get name, slug, branding
+ * @param user_id - User ID
+ * @returns Array of scope details with branding information
+ */
+async function fetch_user_scope_details(user_id) {
+    const hazoConnect = get_hazo_connect_instance();
+    const user_scopes_service = createCrudService(hazoConnect, "hazo_user_scopes", USER_SCOPES_CRUD_OPTIONS);
+    const scopes_service = createCrudService(hazoConnect, "hazo_scopes");
+    const user_scope_assignments = await user_scopes_service.findBy({ user_id });
+    if (!Array.isArray(user_scope_assignments) || user_scope_assignments.length === 0) {
+        return [];
+    }
+    const scope_details = [];
+    for (const assignment of user_scope_assignments) {
+        const scope_id = assignment.scope_id;
+        const role_id = assignment.role_id;
+        const scopes = await scopes_service.findBy({ id: scope_id });
+        if (Array.isArray(scopes) && scopes.length > 0) {
+            const scope = scopes[0];
+            scope_details.push({
+                id: scope_id,
+                name: scope.name,
+                slug: scope.slug || null,
+                level: scope.level,
+                parent_id: scope.parent_id,
+                role_id,
+                logo_url: scope.logo_url || null,
+                primary_color: scope.primary_color || null,
+                secondary_color: scope.secondary_color || null,
+                tagline: scope.tagline || null,
+            });
+        }
+    }
+    return scope_details;
+}
+/**
+ * Fetches user data and permissions from database
+ * @param user_id - User ID
+ * @returns Object with user, permissions, role_ids, and scopes
+ */
 async function fetch_user_data_from_db(user_id) {
     const hazoConnect = get_hazo_connect_instance();
     const users_service = createCrudService(hazoConnect, "hazo_users");
@@ -138,7 +175,9 @@ async function fetch_user_data_from_db(user_id) {
         }
     }
     const permissions = Array.from(permissions_set);
-    return { user, permissions, role_ids };
+    // v5.2: Fetch full scope details for caching
+    const scopes = await fetch_user_scope_details(user_id);
+    return { user, permissions, role_ids, scopes };
 }
 /**
  * Checks if user has required permissions
@@ -325,8 +364,8 @@ export async function hazo_get_auth(request, options) {
             user = user_data.user;
             permissions = user_data.permissions;
             role_ids = user_data.role_ids;
-            // Update cache
-            cache.set(user_id, user, permissions, role_ids);
+            // Update cache (v5.2: includes scope details for tenant auth)
+            cache.set(user_id, user, permissions, role_ids, user_data.scopes);
         }
         catch (error) {
             const error_message = error instanceof Error ? error.message : "Unknown error";

package/dist/lib/auth/hazo_get_tenant_auth.server.d.ts

@@ -0,0 +1,64 @@
+import { NextRequest } from "next/server";
+import type { TenantAuthOptions, TenantAuthResult, RequiredTenantAuthResult } from "./auth_types";
+/**
+ * Extracts scope ID from request headers or cookies
+ * Priority: Header > Cookie
+ * @param request - NextRequest object
+ * @param options - TenantAuthOptions for customization
+ * @returns Scope ID if found, undefined otherwise
+ */
+export declare function extract_scope_id_from_request(request: NextRequest, options: TenantAuthOptions): string | undefined;
+/**
+ * Tenant-aware authentication function
+ *
+ * Extracts tenant/scope context from request headers or cookies,
+ * 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, organization, and user_scopes
+ *
+ * @example
+ * ```typescript
+ * const auth = await hazo_get_tenant_auth(request);
+ * if (auth.authenticated && auth.organization) {
+ *   // Access tenant-specific data
+ *   const data = await getData(auth.organization.id);
+ * }
+ * ```
+ */
+export declare function hazo_get_tenant_auth(request: NextRequest, options?: TenantAuthOptions): Promise<TenantAuthResult>;
+/**
+ * Strict tenant authentication helper
+ *
+ * Wraps hazo_get_tenant_auth and throws appropriate errors:
+ * - AuthenticationRequiredError (401) if not authenticated
+ * - TenantRequiredError (403) if no tenant context in request
+ * - TenantAccessDeniedError (403) if user lacks access to requested tenant
+ *
+ * @param request - NextRequest object
+ * @param options - TenantAuthOptions for customization
+ * @returns RequiredTenantAuthResult with guaranteed non-null organization
+ * @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);
+ * } catch (error) {
+ *   if (error instanceof HazoAuthError) {
+ *     return NextResponse.json(
+ *       { error: error.message, code: error.code },
+ *       { status: error.status_code }
+ *     );
+ *   }
+ *   throw error;
+ * }
+ * ```
+ */
+export declare function require_tenant_auth(request: NextRequest, options?: TenantAuthOptions): Promise<RequiredTenantAuthResult>;
+//# sourceMappingURL=hazo_get_tenant_auth.server.d.ts.map

package/dist/lib/auth/hazo_get_tenant_auth.server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hazo_get_tenant_auth.server.d.ts","sourceRoot":"","sources":["../../../src/lib/auth/hazo_get_tenant_auth.server.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAO1C,OAAO,KAAK,EACV,iBAAiB,EACjB,gBAAgB,EAChB,wBAAwB,EAGzB,MAAM,cAAc,CAAC;AAqBtB;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,iBAAiB,GACzB,MAAM,GAAG,SAAS,CAYpB;AAiCD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,WAAW,EACpB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,gBAAgB,CAAC,CAwF3B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,WAAW,EACpB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,wBAAwB,CAAC,CA0BnC"}

package/dist/lib/auth/hazo_get_tenant_auth.server.js

@@ -0,0 +1,201 @@
+import { hazo_get_auth } from "./hazo_get_auth.server.js";
+import { get_auth_cache } from "./auth_cache.js";
+import { get_scope_by_id } from "../services/scope_service.js";
+import { get_hazo_connect_instance } from "../hazo_connect_instance.server.js";
+import { get_cookie_name } from "../cookies_config.server.js";
+import { get_auth_utility_config } from "../auth_utility_config.server.js";
+import { AuthenticationRequiredError, TenantRequiredError, TenantAccessDeniedError, } from "./auth_types.js";
+// section: constants
+/**
+ * Default header name for scope ID
+ */
+const DEFAULT_SCOPE_HEADER = "X-Hazo-Scope-Id";
+/**
+ * Base cookie name for scope ID (will have prefix applied)
+ */
+const BASE_SCOPE_COOKIE = "hazo_auth_scope_id";
+// section: helpers
+/**
+ * Extracts scope ID from request headers or cookies
+ * Priority: Header > Cookie
+ * @param request - NextRequest object
+ * @param options - TenantAuthOptions for customization
+ * @returns Scope ID if found, undefined otherwise
+ */
+export function extract_scope_id_from_request(request, options) {
+    var _a;
+    // Check header first
+    const header_name = options.scope_header_name || DEFAULT_SCOPE_HEADER;
+    const header_value = request.headers.get(header_name);
+    if (header_value) {
+        return header_value;
+    }
+    // Check cookie (with prefix)
+    const cookie_name = options.scope_cookie_name || get_cookie_name(BASE_SCOPE_COOKIE);
+    const cookie_value = (_a = request.cookies.get(cookie_name)) === null || _a === void 0 ? void 0 : _a.value;
+    return cookie_value;
+}
+/**
+ * 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 TenantOrganization object
+ */
+function build_tenant_organization(scope_details, is_super_admin) {
+    return {
+        id: scope_details.id,
+        name: scope_details.name,
+        slug: scope_details.slug,
+        level: scope_details.level,
+        role_id: scope_details.role_id,
+        is_super_admin,
+        branding: scope_details.logo_url || scope_details.primary_color
+            ? {
+                logo_url: scope_details.logo_url,
+                primary_color: scope_details.primary_color,
+                secondary_color: scope_details.secondary_color,
+                tagline: scope_details.tagline,
+            }
+            : undefined,
+    };
+}
+// section: main_functions
+/**
+ * Tenant-aware authentication function
+ *
+ * Extracts tenant/scope context from request headers or cookies,
+ * 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, organization, and user_scopes
+ *
+ * @example
+ * ```typescript
+ * const auth = await hazo_get_tenant_auth(request);
+ * if (auth.authenticated && auth.organization) {
+ *   // Access tenant-specific data
+ *   const data = await getData(auth.organization.id);
+ * }
+ * ```
+ */
+export async function hazo_get_tenant_auth(request, options = {}) {
+    // Extract scope_id from request
+    const scope_id = extract_scope_id_from_request(request, options);
+    // Build hazo_get_auth options, passing through scope_id if present
+    const auth_options = Object.assign(Object.assign({}, options), { scope_id: scope_id || options.scope_id });
+    // Call base hazo_get_auth
+    const auth_result = await hazo_get_auth(request, auth_options);
+    // Handle unauthenticated case
+    if (!auth_result.authenticated) {
+        return {
+            authenticated: false,
+            user: null,
+            permissions: [],
+            permission_ok: false,
+            organization: null,
+            user_scopes: [],
+            scope_ok: false,
+        };
+    }
+    // Get user's scopes from cache (already populated by hazo_get_auth)
+    const config = get_auth_utility_config();
+    const cache = get_auth_cache(config.cache_max_users, config.cache_ttl_minutes, config.cache_max_age_minutes);
+    const cached = cache.get(auth_result.user.id);
+    // User scopes from cache or empty array
+    const user_scopes = (cached === null || cached === void 0 ? void 0 : cached.scopes) || [];
+    // Build organization info if scope access was successful
+    let organization = 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
+        const access_scope = user_scopes.find((s) => { var _a; return s.id === ((_a = auth_result.scope_access_via) === null || _a === void 0 ? void 0 : _a.scope_id); });
+        if (access_scope) {
+            organization = build_tenant_organization(access_scope, auth_result.scope_access_via.is_super_admin || false);
+        }
+        else if (auth_result.scope_access_via.is_super_admin) {
+            // Super admin accessing scope they're not assigned to - fetch scope details
+            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 = {
+                    id: scope_result.scope.id,
+                    name: scope_result.scope.name,
+                    slug: null, // Could fetch from scope if slug column exists
+                    level: scope_result.scope.level,
+                    role_id: "", // Super admin doesn't have a role in the scope
+                    is_super_admin: true,
+                    branding: scope_result.scope.logo_url
+                        ? {
+                            logo_url: scope_result.scope.logo_url,
+                            primary_color: scope_result.scope.primary_color,
+                            secondary_color: scope_result.scope.secondary_color,
+                            tagline: scope_result.scope.tagline,
+                        }
+                        : undefined,
+                };
+            }
+        }
+    }
+    return {
+        authenticated: true,
+        user: auth_result.user,
+        permissions: auth_result.permissions,
+        permission_ok: auth_result.permission_ok,
+        missing_permissions: auth_result.missing_permissions,
+        organization,
+        user_scopes,
+        scope_ok: auth_result.scope_ok,
+        scope_access_via: auth_result.scope_access_via,
+    };
+}
+/**
+ * Strict tenant authentication helper
+ *
+ * Wraps hazo_get_tenant_auth and throws appropriate errors:
+ * - AuthenticationRequiredError (401) if not authenticated
+ * - TenantRequiredError (403) if no tenant context in request
+ * - TenantAccessDeniedError (403) if user lacks access to requested tenant
+ *
+ * @param request - NextRequest object
+ * @param options - TenantAuthOptions for customization
+ * @returns RequiredTenantAuthResult with guaranteed non-null organization
+ * @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);
+ * } catch (error) {
+ *   if (error instanceof HazoAuthError) {
+ *     return NextResponse.json(
+ *       { error: error.message, code: error.code },
+ *       { status: error.status_code }
+ *     );
+ *   }
+ *   throw error;
+ * }
+ * ```
+ */
+export async function require_tenant_auth(request, options = {}) {
+    const result = await hazo_get_tenant_auth(request, options);
+    // Check authentication
+    if (!result.authenticated) {
+        throw new AuthenticationRequiredError();
+    }
+    // Extract scope_id from request for error messages
+    const scope_id = extract_scope_id_from_request(request, options);
+    // Check if scope was requested but access denied
+    if (scope_id && !result.scope_ok) {
+        throw new TenantAccessDeniedError(scope_id, result.user_scopes);
+    }
+    // Check if organization context is required but missing
+    if (!result.organization) {
+        throw new TenantRequiredError("No organization 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
+    return result;
+}

package/dist/lib/auth/index.d.ts

@@ -2,6 +2,9 @@ export * from "./auth_types.js";
 export { hazo_get_auth } from "./hazo_get_auth.server.js";
 export { get_authenticated_user, require_auth, is_authenticated, } from "./auth_utils.server.js";
 export type { AuthResult, AuthUser } from "./auth_utils.server";
+export { hazo_get_tenant_auth, require_tenant_auth, extract_scope_id_from_request, } from "./hazo_get_tenant_auth.server.js";
+export type { ScopeDetails, TenantOrganization, TenantAuthOptions, TenantAuthResult, RequiredTenantAuthResult, } from "./auth_types";
+export { HazoAuthError, AuthenticationRequiredError, TenantRequiredError, TenantAccessDeniedError, } from "./auth_types.js";
 export { get_server_auth_user } from "./server_auth.js";
 export type { ServerAuthResult } from "./server_auth";
 export { get_auth_cache, reset_auth_cache } from "./auth_cache.js";

package/dist/lib/auth/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/auth/index.ts"],"names":[],"mappings":"AAEA,cAAc,cAAc,CAAC;AAG7B,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EACL,sBAAsB,EACtB,YAAY,EACZ,gBAAgB,GACjB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAGhE,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACrD,YAAY,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAGtD,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGhE,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/auth/index.ts"],"names":[],"mappings":"AAEA,cAAc,cAAc,CAAC;AAG7B,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EACL,sBAAsB,EACtB,YAAY,EACZ,gBAAgB,GACjB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAGhE,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,6BAA6B,GAC9B,MAAM,+BAA+B,CAAC;AACvC,YAAY,EACV,YAAY,EACZ,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,wBAAwB,GACzB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,aAAa,EACb,2BAA2B,EAC3B,mBAAmB,EACnB,uBAAuB,GACxB,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACrD,YAAY,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAGtD,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGhE,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/lib/auth/index.js

@@ -4,6 +4,9 @@ export * from "./auth_types.js";
 // section: server_exports
 export { hazo_get_auth } from "./hazo_get_auth.server.js";
 export { get_authenticated_user, require_auth, is_authenticated, } from "./auth_utils.server.js";
+// section: tenant_auth_exports
+export { hazo_get_tenant_auth, require_tenant_auth, extract_scope_id_from_request, } from "./hazo_get_tenant_auth.server.js";
+export { HazoAuthError, AuthenticationRequiredError, TenantRequiredError, TenantAccessDeniedError, } from "./auth_types.js";
 // section: client_exports
 export { get_server_auth_user } from "./server_auth.js";
 // section: cache_exports

package/dist/lib/cookies_config.server.d.ts

@@ -9,6 +9,7 @@ export declare const BASE_COOKIE_NAMES: {
     readonly USER_EMAIL: "hazo_auth_user_email";
     readonly SESSION: "hazo_auth_session";
     readonly DEV_LOCK: "hazo_auth_dev_lock";
+    readonly SCOPE_ID: "hazo_auth_scope_id";
 };
 /**
  * Reads cookie configuration from hazo_auth_config.ini file

package/dist/lib/cookies_config.server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cookies_config.server.d.ts","sourceRoot":"","sources":["../../src/lib/cookies_config.server.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,aAAa,GAAG;IAC1B,6FAA6F;IAC7F,aAAa,EAAE,MAAM,CAAC;IACtB,6EAA6E;IAC7E,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAYF,eAAO,MAAM,iBAAiB;;;;;CAKpB,CAAC;AAGX;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,aAAa,CAWlD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAGzD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC,GAAG;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAQzG;AAKD;;;GAGG;AACH,wBAAgB,yBAAyB,IAAI,aAAa,CAKzD;AAED;;GAEG;AACH,wBAAgB,0BAA0B,IAAI,IAAI,CAEjD"}
+{"version":3,"file":"cookies_config.server.d.ts","sourceRoot":"","sources":["../../src/lib/cookies_config.server.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,aAAa,GAAG;IAC1B,6FAA6F;IAC7F,aAAa,EAAE,MAAM,CAAC;IACtB,6EAA6E;IAC7E,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAYF,eAAO,MAAM,iBAAiB;;;;;;CAMpB,CAAC;AAGX;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,aAAa,CAWlD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAGzD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC,GAAG;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAQzG;AAKD;;;GAGG;AACH,wBAAgB,yBAAyB,IAAI,aAAa,CAKzD;AAED;;GAEG;AACH,wBAAgB,0BAA0B,IAAI,IAAI,CAEjD"}

package/dist/lib/cookies_config.server.js

@@ -13,6 +13,7 @@ export const BASE_COOKIE_NAMES = {
     USER_EMAIL: "hazo_auth_user_email",
     SESSION: "hazo_auth_session",
     DEV_LOCK: "hazo_auth_dev_lock",
+    SCOPE_ID: "hazo_auth_scope_id", // v5.2: Tenant context cookie for multi-tenancy
 };
 // section: main_function
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hazo_auth",
-  "version": "5.1.10",
+  "version": "5.1.12",
   "description": "Zero-config authentication UI components for Next.js with RBAC, OAuth, scope-based multi-tenancy, and invitations",
   "keywords": [
     "authentication",