Privacy CAPTCHA for Cap

FAQ

Is this an official Cap plugin?

No. Cap is an independent open-source project by tiagozip (https://trycap.dev/), licensed under Apache-2.0. This plugin is an unofficial third-party integration and is not affiliated with or endorsed by the Cap project. We reference the “Cap” name only to indicate which software this plugin works with.

Where do I get a Cap endpoint, site key and secret?

You provision those in your self-hosted Cap server. See the Cap documentation at https://trycap.dev/.

Where is the WASM loaded from?

By default: from the copy bundled inside this plugin at wp-content/plugins/privacy-captcha-for-cap/assets/wasm/cap_wasm_bg.wasm. You can optionally switch to your own Cap server’s /assets/cap_wasm_bg.wasm endpoint under Settings → Privacy CAPTCHA for Cap → Privacy. Either way the file is served from your own infrastructure — no third-party CDN is contacted.

Why is a `.wasm` file bundled, and where does it come from?

The bundled assets/wasm/cap_wasm_bg.wasm is the WebAssembly module the Cap widget uses to run the proof-of-work challenge in the visitor’s browser. Bundling it locally is the privacy-friendly default: it means no third-party CDN (jsdelivr) is contacted at page load, so visitor IPs are never shared (DSGVO/GDPR-clean).

It is the unmodified upstream file from the @cap.js/wasm npm package (Apache-2.0), part of the open-source Cap project. The plugin does not alter it. Its source and build live in the Cap repository at https://github.com/tiagozip/cap, and the vendoring step is reproducible via scripts/build-assets.mjs (bun run build), which copies the file verbatim and bun run build:check verifies it matches upstream.

Can I store the secret outside the database?

Yes. Define CAP_CAPTCHA_SECRET_KEY in wp-config.php and the plugin will use it instead of the value saved in wp_options.

What is “fail-open” mode?

When enabled, the plugin lets submissions through if the Cap server is unreachable. Off by default — only turn it on if temporary outages must not block legitimate users (logins, checkouts). It applies only when Cap genuinely can’t be reached; a CAPTCHA the server actively rejects is always blocked. You can set fail-open per form (e.g. open for logins, closed for contact forms) under the global toggle, and any submission accepted this way is flagged for review (Gravity Forms entries, WooCommerce orders, comments, and new users get a cap_captcha_fail_open marker; orders also get a note).

Does the bundled `cap-widget` script make any external requests?

No third-party CDN requests. All widget assets are bundled and served from this plugin, including the pako decompression library (assets/js/vendor/pako_inflate.min.js), which older browsers without the native DecompressionStream API load locally instead of from jsdelivr. The only network requests the widget makes are to your own Cap endpoint to fetch and verify challenges.

Can I turn protection on or off per form in code?

Yes. Every surface passes through the cap_captcha_protect filter — ($enabled, $context) returning a boolean — before the widget renders and before a submission is verified. For example, to skip the CAPTCHA for logged-in users everywhere: add_filter('cap_captcha_protect', fn($on, $ctx) => is_user_logged_in() ? false : $on, 10, 2);. There is also a per-surface filter, e.g. cap_captcha_protect_woocommerce_login. Context ids: gravity_forms, contact_form_7, comments, login, registration, woocommerce_checkout, woocommerce_login, woocommerce_registration, woocommerce_lost_password.

Can I keep the CAPTCHA off a specific Contact Form 7 or Gravity Forms form?

Yes — useful for legally required or accessibility-sensitive forms. For Contact Form 7, set the mode to Manual (Settings → Form placement) and add the [cap_captcha] tag only to the forms you want protected; or, in Automatic mode, add cap_captcha: off to a form’s Additional Settings to skip just that one. For Gravity Forms, each form has a Privacy CAPTCHA setting (Default / Always / Never) so you can exclude individual forms even when “protect all” is on.

Are there developer hooks / filters?

Yes. The main ones:

• cap_captcha_protect — master gate for every surface: ($enabled, $context) returning a boolean. Runs before the widget renders and before a submission is verified.
• cap_captcha_protect_{context} — per-surface gate, e.g. cap_captcha_protect_woocommerce_login.
• cap_captcha_fail_open — ($open, $context) the resolved fail-open decision for a surface; plus a cap_captcha_fail_open_pass action when a submission is accepted via fail-open.
• cap_captcha_widget_src, cap_captcha_floating_src, cap_captcha_programmatic_src, cap_captcha_style_src — override the script/style URLs (return '' for the style to disable bundled CSS).
• cap_captcha_wasm_url, cap_captcha_pako_url — override the WASM / pako URLs (default to the bundled copies).
• cap_captcha_i18n — override the widget’s data-cap-i18n-* strings.
• cap_captcha_floating_button_classes, cap_captcha_floating_position, cap_captcha_floating_autosubmit_src — floating-mode tweaks.
• cap_captcha_display_mode — override the resolved display mode for a specific Gravity Forms field.

The full, annotated list with examples is in README.md.