hazo_auth 4.1.0 → 4.3.0

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

@@ -0,0 +1,136 @@
+// file_description: server-only helper to read auth utility configuration from hazo_auth_config.ini
+// section: imports
+import {
+  get_config_value,
+  get_config_number,
+  get_config_boolean,
+  get_config_array,
+} from "./config/config_loader.server";
+
+// section: types
+
+/**
+ * Auth utility configuration options
+ */
+export type AuthUtilityConfig = {
+  cache_max_users: number;
+  cache_ttl_minutes: number;
+  cache_max_age_minutes: number;
+  rate_limit_per_user: number;
+  rate_limit_per_ip: number;
+  log_permission_denials: boolean;
+  enable_friendly_error_messages: boolean;
+  permission_error_messages: Map<string, string>; // permission -> user-friendly message
+};
+
+// section: helpers
+
+/**
+ * Parses permission error messages from config string
+ * Format: "permission1:message1,permission2:message2"
+ * @param config_value - Config string value
+ * @returns Map of permission to user-friendly message
+ */
+function parse_permission_messages(
+  config_value: string,
+): Map<string, string> {
+  const messages = new Map<string, string>();
+
+  if (!config_value || config_value.trim().length === 0) {
+    return messages;
+  }
+
+  const pairs = config_value.split(",");
+  for (const pair of pairs) {
+    const trimmed = pair.trim();
+    if (trimmed.length === 0) {
+      continue;
+    }
+
+    const colon_index = trimmed.indexOf(":");
+    if (colon_index === -1) {
+      continue; // Skip invalid format
+    }
+
+    const permission = trimmed.substring(0, colon_index).trim();
+    const message = trimmed.substring(colon_index + 1).trim();
+
+    if (permission.length > 0 && message.length > 0) {
+      messages.set(permission, message);
+    }
+  }
+
+  return messages;
+}
+
+/**
+ * Reads auth utility configuration from hazo_auth_config.ini file
+ * Falls back to defaults if hazo_auth_config.ini is not found or section is missing
+ * @returns Auth utility configuration options
+ */
+export function get_auth_utility_config(): AuthUtilityConfig {
+  const section_name = "hazo_auth__auth_utility";
+
+  // Cache settings
+  const cache_max_users = get_config_number(
+    section_name,
+    "cache_max_users",
+    10000,
+  );
+  const cache_ttl_minutes = get_config_number(
+    section_name,
+    "cache_ttl_minutes",
+    5, // Default: 5 minutes
+  );
+  const cache_max_age_minutes = get_config_number(
+    section_name,
+    "cache_max_age_minutes",
+    10, // Default: 10 minutes (force refresh threshold)
+  );
+
+  // Rate limiting
+  const rate_limit_per_user = get_config_number(
+    section_name,
+    "rate_limit_per_user",
+    100,
+  );
+  const rate_limit_per_ip = get_config_number(
+    section_name,
+    "rate_limit_per_ip",
+    200,
+  );
+
+  // Permission check behavior
+  const log_permission_denials = get_config_boolean(
+    section_name,
+    "log_permission_denials",
+    true,
+  );
+  const enable_friendly_error_messages = get_config_boolean(
+    section_name,
+    "enable_friendly_error_messages",
+    true,
+  );
+
+  // Permission message mappings
+  const permission_messages_str = get_config_value(
+    section_name,
+    "permission_error_messages",
+    "",
+  );
+  const permission_error_messages = parse_permission_messages(
+    permission_messages_str,
+  );
+
+  return {
+    cache_max_users,
+    cache_ttl_minutes,
+    cache_max_age_minutes,
+    rate_limit_per_user,
+    rate_limit_per_ip,
+    log_permission_denials,
+    enable_friendly_error_messages,
+    permission_error_messages,
+  };
+}
+

package/cli-src/lib/config/config_loader.server.ts

