User Management Guide

User Management Overview

The HostingCo system implements a robust user management system with role-based access control (RBAC), comprehensive authentication, and detailed user lifecycle management.

User Types and Roles

🔐 User Authentication

Registration Process

Self-Registration

# API endpoint for user registration
POST /api/auth/register

# Request body
{
  "email": "newuser@example.com",
  "password": "SecurePass123!",
  "name": "John Doe",
  "company": "Acme Corp"
}

Admin Registration

# Admin creates user
POST /api/admin/users

# Request body
{
  "email": "user@example.com",
  "name": "Jane Smith",
  "role": "user",
  "permissions": ["servers.read", "billing.read"]
}

Login Process

# User login
POST /api/auth/login

# Request body
{
  "email": "user@example.com",
  "password": "password123"
}

# Response
{
  "token": "jwt-token-here",
  "user": {
    "id": "user-id",
    "email": "user@example.com",
    "name": "John Doe",
    "role": "user"
  }
}

Role-Based Access Control

Permission System

Role Definitions

// Role definitions
export const ROLES = {
  SUPER_ADMIN: {
    name: 'Super Admin',
    permissions: ['*'] // All permissions
  },
  ADMIN: {
    name: 'Admin',
    permissions: [
      'users.read', 'users.write',
      'servers.read', 'servers.write',
      'billing.read', 'billing.write',
      'support.read', 'support.write'
    ]
  },
  SUPPORT: {
    name: 'Support',
    permissions: [
      'users.read',
      'servers.read',
      'billing.read',
      'support.read', 'support.write'
    ]
  },
  USER: {
    name: 'User',
    permissions: [
      'profile.read', 'profile.write',
      'servers.read:own',
      'billing.read:own'
    ]
  },
  READ_ONLY: {
    name: 'Read Only',
    permissions: ['servers.read:assigned']
  }
};

Permission Checking

// Permission checking middleware
export const requirePermission = (permission: string) => {
  return (req: Request, res: Response, next: NextFunction) => {
    const user = req.user;
    
    if (!user) {
      return res.status(401).json({ error: 'Unauthorized' });
    }
    
    if (!user.hasPermission(permission)) {
      return res.status(403).json({ error: 'Forbidden' });
    }
    
    next();
  };
};

// Usage in routes
router.get('/users', requirePermission('users.read'), UserController.getAll);
router.post('/users', requirePermission('users.write'), UserController.create);

User Lifecycle Management

User Creation

// User creation service
export class UserService {
  static async create(userData: CreateUserDto, creator?: User): Promise<User> {
    // Validate user data
    await this.validateUserData(userData);
    
    // Check for existing user
    const existing = await this.findByEmail(userData.email);
    if (existing) {
      throw new Error('User already exists');
    }
    
    // Hash password
    const passwordHash = await bcrypt.hash(userData.password, 12);
    
    // Create user
    const user = await User.create({
      ...userData,
      passwordHash,
      createdBy: creator?.id
    });
    
    // Send welcome email
    await EmailService.sendWelcomeEmail(user.email, user.name);
    
    return user;
  }
}

User Updates

# Update user information
PUT /api/users/:id

# Request body
{
  "name": "Updated Name",
  "company": "New Company",
  "phone": "+1234567890"
}

# Change password
PUT /api/users/:id/password

# Request body
{
  "currentPassword": "oldpassword",
  "newPassword": "newpassword"
}

User Deactivation

// User deactivation
export class UserService {
  static async deactivate(userId: string, deactivatedBy: string): Promise<User> {
    const user = await this.findById(userId);
    if (!user) {
      throw new Error('User not found');
    }
    
    // Deactivate user
    await User.update(userId, {
      isActive: false,
      deactivatedAt: new Date(),
      deactivatedBy
    });
    
    // Revoke all active sessions
    await SessionService.revokeAllUserSessions(userId);
    
    // Send deactivation notification
    await EmailService.sendDeactivationEmail(user.email);
    
    return user;
  }
}

User Administration

User Management Interface

// Admin user management component
export const UserManagement: React.FC = () => {
  const [users, setUsers] = useState<User[]>([]);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    loadUsers();
  }, []);

  const loadUsers = async () => {
    try {
      const response = await api.get('/admin/users');
      setUsers(response.data);
    } catch (error) {
      console.error('Failed to load users:', error);
    } finally {
      setLoading(false);
    }
  };

  const createUser = async (userData: CreateUserDto) => {
    try {
      await api.post('/admin/users', userData);
      loadUsers();
    } catch (error) {
      console.error('Failed to create user:', error);
    }
  };

  return (
    <div className="user-management">
      <UserList users={users} onCreateUser={createUser} />
    </div>
  );
};

Bulk Operations

# Bulk user creation
POST /api/admin/users/bulk

# Request body
{
  "users": [
    {
      "email": "user1@example.com",
      "name": "User One",
      "role": "user"
    },
    {
      "email": "user2@example.com",
      "name": "User Two",
      "role": "user"
    }
  ]
}

