• File: openapi-spec.php
  • Full Path: /home/slvgwrnz/public_html/wp-content/plugins/elementor/modules/agents/components/discovery/openapi-spec.php
  • Date Modified: 11/09/2026 10:39 AM
  • File size: 15.8 KB
  • MIME-type: text/x-php
  • Charset: utf-8
<?php

namespace Elementor\Modules\Agents\Components\Discovery;

use Elementor\Modules\Agents\Agent_Ready_Settings;
use Elementor\Modules\Agents\Classes\Feature_Component;
use Elementor\Modules\Agents\Module;
use Elementor\Modules\Agents\Prompt_Injection_Sanitizer;
use Elementor\Utils;

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * OpenAPI Specification endpoint — /openapi.json
 *
 * Publishes an OpenAPI 3.0.3 description of the WordPress REST API subset safe
 * for anonymous agent access (posts, pages, search). Published only when the
 * Agent Discovery module is enabled, permalink structure is not plain, and
 * anonymous REST API access passes reachability validation.
 *
 * Served via template_redirect, reusing transient + ETag + 304 logic from
 * well-known endpoints.
 */
class Openapi_Spec extends Feature_Component {

	const TRANSIENT_CONTENT = 'elementor_agents_openapi_content';
	const TRANSIENT_ETAG = 'elementor_agents_openapi_etag';
	const TRANSIENT_MODIFIED = 'elementor_agents_openapi_modified';
	const TRANSIENT_VALIDATED = 'elementor_agents_openapi_validated';
	const TRANSIENT_TTL = 3600;

	const ENDPOINT_SLUG = 'openapi.json';

	private Agent_Ready_Settings $settings;
	private Prompt_Injection_Sanitizer $sanitizer;

	public function __construct( Agent_Ready_Settings $settings ) {
		$this->settings  = $settings;
		$this->sanitizer = new Prompt_Injection_Sanitizer();
	}

	public function get_id(): string {
		return 'openapi_spec';
	}

	public function get_layer(): string {
		return 'discovery';
	}

	public function get_required_modules(): array {
		return [ Agent_Ready_Settings::MODULE_AGENT_DISCOVERY ];
	}

	public function register(): void {
		if ( ! $this->settings->is_module_active( Agent_Ready_Settings::MODULE_AGENT_DISCOVERY ) ) {
			return;
		}

		add_action( 'template_redirect', [ $this, 'maybe_serve_openapi' ], 1 );
		add_action( 'update_option_permalink_structure', [ $this, 'flush_cache' ] );
		add_action( 'update_option_blogname', [ $this, 'flush_cache' ] );
		add_action( 'update_option_blogdescription', [ $this, 'flush_cache' ] );
		add_action( 'update_option_home', [ $this, 'flush_cache' ] );
		add_action( 'update_option_siteurl', [ $this, 'flush_cache' ] );
		add_action( 'elementor/agents/llms_txt/cache_invalidated', [ $this, 'flush_cache' ] );
	}

	public function maybe_serve_openapi(): void {
		if ( ! $this->is_request_for_openapi() ) {
			return;
		}

		if ( ! $this->is_publishable() ) {
			status_header( 404 );
			exit;
		}

		$this->serve_openapi();
	}

	public function is_publishable(): bool {
		if ( '' === get_option( 'permalink_structure' ) ) {
			return false;
		}

		if ( $this->has_physical_openapi_file() ) {
			return false;
		}

		if ( ! $this->is_anonymous_rest_accessible() ) {
			return false;
		}

		$spec = $this->generate_spec();
		if ( empty( $spec['paths'] ) ) {
			return false;
		}

		// Must have at least one content endpoint (posts or pages), not just search
		$has_content_endpoint = isset( $spec['paths']['/wp/v2/posts'] ) || isset( $spec['paths']['/wp/v2/pages'] );
		if ( ! $has_content_endpoint ) {
			return false;
		}

		return true;
	}

	public function flush_cache(): void {
		delete_transient( self::TRANSIENT_CONTENT );
		delete_transient( self::TRANSIENT_ETAG );
		delete_transient( self::TRANSIENT_MODIFIED );
		delete_transient( self::TRANSIENT_VALIDATED );
	}

