hazo_auth 4.2.0 → 4.4.0

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

@@ -0,0 +1,73 @@
+// file_description: load ui shell layout settings from hazo_auth_config.ini
+// section: imports
+import { get_config_value } from "./config/config_loader.server.js";
+
+// section: types
+export type UiShellLayoutMode = "test_sidebar" | "standalone";
+
+export type UiShellConfig = {
+  layout_mode: UiShellLayoutMode;
+  standalone_heading: string;
+  standalone_description: string;
+  standalone_wrapper_class: string;
+  standalone_content_class: string;
+  standalone_show_heading: boolean;
+  standalone_show_description: boolean;
+};
+
+// section: helpers
+/**
+ * Reads ui shell configuration controlling whether pages use the sidebar test shell
+ * or a clean standalone wrapper that inherits consumer project styling.
+ */
+export function get_ui_shell_config(): UiShellConfig {
+  const section = "hazo_auth__ui_shell";
+
+  const layoutModeValue = get_config_value(section, "layout_mode", "test_sidebar").toLowerCase();
+  const layout_mode: UiShellLayoutMode =
+    layoutModeValue === "standalone" ? "standalone" : "test_sidebar";
+
+  const standalone_heading = get_config_value(
+    section,
+    "standalone_heading",
+    "Welcome to hazo auth"
+  );
+  const standalone_description = get_config_value(
+    section,
+    "standalone_description",
+    "Reuse the packaged authentication flows while inheriting your existing app shell styles."
+  );
+  const standalone_wrapper_class = get_config_value(
+    section,
+    "standalone_wrapper_class",
+    "cls_standalone_shell flex min-h-screen w-full items-center justify-center bg-background px-4 py-10"
+  );
+  const standalone_content_class = get_config_value(
+    section,
+    "standalone_content_class",
+    "cls_standalone_shell_content w-full max-w-5xl shadow-xl rounded-2xl border bg-card"
+  );
+  const standalone_show_heading = get_config_value(
+    section,
+    "standalone_show_heading",
+    "true"
+  ).toLowerCase() === "true";
+  const standalone_show_description = get_config_value(
+    section,
+    "standalone_show_description",
+    "true"
+  ).toLowerCase() === "true";
+
+  return {
+    layout_mode,
+    standalone_heading,
+    standalone_description,
+    standalone_wrapper_class,
+    standalone_content_class,
+    standalone_show_heading,
+    standalone_show_description,
+  };
+}
+
+
+

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

@@ -0,0 +1,37 @@
+// file_description: server-only helper to read UI size configuration from hazo_auth_config.ini
+// section: imports
+import { get_config_number } from "./config/config_loader.server.js";
+
+// section: types
+export type UISizesConfig = {
+  gravatar_size: number;
+  profile_picture_size: number;
+  tooltip_icon_size_default: number;
+  tooltip_icon_size_small: number;
+  library_photo_grid_columns: number;
+  library_photo_preview_size: number;
+  image_compression_max_dimension: number;
+  upload_file_hard_limit_bytes: number;
+};
+
+// section: helpers
+/**
+ * Reads UI size configuration from hazo_auth_config.ini file
+ * Falls back to defaults if hazo_auth_config.ini is not found or section is missing
+ * @returns UI sizes configuration options
+ */
+export function get_ui_sizes_config(): UISizesConfig {
+  const section = "hazo_auth__ui_sizes";
+
+  return {
+    gravatar_size: get_config_number(section, "gravatar_size", 200),
+    profile_picture_size: get_config_number(section, "profile_picture_size", 200),
+    tooltip_icon_size_default: get_config_number(section, "tooltip_icon_size_default", 16),
+    tooltip_icon_size_small: get_config_number(section, "tooltip_icon_size_small", 14),
+    library_photo_grid_columns: get_config_number(section, "library_photo_grid_columns", 4),
+    library_photo_preview_size: get_config_number(section, "library_photo_preview_size", 200),
+    image_compression_max_dimension: get_config_number(section, "image_compression_max_dimension", 200),
+    upload_file_hard_limit_bytes: get_config_number(section, "upload_file_hard_limit_bytes", 10485760), // 10MB
+  };
+}
+

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

