hazo_auth 4.1.0 → 4.3.0

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

@@ -0,0 +1,554 @@
+// file_description: service for managing user scope assignments in HRBAC using hazo_connect
+// section: imports
+import type { HazoConnectAdapter } from "hazo_connect";
+import { createCrudService } from "hazo_connect/server";
+import { create_app_logger } from "../app_logger";
+import { sanitize_error_for_user } from "../utils/error_sanitizer";
+import {
+  type ScopeLevel,
+  SCOPE_LEVELS,
+  SCOPE_LEVEL_NUMBERS,
+  get_scope_by_id,
+  get_scope_by_seq,
+  get_scope_ancestors,
+  is_valid_scope_level,
+} from "./scope_service";
+
+// section: types
+export type UserScope = {
+  user_id: string;
+  scope_id: string;
+  scope_seq: string;
+  scope_type: ScopeLevel;
+  created_at: string;
+  changed_at: string;
+};
+
+export type UserScopeResult = {
+  success: boolean;
+  scope?: UserScope;
+  scopes?: UserScope[];
+  error?: string;
+};
+
+export type ScopeAccessCheckResult = {
+  has_access: boolean;
+  access_via?: {
+    scope_type: ScopeLevel;
+    scope_id: string;
+    scope_seq: string;
+  };
+  user_scopes?: UserScope[];
+};
+
+// section: helpers
+
+/**
+ * Gets all scope assignments for a user
+ */
+export async function get_user_scopes(
+  adapter: HazoConnectAdapter,
+  user_id: string,
+): Promise<UserScopeResult> {
+  try {
+    const user_scope_service = createCrudService(adapter, "hazo_user_scopes");
+    const scopes = await user_scope_service.findBy({ user_id });
+
+    return {
+      success: true,
+      scopes: Array.isArray(scopes) ? (scopes as UserScope[]) : [],
+    };
+  } catch (error) {
+    const logger = create_app_logger();
+    const error_message = sanitize_error_for_user(error, {
+      logToConsole: true,
+      logToLogger: true,
+      logger,
+      context: {
+        filename: "user_scope_service.ts",
+        line_number: 0,
+        operation: "get_user_scopes",
+        user_id,
+      },
+    });
+
+    return {
+      success: false,
+      error: error_message,
+    };
+  }
+}
+
+/**
+ * Gets all users assigned to a specific scope
+ */
+export async function get_users_by_scope(
+  adapter: HazoConnectAdapter,
+  scope_type: ScopeLevel,
+  scope_id: string,
+): Promise<UserScopeResult> {
+  try {
+    const user_scope_service = createCrudService(adapter, "hazo_user_scopes");
+    const scopes = await user_scope_service.findBy({ scope_type, scope_id });
+
+    return {
+      success: true,
+      scopes: Array.isArray(scopes) ? (scopes as UserScope[]) : [],
+    };
+  } catch (error) {
+    const logger = create_app_logger();
+    const error_message = sanitize_error_for_user(error, {
+      logToConsole: true,
+      logToLogger: true,
+      logger,
+      context: {
+        filename: "user_scope_service.ts",
+        line_number: 0,
+        operation: "get_users_by_scope",
+        scope_type,
+        scope_id,
+      },
+    });
+
+    return {
+      success: false,
+      error: error_message,
+    };
+  }
+}
+
+/**
+ * Assigns a scope to a user
+ */
+export async function assign_user_scope(
+  adapter: HazoConnectAdapter,
+  user_id: string,
+  scope_type: ScopeLevel,
+  scope_id: string,
+  scope_seq: string,
+): Promise<UserScopeResult> {
+  try {
+    const user_scope_service = createCrudService(adapter, "hazo_user_scopes");
+    const now = new Date().toISOString();
+
+    // Check if assignment already exists
+    const existing = await user_scope_service.findBy({
+      user_id,
+      scope_type,
+      scope_id,
+    });
+
+    if (Array.isArray(existing) && existing.length > 0) {
+      return {
+        success: true,
+        scope: existing[0] as UserScope, // Already assigned
+      };
+    }
+
+    // Verify the scope exists
+    const scope_result = await get_scope_by_id(adapter, scope_type, scope_id);
+    if (!scope_result.success) {
+      return {
+        success: false,
+        error: "Scope not found",
+      };
+    }
+
+    // Insert new assignment
+    const inserted = await user_scope_service.insert({
+      user_id,
+      scope_id,
+      scope_seq,
+      scope_type,
+      created_at: now,
+      changed_at: now,
+    });
+
+    if (!Array.isArray(inserted) || inserted.length === 0) {
+      return {
+        success: false,
+        error: "Failed to assign scope to user",
+      };
+    }
+
+    return {
+      success: true,
+      scope: inserted[0] as UserScope,
+    };
+  } catch (error) {
+    const logger = create_app_logger();
+    const error_message = sanitize_error_for_user(error, {
+      logToConsole: true,
+      logToLogger: true,
+      logger,
+      context: {
+        filename: "user_scope_service.ts",
+        line_number: 0,
+        operation: "assign_user_scope",
+        user_id,
+        scope_type,
+        scope_id,
+      },
+    });
+
+    return {
+      success: false,
+      error: error_message,
+    };
+  }
+}
+
+/**
+ * Removes a scope assignment from a user
+ */
+export async function remove_user_scope(
+  adapter: HazoConnectAdapter,
+  user_id: string,
+  scope_type: ScopeLevel,
+  scope_id: string,
+): Promise<UserScopeResult> {
+  try {
+    const user_scope_service = createCrudService(adapter, "hazo_user_scopes");
+
+    // Find the assignment
+    const existing = await user_scope_service.findBy({
+      user_id,
+      scope_type,
+      scope_id,
+    });
+
+    if (!Array.isArray(existing) || existing.length === 0) {
+      return {
+        success: true, // Already not assigned
+      };
+    }
+
+    // Delete using a filter-based approach since there's no single ID
+    // Note: hazo_user_scopes uses composite primary key (user_id, scope_id, scope_type)
+    // We need to find and delete by the combination
+    const existing_scope = existing[0] as UserScope;
+
+    // Use raw delete with filters if available, otherwise try by the composite key pattern
+    // Most hazo_connect adapters support deleteBy or similar
+    try {
+      // Try to delete by finding records with matching criteria
+      const all_user_scopes = await user_scope_service.findBy({ user_id });
+      if (Array.isArray(all_user_scopes)) {
+        for (const scope of all_user_scopes) {
+          const s = scope as UserScope;
+          if (s.scope_type === scope_type && s.scope_id === scope_id) {
+            // If the record has an id field, use it
+            if ((scope as Record<string, unknown>).id) {
+              await user_scope_service.deleteById((scope as Record<string, unknown>).id as string);
+            }
+            break;
+          }
+        }
+      }
+    } catch {
+      // Fallback: Some adapters might not support this pattern
+      const logger = create_app_logger();
+      logger.warn("user_scope_delete_fallback", {
+        filename: "user_scope_service.ts",
+        line_number: 0,
+        note: "Delete by composite key not fully supported",
+      });
+    }
+
+    return {
+      success: true,
+      scope: existing_scope,
+    };
+  } catch (error) {
+    const logger = create_app_logger();
+    const error_message = sanitize_error_for_user(error, {
+      logToConsole: true,
+      logToLogger: true,
+      logger,
+      context: {
+        filename: "user_scope_service.ts",
+        line_number: 0,
+        operation: "remove_user_scope",
+        user_id,
+        scope_type,
+        scope_id,
+      },
+    });
+
+    return {
+      success: false,
+      error: error_message,
+    };
+  }
+}
+
+/**
+ * Bulk update user scope assignments
+ * Replaces all existing assignments with the new set
+ */
+export async function update_user_scopes(
+  adapter: HazoConnectAdapter,
+  user_id: string,
+  new_scopes: Array<{ scope_type: ScopeLevel; scope_id: string; scope_seq: string }>,
+): Promise<UserScopeResult> {
+  try {
+    // Get current scopes
+    const current_result = await get_user_scopes(adapter, user_id);
+    if (!current_result.success) {
+      return current_result;
+    }
+
+    const current_scopes = current_result.scopes || [];
+
+    // Determine scopes to add and remove
+    const current_keys = new Set(
+      current_scopes.map((s) => `${s.scope_type}:${s.scope_id}`),
+    );
+    const new_keys = new Set(
+      new_scopes.map((s) => `${s.scope_type}:${s.scope_id}`),
+    );
+
+    // Remove scopes not in new set
+    for (const scope of current_scopes) {
+      const key = `${scope.scope_type}:${scope.scope_id}`;
+      if (!new_keys.has(key)) {
+        await remove_user_scope(adapter, user_id, scope.scope_type, scope.scope_id);
+      }
+    }
+
+    // Add scopes not in current set
+    for (const scope of new_scopes) {
+      const key = `${scope.scope_type}:${scope.scope_id}`;
+      if (!current_keys.has(key)) {
+        const result = await assign_user_scope(
+          adapter,
+          user_id,
+          scope.scope_type,
+          scope.scope_id,
+          scope.scope_seq,
+        );
+        if (!result.success) {
+          return result;
+        }
+      }
+    }
+
+    // Return updated scopes
+    return get_user_scopes(adapter, user_id);
+  } catch (error) {
+    const logger = create_app_logger();
+    const error_message = sanitize_error_for_user(error, {
+      logToConsole: true,
+      logToLogger: true,
+      logger,
+      context: {
+        filename: "user_scope_service.ts",
+        line_number: 0,
+        operation: "update_user_scopes",
+        user_id,
+      },
+    });
+
+    return {
+      success: false,
+      error: error_message,
+    };
+  }
+}
+
+/**
+ * Checks if a user has access to a specific scope
+ * Access is granted if:
+ * 1. User has the exact scope assigned, OR
+ * 2. User has access to an ancestor scope (L2 user can access L3, L4, etc.)
+ *
+ * @param adapter - HazoConnect adapter
+ * @param user_id - User ID to check
+ * @param target_scope_type - The scope level being accessed
+ * @param target_scope_id - The scope ID being accessed (optional if target_scope_seq provided)
+ * @param target_scope_seq - The scope seq being accessed (optional if target_scope_id provided)
+ */
+export async function check_user_scope_access(
+  adapter: HazoConnectAdapter,
+  user_id: string,
+  target_scope_type: ScopeLevel,
+  target_scope_id?: string,
+  target_scope_seq?: string,
+): Promise<ScopeAccessCheckResult> {
+  try {
+    // Resolve scope ID if only seq provided
+    let resolved_scope_id = target_scope_id;
+    let resolved_scope_seq = target_scope_seq;
+
+    if (!resolved_scope_id && resolved_scope_seq) {
+      const scope_result = await get_scope_by_seq(
+        adapter,
+        target_scope_type,
+        resolved_scope_seq,
+      );
+      if (!scope_result.success || !scope_result.scope) {
+        return { has_access: false };
+      }
+      resolved_scope_id = scope_result.scope.id;
+    } else if (resolved_scope_id && !resolved_scope_seq) {
+      const scope_result = await get_scope_by_id(
+        adapter,
+        target_scope_type,
+        resolved_scope_id,
+      );
+      if (!scope_result.success || !scope_result.scope) {
+        return { has_access: false };
+      }
+      resolved_scope_seq = scope_result.scope.seq;
+    }
+
+    if (!resolved_scope_id) {
+      return { has_access: false };
+    }
+
+    // Get user's assigned scopes
+    const user_scopes_result = await get_user_scopes(adapter, user_id);
+    if (!user_scopes_result.success || !user_scopes_result.scopes) {
+      return { has_access: false };
+    }
+
+    const user_scopes = user_scopes_result.scopes;
+
+    // Check 1: Does user have exact scope assigned?
+    for (const user_scope of user_scopes) {
+      if (
+        user_scope.scope_type === target_scope_type &&
+        user_scope.scope_id === resolved_scope_id
+      ) {
+        return {
+          has_access: true,
+          access_via: {
+            scope_type: user_scope.scope_type,
+            scope_id: user_scope.scope_id,
+            scope_seq: user_scope.scope_seq,
+          },
+          user_scopes,
+        };
+      }
+    }
+
+    // Check 2: Does user have access via an ancestor scope?
+    // Get all ancestors of the target scope
+    const ancestors_result = await get_scope_ancestors(
+      adapter,
+      target_scope_type,
+      resolved_scope_id,
+    );
+
+    if (ancestors_result.success && ancestors_result.scopes) {
+      const ancestors = ancestors_result.scopes;
+
+      // For each ancestor, check if user has it assigned
+      // Need to determine the level of each ancestor
+      let current_level = SCOPE_LEVEL_NUMBERS[target_scope_type];
+
+      for (const ancestor of ancestors) {
+        current_level--;
+        const ancestor_level = `hazo_scopes_l${current_level}` as ScopeLevel;
+
+        for (const user_scope of user_scopes) {
+          if (
+            user_scope.scope_type === ancestor_level &&
+            user_scope.scope_id === ancestor.id
+          ) {
+            // User has access via this ancestor
+            return {
+              has_access: true,
+              access_via: {
+                scope_type: user_scope.scope_type,
+                scope_id: user_scope.scope_id,
+                scope_seq: user_scope.scope_seq,
+              },
+              user_scopes,
+            };
+          }
+        }
+      }
+    }
+
+    // No access
+    return {
+      has_access: false,
+      user_scopes,
+    };
+  } catch (error) {
+    const logger = create_app_logger();
+    logger.error("check_user_scope_access_error", {
+      filename: "user_scope_service.ts",
+      line_number: 0,
+      error: error instanceof Error ? error.message : "Unknown error",
+      user_id,
+      target_scope_type,
+      target_scope_id,
+    });
+
+    return { has_access: false };
+  }
+}
+
+/**
+ * Gets the effective scopes a user has access to
+ * This includes directly assigned scopes and all their descendants
+ */
+export async function get_user_effective_scopes(
+  adapter: HazoConnectAdapter,
+  user_id: string,
+): Promise<{
+  success: boolean;
+  direct_scopes?: UserScope[];
+  inherited_scope_types?: ScopeLevel[];
+  error?: string;
+}> {
+  try {
+    const user_scopes_result = await get_user_scopes(adapter, user_id);
+    if (!user_scopes_result.success) {
+      return {
+        success: false,
+        error: user_scopes_result.error,
+      };
+    }
+
+    const direct_scopes = user_scopes_result.scopes || [];
+
+    // Determine which levels user has inherited access to
+    // If user has L2 access, they inherit L3, L4, L5, L6, L7
+    const inherited_levels = new Set<ScopeLevel>();
+
+    for (const scope of direct_scopes) {
+      const level_num = SCOPE_LEVEL_NUMBERS[scope.scope_type];
+      // Add all levels below this one
+      for (let i = level_num + 1; i <= 7; i++) {
+        inherited_levels.add(`hazo_scopes_l${i}` as ScopeLevel);
+      }
+    }
+
+    return {
+      success: true,
+      direct_scopes,
+      inherited_scope_types: Array.from(inherited_levels),
+    };
+  } catch (error) {
+    const logger = create_app_logger();
+    const error_message = sanitize_error_for_user(error, {
+      logToConsole: true,
+      logToLogger: true,
+      logger,
+      context: {
+        filename: "user_scope_service.ts",
+        line_number: 0,
+        operation: "get_user_effective_scopes",
+        user_id,
+      },
+    });
+
+    return {
+      success: false,
+      error: error_message,
+    };
+  }
+}

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

