users.js

Go to the documentation of this file.

/**
 * @file users.js
 * @brief User Management and Authentication API Routes
 * @description Comprehensive user authentication, authorization, and profile management
 * for MSP/PSA platform. Handles user CRUD, JWT-based authentication, password management,
 * email verification, multi-factor authentication (MFA/TOTP), and tenant-based access control.
 * 
 * **Core Features:**
 * - User registration and management (admin-controlled)
 * - JWT token-based authentication with 30-day expiration
 * - Password reset via email with time-limited tokens
 * - Email verification workflow
 * - Self-service password changes
 * - Theme preferences per user
 * - Multi-factor authentication (TOTP/Google Authenticator)
 * - Multi-tenant user isolation
 * - Role-based access control (admin/user roles)
 * 
 * **Authentication Flow:**
 * 1. POST /login with credentials (+ optional MFA code)
 * 2. Receive JWT token with user_id, role, tenant_id, is_msp
 * 3. Include token in Authorization: Bearer <token> header
 * 4. Token valid for 30 days, refresh required after expiration
 * 
 * **Multi-Factor Authentication:**
 * - TOTP-based (compatible with Google Authenticator, Authy, etc.)
 * - Setup: Generate secret, scan QR code, verify with code
 * - Enable: Store secret and set mfa_enabled flag
 * - Login: Require TOTP code in addition to password
 * - Disable: Verify current code, remove secret
 * 
 * **Password Security:**
 * - Bcrypt hashing with salt (10 rounds)
 * - Password reset tokens valid for 30 minutes (configurable)
 * - Email verification tokens valid for 60 minutes (configurable)
 * - Tokens single-use (marked used_at after consumption)
 * 
 * **Multi-Tenant Access:**
 * - Root MSP users (is_msp=true) can see/manage all users
 * - Regular users only see users in their tenant
 * - Admin users can create users in their tenant or specified tenant_id
 * 
 * **Database Schema:**
 * - users: Main user records with credentials
 * - password_reset_tokens: Time-limited reset tokens
 * - email_verification_tokens: Email verification tokens
 * - tenants: Tenant/MSP organization records
 * @module routes/users
 * @requires express
 * @requires services/db
 * @requires bcrypt
 * @requires jsonwebtoken
 * @requires speakeasy (for MFA/TOTP)
 * @requires middleware/auth
 * @requires middleware/tenant
 * @requires services/email
 * @author RMM-PSA Platform
 * @date 2026-02-10
 * @since 2.0.0
 */
const express = require('express');
const router = express.Router();
const pool = require('../services/db');
const bcrypt = require('bcrypt');
const jwt = require('jsonwebtoken');
const authenticateToken = require('../middleware/auth');
const { setTenantContext } = require('../middleware/tenant');
 
/**
 * @api {post} /users Create new user
 * @apiName CreateUser
 * @apiGroup Users
 * @apiDescription Creates a new user account. Admin-only operation. Root MSP admins can
 * create users in any tenant by specifying tenant_id. Regular admins create users in
 * their own tenant. Password is bcrypt-hashed before storage.
 * 
 * **Tenant Assignment:**
 * - Root MSP: Can specify any tenant_id to create users in sub-tenants
 * - Regular Admin: Creates users in their own tenant only
 * - If tenant_id omitted, uses current tenant from JWT
 * 
 * **Roles:**
 * - admin: Full access, can manage users and system settings
 * - user: Standard access, cannot manage users
 * @apiHeader {string} Authorization Bearer JWT token with admin role
 * @apiHeader {string} Content-Type application/json
 * @apiParam {string} name Full name of user (required)
 * @apiParam {string} email Email address (required, unique)
 * @apiParam {string} role User role: "admin" or "user" (required)
 * @apiParam {string} password Plain text password (required, will be hashed)
 * @apiParam {number} [tenant_id] Tenant ID (MSP root only)
 * @apiSuccess {number} user_id Auto-generated user ID
 * @apiSuccess {string} name User's full name
 * @apiSuccess {string} email User's email
 * @apiSuccess {string} role User's role
 * @apiSuccess {number} tenant_id Assigned tenant ID
 * @apiError {number} 403 Admin access required
 * @apiError {number} 400 Missing tenant context
 * @apiError {number} 500 User creation failed
 * @apiExample {curl} Example Request:
 *   curl -X POST https://api.example.com/users \
 *     -H "Authorization: Bearer TOKEN" \
 *     -H "Content-Type: application/json" \
 *     -d '{"name":"John","email":"john@example.com","role":"user","password":"pass123"}'
 * 
 * @apiExample {json} Success Response:
 *   HTTP/1.1 201 Created
 *   {
 *     "user_id": 42,
 *     "name": "John",
 *     "email": "john@example.com",
 *     "role": "user",
 *     "tenant_id": 5
 *   }
 */
router.post('/', authenticateToken, setTenantContext, async (req, res) => {
  // only admin can create users
  if (!req.user || req.user.role !== 'admin') return res.status(403).send('Admin only');
  const { name, email, role, password, tenant_id } = req.body;
 
  try {
    // Determine which tenant to assign the user to
    let targetTenantId;
    
    if (tenant_id && req.tenant?.isMsp) {
      // Root user can specify any tenant
      targetTenantId = tenant_id;
    } else if (tenant_id) {
      // Non-root users can only create users in their own tenant
      targetTenantId = req.tenant?.id || req.user?.tenantId;
    } else {
      // No tenant_id provided, use current tenant
      targetTenantId = req.tenant?.id || req.user?.tenantId;
    }
 
    if (!targetTenantId) {
      return res.status(400).json({ error: 'Tenant context required' });
    }
 
    const salt = await bcrypt.genSalt(10);
    const password_hash = await bcrypt.hash(password, salt);
 
    const result = await pool.query(
      `INSERT INTO users (name, email, role, password_hash, tenant_id)
       VALUES ($1, $2, $3, $4, $5) RETURNING user_id, name, email, role, tenant_id`,
      [name, email, role, password_hash, targetTenantId]
    );
 
    res.status(201).json(result.rows[0]);
  } catch (err) {
    console.error('User creation error:', err);
    res.status(500).json({ error: 'User creation failed: ' + err.message });
  }
});
 
