{"id":39169921,"url":"https://github.com/dog-broad/keybridge-server","last_synced_at":"2026-01-17T22:20:05.217Z","repository":{"id":332328123,"uuid":"1112040728","full_name":"dog-broad/keybridge-server","owner":"dog-broad","description":"Secure WebSocket server for remote keyboard control with AES-256-GCM encryption,  token-based authentication, and QR code pairing. Control your computer's keyboard  from any mobile device over WiFi.","archived":false,"fork":false,"pushed_at":"2025-12-08T05:15:33.000Z","size":51,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-13T13:53:32.241Z","etag":null,"topics":["aes-encryption","automation","keyboard-control","pynput","python","qr-code","remote-control","security","websocket","websocket-server"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dog-broad.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-08T04:15:23.000Z","updated_at":"2025-12-08T05:15:37.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dog-broad/keybridge-server","commit_stats":null,"previous_names":["dog-broad/keybridge-server"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/dog-broad/keybridge-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dog-broad%2Fkeybridge-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dog-broad%2Fkeybridge-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dog-broad%2Fkeybridge-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dog-broad%2Fkeybridge-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dog-broad","download_url":"https://codeload.github.com/dog-broad/keybridge-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dog-broad%2Fkeybridge-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28519966,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T22:11:28.393Z","status":"ssl_error","status_checked_at":"2026-01-17T22:11:27.841Z","response_time":85,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aes-encryption","automation","keyboard-control","pynput","python","qr-code","remote-control","security","websocket","websocket-server"],"created_at":"2026-01-17T22:20:04.500Z","updated_at":"2026-01-17T22:20:05.202Z","avatar_url":"https://github.com/dog-broad.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# KeyBridge Server\n\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)\n[![Python](https://img.shields.io/badge/Python-3.8+-blue.svg)](https://www.python.org/)\n[![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey)](https://github.com/dog-broad/keybridge-server)\n\nA secure WebSocket server that receives keyboard input from mobile devices and simulates typing on the host computer. Features end-to-end encryption and token-based authentication.\n\n---\n\n### 📱 **This server requires the KeyBridge Android App**\n\n**[➡️ Get KeyBridge Android App](https://github.com/dog-broad/KeyBridge)**\n\nBoth components work together to provide secure remote keyboard control.\n\n---\n\n\u003c/div\u003e\n\n## Features\n\n- **Secure WebSocket Server** for real-time communication\n- **AES-256-GCM Encryption** for all message traffic\n- **Token-based Authentication** with QR code setup\n- **Rate Limiting** to prevent abuse\n- **Keyboard Simulation** using pynput\n- **Comprehensive Logging** system\n- **JSON-based Protocol** with acknowledgment support\n- **Connection Management** with session tracking and keep-alive\n- **QR Code Generation** for easy mobile pairing\n\n## Requirements\n\n- Python 3.8 or higher\n- Windows 10/11 (or Linux/macOS with pynput support)\n\n## Setup\n\n1. Create and activate virtual environment:\n```bash\n# Create virtual environment\npython -m venv venv\n\n# Activate virtual environment (Windows)\n.\\venv\\Scripts\\activate\n\n# Activate virtual environment (Linux/macOS)\nsource venv/bin/activate\n```\n\n2. Install dependencies:\n```bash\npip install -r requirements.txt\n```\n\n3. Run the server:\n```bash\npython src/main.py\n```\n\nThe server will start and display a QR code containing encrypted connection data. Scan this with the mobile app to establish a secure connection.\n\n## Security Features\n\n### Encryption\n- **AES-256-GCM** symmetric encryption for all messages after authentication\n- **PBKDF2** key derivation with SHA256 and 100,000 iterations\n- Unique nonce for each encrypted message\n\n### Authentication\n- **Token-based** authentication with expiration\n- Maximum authentication attempts to prevent brute force\n- Session ID tracking for connection management\n\n### Rate Limiting\n- Configurable request limits per minute per connection\n- Automatic rejection of excessive requests\n\n### Configuration\nSecurity settings can be modified via environment variables in `src/.env`:\n```bash\n# Security Configuration\nSECRET_KEY=your-strong-random-secret-key-here  # REQUIRED: Change from default!\nENABLE_AUTH=true\nTOKEN_EXPIRY=60\nMAX_AUTH_ATTEMPTS=3\nRATE_LIMIT=300\nENABLE_ENCRYPTION=true\n```\n\n**⚠️ SECURITY WARNING**: The default secret key is for development only. **You must set a strong `SECRET_KEY` in production!** See [SECURITY.md](SECURITY.md) for details.\n\n## Message Protocol\n\nMessages are sent in JSON format with the following command types:\n\n### Type Text\n```json\n{\n    \"command\": \"type\",\n    \"text\": \"Hello, World!\"\n}\n```\n\n### Press Single Key\n```json\n{\n    \"command\": \"key_press\",\n    \"key\": \"backspace\"\n}\n```\n\n### Release Single Key\n```json\n{\n    \"command\": \"key_release\",\n    \"key\": \"shift\"\n}\n```\n\n### Key Combination\n```json\n{\n    \"command\": \"key_combo\",\n    \"keys\": [\"ctrl\", \"c\"]\n}\n```\n\n### Hotkey\n```json\n{\n    \"command\": \"hotkey\",\n    \"keys\": [\"ctrl\", \"alt\", \"delete\"]\n}\n```\n\n### Keep-Alive Ping\n```json\n{\n    \"command\": \"ping\",\n    \"timestamp\": 1701234567890\n}\n```\n\n## Supported Keys\n\nThe server supports the following special keys:\n\n### Navigation Keys\n- `backspace`, `tab`, `enter`, `space`\n- `esc`, `escape`\n\n### Modifier Keys\n- `shift`, `ctrl`, `alt`\n- `cmd`, `command`, `windows`, `win`\n\n### Arrow Keys\n- `up`, `down`, `left`, `right`\n\n### Function Keys\n- `f1` through `f12`\n\n### Extended Navigation\n- `home`, `end`, `page_up`, `page_down`\n- `insert`, `delete`\n\n### System Keys\n- `caps_lock`, `num_lock`, `scroll_lock`\n- `print_screen`, `prtsc`, `prtscr`\n- `pause`, `break`\n- `menu`, `apps`\n\n### Media Keys\n- `media_play_pause`, `media_next`, `media_previous`\n- `media_volume_up`, `media_volume_down`, `media_volume_mute`\n\n## Response Format\n\nAll commands return a JSON response:\n\n### Success Response\n```json\n{\n    \"status\": \"success\",\n    \"message\": \"Successfully typed text: Hello, World!\"\n}\n```\n\n### Error Response\n```json\n{\n    \"status\": \"error\",\n    \"message\": \"Error description\"\n}\n```\n\n### Response with Acknowledgment\n```json\n{\n    \"status\": \"success\",\n    \"message\": \"Successfully pressed key: ctrl\",\n    \"message_id\": \"uuid-here\",\n    \"requires_ack\": true\n}\n```\n\n## Project Structure\n\n```\nkeybridge-server/\n├── src/\n│   ├── main.py                    # Main server script\n│   ├── config.py                  # Configuration settings\n│   └── utils/\n│       ├── __init__.py\n│       ├── commands.py            # Command definitions and validation\n│       ├── connection_manager.py  # WebSocket connection management\n│       ├── keyboard_controller.py # Keyboard simulation controller\n│       ├── logger.py              # Logging configuration\n│       ├── message_handler.py     # Message parsing and routing\n│       ├── qr_utils.py            # QR code generation utilities\n│       └── security.py            # Encryption and authentication\n├── logs/                          # Log files directory\n├── connection_qr.png              # Generated QR code image\n├── requirements.txt               # Python dependencies\n├── LICENSE                        # Apache License 2.0\n├── NOTICE                         # Third-party notices\n└── README.md                      # This file\n```\n\n## Configuration\n\n### Server Settings (config.py)\n```python\nSERVER_CONFIG = {\n    'host': '0.0.0.0',           # Listen on all interfaces\n    'port': 8765,                 # WebSocket port\n    'ping_interval': 20,          # Ping every 20 seconds\n    'ping_timeout': 20,           # Wait 20 seconds for pong\n    'idle_timeout': 600,          # Close idle connections after 10 min\n    'max_connections': 10,        # Maximum concurrent connections\n}\n```\n\n### Performance Settings\n```python\nPERFORMANCE_CONFIG = {\n    'enable_compression': True,\n    'max_message_size': 1024,     # Max message size in bytes\n    'enable_metrics': True,\n}\n```\n\n## Troubleshooting\n\n### Server Won't Start\n- Check if port 8765 is already in use\n- Ensure Python 3.8+ is installed\n- Verify all dependencies are installed\n\n### Keys Not Working\n- Run the server with administrator privileges\n- Check if another app is capturing keyboard input\n- Verify the key name matches supported keys list\n\n### Connection Issues\n- Ensure firewall allows port 8765\n- Check both devices are on the same network\n- Regenerate QR code if token has expired\n\n### Encryption Errors\n- Verify same encryption key on server and client\n- Check system time synchronization\n- Enable debug logging to see detailed errors\n\n## Development\n\n### Git Workflow\n\n1. Create a new branch for features:\n```bash\ngit checkout -b feature/your-feature-name\n```\n\n2. Make your changes and commit:\n```bash\ngit add .\ngit commit -m \"Description of changes\"\n```\n\n3. Push changes:\n```bash\ngit push origin feature/your-feature-name\n```\n\n### Running Tests\n```bash\npython -m pytest tests/\n```\n\n### Versioning\n\nThis project follows [Semantic Versioning](https://semver.org/).\n\n## License\n\nApache License 2.0\n\nSee the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdog-broad%2Fkeybridge-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdog-broad%2Fkeybridge-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdog-broad%2Fkeybridge-server/lists"}