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.
*/