hazo_auth 5.1.11 → 5.1.13

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

@@ -10,6 +10,7 @@ import type {
   HazoAuthUser,
   HazoAuthOptions,
   ScopeAccessInfo,
+  ScopeDetails,
 } from "./auth_types";
 import { PermissionError, ScopeAccessError } from "./auth_types.js";
 import { get_auth_cache } from "./auth_cache.js";
@@ -72,11 +73,6 @@ function get_client_ip(request: NextRequest): string {
   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
@@ -86,10 +82,63 @@ const USER_SCOPES_CRUD_OPTIONS = {
   autoId: false as const,
 };
 
+/**
+ * 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: string): Promise<ScopeDetails[]> {
+  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: ScopeDetails[] = [];
+  for (const assignment of user_scope_assignments) {
+    const scope_id = assignment.scope_id as string;
+    const role_id = assignment.role_id as string;
+
+    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 as string,
+        slug: (scope.slug as string) || null,
+        level: scope.level as string,
+        parent_id: scope.parent_id as string | null,
+        role_id,
+        logo_url: (scope.logo_url as string) || null,
+        primary_color: (scope.primary_color as string) || null,
+        secondary_color: (scope.secondary_color as string) || null,
+        tagline: (scope.tagline as string) || 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: string): Promise<{
   user: HazoAuthUser;
   permissions: string[];
   role_ids: string[];
+  scopes: ScopeDetails[];
 }> {
   const hazoConnect = get_hazo_connect_instance();
   const users_service = createCrudService(hazoConnect, "hazo_users");
@@ -186,7 +235,10 @@ async function fetch_user_data_from_db(user_id: string): Promise<{
 
   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 };
 }
 
 /**
@@ -430,8 +482,8 @@ export async function hazo_get_auth(
       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/cli-src/lib/auth/hazo_get_tenant_auth.server.ts

@@ -0,0 +1,267 @@
+// file_description: tenant-aware authentication function that extracts scope from request headers/cookies
+// section: imports
+import { NextRequest } from "next/server";
+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 type {
+  TenantAuthOptions,
+  TenantAuthResult,
+  RequiredTenantAuthResult,
+  TenantOrganization,
+  ScopeDetails,
+} from "./auth_types";
+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: NextRequest,
+  options: TenantAuthOptions,
+): string | undefined {
+  // 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 = request.cookies.get(cookie_name)?.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: ScopeDetails,
+  is_super_admin: boolean,
+): TenantOrganization {
+  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: NextRequest,
+  options: TenantAuthOptions = {},
+): Promise<TenantAuthResult> {
+  // 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 = {
+    ...options,
+    scope_id: scope_id || options.scope_id, // Allow explicit override via options
+  };
+
+  // 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,
+      organization_id: 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: ScopeDetails[] = cached?.scopes || [];
+
+  // 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
+    const access_scope = user_scopes.find(
+      (s) => s.id === auth_result.scope_access_via?.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,
+    organization_id: organization?.id || null,
+    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: NextRequest,
+  options: TenantAuthOptions = {},
+): Promise<RequiredTenantAuthResult> {
+  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 as RequiredTenantAuthResult;
+}

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

@@ -11,6 +11,26 @@ export {
 } from "./auth_utils.server.js";
 export type { AuthResult, AuthUser } from "./auth_utils.server";
 
+// 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 type {
+  ScopeDetails,
+  TenantOrganization,
+  TenantAuthOptions,
+  TenantAuthResult,
+  RequiredTenantAuthResult,
+} from "./auth_types";
+export {
+  HazoAuthError,
+  AuthenticationRequiredError,
+  TenantRequiredError,
+  TenantAccessDeniedError,
+} from "./auth_types.js";
+
 // section: client_exports
 export { get_server_auth_user } from "./server_auth.js";
 export type { ServerAuthResult } from "./server_auth";

package/cli-src/lib/cookies_config.server.ts

@@ -25,6 +25,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
 } as const;
 
 // section: main_function

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

@@ -1,12 +1,14 @@
-import type { HazoAuthUser } from "./auth_types";
+import type { HazoAuthUser, ScopeDetails } from "./auth_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[];
     timestamp: number;
     cache_version: number;
 };
@@ -35,8 +37,9 @@ declare 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[]): void;
+    set(user_id: string, user: HazoAuthUser, permissions: string[], role_ids: string[], scopes?: ScopeDetails[]): void;
     /**
      * Invalidates cache for a specific user
      * @param user_id - User ID to invalidate
@@ -52,6 +55,12 @@ declare class AuthCache {
      * Invalidates all cache entries
      */
     invalidate_all(): void;
+    /**
+     * 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;
     /**
      * Gets the maximum cache version for a set of roles
      * Used to determine if cache entry is stale

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

@@ -1 +1 @@
-{"version":3,"file":"auth_cache.d.ts","sourceRoot":"","sources":["../../../src/lib/auth/auth_cache.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAIjD;;;GAGG;AACH,KAAK,UAAU,GAAG;IAChB,IAAI,EAAE,YAAY,CAAC;IACnB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF;;;GAGG;AACH,cAAM,SAAS;IACb,OAAO,CAAC,KAAK,CAA0B;IACvC,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,gBAAgB,CAAsB;gBAG5C,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,eAAe,EAAE,MAAM;IASzB;;;;;OAKG;IACH,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IA+B5C;;;;;;;OAOG;IACH,GAAG,CACD,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,YAAY,EAClB,WAAW,EAAE,MAAM,EAAE,EACrB,QAAQ,EAAE,MAAM,EAAE,GACjB,IAAI;IAyBP;;;OAGG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAItC;;;;OAIG;IACH,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI;IAqB7C;;OAEG;IACH,cAAc,IAAI,IAAI;IAItB;;;;;OAKG;IACH,OAAO,CAAC,oBAAoB;IAc5B;;;OAGG;IACH,SAAS,IAAI;QACX,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;KAClB;CAMF;AAMD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,GAAE,MAAc,EACxB,WAAW,GAAE,MAAW,EACxB,eAAe,GAAE,MAAW,GAC3B,SAAS,CAKX;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC"}
+{"version":3,"file":"auth_cache.d.ts","sourceRoot":"","sources":["../../../src/lib/auth/auth_cache.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAI/D;;;;GAIG;AACH,KAAK,UAAU,GAAG;IAChB,IAAI,EAAE,YAAY,CAAC;IACnB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF;;;GAGG;AACH,cAAM,SAAS;IACb,OAAO,CAAC,KAAK,CAA0B;IACvC,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,gBAAgB,CAAsB;gBAG5C,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,eAAe,EAAE,MAAM;IASzB;;;;;OAKG;IACH,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IA+B5C;;;;;;;;OAQG;IACH,GAAG,CACD,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,YAAY,EAClB,WAAW,EAAE,MAAM,EAAE,EACrB,QAAQ,EAAE,MAAM,EAAE,EAClB,MAAM,GAAE,YAAY,EAAO,GAC1B,IAAI;IA0BP;;;OAGG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAItC;;;;OAIG;IACH,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI;IAqB7C;;OAEG;IACH,cAAc,IAAI,IAAI;IAItB;;;;OAIG;IACH,uBAAuB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI;IAalD;;;;;OAKG;IACH,OAAO,CAAC,oBAAoB;IAc5B;;;OAGG;IACH,SAAS,IAAI;QACX,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;KAClB;CAMF;AAMD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,GAAE,MAAc,EACxB,WAAW,GAAE,MAAW,EACxB,eAAe,GAAE,MAAW,GAC3B,SAAS,CAKX;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC"}

package/dist/lib/auth/auth_cache.js

@@ -47,8 +47,9 @@ 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, user, permissions, role_ids) {
+    set(user_id, user, permissions, role_ids, scopes = []) {
         // Evict LRU entries if cache is full
         while (this.cache.size >= this.max_size) {
             const first_key = this.cache.keys().next().value;
@@ -65,6 +66,7 @@ class AuthCache {
             user,
             permissions,
             role_ids,
+            scopes,
             timestamp: Date.now(),
             cache_version,
         };
@@ -106,6 +108,23 @@ class AuthCache {
     invalidate_all() {
         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) {
+        const entries_to_remove = [];
+        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/dist/lib/auth/auth_types.d.ts

@@ -85,4 +85,117 @@ 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;
+    /** Shorthand for organization?.id - commonly used for DB query filters */
+    organization_id: string | null;
+    user_scopes: ScopeDetails[];
+    scope_ok?: boolean;
+    scope_access_via?: ScopeAccessInfo;
+} | {
+    authenticated: false;
+    user: null;
+    permissions: [];
+    permission_ok: false;
+    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 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"}