Captcha

Spam is inevitable for any public form. Flux provides built-in, server-side verification for modern Captcha providers to keep your inbox clean without frustrating real users.

Unlike client-side only solutions, Flux handles the verification strictly on the server, ensuring that bots cannot bypass checks by simply manipulating the browser.

How it works

The protection process involves a secure handshake between your website, the Flux server, and the Captcha provider.

1. Configuration: You securely store the provider's Site Key (public) and Secret Key (private) in Flux via the TUI.
2. Rendering: When Flux serves a form, it automatically injects the Site Key and the necessary JavaScript. The client-side widget (e.g., the Turnstile widget) renders on your page.
3. Submission: When a user submits the form, the widget generates a unique response token.
4. Verification: Flux intercepts the submission, extracts the token, and securely communicates with the provider (Cloudflare or Google) using your encrypted Secret Key.
5. Decision:
   • Valid: The form processes normally, and notifications are dispatched.
   • Invalid: The submission is rejected immediately with a 400 Bad Request error.

Supported Providers

Flux currently supports the two most popular and reliable providers:

• Cloudflare Turnstile: (Recommended) A privacy-focused, smart alternative to reCAPTCHA.
• Google reCAPTCHA: The industry standard. Flux supports reCAPTCHA v2 (Checkbox).

Managing Captchas via TUI

All Captcha configurations are managed through the Dashboard menu in the SSH interface.

Accessing the Dashboard

1. SSH into your instance: ssh -p 2222 admin@localhost
2. Navigate to Infrastructure > Captcha.

You will see a table listing all your configured providers.

Creating a new configuration

1. Press n to start a new configuration.
2. Name: Give it a unique identifier (e.g., marketing-turnstile).
3. Type: Select either turnstile or recaptcha from the list.
4. Site Key: Paste the public key provided by the service.
5. Secret Key: Paste the private key.
   • Note: The secret key is masked immediately upon entry.

Modifying and deleting

• Edit: Select a provider from the list and press Enter to update keys or rename it.
• Delete: Select an item and press x. Confirm the prompt to permanently remove the configuration.
  • Warning: If you delete a provider that is currently assigned to a live form, submissions for that form may fail.

Security and encryption

Flux treats your Secret Key as a highly sensitive credential.

• Encryption at Rest: Keys are encrypted using AES-GCM before being written to the database.
• Isolation: The decrypted keys exist only in the server's RAM.
• Safety: Even if an attacker gains access to your flux.db file, they cannot recover your Captcha secrets without the Master Password.