Merge pull request #22 from StreetSupport/feature/3011-build-user-management-interface

Feature/3011 build user management interface

Author: o-seliuchenko

AUTH0_SETUP.md

@@ -0,0 +1,166 @@
+# Auth0 User Creation Setup
+
+## Overview
+The API now integrates with Auth0 Management API to create users programmatically when admins add new users through the admin panel.
+
+## Required Environment Variables
+
+Add the following environment variables to your `.env` file:
+
+```env
+# Existing Auth0 Configuration (for JWT verification)
+AUTH0_DOMAIN=your-tenant.auth0.com
+AUTH0_AUDIENCE=https://your-api-identifier
+
+# Auth0 Management API Configuration (for user creation)
+AUTH0_MANAGEMENT_CLIENT_ID=your_management_api_client_id
+AUTH0_MANAGEMENT_CLIENT_SECRET=your_management_api_client_secret
+AUTH0_MANAGEMENT_AUDIENCE=https://your-tenant.auth0.com/api/v2/
+AUTH0_USER_DB_CONNECTION=Username-Password-Authentication
+```
+
+## Setting Up Auth0 Management API
+
+### 1. Create a Machine-to-Machine Application
+
+1. Go to your Auth0 Dashboard
+2. Navigate to **Applications** → **Applications**
+3. Click **Create Application**
+4. Name it "Street Support Management API" (or similar)
+5. Select **Machine to Machine Applications**
+6. Click **Create**
+
+### 2. Authorize the Application
+
+1. Select **Auth0 Management API** as the API
+2. Grant the following permissions (scopes):
+   - `create:users` - Create users
+   - `update:users` - Update user metadata
+   - `delete:users` - Delete users (for cleanup on errors)
+   - `read:users` - Read user information
+3. Click **Authorize**
+
+### 3. Get Credentials
+
+1. Go to the **Settings** tab of your Machine-to-Machine application
+2. Copy the **Client ID** → Use as `AUTH0_MANAGEMENT_CLIENT_ID`
+3. Copy the **Client Secret** → Use as `AUTH0_MANAGEMENT_CLIENT_SECRET`
+
+### 4. Configure Database Connection
+
+1. Go to **Authentication** → **Database**
+2. Note the name of your database connection (usually "Username-Password-Authentication")
+3. Use this as `AUTH0_USER_DB_CONNECTION`
+
+### 5. Set Management API Audience
+
+The audience is typically: `https://YOUR_DOMAIN/api/v2/`
+
+For example: `https://your-tenant.auth0.com/api/v2/`
+
+## How It Works
+
+### User Creation Flow
+
+1. **Admin creates user** in the admin panel
+2. **API validates** user data with Zod schema
+3. **Auth0 user created** first via Management API with:
+   - `email`: User's email
+   - `name`: User's email (used as display name)
+   - `password`: Auto-generated secure password
+   - `app_metadata.authorization.roles`: User's AuthClaims array
+   - `email_verified`: false (requires email verification)
+   - `verify_email`: true (sends verification email)
+   - Auth0 auto-generates unique `user_id` (e.g., `auth0|507f1f77bcf86cd799439011`)
+4. **MongoDB user created** with Auth0's generated `user_id` stored in `Auth0Id` field
+
+### Error Handling
+
+- If **Auth0 creation fails**: Error returned immediately, no MongoDB user created
+- If **MongoDB creation fails**: Auth0 user is deleted (rollback for consistency)
+- Detailed error messages returned to admin panel
+
+### Password Management
+
+- **Auto-generated** secure 30-character password
+- Contains uppercase, lowercase, numbers, and special characters
+- Meets Auth0 password policy requirements
+- Users will use **password reset** flow for first login
+
+## API Functions
+
+### `createAuth0User(email, authClaims)`
+Creates a new user in Auth0 with auto-generated user ID
+
+**Parameters:**
+- `email`: User's email address
+- `authClaims`: Array of role strings (e.g., `['SuperAdmin']`, `['CityAdmin', 'CityAdminFor:manchester']`)
+
+**Returns:** Auth0 user object with auto-generated `user_id` (e.g., `auth0|507f1f77bcf86cd799439011`)
+
+### `deleteAuth0User(auth0UserId)`
+Deletes a user from Auth0
+
+**Parameters:**
+- `auth0UserId`: Auth0 user ID (e.g., `"auth0|123456"`)
+
+### `updateAuth0UserRoles(auth0UserId, authClaims)`
+Updates user roles in Auth0 app_metadata
+
+**Parameters:**
+- `auth0UserId`: Auth0 user ID
+- `authClaims`: Updated array of role strings
+
+## Testing
+
+### Test User Creation
+
+```bash
+curl -X POST http://localhost:5000/api/users \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
+  -d '{
+    "Email": "[email protected]",
+    "UserName": "testuser",
+    "AuthClaims": ["CityAdmin", "CityAdminFor:manchester"]
+  }'
+```
+
+### Verify in Auth0 Dashboard
+
+1. Go to **User Management** → **Users**
+2. Find the newly created user
+3. Check **app_metadata** contains authorization roles
+4. Copy the **user_id** and verify it matches the `Auth0Id` field in MongoDB
+
+## Troubleshooting
+
+### "Failed to get Auth0 management token"
+- Verify `AUTH0_MANAGEMENT_CLIENT_ID` and `AUTH0_MANAGEMENT_CLIENT_SECRET` are correct
+- Check that Machine-to-Machine application is authorized for Management API
+
+### "Failed to create Auth0 user"
+- Verify `AUTH0_DOMAIN` is correct (without `https://`)
+- Check `AUTH0_USER_DB_CONNECTION` matches your database connection name
+- Ensure Management API has `create:users` permission
+- Check Auth0 Dashboard → Logs for detailed error messages
+
+### "User created in Auth0 but not in MongoDB"
+- Check server logs for MongoDB error details
+- Auth0 user should be automatically deleted on MongoDB failure
+- If Auth0 user remains without MongoDB record, it will be cleaned up on retry
+
+## Security Considerations
+
+- **Management API credentials** are highly sensitive - store securely
+- **Never expose** `AUTH0_MANAGEMENT_CLIENT_SECRET` in client-side code
+- **Auto-generated passwords** are not accessible after creation
+- Users must use **password reset flow** for first login
+- **Role-based access control** enforced via RBAC middleware
+
+## Next Steps
+
+1. Set up password reset email templates in Auth0
+2. Configure Auth0 Actions/Rules if needed
+3. Set up user invitation email flow (optional)
+4. Configure multi-factor authentication (recommended)