/**
 * @api {post} /users/register Register new user (Legacy)
 * @apiName RegisterUser
 * @apiGroup Users
 * @apiDescription Legacy endpoint for user registration. Functions identically to POST /users.
 * Maintained for backwards compatibility with existing clients. Admin-only operation.
 * 
 * **Deprecation Notice:**
 * Use POST /users instead. This endpoint will be removed in future versions.
 * @apiHeader {string} Authorization Bearer JWT token with admin role
 * @apiHeader {string} Content-Type application/json
 * @apiParam {string} name Full name
 * @apiParam {string} email Email address
 * @apiParam {string} role User role
 * @apiParam {string} password Password (will be hashed)
 * @apiParam {number} [tenant_id] Tenant ID
 * @apiSuccess {Object} user Created user object
 * @apiError {number} 403 Admin only
 * @apiError {number} 500 Registration failed
 * @since 1.0.0
 * @deprecated Use POST /users instead
 * @see {@link module:routes/users.createUser}
 */
router.post('/register', authenticateToken, setTenantContext, async (req, res) => {
  // only admin can create users
  if (!req.user || req.user.role !== 'admin') return res.status(403).send('Admin only');
  const { name, email, role, password, tenant_id } = req.body;
 
  try {
    // Determine which tenant to assign the user to
    let targetTenantId;
    
    if (tenant_id && req.tenant?.isMsp) {
      // Root user can specify any tenant
      targetTenantId = tenant_id;
    } else if (tenant_id) {
      // Non-root users can only create users in their own tenant
      targetTenantId = req.tenant?.id || req.user?.tenantId;
    } else {
      // No tenant_id provided, use current tenant
      targetTenantId = req.tenant?.id || req.user?.tenantId;
    }
 
    if (!targetTenantId) {
      return res.status(400).json({ error: 'Tenant context required' });
    }
 
    const salt = await bcrypt.genSalt(10);
    const password_hash = await bcrypt.hash(password, salt);
 
    const result = await pool.query(
      `INSERT INTO users (name, email, role, password_hash, tenant_id)
       VALUES ($1, $2, $3, $4, $5) RETURNING user_id, name, email, role, tenant_id`,
      [name, email, role, password_hash, targetTenantId]
    );
 
    res.status(201).json(result.rows[0]);
  } catch (err) {
    console.error('Registration error:', err);
    res.status(500).json({ error: 'User registration failed: ' + err.message });
  }
});
 
/**
 * @api {get} /users List all users
 * @apiName ListUsers
 * @apiGroup Users
 * @apiDescription Retrieves list of users with tenant filtering and optional search.
 * Root MSP users see all users across all tenants. Regular users only see users in
 * their own tenant. Returns up to 50 results when searching.
 * 
 * **Tenant Filtering:**
 * - MSP Root (is_msp=true): Returns all users from all tenants
 * - Regular users: Returns only users from their tenant
 * 
 * **Search Behavior:**
 * - Searches in name and email fields (case-insensitive ILIKE)
 * - Limited to 50 results to prevent excessive data transfer
 * - Returns empty array if no matches
 * @apiHeader {string} Authorization Bearer JWT token
 * @apiParam {string} [search] Search query for name or email
 * @apiSuccess {Array} users Array of user objects (password_hash excluded)
 * @apiSuccess {number} users.user_id User ID
 * @apiSuccess {string} users.name User name
 * @apiSuccess {string} users.email User email
 * @apiSuccess {string} users.role User role
 * @apiSuccess {number} users.tenant_id Tenant ID
 * @apiExample {curl} List All Users:
 *   curl -H "Authorization: Bearer eyJhbGc..." \
 *        "https://api.everydaytech.au/users"
 * @apiExample {curl} Search Users:
 *   curl -H "Authorization: Bearer eyJhbGc..." \
 *        "https://api.everydaytech.au/users?search=john"
 * @apiExample {json} Success Response:
 *   HTTP/1.1 200 OK
 *   [
 *     {
 *       "user_id": 42,
 *       "name": "John Smith",
 *       "email": "john@example.com",
 *       "role": "user",
 *       "tenant_id": 5
 *     }
 *   ]
 * @since 2.0.0
 */
router.get('/', authenticateToken, setTenantContext, async (req, res) => {
  try {
    const { search } = req.query;
    
    // Root users can see all users, regular users only see their tenant's users
    const tenantFilter = req.tenant?.isMsp ? '' : 'WHERE tenant_id = $1';
    const params = req.tenant?.isMsp ? [] : [req.tenant?.id || req.user?.tenantId];
    
    if (search && search.trim() !== '') {
      const q = `%${search.trim()}%`;
      const searchFilter = req.tenant?.isMsp 
        ? 'WHERE (name ILIKE $1 OR email ILIKE $1)'
        : 'WHERE tenant_id = $1 AND (name ILIKE $2 OR email ILIKE $2)';
      const searchParams = req.tenant?.isMsp ? [q] : [req.tenant?.id || req.user?.tenantId, q];
      
      const result = await pool.query(
        `SELECT user_id, name, email, role, tenant_id FROM users ${searchFilter} LIMIT 50`,
        searchParams
      );
      return res.json(result.rows);
    }
 
    const result = await pool.query(
      `SELECT user_id, name, email, role, tenant_id FROM users ${tenantFilter}`,
      params
    );
    res.json(result.rows);
  } catch (err) {
    console.error('Error fetching users:', err);
    res.status(500).send('Server error');
  }
});
 
/**
 * @api {put} /users/:id Update user
 * @apiName UpdateUser
 * @apiGroup Users
 * @apiDescription Updates an existing user's information. Admin-only operation. Can update
 * name, email, role, and optionally password. If password provided, it is bcrypt-hashed
 * before storage.
 * 
 * **Update Behavior:**
 * - Password update is optional (omit to keep existing password)
 * - If password included, old password is replaced with new hash
 * - Email changes do not automatically reverify email (email_verified remains unchanged)
 * - Role changes take effect immediately
 * @apiHeader {string} Authorization Bearer JWT token with admin role
 * @apiHeader {string} Content-Type application/json
 * @apiParam {number} id User ID (URL parameter)
 * @apiParam {string} name Updated name
 * @apiParam {string} email Updated email
 * @apiParam {string} role Updated role
 * @apiParam {string} [password] New password (optional, will be hashed if provided)
 * @apiSuccess {number} user_id User ID
 * @apiSuccess {string} name Updated name
 * @apiSuccess {string} email Updated email
 * @apiSuccess {string} role Updated role
 * @apiError {number} 403 Admin only
 * @apiError {number} 500 Update failed
 * @apiExample {curl} Example Request:
 *   curl -X PUT \
 *        -H "Authorization: Bearer eyJhbGc..." \
 *        -H "Content-Type: application/json" \
 *        -d '{
 *          "name": "Jane Doe",
 *          "email": "jane.doe@example.com",
 *          "role": "admin",
 *          "password": "NewP@ssw0rd"
 *        }' \
 *        "https://api.everydaytech.au/users/42"
 * @since 2.0.0
 */
