*/ private const DOCUMENTS = [ 'oauth-protected-resource' => '/.well-known/oauth-protected-resource', 'oauth-authorization-server' => '/.well-known/oauth-authorization-server', ]; /** * Status severity used to pick the combined result. * * @var array */ private const STATUS_RANK = [ 'good' => 0, 'recommended' => 1, 'critical' => 2, ]; /** * OAuth server context. * * @var Context */ private Context $context; /** * Constructor. * * @param Context $context OAuth server context. */ public function __construct( Context $context ) { $this->context = $context; } /** * Register the combined discovery-document self-check as a `direct` Site Health test. * * @param array>> $tests Existing Site Health tests, keyed by bucket ('direct'|'async'). * @return array>> Modified tests. */ public function add_test( array $tests ): array { $tests['direct'][ self::TEST_KEY ] = [ 'label' => __( 'MCP OAuth discovery documents', 'mcp-oauth' ), 'test' => [ $this, 'run_self_check' ], ]; return $tests; } /** * Run the combined discovery-document self-check. * * @return array Site Health test result (label, status, badge, description, actions, test). */ public function run_self_check(): array { if ( ! $this->context->is_enabled() ) { return $this->build_result( 'good', [], __( 'The MCP OAuth server is intentionally disabled (the wpmedia_mcp_oauth_server_enabled filter returns false), so the .well-known discovery documents are not expected to be reachable.', 'mcp-oauth' ) ); } if ( '' === (string) get_option( 'permalink_structure' ) ) { return $this->build_result( 'recommended', [], __( 'The .well-known OAuth discovery documents are served through a rewrite rule, which requires a pretty permalink structure. Enable one under Settings → Permalinks, then re-check this test.', 'mcp-oauth' ) ); } $cached = get_transient( self::TRANSIENT_KEY ); if ( is_array( $cached ) ) { return $cached; } $worst_status = 'good'; $failing = []; foreach ( self::DOCUMENTS as $name => $path ) { $response = wp_safe_remote_get( home_url( $path ), [ 'timeout' => self::FETCH_TIMEOUT, ] ); $status = $this->classify( $response ); if ( self::STATUS_RANK[ $status ] > self::STATUS_RANK[ $worst_status ] ) { $worst_status = $status; } if ( 'good' !== $status ) { $failing[] = $name; } } $result = $this->build_result( $worst_status, $failing ); set_transient( self::TRANSIENT_KEY, $result, self::TRANSIENT_TTL ); return $result; } /** * Classify a single document's fetch result into a Site Health status. * * @param array|WP_Error $response The wp_remote_get() response array, or a WP_Error. * @return string One of 'good', 'recommended', 'critical'. */ private function classify( $response ): string { if ( is_wp_error( $response ) ) { return 'recommended'; } $status_code = (int) wp_remote_retrieve_response_code( $response ); if ( in_array( $status_code, [ 401, 403, 407 ], true ) ) { return 'recommended'; } if ( 404 === $status_code ) { $powered_by = (string) wp_remote_retrieve_header( $response, 'x-powered-by' ); $redirect_by = (string) wp_remote_retrieve_header( $response, 'x-redirect-by' ); if ( '' === $powered_by && false === stripos( $redirect_by, 'WordPress' ) ) { return 'critical'; } return 'recommended'; } if ( 200 === $status_code ) { $body = (string) wp_remote_retrieve_body( $response ); $decoded = json_decode( $body, true ); if ( is_array( $decoded ) ) { return 'good'; } } return 'recommended'; } /** * Build the Site Health result array for a given combined status. * * @param string $status One of 'good', 'recommended', 'critical'. * @param string[] $failing Display names of the documents that did not report 'good'. * @param string $summary Optional override for the description's leading sentence * (used by the disabled/plain-permalinks short-circuits). * @return array */ private function build_result( string $status, array $failing, string $summary = '' ): array { $loopback_caveat = __( 'This check runs from the server to itself. A "Good" result here does not guarantee external clients can reach these documents: a CDN, WAF, or reverse proxy in front of the site can still 404 these paths for external traffic while the server\'s own loopback request bypasses it. Verify with an external curl request after applying any server-config change.', 'mcp-oauth' ); /* * The acme-challenge fingerprint is classified 'critical' internally so * the detailed guidance below is selected, but it is reported to Site * Health as 'recommended': the .well-known discovery documents are an * optional MCP feature, and a "critical" badge generates support tickets * for what is a non-blocking misconfiguration. */ $reported_status = 'critical' === $status ? 'recommended' : $status; if ( '' !== $summary ) { $description = sprintf( '

', $summary ); $actions = sprintf( '

', $loopback_caveat ); } elseif ( 'good' === $status ) { $description = sprintf( '

', __( 'Both .well-known OAuth discovery documents (oauth-protected-resource and oauth-authorization-server) responded with HTTP 200 and valid JSON.', 'mcp-oauth' ) ); $actions = sprintf( '

', $loopback_caveat ); } else { $document_list = implode( ', ', $failing ); if ( 'critical' === $status ) { $description = sprintf( '

', sprintf( /* translators: %s: comma-separated list of failing discovery document names. */ __( 'The following .well-known discovery document(s) returned a bare 404 with no WordPress-originated response header: %s. This matches the fingerprint of a physical .well-known/acme-challenge/ directory (provisioned by the host for Let\'s Encrypt auto-SSL) intercepting the request before WordPress runs — likely the cause here, though this should be confirmed against the actual .well-known/acme-challenge/ directory on the server before concluding root cause.', 'mcp-oauth' ), esc_html( $document_list ) ) ); $actions = sprintf( '

', __( 'Apply the Apache or Nginx snippet from this library\'s README ("Hosting: .well-known conflicts") to re-enable routing for these two paths without touching acme-challenge/.', 'mcp-oauth' ), __( 'If a CDN or page cache is in front of the site, purge it after applying the fix — a stale cached 404 for these paths can otherwise persist even once the server config is corrected.', 'mcp-oauth' ), $loopback_caveat ); } else { $description = sprintf( '

', sprintf( /* translators: %s: comma-separated list of failing discovery document names. */ __( 'The following .well-known discovery document(s) did not respond as expected: %s. This does not match the confirmed .well-known/acme-challenge/ interception fingerprint, so the cause is inconclusive from this check alone (it may be a timeout, an access wall such as HTTP Basic Auth or a WAF, or a WordPress-served error).', 'mcp-oauth' ), esc_html( $document_list ) ) ); $actions = sprintf( '

', __( 'Check your error/access logs for the requests to these paths, and rule out an authentication wall (staging HTTP Basic Auth, a WAF, or bot mitigation) before assuming a routing problem.', 'mcp-oauth' ), $loopback_caveat ); } } return [ 'label' => __( 'MCP OAuth discovery documents', 'mcp-oauth' ), 'status' => $reported_status, 'badge' => [ 'label' => __( 'Configuration', 'mcp-oauth' ), 'color' => 'blue', ], 'description' => $description, 'actions' => $actions, 'test' => self::TEST_KEY, ]; } }