hazo_auth 4.2.0 → 4.3.0

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

@@ -0,0 +1,101 @@
+// file_description: singleton instance of hazo_connect adapter - initialized once and reused across all routes
+// This ensures all routes/components use the same database connection
+// Uses the new hazo_connect singleton API from hazo_connect/nextjs/setup
+// Reads configuration from hazo_auth_config.ini using hazo_config
+// section: imports
+import type { HazoConnectAdapter } from "hazo_connect";
+import { getHazoConnectSingleton } from "hazo_connect/nextjs/setup";
+import { create_sqlite_hazo_connect_server, get_hazo_connect_config_options } from "./hazo_connect_setup.server";
+import { initializeAdminService, getSqliteAdminService } from "hazo_connect/server";
+import { create_app_logger } from "./app_logger";
+
+// section: singleton_state
+let hazoConnectInstance: HazoConnectAdapter | null = null;
+let isInitialized = false;
+
+// section: helpers
+/**
+ * Gets or creates the singleton hazo_connect adapter instance
+ * This ensures all routes/components use the same database connection
+ * 
+ * Uses the new hazo_connect singleton API which:
+ * - Automatically reuses the adapter instance
+ * - Automatically registers SQLite adapters with the admin service
+ * - Is thread-safe for Next.js serverless environments
+ * - Reads configuration from hazo_auth_config.ini using hazo_config (falls back to environment variables)
+ * 
+ * Falls back to manual singleton if the new API is not available
+ * 
+ * @returns The singleton HazoConnectAdapter instance
+ */
+export function get_hazo_connect_instance(): HazoConnectAdapter {
+  // Use the new singleton API from hazo_connect
+  // This automatically handles:
+  // - Instance reuse
+  // - Admin service registration (via registerSqliteAdapter)
+  // - Thread-safety for Next.js serverless
+  // - Configuration from hazo_auth_config.ini (via hazo_config) or environment variables
+  try {
+    // Get configuration from hazo_auth_config.ini (falls back to environment variables)
+    const config_options = get_hazo_connect_config_options();
+    const logger = create_app_logger();
+    logger.debug("hazo_connect_singleton_attempt", {
+      filename: "hazo_connect_instance.server.ts",
+      line_number: 38,
+      config_options,
+      note: "Attempting to get singleton with these options",
+    });
+    return getHazoConnectSingleton(config_options);
+  } catch (error) {
+    const logger = create_app_logger();
+    const error_message = error instanceof Error ? error.message : "Unknown error";
+    logger.error("hazo_connect_singleton_failed", {
+      filename: "hazo_connect_instance.server.ts",
+      line_number: 45,
+      error: error_message,
+      error_stack: error instanceof Error ? error.stack : undefined,
+      note: "Falling back to manual singleton implementation",
+    });
+    
+    // Fallback: Manual singleton implementation if new API fails
+    // This should not happen with the updated package, but kept for safety
+    if (!hazoConnectInstance) {
+      // Get config options to determine database type
+      const config_options = get_hazo_connect_config_options();
+      const db_type = config_options.type;
+      
+      // Only initialize SQLite admin service for SQLite databases
+      if (db_type === "sqlite" && !isInitialized) {
+        initializeAdminService({ enable_admin_ui: true });
+        isInitialized = true;
+      }
+      
+      // Create the adapter instance (reads from hazo_auth_config.ini)
+      // Note: Despite the name, this function supports both SQLite and PostgREST
+      hazoConnectInstance = create_sqlite_hazo_connect_server();
+
+      // Note: Database migrations should be applied manually via SQLite Admin UI
+      // or through a separate migration script. The token_service has fallback
+      // logic to work without the token_type column if migration hasn't been applied.
+
+      // Finalize initialization by getting the admin service (only for SQLite)
+      if (db_type === "sqlite") {
+        try {
+          getSqliteAdminService();
+        } catch (adminError) {
+          const logger = create_app_logger();
+          const error_message = adminError instanceof Error ? adminError.message : "Unknown error";
+          logger.warn("hazo_connect_instance_admin_service_init_failed", {
+            filename: "hazo_connect_instance.server.ts",
+            line_number: 0,
+            error: error_message,
+            note: "Could not get SqliteAdminService during initialization, continuing...",
+          });
+        }
+      }
+    }
+    
+    return hazoConnectInstance;
+  }
+}
+

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

