docs are cool

doc/HTTPS_SETUP.md

@@ -0,0 +1,166 @@
+# HTTPS Webhook Setup Guide
+
+## Quick Start (Self-Signed Certificate for Testing)
+
+### 1. Generate Certificate
+```powershell
+python generate_cert.py
+```
+
+This creates `cert.pem` and `key.pem` files.
+
+### 1.5. Convert to P7B for Square (Required for Square Webhooks)
+```powershell
+python convert_to_p7b.py
+```
+
+This creates `cert.p7b` which Square needs for webhook signature verification.
+Upload this P7B file to Square Developer Dashboard → Webhooks → Manage Notification Settings.
+
+### 2. Run Server with HTTPS
+
+#### Option A: HTTPS for webhook only (recommended for development)
+```powershell
+python src/test_server.py --ssl-cert cert.pem --ssl-key key.pem --hook-port 8443 --hook-ssl-only
+```
+- Main server: `http://localhost:7432/` (HTTP)
+- Webhook: `https://localhost:8443/hook` (HTTPS)
+
+#### Option B: HTTPS for everything
+```powershell
+python src/test_server.py --ssl-cert cert.pem --ssl-key key.pem --hook-port 8443
+```
+- Main server: `https://localhost:7432/` (HTTPS)
+- Webhook: `https://localhost:8443/hook` (HTTPS)
+
+#### Option C: Single port with HTTPS
+```powershell
+python src/test_server.py --ssl-cert cert.pem --ssl-key key.pem
+```
+- Everything on: `https://localhost:7432/`
+
+### 3. Test the Webhook
+
+Update `src/test_webhook.py` to use HTTPS:
+```python
+url = "https://localhost:8443/hook"
+```
+
+Then run:
+```powershell
+python src/test_webhook.py
+```
+
+## Production Setup (with Real Certificate)
+
+### Option 1: Let's Encrypt (Free, Recommended)
+
+On Linux/WSL:
+```bash
+# Install certbot
+sudo apt-get install certbot
+
+# Generate certificate (replace yourdomain.com)
+sudo certbot certonly --standalone -d yourdomain.com
+
+# Certificates will be at:
+# /etc/letsencrypt/live/yourdomain.com/fullchain.pem
+# /etc/letsencrypt/live/yourdomain.com/privkey.pem
+
+# Run server
+python src/test_server.py \
+  --ssl-cert /etc/letsencrypt/live/yourdomain.com/fullchain.pem \
+  --ssl-key /etc/letsencrypt/live/yourdomain.com/privkey.pem \
+  --host 0.0.0.0 \
+  --hook-port 443 \
+  --hook-ssl-only
+```
+
+### Option 2: Reverse Proxy (nginx/Caddy)
+
+Run studspider on HTTP internally, use nginx/Caddy for HTTPS:
+
+```nginx
+# nginx config
+server {
+    listen 443 ssl;
+    server_name yourdomain.com;
+    
+    ssl_certificate /path/to/cert.pem;
+    ssl_certificate_key /path/to/key.pem;
+    
+    location /hook {
+        proxy_pass http://localhost:7432/hook;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+}
+```
+
+Then run studspider normally:
+```powershell
+python src/test_server.py
+```
+
+## Troubleshooting
+
+### "OpenSSL not found" Error
+- **Windows**: Install from https://slproweb.com/products/Win32OpenSSL.html
+- **Alternative**: Use Git Bash or WSL which include OpenSSL
+
+### Self-Signed Certificate Warnings
+- Normal for development
+- Use `--insecure` flag with curl/tools for testing
+- For production, get a proper certificate from Let's Encrypt
+
+### Port 443 Already in Use
+- Use a different port like 8443
+- Or stop the service using port 443
+
+### Certificate File Not Found
+- Use absolute paths: `--ssl-cert C:\path\to\cert.pem`
+- Or run from the directory containing the certificates
+
+## Square Webhook Configuration
+
+### Certificate Requirements
+Square requires a **P7B (PKCS#7)** certificate file for webhook signature verification.
+
+### Setup Steps:
+
+1. **Generate your certificate** (if you haven't already):
+   ```powershell
+   python generate_cert.py
+   ```
+
+2. **Convert PEM to P7B format**:
+   ```powershell
+   # Basic conversion
+   python convert_to_p7b.py
+   
+   # With intermediate certificates (production)
+   python convert_to_p7b.py --cert fullchain.pem --chain intermediate.pem --output square.p7b
+   ```
+
+3. **Upload to Square Dashboard**:
+   - Go to https://developer.squareup.com/
+   - Navigate to your application
+   - Click on "Webhooks"
+   - Click "Manage Notification Settings"
+   - Upload the `cert.p7b` file
+   - Square will use this to verify webhook signatures
+
+4. **Configure webhook URL in Square**:
+   - Use your public HTTPS URL: `https://yourdomain.com:8443/hook`
+   - Square requires valid SSL (not self-signed for production)
+
+### Testing with Square Webhooks:
+
+When setting up webhooks in Square Dashboard:
+1. Use your HTTPS URL: `https://yourdomain.com:8443/hook`
+2. Square requires valid SSL (not self-signed)
+3. Consider using ngrok for local testing:
+   ```powershell
+   ngrok http 8443
+   ```
+   Then use the ngrok HTTPS URL in Square Dashboard