router.put('/:id', authenticateToken, setTenantContext, async (req, res) => {
  if (!req.user || req.user.role !== 'admin') return res.status(403).send('Admin only');
  const { id } = req.params;
  const { name, email, role, password } = req.body;
  try {
    if (password) {
      const salt = await bcrypt.genSalt(10);
      const password_hash = await bcrypt.hash(password, salt);
      const result = await pool.query('UPDATE users SET name=$1, email=$2, role=$3, password_hash=$4 WHERE user_id=$5 RETURNING user_id, name, email, role', [name, email, role, password_hash, id]);
      return res.json(result.rows[0]);
    }
    const result = await pool.query('UPDATE users SET name=$1, email=$2, role=$3 WHERE user_id=$4 RETURNING user_id, name, email, role', [name, email, role, id]);
    res.json(result.rows[0]);
  } catch (err) {
    console.error('Error updating user:', err);
    res.status(500).send('Update failed');
  }
});
 
/**
 * @api {delete} /users/:id Delete user
 * @apiName DeleteUser
 * @apiGroup Users
 * @apiDescription Permanently deletes a user account. Admin-only operation. This action
 * cannot be undone. User's associated data (tickets, notes, time entries) may become
 * orphaned depending on database constraints.
 * 
 * **Warning:**
 * Hard delete removes user from database permanently. Consider deactivating users
 * instead by setting a status field (if implemented) to preserve audit trails.
 * @apiHeader {string} Authorization Bearer JWT token with admin role
 * @apiParam {number} id User ID to delete (URL parameter)
 * @apiSuccess {number} 204 No Content (user deleted successfully)
 * @apiError {number} 403 Admin only
 * @apiError {number} 500 Delete failed
 * @apiExample {curl} Example Request:
 *   curl -X DELETE \
 *        -H "Authorization: Bearer eyJhbGc..." \
 *        "https://api.everydaytech.au/users/42"
 * @since 2.0.0
 */
router.delete('/:id', authenticateToken, setTenantContext, async (req, res) => {
  if (!req.user || req.user.role !== 'admin') return res.status(403).send('Admin only');
  const { id } = req.params;
  try {
    await pool.query('DELETE FROM users WHERE user_id=$1', [id]);
    res.sendStatus(204);
  } catch (err) {
    console.error('Error deleting user:', err);
    res.status(500).send('Delete failed');
  }
});
 
/**
 * @api {post} /users/login User login
 * @apiName LoginUser
 * @apiGroup Authentication
 * @apiDescription Authenticates user with email/password and optional MFA code. Returns JWT
 * token valid for 30 days containing user_id, role, tenant_id, and is_msp flag. Token must
 * be included in Authorization header for protected endpoints.
 * 
 * **Authentication Flow:**
 * 1. Verify email exists in users table
 * 2. Compare password with bcrypt hash
 * 3. If MFA enabled, verify TOTP code (6-digit, 30-second window)
 * 4. Fetch tenant info (subdomain, is_msp flag)
 * 5. Generate JWT token with user + tenant data
 * 6. Return token and tenant information
 * 
 * **MFA Behavior:**
 * - If user has mfa_enabled=true, mfaCode parameter required
 * - TOTP code verified with ±1 time window (90 seconds total)
 * - Login fails if MFA enabled but code not provided or invalid
 * 
 * **JWT Payload:**
 * - user_id: User's unique ID
 * - role: "admin" or "user"
 * - name: User's display name
 * - tenant_id: User's tenant ID
 * - is_msp: Whether tenant is MSP root (boolean)
 * @apiHeader {string} Content-Type application/json
 * @apiParam {string} email User email address (required)
 * @apiParam {string} password User password (required)
 * @apiParam {string} [mfaCode] 6-digit TOTP code (required if MFA enabled)
 * @apiSuccess {string} token JWT bearer token (valid 30 days)
 * @apiSuccess {number} tenant_id User's tenant ID
 * @apiSuccess {string} subdomain Tenant subdomain
 * @apiSuccess {boolean} is_msp Whether tenant is MSP root
 * @apiError {number} 401 Invalid credentials
 * @apiError {number} 401 MFA required (when mfaCode not provided)
 * @apiError {number} 401 Invalid MFA code
 * @apiError {number} 500 Login failed (server error)
 * @apiExample {curl} Login Without MFA:
 *   curl -X POST \
 *        -H "Content-Type: application/json" \
 *        -d '{
 *          "email": "john@example.com",
 *          "password": "MyP@ssw0rd"
 *        }' \
 *        "https://api.everydaytech.au/users/login"
 * @apiExample {curl} Login With MFA:
 *   curl -X POST \
 *        -H "Content-Type: application/json" \
 *        -d '{
 *          "email": "john@example.com",
 *          "password": "MyP@ssw0rd",
 *          "mfaCode": "123456"
 *        }' \
 *        "https://api.everydaytech.au/users/login"
 * @apiExample {json} Success Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
 *     "tenant_id": 5,
 *     "subdomain": "acmecorp",
 *     "is_msp": false
 *   }
 * @apiExample {json} Error Response (MFA Required):
 *   HTTP/1.1 401 Unauthorized
 *   {
 *     "error": "MFA required"
 *   }
 * 
 * @since 2.0.0
 * @see {@link module:routes/users.getMe} for retrieving user info with token
 */
