Skip to content

BROWSER_MODE.md

Latest commit

 

History

History
307 lines (225 loc) · 9.67 KB

BROWSER_MODE.md

File metadata and controls

307 lines (225 loc) · 9.67 KB

Browser Mode Documentation

MQTT Explorer now supports running as a web application served by a Node.js server, in addition to the existing Electron desktop app.

Running in Browser Mode

Quick Start

  1. Build the application for browser mode:

    yarn build:server

  2. Start the server:

    yarn start:server

  3. Open your browser and navigate to http://localhost:3000

  4. You'll be prompted to log in with credentials that were generated on server startup.

Development Mode

To run in development mode with hot reload:

yarn dev:server

This starts both the webpack dev server and the backend server.

Authentication

Environment Variables

You can set custom authentication credentials using environment variables:

export MQTT_EXPLORER_USERNAME=admin
export MQTT_EXPLORER_PASSWORD=secretpassword
yarn start:server

Generated Credentials

If no environment variables are set, the server will generate credentials on first startup and save them to data/credentials.json. The generated credentials will be printed to the console:

============================================================
Generated new credentials:
Username: user-abc123
Password: 123e4567-e89b-12d3-a456-426614174000
============================================================
Please save these credentials. They will be persisted to:
/path/to/data/credentials.json
============================================================

Features

Certificate Upload

In browser mode, certificate files are uploaded directly through the browser using the HTML5 File API. The certificates are:

  • Read client-side as base64
  • Stored in the connection configuration
  • Used when establishing MQTT connections

Data Storage

In browser mode, all data is stored on the server:

  • Credentials: data/credentials.json
  • Uploaded certificates: data/certificates/
  • File uploads: data/uploads/

Port Configuration

The default port is 3000. You can change it using the PORT environment variable:

PORT=8080 yarn start:server

Architecture

Client-Server Communication

  • Electron Mode: Uses Electron IPC for communication between renderer and main process
  • Browser Mode: Uses Socket.io WebSockets for real-time communication between browser and server

The application automatically detects the environment and uses the appropriate transport layer.

Event Bus Abstraction

Both Electron IPC and Socket.io implement the same EventBusInterface, allowing the application code to work seamlessly in both modes without modification.

Differences from Electron Mode

Browser Mode Limitations

  1. File System Access: Limited to server-side operations
  2. Native Dialogs: File selection uses browser file input instead of native dialogs
  3. Auto-Updates: Not available in browser mode
  4. Tray Icon: Not available in browser mode

Browser Mode Advantages

  1. No Installation: Access from any browser
  2. Cross-Platform: Works on any device with a modern browser
  3. Remote Access: Can be deployed on a server for remote access
  4. Multi-User: Can support authentication for multiple users

Security Considerations

Production Deployment

CRITICAL: The following security measures must be implemented for production deployments:

1. HTTPS/TLS Encryption

Always use HTTPS in production to protect credentials and MQTT data in transit:

