Captcha
Table of Contents
Packages
Classes
- Analytics
- Records security events into per-day and per-hour aggregate counters and, when the detailed event log is enabled, into a dedicated database table.
- EmailObfuscator
- Obfuscates mailto: links and plain-text email addresses in front-end output. The real address is XOR-hex encoded into a data-cce attribute and restored client-side by the decoder script. Two modes share this class: the content-filter mode (process()) and the full-page-buffer mode (process_page()). See the module-7 and module-8 design specs.
- Engine
- Wraps the bundled ALTCHA library for the WordPress plugin.
- Firewall
- Blocks requests by client IP or user-agent before WordPress processes them.
- Interceptor
- Inspects front-end POST requests and enforces a valid ALTCHA payload for requests whose path matches a configured pattern. See the module-2 design spec for the bypass chain (§6) and the guard decision (§7/§8).
- RateLimiter
- Counts requests per client IP in a fixed time window and blocks with HTTP 429 once the configured limit is exceeded. See the module-4 design spec §6.
- UnderAttack
- Gates anonymous front-end page views behind an interstitial proof-of-work challenge while under-attack mode is active. See the module-5 design spec.
- Cloudflare_Command
- `wp creacaptcha cloudflare …` — refresh, clear and status for the cached Cloudflare IP-range list.
- Command
- Inspects and controls CreaCaptcha from the command line.
- Doctor_Command
- `wp creacaptcha doctor`
- List_Command
- Manages one list-type setting — IP block/allow list, UA block list or the interceptor path list. The same class backs the blocklist, allowlist, ua-blocklist and paths command namespaces.
- Log_Command
- Inspects and maintains the optional event-log table.
- Settings_Command
- Reads, writes, exports, imports and resets CreaCaptcha settings.
- Test_Bypass_Command
- `wp creacaptcha test-bypass`
Constants
- CREATIONELL_CAPTCHA_EXPORT_SCHEMA = 1
- Schema version of the settings-export format.
- CREATIONELL_CAPTCHA_LOCALE_MAP = [ // Deutsch 'de_DE' => 'de', 'de_DE_formal' => 'de', 'de_AT' => 'de', 'de_CH' => 'de', 'de_CH_informal' => 'de', // Englisch 'en_US' => 'en', 'en_GB' => 'en', 'en_AU' => 'en', 'en_CA' => 'en', 'en_NZ' => 'en', 'en_ZA' => 'en', // Französisch 'fr_FR' => 'fr-fr', 'fr_BE' => 'fr-fr', 'fr_LU' => 'fr-fr', 'fr_CH' => 'fr-fr', 'fr_CA' => 'fr-ca', // Spanisch (Europa) 'es_ES' => 'es-es', // Spanisch (LatAm — alle nach es-419) 'es_AR' => 'es-419', 'es_CL' => 'es-419', 'es_CO' => 'es-419', 'es_CR' => 'es-419', 'es_DO' => 'es-419', 'es_EC' => 'es-419', 'es_GT' => 'es-419', 'es_HN' => 'es-419', 'es_MX' => 'es-419', 'es_PA' => 'es-419', 'es_PE' => 'es-419', 'es_PR' => 'es-419', 'es_UY' => 'es-419', 'es_VE' => 'es-419', // Portugiesisch 'pt_PT' => 'pt-pt', 'pt_AO' => 'pt-pt', 'pt_BR' => 'pt-br', // Italienisch / Niederländisch / Polnisch 'it_IT' => 'it', 'nl_NL' => 'nl', 'nl_BE' => 'nl', 'pl_PL' => 'pl', // Tschechisch / Slowakisch 'cs_CZ' => 'cs', 'sk_SK' => 'sk', // Nordisch 'da_DK' => 'da', 'sv_SE' => 'sv', 'fi' => 'fi', 'nb_NO' => 'nb', 'nn_NO' => 'nb', // Sonstige EU 'hu_HU' => 'hu', 'ro_RO' => 'ro', 'el' => 'el', ]
- Maps WordPress locales to the matching ALTCHA i18n locale bundle.
Functions
- creationell_captcha_register_admin_menu() : void
- Registers the top-level "CreaCaptcha" admin menu entry.
- creationell_captcha_render_settings_page() : void
- Renders the tabbed settings page.
- creationell_captcha_render_trust_notice() : void
- Renders the "proxy mode on but trust-set empty" admin notice on plugin pages.
- creationell_captcha_tabbed_page_hooks() : array<int, string>
- Records and reports the admin-page hook suffixes of the plugin's tab-organised pages.
- creationell_captcha_active_tab() : string
- Determines the active tab from the request, whitelisted against $tabs.
- creationell_captcha_render_nav_tabs() : void
- Renders the no-JavaScript fallback style and the nav-tab bar.
- creationell_captcha_csv_cell() : string
- Neutralises a CSV cell against spreadsheet formula injection.
- creationell_captcha_export_events() : void
- Streams the filtered event log as a CSV download.
- creationell_captcha_register_analytics_page() : void
- Registers the "Statistik" submenu page under the CreaCaptcha menu.
- creationell_captcha_analytics_labels() : array<string, string>
- Human-readable labels for the seven event types.
-
creationell_captcha_analytics_groups()
: array<int, array{title: string, description: string, types: array
}> - Thematic groups for the overview tab: title, explanation and the member event types with their short in-group labels.
- creationell_captcha_analytics_tabs() : array<string, string>
- The three tabs of the analytics page.
- creationell_captcha_sum_recent_days() : array<string, int>
- Sums the $days most recent day buckets, per event type.
- creationell_captcha_sum_recent_hours() : array<string, int>
- Sums the $hours most recent hour buckets, per event type.
- creationell_captcha_render_analytics_page() : void
- Renders the tabbed analytics dashboard page.
- creationell_captcha_render_analytics_overview() : void
- Renders the "Übersicht" tab: four 24-hour KPI tiles and one four-window comparison table per thematic group.
- creationell_captcha_render_analytics_history() : void
- Renders the "Verlauf" tab: the day-by-day table for the last 30 days.
- creationell_captcha_events_query_args() : array{search: string, event_type: string, date_from: string, date_to: string}
- Reads and sanitises the event-log filter from the request.
- creationell_captcha_render_analytics_events() : void
- Renders the "Ereignisse" tab: filter toolbar, the event table with a detail link per row, the embedded event data and the detail modal.
- creationell_captcha_render_event_modal() : void
- Renders the (initially hidden) event-detail modal skeleton.
- creationell_captcha_render_events_toolbar() : void
- Renders the event-log filter toolbar: search, type filter, date range, the "Filtern"/"Zurücksetzen" controls and the CSV export link.
- creationell_captcha_render_events_pagination() : void
- Renders the pagination navigation below the event-log table.
- creationell_captcha_analytics() : Analytics
- Returns the shared analytics recorder instance.
- creationell_captcha_record_event() : void
- Records a security event of the given type.
- creationell_captcha_enqueue_admin_assets() : void
- Enqueues admin styles and scripts on the CreaCaptcha admin pages.
- creationell_captcha_cloudflare_snapshot() : array{v4: string[], v6: string[], updated_at: string}
- Returns the bundled Cloudflare snapshot.
- creationell_captcha_cloudflare_ranges() : array<string|int, string>
- The active CF range list: cached option (if fresh) → bundled snapshot.
- creationell_captcha_refresh_cloudflare_ips_now() : array{ok: bool, v4: int, v6: int, fetched_at: int|null, error: string|null}
- Fetches the live Cloudflare ranges and writes them to the cache option.
- creationell_captcha_clear_cloudflare_cache() : bool
- Deletes the cached Cloudflare-range option. The next read falls back to the bundled snapshot. Returns true when the option existed and was deleted, false when the option was absent or the delete failed.
- creationell_captcha_fetch_cloudflare_list() : array<string|int, string>
- Fetches one Cloudflare endpoint and returns the valid CIDR entries.
- creationell_captcha_sync_cloudflare_cron() : void
- Ensures the daily refresh cron slot is in sync with the auto-refresh toggle.
- creationell_captcha_render_code_image() : string
- Renders a PNG of the given code and returns the raw bytes. Caller is responsible for emitting headers (`Content-Type: image/png`, `Cache-Control: no-store`) and the body.
- creationell_captcha_should_issue_code_challenge() : bool
- Decides whether the current /challenge request should attach a code-challenge instruction. Returns true iff:
- creationell_captcha_code_charset() : string
- Returns the active charset string for the configured option.
- creationell_captcha_generate_code() : string
- Generates a fresh random code from the configured charset.
- creationell_captcha_code_token_issue() : string
- Issues a token backed by a server-side WP transient that stores the expected code for at most $expiry_seconds. Returns the opaque ID that `/code-image` and `/code-verify` use to look the code up again.
- creationell_captcha_code_token_verify() : string|null
- Looks up the code for a token and returns it, or null on: - malformed token (not 32 hex chars) - missing transient (expired or unknown)
- creationell_captcha_rest_code_image() : WP_REST_Response
- Handles GET /code-image?t=<token>. Looks up the code from the token (server-side transient), renders the PNG, returns 410 on token failure.
- creationell_captcha_rest_code_verify() : WP_REST_Response
- Handles POST /code-verify. Two body shapes:
- creationell_captcha_register_code_challenge_routes() : void
- Registers the two code-challenge REST routes. The /challenge handler itself stays in includes/rest.php; Task 11 extends it with the codeChallenge field and the data.ccode embed.
- creationell_captcha_register_email_obfuscation() : void
- Registers email obfuscation on `init`. The decoder script is always registered; then, unless the kill-switch is set or the feature is off, the configured mode is wired up — the content filters (module 7) or the full-page output buffer (module 8).
- creationell_captcha_register_email_buffer() : void
- Wires up the full-page-buffer mode: on `template_redirect` for non-feed front-end requests it enqueues the decoder script and starts an output buffer whose callback obfuscates the page body at flush time.
- creationell_captcha_run_firewall() : void
- Runs the IP/user-agent firewall. Hooked on `init` at priority 0 so it fires before the rate limiter, the interceptor and any form-processing handler.
- creationell_captcha_comments_active() : bool
- Whether comment protection applies to the current request.
- creationell_captcha_comments_render() : string
- Injects the widget just above the comment form submit button.
- creationell_captcha_comments_verify() : array<string, mixed>
- Verifies the captcha before a comment is accepted.
- creationell_captcha_login_enabled() : bool
- Whether login protection is enabled.
- creationell_captcha_login_render() : void
- Renders the widget inside the login form.
- creationell_captcha_login_verify() : WP_User|WP_Error|null
- Verifies the captcha during an interactive login.
- creationell_captcha_password_reset_enabled() : bool
- Whether password-reset protection is enabled.
- creationell_captcha_password_reset_render() : void
- Renders the widget inside the lost-password form.
- creationell_captcha_password_reset_verify() : void
- Verifies the captcha during a password-reset request.
- creationell_captcha_registration_enabled() : bool
- Whether registration protection is enabled.
- creationell_captcha_registration_render() : void
- Renders the widget inside the registration form.
- creationell_captcha_registration_verify() : WP_Error
- Verifies the captcha during registration.
- creationell_captcha_resolve_widget_locale() : string|null
- Resolves the active WordPress locale to a vendored ALTCHA locale code.
- creationell_captcha_get_default_settings() : array<string, mixed>
- Default plugin settings.
- creationell_captcha_get_settings() : array<string, mixed>
- Current plugin settings, merged over the defaults.
- creationell_captcha_invalidate_settings_cache() : void
- Drops the in-request settings cache. Wired to the option-change hooks below so callers that read settings after an update see the fresh value.
- creationell_captcha_is_disabled() : bool
- Whether the captcha is globally disabled via the wp-config constant.
- creationell_captcha_sodium_available() : bool
- Whether ext-sodium (required for Argon2id) is available.
- creationell_captcha_generate_secrets() : array{signature: string, key_signature: string}
- Generates both HMAC secrets and persists them (non-autoloaded).
- creationell_captcha_get_secret() : string
- Returns a stored HMAC secret, generating + persisting it on first use.
- creationell_captcha_get_hmac_secret() : string
- The HMAC signature secret (signs each challenge).
- creationell_captcha_get_hmac_key_secret() : string
- The HMAC key-signature secret (enables the fast verification path).
- creationell_captcha_engine() : Engine
- Shared captcha engine instance.
- creationell_captcha_log() : void
- Write a message to the debug log when CREATIONELL_CAPTCHA_DEBUG is active.
- creationell_captcha_get_client_ip() : string
- Resolves the client IP address.
- creationell_captcha_ip_in_list() : bool
- Whether an IP matches any entry in a list of IPs or CIDR ranges.
- creationell_captcha_ip_in_cidr() : bool
- Whether an IP falls within a CIDR range. Supports IPv4 and IPv6.
- creationell_captcha_is_valid_ip_or_cidr() : bool
- Whether a string is a valid IP address or CIDR range (IPv4 or IPv6).
- creationell_captcha_wildcard_match() : bool
- Whether a subject matches any of the given wildcard patterns (case-insensitive).
- creationell_captcha_private_ranges() : array<string|int, string>
- Returns the canonical list of private/loopback CIDR ranges used when the `firewall_trust_private_ranges` toggle is active.
- creationell_captcha_trusted_proxies_constant() : array<string|int, string>
- Reads the optional `CREATIONELL_CAPTCHA_TRUSTED_PROXIES` wp-config constant as a list. Accepts either a string array or a comma/whitespace-separated scalar; invalid entries are dropped.
- creationell_captcha_is_trusted_proxy() : bool
- Whether the given IP belongs to a trusted upstream proxy.
- creationell_captcha_evaluate_bypass() : array{reason: string, source: string}|false
- Pure bypass evaluator — checks the three bypass sources against the supplied inputs without touching $_SERVER, $_COOKIE or any static cache. The caller is responsible for providing the values.
- creationell_captcha_request_bypassed() : array{reason: string, source: string}|false
- Whether the current request is allowed to bypass captcha, under-attack and firewall protections. Reads $_SERVER, $_COOKIE and the request's client IP, then delegates to `creationell_captcha_evaluate_bypass()`.
- creationell_captcha_validate_action_pattern() : string|null
- Validates a single interceptor-action pattern.
- creationell_captcha_validate_cookie_entry() : string|null
- Validates a single bypass-cookie entry of the form `name=value`.
- creationell_captcha_anonymize_ip() : string
- Truncates an IP for DSGVO-compliant storage. IPv4 → last octet zeroed, IPv6 → last 80 bits zeroed. Invalid IPs return ''.
- creationell_captcha_request_body_fingerprint() : string
- Returns a JSON-encoded fingerprint of $_POST: { field-name: value-byte-length }.
- creationell_captcha_block_response() : void
- Sends a fail-closed block response and terminates the request.
- creationell_captcha_base64url_encode() : string
- Base64URL encoder (RFC 4648 §5) — strips standard-base64 padding and replaces +/ with -_ so the value is URL-safe.
- creationell_captcha_base64url_decode() : string
- Base64URL decoder — accepts unpadded URL-safe input and returns the raw bytes. Returns the empty string on malformed input (no exceptions).
- creationell_captcha_ratelimit_current_count() : int
- Reads the current rate-limit counter for an IP without incrementing it.
- creationell_captcha_cf7_active() : bool
- Whether the Contact Form 7 integration is active.
- creationell_captcha_cf7_register_tag() : void
- Registers the [creationell_captcha] Contact Form 7 form-tag.
- creationell_captcha_cf7_tag_handler() : string
- Renders the widget for the [creationell_captcha] form-tag.
- creationell_captcha_cf7_auto_inject() : string
- Auto-injects the widget into CF7 forms without a [creationell_captcha] tag.
- creationell_captcha_cf7_verify() : bool
- Verifies the captcha on a Contact Form 7 submission.
- creationell_captcha_forminator_active() : bool
- Whether the Forminator integration is active.
- creationell_captcha_forminator_inject() : string
- Auto-injects the widget before the submit button of a Forminator custom form.
- creationell_captcha_forminator_verify() : array<int, array<string, string>>
- Verifies the captcha on a Forminator custom-form submission.
- creationell_captcha_woocommerce_active() : bool
- Whether any WooCommerce protection applies right now.
- creationell_captcha_wc_checkout_active() : bool
- Whether the WooCommerce checkout protection is active.
- creationell_captcha_wc_checkout_render() : void
- Renders the widget directly before the Place-Order button on the checkout.
- creationell_captcha_wc_checkout_verify() : void
- Verifies the captcha during checkout validation.
- creationell_captcha_wc_login_active() : bool
- Whether the WooCommerce my-account login protection is active.
- creationell_captcha_wc_login_render() : void
- Renders the widget at the bottom of the WooCommerce login form.
- creationell_captcha_wc_login_verify() : mixed
- Verifies the captcha on a WooCommerce my-account login submission.
- creationell_captcha_wc_registration_active() : bool
- Whether the WooCommerce registration protection is active.
- creationell_captcha_wc_registration_render() : void
- Renders the widget at the bottom of the WooCommerce registration form.
- creationell_captcha_wc_registration_verify() : mixed
- Verifies the captcha during WooCommerce my-account registration.
- creationell_captcha_wc_lost_password_active() : bool
- Whether the WooCommerce lost-password render is active.
- creationell_captcha_wc_lost_password_render() : void
- Renders the widget inside the WooCommerce lost-password form.
- creationell_captcha_wpforms_active() : bool
- Whether the WPForms integration is active.
- creationell_captcha_wpforms_inject() : void
- Auto-injects the widget directly before the WPForms submit button.
- creationell_captcha_wpforms_verify() : void
- Verifies the captcha on a WPForms submission.
- creationell_captcha_interceptor_inject_buffer_start() : void
- Conditionally starts the output buffer on template_redirect priority 0.
- creationell_captcha_interceptor_inject_buffer() : string
- Buffer callback. Replaces every `<form …>…</form>` with the same form plus an `<altcha-widget>` inserted directly before `</form>`. Idempotent — forms that already contain `<altcha-widget` are returned unchanged.
- creationell_captcha_run_interceptor() : void
- Runs the request interceptor. Hooked on `init` at priority 1 so it fires before any form-processing handler.
- creationell_captcha_protect_path() : void
- Registers one or more path patterns to be guarded by the interceptor.
- creationell_captcha_activate() : void
- Runs on plugin activation: seeds default options and HMAC secrets.
- creationell_captcha_deactivate() : void
- Runs on plugin deactivation: clears scheduled cron slots and lets every module react via the `creationell_captcha_deactivated` action hook.
- creationell_captcha_run_rate_limiter() : void
- Runs the per-IP rate limiter. Hooked on `init` at priority 0; registered after the firewall so the firewall runs first.
- creationell_captcha_register_rest_routes() : void
- Registers the public challenge route.
- creationell_captcha_rest_challenge() : WP_REST_Response
- Returns a fresh, single-use challenge. Records the issuance via the standard event channel — aggregate counters always increment, the detail-log entry is gated by the `log_challenge` per-type toggle from Modul 11c.
- creationell_captcha_canonical_params_json() : string
- Canonical-JSON serialisation of ALTCHA challenge parameters, byte- identical to `altcha-lib-php`'s `ChallengeParameters::toCanonicalJson()` (= ksort top-level + recursive ksort on assoc sub-arrays, JSON-encoded with UNESCAPED_SLASHES | UNESCAPED_UNICODE, null keys dropped).
- creationell_captcha_canonical_sort_recursive() : void
- Recursive helper used by `canonical_params_json` — mirrors the lib's `sortRecursive`. List arrays (sequential integer keys) keep their order; associative arrays get `ksort`-ed in place.
- creationell_captcha_list_setting_keys() : array<int, string>
- Setting keys whose value is a list (every `textarea` field).
- creationell_captcha_export_settings() : array<string, mixed>
- Builds the settings-export payload.
- creationell_captcha_import_settings() : array<string, mixed>|WP_Error
- Validates and applies a settings-export payload.
- creationell_captcha_reset_settings() : void
- Full factory reset: writes the complete default settings array, which also empties every list. Secrets, analytics counters and the event log are left untouched.
- creationell_captcha_load_default_settings() : void
- Resets every non-list setting to its default while preserving the current list values (IP block/allow, UA block, interceptor paths).
- creationell_captcha_admin_tabs() : array<string, string>
- Ordered list of the admin settings tabs.
- creationell_captcha_admin_sections() : array<string, array<string, string>>
- Settings sections and the tab each one belongs to.
- creationell_captcha_settings_fields() : array<string, array<string, mixed>>
- Field specification for the captcha settings.
- creationell_captcha_register_settings() : void
- Registers the plugin setting, the per-tab sections and the fields.
- creationell_captcha_sanitize_settings() : array<string, mixed>
- Sanitises the settings array before it is stored.
- creationell_captcha_render_engine_section() : void
- Renders the description shown at the top of the Proof-of-Work-Engine section.
- creationell_captcha_render_widget_appearance_section() : void
- Renders the description shown at the top of the widget-appearance section.
- creationell_captcha_render_code_challenge_section() : void
- Renders the description shown at the top of the code-challenge section.
- creationell_captcha_render_core_forms_section() : void
- Renders the description shown at the top of the core-forms section.
- creationell_captcha_render_interceptor_section() : void
- Renders the description shown at the top of the interceptor section.
- creationell_captcha_render_form_plugins_section() : void
- Renders the description shown at the top of the form-plugins section.
- creationell_captcha_render_proxy_section() : void
- Renders the description shown at the top of the proxy section.
- creationell_captcha_render_bypass_section() : void
- Renders the description shown at the top of the bypass section.
- creationell_captcha_render_firewall_section() : void
- Renders the description shown at the top of the firewall section.
- creationell_captcha_render_ratelimit_section() : void
- Renders the description shown at the top of the rate-limiting section.
- creationell_captcha_render_underattack_section() : void
- Renders the description shown at the top of the under-attack section.
- creationell_captcha_render_underattack_appearance_section() : void
- Renders the description shown at the top of the under-attack appearance section.
- creationell_captcha_render_analytics_section() : void
- Renders the description shown at the top of the analytics section.
- creationell_captcha_render_email_section() : void
- Renders the description shown at the top of the email-protection section.
- creationell_captcha_render_field() : void
- Renders a single settings field.
- creationell_captcha_tools_redirect() : never
- Stores a one-shot admin notice and redirects back to the Werkzeuge page.
- creationell_captcha_tools_guard() : void
- Guards a tools action: requires manage_options and a valid nonce.
- creationell_captcha_handle_export_settings() : void
- Streams the current settings as a JSON download.
- creationell_captcha_handle_import_settings() : void
- Handles the settings-import upload.
- creationell_captcha_handle_reset_settings() : void
- Handles the full factory reset.
- creationell_captcha_handle_load_defaults() : void
- Handles "load defaults" (keeps the lists).
- creationell_captcha_handle_cloudflare_refresh() : void
- Triggers a manual Cloudflare-range refresh from the Werkzeuge page.
- creationell_captcha_handle_cloudflare_clear() : void
- Empties the cached Cloudflare-range option from the Werkzeuge page.
- creationell_captcha_register_tools_page() : void
- Registers the "Werkzeuge" submenu page under the CreaCaptcha menu.
- creationell_captcha_render_tools_notice() : void
- Renders the one-shot admin notice left behind by a tools action.
- creationell_captcha_render_tools_page() : void
- Renders the "Werkzeuge" page.
- creationell_captcha_render_cloudflare_status() : void
- Renders the Cloudflare-cache status block inside the Werkzeuge tool card.
- creationell_captcha_run_under_attack() : void
- Runs the under-attack interstitial gate for front-end page views. Hooked on `template_redirect` — fires only for front-end requests, so wp-admin, wp-login.php, REST and cron are inherently exempt.
- creationell_captcha_maybe_upgrade() : void
- Runs schema migrations when the stored version differs from the running one.
- creationell_captcha_migrate_widget_mode() : void
- Migrates the legacy `widget_mode` setting (Modul 11a) to the new `widget_display` + `widget_auto_trigger` pair (Modul 14). Idempotent — if `widget_display` is already present in the stored option, the migration is skipped.
- creationell_captcha_register_assets() : void
- Registers the widget script and — for Argon2id — its worker registration.
- creationell_captcha_build_widget_markup() : string
- Builds the ALTCHA widget markup as a plain string. Enqueues the widget script as a side effect.
- creationell_captcha_render_widget() : void
- Renders the ALTCHA widget markup and enqueues its assets.
- creationell_captcha_verify_payload() : bool
- Verifies a raw base64 ALTCHA payload string.
- creationell_captcha_verify_request() : bool
- Reads and verifies the ALTCHA payload from the current POST request.
- creationell_captcha_widget() : void
- Public template tag — renders the ALTCHA widget.
- creationell_captcha_get_widget_markup() : string
- Returns the ALTCHA widget markup as a string.
- creationell_captcha_widget_shortcode() : string
- Shortcode handler for [creationell_captcha].
Constants
CREATIONELL_CAPTCHA_EXPORT_SCHEMA
Schema version of the settings-export format.
public
mixed
CREATIONELL_CAPTCHA_EXPORT_SCHEMA
= 1
CREATIONELL_CAPTCHA_LOCALE_MAP
Maps WordPress locales to the matching ALTCHA i18n locale bundle.
public
mixed
CREATIONELL_CAPTCHA_LOCALE_MAP
= [
// Deutsch
'de_DE' => 'de',
'de_DE_formal' => 'de',
'de_AT' => 'de',
'de_CH' => 'de',
'de_CH_informal' => 'de',
// Englisch
'en_US' => 'en',
'en_GB' => 'en',
'en_AU' => 'en',
'en_CA' => 'en',
'en_NZ' => 'en',
'en_ZA' => 'en',
// Französisch
'fr_FR' => 'fr-fr',
'fr_BE' => 'fr-fr',
'fr_LU' => 'fr-fr',
'fr_CH' => 'fr-fr',
'fr_CA' => 'fr-ca',
// Spanisch (Europa)
'es_ES' => 'es-es',
// Spanisch (LatAm — alle nach es-419)
'es_AR' => 'es-419',
'es_CL' => 'es-419',
'es_CO' => 'es-419',
'es_CR' => 'es-419',
'es_DO' => 'es-419',
'es_EC' => 'es-419',
'es_GT' => 'es-419',
'es_HN' => 'es-419',
'es_MX' => 'es-419',
'es_PA' => 'es-419',
'es_PE' => 'es-419',
'es_PR' => 'es-419',
'es_UY' => 'es-419',
'es_VE' => 'es-419',
// Portugiesisch
'pt_PT' => 'pt-pt',
'pt_AO' => 'pt-pt',
'pt_BR' => 'pt-br',
// Italienisch / Niederländisch / Polnisch
'it_IT' => 'it',
'nl_NL' => 'nl',
'nl_BE' => 'nl',
'pl_PL' => 'pl',
// Tschechisch / Slowakisch
'cs_CZ' => 'cs',
'sk_SK' => 'sk',
// Nordisch
'da_DK' => 'da',
'sv_SE' => 'sv',
'fi' => 'fi',
'nb_NO' => 'nb',
'nn_NO' => 'nb',
// Sonstige EU
'hu_HU' => 'hu',
'ro_RO' => 'ro',
'el' => 'el',
]
Keys are values returned by get_locale() — including the formal /
informal variants WP exposes (de_DE_formal, de_CH_informal). Values
are the exact locale codes used by the vendored ALTCHA bundles under
assets/js/altcha-i18n/<code>.js. Locales not in the map fall through
to the widget's own auto-detection (which itself falls back to English
since only the bundles enqueued by this plugin are registered).
Extend via the creationell_captcha_widget_locale_map filter rather
than patching this constant.
Functions
creationell_captcha_register_admin_menu()
Registers the top-level "CreaCaptcha" admin menu entry.
creationell_captcha_register_admin_menu() : void
creationell_captcha_render_settings_page()
Renders the tabbed settings page.
creationell_captcha_render_settings_page() : void
All tabs share one
creationell_captcha_render_trust_notice()
Renders the "proxy mode on but trust-set empty" admin notice on plugin pages.
creationell_captcha_render_trust_notice() : void
The notice is persistent (not dismissible) — it disappears automatically as soon as any trust source is configured.
creationell_captcha_tabbed_page_hooks()
Records and reports the admin-page hook suffixes of the plugin's tab-organised pages.
creationell_captcha_tabbed_page_hooks([mixed $add = null ]) : array<int, string>
A submenu page's hook suffix derives from the sanitised parent menu title, not its slug, so it cannot be reliably hardcoded. Each tabbed page passes the value WordPress returns from add_menu_page()/add_submenu_page() here, and the admin asset loader matches the current screen against the recorded set.
Parameters
- $add : mixed = null
-
Hook suffix to record; ignored unless a non-empty string.
Return values
array<int, string> —All recorded hook suffixes.
creationell_captcha_active_tab()
Determines the active tab from the request, whitelisted against $tabs.
creationell_captcha_active_tab(array<string, string> $tabs) : string
Falls back to the first tab when no valid tab query parameter is present.
The value only selects which panel is shown and is strictly whitelisted
against the given registry, so no nonce check is required.
Parameters
- $tabs : array<string, string>
-
Tab registry (id => label).
Return values
string —Active tab id.
creationell_captcha_render_nav_tabs()
Renders the no-JavaScript fallback style and the nav-tab bar.
creationell_captcha_render_nav_tabs(array<string, string> $tabs, string $active_tab, string $base_url) : void
Without JavaScript the per-tab panels would each be hidden by admin.css; the
Parameters
- $tabs : array<string, string>
-
Tab registry (id => label).
- $active_tab : string
-
Active tab id.
- $base_url : string
-
Page URL the tab links point at.
creationell_captcha_csv_cell()
Neutralises a CSV cell against spreadsheet formula injection.
creationell_captcha_csv_cell(string $value) : string
A value beginning with =, +, - or @ can be executed as a formula by Excel or LibreOffice; the path column carries attacker-controlled request URIs. A leading single quote forces the spreadsheet to treat the value as text.
Parameters
- $value : string
-
Raw cell value.
Return values
stringcreationell_captcha_export_events()
Streams the filtered event log as a CSV download.
creationell_captcha_export_events() : void
Hooked to admin-post.php. Requires the manage_options capability and a
valid nonce. The filter (search, event type, date range) is read from the
request via the shared parser, so the export mirrors the on-screen filter.
creationell_captcha_register_analytics_page()
Registers the "Statistik" submenu page under the CreaCaptcha menu.
creationell_captcha_register_analytics_page() : void
creationell_captcha_analytics_labels()
Human-readable labels for the seven event types.
creationell_captcha_analytics_labels() : array<string, string>
Return values
array<string, string>creationell_captcha_analytics_groups()
Thematic groups for the overview tab: title, explanation and the member event types with their short in-group labels.
creationell_captcha_analytics_groups() : array<int, array{title: string, description: string, types: array}>
Together the groups cover all seven event types exactly once. The long labels from creationell_captcha_analytics_labels() stay untouched for the filter dropdown, CSV export, CLI and history tab.
Return values
array<int, array{title: string, description: string, types: arraycreationell_captcha_analytics_tabs()
The three tabs of the analytics page.
creationell_captcha_analytics_tabs() : array<string, string>
Return values
array<string, string> —Tab id => visible label.
creationell_captcha_sum_recent_days()
Sums the $days most recent day buckets, per event type.
creationell_captcha_sum_recent_days(array<string, array<string, int>> $daily, int $days) : array<string, int>
Iterates today plus the ($days - 1) preceding days — the same window the 30-day history table walks.
Parameters
- $daily : array<string, array<string, int>>
-
Daily counters keyed by 'Y-m-d'.
- $days : int
-
Number of day buckets to sum.
Return values
array<string, int> —Event type => sum.
creationell_captcha_sum_recent_hours()
Sums the $hours most recent hour buckets, per event type.
creationell_captcha_sum_recent_hours(array<string, array<string, int>> $hourly, int $hours) : array<string, int>
Iterates the current hour plus the ($hours - 1) preceding hours.
Parameters
- $hourly : array<string, array<string, int>>
-
Hourly counters keyed by 'Y-m-d H'.
- $hours : int
-
Number of hour buckets to sum.
Return values
array<string, int> —Event type => sum.
creationell_captcha_render_analytics_page()
Renders the tabbed analytics dashboard page.
creationell_captcha_render_analytics_page() : void
creationell_captcha_render_analytics_overview()
Renders the "Übersicht" tab: four 24-hour KPI tiles and one four-window comparison table per thematic group.
creationell_captcha_render_analytics_overview() : void
creationell_captcha_render_analytics_history()
Renders the "Verlauf" tab: the day-by-day table for the last 30 days.
creationell_captcha_render_analytics_history() : void
creationell_captcha_events_query_args()
Reads and sanitises the event-log filter from the request.
creationell_captcha_events_query_args() : array{search: string, event_type: string, date_from: string, date_to: string}
Used by the "Ereignisse" tab and by the CSV export handler. The values only narrow a read-only query and are bound via $wpdb->prepare downstream, so no nonce check is required here; the page number is read separately by the tab.
Return values
array{search: string, event_type: string, date_from: string, date_to: string}creationell_captcha_render_analytics_events()
Renders the "Ereignisse" tab: filter toolbar, the event table with a detail link per row, the embedded event data and the detail modal.
creationell_captcha_render_analytics_events() : void
creationell_captcha_render_event_modal()
Renders the (initially hidden) event-detail modal skeleton.
creationell_captcha_render_event_modal() : void
The value cells carry a data-field matching the event record key; the modal
JavaScript fills them client-side from the embedded JSON map.
creationell_captcha_render_events_toolbar()
Renders the event-log filter toolbar: search, type filter, date range, the "Filtern"/"Zurücksetzen" controls and the CSV export link.
creationell_captcha_render_events_toolbar(array{search: string, event_type: string, date_from: string, date_to: string} $filter) : void
Parameters
- $filter : array{search: string, event_type: string, date_from: string, date_to: string}
-
Active filter.
creationell_captcha_render_events_pagination()
Renders the pagination navigation below the event-log table.
creationell_captcha_render_events_pagination(array{search: string, event_type: string, date_from: string, date_to: string} $filter, int $paged, int $total_pages) : void
Parameters
- $filter : array{search: string, event_type: string, date_from: string, date_to: string}
-
Active filter.
- $paged : int
-
Current page (1-based).
- $total_pages : int
-
Total page count.
creationell_captcha_analytics()
Returns the shared analytics recorder instance.
creationell_captcha_analytics() : Analytics
Return values
Analyticscreationell_captcha_record_event()
Records a security event of the given type.
creationell_captcha_record_event(string $type[, array<string, mixed> $context = [] ]) : void
Parameters
- $type : string
-
The event type.
- $context : array<string, mixed> = []
-
Optional caller-supplied context.
creationell_captcha_enqueue_admin_assets()
Enqueues admin styles and scripts on the CreaCaptcha admin pages.
creationell_captcha_enqueue_admin_assets(string $hook_suffix) : void
Parameters
- $hook_suffix : string
-
Current admin page hook suffix.
creationell_captcha_cloudflare_snapshot()
Returns the bundled Cloudflare snapshot.
creationell_captcha_cloudflare_snapshot() : array{v4: string[], v6: string[], updated_at: string}
Return values
array{v4: string[], v6: string[], updated_at: string}creationell_captcha_cloudflare_ranges()
The active CF range list: cached option (if fresh) → bundled snapshot.
creationell_captcha_cloudflare_ranges() : array<string|int, string>
The cached option is considered stale once it is older than 48 hours, shielding against a silently broken cron job.
Return values
array<string|int, string> —IPv4 and IPv6 CIDR ranges, merged.
creationell_captcha_refresh_cloudflare_ips_now()
Fetches the live Cloudflare ranges and writes them to the cache option.
creationell_captcha_refresh_cloudflare_ips_now() : array{ok: bool, v4: int, v6: int, fetched_at: int|null, error: string|null}
Return values
array{ok: bool, v4: int, v6: int, fetched_at: int|null, error: string|null}creationell_captcha_clear_cloudflare_cache()
Deletes the cached Cloudflare-range option. The next read falls back to the bundled snapshot. Returns true when the option existed and was deleted, false when the option was absent or the delete failed.
creationell_captcha_clear_cloudflare_cache() : bool
Return values
boolcreationell_captcha_fetch_cloudflare_list()
Fetches one Cloudflare endpoint and returns the valid CIDR entries.
creationell_captcha_fetch_cloudflare_list(string $url) : array<string|int, string>
Parameters
- $url : string
Return values
array<string|int, string>creationell_captcha_sync_cloudflare_cron()
Ensures the daily refresh cron slot is in sync with the auto-refresh toggle.
creationell_captcha_sync_cloudflare_cron() : void
Hooked on update_option_creationell_captcha_settings (fires on every
settings save). Deactivation cleanup is handled explicitly in
creationell_captcha_deactivate() to avoid re-scheduling the slot during
the deactivation handler.
creationell_captcha_render_code_image()
Renders a PNG of the given code and returns the raw bytes. Caller is responsible for emitting headers (`Content-Type: image/png`, `Cache-Control: no-store`) and the body.
creationell_captcha_render_code_image(string $code) : string
Falls back to GD's built-in bitmap font 5 if the vendored TTF is missing (logs a one-line warning so the operator sees the degradation).
Parameters
- $code : string
-
The code to render (4–8 chars expected; longer is trimmed implicitly by the width budget).
Return values
stringcreationell_captcha_should_issue_code_challenge()
Decides whether the current /challenge request should attach a code-challenge instruction. Returns true iff:
creationell_captcha_should_issue_code_challenge() : bool
- the master toggle is on, AND
- PHP-GD is available, AND
- at least one of the three trigger conditions matches (under-attack, ratelimit threshold, watch-list).
Return values
boolcreationell_captcha_code_charset()
Returns the active charset string for the configured option.
creationell_captcha_code_charset(string $charset_key) : string
Parameters
- $charset_key : string
-
One of: digits / alphanumeric / alphanumeric-no-confusing.
Return values
stringcreationell_captcha_generate_code()
Generates a fresh random code from the configured charset.
creationell_captcha_generate_code() : string
Return values
stringcreationell_captcha_code_token_issue()
Issues a token backed by a server-side WP transient that stores the expected code for at most $expiry_seconds. Returns the opaque ID that `/code-image` and `/code-verify` use to look the code up again.
creationell_captcha_code_token_issue(string $code, int $expiry_seconds) : string
The code is intentionally NOT encoded into the token itself — a base64 round-trip would leak the code to anyone who can read the network response (defeats the OCR-resistant captcha goal). Server state via WP transients is the accepted trade-off.
Parameters
- $code : string
-
The expected code (already from generator).
- $expiry_seconds : int
-
Seconds until the token expires.
Return values
stringcreationell_captcha_code_token_verify()
Looks up the code for a token and returns it, or null on: - malformed token (not 32 hex chars) - missing transient (expired or unknown)
creationell_captcha_code_token_verify(string $token[, bool $consume = false ]) : string|null
Parameters
- $token : string
-
The 32-hex-char ID from
code_token_issue. - $consume : bool = false
-
Delete the transient after successful lookup (single-use semantics). The /code-image handler passes false; /code-verify passes true ONLY after a successful code match so retries on wrong input still work.
Return values
string|nullcreationell_captcha_rest_code_image()
Handles GET /code-image?t=<token>. Looks up the code from the token (server-side transient), renders the PNG, returns 410 on token failure.
creationell_captcha_rest_code_image(WP_REST_Request $request) : WP_REST_Response
Idempotent — the transient is NOT consumed here so the browser may reload the image.
Parameters
- $request : WP_REST_Request
-
The REST request. Required query parameter
t(opaque server-issued token).
Return values
WP_REST_Response —200 with image/png body on success; 410 when the
token is unknown/expired or PHP-GD is unavailable.
creationell_captcha_rest_code_verify()
Handles POST /code-verify. Two body shapes:
creationell_captcha_rest_code_verify(WP_REST_Request $request) : WP_REST_Response
-
Code-Challenge mode: { "code": "
", "payload": " " } The widget rendered a code-image because the /challenge response embedded data.ccode. Token lookup → case-insensitive match → single-use consume → fresh signed payload. -
Plain server-verify mode: { "payload": "
" } (no code) ALTCHA's widget posts here unconditionally whenever verifyUrl is set (see widget.js logic: verifyUrl ? _e() : verified()). Structural verify on the incoming payload + single-use replay guard on its signature + fresh signed payload back. The replay guard matters: without it a single solved PoW could be amplified into N fresh payloads, undercutting Engine::verify()'s per-form single-use protection.
Parameters
- $request : WP_REST_Request
-
The REST request with JSON body
{payload: string, code?: string}.
Return values
WP_REST_Response —200 on success ({payload, verified: true}); 400 on malformed body; 401 on wrong code; 410 on missing/expired/replayed payload or token; 500 on internal error.
creationell_captcha_register_code_challenge_routes()
Registers the two code-challenge REST routes. The /challenge handler itself stays in includes/rest.php; Task 11 extends it with the codeChallenge field and the data.ccode embed.
creationell_captcha_register_code_challenge_routes() : void
creationell_captcha_register_email_obfuscation()
Registers email obfuscation on `init`. The decoder script is always registered; then, unless the kill-switch is set or the feature is off, the configured mode is wired up — the content filters (module 7) or the full-page output buffer (module 8).
creationell_captcha_register_email_obfuscation() : void
creationell_captcha_register_email_buffer()
Wires up the full-page-buffer mode: on `template_redirect` for non-feed front-end requests it enqueues the decoder script and starts an output buffer whose callback obfuscates the page body at flush time.
creationell_captcha_register_email_buffer(EmailObfuscator $obfuscator) : void
Parameters
- $obfuscator : EmailObfuscator
-
The obfuscator.
creationell_captcha_run_firewall()
Runs the IP/user-agent firewall. Hooked on `init` at priority 0 so it fires before the rate limiter, the interceptor and any form-processing handler.
creationell_captcha_run_firewall() : void
creationell_captcha_comments_active()
Whether comment protection applies to the current request.
creationell_captcha_comments_active() : bool
Return values
boolcreationell_captcha_comments_render()
Injects the widget just above the comment form submit button.
creationell_captcha_comments_render(string $submit_field) : string
Parameters
- $submit_field : string
-
The submit button field HTML.
Return values
stringcreationell_captcha_comments_verify()
Verifies the captcha before a comment is accepted.
creationell_captcha_comments_verify(array<string, mixed> $commentdata) : array<string, mixed>
Parameters
- $commentdata : array<string, mixed>
-
Comment data.
Return values
array<string, mixed>creationell_captcha_login_enabled()
Whether login protection is enabled.
creationell_captcha_login_enabled() : bool
Return values
boolcreationell_captcha_login_render()
Renders the widget inside the login form.
creationell_captcha_login_render() : void
creationell_captcha_login_verify()
Verifies the captcha during an interactive login.
creationell_captcha_login_verify(WP_User|WP_Error|null $user, string $username, string $password) : WP_User|WP_Error|null
Parameters
- $user : WP_User|WP_Error|null
-
Authenticated user or error.
- $username : string
-
Submitted username.
- $password : string
-
Submitted password.
Return values
WP_User|WP_Error|nullcreationell_captcha_password_reset_enabled()
Whether password-reset protection is enabled.
creationell_captcha_password_reset_enabled() : bool
Return values
boolcreationell_captcha_password_reset_render()
Renders the widget inside the lost-password form.
creationell_captcha_password_reset_render() : void
creationell_captcha_password_reset_verify()
Verifies the captcha during a password-reset request.
creationell_captcha_password_reset_verify(WP_Error $errors) : void
Parameters
- $errors : WP_Error
-
Password-reset errors (passed by WordPress >= 5.4).
creationell_captcha_registration_enabled()
Whether registration protection is enabled.
creationell_captcha_registration_enabled() : bool
Return values
boolcreationell_captcha_registration_render()
Renders the widget inside the registration form.
creationell_captcha_registration_render() : void
creationell_captcha_registration_verify()
Verifies the captcha during registration.
creationell_captcha_registration_verify(WP_Error $errors, string $sanitized_user_login, string $user_email) : WP_Error
Parameters
- $errors : WP_Error
-
Registration errors.
- $sanitized_user_login : string
-
Submitted user login.
- $user_email : string
-
Submitted user email.
Return values
WP_Errorcreationell_captcha_resolve_widget_locale()
Resolves the active WordPress locale to a vendored ALTCHA locale code.
creationell_captcha_resolve_widget_locale() : string|null
Returns the locale string (e.g. "de", "fr-fr", "pt-br") if a mapping exists, or null when the WP locale is not in the vendor set — in which case the widget renderer skips both the language attribute and the i18n script enqueue, letting the widget fall through to its own detection (which has only the EN built-in available).
Two filters are applied: creationell_captcha_widget_locale_map to
extend / override the lookup table, and
creationell_captcha_widget_locale for last-mile overrides after
lookup.
Tags
Return values
string|null —Vendored ALTCHA locale code or null.
creationell_captcha_get_default_settings()
Default plugin settings.
creationell_captcha_get_default_settings() : array<string, mixed>
Return values
array<string, mixed>creationell_captcha_get_settings()
Current plugin settings, merged over the defaults.
creationell_captcha_get_settings([bool $force_refresh = false ]) : array<string, mixed>
Memoised for the duration of the request — get_option() itself is cheap thanks to WP's object cache, but the defaults-merge over ~70 keys adds up across the 10+ call sites per request (Interceptor, Firewall, Rate- Limiter, Under-Attack, every form integration). The cache is invalidated automatically when the option is added, updated or deleted.
Parameters
- $force_refresh : bool = false
-
Re-read from the DB even if a cached copy exists. Used by the invalidation hook.
Return values
array<string, mixed>creationell_captcha_invalidate_settings_cache()
Drops the in-request settings cache. Wired to the option-change hooks below so callers that read settings after an update see the fresh value.
creationell_captcha_invalidate_settings_cache() : void
creationell_captcha_is_disabled()
Whether the captcha is globally disabled via the wp-config constant.
creationell_captcha_is_disabled() : bool
Return values
boolcreationell_captcha_sodium_available()
Whether ext-sodium (required for Argon2id) is available.
creationell_captcha_sodium_available() : bool
Return values
boolcreationell_captcha_generate_secrets()
Generates both HMAC secrets and persists them (non-autoloaded).
creationell_captcha_generate_secrets() : array{signature: string, key_signature: string}
Return values
array{signature: string, key_signature: string}creationell_captcha_get_secret()
Returns a stored HMAC secret, generating + persisting it on first use.
creationell_captcha_get_secret(string $which) : string
Parameters
- $which : string
-
Either 'signature' or 'key_signature'.
Return values
stringcreationell_captcha_get_hmac_secret()
The HMAC signature secret (signs each challenge).
creationell_captcha_get_hmac_secret() : string
A wp-config constant takes precedence over the stored option.
Return values
stringcreationell_captcha_get_hmac_key_secret()
The HMAC key-signature secret (enables the fast verification path).
creationell_captcha_get_hmac_key_secret() : string
A wp-config constant takes precedence over the stored option.
Return values
stringcreationell_captcha_engine()
Shared captcha engine instance.
creationell_captcha_engine() : Engine
Return values
Enginecreationell_captcha_log()
Write a message to the debug log when CREATIONELL_CAPTCHA_DEBUG is active.
creationell_captcha_log(string $message) : void
Parameters
- $message : string
-
Message to log.
creationell_captcha_get_client_ip()
Resolves the client IP address.
creationell_captcha_get_client_ip() : string
Returns the validated REMOTE_ADDR by default. When the firewall_behind_proxy
setting is on, the configured forwarded header is used instead — falling back
to REMOTE_ADDR if it yields no valid IP.
Return values
stringcreationell_captcha_ip_in_list()
Whether an IP matches any entry in a list of IPs or CIDR ranges.
creationell_captcha_ip_in_list(string $ip, mixed $list) : bool
Parameters
- $ip : string
-
The client IP.
- $list : mixed
-
A list of IPs / CIDR ranges (non-arrays are ignored).
Return values
boolcreationell_captcha_ip_in_cidr()
Whether an IP falls within a CIDR range. Supports IPv4 and IPv6.
creationell_captcha_ip_in_cidr(string $ip, string $cidr) : bool
Parameters
- $ip : string
-
The client IP.
- $cidr : string
-
A CIDR range, e.g. "203.0.113.0/24".
Return values
boolcreationell_captcha_is_valid_ip_or_cidr()
Whether a string is a valid IP address or CIDR range (IPv4 or IPv6).
creationell_captcha_is_valid_ip_or_cidr(string $entry) : bool
Parameters
- $entry : string
-
The candidate string.
Return values
boolcreationell_captcha_wildcard_match()
Whether a subject matches any of the given wildcard patterns (case-insensitive).
creationell_captcha_wildcard_match(string $subject, mixed $patterns) : bool
The pattern alphabet is the same as the firewall UA-blocklist: * is the
single wildcard, everything else is matched literally.
Parameters
- $subject : string
-
The string to test.
- $patterns : mixed
-
A list of patterns; non-arrays return false.
Return values
boolcreationell_captcha_private_ranges()
Returns the canonical list of private/loopback CIDR ranges used when the `firewall_trust_private_ranges` toggle is active.
creationell_captcha_private_ranges() : array<string|int, string>
Return values
array<string|int, string>creationell_captcha_trusted_proxies_constant()
Reads the optional `CREATIONELL_CAPTCHA_TRUSTED_PROXIES` wp-config constant as a list. Accepts either a string array or a comma/whitespace-separated scalar; invalid entries are dropped.
creationell_captcha_trusted_proxies_constant() : array<string|int, string>
Return values
array<string|int, string>creationell_captcha_is_trusted_proxy()
Whether the given IP belongs to a trusted upstream proxy.
creationell_captcha_is_trusted_proxy(string $ip) : bool
Sources are checked in this order; the first match wins:
- firewall_trusted_proxies (the explicit textarea list)
- CREATIONELL_CAPTCHA_TRUSTED_PROXIES (wp-config constant)
- firewall_trust_private_ranges (when on): the private/loopback ranges
- firewall_trust_cloudflare (when on): the cached/bundled CF ranges
Parameters
- $ip : string
-
A validated client IP address.
Return values
boolcreationell_captcha_evaluate_bypass()
Pure bypass evaluator — checks the three bypass sources against the supplied inputs without touching $_SERVER, $_COOKIE or any static cache. The caller is responsible for providing the values.
creationell_captcha_evaluate_bypass(string|null $ip, string|null $ua, array<string, string> $cookies) : array{reason: string, source: string}|false
Sources are checked in this order; the first match wins:
- firewall_ip_allow vs $ip
- bypass_ua_allow vs $ua
- bypass_cookies vs $cookies (strict name=value)
Parameters
- $ip : string|null
-
Client IP, or null to skip the IP check.
- $ua : string|null
-
User-Agent, or null to skip the UA check.
- $cookies : array<string, string>
-
Cookie map (name => value).
Return values
array{reason: string, source: string}|falsecreationell_captcha_request_bypassed()
Whether the current request is allowed to bypass captcha, under-attack and firewall protections. Reads $_SERVER, $_COOKIE and the request's client IP, then delegates to `creationell_captcha_evaluate_bypass()`.
creationell_captcha_request_bypassed() : array{reason: string, source: string}|false
Result is memoised for the request — settings, IP and cookies do not change
within a single PHP request. Only reason flows into the event-log context;
source is exposed for diagnostic logging by callers.
Return values
array{reason: string, source: string}|falsecreationell_captcha_validate_action_pattern()
Validates a single interceptor-action pattern.
creationell_captcha_validate_action_pattern(string $entry) : string|null
Allowed: lowercase/uppercase letters, digits, _, -, * (wildcard),
with an optional leading ! for exclusion patterns. Empty input or
patterns of only ! are rejected.
Parameters
- $entry : string
-
Raw entry (already trimmed by the caller).
Return values
string|null —Normalised entry, or null if invalid.
creationell_captcha_validate_cookie_entry()
Validates a single bypass-cookie entry of the form `name=value`.
creationell_captcha_validate_cookie_entry(string $entry) : string|null
Name must be alphanumeric, _ or -. Value may be empty and is
length-capped to 200 bytes. The returned entry has the value passed
through sanitize_text_field().
Parameters
- $entry : string
-
Raw entry (already trimmed by the caller).
Return values
string|null —Normalised name=value entry, or null if invalid.
creationell_captcha_anonymize_ip()
Truncates an IP for DSGVO-compliant storage. IPv4 → last octet zeroed, IPv6 → last 80 bits zeroed. Invalid IPs return ''.
creationell_captcha_anonymize_ip(string $ip) : string
Parameters
- $ip : string
-
A validated client IP address.
Return values
stringcreationell_captcha_request_body_fingerprint()
Returns a JSON-encoded fingerprint of $_POST: { field-name: value-byte-length }.
creationell_captcha_request_body_fingerprint() : string
No values are recorded — only structural metadata for attack-pattern
diagnosis. Field names that contain known sensitive substrings (password,
iban, api_key, …) are replaced with [masked:<8-char-sha256>] so the
fingerprint does not leak custom-form schema (e.g. bank_iban_input).
Output is length-capped to 2048 bytes; if longer, the JSON is collapsed
to "}" rather than truncated mid-entry.
Return values
stringcreationell_captcha_block_response()
Sends a fail-closed block response and terminates the request.
creationell_captcha_block_response(int $status, string $message[, int $retry_after = 0 ]) : void
Parameters
- $status : int
-
HTTP status code (403 firewall, 429 rate limit).
- $message : string
-
The message shown to the client.
- $retry_after : int = 0
-
Optional Retry-After value in seconds.
creationell_captcha_base64url_encode()
Base64URL encoder (RFC 4648 §5) — strips standard-base64 padding and replaces +/ with -_ so the value is URL-safe.
creationell_captcha_base64url_encode(string $bytes) : string
Parameters
- $bytes : string
-
Raw bytes to encode.
Return values
stringcreationell_captcha_base64url_decode()
Base64URL decoder — accepts unpadded URL-safe input and returns the raw bytes. Returns the empty string on malformed input (no exceptions).
creationell_captcha_base64url_decode(string $encoded) : string
Parameters
- $encoded : string
-
URL-safe base64 string.
Return values
stringcreationell_captcha_ratelimit_current_count()
Reads the current rate-limit counter for an IP without incrementing it.
creationell_captcha_ratelimit_current_count(string $ip) : int
Uses the same bucket key as Creationell\Captcha\RateLimiter::run() so the
value matches what the run-loop would see. Returns 0 if no transient exists
for the current window.
Parameters
- $ip : string
-
Client IP (call
creationell_captcha_get_client_ip()).
Return values
intcreationell_captcha_cf7_active()
Whether the Contact Form 7 integration is active.
creationell_captcha_cf7_active() : bool
Return values
boolcreationell_captcha_cf7_register_tag()
Registers the [creationell_captcha] Contact Form 7 form-tag.
creationell_captcha_cf7_register_tag() : void
Registered unconditionally (no creationell_captcha_cf7_active() guard) so CF7 always recognises the tag and never prints it as raw text; the tag handler returns an empty string when the integration is inactive.
creationell_captcha_cf7_tag_handler()
Renders the widget for the [creationell_captcha] form-tag.
creationell_captcha_cf7_tag_handler() : string
Return values
stringcreationell_captcha_cf7_auto_inject()
Auto-injects the widget into CF7 forms without a [creationell_captcha] tag.
creationell_captcha_cf7_auto_inject(string $elements) : string
Parameters
- $elements : string
-
The form's inner HTML.
Return values
stringcreationell_captcha_cf7_verify()
Verifies the captcha on a Contact Form 7 submission.
creationell_captcha_cf7_verify(mixed $spam, mixed $submission) : bool
Hooked on wpcf7_spam: returning true marks the submission as spam, which
CF7 then rejects through its standard flow.
Parameters
- $spam : mixed
-
Whether CF7 already classified the submission as spam.
- $submission : mixed
-
The WPCF7_Submission object.
Return values
boolcreationell_captcha_forminator_active()
Whether the Forminator integration is active.
creationell_captcha_forminator_active() : bool
Return values
boolcreationell_captcha_forminator_inject()
Auto-injects the widget before the submit button of a Forminator custom form.
creationell_captcha_forminator_inject(mixed $html, mixed $form_id) : string
The forminator_render_form_submit_markup filter also fires for polls and
quizzes; injection is restricted to the forminator_forms post type.
Parameters
- $html : mixed
-
The submit-section HTML.
- $form_id : mixed
-
The form's post ID.
Return values
stringcreationell_captcha_forminator_verify()
Verifies the captcha on a Forminator custom-form submission.
creationell_captcha_forminator_verify(mixed $errors) : array<int, array<string, string>>
Hooked on forminator_custom_form_submit_errors (custom forms only): a
non-empty errors array makes Forminator reject the submission.
Parameters
- $errors : mixed
-
The current array of submission errors.
Return values
array<int, array<string, string>>creationell_captcha_woocommerce_active()
Whether any WooCommerce protection applies right now.
creationell_captcha_woocommerce_active() : bool
Shared gate that the per-form predicates _wc_*_active() route through —
encapsulates the kill-switch, the class_exists check and the master
toggle so each form predicate just needs to add its own sub-toggle check.
Return values
boolcreationell_captcha_wc_checkout_active()
Whether the WooCommerce checkout protection is active.
creationell_captcha_wc_checkout_active() : bool
Return values
boolcreationell_captcha_wc_checkout_render()
Renders the widget directly before the Place-Order button on the checkout.
creationell_captcha_wc_checkout_render() : void
creationell_captcha_wc_checkout_verify()
Verifies the captcha during checkout validation.
creationell_captcha_wc_checkout_verify(array<string, mixed> $data, mixed $errors) : void
woocommerce_after_checkout_validation fires inside WooCommerce's
process_checkout() after all other validation has run; adding an error
to the passed-through WP_Error aborts the order.
Parameters
- $data : array<string, mixed>
-
Posted checkout data (unused).
- $errors : mixed
-
The checkout
WP_Error(passed by reference of the object).
creationell_captcha_wc_login_active()
Whether the WooCommerce my-account login protection is active.
creationell_captcha_wc_login_active() : bool
Return values
boolcreationell_captcha_wc_login_render()
Renders the widget at the bottom of the WooCommerce login form.
creationell_captcha_wc_login_render() : void
creationell_captcha_wc_login_verify()
Verifies the captcha on a WooCommerce my-account login submission.
creationell_captcha_wc_login_verify(mixed $validation_error, string $username, string $password) : mixed
Returns a WP_Error to fail the login; otherwise returns the incoming
$validation_error value unchanged (so other filters can keep working).
Parameters
- $validation_error : mixed
-
The current validation error (
WP_Error|null|false). - $username : string
-
Submitted username (unused).
- $password : string
-
Submitted password (unused).
creationell_captcha_wc_registration_active()
Whether the WooCommerce registration protection is active.
creationell_captcha_wc_registration_active() : bool
Return values
boolcreationell_captcha_wc_registration_render()
Renders the widget at the bottom of the WooCommerce registration form.
creationell_captcha_wc_registration_render() : void
creationell_captcha_wc_registration_verify()
Verifies the captcha during WooCommerce my-account registration.
creationell_captcha_wc_registration_verify(mixed $errors, string $username, string $email) : mixed
Parameters
- $errors : mixed
-
The current
WP_Errorcarrier from WooCommerce. - $username : string
-
Submitted username (unused).
- $email : string
-
Submitted email (unused).
creationell_captcha_wc_lost_password_active()
Whether the WooCommerce lost-password render is active.
creationell_captcha_wc_lost_password_active() : bool
Return values
boolcreationell_captcha_wc_lost_password_render()
Renders the widget inside the WooCommerce lost-password form.
creationell_captcha_wc_lost_password_render() : void
creationell_captcha_wpforms_active()
Whether the WPForms integration is active.
creationell_captcha_wpforms_active() : bool
Return values
boolcreationell_captcha_wpforms_inject()
Auto-injects the widget directly before the WPForms submit button.
creationell_captcha_wpforms_inject(array<string, mixed> $form_data, mixed $form) : void
Fires inside the
Parameters
- $form_data : array<string, mixed>
-
WPForms form configuration.
- $form : mixed
-
WPForms form post (unused).
creationell_captcha_wpforms_verify()
Verifies the captcha on a WPForms submission.
creationell_captcha_wpforms_verify(array<int, mixed> $fields, array<string, mixed> $entry, array<string, mixed> $form_data) : void
Hooked on wpforms_process (action). On failure we set an entry in
wpforms()->process->errors[ $form_id ]['header'] — WPForms then renders
the message above the form and refuses to save the entry.
Parameters
- $fields : array<int, mixed>
-
Sanitized field values (unused).
- $entry : array<string, mixed>
-
Raw
$_POST['wpforms'](unused). - $form_data : array<string, mixed>
-
Form configuration.
creationell_captcha_interceptor_inject_buffer_start()
Conditionally starts the output buffer on template_redirect priority 0.
creationell_captcha_interceptor_inject_buffer_start() : void
The buffer only runs when (a) the master interceptor toggle is on, (b) at least one inject path is configured, AND (c) the current request path matches that pattern list. On non-matching pages the request is unaffected.
creationell_captcha_interceptor_inject_buffer()
Buffer callback. Replaces every `<form …>…</form>` with the same form plus an `<altcha-widget>` inserted directly before `</form>`. Idempotent — forms that already contain `<altcha-widget` are returned unchanged.
creationell_captcha_interceptor_inject_buffer(string $html) : string
Parameters
- $html : string
-
Full page HTML.
Return values
stringcreationell_captcha_run_interceptor()
Runs the request interceptor. Hooked on `init` at priority 1 so it fires before any form-processing handler.
creationell_captcha_run_interceptor() : void
creationell_captcha_protect_path()
Registers one or more path patterns to be guarded by the interceptor.
creationell_captcha_protect_path(string|array<int, string> $patterns) : void
Developer API — later form-plugin integrations call this to protect their
submission endpoints without an admin entering patterns by hand. The
patterns are merged into the creationell_captcha_interceptor_paths filter.
Parameters
- $patterns : string|array<int, string>
-
A path pattern or list of patterns.
creationell_captcha_activate()
Runs on plugin activation: seeds default options and HMAC secrets.
creationell_captcha_activate() : void
creationell_captcha_deactivate()
Runs on plugin deactivation: clears scheduled cron slots and lets every module react via the `creationell_captcha_deactivated` action hook.
creationell_captcha_deactivate() : void
creationell_captcha_run_rate_limiter()
Runs the per-IP rate limiter. Hooked on `init` at priority 0; registered after the firewall so the firewall runs first.
creationell_captcha_run_rate_limiter() : void
creationell_captcha_register_rest_routes()
Registers the public challenge route.
creationell_captcha_register_rest_routes() : void
creationell_captcha_rest_challenge()
Returns a fresh, single-use challenge. Records the issuance via the standard event channel — aggregate counters always increment, the detail-log entry is gated by the `log_challenge` per-type toggle from Modul 11c.
creationell_captcha_rest_challenge(WP_REST_Request $request) : WP_REST_Response
Parameters
- $request : WP_REST_Request
-
The REST request. Optional query parameter
ctx(HMAC token, used by the under-attack interstitial to suppress the code-challenge attachment).
Return values
WP_REST_Response —JSON challenge envelope with algorithm, challenge,
salt, signature, parameters and optional
codeChallenge.image URL.
creationell_captcha_canonical_params_json()
Canonical-JSON serialisation of ALTCHA challenge parameters, byte- identical to `altcha-lib-php`'s `ChallengeParameters::toCanonicalJson()` (= ksort top-level + recursive ksort on assoc sub-arrays, JSON-encoded with UNESCAPED_SLASHES | UNESCAPED_UNICODE, null keys dropped).
creationell_captcha_canonical_params_json(array<string, mixed> $params) : string
Needed for the re-sign step in Modul 15's /challenge handler after we mutate parameters.data.ccode.
Parameters
- $params : array<string, mixed>
-
Parameter array from
create_challenge().
Return values
stringcreationell_captcha_canonical_sort_recursive()
Recursive helper used by `canonical_params_json` — mirrors the lib's `sortRecursive`. List arrays (sequential integer keys) keep their order; associative arrays get `ksort`-ed in place.
creationell_captcha_canonical_sort_recursive(array<string|int, mixed> &$data) : void
Parameters
- $data : array<string|int, mixed>
creationell_captcha_list_setting_keys()
Setting keys whose value is a list (every `textarea` field).
creationell_captcha_list_setting_keys() : array<int, string>
Derived from the field specification so the list never drifts. "Load defaults" preserves these keys; "reset" clears them.
Return values
array<int, string>creationell_captcha_export_settings()
Builds the settings-export payload.
creationell_captcha_export_settings() : array<string, mixed>
The HMAC secrets are deliberately excluded — they must never leave the site.
Return values
array<string, mixed>creationell_captcha_import_settings()
Validates and applies a settings-export payload.
creationell_captcha_import_settings(array<string, mixed> $payload) : array<string, mixed>|WP_Error
The settings array is run through creationell_captcha_sanitize_settings(),
so the same guarantees as the settings form apply: whitelisted selects,
clamped numbers, bounded lists, unknown keys dropped, missing keys defaulted.
Parameters
- $payload : array<string, mixed>
-
Decoded export payload.
Return values
array<string, mixed>|WP_Error —On success: { imported, version_notice }.
creationell_captcha_reset_settings()
Full factory reset: writes the complete default settings array, which also empties every list. Secrets, analytics counters and the event log are left untouched.
creationell_captcha_reset_settings() : void
creationell_captcha_load_default_settings()
Resets every non-list setting to its default while preserving the current list values (IP block/allow, UA block, interceptor paths).
creationell_captcha_load_default_settings() : void
creationell_captcha_admin_tabs()
Ordered list of the admin settings tabs.
creationell_captcha_admin_tabs() : array<string, string>
The array key is the tab id; it doubles as the suffix of the Settings-API
page slug (creationell-captcha-tab-<id>) that do_settings_sections() uses.
Return values
array<string, string> —Tab id => visible label.
creationell_captcha_admin_sections()
Settings sections and the tab each one belongs to.
creationell_captcha_admin_sections() : array<string, array<string, string>>
Section order within a tab follows this array's order.
Return values
array<string, array<string, string>> —Section id => { tab, title, callback }.
creationell_captcha_settings_fields()
Field specification for the captcha settings.
creationell_captcha_settings_fields() : array<string, array<string, mixed>>
Every field carries a section key naming the section (and thereby the tab)
it renders in; the section ids match creationell_captcha_admin_sections().
Return values
array<string, array<string, mixed>>creationell_captcha_register_settings()
Registers the plugin setting, the per-tab sections and the fields.
creationell_captcha_register_settings() : void
creationell_captcha_sanitize_settings()
Sanitises the settings array before it is stored.
creationell_captcha_sanitize_settings(mixed $input) : array<string, mixed>
Parameters
- $input : mixed
-
Raw input from the settings form.
Return values
array<string, mixed>creationell_captcha_render_engine_section()
Renders the description shown at the top of the Proof-of-Work-Engine section.
creationell_captcha_render_engine_section() : void
creationell_captcha_render_widget_appearance_section()
Renders the description shown at the top of the widget-appearance section.
creationell_captcha_render_widget_appearance_section() : void
creationell_captcha_render_code_challenge_section()
Renders the description shown at the top of the code-challenge section.
creationell_captcha_render_code_challenge_section() : void
Includes a warning notice when the PHP-GD extension is missing — without it, image rendering cannot work and the trigger logic stays disabled.
creationell_captcha_render_core_forms_section()
Renders the description shown at the top of the core-forms section.
creationell_captcha_render_core_forms_section() : void
creationell_captcha_render_interceptor_section()
Renders the description shown at the top of the interceptor section.
creationell_captcha_render_interceptor_section() : void
creationell_captcha_render_form_plugins_section()
Renders the description shown at the top of the form-plugins section.
creationell_captcha_render_form_plugins_section() : void
When no supported form plugin is active the section has no fields, so the description doubles as a hint.
creationell_captcha_render_proxy_section()
Renders the description shown at the top of the proxy section.
creationell_captcha_render_proxy_section() : void
creationell_captcha_render_bypass_section()
Renders the description shown at the top of the bypass section.
creationell_captcha_render_bypass_section() : void
creationell_captcha_render_firewall_section()
Renders the description shown at the top of the firewall section.
creationell_captcha_render_firewall_section() : void
creationell_captcha_render_ratelimit_section()
Renders the description shown at the top of the rate-limiting section.
creationell_captcha_render_ratelimit_section() : void
creationell_captcha_render_underattack_section()
Renders the description shown at the top of the under-attack section.
creationell_captcha_render_underattack_section() : void
creationell_captcha_render_underattack_appearance_section()
Renders the description shown at the top of the under-attack appearance section.
creationell_captcha_render_underattack_appearance_section() : void
creationell_captcha_render_analytics_section()
Renders the description shown at the top of the analytics section.
creationell_captcha_render_analytics_section() : void
creationell_captcha_render_email_section()
Renders the description shown at the top of the email-protection section.
creationell_captcha_render_email_section() : void
creationell_captcha_render_field()
Renders a single settings field.
creationell_captcha_render_field(array<string, mixed> $args) : void
Parameters
- $args : array<string, mixed>
-
Field arguments (key + field spec).
creationell_captcha_tools_redirect()
Stores a one-shot admin notice and redirects back to the Werkzeuge page.
creationell_captcha_tools_redirect(string $type, string $message) : never
Parameters
- $type : string
-
'success' or 'error'.
- $message : string
-
Notice text.
Return values
nevercreationell_captcha_tools_guard()
Guards a tools action: requires manage_options and a valid nonce.
creationell_captcha_tools_guard(string $action) : void
Parameters
- $action : string
-
The nonce action name.
creationell_captcha_handle_export_settings()
Streams the current settings as a JSON download.
creationell_captcha_handle_export_settings() : void
creationell_captcha_handle_import_settings()
Handles the settings-import upload.
creationell_captcha_handle_import_settings() : void
creationell_captcha_handle_reset_settings()
Handles the full factory reset.
creationell_captcha_handle_reset_settings() : void
creationell_captcha_handle_load_defaults()
Handles "load defaults" (keeps the lists).
creationell_captcha_handle_load_defaults() : void
creationell_captcha_handle_cloudflare_refresh()
Triggers a manual Cloudflare-range refresh from the Werkzeuge page.
creationell_captcha_handle_cloudflare_refresh() : void
creationell_captcha_handle_cloudflare_clear()
Empties the cached Cloudflare-range option from the Werkzeuge page.
creationell_captcha_handle_cloudflare_clear() : void
creationell_captcha_register_tools_page()
Registers the "Werkzeuge" submenu page under the CreaCaptcha menu.
creationell_captcha_register_tools_page() : void
creationell_captcha_render_tools_notice()
Renders the one-shot admin notice left behind by a tools action.
creationell_captcha_render_tools_notice() : void
creationell_captcha_render_tools_page()
Renders the "Werkzeuge" page.
creationell_captcha_render_tools_page() : void
creationell_captcha_render_cloudflare_status()
Renders the Cloudflare-cache status block inside the Werkzeuge tool card.
creationell_captcha_render_cloudflare_status() : void
creationell_captcha_run_under_attack()
Runs the under-attack interstitial gate for front-end page views. Hooked on `template_redirect` — fires only for front-end requests, so wp-admin, wp-login.php, REST and cron are inherently exempt.
creationell_captcha_run_under_attack() : void
creationell_captcha_maybe_upgrade()
Runs schema migrations when the stored version differs from the running one.
creationell_captcha_maybe_upgrade() : void
Hooked on admin_init. When the event-log table already exists it is re-run through dbDelta so new columns are added; a missing table is left alone — it is created on demand when the event log is switched on.
creationell_captcha_migrate_widget_mode()
Migrates the legacy `widget_mode` setting (Modul 11a) to the new `widget_display` + `widget_auto_trigger` pair (Modul 14). Idempotent — if `widget_display` is already present in the stored option, the migration is skipped.
creationell_captcha_migrate_widget_mode() : void
Mapping: visible → widget_display=standard, widget_auto_trigger=none auto → widget_display=invisible, widget_auto_trigger=onload overlay → widget_display=floating, widget_auto_trigger=onsubmit
The legacy widget_mode key is removed from the option once the new keys
are in place.
creationell_captcha_register_assets()
Registers the widget script and — for Argon2id — its worker registration.
creationell_captcha_register_assets() : void
creationell_captcha_build_widget_markup()
Builds the ALTCHA widget markup as a plain string. Enqueues the widget script as a side effect.
creationell_captcha_build_widget_markup() : string
Safe to call from inside an ob_start callback because it does not use
output-buffering itself — unlike the legacy creationell_captcha_get_widget_markup
wrapper that this function now powers.
Reads eight widget-customization settings (display, type, auto_trigger, theme, hide_branding, primary_color, custom_css, strings_override) and maps them to the corresponding v3 attributes. Boolean attributes are emitted as empty-string values per HTML5 convention.
Return values
stringcreationell_captcha_render_widget()
Renders the ALTCHA widget markup and enqueues its assets.
creationell_captcha_render_widget() : void
creationell_captcha_verify_payload()
Verifies a raw base64 ALTCHA payload string.
creationell_captcha_verify_payload(string $raw) : bool
Shared by the POST-based request helper and the third-party form integrations, which read the payload from their plugin's submission data.
Parameters
- $raw : string
-
The raw
altchapayload.
Return values
boolcreationell_captcha_verify_request()
Reads and verifies the ALTCHA payload from the current POST request.
creationell_captcha_verify_request() : bool
The ALTCHA payload itself is the anti-bot token — no separate WordPress nonce applies here.
Return values
boolcreationell_captcha_widget()
Public template tag — renders the ALTCHA widget.
creationell_captcha_widget() : void
For use in theme templates or custom-form markup; the call must sit inside the
creationell_captcha_get_widget_markup()
Returns the ALTCHA widget markup as a string.
creationell_captcha_get_widget_markup() : string
Used by the shortcode and by the third-party form integrations, which embed the widget into another plugin's form markup. Implementation routes through the underlying string builder rather than ob_start so the function is safe to call from inside other output-buffer callbacks (e.g. Modul 12's auto-inject buffer).
Return values
string —The widget markup.
creationell_captcha_widget_shortcode()
Shortcode handler for [creationell_captcha].
creationell_captcha_widget_shortcode() : string
Place the shortcode inside a
Return values
string —The widget markup.