BotPort GUI Framework

A secure database framework for React applications with MySQL support, user management, and comprehensive security features.

Features

• 🔐 Secure User Management: Password hashing with SHA-256 and salt generation
• 🗄️ MySQL Connection Pooling: Built on mysql2 with persistent connections
• 🛡️ SQL Injection Protection: Parameterized queries and input sanitization
• 📝 TypeScript Support: Full type definitions included
• 🔍 User Search & Pagination: Efficient data retrieval with pagination
• ✅ Input Validation: Username and password validation
• 🚀 Easy Integration: Simple API for React applications
• ⚙️ Environment Configuration: Automatic .env.local loading

Installation

npm install @botport/gui

Quick Start

1. Create .env.local file

Create a .env.local file in your project root:

DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=root
DB_NAME=botport

2. Initialize the Framework

import { BotPortFramework } from '@botport/gui';

const framework = new BotPortFramework();

// Initialize - will automatically use .env.local configuration
await framework.initialize();

3. User Registration

const userService = framework.getUserService();

try {
  const newUser = await userService.registerUser({
    username: 'john_doe',
    password: 'SecurePassword123!'
  });
  
  console.log('User registered:', newUser);
} catch (error) {
  console.error('Registration failed:', error.message);
}

4. User Authentication

try {
  const user = await userService.authenticateUser('john_doe', 'SecurePassword123!');
  console.log('User authenticated:', user);
} catch (error) {
  console.error('Authentication failed:', error.message);
}

API Reference

BotPortFramework

Main framework class for easy initialization and management.

Methods

• initialize(config?: DatabaseConfig): Promise<boolean> - Initialize the framework
• getDatabase(): DatabaseManager - Get database manager instance
• getUserService(): UserService - Get user service instance
• isReady(): boolean - Check if framework is initialized
• disconnect(): Promise<void> - Disconnect from database

UserService

High-level user management with security features.

Methods

• registerUser(userData: UserData): Promise<User> - Register a new user
• authenticateUser(username: string, password: string): Promise<User> - Authenticate user
• getUserById(userId: number): Promise<User> - Get user by ID
• updateUserProfile(userId: number, updateData: Partial<UserUpdateData>): Promise<User> - Update user profile
• changePassword(userId: number, currentPassword: string, newPassword: string): Promise<boolean> - Change password
• getAllUsers(limit?: number, offset?: number): Promise<User[]> - Get all users with pagination
• searchUsers(query: string, limit?: number): Promise<User[]> - Search users
• getUserCount(): Promise<number> - Get total user count

DatabaseManager

Low-level database operations with connection pooling.

Methods

• connect(config?: DatabaseConfig): Promise<any> - Connect to database
• createUser(userData): Promise<User> - Create user in database
• getUserById(userId: number): Promise<User | null> - Get user by ID
• getUserByUsername(username: string): Promise<UserWithAuth | null> - Get user by username
• updateUser(userId: number, updateData: UserUpdateData): Promise<boolean> - Update user
• deleteUser(userId: number): Promise<boolean> - Delete user
• disconnect(): Promise<void> - Disconnect from database
• getConnection(): Promise<any> - Get connection from pool

Security Utilities

import {
  generateSalt,
  hashPassword,
  verifyPassword,
  validateUsername,
  validatePassword,
  sanitizeInput
} from '@botport/gui';

// Generate salt for password hashing
const salt = generateSalt();

// Hash password with salt using SHA-256
const hashedPassword = hashPassword('myPassword', salt);

// Verify password
const isValid = verifyPassword('myPassword', hashedPassword, salt);

// Validate inputs
const isUsernameValid = validateUsername('john_doe');
const passwordValidation = validatePassword('MyPassword123!');

// Sanitize input
const sanitized = sanitizeInput('<script>alert("xss")</script>');

React Integration Example

User Registration Component

import React, { useState } from 'react';
import { BotPortFramework } from '@botport/gui';

const RegisterForm: React.FC = () => {
  const [formData, setFormData] = useState({
    username: '',
    password: ''
  });
  const [error, setError] = useState('');
  const [success, setSuccess] = useState('');

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    setError('');
    setSuccess('');

    try {
      const framework = new BotPortFramework();
      await framework.initialize(); // Uses .env.local automatically

      const userService = framework.getUserService();
      const newUser = await userService.registerUser(formData);
      
      setSuccess(`User ${newUser.username} registered successfully!`);
      await framework.disconnect();
    } catch (err) {
      setError(err instanceof Error ? err.message : 'Registration failed');
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <input
        type="text"
        placeholder="Username"
        value={formData.username}
        onChange={(e) => setFormData({...formData, username: e.target.value})}
      />
      <input
        type="password"
        placeholder="Password"
        value={formData.password}
        onChange={(e) => setFormData({...formData, password: e.target.value})}
      />
      <button type="submit">Register</button>
      {error && <div className="error">{error}</div>}
      {success && <div className="success">{success}</div>}
    </form>
  );
};

User Authentication Hook

import { useState, useEffect } from 'react';
import { BotPortFramework } from '@botport/gui';

export const useAuth = () => {
  const [user, setUser] = useState(null);
  const [loading, setLoading] = useState(true);
  const [framework, setFramework] = useState(null);

  useEffect(() => {
    const initFramework = async () => {
      const fw = new BotPortFramework();
      await fw.initialize(); // Uses .env.local automatically
      setFramework(fw);
      setLoading(false);
    };

    initFramework();
  }, []);

  const login = async (username: string, password: string) => {
    if (!framework) throw new Error('Framework not initialized');
    
    const userService = framework.getUserService();
    const authenticatedUser = await userService.authenticateUser(username, password);
    setUser(authenticatedUser);
    return authenticatedUser;
  };

  const logout = () => {
    setUser(null);
  };

  const register = async (userData) => {
    if (!framework) throw new Error('Framework not initialized');
    
    const userService = framework.getUserService();
    const newUser = await userService.registerUser(userData);
    setUser(newUser);
    return newUser;
  };

  return { user, loading, login, logout, register };
};

Database Schema

The framework automatically creates a users table with the following structure:

CREATE TABLE users (
  id INT AUTO_INCREMENT PRIMARY KEY,
  username VARCHAR(255) NOT NULL UNIQUE,
  password_hash VARCHAR(255) NOT NULL,
  salt VARCHAR(255) NOT NULL,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  is_active BOOLEAN DEFAULT TRUE,
  last_login TIMESTAMP NULL,
  INDEX idx_username (username),
  INDEX idx_created_at (created_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

Security Features

• Password Hashing: SHA-256 with unique salt per user
• SQL Injection Protection: Parameterized queries
• Input Sanitization: XSS prevention
• Validation: Username and password strength validation
• Connection Pooling: Efficient database connections
• Environment Security: Configuration via .env.local

Environment Variables

Set these environment variables in your .env.local file:

DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=root
DB_NAME=botport

Connection Pooling

The framework uses MySQL connection pooling for better performance:

• Connection Limit: 10 concurrent connections
• Acquire Timeout: 60 seconds
• Reconnection: Automatic reconnection on failure
• Connection Management: Automatic connection release

Error Handling

The framework provides detailed error messages for common scenarios:

• Invalid credentials
• Username already exists
• Database connection failures
• Validation errors
• Permission errors

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For support and questions, please open an issue on GitHub or contact the maintainers.