Skip to content
RevokeGPTRevokeGPTRevokeGPT docs

WordPress plugin reference

The RevokeGPT plugin protects WordPress forms with an invisible check and verifies every response token on your server with the RevokeGPT PHP SDK. The SDK is bundled under its own namespace prefix (RevokeGPT\WP\Vendor), so it cannot clash with another plugin’s copy. You write no verification code. For a walkthrough, see the WordPress quickstart.

Plugin version: 0.1.0. It needs WordPress 6.5 or later and PHP 8.1 or later.

Install

Section titled “Install”
Terminal window
composer install
composer build            # writes dist/revokegpt (PHP 8.2 or later for the build tools)

Copy dist/revokegpt into wp-content/plugins/, activate it, then open Settings, RevokeGPT. The plugin does nothing until a site key, a secret key and an endpoint are set.

What it protects

Section titled “What it protects”
Form Setting name On by default
Login (and WooCommerce My Account login) login yes
Registration (and WooCommerce My Account registration) register yes
Lost password (and the WooCommerce form) lostpassword yes
Comments comment yes
WooCommerce checkout, classic and block, and Pay for order woocommerce no
Contact Form 7 cf7 no
WPForms wpforms no

The check runs on the server, in these actions: login, register, lostpassword, comment, cf7 and wpforms.

Not checked, because they are not forms: REST requests, application-password logins, WP-CLI, cron, pingbacks and trackbacks. A login plugin that signs users in without a password (a magic link) is not checked. Multisite site sign-up and post-password forms are not checked. Administrators replying to comments, or sending a password reset from the Users screen, are not refused.

Options

Section titled “Options”

Stored in the revokegpt_settings option, edited under Settings, RevokeGPT.

Setting Type Default Notes
site_key string empty Your public site key: rgpk_ and 20 letters and digits. An invalid value keeps the stored one.
endpoint string empty The siteverify URL of your RevokeGPT service. https: (plain http: only on localhost or 127.0.0.1), ending in /siteverify, with no username, query or fragment.
widget_origin string https://js.revokegpt.com Where the visitor’s browser loads the widget script. An origin with no path; https: (plain http: only on localhost or 127.0.0.1). Empty resets to the default.
mode enforce or monitor enforce In monitor a refusal is let through, with the reason kept. A checkout decision other than allow is also let through.
min_score number 0 to 1 0.5 The minimum token score. A request below it is refused.
forms map of booleans see the table above Which forms are protected.
fail_open_login bool false Allow login when RevokeGPT cannot be reached (a network or HTTP error). Applies to login only.
exempt_roles list of role slugs empty Signed-in users with these roles skip the comment check. Only existing roles are kept.
block_xmlrpc bool true Refuse username and password logins over XML-RPC and remove system.multicall. Application passwords keep working.
checkout_open bool true Take WooCommerce orders when RevokeGPT cannot be reached (the order gets a note and the meta _revokegpt_unchecked). Off refuses such orders.

The secret key is stored apart, in the revokegpt_secret option (autoload off). The admin field is write-only: it is never read back into a page. A blank submission keeps the stored value, and a value that is not a secret key (rgsk_) is refused, a management key included. Test connection verifies a dummy token to check the key and the endpoint.

Constants (wp-config.php)

Section titled “Constants (wp-config.php)”
Constant Effect
REVOKEGPT_SECRET_KEY The secret key. When it is set, it wins over the stored value and the admin never shows or stores it. Recommended.
REVOKEGPT_DISABLE true turns every check off. This is the way back in if you lock yourself out. The admin shows a warning while it is set. Remove it after you fix the settings. 
define( 'REVOKEGPT_SECRET_KEY', getenv( 'REVOKEGPT_SECRET_KEY' ) );
define( 'REVOKEGPT_DISABLE', true ); // only while locked out

The plugin also defines REVOKEGPT_VERSION, REVOKEGPT_FILE and REVOKEGPT_DIR for its own use.

Filters

