Merge pull request olivierlambert#122 from florian-SV/feat/captcha-booking

olivierlambert · web-flow · commit 75d71aaaf139 · 2026-06-03T21:39:15.000+02:00
feat(book): add captcha system for secure booking endpoint
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -317,6 +317,104 @@ File: `src/web/mod.rs`, templates in `templates/`
 
 ---
 
+## Captcha (trycap / Cap)
+
+### What it does
+
+Protects booking endpoints against bots with a privacy-first proof-of-work CAPTCHA. The feature is **opt-in**: when no configuration is stored the booking flow works exactly as before — no widget, no server-side check. The captcha is only active on booking form pages (guest-facing), never on registration or dashboard routes.
+
+The chosen provider is [Cap](https://trycap.dev) — self-hosted, no GAFAM, no tracking, Docker-deployable. It is API-compatible with the reCAPTCHA/hCaptcha verification protocol, so switching providers in the future only requires updating `src/web/captcha.rs`.
+
+### Configuration (admin panel)
+
+Configured at `/dashboard/admin` → **Captcha** section. Four fields:
+
+| Field | Required | Description |
+|---|---|---|
+| Instance URL | Yes | Base URL of your Cap server, e.g. `https://captcha.example.com` |
+| Site key | Yes | Site key from the Cap dashboard |
+| Secret | Yes | Secret key for server-to-server verification (encrypted at rest with AES-256-GCM, same pattern as OIDC client secret) |
+| Widget script URL | No | Override the JS bundle URL. Defaults to `https://cdn.jsdelivr.net/npm/cap-widget`. Useful for air-gapped deployments. Changes take effect immediately after saving (CSP is rebuilt in memory). |
+
+Leaving all three main fields empty disables the captcha. The secret uses the keep-current pattern: leaving the password field empty on save preserves the stored value.
+
+### How it works end-to-end
+
+**GET (booking form):** The handler reads `state.captcha_config` (a `RwLock<Option<CaptchaConfig>>`). If `Some`, it passes `captcha_enabled = true`, `captcha_api_endpoint`, and `captcha_widget_url` to the template. The `<cap-widget>` element is rendered conditionally in `templates/book.html` with all i18n attributes pre-filled via the Fluent `t()` helper.
+
+**POST (booking submit):** The `BookForm` struct has a `captcha_token: Option<String>` field with `#[serde(rename = "cap-token")]` — the field name the Cap widget submits. After the CSRF check, `captcha::verify(&captcha_cfg, form.captcha_token.as_deref()).await` is called:
+- `config = None` → `Ok(())` immediately (pass-through)
+- `config = Some`, token missing/empty → `Err(())` → renders `booking_action_error.html`
+- `config = Some`, token present → POST to `<instance>/<site-key>/siteverify` with JSON `{"secret": "...", "response": "<token>"}` → parses `{"success": bool}`
+
+The verification is implemented in `src/web/captcha.rs` and applies to **3 handlers**: `handle_booking`, `handle_booking_for_user`, `handle_group_booking`. The dynamic group booking path (`username.contains('+')`) is also protected because the check happens before the branch.
+
+### Code structure
+
+| File | Role |
+|---|---|
+| `src/web/captcha.rs` | Self-contained module: `CaptchaConfig` struct, `load_captcha_config()`, `verify()`, `extract_origin()` helper, unit tests |
+| `src/web/mod.rs` | `AppState.captcha_config: RwLock<Option<CaptchaConfig>>`, `build_csp()`, `csp_middleware()`, `admin_update_captcha()` handler, wiring in the 4 GET form handlers and 3 POST booking handlers |
+| `migrations/053_captcha.sql` | Adds `captcha_instance_url`, `captcha_site_key`, `captcha_secret`, `captcha_widget_url` columns to `auth_config` |
+| `templates/admin.html` | Captcha configuration section (status badge, 4 inputs, save button) |
+| `templates/book.html` | Conditional `<cap-widget>` with all `data-cap-i18n-*` attributes |
+| `templates/base.html` | CSS custom property overrides for `cap-widget` theming |
+
+### Content-Security-Policy
+
+The CSP is **dynamic** — it is rebuilt whenever the admin saves captcha settings, without a server restart (except for the widget script URL, which controls the `script-src` domain). It is stored as a pre-built string in `AppState.csp: RwLock<String>` and applied by `csp_middleware` (an Axum `from_fn_with_state` layer).
+
+`build_csp(captcha: &Option<CaptchaConfig>) -> String` produces:
+
+**Without captcha configured:**
+```
+default-src 'self'; img-src 'self' data:; style-src 'self' 'unsafe-inline';
+script-src 'self' 'unsafe-inline';
+connect-src 'self';
+object-src 'none'; base-uri 'self'; frame-ancestors 'self'
+```
+
+**With captcha configured:**
+```
+default-src 'self'; img-src 'self' data:; style-src 'self' 'unsafe-inline';
+script-src 'self' 'unsafe-inline' 'wasm-unsafe-eval' <widget-origin>;
+worker-src blob:;
+connect-src 'self' <instance-origin> <widget-origin>;
+object-src 'none'; base-uri 'self'; frame-ancestors 'self'
+```
+
+The three extra directives and why they are needed:
+- **`'wasm-unsafe-eval'` in `script-src`** — Cap's proof-of-work solver runs as a WASM module. Without this, browsers block `WebAssembly.instantiate()` under a strict CSP. Falls back to a JS solver if blocked, but WASM is much faster.
+- **`worker-src blob:`** — The Cap widget spawns a Web Worker via a `blob:` URL to run the solver off the main thread. `worker-src` is not inherited from `script-src` in all browsers, so it must be explicit.
+- **`<widget-origin>` in `connect-src`** — The widget's JS fetches the WASM binary from the same CDN origin via `fetch()`. This is controlled by `connect-src`, not `script-src`. Both the Cap server origin (for token verification XHR) and the widget CDN origin (for WASM fetch) must be in `connect-src`.
+
+The `csp_middleware` skips setting the header if it is already present, so individual handlers can override it if needed in the future.
+
+### Translations
+
+All visible strings in the Cap widget are localised via the standard Fluent system. Keys use the `captcha-` prefix and live in each language file:
+
+Keys: `captcha-label`, `captcha-initial-state`, `captcha-verifying`, `captcha-solved`, `captcha-error`, `captcha-troubleshooting`, `captcha-wasm-disabled`, plus five `*-aria` keys for accessibility.
+
+### Styling
+
+The `<cap-widget>` custom element exposes CSS custom properties. They are overridden globally in `templates/base.html` to follow the app's existing theme variables:
+
+```css
+cap-widget {
+  --cap-background: var(--surface);
+  --cap-border-color: var(--border);
+  --cap-color: var(--text);
+  --cap-checkbox-background: var(--surface-hover);
+  --cap-spinner-color: var(--text);
+  --cap-spinner-background-color: var(--border);
+}
+```
+
+Because `--surface`, `--border`, etc. are already overridden by `html.dark { ... }` (in `base.html`) and by each preset/custom theme (via `theme_css` in `AppState`), the widget automatically adapts to dark mode and all custom themes (Nord, Dracula, Tokyo Night, etc.) with no additional CSS.
+
+---
+
 ## Known issues & TODOs
 
 ### Security
diff --git a/README.md b/README.md
@@ -194,6 +194,7 @@ Each team member's CalDAV calendars are checked for conflicts. The availability
 
 - **Credential encryption** — CalDAV and SMTP passwords encrypted at rest with AES-256-GCM; secret key auto-generated or provided via `CALRS_SECRET_KEY`
 - **Hidden password input** — passwords never echoed to the terminal
+- **Privacy-first CAPTCHA** — optional [Cap](https://trycap.dev) integration (self-hosted, proof-of-work, no GAFAM). When configured, a `<cap-widget>` is shown on all booking pages and the token is verified server-to-server before any booking is processed. Disabled by default — no widget, no network call if unconfigured
 
 ### Localization
 
@@ -368,6 +369,64 @@ calrs serve --port 3000
 
 The login page will show a "Sign in with SSO" button. With `--auto-register true`, users are created automatically on first OIDC login. Existing local users are linked by email.
 
+## Captcha setup (Cap / trycap.dev)
+
+calrs integrates [Cap](https://trycap.dev), a self-hosted proof-of-work CAPTCHA that requires no third-party service and collects no user data. The widget appears only on booking pages — never on the dashboard or registration form.
+
+**The feature is opt-in.** If you do not configure it, the booking flow works exactly as before: no widget, no network call.
+
+### 1. Deploy a Cap instance
+
+Cap is distributed as a Docker image. Minimal compose example:
+
+```yaml
+services:
+  cap:
+    image: ghcr.io/trycap/cap:latest
+    ports:
+      - "3001:3001"
+    environment:
+      CAP_SECRET: your-secret-key
+```
+
+Create a site in the Cap dashboard and note the **site key** and **secret**.
+
+### 2. Configure calrs
+
+Go to **Admin panel → Captcha** and fill in:
+
+| Field | Example | Notes |
+|---|---|---|
+| Instance URL | `https://captcha.example.com` | Base URL of your Cap server |
+| Site key | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | From the Cap dashboard |
+| Secret | `your-secret-key` | Encrypted at rest with AES-256-GCM |
+| Widget script URL | *(leave empty)* | Defaults to `https://cdn.jsdelivr.net/npm/cap-widget`. Override for air-gapped deployments. |
+
+Click **Save captcha settings**. All changes — including the widget script URL — take effect immediately, no restart required.
+
+To disable, clear the Instance URL, Site key, and Secret fields and save.
+
+### How verification works
+
+1. The guest completes the proof-of-work challenge in the browser (the Cap widget handles this automatically, with a WASM solver for speed)
+2. The widget writes the resulting token into a hidden `cap-token` form field
+3. On submit, calrs calls `POST <instance>/<site-key>/siteverify` with the token and the secret (server-to-server, never exposed to the browser)
+4. If verification fails, the guest sees the standard error page — no booking is created
+
+### Content-Security-Policy
+
+calrs sets a strict CSP on all responses. When Cap is configured, the following directives are added and updated automatically on every save:
+
+| Directive | Added value | Why |
+|---|---|---|
+| `script-src` | `'wasm-unsafe-eval' <widget-origin>` | The widget JS loads from an external origin; `wasm-unsafe-eval` allows the WASM proof-of-work solver |
+| `worker-src` | `blob:` | The widget spawns a Web Worker via a blob URL to run the solver off the main thread |
+| `connect-src` | `<instance-origin> <widget-origin>` | The browser fetches the WASM binary from the widget CDN and sends the solved token to the Cap server |
+
+When captcha is disabled, none of these directives are present — the CSP reverts to its strict baseline immediately after saving.
+
+---
+
 ## Reverse proxy
 
 calrs listens on HTTP (port 3000 by default). Use a reverse proxy for TLS termination.
diff --git a/i18n/de/main.ftl b/i18n/de/main.ftl
@@ -74,6 +74,18 @@ book-additional-guests-label = Weitere Teilnehmer
 book-additional-guests-hint = (optional, bis zu { $max })
 book-add-guest-btn = + Teilnehmer hinzufügen
 book-guest-email-placeholder = kollege@example.com
+captcha-label = Sicherheitsüberprüfung
+captcha-initial-state = Bestätigen Sie, dass Sie ein Mensch sind
+captcha-verifying = Überprüfung läuft...
+captcha-solved = Sie sind ein Mensch
+captcha-error = Fehler
+captcha-troubleshooting = Fehlerbehebung
+captcha-wasm-disabled = WASM aktivieren für deutlich schnellere Lösung
+captcha-verify-aria = Klicken Sie, um zu bestätigen, dass Sie ein Mensch sind
+captcha-verifying-aria = Überprüfung läuft, bitte warten
+captcha-verified-aria = Bestätigt
+captcha-required = Bitte bestätigen Sie, dass Sie ein Mensch sind
+captcha-error-aria = Ein Fehler ist aufgetreten, bitte versuchen Sie es erneut
 book-confirm-button = Buchung bestätigen
 
 # Shared labels used across the cancel / decline / approve / reschedule / claim flows
diff --git a/i18n/en/main.ftl b/i18n/en/main.ftl
@@ -74,6 +74,18 @@ book-additional-guests-label = Additional guests
 book-additional-guests-hint = (optional, up to { $max })
 book-add-guest-btn = + Add guest email
 book-guest-email-placeholder = colleague@example.com
+captcha-label = Security verification
+captcha-initial-state = Verify you're human
+captcha-verifying = Verifying...
+captcha-solved = You're human
+captcha-error = Error
+captcha-troubleshooting = Troubleshooting
+captcha-wasm-disabled = Enable WASM for significantly faster solving
+captcha-verify-aria = Click to verify you're a human
+captcha-verifying-aria = Verifying, please wait
+captcha-verified-aria = Verified
+captcha-required = Please verify you're human
+captcha-error-aria = An error occurred, please try again
 book-confirm-button = Confirm booking
 
 # Shared labels used across the cancel / decline / approve / reschedule / claim flows
diff --git a/i18n/es/main.ftl b/i18n/es/main.ftl
@@ -74,6 +74,18 @@ book-additional-guests-label = Invitados adicionales
 book-additional-guests-hint = (opcional, hasta { $max })
 book-add-guest-btn = + Añadir invitado
 book-guest-email-placeholder = colega@example.com
+captcha-label = Verificación de seguridad
+captcha-initial-state = Verifique que es humano
+captcha-verifying = Verificando...
+captcha-solved = Eres humano
+captcha-error = Error
+captcha-troubleshooting = Solución de problemas
+captcha-wasm-disabled = Active WASM para una resolución significativamente más rápida
+captcha-verify-aria = Haga clic para verificar que es humano
+captcha-verifying-aria = Verificando, por favor espere
+captcha-verified-aria = Verificado
+captcha-required = Por favor, verifique que es humano
+captcha-error-aria = Se ha producido un error, por favor inténtelo de nuevo
 book-confirm-button = Confirmar reserva
 
 # Shared labels used across the cancel / decline / approve / reschedule / claim flows
diff --git a/i18n/fr/main.ftl b/i18n/fr/main.ftl
@@ -74,6 +74,18 @@ book-additional-guests-label = Invités supplémentaires
 book-additional-guests-hint = (facultatif, jusqu'à { $max })
 book-add-guest-btn = + Ajouter un invité
 book-guest-email-placeholder = collegue@example.com
+captcha-label = Vérification de sécurité
+captcha-initial-state = Vérifiez que vous êtes humain
+captcha-verifying = Vérification en cours...
+captcha-solved = Vous êtes humain
+captcha-error = Erreur
+captcha-troubleshooting = Dépannage
+captcha-wasm-disabled = Activez WASM pour une résolution plus rapide
+captcha-verify-aria = Cliquez pour vérifier que vous êtes humain
+captcha-verifying-aria = Vérification en cours, veuillez patienter
+captcha-verified-aria = Vérifié
+captcha-required = Veuillez vérifier que vous êtes humain
+captcha-error-aria = Une erreur est survenue, veuillez réessayer
 book-confirm-button = Confirmer la réservation
 
 # Shared labels used across the cancel / decline / approve / reschedule / claim flows
diff --git a/i18n/it/main.ftl b/i18n/it/main.ftl
@@ -74,6 +74,18 @@ book-additional-guests-label = Ospiti aggiuntivi
 book-additional-guests-hint = (opzionale, fino a { $max })
 book-add-guest-btn = + Aggiungi ospite
 book-guest-email-placeholder = collega@example.com
+captcha-label = Verifica di sicurezza
+captcha-initial-state = Verifica di essere umano
+captcha-verifying = Verifica in corso...
+captcha-solved = Sei umano
+captcha-error = Errore
+captcha-troubleshooting = Risoluzione dei problemi
+captcha-wasm-disabled = Abilita WASM per una risoluzione significativamente più rapida
+captcha-verify-aria = Clicca per verificare di essere umano
+captcha-verifying-aria = Verifica in corso, attendere prego
+captcha-verified-aria = Verificato
+captcha-required = Verifica di essere umano
+captcha-error-aria = Si è verificato un errore, riprova
 book-confirm-button = Conferma prenotazione
 
 # Shared labels used across the cancel / decline / approve / reschedule / claim flows
diff --git a/i18n/pl/main.ftl b/i18n/pl/main.ftl
@@ -74,6 +74,18 @@ book-additional-guests-label = Dodatkowi goście
 book-additional-guests-hint = (opcjonalne, do { $max })
 book-add-guest-btn = + Dodaj gościa
 book-guest-email-placeholder = wspolpracownik@example.com
+captcha-label = Weryfikacja bezpieczeństwa
+captcha-initial-state = Potwierdź, że jesteś człowiekiem
+captcha-verifying = Weryfikacja...
+captcha-solved = Jesteś człowiekiem
+captcha-error = Błąd
+captcha-troubleshooting = Rozwiązywanie problemów
+captcha-wasm-disabled = Włącz WASM dla znacznie szybszego rozwiązywania
+captcha-verify-aria = Kliknij, aby potwierdzić, że jesteś człowiekiem
+captcha-verifying-aria = Weryfikacja, proszę czekać
+captcha-verified-aria = Zweryfikowano
+captcha-required = Proszę potwierdzić, że jesteś człowiekiem
+captcha-error-aria = Wystąpił błąd, spróbuj ponownie
 book-confirm-button = Potwierdź rezerwację
 
 # Shared labels used across the cancel / decline / approve / reschedule / claim flows
diff --git a/migrations/054_captcha.sql b/migrations/054_captcha.sql
@@ -0,0 +1,4 @@
+ALTER TABLE auth_config ADD COLUMN captcha_instance_url TEXT;
+ALTER TABLE auth_config ADD COLUMN captcha_site_key TEXT;
+ALTER TABLE auth_config ADD COLUMN captcha_secret TEXT;
+ALTER TABLE auth_config ADD COLUMN captcha_widget_url TEXT;
diff --git a/src/db.rs b/src/db.rs
@@ -231,6 +231,7 @@ pub async fn migrate(pool: &SqlitePool) -> Result<()> {
             "053_oauth2_caldav",
             include_str!("../migrations/053_oauth2_caldav.sql"),
         ),
+        ("054_captcha", include_str!("../migrations/054_captcha.sql")),
     ];
 
     let mut applied_count = 0u32;
@@ -838,7 +839,7 @@ mod tests {
             .fetch_one(&pool)
             .await
             .unwrap();
-        assert_eq!(count.0, 53, "All 53 migrations should be tracked");
+        assert_eq!(count.0, 54, "All 54 migrations should be tracked");
     }
 
     #[tokio::test]
@@ -852,7 +853,7 @@ mod tests {
             .fetch_one(&pool)
             .await
             .unwrap();
-        assert_eq!(count.0, 53, "Still 53 migrations after second run");
+        assert_eq!(count.0, 54, "Still 54 migrations after second run");
     }
 
     #[tokio::test]
diff --git a/src/web/captcha.rs b/src/web/captcha.rs
diff --git a/src/web/mod.rs b/src/web/mod.rs
diff --git a/templates/admin.html b/templates/admin.html
diff --git a/templates/base.html b/templates/base.html
diff --git a/templates/book.html b/templates/book.html
