hazo_auth 4.1.0 → 4.3.0

package/cli-src/lib/auth/auth_cache.ts

@@ -0,0 +1,220 @@
+// file_description: LRU cache implementation for hazo_get_auth with TTL and size limits
+// section: imports
+import type { HazoAuthUser } from "./auth_types";
+
+// section: types
+
+/**
+ * Cache entry structure
+ */
+type CacheEntry = {
+  user: HazoAuthUser;
+  permissions: string[];
+  role_ids: number[];
+  timestamp: number; // Unix timestamp in milliseconds
+  cache_version: number; // Version number for smart invalidation
+};
+
+/**
+ * LRU cache implementation with TTL and size limits
+ * Uses Map to maintain insertion order for LRU eviction
+ */
+class AuthCache {
+  private cache: Map<string, CacheEntry>;
+  private max_size: number;
+  private ttl_ms: number;
+  private max_age_ms: number;
+  private role_version_map: Map<number, number>; // Track version per role for smart invalidation
+
+  constructor(
+    max_size: number,
+    ttl_minutes: number,
+    max_age_minutes: number,
+  ) {
+    this.cache = new Map();
+    this.max_size = max_size;
+    this.ttl_ms = ttl_minutes * 60 * 1000;
+    this.max_age_ms = max_age_minutes * 60 * 1000;
+    this.role_version_map = new Map();
+  }
+
+  /**
+   * Gets a cache entry for a user
+   * Returns undefined if not found, expired, or too old
+   * @param user_id - User ID to look up
+   * @returns Cache entry or undefined
+   */
+  get(user_id: string): CacheEntry | 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 (TTL)
+    if (age > this.ttl_ms) {
+      this.cache.delete(user_id);
+      return undefined;
+    }
+
+    // Check if entry is too old (force refresh threshold)
+    if (age > this.max_age_ms) {
+      // Don't delete, but mark as stale so caller can refresh
+      // Return undefined to force refresh
+      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;
+  }
+
+  /**
+   * Sets a cache entry for a user
+   * Evicts least recently used entries if cache is full
+   * @param user_id - User ID
+   * @param user - User data
+   * @param permissions - User permissions
+   * @param role_ids - User role IDs
+   */
+  set(
+    user_id: string,
+    user: HazoAuthUser,
+    permissions: string[],
+    role_ids: number[],
+  ): 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;
+      }
+    }
+
+    // Get current cache version for user's roles
+    const cache_version = this.get_max_role_version(role_ids);
+
+    const entry: CacheEntry = {
+      user,
+      permissions,
+      role_ids,
+      timestamp: Date.now(),
+      cache_version,
+    };
+
+    this.cache.set(user_id, entry);
+  }
+
+  /**
+   * 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 all users with specific roles
+   * Uses cache version to determine if invalidation is needed
+   * @param role_ids - Array of role IDs to invalidate
+   */
+  invalidate_by_roles(role_ids: number[]): void {
+    // Increment version for affected roles
+    for (const role_id of role_ids) {
+      const current_version = this.role_version_map.get(role_id) || 0;
+      this.role_version_map.set(role_id, current_version + 1);
+    }
+
+    // Remove entries where cache version is older than role version
+    const entries_to_remove: string[] = [];
+    for (const [user_id, entry] of this.cache.entries()) {
+      const max_role_version = this.get_max_role_version(entry.role_ids);
+      if (max_role_version > entry.cache_version) {
+        entries_to_remove.push(user_id);
+      }
+    }
+
+    for (const user_id of entries_to_remove) {
+      this.cache.delete(user_id);
+    }
+  }
+
+  /**
+   * Invalidates all cache entries
+   */
+  invalidate_all(): void {
+    this.cache.clear();
+  }
+
+  /**
+   * Gets the maximum cache version for a set of roles
+   * Used to determine if cache entry is stale
+   * @param role_ids - Array of role IDs
+   * @returns Maximum version number
+   */
+  private get_max_role_version(role_ids: number[]): number {
+    if (role_ids.length === 0) {
+      return 0;
+    }
+
+    let max_version = 0;
+    for (const role_id of role_ids) {
+      const version = this.role_version_map.get(role_id) || 0;
+      max_version = Math.max(max_version, version);
+    }
+
+    return max_version;
+  }
+
+  /**
+   * Gets cache statistics
+   * @returns Object with cache size, max size, and hit rate estimate
+   */
+  get_stats(): {
+    size: number;
+    max_size: number;
+  } {
+    return {
+      size: this.cache.size,
+      max_size: this.max_size,
+    };
+  }
+}
+
+// section: singleton
+// Global cache instance (initialized with defaults, will be configured on first use)
+let auth_cache_instance: AuthCache | null = null;
+
+/**
+ * Gets or creates the global auth cache instance
+ * @param max_size - Maximum cache size (default: 10000)
+ * @param ttl_minutes - TTL in minutes (default: 15)
+ * @param max_age_minutes - Max age in minutes (default: 30)
+ * @returns Auth cache instance
+ */
+export function get_auth_cache(
+  max_size: number = 10000,
+  ttl_minutes: number = 15,
+  max_age_minutes: number = 30,
+): AuthCache {
+  if (!auth_cache_instance) {
+    auth_cache_instance = new AuthCache(max_size, ttl_minutes, max_age_minutes);
+  }
+  return auth_cache_instance;
+}
+
+/**
+ * Resets the global cache instance (useful for testing)
+ */
+export function reset_auth_cache(): void {
+  auth_cache_instance = null;
+}
+

