hazo_auth 1.6.2 → 1.6.5

package/README.md

@@ -648,7 +648,52 @@ export default async function LoginPage() {
 - `ResetPasswordLayout` - Set new password with token
 - `EmailVerificationLayout` - Verify email address
 - `MySettingsLayout` - User profile and settings
-- `UserManagementLayout` - Admin user/role management
+- `UserManagementLayout` - Admin user/role management (requires user_management API routes)
+
+### User Management Component
+
+The `UserManagementLayout` component provides a comprehensive admin interface for managing users, roles, and permissions. It requires the user_management API routes to be set up in your project.
+
+**Required Permissions:**
+- `admin_user_management` - Access to Users tab
+- `admin_role_management` - Access to Roles tab
+- `admin_permission_management` - Access to Permissions tab
+
+**Required API Routes:**
+The `UserManagementLayout` component requires the following API routes to be created in your project:
+
+```typescript
+// app/api/hazo_auth/user_management/users/route.ts
+export { GET, PATCH, POST } from "hazo_auth/server/routes";
+
+// app/api/hazo_auth/user_management/permissions/route.ts
+export { GET, POST, PUT, DELETE } from "hazo_auth/server/routes";
+
+// app/api/hazo_auth/user_management/roles/route.ts
+export { GET, POST, PUT } from "hazo_auth/server/routes";
+
+// app/api/hazo_auth/user_management/users/roles/route.ts
+export { GET, POST, PUT } from "hazo_auth/server/routes";
+```
+
+**Note:** These routes are automatically created when you run `npx hazo_auth generate-routes`. The routes handle:
+- **Users:** List users, deactivate users, send password reset emails
+- **Permissions:** List permissions (from DB and config), migrate config permissions to DB, create/update/delete permissions
+- **Roles:** List roles with permissions, create roles, update role-permission assignments
+- **User Roles:** Get user roles, assign roles to users, bulk update user role assignments
+
+**Example Usage:**
+
+```tsx
+// app/hazo_auth/user_management/page.tsx
+import { UserManagementLayout } from "hazo_auth/components/layouts/user_management";
+
+export default function UserManagementPage() {
+  return <UserManagementLayout />;
+}
+```
+
+The component automatically shows/hides tabs based on the user's permissions, so users will only see the tabs they have access to.
 
 **Shared Components:**
 - `ProfilePicMenu` / `ProfilePicMenuWrapper` - Navbar profile menu
@@ -680,6 +725,76 @@ layout_mode = standalone
 
 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.
 
+### Client-Side API Endpoint (Recommended)
+
+#### `/api/hazo_auth/me` (GET) - Standardized User Info Endpoint
+
+**⚠️ IMPORTANT: Use this endpoint for all client-side authentication checks. It always returns the same standardized format with permissions.**
+
+This is the **standardized endpoint** that ensures consistent response format across all projects. It always includes permissions and user information in a unified structure.
+
+**Endpoint:** `GET /api/hazo_auth/me`
+
+**Response Format (Authenticated):**
+```typescript
+{
+  authenticated: true,
+  // Top-level fields (for backward compatibility)
+  user_id: string,
+  email: string,
+  name: string | null,
+  email_verified: boolean,
+  last_logon: string | undefined,
+  profile_picture_url: string | null,
+  profile_source: "upload" | "library" | "gravatar" | "custom" | undefined,
+  // Permissions (always included)
+  user: {
+    id: string,
+    email_address: string,
+    name: string | null,
+    is_active: boolean,
+    profile_picture_url: string | null,
+  },
+  permissions: string[],
+  permission_ok: boolean,
+  missing_permissions?: string[],
+}
+```
+
+**Response Format (Not Authenticated):**
+```typescript
+{
+  authenticated: false
+}
+```
+
+**Example Usage:**
+
+```typescript
+// Client-side (React component)
+const response = await fetch("/api/hazo_auth/me", {
+  method: "GET",
+  credentials: "include",
+});
+
+const data = await response.json();
+
+if (data.authenticated) {
+  console.log("User:", data.user);
+  console.log("Email:", data.email);
+  console.log("Permissions:", data.permissions);
+  console.log("Permission OK:", data.permission_ok);
+}
+```
+
+**Why Use `/api/hazo_auth/me`?**
+- ✅ **Standardized format** - Always returns the same structure
+- ✅ **Always includes permissions** - No need for separate permission checks
+- ✅ **Backward compatible** - Top-level fields work with existing code
+- ✅ **Single source of truth** - Prevents downstream variations
+
+**Note:** The `use_auth_status` hook automatically uses this endpoint and includes permissions in its return value.
+
 ### Server-Side Functions
 
 #### `hazo_get_auth` (Recommended)
@@ -917,13 +1032,22 @@ enable_friendly_error_messages = true
 ## Profile Picture Menu Widget
 
 The Profile Picture Menu is a versatile component for navbar or sidebar that automatically displays:
-- **When authenticated**: User's profile picture with a dropdown menu containing user info, settings link, logout, and custom menu items
+- **When authenticated**: User's profile picture with a dropdown menu (navbar) or sidebar menu (sidebar) containing user info, settings link, logout, and custom menu items
 - **When not authenticated**: Sign Up and Sign In buttons (or a single button, configurable)
 
+### Variants
+
+The component supports two rendering variants:
+
+- **`dropdown`** (default): Renders as a clickable avatar that opens a dropdown menu. Use this for navbar/header contexts.
+- **`sidebar`**: Shows profile picture and name in a sidebar group. Clicking opens a dropdown menu with account actions. Use this inside `SidebarContent` for sidebar navigation.
+
 ### Basic Usage (Recommended)
 
 Use the `ProfilePicMenuWrapper` component which automatically loads configuration from `hazo_auth_config.ini`:
 
+#### Dropdown Variant (Navbar/Header)
+
 ```typescript
 // In your navbar or layout component
 import { ProfilePicMenuWrapper } from "hazo_auth/components/layouts/shared/components/profile_pic_menu_wrapper";
@@ -935,12 +1059,65 @@ export function Navbar() {
       <ProfilePicMenuWrapper 
         avatar_size="default" // "sm" | "default" | "lg"
         className="ml-auto"
+        // variant="dropdown" is the default
       />
     </nav>
   );
 }
 ```
 
+#### Sidebar Variant
+
+The sidebar variant shows only the profile picture and name. Clicking opens a dropdown menu with account actions:
+
+```typescript
+// In your sidebar component
+import { ProfilePicMenu } from "hazo_auth/components/layouts/shared";
+import { SidebarContent } from "hazo_auth/components/ui/sidebar";
+
+export function Sidebar() {
+  return (
+    <SidebarContent>
+      {/* Other sidebar groups */}
+      
+      {/* Profile menu as sidebar variant - shows avatar + name, clicking opens dropdown */}
+      <ProfilePicMenu 
+        variant="sidebar"
+        avatar_size="sm"
+        sidebar_group_label="Account" // Optional: defaults to "Account"
+        className="mt-auto" // Optional: push to bottom
+      />
+    </SidebarContent>
+  );
+}
+```
+
+### Direct Usage (Advanced)
+
+If you need more control, use `ProfilePicMenu` directly:
+
+```typescript
+import { ProfilePicMenu } from "hazo_auth/components/layouts/shared";
+
+// Dropdown variant (navbar)
+<ProfilePicMenu 
+  variant="dropdown"
+  avatar_size="sm"
+  settings_path="/settings"
+  logout_path="/api/logout"
+/>
+
+// Sidebar variant
+<ProfilePicMenu 
+  variant="sidebar"
+  avatar_size="sm"
+  sidebar_group_label="My Account"
+  custom_menu_items={[
+    { type: "link", label: "Dashboard", href: "/dashboard", order: 1, id: "dashboard" }
+  ]}
+/>
+```
+
 ### Configuration
 
 ```ini

package/SETUP_CHECKLIST.md

@@ -392,6 +392,41 @@ SELECT table_name FROM information_schema.tables WHERE table_name LIKE 'hazo_%';
 
 ---
 
+## Phase 3.1: Configure Default Permissions (Optional)
+
+The `hazo_auth_config.ini` file includes default permissions that will be available in the Permissions tab. These defaults are already configured when you run `npx hazo_auth init`.
+
+**Default permissions included:**
+- `admin_user_management`
+- `admin_role_management`
+- `admin_permission_management`
+
+**To customize permissions:**
+
+Edit `hazo_auth_config.ini`:
+```ini
+[hazo_auth__user_management]
+application_permission_list_defaults = admin_user_management,admin_role_management,admin_permission_management
+```
+
+**To initialize permissions and create a super user:**
+
+After setting up your database and configuring permissions, you can run:
+```bash
+npm run init-users
+```
+
+This script will:
+1. Create all permissions from `application_permission_list_defaults`
+2. Create a `default_super_user_role` role with all permissions
+3. Assign the role to the user specified in `default_super_user_email` (configure in `[hazo_auth__initial_setup]` section)
+
+**Checklist:**
+- [ ] Default permissions configured in `hazo_auth_config.ini` (already set by default)
+- [ ] `default_super_user_email` configured if you want to use `init-users` script
+
+---
+
 ## Phase 4: API Routes
 
 Create API route files in your project. Each file re-exports handlers from hazo_auth.
@@ -427,8 +462,14 @@ app/api/hazo_auth/
 ├── library_photos/route.ts
 ├── get_auth/route.ts
 ├── validate_reset_token/route.ts
-└── profile_picture/
-    └── [filename]/route.ts
+├── profile_picture/
+│   └── [filename]/route.ts
+└── user_management/
+    ├── users/route.ts
+    ├── permissions/route.ts
+    ├── roles/route.ts
+    └── users/
+        └── roles/route.ts
 ```
 
 **Example route file content:**
@@ -513,9 +554,34 @@ export { POST } from "hazo_auth/server/routes/validate_reset_token";
 export { GET } from "hazo_auth/server/routes/profile_picture_filename";
 ```
 
+**User Management routes (optional - required if using UserManagementLayout):**
+
+`app/api/hazo_auth/user_management/users/route.ts`:
+```typescript
+export { GET, PATCH, POST } from "hazo_auth/server/routes";
+```
+
+`app/api/hazo_auth/user_management/permissions/route.ts`:
+```typescript
+export { GET, POST, PUT, DELETE } from "hazo_auth/server/routes";
+```
+
+`app/api/hazo_auth/user_management/roles/route.ts`:
+```typescript
+export { GET, POST, PUT } from "hazo_auth/server/routes";
+```
+
+`app/api/hazo_auth/user_management/users/roles/route.ts`:
+```typescript
+export { GET, POST, PUT } from "hazo_auth/server/routes";
+```
+
+**Note:** The `generate-routes` command automatically creates all user_management routes. These routes are required if you plan to use the `UserManagementLayout` component for managing users, roles, and permissions.
+
 **Checklist:**
-- [ ] All 16 API route files created
-- [ ] Each file exports the correct HTTP method (POST, GET, PATCH, DELETE)
+- [ ] All 16 core API route files created
+- [ ] User management routes created (if using UserManagementLayout)
+- [ ] Each file exports the correct HTTP method (POST, GET, PATCH, DELETE, PUT)
 
 ---
 
@@ -616,19 +682,51 @@ export default function CustomLoginPage() {
 
 Run these tests to verify your setup is working correctly.
 
-### Test 1: API Health Check
+### Test 1: API Health Check - Standardized `/api/hazo_auth/me` Endpoint
+
+**⚠️ IMPORTANT: Use `/api/hazo_auth/me` for all client-side authentication checks. It always returns a standardized format with permissions.**
 
 ```bash
 curl -s http://localhost:3000/api/hazo_auth/me | jq
 ```
 
-**Expected response:**
+**Expected response (not authenticated):**
 ```json
 {
   "authenticated": false
 }
 ```
 
+**Expected response (authenticated - standardized format):**
+```json
+{
+  "authenticated": true,
+  "user_id": "28fe0aff-29c7-407e-b92e-bf11a6a3332f",
+  "email": "test@example.com",
+  "name": "Test User",
+  "email_verified": false,
+  "last_logon": "2025-01-27T16:18:00.054Z",
+  "profile_picture_url": "https://gravatar.com/avatar/...",
+  "profile_source": "gravatar",
+  "user": {
+    "id": "28fe0aff-29c7-407e-b92e-bf11a6a3332f",
+    "email_address": "test@example.com",
+    "name": "Test User",
+    "is_active": true,
+    "profile_picture_url": "https://gravatar.com/avatar/..."
+  },
+  "permissions": [],
+  "permission_ok": true
+}
+```
+
+**Key Points:**
+- ✅ Always returns the same standardized format
+- ✅ Always includes `permissions` and `permission_ok` fields
+- ✅ Top-level fields (`user_id`, `email`, `name`) for backward compatibility
+- ✅ `user` object contains full user details
+- ✅ Use this endpoint instead of `/api/hazo_auth/get_auth` for client-side code
+
 ### Test 2: Registration API
 
 ```bash

package/dist/app/api/hazo_auth/me/route.d.ts

@@ -1,3 +1,32 @@
 import { NextRequest, NextResponse } from "next/server";
-export declare function GET(request: NextRequest): Promise<NextResponse<unknown>>;
+/**
+ * GET /api/hazo_auth/me
+ *
+ * Standardized endpoint that returns authenticated user information with permissions.
+ * Always returns the same format to prevent downstream variations.
+ *
+ * Response format (authenticated):
+ * {
+ *   authenticated: true,
+ *   user_id: string,
+ *   email: string,
+ *   name: string | null,
+ *   email_verified: boolean,
+ *   last_logon: string | undefined,
+ *   profile_picture_url: string | null,
+ *   profile_source: "upload" | "library" | "gravatar" | "custom" | undefined,
+ *   user: { id, email_address, name, is_active, profile_picture_url },
+ *   permissions: string[],
+ *   permission_ok: boolean,
+ *   missing_permissions?: string[],
+ * }
+ *
+ * Response format (not authenticated):
+ * {
+ *   authenticated: false
+ * }
+ */
+export declare function GET(request: NextRequest): Promise<NextResponse<{
+    authenticated: boolean;
+}>>;
 //# sourceMappingURL=route.d.ts.map

package/dist/app/api/hazo_auth/me/route.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../../../../src/app/api/hazo_auth/me/route.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAIxD,wBAAsB,GAAG,CAAC,OAAO,EAAE,WAAW,kCAuC7C"}
+{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../../../../src/app/api/hazo_auth/me/route.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AASxD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,GAAG,CAAC,OAAO,EAAE,WAAW;;IA0E7C"}

package/dist/app/api/hazo_auth/me/route.js

@@ -1,33 +1,93 @@
-// file_description: API route to get current authenticated user information
+// file_description: API route to get current authenticated user information with permissions
+// This is the standardized endpoint that always returns the same format including permissions
 // section: imports
 import { NextResponse } from "next/server";
-import { get_authenticated_user_with_response } from "../../../../lib/auth/auth_utils.server";
+import { hazo_get_auth } from "../../../../lib/auth/hazo_get_auth.server";
+import { get_hazo_connect_instance } from "../../../../lib/hazo_connect_instance.server";
+import { createCrudService } from "hazo_connect/server";
+import { map_db_source_to_ui } from "../../../../lib/services/profile_picture_source_mapper";
+import { create_app_logger } from "../../../../lib/app_logger";
+import { get_filename, get_line_number } from "../../../../lib/utils/api_route_helpers";
 // section: api_handler
+/**
+ * GET /api/hazo_auth/me
+ *
+ * Standardized endpoint that returns authenticated user information with permissions.
+ * Always returns the same format to prevent downstream variations.
+ *
+ * Response format (authenticated):
+ * {
+ *   authenticated: true,
+ *   user_id: string,
+ *   email: string,
+ *   name: string | null,
+ *   email_verified: boolean,
+ *   last_logon: string | undefined,
+ *   profile_picture_url: string | null,
+ *   profile_source: "upload" | "library" | "gravatar" | "custom" | undefined,
+ *   user: { id, email_address, name, is_active, profile_picture_url },
+ *   permissions: string[],
+ *   permission_ok: boolean,
+ *   missing_permissions?: string[],
+ * }
+ *
+ * Response format (not authenticated):
+ * {
+ *   authenticated: false
+ * }
+ */
 export async function GET(request) {
+    const logger = create_app_logger();
     try {
-        // Use centralized auth utility
-        const { auth_result, response } = await get_authenticated_user_with_response(request);
-        // If response is provided, it means cookies were cleared (invalid auth)
-        if (response) {
-            return response;
-        }
+        // Use hazo_get_auth to get user with permissions
+        const auth_result = await hazo_get_auth(request);
         // If not authenticated, return false
         if (!auth_result.authenticated) {
             return NextResponse.json({ authenticated: false }, { status: 200 });
         }
-        // Return user info
+        // Fetch additional user fields from database (email_verified, last_logon, profile_source)
+        const hazoConnect = get_hazo_connect_instance();
+        const users_service = createCrudService(hazoConnect, "hazo_users");
+        const users = await users_service.findBy({ id: auth_result.user.id });
+        if (!Array.isArray(users) || users.length === 0) {
+            logger.warn("me_endpoint_user_not_found", {
+                filename: get_filename(),
+                line_number: get_line_number(),
+                user_id: auth_result.user.id,
+                message: "User found in auth but not in database",
+            });
+            return NextResponse.json({ authenticated: false }, { status: 200 });
+        }
+        const user_db = users[0];
+        // Map database profile_source to UI representation
+        const profile_source_db = user_db.profile_source;
+        const profile_source_ui = profile_source_db ? map_db_source_to_ui(profile_source_db) : undefined;
+        // Return unified format with all fields
         return NextResponse.json({
             authenticated: true,
-            user_id: auth_result.user_id,
-            email: auth_result.email,
-            name: auth_result.name,
-            email_verified: auth_result.email_verified,
-            last_logon: auth_result.last_logon,
-            profile_picture_url: auth_result.profile_picture_url,
-            profile_source: auth_result.profile_source,
+            // Top-level fields for backward compatibility
+            user_id: auth_result.user.id,
+            email: auth_result.user.email_address,
+            name: auth_result.user.name,
+            email_verified: user_db.email_verified === true,
+            last_logon: user_db.last_logon || undefined,
+            profile_picture_url: auth_result.user.profile_picture_url,
+            profile_source: profile_source_ui,
+            // Permissions and user object (always included)
+            user: auth_result.user,
+            permissions: auth_result.permissions,
+            permission_ok: auth_result.permission_ok,
+            missing_permissions: auth_result.missing_permissions,
         }, { status: 200 });
     }
     catch (error) {
+        const error_message = error instanceof Error ? error.message : "Unknown error";
+        logger.error("me_endpoint_error", {
+            filename: get_filename(),
+            line_number: get_line_number(),
+            error_message,
+            error_stack: error instanceof Error ? error.stack : undefined,
+        });
         // On error, assume not authenticated
         return NextResponse.json({ authenticated: false }, { status: 200 });
     }

package/dist/app/api/hazo_auth/user_management/permissions/route.d.ts

@@ -0,0 +1,50 @@
+import { NextRequest, NextResponse } from "next/server";
+export declare const dynamic = "force-dynamic";
+/**
+ * GET - Fetch all permissions from database and config
+ */
+export declare function GET(request: NextRequest): Promise<NextResponse<{
+    error: string;
+}> | NextResponse<{
+    success: boolean;
+    db_permissions: {
+        id: unknown;
+        permission_name: unknown;
+        description: {};
+    }[];
+    config_permissions: string[];
+}>>;
+/**
+ * POST - Create new permission or migrate config permissions to database
+ */
+export declare function POST(request: NextRequest): Promise<NextResponse<{
+    success: boolean;
+    created: string[];
+    skipped: string[];
+}> | NextResponse<{
+    error: string;
+}> | NextResponse<{
+    success: boolean;
+    permission: {
+        id: number;
+        permission_name: string;
+        description: any;
+    };
+}>>;
+/**
+ * PUT - Update permission description
+ */
+export declare function PUT(request: NextRequest): Promise<NextResponse<{
+    error: string;
+}> | NextResponse<{
+    success: boolean;
+}>>;
+/**
+ * DELETE - Delete permission from database
+ */
+export declare function DELETE(request: NextRequest): Promise<NextResponse<{
+    error: string;
+}> | NextResponse<{
+    success: boolean;
+}>>;
+//# sourceMappingURL=route.d.ts.map

package/dist/app/api/hazo_auth/user_management/permissions/route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../../../../../src/app/api/hazo_auth/user_management/permissions/route.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAQxD,eAAO,MAAM,OAAO,kBAAkB,CAAC;AAGvC;;GAEG;AACH,wBAAsB,GAAG,CAAC,OAAO,EAAE,WAAW;;;;;;;;;;IAgE7C;AAED;;GAEG;AACH,wBAAsB,IAAI,CAAC,OAAO,EAAE,WAAW;;;;;;;;;;;;;IAyJ9C;AAED;;GAEG;AACH,wBAAsB,GAAG,CAAC,OAAO,EAAE,WAAW;;;;IAkD7C;AAED;;GAEG;AACH,wBAAsB,MAAM,CAAC,OAAO,EAAE,WAAW;;;;IAmEhD"}