Updated qr code events and tls server

2025-12-29 17:22:06 +02:00
parent bb9aa01519
commit 94fc899bab
17 changed files with 929 additions and 26 deletions
--- a/README.md
+++ b/README.md
@@ -17,6 +17,7 @@ A Go library and service that connects to WhatsApp and forwards messages to regi

 - **Multi-Account Support**: Connect to multiple WhatsApp accounts simultaneously
 - **Dual Client Types**: Support for both personal WhatsApp (whatsmeow) and WhatsApp Business API
+- **QR Code Pairing**: Browser-based QR code display for easy device pairing with PNG image endpoint
 - **Webhook Integration**: Register multiple webhooks to receive WhatsApp messages
 - **Two-Way Communication**: Webhooks can respond with messages to send back to WhatsApp
 - **Instance/Config Level Hooks**: Global hooks that receive all messages from all accounts
@@ -24,6 +25,7 @@ A Go library and service that connects to WhatsApp and forwards messages to regi
 - **CLI Management**: Command-line tool for managing accounts and hooks
 - **Structured Logging**: JSON-based logging with configurable log levels
 - **Authentication**: HTTP Basic Auth and API key authentication for server endpoints
+- **HTTPS/TLS Support**: Three certificate modes - self-signed, custom certificates, and Let's Encrypt autocert
 - **Event Logging**: Optional event persistence to file, SQLite, or PostgreSQL
 - **Library Mode**: Use WhatsHooked as a Go library in your own applications
 - **Flexible Handlers**: Mount individual HTTP handlers in custom servers
@@ -65,6 +67,46 @@ make build
 ./bin/whatshook-server -config config.json
 ```

+## Pairing WhatsApp Accounts
+
+When using personal WhatsApp accounts (whatsmeow), you'll need to pair the device on first launch. The QR code will be displayed in two ways:
+
+### Terminal Display
+The QR code is shown as ASCII art directly in the terminal:
+```
+========================================
+WhatsApp QR Code for account: personal
+Phone: +1234567890
+========================================
+Scan this QR code with WhatsApp on your phone:
+
+[ASCII QR Code displayed here]
+
+Or open in browser: http://localhost:8080/api/qr/personal
+========================================
+```
+
+### Browser Display
+For easier scanning, open the provided URL in your browser to view a larger PNG image:
+- URL format: `http://localhost:8080/api/qr/{account_id}`
+- No authentication required for this endpoint
+- The QR code updates automatically when a new code is generated
+
+### Webhook Events
+The QR code URL is also included in the `whatsapp.qr.code` event:
+```json
+{
+  "type": "whatsapp.qr.code",
+  "data": {
+    "account_id": "personal",
+    "qr_code": "2@...",
+    "qr_url": "http://localhost:8080/api/qr/personal"
+  }
+}
+```
+
+This allows your webhooks to programmatically display or forward QR codes for remote device pairing.
+
 ## Architecture

 The project uses an event-driven architecture with the following packages:
@@ -312,6 +354,18 @@ Create a `config.json` file based on the example:
 cp config.example.json config.json
 ```

+Or use one of the HTTPS examples:
+```bash
+# Self-signed certificate (development)
+cp config.https-self-signed.example.json config.json
+
+# Custom certificate (production)
+cp config.https-custom.example.json config.json
+
+# Let's Encrypt autocert (production)
+cp config.https-letsencrypt.example.json config.json
+```
+
 Edit the configuration file to add your WhatsApp accounts and webhooks:

 ```json
@@ -396,6 +450,168 @@ Edit the configuration file to add your WhatsApp accounts and webhooks:
 - `events`: List of event types to subscribe to (optional, defaults to all)
 - `description`: Optional description