router.post('/login', async (req, res) => {
  const { email, password, mfaCode } = req.body;
 
  try {
    const result = await pool.query(
      `SELECT * FROM users WHERE email = $1`,
      [email]
    );
 
    if (result.rows.length === 0) return res.status(401).json({ error: 'Invalid credentials' });
 
    const user = result.rows[0];
    const valid = await bcrypt.compare(password, user.password_hash);
 
    if (!valid) return res.status(401).json({ error: 'Invalid credentials' });
 
    // If MFA enabled, require a valid TOTP code
    if (user.mfa_enabled) {
      if (!mfaCode) {
        return res.status(401).json({ error: 'MFA required' });
      }
      try {
        const speakeasy = require('speakeasy');
        const ok = speakeasy.totp.verify({ secret: user.mfa_secret, encoding: 'base32', token: mfaCode, window: 1 });
        if (!ok) return res.status(401).json({ error: 'Invalid MFA code' });
      } catch (e) {
        console.error('MFA verify error:', e);
        return res.status(500).json({ error: 'MFA verification failed' });
      }
    }
 
    // Get user's tenant info
    let subdomain = null;
    let tenant_id = user.tenant_id || null;
    let is_msp = false;
    if (tenant_id) {
      const tenantRes = await pool.query('SELECT subdomain, is_msp FROM tenants WHERE tenant_id = $1', [tenant_id]);
      if (tenantRes.rows.length > 0) {
        subdomain = tenantRes.rows[0].subdomain;
        is_msp = tenantRes.rows[0].is_msp || false;
      }
    }
 
    // Include tenant_id and is_msp in JWT payload
    const token = jwt.sign(
      { user_id: user.user_id, role: user.role, name: user.name, tenant_id, is_msp },
      process.env.JWT_SECRET,
      { expiresIn: '30d' }
    );
 
    // Set token as HTTP-only cookie for iframe requests (PDFs, etc.)
    // Use SameSite=None for production cross-origin (App Platform separate domains)
    res.cookie('auth_token', token, {
      httpOnly: true,
      secure: true, // Always require HTTPS in production
      sameSite: process.env.NODE_ENV === 'production' ? 'none' : 'lax',
      maxAge: 30 * 24 * 60 * 60 * 1000, // 30 days
      domain: process.env.NODE_ENV === 'production' ? '.ondigitalocean.app' : undefined
    });
 
    res.json({ token, tenant_id, subdomain, is_msp });
  } catch (err) {
    console.error('Login error:', err);
    res.status(500).send('Login failed');
  }
});
 
/**
 * @api {get} /users/me/theme Get user theme
 * @apiName GetUserTheme
 * @apiGroup User Profile
 * @apiDescription Retrieves the current user's theme preference. Used for UI theming
 * (light/dark mode, color schemes). Returns null if no theme set.
 * 
 * **Theme Values:**
 * Typical values: "light", "dark", "auto" (or custom theme names)
 * @apiHeader {string} Authorization Bearer JWT token
 * @apiSuccess {string} theme User's theme preference (or null)
 * @apiExample {curl} Example Request:
 *   curl -H "Authorization: Bearer eyJhbGc..." \
 *        "https://api.everydaytech.au/users/me/theme"
 * @apiExample {json} Success Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "theme": "dark"
 *   }
 * @since 2.0.0
 * @see {@link module:routes/users.updateUserTheme} for setting theme
 */
router.get('/me/theme', authenticateToken, async (req, res) => {
  try {
    const userId = req.user.user_id;
    const result = await pool.query('SELECT theme FROM users WHERE user_id = $1', [userId]);
    const theme = result.rows[0] ? result.rows[0].theme : null;
    res.json({ theme });
  } catch (err) {
    console.error('Error fetching user theme:', err);
    res.status(500).send('Server error');
  }
});
 
/**
 * @api {get} /users/me Get current user
 * @apiName GetCurrentUser
 * @apiGroup User Profile
 * @apiDescription Retrieves the authenticated user's profile information. Returns user
 * details extracted from JWT token. Does not include password_hash or sensitive fields.
 * 
 * **Use Cases:**
 * - Display user profile in UI
 * - Verify authentication status
 * - Get user role for client-side authorization
 * - Retrieve theme preference
 * @apiHeader {string} Authorization Bearer JWT token
 * @apiSuccess {number} user_id User's unique ID
 * @apiSuccess {string} name User's full name
 * @apiSuccess {string} email User's email address
 * @apiSuccess {string} role User's role (admin or user)
 * @apiSuccess {string} theme User's theme preference
 * @apiError {number} 404 User not found (token valid but user deleted)
 * @apiError {number} 500 Server error
 * @apiExample {curl} Example Request:
 *   curl -H "Authorization: Bearer eyJhbGc..." \
 *        "https://api.everydaytech.au/users/me"
 * @apiExample {json} Success Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "user_id": 42,
 *     "name": "John Smith",
 *     "email": "john@example.com",
 *     "role": "user",
 *     "theme": "dark"
 *   }
 * @since 2.0.0
 * @see {@link module:routes/users.login} for obtaining JWT token
 */
router.get('/me', authenticateToken, async (req, res) => {
  try {
    const userId = req.user.user_id;
    const result = await pool.query('SELECT user_id, name, email, role, theme FROM users WHERE user_id = $1', [userId]);
    if (result.rows.length === 0) {
      return res.status(404).send('User not found');
    }
    res.json(result.rows[0]);
  } catch (err) {
    console.error('Error fetching user info:', err);
    res.status(500).send('Server error');
  }
});
 
/**
 * @api {put} /users/me/theme Update user theme
 * @apiName UpdateUserTheme
 * @apiGroup User Profile
 * @apiDescription Updates the current user's theme preference. Theme is stored per-user
 * and persists across sessions. Used for UI theming customization.
 * 
 * **Theme Values:**
 * Common values: "light", "dark", "auto"
 * Can be any string value for custom themes
 * @apiHeader {string} Authorization Bearer JWT token
 * @apiHeader {string} Content-Type application/json
 * @apiParam {string} theme Theme preference (e.g., "light", "dark")
 * @apiSuccess {string} theme Updated theme value
 * @apiExample {curl} Example Request:
 *   curl -X PUT \
 *        -H "Authorization: Bearer eyJhbGc..." \
 *        -H "Content-Type: application/json" \
 *        -d '{"theme": "dark"}' \
 *        "https://api.everydaytech.au/users/me/theme"
 * @apiExample {json} Success Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "theme": "dark"
 *   }
 * @since 2.0.0
 */
