hazo_auth 4.2.0 → 4.4.0

package/cli-src/lib/auth/session_token_validator.edge.ts

@@ -0,0 +1,92 @@
+// file_description: Edge-compatible JWT session token validator for Next.js proxy/middleware
+// Uses jose library which works in Edge Runtime
+// section: imports
+import { jwtVerify } from "jose";
+import type { NextRequest } from "next/server";
+
+// section: types
+export type ValidateSessionCookieResult = {
+  valid: boolean;
+  user_id?: string;
+  email?: string;
+};
+
+// section: helpers
+/**
+ * Gets JWT secret from environment variables
+ * Works in Edge Runtime (no Node.js APIs)
+ * @returns JWT secret as Uint8Array for jose library
+ */
+function get_jwt_secret(): Uint8Array | null {
+  const jwt_secret = process.env.JWT_SECRET;
+  
+  if (!jwt_secret) {
+    // In Edge Runtime, we can't use logger, so we just return null
+    // The validation will fail gracefully
+    return null;
+  }
+  
+  // Convert string secret to Uint8Array for jose
+  return new TextEncoder().encode(jwt_secret);
+}
+
+// section: main_function
+/**
+ * Validates session cookie from NextRequest (Edge-compatible)
+ * Extracts hazo_auth_session cookie and validates JWT signature and expiry
+ * Works in Edge Runtime (Next.js proxy/middleware)
+ * @param request - NextRequest object
+ * @returns Validation result with user_id and email if valid
+ */
+export async function validate_session_cookie(
+  request: NextRequest,
+): Promise<ValidateSessionCookieResult> {
+  try {
+    // Extract session cookie
+    const session_cookie = request.cookies.get("hazo_auth_session")?.value;
+    
+    if (!session_cookie) {
+      return { valid: false };
+    }
+    
+    // Get JWT secret
+    const secret = get_jwt_secret();
+    
+    if (!secret) {
+      // JWT_SECRET not set - cannot validate
+      return { valid: false };
+    }
+    
+    // Verify JWT signature and expiration
+    const { payload } = await jwtVerify(session_cookie, secret, {
+      algorithms: ["HS256"],
+    });
+    
+    // Extract user_id and email from payload
+    const user_id = payload.user_id as string;
+    const email = payload.email as string;
+    
+    if (!user_id || !email) {
+      return { valid: false };
+    }
+    
+    return {
+      valid: true,
+      user_id,
+      email,
+    };
+  } catch (error) {
+    // jose throws JWTExpired, JWTInvalid, etc. - these are expected for invalid tokens
+    // In Edge Runtime, we can't log, so we just return invalid
+    return { valid: false };
+  }
+}
+
+
+
+
+
+
+
+
+

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.js";
+
+// 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.js";
+
+// 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,243 @@
+// 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: multi_tenancy
+export const DEFAULT_MULTI_TENANCY = {
+  /** Enable multi-tenancy support (default: false) */
+  enable_multi_tenancy: false,
+  /** Cache TTL in minutes for org lookups (default: 15) */
+  org_cache_ttl_minutes: 15,
+  /** Maximum entries in org cache (default: 1000) */
+  org_cache_max_entries: 1000,
+  /** Default user limit per organization (0 = unlimited) */
+  default_user_limit: 0,
+} as const;
+
+// section: dev_lock
+export const DEFAULT_DEV_LOCK = {
+  /** Enable the development lock screen (also requires HAZO_AUTH_DEV_LOCK_ENABLED env var) */
+  enable: false,
+  /** Session duration in days */
+  session_duration_days: 7,
+  /** Background color (default: black) */
+  background_color: "#000000",
+  /** Logo image path (default: /logo.png in public folder) */
+  logo_path: "/logo.png",
+  /** Logo width in pixels */
+  logo_width: 120,
+  /** Logo height in pixels */
+  logo_height: 120,
+  /** Application name displayed below logo */
+  application_name: "",
+  /** Limited access text displayed with lock icon */
+  limited_access_text: "Limited Access",
+  /** Password input placeholder text */
+  password_placeholder: "Enter access password",
+  /** Submit button text */
+  submit_button_text: "Unlock",
+  /** Error message for incorrect password */
+  error_message: "Incorrect password",
+  /** Text color for labels (default: white) */
+  text_color: "#ffffff",
+  /** Accent color for button (default: blue) */
+  accent_color: "#3b82f6",
+} 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,
+  devLock: DEFAULT_DEV_LOCK,
+  multiTenancy: DEFAULT_MULTI_TENANCY,
+} as const;
+
+// section: types
+/**
+ * Type representing the complete default configuration structure
+ */
+export type HazoAuthDefaults = typeof HAZO_AUTH_DEFAULTS;