fix: address Codex review — PHPCS suppression + legacy-header scoping + README auth

Three fixes from the third Codex review:

P1: PHPCS suppression on the new auth query

The new permissions-aware lookup in `authenticate_mcp_request` only
suppressed `WordPress.DB.DirectDatabaseQuery`. Every comparable query
in the codebase (RestApiKey's three lookup helpers, the analytics
controller, the customer-value test fixture) suppresses
`WordPress.DB.PreparedSQL.InterpolatedNotPrepared` alongside it,
since `{$wpdb->prefix}` interpolation triggers that sniff. Local
PHPCS happened to pass without it but the convention exists for a
reason — CI may be stricter or the rule may light up under future
upstream tightening. Match the convention.

P2: legacy X-MCP-API-Key bundles re-scoped

The previous commit dropped X-MCP-API-Key reading from
`extract_request_credential` "for consistency" with the auth
callback. Wrong move: the credential extractor's job is defensive
recognition, not authentication, and pre-migration `.mcpb` bundles
distributed against earlier plugin versions still send the header
to /wp-json/woocommerce/mcp (the deprecated WC core MCP endpoint,
which still authenticates the same WC API key when its feature flag
is on). Without the extractor reading the header,
`enforce_setup_key_route_scope` treats those legacy requests as
unrelated and lets them through — silently keeping the credential
usable on a route the merchant didn't intend.

Restore the X-MCP-API-Key branch in the extractor (defense-only,
not a supported auth path on the new endpoint) and pin the deny
behaviour with a regression test against /wp-json/woocommerce/mcp.

P3: README documents the new auth shape

The architecture paragraph still claimed "authenticates via an
X-MCP-API-Key header" after the Basic-auth migration. The setup
snippets, MCPB manifest, and `authenticate_mcp_request` all use
`WP_API_USERNAME` / `WP_API_PASSWORD` Basic auth now. Native HTTP
clients following the old paragraph would send the wrong shape and
get rejected. Updated to describe the actual contract (ck:cs Basic
auth from a WC key with read or read_write scope).

297 PHPUnit tests pass (was 296). PHPCS clean.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: garysmurray

README.md

@@ -182,7 +182,7 @@ WooCommerce core already exposes basic product and order CRUD via MCP. This proj
 | **WooCommerce core MCP** | HTTP transport, auth, product/order CRUD tools                    | WooCommerce core team |
 | **Hey Woo plugin**       | Analytics skills, knowledge resources, prompts, readiness scoring | This project          |
 
-Everything ships through the single endpoint at `/wp-json/hey-woo/mcp`. There is no separate MCP server process to run — the plugin registers its abilities and stands up its own MCP server on `mcp_adapter_init` using the WordPress MCP adapter (vendored inside WooCommerce). The server bundles tools, resources, and prompts directly, and authenticates via an `X-MCP-API-Key` header backed by a standard WooCommerce REST API key.
+Everything ships through the single endpoint at `/wp-json/hey-woo/mcp`. There is no separate MCP server process to run — the plugin registers its abilities and stands up its own MCP server on `mcp_adapter_init` using the WordPress MCP adapter (vendored inside WooCommerce). The server bundles tools, resources, and prompts directly, and authenticates via standard HTTP Basic auth — `ck_xxx` as the username, `cs_xxx` as the password, sourced from a WooCommerce REST API key with `read` or `read_write` scope.
 
 ---
 

includes/class-plugin.php

@@ -514,7 +514,7 @@ public function authenticate_mcp_request( $request ) {
 		}
 
 		global $wpdb;
