hazo_auth 1.0.5 → 1.2.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:
@@ -50,6 +259,56 @@ Because `src/app/hazo_auth` (pages) and `src/app/api/hazo_auth` (API routes) nee
 
 > The package expects these routes to live at `src/app/api/hazo_auth` and `src/app/hazo_auth` inside the consumer project. Without copying or linking them, Next.js won’t mount the auth pages or APIs.
 
+### Choose the UI Shell (Test Sidebar vs Standalone)
+
+By default, the pages render inside the “test workspace” sidebar so you can quickly preview every flow. When you reuse the routes inside another project you’ll usually want a clean, standalone wrapper instead. Set this in `hazo_auth_config.ini`:
+
+```ini
+[hazo_auth__ui_shell]
+# Options: test_sidebar | standalone
+layout_mode = standalone 
+# Optional tweaks for the standalone header wrapper/classes:
+# standalone_heading = Welcome back
+# standalone_description = Your description here
+# standalone_wrapper_class = min-h-screen bg-background py-8
+# standalone_content_class = mx-auto w-full max-w-4xl rounded-2xl border bg-card
+```
+
+- `test_sidebar`: keeps the developer sidebar (perfect for the demo workspace or Storybook screenshots).
+- `standalone`: renders the page body directly so it inherits your own app shell, layout, and theme tokens.
+- The wrapper and content class overrides let you align spacing/borders with your design system without editing package code.
+
+Every route (`/hazo_auth/login`, `/hazo_auth/register`, etc.) automatically looks at this config, so switching modes is instant.
+
+### Using Just the Layout Components
+
+Prefer to drop the forms into your own routes without copying the provided pages? Import the layouts directly and feed them a `data_client` plus any label/button overrides:
+
+```tsx
+// app/(auth)/login/page.tsx in your project
+import login_layout from "hazo_auth/components/layouts/login";
+import { createLayoutDataClient } from "hazo_auth/components/layouts/shared/data/layout_data_client";
+import { create_sqlite_hazo_connect } from "hazo_auth/lib/hazo_connect_setup";
+
+export default async function LoginPage() {
+  const hazoConnect = create_sqlite_hazo_connect();
+  const dataClient = createLayoutDataClient(hazoConnect);
+  const LoginLayout = login_layout;
+
+  return (
+    <div className="my-app-shell">
+      <LoginLayout
+        image_src="/marketing/login-hero.svg"
+        data_client={dataClient}
+        redirectRoute="/dashboard"
+      />
+    </div>
+  );
+}
+```
+
+The same import pattern works for every layout under `components/layouts/*`, so you can mix-and-match pieces (profile picture dialog, password field, etc.) wherever you need them.
+
 ## Authentication Service
 
 The `hazo_auth` package provides a comprehensive authentication and authorization system with role-based access control (RBAC). The main authentication utility is `hazo_get_auth`, which provides user details, permissions, and permission checking with built-in caching and rate limiting.
@@ -959,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/hazo_auth_config.example.ini

@@ -7,6 +7,31 @@
 # Database type: sqlite, postgrest, supabase, or file
 type = sqlite
 
+# UI shell controls whether pages render inside the developer sidebar or a minimal wrapper.
+[hazo_auth__ui_shell]
+# layout_mode = test_sidebar
+# Options:
+#   - test_sidebar: keeps the demo sidebar for quick testing in the package workspace.
+#   - standalone: renders pages in a minimal wrapper so consumers inherit their own shell/theme.
+#
+# Heading shown above standalone layouts
+# standalone_heading = Welcome to hazo auth
+#
+# Description beneath the heading for standalone layouts
+# standalone_description = Reuse the packaged authentication flows while inheriting your existing app shell styles.
+#
+# Tailwind utility classes applied to the standalone wrapper div
+# standalone_wrapper_class = cls_standalone_shell flex min-h-screen w-full items-center justify-center bg-background px-4 py-10
+#
+# Tailwind utility classes applied to the standalone inner content div
+# standalone_content_class = cls_standalone_shell_content w-full max-w-5xl shadow-xl rounded-2xl border bg-card
+#
+# Show/hide heading in standalone mode (true/false, default: true)
+# standalone_show_heading = true
+#
+# Show/hide description in standalone mode (true/false, default: true)
+# standalone_show_description = true
+
 # SQLite database configuration
 # Path to SQLite database file (relative to process.cwd() or absolute)
 sqlite_path = ./data/hazo_auth.sqlite
