Commit e9865326103 for woocommerce

commit e98653261036eeeeda4226b35dc46c648ce87078
Author: Sergey Mitroshin <sergeymitr@gmail.com>
Date:   Sat Nov 21 16:35:59 2026 -0500

    Refuse UCP requests for an unsupported protocol version (#71174)

    Catalog, cart and checkout routes now return 422 version_unsupported when the UCP-Agent header's version is not the one the store implements (2026-04-08).

diff --git a/plugins/woocommerce/changelog/add-ucp-version-negotiation b/plugins/woocommerce/changelog/add-ucp-version-negotiation
new file mode 100644
index 00000000000..7d29ca702b9
--- /dev/null
+++ b/plugins/woocommerce/changelog/add-ucp-version-negotiation
@@ -0,0 +1,4 @@
+Significance: patch
+Type: fix
+
+UCP routes now refuse an agent request for a protocol version the store does not support, with a version_unsupported error.
diff --git a/plugins/woocommerce/src/StoreApi/Routes/V1/Ucp/AbstractCartRoute.php b/plugins/woocommerce/src/StoreApi/Routes/V1/Ucp/AbstractCartRoute.php
index 059206cc4fc..89b0fa524f3 100644
--- a/plugins/woocommerce/src/StoreApi/Routes/V1/Ucp/AbstractCartRoute.php
+++ b/plugins/woocommerce/src/StoreApi/Routes/V1/Ucp/AbstractCartRoute.php
@@ -90,10 +90,11 @@ abstract class AbstractCartRoute extends StoreApiCartRoute {
 	/**
 	 * Answer the request, under the `Idempotency-Key` it carries.
 	 *
-	 * A payload the route cannot read is refused before the key is claimed, so a 415 never
-	 * touches the store. After that the key is settled before anything else runs: a replay
-	 * must not load a session or resolve a cart id, since a retried `cancel` has to return the
-	 * stored response rather than the `not_found` its own first run left behind.
+	 * An unsupported version or a payload the route cannot read is refused before the key is
+	 * claimed, so a 422 or 415 never touches the store. After that the key is settled before
+	 * anything else runs: a replay must not load a session or resolve a cart id, since a
+	 * retried `cancel` has to return the stored response rather than the `not_found` its own
+	 * first run left behind.
 	 *
 	 * @param \WP_REST_Request $request Request object.
 	 *
@@ -102,7 +103,7 @@ abstract class AbstractCartRoute extends StoreApiCartRoute {
 	 * @return \WP_REST_Response
 	 */
 	public function get_response( \WP_REST_Request $request ) {
-		$refusal = Utils::refuse_non_json_payload( $request, $this->capability() );
+		$refusal = Utils::refuse_unsupported_version( $request, $this->capability() ) ?? Utils::refuse_non_json_payload( $request, $this->capability() );
 		if ( null !== $refusal ) {
 			return $this->add_response_headers( $refusal );
 		}
diff --git a/plugins/woocommerce/src/StoreApi/Routes/V1/Ucp/AbstractCatalogRoute.php b/plugins/woocommerce/src/StoreApi/Routes/V1/Ucp/AbstractCatalogRoute.php
index 0d34d47dbe7..f670322fd93 100644
--- a/plugins/woocommerce/src/StoreApi/Routes/V1/Ucp/AbstractCatalogRoute.php
+++ b/plugins/woocommerce/src/StoreApi/Routes/V1/Ucp/AbstractCatalogRoute.php
@@ -63,7 +63,7 @@ abstract class AbstractCatalogRoute extends AbstractRoute {
 	}

 	/**
-	 * Refuse a non-JSON payload before the handler reads anything.
+	 * Refuse an unsupported version or a non-JSON payload before the handler reads anything.
 	 *
 	 * @param \WP_REST_Request $request Request object.
 	 *
@@ -72,7 +72,9 @@ abstract class AbstractCatalogRoute extends AbstractRoute {
 	 * @return \WP_REST_Response
 	 */
 	public function get_response( \WP_REST_Request $request ) {
-		return Utils::refuse_non_json_payload( $request, $this->get_capability() ) ?? parent::get_response( $request );
+		return Utils::refuse_unsupported_version( $request, $this->get_capability() )
+			?? Utils::refuse_non_json_payload( $request, $this->get_capability() )
+			?? parent::get_response( $request );
 	}

 	/**
diff --git a/plugins/woocommerce/src/StoreApi/Routes/V1/Ucp/CheckoutSessionsComplete.php b/plugins/woocommerce/src/StoreApi/Routes/V1/Ucp/CheckoutSessionsComplete.php
index 9cc441fc182..1477ca737ae 100644
--- a/plugins/woocommerce/src/StoreApi/Routes/V1/Ucp/CheckoutSessionsComplete.php
+++ b/plugins/woocommerce/src/StoreApi/Routes/V1/Ucp/CheckoutSessionsComplete.php
@@ -260,7 +260,7 @@ class CheckoutSessionsComplete extends AbstractCheckoutRoute {
 	 * @return string
 	 */
 	private function agent_profile_host( string $header ): string {
-		$profile = $this->quoted_header_parameter( $header, 'profile' );
+		$profile = Utils::quoted_header_parameter( $header, 'profile' );
 		$host    = strtolower( (string) wp_parse_url( $profile, PHP_URL_HOST ) );

 		if ( '' === $host ) {
@@ -272,49 +272,6 @@ class CheckoutSessionsComplete extends AbstractCheckoutRoute {
 		return is_string( $valid ) ? $valid : 'ucp';
 	}

-	/**
-	 * Value of one double-quoted parameter, matched by its exact name.
-	 *
-	 * A match counts only outside quotes, at the start of the header or after whitespace or a semicolon.
-	 *
-	 * @param string $header Header value.
-	 * @param string $name   Parameter name.
-	 * @return string Empty when the parameter is absent.
-	 */
-	private function quoted_header_parameter( string $header, string $name ): string {
-		$prefix = $name . '="';
-		$offset = 0;
-		$length = strlen( $header );
-
-		while ( $offset < $length ) {
-			$start = strpos( $header, $prefix, $offset );
-			if ( false === $start ) {
-				return '';
-			}
-
-			// An even number of quotes before the name means it is outside a value.
-			$outside_quotes = 0 === ( substr_count( substr( $header, 0, $start ), '"' ) % 2 );
-			$is_parameter   = 0 === $start;
-			if ( ! $is_parameter ) {
-				$previous     = substr( $header, $start - 1, 1 );
-				$is_parameter = ' ' === $previous || "\t" === $previous || ';' === $previous;
-			}
-
-			if ( $outside_quotes && $is_parameter ) {
-				$value_start = $start + strlen( $prefix );
-				$end         = strpos( $header, '"', $value_start );
-				if ( false === $end ) {
-					return '';
-				}
-				return substr( $header, $value_start, $end - $value_start );
-			}
-
-			$offset = $start + strlen( $prefix );
-		}
-
-		return '';
-	}
-
 	/**
 	 * Return a checkout whose payment was already handed off, as it stands, with a warning that nothing was done.
 	 *
diff --git a/plugins/woocommerce/src/StoreApi/Utilities/Ucp/Utils.php b/plugins/woocommerce/src/StoreApi/Utilities/Ucp/Utils.php
index f9ea1682eba..c526806ab44 100644
--- a/plugins/woocommerce/src/StoreApi/Utilities/Ucp/Utils.php
+++ b/plugins/woocommerce/src/StoreApi/Utilities/Ucp/Utils.php
@@ -196,6 +196,73 @@ class Utils {
 		return self::error_response( $capability, 'VALIDATION_ERROR', __( 'UCP requests must be sent as application/json.', 'woocommerce' ), 'recoverable', 415 );
 	}

+	/**
+	 * Refuse a request whose `UCP-Agent` header names a protocol version other than VERSION.
+	 *
+	 * No `supported_versions` are published, so only an exact match is served. A header without a version is not refused.
+	 * https://ucp.dev/2026-04-08/specification/overview/#request-time-validation
+	 *
+	 * @param \WP_REST_Request $request Request object.
+	 * @param string           $capability One of the CAPABILITY_* constants.
+	 *
+	 * @phpstan-param \WP_REST_Request<array<string, mixed>> $request
+	 *
+	 * @return \WP_REST_Response|null The 422 refusal, or null when the version is served.
+	 */
+	public static function refuse_unsupported_version( \WP_REST_Request $request, string $capability ): ?\WP_REST_Response {
+		$version = self::quoted_header_parameter( (string) $request->get_header( 'UCP-Agent' ), 'version' );
+
+		if ( '' === $version || self::VERSION === $version ) {
+			return null;
+		}
+
+		return self::error_response(
+			$capability,
+			'version_unsupported',
+			/* translators: 1: protocol version the agent asked for, 2: protocol version the store implements. */
+			sprintf( __( 'UCP version %1$s is not supported. This store implements version %2$s.', 'woocommerce' ), $version, self::VERSION ),
+			'unrecoverable',
+			422
+		);
+	}
+
+	/**
+	 * Unescaped value of one double-quoted parameter, matched by its exact name.
+	 *
+	 * A match counts only outside quotes, at the start of the header or after whitespace, a semicolon or a comma.
+	 * A repeated name resolves to its last occurrence, as RFC 8941 requires for a dictionary key.
+	 *
+	 * @param string $header Header value.
+	 * @param string $name   Parameter name.
+	 * @return string Empty when the parameter is absent.
+	 */
+	public static function quoted_header_parameter( string $header, string $name ): string {
+		// Each match is one whole quoted string, `\"` and `\\` escapes included, so text inside a value is never read as a parameter.
+		preg_match_all( '/"((?:[^"\\\\]++|\\\\.)*+)"/', $header, $strings, PREG_SET_ORDER | PREG_OFFSET_CAPTURE );
+
+		$prefix = $name . '=';
+		$value  = '';
+		foreach ( $strings as $string ) {
+			$start = $string[0][1] - strlen( $prefix );
+			if ( $start < 0 || substr( $header, $start, strlen( $prefix ) ) !== $prefix ) {
+				continue;
+			}
+
+			if ( 0 === $start || false !== strpos( " \t;,", $header[ $start - 1 ] ) ) {
+				// Keep scanning rather than return: the last matching occurrence wins.
+				$value = strtr(
+					$string[1][0],
+					array(
+						'\\"'  => '"',
+						'\\\\' => '\\',
+					)
+				);
+			}
+		}
+
+		return $value;
+	}
+
 	/**
 	 * Read a parameter from the JSON document alone.
 	 *
diff --git a/plugins/woocommerce/tests/php/src/Blocks/StoreApi/Routes/UcpCatalog.php b/plugins/woocommerce/tests/php/src/Blocks/StoreApi/Routes/UcpCatalog.php
index c54460749d3..716fc9893b3 100644
--- a/plugins/woocommerce/tests/php/src/Blocks/StoreApi/Routes/UcpCatalog.php
+++ b/plugins/woocommerce/tests/php/src/Blocks/StoreApi/Routes/UcpCatalog.php
@@ -359,6 +359,21 @@ class UcpCatalog extends ControllerTestCase {
 		$this->assertSame( 'VALIDATION_ERROR', $data['messages'][0]['code'] );
 	}

+	/**
+	 * A protocol version the store does not implement is refused.
+	 */
+	public function test_an_unsupported_version_is_refused(): void {
+		$request = new \WP_REST_Request( 'POST', '/wc/ucp/v1/catalog/lookup' );
+		$request->set_header( 'content-type', 'application/json' );
+		$request->set_header( 'UCP-Agent', 'profile="https://agent.example/profile.json"; version="2099-01-01"' );
+		$request->set_body( wp_json_encode( array( 'ids' => array( (string) self::$product_ids[0] ) ) ) );
+
+		$response = rest_get_server()->dispatch( $request );
+
+		$this->assertSame( 422, $response->get_status() );
+		$this->assertSame( 'version_unsupported', $response->get_data()['messages'][0]['code'] );
+	}
+
 	/**
 	 * Product detail answers with `ucp.status`, and reports a miss as 200 + `not_found`.
 	 */
diff --git a/plugins/woocommerce/tests/php/src/Blocks/StoreApi/Routes/UcpCheckout.php b/plugins/woocommerce/tests/php/src/Blocks/StoreApi/Routes/UcpCheckout.php
index 34c661a5bb2..ab48c68e54f 100644
--- a/plugins/woocommerce/tests/php/src/Blocks/StoreApi/Routes/UcpCheckout.php
+++ b/plugins/woocommerce/tests/php/src/Blocks/StoreApi/Routes/UcpCheckout.php
@@ -234,6 +234,48 @@ class UcpCheckout extends ControllerTestCase {
 		$this->assertSame( 400, $missing->get_status(), 'line_items is required without a cart_id.' );
 	}

+	/**
+	 * Version cases for the `UCP-Agent` header.
+	 *
+	 * @return array<string, array{string, int}>
+	 */
+	public function provider_agent_versions(): array {
+		$profile = 'profile="https://agent.example/profile.json"';
+
+		return array(
+			'supported'                   => array( $profile . '; version="' . Utils::VERSION . '"', 201 ),
+			'newer'                       => array( $profile . '; version="2099-01-01"', 422 ),
+			'older'                       => array( $profile . '; version="2026-01-23"', 422 ),
+			'bare comma'                  => array( $profile . ',version="2099-01-01"', 422 ),
+			'duplicate, unsupported last' => array( $profile . ', version="' . Utils::VERSION . '", version="2099-01-01"', 422 ),
+			'duplicate, supported last'   => array( $profile . ', version="2099-01-01", version="' . Utils::VERSION . '"', 201 ),
+			'escaped quote, newer'        => array( $profile . ', note="a\\"b", version="2099-01-01"', 422 ),
+			'escaped quote, supported'    => array( $profile . ', note="a\\"b", version="' . Utils::VERSION . '"', 201 ),
+		);
+	}
+
+	/**
+	 * Only the protocol version the store implements is served.
+	 *
+	 * @dataProvider provider_agent_versions
+	 *
+	 * @param string $header UCP-Agent header.
+	 * @param int    $status Expected HTTP status.
+	 */
+	public function test_agent_version_is_negotiated( string $header, int $status ): void {
+		$response = $this->request(
+			'POST',
+			'/checkout-sessions',
+			array( 'line_items' => array( $this->line_item( 0, 1 ) ) ),
+			array( 'UCP-Agent' => $header )
+		);
+
+		$this->assertSame( $status, $response->get_status() );
+		if ( 422 === $status ) {
+			$this->assertSame( 'version_unsupported', $response->get_data()['messages'][0]['code'] );
+		}
+	}
+
 	/**
 	 * @testdox Creating from a cart keeps the cart id and contents; a checkout without a buyer email is incomplete.
 	 */