Recovery URL — Unlock a Stuck IP

A secret URL that clears any rate-limit lockout on the IP that visits it. Zero database access needed.

Why You Need This

Sometimes a legit user gets locked out:

• Your own admin fat-fingered the password 10 times
• A shared office IP hit the threshold
• A customer used a public WiFi that had been flagged
• You're testing and keep failing on purpose

Instead of:

• Waiting for the 5-minute lockout to expire
• SSHing into the database to delete transients
• Disabling the plugin entirely

You can send them a recovery URL.

How It Works

1. Admin generates a recovery token (a random string) in the settings
2. Recovery URL is: https://yoursite.com/?wkcft_recovery=THE_TOKEN
3. Stuck user visits that URL
4. Plugin compares token (timing-safe via hash_equals())
5. On match: all rate-limit transients for that user's IP are cleared
6. User can now submit forms normally

Setup — Create the Token

1. WooCommerce → Turnstile Settings → Conditional Rules tab
2. Scroll to Abuse Protection section
3. Click Generate Recovery Token (or paste your own 32+ char random string)
4. Save Changes
5. Token is stored in options wkcft_recovery_token (primary) and wkcft_recovery_key (login-level bypass)

Example generator (any 32-char random string works):

# On Mac/Linux
openssl rand -hex 16
# → e.g., 7a3b9c1d4e6f8a2b5c7d9e1f3a5b7c9d

Use the URL

Send to the stuck user:

https://yoursite.com/?wkcft_recovery=7a3b9c1d4e6f8a2b5c7d9e1f3a5b7c9d

They visit the URL. Nothing happens visually (page loads as normal). But in the background, their IP's rate-limit entries are cleared.

They go back to the original form and submit — works.

Two Recovery Methods

Method 1 — Query Parameter

The straightforward approach:

https://yoursite.com/?wkcft_recovery=TOKEN

Works on any page. Hook runs on init, so lockout clears on every page load.

Method 2 — Admin-Ajax Endpoint

Bypasses full-page cache:

https://yoursite.com/wp-admin/admin-ajax.php?action=wkcft_recover&token=TOKEN

AJAX endpoints are never cached by WordPress caching plugins.

Security Notes

Timing-Safe Comparison

The plugin uses PHP's hash_equals() to compare the submitted token with the stored one. This prevents timing attacks where an attacker could guess the token character-by-character.

One-Time-Use Is Not Automatic

By default, the token stays valid until you regenerate it. For truly one-time-use tokens:

1. After a user uses the recovery URL, manually clear the token: Conditional Rules → Recovery Token field → empty → Save
2. Generate a fresh one for next use

Authentication Removal

When the token matches, the plugin also removes these filters for the current request:

• authenticate (WP login hook)
• woocommerce_process_login_errors (WC login hook)

This lets the stuck user log in even if WP Login has CAPTCHA enabled and Cloudflare is having issues.

Only the current request is affected. Subsequent requests go through full CAPTCHA flow.

Rotation

Treat the recovery token like a password:

• Rotate every 90 days
• Rotate immediately if you suspect it leaked
• Never share publicly — only via private channel (email, internal chat)

Admin Use Case

You locked yourself out of wp-admin and cannot log in:

1. Open incognito window
2. Hit https://yoursite.com/?wkcft_recovery=YOUR_TOKEN
3. Go to https://yoursite.com/wp-admin/ and log in normally
4. Login works — CAPTCHA is bypassed for this request

Customer Support Use Case

A customer emails you: "I cannot check out, says security error, I just wanted to buy!"

1. Check Analytics → Top Blocked IPs — confirm their IP is in the list
2. Reply with the recovery URL:

Hi! It looks like your IP hit our security limit (probably from multiple submit attempts). To unlock, please visit this URL once from the same device: https://yoursite.com/?wkcft_recovery=TOKEN — you do not need to do anything on the page, just visit it. Then try checkout again.

Optional: after confirming the customer is unblocked, rotate the token.

What It Does NOT Do

• Does not clear IP blacklist — those are permanent until you remove them
• Does not clear blocked usernames — those are permanent
• Does not reset the after-N-failures counter for OTHER IPs — only the visiting IP
• Does not disable CAPTCHA globally — future submissions from this IP still need valid Turnstile tokens

Generate the Token Programmatically

Use WP-CLI or a one-liner MU-plugin to seed a strong token without UI clicking:

wp option update wkcft_recovery_token "$(openssl rand -hex 16)"
wp option update wkcft_recovery_key "$(wp option get wkcft_recovery_token)"

Both options must match for every recovery path (validator's full-clear + main-file's authenticate-filter bypass) to work.

Troubleshooting

Related Pages

• Conditional Rules — Where to set the token
• Rate Limiting — What the lockout actually does
• Analytics — See top blocked IPs