hazo_auth 4.2.0 → 4.3.0

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

@@ -0,0 +1,177 @@
+// file_description: service for creating and validating JWT session tokens for authentication
+// Uses jose library for Edge-compatible JWT operations
+// section: imports
+import { SignJWT, jwtVerify } from "jose";
+import { create_app_logger } from "../app_logger";
+import { get_filename, get_line_number } from "../utils/api_route_helpers";
+
+// section: types
+export type SessionTokenPayload = {
+  user_id: string;
+  email: string;
+  iat: number;
+  exp: number;
+};
+
+export type ValidateSessionTokenResult = {
+  valid: boolean;
+  user_id?: string;
+  email?: string;
+};
+
+// section: helpers
+/**
+ * Gets JWT secret from environment variables
+ * @returns JWT secret as Uint8Array for jose library
+ * @throws Error if JWT_SECRET is not set
+ */
+function get_jwt_secret(): Uint8Array {
+  const jwt_secret = process.env.JWT_SECRET;
+  
+  if (!jwt_secret) {
+    const logger = create_app_logger();
+    logger.error("session_token_jwt_secret_missing", {
+      filename: get_filename(),
+      line_number: get_line_number(),
+      error: "JWT_SECRET environment variable is required",
+    });
+    throw new Error("JWT_SECRET environment variable is required");
+  }
+  
+  // Convert string secret to Uint8Array for jose
+  return new TextEncoder().encode(jwt_secret);
+}
+
+/**
+ * Gets session token expiry in seconds (default: 30 days)
+ * @returns Number of seconds until token expires
+ */
+function get_session_token_expiry_seconds(): number {
+  // Default: 30 days = 30 * 24 * 60 * 60 = 2,592,000 seconds
+  const default_expiry_seconds = 60 * 60 * 24 * 30;
+  
+  // Could be extended to read from config in the future
+  // For now, use default 30 days to match cookie expiry
+  return default_expiry_seconds;
+}
+
+// section: main_functions
+/**
+ * Creates a JWT session token for a user
+ * Token includes user_id, email, issued at time, and expiration
+ * @param user_id - User ID
+ * @param email - User email address
+ * @returns JWT token string
+ */
+export async function create_session_token(
+  user_id: string,
+  email: string,
+): Promise<string> {
+  const logger = create_app_logger();
+  
+  try {
+    const secret = get_jwt_secret();
+    const now = Math.floor(Date.now() / 1000); // Current time in seconds
+    const expiry_seconds = get_session_token_expiry_seconds();
+    const exp = now + expiry_seconds;
+    
+    const jwt = await new SignJWT({
+      user_id,
+      email,
+    })
+      .setProtectedHeader({ alg: "HS256" })
+      .setIssuedAt(now)
+      .setExpirationTime(exp)
+      .sign(secret);
+    
+    logger.info("session_token_created", {
+      filename: get_filename(),
+      line_number: get_line_number(),
+      user_id,
+      email,
+      expires_in_seconds: expiry_seconds,
+    });
+    
+    return jwt;
+  } catch (error) {
+    const error_message = error instanceof Error ? error.message : "Unknown error";
+    const error_stack = error instanceof Error ? error.stack : undefined;
+    
+    logger.error("session_token_creation_failed", {
+      filename: get_filename(),
+      line_number: get_line_number(),
+      user_id,
+      email,
+      error_message,
+      error_stack,
+    });
+    
+    throw new Error("Failed to create session token");
+  }
+}
+
+/**
+ * Validates a JWT session token
+ * Checks signature and expiration
+ * @param token - JWT token string
+ * @returns Validation result with user_id and email if valid
+ */
+export async function validate_session_token(
+  token: string,
+): Promise<ValidateSessionTokenResult> {
+  const logger = create_app_logger();
+  
+  try {
+    const secret = get_jwt_secret();
+    
+    const { payload } = await jwtVerify(token, 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) {
+      logger.warn("session_token_invalid_payload", {
+        filename: get_filename(),
+        line_number: get_line_number(),
+        error: "Token payload missing user_id or email",
+      });
+      
+      return { valid: false };
+    }
+    
+    logger.info("session_token_validated", {
+      filename: get_filename(),
+      line_number: get_line_number(),
+      user_id,
+      email,
+    });
+    
+    return {
+      valid: true,
+      user_id,
+      email,
+    };
+  } catch (error) {
+    const error_message = error instanceof Error ? error.message : "Unknown error";
+    
+    // jose throws JWTExpired, JWTInvalid, etc. - these are expected for invalid tokens
+    logger.debug("session_token_validation_failed", {
+      filename: get_filename(),
+      line_number: get_line_number(),
+      error_message,
+    });
+    
+    return { valid: false };
+  }
+}
+
+
+
+
+
+
+
+

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