# Use a reverse proxy like nginx or Apache with TLS
# Example nginx configuration:
server {
    listen 443 ssl http2;
    server_name mqtt-explorer.example.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

2. Environment Variables for Credentials

NEVER use generated credentials in production. Always set secure credentials via environment variables:

export MQTT_EXPLORER_USERNAME=your_secure_username
export MQTT_EXPLORER_PASSWORD=your_strong_password_min_12_chars
export NODE_ENV=production
yarn start:server

3. CORS Configuration

Configure allowed origins instead of using the wildcard (*):

# Single origin
export ALLOWED_ORIGINS=https://mqtt-explorer.example.com

# Multiple origins (comma-separated)
export ALLOWED_ORIGINS=https://app1.example.com,https://app2.example.com

yarn start:server

In production with NODE_ENV=production, wildcard CORS is automatically disabled for security.

4. Network Security

  • Deploy behind a firewall or VPN
  • Use IP whitelisting if possible
  • Implement network-level rate limiting
  • Monitor for suspicious connection patterns

5. File Upload Security

The server implements several protections against malicious file uploads:

  • Maximum file size: 16MB (configurable via MAX_FILE_SIZE constant)
  • Path traversal protection via filename sanitization
  • Files stored in isolated directories
  • Real path validation to prevent directory escapes

6. Authentication Security

The server implements multiple layers of authentication security:

  • Password Hashing: bcrypt with 10 rounds
  • Timing Attack Protection: Constant-time string comparison for usernames
  • Rate Limiting: Maximum 5 failed attempts per IP per 15 minutes
  • Session Tracking: Failed attempts are tracked per client IP
  • No Credential Logging: In production mode, credentials are not logged

7. HTTP Security Headers

The server uses helmet.js to set security headers:

  • Content Security Policy (CSP)
  • HTTP Strict Transport Security (HSTS) in production
  • X-Content-Type-Options: nosniff
  • X-Frame-Options: DENY
  • X-XSS-Protection

Security Best Practices

  1. Rotate Credentials Regularly: Change authentication credentials periodically
  2. Monitor Logs: Watch for authentication failures and unusual patterns
  3. Keep Dependencies Updated: Run yarn audit regularly
  4. Limit Network Exposure: Don't expose the server directly to the internet
  5. Use Strong Passwords: Minimum 12 characters with mixed case, numbers, and symbols
  6. Enable Logging: Monitor access logs and error logs
  7. Regular Backups: Back up configuration and certificate data
  8. Principle of Least Privilege: Run the server with minimal required permissions

Vulnerability Reporting

If you discover a security vulnerability, please report it via:

  • GitHub Security Advisories
  • Email to the maintainer
  • Do NOT create public issues for security vulnerabilities

Security Audit Log

  • 2024-12: Initial security review and hardening
    • Added helmet.js for HTTP security headers
    • Implemented rate limiting for authentication
    • Added path traversal protection
    • Implemented constant-time comparison for credentials
    • Added input validation and size limits
    • Removed credential logging in production
    • Added configurable CORS origins
    • Created comprehensive security test suite

Security Considerations (Legacy)

  1. HTTPS: For production, always use HTTPS to encrypt credentials and MQTT data
  2. Authentication: Keep credentials secure and rotate them regularly
  3. Network: Ensure the server is on a trusted network or behind a firewall
  4. Environment Variables: Use environment variables for production credentials, not the generated ones

Deployment

For production deployment:

  1. Build the application:

    yarn build:server

  2. Set environment variables:

    export MQTT_EXPLORER_USERNAME=your_username
export MQTT_EXPLORER_PASSWORD=your_secure_password
export PORT=3000

  3. Start the server:

    yarn start:server

  4. Use a reverse proxy (nginx, Apache) to add HTTPS and additional security features

Troubleshooting

Debugging

Enable detailed Socket.IO connection and lifecycle debugging:

DEBUG=mqtt-explorer:socketio* yarn start:server

Available debug namespaces:

  • mqtt-explorer:socketio - General Socket.IO events and metrics
  • mqtt-explorer:socketio:connect - Client connection events
  • mqtt-explorer:socketio:disconnect - Client disconnection and cleanup
  • mqtt-explorer:socketio:subscriptions - Subscription lifecycle tracking
  • mqtt-explorer:socketio:connections - MQTT connection ownership

This will log:

  • Client connect/disconnect events
  • Subscription counts per socket
  • MQTT connection ownership tracking
  • Memory leak detection metrics (subscriptions, handlers, connections)

Example output:

mqtt-explorer:socketio:connect Client connected: abc123de
mqtt-explorer:socketio [connect] clients=1 subscriptions=8 mqttConns=0 | socket[abc123de]: subs=8 conns=0
mqtt-explorer:socketio:connections Connection my-mqtt owned by socket abc123de (total: 1)
mqtt-explorer:socketio:disconnect Client disconnected: abc123de
mqtt-explorer:socketio:subscriptions Removed 8 subscriptions for socket abc123de
mqtt-explorer:socketio [disconnect] clients=0 subscriptions=0 mqttConns=0 | socket[abc123de]: subs=0 conns=0

Authentication Fails

  1. Check the console output for the generated credentials
  2. Clear browser session storage: sessionStorage.clear() in browser console
  3. Restart the server to regenerate credentials

Connection Issues

  1. Check that the server is running: http://localhost:3000
  2. Check browser console for Socket.io connection errors
  3. Verify firewall rules allow the port

Certificate Upload Issues

In browser mode, certificates are handled differently:

  • Use the file upload button to select certificate files
  • Files are read and encoded client-side
  • Large certificate files (>16KB) will be rejected