@@ -0,0 +1,164 @@
+// file_description: shared utility for reading configuration from hazo_auth_config.ini using hazo_config
+// section: imports
+import { HazoConfig } from "hazo_config/dist/lib";
+import path from "path";
+import fs from "fs";
+import { create_app_logger } from "../app_logger";
+
+// section: constants
+const DEFAULT_CONFIG_FILE = "hazo_auth_config.ini";
+
+// section: helpers
+/**
+ * Gets the default config file path
+ * @param custom_path - Optional custom config file path
+ * @returns Resolved config file path
+ */
+function get_config_file_path(custom_path?: string): string {
+  if (custom_path) {
+    return path.isAbsolute(custom_path) ? custom_path : path.resolve(process.cwd(), custom_path);
+  }
+  return path.resolve(process.cwd(), DEFAULT_CONFIG_FILE);
+}
+
+/**
+ * Reads a section from the config file
+ * @param section_name - Name of the section to read (e.g., "hazo_auth__register_layout")
+ * @param file_path - Optional custom config file path (defaults to hazo_auth_config.ini)
+ * @returns Section data as Record<string, string> or undefined if not found
+ */
+export function read_config_section(
+  section_name: string,
+  file_path?: string,
+): Record<string, string> | undefined {
+  const config_path = get_config_file_path(file_path);
+  const logger = create_app_logger();
+
+  if (!fs.existsSync(config_path)) {
+    return undefined;
+  }
+
+  try {
+    const hazo_config = new HazoConfig({
+      filePath: config_path,
+    });
+    return hazo_config.getSection(section_name);
+  } catch (error) {
+    const error_message = error instanceof Error ? error.message : "Unknown error";
+    logger.warn("config_loader_read_section_failed", {
+      filename: "config_loader.server.ts",
+      line_number: 0,
+      section_name,
+      config_path,
+      error: error_message,
+    });
+    return undefined;
+  }
+}
+
+/**
+ * Gets a single config value from a section
+ * @param section_name - Name of the section
+ * @param key - Key name within the section
+ * @param default_value - Default value if key is not found
+ * @param file_path - Optional custom config file path
+ * @returns Config value as string or default value
+ */
+export function get_config_value(
+  section_name: string,
+  key: string,
+  default_value: string,
+  file_path?: string,
+): string {
+  const section = read_config_section(section_name, file_path);
+  // Optional chaining on section and section[key]
+  // If section is undefined, or key is undefined, fall back to default
+  if (!section || section[key] === undefined) {
+    return default_value;
+  }
+  return section[key].trim() || default_value;
+}
+
+/**
+ * Gets a boolean config value from a section
+ * @param section_name - Name of the section
+ * @param key - Key name within the section
+ * @param default_value - Default boolean value if key is not found
+ * @param file_path - Optional custom config file path
+ * @returns Config value as boolean
+ */
+export function get_config_boolean(
+  section_name: string,
+  key: string,
+  default_value: boolean,
+  file_path?: string,
+): boolean {
+  const section = read_config_section(section_name, file_path);
+  
+  if (!section || section[key] === undefined) {
+    return default_value;
+  }
+  
+  const value = section[key].trim().toLowerCase();
+  return value !== "false" && value !== "0" && value !== "";
+}
+
+/**
+ * Gets a number config value from a section
+ * @param section_name - Name of the section
+ * @param key - Key name within the section
+ * @param default_value - Default number value if key is not found or invalid
+ * @param file_path - Optional custom config file path
+ * @returns Config value as number
+ */
+export function get_config_number(
+  section_name: string,
+  key: string,
+  default_value: number,
+  file_path?: string,
+): number {
+  const section = read_config_section(section_name, file_path);
+  
+  if (!section || section[key] === undefined) {
+    return default_value;
+  }
+  
+  const value = section[key].trim();
+  
+  if (!value) {
+    return default_value;
+  }
+  
+  const parsed = parseFloat(value);
+  return isNaN(parsed) ? default_value : parsed;
+}
+
+/**
+ * Gets a comma-separated list config value from a section
+ * @param section_name - Name of the section
+ * @param key - Key name within the section
+ * @param default_value - Default array value if key is not found
+ * @param file_path - Optional custom config file path
+ * @returns Config value as array of strings
+ */
+export function get_config_array(
+  section_name: string,
+  key: string,
+  default_value: string[],
+  file_path?: string,
+): string[] {
+  const section = read_config_section(section_name, file_path);
+  
+  if (!section || section[key] === undefined) {
+    return default_value;
+  }
+  
+  const value = section[key].trim();
+  
+  if (!value) {
+    return default_value;
+  }
+  
+  return value.split(",").map((item) => item.trim()).filter((item) => item.length > 0);
+}
+