router.put('/me/theme', authenticateToken, async (req, res) => {
  try {
    const userId = req.user.user_id;
    const { theme } = req.body;
    const result = await pool.query('UPDATE users SET theme = $1 WHERE user_id = $2 RETURNING theme', [theme, userId]);
    res.json({ theme: result.rows[0].theme });
  } catch (err) {
    console.error('Error updating user theme:', err);
    res.status(500).send('Server error');
  }
});
 
/**
 * @api {post} /users/request-password-reset Request password reset
 * @apiName RequestPasswordReset
 * @apiGroup Password Management
 * @apiDescription Initiates password reset flow by sending email with time-limited reset link.
 * Generates secure random token valid for 30 minutes (configurable via RESET_TOKEN_TTL_MIN).
 * Email contains link to reset password page with token embedded.
 * 
 * **Security:**
 * - Does not reveal whether email exists (always returns ok: true)
 * - Token is single-use (marked used_at after consumption)
 * - Tokens expire after 30 minutes by default
 * - Reset link includes token as query parameter
 * 
 * **Email Content:**
 * Sends email with reset link: {PUBLIC_APP_URL}/reset-password?token={token}
 * @apiHeader {string} Content-Type application/json
 * @apiParam {string} email User's email address (required)
 * @apiSuccess {boolean} ok Always true (even if email doesn't exist)
 * @apiError {number} 400 Email is required
 * @apiError {number} 500 Failed to create reset token
 * @apiExample {curl} Example Request:
 *   curl -X POST \
 *        -H "Content-Type: application/json" \
 *        -d '{"email": "john@example.com"}' \
 *        "https://api.everydaytech.au/users/request-password-reset"
 * @apiExample {json} Success Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "ok": true
 *   }
 * @since 2.0.0
 * @see {@link module:routes/users.resetPassword} for completing reset
 * @see {@link module:services/email.sendEmail} for email sending
 */
router.post('/request-password-reset', async (req, res) => {
  const { email } = req.body;
  if (!email) return res.status(400).json({ error: 'Email is required' });
  try {
    const userRes = await pool.query('SELECT user_id, email FROM users WHERE email=$1', [email]);
    if (userRes.rows.length === 0) {
      // Do not reveal that email does not exist
      return res.json({ ok: true });
    }
    const user = userRes.rows[0];
    const crypto = require('crypto');
    const token = crypto.randomBytes(32).toString('hex');
    const ttlMinutes = parseInt(process.env.RESET_TOKEN_TTL_MIN || '30', 10);
    await pool.query(
      `INSERT INTO password_reset_tokens (token, user_id, expires_at)
       VALUES ($1, $2, NOW() + INTERVAL '${ttlMinutes} minutes')`,
      [token, user.user_id]
    );
 
    const appUrl = process.env.PUBLIC_APP_URL || 'http://localhost:5173';
    const link = `${appUrl}/reset-password?token=${encodeURIComponent(token)}`;
    const { sendEmail } = require('../services/email');
    await sendEmail({
      to: email,
      subject: 'Password reset instructions',
      text: `Click the link to reset your password: ${link}`,
      html: `<p>Click the link to reset your password:</p><p><a href="${link}">${link}</a></p>`
    });
 
    res.json({ ok: true });
  } catch (err) {
    console.error('request-password-reset error:', err);
    res.status(500).json({ error: 'Failed to create reset token' });
  }
});
 
/**
 * @api {post} /users/reset-password Reset password with token
 * @apiName ResetPassword
 * @apiGroup Password Management
 * @apiDescription Completes password reset using token from email. New password is bcrypt-hashed
 * and stored. Token is marked as used to prevent reuse. Clears password_reset_required flag.
 * 
 * **Token Validation:**
 * - Token must exist in password_reset_tokens table
 * - Token must not be used (used_at IS NULL)
 * - Token must not be expired (expires_at > NOW())
 * - Token is single-use (marked used_at after successful reset)
 * 
 * **Password Storage:**
 * New password is bcrypt-hashed with 10-round salt before storage.
 * @apiHeader {string} Content-Type application/json
 * @apiParam {string} token Password reset token from email (required)
 * @apiParam {string} password New password to set (required)
 * @apiSuccess {boolean} ok Always true when successful
 * @apiError {number} 400 Token and password required
 * @apiError {number} 400 Invalid or expired token
 * @apiError {number} 500 Reset failed
 * @apiExample {curl} Example Request:
 *   curl -X POST \
 *        -H "Content-Type: application/json" \
 *        -d '{
 *          "token": "abc123def456...",
 *          "password": "NewS3cur3P@ss!"
 *        }' \
 *        "https://api.everydaytech.au/users/reset-password"
 * @apiExample {json} Success Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "ok": true
 *   }
 * @since 2.0.0
 * @see {@link module:routes/users.requestPasswordReset} for initiating reset
 */
router.post('/reset-password', async (req, res) => {
  const { token, password } = req.body;
  if (!token || !password) return res.status(400).json({ error: 'Token and password required' });
  try {
    const tRes = await pool.query(
      `SELECT t.user_id FROM password_reset_tokens t
       WHERE t.token=$1 AND t.used_at IS NULL AND t.expires_at > NOW()`,
      [token]
    );
    if (tRes.rows.length === 0) return res.status(400).json({ error: 'Invalid or expired token' });
    const userId = tRes.rows[0].user_id;
    const salt = await bcrypt.genSalt(10);
    const password_hash = await bcrypt.hash(password, salt);
    await pool.query('UPDATE users SET password_hash=$1, password_reset_required=false WHERE user_id=$2', [password_hash, userId]);
    await pool.query('UPDATE password_reset_tokens SET used_at=NOW() WHERE token=$1', [token]);
    res.json({ ok: true });
  } catch (err) {
    console.error('reset-password error:', err);
    res.status(500).json({ error: 'Reset failed' });
  }
});
 