@@ -0,0 +1,194 @@
+// file_description: server-only helper to create hazo_connect instance (imports server-side code)
+// This file should only be imported in server contexts (API routes, server components)
+// Reads configuration from hazo_auth_config.ini using hazo_config
+// section: imports
+import { createHazoConnect } from "hazo_connect/server";
+import { HazoConfig } from "hazo_config/dist/lib";
+import path from "path";
+import fs from "fs";
+import { create_app_logger } from "./app_logger";
+import { read_config_section } from "./config/config_loader.server";
+
+// section: helpers
+/**
+ * Reads hazo_connect configuration from hazo_auth_config.ini file
+ * Falls back to environment variables if hazo_auth_config.ini is not found or section is missing
+ * @returns Configuration options for hazo_connect
+ */
+function get_hazo_connect_config(): {
+  type: "sqlite" | "postgrest";
+  sqlitePath?: string;
+  enableAdminUi: boolean;
+  readOnly?: boolean;
+  postgrestUrl?: string;
+  postgrestApiKey?: string;
+} {
+  const default_config_path = path.resolve(process.cwd(), "hazo_auth_config.ini");
+  let hazo_connect_section: Record<string, string> | undefined;
+
+  // Try to read from hazo_auth_config.ini
+  const logger = create_app_logger();
+  hazo_connect_section = read_config_section("hazo_connect");
+
+  // Read type (defaults to sqlite)
+  const type = (
+    hazo_connect_section?.type ||
+    process.env.HAZO_CONNECT_TYPE ||
+    "sqlite"
+  ).toLowerCase() as "sqlite" | "postgrest";
+
+  // Read enable_admin_ui (defaults to true)
+  const enable_admin_ui_str =
+    hazo_connect_section?.enable_admin_ui ||
+    process.env.HAZO_CONNECT_ENABLE_ADMIN_UI ||
+    "true";
+  const enableAdminUi = enable_admin_ui_str.toLowerCase() === "true";
+
+  // Read read_only (defaults to false)
+  const read_only_str =
+    hazo_connect_section?.read_only ||
+    process.env.HAZO_CONNECT_SQLITE_READONLY ||
+    "false";
+  const readOnly = read_only_str.toLowerCase() === "true";
+
+  // SQLite configuration
+  if (type === "sqlite") {
+    const sqlite_path_config =
+      hazo_connect_section?.sqlite_path || process.env.HAZO_CONNECT_SQLITE_PATH;
+
+    let sqlite_path: string | undefined;
+
+    if (sqlite_path_config) {
+      // If path is absolute, use as-is; otherwise resolve relative to process.cwd()
+      sqlite_path = path.isAbsolute(sqlite_path_config)
+        ? sqlite_path_config
+        : path.resolve(process.cwd(), sqlite_path_config);
+
+      // Normalize the path to ensure consistency (resolves .., ., etc.)
+      sqlite_path = path.normalize(sqlite_path);
+    } else {
+      // Fallback to test fixture database
+      const fallback_sqlite_path = path.resolve(
+        process.cwd(),
+        "__tests__",
+        "fixtures",
+        "hazo_auth.sqlite"
+      );
+      sqlite_path = path.normalize(fallback_sqlite_path);
+    }
+
+    // Log the resolved path for debugging
+    logger.debug("hazo_connect_sqlite_path_resolved", {
+      filename: "hazo_connect_setup.server.ts",
+      line_number: 0,
+      sqlite_path,
+      process_cwd: process.cwd(),
+      config_source: hazo_connect_section ? "hazo_auth_config.ini" : "environment variables",
+    });
+
+    return {
+      type: "sqlite",
+      sqlitePath: sqlite_path,
+      enableAdminUi,
+      readOnly,
+    };
+  }
+
+  // PostgREST configuration
+  if (type === "postgrest") {
+    const postgrest_url =
+      hazo_connect_section?.postgrest_url ||
+      process.env.HAZO_CONNECT_POSTGREST_URL ||
+      process.env.POSTGREST_URL;
+    // API key must only come from environment variables for security
+    // Check multiple possible env var names for compatibility
+    const postgrest_api_key =
+      process.env.postgrest_api_key ||  // hazo_connect package expects this
+      process.env.HAZO_CONNECT_POSTGREST_API_KEY ||
+      process.env.POSTGREST_API_KEY;
+
+    if (!postgrest_url) {
+      throw new Error(
+        "PostgREST URL is required. Set postgrest_url in [hazo_connect] section of hazo_auth_config.ini or HAZO_CONNECT_POSTGREST_URL environment variable."
+      );
+    }
+
+    return {
+      type: "postgrest",
+      postgrestUrl: postgrest_url,
+      postgrestApiKey: postgrest_api_key,
+      enableAdminUi,
+    };
+  }
+
+  throw new Error(
+    `Unsupported HAZO_CONNECT_TYPE: ${type}. Supported types: sqlite, postgrest`
+  );
+}
+
+/**
+ * Server-only function to create hazo_connect adapter
+ * Reads configuration from hazo_auth_config.ini using hazo_config, falls back to environment variables
+ * This should only be called from server-side code (API routes, server components)
+ */
+export function create_sqlite_hazo_connect_server() {
+  const config = get_hazo_connect_config();
+
+  if (config.type === "sqlite") {
+    return createHazoConnect({
+      type: "sqlite",
+      database: config.sqlitePath!,
+      enable_admin_ui: config.enableAdminUi,
+    });
+  }
+
+  if (config.type === "postgrest") {
+    // Ensure we have a value (empty string if not set, for PostgREST instances without auth)
+    const apiKey = config.postgrestApiKey || "";
+    
+    return createHazoConnect({
+      type: "postgrest",
+      baseUrl: config.postgrestUrl!,
+      apiKey: apiKey, // Pass empty string if not set
+    });
+  }
+
+  throw new Error(`Unsupported database type: ${config.type}`);
+}
+
+/**
+ * Gets hazo_connect configuration options for use with singleton API
+ * Reads from hazo_auth_config.ini using hazo_config, falls back to environment variables
+ * @returns Configuration options compatible with getHazoConnectSingleton
+ */
+export function get_hazo_connect_config_options(): {
+  type?: "sqlite" | "postgrest";
+  sqlitePath?: string;
+  enableAdminUi?: boolean;
+  readOnly?: boolean;
+  baseUrl?: string;
+  apiKey?: string;
+} {
+  const config = get_hazo_connect_config();
+
+  if (config.type === "sqlite") {
+    return {
+      type: "sqlite",
+      sqlitePath: config.sqlitePath,
+      enableAdminUi: config.enableAdminUi,
+      readOnly: config.readOnly,
+    };
+  }
+
+  if (config.type === "postgrest") {
+    return {
+      type: "postgrest",
+      baseUrl: config.postgrestUrl, // Corrected from postgrestUrl
+      apiKey: config.postgrestApiKey || "", // Corrected from postgrestApiKey and ensured string value
+    };
+  }
+
+  // Fallback: return empty object to let it use environment variables
+  return {};
+}
+

