Admin
1 month ago
Emails
1 month ago
CustomerEmailVerification.php
1 month ago
EmailVerificationService.php
1 month ago
VerificationController.php
1 week ago
VerificationEventListener.php
1 month ago
VerificationController.php
395 lines
| 1 | <?php |
| 2 | declare( strict_types=1 ); |
| 3 | |
| 4 | namespace Automattic\WooCommerce\Internal\CustomerEmailVerification; |
| 5 | |
| 6 | /** |
| 7 | * Drives the customer email-verification UI on My Account and processes its verify-links. |
| 8 | * |
| 9 | * Verification uses a one-time link emailed to the customer. Opening the link verifies the address |
| 10 | * directly — but ONLY when the request is authenticated as the link's target user. The login gate is |
| 11 | * the control, not the HTTP verb. |
| 12 | * |
| 13 | * This intentionally mirrors WordPress core's own email-change confirmation links, which likewise |
| 14 | * complete a sensitive change on an authenticated GET carrying an unguessable secret — no interstitial, |
| 15 | * form, or nonce — relying on the auth gate plus the secret: |
| 16 | * |
| 17 | * - Administration email change: wp-admin/options.php (`adminhash`) — |
| 18 | * https://github.com/WordPress/WordPress/blob/master/wp-admin/options.php |
| 19 | * - Profile email change: wp-admin/user-edit.php (`newuseremail`) — |
| 20 | * https://github.com/WordPress/WordPress/blob/master/wp-admin/user-edit.php |
| 21 | * |
| 22 | * What makes the link safe: |
| 23 | * |
| 24 | * - A prefetch (email client or security scanner) is never logged in as the customer, so it can never |
| 25 | * reach the verify branch — it only ever sees the My Account login. It cannot consume the key. |
| 26 | * - The key is a one-time, time-limited secret bound by hash to the account's current email, so it is |
| 27 | * inert without an authenticated session as the target: a leaked key cannot be spent by anyone who is |
| 28 | * not already that user (which is also why, like core, it is safe to carry the key in the URL). |
| 29 | * - An attacker who registered an account with someone else's email can't read the victim's inbox, so |
| 30 | * never receives the link; and the victim can only reach a logged-in-as-target state by resetting the |
| 31 | * password, which invalidates the attacker's session. |
| 32 | * |
| 33 | * No auth cookie is ever minted by the link (that would be exploitable as login CSRF): a logged-out |
| 34 | * visitor is shown the My Account login on the link itself, and signing in returns them to the link |
| 35 | * (the verify params are preserved in its URL) to complete it as themselves. |
| 36 | * |
| 37 | * @since 11.0.0 |
| 38 | */ |
| 39 | class VerificationController { |
| 40 | |
| 41 | /** |
| 42 | * Nonce action used to protect the send-verification request. |
| 43 | */ |
| 44 | private const SEND_NONCE_ACTION = 'woocommerce-send-verification-email'; |
| 45 | |
| 46 | /** |
| 47 | * Query param used to trigger the send-verification request. |
| 48 | */ |
| 49 | private const SEND_PARAM = 'wc_send_verification'; |
| 50 | |
| 51 | /** |
| 52 | * Query param carrying the plaintext verification key. |
| 53 | */ |
| 54 | private const KEY_PARAM = 'wc_verify_email_key'; |
| 55 | |
| 56 | /** |
| 57 | * Query param carrying the target user ID. |
| 58 | */ |
| 59 | private const USER_PARAM = 'wc_verify_email_user'; |
| 60 | |
| 61 | /** |
| 62 | * Query param carrying a one-off result code to print as a notice on the account page. |
| 63 | */ |
| 64 | private const NOTICE_PARAM = 'wc_verify_notice'; |
| 65 | |
| 66 | /** |
| 67 | * Minimum seconds between sends (rate limit). |
| 68 | */ |
| 69 | private const SEND_RATE_LIMIT = 60; |
| 70 | |
| 71 | /** |
| 72 | * Verification service. |
| 73 | * |
| 74 | * @var EmailVerificationService |
| 75 | */ |
| 76 | private $service; |
| 77 | |
| 78 | /** |
| 79 | * Constructor. Registers hooks. |
| 80 | */ |
| 81 | public function __construct() { |
| 82 | add_action( 'template_redirect', array( $this, 'maybe_process_request' ) ); |
| 83 | add_action( 'woocommerce_before_account_orders', array( $this, 'print_result_notice' ), 5 ); |
| 84 | add_action( 'woocommerce_before_account_orders', array( $this, 'render_prompt' ) ); |
| 85 | } |
| 86 | |
| 87 | /** |
| 88 | * Inject dependencies. |
| 89 | * |
| 90 | * @internal |
| 91 | * @param EmailVerificationService $service Verification service. |
| 92 | */ |
| 93 | final public function init( EmailVerificationService $service ): void { |
| 94 | $this->service = $service; |
| 95 | } |
| 96 | |
| 97 | /** |
| 98 | * Route an incoming request: a send request or an opened verify-link. |
| 99 | * |
| 100 | * Opening the emailed link is a GET, which email clients and security scanners routinely prefetch. |
| 101 | * Verification is gated on authentication ({@see self::handle_verify_link()}), so a prefetch — always |
| 102 | * logged out — only ever reaches the My Account login and can never consume the key. |
| 103 | * |
| 104 | * @since 11.0.0 |
| 105 | */ |
| 106 | public function maybe_process_request(): void { |
| 107 | if ( isset( $_GET[ self::SEND_PARAM ] ) ) { // phpcs:ignore WordPress.Security.NonceVerification.Recommended |
| 108 | $this->handle_send_request(); |
| 109 | return; |
| 110 | } |
| 111 | |
| 112 | // No nonce on the verify-link: like WordPress core's email-change confirmation links, the |
| 113 | // unguessable one-time key is the CSRF defence and the login gate is the authority. |
| 114 | // phpcs:disable WordPress.Security.NonceVerification.Recommended |
| 115 | if ( isset( $_GET[ self::KEY_PARAM ], $_GET[ self::USER_PARAM ] ) ) { |
| 116 | $this->handle_verify_link( |
| 117 | absint( wp_unslash( $_GET[ self::USER_PARAM ] ) ), |
| 118 | sanitize_text_field( wp_unslash( $_GET[ self::KEY_PARAM ] ) ) |
| 119 | ); |
| 120 | } |
| 121 | // phpcs:enable WordPress.Security.NonceVerification.Recommended |
| 122 | } |
| 123 | |
| 124 | /** |
| 125 | * Verify the address from an opened verify-link — gated on being logged in as the link's target user. |
| 126 | * |
| 127 | * The login gate is the control: verification, and key consumption, happen ONLY on the path where the |
| 128 | * request is authenticated as $user_id. A prefetch or any logged-out visit is shown the My Account |
| 129 | * login and never touches the key; a visitor logged in as a different account is refused without |
| 130 | * consuming it. This is the same shape as WordPress core's email-change confirmation links |
| 131 | * (wp-admin/options.php `adminhash`, wp-admin/user-edit.php `newuseremail`): a sensitive change |
| 132 | * completed on an authenticated GET carrying an unguessable secret. |
| 133 | * |
| 134 | * @since 11.0.0 |
| 135 | * |
| 136 | * @param int $user_id Target user ID from the link. |
| 137 | * @param string $key Plaintext verification key from the link. |
| 138 | * @return void |
| 139 | */ |
| 140 | private function handle_verify_link( int $user_id, string $key ): void { |
| 141 | // The key rides in the URL, so keep this response off caches and out of third-party Referer |
| 142 | // headers (the logged-out branch renders a themed front-end page that may load such assets). |
| 143 | nocache_headers(); |
| 144 | if ( ! headers_sent() ) { |
| 145 | header( 'Referrer-Policy: no-referrer' ); |
| 146 | } |
| 147 | |
| 148 | $current_user_id = get_current_user_id(); |
| 149 | |
| 150 | // Logged out (including any prefetcher): never verify, never consume the key. Render the My |
| 151 | // Account login; the verify params stay in the URL so signing in returns here to complete it. |
| 152 | if ( ! $current_user_id ) { |
| 153 | wc_add_notice( __( 'You need to be logged in to confirm your email address.', 'woocommerce' ), 'notice' ); |
| 154 | return; |
| 155 | } |
| 156 | |
| 157 | // Logged in as someone else: refuse rather than silently switching accounts. The key is untouched. |
| 158 | if ( $current_user_id !== $user_id ) { |
| 159 | $this->redirect_with_result( 'mismatch' ); |
| 160 | } |
| 161 | |
| 162 | // Authenticated as the target — the only path that consumes the key and verifies. |
| 163 | if ( $this->process_verification( $user_id, $key ) ) { |
| 164 | $this->redirect_with_result( 'confirmed' ); |
| 165 | } |
| 166 | |
| 167 | // Already verified (e.g. the link re-opened after the key was spent): land on Orders quietly, |
| 168 | // without repeating the success notice for a confirmation that already happened. |
| 169 | if ( $this->service->is_verified( $user_id ) ) { |
| 170 | wp_safe_redirect( wc_get_account_endpoint_url( 'orders' ) ); |
| 171 | exit; |
| 172 | } |
| 173 | |
| 174 | // Authenticated as the target, but the key is invalid or expired and they are not verified. |
| 175 | $this->redirect_with_result( 'expired' ); |
| 176 | } |
| 177 | |
| 178 | /** |
| 179 | * Handle a request to send (or resend) the verification email, triggered by the My Account prompt. |
| 180 | * |
| 181 | * Verifies the nonce, applies a rate-limit (does not re-send within the window), dispatches the |
| 182 | * email, and redirects to the orders section, where the prompt points the customer to their inbox. |
| 183 | * |
| 184 | * @since 11.0.0 |
| 185 | */ |
| 186 | public function handle_send_request(): void { |
| 187 | $user_id = get_current_user_id(); |
| 188 | |
| 189 | if ( ! $user_id ) { |
| 190 | return; |
| 191 | } |
| 192 | |
| 193 | $nonce = isset( $_GET['_wpnonce'] ) ? sanitize_text_field( wp_unslash( $_GET['_wpnonce'] ) ) : ''; |
| 194 | |
| 195 | if ( ! wp_verify_nonce( $nonce, self::SEND_NONCE_ACTION ) ) { |
| 196 | $this->redirect_with_result( 'invalid' ); |
| 197 | } |
| 198 | |
| 199 | // Only send a fresh link once the last one is outside the rate-limit window; otherwise the |
| 200 | // existing link still stands and the prompt continues to point the customer to their inbox. |
| 201 | $seconds_since = $this->service->seconds_since_last_key( $user_id ); |
| 202 | if ( null === $seconds_since || $seconds_since >= self::SEND_RATE_LIMIT ) { |
| 203 | $this->send_verification_email( $user_id ); |
| 204 | $this->redirect_with_result( 'sent' ); |
| 205 | } |
| 206 | |
| 207 | $this->redirect_with_result( 'throttled' ); |
| 208 | } |
| 209 | |
| 210 | /** |
| 211 | * Return whether the verification prompt should be shown for the current user. |
| 212 | * |
| 213 | * This cannot depend on whether matching guest orders exist, since that would disclose order |
| 214 | * existence before the customer proves they control the email address. |
| 215 | * |
| 216 | * @since 11.0.0 |
| 217 | * |
| 218 | * @return bool |
| 219 | */ |
| 220 | public function should_show_prompt(): bool { |
| 221 | $user_id = get_current_user_id(); |
| 222 | |
| 223 | if ( ! $user_id || $this->service->is_verified( $user_id ) ) { |
| 224 | return false; |
| 225 | } |
| 226 | |
| 227 | $email_setting = get_option( 'woocommerce_customer_verify_email_settings', array() ); |
| 228 | $email_enabled = 'yes' === ( $email_setting['enabled'] ?? 'yes' ); |
| 229 | |
| 230 | $should_show = $email_enabled && wc_string_to_bool( get_option( 'woocommerce_enable_guest_checkout' ) ); |
| 231 | |
| 232 | // A temporary-password account already has a set-password link (which also verifies on use), |
| 233 | // surfaced by the temporary-password notice, so skip a second prompt alongside it. |
| 234 | $should_show = $should_show && ! get_user_option( 'default_password_nag', $user_id ); |
| 235 | |
| 236 | /** |
| 237 | * Filter whether to show the verification prompt for an unverified user. |
| 238 | * |
| 239 | * @since 11.1.0 |
| 240 | * |
| 241 | * @param bool $should_show Whether to show the prompt, before this filter runs. |
| 242 | * @param int $user_id The WordPress user ID of the customer. |
| 243 | */ |
| 244 | return (bool) apply_filters( 'woocommerce_customer_email_verification_should_show_prompt', $should_show, $user_id ); |
| 245 | } |
| 246 | |
| 247 | /** |
| 248 | * Render the verification prompt notice on the My Account "Orders" panel. |
| 249 | * |
| 250 | * Within the rate-limit window a link was sent recently, so the prompt points the customer to their |
| 251 | * inbox and offers no immediate resend; otherwise it carries the "confirm email" call to action. |
| 252 | * |
| 253 | * @internal |
| 254 | * @since 11.0.0 |
| 255 | */ |
| 256 | public function render_prompt(): void { |
| 257 | if ( ! $this->should_show_prompt() ) { |
| 258 | return; |
| 259 | } |
| 260 | |
| 261 | $user_id = get_current_user_id(); |
| 262 | $seconds_since = $this->service->seconds_since_last_key( $user_id ); |
| 263 | |
| 264 | if ( null !== $seconds_since && $seconds_since <= self::SEND_RATE_LIMIT ) { |
| 265 | // A just-sent/throttled result notice (from the redirect) already points to the inbox this |
| 266 | // page load, so don't print a second "check your inbox" alongside it. |
| 267 | // phpcs:ignore WordPress.Security.NonceVerification.Recommended -- display-only, no state change. |
| 268 | if ( ! isset( $_GET[ self::NOTICE_PARAM ] ) ) { |
| 269 | wc_print_notice( |
| 270 | esc_html__( 'Confirm your email address to check for past orders. A confirmation link was sent recently — please check your inbox.', 'woocommerce' ), |
| 271 | 'notice' |
| 272 | ); |
| 273 | } |
| 274 | return; |
| 275 | } |
| 276 | |
| 277 | $send_url = wp_nonce_url( |
| 278 | add_query_arg( self::SEND_PARAM, '1', wc_get_account_endpoint_url( 'orders' ) ), |
| 279 | self::SEND_NONCE_ACTION |
| 280 | ); |
| 281 | |
| 282 | $notice = sprintf( |
| 283 | '<a href="%2$s" class="button wc-forward">%3$s</a> %1$s', |
| 284 | esc_html__( 'Confirm your email address to check for past orders and link them to your account.', 'woocommerce' ), |
| 285 | esc_url( $send_url ), |
| 286 | esc_html__( 'Confirm email address', 'woocommerce' ) |
| 287 | ); |
| 288 | |
| 289 | wc_print_notice( $notice, 'notice' ); |
| 290 | } |
| 291 | |
| 292 | /** |
| 293 | * Print the one-off result notice carried by the {@see self::NOTICE_PARAM} query arg, if any. |
| 294 | * |
| 295 | * Send/confirm actions redirect here with a result code rather than queuing a session notice, so the |
| 296 | * page shows exactly the current request's outcome — re-running an action can't stack notices. |
| 297 | * |
| 298 | * @internal |
| 299 | * @since 11.0.0 |
| 300 | */ |
| 301 | public function print_result_notice(): void { |
| 302 | // phpcs:ignore WordPress.Security.NonceVerification.Recommended -- display-only, no state change. |
| 303 | $code = isset( $_GET[ self::NOTICE_PARAM ] ) ? sanitize_key( wp_unslash( $_GET[ self::NOTICE_PARAM ] ) ) : ''; |
| 304 | $notice = $this->result_notice( $code ); |
| 305 | |
| 306 | if ( null !== $notice ) { |
| 307 | wc_print_notice( esc_html( $notice[0] ), $notice[1] ); |
| 308 | } |
| 309 | } |
| 310 | |
| 311 | /** |
| 312 | * Map a redirect result code to its [ message, notice type ], or null for an unknown code. |
| 313 | * |
| 314 | * @param string $code Result code from a send/confirm redirect. |
| 315 | * @return array{0: string, 1: string}|null |
| 316 | */ |
| 317 | private function result_notice( string $code ): ?array { |
| 318 | switch ( $code ) { |
| 319 | case 'sent': |
| 320 | return array( __( 'A confirmation link has been sent to your email address. Please check your inbox.', 'woocommerce' ), 'success' ); |
| 321 | case 'throttled': |
| 322 | return array( __( 'A confirmation link was sent recently. Please check your inbox, or wait a moment before requesting a new one.', 'woocommerce' ), 'notice' ); |
| 323 | case 'confirmed': |
| 324 | return array( __( 'Your email address has been confirmed.', 'woocommerce' ), 'success' ); |
| 325 | case 'expired': |
| 326 | return array( __( 'This confirmation link is invalid or has expired. Please request a new one.', 'woocommerce' ), 'error' ); |
| 327 | case 'mismatch': |
| 328 | return array( __( 'Unable to confirm this email while you are logged in to a different account. Please log out and open the link again.', 'woocommerce' ), 'error' ); |
| 329 | case 'invalid': |
| 330 | return array( __( 'Invalid request. Please try again.', 'woocommerce' ), 'error' ); |
| 331 | default: |
| 332 | return null; |
| 333 | } |
| 334 | } |
| 335 | |
| 336 | /** |
| 337 | * Redirect to the orders section carrying a one-off result code, then exit. |
| 338 | * |
| 339 | * @param string $code Result code understood by {@see self::result_notice()}. |
| 340 | * @return never |
| 341 | */ |
| 342 | private function redirect_with_result( string $code ): void { |
| 343 | wp_safe_redirect( add_query_arg( self::NOTICE_PARAM, $code, wc_get_account_endpoint_url( 'orders' ) ) ); |
| 344 | exit; |
| 345 | } |
| 346 | |
| 347 | /** |
| 348 | * Validate a key and verify the user. |
| 349 | * |
| 350 | * @since 11.0.0 |
| 351 | * |
| 352 | * @param int $user_id User ID. |
| 353 | * @param string $key Plaintext verification key. |
| 354 | * @return bool True when verification succeeded. |
| 355 | */ |
| 356 | public function process_verification( int $user_id, string $key ): bool { |
| 357 | if ( ! $user_id || '' === $key ) { |
| 358 | return false; |
| 359 | } |
| 360 | if ( ! $this->service->check_verification_key( $user_id, $key ) ) { |
| 361 | return false; |
| 362 | } |
| 363 | $this->service->mark_verified( $user_id ); |
| 364 | return true; |
| 365 | } |
| 366 | |
| 367 | /** |
| 368 | * Send (or resend) a verification email to a user. |
| 369 | * |
| 370 | * @since 11.0.0 |
| 371 | * |
| 372 | * @param int $user_id User ID. |
| 373 | */ |
| 374 | public function send_verification_email( int $user_id ): void { |
| 375 | $user = get_user_by( 'id', $user_id ); |
| 376 | if ( ! $user ) { |
| 377 | return; |
| 378 | } |
| 379 | |
| 380 | $verify_url = $this->service->build_verification_url( $user_id ); |
| 381 | |
| 382 | WC()->mailer(); |
| 383 | |
| 384 | /** |
| 385 | * Triggers sending of the customer email-verification email. |
| 386 | * |
| 387 | * @param int $user_id The WordPress user ID of the customer. |
| 388 | * @param string $verify_url The one-time verification URL to include in the email. |
| 389 | * |
| 390 | * @since 11.0.0 |
| 391 | */ |
| 392 | do_action( 'woocommerce_customer_verify_email_notification', $user_id, $verify_url ); |
| 393 | } |
| 394 | } |
| 395 |