package/cli-src/lib/auth/auth_rate_limiter.ts

@@ -0,0 +1,121 @@
+// 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/cli-src/lib/auth/auth_types.ts

@@ -0,0 +1,110 @@
+// 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;
+};
+
+/**
+ * Scope access information returned when HRBAC scope checking is used
+ */
+export type ScopeAccessInfo = {
+  scope_type: string;
+  scope_id: string;
+  scope_seq: string;
+};
+
+/**
+ * Result type for hazo_get_auth function
+ * Returns authenticated state with user data and permissions, or unauthenticated state
+ * Optionally includes scope access information when HRBAC is used
+ */
+export type HazoAuthResult =
+  | {
+      authenticated: true;
+      user: HazoAuthUser;
+      permissions: string[];
+      permission_ok: boolean;
+      missing_permissions?: string[];
+      // HRBAC scope access fields (only present when scope options are provided)
+      scope_ok?: boolean;
+      scope_access_via?: ScopeAccessInfo;
+    }
+  | {
+      authenticated: false;
+      user: null;
+      permissions: [];
+      permission_ok: false;
+      scope_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;
+  // HRBAC (Hierarchical Role-Based Access Control) options
+  /**
+   * The scope level to check access for (e.g., "hazo_scopes_l3")
+   * If provided along with scope_id or scope_seq, enables HRBAC checking
+   */
+  scope_type?: string;
+  /**
+   * The scope ID (UUID) to check access for
+   * Takes precedence over scope_seq if both provided
+   */
+  scope_id?: string;
+  /**
+   * The scope seq (friendly ID like "L3_001") to check access for
+   * Used if scope_id is not provided
+   */
+  scope_seq?: string;
+};
+
+/**
+ * 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";
+  }
+}
+
+/**
+ * Custom error class for scope access denials in HRBAC
+ * Thrown when strict mode is enabled and user lacks access to required scope
+ */
+export class ScopeAccessError extends Error {
+  constructor(
+    public scope_type: string,
+    public scope_identifier: string,
+    public user_scopes: Array<{ scope_type: string; scope_id: string; scope_seq: string }>,
+  ) {
+    super(`Access denied to scope: ${scope_type} / ${scope_identifier}`);
+    this.name = "ScopeAccessError";
+  }
+}
+

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

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