package/cli-src/lib/hazo_connect_setup.ts

@@ -0,0 +1,54 @@
+// file_description: helper function to create hazo_connect instance with configuration from environment variables
+// This file provides a client-safe wrapper that returns a mock on client-side
+// section: imports
+// Note: We don't import server-side code here to avoid client-side bundling issues
+
+// section: helpers
+/**
+ * Creates a hazo_connect instance configured from environment variables
+ * 
+ * Environment variables:
+ * - HAZO_CONNECT_TYPE: Database type ("sqlite" | "postgrest") - defaults to "sqlite"
+ * - HAZO_CONNECT_SQLITE_PATH: Path to SQLite database file (relative to process.cwd() or absolute)
+ * - HAZO_CONNECT_POSTGREST_URL: PostgREST API URL (for postgrest type)
+ * - HAZO_CONNECT_POSTGREST_API_KEY: PostgREST API key (for postgrest type)
+ * 
+ * Falls back to test fixture database if HAZO_CONNECT_SQLITE_PATH is not set
+ * 
+ * Note: For client-side usage (Next.js pages), this returns a mock adapter
+ * since SQLite cannot run in browser environments. Use PostgREST for client-side database access.
+ */
+// Lazy loader for server module - prevents webpack from statically analyzing the require
+function loadServerModule() {
+  // Use Function constructor to create a dynamic require that webpack can't analyze
+  // eslint-disable-next-line no-new-func
+  const requireFunc = new Function('modulePath', 'return require(modulePath)');
+  return requireFunc('./hazo_connect_setup.server');
+}
+
+export function create_sqlite_hazo_connect() {
+  // Check if we're in a browser/client environment
+  if (typeof window !== "undefined") {
+    // Return a mock adapter for client-side usage
+    return create_client_mock_hazo_connect();
+  }
+
+  // Server-side: dynamically load server module
+  // Using Function constructor prevents webpack from statically analyzing the require
+  const serverModule = loadServerModule();
+  return serverModule.create_sqlite_hazo_connect_server();
+}
+
+/**
+ * Creates a mock hazo_connect adapter for client-side usage
+ * This satisfies the LayoutDataClient interface without requiring SQLite
+ */
+function create_client_mock_hazo_connect() {
+  return {
+    healthCheck: async () => {
+      // Mock health check for client-side - no-op
+      return Promise.resolve();
+    },
+  };
+}
+