/**
 * @api {post} /users/verify-email/request Request email verification
 * @apiName RequestEmailVerification
 * @apiGroup Email Verification
 * @apiDescription Sends email verification link to authenticated user. Generates secure
 * random token valid for 60 minutes (configurable via EMAIL_TOKEN_TTL_MIN). If email
 * already verified, returns success without sending email.
 * 
 * **Verification Flow:**
 * 1. User requests verification (this endpoint)
 * 2. System sends email with verification link
 * 3. User clicks link (opens /verify-email?token={token})
 * 4. Frontend calls POST /users/verify-email with token
 * 5. User's email_verified flag set to true
 * 
 * **Token Security:**
 * - Token valid for 60 minutes by default
 * - Single-use token (marked used_at after verification)
 * - Secure random generation (32 bytes)
 * @apiHeader {string} Authorization Bearer JWT token
 * @apiSuccess {boolean} ok Always true when successful
 * @apiSuccess {boolean} [alreadyVerified] true if email already verified
 * @apiError {number} 404 User not found
 * @apiError {number} 500 Failed to send verification email
 * @apiExample {curl} Example Request:
 *   curl -X POST \
 *        -H "Authorization: Bearer eyJhbGc..." \
 *        "https://api.everydaytech.au/users/verify-email/request"
 * @apiExample {json} Success Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "ok": true
 *   }
 * @apiExample {json} Already Verified:
 *   HTTP/1.1 200 OK
 *   {
 *     "ok": true,
 *     "alreadyVerified": true
 *   }
 * @since 2.0.0
 * @see {@link module:routes/users.verifyEmail} for completing verification
 */
router.post('/verify-email/request', authenticateToken, async (req, res) => {
  try {
    const userId = req.user.user_id;
    const uRes = await pool.query('SELECT email, email_verified FROM users WHERE user_id=$1', [userId]);
    if (uRes.rows.length === 0) return res.status(404).json({ error: 'User not found' });
    const { email, email_verified } = uRes.rows[0];
    if (email_verified) return res.json({ ok: true, alreadyVerified: true });
 
    const crypto = require('crypto');
    const token = crypto.randomBytes(32).toString('hex');
    const ttlMinutes = parseInt(process.env.EMAIL_TOKEN_TTL_MIN || '60', 10);
    await pool.query(
      `INSERT INTO email_verification_tokens (token, user_id, expires_at)
       VALUES ($1, $2, NOW() + INTERVAL '${ttlMinutes} minutes')`,
      [token, userId]
    );
 
    const appUrl = process.env.PUBLIC_APP_URL || 'http://localhost:5173';
    const link = `${appUrl}/verify-email?token=${encodeURIComponent(token)}`;
    const { sendEmail } = require('../services/email');
    await sendEmail({
      to: email,
      subject: 'Verify your email',
      text: `Verify your email address: ${link}`,
      html: `<p>Verify your email address:</p><p><a href="${link}">${link}</a></p>`
    });
 
    res.json({ ok: true });
  } catch (err) {
    console.error('verify-email/request error:', err);
    res.status(500).json({ error: 'Failed to send verification email' });
  }
});
 
/**
 * @api {post} /users/verify-email Verify email address
 * @apiName VerifyEmail
 * @apiGroup Email Verification
 * @apiDescription Completes email verification using token from email. Sets user's
 * email_verified flag to true. Token is marked as used to prevent reuse.
 * 
 * **Token Validation:**
 * - Token must exist in email_verification_tokens table
 * - Token must not be used (used_at IS NULL)
 * - Token must not be expired (expires_at > NOW())
 * - Token is single-use
 * @apiHeader {string} Content-Type application/json
 * @apiParam {string} token Email verification token from email (required)
 * @apiSuccess {boolean} ok Always true when successful
 * @apiError {number} 400 Token required
 * @apiError {number} 400 Invalid or expired token
 * @apiError {number} 500 Verification failed
 * @apiExample {curl} Example Request:
 *   curl -X POST \
 *        -H "Content-Type: application/json" \
 *        -d '{"token": "abc123def456..."}' \
 *        "https://api.everydaytech.au/users/verify-email"
 * @apiExample {json} Success Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "ok": true
 *   }
 * @since 2.0.0
 * @see {@link module:routes/users.requestEmailVerification} for initiating verification
 */
router.post('/verify-email', async (req, res) => {
  const { token } = req.body;
  if (!token) return res.status(400).json({ error: 'Token required' });
  try {
    const tRes = await pool.query(
      `SELECT user_id FROM email_verification_tokens
       WHERE token=$1 AND used_at IS NULL AND expires_at > NOW()`,
      [token]
    );
    if (tRes.rows.length === 0) return res.status(400).json({ error: 'Invalid or expired token' });
    const userId = tRes.rows[0].user_id;
    await pool.query('UPDATE users SET email_verified=true WHERE user_id=$1', [userId]);
    await pool.query('UPDATE email_verification_tokens SET used_at=NOW() WHERE token=$1', [token]);
    res.json({ ok: true });
  } catch (err) {
    console.error('verify-email error:', err);
    res.status(500).json({ error: 'Verification failed' });
  }
});
 
/**
 * @api {put} /users/me/password Change own password
 * @apiName ChangeOwnPassword
 * @apiGroup User Profile
 * @apiDescription Allows authenticated user to change their own password. Requires current
 * password for verification. New password is bcrypt-hashed before storage.
 * 
 * **Security:**
 * - Current password must be correct (verified against hash)
 * - New password immediately becomes active
 * - Does NOT invalidate existing JWT tokens
 * - User remains logged in after password change
 * 
 * **Best Practice:**
 * Implement password strength requirements on client side (length, complexity).
 * @apiHeader {string} Authorization Bearer JWT token
 * @apiHeader {string} Content-Type application/json
 * @apiParam {string} currentPassword User's current password (required for verification)
 * @apiParam {string} newPassword New password to set (required)
 * @apiSuccess {boolean} ok Always true when successful
 * @apiError {number} 400 Missing currentPassword or newPassword
 * @apiError {number} 401 Invalid current password
 * @apiError {number} 404 User not found
 * @apiError {number} 500 Password change failed
 * @apiExample {curl} Example Request:
 *   curl -X PUT \
 *        -H "Authorization: Bearer eyJhbGc..." \
 *        -H "Content-Type: application/json" \
 *        -d '{
 *          "currentPassword": "OldP@ss123",
 *          "newPassword": "NewS3cur3P@ss!"
 *        }' \
 *        "https://api.everydaytech.au/users/me/password"
 * @apiExample {json} Success Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "ok": true
 *   }
 * @since 2.0.0
 */