@@ -0,0 +1,31 @@
+// file_description: server-only helper to read shared user fields configuration from hazo_auth_config.ini
+// section: imports
+import { get_config_boolean } from "./config/config_loader.server.js";
+
+// section: types
+export type UserFieldsConfig = {
+  show_name_field: boolean;
+  show_email_field: boolean;
+  show_password_field: boolean;
+};
+
+// section: helpers
+/**
+ * Reads shared user fields configuration from hazo_auth_config.ini file
+ * Falls back to defaults if hazo_auth_config.ini is not found or section is missing
+ * This configuration is used by register and my_settings layouts
+ * @returns User fields configuration options
+ */
+export function get_user_fields_config(): UserFieldsConfig {
+  // Read field visibility with defaults (all true by default)
+  const show_name_field = get_config_boolean("hazo_auth__user_fields", "show_name_field", true);
+  const show_email_field = get_config_boolean("hazo_auth__user_fields", "show_email_field", true);
+  const show_password_field = get_config_boolean("hazo_auth__user_fields", "show_password_field", true);
+
+  return {
+    show_name_field,
+    show_email_field,
+    show_password_field,
+  };
+}
+

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

@@ -0,0 +1,39 @@
+// file_description: server-only helper to read user management configuration from hazo_auth_config.ini
+// section: imports
+import { get_config_value, get_config_array, read_config_section } from "./config/config_loader.server.js";
+
+// section: types
+export type UserManagementConfig = {
+  application_permission_list_defaults: string[];
+};
+
+// section: helpers
+/**
+ * Reads user management configuration from hazo_auth_config.ini file
+ * Falls back to defaults if hazo_auth_config.ini is not found or section is missing
+ * @returns User management configuration options
+ */
+export function get_user_management_config(): UserManagementConfig {
+  // Try to read from hazo_auth__user_management section first
+  const user_management_section = read_config_section("hazo_auth__user_management");
+  const permissions_section = read_config_section("permissions");
+
+  // Try application_permission_list_defaults from user_management section
+  let permission_list: string[] = [];
+  
+  if (user_management_section?.application_permission_list_defaults) {
+    permission_list = get_config_array(
+      "hazo_auth__user_management",
+      "application_permission_list_defaults",
+      []
+    );
+  } else if (permissions_section?.list) {
+    // Fallback to permissions section list key
+    permission_list = get_config_array("permissions", "list", []);
+  }
+
+  return {
+    application_permission_list_defaults: permission_list,
+  };
+}
+

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

@@ -0,0 +1,55 @@
+// file_description: server-only helper to read user profiles cache configuration from hazo_auth_config.ini
+// section: imports
+import {
+  get_config_number,
+} from "./config/config_loader.server.js";
+
+// section: types
+
+/**
+ * User profiles cache configuration options
+ */
+export type UserProfilesCacheConfig = {
+  cache_enabled: boolean;
+  cache_max_entries: number;
+  cache_ttl_minutes: number;
+};
+
+// section: helpers
+
+/**
+ * Reads user profiles cache configuration from hazo_auth_config.ini file
+ * Falls back to defaults if hazo_auth_config.ini is not found or section is missing
+ * @returns User profiles cache configuration options
+ */
+export function get_user_profiles_cache_config(): UserProfilesCacheConfig {
+  const section_name = "hazo_auth__user_profiles";
+
+  // Cache settings
+  // cache_enabled: 0 = disabled, 1 = enabled (default: 1)
+  const cache_enabled_num = get_config_number(
+    section_name,
+    "cache_enabled",
+    1,
+  );
+  const cache_enabled = cache_enabled_num === 1;
+
+  const cache_max_entries = get_config_number(
+    section_name,
+    "cache_max_entries",
+    5000, // Default: 5000 entries
+  );
+
+  const cache_ttl_minutes = get_config_number(
+    section_name,
+    "cache_ttl_minutes",
+    5, // Default: 5 minutes
+  );
+
+  return {
+    cache_enabled,
+    cache_max_entries,
+    cache_ttl_minutes,
+  };
+}
+

package/cli-src/lib/utils/api_route_helpers.ts

