hazo_auth 0.3.0 → 1.0.0

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

@@ -0,0 +1,333 @@
+// file_description: server-side implementation of hazo_get_auth utility for API routes
+// section: imports
+import { NextRequest } from "next/server";
+import { get_hazo_connect_instance } from "../hazo_connect_instance.server";
+import { createCrudService } from "hazo_connect/server";
+import { create_app_logger } from "../app_logger";
+import { get_filename, get_line_number } from "../utils/api_route_helpers";
+import type { HazoAuthResult, HazoAuthUser, HazoAuthOptions } from "./auth_types";
+import { PermissionError } from "./auth_types";
+import { get_auth_cache } from "./auth_cache";
+import { get_rate_limiter } from "./auth_rate_limiter";
+import { get_auth_utility_config } from "../auth_utility_config.server";
+
+// section: helpers
+
+/**
+ * Gets client IP address from request
+ * @param request - NextRequest object
+ * @returns IP address string
+ */
+function get_client_ip(request: NextRequest): string {
+  const forwarded = request.headers.get("x-forwarded-for");
+  if (forwarded) {
+    return forwarded.split(",")[0].trim();
+  }
+  const real_ip = request.headers.get("x-real-ip");
+  if (real_ip) {
+    return real_ip;
+  }
+  return "unknown";
+}
+
+/**
+ * Fetches user data and permissions from database
+ * @param user_id - User ID
+ * @returns Object with user, permissions, and role_ids
+ */
+async function fetch_user_data_from_db(user_id: string): Promise<{
+  user: HazoAuthUser;
+  permissions: string[];
+  role_ids: number[];
+}> {
+  const hazoConnect = get_hazo_connect_instance();
+  const users_service = createCrudService(hazoConnect, "hazo_users");
+  const user_roles_service = createCrudService(hazoConnect, "hazo_user_roles");
+  const role_permissions_service = createCrudService(
+    hazoConnect,
+    "hazo_role_permissions",
+  );
+  const permissions_service = createCrudService(
+    hazoConnect,
+    "hazo_permissions",
+  );
+
+  // Fetch user
+  const users = await users_service.findBy({ id: user_id });
+  if (!Array.isArray(users) || users.length === 0) {
+    throw new Error("User not found");
+  }
+
+  const user_db = users[0];
+
+  // Check if user is active
+  if (user_db.is_active === false) {
+    throw new Error("User is inactive");
+  }
+
+  // Build user object
+  const user: HazoAuthUser = {
+    id: user_db.id as string,
+    name: (user_db.name as string | null) || null,
+    email_address: user_db.email_address as string,
+    is_active: user_db.is_active === true,
+    profile_picture_url:
+      (user_db.profile_picture_url as string | null) || null,
+  };
+
+  // Fetch user roles
+  const user_roles = await user_roles_service.findBy({ user_id });
+  const role_ids: number[] = [];
+  if (Array.isArray(user_roles)) {
+    for (const ur of user_roles) {
+      const role_id = ur.role_id as number | undefined;
+      if (role_id !== undefined) {
+        role_ids.push(role_id);
+      }
+    }
+  }
+
+  // Fetch role permissions
+  const permissions_set = new Set<string>();
+  if (role_ids.length > 0) {
+    const role_permissions = await role_permissions_service.findBy({});
+    if (Array.isArray(role_permissions)) {
+      // Filter role_permissions for user's roles
+      const user_role_permissions = role_permissions.filter((rp) =>
+        role_ids.includes(rp.role_id as number),
+      );
+
+      // Get permission IDs
+      const permission_ids = new Set<number>();
+      for (const rp of user_role_permissions) {
+        const perm_id = rp.permission_id as number | undefined;
+        if (perm_id !== undefined) {
+          permission_ids.add(perm_id);
+        }
+      }
+
+      // Fetch permission names
+      if (permission_ids.size > 0) {
+        const permissions = await permissions_service.findBy({});
+        if (Array.isArray(permissions)) {
+          for (const perm of permissions) {
+            const perm_id = perm.id as number | undefined;
+            if (perm_id !== undefined && permission_ids.has(perm_id)) {
+              const perm_name = perm.permission_name as string | undefined;
+              if (perm_name) {
+                permissions_set.add(perm_name);
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+
+  const permissions = Array.from(permissions_set);
+
+  return { user, permissions, role_ids };
+}
+
+/**
+ * Checks if user has required permissions
+ * @param user_permissions - User's permissions
+ * @param required_permissions - Required permissions
+ * @returns Object with permission_ok and missing_permissions
+ */
+function check_permissions(
+  user_permissions: string[],
+  required_permissions: string[],
+): { permission_ok: boolean; missing_permissions: string[] } {
+  const user_perms_set = new Set(user_permissions);
+  const missing = required_permissions.filter(
+    (perm) => !user_perms_set.has(perm),
+  );
+
+  return {
+    permission_ok: missing.length === 0,
+    missing_permissions: missing,
+  };
+}
+
+/**
+ * Gets user-friendly error message for missing permissions
+ * @param missing_permissions - Array of missing permission names
+ * @param config - Auth utility config
+ * @returns User-friendly message or undefined
+ */
+function get_friendly_error_message(
+  missing_permissions: string[],
+  config: ReturnType<typeof get_auth_utility_config>,
+): string | undefined {
+  if (!config.enable_friendly_error_messages) {
+    return undefined;
+  }
+
+  // Try to get messages for each missing permission
+  const messages: string[] = [];
+  for (const perm of missing_permissions) {
+    const message = config.permission_error_messages.get(perm);
+    if (message) {
+      messages.push(message);
+    }
+  }
+
+  if (messages.length > 0) {
+    return messages.join(". ");
+  }
+
+  // Default message if no specific mapping
+  return "You don't have the required permissions to perform this action. Please contact your administrator.";
+}
+
+// section: main_function
+
+/**
+ * Main hazo_get_auth function for server-side use in API routes
+ * Returns user details, permissions, and checks required permissions
+ * @param request - NextRequest object
+ * @param options - Optional parameters for permission checking
+ * @returns HazoAuthResult with user data and permissions
+ * @throws PermissionError if strict mode and permissions are missing
+ */
+export async function hazo_get_auth(
+  request: NextRequest,
+  options?: HazoAuthOptions,
+): Promise<HazoAuthResult> {
+  const logger = create_app_logger();
+  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 rate_limiter = get_rate_limiter();
+
+  // Fast path: Check for authentication cookies
+  const user_id = request.cookies.get("hazo_auth_user_id")?.value;
+  const user_email = request.cookies.get("hazo_auth_user_email")?.value;
+
+  if (!user_id || !user_email) {
+    // Unauthenticated - check rate limit by IP
+    const client_ip = get_client_ip(request);
+    const ip_key = `ip:${client_ip}`;
+    if (!rate_limiter.check(ip_key, config.rate_limit_per_ip)) {
+      logger.warn("auth_utility_rate_limit_exceeded_ip", {
+        filename: get_filename(),
+        line_number: get_line_number(),
+        ip: client_ip,
+      });
+      throw new Error("Rate limit exceeded. Please try again later.");
+    }
+
+    return {
+      authenticated: false,
+      user: null,
+      permissions: [],
+      permission_ok: false,
+    };
+  }
+
+  // Authenticated - check rate limit by user
+  const user_key = `user:${user_id}`;
+  if (!rate_limiter.check(user_key, config.rate_limit_per_user)) {
+    logger.warn("auth_utility_rate_limit_exceeded_user", {
+      filename: get_filename(),
+      line_number: get_line_number(),
+      user_id,
+    });
+    throw new Error("Rate limit exceeded. Please try again later.");
+  }
+
+  // Check cache
+  let cached_entry = cache.get(user_id);
+  let user: HazoAuthUser;
+  let permissions: string[];
+  let role_ids: number[];
+
+  if (cached_entry) {
+    // Cache hit
+    user = cached_entry.user;
+    permissions = cached_entry.permissions;
+    role_ids = cached_entry.role_ids;
+  } else {
+    // Cache miss - fetch from database
+    try {
+      const user_data = await fetch_user_data_from_db(user_id);
+      user = user_data.user;
+      permissions = user_data.permissions;
+      role_ids = user_data.role_ids;
+
+      // Update cache
+      cache.set(user_id, user, permissions, role_ids);
+    } catch (error) {
+      const error_message =
+        error instanceof Error ? error.message : "Unknown error";
+      logger.error("auth_utility_fetch_user_failed", {
+        filename: get_filename(),
+        line_number: get_line_number(),
+        user_id,
+        error: error_message,
+      });
+
+      return {
+        authenticated: false,
+        user: null,
+        permissions: [],
+        permission_ok: false,
+      };
+    }
+  }
+
+  // Check permissions if required
+  let permission_ok = true;
+  let missing_permissions: string[] | undefined;
+
+  if (options?.required_permissions && options.required_permissions.length > 0) {
+    const check_result = check_permissions(
+      permissions,
+      options.required_permissions,
+    );
+    permission_ok = check_result.permission_ok;
+    missing_permissions = check_result.missing_permissions;
+
+    // Log permission denial if enabled
+    if (!permission_ok && config.log_permission_denials) {
+      const client_ip = get_client_ip(request);
+      logger.warn("auth_utility_permission_denied", {
+        filename: get_filename(),
+        line_number: get_line_number(),
+        user_id,
+        requested_permissions: options.required_permissions,
+        missing_permissions,
+        user_permissions: permissions,
+        ip: client_ip,
+      });
+    }
+
+    // Throw error if strict mode
+    if (!permission_ok && options.strict) {
+      const friendly_message = get_friendly_error_message(
+        missing_permissions,
+        config,
+      );
+
+      throw new PermissionError(
+        missing_permissions,
+        permissions,
+        options.required_permissions,
+        friendly_message,
+      );
+    }
+  }
+
+  return {
+    authenticated: true,
+    user,
+    permissions,
+    permission_ok,
+    missing_permissions,
+  };
+}
+

package/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",
+    15,
+  );
+  const cache_max_age_minutes = get_config_number(
+    section_name,
+    "cache_max_age_minutes",
+    30,
+  );
+
+  // 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/src/lib/hazo_connect_setup.server.ts

@@ -68,14 +68,13 @@ function get_hazo_connect_config(): {
       sqlite_path = path.normalize(sqlite_path);
     } else {
       // Fallback to test fixture database
-      const ui_component_path = path.resolve(
+      const fallback_sqlite_path = path.resolve(
         process.cwd(),
-        "ui_component",
         "__tests__",
         "fixtures",
         "hazo_auth.sqlite"
       );
-      sqlite_path = path.normalize(ui_component_path);
+      sqlite_path = path.normalize(fallback_sqlite_path);
     }
 
     // Log the resolved path for debugging

package/src/lib/my_settings_config.server.ts

@@ -106,7 +106,7 @@ export function get_my_settings_config(): MySettingsConfig {
   const savePasswordButtonLabel = get_config_value(section, "save_password_button_label", "Save Password");
   const unauthorizedMessage = get_config_value(section, "unauthorized_message", "You must be logged in to access this page.");
   const loginButtonLabel = get_config_value(section, "login_button_label", "Go to login");
-  const loginPath = get_config_value(section, "login_path", "/login");
+  const loginPath = get_config_value(section, "login_path", "/hazo_auth/login");
 
   return {
     userFields,

package/src/lib/profile_pic_menu_config.server.ts

@@ -113,12 +113,12 @@ export function get_profile_pic_menu_config(): ProfilePicMenuConfig {
   const show_single_button = get_config_boolean(section, "show_single_button", false);
   const sign_up_label = get_config_value(section, "sign_up_label", "Sign Up");
   const sign_in_label = get_config_value(section, "sign_in_label", "Sign In");
-  const register_path = get_config_value(section, "register_path", "/register");
-  const login_path = get_config_value(section, "login_path", "/login");
+  const register_path = get_config_value(section, "register_path", "/hazo_auth/register");
+  const login_path = get_config_value(section, "login_path", "/hazo_auth/login");
 
   // Read menu paths
-  const settings_path = get_config_value(section, "settings_path", "/my_settings");
-  const logout_path = get_config_value(section, "logout_path", "/api/auth/logout");
+  const settings_path = get_config_value(section, "settings_path", "/hazo_auth/my_settings");
+  const logout_path = get_config_value(section, "logout_path", "/api/hazo_auth/logout");
 
   // Read custom menu items
   const custom_items_string = get_config_array(section, "custom_menu_items", []);

package/src/lib/reset_password_config.server.ts

@@ -50,11 +50,11 @@ export function get_reset_password_config(): ResetPasswordConfig {
     "Password reset successfully. Redirecting to login..."
   );
 
-  // Read login path (defaults to "/login")
-  const loginPath = get_config_value(section, "login_path", "/login");
-
-  // Read forgot password path (defaults to "/forgot_password")
-  const forgotPasswordPath = get_config_value(section, "forgot_password_path", "/forgot_password");
+  // Read login path (defaults to "/hazo_auth/login")
+  const loginPath = get_config_value(section, "login_path", "/hazo_auth/login");
+  
+  // Read forgot password path (defaults to "/hazo_auth/forgot_password")
+  const forgotPasswordPath = get_config_value(section, "forgot_password_path", "/hazo_auth/forgot_password");
 
   // Get shared password requirements
   const passwordRequirements = get_password_requirements_config();

package/src/lib/services/email_service.ts

@@ -176,7 +176,7 @@ function get_base_url(): string {
  */
 function get_verification_url(token: string): string {
   const base_url = get_base_url();
-  const path = "/verify_email";
+  const path = "/hazo_auth/verify_email";
   const url = base_url ? `${base_url}${path}?token=${encodeURIComponent(token)}` : `${path}?token=${encodeURIComponent(token)}`;
   return url;
 }
@@ -188,7 +188,7 @@ function get_verification_url(token: string): string {
  */
 function get_reset_password_url(token: string): string {
   const base_url = get_base_url();
-  const path = "/reset_password";
+  const path = "/hazo_auth/reset_password";
   const url = base_url ? `${base_url}${path}?token=${encodeURIComponent(token)}` : `${path}?token=${encodeURIComponent(token)}`;
   return url;
 }

package/src/lib/services/profile_picture_remove_service.ts

@@ -62,7 +62,7 @@ export async function remove_user_profile_picture(
         const config = get_profile_picture_config();
 
         if (config.upload_photo_path) {
-          // Extract filename from URL (e.g., /api/auth/profile_picture/user_id.jpg)
+          // Extract filename from URL (e.g., /api/hazo_auth/profile_picture/user_id.jpg)
           const fileName = profile_picture_url.split("/").pop();
 
           if (fileName && fileName.startsWith(user_id)) {

package/src/lib/services/token_service.ts

@@ -206,9 +206,9 @@ export async function create_token(
       token_type,
       raw_token,
       test_url: token_type === "email_verification" 
-        ? `/verify_email?token=${raw_token}`
+        ? `/hazo_auth/verify_email?token=${raw_token}`
         : token_type === "password_reset"
-        ? `/reset_password?token=${raw_token}`
+        ? `/hazo_auth/reset_password?token=${raw_token}`
         : undefined,
     });
 

package/src/lib/user_management_config.server.ts

@@ -0,0 +1,40 @@
+// file_description: server-only helper to read user management configuration from hazo_auth_config.ini
+// section: imports
+import { get_config_value, get_config_array } from "./config/config_loader.server";
+import { read_config_section } from "./config/config_loader.server";
+
+// 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/src/lib/utils.ts

@@ -1,4 +1,4 @@
-// file_description: provide shared utility helpers for the ui_component project
+// file_description: provide shared utility helpers for the hazo_auth project
 import { clsx, type ClassValue } from "clsx";
 import { twMerge } from "tailwind-merge";
 

package/src/middleware.ts

@@ -35,18 +35,20 @@ export async function middleware(request: NextRequest) {
 
   // Public routes that don't require authentication
   const public_routes = [
-    "/login",
-    "/register",
-    "/forgot_password",
-    "/reset_password",
-    "/verify_email",
-    "/api/auth/login",
-    "/api/auth/register",
-    "/api/auth/forgot_password",
-    "/api/auth/reset_password",
-    "/api/auth/verify_email",
-    "/api/auth/validate_reset_token",
-    "/api/auth/me", // Allow /api/auth/me to be public (returns authenticated: false if not logged in)
+    "/hazo_auth/login",
+    "/hazo_auth/register",
+    "/hazo_auth/forgot_password",
+    "/hazo_auth/reset_password",
+    "/hazo_auth/verify_email",
+    "/api/hazo_auth/login",
+    "/api/hazo_auth/register",
+    "/api/hazo_auth/forgot_password",
+    "/api/hazo_auth/reset_password",
+    "/api/hazo_auth/verify_email",
+    "/api/hazo_auth/validate_reset_token",
+    "/api/hazo_auth/me", // Allow /api/hazo_auth/me to be public (returns authenticated: false if not logged in)
+    "/hazo_connect/api/sqlite", // SQLite Admin API routes (admin tool, should be accessible)
+    "/hazo_connect/sqlite_admin", // SQLite Admin UI page
   ];
 
   // Check if route is public
@@ -65,7 +67,7 @@ export async function middleware(request: NextRequest) {
 
   if (!has_cookies) {
     // Redirect to login if no cookies (not authenticated)
-    const login_url = new URL("/login", request.url);
+    const login_url = new URL("/hazo_auth/login", request.url);
     login_url.searchParams.set("redirect", pathname);
     return NextResponse.redirect(login_url);
   }

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

@@ -13,3 +13,4 @@ export {};
 
 
 
+

package/src/stories/project_overview.stories.tsx

@@ -1,4 +1,4 @@
-// file_description: provide a high level story describing the purpose of the ui_component workspace
+// file_description: provide a high level story describing the purpose of the hazo_auth workspace
 import type { Meta, StoryObj } from "@storybook/nextjs";
 
 // section: story_configuration

package/tailwind.config.ts

@@ -1,4 +1,4 @@
-// file_description: configure tailwindcss for the ui_component project
+// file_description: configure tailwindcss for the hazo_auth project
 import type { Config } from "tailwindcss";
 
 // section: tailwind_configuration