budiCAPTCHA

A simple Budibase plugin that adds human-verification protection to forms using Cloudflare Turnstile or Google reCAPTCHA (v2 and v3).

Video Demonstration

What this plugin does

• Adds a CAPTCHA field to a Budibase form.
• Generates a CAPTCHA token and stores it in a hidden form field when the user completes the challenge.
• Prevents the form from submitting unless a valid token exists.
• Supports three providers:
  • cloudflare — Cloudflare Turnstile
  • recaptcha2 — Google reCAPTCHA v2
  • recaptcha3 — Google reCAPTCHA v3

⚠️ Security: Backend Verification Required

This component handles frontend validation only. Without server-side verification, anyone can bypass the CAPTCHA and submit your form directly via API.

You must verify the CAPTCHA token on your backend by calling your CAPTCHA provider's verification API. See BACKEND-SETUP.md for complete setup instructions.

Quick Summary

1. Get your secret/private key from Cloudflare or Google
2. Add a backend verification step in your Budibase workflow or API
3. Call verifyToken() in lib/verifyToken.js with the token, provider, and secret key
4. Only accept form submission if verification succeeds

Without this, the CAPTCHA is purely aesthetic.

Usage

1. Add the plugin to a Budibase form

• Place the budiCAPTCHA component inside a Form or Form Block component.
• Configure the Provider Name setting to choose one of:
  • Cloudflare Turnstile
  • reCAPTCHA v2
  • reCAPTCHA v3
• Provide your CAPTCHA Site Key.
• Optionally bind the token to a field using Form Field, or leave it empty to use the plugin's hidden token field.

2. Use Cloudflare Turnstile

• Set Provider Name to Cloudflare Turnstile.
• Enter your Turnstile site key in the Site Key field.
• The plugin will render the Turnstile widget in the form.
• The form will only submit after the Turnstile challenge is completed and a token is generated.

Note about Invisible mode

• If you choose Size: Invisible for Turnstile, the component automatically intercepts the closest form's submit event, calls turnstile.execute(widgetId), and resumes submission once a token is returned. This ensures invisible widgets behave correctly without extra wiring in your form logic.

Testing and integration

• This repository includes automated test helpers:
  • npm test runs a mock-based unit test harness (test/run-tests.js).
  • npm run test:integration runs a live integration runner (test/integration-run.js) — requires provider secret keys and freshly generated tokens exported as environment variables. See test/INTEGRATION.md for details.

3. Use reCAPTCHA v2

• Set Provider Name to reCAPTCHA v2.
• Enter your reCAPTCHA v2 site key in the Site Key field.
• The plugin will render the reCAPTCHA checkbox widget.
• The form will only submit after the user checks the reCAPTCHA box and a token is generated.

4. Use reCAPTCHA v3

• Set Provider Name to reCAPTCHA v3.
• Enter your reCAPTCHA v3 site key in the Site Key field.
• No user interaction is required.
• The plugin automatically executes the reCAPTCHA action and refreshes the token periodically.

General settings

• Validation allows you to add custom Budibase validation rules for the CAPTCHA field.
• Form Field can be used to bind the CAPTCHA token to an existing form field. If left empty, the plugin uses a hidden field named _bb_captcha_token.
• Alignment controls how the CAPTCHA widget is placed inside the form: left, center, or right.

Appearance settings

• Theme controls the visual theme of the CAPTCHA widget. Common options include Auto, Light, and Dark.
• Size controls widget layout. For Cloudflare Turnstile, Flexible and Invisible are supported; for reCAPTCHA v2 the plugin falls back to the normal checkbox widget.
• Action is only meaningful for reCAPTCHA v3 and is shown only when Provider Name is set to reCAPTCHA v3. It labels the reCAPTCHA action sent to Google (for example submit or login). This is optional and defaults to submit. It will be ignored if you select Cloudflare Turnstile or reCAPTCHA v2.

Styles settings

The plugin supports Budibase style controls for the component container, including:

• Padding — adjust internal spacing around the CAPTCHA widget
• Background — set the background color behind the widget
• Border — configure border style, width, and color for the CAPTCHA container

These settings let you visually match the CAPTCHA block with your form layout and branding.

Notes

• The Form Field setting is optional. When no field is provided, the plugin registers a hidden token field automatically.
• If you bind the CAPTCHA token to an existing form field, make sure that field is included in your form's validation rules.
• If the CAPTCHA script fails to load, the component displays an error message instead of a widget.

Build / development

From the plugin directory:

npm run build

For continuous rebuilds while editing:

npm run watch

If you are running Budibase in Docker, restart the Budibase service after building so the plugin bundle is reloaded.