@@ -0,0 +1,60 @@
+// file_description: shared helper functions for API routes to get filename and line number
+// section: helpers
+/**
+ * Gets the filename from the call stack
+ * This is a simplified version that extracts the filename from the error stack
+ * @returns Filename or "route.ts" as default
+ */
+export function get_filename(): string {
+  try {
+    const stack = new Error().stack;
+    if (!stack) {
+      return "route.ts";
+    }
+
+    // Parse stack trace to find the caller's file
+    const lines = stack.split("\n");
+    // Skip Error line and get_filename line, get the actual caller
+    for (let i = 2; i < lines.length; i++) {
+      const line = lines[i];
+      // Match file paths in stack trace (e.g., "at /path/to/file.ts:123:45")
+      const match = line.match(/([^/\\]+\.tsx?):(\d+):(\d+)/);
+      if (match) {
+        return match[1];
+      }
+    }
+    return "route.ts";
+  } catch {
+    return "route.ts";
+  }
+}
+
+/**
+ * Gets the line number from the call stack
+ * This is a simplified version that extracts the line number from the error stack
+ * @returns Line number or 0
+ */
+export function get_line_number(): number {
+  try {
+    const stack = new Error().stack;
+    if (!stack) {
+      return 0;
+    }
+
+    // Parse stack trace to find the caller's line number
+    const lines = stack.split("\n");
+    // Skip Error line and get_line_number line, get the actual caller
+    for (let i = 2; i < lines.length; i++) {
+      const line = lines[i];
+      // Match line numbers in stack trace (e.g., "at /path/to/file.ts:123:45")
+      const match = line.match(/([^/\\]+\.tsx?):(\d+):(\d+)/);
+      if (match) {
+        return parseInt(match[2], 10) || 0;
+      }
+    }
+    return 0;
+  } catch {
+    return 0;
+  }
+}
+

package/cli-src/lib/utils/error_sanitizer.ts

@@ -0,0 +1,75 @@
+// file_description: utility functions for sanitizing error messages for user display
+// section: imports
+import { create_app_logger } from "../app_logger.js";
+
+// section: constants
+const USER_FRIENDLY_ERROR_MESSAGE = "We are facing some issues in our system, please try again later.";
+
+// section: types
+export type ErrorSanitizationOptions = {
+  logToConsole?: boolean;
+  logToLogger?: boolean;
+  logger?: ReturnType<typeof create_app_logger>;
+  context?: Record<string, unknown>;
+};
+
+// section: helpers
+/**
+ * Sanitizes error messages for user display
+ * Replaces technical error messages with user-friendly ones
+ * @param error - The error object or message
+ * @param options - Options for logging and context
+ * @returns User-friendly error message
+ */
+export function sanitize_error_for_user(
+  error: unknown,
+  options: ErrorSanitizationOptions = {}
+): string {
+  const { logToConsole = true, logToLogger = true, logger, context = {} } = options;
+
+  // Extract detailed error message
+  const detailed_error_message =
+    error instanceof Error ? error.message : String(error);
+  const error_stack = error instanceof Error ? error.stack : undefined;
+
+  // Log detailed error to console
+  if (logToConsole) {
+    console.error("Detailed error:", {
+      message: detailed_error_message,
+      stack: error_stack,
+      ...context,
+    });
+  }
+
+  // Log detailed error to logger if provided
+  if (logToLogger && logger) {
+    logger.error("error_occurred", {
+      filename: context.filename as string || "unknown",
+      line_number: context.line_number as number || 0,
+      error_message: detailed_error_message,
+      error_stack,
+      ...context,
+    });
+  }
+
+  // Check if error is a PostgREST or database-related error
+  const is_database_error =
+    detailed_error_message.includes("PostgREST") ||
+    detailed_error_message.includes("403 Forbidden") ||
+    detailed_error_message.includes("404 Not Found") ||
+    detailed_error_message.includes("500 Internal Server Error") ||
+    detailed_error_message.includes("database") ||
+    detailed_error_message.includes("connection") ||
+    detailed_error_message.includes("timeout");
+
+  // Return user-friendly message for database/API errors
+  if (is_database_error) {
+    return USER_FRIENDLY_ERROR_MESSAGE;
+  }
+
+  // For other errors, return the original message (could be user-friendly already)
+  // But still log the detailed error
+  return detailed_error_message;
+}
+
+

package/cli-src/lib/utils/password_validator.ts

