hazo_auth 4.2.0 → 4.3.0

package/cli-src/lib/services/profile_picture_service.ts

@@ -0,0 +1,451 @@
+// file_description: service for profile picture management including default photo logic, Gravatar, and library photos
+// section: imports
+import type { HazoConnectAdapter } from "hazo_connect";
+import { createCrudService } from "hazo_connect/server";
+import gravatarUrl from "gravatar-url";
+import { get_profile_picture_config } from "../profile_picture_config.server";
+import { get_ui_sizes_config } from "../ui_sizes_config.server";
+import { get_file_types_config } from "../file_types_config.server";
+import { create_app_logger } from "../app_logger";
+import path from "path";
+import fs from "fs";
+import { map_ui_source_to_db, type ProfilePictureSourceUI } from "./profile_picture_source_mapper";
+
+// section: types
+export type ProfilePictureSource = ProfilePictureSourceUI;
+
+export type DefaultProfilePictureResult = {
+  profile_picture_url: string;
+  profile_source: ProfilePictureSource;
+};
+
+export type LibraryPhotosResult = {
+  photos: string[];
+  total: number;
+  page: number;
+  page_size: number;
+  has_more: boolean;
+  source: "project" | "node_modules";
+};
+
+// section: cache
+// Cache the resolved library path to avoid repeated filesystem checks
+let cached_library_path: string | null = null;
+let cached_library_source: "project" | "node_modules" | null = null;
+
+// section: helpers
+/**
+ * Resolves the library path, checking project's public folder first, then node_modules
+ * @returns Object with path and source, or null if not found
+ */
+function resolve_library_path(): { path: string; source: "project" | "node_modules" } | null {
+  // Return cached value if available
+  if (cached_library_path && cached_library_source) {
+    if (fs.existsSync(cached_library_path)) {
+      return { path: cached_library_path, source: cached_library_source };
+    }
+    // Cache is stale, clear it
+    cached_library_path = null;
+    cached_library_source = null;
+  }
+
+  const config = get_profile_picture_config();
+  const library_subpath = config.library_photo_path.replace(/^\//, "");
+
+  // Try 1: Project's public folder
+  const project_library_path = path.resolve(process.cwd(), "public", library_subpath);
+  if (fs.existsSync(project_library_path)) {
+    // Check if it has any content (not just empty directory)
+    try {
+      const entries = fs.readdirSync(project_library_path);
+      if (entries.length > 0) {
+        cached_library_path = project_library_path;
+        cached_library_source = "project";
+        return { path: project_library_path, source: "project" };
+      }
+    } catch {
+      // Continue to fallback
+    }
+  }
+
+  // Try 2: node_modules/hazo_auth/public folder
+  const node_modules_library_path = path.resolve(
+    process.cwd(),
+    "node_modules",
+    "hazo_auth",
+    "public",
+    library_subpath
+  );
+  if (fs.existsSync(node_modules_library_path)) {
+    cached_library_path = node_modules_library_path;
+    cached_library_source = "node_modules";
+    return { path: node_modules_library_path, source: "node_modules" };
+  }
+
+  return null;
+}
+
+/**
+ * Generates Gravatar URL from email address
+ * @param email - User's email address
+ * @param size - Image size in pixels (defaults to config value)
+ * @returns Gravatar URL
+ */
+export function get_gravatar_url(email: string, size?: number): string {
+  const uiSizes = get_ui_sizes_config();
+  const gravatarSize = size || uiSizes.gravatar_size;
+  return gravatarUrl(email, {
+    size: gravatarSize,
+    default: "identicon",
+  });
+}
+
+/**
+ * Gets library photo categories by reading subdirectories
+ * @returns Array of category names
+ */
+export function get_library_categories(): string[] {
+  const resolved = resolve_library_path();
+  
+  if (!resolved) {
+    return [];
+  }
+
+  try {
+    const entries = fs.readdirSync(resolved.path, { withFileTypes: true });
+    return entries
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name)
+      .sort();
+  } catch (error) {
+    const logger = create_app_logger();
+    const error_message = error instanceof Error ? error.message : "Unknown error";
+    logger.warn("profile_picture_service_read_categories_failed", {
+      filename: "profile_picture_service.ts",
+      line_number: 0,
+      library_path: resolved.path,
+      source: resolved.source,
+      error: error_message,
+    });
+    return [];
+  }
+}
+
+/**
+ * Gets photos in a specific library category with pagination support
+ * @param category - Category name
+ * @param page - Page number (1-indexed, default 1)
+ * @param page_size - Number of photos per page (default 20, max 100)
+ * @returns Object with photos array and pagination info
+ */
+export function get_library_photos_paginated(
+  category: string,
+  page: number = 1,
+  page_size: number = 20
+): LibraryPhotosResult {
+  const resolved = resolve_library_path();
+  const config = get_profile_picture_config();
+  
+  // Ensure page_size is within bounds
+  const effective_page_size = Math.min(Math.max(1, page_size), 100);
+  const effective_page = Math.max(1, page);
+
+  if (!resolved) {
+    return {
+      photos: [],
+      total: 0,
+      page: effective_page,
+      page_size: effective_page_size,
+      has_more: false,
+      source: "project",
+    };
+  }
+
+  const category_path = path.join(resolved.path, category);
+  
+  if (!fs.existsSync(category_path)) {
+    return {
+      photos: [],
+      total: 0,
+      page: effective_page,
+      page_size: effective_page_size,
+      has_more: false,
+      source: resolved.source,
+    };
+  }
+
+  try {
+    const fileTypes = get_file_types_config();
+    const allowedExtensions = fileTypes.allowed_image_extensions.map(ext => 
+      ext.startsWith(".") ? ext.toLowerCase() : `.${ext.toLowerCase()}`
+    );
+    
+    const entries = fs.readdirSync(category_path, { withFileTypes: true });
+    const all_photos = entries
+      .filter((entry) => {
+        if (!entry.isFile()) return false;
+        const ext = path.extname(entry.name).toLowerCase();
+        return allowedExtensions.includes(ext);
+      })
+      .map((entry) => entry.name)
+      .sort();
+
+    const total = all_photos.length;
+    const start_index = (effective_page - 1) * effective_page_size;
+    const end_index = start_index + effective_page_size;
+    const page_photos = all_photos.slice(start_index, end_index);
+
+    // Generate URLs based on source
+    // For node_modules source, we need to serve via API route
+    const photo_urls = page_photos.map((filename) => {
+      if (resolved.source === "node_modules") {
+        // Serve via API route that reads from node_modules
+        return `/api/hazo_auth/library_photo/${category}/${filename}`;
+      } else {
+        // Serve directly from public folder
+        return `${config.library_photo_path}/${category}/${filename}`;
+      }
+    });
+
+    return {
+      photos: photo_urls,
+      total,
+      page: effective_page,
+      page_size: effective_page_size,
+      has_more: end_index < total,
+      source: resolved.source,
+    };
+  } catch (error) {
+    const logger = create_app_logger();
+    const error_message = error instanceof Error ? error.message : "Unknown error";
+    logger.warn("profile_picture_service_read_photos_failed", {
+      filename: "profile_picture_service.ts",
+      line_number: 0,
+      category,
+      category_path,
+      source: resolved.source,
+      error: error_message,
+    });
+    return {
+      photos: [],
+      total: 0,
+      page: effective_page,
+      page_size: effective_page_size,
+      has_more: false,
+      source: resolved.source,
+    };
+  }
+}
+
+/**
+ * Gets photos in a specific library category (legacy non-paginated version)
+ * @param category - Category name
+ * @returns Array of photo URLs (relative to public directory or API route)
+ */
+export function get_library_photos(category: string): string[] {
+  // Use paginated version with large page size for backwards compatibility
+  const result = get_library_photos_paginated(category, 1, 1000);
+  return result.photos;
+}
+
+/**
+ * Gets the physical file path for a library photo (used for serving from node_modules)
+ * @param category - Category name
+ * @param filename - Photo filename
+ * @returns Full file path or null if not found
+ */
+export function get_library_photo_path(category: string, filename: string): string | null {
+  const resolved = resolve_library_path();
+  
+  if (!resolved) {
+    return null;
+  }
+
+  const photo_path = path.join(resolved.path, category, filename);
+  
+  if (fs.existsSync(photo_path)) {
+    return photo_path;
+  }
+  
+  return null;
+}
+
+/**
+ * Gets the source of library photos (for diagnostic purposes)
+ * @returns Source type or null if no library found
+ */
+export function get_library_source(): "project" | "node_modules" | null {
+  const resolved = resolve_library_path();
+  return resolved?.source ?? null;
+}
+
+/**
+ * Clears the library path cache (useful for testing or after copying files)
+ */
+export function clear_library_cache(): void {
+  cached_library_path = null;
+  cached_library_source = null;
+}
+
+/**
+ * Gets default profile picture based on configuration priority
+ * @param user_email - User's email address
+ * @param user_name - User's name (optional)
+ * @returns Default profile picture URL and source, or null if no default available
+ */
+/**
+ * Checks if a Gravatar exists for the given email by making a HEAD request
+ * @param email - User email address
+ * @returns Promise<boolean> - true if Gravatar exists (status 200), false otherwise (404 or error)
+ */
+async function check_gravatar_exists(email: string): Promise<boolean> {
+  try {
+    const uiSizes = get_ui_sizes_config();
+    const gravatar_url = get_gravatar_url(email, uiSizes.gravatar_size);
+
+    // Make HEAD request to check if image exists without downloading it
+    const response = await fetch(gravatar_url, {
+      method: 'HEAD',
+      // Add timeout to prevent hanging
+      signal: AbortSignal.timeout(5000) // 5 second timeout
+    });
+
+    // Gravatar returns 200 if user has an image, 404 if using default/mystery-person
+    return response.ok;
+  } catch (error) {
+    // If fetch fails (network error, timeout, etc.), assume no Gravatar
+    return false;
+  }
+}
+
+/**
+ * Gets a random image from a random category in the library
+ * @returns string | null - Random library photo URL or null if no photos available
+ */
+function get_random_library_photo(): string | null {
+  const categories = get_library_categories();
+
+  if (categories.length === 0) {
+    return null;
+  }
+
+  // Pick a random category
+  const random_category = categories[Math.floor(Math.random() * categories.length)];
+
+  // Get photos from that category
+  const photos = get_library_photos(random_category);
+
+  if (photos.length === 0) {
+    return null;
+  }
+
+  // Pick a random photo from that category
+  const random_photo = photos[Math.floor(Math.random() * photos.length)];
+
+  return random_photo;
+}
+
+export async function get_default_profile_picture(
+  user_email: string,
+  user_name?: string,
+): Promise<DefaultProfilePictureResult | null> {
+  const config = get_profile_picture_config();
+
+  if (!config.user_photo_default) {
+    return null;
+  }
+
+  const uiSizes = get_ui_sizes_config();
+
+  // Try priority 1
+  if (config.user_photo_default_priority1 === "gravatar") {
+    // Check if Gravatar actually exists for this email
+    const gravatar_exists = await check_gravatar_exists(user_email);
+
+    if (gravatar_exists) {
+      const gravatar_url = get_gravatar_url(user_email, uiSizes.gravatar_size);
+      return {
+        profile_picture_url: gravatar_url,
+        profile_source: "gravatar",
+      };
+    }
+    // If Gravatar doesn't exist, fall through to priority 2
+  } else if (config.user_photo_default_priority1 === "library") {
+    // Use random library photo instead of first photo
+    const random_photo = get_random_library_photo();
+    if (random_photo) {
+      return {
+        profile_picture_url: random_photo,
+        profile_source: "library",
+      };
+    }
+  }
+
+  // Try priority 2 if priority 1 didn't work (only if priority2 is different from priority1)
+  const priority1 = config.user_photo_default_priority1;
+  const priority2 = config.user_photo_default_priority2;
+
+  if (priority2 && priority2 !== priority1) {
+    if (priority2 === "gravatar") {
+      // Check if Gravatar actually exists for this email
+      const gravatar_exists = await check_gravatar_exists(user_email);
+
+      if (gravatar_exists) {
+        const gravatar_url = get_gravatar_url(user_email, uiSizes.gravatar_size);
+        return {
+          profile_picture_url: gravatar_url,
+          profile_source: "gravatar",
+        };
+      }
+    } else if (priority2 === "library") {
+      // Use random library photo instead of first photo
+      const random_photo = get_random_library_photo();
+      if (random_photo) {
+        return {
+          profile_picture_url: random_photo,
+          profile_source: "library",
+        };
+      }
+    }
+  }
+
+  // No default photo available
+  return null;
+}
+
+/**
+ * Updates user profile picture in database
+ * @param adapter - The hazo_connect adapter instance
+ * @param user_id - User ID
+ * @param profile_picture_url - Profile picture URL
+ * @param profile_source - Profile picture source type
+ * @returns Success status
+ */
+export async function update_user_profile_picture(
+  adapter: HazoConnectAdapter,
+  user_id: string,
+  profile_picture_url: string,
+  profile_source: ProfilePictureSource,
+): Promise<{ success: boolean; error?: string }> {
+  try {
+    const users_service = createCrudService(adapter, "hazo_users");
+    const now = new Date().toISOString();
+
+    // Map UI source value to database enum value
+    const db_profile_source = map_ui_source_to_db(profile_source);
+
+    await users_service.updateById(user_id, {
+      profile_picture_url,
+      profile_source: db_profile_source,
+      changed_at: now,
+    });
+
+    return { success: true };
+  } catch (error) {
+    const error_message = error instanceof Error ? error.message : "Unknown error";
+    return {
+      success: false,
+      error: error_message,
+    };
+  }
+}