	private function is_request_for_openapi(): bool {
		$request_uri = isset( $_SERVER['REQUEST_URI'] ) ? sanitize_text_field( wp_unslash( $_SERVER['REQUEST_URI'] ) ) : '';
		$path        = wp_parse_url( $request_uri, PHP_URL_PATH );

		if ( ! $path ) {
			return false;
		}

		$home_path = wp_parse_url( home_url(), PHP_URL_PATH );
		$home_path = $home_path ? trailingslashit( $home_path ) : '/';

		if ( 0 === strpos( $path, $home_path ) ) {
			$path = substr( $path, strlen( $home_path ) );
		}

		return self::ENDPOINT_SLUG === ltrim( $path, '/' );
	}

	private function has_physical_openapi_file(): bool {
		$root_path = Module::get_llms_file_root_path();
		return file_exists( $root_path . self::ENDPOINT_SLUG );
	}

	private function is_anonymous_rest_accessible(): bool {
		$validated = get_transient( self::TRANSIENT_VALIDATED );

		if ( false !== $validated ) {
			return (bool) $validated;
		}

		$result = $this->validate_anonymous_rest_access();
		set_transient( self::TRANSIENT_VALIDATED, $result ? 1 : 0, self::TRANSIENT_TTL );

		return $result;
	}

	private function validate_anonymous_rest_access(): bool {
		$auth_error = apply_filters( 'rest_authentication_errors', null );

		if ( is_wp_error( $auth_error ) ) {
			return false;
		}

		$posts_url = rest_url( 'wp/v2/posts' );
		$args      = [
			'timeout'    => 5,
			'user-agent' => 'Elementor-Agent-Ready/OpenAPI-Validator',
			'sslverify'  => false,
		];

		$response = wp_remote_get( $posts_url, $args );

		if ( is_wp_error( $response ) ) {
			return false;
		}

		$status = wp_remote_retrieve_response_code( $response );
		return in_array( $status, [ 200, 403, 401 ], true );
	}

	private function serve_openapi(): void {
		$cached_content = get_transient( self::TRANSIENT_CONTENT );
		$cached_etag    = get_transient( self::TRANSIENT_ETAG );

		if ( false !== $cached_content && false !== $cached_etag ) {
			$this->send_response( $cached_content, $cached_etag );
			exit;
		}

		$spec           = $this->generate_spec();
		$content        = wp_json_encode( $spec, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE );
		$etag           = '"' . md5( $content ) . '"';
		$last_modified  = time();

		set_transient( self::TRANSIENT_CONTENT, $content, self::TRANSIENT_TTL );
		set_transient( self::TRANSIENT_ETAG, $etag, self::TRANSIENT_TTL );
		set_transient( self::TRANSIENT_MODIFIED, $last_modified, self::TRANSIENT_TTL );

		$this->send_response( $content, $etag );
		exit;
	}

	private function send_response( string $content, string $etag ): void {
		$if_none_match = isset( $_SERVER['HTTP_IF_NONE_MATCH'] )
			? trim( sanitize_text_field( wp_unslash( $_SERVER['HTTP_IF_NONE_MATCH'] ) ) )
			: '';

		if ( '' !== $if_none_match && $this->etag_matches( $if_none_match, $etag ) ) {
			status_header( 304 );
			header( 'ETag: ' . $etag );
			exit;
		}

		status_header( 200 );
		header( 'Content-Type: application/json; charset=utf-8' );
		header( 'X-Content-Type-Options: nosniff' );
		header( 'Cache-Control: public, max-age=' . self::TRANSIENT_TTL );
		header( 'ETag: ' . $etag );
		header( 'Access-Control-Allow-Origin: *' );
		header( 'X-Robots-Tag: noindex' );

		$last_modified = get_transient( self::TRANSIENT_MODIFIED );
		if ( false !== $last_modified ) {
			header( 'Last-Modified: ' . gmdate( 'D, d M Y H:i:s', (int) $last_modified ) . ' GMT' );
		}

		Utils::print_unescaped_internal_string( $content );
	}

	private function etag_matches( string $header, string $etag ): bool {
		foreach ( explode( ',', $header ) as $candidate ) {
			$candidate = trim( $candidate );

			if ( '*' === $candidate ) {
				return true;
			}

			if ( 0 === strpos( $candidate, 'W/' ) ) {
				$candidate = substr( $candidate, 2 );
			}

			if ( $candidate === $etag ) {
				return true;
			}
		}

		return false;
	}