router.put('/me/password', authenticateToken, async (req, res) => {
  const { currentPassword, newPassword } = req.body;
  if (!currentPassword || !newPassword) return res.status(400).json({ error: 'currentPassword and newPassword required' });
  try {
    const userId = req.user.user_id;
    const uRes = await pool.query('SELECT password_hash FROM users WHERE user_id=$1', [userId]);
    if (uRes.rows.length === 0) return res.status(404).json({ error: 'User not found' });
    const valid = await bcrypt.compare(currentPassword, uRes.rows[0].password_hash);
    if (!valid) return res.status(401).json({ error: 'Invalid current password' });
    const salt = await bcrypt.genSalt(10);
    const password_hash = await bcrypt.hash(newPassword, salt);
    await pool.query('UPDATE users SET password_hash=$1 WHERE user_id=$2', [password_hash, userId]);
    res.json({ ok: true });
  } catch (err) {
    console.error('me/password error:', err);
    res.status(500).json({ error: 'Password change failed' });
  }
});
 
/**
 * @api {post} /users/:id/reset-password Admin reset user password
 * @apiName AdminResetPassword
 * @apiGroup Password Management
 * @apiDescription Admin-initiated password reset for a user. Generates reset token and sends
 * email with reset link. Sets password_reset_required flag to force user to change password
 * on next login. Admin-only operation.
 * 
 * **Use Cases:**
 * - User forgot password and can't access email
 * - Security incident requiring password reset
 * - New user account setup
 * - Compromised account recovery
 * 
 * **Reset Flow:**
 * 1. Admin calls this endpoint with user ID
 * 2. Reset token generated (30 minute expiry)
 * 3. Email sent to user with reset link
 * 4. password_reset_required flag set to true
 * 5. User clicks link and sets new password
 * 6. Flag cleared after successful reset
 * @apiHeader {string} Authorization Bearer JWT token with admin role
 * @apiHeader {string} Content-Type application/json
 * @apiParam {number} id User ID to reset (URL parameter)
 * @apiSuccess {boolean} ok Always true when successful
 * @apiError {number} 403 Admin only
 * @apiError {number} 404 User not found
 * @apiError {number} 500 Failed to initiate reset
 * @apiExample {curl} Example Request:
 *   curl -X POST \
 *        -H "Authorization: Bearer eyJhbGc..." \
 *        "https://api.everydaytech.au/users/42/reset-password"
 * @apiExample {json} Success Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "ok": true
 *   }
 * @since 2.0.0
 */
router.post('/:id/reset-password', authenticateToken, async (req, res) => {
  // require admin role to reset
  if (!req.user || req.user.role !== 'admin') return res.status(403).json({ error: 'Admin only' });
  try {
    const { id } = req.params;
    const uRes = await pool.query('SELECT user_id, email FROM users WHERE user_id=$1', [id]);
    if (uRes.rows.length === 0) return res.status(404).json({ error: 'User not found' });
 
    const crypto = require('crypto');
    const token = crypto.randomBytes(32).toString('hex');
    const ttlMinutes = parseInt(process.env.RESET_TOKEN_TTL_MIN || '30', 10);
    await pool.query(
      `INSERT INTO password_reset_tokens (token, user_id, expires_at)
       VALUES ($1, $2, NOW() + INTERVAL '${ttlMinutes} minutes')`,
      [token, id]
    );
 
    const appUrl = process.env.PUBLIC_APP_URL || 'http://localhost:5173';
    const link = `${appUrl}/reset-password?token=${encodeURIComponent(token)}`;
    const { sendEmail } = require('../services/email');
    await sendEmail({
      to: uRes.rows[0].email,
      subject: 'Admin initiated password reset',
      text: `An administrator has initiated a password reset for your account. Reset here: ${link}`,
      html: `<p>An administrator has initiated a password reset for your account.</p><p><a href="${link}">Reset Password</a></p>`
    });
 
    await pool.query('UPDATE users SET password_reset_required=true WHERE user_id=$1', [id]);
 
    res.json({ ok: true });
  } catch (err) {
    console.error('admin reset-password error:', err);
    res.status(500).json({ error: 'Failed to initiate reset' });
  }
});
 
/**
 * @api {post} /users/mfa/setup Setup MFA/2FA
 * @apiName SetupMFA
 * @apiGroup Multi-Factor Authentication
 * @apiDescription Generates TOTP secret for multi-factor authentication setup. Returns
 * secret in base32 format and otpauth URL for QR code generation. User scans QR code with
 * authenticator app (Google Authenticator, Authy, etc.) and then calls /mfa/enable with
 * verification code.
 * 
 * **MFA Setup Flow:**
 * 1. User calls /mfa/setup to get secret
 * 2. Frontend generates QR code from otpauth_url
 * 3. User scans QR code with authenticator app
 * 4. App displays 6-digit TOTP code
 * 5. User enters code, frontend calls /mfa/enable with base32 + code
 * 6. Code verified, MFA enabled
 * 
 * **TOTP Details:**
 * - Algorithm: SHA-1
 * - Digits: 6
 * - Period: 30 seconds
 * - Compatible with Google Authenticator, Authy, Microsoft Authenticator, etc.
 * 
 * **Security:**
 * Secret generated but not yet stored in database. Only stored when /mfa/enable
 * called with valid verification code.
 * @apiHeader {string} Authorization Bearer JWT token
 * @apiSuccess {string} base32 TOTP secret in base32 encoding (store for /mfa/enable)
 * @apiSuccess {string} otpauth_url OTP auth URL for QR code generation
 * @apiError {number} 404 User not found
 * @apiError {number} 500 MFA setup failed
 * @apiExample {curl} Example Request:
 *   curl -X POST \
 *        -H "Authorization: Bearer eyJhbGc..." \
 *        "https://api.everydaytech.au/users/mfa/setup"
 * @apiExample {json} Success Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "base32": "JBSWY3DPEHPK3PXP",
 *     "otpauth_url": "otpauth://totp/IBG%20MSP%20Platform%20(john@example.com)?secret=JBSWY3DPEHPK3PXP&issuer=IBG%20MSP%20Platform"
 *   }
 * @since 2.0.0
 * @see {@link module:routes/users.enableMFA} for completing MFA setup
 * @see {@link module:routes/users.login} for MFA-enabled login
 */