@@ -0,0 +1,65 @@
+// file_description: server-side password validation utility
+// section: types
+export type PasswordRequirementOptions = {
+  minimum_length: number;
+  require_uppercase: boolean;
+  require_lowercase: boolean;
+  require_number: boolean;
+  require_special: boolean;
+};
+
+export type PasswordValidationResult = {
+  valid: boolean;
+  errors: string[];
+};
+
+// section: helpers
+/**
+ * Validates a password against specified requirements (server-side version)
+ * @param password - The password to validate
+ * @param requirements - Password requirement options
+ * @returns Validation result with valid flag and error messages
+ */
+export function validate_password(
+  password: string,
+  requirements: PasswordRequirementOptions
+): PasswordValidationResult {
+  const errors: string[] = [];
+
+  if (!password || password.trim().length === 0) {
+    return {
+      valid: false,
+      errors: ["Password is required"],
+    };
+  }
+
+  if (password.length < requirements.minimum_length) {
+    errors.push(
+      `Password must be at least ${requirements.minimum_length} characters`
+    );
+  }
+
+  if (requirements.require_uppercase && !/[A-Z]/.test(password)) {
+    errors.push("Password must include at least one uppercase letter");
+  }
+
+  if (requirements.require_lowercase && !/[a-z]/.test(password)) {
+    errors.push("Password must include at least one lowercase letter");
+  }
+
+  if (requirements.require_number && !/\d/.test(password)) {
+    errors.push("Password must include at least one number");
+  }
+
+  if (
+    requirements.require_special &&
+    !/[!@#$%^&*(),.?":{}|<>\-_+=\[\];'/\\]/.test(password)
+  ) {
+    errors.push("Password must include at least one special character");
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}

package/cli-src/lib/utils.ts

@@ -0,0 +1,11 @@
+// file_description: provide shared utility helpers for the hazo_auth project
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+// section: tailwind_merge_helper
+export function merge_class_names(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}
+
+// section: shadcn_compatibility_helper
+export const cn = (...inputs: ClassValue[]) => merge_class_names(...inputs);

package/cli-src/server/logging/logger_service.ts

@@ -0,0 +1,56 @@
+// file_description: expose the logging facade used across the hazo_auth backend
+// section: imports
+import type { logger_method, logger_service } from "../types/app_types";
+
+// section: helper_functions
+const create_console_logger = (namespace: string): logger_service => {
+  const write = (level: string, message: string, data?: Record<string, unknown>) => {
+    const timestamp = new Date().toISOString();
+    // eslint-disable-next-line no-console
+    console.log(
+      JSON.stringify({
+        namespace,
+        level,
+        message,
+        data,
+        timestamp,
+      })
+    );
+  };
+
+  return {
+    debug: (message, data) => write("debug", message, data),
+    info: (message, data) => write("info", message, data),
+    warn: (message, data) => write("warn", message, data),
+    error: (message, data) => write("error", message, data),
+  };
+};
+
+// section: factory
+export const create_logger_service = (
+  namespace: string,
+  external_logger?: Partial<logger_service>
+): logger_service => {
+  const console_logger = create_console_logger(namespace);
+
+  const safe_bind = (
+    level: keyof logger_service,
+    fallback: logger_method
+  ): logger_method => {
+    const candidate = external_logger?.[level];
+    if (typeof candidate === "function") {
+      return (message, data) => candidate(message, data);
+    }
+    return fallback;
+  };
+
+  type logger_method = (message: string, data?: Record<string, unknown>) => void;
+
+  return {
+    debug: safe_bind("debug", console_logger.debug),
+    info: safe_bind("info", console_logger.info),
+    warn: safe_bind("warn", console_logger.warn),
+    error: safe_bind("error", console_logger.error),
+  };
+};
+

package/cli-src/server/types/app_types.ts

@@ -0,0 +1,74 @@
+// file_description: define shared application level types for the hazo_auth server
+// section: request_context_types
+import type { Request } from "express";
+
+// section: logger_interface_definition
+export type logger_method = (
+  message: string,
+  data?: Record<string, unknown>
+) => void;
+
+export type logger_service = {
+  debug: logger_method;
+  info: logger_method;
+  warn: logger_method;
+  error: logger_method;
+};
+
+// section: configuration_types
+export type emailer_client = {
+  send_message: (
+    payload: Record<string, unknown>
+  ) => Promise<{ success: boolean }>;
+};
+
+export type handlebars_templates = Record<string, string>;
+
+export type password_policy = {
+  min_length: number;
+  requires_uppercase: boolean;
+  requires_lowercase: boolean;
+  requires_number: boolean;
+  requires_symbol: boolean;
+};
+
+export type token_settings = {
+  access_token_ttl_seconds: number;
+  refresh_token_ttl_seconds: number;
+};
+
+export type rate_limit_settings = {
+  max_attempts: number;
+  window_minutes: number;
+};
+
+export type captcha_settings =
+  | {
+      provider: "recaptcha_v2" | "recaptcha_v3" | "hcaptcha";
+      secret_key: string;
+    }
+  | undefined;
+
+export type runtime_configuration = {
+  permission_names: string[];
+  logger: logger_service;
+  emailer: emailer_client;
+  templates: handlebars_templates;
+  labels: Record<string, string>;
+  styles: Record<string, string>;
+  password_policy: password_policy;
+  token_settings: token_settings;
+  rate_limit: rate_limit_settings;
+  captcha: captcha_settings;
+};
+
+export type app_context = {
+  config: runtime_configuration;
+};
+
+// section: typed_request_wrapper
+export type context_request<T = unknown> = Request & {
+  body: T;
+  context: app_context;
+};
+

package/cli-src/server/types/express.d.ts

@@ -0,0 +1,16 @@
+// file_description: augment express request with hazo_auth context
+import type { app_context } from "./app_types";
+
+declare global {
+  namespace Express {
+    interface Request {
+      context: app_context;
+    }
+  }
+}
+
+export {};
+
+
+
+

package/dist/cli/index.js

@@ -5,6 +5,7 @@
 import { run_validation } from "./validate.js";
 import { generate_routes } from "./generate.js";
 import { handle_init } from "./init.js";
+import { handle_init_users, show_init_users_help } from "./init_users.js";
 // section: constants
 const VERSION = "1.6.0";
 const HELP_TEXT = `
@@ -14,6 +15,7 @@ Usage: hazo_auth <command> [options]
 
 Commands:
   init               Initialize hazo_auth in your project (creates directories, copies config)
+  init-users         Initialize permissions, roles, and super user from config
   validate           Check your hazo_auth setup and configuration
   generate-routes    Generate API route files and pages in your project
 
@@ -23,6 +25,7 @@ Options:
 
 Examples:
   npx hazo_auth init
+  npx hazo_auth init-users
   npx hazo_auth validate
   npx hazo_auth generate-routes
   npx hazo_auth generate-routes --pages
@@ -139,6 +142,21 @@ Actions:
             }
             handle_init();
             break;
+        case "init-users": {
+            if (help) {
+                show_init_users_help();
+                return;
+            }
+            // Parse --email option
+            let email;
+            for (const arg of args) {
+                if (arg.startsWith("--email=")) {
+                    email = arg.replace("--email=", "");
+                }
+            }
+            await handle_init_users({ email });
+            break;
+        }
         case "validate":
             if (help) {
                 console.log(`

package/dist/cli/init_users.d.ts

@@ -0,0 +1,17 @@
+export type InitUsersOptions = {
+    /** Email address of the user to assign super user role (overrides config) */
+    email?: string;
+};
+/**
+ * Initializes users, roles, and permissions from configuration
+ * This function reads from hazo_auth_config.ini and sets up:
+ * 1. Permissions from [hazo_auth__user_management] application_permission_list_defaults
+ * 2. A default_super_user_role with all permissions
+ * 3. Assigns the role to user from --email parameter or [hazo_auth__initial_setup] default_super_user_email
+ */
+export declare function handle_init_users(options?: InitUsersOptions): Promise<void>;
+/**
+ * Shows help for the init-users command
+ */
+export declare function show_init_users_help(): void;
+//# sourceMappingURL=init_users.d.ts.map

package/dist/cli/init_users.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init_users.d.ts","sourceRoot":"","sources":["../../src/cli/init_users.ts"],"names":[],"mappings":"AAqFA,MAAM,MAAM,gBAAgB,GAAG;IAC7B,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAGF;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CA+OrF;AAGD;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAgC3C"}