hazo_auth 1.4.2 → 1.6.0

package/src/lib/auth/auth_rate_limiter.ts

@@ -1,121 +0,0 @@
-// file_description: Simple in-memory rate limiter for hazo_get_auth API endpoint
-// section: types
-
-/**
- * Rate limit entry structure
- */
-type RateLimitEntry = {
-  count: number;
-  window_start: number; // Unix timestamp in milliseconds
-};
-
-/**
- * Simple in-memory rate limiter
- * Tracks request counts per key within a time window
- */
-class RateLimiter {
-  private limits: Map<string, RateLimitEntry>;
-  private window_ms: number; // 1 minute = 60000ms
-
-  constructor() {
-    this.limits = new Map();
-    this.window_ms = 60 * 1000; // 1 minute window
-  }
-
-  /**
-   * Checks if a request should be allowed
-   * @param key - Rate limit key (e.g., "user:123" or "ip:192.168.1.1")
-   * @param max_requests - Maximum requests allowed per window
-   * @returns true if allowed, false if rate limited
-   */
-  check(key: string, max_requests: number): boolean {
-    const now = Date.now();
-    const entry = this.limits.get(key);
-
-    if (!entry) {
-      // First request for this key
-      this.limits.set(key, {
-        count: 1,
-        window_start: now,
-      });
-      return true;
-    }
-
-    // Check if window has expired
-    if (now - entry.window_start >= this.window_ms) {
-      // Reset window
-      this.limits.set(key, {
-        count: 1,
-        window_start: now,
-      });
-      return true;
-    }
-
-    // Check if limit exceeded
-    if (entry.count >= max_requests) {
-      return false;
-    }
-
-    // Increment count
-    entry.count++;
-    return true;
-  }
-
-  /**
-   * Cleans up old entries (call periodically to prevent memory leak)
-   * Removes entries older than 2 windows
-   */
-  cleanup(): void {
-    const now = Date.now();
-    const cutoff = now - 2 * this.window_ms;
-
-    const keys_to_delete: string[] = [];
-    for (const [key, entry] of this.limits.entries()) {
-      if (entry.window_start < cutoff) {
-        keys_to_delete.push(key);
-      }
-    }
-
-    for (const key of keys_to_delete) {
-      this.limits.delete(key);
-    }
-  }
-
-  /**
-   * Gets rate limit statistics
-   * @returns Object with current limit entries count
-   */
-  get_stats(): { active_limits: number } {
-    return {
-      active_limits: this.limits.size,
-    };
-  }
-}
-
-// section: singleton
-// Global rate limiter instance
-let rate_limiter_instance: RateLimiter | null = null;
-
-/**
- * Gets or creates the global rate limiter instance
- * @returns Rate limiter instance
- */
-export function get_rate_limiter(): RateLimiter {
-  if (!rate_limiter_instance) {
-    rate_limiter_instance = new RateLimiter();
-
-    // Cleanup old entries every 5 minutes
-    setInterval(() => {
-      rate_limiter_instance?.cleanup();
-    }, 5 * 60 * 1000);
-  }
-  return rate_limiter_instance;
-}
-
-/**
- * Resets the global rate limiter instance (useful for testing)
- */
-export function reset_rate_limiter(): void {
-  rate_limiter_instance = null;
-}
-

package/src/lib/auth/auth_types.ts

@@ -1,65 +0,0 @@
-// file_description: Type definitions and error classes for hazo_get_auth utility
-// section: types
-
-/**
- * User data structure returned by hazo_get_auth
- */
-export type HazoAuthUser = {
-  id: string;
-  name: string | null;
-  email_address: string;
-  is_active: boolean;
-  profile_picture_url: string | null;
-};
-
-/**
- * Result type for hazo_get_auth function
- * Returns authenticated state with user data and permissions, or unauthenticated state
- */
-export type HazoAuthResult =
-  | {
-      authenticated: true;
-      user: HazoAuthUser;
-      permissions: string[];
-      permission_ok: boolean;
-      missing_permissions?: string[];
-    }
-  | {
-      authenticated: false;
-      user: null;
-      permissions: [];
-      permission_ok: false;
-    };
-
-/**
- * Options for hazo_get_auth function
- */
-export type HazoAuthOptions = {
-  /**
-   * Array of required permissions to check
-   * If provided, permission_ok will be set based on whether user has all required permissions
-   */
-  required_permissions?: string[];
-  /**
-   * If true, throws PermissionError when user lacks required permissions
-   * If false (default), returns permission_ok: false without throwing
-   */
-  strict?: boolean;
-};
-
-/**
- * Custom error class for permission denials
- * Includes technical and user-friendly error messages
- */
-export class PermissionError extends Error {
-  constructor(
-    public missing_permissions: string[],
-    public user_permissions: string[],
-    public required_permissions: string[],
-    public user_friendly_message?: string,
-  ) {
-    super(`Missing permissions: ${missing_permissions.join(", ")}`);
-    this.name = "PermissionError";
-  }
-}
-

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

