| @@ -62,12 +62,35 @@ | ||
| 62 | 62 | * deliberate. See #379. |
| 63 | 63 | */ |
| 64 | 64 | private const CLIENT_USER_AGENTS = [ |
| 65 | 65 | 'python-requests/2.32.3', |
| 66 | + // aiohttp's default, `Python/{major}.{minor} aiohttp/{version}`. A | |
| 67 | + // large share of real MCP backends send this shape, and it is the one | |
| 68 | + // an nginx "block bad bots" rule matches first because it leads with | |
| 69 | + // `Python/`. Its absence here is half of #884: a customer's host was | |
| 70 | + // refusing it while this check reported green. | |
| 71 | + 'Python/3.11 aiohttp/3.9.5', | |
| 66 | 72 | 'node-fetch/3.3.2', |
| 73 | + // No User-Agent header at all, which is what a Cloudflare managed | |
| 74 | + // challenge refuses. probe_status() sends this as an absent header | |
| 75 | + // rather than an empty one: measured, `'user-agent' => ''` makes | |
| 76 | + // WP_Http omit the header instead of falling back to WordPress's own | |
| 77 | + // agent, so this probe tests what it says it tests. | |
| 78 | + self::NO_USER_AGENT, | |
| 67 | 79 | ]; |
| 68 | 80 | |
| 69 | 81 | /** |
| 82 | + * Stands for "send no User-Agent header" in CLIENT_USER_AGENTS. | |
| 83 | + * | |
| 84 | + * Distinct from the `null` probe_status() takes for WordPress's own agent: | |
| 85 | + * that one is the baseline every probe is compared against. | |
| 86 | + * | |
| 87 | + * @since 2.14.0 | |
| 88 | + * @var string | |
| 89 | + */ | |
| 90 | + private const NO_USER_AGENT = ''; | |
| 91 | + | |
| 92 | + /** | |
| 70 | 93 | * Where an affected site owner is sent for the workaround list. The plugin |
| 71 | 94 | * cannot fix an edge block, so the failing check hands over the diagnostic |
| 72 | 95 | * and the host-side options instead. |
| 73 | 96 | */ |
| @@ -110,8 +133,18 @@ | ||
| 110 | 133 | $result['message'] = __( 'No connection token exists yet. Click Connect to mint one, then run the test again.', 'thinkrank' ); |
| 111 | 134 | return $result; |
| 112 | 135 | } |
| 113 | 136 | |
| 137 | + if ( Mcp_Pairing::state()['token_sealed'] ) { | |
| 138 | + // A token exists and still authenticates the clients holding it, | |
| 139 | + // but this site can no longer decrypt it, so there is nothing to | |
| 140 | + // present. Probing with '' would report an authentication failure | |
| 141 | + // and point support at entirely the wrong thing. | |
| 142 | + $result['stage'] = 'token_sealed'; | |
| 143 | + $result['message'] = __( 'A connection token exists but can no longer be read on this site: the security keys in wp-config.php changed after it was minted. Clients already set up with it keep working. Use Reset token to mint one this site can show, then run the test again.', 'thinkrank' ); | |
| 144 | + return $result; | |
| 145 | + } | |
| 146 | + | |
| 114 | 147 | $token = Mcp_Pairing::site_token(); |
| 115 | 148 | |
| 116 | 149 | $pretty = self::probe_jsonrpc( $endpoint, $token ); |
| 117 | 150 | $rest = self::probe_jsonrpc( $fallback, $token ); |
| @@ -137,9 +170,9 @@ | ||
| 137 | 170 | $result['checks'][] = self::check( 'challenge', __( 'OAuth challenge', 'thinkrank' ), $challenge['stage'], $challenge['detail'] ); |
| 138 | 171 | |
| 139 | 172 | // Only reported when it could actually run — claiming a pass we did |
| 140 | 173 | // not measure is the failure mode this whole test exists to avoid. |
| 141 | - $user_agent = self::probe_user_agent( $endpoint ); | |
| 174 | + $user_agent = self::probe_user_agent( $endpoint, $fallback ); | |
| 142 | 175 | if ( null !== $user_agent ) { |
| 143 | 176 | $result['checks'][] = self::check( 'user_agent', __( 'Client access', 'thinkrank' ), $user_agent['stage'], $user_agent['detail'], $user_agent['doc_url'] ?? '' ); |
| 144 | 177 | } |
| 145 | 178 | |
| @@ -156,10 +189,10 @@ | ||
| 156 | 189 | 'locked_clients', |
| 157 | 190 | sprintf( |
| 158 | 191 | /* translators: %d: number of currently locked-out clients. */ |
| 159 | 192 | _n( |
| 160 | - '%d client is currently locked out after repeated failed authentications — typically a connector still holding a rotated-away token. Remove and re-add the connector in the AI client; the lockout clears itself within 15 minutes of the retries stopping.', | |
| 161 | - '%d clients are currently locked out after repeated failed authentications — typically connectors still holding a rotated-away token. Remove and re-add the connector in the AI client; lockouts clear within 15 minutes of the retries stopping.', | |
| 193 | + '%d client is currently locked out after repeated failed authentications, typically a connector still holding a rotated-away token. Remove and re-add the connector in the AI client; the lockout clears itself within 15 minutes of the retries stopping.', | |
| 194 | + '%d clients are currently locked out after repeated failed authentications, typically connectors still holding a rotated-away token. Remove and re-add the connector in the AI client; lockouts clear within 15 minutes of the retries stopping.', | |
| 162 | 195 | $lockouts, |
| 163 | 196 | 'thinkrank' |
| 164 | 197 | ), |
| 165 | 198 | $lockouts |
| @@ -276,9 +309,9 @@ | ||
| 276 | 309 | if ( 404 === $status ) { |
| 277 | 310 | $out['stage'] = 'rewrite'; |
| 278 | 311 | $out['detail'] = sprintf( |
| 279 | 312 | /* translators: %s: endpoint URL. */ |
| 280 | - __( '%s returned 404 — WordPress does not know this URL. Re-save Settings → Permalinks to rebuild the rewrite rules.', 'thinkrank' ), | |
| 313 | + __( '%s returned 404. WordPress does not know this URL. Re-save Settings → Permalinks to rebuild the rewrite rules.', 'thinkrank' ), | |
| 281 | 314 | $url |
| 282 | 315 | ); |
| 283 | 316 | return $out; |
| 284 | 317 | } |
| @@ -319,9 +352,9 @@ | ||
| 319 | 352 | $out['stage'] = 'no_tools'; |
| 320 | 353 | $out['tools'] = is_array( $tools ) ? count( $tools ) : 0; |
| 321 | 354 | $out['detail'] = sprintf( |
| 322 | 355 | /* translators: 1: endpoint URL, 2: abilities-registry diagnostic summary. */ |
| 323 | - __( '%1$s answered but returned no tool catalog. Confirm the MCP runtime is built and abilities are registered. Diagnostics — %2$s', 'thinkrank' ), | |
| 356 | + __( '%1$s answered but returned no tool catalog. Confirm the MCP runtime is built and abilities are registered. Diagnostics: %2$s', 'thinkrank' ), | |
| 324 | 357 | $url, |
| 325 | 358 | Abilities_Registrar::summary() |
| 326 | 359 | ); |
| 327 | 360 | return $out; |
| @@ -346,8 +379,41 @@ | ||
| 346 | 379 | */ |
| 347 | 380 | private static function probe_discovery(): array { |
| 348 | 381 | $documents = []; |
| 349 | 382 | |
| 383 | + // --- Published files vs. the identity this site has NOW ----------- | |
| 384 | + // The static /.well-known/ documents embed absolute home_url()-derived | |
| 385 | + // identifiers, and the whole reason they exist is that the host serves | |
| 386 | + // them before WordPress. After a domain change, an http->https switch | |
| 387 | + // or a staging clone, the stale copy therefore wins over the correct | |
| 388 | + // dynamic route and the site advertises an issuer it no longer owns, | |
| 389 | + // which a spec-compliant client must refuse (#486). | |
| 390 | + // | |
| 391 | + // Checked on disk, ahead of the HTTP probes below, because loopback | |
| 392 | + // does not always take the path an external client does — a site can | |
| 393 | + // serve a stale document to the internet while our own request never | |
| 394 | + // sees it, and every probe below then passes. | |
| 395 | + $stale = Mcp_Static_Discovery::stale_document(); | |
| 396 | + if ( null !== $stale ) { | |
| 397 | + Mcp_Static_Discovery::refresh(); | |
| 398 | + $still_stale = Mcp_Static_Discovery::stale_document(); | |
| 399 | + | |
| 400 | + if ( null !== $still_stale ) { | |
| 401 | + return [ | |
| 402 | + 'stage' => 'stale_static_discovery', | |
| 403 | + 'documents' => $documents, | |
| 404 | + 'detail' => sprintf( | |
| 405 | + /* translators: 1: file path relative to the site root, 2: identifier name, 3: value found in the file, 4: value it should carry. */ | |
| 406 | + __( 'The static discovery file %1$s advertises %2$s as %3$s, but this site is %4$s. It was written before the site URL changed, the host serves it ahead of WordPress, and it could not be rewritten or removed, so clients read the old identity and refuse to connect. Delete that file from the site root, or restore write access there and run this test again.', 'thinkrank' ), | |
| 407 | + $still_stale['file'], | |
| 408 | + $still_stale['key'], | |
| 409 | + '' === $still_stale['found'] ? __( 'nothing', 'thinkrank' ) : $still_stale['found'], | |
| 410 | + $still_stale['expected'] | |
| 411 | + ), | |
| 412 | + ]; | |
| 413 | + } | |
| 414 | + } | |
| 415 | + | |
| 350 | 416 | // --- The documents clients are POINTED at (must work) ------------- |
| 351 | 417 | // The 401 challenge advertises the REST-served resource metadata, and |
| 352 | 418 | // spec-compliant clients derive the OIDC-suffix form of the AS |
| 353 | 419 | // metadata from our path-based issuer. Neither lives under the site |
| @@ -445,9 +511,9 @@ | ||
| 445 | 511 | } |
| 446 | 512 | return [ |
| 447 | 513 | 'stage' => 'ok', |
| 448 | 514 | 'documents' => $documents, |
| 449 | - 'detail' => __( 'The primary discovery documents are served and correct, but the host intercepts the site root\'s /.well-known/ directory before WordPress runs (common on SiteGround shared hosting), and static files could not be published there. Clients that follow the challenge — ChatGPT, Claude — still connect; a client that only derives the root /.well-known/ URL itself may not. If write access to the site root is possible, granting it lets ThinkRank publish static discovery files that fix this completely.', 'thinkrank' ), | |
| 515 | + 'detail' => __( 'The primary discovery documents are served and correct, but the host intercepts the site root\'s /.well-known/ directory before WordPress runs (common on SiteGround shared hosting), and static files could not be published there. Clients that follow the challenge, such as ChatGPT and Claude, still connect; a client that only derives the root /.well-known/ URL itself may not. If write access to the site root is possible, granting it lets ThinkRank publish static discovery files that fix this completely.', 'thinkrank' ), | |
| 450 | 516 | ]; |
| 451 | 517 | } |
| 452 | 518 | } |
| 453 | 519 | |
| @@ -563,9 +629,9 @@ | ||
| 563 | 629 | return [ |
| 564 | 630 | 'stage' => 'discovery', |
| 565 | 631 | 'detail' => sprintf( |
| 566 | 632 | /* translators: 1: http endpoint URL advertised, 2: https endpoint URL that also answers. */ |
| 567 | - __( 'The discovery documents advertise %1$s, but %2$s answers as well — WordPress is storing an http:// site address behind a proxy that terminates TLS. AI clients connect over https and reject the http identifier as a mismatch. Fix the Site Address in Settings → General, or have the proxy send X-Forwarded-Proto.', 'thinkrank' ), | |
| 633 | + __( 'The discovery documents advertise %1$s, but %2$s answers as well. WordPress is storing an http:// site address behind a proxy that terminates TLS. AI clients connect over https and reject the http identifier as a mismatch. Fix the Site Address in Settings → General, or have the proxy send X-Forwarded-Proto.', 'thinkrank' ), | |
| 568 | 634 | $endpoint, |
| 569 | 635 | $secure |
| 570 | 636 | ), |
| 571 | 637 | ]; |
| @@ -627,9 +693,9 @@ | ||
| 627 | 693 | return [ |
| 628 | 694 | 'stage' => 'challenge', |
| 629 | 695 | 'detail' => sprintf( |
| 630 | 696 | /* translators: %s: endpoint URL. */ |
| 631 | - __( '%s answered 401 but sent no WWW-Authenticate header — a security plugin or proxy is likely stripping it. Clients that connect by URL alone will report that this server does not implement OAuth.', 'thinkrank' ), | |
| 697 | + __( '%s answered 401 but sent no WWW-Authenticate header. A security plugin or proxy is likely stripping it. Clients that connect by URL alone will report that this server does not implement OAuth.', 'thinkrank' ), | |
| 632 | 698 | $url |
| 633 | 699 | ), |
| 634 | 700 | ]; |
| 635 | 701 | } |
| @@ -700,53 +766,97 @@ | ||
| 700 | 766 | * which host firewalls usually trust, so it catches UA filtering but NOT |
| 701 | 767 | * an IP-range block of the AI vendor. A green result here does not prove |
| 702 | 768 | * an external client can connect. |
| 703 | 769 | * |
| 770 | + * Both URLs are probed, not just the pretty one. A rule scoped to a path | |
| 771 | + * blocks one and not the other, and reporting "REST fallback URL ✓" for a | |
| 772 | + * path that was only ever reached under WordPress's own agent is the pass | |
| 773 | + * this test was written to avoid (#884). | |
| 774 | + * | |
| 704 | 775 | * @param string $endpoint Pretty endpoint URL. |
| 776 | + * @param string $fallback REST endpoint URL. | |
| 705 | 777 | * @return array{stage:string,detail:string}|null Null when it could not run. |
| 706 | 778 | */ |
| 707 | - private static function probe_user_agent( string $endpoint ): ?array { | |
| 708 | - $baseline = self::probe_status( $endpoint, null ); | |
| 709 | - if ( null === $baseline ) { | |
| 710 | - return null; // Endpoint unreachable — the other checks own that. | |
| 711 | - } | |
| 779 | + private static function probe_user_agent( string $endpoint, string $fallback ): ?array { | |
| 780 | + $probed = 0; | |
| 712 | 781 | |
| 713 | - foreach ( self::CLIENT_USER_AGENTS as $agent ) { | |
| 714 | - $status = self::probe_status( $endpoint, $agent ); | |
| 715 | - if ( null === $status || $status === $baseline ) { | |
| 716 | - continue; | |
| 782 | + foreach ( [ $endpoint, $fallback ] as $url ) { | |
| 783 | + $baseline = self::probe_status( $url, null ); | |
| 784 | + if ( null === $baseline ) { | |
| 785 | + continue; // This URL is unreachable — the other checks own that. | |
| 717 | 786 | } |
| 718 | - // A different status is only damning when it is a refusal. An MCP | |
| 719 | - // answer (401 challenge / 200 / 202) under any UA is fine. | |
| 720 | - if ( in_array( $status, [ 200, 202, 401 ], true ) ) { | |
| 721 | - continue; | |
| 787 | + | |
| 788 | + ++$probed; | |
| 789 | + | |
| 790 | + foreach ( self::CLIENT_USER_AGENTS as $agent ) { | |
| 791 | + $status = self::probe_status( $url, $agent ); | |
| 792 | + if ( null === $status || $status === $baseline ) { | |
| 793 | + continue; | |
| 794 | + } | |
| 795 | + // A different status is only damning when it is a refusal. An | |
| 796 | + // MCP answer (401 challenge / 200 / 202) under any UA is fine. | |
| 797 | + if ( in_array( $status, [ 200, 202, 401 ], true ) ) { | |
| 798 | + continue; | |
| 799 | + } | |
| 800 | + return [ | |
| 801 | + 'stage' => 'ua_filter', | |
| 802 | + 'doc_url' => self::HOSTING_DOC_URL, | |
| 803 | + 'detail' => sprintf( | |
| 804 | + /* translators: 1: endpoint URL that refused the probe, 2: user agent description, 3: HTTP status returned for it, 4: HTTP status returned for WordPress's own user agent. */ | |
| 805 | + __( 'Ask the host to exempt %1$s from its bot filtering, along with the /.well-known/ documents. That URL answered %4$d for WordPress and %3$d for %2$s, so a security plugin, firewall or host-level "block bad bots" rule is refusing AI clients on it. Allowlisting the User-Agents ThinkRank probes with is not enough on its own: a real client sends whichever agent its own backend uses, and the next one will be refused in the same way.', 'thinkrank' ), | |
| 806 | + $url, | |
| 807 | + self::describe_agent( $agent ), | |
| 808 | + $status, | |
| 809 | + $baseline | |
| 810 | + ), | |
| 811 | + ]; | |
| 722 | 812 | } |
| 723 | - return [ | |
| 724 | - 'stage' => 'ua_filter', | |
| 725 | - 'doc_url' => self::HOSTING_DOC_URL, | |
| 726 | - 'detail' => sprintf( | |
| 727 | - /* translators: 1: user agent string, 2: HTTP status returned for it, 3: HTTP status returned for WordPress's own user agent. */ | |
| 728 | - __( 'The endpoint answered %3$d for WordPress but %2$d for an AI client\'s User-Agent (%1$s). ThinkRank deliberately tests with the generic agents real MCP backends send; this refusal means a security plugin, firewall or host-level "block bad bots" rule (SiteGround\'s edge protection does this) will also refuse the real AI client. Ask the host to exempt the MCP and /.well-known/ paths, or allowlist these User-Agents.', 'thinkrank' ), | |
| 729 | - $agent, | |
| 730 | - $status, | |
| 731 | - $baseline | |
| 732 | - ), | |
| 733 | - ]; | |
| 734 | 813 | } |
| 735 | 814 | |
| 815 | + if ( 0 === $probed ) { | |
| 816 | + return null; // Neither URL answered at all. | |
| 817 | + } | |
| 818 | + | |
| 736 | 819 | return [ |
| 737 | 820 | 'stage' => 'ok', |
| 738 | - 'detail' => __( 'The endpoint answers AI-client User-Agents the same way it answers WordPress, so no bot filter is blocking them. This cannot see an IP-level block of the AI vendor.', 'thinkrank' ), | |
| 821 | + 'detail' => __( 'Both the connection URL and the REST fallback answer AI-client User-Agents, including a request with no User-Agent at all, the same way they answer WordPress. No bot filter is blocking them. This cannot see an IP-level block of the AI vendor.', 'thinkrank' ), | |
| 739 | 822 | ]; |
| 740 | 823 | } |
| 741 | 824 | |
| 825 | + /** | |
| 826 | + * How one probed User-Agent reads in the failure message. | |
| 827 | + * | |
| 828 | + * The empty agent is a request with no header at all, so printing it as a | |
| 829 | + * quoted empty string would read as though nothing was tested. | |
| 830 | + * | |
| 831 | + * @since 2.14.0 | |
| 832 | + * @param string $agent Probed agent, or NO_USER_AGENT. | |
| 833 | + * @return string | |
| 834 | + */ | |
| 835 | + private static function describe_agent( string $agent ): string { | |
| 836 | + if ( self::NO_USER_AGENT === $agent ) { | |
| 837 | + return __( 'a request with no User-Agent header', 'thinkrank' ); | |
| 838 | + } | |
| 839 | + | |
| 840 | + /* translators: %s: user agent string an AI client sends. */ | |
| 841 | + return sprintf( __( 'an AI client\'s User-Agent (%s)', 'thinkrank' ), $agent ); | |
| 842 | + } | |
| 843 | + | |
| 742 | 844 | // -- Helpers ----------------------------------------------------------- |
| 743 | 845 | |
| 744 | 846 | /** |
| 745 | 847 | * Status code of one unauthenticated probe, or null if it never answered. |
| 746 | 848 | * |
| 849 | + * Three agent values, all distinct: `null` sends WordPress's own agent and | |
| 850 | + * is the baseline; a string sends that agent; and the empty string sends no | |
| 851 | + * User-Agent header at all. The last one was measured rather than assumed, | |
| 852 | + * because a fallback to WordPress's agent there would mean the empty-UA | |
| 853 | + * probe silently tested nothing while reporting a pass (#884). Against this | |
| 854 | + * site, `'user-agent' => ''` arrived with HTTP_USER_AGENT unset. | |
| 855 | + * | |
| 747 | 856 | * @param string $url Endpoint to call. |
| 748 | - * @param string|null $agent User-Agent to send, or null for WordPress's own. | |
| 857 | + * @param string|null $agent User-Agent to send, null for WordPress's own, | |
| 858 | + * or '' to send no User-Agent header. | |
| 749 | 859 | * @return int|null |
| 750 | 860 | */ |
| 751 | 861 | private static function probe_status( string $url, ?string $agent ): ?int { |
| 752 | 862 | $args = [ |