# Bulk user updates
PUT /api/admin/users/bulk

# Bulk user deactivation
DELETE /api/admin/users/bulk

User Import/Export

# Export users
GET /api/admin/users/export?format=csv
GET /api/admin/users/export?format=json

# Import users
POST /api/admin/users/import
Content-Type: multipart/form-data

# File: users.csv
email,name,role,company
user1@example.com,User One,user,Company A
user2@example.com,User Two,user,Company B

🔑 Session Management

JWT Token Management

// JWT token service
export class TokenService {
  static generateToken(user: User): string {
    const payload = {
      id: user.id,
      email: user.email,
      role: user.role,
      permissions: user.permissions
    };
    
    return jwt.sign(payload, process.env.JWT_SECRET, {
      expiresIn: '24h',
      issuer: 'hostingco',
      audience: 'hostingco-users'
    });
  }

  static verifyToken(token: string): any {
    try {
      return jwt.verify(token, process.env.JWT_SECRET);
    } catch (error) {
      throw new Error('Invalid token');
    }
  }

  static refreshToken(refreshToken: string): string {
    // Implement refresh token logic
  }
}

Session Tracking

// Session tracking
export class SessionService {
  static async createSession(user: User, userAgent: string): Promise<Session> {
    return Session.create({
      userId: user.id,
      token: generateToken(user),
      userAgent,
      ipAddress: getClientIP(),
      createdAt: new Date(),
      expiresAt: new Date(Date.now() + 24 * 60 * 60 * 1000) // 24 hours
    });
  }

  static async revokeSession(sessionId: string): Promise<void> {
    await Session.update(sessionId, { isActive: false });
  }

  static async revokeAllUserSessions(userId: string): Promise<void> {
    await Session.update({ userId }, { isActive: false });
  }
}

Session Monitoring

# View active sessions
GET /api/admin/sessions

# Revoke specific session
DELETE /api/admin/sessions/:sessionId

# Revoke all user sessions
DELETE /api/admin/users/:userId/sessions

🔒 User Security

Password Policies

Password Validation

// Password validation
export class PasswordValidator {
  static validate(password: string): ValidationResult {
    const errors: string[] = [];

    if (password.length < 8) {
      errors.push('Password must be at least 8 characters long');
    }

    if (!/[A-Z]/.test(password)) {
      errors.push('Password must contain at least one uppercase letter');
    }

    if (!/[a-z]/.test(password)) {
      errors.push('Password must contain at least one lowercase letter');
    }

    if (!/\d/.test(password)) {
      errors.push('Password must contain at least one number');
    }

    if (!/[!@#$%^&*]/.test(password)) {
      errors.push('Password must contain at least one special character');
    }

    return {
      isValid: errors.length === 0,
      errors
    };
  }
}

Two-Factor Authentication

// 2FA implementation
export class TwoFactorService {
  static generateSecret(): string {
    return speakeasy.generateSecret({
      name: 'HostingCo',
      issuer: 'HostingCo'
    }).base32;
  }

  static verifyToken(secret: string, token: string): boolean {
    return speakeasy.totp.verify({
      secret,
      encoding: 'base32',
      token,
      window: 2
    });
  }

  static generateQRCode(secret: string): string {
    return speakeasy.otpauthURL({
      secret,
      label: 'HostingCo',
      issuer: 'HostingCo'
    });
  }
}

Account Lockout

// Account lockout protection
export class SecurityService {
  static async handleFailedLogin(email: string): Promise<void> {
    const attempts = await Redis.incr(`login_attempts:${email}`);
    await Redis.expire(`login_attempts:${email}`, 3600); // 1 hour

    if (attempts >= 5) {
      await UserService.lockAccount(email);
      await EmailService.sendAccountLockedEmail(email);
    }
  }

  static async resetLoginAttempts(email: string): Promise<void> {
    await Redis.del(`login_attempts:${email}`);
  }
}

User Analytics

User Metrics

Usage Analytics

# Get user statistics
GET /api/admin/analytics/users

# Get user activity
GET /api/admin/analytics/users/activity?period=30d

# Get user retention
GET /api/admin/analytics/users/retention

Reporting

// User analytics service
export class UserAnalyticsService {
  static async getUserMetrics(): Promise<UserMetrics> {
    const totalUsers = await User.count();
    const activeUsers = await User.count({
      where: {
        lastLoginAt: {
          [Op.gte]: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000)
        }
      }
    });

    return {
      totalUsers,
      activeUsers,
      newUsers: await this.getNewUsers(),
      retentionRate: await this.calculateRetentionRate()
    };
  }
}

User Management Best Practices

Security Best Practices

User Experience Best Practices

• Clear and intuitive registration process
• Helpful error messages and validation feedback
• Easy password reset and account recovery
• Consistent user interface across all user management features

Administrative Best Practices

# Regular user management tasks
npm run users:audit           # Audit user permissions
npm run users:cleanup          # Clean up inactive users
npm run users:backup           # Backup user data
npm run users:report           # Generate user reports