@@ -1,196 +0,0 @@
-// file_description: server-side authentication utilities for checking login status in API routes
-// section: imports
-import { NextRequest, NextResponse } from "next/server";
-import { get_hazo_connect_instance } from "../hazo_connect_instance.server";
-import { createCrudService } from "hazo_connect/server";
-import { map_db_source_to_ui } from "../services/profile_picture_source_mapper";
-
-// section: types
-export type AuthUser = {
-  authenticated: true;
-  user_id: string;
-  email: string;
-  name?: string;
-  email_verified: boolean;
-  is_active: boolean;
-  last_logon?: string;
-  profile_picture_url?: string;
-  profile_source?: "upload" | "library" | "gravatar" | "custom";
-};
-
-export type AuthResult = 
-  | AuthUser
-  | { authenticated: false };
-
-// section: helpers
-/**
- * Clears authentication cookies from response
- * @param response - NextResponse object to clear cookies from
- * @returns The response with cleared cookies
- */
-function clear_auth_cookies(response: NextResponse): NextResponse {
-  response.cookies.set("hazo_auth_user_email", "", {
-    expires: new Date(0),
-    path: "/",
-  });
-  response.cookies.set("hazo_auth_user_id", "", {
-    expires: new Date(0),
-    path: "/",
-  });
-  return response;
-}
-
-// section: functions
-/**
- * Checks if a user is authenticated from request cookies
- * Validates user exists, is active, and cookies match
- * @param request - NextRequest object
- * @returns AuthResult with user info or authenticated: false
- */
-export async function get_authenticated_user(request: NextRequest): Promise<AuthResult> {
-  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) {
-    return { authenticated: false };
-  }
-
-  try {
-    const hazoConnect = get_hazo_connect_instance();
-    const users_service = createCrudService(hazoConnect, "hazo_users");
-    
-    const users = await users_service.findBy({
-      id: user_id,
-      email_address: user_email,
-    });
-
-    if (!Array.isArray(users) || users.length === 0) {
-      return { authenticated: false };
-    }
-
-    const user = users[0];
-
-    // Check if user is active
-    if (user.is_active === false) {
-      return { authenticated: false };
-    }
-
-    // Map database profile_source to UI representation
-    const profile_source_db = user.profile_source as string | null | undefined;
-    const profile_source_ui = profile_source_db ? map_db_source_to_ui(profile_source_db) : undefined;
-
-    return {
-      authenticated: true,
-      user_id: user.id as string,
-      email: user.email_address as string,
-      name: (user.name as string | null | undefined) || undefined,
-      email_verified: user.email_verified === true,
-      is_active: user.is_active === true,
-      last_logon: (user.last_logon as string | null | undefined) || undefined,
-      profile_picture_url: (user.profile_picture_url as string | null | undefined) || undefined,
-      profile_source: profile_source_ui,
-    };
-  } catch (error) {
-    return { authenticated: false };
-  }
-}
-
-/**
- * Checks if user is authenticated (simple boolean check)
- * @param request - NextRequest object
- * @returns true if authenticated, false otherwise
- */
-export async function is_authenticated(request: NextRequest): Promise<boolean> {
-  const result = await get_authenticated_user(request);
-  return result.authenticated;
-}
-
-/**
- * Requires authentication - throws error if not authenticated
- * Use in API routes that require authentication
- * @param request - NextRequest object
- * @returns AuthUser (never returns authenticated: false, throws instead)
- * @throws Error if not authenticated
- */
-export async function require_auth(request: NextRequest): Promise<AuthUser> {
-  const result = await get_authenticated_user(request);
-  
-  if (!result.authenticated) {
-    throw new Error("Authentication required");
-  }
-  
-  return result;
-}
-
-/**
- * Gets authenticated user and returns response with cleared cookies if invalid
- * Useful for /api/auth/me endpoint that needs to clear cookies on invalid auth
- * @param request - NextRequest object
- * @returns Object with auth_result and response (with cleared cookies if invalid)
- */
-export async function get_authenticated_user_with_response(request: NextRequest): Promise<{
-  auth_result: AuthResult;
-  response?: NextResponse;
-}> {
-  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) {
-    return { auth_result: { authenticated: false } };
-  }
-
-  try {
-    const hazoConnect = get_hazo_connect_instance();
-    const users_service = createCrudService(hazoConnect, "hazo_users");
-    
-    const users = await users_service.findBy({
-      id: user_id,
-      email_address: user_email,
-    });
-
-    if (!Array.isArray(users) || users.length === 0) {
-      // User not found - clear cookies
-      const response = NextResponse.json(
-        { authenticated: false },
-        { status: 200 }
-      );
-      clear_auth_cookies(response);
-      return { auth_result: { authenticated: false }, response };
-    }
-
-    const user = users[0];
-
-    // Check if user is still active
-    if (user.is_active === false) {
-      // User is inactive - clear cookies
-      const response = NextResponse.json(
-        { authenticated: false },
-        { status: 200 }
-      );
-      clear_auth_cookies(response);
-      return { auth_result: { authenticated: false }, response };
-    }
-
-    // Map database profile_source to UI representation
-    const profile_source_db = user.profile_source as string | null | undefined;
-    const profile_source_ui = profile_source_db ? map_db_source_to_ui(profile_source_db) : undefined;
-
-    return {
-      auth_result: {
-        authenticated: true,
-        user_id: user.id as string,
-        email: user.email_address as string,
-        name: (user.name as string | null | undefined) || undefined,
-        email_verified: user.email_verified === true,
-        is_active: user.is_active === true,
-        last_logon: (user.last_logon as string | null | undefined) || undefined,
-        profile_picture_url: (user.profile_picture_url as string | null | undefined) || undefined,
-        profile_source: profile_source_ui,
-      },
-    };
-  } catch (error) {
-    // On error, assume not authenticated
-    return { auth_result: { authenticated: false } };
-  }
-}
-

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

@@ -1,333 +0,0 @@
-// 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,
-  };
-}
-