package/cli-src/lib/index.ts

@@ -0,0 +1,46 @@
+// file_description: barrel export for lib utilities
+// section: auth_exports
+export * from "./auth/index";
+
+// section: service_exports
+export * from "./services/index";
+
+// section: utility_exports
+export { cn, merge_class_names } from "./utils";
+
+// section: config_exports
+export { get_config_value, get_config_number, get_config_boolean, get_config_array, read_config_section } from "./config/config_loader.server";
+
+// section: hazo_connect_exports
+export { create_sqlite_hazo_connect } from "./hazo_connect_setup";
+export { get_hazo_connect_instance } from "./hazo_connect_instance.server";
+
+// section: logger_exports
+export { create_app_logger } from "./app_logger";
+
+// section: config_server_exports
+export { get_login_config } from "./login_config.server";
+export { get_register_config } from "./register_config.server";
+export { get_forgot_password_config } from "./forgot_password_config.server";
+export { get_reset_password_config } from "./reset_password_config.server";
+export { get_email_verification_config } from "./email_verification_config.server";
+export { get_my_settings_config } from "./my_settings_config.server";
+export { get_user_management_config } from "./user_management_config.server";
+export { get_profile_picture_config } from "./profile_picture_config.server";
+export { get_profile_pic_menu_config } from "./profile_pic_menu_config.server";
+export { get_already_logged_in_config } from "./already_logged_in_config.server";
+export { get_ui_shell_config } from "./ui_shell_config.server";
+export { get_ui_sizes_config } from "./ui_sizes_config.server";
+export { get_auth_utility_config } from "./auth_utility_config.server";
+export { get_password_requirements_config } from "./password_requirements_config.server";
+export { get_messages_config } from "./messages_config.server";
+export { get_user_fields_config } from "./user_fields_config.server";
+export { get_file_types_config } from "./file_types_config.server";
+export { get_oauth_config, is_google_oauth_enabled, is_email_password_enabled } from "./oauth_config.server";
+export type { OAuthConfig } from "./oauth_config.server";
+
+// section: util_exports
+export { sanitize_error_for_user } from "./utils/error_sanitizer";
+export type { ErrorSanitizationOptions } from "./utils/error_sanitizer";
+export * from "./utils/api_route_helpers";
+

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

