hazo_auth 1.1.0 → 1.3.0

package/README.md

@@ -29,6 +29,215 @@ After installing the package, you need to set up configuration files in your pro
 
 **Important:** The configuration files must be located in your project root directory (where `process.cwd()` points to), not inside `node_modules`. The package reads configuration from `process.cwd()` at runtime, so storing them elsewhere (including `node_modules/hazo_auth`) will break runtime access.
 
+### Database Setup
+
+Before using `hazo_auth`, you need to create the required database tables. Run the following SQL scripts in your PostgreSQL database:
+
+#### 1. Create the Profile Source Enum Type
+
+```sql
+-- Enum type for profile picture source
+CREATE TYPE hazo_enum_profile_source_enum AS ENUM ('gravatar', 'custom', 'predefined');
+```
+
+#### 2. Create the Users Table
+
+```sql
+-- Main users table
+CREATE TABLE hazo_users (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    email_address TEXT NOT NULL UNIQUE,
+    password_hash TEXT NOT NULL,
+    name TEXT,
+    email_verified BOOLEAN NOT NULL DEFAULT FALSE,
+    is_active BOOLEAN NOT NULL DEFAULT TRUE,
+    login_attempts INTEGER NOT NULL DEFAULT 0,
+    last_logon TIMESTAMP WITH TIME ZONE,
+    profile_picture_url TEXT,
+    profile_source hazo_enum_profile_source_enum,
+    mfa_secret TEXT,
+    url_on_logon TEXT,
+    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+    changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
+);
+
+-- Index for email lookups
+CREATE INDEX idx_hazo_users_email ON hazo_users(email_address);
+```
+
+#### 3. Create the Refresh Tokens Table
+
+```sql
+-- Refresh tokens table (used for password reset, email verification, etc.)
+CREATE TABLE hazo_refresh_tokens (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    user_id UUID NOT NULL REFERENCES hazo_users(id) ON DELETE CASCADE,
+    token_hash TEXT NOT NULL,
+    token_type TEXT NOT NULL,
+    expires_at TIMESTAMP WITH TIME ZONE NOT NULL,
+    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
+);
+
+-- Index for token lookups
+CREATE INDEX idx_hazo_refresh_tokens_user_id ON hazo_refresh_tokens(user_id);
+CREATE INDEX idx_hazo_refresh_tokens_token_type ON hazo_refresh_tokens(token_type);
+```
+
+#### 4. Create the Permissions Table
+
+```sql
+-- Permissions table for RBAC
+CREATE TABLE hazo_permissions (
+    id SERIAL PRIMARY KEY,
+    permission_name TEXT NOT NULL UNIQUE,
+    description TEXT,
+    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+    changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
+);
+```
+
+#### 5. Create the Roles Table
+
+```sql
+-- Roles table for RBAC
+CREATE TABLE hazo_roles (
+    id SERIAL PRIMARY KEY,
+    role_name TEXT NOT NULL UNIQUE,
+    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+    changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
+);
+```
+
+#### 6. Create the Role-Permissions Junction Table
+
+```sql
+-- Junction table linking roles to permissions
+CREATE TABLE hazo_role_permissions (
+    role_id INTEGER NOT NULL REFERENCES hazo_roles(id) ON DELETE CASCADE,
+    permission_id INTEGER NOT NULL REFERENCES hazo_permissions(id) ON DELETE CASCADE,
+    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+    changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+    PRIMARY KEY (role_id, permission_id)
+);
+
+-- Indexes for lookups
+CREATE INDEX idx_hazo_role_permissions_role_id ON hazo_role_permissions(role_id);
+CREATE INDEX idx_hazo_role_permissions_permission_id ON hazo_role_permissions(permission_id);
+```
+
+#### 7. Create the User-Roles Junction Table
+
+```sql
+-- Junction table linking users to roles
+CREATE TABLE hazo_user_roles (
+    user_id UUID NOT NULL REFERENCES hazo_users(id) ON DELETE CASCADE,
+    role_id INTEGER NOT NULL REFERENCES hazo_roles(id) ON DELETE CASCADE,
+    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+    changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+    PRIMARY KEY (user_id, role_id)
+);
+
+-- Indexes for lookups
+CREATE INDEX idx_hazo_user_roles_user_id ON hazo_user_roles(user_id);
+CREATE INDEX idx_hazo_user_roles_role_id ON hazo_user_roles(role_id);
+```
+
+#### Complete Setup Script
+
+For convenience, here's the complete SQL script to create all tables at once:
+
+```sql
+-- ============================================
+-- hazo_auth Database Setup Script
+-- ============================================
+
+-- 1. Create enum type
+CREATE TYPE hazo_enum_profile_source_enum AS ENUM ('gravatar', 'custom', 'predefined');
+
+-- 2. Create users table
+CREATE TABLE hazo_users (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    email_address TEXT NOT NULL UNIQUE,
+    password_hash TEXT NOT NULL,
+    name TEXT,
+    email_verified BOOLEAN NOT NULL DEFAULT FALSE,
+    is_active BOOLEAN NOT NULL DEFAULT TRUE,
+    login_attempts INTEGER NOT NULL DEFAULT 0,
+    last_logon TIMESTAMP WITH TIME ZONE,
+    profile_picture_url TEXT,
+    profile_source hazo_enum_profile_source_enum,
+    mfa_secret TEXT,
+    url_on_logon TEXT,
+    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+    changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
+);
+CREATE INDEX idx_hazo_users_email ON hazo_users(email_address);
+
+-- 3. Create refresh tokens table
+CREATE TABLE hazo_refresh_tokens (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    user_id UUID NOT NULL REFERENCES hazo_users(id) ON DELETE CASCADE,
+    token_hash TEXT NOT NULL,
+    token_type TEXT NOT NULL,
+    expires_at TIMESTAMP WITH TIME ZONE NOT NULL,
+    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
+);
+CREATE INDEX idx_hazo_refresh_tokens_user_id ON hazo_refresh_tokens(user_id);
+CREATE INDEX idx_hazo_refresh_tokens_token_type ON hazo_refresh_tokens(token_type);
+
+-- 4. Create permissions table
+CREATE TABLE hazo_permissions (
+    id SERIAL PRIMARY KEY,
+    permission_name TEXT NOT NULL UNIQUE,
+    description TEXT,
+    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+    changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
+);
+
+-- 5. Create roles table
+CREATE TABLE hazo_roles (
+    id SERIAL PRIMARY KEY,
+    role_name TEXT NOT NULL UNIQUE,
+    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+    changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
+);
+
+-- 6. Create role-permissions junction table
+CREATE TABLE hazo_role_permissions (
+    role_id INTEGER NOT NULL REFERENCES hazo_roles(id) ON DELETE CASCADE,
+    permission_id INTEGER NOT NULL REFERENCES hazo_permissions(id) ON DELETE CASCADE,
+    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+    changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+    PRIMARY KEY (role_id, permission_id)
+);
+CREATE INDEX idx_hazo_role_permissions_role_id ON hazo_role_permissions(role_id);
+CREATE INDEX idx_hazo_role_permissions_permission_id ON hazo_role_permissions(permission_id);
+
+-- 7. Create user-roles junction table
+CREATE TABLE hazo_user_roles (
+    user_id UUID NOT NULL REFERENCES hazo_users(id) ON DELETE CASCADE,
+    role_id INTEGER NOT NULL REFERENCES hazo_roles(id) ON DELETE CASCADE,
+    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+    changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+    PRIMARY KEY (user_id, role_id)
+);
+CREATE INDEX idx_hazo_user_roles_user_id ON hazo_user_roles(user_id);
+CREATE INDEX idx_hazo_user_roles_role_id ON hazo_user_roles(role_id);
+```
+
+#### Initialize Default Permissions and Super User
+
+After creating the tables, you can use the `init-users` script to set up default permissions and a super user:
+
+```bash
+npm run init-users
+```
+
+This script reads from `hazo_auth_config.ini` and:
+1. Creates default permissions from `application_permission_list_defaults`
+2. Creates a `default_super_user_role` role with all permissions
+3. Assigns the role to the user specified in `default_super_user_email`
+
 ### Expose hazo_auth Routes in the Consumer App
 
 Because `src/app/hazo_auth` (pages) and `src/app/api/hazo_auth` (API routes) need to be part of the consuming Next.js app’s routing tree, make sure they exist in your project’s `src/app` directory. Two recommended approaches:
@@ -1009,6 +1218,88 @@ Example custom styling:
 }
 ```
 
+## User Profile Service
+
+The `hazo_auth` package provides a batch user profile retrieval service for applications that need basic user information, such as chat applications or user lists.
+
+### `hazo_get_user_profiles`
+
+Retrieves basic profile information for multiple users in a single batch call.
+
+**Location:** `src/lib/services/user_profiles_service.ts`
+
+**Function Signature:**
+```typescript
+import { hazo_get_user_profiles } from "hazo_auth/lib/services/user_profiles_service";
+import type { GetProfilesResult, UserProfileInfo } from "hazo_auth/lib/services/user_profiles_service";
+
+async function hazo_get_user_profiles(
+  adapter: HazoConnectAdapter,
+  user_ids: string[],
+): Promise<GetProfilesResult>
+```
+
+**Return Type:**
+```typescript
+type UserProfileInfo = {
+  user_id: string;
+  profile_picture_url: string | null;
+  email: string;
+  name: string | null;
+  days_since_created: number;
+};
+
+type GetProfilesResult = {
+  success: boolean;
+  profiles: UserProfileInfo[];
+  not_found_ids: string[];
+  error?: string;
+};
+```
+
+**Features:**
+- **Batch Retrieval:** Fetches multiple user profiles in a single database query
+- **Deduplication:** Automatically removes duplicate user IDs from input
+- **Not Found Tracking:** Returns list of user IDs that were not found in the database
+- **Profile Picture:** Returns the resolved profile picture URL (Gravatar, library, or uploaded)
+- **Account Age:** Calculates days since account creation
+
+**Example Usage:**
+
+```typescript
+// In an API route or server component
+import { hazo_get_user_profiles } from "hazo_auth/lib/services/user_profiles_service";
+import { get_hazo_connect_instance } from "hazo_auth/lib/hazo_connect_instance.server";
+
+export async function GET(request: NextRequest) {
+  const adapter = get_hazo_connect_instance();
+  
+  // Get profiles for multiple users (e.g., chat participants)
+  const result = await hazo_get_user_profiles(adapter, [
+    "user-id-1",
+    "user-id-2",
+    "user-id-3",
+  ]);
+
+  if (!result.success) {
+    return NextResponse.json({ error: result.error }, { status: 500 });
+  }
+
+  // result.profiles contains found user profiles
+  // result.not_found_ids contains IDs that weren't found
+  return NextResponse.json({
+    profiles: result.profiles,
+    not_found: result.not_found_ids,
+  });
+}
+```
+
+**Use Cases:**
+- Chat applications displaying participant information
+- User lists with profile pictures and names
+- Activity feeds showing user details
+- Any feature requiring batch user profile lookups
+
 ### Local Development (for package contributors)
 
 - `npm install` to install dependencies.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hazo_auth",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "files": [
     "src/**/*",
     "public/file.svg",
@@ -103,7 +103,7 @@
     "better-sqlite3": "^12.4.1",
     "cross-env": "^10.1.0",
     "eslint": "^8.57.0",
-    "eslint-config-next": "^14.2.7",
+    "eslint-config-next": "^16.0.4",
     "eslint-plugin-storybook": "^10.0.6",
     "jest": "^30.2.0",
     "jest-environment-jsdom": "^29.7.0",

package/scripts/init_users.ts

@@ -16,7 +16,7 @@ type InitSummary = {
   role: {
     inserted: boolean;
     existing: boolean;
-    role_id: number | null;
+    role_id: string | null;
   };
   role_permissions: {
     inserted: number;
@@ -115,7 +115,7 @@ async function init_users(): Promise<void> {
     console.log();
 
     // 2. Add permissions to hazo_permissions table
-    const permission_id_map: Record<string, number> = {};
+    const permission_id_map: Record<string, string> = {};
     const now = new Date().toISOString();
 
     for (const permission_name of permission_names) {
@@ -129,7 +129,7 @@ async function init_users(): Promise<void> {
 
       if (Array.isArray(existing_permissions) && existing_permissions.length > 0) {
         const existing_permission = existing_permissions[0];
-        const perm_id = existing_permission.id as number;
+        const perm_id = existing_permission.id as string;
         permission_id_map[trimmed_name] = perm_id;
         summary.permissions.existing.push(trimmed_name);
         console.log(`✓ Permission already exists: ${trimmed_name} (ID: ${perm_id})`);
@@ -143,8 +143,8 @@ async function init_users(): Promise<void> {
         });
 
         const perm_id = Array.isArray(new_permission)
-          ? (new_permission[0] as { id: number }).id
-          : (new_permission as { id: number }).id;
+          ? (new_permission[0] as { id: string }).id
+          : (new_permission as { id: string }).id;
         permission_id_map[trimmed_name] = perm_id;
         summary.permissions.inserted.push(trimmed_name);
         console.log(`✓ Inserted permission: ${trimmed_name} (ID: ${perm_id})`);
@@ -159,9 +159,9 @@ async function init_users(): Promise<void> {
       role_name,
     });
 
-    let role_id: number;
+    let role_id: string;
     if (Array.isArray(existing_roles) && existing_roles.length > 0) {
-      role_id = existing_roles[0].id as number;
+      role_id = existing_roles[0].id as string;
       summary.role.existing = true;
       summary.role.role_id = role_id;
       console.log(`✓ Role already exists: ${role_name} (ID: ${role_id})`);
@@ -173,8 +173,8 @@ async function init_users(): Promise<void> {
       });
 
       role_id = Array.isArray(new_role)
-        ? (new_role[0] as { id: number }).id
-        : (new_role as { id: number }).id;
+        ? (new_role[0] as { id: string }).id
+        : (new_role as { id: string }).id;
       summary.role.inserted = true;
       summary.role.role_id = role_id;
       console.log(`✓ Created role: ${role_name} (ID: ${role_id})`);

package/src/lib/services/user_profiles_service.ts

@@ -0,0 +1,143 @@
+// file_description: service for batch retrieval of basic user profile information for chat applications and similar use cases
+// section: imports
+import type { HazoConnectAdapter } from "hazo_connect";
+import { createCrudService } from "hazo_connect/server";
+import { differenceInDays } from "date-fns";
+import { create_app_logger } from "../app_logger";
+import { sanitize_error_for_user } from "../utils/error_sanitizer";
+
+// section: types
+/**
+ * Basic user profile information returned by get_profiles
+ * Contains resolved profile picture URL, email, name, and account age
+ */
+export type UserProfileInfo = {
+  user_id: string;
+  profile_picture_url: string | null;
+  email: string;
+  name: string | null;
+  days_since_created: number;
+};
+
+/**
+ * Result type for get_profiles function
+ * Includes found profiles and list of IDs that were not found
+ */
+export type GetProfilesResult = {
+  success: boolean;
+  profiles: UserProfileInfo[];
+  not_found_ids: string[];
+  error?: string;
+};
+
+// section: helpers
+/**
+ * Retrieves basic profile information for multiple users in a single batch call
+ * Useful for chat applications and similar use cases where basic user info is needed
+ * @param adapter - The hazo_connect adapter instance
+ * @param user_ids - Array of user IDs to retrieve profiles for
+ * @returns GetProfilesResult with found profiles and list of not found IDs
+ */
+export async function hazo_get_user_profiles(
+  adapter: HazoConnectAdapter,
+  user_ids: string[],
+): Promise<GetProfilesResult> {
+  const logger = create_app_logger();
+
+  try {
+    // Handle empty input
+    if (!user_ids || user_ids.length === 0) {
+      return {
+        success: true,
+        profiles: [],
+        not_found_ids: [],
+      };
+    }
+
+    // Remove duplicates from input
+    const unique_user_ids = [...new Set(user_ids)];
+
+    // Create CRUD service for hazo_users table
+    const users_service = createCrudService(adapter, "hazo_users");
+
+    // Query users by IDs using the 'in' filter
+    // PostgREST supports 'in' filter syntax: id=in.(id1,id2,id3)
+    const users = await users_service.findBy({
+      id: `in.(${unique_user_ids.join(",")})`,
+    });
+
+    // Handle case where no users are found
+    if (!Array.isArray(users)) {
+    logger.warn("hazo_get_user_profiles_unexpected_response", {
+      filename: "user_profiles_service.ts",
+      line_number: 70,
+      message: "Unexpected response format from database query",
+      user_ids: unique_user_ids,
+    });
+
+      return {
+        success: true,
+        profiles: [],
+        not_found_ids: unique_user_ids,
+      };
+    }
+
+    // Build set of found user IDs for quick lookup
+    const found_user_ids = new Set(users.map((user) => user.id as string));
+
+    // Determine which user IDs were not found
+    const not_found_ids = unique_user_ids.filter((id) => !found_user_ids.has(id));
+
+    // Transform database records to UserProfileInfo
+    const now = new Date();
+    const profiles: UserProfileInfo[] = users.map((user) => {
+      const created_at = user.created_at as string;
+      const created_date = new Date(created_at);
+      const days_since_created = differenceInDays(now, created_date);
+
+      return {
+        user_id: user.id as string,
+        profile_picture_url: (user.profile_picture_url as string) || null,
+        email: user.email_address as string,
+        name: (user.name as string) || null,
+        days_since_created,
+      };
+    });
+
+    // Log successful retrieval
+    logger.info("hazo_get_user_profiles_success", {
+      filename: "user_profiles_service.ts",
+      line_number: 105,
+      message: "Successfully retrieved user profiles",
+      requested_count: unique_user_ids.length,
+      found_count: profiles.length,
+      not_found_count: not_found_ids.length,
+    });
+
+    return {
+      success: true,
+      profiles,
+      not_found_ids,
+    };
+  } catch (error) {
+    const user_friendly_error = sanitize_error_for_user(error, {
+      logToConsole: true,
+      logToLogger: true,
+      logger,
+      context: {
+        filename: "user_profiles_service.ts",
+        line_number: 122,
+        operation: "hazo_get_user_profiles",
+        user_ids_count: user_ids?.length || 0,
+      },
+    });
+
+    return {
+      success: false,
+      profiles: [],
+      not_found_ids: [],
+      error: user_friendly_error,
+    };
+  }
+}
+