package/cli-src/lib/services/profile_picture_source_mapper.ts

@@ -0,0 +1,62 @@
+// file_description: helper to map between UI profile picture source values and database enum values
+// section: types
+/**
+ * UI representation of profile picture source
+ * Used in components and API interfaces
+ */
+export type ProfilePictureSourceUI = "upload" | "library" | "gravatar" | "custom";
+
+/**
+ * Database enum values for profile_source
+ * Must match the CHECK constraint in the database
+ */
+export type ProfilePictureSourceDB = "gravatar" | "custom" | "predefined";
+
+// section: helpers
+/**
+ * Maps UI profile picture source to database enum value
+ * @param uiSource - UI representation of source ("upload", "library", "gravatar", "custom")
+ * @returns Database enum value ("gravatar", "custom", "predefined")
+ */
+export function map_ui_source_to_db(uiSource: ProfilePictureSourceUI): ProfilePictureSourceDB {
+  switch (uiSource) {
+    case "upload":
+      return "custom"; // User uploaded their own photo
+    case "library":
+      return "predefined"; // User selected from predefined library
+    case "gravatar":
+      return "gravatar"; // User's Gravatar
+    case "custom":
+      return "custom"; // Already in database format
+    default:
+      // Fallback to custom for unknown values
+      return "custom";
+  }
+}
+
+/**
+ * Maps database enum value to UI representation
+ * @param dbSource - Database enum value ("gravatar", "custom", "predefined")
+ * @returns UI representation ("upload", "library", "gravatar", "custom")
+ */
+export function map_db_source_to_ui(dbSource: ProfilePictureSourceDB | string | null | undefined): ProfilePictureSourceUI {
+  if (!dbSource) {
+    return "custom"; // Default fallback
+  }
+
+  switch (dbSource) {
+    case "gravatar":
+      return "gravatar";
+    case "custom":
+      return "upload"; // Map custom to upload in UI (user uploaded their own)
+    case "predefined":
+      return "library"; // Map predefined to library in UI (user selected from library)
+    default:
+      // For unknown values, try to return as-is if it matches UI format
+      if (dbSource === "upload" || dbSource === "library") {
+        return dbSource as ProfilePictureSourceUI;
+      }
+      return "custom"; // Fallback
+  }
+}
+