@@ -57,6 +82,10 @@ enable_admin_ui = true
 # Show name field (true/false)
 # Note: This is now deprecated, use hazo_auth__user_fields section instead
 # show_name_field = false
+#
+# Sign in link shown below register button
+# sign_in_path = /hazo_auth/login
+# sign_in_label = Sign in
 
 [hazo_auth__user_fields]
 # Shared user fields configuration used by register and my_settings layouts
@@ -104,6 +133,12 @@ enable_admin_ui = true
 # Redirect on successful login (leave empty to show success message instead)
 # redirect_route_on_successful_login = /
 
+# Forgot password + sign up links shown under login button
+# forgot_password_path = /hazo_auth/forgot_password
+# forgot_password_label = Forgot password?
+# create_account_path = /hazo_auth/register
+# create_account_label = Create account
+
 # Success message (shown when no redirect route is provided)
 # success_message = Successfully logged in
 
@@ -263,6 +298,12 @@ enable_admin_ui = true
 # Example: application_permission_list_defaults = PERM_ONE,PERM_TWO,PERM_THREE
 # application_permission_list_defaults = 
 
+[hazo_auth__initial_setup]
+# Initial setup configuration for initializing users, roles, and permissions
+# Email address of the super user to assign the default_super_user_role
+# This user will receive all permissions from application_permission_list_defaults
+# default_super_user_email = admin@example.com
+
 [hazo_auth__auth_utility]
 # Authentication utility configuration
 

package/instrumentation.ts

@@ -9,13 +9,13 @@ export async function register() {
       const hazo_notify_module = await import("hazo_notify");
       
       // Step 2: Load hazo_notify emailer configuration
-      // This reads from hazo_notify_config.ini in the project root (same location as hazo_auth_config.ini)
+      // This reads from hazo_notify_config.ini in the ui_component directory (same location as hazo_auth_config.ini)
       const { load_emailer_config } = hazo_notify_module;
       const notify_config = load_emailer_config();
       
       // Step 3: Pass the initialized configuration to hazo_auth email service
       // This allows the email service to reuse the same configuration instance
-      const { set_hazo_notify_instance } = await import("@/lib/services/email_service");
+      const { set_hazo_notify_instance } = await import("./src/lib/services/email_service");
       set_hazo_notify_instance(notify_config);
       
       // Log successful initialization

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hazo_auth",
-  "version": "1.0.5",
+  "version": "1.2.0",
   "files": [
     "src/**/*",
     "public/file.svg",
@@ -31,6 +31,7 @@
     "build-storybook": "storybook build",
     "dev:server": "tsx src/server/index.ts",
     "migrate": "tsx scripts/apply_migration.ts",
+    "init-users": "tsx scripts/init_users.ts init_users",
     "test": "cross-env NODE_ENV=test POSTGREST_URL=http://209.38.26.241:4402 POSTGREST_API_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiYXBpX3VzZXIifQ.zBoUGymrxTUk1DNYIGUCtQU4HFaWEHlbE9_8Y3hUaTw jest --runInBand",
     "test:watch": "cross-env NODE_ENV=test POSTGREST_URL=http://209.38.26.241:4402 POSTGREST_API_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiYXBpX3VzZXIifQ.zBoUGymrxTUk1DNYIGUCtQU4HFaWEHlbE9_8Y3hUaTw jest --watch"
   },