+### HTTPS/TLS Configuration
+
+WhatsHooked supports HTTPS with three certificate modes for secure connections:
+
+#### 1. Self-Signed Certificates (Development/Testing)
+
+Automatically generates and manages self-signed certificates. Ideal for development and testing environments.
+
+```json
+{
+  "server": {
+    "host": "localhost",
+    "port": 8443,
+    "tls": {
+      "enabled": true,
+      "mode": "self-signed",
+      "cert_dir": "./data/certs"
+    }
+  }
+}
+```
+
+Or programmatically:
+```go
+wh, err := whatshooked.New(
+    whatshooked.WithServer("0.0.0.0", 8443),
+    whatshooked.WithSelfSignedTLS("./data/certs"),
+)
+```
+
+**Features:**
+- Automatically generates certificates on first run
+- Certificates valid for 1 year
+- Auto-renewal when expiring within 30 days
+- Supports both IP addresses and hostnames as SANs
+- No external dependencies
+
+**Note:** Browsers will show security warnings for self-signed certificates. This is normal and expected for development environments.
+
+#### 2. Custom Certificates (Production)
+
+Use your own certificate files from a trusted Certificate Authority (CA) or an existing certificate.
+
+```json
+{
+  "server": {
+    "host": "0.0.0.0",
+    "port": 8443,
+    "tls": {
+      "enabled": true,
+      "mode": "custom",
+      "cert_file": "/etc/ssl/certs/myserver.crt",
+      "key_file": "/etc/ssl/private/myserver.key"
+    }
+  }
+}
+```
+
+Or programmatically:
+```go
+wh, err := whatshooked.New(
+    whatshooked.WithServer("0.0.0.0", 8443),
+    whatshooked.WithCustomTLS("/etc/ssl/certs/myserver.crt", "/etc/ssl/private/myserver.key"),
+)
+```
+
+**Features:**
+- Use certificates from any CA (Let's Encrypt, DigiCert, etc.)
+- Full control over certificate lifecycle
+- Validates certificate files on startup
+- Supports PKCS1, PKCS8, and EC private keys
+
+#### 3. Let's Encrypt with Autocert (Production)
+
+Automatically obtains and renews SSL certificates from Let's Encrypt. Best for production deployments with a registered domain.
+
+```json
+{
+  "server": {
+    "host": "0.0.0.0",
+    "port": 443,
+    "tls": {
+      "enabled": true,
+      "mode": "autocert",
+      "domain": "whatshooked.example.com",
+      "email": "admin@example.com",
+      "cache_dir": "./data/autocert",
+      "production": true
+    }
+  }
+}
+```
+
+Or programmatically:
+```go
+wh, err := whatshooked.New(
+    whatshooked.WithServer("0.0.0.0", 443),
+    whatshooked.WithAutocertTLS("whatshooked.example.com", "admin@example.com", true),
+)
+```
+
+**Features:**
+- Automatic certificate provisioning from Let's Encrypt
+- Automatic certificate renewal before expiration
+- Fully managed - no manual intervention required
+- Automatically starts HTTP challenge server on port 80 (when using port 443)
+- Production and staging modes available
+
+**Requirements:**
+- Server must be publicly accessible
+- Port 443 (HTTPS) must be open
+- Port 80 (HTTP) must be open for ACME challenges
+- Valid domain name pointing to your server
+- Email address for Let's Encrypt notifications
+
+**Important Notes:**
+- Set `production: false` for testing to use Let's Encrypt staging environment (avoids rate limits)
+- Set `production: true` for production deployments to get trusted certificates
+- Ensure your domain's DNS A/AAAA record points to your server's IP
+- Let's Encrypt has rate limits: 50 certificates per domain per week
+
+#### TLS Configuration Reference
+
+All TLS configuration options:
+
+```json
+{
+  "server": {
+    "tls": {
+      "enabled": true,              // Enable HTTPS (default: false)
+      "mode": "self-signed",        // Mode: "self-signed", "custom", or "autocert" (required if enabled)
+
+      // Self-signed mode options
+      "cert_dir": "./data/certs",   // Directory for generated certificates (default: ./data/certs)
+
+      // Custom mode options
+      "cert_file": "/path/to/cert", // Path to certificate file (required for custom mode)
+      "key_file": "/path/to/key",   // Path to private key file (required for custom mode)
+
+      // Autocert mode options
+      "domain": "example.com",      // Domain name (required for autocert mode)
+      "email": "admin@example.com", // Email for Let's Encrypt notifications (optional)
+      "cache_dir": "./data/autocert", // Cache directory for certificates (default: ./data/autocert)
+      "production": true            // Use Let's Encrypt production (default: false/staging)
+    }
+  }
+}
+```
+
+#### Switching Between HTTP and HTTPS
+
+To disable HTTPS and use HTTP, set `enabled: false` or omit the `tls` section entirely:
+
+```json
+{
+  "server": {
+    "host": "localhost",
+    "port": 8080
+  }
+}
+```
+
 ### Server Authentication

 The server supports two authentication methods to protect API endpoints: