• Secure WebSocket Server for real-time communication
• AES-256-GCM Encryption for all message traffic
• Token-based Authentication with QR code setup
• Rate Limiting to prevent abuse
• Keyboard Simulation using pynput
• Comprehensive Logging system
• JSON-based Protocol with acknowledgment support
• Connection Management with session tracking and keep-alive
• QR Code Generation for easy mobile pairing

• Python 3.8 or higher
• Windows 10/11 (or Linux/macOS with pynput support)

1. Create and activate virtual environment:

# Create virtual environment
python -m venv venv

# Activate virtual environment (Windows)
.\venv\Scripts\activate

# Activate virtual environment (Linux/macOS)
source venv/bin/activate

2. Install dependencies:

pip install -r requirements.txt

3. Run the server:

python src/main.py

The server will start and display a QR code containing encrypted connection data. Scan this with the mobile app to establish a secure connection.

• AES-256-GCM symmetric encryption for all messages after authentication
• PBKDF2 key derivation with SHA256 and 100,000 iterations
• Unique nonce for each encrypted message

• Token-based authentication with expiration
• Maximum authentication attempts to prevent brute force
• Session ID tracking for connection management

• Configurable request limits per minute per connection
• Automatic rejection of excessive requests

Security settings can be modified via environment variables in src/.env:

# Security Configuration
SECRET_KEY=your-strong-random-secret-key-here  # REQUIRED: Change from default!
ENABLE_AUTH=true
TOKEN_EXPIRY=60
MAX_AUTH_ATTEMPTS=3
RATE_LIMIT=300
ENABLE_ENCRYPTION=true

⚠️ SECURITY WARNING: The default secret key is for development only. You must set a strong SECRET_KEY in production! See SECURITY.md for details.

Messages are sent in JSON format with the following command types:

{
    "command": "type",
    "text": "Hello, World!"
}

{
    "command": "key_press",
    "key": "backspace"
}

{
    "command": "key_release",
    "key": "shift"
}

{
    "command": "key_combo",
    "keys": ["ctrl", "c"]
}

{
    "command": "hotkey",
    "keys": ["ctrl", "alt", "delete"]
}

{
    "command": "ping",
    "timestamp": 1701234567890
}

The server supports the following special keys:

• backspace, tab, enter, space
• esc, escape

• shift, ctrl, alt
• cmd, command, windows, win

• up, down, left, right

• f1 through f12

• home, end, page_up, page_down
• insert, delete

• caps_lock, num_lock, scroll_lock
• print_screen, prtsc, prtscr
• pause, break
• menu, apps

• media_play_pause, media_next, media_previous
• media_volume_up, media_volume_down, media_volume_mute

All commands return a JSON response:

{
    "status": "success",
    "message": "Successfully typed text: Hello, World!"
}

{
    "status": "error",
    "message": "Error description"
}

{
    "status": "success",
    "message": "Successfully pressed key: ctrl",
    "message_id": "uuid-here",
    "requires_ack": true
}

keybridge-server/
├── src/
│   ├── main.py                    # Main server script
│   ├── config.py                  # Configuration settings
│   └── utils/
│       ├── __init__.py
│       ├── commands.py            # Command definitions and validation
│       ├── connection_manager.py  # WebSocket connection management
│       ├── keyboard_controller.py # Keyboard simulation controller
│       ├── logger.py              # Logging configuration
│       ├── message_handler.py     # Message parsing and routing
│       ├── qr_utils.py            # QR code generation utilities
│       └── security.py            # Encryption and authentication
├── logs/                          # Log files directory
├── connection_qr.png              # Generated QR code image
├── requirements.txt               # Python dependencies
├── LICENSE                        # Apache License 2.0
├── NOTICE                         # Third-party notices
└── README.md                      # This file

SERVER_CONFIG = {
    'host': '0.0.0.0',           # Listen on all interfaces
    'port': 8765,                 # WebSocket port
    'ping_interval': 20,          # Ping every 20 seconds
    'ping_timeout': 20,           # Wait 20 seconds for pong
    'idle_timeout': 600,          # Close idle connections after 10 min
    'max_connections': 10,        # Maximum concurrent connections
}

PERFORMANCE_CONFIG = {
    'enable_compression': True,
    'max_message_size': 1024,     # Max message size in bytes
    'enable_metrics': True,
}

• Check if port 8765 is already in use
• Ensure Python 3.8+ is installed
• Verify all dependencies are installed

• Run the server with administrator privileges
• Check if another app is capturing keyboard input
• Verify the key name matches supported keys list

• Ensure firewall allows port 8765
• Check both devices are on the same network
• Regenerate QR code if token has expired

• Verify same encryption key on server and client
• Check system time synchronization
• Enable debug logging to see detailed errors

1. Create a new branch for features:

git checkout -b feature/your-feature-name

2. Make your changes and commit:

git add .
git commit -m "Description of changes"

3. Push changes:

git push origin feature/your-feature-name

python -m pytest tests/

This project follows Semantic Versioning.

Apache License 2.0

See the LICENSE file for details.