[URGENT] fix(checkout-pages): rewrite password reset URL on subsites (#1168)

[kenedytorcatt]

Fixes #1168.

Summary

replace_reset_password_link() returned early on subsites, so the password reset email always pointed to the main network site's wp-login.php. End customers of subsite owners (especially on mapped custom domains) were taken to a brand they didn't recognize and frequently couldn't complete the reset. This PR makes the function subsite-aware.

Why this is urgent

This is breaking real users in production right now. We run a multisite SaaS where every customer has their own mapped custom domain. Today a customer's customer (zuletadia on yariglam.cl) tried to reset her password and received a link to https://kursopro.com/wp-login.php — a domain she doesn't recognize. She didn't trust it. Every subsite owner in any UM-based network is hitting this whenever one of their users requests a password reset.

Reproduced on 8 subsites in our staging network, including subdomains and a .cl mapped TLD. 8/8 broken before patch.

Root cause

Two issues in inc/checkout/class-checkout-pages.php:

1. Hook never runs on subsites. The add_filter('retrieve_password_message', ...) registration is wrapped inside if (is_main_site()) (around line 67), so on a subsite the filter is not even attached.

2. Function returns early on subsites. Even if the filter ran, replace_reset_password_link() had if ( ! is_main_site()) return $message; at the top (line 354), so it never rewrote the URL.

Combined, WordPress's default retrieve_password() builds the URL with network_site_url('wp-login.php'), which on every subsite resolves to the main site's wp-login.php. UM never gets a chance to fix it.

Solution

This PR:

• Moves add_filter('retrieve_password_message', ...) out of the is_main_site() branch and into the if ($use_custom_login) block, so the filter runs on all sites in the network when custom login is enabled.

• Rewrites replace_reset_password_link() to be subsite-aware:

  • On the main site: behaviour unchanged. URL is rewritten to point at the custom login page, exactly like before.
  • On a subsite: URL is rewritten to home_url('/') of the current subsite, with the same action=rp / key / login / wp_lang query args. Existing handlers (WooCommerce my-account, BuddyPress, custom themes, even default wp-login fallback) pick up the request on the subsite's own domain and complete the reset there. The user never leaves the brand they signed up on.

• Adds a wu_subsite_password_reset_url filter so integrations can point at a specific endpoint (e.g. the WooCommerce lost-password endpoint, a custom page, etc.) without having to re-implement the rewrite themselves.

The diff is intentionally minimal and self-contained: one method body refactored, one hook registration moved by ~10 lines, one new filter introduced. No new files. No changes to filter_lostpassword_url() or filter_login_url() — those were already correct.

What I changed

inc/checkout/class-checkout-pages.php:

• Moved add_filter('retrieve_password_message', [$this, 'replace_reset_password_link'], 10, 4); from inside if (is_main_site()) to the if ($use_custom_login) block (so it runs on all sites).
• Removed the early if ( ! is_main_site()) return $message; guard from replace_reset_password_link().
• Added a subsite branch that builds the reset URL from home_url('/') of the current subsite.
• Added the wu_subsite_password_reset_url filter for integration overrides.
• Updated the docblock with @since 2.10.2 for the new behaviour.

Test plan

• Verified bug exists on UM 2.10.1 across 8 subsites (8/8 generate URL on main site host).
• Applied patch on a UM 2.10.1 staging network (kpstage, 313+ subsites).
• PHP -l syntax check passes.
• Re-tested 8 subsites with patch: 8/8 PASS at filter level (URL host matches subsite host).
• End-to-end retrieve_password() flow tested on 5 subsites with non-network-admin users: PASS (the failures we saw in our test runs were unrelated rate-limit / SMTP issues, not the patch).
• Tested with a real mapped custom domain (yariglam.cl, .cl TLD): URL correctly rewritten to http://yariglam.cl/?action=rp&key=...&login=zuletadia&wp_lang=es_ES.
• Main site regression: URL still points at the configured custom login page (/login).
• Verified that themes/plugins that handle the reset on subsites (WooCommerce my-account, BuddyPress, default wp-login) still work, because we keep the standard action=rp / key / login / wp_lang query args.

Backwards compatibility

• Networks with enable_custom_login_page = 0: no change at all. The hook registration is still gated on this setting.
• Networks with enable_custom_login_page = 1 (the affected setup): main site behaviour is exactly the same as before. Only the subsite branch is new — and on subsites the previous behaviour was already broken (URL pointed to the main site), so there is nothing useful to preserve.
• Themes/plugins overriding the reset flow: still work, because the URL keeps the standard query args. They can also use the new wu_subsite_password_reset_url filter to direct the URL at a specific endpoint.

Suggested release

Please consider a 2.10.2 patch release shortly after merge — every UM-based network with custom login enabled is impacted. Happy to iterate on review feedback ASAP.

Thanks David, and sorry for the urgency — we have customers losing trust over this every time someone forgets their password.

Summary by CodeRabbit

• Bug Fixes

  • Fixed password reset link handling for subsites to ensure reset links properly redirect to the correct subsite domain while maintaining user locale settings and consistency with main site behavior.

• New Features

  • Added a new integration hook allowing developers to customize password reset link destinations on subsites while maintaining domain scoping.

[coderabbitai]

Warning

Rate limit exceeded

@kenedytorcatt has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 50 minutes and 40 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: d094ea82-72bd-4d6b-b016-4bbaf7a4248c

📥 Commits

Reviewing files that changed from the base of the PR and between 300db87 and 946a3a7.

📒 Files selected for processing (1)

• inc/checkout/class-checkout-pages.php

📝 Walkthrough

Walkthrough

The Checkout_Pages class now handles password reset emails on both main site and subsites. The retrieve_password_message filter is reworked to parse email content for wp-login.php URLs and route reset links to the correct domain: main site via wp_login_url(), subsites via their own home_url() with a new wu_subsite_password_reset_url filter for customization.

Changes

Subsite-Aware Password Reset Links

Layer / File(s)	Summary
Documentation & Behavior Contract inc/checkout/class-checkout-pages.php	Inline comments in init() and method docblock document filter scope on both main site and subsites with domain-specific reset URL routing.
URL Parsing and Validation inc/checkout/class-checkout-pages.php	Message is parsed for wp-login.php URLs; unchanged message is returned early when no match is found.
Locale Handling inc/checkout/class-checkout-pages.php	User locale is switched before reset URL construction and restored afterward to ensure parameters use correct locale.
Main Site vs Subsite Routing inc/checkout/class-checkout-pages.php	Main site resets target wp_login_url(); subsites rewrite to subsite home_url() with rp/key/login/wp_lang query parameters. New wu_subsite_password_reset_url filter enables customization of subsite reset destination.
Message Update inc/checkout/class-checkout-pages.php	Matched wp-login.php URL in email content is replaced with constructed reset URL.

🎯 3 (Moderate) | ⏱️ ~22 minutes

Poem

🐰 A subsite's plight, once lost in the mail,
Password reset links to domains they'd fail,
Now routers stay home, by domain they dwell,
With hooks for the wise who wish to compel,
The lost find their way—no phishing fare!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly specifies the main change: fixing password reset URL rewriting on subsites within the checkout-pages component, directly addressing issue #1168.
Linked Issues check	✅ Passed	The PR fully implements all coding objectives from #1168: filter registration moved to run on subsites, replace_reset_password_link() refactored for subsite-awareness, reset URLs rewritten to subsite domains preserving query args, and wu_subsite_password_reset_url integration hook added.
Out of Scope Changes check	✅ Passed	All changes in inc/checkout/class-checkout-pages.php are directly scoped to the password reset URL rewriting objective; no unrelated modifications detected.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

• Generate code and open pull requests
• Plan features and break down work
• Investigate incidents and troubleshoot customer tickets together
• Automate recurring tasks and respond to alerts with triggers
• Summarize progress and report instantly

Built for teams:

• Shared memory across your entire org—no repeating context
• Per-thread sandboxes to safely plan and execute work
• Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@inc/checkout/class-checkout-pages.php`:
- Around line 423-451: The filter wu_subsite_password_reset_url should be
applied to the base endpoint before you append the reset query parameters;
currently apply_filters is called after add_query_arg which causes integrations
that return a clean path (e.g., "/my-account/lost-password/") to lose
action/key/login/wp_lang. Fix by calling
apply_filters('wu_subsite_password_reset_url', $subsite_base, $key, $user_login,
$user_data) (or similar) to let integrations override the endpoint, then build
$new_url = add_query_arg([
'action'=>'rp','key'=>$key,'login'=>rawurlencode($user_login),'wp_lang'=>$locale,
], $filtered_base) and finally call set_url_scheme($new_url, null).

🪄 Autofix (Beta)

❌ Autofix failed (check again to retry)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 411faef3-7ebd-41a1-a78a-481eb529f43d

📥 Commits

Reviewing files that changed from the base of the PR and between c428ca0 and 300db87.

📒 Files selected for processing (1)

• inc/checkout/class-checkout-pages.php

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Apply wu_subsite_password_reset_url before appending the reset params.

The new hook currently receives the fully-built reset URL. If an integration returns a clean endpoint like /my-account/lost-password/, it will accidentally drop action, key, login, and wp_lang, and the emailed link stops working. Filter the base endpoint first, then append the standard reset query args afterward.

Suggested change

-			$subsite_base = home_url('/');
-
-			$new_url = add_query_arg(
-				[
-					'action'  => 'rp',
-					'key'     => $key,
-					'login'   => rawurlencode($user_login),
-					'wp_lang' => $locale,
-				],
-				$subsite_base
-			);
+			$subsite_base = apply_filters('wu_subsite_password_reset_url', home_url('/'), $key, $user_login, $user_data);
+
+			$new_url = add_query_arg(
+				[
+					'action'  => 'rp',
+					'key'     => $key,
+					'login'   => rawurlencode($user_login),
+					'wp_lang' => $locale,
+				],
+				$subsite_base
+			);
 
 			/**
-			 * Filter the subsite-aware password reset URL.
+			 * Filter the subsite-aware password reset endpoint.
 			 *
 			 * Allows integrations (WooCommerce, BuddyPress, custom themes)
-			 * to override the destination URL while keeping it on the
+			 * to override the destination endpoint while keeping it on the
 			 * subsite's own domain.
 			 *
 			 * `@since` 2.10.2
 			 *
-			 * `@param` string  $new_url    The default subsite reset URL.
+			 * `@param` string  $subsite_base The default subsite reset endpoint.
 			 * `@param` string  $key        The reset key.
 			 * `@param` string  $user_login The user login.
 			 * `@param` WP_User $user_data  The user data.
 			 */
-			$new_url = apply_filters('wu_subsite_password_reset_url', $new_url, $key, $user_login, $user_data);
-
 			$new_url = set_url_scheme($new_url, null);

🧰 Tools

🪛 GitHub Check: Code Quality Checks

[warning] 449-449:
@param WP_Ultimo\Checkout\WP_User $user_data does not accept actual type of parameter: array.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@inc/checkout/class-checkout-pages.php` around lines 423 - 451, The filter
wu_subsite_password_reset_url should be applied to the base endpoint before you
append the reset query parameters; currently apply_filters is called after
add_query_arg which causes integrations that return a clean path (e.g.,
"/my-account/lost-password/") to lose action/key/login/wp_lang. Fix by calling
apply_filters('wu_subsite_password_reset_url', $subsite_base, $key, $user_login,
$user_data) (or similar) to let integrations override the endpoint, then build
$new_url = add_query_arg([
'action'=>'rp','key'=>$key,'login'=>rawurlencode($user_login),'wp_lang'=>$locale,
], $filtered_base) and finally call set_url_scheme($new_url, null).

[superdav42]

Auto-approved by pulse runner @superdav42 — author @kenedytorcatt confirmed collaborator, pre-merge gates passed.

[kenedytorcatt]

PR extended — covering 3 more auth-email hooks with the same root cause

Hi David, after the initial fix I went back and audited every auth-related email WordPress fires from a subsite, to see whether the same problem existed elsewhere. It does. Pushed an additional commit (946a3a7) extending the PR.

What I found

The original report (zuletadia / yariglam.cl) was about the "I forgot my password" flow only. But the underlying cause — network_site_url('wp-login.php') always resolving to the main site, with no UM filter rewriting it on subsites — affects every WP auth email that embeds a wp-login.php URL. There are four of them, not one:

#	Hook	Triggered when	Was UM rewriting it?
1	retrieve_password_message	User clicks "lost password"	❌ Returned early on subsites (the original bug)
2	wp_new_user_notification_email	Admin creates a new user, user gets a "set your password" link	❌ Not handled
3	retrieve_password_notification_email	Admin notification fired alongside the user reset email	❌ Not handled
4	new_user_email_content	User changes their email address from their profile, gets a confirmation link	❌ Not handled

I reproduced all four on UM 2.10.1 in our staging network. Sample output across 5 subsites before the extension:

[BLOG 302 yariglam.cl]
  [1] retrieve_password_message            -> URL on kpstage.com   (WRONG, fixed by initial commit)
  [2] wp_new_user_notification_email       -> URL on kpstage.com   (WRONG)
  [3] retrieve_password_notification_email -> URL on kpstage.com   (WRONG)
  [4] new_user_email_content               -> URL on kpstage.com   (WRONG)

So a real user life-cycle on a subsite (be created → set password → maybe change password later → maybe change email later) was hitting cross-domain URLs at every single step, not just the password-reset one. The user is sent away from the subsite they are actually using on every auth touchpoint.

Why the extension

Three reasons I think it belongs in the same PR rather than a follow-up:

1. Same root cause. All four hooks fail for the same reason. Splitting them across two PRs means two different reviewers (or you, twice) re-reading the same context.
2. Same fix shape. All three additional handlers share a 30-line helper that rewrites any wp-login.php URL inside an email body to a subsite-aware equivalent. Once the helper exists for hook Welcome to WP Multisite WaaS Discussions! #1, the cost of wiring it to the other three is minimal.
3. Same release. A 2.10.2 that only fixes Welcome to WP Multisite WaaS Discussions! #1 still leaves new-user signup, the admin reset notification, and email-change confirmation pointing at the main site. Subsite owners would still be opening tickets the day after upgrading.

What changed in the extension commit (946a3a7)

• New protected helper rewrite_subsite_aware_login_url($url) on the same class. Centralises the "rewrite a wp-login.php URL so it stays on the current site" logic that all four callbacks now share. On the main site it still uses default_login_page (preserving the existing rewrite behaviour); on a subsite it returns home_url('/?<query>').
• New callback rewrite_new_user_notification_email($email, $user, $blogname) for wp_new_user_notification_email.
• New callback rewrite_password_notification_email($defaults, $key, $user_login, $user_data) for retrieve_password_notification_email.
• New callback rewrite_email_change_content($email_text, $new_user_email) for new_user_email_content.
• Three corresponding add_filter() registrations inside the existing if ($use_custom_login) block, so all of them are gated on the same setting that already gates the rest of the custom-login behaviour.

I deliberately kept all of this scoped to URL rewriting. Email content, headers, locale switching and the filter signatures are unchanged. The callbacks operate on preg_replace_callback against wp-login.php only, so messages that don't contain such URLs are returned untouched and existing customizations from other plugins still apply.

Test results after the extension

Run on UM 2.10.1 with the patch applied, custom login enabled, network of 313 subsites:

======================================================================
EXTENDED PATCH TEST — 4 AUTH EMAIL HOOKS
======================================================================
[BLOG 302 yariglam.cl] (mapped .cl TLD)
  [1] retrieve_password_message            PASS -> yariglam.cl
  [2] wp_new_user_notification_email       PASS -> yariglam.cl, yariglam.cl
  [3] retrieve_password_notification_email PASS -> yariglam.cl
  [4] new_user_email_content               PASS -> yariglam.cl

[BLOG 303 ekgcommunity.kpstage.com]
  [1..4] PASS (all on ekgcommunity.kpstage.com)

[BLOG 305 cursosdemaquillajeprofesional.kpstage.com]
  [1..4] PASS

[BLOG 306 blickclub.kpstage.com]
  [1..4] PASS

[BLOG 311 luna.kpstage.com]
  [1..4] PASS

FINAL: 20 PASS / 0 FAIL (out of 20 tests)

Main site regression check (same 4 hooks):

=== MAIN SITE REGRESSION CHECK (4 hooks) ===
home: kpstage.com  (custom login page slug = "login")

[1] retrieve_password_message            -> https://kpstage.com/login?... (uses /login slug, correct)
[2] wp_new_user_notification_email       -> https://kpstage.com/login?... (uses /login slug, correct)
[3] retrieve_password_notification_email -> https://kpstage.com/login?... (uses /login slug, correct)
[4] new_user_email_content               -> https://kpstage.com/login?... (uses /login slug, correct)

Same behaviour as today on the main site for all four hooks.

Backwards compatibility

• Networks with enable_custom_login_page = 0: nothing changes. None of the new filters are even registered.
• Networks with enable_custom_login_page = 1:
  • Main site: identical behaviour, URLs continue to be rewritten to the configured custom login page.
  • Subsites: previously broken (URLs pointed off-site to the main); now stay on the subsite they belong to.
• Themes/plugins customising any of these emails keep working — the callbacks only touch wp-login.php substrings inside the message body, the email shape is preserved.

Summary of the PR now

Single file changed (inc/checkout/class-checkout-pages.php):

• Existing replace_reset_password_link() made subsite-aware (initial commit).
• 4 hook registrations now in the if ($use_custom_login) block so they all run on subsites too.
• 3 new public callbacks for the three additional hooks.
• 1 protected helper that all of them share.
• 1 new filter wu_subsite_password_reset_url for integrations.

Net diff: ~250 lines added, ~12 modified, no removals. No new files. All scoped to URL rewriting, no behavioural changes elsewhere.

Happy to split into separate commits or rework if you prefer a different shape — just let me know. The reason I bundled them is that splitting feels like it would slow down a 2.10.2 release for what is one architectural fix expressed across four hooks.

Thanks again for looking at this.

[superdav42]

Auto-approved by pulse runner @superdav42 — author @kenedytorcatt confirmed collaborator, pre-merge gates passed.

[coderabbitai]

Note

Autofix is a beta feature. Expect some limitations and changes as we gather feedback and continue to improve it.

An unexpected error occurred while generating fixes: Cannot open a stacked PR on a forked repository.