Section titled “Filters”
Filter Default Use
revokegpt_client_ip REMOTE_ADDR Return the visitor’s address when a proxy sits in front. WordPress cannot know which proxy header to trust. A value that is not an IP address is dropped, and no address is sent.
revokegpt_timeout_ms 5000 The deadline of the verification call, 1 to 60000. Anything else gives 5000.
revokegpt_verifier null Return an object with check( string $action, ?string $token ): Verdict to replace the verifier entirely (tests and advanced setups). Whatever it answers is enforced. Anything else is ignored.
revokegpt_assessor null Return an object with assess( ?string, TransactionData, ?string ): CheckoutResult to replace the WooCommerce checkout check entirely.
revokegpt_checkout_decision the decision Receives allow, stepup or block and the full CheckoutResult. Return one of the three to change it. Monitor mode still turns a non-allow into allow.
revokegpt_checkout_is_express computed Receives whether the request is a wallet checkout (Apple Pay, Google Pay, PayPal), the gateway id and the request parameters. Return false to require the token everywhere. Only true counts as express.
revokegpt_pay_attempts_per_hour 5 The most payment attempts on one order in an hour, on Pay for order. An integer of 1 or more; anything else gives 5. 
add_filter( 'revokegpt_client_ip', function ( $ip ) {
  return $_SERVER['HTTP_CF_CONNECTING_IP'] ?? $ip; // only if you trust that header
} );

Actions

Section titled “Actions”
Action Arguments When
revokegpt_event event name, code A constant diagnostic: annotation-failed (with an error code or misconfigured) when reporting an order outcome fails, and checkout-data when checkout data could not be collected. Never an order value.
revokegpt_annotate_order order arguments The Action Scheduler job (or a WP-Cron single event) that tells RevokeGPT an order failed, was paid or had a chargeback, once per order, up to three tries. Do not hook it to change behaviour.

The WooCommerce order action Report chargeback to RevokeGPT reports a fraud chargeback.

Errors and failure model

Section titled “Errors and failure model”

The plugin fails closed. When the check cannot run, the request is refused. The exceptions are:

  • fail_open_login, off by default, which applies to login only and only to network and HTTP errors.
  • The WooCommerce checkout, which takes the order by default (checkout_open), flags it, and shows administrators a notice until the next successful check.
  • monitor mode, which lets everything through.
  • The plugin not being configured (a missing site key, secret key or endpoint) and REVOKEGPT_DISABLE, which check nothing.

A refused visitor sees only “The security check failed.” On registration and lost password, WordPress’s own messages (which would reveal whether an account exists) are replaced by it. The refusal reasons the plugin keeps include network-error, http-error, misconfigured, invalid-expectation and not-verified. The SDK’s reason is not shown to the visitor. For a failed token, see error codes.

The check expects the hostname of home_url(), the form’s action, and the configured min_score.

Security notes

Section titled “Security notes”
  • Keep the secret key in REVOKEGPT_SECRET_KEY. A key stored in the database is readable in plain text by administrators at wp-admin/options.php. The stored option is created with autoload off.
  • The endpoint and the widget origin must be https:, with no credentials, query or fragment. The plugin sends the response token, your secret key in an Authorization header and the visitor’s IP address to the endpoint you configure.
  • For WooCommerce checkout it also sends the order amount, currency, shipping amount, billing and shipping address, email address, customer id, the payment gateway’s id and up to 20 item names with quantities and prices. No card data is ever read or sent, and a name or address that looks like a card number is left out.
  • Wallet buttons carry no token. They are checked with the express assessment, which scores the visitor’s network address alone and sends no order data. A request that names a wallet type and a known wallet gateway skips the token check, so a bot that fakes that marker is held back only by the address check.
  • Password logins over XML-RPC are refused by default. Give older clients an application password.
  • On a WooCommerce order the plugin keeps _revokegpt_assessment, _revokegpt_annotated, _revokegpt_stepup and, when the service was unreachable, _revokegpt_unchecked. Deleting the plugin removes its options and transients. No visitor profile is stored.

See also the WordPress quickstart and modes and thresholds.