	private function generate_spec(): array {
		$site_name        = $this->sanitizer->sanitize( get_bloginfo( 'name' ) );
		$site_description = $this->sanitizer->sanitize( get_bloginfo( 'description' ) );

		$spec = [
			'openapi'  => '3.0.3',
			'info'     => [
				'title'       => $site_name ? $site_name : 'WordPress Site',
				'description' => $site_description ? $site_description : 'WordPress REST API for agent access',
				'version'     => '1.0.0',
			],
			'security' => [],
			'servers'  => [
				[
					'url'         => untrailingslashit( rest_url() ),
					'description' => 'WordPress REST API',
				],
			],
			'paths'      => [],
			'components' => [
				'schemas' => [
					'Content'  => [
						'type'       => 'object',
						'properties' => [
							'id'       => [ 'type' => 'integer' ],
							'slug'     => [ 'type' => 'string' ],
							'link'     => [
								'type'   => 'string',
								'format' => 'uri',
							],
							'date'     => [ 'type' => 'string' ],
							'modified' => [ 'type' => 'string' ],
							'title'    => [ '$ref' => '#/components/schemas/Rendered' ],
							'excerpt'  => [ '$ref' => '#/components/schemas/Rendered' ],
							'content'  => [ '$ref' => '#/components/schemas/Rendered' ],
						],
					],
					'Rendered' => [
						'type'       => 'object',
						'properties' => [
							'rendered' => [ 'type' => 'string' ],
						],
					],
					'SearchResult' => [
						'type'       => 'object',
						'properties' => [
							'id'      => [ 'type' => 'integer' ],
							'title'   => [ 'type' => 'string' ],
							'url'     => [
								'type'   => 'string',
								'format' => 'uri',
							],
							'type'    => [ 'type' => 'string' ],
							'subtype' => [ 'type' => 'string' ],
						],
					],
					'Error' => [
						'type'       => 'object',
						'properties' => [
							'code'    => [ 'type' => 'string' ],
							'message' => [ 'type' => 'string' ],
						],
					],
				],
			],
		];

		$post_type = get_post_type_object( 'post' );
		if ( $post_type && $post_type->show_in_rest ) {
			$spec['paths']['/wp/v2/posts']      = $this->build_list_operation( 'posts', 'listPosts' );
			$spec['paths']['/wp/v2/posts/{id}'] = $this->build_get_operation( 'post', 'getPost' );
		}

		$page_type = get_post_type_object( 'page' );
		if ( $page_type && $page_type->show_in_rest ) {
			$spec['paths']['/wp/v2/pages']      = $this->build_list_operation( 'pages', 'listPages' );
			$spec['paths']['/wp/v2/pages/{id}'] = $this->build_get_operation( 'page', 'getPage' );
		}

		$subtypes = [];
		if ( $post_type && $post_type->show_in_rest ) {
			$subtypes[] = 'post';
		}
		if ( $page_type && $page_type->show_in_rest ) {
			$subtypes[] = 'page';
		}

		if ( ! empty( $subtypes ) ) {
			$spec['paths']['/wp/v2/search'] = $this->build_search_operation( $subtypes );
		}

		return $spec;
	}

