Developer Reference

wp_authenticate_user

Main authentication filter. Applies delays and lockouts to login attempts. Parameters: $user (WP_User|WP_Error), $password. Returns WP_Error if locked out, otherwise applies sleep() delay on failure and returns $user.

rest_authentication_errors

REST API authentication protection. Applies delays and lockout to failed REST API authentication when wldelay_rest_enabled is on. Returns a 403 WP_Error if the IP is locked out. Respects the IP whitelist and skips application-password attempts (handled separately). Since v2.1.2.

authenticate

Application-password authentication protection. Applies delays and lockout to failed Basic Auth attempts when wldelay_application_password_enabled is on. Detects app-password attempts via PHP_AUTH_USER/PHP_AUTH_PW server headers. Parameters: $user, $username, $password. Since v2.1.2.

authenticate

Blocks XML-RPC authentication when the “block XML-RPC” setting is enabled. Parameters: $user, $username, $password. Returns WP_Error('wldelay_xmlrpc_blocked') for XML-RPC requests.

wldelay_2fa_providers

Customize the list of recognized 2FA plugins for the settings-page health check. Receives an associative array of slug => [ plugin_basename, … ]. Return the modified array to add or remove providers. The default map includes two-factor, wp-2fa, mini-orange, and google-authenticator. Since v2.1.4.

wldelay_2fa_coverage_checkers

Register provider-specific callbacks that report privileged-user 2FA coverage for the settings-page notice. Receives a map of provider_slug => callable (the built-in entry covers the two-factor plugin). Each callback returns an array with keys supported, privileged_total, protected, unprotected, and unknown.

wldelay_normalize_username

Customize how usernames are normalized for failure tracking and lockout identity. Receives the normalized username and the original input. Return your own normalized value to support LDAP, email-as-login, or SSO backends where the default lowercase/sanitize behavior is not enough. Since v2.3.0.

wldelay_persistence_store

Swap the lockout persistence backend. Receives null; return a WLDelay_Persistence implementation to replace the default DB-backed store (for example a Redis or external store) without touching call sites. Falls back to WLDelay_DB_Persistence when the filter returns anything else.

wldelay_login_help_url

Set the “Need help getting in?” link shown in the login-page lockout feedback block. Defaults to the site’s lost-password URL (respecting any custom-login-slug rewrite); point it at a support or docs page instead. Returned value is escaped at output.

wldelay_fail2ban_allowed_log_dirs

Extend the set of directories a custom fail2ban log path may live in. By default only the plugin-owned protected directory is allowed; add server-protected directories here. Web-server protection files (.htaccess, index.html, index.php) are written to every allowed directory. A custom path outside the allowed set disables logging rather than writing elsewhere.

wldelay_fail2ban_max_log_bytes

Control the size at which the fail2ban log is rotated to a single .log.1 backup. Defaults to 5 MB. Return 0 to disable in-plugin rotation and rely on system logrotate instead. Since v2.3.4.

wldelay_botnet_ip_threshold

Number of distinct source IPs targeting one username that triggers a distributed-attack alert. The stored option is clamped to [2, 100] before the filter runs, and the result is re-floored at 2 so a filter cannot drop below the minimum. Default 5. Since v2.5.0.

wldelay_botnet_window

Sliding detection window, in seconds. The stored minutes option is clamped to [5, 60] and converted to seconds before the filter; the result is floored at MINUTE_IN_SECONDS. Default 900 (15 minutes). Since v2.5.0.

wldelay_botnet_alert_cooldown

Per-username cooldown, in seconds, that suppresses repeat distributed-attack alerts after one fires. Default HOUR_IN_SECONDS. Since v2.5.0.

wldelay_cloudflare_ip_ranges

The list of Cloudflare CIDR ranges used to validate the CF-Connecting-IP header. The header is honored only when REMOTE_ADDR falls inside one of these ranges, so it cannot be spoofed. Return your own array to extend or replace the built-in IPv4/IPv6 ranges. Since v2.4.0.

wldelay_resolve_country_code