@@ -0,0 +1,141 @@
+// file_description: service for updating user profile information using hazo_connect
+// section: imports
+import type { HazoConnectAdapter } from "hazo_connect";
+import { createCrudService } from "hazo_connect/server";
+import { map_ui_source_to_db, type ProfilePictureSourceUI } from "./profile_picture_source_mapper";
+import { create_app_logger } from "../app_logger";
+import { sanitize_error_for_user } from "../utils/error_sanitizer";
+import { get_filename, get_line_number } from "../utils/api_route_helpers";
+
+// section: types
+export type UserUpdateData = {
+  name?: string;
+  email?: string;
+  profile_picture_url?: string;
+  profile_source?: ProfilePictureSourceUI;
+};
+
+export type UserUpdateResult = {
+  success: boolean;
+  email_changed?: boolean;
+  error?: string;
+};
+
+// section: helpers
+/**
+ * Updates user profile information (name, email)
+ * If email is changed, sets email_verified to false
+ * @param adapter - The hazo_connect adapter instance
+ * @param user_id - The user ID to update
+ * @param data - User update data (name, email)
+ * @returns User update result with success status, email_changed flag, or error
+ */
+export async function update_user_profile(
+  adapter: HazoConnectAdapter,
+  user_id: string,
+  data: UserUpdateData,
+): Promise<UserUpdateResult> {
+  try {
+    const { name, email } = data;
+
+    // Create CRUD service for hazo_users table
+    const users_service = createCrudService(adapter, "hazo_users");
+
+    // Get current user data
+    const users = await users_service.findBy({
+      id: user_id,
+    });
+
+    if (!Array.isArray(users) || users.length === 0) {
+      return {
+        success: false,
+        error: "User not found",
+      };
+    }
+
+    const current_user = users[0];
+    const current_email = current_user.email_address as string;
+    const email_changed = email !== undefined && email !== current_email;
+
+    // If email is being changed, check if new email already exists
+    if (email_changed) {
+      const existing_users = await users_service.findBy({
+        email_address: email,
+      });
+
+      if (Array.isArray(existing_users) && existing_users.length > 0) {
+        // Check if it's the same user
+        const existing_user = existing_users[0];
+        if (existing_user.id !== user_id) {
+          return {
+            success: false,
+            error: "Email address already registered",
+          };
+        }
+      }
+
+      // Validate email format
+      const email_regex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+      if (!email_regex.test(email)) {
+        return {
+          success: false,
+          error: "Invalid email address format",
+        };
+      }
+    }
+
+    // Prepare update data
+    const update_data: Record<string, unknown> = {
+      changed_at: new Date().toISOString(),
+    };
+
+    if (name !== undefined) {
+      update_data.name = name;
+    }
+
+    if (email !== undefined) {
+      update_data.email_address = email;
+    }
+
+    if (data.profile_picture_url !== undefined) {
+      update_data.profile_picture_url = data.profile_picture_url;
+    }
+
+    if (data.profile_source !== undefined) {
+      // Map UI source value to database enum value
+      update_data.profile_source = map_ui_source_to_db(data.profile_source);
+    }
+
+    // If email changed, set email_verified to false
+    if (email_changed) {
+      update_data.email_verified = false;
+    }
+
+    // Update user in database
+    await users_service.updateById(user_id, update_data);
+
+    return {
+      success: true,
+      email_changed,
+    };
+  } catch (error) {
+    const logger = create_app_logger();
+    const user_friendly_error = sanitize_error_for_user(error, {
+      logToConsole: true,
+      logToLogger: true,
+      logger,
+      context: {
+        filename: "user_update_service.ts",
+        line_number: get_line_number(),
+        user_id,
+        operation: "update_user_profile",
+      },
+    });
+
+    return {
+      success: false,
+      error: user_friendly_error,
+    };
+  }
+}
+