-		// phpcs:ignore WordPress.DB.DirectDatabaseQuery -- direct lookup against woocommerce_api_keys; no caching surface for auth.
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery,WordPress.DB.PreparedSQL.InterpolatedNotPrepared -- direct lookup against woocommerce_api_keys; table prefix is trusted; no caching surface for auth.
 		$row = $wpdb->get_row(
 			$wpdb->prepare(
 				"SELECT key_id, user_id, consumer_secret, permissions FROM {$wpdb->prefix}woocommerce_api_keys WHERE consumer_key = %s",

includes/setup/class-setup-page.php

@@ -522,9 +522,20 @@ private static function route_is_allowed_for_setup_key( $route ) {
 
 	/**
 	 * Extract the credential from the current REST request, if any.
-	 * Mirrors the surfaces that WC's REST auth recognises: HTTP Basic
-	 * auth (split form via PHP_AUTH_USER/PW or raw HTTP_AUTHORIZATION
-	 * header) and `consumer_key` / `consumer_secret` query params.
+	 * Recognises the surfaces WC's REST auth reads (Basic auth split
+	 * form via PHP_AUTH_USER/PW; raw HTTP_AUTHORIZATION; query-string
+	 * `consumer_key` / `consumer_secret`) plus the legacy
+	 * `X-MCP-API-Key` header.
+	 *
+	 * The legacy header is no longer accepted by our MCP auth callback,
+	 * but pre-migration `.mcpb` bundles distributed against earlier
+	 * plugin versions still send it — typically targeting the
+	 * deprecated WC core MCP endpoint at `/wp-json/woocommerce/mcp`.
+	 * Reading it here means `enforce_setup_key_route_scope()` can
+	 * still recognise our credential on those legacy requests and
+	 * deny them on every route except `/wp-json/hey-woo/mcp`. Drop
+	 * the header here and a leaked legacy bundle silently keeps
+	 * authenticating against the WC core endpoint.
 	 *
 	 * Returns '' if no credential is present (the request will be
 	 * unauthenticated or rely on cookies/nonces instead, neither of
@@ -536,7 +547,16 @@ private static function extract_request_credential() {
 		// phpcs:disable WordPress.Security.NonceVerification.Recommended -- read-only inspection of an in-flight REST request.
 		// phpcs:disable WordPress.Security.ValidatedSanitizedInput.InputNotSanitized -- credentials are byte-compared, not interpolated; sanitisation would corrupt them.
 
-		// 1a. PHP_AUTH_USER + PHP_AUTH_PW — the split form Apache/mod_php
+		// 1. Legacy X-MCP-API-Key header — kept for defense-in-depth so
+		// pre-migration bundles still hit the route-scope deny path on
+		// non-allowed routes. Not a supported auth path for the new
+		// /wp-json/hey-woo/mcp endpoint (Plugin::authenticate_mcp_request
+		// only reads Basic auth).
+		if ( ! empty( $_SERVER['HTTP_X_MCP_API_KEY'] ) ) {
+			return wp_unslash( (string) $_SERVER['HTTP_X_MCP_API_KEY'] );
+		}
+
+		// 2a. PHP_AUTH_USER + PHP_AUTH_PW — the split form Apache/mod_php
 		// (and many fastcgi setups) expose Basic auth as. WC's auth reads
 		// these directly, so the route-scope filter must too — otherwise
 		// a request bearing our setup credential against a non-MCP route
@@ -546,7 +566,7 @@ private static function extract_request_credential() {
 			return wp_unslash( (string) $_SERVER['PHP_AUTH_USER'] ) . ':' . wp_unslash( (string) $_SERVER['PHP_AUTH_PW'] );
 		}
 
-		// 1b. HTTP Basic auth (raw header form) — username:password = ck_xxx:cs_xxx.
+		// 2b. HTTP Basic auth (raw header form) — username:password = ck_xxx:cs_xxx.
 		$auth = isset( $_SERVER['HTTP_AUTHORIZATION'] ) ? wp_unslash( (string) $_SERVER['HTTP_AUTHORIZATION'] ) : '';
 		if ( 0 === stripos( $auth, 'Basic ' ) ) {
 			// phpcs:ignore WordPress.PHP.DiscouragedPHPFunctions.obfuscation_base64_decode -- decoding HTTP Basic auth header per RFC 7617; strict mode rejects invalid input.
@@ -556,7 +576,7 @@ private static function extract_request_credential() {
 			}
 		}
 
-		// 2. Query string consumer_key + consumer_secret (WC legacy auth).
+		// 3. Query string consumer_key + consumer_secret (WC legacy auth).
 		if ( ! empty( $_GET['consumer_key'] ) && ! empty( $_GET['consumer_secret'] ) ) {
 			return wp_unslash( (string) $_GET['consumer_key'] ) . ':' . wp_unslash( (string) $_GET['consumer_secret'] );
 		}

tests/integration/test-rest-api-key.php

@@ -620,6 +620,39 @@ public function test_setup_key_is_allowed_on_mcp_route_with_php_auth_basic() {
 		}
 	}
 
+	/**
+	 * Legacy `.mcpb` bundles distributed before the wordpress/mcp
+	 * migration ship the credential as `X-MCP-API-Key` and target the
+	 * deprecated WC core MCP endpoint at /wp-json/woocommerce/mcp. The
+	 * auth callback for the new endpoint no longer accepts that header,
+	 * but the route-scope filter must still recognise it — otherwise a
+	 * pre-migration bundle whose credential matches our stored one
+	 * silently bypasses the scope guard against the WC core endpoint
+	 * (which still authenticates the same WC API key when its feature
+	 * flag is on). Pin the deny path so a regression here doesn't
+	 * re-open that bypass.
+	 */
+	public function test_legacy_x_mcp_api_key_header_is_scope_denied_on_non_mcp_routes() {
+		$helper = new RestApiKey();
+		$state  = $helper->get_or_create();
+
+		$original_server = $_SERVER;
+		try {
+			// phpcs:disable WordPress.Security.NonceVerification.Recommended -- test fixture mutates $_SERVER directly.
+			unset( $_SERVER['PHP_AUTH_USER'], $_SERVER['PHP_AUTH_PW'], $_SERVER['HTTP_AUTHORIZATION'] );
+			$_SERVER['HTTP_X_MCP_API_KEY'] = $state['credential'];
+			$_SERVER['REQUEST_URI']        = '/wp-json/woocommerce/mcp';
+			$result                        = SetupPage::enforce_setup_key_route_scope( null );
+
+			$this->assertInstanceOf( \WP_Error::class, $result, 'Legacy X-MCP-API-Key against the deprecated WC MCP route must be denied.' );
+			$this->assertSame( 'hey_woo_route_restricted', $result->get_error_code() );
+			$this->assertSame( 403, $result->get_error_data()['status'] ?? 0 );
+		} finally {
+			$_SERVER = $original_server;
+			// phpcs:enable WordPress.Security.NonceVerification.Recommended
+		}
+	}
+
 	/**
 	 * The route-scope filter is a no-op when the request isn't using
 	 * our credential at all. Anything else would inadvertently