Supplies the visitor country for the optional Country Blocking feature. Return an ISO 3166-1 alpha-2 code such as US or DE (case-insensitive; normalized internally). Parameters: $country_code, $ip (client IP after proxy handling), $source (auth source label: wp-login, xmlrpc, rest, application-password). The incoming value is always empty: your resolver runs first and wins. Only when it returns an empty string does the plugin fall back to its built-in detection (wldelay_detect_country_from_request(), since v2.7.0), which reads, in order, Cloudflare’s CF-IPCountry (trusted proxy headers + a verified Cloudflare peer), $_SERVER['GEOIP_COUNTRY_CODE'], then an X-Country-Code proxy header (trusted proxy headers). A resolver is therefore never handed a visitor-supplied header value to defer to. The plugin still ships no GeoIP database and performs no network lookup. The block is asserted at several points in the auth chain, so this filter can run more than once per attempt; cache any expensive lookup per request. Whitelisted IPs and safe mode always bypass the check. Since v2.6.0.

wldelay_trust_server_country_variable

Whether a bare $_SERVER['GEOIP_COUNTRY_CODE'] is trusted by the built-in country resolver. Default true: PHP exposes request headers as HTTP_*, so an unprefixed variable normally can only come from the web server’s own GeoIP module. Return false on a deployment that deliberately maps client input into a bare CGI parameter (an unusual fastcgi_param or SetEnvIf rule). Since v2.7.0.

wldelay_challenge_providers

The challenge-provider registry for Challenge Mode, keyed by provider id. Add your own entry to offer a custom challenge in the settings dropdown; each value must be an instance of LDS_Challenge_Provider (see Challenge Providers). Entries that are not LDS_Challenge_Provider instances are dropped. Removing the built-in math provider is safe — the resolver falls back to a fresh instance of it rather than returning null. Since v2.7.0.

wldelay_send_custom_login_email

Whether to email the new login URL to the site admin when the Custom Login URL feature is enabled or its slug changes. Default true; return false (e.g. __return_false) to suppress the recovery email. Since v2.4.0.

wldelay_help_base_url

Base URL for the “Learn more” documentation links on each settings card. Defaults to https://damoiseau.xyz/docs/login-delay-shield/user-guide/. Return an empty string to hide the links, or point them at your own mirror. Since v2.5.0.

wldelay_export_login_log_should_exit

Controls whether the CSV export handler calls exit() after streaming. Default true. Set to false in test environments. Since v2.1.2.

plugin_action_links_{basename}

Adds a “Settings” link to the plugin’s entry on the Plugins page.

wp_login_failed

Hooked to log failed login attempts to the database. Parameters: $username. Records the IP address, username, timestamp, and source (wp-login, xmlrpc, rest, application-password, or password-reset).

wldelay_cleanup_logs

Custom cron hook that runs daily. Deletes log entries older than the configured retention period. Processes in batches of 1,000 rows.

wp_dashboard_setup

Registers the “Recent Failed Login Attempts” dashboard widget.

admin_post_wldelay_unlock_current_ip

Handles the “Unlock Current IP” button on the settings page. Removes the lockout and failure counters for the requesting admin’s IP address. Nonce-protected and requires manage_options capability.

admin_post_wldelay_export_login_log

Handles CSV export of the failed login log. Streams results in 1,000-row batches with formula-injection protection. Reads optional filters from $_GET (source, IP, username, date range). Nonce-protected and requires manage_options capability. Since v2.1.2.

admin_post_wldelay_recovery_generate

Mints a new Emergency Recovery token, stores its hash, emails the URL to the site admin, and sets the one-time reveal. Nonce-protected, requires manage_options. Since v2.6.0.

admin_post_wldelay_recovery_download

Streams the once-revealed recovery URL as a .txt download. Nonce-protected, requires manage_options; only works inside the reveal window. Since v2.6.0.

admin_post_wldelay_recovery_confirm / admin_post_nopriv_wldelay_recovery_confirm

Handles the confirm POST from the recovery landing page. Re-validates the token and nonce, then clears the caller’s own IP lockout (it never logs the user in). Registered for both authenticated and unauthenticated callers so a locked-out admin can use it. Since v2.6.0.

wldelay_event_{event}

Per-event hook fired for each plugin event (e.g. wldelay_event_cron_tick). Receives the event payload array. Subscribe with wldelay_on_event(), or hook the generic wldelay_event action (which receives $event_name, $payload) to observe every event as an audit/SIEM firehose.

wldelay_persistence_write_failed

Fires when a lockout could not be written to the durable store. Parameters: $ip, $type (login or password-reset). The lockout falls back to transient-only state until the store recovers.

wldelay_audit_write_failed

Fires when an audit-log row could not be written. Parameters: $action (the action key whose row was lost), $error (DB error string).