package/cli-src/lib/config/default_config.ts

@@ -0,0 +1,199 @@
+// file_description: Centralized default configuration for hazo_auth
+// All default values in one place for easy reference and maintenance
+// These defaults are used when hazo_auth_config.ini is missing or incomplete
+
+// section: password_requirements
+export const DEFAULT_PASSWORD_REQUIREMENTS = {
+  minimum_length: 8,
+  require_uppercase: false,
+  require_lowercase: false,
+  require_number: false,
+  require_special: false,
+} as const;
+
+// section: user_fields
+export const DEFAULT_USER_FIELDS = {
+  show_name_field: true,
+  show_email_field: true,
+  show_password_field: true,
+} as const;
+
+// section: profile_picture
+export const DEFAULT_PROFILE_PICTURE = {
+  allow_photo_upload: true,
+  max_photo_size: 5242880, // 5MB in bytes
+  user_photo_default: true,
+  user_photo_default_priority1: "gravatar" as const,
+  user_photo_default_priority2: "library" as const,
+  library_photo_path: "/profile_pictures/library",
+} as const;
+
+// section: ui_sizes
+export const DEFAULT_UI_SIZES = {
+  gravatar_size: 200,
+  profile_picture_size: 128,
+  tooltip_icon_size_default: 16,
+  tooltip_icon_size_small: 14,
+  library_photo_grid_columns: 4,
+  library_photo_preview_size: 80,
+  image_compression_max_dimension: 800,
+  upload_file_hard_limit_bytes: 10485760, // 10MB
+} as const;
+
+// section: file_types
+export const DEFAULT_FILE_TYPES = {
+  allowed_image_extensions: [".jpg", ".jpeg", ".png", ".gif", ".webp"],
+  allowed_image_mime_types: ["image/jpeg", "image/png", "image/gif", "image/webp"],
+} as const;
+
+// section: messages
+export const DEFAULT_MESSAGES = {
+  photo_upload_disabled_message: "Photo upload is currently disabled. Contact your administrator.",
+  gravatar_setup_message: "To use Gravatar, create a free account at gravatar.com with the same email address you use here.",
+  gravatar_no_account_message: "No Gravatar account found for your email. Using library photo instead.",
+  library_tooltip_message: "Choose from our library of profile pictures",
+} as const;
+
+// section: already_logged_in
+export const DEFAULT_ALREADY_LOGGED_IN = {
+  message: "You are already logged in",
+  showLogoutButton: true,
+  showReturnHomeButton: true,
+  returnHomeButtonLabel: "Return Home",
+  returnHomePath: "/",
+} as const;
+
+// section: login
+export const DEFAULT_LOGIN = {
+  redirectRoute: undefined as string | undefined,
+  successMessage: "Successfully logged in",
+  forgotPasswordPath: "/hazo_auth/forgot_password",
+  forgotPasswordLabel: "Forgot password?",
+  createAccountPath: "/hazo_auth/register",
+  createAccountLabel: "Create account",
+} as const;
+
+// section: register
+export const DEFAULT_REGISTER = {
+  redirectRoute: undefined as string | undefined,
+  successMessage: "Registration successful! Please check your email to verify your account.",
+  loginPath: "/hazo_auth/login",
+  loginLabel: "Already have an account? Sign in",
+  requireEmailVerification: true,
+} as const;
+
+// section: forgot_password
+export const DEFAULT_FORGOT_PASSWORD = {
+  successMessage: "If an account with that email exists, a password reset link has been sent.",
+  loginPath: "/hazo_auth/login",
+  loginLabel: "Back to login",
+} as const;
+
+// section: reset_password
+export const DEFAULT_RESET_PASSWORD = {
+  successMessage: "Password reset successfully. You can now log in with your new password.",
+  loginPath: "/hazo_auth/login",
+  redirectDelay: 2, // seconds
+} as const;
+
+// section: email_verification
+export const DEFAULT_EMAIL_VERIFICATION = {
+  successMessage: "Email verified successfully! Redirecting to login...",
+  errorMessage: "Email verification failed. The link may have expired.",
+  loginPath: "/hazo_auth/login",
+  redirectDelay: 5, // seconds
+} as const;
+
+// section: my_settings
+export const DEFAULT_MY_SETTINGS = {
+  showNameField: true,
+  showEmailField: true,
+  showPasswordField: true,
+  showProfilePicture: true,
+} as const;
+
+// section: user_management
+export const DEFAULT_USER_MANAGEMENT = {
+  enableUserManagement: true,
+  enableRoleManagement: true,
+  enablePermissionManagement: true,
+} as const;
+
+// section: auth_utility
+export const DEFAULT_AUTH_UTILITY = {
+  sessionCookieName: "hazo_session",
+  sessionDuration: 86400, // 24 hours in seconds
+  requireEmailVerification: true,
+} as const;
+
+// section: ui_shell
+export const DEFAULT_UI_SHELL = {
+  layout_mode: "standalone" as "standalone" | "test_sidebar",
+  image_src: "/globe.svg",
+  image_width: 400,
+  image_height: 400,
+  show_visual_panel: true,
+} as const;
+
+// section: profile_pic_menu
+export const DEFAULT_PROFILE_PIC_MENU = {
+  show_single_button: false,
+  sign_up_label: "Sign Up",
+  sign_in_label: "Sign In",
+  register_path: "/hazo_auth/register",
+  login_path: "/hazo_auth/login",
+  settings_path: "/hazo_auth/my_settings",
+  logout_path: "/api/hazo_auth/logout",
+} as const;
+
+// section: api_paths
+export const DEFAULT_API_PATHS = {
+  apiBasePath: "/api/hazo_auth",
+} as const;
+
+// section: oauth
+export const DEFAULT_OAUTH = {
+  /** Enable Google OAuth login (requires HAZO_AUTH_GOOGLE_CLIENT_ID and HAZO_AUTH_GOOGLE_CLIENT_SECRET env vars) */
+  enable_google: true,
+  /** Enable traditional email/password login */
+  enable_email_password: true,
+  /** Auto-link Google login to existing unverified email/password accounts and mark as verified */
+  auto_link_unverified_accounts: true,
+  /** Text displayed on the Google sign-in button */
+  google_button_text: "Continue with Google",
+  /** Text displayed on the divider between OAuth and email/password form */
+  oauth_divider_text: "or continue with email",
+} as const;
+
+// section: combined_defaults
+/**
+ * All default configuration values combined in one object
+ * This makes it easy to see all defaults at a glance and export them as needed
+ */
+export const HAZO_AUTH_DEFAULTS = {
+  passwordRequirements: DEFAULT_PASSWORD_REQUIREMENTS,
+  userFields: DEFAULT_USER_FIELDS,
+  profilePicture: DEFAULT_PROFILE_PICTURE,
+  uiSizes: DEFAULT_UI_SIZES,
+  fileTypes: DEFAULT_FILE_TYPES,
+  messages: DEFAULT_MESSAGES,
+  alreadyLoggedIn: DEFAULT_ALREADY_LOGGED_IN,
+  login: DEFAULT_LOGIN,
+  register: DEFAULT_REGISTER,
+  forgotPassword: DEFAULT_FORGOT_PASSWORD,
+  resetPassword: DEFAULT_RESET_PASSWORD,
+  emailVerification: DEFAULT_EMAIL_VERIFICATION,
+  mySettings: DEFAULT_MY_SETTINGS,
+  userManagement: DEFAULT_USER_MANAGEMENT,
+  authUtility: DEFAULT_AUTH_UTILITY,
+  uiShell: DEFAULT_UI_SHELL,
+  profilePicMenu: DEFAULT_PROFILE_PIC_MENU,
+  apiPaths: DEFAULT_API_PATHS,
+  oauth: DEFAULT_OAUTH,
+} as const;
+
+// section: types
+/**
+ * Type representing the complete default configuration structure
+ */
+export type HazoAuthDefaults = typeof HAZO_AUTH_DEFAULTS;

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