package/cli-src/lib/services/registration_service.ts

@@ -0,0 +1,185 @@
+// file_description: service for user registration operations using hazo_connect
+// section: imports
+import type { HazoConnectAdapter } from "hazo_connect";
+import { createCrudService } from "hazo_connect/server";
+import argon2 from "argon2";
+import { randomUUID } from "crypto";
+import { create_token } from "./token_service";
+import { get_default_profile_picture } from "./profile_picture_service";
+import { get_profile_picture_config } from "../profile_picture_config.server";
+import { map_ui_source_to_db } from "./profile_picture_source_mapper";
+import { create_app_logger } from "../app_logger";
+import { send_template_email } from "./email_service";
+import { sanitize_error_for_user } from "../utils/error_sanitizer";
+import { get_filename, get_line_number } from "../utils/api_route_helpers";
+
+// section: types
+export type RegistrationData = {
+  email: string;
+  password: string;
+  name?: string;
+  url_on_logon?: string;
+};
+
+export type RegistrationResult = {
+  success: boolean;
+  user_id?: string;
+  error?: string;
+};
+
+// section: helpers
+/**
+ * Registers a new user in the database using hazo_connect
+ * @param adapter - The hazo_connect adapter instance
+ * @param data - Registration data (email, password, optional name)
+ * @returns Registration result with success status and user_id or error
+ */
+export async function register_user(
+  adapter: HazoConnectAdapter,
+  data: RegistrationData,
+): Promise<RegistrationResult> {
+  try {
+    const { email, password, name, url_on_logon } = data;
+
+    // Create CRUD service for hazo_users table
+    const users_service = createCrudService(adapter, "hazo_users");
+
+    // Check if user already exists
+    const existing_users = await users_service.findBy({
+      email_address: email,
+    });
+
+    if (Array.isArray(existing_users) && existing_users.length > 0) {
+      return {
+        success: false,
+        error: "Email address already registered",
+      };
+    }
+
+    // Hash password using argon2
+    const password_hash = await argon2.hash(password);
+
+    // Generate user ID
+    const user_id = randomUUID();
+    const now = new Date().toISOString();
+
+    // Insert user into database using CRUD service
+    const insert_data: Record<string, unknown> = {
+      id: user_id,
+      email_address: email,
+      password_hash: password_hash,
+      email_verified: false,
+      is_active: true,
+      login_attempts: 0,
+      auth_providers: "email", // Track that this user registered with email/password
+      created_at: now,
+      changed_at: now,
+    };
+
+    // Include name if provided
+    if (name) {
+      insert_data.name = name;
+    }
+
+    // Validate and include url_on_logon if provided
+    if (url_on_logon) {
+      // Ensure it's a relative path starting with / but not //
+      if (url_on_logon.startsWith("/") && !url_on_logon.startsWith("//")) {
+        insert_data.url_on_logon = url_on_logon;
+      }
+    }
+
+    // Set default profile picture if enabled
+    const profile_picture_config = get_profile_picture_config();
+    if (profile_picture_config.user_photo_default) {
+      const default_photo = await get_default_profile_picture(email, name);
+      if (default_photo) {
+        insert_data.profile_picture_url = default_photo.profile_picture_url;
+        // Map UI source value to database enum value
+        insert_data.profile_source = map_ui_source_to_db(default_photo.profile_source);
+      }
+    }
+
+    const inserted_users = await users_service.insert(insert_data);
+
+    // Verify insertion was successful
+    if (!Array.isArray(inserted_users) || inserted_users.length === 0) {
+      return {
+        success: false,
+        error: "Failed to create user account",
+      };
+    }
+
+    // Create email verification token for the new user
+    const token_result = await create_token({
+      adapter,
+      user_id,
+      token_type: "email_verification",
+    });
+
+    if (!token_result.success) {
+      // Log error but don't fail registration - token can be resent later
+      const logger = create_app_logger();
+      const error_message = token_result.error || "Unknown error";
+      logger.error("registration_service_token_creation_failed", {
+        filename: "registration_service.ts",
+        line_number: 0,
+        user_id,
+        error: error_message,
+        note: "This may be due to missing token_type column in hazo_refresh_tokens table. Please ensure migration 001_add_token_type_to_refresh_tokens.sql has been applied.",
+      });
+    } else {
+      const logger = create_app_logger();
+      logger.info("registration_service_token_created", {
+        filename: "registration_service.ts",
+        line_number: 0,
+        user_id,
+      });
+    }
+
+    // Send verification email if token was created successfully
+    if (token_result.success && token_result.raw_token) {
+      const email_result = await send_template_email("email_verification", email, {
+        token: token_result.raw_token,
+        user_email: email,
+        user_name: name,
+      });
+      
+      if (!email_result.success) {
+        const logger = create_app_logger();
+        logger.error("registration_service_email_send_failed", {
+          filename: "registration_service.ts",
+          line_number: 0,
+          user_id,
+          email,
+          error: email_result.error,
+          note: "User registration succeeded but verification email failed to send",
+        });
+      }
+    }
+
+    return {
+      success: true,
+      user_id,
+    };
+  } catch (error) {
+    const logger = create_app_logger();
+    const user_friendly_error = sanitize_error_for_user(error, {
+      logToConsole: true,
+      logToLogger: true,
+      logger,
+      context: {
+        filename: "registration_service.ts",
+        line_number: get_line_number(),
+        email: data.email,
+        operation: "register_user",
+      },
+    });
+
+    return {
+      success: false,
+      error: user_friendly_error,
+    };
+  }
+}
+