@@ -0,0 +1,106 @@
+// file_description: server-only helper to read login layout configuration from hazo_auth_config.ini
+// section: imports
+import { get_config_value } from "./config/config_loader.server";
+import { get_already_logged_in_config } from "./already_logged_in_config.server";
+import { get_oauth_config, type OAuthConfig } from "./oauth_config.server";
+import loginDefaultImage from "../assets/images/login_default.jpg";
+
+// section: types
+import type { StaticImageData } from "next/image";
+
+export type LoginConfig = {
+  redirectRoute?: string;
+  successMessage: string;
+  alreadyLoggedInMessage: string;
+  showLogoutButton: boolean;
+  showReturnHomeButton: boolean;
+  returnHomeButtonLabel: string;
+  returnHomePath: string;
+  forgotPasswordPath: string;
+  forgotPasswordLabel: string;
+  createAccountPath: string;
+  createAccountLabel: string;
+  imageSrc: string | StaticImageData;
+  imageAlt: string;
+  imageBackgroundColor: string;
+  /** OAuth configuration */
+  oauth: OAuthConfig;
+};
+
+// section: helpers
+/**
+ * Reads login layout configuration from hazo_auth_config.ini file
+ * Falls back to defaults if hazo_auth_config.ini is not found or section is missing
+ * @returns Login configuration options
+ */
+export function get_login_config(): LoginConfig {
+  const section = "hazo_auth__login_layout";
+
+  // Read redirect route (optional)
+  const redirectRouteValue = get_config_value(section, "redirect_route_on_successful_login", "");
+  const redirectRoute = redirectRouteValue || undefined;
+
+  // Read success message (defaults to "Successfully logged in")
+  const successMessage = get_config_value(section, "success_message", "Successfully logged in");
+
+  const forgotPasswordPath = get_config_value(
+    section,
+    "forgot_password_path",
+    "/hazo_auth/forgot_password"
+  );
+  const forgotPasswordLabel = get_config_value(
+    section,
+    "forgot_password_label",
+    "Forgot password?"
+  );
+  const createAccountPath = get_config_value(section, "create_account_path", "/hazo_auth/register");
+  const createAccountLabel = get_config_value(
+    section,
+    "create_account_label",
+    "Create account"
+  );
+
+  // Get shared already logged in config
+  const alreadyLoggedInConfig = get_already_logged_in_config();
+
+  // Read image configuration
+  // If not set in config, falls back to default image from assets
+  const imageSrc = get_config_value(
+    section,
+    "image_src",
+    "" // Empty string means not set in config
+  ) || loginDefaultImage;
+
+  const imageAlt = get_config_value(
+    section,
+    "image_alt",
+    "Secure login illustration"
+  );
+  const imageBackgroundColor = get_config_value(
+    section,
+    "image_background_color",
+    "#f1f5f9"
+  );
+
+  // Get OAuth configuration
+  const oauth = get_oauth_config();
+
+  return {
+    redirectRoute,
+    successMessage,
+    alreadyLoggedInMessage: alreadyLoggedInConfig.message,
+    showLogoutButton: alreadyLoggedInConfig.showLogoutButton,
+    showReturnHomeButton: alreadyLoggedInConfig.showReturnHomeButton,
+    returnHomeButtonLabel: alreadyLoggedInConfig.returnHomeButtonLabel,
+    returnHomePath: alreadyLoggedInConfig.returnHomePath,
+    forgotPasswordPath,
+    forgotPasswordLabel,
+    createAccountPath,
+    createAccountLabel,
+    imageSrc,
+    imageAlt,
+    imageBackgroundColor,
+    oauth,
+  };
+}
+

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

@@ -0,0 +1,45 @@
+// file_description: server-only helper to read user-facing messages from hazo_auth_config.ini
+// section: imports
+import { get_config_value } from "./config/config_loader.server";
+
+// section: types
+export type MessagesConfig = {
+  photo_upload_disabled_message: string;
+  gravatar_setup_message: string;
+  gravatar_no_account_message: string;
+  library_tooltip_message: string;
+};
+
+// section: helpers
+/**
+ * Reads user-facing messages from hazo_auth_config.ini file
+ * Falls back to defaults if hazo_auth_config.ini is not found or section is missing
+ * @returns Messages configuration options
+ */
+export function get_messages_config(): MessagesConfig {
+  const section = "hazo_auth__messages";
+
+  return {
+    photo_upload_disabled_message: get_config_value(
+      section,
+      "photo_upload_disabled_message",
+      "Photo upload is not enabled. Please contact your administrator."
+    ),
+    gravatar_setup_message: get_config_value(
+      section,
+      "gravatar_setup_message",
+      "To set up your Gravatar:"
+    ),
+    gravatar_no_account_message: get_config_value(
+      section,
+      "gravatar_no_account_message",
+      "You don't have a Gravatar account set up for this email address."
+    ),
+    library_tooltip_message: get_config_value(
+      section,
+      "library_tooltip_message",
+      "Select another tab image style to remove this image"
+    ),
+  };
+}
+