router.post('/mfa/setup', authenticateToken, async (req, res) => {
  try {
    const speakeasy = require('speakeasy');
    const uRes = await pool.query('SELECT email FROM users WHERE user_id=$1', [req.user.user_id]);
    if (uRes.rows.length === 0) return res.status(404).json({ error: 'User not found' });
    const email = uRes.rows[0].email;
    const secret = speakeasy.generateSecret({ name: `IBG MSP Platform (${email})` });
    res.json({ base32: secret.base32, otpauth_url: secret.otpauth_url });
  } catch (err) {
    console.error('mfa/setup error:', err);
    res.status(500).json({ error: 'MFA setup failed' });
  }
});
 
/**
 * @api {post} /users/mfa/enable Enable MFA/2FA
 * @apiName EnableMFA
 * @apiGroup Multi-Factor Authentication
 * @apiDescription Enables multi-factor authentication after verifying TOTP code. User must
 * provide base32 secret from /mfa/setup and valid 6-digit code from authenticator app.
 * Stores secret and sets mfa_enabled flag to true.
 * 
 * **Verification:**
 * - TOTP code verified with ±1 time window (90 seconds total)
 * - Code must match secret generated in /mfa/setup
 * - If verification fails, MFA not enabled
 * 
 *After Enabling:**
 * - User required to provide TOTP code on every login
 * - Login endpoint expects mfaCode parameter
 * - Can be disabled via /mfa/disable with valid code
 * @apiHeader {string} Authorization Bearer JWT token
 * @apiHeader {string} Content-Type application/json
 * @apiParam {string} base32 Secret from /mfa/setup (required)
 * @apiParam {string} code 6-digit TOTP code from authenticator app (required)
 * @apiSuccess {boolean} ok Always true when successful
 * @apiError {number} 400 base32 and code required
 * @apiError {number} 400 Invalid code (TOTP verification failed)
 * @apiError {number} 500 Failed to enable MFA
 * @apiExample {curl} Example Request:
 *   curl -X POST \
 *        -H "Authorization: Bearer eyJhbGc..." \
 *        -H "Content-Type: application/json" \
 *        -d '{
 *          "base32": "JBSWY3DPEHPK3PXP",
 *          "code": "123456"
 *        }' \
 *        "https://api.everydaytech.au/users/mfa/enable"
 * @apiExample {json} Success Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "ok": true
 *   }
 * @apiExample {json} Error Response (Invalid Code):
 *   HTTP/1.1 400 Bad Request
 *   {
 *     "error": "Invalid code"
 *   }
 * @since 2.0.0
 * @see {@link module:routes/users.setupMFA} for getting secret
 * @see {@link module:routes/users.disableMFA} for disabling MFA
 */
router.post('/mfa/enable', authenticateToken, async (req, res) => {
  const { base32, code } = req.body;
  if (!base32 || !code) return res.status(400).json({ error: 'base32 and code required' });
  try {
    const speakeasy = require('speakeasy');
    const ok = speakeasy.totp.verify({ secret: base32, encoding: 'base32', token: code, window: 1 });
    if (!ok) return res.status(400).json({ error: 'Invalid code' });
    await pool.query('UPDATE users SET mfa_enabled=true, mfa_secret=$1 WHERE user_id=$2', [base32, req.user.user_id]);
    res.json({ ok: true });
  } catch (err) {
    console.error('mfa/enable error:', err);
    res.status(500).json({ error: 'Failed to enable MFA' });
  }
});
 
/**
 * @api {post} /users/mfa/disable Disable MFA/2FA
 * @apiName DisableMFA
 * @apiGroup Multi-Factor Authentication
 * @apiDescription Disables multi-factor authentication for user. Requires valid TOTP code
 * for verification. Clears mfa_enabled flag and removes mfa_secret from database.
 * 
 * **Security:**
 * - User must provide valid TOTP code to disable MFA
 * - Prevents unauthorized MFA removal
 * - Code verified with ±1 time window
 * 
 * **After Disabling:**
 * - User can login with just email/password
 * - No TOTP code required
 * - Secret removed from database
 * - User can re-enable MFA anytime by running setup flow again
 * @apiHeader {string} Authorization Bearer JWT token
 * @apiHeader {string} Content-Type application/json
 * @apiParam {string} code 6-digit TOTP code from authenticator app (required)
 * @apiSuccess {boolean} ok Always true when successful
 * @apiError {number} 400 MFA is not enabled
 * @apiError {number} 400 Invalid code
 * @apiError {number} 500 Failed to disable MFA
 * @apiExample {curl} Example Request:
 *   curl -X POST \
 *        -H "Authorization: Bearer eyJhbGc..." \
 *        -H "Content-Type: application/json" \
 *        -d '{"code": "123456"}' \
 *        "https://api.everydaytech.au/users/mfa/disable"
 * @apiExample {json} Success Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "ok": true
 *   }
 * @apiExample {json} Error Response (Not Enabled):
 *   HTTP/1.1 400 Bad Request
 *   {
 *     "error": "MFA is not enabled"
 *   }
 * @since 2.0.0
 * @see {@link module:routes/users.enableMFA} for enabling MFA
 */
router.post('/mfa/disable', authenticateToken, async (req, res) => {
  const { code } = req.body;
  try {
    const speakeasy = require('speakeasy');
    const uRes = await pool.query('SELECT mfa_secret FROM users WHERE user_id=$1', [req.user.user_id]);
    const secret = uRes.rows[0]?.mfa_secret;
    if (!secret) return res.status(400).json({ error: 'MFA is not enabled' });
    const ok = speakeasy.totp.verify({ secret, encoding: 'base32', token: code, window: 1 });
    if (!ok) return res.status(400).json({ error: 'Invalid code' });
    await pool.query('UPDATE users SET mfa_enabled=false, mfa_secret=NULL WHERE user_id=$1', [req.user.user_id]);
    res.json({ ok: true });
  } catch (err) {
    console.error('mfa/disable error:', err);
    res.status(500).json({ error: 'Failed to disable MFA' });
  }
});
 
module.exports = router;