@@ -0,0 +1,240 @@
+// file_description: shared service for creating and managing tokens in hazo_refresh_tokens table
+// section: imports
+import type { HazoConnectAdapter } from "hazo_connect";
+import { createCrudService } from "hazo_connect/server";
+import { randomBytes, randomUUID } from "crypto";
+import argon2 from "argon2";
+import { read_config_section } from "../config/config_loader.server";
+import { create_app_logger } from "../app_logger";
+
+// section: types
+export type TokenType = "refresh" | "password_reset" | "email_verification";
+
+export type CreateTokenParams = {
+  adapter: HazoConnectAdapter;
+  user_id: string;
+  token_type: TokenType;
+};
+
+export type CreateTokenResult = {
+  success: boolean;
+  raw_token?: string;
+  error?: string;
+};
+
+// section: helpers
+/**
+ * Gets token expiry hours from hazo_auth_config.ini for a specific token type
+ * Falls back to defaults if config is not found
+ * @param token_type - The type of token (refresh, password_reset, email_verification)
+ * @returns Number of hours until token expires
+ */
+function get_token_expiry_hours(token_type: TokenType): number {
+  const default_expiries: Record<TokenType, number> = {
+    refresh: 720, // 30 days
+    password_reset: 0.167, // 10 minutes
+    email_verification: 48, // 48 hours
+  };
+
+  const logger = create_app_logger();
+  const token_config_section = read_config_section("hazo_auth__tokens");
+
+  // Get expiry from config or environment variable or default
+  const config_key = `${token_type}_expiry_hours`;
+  const env_key = `HAZO_AUTH_${token_type.toUpperCase()}_TOKEN_EXPIRY_HOURS`;
+
+  const expiry_hours =
+    token_config_section?.[config_key] ||
+    process.env[env_key] ||
+    default_expiries[token_type];
+
+  return parseFloat(String(expiry_hours)) || default_expiries[token_type];
+}
+
+/**
+ * Creates a token for a user and stores it in hazo_refresh_tokens table
+ * Invalidates any existing tokens of the same type for the user before creating a new one
+ * @param params - Token creation parameters (adapter, user_id, token_type)
+ * @returns Token creation result with raw_token (for sending to user) or error
+ */
+export async function create_token(
+  params: CreateTokenParams,
+): Promise<CreateTokenResult> {
+  try {
+    const { adapter, user_id, token_type } = params;
+
+    // Create CRUD service for hazo_refresh_tokens table
+    const tokens_service = createCrudService(adapter, "hazo_refresh_tokens");
+
+    // Invalidate any existing tokens of this type for this user
+    // If token_type column doesn't exist, this will fail - catch and continue
+    let existing_tokens: unknown[] = [];
+    try {
+      existing_tokens = (await tokens_service.findBy({
+        user_id: user_id,
+        token_type: token_type,
+      })) as unknown[];
+    } catch (error) {
+      // If token_type column doesn't exist, try without it
+      // This is a fallback for databases that haven't had the migration applied
+      const logger = create_app_logger();
+      const error_message = error instanceof Error ? error.message : "Unknown error";
+      logger.warn("token_service_token_type_column_missing", {
+        filename: "token_service.ts",
+        line_number: 0,
+        user_id,
+        token_type,
+        error: error_message,
+        note: "token_type column may not exist, trying without filter",
+      });
+      // Try to find tokens by user_id only (less precise but works without migration)
+      try {
+        existing_tokens = (await tokens_service.findBy({
+          user_id: user_id,
+        })) as unknown[];
+      } catch (fallbackError) {
+        // If that also fails, log and continue (will just create new token)
+        const fallback_error_message = fallbackError instanceof Error ? fallbackError.message : "Unknown error";
+        logger.warn("token_service_query_existing_tokens_failed", {
+          filename: "token_service.ts",
+          line_number: 0,
+          user_id,
+          error: fallback_error_message,
+          note: "Could not query existing tokens, will create new token anyway",
+        });
+      }
+    }
+
+    if (Array.isArray(existing_tokens) && existing_tokens.length > 0) {
+      // Delete existing tokens (of this type if token_type exists, or all for user if not)
+      for (const token of existing_tokens) {
+        try {
+          await tokens_service.deleteById((token as { id: unknown }).id);
+        } catch (deleteError) {
+          const logger = create_app_logger();
+          const error_message = deleteError instanceof Error ? deleteError.message : "Unknown error";
+          logger.warn("token_service_delete_existing_token_failed", {
+            filename: "token_service.ts",
+            line_number: 0,
+            user_id,
+            token_id: (token as { id: unknown }).id,
+            error: error_message,
+          });
+        }
+      }
+    }
+
+    // Generate a secure random token
+    const raw_token = randomBytes(32).toString("hex");
+
+    // Hash the token before storing
+    const token_hash = await argon2.hash(raw_token);
+
+    // Get expiry hours from config
+    const expiry_hours = get_token_expiry_hours(token_type);
+
+    // Calculate expiration time (convert hours to milliseconds)
+    const expires_at = new Date();
+    expires_at.setTime(expires_at.getTime() + expiry_hours * 60 * 60 * 1000);
+
+    const now = new Date().toISOString();
+
+    // Insert the token into the database
+    // Try with token_type first, fallback to without if column doesn't exist
+    let inserted_tokens: unknown[];
+    try {
+      inserted_tokens = (await tokens_service.insert({
+        id: randomUUID(),
+        user_id: user_id,
+        token_hash: token_hash,
+        token_type: token_type,
+        expires_at: expires_at.toISOString(),
+        created_at: now,
+      })) as unknown[];
+    } catch (error) {
+      // If token_type column doesn't exist, try without it
+      const logger = create_app_logger();
+      const error_message = error instanceof Error ? error.message : "Unknown error";
+      logger.warn("token_service_insert_with_token_type_failed", {
+        filename: "token_service.ts",
+        line_number: 0,
+        user_id,
+        token_type,
+        error: error_message,
+        note: "token_type column may not exist, inserting without it",
+      });
+      // Fallback: insert without token_type (will use default if column exists with default)
+      inserted_tokens = (await tokens_service.insert({
+        id: randomUUID(),
+        user_id: user_id,
+        token_hash: token_hash,
+        expires_at: expires_at.toISOString(),
+        created_at: now,
+      })) as unknown[];
+    }
+
+    // Verify insertion was successful
+    if (!Array.isArray(inserted_tokens) || inserted_tokens.length === 0) {
+      const logger = create_app_logger();
+      const error_msg = `Failed to create ${token_type} token - no rows inserted`;
+      logger.error("token_service_insertion_failed", {
+        filename: "token_service.ts",
+        line_number: 0,
+        user_id,
+        token_type,
+        error: error_msg,
+      });
+      return {
+        success: false,
+        error: error_msg,
+      };
+    }
+
+    const logger = create_app_logger();
+    logger.info("token_service_token_created", {
+      filename: "token_service.ts",
+      line_number: 0,
+      user_id,
+      token_type,
+    });
+    
+    // Log raw token and test URLs in debug mode (logger handles dev mode)
+    logger.debug("token_service_raw_token", {
+      filename: "token_service.ts",
+      line_number: 0,
+      user_id,
+      token_type,
+      raw_token,
+      test_url: token_type === "email_verification" 
+        ? `/hazo_auth/verify_email?token=${raw_token}`
+        : token_type === "password_reset"
+        ? `/hazo_auth/reset_password?token=${raw_token}`
+        : undefined,
+    });
+
+    return {
+      success: true,
+      raw_token,
+    };
+  } catch (error) {
+    const logger = create_app_logger();
+    const error_message =
+      error instanceof Error ? error.message : "Unknown error";
+    const error_stack = error instanceof Error ? error.stack : undefined;
+
+    logger.error("token_service_create_token_error", {
+      filename: "token_service.ts",
+      line_number: 0,
+      user_id: params.user_id,
+      token_type: params.token_type,
+      error: error_message,
+      error_stack,
+    });
+
+    return {
+      success: false,
+      error: error_message,
+    };
+  }
+}
+

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

