ALTCHA for Gravity Forms

Invisible ALTCHA proof-of-work spam protection for Gravity Forms. No user interaction, no third-party requests, no captcha puzzles — every submission carries a signed PBKDF2 proof that the browser quietly solved in the background.

• MIT-licensed end to end (altcha-org/altcha for PHP, altcha widget for JS, this plugin for the glue).
• No external API calls — challenges are issued and verified by your own WordPress install.
• No license keys, no quotas.
• Drop-in: enables itself automatically for every Gravity Form.

Requirements

• WordPress 6.0+
• PHP 8.2+
• Gravity Forms 2.5+

Installation

Composer (Bedrock-style sites)

The plugin is published through generoi/packagist. With that repository configured in your root composer.json:

composer require generoi/gravityforms-altcha
wp plugin activate gravityforms-altcha

Manual

1. Download the latest gravityforms-altcha.zip from Releases.
2. Upload to wp-content/plugins/ (or via Plugins → Add New → Upload).
3. Activate.

How it works

1. Form render — the plugin injects a hidden <altcha-widget> web component above the submit button on every Gravity Form.
2. Browser-side proof-of-work — the widget fetches a fresh challenge from /wp-json/genero/gravityforms-altcha/v1/challenge (signed with a per-site HMAC secret) and brute-forces a PBKDF2/SHA-256 derived-key match.
3. Submission — the widget writes the solution into a hidden altcha field that Gravity Forms posts back with the rest of the form.
4. Server-side verification — gform_validation decodes the payload, reconstructs the challenge, and runs altcha-org/altcha::verifySolution(). On failure the submission is rejected with a generic error message.

There is no admin UI, no per-form configuration, and no settings page — everything customisable lives behind WordPress filters.

Filters

genero/gravityforms_altcha/should_protect

Skip protection on specific forms:

add_filter('genero/gravityforms_altcha/should_protect', function (bool $protect, array $form): bool {
    // Don't run ALTCHA on internal preview-only forms.
    if (in_array((int) $form['id'], [42, 43], true)) {
        return false;
    }
    return $protect;
}, 10, 2);

genero/gravityforms_altcha/hmac_key

Use an externally-managed secret (for example a dedicated vault entry shared across a fleet of sites):

add_filter('genero/gravityforms_altcha/hmac_key', fn () => getenv('ALTCHA_HMAC_KEY') ?: null);

Returning null falls back to the auto-generated gravityforms_altcha_hmac_key option.

genero/gravityforms_altcha/error_message

Localise or rewrite the validation error:

add_filter('genero/gravityforms_altcha/error_message', fn () => __('Spam check failed. Please reload and try again.', 'your-textdomain'));

Development

composer install
npm install
npm run build       # outputs build/widget.js
composer test       # PHPUnit suite, no WordPress dependency
composer lint:fix   # Pint

License

MIT — see LICENSE.

Bundles the MIT-licensed altcha-org/altcha PHP library and the MIT-licensed altcha widget. Neither ships with this repository — both are installed through Composer and npm respectively.