22

✏️ Editing: MobileAppQRLogin.php

<?php
/**
 * REST API Mobile App QR Login controller.
 *
 * Handles requests to generate and exchange QR login tokens for direct mobile
 * app authentication via Application Passwords. Token generation is gated on
 * the `manage_woocommerce` capability (administrators and shop managers by
 * default).
 */

declare( strict_types=1 );

namespace Automattic\WooCommerce\Admin\API;

use Automattic\WooCommerce\Admin\API\RateLimits\QRLoginRateLimits;

defined( 'ABSPATH' ) || exit;

/**
 * Mobile App QR Login controller.
 *
 * @internal
 */
class MobileAppQRLogin extends \WC_REST_Data_Controller {

/**
	 * Endpoint namespace.
	 *
	 * @var string
	 */
	protected $namespace = 'wc-admin';

/**
	 * Route base.
	 *
	 * @var string
	 */
	protected $rest_base = 'mobile-app';

/**
	 * Token TTL in seconds (5 minutes).
	 */
	const TOKEN_TTL = 300;

/**
	 * Transient prefix for QR login tokens.
	 */
	const TOKEN_TRANSIENT_PREFIX = '_wc_qr_login_token_';

/**
	 * Max tokens per user per 15-minute window.
	 */
	const MAX_TOKENS_PER_WINDOW = 5;

/**
	 * Max exchange attempts per valid token per 15-minute window.
	 */
	const MAX_EXCHANGE_ATTEMPTS = 10;

/**
	 * Max invalid-token exchange attempts per IP per 15-minute window.
	 */
	const MAX_INVALID_EXCHANGE_ATTEMPTS = 100;

/**
	 * Max invalid-token scan attempts per IP per 15-minute window.
	 */
	const MAX_INVALID_SCAN_ATTEMPTS = 100;

/**
	 * Broad anonymous exchange abuse guard per IP per 15-minute window.
	 */
	const MAX_EXCHANGE_IP_ATTEMPTS = 1000;

/**
	 * Option prefix for database-backed atomic token claims.
	 */
	const CLAIM_OPTION_PREFIX = '_wc_qr_login_claim_';

/**
	 * Scan-claim option prefix. Independent from `CLAIM_OPTION_PREFIX` so the
	 * scan and exchange mutexes can't deadlock each other; they protect
	 * different write windows on the same token record.
	 */
	const SCAN_CLAIM_OPTION_PREFIX = '_wc_qr_login_scan_claim_';

/**
	 * Approval-claim option prefix. Prevents concurrent number choices from
	 * racing the one-strike scanned -> approved/rejected transition.
	 */
	const APPROVE_CLAIM_OPTION_PREFIX = '_wc_qr_login_approve_claim_';

/**
	 * Stable Application Passwords `app_id` for credentials issued by this
	 * flow. Lets administrators identify QR-issued credentials in the
	 * Application Passwords screen and revoke them in bulk.
	 */
	const APP_ID = '0b540e2f-86b7-4b8a-8e0c-f61e9bfbde59';

/**
	 * Transient prefix for the "token consumed" record written after a successful
	 * exchange. The wc-admin UI polls a status endpoint that reads this so it can
	 * transition to a confirmation panel and surface the device that signed in.
	 */
	const CONSUMED_TRANSIENT_PREFIX = '_wc_qr_login_consumed_';

/**
	 * Max status checks per user per 15-minute window. The polling client hits
	 * this every ~2.5s while a QR is on screen; 600/15min ≈ 40/min, comfortably
	 * above the polling rate but tight enough to short-circuit a misbehaving
	 * client or a credential-stuffing scan.
	 */
	const MAX_STATUS_CHECKS_PER_WINDOW = 600;

/**
	 * Max revoke attempts per user per 15-minute window.
	 */
	const MAX_REVOKE_ATTEMPTS = 10;

/**
	 * Whitelisted keys for the `device` payload sent by the mobile app on the
	 * scan call. Anything outside this set is dropped before storage.
	 *
	 * `brand` is Android-only (`Build.BRAND`, e.g. "google", "samsung"); iOS
	 * doesn't have a direct analogue and clients that don't have the field
	 * just leave it absent.
	 *
	 * @var string[]
	 */
	const DEVICE_PAYLOAD_KEYS = array( 'os', 'os_version', 'model', 'brand', 'app_version' );

/**
	 * Maximum length (chars) for any individual sanitized device-payload field.
	 * Defends against accidental or hostile bloat ending up in transients and
	 * the Application Password name.
	 */
	const DEVICE_FIELD_MAX_LENGTH = 64;

/**
	 * State machine values for the per-token record. Transitions are gated
	 * by an explicit `current_state` check at the top of each handler
	 * (scan/approve/exchange) so the only writers are the handlers themselves.
	 */
	const STATE_PENDING  = 'pending';
	const STATE_SCANNED  = 'scanned';
	const STATE_APPROVED = 'approved';
	const STATE_REJECTED = 'rejected';
	const STATE_EXPIRED  = 'expired';
	const STATE_CONSUMED = 'consumed';

/**
	 * Pick window after the app scans a QR (seconds). The merchant has this
	 * long to tap the matching number on wc-admin before the session
	 * auto-rejects. Short enough to limit replay; long enough for a confused
	 * user to read the phone, find their browser, and click.
	 */
	const CHALLENGE_TTL_SECONDS = 90;

/**
	 * Length (bytes pre-bin2hex) of the exchange-grant nonce minted on
	 * approval. The grant gates the final `/qr-login-exchange` call so an
	 * attacker who learned the token can't race the legit app to exchange
	 * after approval. 32 bytes = 64 hex chars = 256 bits of entropy.
	 */
	const EXCHANGE_GRANT_BYTES = 32;

/**
	 * Invalid exchange grants allowed before the token is terminally rejected.
	 */
	const MAX_INVALID_GRANT_ATTEMPTS = 3;

/**
	 * Transient prefix mapping `session_id` → `token_hash` so the mobile-side
	 * `/qr-login-session-status` poll can resolve a session id back to the
	 * underlying token record without exposing the original token to the
	 * polling channel.
	 */
	const SESSION_TRANSIENT_PREFIX = '_wc_qr_login_session_';

/**
	 * Rate limit for /qr-login-scan (per IP per 15 min).
	 */
	const MAX_SCAN_PER_WINDOW = 10;

/**
	 * Rate limit for /qr-login-approve (per user per 15 min).
	 */
	const MAX_APPROVE_PER_WINDOW = 20;

/**
	 * Rate limit for /qr-login-session-status (per session id per 15 min).
	 *
	 * Accounts for ~2-s polling over a 90-s challenge window plus headroom.
	 */
	const MAX_SESSION_STATUS_PER_WINDOW = 60;

/**
	 * Register routes.
	 *
	 * @return void
	 */
	public function register_routes() {
		// Generate a QR login token (requires authentication and `manage_woocommerce` capability).
		register_rest_route(
			$this->namespace,
			'/' . $this->rest_base . '/qr-login-token',
			array(
				array(
					'methods'             => \WP_REST_Server::CREATABLE,
					'callback'            => array( $this, 'generate_token' ),
					'permission_callback' => array( $this, 'get_items_permissions_check' ),
				),
				'schema' => array( $this, 'get_public_item_schema' ),
			)
		);

// Exchange a QR login token for Application Password (no authentication required).
		// The device payload is captured at /qr-login-scan time and sourced from the
		// approved record — the exchange call only needs the token + grant nonce.
		register_rest_route(
			$this->namespace,
			'/' . $this->rest_base . '/qr-login-exchange',
			array(
				array(
					'methods'             => \WP_REST_Server::CREATABLE,
					'callback'            => array( $this, 'exchange_token' ),
					'permission_callback' => '__return_true',
					'args'                => array(
						'token'          => array(
							'required'          => true,
							'type'              => 'string',
							'sanitize_callback' => 'sanitize_text_field',
						),
						// Soft-required: the handler enforces presence + validity
						// via constant-time comparison and returns a clear
						// `invalid_exchange_grant` 412 if missing. We don't make
						// it `required: true` at the schema layer because that
						// would short-circuit earlier checks (HTTPS, invalid
						// token, rate limit) with a generic WP validation 400
						// before our diagnostic responses can fire.
						'exchange_grant' => array(
							'type'              => 'string',
							'sanitize_callback' => 'sanitize_text_field',
						),
					),
				),
				'schema' => array( $this, 'get_public_item_schema' ),
			)
		);

// Poll for token status (consumed yet?). Used by wc-admin to transition
		// the modal from "QR shown" to "Signed in successfully on {device}".
		register_rest_route(
			$this->namespace,
			'/' . $this->rest_base . '/qr-login-status',
			array(
				array(
					'methods'             => \WP_REST_Server::CREATABLE,
					'callback'            => array( $this, 'get_status' ),
					'permission_callback' => array( $this, 'get_items_permissions_check' ),
					'args'                => array(
						'token' => array(
							'required'          => true,
							'type'              => 'string',
							'sanitize_callback' => 'sanitize_text_field',
						),
					),
				),
				'schema' => array( $this, 'get_public_item_schema' ),
			)
		);

// Revoke (delete) the Application Password issued by an exchange. The
		// user must own the AP — verified inside the callback via the WP API.
		register_rest_route(
			$this->namespace,
			'/' . $this->rest_base . '/qr-login-revoke',
			array(
				array(
					'methods'             => \WP_REST_Server::DELETABLE,
					'callback'            => array( $this, 'revoke_password' ),
					'permission_callback' => array( $this, 'get_items_permissions_check' ),
					'args'                => array(
						'uuid' => array(
							'required'          => true,
							'type'              => 'string',
							'sanitize_callback' => 'sanitize_text_field',
						),
					),
				),
				'schema' => array( $this, 'get_public_item_schema' ),
			)
		);

// Mobile app reports the QR was scanned. Server generates the
		// number-match challenge and returns the *real* number to the app
		// only. Public — token + capability flag are the auth.
		register_rest_route(
			$this->namespace,
			'/' . $this->rest_base . '/qr-login-scan',
			array(
				array(
					'methods'             => \WP_REST_Server::CREATABLE,
					'callback'            => array( $this, 'scan_token' ),
					'permission_callback' => '__return_true',
					'args'                => array(
						'token'                    => array(
							'required'          => true,
							'type'              => 'string',
							'sanitize_callback' => 'sanitize_text_field',
						),
						// The device payload is required: it shows up in the
						// merchant's "match this number" device card, in the
						// Application Password name, and in the sign-in
						// notification email. Mobile clients always have these
						// fields available from the platform SDK (Build.MODEL,
						// UIDevice.current.model, etc.), so requiring the
						// payload at the protocol level keeps every downstream
						// surface honest.
						'device'                   => array(
							'required'   => true,
							'type'       => 'object',
							'properties' => array(
								'os'          => array( 'type' => 'string' ),
								'os_version'  => array( 'type' => 'string' ),
								'model'       => array( 'type' => 'string' ),
								'brand'       => array( 'type' => 'string' ),
								'app_version' => array( 'type' => 'string' ),
							),
						),
						// Capability flag the mobile app sets to advertise that
						// it implements the number-matching protocol. Reserved
						// for future protocol bumps that might gate behavior on
						// further capability bits.
						'supports_number_matching' => array(
							'required' => true,
							'type'     => 'boolean',
						),
					),
				),
				'schema' => array( $this, 'get_public_item_schema' ),
			)
		);

// Merchant taps a number on wc-admin. Server validates against the
		// stored real number with hash_equals; correct → approved, wrong →
		// rejected (terminal, no retry).
		register_rest_route(
			$this->namespace,
			'/' . $this->rest_base . '/qr-login-approve',
			array(
				array(
					'methods'             => \WP_REST_Server::CREATABLE,
					'callback'            => array( $this, 'approve_token' ),
					'permission_callback' => array( $this, 'get_items_permissions_check' ),
					'args'                => array(
						'token'  => array(
							'required'          => true,
							'type'              => 'string',
							'sanitize_callback' => 'sanitize_text_field',
						),
						'choice' => array(
							'required'          => true,
							'type'              => 'string',
							'sanitize_callback' => 'sanitize_text_field',
						),
					),
				),
				'schema' => array( $this, 'get_public_item_schema' ),
			)
		);

// Mobile app polls this with the session id returned from /scan.
		// While in `scanned` we say so; on `approved` we hand over the
		// short-lived `exchange_grant` nonce required by the final
		// /qr-login-exchange call.
		register_rest_route(
			$this->namespace,
			'/' . $this->rest_base . '/qr-login-session-status',
			array(
				array(
					'methods'             => \WP_REST_Server::READABLE,
					'callback'            => array( $this, 'get_session_status' ),
					'permission_callback' => '__return_true',
					'args'                => array(
						'session_id' => array(
							'required'          => true,
							'type'              => 'string',
							'sanitize_callback' => 'sanitize_text_field',
						),
						'token_hash' => array(
							'type'              => 'string',
							'sanitize_callback' => 'sanitize_text_field',
						),
					),
				),
				'schema' => array( $this, 'get_public_item_schema' ),
			)
		);

// Cheap up-front capability check so wc-admin can render a permanently
		// disabled QR card (rather than spin up a token request that will fail)
		// when application passwords are unavailable on this site. Same gate as
		// the token endpoint so a subscriber cannot probe site configuration.
		register_rest_route(
			$this->namespace,
			'/' . $this->rest_base . '/qr-login-availability',
			array(
				array(
					'methods'             => \WP_REST_Server::READABLE,
					'callback'            => array( $this, 'get_availability' ),
					'permission_callback' => array( $this, 'get_items_permissions_check' ),
				),
				'schema' => array( $this, 'get_public_item_schema' ),
			)
		);

parent::register_routes();
	}

/**
	 * Check whether the current user can access the QR login browser endpoints.
	 *
	 * These endpoints back an interactive wp-admin flow, so they require a real
	 * logged-in browser session — a valid `logged_in` cookie for the current user
	 * plus a matching `wp_rest` nonce — as well as the `manage_woocommerce`
	 * capability. The capability check is deliberately explicit (not routed through
	 * `wc_rest_check_manager_permissions()`) so it cannot be loosened by the
	 * `woocommerce_rest_check_permissions` filter that other Admin API endpoints share.
	 *
	 * @param \WP_REST_Request<array<string, mixed>> $request The REST request.
	 * @return \WP_Error|bool True if the user is allowed, WP_Error otherwise.
	 */
	public function get_items_permissions_check( $request ) {
		$user_id = get_current_user_id();
		if ( ! $user_id || (int) wp_validate_auth_cookie( '', 'logged_in' ) !== $user_id ) {
			return new \WP_Error(
				'woocommerce_rest_qr_login_missing_session',
				__( 'This action requires an interactive admin session.', 'woocommerce' ),
				array( 'status' => rest_authorization_required_code() )
			);
		}

$nonce = $request->get_header( 'X-WP-Nonce' );
		if ( ! $nonce || ! wp_verify_nonce( $nonce, 'wp_rest' ) ) {
			return new \WP_Error(
				'woocommerce_rest_qr_login_missing_session',
				__( 'This action requires an interactive admin session.', 'woocommerce' ),
				array( 'status' => rest_authorization_required_code() )
			);
		}

if ( ! current_user_can( 'manage_woocommerce' ) ) {
			return new \WP_Error(
				'woocommerce_rest_cannot_view',
				__( 'Sorry, you are not allowed to generate a mobile app QR login token.', 'woocommerce' ),
				array( 'status' => rest_authorization_required_code() )
			);
		}

return true;
	}

/**
	 * Check if Application Passwords are available.
	 *
	 * @return bool
	 */
	private function are_application_passwords_available() {
		return function_exists( 'wp_is_application_passwords_available' )
			&& wp_is_application_passwords_available();
	}

/**
	 * Return a REST response carrying WordPress' no-cache headers.
	 *
	 * @param array<string, mixed> $data Response payload.
	 * @return \WP_REST_Response
	 */
	private function rest_ensure_nocache_response( array $data ): \WP_REST_Response {
		$response = rest_ensure_response( $data );

foreach ( wp_get_nocache_headers() as $header_name => $header_value ) {
			if ( false === $header_value ) {
				continue;
			}

$response->header( $header_name, (string) $header_value );
		}

return $response;
	}

/**
	 * Reason codes returned by `/qr-login-availability` so wc-admin can
	 * tailor the disabled card to the specific cause.
	 */
	const AVAILABILITY_REASON_HTTPS_REQUIRED        = 'https_required';
	const AVAILABILITY_REASON_AP_UNSUPPORTED        = 'application_passwords_unsupported';
	const AVAILABILITY_REASON_AP_DISABLED_BY_FILTER = 'application_passwords_disabled_by_filter';

/**
	 * Report whether QR login is currently available on this site.
	 *
	 * Lets wc-admin render a permanently-disabled QR card with the right
	 * explanation up-front, instead of mounting `<QRDirectLoginCode />`,
	 * spinning, calling `/qr-login-token`, and only then showing a generic
	 * error. The reason code is the heuristic best we can do without each
	 * security plugin self-identifying:
	 *
	 *  - `https_required` — `is_ssl()` is false or the raw/final `siteurl` is
	 *    `http://`. The most common cause is a local dev environment;
	 *    production sites without HTTPS can't use QR login at all.
	 *  - `application_passwords_unsupported` — WordPress core's own support
	 *    gate (`wp_is_application_passwords_supported()`) returns false.
	 *    Ships true on every modern WP host that has SSL or is local; false
	 *    here typically means the site is non-local + non-SSL.
	 *  - `application_passwords_disabled_by_filter` — the WP support gate
	 *    passes, but the `wp_is_application_passwords_available` filter
	 *    returns false. This is the case where a security plugin (Wordfence,
	 *    Solid Security, etc.) or a custom code snippet has explicitly
	 *    disabled application passwords. We can't name the exact source from
	 *    the filter alone; the docs link in the merchant-facing UI covers it.
	 *
	 * `nocache_headers()` so an upstream cache cannot pin a stale
	 * "unavailable" response for a site that just installed an HTTPS cert.
	 *
	 * @param \WP_REST_Request<array<string, mixed>> $request The REST request (unused).
	 * @return \WP_REST_Response
	 */
	public function get_availability( $request ): \WP_REST_Response {
		unset( $request );

nocache_headers();

$site_url     = $this->get_secure_site_url();
		$https_ok     = ! is_wp_error( $site_url );
		$ap_supported = function_exists( 'wp_is_application_passwords_supported' )
			&& wp_is_application_passwords_supported();
		$ap_available = $this->are_application_passwords_available();

$https_ok  = is_ssl() && $https_ok;
		$available = $https_ok && $ap_available;
		$reason    = null;

if ( ! $available ) {
			if ( ! $https_ok ) {
				$reason = self::AVAILABILITY_REASON_HTTPS_REQUIRED;
			} elseif ( ! $ap_supported ) {
				$reason = self::AVAILABILITY_REASON_AP_UNSUPPORTED;
			} else {
				$reason = self::AVAILABILITY_REASON_AP_DISABLED_BY_FILTER;
			}
		}

return $this->rest_ensure_nocache_response(
			array(
				'available' => $available,
				'reason'    => $reason,
			)
		);
	}

/**
	 * Check rate limit for token generation.
	 *
	 * @param int $user_id The user ID.
	 * @return bool True if within rate limit.
	 */
	private function check_generation_rate_limit( $user_id ) {
		return QRLoginRateLimits::consume( QRLoginRateLimits::BUCKET_GENERATION, (string) $user_id );
	}

/**
	 * Broad anonymous abuse guard for token exchange.
	 *
	 * This intentionally has a high ceiling. It is only meant to slow obvious
	 * unauthenticated floods; valid-token and invalid-token traffic use separate
	 * lower buckets so a few random requests from a shared proxy IP cannot block
	 * legitimate QR login exchanges.
	 *
	 * @return bool True if within rate limit.
	 */
	private function check_exchange_ip_rate_limit() {
		return QRLoginRateLimits::consume( QRLoginRateLimits::BUCKET_EXCHANGE_IP, $this->get_client_ip() );
	}

/**
	 * Check rate limit for random/nonexistent exchange tokens.
	 *
	 * @return bool True if within rate limit.
	 */
	private function check_invalid_exchange_rate_limit() {
		return QRLoginRateLimits::consume( QRLoginRateLimits::BUCKET_INVALID_EXCHANGE, $this->get_client_ip() );
	}

/**
	 * Check rate limit for random/nonexistent scan tokens.
	 *
	 * @return bool True if within rate limit.
	 */
	private function check_invalid_scan_rate_limit() {
		return QRLoginRateLimits::consume( QRLoginRateLimits::BUCKET_INVALID_SCAN, $this->get_client_ip() );
	}

/**
	 * Check rate limit for exchange attempts against a valid token.
	 *
	 * @param string $token_hash SHA-256 hash of the plaintext token.
	 * @return bool True if within rate limit.
	 */
	private function check_valid_exchange_rate_limit( $token_hash ) {
		return QRLoginRateLimits::consume( QRLoginRateLimits::BUCKET_VALID_EXCHANGE, $token_hash );
	}

/**
	 * Get the client IP address used as the per-IP rate-limit key.
	 *
	 * Uses `REMOTE_ADDR` exclusively. We intentionally do not honor
	 * `HTTP_X_FORWARDED_FOR` here: the exchange endpoint is unauthenticated, and
	 * without a project-wide trusted-proxy list we cannot tell a legitimate
	 * proxy header from an attacker-supplied one. Trusting the first XFF value
	 * would let any client choose a fresh rate-limit bucket per request and
	 * bypass per-IP caps. On sites behind a CDN/load balancer that all clients
	 * share, REMOTE_ADDR is the proxy IP, so exchange uses broad IP throttling
	 * only as an abuse guard and relies on token-scoped buckets for security.
	 *
	 * @return string
	 */
	private function get_client_ip() {
		if ( ! empty( $_SERVER['REMOTE_ADDR'] ) ) {
			return sanitize_text_field( wp_unslash( $_SERVER['REMOTE_ADDR'] ) );
		}
		return '';
	}

/**
	 * Build the option name used for a token exchange claim.
	 *
	 * @param string $token_hash SHA-256 hash of the plaintext token.
	 * @return string
	 */
	private function get_token_claim_key( $token_hash ) {
		return self::CLAIM_OPTION_PREFIX . $token_hash;
	}

/**
	 * Atomically claim a token for exchange using the options table.
	 *
	 * `add_option()` is backed by a unique option_name constraint, so it works
	 * across PHP workers even on default installs without a persistent object
	 * cache. Stale claims are cleaned only if their stored value still matches
	 * the value this request observed, avoiding deletion of another worker's
	 * fresh claim.
	 *
	 * @param string $token_hash SHA-256 hash of the plaintext token.
	 * @param int    $expires_at Unix timestamp when the token expires.
	 * @return bool True if the claim was acquired.
	 */
	private function claim_token_for_exchange( $token_hash, $expires_at ) {
		return $this->claim_token_with_option_key(
			$this->get_token_claim_key( $token_hash ),
			$expires_at
		);
	}

/**
	 * Atomically claim a token using an option key.
	 *
	 * @param string $claim_key Option key used as the claim mutex.
	 * @param int    $expires_at Unix timestamp when the token expires.
	 * @return bool True if the claim was acquired.
	 */
	private function claim_token_with_option_key( $claim_key, $expires_at ) {
		$claim_expires_at = max( time() + 30, (int) $expires_at );

if ( add_option( $claim_key, (string) $claim_expires_at, '', false ) ) {
			return true;
		}

$existing_expires_at = (int) get_option( $claim_key, 0 );
		if ( $existing_expires_at > 0 && $existing_expires_at <= time() ) {
			$this->delete_claim_if_value_matches( $claim_key, (string) $existing_expires_at );
			return add_option( $claim_key, (string) $claim_expires_at, '', false );
		}

return false;
	}

/**
	 * Delete a claim option only if it still has the value this request observed.
	 *
	 * @param string $claim_key            Option key used as the claim mutex.
	 * @param string $observed_claim_value Claim expiry value previously read from the option.
	 * @return bool True if the observed stale claim was deleted.
	 */
	private function delete_claim_if_value_matches( $claim_key, $observed_claim_value ) {
		global $wpdb;

$result = $wpdb->query(
			$wpdb->prepare(
				"DELETE FROM {$wpdb->options} WHERE option_name = %s AND option_value = %s",
				$claim_key,
				$observed_claim_value
			)
		);

if ( false === $result ) {
			wc_get_logger()->warning(
				sprintf(
					'QR login stale-claim cleanup query failed for %s: %s',
					$claim_key,
					$wpdb->last_error
				),
				array( 'source' => 'mobile-app-qr-login' )
			);
		}

wp_cache_delete( $claim_key, 'options' );

return (int) $result > 0;
	}

/**
	 * Release a token exchange claim.
	 *
	 * @param string $token_hash SHA-256 hash of the plaintext token.
	 * @return void
	 */
	private function release_token_exchange_claim( $token_hash ) {
		delete_option( $this->get_token_claim_key( $token_hash ) );
	}

/**
	 * Atomically claim a token for scan. Mirrors `claim_token_for_exchange()`
	 * (same `add_option()` unique-constraint mutex, same staleness recovery)
	 * but uses its own option key so the scan and exchange windows are
	 * independent.
	 *
	 * Without this, two concurrent `/qr-login-scan` requests both pass the
	 * `state === pending` gate, both write a fresh challenge, and the last
	 * writer wins — leaving the loser's session_id silently orphaned and
	 * pointing at the wrong challenge.
	 *
	 * @param string $token_hash SHA-256 hash of the plaintext token.
	 * @param int    $expires_at Unix timestamp when the token expires.
	 * @return bool True if the claim was acquired.
	 */
	private function claim_token_for_scan( $token_hash, $expires_at ) {
		return $this->claim_token_with_option_key(
			self::SCAN_CLAIM_OPTION_PREFIX . $token_hash,
			$expires_at
		);
	}

/**
	 * Release a token scan claim owned by this request.
	 *
	 * @param string $token_hash SHA-256 hash of the plaintext token.
	 * @return void
	 */
	private function release_token_scan_claim( $token_hash ) {
		delete_option( self::SCAN_CLAIM_OPTION_PREFIX . $token_hash );
	}

/**
	 * Atomically claim a token for approval.
	 *
	 * @param string $token_hash SHA-256 hash of the plaintext token.
	 * @param int    $expires_at Unix timestamp when the claim should expire.
	 * @return bool True if the claim was acquired.
	 */
	private function claim_token_for_approval( $token_hash, $expires_at ) {
		return $this->claim_token_with_option_key(
			self::APPROVE_CLAIM_OPTION_PREFIX . $token_hash,
			$expires_at
		);
	}

/**
	 * Release a token approval claim owned by this request.
	 *
	 * @param string $token_hash SHA-256 hash of the plaintext token.
	 * @return void
	 */
	private function release_token_approval_claim( $token_hash ) {
		delete_option( self::APPROVE_CLAIM_OPTION_PREFIX . $token_hash );
	}

/**
	 * Get the remaining storage TTL for a token record.
	 *
	 * @param array<string, mixed> $token_data Token record.
	 * @return int Remaining TTL in seconds.
	 */
	private function get_token_record_ttl( array $token_data ) {
		return max(
			1,
			isset( $token_data['expires_at'] ) ? (int) $token_data['expires_at'] - time() : self::TOKEN_TTL
		);
	}

/**
	 * Delete the session-id to token-hash mapping for a token record.
	 *
	 * @param array<string, mixed> $token_data Token record.
	 * @return void
	 */
	private function delete_session_mapping_for_record( array $token_data ) {
		if ( empty( $token_data['challenge']['session_id'] ) ) {
			return;
		}

delete_transient(
			self::SESSION_TRANSIENT_PREFIX . hash( 'sha256', (string) $token_data['challenge']['session_id'] )
		);
	}

/**
	 * Validate that the configured site URL is HTTPS and return it.
	 *
	 * `is_ssl()` only tells us the current REQUEST is HTTPS — it says nothing about
	 * the canonical site URL WordPress is configured to advertise. `get_site_url()`
	 * itself is also insufficient because it passes its result through
	 * `set_url_scheme()`, which rewrites the scheme to match `is_ssl()` — so
	 * `get_site_url()` will return `https://…` whenever the request happens to be
	 * HTTPS, masking a stale `http://` `siteurl` option underneath. We therefore
	 * check the RAW stored option, which is what reflects admin configuration
	 * and what shows up in reset-password emails, webhooks, canonical redirects,
	 * etc. If that is `http://`, a misconfigured proxy that terminated TLS before
	 * reaching PHP could still cause this endpoint to hand the mobile app a cleartext
	 * site URL for the token-exchange POST.
	 *
	 * We deliberately reject (rather than silently normalizing to `https://`)
	 * because:
	 *   1. The misconfig usually affects other things (reset-password emails,
	 *      webhooks, canonical redirects). Failing loudly surfaces it.
	 *   2. Normalizing assumes the site actually serves HTTPS on the same host,
	 *      which we cannot verify from within a single request.
	 *   3. A 500 is strictly safer than a leaky success.
	 *
	 * @return string|\WP_Error The HTTPS site URL, or a WP_Error if it is not HTTPS.
	 */
	private function get_secure_site_url() {
		// Raw option: what the admin actually configured, before `set_url_scheme()`
		// inside `get_site_url()` normalizes it based on the current request's scheme.
		$raw_site_url = get_option( 'siteurl' );
		$raw_scheme   = is_string( $raw_site_url ) ? wp_parse_url( $raw_site_url, PHP_URL_SCHEME ) : null;

if ( 'https' !== $raw_scheme ) {
			return new \WP_Error(
				'insecure_site_url',
				__( 'QR login cannot be used because the site URL is not configured for HTTPS. Please update the WordPress Address (URL) in Settings → General to use https://.', 'woocommerce' ),
				array( 'status' => 500 )
			);
		}

// Use get_site_url() for the returned value so any scheme normalization
		// or filtering that WordPress applies downstream is preserved, then
		// validate the final value too. A plugin can still filter `site_url`
		// after the raw option check above; never hand the mobile app an
		// HTTP exchange target.
		$site_url     = get_site_url();
		$final_scheme = wp_parse_url( $site_url, PHP_URL_SCHEME );

if ( 'https' !== $final_scheme ) {
			return new \WP_Error(
				'insecure_site_url',
				__( 'QR login cannot be used because the site URL is not configured for HTTPS. Please update the WordPress Address (URL) in Settings → General to use https://.', 'woocommerce' ),
				array( 'status' => 500 )
			);
		}

return $site_url;
	}

/**
	 * Generate a QR login token.
	 *
	 * Creates a short-lived one-time token that can be exchanged for an Application
	 * Password by the mobile app. The caller is assumed to have already passed the
	 * `manage_woocommerce` capability check in `get_items_permissions_check()`.
	 *
	 * @param \WP_REST_Request<array<string, mixed>> $request Full details about the request.
	 * @return \WP_REST_Response|\WP_Error
	 */
	public function generate_token( $request ) {
		unset( $request );
		// Parameter required by WP REST contract but unused here.

// Check HTTPS.
		if ( ! is_ssl() ) {
			return new \WP_Error(
				'ssl_required',
				__( 'QR login requires an HTTPS connection.', 'woocommerce' ),
				array( 'status' => 403 )
			);
		}

// Verify the canonical site URL is HTTPS — is_ssl() alone is not enough
		// when WordPress is behind a misconfigured proxy.
		$site_url = $this->get_secure_site_url();
		if ( is_wp_error( $site_url ) ) {
			return $site_url;
		}

// Check Application Passwords are available.
		if ( ! $this->are_application_passwords_available() ) {
			return new \WP_Error(
				'application_passwords_unavailable',
				__( 'Application Passwords are not available on this site.', 'woocommerce' ),
				array( 'status' => 501 )
			);
		}

// Check rate limit.
		if ( ! $this->check_generation_rate_limit( get_current_user_id() ) ) {
			return new \WP_Error(
				'rate_limit_exceeded',
				__( 'Too many QR login requests. Please try again later.', 'woocommerce' ),
				array( 'status' => 429 )
			);
		}

// Generate a cryptographically secure token.
		$token      = wp_generate_password( 64, false );
		$token_hash = hash( 'sha256', $token );
		$now        = time();
		$expires_at = $now + self::TOKEN_TTL;

// Structured state-machine record. Subsequent transitions
		// (scan/approve/exchange) gate themselves on the current state at the
		// top of each handler.
		$token_data = array(
			'state'      => self::STATE_PENDING,
			'created_at' => $now,
			'state_at'   => $now,
			'user_id'    => get_current_user_id(),
			'site_url'   => $site_url,
			'expires_at' => $expires_at,
		);

set_transient( self::TOKEN_TRANSIENT_PREFIX . $token_hash, $token_data, self::TOKEN_TTL );

// Build the QR URL (deep link for the mobile app).
		$qr_url = sprintf(
			'woocommerce://qr-login?token=%s&siteUrl=%s',
			rawurlencode( $token ),
			rawurlencode( $site_url )
		);

return rest_ensure_response(
			array(
				'qr_url'     => $qr_url,
				'expires_at' => $expires_at,
				'ttl'        => self::TOKEN_TTL,
			)
		);
	}

/**
	 * Exchange a QR login token for an Application Password.
	 *
	 * This endpoint does not require authentication — the token serves
	 * as the authentication mechanism.
	 *
	 * @param \WP_REST_Request<array<string, mixed>> $request Full details about the request.
	 * @return \WP_REST_Response|\WP_Error
	 */
	public function exchange_token( $request ) {
		// Refuse to return credentials over a non-HTTPS request.
		if ( ! is_ssl() ) {
			return new \WP_Error(
				'ssl_required',
				__( 'QR login requires an HTTPS connection.', 'woocommerce' ),
				array( 'status' => 403 )
			);
		}

// Refuse to return credentials bound to a non-HTTPS site URL — see
		// get_secure_site_url() for rationale. A token that was minted while the
		// siteurl was still https:// but has since been changed to http:// should
		// also be refused here.
		$site_url = $this->get_secure_site_url();
		if ( is_wp_error( $site_url ) ) {
			return $site_url;
		}

// Defensive sanitize even though the REST `sanitize_callback` already
		// did so — guards against future refactors that bypass the callback.
		$token      = sanitize_text_field( (string) $request->get_param( 'token' ) );
		$token_hash = hash( 'sha256', $token );
		$key        = self::TOKEN_TRANSIENT_PREFIX . $token_hash;

$token_data = get_transient( $key );
		if ( ! is_array( $token_data ) ) {
			if ( ! $this->check_invalid_exchange_rate_limit() ) {
				return new \WP_Error(
					'rate_limit_exceeded',
					__( 'Too many exchange attempts. Please try again later.', 'woocommerce' ),
					array( 'status' => 429 )
				);
			}

return new \WP_Error(
				'invalid_token',
				__( 'Invalid or expired QR login token.', 'woocommerce' ),
				array( 'status' => 401 )
			);
		}

// Broad anonymous abuse guard applies only after token lookup. Random
		// invalid requests use the invalid-token bucket above so they cannot
		// exhaust this shared-IP guard for later valid exchanges behind the same
		// proxy/CDN IP.
		if ( ! $this->check_exchange_ip_rate_limit() ) {
			return new \WP_Error(
				'rate_limit_exceeded',
				__( 'Too many exchange attempts. Please try again later.', 'woocommerce' ),
				array( 'status' => 429 )
			);
		}

if ( ! $this->check_valid_exchange_rate_limit( $token_hash ) ) {
			return new \WP_Error(
				'rate_limit_exceeded',
				__( 'Too many exchange attempts. Please try again later.', 'woocommerce' ),
				array( 'status' => 429 )
			);
		}

if ( ! $this->claim_token_for_exchange( $token_hash, isset( $token_data['expires_at'] ) ? (int) $token_data['expires_at'] : time() + self::TOKEN_TTL ) ) {
			return new \WP_Error(
				'invalid_token',
				__( 'Invalid or expired QR login token.', 'woocommerce' ),
				array( 'status' => 401 )
			);
		}

// Re-read after acquiring the database claim in case another process
		// consumed or expired the token while this request was waiting.
		$token_data = get_transient( $key );
		if ( ! is_array( $token_data ) ) {
			$this->release_token_exchange_claim( $token_hash );
			return new \WP_Error(
				'invalid_token',
				__( 'Invalid or expired QR login token.', 'woocommerce' ),
				array( 'status' => 401 )
			);
		}

// Validate token hasn't expired (belt and suspenders with transient TTL).
		if ( ! empty( $token_data['expires_at'] ) && time() >= (int) $token_data['expires_at'] ) {
			delete_transient( $key );
			$this->delete_session_mapping_for_record( $token_data );
			$this->release_token_exchange_claim( $token_hash );
			return new \WP_Error(
				'token_expired',
				__( 'QR login token has expired.', 'woocommerce' ),
				array( 'status' => 401 )
			);
		}

// Number-matching enforcement: exchange must be preceded by /scan +
		// /approve. Anything other than `approved` (including `pending` —
		// scan was skipped — and `scanned` — scan completed but merchant
		// didn't tap a number yet) is a hard 412.
		$current_state = isset( $token_data['state'] ) ? (string) $token_data['state'] : self::STATE_PENDING;

if ( self::STATE_APPROVED !== $current_state ) {
			$this->release_token_exchange_claim( $token_hash );
			return new \WP_Error(
				'qr_login_not_approved',
				__( 'This QR login session has not been approved.', 'woocommerce' ),
				array( 'status' => 412 )
			);
		}

// Constant-time grant comparison. The grant is bound to this token
		// at /approve time and only handed back to the polling app via
		// /session-status, so an attacker who somehow learned the token
		// can't race the legit app to exchange after approval.
		$submitted_grant = (string) $request->get_param( 'exchange_grant' );
		$stored_grant    = isset( $token_data['exchange_grant'] ) ? (string) $token_data['exchange_grant'] : '';

if ( '' === $stored_grant || ! hash_equals( $stored_grant, $submitted_grant ) ) {
			$invalid_grant_attempts = isset( $token_data['invalid_grant_attempts'] ) ? (int) $token_data['invalid_grant_attempts'] : 0;
			++$invalid_grant_attempts;

$token_data['invalid_grant_attempts']          = $invalid_grant_attempts;
			$token_data['invalid_grant_last_attempted_at'] = time();

if ( $invalid_grant_attempts >= self::MAX_INVALID_GRANT_ATTEMPTS ) {
				$token_data['state']    = self::STATE_REJECTED;
				$token_data['state_at'] = time();

wc_get_logger()->warning(
					'QR login rejected after repeated invalid exchange grants',
					array(
						'source'  => 'qr-login-security',
						'user_id' => isset( $token_data['user_id'] ) ? (int) $token_data['user_id'] : 0,
						'ip'      => $this->get_client_ip(),
					)
				);
			}

set_transient( $key, $token_data, $this->get_token_record_ttl( $token_data ) );
			$this->release_token_exchange_claim( $token_hash );
			return new \WP_Error(
				'invalid_exchange_grant',
				__( 'Invalid exchange grant for this QR login session.', 'woocommerce' ),
				array( 'status' => 412 )
			);
		}//end if

$user_id = $token_data['user_id'];
		$user    = get_userdata( $user_id );

if ( ! $user ) {
			$this->release_token_exchange_claim( $token_hash );
			return new \WP_Error(
				'user_not_found',
				__( 'User associated with this token no longer exists.', 'woocommerce' ),
				array( 'status' => 404 )
			);
		}

// Application Passwords may have been disabled after the token was minted.
		if ( ! $this->are_application_passwords_available() ) {
			$this->release_token_exchange_claim( $token_hash );
			return new \WP_Error(
				'application_passwords_unavailable',
				__( 'Application Passwords are not available on this site.', 'woocommerce' ),
				array( 'status' => 501 )
			);
		}

// Mirror the permission check WP core performs in
		// WP_REST_Application_Passwords_Controller::create_item_permissions_check().
		// Capability or per-user availability filters could have changed in the
		// window between token generation and exchange.
		if ( ! user_can( $user, 'create_app_password', $user_id ) ) {
			$this->release_token_exchange_claim( $token_hash );
			return new \WP_Error(
				'rest_cannot_create_application_passwords',
				__( 'Application passwords are not available for your account. Please contact the site administrator for assistance.', 'woocommerce' ),
				array( 'status' => rest_authorization_required_code() )
			);
		}

// Source the device payload from the scan record. /qr-login-scan
		// requires a device object, so by the time we reach `approved` it's
		// guaranteed present. Re-sanitize defensively in case the transient
		// was tampered with at the storage layer.
		$device_source = isset( $token_data['challenge']['device'] ) && is_array( $token_data['challenge']['device'] )
			? $token_data['challenge']['device']
			: array();
		$device        = $this->sanitize_device_payload( $device_source );

// Create an Application Password for the mobile app. The name is
		// descriptive (e.g. "Woo Mobile · iPhone 15 · 2026-04-28") so the user
		// can identify it later in Users → Profile → Application Passwords.
		$app_password_result = \WP_Application_Passwords::create_new_application_password(
			$user_id,
			array(
				'name'   => $this->format_application_password_name( $device ),
				'app_id' => self::APP_ID,
			)
		);

if ( is_wp_error( $app_password_result ) ) {
			wc_get_logger()->error(
				sprintf(
					'QR login: failed to create Application Password for user %d: %s',
					$user_id,
					$app_password_result->get_error_message()
				),
				array( 'source' => 'mobile-app-qr-login' )
			);
			$this->release_token_exchange_claim( $token_hash );
			return new \WP_Error(
				'application_password_failed',
				__( 'Could not create a mobile-app credential. Please try again, or contact your site administrator.', 'woocommerce' ),
				array( 'status' => 500 )
			);
		}

list( $new_password, $item ) = $app_password_result;

// Write a "consumed" record so wc-admin's polling client can transition
		// from "QR shown" to "Signed in successfully on {device}" and surface
		// a revoke button. Same TTL as the original token transient — there's
		// no value in keeping this record longer than the modal that polls it.
		$consumed_record = array(
			'consumed_at' => time(),
			'user_id'     => $user_id,
			'ap_uuid'     => $item['uuid'],
			'ap_name'     => $item['name'],
			'device'      => $device,
		);
		set_transient(
			self::CONSUMED_TRANSIENT_PREFIX . $token_hash,
			$consumed_record,
			self::TOKEN_TTL
		);

// One-shot: consume only after the Application Password has been
		// successfully created and the consumed record is visible to wc-admin's
		// polling client.
		delete_transient( $key );
		$this->delete_session_mapping_for_record( $token_data );
		$this->release_token_exchange_claim( $token_hash );

// Notify the merchant out-of-band so they're aware of a fresh sign-in
		// even when they aren't currently looking at wc-admin. Wrapped in a
		// try/catch + filter to keep the exchange path uninterrupted if the
		// site's mailer is misconfigured.
		$this->maybe_send_sign_in_notification_email( $user, $consumed_record );

return rest_ensure_response(
			array(
				'success'              => true,
				'user_login'           => $user->user_login,
				'user_email'           => $user->user_email,
				'user_id'              => $user_id,
				'site_url'             => $site_url,
				'application_password' => $new_password,
				'uuid'                 => $item['uuid'],
			)
		);
	}

/**
	 * Get the status of a previously generated QR login token.
	 *
	 * Used by the wc-admin UI to poll while the QR is on screen. Returns one of:
	 *   - `pending`  — token transient exists, has not been exchanged yet.
	 *   - `consumed` — token has been exchanged; payload includes the device that
	 *                  signed in and the AP UUID so the UI can render the
	 *                  confirmation panel and (optionally) revoke the AP.
	 *   - `expired`  — neither transient exists, so the token has expired or
	 *                  was never valid for this user.
	 *
	 * The user calling this endpoint must be the same user who minted the token.
	 * That's defense in depth — tokens are 64 random chars and not realistically
	 * guessable, but cross-user status reads should be impossible regardless.
	 *
	 * @param \WP_REST_Request<array<string, mixed>> $request Full details about the request.
	 * @return \WP_REST_Response|\WP_Error
	 */
	public function get_status( $request ) {
		// Defeat any intermediary cache (Cloudflare, NGINX micro-cache, browser, edge proxy)
		// that might pin this GET to its first response. Polling endpoints are by definition
		// state-bearing — every tick must see the live transient. Returning a stale `scanned`
		// response forever is exactly the symptom we'd see if the cache pins the first hit.
		nocache_headers();

$user_id = get_current_user_id();

if ( ! $this->check_status_rate_limit( $user_id ) ) {
			return new \WP_Error(
				'rate_limit_exceeded',
				__( 'Too many QR login status checks. Please try again later.', 'woocommerce' ),
				array( 'status' => 429 )
			);
		}

$token = (string) $request->get_param( 'token' );
		if ( '' === $token ) {
			return $this->rest_ensure_nocache_response( array( 'status' => 'expired' ) );
		}

$token_hash = hash( 'sha256', $token );

// Consumed lookup first — once a token has been exchanged the main
		// transient is deleted, but we keep a one-way breadcrumb at the
		// `_wc_qr_login_consumed_` key so the polling client (which still
		// has the plaintext token) can render the success panel.
		$consumed = get_transient( self::CONSUMED_TRANSIENT_PREFIX . $token_hash );
		if ( is_array( $consumed ) ) {
			if ( ! isset( $consumed['user_id'] ) || (int) $consumed['user_id'] !== (int) $user_id ) {
				return $this->rest_ensure_nocache_response( array( 'status' => 'expired' ) );
			}

return $this->rest_ensure_nocache_response(
				array(
					'status'      => self::STATE_CONSUMED,
					'consumed_at' => isset( $consumed['consumed_at'] ) ? (int) $consumed['consumed_at'] : null,
					'ap_uuid'     => isset( $consumed['ap_uuid'] ) ? (string) $consumed['ap_uuid'] : null,
					'ap_name'     => isset( $consumed['ap_name'] ) ? (string) $consumed['ap_name'] : null,
					'device'      => isset( $consumed['device'] ) && is_array( $consumed['device'] ) ? $consumed['device'] : array(),
				)
			);
		}

$record = get_transient( self::TOKEN_TRANSIENT_PREFIX . $token_hash );
		if ( ! is_array( $record ) ) {
			return $this->rest_ensure_nocache_response( array( 'status' => self::STATE_EXPIRED ) );
		}

// Cross-user defense in depth — same as before.
		if ( ! isset( $record['user_id'] ) || (int) $record['user_id'] !== (int) $user_id ) {
			return $this->rest_ensure_nocache_response( array( 'status' => self::STATE_EXPIRED ) );
		}

$state = isset( $record['state'] ) ? (string) $record['state'] : self::STATE_PENDING;

// Rejected / expired states are terminal — surface them directly so
		// wc-admin can render the "Login denied" terminal screen.
		if ( in_array( $state, array( self::STATE_REJECTED, self::STATE_EXPIRED ), true ) ) {
			return $this->rest_ensure_nocache_response( array( 'status' => $state ) );
		}

if ( ! empty( $record['expires_at'] ) && time() >= (int) $record['expires_at'] ) {
			return $this->rest_ensure_nocache_response( array( 'status' => self::STATE_EXPIRED ) );
		}

// While in `scanned`, surface the shuffled candidate triple and the
		// device that scanned so wc-admin can render the matching UI. The
		// REAL number is never returned via this endpoint — only the
		// shuffled triple of (real + 2 distractors) is, so an XSS / hostile
		// extension can't read which one is correct from JS state.
		if ( self::STATE_SCANNED === $state ) {
			$challenge = isset( $record['challenge'] ) && is_array( $record['challenge'] ) ? $record['challenge'] : array();
			$numbers   = $this->shuffled_candidate_numbers( $challenge );

return $this->rest_ensure_nocache_response(
				array(
					'status'     => self::STATE_SCANNED,
					'numbers'    => $numbers,
					'device'     => isset( $challenge['device'] ) && is_array( $challenge['device'] ) ? $challenge['device'] : array(),
					'expires_at' => isset( $challenge['expires_at'] ) ? (int) $challenge['expires_at'] : null,
				)
			);
		}

// Approved (post-tap, pre-exchange) — surface so a wc-admin tab that
		// reloaded between approve and exchange shows the "Signing in…"
		// transitional state rather than going back to the QR.
		if ( self::STATE_APPROVED === $state ) {
			return $this->rest_ensure_nocache_response( array( 'status' => self::STATE_APPROVED ) );
		}

// Pending: same shape as before, plus the new `state` field for
		// clients that want to switch on it directly.
		return $this->rest_ensure_nocache_response(
			array(
				'status'     => self::STATE_PENDING,
				'expires_at' => isset( $record['expires_at'] ) ? (int) $record['expires_at'] : null,
			)
		);
	}

/**
	 * Revoke (delete) the Application Password issued by a QR login exchange.
	 *
	 * The current user must own the AP being revoked — verified via
	 * `WP_Application_Passwords::get_user_application_password()`. We
	 * deliberately do NOT use `current_user_can( 'edit_user', $user_id )`
	 * because that would let a higher-privilege admin revoke another user's AP
	 * here; the QR flow's revoke surface is for "I just authorized this — undo,"
	 * not for site-wide AP management (which lives at Users → Profile).
	 *
	 * @param \WP_REST_Request<array<string, mixed>> $request Full details about the request.
	 * @return \WP_REST_Response|\WP_Error
	 */
	public function revoke_password( $request ) {
		$user_id = get_current_user_id();

if ( ! $this->check_revoke_rate_limit( $user_id ) ) {
			return new \WP_Error(
				'rate_limit_exceeded',
				__( 'Too many QR login revoke attempts. Please try again later.', 'woocommerce' ),
				array( 'status' => 429 )
			);
		}

if ( ! $this->are_application_passwords_available() ) {
			return new \WP_Error(
				'application_passwords_unavailable',
				__( 'Application Passwords are not available on this site.', 'woocommerce' ),
				array( 'status' => 501 )
			);
		}

$uuid = (string) $request->get_param( 'uuid' );

// Ownership check: the AP must exist AND belong to the current user.
		$ap = \WP_Application_Passwords::get_user_application_password( $user_id, $uuid );
		if ( ! is_array( $ap ) ) {
			return new \WP_Error(
				'application_password_not_found',
				__( 'No matching Application Password to revoke.', 'woocommerce' ),
				array( 'status' => 404 )
			);
		}

$deleted = \WP_Application_Passwords::delete_application_password( $user_id, $uuid );
		if ( true !== $deleted ) {
			return new \WP_Error(
				'application_password_revoke_failed',
				__( 'Could not revoke the Application Password. Please try again.', 'woocommerce' ),
				array( 'status' => 500 )
			);
		}

return rest_ensure_response(
			array(
				'success' => true,
				'uuid'    => $uuid,
			)
		);
	}

/**
	 * Whitelist + sanitize the `device` payload sent by the mobile app.
	 *
	 * Returns an array of strings keyed by the whitelisted keys defined in
	 * `DEVICE_PAYLOAD_KEYS`. Anything outside that whitelist is dropped. Each
	 * value is run through `sanitize_text_field()` and capped at
	 * `DEVICE_FIELD_MAX_LENGTH` characters. The function is total — pass `null`
	 * or anything non-array and you get back `array()`.
	 *
	 * @param mixed $device Raw payload from the request.
	 * @return array<string, string>
	 */
	private function sanitize_device_payload( $device ) {
		if ( ! is_array( $device ) ) {
			return array();
		}

$sanitized = array();
		foreach ( self::DEVICE_PAYLOAD_KEYS as $key ) {
			if ( ! isset( $device[ $key ] ) || ! is_scalar( $device[ $key ] ) ) {
				continue;
			}
			$value = sanitize_text_field( (string) $device[ $key ] );
			if ( '' === $value ) {
				continue;
			}
			if ( strlen( $value ) > self::DEVICE_FIELD_MAX_LENGTH ) {
				$value = substr( $value, 0, self::DEVICE_FIELD_MAX_LENGTH );
			}
			$sanitized[ $key ] = $value;
		}

return $sanitized;
	}

/**
	 * Build a descriptive name for the Application Password issued by the QR
	 * login exchange.
	 *
	 * Preferred: `Woo Mobile · iPhone 15 · 2026-04-28` (model + ISO date).
	 * Falls back to `Woo Mobile · iOS · 2026-04-28` when only the OS is known.
	 * The scan endpoint requires at least model or OS. The legacy fallback is
	 * retained as a defensive guard in case stored token data is corrupted.
	 *
	 * The name is what the merchant sees in WP admin → Users → Profile →
	 * Application Passwords, so it should be human-readable, single-line, and
	 * not contain anything that would only make sense to an engineer.
	 *
	 * @param array<string, string> $device Sanitized device payload.
	 * @return string
	 */
	private function format_application_password_name( array $device ): string {
		$model = isset( $device['model'] ) ? trim( $device['model'] ) : '';
		$os    = isset( $device['os'] ) ? trim( $device['os'] ) : '';

// Prefer model (e.g. "iPhone 15", "Pixel 10"); fall back to the OS
		// label if a particular device build returns an empty MODEL string.
		// Both fields come from the platform SDK on the mobile side and are
		// effectively always populated, but defending against an empty model
		// is cheaper than chasing the edge case at runtime.
		$descriptor = '' !== $model ? $model : $os;
		if ( '' === $descriptor ) {
			return __( 'WooCommerce Mobile App (QR Login)', 'woocommerce' );
		}

// Use the site's configured timezone so the date the merchant sees in
		// the AP list matches what they'd see in the rest of wp-admin.
		$date = wp_date( 'Y-m-d' );

/* translators: 1: device descriptor (model or OS, e.g. "iPhone 15"). 2: ISO date the AP was created. */
		return sprintf( __( 'Woo Mobile · %1$s · %2$s', 'woocommerce' ), $descriptor, $date );
	}

/**
	 * Per-user rate limit for the polling status endpoint.
	 *
	 * @param int $user_id The user ID.
	 * @return bool True if within rate limit.
	 */
	private function check_status_rate_limit( $user_id ) {
		return QRLoginRateLimits::consume( QRLoginRateLimits::BUCKET_STATUS, (string) $user_id );
	}

/**
	 * Per-user rate limit for the revoke endpoint.
	 *
	 * @param int $user_id The user ID.
	 * @return bool True if within rate limit.
	 */
	private function check_revoke_rate_limit( $user_id ) {
		return QRLoginRateLimits::consume( QRLoginRateLimits::BUCKET_REVOKE, (string) $user_id );
	}

/**
	 * Mobile app reports the QR was scanned. Generates the number-match
	 * challenge, marks the state as `scanned`, and returns the *real* number
	 * + a session id back to the app. Public — the token is the auth.
	 *
	 * Hard-break compat: clients that don't send `supports_number_matching`
	 * get 426 Upgrade Required. The Android Task 7 PR adds the flag; older
	 * apps in the wild see a clear "update required" error.
	 *
	 * @param \WP_REST_Request<array<string, mixed>> $request Full details about the request.
	 * @return \WP_REST_Response|\WP_Error
	 */
	public function scan_token( $request ) {
		if ( ! is_ssl() ) {
			return new \WP_Error(
				'ssl_required',
				__( 'QR login requires an HTTPS connection.', 'woocommerce' ),
				array( 'status' => 403 )
			);
		}

if ( true !== (bool) $request->get_param( 'supports_number_matching' ) ) {
			return new \WP_Error(
				'mobile_app_update_required',
				__( 'This Woo mobile app version is no longer supported for QR sign-in. Please update the app and try again.', 'woocommerce' ),
				array( 'status' => 426 )
			);
		}

$token      = (string) $request->get_param( 'token' );
		$token_hash = hash( 'sha256', $token );
		$key        = self::TOKEN_TRANSIENT_PREFIX . $token_hash;

$record = get_transient( $key );
		if ( ! is_array( $record ) ) {
			if ( ! $this->check_invalid_scan_rate_limit() ) {
				return new \WP_Error(
					'rate_limit_exceeded',
					__( 'Too many QR login scans. Please try again later.', 'woocommerce' ),
					array( 'status' => 429 )
				);
			}

return new \WP_Error(
				'invalid_token',
				__( 'Invalid or expired QR login token.', 'woocommerce' ),
				array( 'status' => 401 )
			);
		}

if ( ! $this->check_scan_rate_limit() ) {
			return new \WP_Error(
				'rate_limit_exceeded',
				__( 'Too many QR login scans. Please try again later.', 'woocommerce' ),
				array( 'status' => 429 )
			);
		}

$device = $this->sanitize_device_payload( $request->get_param( 'device' ) );
		if ( empty( $device['model'] ) && empty( $device['os'] ) ) {
			return new \WP_Error(
				'invalid_device',
				__( 'QR login requires device information from the mobile app.', 'woocommerce' ),
				array( 'status' => 400 )
			);
		}

// Atomic mutex on the read-mutate-write window. Without this, two
		// concurrent scans both pass the state==pending check below and both
		// write a new challenge — last writer wins, the loser's session_id
		// is silently orphaned. The state check is kept as defense-in-depth
		// for any path that bypasses the claim (e.g. the staleness branch).
		if ( ! $this->claim_token_for_scan(
			$token_hash,
			isset( $record['expires_at'] ) ? (int) $record['expires_at'] : time() + self::TOKEN_TTL
		) ) {
			return new \WP_Error(
				'qr_login_already_scanned',
				__( 'This QR login session is no longer accepting scans.', 'woocommerce' ),
				array( 'status' => 409 )
			);
		}

$current_state = isset( $record['state'] ) ? (string) $record['state'] : self::STATE_PENDING;
		if ( self::STATE_PENDING !== $current_state ) {
			$this->release_token_scan_claim( $token_hash );
			return new \WP_Error(
				'qr_login_already_scanned',
				__( 'This QR login session is no longer accepting scans.', 'woocommerce' ),
				array( 'status' => 409 )
			);
		}

$challenge_numbers = $this->generate_challenge_numbers();
		$session_id        = wp_generate_uuid4();
		$now               = time();
		$token_expires_at  = isset( $record['expires_at'] ) ? (int) $record['expires_at'] : $now + self::TOKEN_TTL;

if ( $token_expires_at <= $now ) {
			$this->release_token_scan_claim( $token_hash );
			return new \WP_Error(
				'invalid_token',
				__( 'Invalid or expired QR login token.', 'woocommerce' ),
				array( 'status' => 401 )
			);
		}

$challenge_expires_at = min( $now + self::CHALLENGE_TTL_SECONDS, $token_expires_at );
		$challenge_ttl        = max( 1, $challenge_expires_at - $now );

// Shuffle the candidate triple ONCE at scan time and persist the chosen ordering so
		// every subsequent /qr-login-status poll returns the same array. Re-shuffling per-poll
		// would make the wc-admin tile order flicker every 2.5 s — terrible UX, and makes the
		// merchant doubt they're reading the right number.
		$candidates = array_merge( array( $challenge_numbers['real'] ), $challenge_numbers['distractors'] );
		shuffle( $candidates );

$record['state']     = self::STATE_SCANNED;
		$record['state_at']  = $now;
		$record['challenge'] = array(
			'real'        => $challenge_numbers['real'],
			'distractors' => $challenge_numbers['distractors'],
			'shuffled'    => $candidates,
			'session_id'  => $session_id,
			'expires_at'  => $challenge_expires_at,
			'device'      => $device,
		);

// Re-use whatever TTL the original transient had left. The challenge
		// window itself is capped to the remaining token lifetime, while the
		// storage TTL keeps the full challenge visible for normal fresh scans.
		$ttl_left    = max( 1, $token_expires_at - $now );
		$storage_ttl = min( $ttl_left, self::CHALLENGE_TTL_SECONDS + 30 );
		set_transient( $key, $record, $storage_ttl );

// Sibling transient that resolves session_id → token_hash for the
		// app's session-status poll. Stored hashed so the session id isn't
		// directly indexable in wp_options.
		set_transient(
			self::SESSION_TRANSIENT_PREFIX . hash( 'sha256', $session_id ),
			$token_hash,
			$storage_ttl
		);

$this->release_token_scan_claim( $token_hash );

return rest_ensure_response(
			array(
				'session_id'  => $session_id,
				'real_number' => $challenge_numbers['real'],
				'expires_in'  => $challenge_ttl,
			)
		);
	}

/**
	 * Merchant taps a number on wc-admin. Server validates against the
	 * stored real number with `hash_equals()` (constant-time). Correct →
	 * `approved` + mints `exchange_grant`. Wrong → `rejected` (terminal,
	 * security event logged). One-strike: no retry.
	 *
	 * @param \WP_REST_Request<array<string, mixed>> $request Full details about the request.
	 * @return \WP_REST_Response|\WP_Error
	 */
	public function approve_token( $request ) {
		$user_id = get_current_user_id();

if ( ! $this->check_approve_rate_limit( $user_id ) ) {
			return new \WP_Error(
				'rate_limit_exceeded',
				__( 'Too many QR login approval attempts. Please try again later.', 'woocommerce' ),
				array( 'status' => 429 )
			);
		}

$token      = (string) $request->get_param( 'token' );
		$token_hash = hash( 'sha256', $token );
		$key        = self::TOKEN_TRANSIENT_PREFIX . $token_hash;

$record = get_transient( $key );
		if ( ! is_array( $record ) ) {
			return new \WP_Error(
				'invalid_token',
				__( 'Invalid or expired QR login token.', 'woocommerce' ),
				array( 'status' => 401 )
			);
		}

$approval_claim_expires_at = ! empty( $record['challenge']['expires_at'] )
			? (int) $record['challenge']['expires_at']
			: ( isset( $record['expires_at'] ) ? (int) $record['expires_at'] : time() + self::TOKEN_TTL );
		if ( ! $this->claim_token_for_approval( $token_hash, $approval_claim_expires_at ) ) {
			return new \WP_Error(
				'qr_login_approval_in_progress',
				__( 'This QR login session is already being approved.', 'woocommerce' ),
				array( 'status' => 409 )
			);
		}

// Re-read after acquiring the database claim in case another request
		// approved, rejected, or expired the challenge while this one was waiting.
		$record = get_transient( $key );
		if ( ! is_array( $record ) ) {
			$this->release_token_approval_claim( $token_hash );
			return new \WP_Error(
				'invalid_token',
				__( 'Invalid or expired QR login token.', 'woocommerce' ),
				array( 'status' => 401 )
			);
		}

// Same cross-user defense as get_status — only the user that minted
		// the token can approve it.
		if ( ! isset( $record['user_id'] ) || (int) $record['user_id'] !== (int) $user_id ) {
			$this->release_token_approval_claim( $token_hash );
			return new \WP_Error(
				'invalid_token',
				__( 'Invalid or expired QR login token.', 'woocommerce' ),
				array( 'status' => 401 )
			);
		}

if ( ! empty( $record['expires_at'] ) && time() >= (int) $record['expires_at'] ) {
			$record['state']    = self::STATE_EXPIRED;
			$record['state_at'] = time();
			set_transient( $key, $record, 60 );
			$this->release_token_approval_claim( $token_hash );
			return new \WP_Error(
				'qr_login_expired',
				__( 'The QR login challenge has expired. Please generate a new code.', 'woocommerce' ),
				array( 'status' => 410 )
			);
		}

$current_state = isset( $record['state'] ) ? (string) $record['state'] : self::STATE_PENDING;
		if ( self::STATE_SCANNED !== $current_state ) {
			$this->release_token_approval_claim( $token_hash );
			return new \WP_Error(
				'qr_login_not_scanned',
				__( 'This QR login session is not waiting for approval.', 'woocommerce' ),
				array( 'status' => 409 )
			);
		}

// Challenge expiry — normally 90 s after scan, capped by token expiry.
		if ( ! empty( $record['challenge']['expires_at'] ) && time() > (int) $record['challenge']['expires_at'] ) {
			$record['state']    = self::STATE_EXPIRED;
			$record['state_at'] = time();
			set_transient( $key, $record, 60 );
			$this->release_token_approval_claim( $token_hash );
			return new \WP_Error(
				'qr_login_expired',
				__( 'The QR login challenge has expired. Please generate a new code.', 'woocommerce' ),
				array( 'status' => 410 )
			);
		}

$choice = (string) $request->get_param( 'choice' );
		$real   = isset( $record['challenge']['real'] ) ? (string) $record['challenge']['real'] : '';

// Constant-time compare. Defends against PHP string-comparison fast
		// paths that can leak prefix-matching info via timing.
		if ( '' === $real || ! hash_equals( $real, $choice ) ) {
			$record['state']    = self::STATE_REJECTED;
			$record['state_at'] = time();
			set_transient( $key, $record, 60 );

wc_get_logger()->warning(
				'QR login number-match rejected — wrong choice submitted',
				array(
					'source'  => 'qr-login-security',
					'user_id' => (int) $user_id,
					'ip'      => $this->get_client_ip(),
					'device'  => isset( $record['challenge']['device'] ) ? $record['challenge']['device'] : array(),
				)
			);

$this->release_token_approval_claim( $token_hash );
			return rest_ensure_response( array( 'state' => self::STATE_REJECTED ) );
		}

$record['state']          = self::STATE_APPROVED;
		$record['state_at']       = time();
		$record['exchange_grant'] = bin2hex( random_bytes( self::EXCHANGE_GRANT_BYTES ) );
		$ttl                      = max(
			1,
			isset( $record['expires_at'] ) ? (int) $record['expires_at'] - time() : self::CHALLENGE_TTL_SECONDS
		);

set_transient( $key, $record, $ttl );
		$this->release_token_approval_claim( $token_hash );

return rest_ensure_response( array( 'state' => self::STATE_APPROVED ) );
	}

/**
	 * Mobile app polls this with the session id from /scan. Returns the
	 * current state of the underlying token, plus — when state is
	 * `approved` — the `exchange_grant` nonce required by /qr-login-exchange.
	 *
	 * @param \WP_REST_Request<array<string, mixed>> $request Full details about the request.
	 * @return \WP_REST_Response|\WP_Error
	 */
	public function get_session_status( $request ) {
		// Defeat any intermediary cache (Cloudflare, NGINX micro-cache, OkHttp's shared
		// cache, edge proxy) that might pin this GET to its first response. Polling
		// endpoints are by definition state-bearing — every tick must see the live
		// transient. Returning a stale `scanned` response forever is exactly the
		// symptom we see if the cache pins the first hit.
		nocache_headers();

if ( ! is_ssl() ) {
			return new \WP_Error(
				'ssl_required',
				__( 'QR login requires an HTTPS connection.', 'woocommerce' ),
				array( 'status' => 403 )
			);
		}

$session_id     = (string) $request->get_param( 'session_id' );
		$submitted_hash = (string) $request->get_param( 'token_hash' );

$token_hash = get_transient( self::SESSION_TRANSIENT_PREFIX . hash( 'sha256', $session_id ) );
		if ( ! is_string( $token_hash ) || '' === $token_hash ) {
			// Either the session never existed or it has expired. Either way,
			// surface as expired to the polling app.
			return $this->rest_ensure_nocache_response( array( 'state' => self::STATE_EXPIRED ) );
		}

// Bind grant delivery to proof of token knowledge: an attacker who
		// learns the session_id alone (mobile logs, network capture, debug
		// output) cannot poll for state transitions and walk away with the
		// `exchange_grant` the moment the merchant approves. The mobile app
		// already holds the plaintext token from the QR scan — passing
		// SHA-256(token) on every poll is essentially free for it.
		// `hash_equals` for constant-time comparison; `expired` opacity so
		// we never leak whether the session_id is real or not.
		if ( ! hash_equals( $token_hash, $submitted_hash ) ) {
			return $this->rest_ensure_nocache_response( array( 'state' => self::STATE_EXPIRED ) );
		}

if ( ! $this->check_session_status_rate_limit( $session_id ) ) {
			return new \WP_Error(
				'rate_limit_exceeded',
				__( 'Too many QR login session-status checks. Please try again later.', 'woocommerce' ),
				array( 'status' => 429 )
			);
		}

$record = get_transient( self::TOKEN_TRANSIENT_PREFIX . $token_hash );
		if ( ! is_array( $record ) ) {
			return $this->rest_ensure_nocache_response( array( 'state' => self::STATE_EXPIRED ) );
		}

$canonical_session = isset( $record['challenge']['session_id'] ) ? (string) $record['challenge']['session_id'] : '';
		if ( '' === $canonical_session || ! hash_equals( $canonical_session, $session_id ) ) {
			return $this->rest_ensure_nocache_response( array( 'state' => self::STATE_EXPIRED ) );
		}

$state    = isset( $record['state'] ) ? (string) $record['state'] : self::STATE_PENDING;
		$response = array( 'state' => $state );

if ( in_array( $state, array( self::STATE_REJECTED, self::STATE_EXPIRED ), true ) ) {
			return $this->rest_ensure_nocache_response( $response );
		}

if ( ! empty( $record['expires_at'] ) && time() >= (int) $record['expires_at'] ) {
			return $this->rest_ensure_nocache_response( array( 'state' => self::STATE_EXPIRED ) );
		}

if ( self::STATE_APPROVED === $state && ! empty( $record['exchange_grant'] ) ) {
			$response['exchange_grant'] = (string) $record['exchange_grant'];
		}

return $this->rest_ensure_nocache_response( $response );
	}

/**
	 * Generate a 1-real + 2-distractor number triple for the match
	 * challenge. Distractors must differ from the real number and from each
	 * other by ≥ 100 — defends against a partial-read leak fingerprinting
	 * the real one (no `042` vs `043` near-misses).
	 *
	 * Uses `random_int()` (CSPRNG-backed) rather than `wp_rand()`, which can
	 * fall back to mt_rand() and is predictable.
	 *
	 * @return array{real: string, distractors: array<int, string>}
	 * @throws \RuntimeException If a valid distractor set cannot be generated.
	 */
	private function generate_challenge_numbers(): array {
		$real             = random_int( 0, 999 );
		$valid_candidates = array();

for ( $candidate = 0; $candidate <= 999; $candidate++ ) {
			if ( $candidate !== $real && abs( $candidate - $real ) >= 100 ) {
				$valid_candidates[] = $candidate;
			}
		}

if ( empty( $valid_candidates ) ) {
			throw new \RuntimeException( 'QR login challenge generator could not find a valid first distractor.' );
		}

$first_index = random_int( 0, count( $valid_candidates ) - 1 );
		$first       = $valid_candidates[ $first_index ];

$second_candidates = array_values(
			array_filter(
				$valid_candidates,
				static function ( $candidate ) use ( $first ) {
					return abs( $candidate - $first ) >= 100;
				}
			)
		);

if ( empty( $second_candidates ) ) {
			throw new \RuntimeException( 'QR login challenge generator could not find a valid second distractor.' );
		}

$second      = $second_candidates[ random_int( 0, count( $second_candidates ) - 1 ) ];
		$distractors = array( $first, $second );

return array(
			'real'        => str_pad( (string) $real, 3, '0', STR_PAD_LEFT ),
			'distractors' => array_map(
				static function ( $n ) {
					return str_pad( (string) $n, 3, '0', STR_PAD_LEFT );
				},
				$distractors
			),
		);
	}

/**
	 * Build the shuffled candidate triple returned by `/qr-login-status`
	 * while in the `scanned` state. The order is fixed at scan time (in
	 * `scan_token`) and stored in `challenge.shuffled` so every poll returns
	 * the same array — re-shuffling per-poll caused visible tile flicker on
	 * wc-admin. Falls back to building + shuffling on the fly for any token
	 * record that predates the persisted-shuffle change.
	 *
	 * @param array<string, mixed> $challenge The challenge payload from the token record.
	 * @return array<int, string>
	 */
	private function shuffled_candidate_numbers( array $challenge ): array {
		if ( isset( $challenge['shuffled'] ) && is_array( $challenge['shuffled'] ) ) {
			return array_map( 'strval', $challenge['shuffled'] );
		}

$real        = isset( $challenge['real'] ) ? (string) $challenge['real'] : '';
		$distractors = isset( $challenge['distractors'] ) && is_array( $challenge['distractors'] )
			? array_map( 'strval', $challenge['distractors'] )
			: array();

$candidates = array_merge( array( $real ), $distractors );
		shuffle( $candidates );
		return $candidates;
	}

/**
	 * Per-IP rate limit on /qr-login-scan.
	 *
	 * @return bool True if within rate limit.
	 */
	private function check_scan_rate_limit() {
		return QRLoginRateLimits::consume( QRLoginRateLimits::BUCKET_SCAN, $this->get_client_ip() );
	}

/**
	 * Per-user rate limit on /qr-login-approve.
	 *
	 * @param int $user_id The user ID.
	 * @return bool True if within rate limit.
	 */
	private function check_approve_rate_limit( $user_id ) {
		return QRLoginRateLimits::consume( QRLoginRateLimits::BUCKET_APPROVE, (string) $user_id );
	}

/**
	 * Per-session rate limit on /qr-login-session-status.
	 *
	 * @param string $session_id The session ID.
	 * @return bool True if within rate limit.
	 */
	private function check_session_status_rate_limit( $session_id ) {
		return QRLoginRateLimits::consume( QRLoginRateLimits::BUCKET_SESSION_STATUS, $session_id );
	}

/**
	 * Send the merchant a transactional email summarizing a successful QR
	 * sign-in, unless they (or a site owner) opt out via the
	 * `woocommerce_qr_login_should_send_signin_email` filter.
	 *
	 * Wrapped so a misconfigured mailer cannot break the exchange path. Mailer
	 * false returns and exceptions are logged, but delivery never blocks the API
	 * response.
	 *
	 * @param \WP_User             $user            The user who minted the token (recipient).
	 * @param array<string, mixed> $consumed_record The record persisted to the consumed transient (keys: consumed_at, user_id, ap_uuid, ap_name, device).
	 * @return void
	 */
	private function maybe_send_sign_in_notification_email( \WP_User $user, array $consumed_record ): void {
		/**
		 * Filter whether to send the QR sign-in notification email.
		 *
		 * Default: true. Return false to suppress the send for a specific
		 * user, environment (e.g. staging), or test run.
		 *
		 * @since 10.9.0
		 *
		 * @param bool                 $should_send     Whether to send the email.
		 * @param \WP_User             $user            The user who minted the QR token.
		 * @param array<string, mixed> $consumed_record The consumed record about to be emailed (keys: consumed_at, user_id, ap_uuid, ap_name, device).
		 */
		$should_send = (bool) apply_filters(
			'woocommerce_qr_login_should_send_signin_email',
			true,
			$user,
			$consumed_record
		);

if ( ! $should_send ) {
			return;
		}

try {
			if ( ! $this->send_sign_in_notification_email( $user, $consumed_record ) ) {
				wc_get_logger()->warning(
					sprintf(
						'QR sign-in notification email failed for user %d: wp_mail returned false',
						$user->ID
					),
					array( 'source' => 'mobile-app-qr-login' )
				);
			}
		} catch ( \Throwable $e ) {
			// Don't surface mailer failures to the exchange response — the
			// merchant already has the API result, and the email is best-effort.
			// Log instead so a misconfigured mailer is observable rather than
			// invisible. Catch \Throwable so an \Error from the mailer also
			// stays out of the exchange path.
			wc_get_logger()->warning(
				sprintf(
					'QR sign-in notification email failed for user %d: %s',
					$user->ID,
					$e->getMessage()
				),
				array( 'source' => 'mobile-app-qr-login' )
			);
		}
	}

/**
	 * Render and dispatch the sign-in notification email.
	 *
	 * Uses `wp_mail()` directly with our own minimal HTML shell rather than
	 * `WC()->mailer()->wrap_message()` — the WC wrapper auto-prepends a small
	 * site-name header that duplicates the subject line shown by most clients
	 * and constrains the body width. Owning the wrapper lets us deliver one
	 * coherent layout.
	 *
	 * @param \WP_User             $user            Recipient.
	 * @param array<string, mixed> $consumed_record The consumed record (same shape as `maybe_send_sign_in_notification_email`).
	 * @return bool True if WordPress accepted the message for delivery.
	 */
	private function send_sign_in_notification_email( \WP_User $user, array $consumed_record ): bool {
		$site_name = wp_specialchars_decode(
			(string) get_bloginfo( 'name' ),
			ENT_QUOTES
		);

/* translators: %s: site name. */
		$subject = sprintf( __( 'A new device signed in to %s', 'woocommerce' ), $site_name );

$body_html = $this->render_sign_in_notification_email_body( $user, $consumed_record, $site_name, $subject );

return wp_mail(
			$user->user_email,
			$subject,
			$body_html,
			array( 'Content-Type: text/html; charset=UTF-8' )
		);
	}

/**
	 * Render the full HTML email document for the sign-in notification.
	 *
	 * @param \WP_User             $user            Recipient.
	 * @param array<string, mixed> $consumed_record The consumed record (same shape as `maybe_send_sign_in_notification_email`).
	 * @param string               $site_name       Decoded site name (passed in to avoid double-decoding).
	 * @param string               $subject         Email subject; rendered as the in-body heading.
	 * @return string Rendered HTML document.
	 */
	private function render_sign_in_notification_email_body( \WP_User $user, array $consumed_record, string $site_name, string $subject ): string {
		$device           = $consumed_record['device'] ?? array();
		$consumed_at      = isset( $consumed_record['consumed_at'] ) ? (int) $consumed_record['consumed_at'] : time();
		$ap_name          = $consumed_record['ap_name'] ?? '';
		$applications_url = admin_url( 'profile.php#application-passwords-section' );

ob_start();
		include __DIR__ . '/views/mobile-app-qr-login-signin-email.php';
		$html = ob_get_clean();

return is_string( $html ) ? $html : '';
	}
}

MR SKB