hazo_auth 1.6.4 → 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

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)
 
 ---
 

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"}

package/dist/app/api/hazo_auth/user_management/permissions/route.js

@@ -0,0 +1,257 @@
+// file_description: API route for permissions management operations (list, migrate from config, update, delete)
+// section: imports
+import { NextResponse } from "next/server";
+import { get_hazo_connect_instance } from "../../../../../lib/hazo_connect_instance.server";
+import { createCrudService } from "hazo_connect/server";
+import { create_app_logger } from "../../../../../lib/app_logger";
+import { get_filename, get_line_number } from "../../../../../lib/utils/api_route_helpers";
+import { get_user_management_config } from "../../../../../lib/user_management_config.server";
+// section: route_config
+export const dynamic = 'force-dynamic';
+// section: api_handler
+/**
+ * GET - Fetch all permissions from database and config
+ */
+export async function GET(request) {
+    const logger = create_app_logger();
+    try {
+        const hazoConnect = get_hazo_connect_instance();
+        const permissions_service = createCrudService(hazoConnect, "hazo_permissions");
+        // Fetch all permissions from database (empty object means no filter - get all records)
+        const db_permissions = await permissions_service.findBy({});
+        if (!Array.isArray(db_permissions)) {
+            return NextResponse.json({ error: "Failed to fetch permissions" }, { status: 500 });
+        }
+        // Get config permissions
+        const config = get_user_management_config();
+        const config_permission_names = config.application_permission_list_defaults || [];
+        // Get DB permission names
+        const db_permission_names = db_permissions.map((p) => p.permission_name);
+        // Find config permissions not in DB
+        const config_only_permissions = config_permission_names.filter((name) => !db_permission_names.includes(name));
+        logger.info("user_management_permissions_fetched", {
+            filename: get_filename(),
+            line_number: get_line_number(),
+            db_count: db_permissions.length,
+            config_count: config_permission_names.length,
+        });
+        return NextResponse.json({
+            success: true,
+            db_permissions: db_permissions.map((p) => ({
+                id: p.id,
+                permission_name: p.permission_name,
+                description: p.description || "",
+            })),
+            config_permissions: config_only_permissions,
+        }, { status: 200 });
+    }
+    catch (error) {
+        const error_message = error instanceof Error ? error.message : "Unknown error";
+        const error_stack = error instanceof Error ? error.stack : undefined;
+        logger.error("user_management_permissions_fetch_error", {
+            filename: get_filename(),
+            line_number: get_line_number(),
+            error_message,
+            error_stack,
+        });
+        return NextResponse.json({ error: "Failed to fetch permissions" }, { status: 500 });
+    }
+}
+/**
+ * POST - Create new permission or migrate config permissions to database
+ */
+export async function POST(request) {
+    const logger = create_app_logger();
+    try {
+        const { searchParams } = new URL(request.url);
+        const action = searchParams.get("action");
+        // Handle migrate action
+        if (action === "migrate") {
+            const hazoConnect = get_hazo_connect_instance();
+            const permissions_service = createCrudService(hazoConnect, "hazo_permissions");
+            // Get config permissions
+            const config = get_user_management_config();
+            const config_permission_names = config.application_permission_list_defaults || [];
+            if (config_permission_names.length === 0) {
+                return NextResponse.json({
+                    success: true,
+                    message: "No permissions to migrate",
+                    created: [],
+                    skipped: [],
+                }, { status: 200 });
+            }
+            // Get existing permissions from DB (empty object means no filter - get all records)
+            const db_permissions = await permissions_service.findBy({});
+            const db_permission_names = Array.isArray(db_permissions)
+                ? db_permissions.map((p) => p.permission_name)
+                : [];
+            const now = new Date().toISOString();
+            const created = [];
+            const skipped = [];
+            // Migrate each config permission
+            for (const permission_name of config_permission_names) {
+                if (db_permission_names.includes(permission_name)) {
+                    // Skip if already exists
+                    skipped.push(permission_name);
+                    continue;
+                }
+                // Create new permission
+                await permissions_service.insert({
+                    permission_name: permission_name.trim(),
+                    description: "",
+                    created_at: now,
+                    changed_at: now,
+                });
+                created.push(permission_name);
+            }
+            logger.info("user_management_permissions_migrated", {
+                filename: get_filename(),
+                line_number: get_line_number(),
+                created_count: created.length,
+                skipped_count: skipped.length,
+            });
+            return NextResponse.json({
+                success: true,
+                created,
+                skipped,
+            }, { status: 200 });
+        }
+        // Handle create new permission
+        const body = await request.json();
+        const { permission_name, description } = body;
+        if (!permission_name || typeof permission_name !== "string" || permission_name.trim().length === 0) {
+            return NextResponse.json({ error: "permission_name is required and must be a non-empty string" }, { status: 400 });
+        }
+        const hazoConnect = get_hazo_connect_instance();
+        const permissions_service = createCrudService(hazoConnect, "hazo_permissions");
+        // Check if permission already exists
+        const existing_permissions = await permissions_service.findBy({
+            permission_name: permission_name.trim(),
+        });
+        if (Array.isArray(existing_permissions) && existing_permissions.length > 0) {
+            return NextResponse.json({ error: "Permission with this name already exists" }, { status: 409 });
+        }
+        // Create new permission
+        const now = new Date().toISOString();
+        const new_permission_result = await permissions_service.insert({
+            permission_name: permission_name.trim(),
+            description: (description || "").trim(),
+            created_at: now,
+            changed_at: now,
+        });
+        // insert() returns an array, get the first element
+        if (!Array.isArray(new_permission_result) || new_permission_result.length === 0) {
+            return NextResponse.json({ error: "Failed to create permission - no record returned" }, { status: 500 });
+        }
+        const new_permission = new_permission_result[0];
+        logger.info("user_management_permission_created", {
+            filename: get_filename(),
+            line_number: get_line_number(),
+            permission_id: new_permission.id,
+            permission_name: permission_name.trim(),
+        });
+        return NextResponse.json({
+            success: true,
+            permission: {
+                id: new_permission.id,
+                permission_name: permission_name.trim(),
+                description: (description || "").trim(),
+            },
+        }, { status: 201 });
+    }
+    catch (error) {
+        const error_message = error instanceof Error ? error.message : "Unknown error";
+        const error_stack = error instanceof Error ? error.stack : undefined;
+        logger.error("user_management_permissions_post_error", {
+            filename: get_filename(),
+            line_number: get_line_number(),
+            error_message,
+            error_stack,
+        });
+        return NextResponse.json({ error: "Failed to create permission" }, { status: 500 });
+    }
+}
+/**
+ * PUT - Update permission description
+ */
+export async function PUT(request) {
+    const logger = create_app_logger();
+    try {
+        const body = await request.json();
+        const { permission_id, description } = body;
+        if (!permission_id || typeof description !== "string") {
+            return NextResponse.json({ error: "permission_id and description are required" }, { status: 400 });
+        }
+        const hazoConnect = get_hazo_connect_instance();
+        const permissions_service = createCrudService(hazoConnect, "hazo_permissions");
+        // Update permission with changed_at timestamp
+        const now = new Date().toISOString();
+        await permissions_service.updateById(permission_id, {
+            description: description.trim(),
+            changed_at: now,
+        });
+        logger.info("user_management_permission_updated", {
+            filename: get_filename(),
+            line_number: get_line_number(),
+            permission_id,
+        });
+        return NextResponse.json({ success: true }, { status: 200 });
+    }
+    catch (error) {
+        const error_message = error instanceof Error ? error.message : "Unknown error";
+        const error_stack = error instanceof Error ? error.stack : undefined;
+        logger.error("user_management_permission_update_error", {
+            filename: get_filename(),
+            line_number: get_line_number(),
+            error_message,
+            error_stack,
+        });
+        return NextResponse.json({ error: "Failed to update permission" }, { status: 500 });
+    }
+}
+/**
+ * DELETE - Delete permission from database
+ */
+export async function DELETE(request) {
+    const logger = create_app_logger();
+    try {
+        const { searchParams } = new URL(request.url);
+        const permission_id = searchParams.get("permission_id");
+        if (!permission_id) {
+            return NextResponse.json({ error: "permission_id is required" }, { status: 400 });
+        }
+        const permission_id_num = parseInt(permission_id, 10);
+        if (isNaN(permission_id_num)) {
+            return NextResponse.json({ error: "permission_id must be a number" }, { status: 400 });
+        }
+        const hazoConnect = get_hazo_connect_instance();
+        const permissions_service = createCrudService(hazoConnect, "hazo_permissions");
+        const role_permissions_service = createCrudService(hazoConnect, "hazo_role_permissions");
+        // Check if permission is used in any role
+        const role_permissions = await role_permissions_service.findBy({
+            permission_id: permission_id_num,
+        });
+        if (Array.isArray(role_permissions) && role_permissions.length > 0) {
+            return NextResponse.json({ error: "Cannot delete permission that is assigned to roles" }, { status: 409 });
+        }
+        // Delete permission
+        await permissions_service.deleteById(permission_id_num);
+        logger.info("user_management_permission_deleted", {
+            filename: get_filename(),
+            line_number: get_line_number(),
+            permission_id: permission_id_num,
+        });
+        return NextResponse.json({ success: true }, { status: 200 });
+    }
+    catch (error) {
+        const error_message = error instanceof Error ? error.message : "Unknown error";
+        const error_stack = error instanceof Error ? error.stack : undefined;
+        logger.error("user_management_permission_delete_error", {
+            filename: get_filename(),
+            line_number: get_line_number(),
+            error_message,
+            error_stack,
+        });
+        return NextResponse.json({ error: "Failed to delete permission" }, { status: 500 });
+    }
+}

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

@@ -0,0 +1,40 @@
+import { NextRequest, NextResponse } from "next/server";
+export declare const dynamic = "force-dynamic";
+/**
+ * GET - Fetch all roles with their permissions
+ */
+export declare function GET(request: NextRequest): Promise<NextResponse<{
+    error: string;
+}> | NextResponse<{
+    success: boolean;
+    roles: {
+        role_id: unknown;
+        role_name: unknown;
+        permissions: string[];
+    }[];
+    permissions: {
+        id: unknown;
+        permission_name: unknown;
+    }[];
+}>>;
+/**
+ * POST - Create new role
+ */
+export declare function POST(request: NextRequest): Promise<NextResponse<{
+    error: string;
+}> | NextResponse<{
+    success: boolean;
+    role: {
+        role_id: number;
+        role_name: string;
+    };
+}>>;
+/**
+ * PUT - Update role permissions (save role-permission matrix)
+ */
+export declare function PUT(request: NextRequest): Promise<NextResponse<{
+    error: string;
+}> | NextResponse<{
+    success: boolean;
+}>>;
+//# sourceMappingURL=route.d.ts.map

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

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