Connection: Don't full-reconnect on inconclusive validation when the blog token is healthy by fgiannar · Pull Request #52851 · Automattic/jetpack

fgiannar · 2026-09-28T05:32:12Z

Proposed changes

This PR makes two complementary fixes to the owner-reconnect ("Restore Connection") flow for the deleted-owner-token case — the one the invalid_connection_owner / has_user_token: false notice is shown for. The first makes the reconnect surgical instead of destructive; the second makes the stale notice clear on the first attempt instead of the second. Neither depends on the other, but they land together because they fix the same user-visible flow.

1. `restore()` no longer full-reconnects when only the owner's user token is missing

Manager::restore() (the backend of the "Restore Connection" CTA) escalated to a full reconnect() — disconnect_site_wpcom( true ) (jetpack.deregister, revoking every user connection on WordPress.com) plus register() (wiping the local user_tokens option) — whenever Tokens::validate() failed to return health flags. But validate() returns a non-parseable result in several cases that say nothing about token health: the current user's token is missing locally (the deleted-owner-token case, which bails before ever contacting WordPress.com), the blog token is missing locally, a transient transport failure / non-200, or a malformed response body. restore() collapsed all of these into blog_token_healthy = false; user_token_healthy = false, which satisfied the equal-flags branch and triggered the full teardown. The escalation was the else of a parsing check, not a decision.

Concretely: an owner whose token was deleted (blog token perfectly healthy) clicked "Restore connection" and every healthy secondary user got disconnected — while the notice copy we ship for exactly that state (invalid_connection_owner, has_user_token: false) promises "reconnect your WordPress.com account", a surgical fix.

This PR replaces the collapsing else with an independent blog-token check:

} else {
    // The paired health check could not run (a token is missing locally — e.g. a
    // deleted owner token — or the request failed): no evidence the blog token is
    // broken, and it's the one credential reconnect() would revoke for every user,
    // so check it on its own before that teardown.
    $blog_token_healthy = true === $this->get_tokens()->validate_blog_token();
    $user_token_healthy = false;
}

Tokens::validate_blog_token() signs with the blog token only (usable precisely when the user token is missing) and returns strict true only on a confirmed-healthy response — as of #52718 it returns a WP_Error when the check can't be performed, so true === … treats a transient/unverifiable check as "not healthy" and its own failures can't masquerade as health. When it confirms health, the existing unequal-flags logic routes to refresh_user_token() → 'authorize', minting a fresh user token without needing the old one. Everything below the branch is unchanged.

Behavior matrix