@@ -0,0 +1,63 @@
+// file_description: server-only helper to read email verification layout configuration from hazo_auth_config.ini
+// section: imports
+import { get_already_logged_in_config } from "./already_logged_in_config.server";
+import { get_config_value } from "./config/config_loader.server";
+import verifyEmailDefaultImage from "../assets/images/verify_email_default.jpg";
+
+// section: types
+import type { StaticImageData } from "next/image";
+
+export type EmailVerificationConfig = {
+  alreadyLoggedInMessage: string;
+  showLogoutButton: boolean;
+  showReturnHomeButton: boolean;
+  returnHomeButtonLabel: string;
+  returnHomePath: string;
+  imageSrc: string | StaticImageData;
+  imageAlt: string;
+  imageBackgroundColor: string;
+};
+
+// section: helpers
+/**
+ * Reads email verification 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 Email verification configuration options
+ */
+export function get_email_verification_config(): EmailVerificationConfig {
+  const section = "hazo_auth__email_verification_layout";
+
+  // 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
+  ) || verifyEmailDefaultImage;
+
+  const imageAlt = get_config_value(
+    section,
+    "image_alt",
+    "Email verification illustration"
+  );
+  const imageBackgroundColor = get_config_value(
+    section,
+    "image_background_color",
+    "#f1f5f9"
+  );
+
+  return {
+    alreadyLoggedInMessage: alreadyLoggedInConfig.message,
+    showLogoutButton: alreadyLoggedInConfig.showLogoutButton,
+    showReturnHomeButton: alreadyLoggedInConfig.showReturnHomeButton,
+    returnHomeButtonLabel: alreadyLoggedInConfig.returnHomeButtonLabel,
+    returnHomePath: alreadyLoggedInConfig.returnHomePath,
+    imageSrc,
+    imageAlt,
+    imageBackgroundColor,
+  };
+}
+

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