@@ -0,0 +1,189 @@
+// file_description: LRU cache implementation for hazo_get_user_profiles with TTL and size limits
+// section: imports
+import type { UserProfileInfo } from "./user_profiles_service";
+
+// section: types
+
+/**
+ * Cache entry structure for user profiles
+ */
+type ProfileCacheEntry = {
+  profile: UserProfileInfo;
+  timestamp: number; // Unix timestamp in milliseconds
+};
+
+// section: cache_class
+
+/**
+ * LRU cache implementation with TTL and size limits for user profiles
+ * Uses Map to maintain insertion order for LRU eviction
+ */
+class UserProfilesCache {
+  private cache: Map<string, ProfileCacheEntry>;
+  private max_size: number;
+  private ttl_ms: number;
+
+  constructor(max_size: number, ttl_minutes: number) {
+    this.cache = new Map();
+    this.max_size = max_size;
+    this.ttl_ms = ttl_minutes * 60 * 1000;
+  }
+
+  /**
+   * Gets a cached profile for a user
+   * Returns undefined if not found or expired
+   * @param user_id - User ID to look up
+   * @returns Profile or undefined
+   */
+  get(user_id: string): UserProfileInfo | undefined {
+    const entry = this.cache.get(user_id);
+
+    if (!entry) {
+      return undefined;
+    }
+
+    const now = Date.now();
+    const age = now - entry.timestamp;
+
+    // Check if entry is expired
+    if (age > this.ttl_ms) {
+      this.cache.delete(user_id);
+      return undefined;
+    }
+
+    // Move to end (most recently used)
+    this.cache.delete(user_id);
+    this.cache.set(user_id, entry);
+
+    return entry.profile;
+  }
+
+  /**
+   * Gets multiple profiles from cache
+   * Returns object with found profiles and missing IDs
+   * @param user_ids - Array of user IDs to look up
+   * @returns Object with cached profiles and IDs not in cache
+   */
+  get_many(user_ids: string[]): {
+    cached: UserProfileInfo[];
+    missing_ids: string[];
+  } {
+    const cached: UserProfileInfo[] = [];
+    const missing_ids: string[] = [];
+
+    for (const user_id of user_ids) {
+      const profile = this.get(user_id);
+      if (profile) {
+        cached.push(profile);
+      } else {
+        missing_ids.push(user_id);
+      }
+    }
+
+    return { cached, missing_ids };
+  }
+
+  /**
+   * Sets a cache entry for a user profile
+   * Evicts least recently used entries if cache is full
+   * @param user_id - User ID
+   * @param profile - User profile data
+   */
+  set(user_id: string, profile: UserProfileInfo): void {
+    // Evict LRU entries if cache is full
+    while (this.cache.size >= this.max_size) {
+      const first_key = this.cache.keys().next().value;
+      if (first_key) {
+        this.cache.delete(first_key);
+      } else {
+        break;
+      }
+    }
+
+    const entry: ProfileCacheEntry = {
+      profile,
+      timestamp: Date.now(),
+    };
+
+    this.cache.set(user_id, entry);
+  }
+
+  /**
+   * Sets multiple cache entries at once
+   * @param profiles - Array of user profiles to cache
+   */
+  set_many(profiles: UserProfileInfo[]): void {
+    for (const profile of profiles) {
+      this.set(profile.user_id, profile);
+    }
+  }
+
+  /**
+   * Invalidates cache for a specific user
+   * @param user_id - User ID to invalidate
+   */
+  invalidate_user(user_id: string): void {
+    this.cache.delete(user_id);
+  }
+
+  /**
+   * Invalidates cache for multiple users
+   * @param user_ids - Array of user IDs to invalidate
+   */
+  invalidate_users(user_ids: string[]): void {
+    for (const user_id of user_ids) {
+      this.cache.delete(user_id);
+    }
+  }
+
+  /**
+   * Invalidates all cache entries
+   */
+  invalidate_all(): void {
+    this.cache.clear();
+  }
+
+  /**
+   * Gets cache statistics
+   * @returns Object with cache size and max size
+   */
+  get_stats(): {
+    size: number;
+    max_size: number;
+    ttl_minutes: number;
+  } {
+    return {
+      size: this.cache.size,
+      max_size: this.max_size,
+      ttl_minutes: this.ttl_ms / 60000,
+    };
+  }
+}
+
+// section: singleton
+// Global cache instance (initialized with defaults, will be configured on first use)
+let user_profiles_cache_instance: UserProfilesCache | null = null;
+
+/**
+ * Gets or creates the global user profiles cache instance
+ * @param max_size - Maximum cache size (default: 5000)
+ * @param ttl_minutes - TTL in minutes (default: 5)
+ * @returns User profiles cache instance
+ */
+export function get_user_profiles_cache(
+  max_size: number = 5000,
+  ttl_minutes: number = 5,
+): UserProfilesCache {
+  if (!user_profiles_cache_instance) {
+    user_profiles_cache_instance = new UserProfilesCache(max_size, ttl_minutes);
+  }
+  return user_profiles_cache_instance;
+}
+
+/**
+ * Resets the global cache instance (useful for testing)
+ */
+export function reset_user_profiles_cache(): void {
+  user_profiles_cache_instance = null;
+}
+