package/cli-src/lib/migrations/apply_migration.ts

@@ -0,0 +1,105 @@
+// file_description: helper to apply database migrations using hazo_connect
+// section: imports
+import type { HazoConnectAdapter } from "hazo_connect";
+import { createCrudService } from "hazo_connect/server";
+import fs from "fs";
+import path from "path";
+
+// section: helpers
+/**
+ * Applies a SQL migration file to the database
+ * For SQLite, we need to execute raw SQL statements
+ * @param adapter - The hazo_connect adapter instance
+ * @param migration_file_path - Path to the SQL migration file
+ * @returns Success status and error message if any
+ */
+export async function apply_migration(
+  adapter: HazoConnectAdapter,
+  migration_file_path: string,
+): Promise<{ success: boolean; error?: string }> {
+  try {
+    // Read the migration file
+    const migration_sql = fs.readFileSync(migration_file_path, "utf-8");
+
+    // Split SQL statements by semicolon and execute each one
+    // Remove comments and empty statements
+    const statements = migration_sql
+      .split(";")
+      .map((stmt) => stmt.trim())
+      .filter((stmt) => stmt.length > 0 && !stmt.startsWith("--"));
+
+    // Execute each statement
+    // For SQLite via hazo_connect, we may need to use a raw query method
+    // Since hazo_connect doesn't expose raw SQL execution directly,
+    // we'll try to use the adapter's internal methods or skip migration
+    // and rely on the fallback in token_service
+    
+    // For now, we'll log that migration should be applied manually
+    // The token_service has fallback logic to work without token_type column
+    if (process.env.NODE_ENV === "development") {
+      console.log(
+        `[migrations] Migration file found: ${migration_file_path}`,
+        "\n[migrations] Note: Raw SQL execution not available via hazo_connect adapter.",
+        "\n[migrations] Please apply migration manually or ensure token_type column exists."
+      );
+    }
+
+    // Try to check if token_type column already exists by querying the schema
+    // If it doesn't exist, we'll rely on the fallback in token_service
+    return { success: true };
+  } catch (error) {
+    const error_message =
+      error instanceof Error ? error.message : "Unknown error";
+
+    return {
+      success: false,
+      error: error_message,
+    };
+  }
+}
+
+/**
+ * Applies all migrations in the migrations directory
+ * @param adapter - The hazo_connect adapter instance
+ * @returns Success status and error message if any
+ */
+export async function apply_all_migrations(
+  adapter: HazoConnectAdapter,
+): Promise<{ success: boolean; error?: string }> {
+  try {
+    const migrations_dir = path.resolve(process.cwd(), "migrations");
+
+    if (!fs.existsSync(migrations_dir)) {
+      return { success: true }; // No migrations directory, nothing to apply
+    }
+
+    // Get all SQL files in migrations directory, sorted by name
+    const migration_files = fs
+      .readdirSync(migrations_dir)
+      .filter((file) => file.endsWith(".sql"))
+      .sort();
+
+    for (const migration_file of migration_files) {
+      const migration_path = path.join(migrations_dir, migration_file);
+      const result = await apply_migration(adapter, migration_path);
+
+      if (!result.success) {
+        return {
+          success: false,
+          error: `Failed to apply migration ${migration_file}: ${result.error}`,
+        };
+      }
+    }
+
+    return { success: true };
+  } catch (error) {
+    const error_message =
+      error instanceof Error ? error.message : "Unknown error";
+
+    return {
+      success: false,
+      error: error_message,
+    };
+  }
+}
+