@@ -0,0 +1,25 @@
+// file_description: server-only helper to read file type configuration from hazo_auth_config.ini
+// section: imports
+import { get_config_array } from "./config/config_loader.server";
+
+// section: types
+export type FileTypesConfig = {
+  allowed_image_extensions: string[];
+  allowed_image_mime_types: string[];
+};
+
+// section: helpers
+/**
+ * Reads file type configuration from hazo_auth_config.ini file
+ * Falls back to defaults if hazo_auth_config.ini is not found or section is missing
+ * @returns File types configuration options
+ */
+export function get_file_types_config(): FileTypesConfig {
+  const section = "hazo_auth__file_types";
+
+  return {
+    allowed_image_extensions: get_config_array(section, "allowed_image_extensions", ["jpg", "jpeg", "png"]),
+    allowed_image_mime_types: get_config_array(section, "allowed_image_mime_types", ["image/jpeg", "image/jpg", "image/png"]),
+  };
+}
+

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

@@ -0,0 +1,63 @@
+// file_description: server-only helper to read forgot password layout configuration from hazo_auth_config.ini
+// section: imports
+import { get_already_logged_in_config } from "./already_logged_in_config.server";
+import { get_config_value } from "./config/config_loader.server";
+import forgotPasswordDefaultImage from "../assets/images/forgot_password_default.jpg";
+
+// section: types
+import type { StaticImageData } from "next/image";
+
+export type ForgotPasswordConfig = {
+  alreadyLoggedInMessage: string;
+  showLogoutButton: boolean;
+  showReturnHomeButton: boolean;
+  returnHomeButtonLabel: string;
+  returnHomePath: string;
+  imageSrc: string | StaticImageData;
+  imageAlt: string;
+  imageBackgroundColor: string;
+};
+
+// section: helpers
+/**
+ * Reads forgot password 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 Forgot password configuration options
+ */
+export function get_forgot_password_config(): ForgotPasswordConfig {
+  const section = "hazo_auth__forgot_password_layout";
+
+  // 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
+  ) || forgotPasswordDefaultImage;
+
+  const imageAlt = get_config_value(
+    section,
+    "image_alt",
+    "Password recovery illustration"
+  );
+  const imageBackgroundColor = get_config_value(
+    section,
+    "image_background_color",
+    "#f1f5f9"
+  );
+
+  return {
+    alreadyLoggedInMessage: alreadyLoggedInConfig.message,
+    showLogoutButton: alreadyLoggedInConfig.showLogoutButton,
+    showReturnHomeButton: alreadyLoggedInConfig.showReturnHomeButton,
+    returnHomeButtonLabel: alreadyLoggedInConfig.returnHomeButtonLabel,
+    returnHomePath: alreadyLoggedInConfig.returnHomePath,
+    imageSrc,
+    imageAlt,
+    imageBackgroundColor,
+  };
+}
+