State	Before	After
User token missing locally, blog token healthy	full reconnect (all users disconnected)	`'authorize'` (caller re-links; blog token and other users untouched)
User token missing, blog token broken/unreachable	full reconnect	full reconnect (unchanged)
Blog token missing locally	full reconnect	full reconnect (unchanged — `validate_blog_token()` can't sign, returns non-`true`)
Transient failure on `validate()`	full reconnect	full reconnect, unless the retried blog check confirms health → `'authorize'` (strictly less destructive)
Both flags known-equal (both healthy / both broken)	full reconnect	unchanged
Unequal known flags / site connection	surgical paths	unchanged

This is the low-risk diagnosis fix that CONNECT-381 Phase C's caller-aware routing depends on: Phase C's "only the user token is unhealthy (blog token healthy)" condition wasn't evaluable in the deleted-owner-token case, because restore() never learned the blog token was healthy. This slice fixes the diagnosis only — it touches no ownership semantics, needs no WordPress.com changes (jetpack-token-health/blog already exists), and routes to the existing 'authorize' path.

2. Owner reconnect now clears the stale connection error on the first attempt

With fix #1 in place, reconnecting the owner via authorize() mints a fresh user token — but the pre-existing invalid_connection_owner error stayed stored, so the broken-connection notice lingered until a second reconnect. That is a plain single-node bug, not a race:

Error_Handler clears stored errors by listening on jetpack_updated_user_token (→ delete_all_errors()).
Every user-token write funnels through Tokens::update_user_token(), but only the REST user-token endpoint fired jetpack_updated_user_token. authorize() (the owner-reconnect path), provisioning, and WP-CLI all wrote the token silently, so the listener never ran and the error persisted.
The second click worked only because the first reconnect had by then given the user a token, so the subsequent disconnect_user() finally succeeded and fired jetpack_unlinked_user (which also clears errors). Reproducible on a single-node site with no object cache and no concurrency.

The fix moves the do_action( 'jetpack_updated_user_token', $user_id, $token ) down into Tokens::update_user_token() — the one function every write path funnels through — and drops the now-redundant call in the REST endpoint so it doesn't double-fire. It fires unconditionally, matching the endpoint's prior behavior: Jetpack_Options::update_options() returns void, so there is no success flag to gate on. Manager's memoized owner id is already reset on any user-token write (reset_connection_status() is hooked to pre_update_jetpack_option_user_tokens), so no extra bookkeeping is needed.

Net effect: authorize(), provisioning, and CLI now clear stale connection errors exactly as the REST endpoint always did — so the owner reconnect resolves the notice on the first attempt.

Related product discussion/links

CONNECT-455 (parent: CONNECT-381 — Audit CTA backend flows and refactoring)
Traced during review of Connection: Do not show errors users can't resolve #52049 (reconnecting as the owner disconnected a healthy secondary user)
Fix Allow plugins to inject additional template-specific open graph tags #2 surfaced during manual testing of this PR (the invalid_connection_owner notice persisted after the first reconnect)

Does this pull request change what data or activity we track or use?

No.

Testing instructions

Unit tests — jp test php packages/connection

Fix 1 — a new restore() suite in ManagerTest (partial-mocked Manager, spying on reconnect()) covers the full matrix above:
- inconclusive validate() + confirmed-healthy blog token ⇒ reconnect() never called, returns 'authorize';
- inconclusive + broken blog token ⇒ reconnect() called (unchanged);
- inconclusive + unverifiable blog check (WP_Error) ⇒ reconnect() called (not treated as healthy);
- all known-flag combinations (both healthy, both broken, blog-only, user-only) and the site-connection early branch route exactly as before.
Fix 2:
- TokensTest::test_update_user_token_fires_action — a user-token write fires jetpack_updated_user_token with ($user_id, $token).
- Error_Handler_Test::test_user_token_write_clears_stored_owner_error — the end-to-end guarantee: a stored invalid_connection_owner error is gone after a user-token write, via the production jetpack_updated_user_token → delete_all_errors() wiring.

Manual (a Jetpack-connected self-hosted site, e.g. Jurassic Ninja)

Connect the site as an owner, and connect at least one secondary user (an admin or editor) to WordPress.com.
Delete the owner's user token locally so the site is in the invalid_connection_owner / has_user_token: false state (e.g. clear the owner's row from the user_tokens option), leaving the blog token intact.
As the owner, visit My Jetpack and click Restore Connection.
- Before: the secondary user is disconnected too (they must re-authorize), and the broken-connection notice is still showing after you reconnect — it only clears on a second Restore Connection.
- After: you're sent through authorization to re-link only your own account (the blog token and the secondary user's connection are untouched), and the notice is gone as soon as the reconnect completes — no second attempt.
Sanity-check the unchanged paths: break only the blog token → it refreshes the blog token; break only your user token → it re-links your account; a genuinely broken connection (both) → full reconnect, as before.

Cost note: one extra signed GET (jetpack-token-health/blog), only in the previously-inconclusive branch of a user-initiated restore.

github-actions · 2026-09-28T05:33:26Z

Are you an Automattician? Please test your changes on all WordPress.com environments to help mitigate accidental explosions.

To test on WoA, go to the Plugins menu on a WoA dev site. Click on the "Upload" button and follow the upgrade flow to be able to upload, install, and activate the Jetpack Beta plugin. Once the plugin is active, go to Jetpack > Jetpack Beta, select your plugin (Jetpack or WordPress.com Site Helper), and enable the fix/restore-inconclusive-validation-blog-token branch.
To test on Simple, run the following command on your sandbox:

bin/jetpack-downloader test jetpack fix/restore-inconclusive-validation-blog-token

bin/jetpack-downloader test jetpack-mu-wpcom-plugin fix/restore-inconclusive-validation-blog-token

Interested in more tips and information?

In your local development environment, use the jetpack rsync command to sync your changes to a WoA dev blog.
Read more about our development workflow here: PCYsg-eg0-p2
Figure out when your changes will be shipped to customers here: PCYsg-eg5-p2

github-actions · 2026-09-28T05:33:46Z

Thank you for your PR!

When contributing to Jetpack, we have a few suggestions that can help us test and review your patch:

✅ Include a description of your PR changes.
✅ Add a "[Status]" label (In Progress, Needs Review, ...).
✅ Add testing instructions.
✅ Specify whether this PR includes any changes to data or privacy.
✅ Add changelog entries to affected projects

This comment will be updated as you work on your PR and make changes. If you think that some of those checks are not needed for your PR, please explain why you think so. Thanks for cooperation 🤖

Follow this PR Review Process:

Ensure all required checks appearing at the bottom of this PR are passing.
Make sure to test your changes on all platforms that it applies to. You're responsible for the quality of the code you ship.
You can use GitHub's Reviewers functionality to request a review.
When it's reviewed and merged, you will be pinged in Slack to deploy the changes to WordPress.com simple once the build is done.

If you have questions about anything, reach out in #jetpack-developers for guidance!

Jetpack plugin:

The Jetpack plugin has different release cadences depending on the platform:

WordPress.com Simple releases happen as soon as you deploy your changes after merging this PR (PCYsg-Jjm-p2).
WoA releases happen weekly.
Releases to self-hosted sites happen monthly:
- Scheduled release: October 6, 2026