	private function build_list_operation( string $type, string $operation_id ): array {
		return [
			'get' => [
				'operationId' => $operation_id,
				'summary'     => "List all {$type}",
				'description' => "Retrieve a paginated collection of published {$type} for agent consumption",
				'parameters'  => [
					[
						'name'        => 'page',
						'in'          => 'query',
						'required'    => false,
						'schema'      => [
							'type'    => 'integer',
							'minimum' => 1,
							'default' => 1,
						],
						'description' => 'Current page of the collection',
					],
					[
						'name'        => 'per_page',
						'in'          => 'query',
						'required'    => false,
						'schema'      => [
							'type'    => 'integer',
							'minimum' => 1,
							'maximum' => 100,
							'default' => 10,
						],
						'description' => 'Maximum number of items per page',
					],
					[
						'name'        => 'search',
						'in'          => 'query',
						'required'    => false,
						'schema'      => [ 'type' => 'string' ],
						'description' => 'Limit results to those matching a string',
					],
					[
						'name'        => 'slug',
						'in'          => 'query',
						'required'    => false,
						'schema'      => [ 'type' => 'string' ],
						'description' => 'Limit result set to specific slug',
					],
					[
						'name'        => 'orderby',
						'in'          => 'query',
						'required'    => false,
						'schema'      => [
							'type'    => 'string',
							'enum'    => [ 'date', 'modified', 'title', 'slug', 'id', 'relevance' ],
							'default' => 'date',
						],
						'description' => 'Sort collection by object attribute',
					],
					[
						'name'        => 'order',
						'in'          => 'query',
						'required'    => false,
						'schema'      => [
							'type'    => 'string',
							'enum'    => [ 'asc', 'desc' ],
							'default' => 'desc',
						],
						'description' => 'Order sort attribute ascending or descending',
					],
					[
						'name'        => '_fields',
						'in'          => 'query',
						'required'    => false,
						'schema'      => [ 'type' => 'string' ],
						'description' => 'Limit response to specific fields',
					],
				],
				'responses'   => [
					'200' => [
						'description' => "List of {$type}",
						'headers'     => [
							'X-WP-Total'      => [
								'schema'      => [ 'type' => 'integer' ],
								'description' => 'Total number of items',
							],
							'X-WP-TotalPages' => [
								'schema'      => [ 'type' => 'integer' ],
								'description' => 'Total number of pages',
							],
						],
						'content'     => [
							'application/json' => [
								'schema' => [
									'type'  => 'array',
									'items' => [ '$ref' => '#/components/schemas/Content' ],
								],
							],
						],
					],
					'400' => [
						'description' => 'Invalid request parameters',
						'content'     => [
							'application/json' => [
								'schema' => [ '$ref' => '#/components/schemas/Error' ],
							],
						],
					],
				],
			],
		];
	}

	private function build_get_operation( string $type, string $operation_id ): array {
		return [
			'get' => [
				'operationId' => $operation_id,
				'summary'     => "Get a {$type}",
				'description' => "Retrieve a specific published {$type} by ID for agent consumption",
				'parameters'  => [
					[
						'name'        => 'id',
						'in'          => 'path',
						'required'    => true,
						'schema'      => [
							'type'    => 'integer',
							'minimum' => 1,
						],
						'description' => "Unique identifier for the {$type}",
					],
					[
						'name'        => '_fields',
						'in'          => 'query',
						'required'    => false,
						'schema'      => [ 'type' => 'string' ],
						'description' => 'Limit response to specific fields',
					],
				],
				'responses'   => [
					'200' => [
						'description' => "The requested {$type}",
						'content'     => [
							'application/json' => [
								'schema' => [ '$ref' => '#/components/schemas/Content' ],
							],
						],
					],
					'404' => [
						'description' => "{$type} not found",
						'content'     => [
							'application/json' => [
								'schema' => [ '$ref' => '#/components/schemas/Error' ],
							],
						],
					],
				],
			],
		];
	}

	private function build_search_operation( array $subtypes ): array {
		return [
			'get' => [
				'operationId' => 'searchContent',
				'summary'     => 'Search site content',
				'description' => 'Search across posts and pages using keywords',
				'parameters'  => [
					[
						'name'        => 'search',
						'in'          => 'query',
						'required'    => true,
						'schema'      => [ 'type' => 'string' ],
						'description' => 'Search keyword (required)',
					],
					[
						'name'        => 'subtype',
						'in'          => 'query',
						'required'    => false,
						'schema'      => [
							'type' => 'string',
							'enum' => $subtypes,
						],
						'description' => 'Limit results to a specific content type',
					],
					[
						'name'        => 'page',
						'in'          => 'query',
						'required'    => false,
						'schema'      => [
							'type'    => 'integer',
							'minimum' => 1,
							'default' => 1,
						],
						'description' => 'Current page of the collection',
					],
					[
						'name'        => 'per_page',
						'in'          => 'query',
						'required'    => false,
						'schema'      => [
							'type'    => 'integer',
							'minimum' => 1,
							'maximum' => 100,
							'default' => 10,
						],
						'description' => 'Maximum number of items per page',
					],
				],
				'responses'   => [
					'200' => [
						'description' => 'Search results',
						'content'     => [
							'application/json' => [
								'schema' => [
									'type'  => 'array',
									'items' => [ '$ref' => '#/components/schemas/SearchResult' ],
								],
							],
						],
					],
					'400' => [
						'description' => 'Invalid request parameters',
						'content'     => [
							'application/json' => [
								'schema' => [ '$ref' => '#/components/schemas/Error' ],
							],
						],
					],
				],
			],
		];
	}
}