Documentation
Developer reference
For: developers integrating Gatekeep, protecting custom forms, or extending it. Assumes: PHP and the WordPress plugin API.
Requires PHP 7.4+, WordPress 5.8+. Tested to WordPress 7.1, on MySQL and SQLite, single site and multisite, with and without a persistent object cache.
Contents
- Protecting a custom form
- The public API
- REST endpoints
- Filters
- Actions
- Architecture
- Writing an integration
- Behind a proxy or CDN
- Testing
1. Protecting a custom form
Two calls.
// Inside your <form> markup.
gatekeep_field();
// When handling the submission.
$check = gatekeep_verify();
if ( is_wp_error( $check ) ) {
wp_die( $check->get_error_message() );
}
Or drop [gatekeep] into any builder.
For a form you cannot edit, enable the universal form guard: it injects into rendered markup and intercepts the matching POST. Restrict it with selectors (#signup, .newsletter) or exclude URLs.
2. The public API
gatekeep_field( string $context = 'custom', bool $echo = true ): string
Renders the hidden fields and any configured challenge. Returns '' in Safe mode.
gatekeep_verify( string $context = 'custom', array $post = null ): true|WP_Error
Assesses the current request. Returns true when allowed. Never blocks in Safe mode.
gatekeep_assess( string $context, array $args = [] ): array
The full result:
[
'verdict' => 'allow'|'challenge'|'block',
'score' => 0-100,
'signals' => [ [ 'slug' => …, 'risk' => 0-100, 'label' => … ], … ],
'enforced' => bool, // false while Monitor Mode holds a borderline case
'certain' => bool, // present when a conclusive signal forced enforcement
'passed' => bool, // what to act on
'message' => string,
'context' => string,
]
Accepted $args: post (unslashed array), email (skip address detection), skip_rate (bypass the rate limiter — use for synthetic checks).
Act on passed, not verdict. A block verdict that is not enforced must be let through.
gatekeep_is_safe_mode(): bool
3. REST endpoints
GET /wp-json/gatekeep/v1/challenge
Issues a token for a headless front end. Returns the token, the field name to post it under, the current honeypot field name, and proof-of-work parameters if configured.
The honeypot field name is derived per site from its salts, so it must be read from here rather than hardcoded.
POST /wp-json/gatekeep/v1/siteverify
reCAPTCHA-compatible. Accepts secret and response, returns Google's response shape — anything already written against siteverify works by changing one URL.
{ "success": true, "score": 1.0, "action": "contact",
"challenge_ts": "2026-07-29T09:14:00+00:00", "hostname": "example.com" }
GET /wp-json/gatekeep/v1/captcha?c=…
Renders an image challenge. Requires a signed payload; rate limited to 30 requests per address per minute. The signature is verified before any rendering work.
Both public endpoints can be switched off.
4. Filters
Scoring
| Filter | Signature | Purpose |
|---|---|---|
gatekeep_signals |
array $signals, string $context, array $post |
Add or modify signals before scoring |
gatekeep_assessment |
array $result, string $context |
Change the final verdict |
gatekeep_block_message |
string $message, array $result |
Message shown when blocked |
gatekeep_disposable_domains |
array $map |
Extend the bundled domain map |
gatekeep_autofill_contexts |
array $contexts |
Where fast submission is normal |
add_filter( 'gatekeep_signals', function ( $signals, $context, $post ) {
if ( 'my_form' === $context && empty( $post['referrer'] ) ) {
$signals[] = [
'slug' => 'no_referrer',
'risk' => 30,
'label' => __( 'No referrer supplied', 'my-plugin' ),
];
}
return $signals;
}, 10, 3 );
Risk is 0–100. Anything at or above certain_threshold (default 90) is enforced even during Monitor Mode — reserve that for signals a real visitor cannot trigger.
Rendering and integration
| Filter | Purpose |
|---|---|
gatekeep_fields_html |
Markup injected into forms |
gatekeep_form_shortcodes |
Shortcodes whose output should be protected |
gatekeep_fingerprints |
Submission fingerprints for breakage detection |
gatekeep_request_bufferable |
Whether the current request may be buffered |
gatekeep_overlapping_plugins |
Competing plugins reported to the user |
Infrastructure
| Filter | Purpose | |
|---|---|---|
gatekeep_client_ip |
Supply the client IP | |
gatekeep_can_use |
Override Pro gating | |
gatekeep_license_endpoint |
Licence API URL | |
gatekeep_feed_endpoint |
Threat feed URL | |
gatekeep_captcha_lifetime |
How long a challenge stays valid | |
gatekeep_captcha_fonts |
Font candidates for image challenges | |
gatekeep_captcha_image_limit |
Image requests allowed per minute | |
gatekeep_watched_options |
Options treated as security-critical | |
gatekeep_watched_network_options |
The same, network-wide | |
gatekeep_audit_findings |
Add or remove audit checks | |
gatekeep_diagnostics |
Add or remove self-test checks | |
gatekeep_profiles |
Add a protection profile | |
gatekeep_trusted_capability |
string $capability |
Which capability marks a user as trusted enough to skip every check. Defaults to edit_posts. Lower it and you widen the bypass — a subscriber created by open registration is not the same as somebody you gave standing to. |
gatekeep_login_exempt |
bool $exempt |
Exempt a recovery login from scoring. |
gatekeep_challenge_limit |
int $per_minute |
How many challenges one address may request each minute from the public API. Default 60. |
gatekeep_challenge_limit_global |
int $per_minute |
Site-wide ceiling on the same endpoint. Default 600. The per-address limit above is the one a rotating proxy pool never meets; this is the one it cannot route around. |
gatekeep_guard_admin_endpoints |
array $endpoints |
Admin-post and AJAX endpoints the universal guard covers. |
gatekeep_existing_captchas |
array $map |
Which other plugins count as an existing captcha, for the coexistence report. |
gatekeep_profile_licence_bypass |
bool $bypass |
Allow a protection profile to apply licensed settings. |
gatekeep_friendly_widget_url |
string $url |
Where the Friendly Captcha widget script is loaded from. |
5. Actions
| Action | Fires when | |
|---|---|---|
gatekeep_loaded |
The plugin is ready — hook here before using the API | |
gatekeep_safe_mode |
Loaded in Safe mode | |
gatekeep_adapter_degraded |
An integration was judged broken by an upstream change | |
gatekeep_security_event |
A security event was recorded | |
gatekeep_contained_failure |
A callback of ours failed and was contained | |
gatekeep_profile_applied |
A protection profile was applied | |
gatekeep_onboarding_complete |
Guided setup finished | |
gatekeep_recorded |
array $result |
Fires after a verdict is written to the activity log. The reputation store listens here; anything else that wants the final result can too. |
gatekeep_page_uncacheable |
string $context |
Fires when a page has been given per-request Gatekeep fields. Hook this from a caching layer that does not honour DONOTCACHEPAGE — a cached challenge is the same token and the same answer served to every visitor until the copy expires. |
gatekeep_render_guard |
string $context |
Emit Gatekeep’s fields inside a template you control. |
6. Architecture
Classes are autoloaded; a front-end page view parses about 111 KB of the 298 KB total. Nothing admin-only, licence-related or hardening-related loads for a visitor.
| Class | Responsibility |
|---|---|
GK_Engine |
Collects signals, scores, decides |
GK_Signals |
Individual checks |
GK_Token |
HMAC-signed stateless tokens. GK_Token::sign_payload() is the only correct way to sign one |
GK_Captcha |
Self-hosted challenges |
GK_Providers |
Third-party verification |
GK_Guard |
Universal form protection |
GK_Integrations / GK_Builders |
Per-plugin adapters |
GK_Compat |
Detects adapters that stopped firing |
GK_Isolation |
Buffering safety and failure containment |
GK_Log / GK_Events |
Verdict and security-event storage |
GK_Feed |
Threat feed, in an indexed table. The engine asks GK_Feed::has_domain() - one indexed lookup, returning a confidence rather than a bare yes. domains() reads the same table if you need the map. A refresh that returns dramatically fewer domains than currently held is refused as truncated rather than imported |
GK_License |
Licensing |
Two design rules worth knowing
Signals combine by noisy-OR, not addition. Three weak signals cannot stack into a block. One conclusive signal decides alone.
Failures are contained, never propagated. Adapters run inside third-party code, where an exception takes their form down and gets blamed on Gatekeep. GK_Isolation::safely() wraps callbacks; a failure lets the submission through and is recorded. An unprotected form is recoverable; a broken page is not.
7. Writing an integration
add_action( 'gatekeep_loaded', function () {
add_filter( 'myforms_validate', function ( $errors, $submission ) {
$result = gatekeep_assess( 'myforms', [
'email' => $submission['email'] ?? '',
] );
if ( empty( $result['passed'] ) ) {
$errors[] = $result['message'];
}
return $errors;
}, 10, 2 );
} );
Guidelines:
- Use the target plugin's own error channel so the rejection appears in its normal UI.
- Never fatal. Guard every call into third-party code with
method_exists()orclass_exists(). - Bind several candidate hook names. Hooks that no longer exist never fire, so listing historical names is free insurance.
GK_Compat::bind_any()does this. - Register a fingerprint via
gatekeep_fingerprintsso breakage detection can spot missed submissions. - Do not version-sniff. Inspect what the submission actually carries. Divi 5 changed its format entirely; a version check would only know about versions that existed when it was written.
8. Behind a proxy or CDN
X-Forwarded-For is not trusted by default — doing so lets anyone spoof past a rate limit. Supply the address explicitly:
add_filter( 'gatekeep_client_ip', function () {
return $_SERVER['HTTP_CF_CONNECTING_IP'] ?? $_SERVER['REMOTE_ADDR'];
} );
Only do this where the header genuinely comes from your proxy.
9. Testing
Twenty-one suites ship separately, runnable from a WordPress root. Run reset.php between them. As of 1.43.1 the whole battery passes with zero failures - roughly 1,200 assertions on WordPress 7.0.1 against MySQL and the SQLite integration layer, with WooCommerce 10.9.4, Elementor, Contact Form 7, Formidable, bbPress and Fluent Forms live.
Three suites have preconditions:
- licence-e2e needs the licence server running locally. PHP's built-in server does not route
/v1/*from a docroot; start it in router mode:php -S 127.0.0.1:9099 index.php. - license-fortify expects the Fortify module bound at boot, so set
fortifyon and store a licence before running the suite in a fresh process. Clear that licence afterwards - a live licence routes email checks through the feed table, which skews the timing suites. - pentest budgets 5 ms per blocked submission on MySQL and allows 12 ms on the SQLite layer, where each log write costs a couple of milliseconds more.
Two that matter if you are extending Gatekeep:
- suite-16-settings-matrix flips all 81 switches and asserts each changes observable behaviour. Add a setting without wiring it and this fails.
- suite-19-diagnostics deliberately breaks things and asserts each is caught — including a case that would otherwise pass for the wrong reason.
Verified on WordPress 6.8 (SQLite), 7.0 with nine page builders, and 6.8 on MariaDB as a three-site multisite network with Redis. browser/accessibility-axe.js checks WCAG 2.1 AA.
Signing tokens in tests: use GK_Token::sign_payload(). Signatures are truncated to 32 characters; eight suites once hand-rolled 64-character ones and passed for the wrong reasons.