CONTROLLER_REFACTORING_PLAN.md

@@ -0,0 +1,167 @@
+# Controller Response Refactoring Plan
+
+## Summary
+Unify all controller responses to use standardized response utilities from `apiResponses.ts`.
+
+## Response Utilities Available
+
+### Success Responses
+- `sendSuccess<T>(res, data, message?)` - 200 OK with data
+- `sendCreated<T>(res, data, message?)` - 201 Created with data
+
+### Error Responses
+- `sendUnauthorized(res, error?)` - 401 Unauthorized
+- `sendForbidden(res, error?)` - 403 Forbidden
+- `sendNotFound(res, error?)` - 404 Not Found
+- `sendBadRequest(res, error?)` - 400 Bad Request
+- `sendInternalError(res, error?)` - 500 Internal Server Error
+- `sendError(res, statusCode, error)` - Custom status code
+
+## Current State Analysis
+
+### 1. **cityController.ts** (90 lines)
+**Current Patterns:**
+- ❌ `res.status(200).json({ success: true, data: cities })`
+- ❌ `res.status(404).json({ success: false, message: 'City not found' })`
+- ❌ `res.status(201).json({ success: true, data: created })`
+
+**Changes Needed:** 5 success responses, 3 error responses
+
+---
+
+### 2. **serviceController.ts** (71 lines)
+**Current Patterns:**
+- ❌ `res.status(200).json({ success: true, data: services })`
+- ❌ `res.status(404); throw new Error('Service not found');`
+- ❌ `res.status(201).json({ success: true, data: service })`
+
+**Changes Needed:** 6 success responses, 3 error responses (throw pattern)
+
+---
+
+### 3. **faqController.ts** (68 lines)
+**Current Patterns:**
+- ❌ `res.status(200).json({ success: true, data: faqs })`
+- ❌ `res.status(404); throw new Error('FAQ not found');`
+- ❌ `res.status(201).json({ success: true, data: faq })`
+
+**Changes Needed:** 6 success responses, 3 error responses (throw pattern)
+
+---
+
+### 4. **serviceProviderController.ts** (estimated ~70 lines)
+**Status:** Needs analysis
+**Expected Changes:** Similar to serviceController
+
+---
+
+### 5. **resourceController.ts** (1137 bytes)
+**Status:** Needs analysis
+**Expected Changes:** Minimal updates
+
+---
+
+### 6. **swepBannerController.ts** (1152 bytes)
+**Status:** Needs analysis
+**Expected Changes:** Minimal updates
+
+---
+
+### 7. **userController.ts** (8911 bytes)
+**Current Status:** ✅ **Partially Updated**
+- Already uses `sendNotFound()` in some places
+- Mix of old and new patterns
+
+**Remaining Changes:** 
+- Replace remaining manual `res.status().json()` calls
+- Replace `throw new Error()` patterns with response utilities
+
+---
+
+### 8. **bannerController.ts** (16949 bytes)
+**Current Status:** ✅ **Partially Updated**
+- Already uses `sendNotFound()` and `sendBadRequest()` in some places
+- Mix of old and new patterns
+
+**Remaining Changes:**
+- Replace remaining manual `res.status().json()` calls
+- Standardize success responses with `sendSuccess()` and `sendCreated()`
+
+---
+
+## Refactoring Strategy
+
+### Phase 1: Update Smaller Controllers (Fastest wins)
+1. ✅ **cityController.ts** - Simple CRUD, no complex logic
+2. ✅ **faqController.ts** - Simple CRUD
+3. ✅ **serviceController.ts** - Simple CRUD
+4. ✅ **serviceProviderController.ts** - Simple CRUD
+5. ✅ **resourceController.ts** - Minimal code
+6. ✅ **swepBannerController.ts** - Minimal code
+
+### Phase 2: Complete Partially Updated Controllers
+7. ✅ **userController.ts** - Finish standardization
+8. ✅ **bannerController.ts** - Finish standardization
+
+---
+
+## Example Transformations
+
+### Before (Multiple Inconsistent Patterns)
+```typescript
+// Pattern 1: Direct response
+res.status(200).json({ success: true, data: cities });
+
+// Pattern 2: Throw error
+res.status(404);
+throw new Error('City not found');
+
+// Pattern 3: Inline error
+return res.status(404).json({ success: false, message: 'City not found' });
+
+// Pattern 4: Created
+res.status(201).json({ success: true, data: created });
+```
+
+### After (Unified Pattern)
+```typescript
+// Success responses
+return sendSuccess(res, cities);
+return sendCreated(res, created);
+
+// Error responses
+return sendNotFound(res, 'City not found');
+return sendBadRequest(res, 'Invalid data');
+return sendInternalError(res, 'Database error');
+```
+
+---
+
+## Benefits
+
+1. **Consistency**: All controllers use the same response pattern
+2. **Type Safety**: Generic types ensure proper data typing
+3. **Maintainability**: Centralized response logic
+4. **Testability**: Easier to mock and test responses
+5. **Documentation**: Clear response structure
+6. **Error Handling**: Standardized error format across all endpoints
+
+---
+
+## Next Steps (Awaiting Approval)
+
+1. ✅ Review this plan
+2. ⏳ Approve refactoring approach
+3. ⏳ Update controllers one by one
+4. ⏳ Test each controller after updates
+5. ⏳ Apply same pattern to Admin project
+
+---
+
+## Estimated Impact
+
+- **Files to Update**: 8 controller files
+- **Approximate Changes**: ~80-100 response statements
+- **Risk Level**: Low (response format remains compatible)
+- **Breaking Changes**: None (JSON structure unchanged)
+- **Testing Required**: Verify all endpoints return expected structure