<?php
/**
 * OAuth 2.1 authorization server with mandatory PKCE (S256), dynamic client
 * registration (RFC 7591), authorization server metadata (RFC 8414),
 * protected resource metadata (RFC 9728) and refresh token rotation with
 * replay detection.
 *
 * @package HandyMCP
 */

namespace HandyMCP\Auth;

use HandyMCP\Database\Installer;
use HandyMCP\Security\RateLimiter;
use HandyMCP\Settings;
use HandyMCP\Support\Crypto;
use HandyMCP\Support\Ids;

defined( 'ABSPATH' ) || exit;

/**
 * Self-hosted OAuth server. No third-party relay is involved.
 */
final class OAuthServer {

	/** @var Settings */
	private $settings;

	/** @var TokenRepository */
	private $tokens;

	/** @var RateLimiter */
	private $limiter;

	/** @var string Limiter key for failed grants of the current token request. */
	private $grant_key = '';

	/** @var Authenticator */
	private $auth;

	/**
	 * Constructor.
	 *
	 * @param Settings        $settings Settings.
	 * @param TokenRepository $tokens   Tokens.
	 * @param RateLimiter     $limiter  Limiter.
	 * @param Authenticator   $auth     Authenticator.
	 */
	public function __construct( Settings $settings, TokenRepository $tokens, RateLimiter $limiter, Authenticator $auth ) {
		$this->settings = $settings;
		$this->tokens   = $tokens;
		$this->limiter  = $limiter;
		$this->auth     = $auth;
	}

	/**
	 * Hooks.
	 */
	public function register(): void {
		add_action( 'rest_api_init', array( $this, 'routes' ) );
		add_action( 'init', array( $this, 'maybe_handle_front_request' ), 1 );
		add_filter( 'rest_post_dispatch', array( __CLASS__, 'no_cache_rest' ), 10, 3 );
	}

	/**
	 * Keep page caches and CDNs from storing any HandyMCP REST response.
	 *
	 * @param mixed            $result  Response.
	 * @param \WP_REST_Server  $server  Server.
	 * @param \WP_REST_Request $request Request.
	 * @return mixed
	 */
	public static function no_cache_rest( $result, $server, $request ) {
		if ( $result instanceof \WP_REST_Response && $request instanceof \WP_REST_Request && 0 === strpos( ltrim( (string) $request->get_route(), '/' ), HANDYMCP_REST_NS . '/' ) ) {
			$result->header( 'Cache-Control', 'no-store, no-cache, must-revalidate, private' );
			$result->header( 'Pragma', 'no-cache' );
		}
		return $result;
	}

	/**
	 * Public URLs.
	 *
	 * @return array<string, string>
	 */
	public function urls(): array {
		return array(
			'issuer'                 => self::issuer(),
			'authorization_endpoint' => home_url( '/handymcp/oauth/authorize' ),
			'token_endpoint'         => rest_url( HANDYMCP_REST_NS . '/oauth/token' ),
			'registration_endpoint'  => rest_url( HANDYMCP_REST_NS . '/oauth/register' ),
			'revocation_endpoint'    => rest_url( HANDYMCP_REST_NS . '/oauth/revoke' ),
			'resource'               => rest_url( HANDYMCP_REST_NS . '/mcp' ),
		);
	}

	/**
	 * Option that stores the issuer mode found by the last discovery probe.
	 */
	const ISSUER_MODE = 'handymcp_issuer_mode';

	/**
	 * Can the issuer live under /wp-json/? Not with plain permalinks, where
	 * the REST API is reached through ?rest_route= and has no real path.
	 */
	public static function path_mode_possible(): bool {
		return false === strpos( rest_url( HANDYMCP_REST_NS ), '?' );
	}

	/**
	 * Issuer path mode: the sign-in server is announced under /wp-json/ (for
	 * hosts that answer /.well-known/ themselves before WordPress runs). Off
	 * by default, so working sites keep the same issuer. Turned on by the
	 * discovery probe, or forced with the HANDYMCP_ISSUER_PATH_MODE constant
	 * or the handymcp_oauth_issuer_path_mode filter.
	 */
	public static function issuer_path_mode(): bool {
		if ( ! self::path_mode_possible() ) {
			return false;
		}
		$stored = get_option( self::ISSUER_MODE );
		$on     = is_array( $stored ) && 'path' === ( $stored['mode'] ?? '' );
		if ( defined( 'HANDYMCP_ISSUER_PATH_MODE' ) ) {
			$on = (bool) constant( 'HANDYMCP_ISSUER_PATH_MODE' );
		}
		return (bool) apply_filters( 'handymcp_oauth_issuer_path_mode', $on );
	}

	/**
	 * The current issuer: the site address, or the plugin's REST base in path mode.
	 */
	public static function issuer(): string {
		return self::issuer_path_mode() ? self::path_issuer() : untrailingslashit( home_url() );
	}

	/**
	 * The issuer used in path mode.
	 */
	public static function path_issuer(): string {
		return untrailingslashit( rest_url( HANDYMCP_REST_NS ) );
	}

	/**
	 * Store the issuer mode from a discovery probe.
	 *
	 * Some site owners add static /.well-known/ files by hand (for hosts that
	 * answer /.well-known/ before WordPress runs). Such a file wins: when it
	 * names the site address as issuer, root mode is used; when it names the
	 * /wp-json/ issuer, path mode is used. Any other issuer cannot match this
	 * plugin, so the mode is left as it is and a warning is stored.
	 *
	 * @param bool   $root_ok     Root /.well-known/oauth-authorization-server answers with sign-in JSON.
	 * @param bool   $rest_ok     The copy under /wp-json/ answers with our JSON.
	 * @param string $root_issuer Issuer named by a static root file ('' when WordPress answered itself).
	 * @return string|null The stored mode, or null when nothing was decided.
	 */
	public static function store_issuer_mode( bool $root_ok, bool $rest_ok, string $root_issuer = '' ): ?string {
		$mismatch    = '';
		$root_issuer = untrailingslashit( $root_issuer );
		if ( $root_ok && ( '' === $root_issuer || untrailingslashit( home_url() ) === $root_issuer ) ) {
			// WordPress answers the root address itself, or a static file names the site address.
			$mode = 'root';
		} elseif ( $root_ok && self::path_issuer() === $root_issuer && self::path_mode_possible() ) {
			$mode = 'path'; // A static file that already names the /wp-json/ issuer.
		} elseif ( $root_ok ) {
			$mismatch = $root_issuer;
			$stored   = get_option( self::ISSUER_MODE );
			$mode     = is_array( $stored ) && 'path' === ( $stored['mode'] ?? '' ) ? 'path' : 'root';
		} elseif ( $rest_ok && self::path_mode_possible() ) {
			$mode = 'path';
		} else {
			return null; // Nothing usable either way: keep the previous decision.
		}
		update_option( self::ISSUER_MODE, array( 'mode' => $mode, 'when' => time(), 'mismatch' => $mismatch ), false );
		return $mode;
	}

	/**
	 * Issuer named by a static /.well-known/ file that does not match this
	 * site ('' when there is none).
	 */
	public static function issuer_mismatch(): string {
		$stored = get_option( self::ISSUER_MODE );
		return is_array( $stored ) && is_string( $stored['mismatch'] ?? null ) ? $stored['mismatch'] : '';
	}

	/**
	 * Authorization server metadata (RFC 8414).
	 *
	 * @return array<string, mixed>
	 */
	public function server_metadata(): array {
		$u    = $this->urls();
		$meta = array(
			'issuer'                                => $u['issuer'],
			'authorization_endpoint'                => $u['authorization_endpoint'],
			'token_endpoint'                        => $u['token_endpoint'],
			'revocation_endpoint'                   => $u['revocation_endpoint'],
			'response_types_supported'              => array( 'code' ),
			'grant_types_supported'                 => array( 'authorization_code', 'refresh_token' ),
			'code_challenge_methods_supported'      => array( 'S256' ),
			'token_endpoint_auth_methods_supported' => array( 'none' ),
			'scopes_supported'                      => array_keys( Scopes::all() ),
			'service_documentation'                 => admin_url( 'admin.php?page=handymcp' ),
			'client_id_metadata_document_supported' => (bool) $this->settings->get( 'dcr_enabled', true ),
			'authorization_response_iss_parameter_supported' => true,
		);
		if ( $this->settings->get( 'dcr_enabled', true ) ) {
			$meta['registration_endpoint'] = $u['registration_endpoint'];
		}
		return $meta;
	}

	/**
	 * Protected resource metadata (RFC 9728).
	 *
	 * @return array<string, mixed>
	 */
	public function resource_metadata(): array {
		$u = $this->urls();
		return array(
			'resource'                 => $u['resource'],
			'authorization_servers'    => array( $u['issuer'] ),
			'scopes_supported'         => array_keys( Scopes::all() ),
			'bearer_methods_supported' => array( 'header' ),
			'resource_name'            => get_bloginfo( 'name' ) . ' MCP',
		);
	}

	/**
	 * REST routes.
	 */
	public function routes(): void {
		register_rest_route(
			HANDYMCP_REST_NS,
			'/oauth/register',
			array(
				'methods'             => 'POST',
				'callback'            => array( $this, 'rest_register' ),
				'permission_callback' => '__return_true',
			)
		);
		register_rest_route(
			HANDYMCP_REST_NS,
			'/oauth/token',
			array(
				'methods'             => 'POST',
				'callback'            => array( $this, 'rest_token' ),
				'permission_callback' => '__return_true',
			)
		);
		register_rest_route(
			HANDYMCP_REST_NS,
			'/oauth/revoke',
			array(
				'methods'             => 'POST',
				'callback'            => array( $this, 'rest_revoke' ),
				'permission_callback' => '__return_true',
			)
		);
		// Copy of /.well-known/oauth-protected-resource for hosts that answer
		// /.well-known/ themselves; the WWW-Authenticate header points here when
		// the last connection check found the /.well-known/ address not working.
		register_rest_route(
			HANDYMCP_REST_NS,
			'/oauth-protected-resource',
			array(
				'methods'             => 'GET',
				'callback'            => function () {
					return new \WP_REST_Response( $this->resource_metadata() );
				},
				'permission_callback' => '__return_true',
			)
		);
		$as_meta = function () {
			if ( ! $this->settings->get( 'oauth_enabled', true ) ) {
				return new \WP_REST_Response( array( 'error' => 'oauth_disabled' ), 404 );
			}
			return new \WP_REST_Response( $this->server_metadata() );
		};
		register_rest_route(
			HANDYMCP_REST_NS,
			'/oauth/metadata',
			array(
				'methods'             => 'GET',
				'callback'            => $as_meta,
				'permission_callback' => '__return_true',
			)
		);
		// <issuer>/.well-known/openid-configuration and the RFC 8414 name, for
		// issuer path mode: AI apps read these when /.well-known/ at the site
		// root never reaches WordPress.
		foreach ( array( 'openid-configuration', 'oauth-authorization-server' ) as $doc ) {
			register_rest_route(
				HANDYMCP_REST_NS,
				'/\\.well-known/' . $doc,
				array(
					'methods'             => 'GET',
					'callback'            => $as_meta,
					'permission_callback' => '__return_true',
				)
			);
		}
	}

	/**
	 * Well-known and authorize endpoints outside the REST API.
	 */
	public function maybe_handle_front_request(): void {
		$uri = isset( $_SERVER['REQUEST_URI'] ) ? (string) wp_parse_url( esc_url_raw( wp_unslash( $_SERVER['REQUEST_URI'] ) ), PHP_URL_PATH ) : '';
		if ( '' === $uri ) {
			return;
		}
		$home_path = (string) wp_parse_url( home_url( '/' ), PHP_URL_PATH );
		$path      = '/' . ltrim( substr( $uri, strlen( untrailingslashit( $home_path ) ) ), '/' );

		// phpcs:ignore WordPress.Security.NonceVerification.Recommended
		$qv = isset( $_GET['handymcp_oauth'] ) ? sanitize_key( wp_unslash( $_GET['handymcp_oauth'] ) ) : '';

		// Prefix matches also answer the path-suffixed forms (RFC 9728 / RFC 8414),
		// for example /.well-known/oauth-protected-resource/wp-json/handymcp/v1/mcp.
		if ( 0 === strpos( $path, '/.well-known/oauth-protected-resource' ) ) {
			$this->send_json( $this->resource_metadata() );
		}
		if ( 0 === strpos( $path, '/.well-known/oauth-authorization-server' ) || 0 === strpos( $path, '/.well-known/openid-configuration' ) ) {
			if ( ! $this->settings->get( 'oauth_enabled', true ) ) {
				$this->send_json( array( 'error' => 'oauth_disabled' ), 404 );
			}
			$this->send_json( $this->server_metadata() );
		}
		if ( '/handymcp/oauth/authorize' === untrailingslashit( $path ) || 'authorize' === $qv ) {
			$this->handle_authorize();
		}
		$this->maybe_default_endpoint( untrailingslashit( $path ) );
	}

	/**
	 * Default endpoints at the site root: /authorize, /token and /register.
	 *
	 * When an AI app cannot read the /.well-known/ sign-in details it falls
	 * back to these addresses (MCP 2025-03-26). Some hosts answer /.well-known/
	 * themselves before WordPress runs (SiteGround does this on every site), so
	 * without them the app cannot sign in. Each one only answers requests that
	 * are clearly meant for this plugin, so a page with the same slug keeps
	 * working.
	 *
	 * @param string $path Request path relative to the site root.
	 */
	private function maybe_default_endpoint( string $path ): void {
		if ( ! in_array( $path, array( '/authorize', '/token', '/register' ), true ) || ! $this->settings->get( 'oauth_enabled', true ) ) {
			return;
		}
		$method = strtoupper( sanitize_text_field( wp_unslash( $_SERVER['REQUEST_METHOD'] ?? 'GET' ) ) );
		// phpcs:disable WordPress.Security.NonceVerification
		if ( '/authorize' === $path ) {
			$src = 'POST' === $method ? $_POST : $_GET;
			if ( isset( $src['client_id'], $src['response_type'], $src['code_challenge'] ) && $this->get_client( sanitize_text_field( wp_unslash( self::str( $src['client_id'] ) ) ) ) ) {
				$this->handle_authorize();
			}
			return;
		}
		if ( 'POST' !== $method ) {
			return;
		}
		$raw  = (string) file_get_contents( 'php://input' ); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_get_contents_file_get_contents
		$json = json_decode( $raw, true );
		$json = is_array( $json ) ? $json : array();
		if ( '/register' === $path ) {
			if ( isset( $json['redirect_uris'] ) && is_array( $json['redirect_uris'] ) ) {
				$this->serve_rest( array( $this, 'rest_register' ), $raw, $json );
			}
			return;
		}
		$p     = array_merge( $json, wp_unslash( $_POST ) );
		$grant = self::str( $p['grant_type'] ?? '' );
		$value = self::str( 'refresh_token' === $grant ? ( $p['refresh_token'] ?? '' ) : ( $p['code'] ?? '' ) );
		if ( in_array( $grant, array( 'authorization_code', 'refresh_token' ), true ) && 0 === strpos( $value, 'handymcp_' ) ) {
			$this->serve_rest( array( $this, 'rest_token' ), $raw, $json );
		}
		// phpcs:enable
	}

	/**
	 * Run a REST handler for a request that arrived outside the REST API and
	 * send its answer as JSON.
	 *
	 * @param callable             $handler Handler taking a WP_REST_Request.
	 * @param string               $raw     Raw body.
	 * @param array<string, mixed> $json    Decoded JSON body.
	 */
	private function serve_rest( callable $handler, string $raw, array $json ): void {
		$request = new \WP_REST_Request( 'POST' );
		$request->set_body( $raw );
		$request->set_header( 'content-type', sanitize_text_field( wp_unslash( $_SERVER['CONTENT_TYPE'] ?? ( $json ? 'application/json' : 'application/x-www-form-urlencoded' ) ) ) );
		$request->set_body_params( wp_unslash( $_POST ) ); // phpcs:ignore WordPress.Security.NonceVerification
		$response = call_user_func( $handler, $request );
		if ( ! defined( 'DONOTCACHEPAGE' ) ) {
			define( 'DONOTCACHEPAGE', true ); // phpcs:ignore WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedConstantFound -- standard constant read by cache plugins.
		}
		nocache_headers();
		status_header( $response->get_status() );
		header( 'Content-Type: application/json; charset=utf-8' );
		self::no_cache_headers();
		foreach ( $response->get_headers() as $name => $value ) {
			if ( in_array( strtolower( (string) $name ), array( 'cache-control', 'www-authenticate', 'retry-after' ), true ) ) {
				header( $name . ': ' . $value );
			}
		}
		echo wp_json_encode( $response->get_data(), JSON_UNESCAPED_SLASHES );
		exit;
	}

	/**
	 * Headers that keep page caches, LiteSpeed and CDNs from storing a sign-in answer.
	 * Sent as headers only: no other plugin's settings are changed.
	 */
	public static function no_cache_headers(): void {
		if ( headers_sent() ) {
			return;
		}
		header( 'Cache-Control: no-store, private' );
		header( 'X-LiteSpeed-Cache-Control: no-cache' );
	}

	/**
	 * Emit JSON and stop.
	 *
	 * @param array<string, mixed> $data   Data.
	 * @param int                  $status HTTP status.
	 */
	private function send_json( array $data, int $status = 200 ): void {
		if ( ! defined( 'DONOTCACHEPAGE' ) ) {
			define( 'DONOTCACHEPAGE', true ); // phpcs:ignore WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedConstantFound -- standard constant read by cache plugins.
		}
		nocache_headers();
		status_header( $status );
		header( 'Content-Type: application/json; charset=utf-8' );
		header( 'Access-Control-Allow-Origin: *' );
		header( 'X-HandyMCP: 1' ); // Tells the discovery probe that WordPress answered, not a static file.
		self::no_cache_headers();
		echo wp_json_encode( $data, JSON_UNESCAPED_SLASHES | JSON_PRETTY_PRINT );
		exit;
	}

	/**
	 * A request parameter as a string; arrays and objects become ''.
	 *
	 * @param mixed $v Value.
	 */
	private static function str( $v ): string {
		return is_scalar( $v ) ? (string) $v : '';
	}

	/**
	 * Find a registered client.
	 *
	 * @param string $client_id Client id.
	 * @return object|null
	 */
	public function get_client( string $client_id ) {
		if ( self::is_cimd( $client_id ) ) {
			// A metadata-document client registers itself, so it follows the same switch as dynamic registration.
			return $this->settings->get( 'dcr_enabled', true ) ? $this->cimd_client( $client_id ) : null;
		}
		global $wpdb;
		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- custom table, auth lookup must not be cached.
		$row = $wpdb->get_row( $wpdb->prepare( 'SELECT * FROM %i WHERE client_id = %s AND disabled = 0', Installer::table( 'oauth_clients' ), $client_id ) );
		return $row ? $row : null;
	}

	/**
	 * Is this client_id a Client ID Metadata Document URL (CIMD)?
	 *
	 * @param string $id Client id.
	 */
	public static function is_cimd( string $id ): bool {
		if ( 0 !== stripos( $id, 'https://' ) || strlen( $id ) > 255 ) {
			return false;
		}
		$parts = wp_parse_url( $id );
		if ( ! is_array( $parts ) || empty( $parts['host'] ) || isset( $parts['user'] ) || isset( $parts['pass'] ) || isset( $parts['fragment'] ) || ( isset( $parts['port'] ) && 443 !== (int) $parts['port'] ) ) {
			return false;
		}
		$path = (string) ( $parts['path'] ?? '' );
		return '' !== $path && '/' !== $path;
	}

	/**
	 * Short internal id for a CIMD client (the URL is too long for our tables).
	 *
	 * @param string $url Client id URL.
	 */
	public static function cimd_id( string $url ): string {
		return 'cimd_' . substr( hash( 'sha256', $url ), 0, 40 );
	}

	/**
	 * Load (and refresh daily) a client that identifies itself with a metadata
	 * document URL, as newer Claude and ChatGPT versions do. No registration step.
	 *
	 * @param string $url Client id URL.
	 * @return object|null
	 */
	private function cimd_client( string $url ) {
		global $wpdb;
		$table = Installer::table( 'oauth_clients' );
		$id    = self::cimd_id( $url );
		$row   = $wpdb->get_row( $wpdb->prepare( 'SELECT * FROM %i WHERE client_id = %s', $table, $id ) ); // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- custom table, auth lookup must not be cached.
		if ( $row && (int) $row->disabled ) {
			return null;
		}
		if ( $row && strtotime( $row->created_at . ' UTC' ) > time() - DAY_IN_SECONDS ) {
			return $row;
		}
		if ( ! $this->settings->get( 'oauth_enabled', true ) || ! $this->limiter->allow( 'cimd:' . Authenticator::client_ip(), 'scan' ) ) {
			return $row ? $row : null;
		}
		$res  = wp_safe_remote_get( $url, array( 'timeout' => 5, 'redirection' => 0, 'limit_response_size' => 20000, 'headers' => array( 'Accept' => 'application/json' ) ) );
		$doc  = is_wp_error( $res ) || 200 !== (int) wp_remote_retrieve_response_code( $res ) ? null : json_decode( (string) wp_remote_retrieve_body( $res ), true );
		$uris = is_array( $doc ) && isset( $doc['redirect_uris'] ) && is_array( $doc['redirect_uris'] ) ? array_values( array_filter( $doc['redirect_uris'], 'is_string' ) ) : array();
		$ok   = is_array( $doc ) && ( $doc['client_id'] ?? '' ) === $url && $uris && count( $uris ) <= 10 && 'none' === ( $doc['token_endpoint_auth_method'] ?? 'none' );
		foreach ( $uris as $uri ) {
			$ok = $ok && self::redirect_uri_allowed( $uri );
		}
		if ( ! $ok ) {
			return $row ? $row : null; // Keep a known client working if its document is briefly unreachable.
		}
		$data = array(
			'client_name'   => mb_substr( sanitize_text_field( self::str( $doc['client_name'] ?? wp_parse_url( $url, PHP_URL_HOST ) ) ), 0, 120 ),
			'redirect_uris' => (string) wp_json_encode( $uris ),
			'client_uri'    => esc_url_raw( $url ),
			'created_at'    => Ids::now(),
		);
		if ( $row ) {
			$wpdb->update( $table, $data, array( 'client_id' => $id ) ); // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- custom table write.
		} else {
			if ( ! $this->make_room( 'cimd' ) ) {
				return null;
			}
			$wpdb->insert( $table, $data + array( 'client_id' => $id, 'created_via' => 'cimd' ) ); // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery -- custom table write.
		}
		return $wpdb->get_row( $wpdb->prepare( 'SELECT * FROM %i WHERE client_id = %s AND disabled = 0', $table, $id ) ); // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- custom table, auth lookup must not be cached.
	}

	/**
	 * Clean up sign-in state: dynamically registered apps with no active token,
	 * every pending authorization code, and expired or revoked tokens. Active
	 * tokens and access tokens made in the dashboard (PATs) are never touched;
	 * revoked tokens of a sign-in that is still active are kept so a reused old
	 * refresh token is still caught.
	 *
	 * @return array{clients: int, codes: int, tokens: int}
	 */
	public function reset_state(): array {
		global $wpdb;
		$tokens  = Installer::table( 'tokens' );
		$clients = Installer::table( 'oauth_clients' );
		$now     = Ids::now();
		// phpcs:disable WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- custom tables, one-off cleanup.
		$active   = (array) $wpdb->get_col( $wpdb->prepare( "SELECT DISTINCT client_id FROM %i WHERE kind IN ('at','rt') AND revoked = 0 AND (expires_at IS NULL OR expires_at > %s)", $tokens, $now ) );
		$families = (array) $wpdb->get_col( $wpdb->prepare( "SELECT DISTINCT family FROM %i WHERE kind IN ('at','rt') AND revoked = 0 AND family <> '' AND (expires_at IS NULL OR expires_at > %s)", $tokens, $now ) );
		$out      = array( 'clients' => 0, 'codes' => 0, 'tokens' => 0 );

		$dcr = (array) $wpdb->get_col( $wpdb->prepare( "SELECT client_id FROM %i WHERE created_via = 'dcr'", $clients ) );
		foreach ( array_diff( $dcr, $active ) as $id ) {
			$out['clients'] += (int) $wpdb->delete( $clients, array( 'client_id' => $id ) );
		}
		$out['codes'] = (int) $wpdb->query( $wpdb->prepare( 'DELETE FROM %i', Installer::table( 'oauth_codes' ) ) );

		$dead = $wpdb->get_results( $wpdb->prepare( "SELECT id, family FROM %i WHERE kind IN ('at','rt') AND (revoked = 1 OR (expires_at IS NOT NULL AND expires_at <= %s))", $tokens, $now ) );
		foreach ( (array) $dead as $row ) {
			if ( '' !== (string) $row->family && in_array( (string) $row->family, $families, true ) ) {
				continue;
			}
			$out['tokens'] += (int) $wpdb->delete( $tokens, array( 'id' => (int) $row->id ) );
		}
		// phpcs:enable
		return $out;
	}

	/**
	 * All clients for the dashboard.
	 *
	 * @return array<int, object>
	 */
	public function list_clients(): array {
		global $wpdb;
		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- custom table, client list must be current.
		$rows = $wpdb->get_results( $wpdb->prepare( 'SELECT * FROM %i ORDER BY id DESC LIMIT 100', Installer::table( 'oauth_clients' ) ) );
		return is_array( $rows ) ? $rows : array();
	}

	/**
	 * Disable a client and revoke its tokens.
	 *
	 * @param string $client_id Client id.
	 */
	public function disable_client( string $client_id ): void {
		if ( '' === $client_id ) {
			return;
		}
		global $wpdb;
		$wpdb->update( Installer::table( 'oauth_clients' ), array( 'disabled' => 1 ), array( 'client_id' => $client_id ) ); // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- Custom table of this plugin.
		$this->tokens->revoke_client( $client_id );
	}

	/**
	 * Is a host a loopback address (RFC 8252 section 7.3)?
	 *
	 * @param string $host Host.
	 */
	private static function is_loopback_host( string $host ): bool {
		return in_array( strtolower( $host ), array( 'localhost', '127.0.0.1', '[::1]', '::1' ), true );
	}

	/**
	 * Does a requested redirect URI match one of the registered ones? Exact
	 * match, except that a loopback http URI may use any port (RFC 8252 section 7.3).
	 *
	 * @param string   $redirect   Requested URI.
	 * @param string[] $registered Registered URIs.
	 */
	public static function redirect_matches( string $redirect, array $registered ): bool {
		$registered = array_filter( $registered, 'is_string' );
		if ( in_array( $redirect, $registered, true ) ) {
			return true;
		}
		$req = wp_parse_url( $redirect );
		if ( ! is_array( $req ) || 'http' !== strtolower( $req['scheme'] ?? '' ) || ! self::is_loopback_host( (string) ( $req['host'] ?? '' ) ) || ! self::redirect_uri_allowed( $redirect ) ) {
			return false;
		}
		foreach ( $registered as $uri ) {
			$reg = wp_parse_url( $uri );
			if ( ! is_array( $reg ) || 'http' !== strtolower( $reg['scheme'] ?? '' ) ) {
				continue;
			}
			if ( strtolower( (string) ( $reg['host'] ?? '' ) ) === strtolower( (string) ( $req['host'] ?? '' ) )
				&& (string) ( $reg['path'] ?? '' ) === (string) ( $req['path'] ?? '' )
				&& (string) ( $reg['query'] ?? '' ) === (string) ( $req['query'] ?? '' ) ) {
				return true;
			}
		}
		return false;
	}

	/**
	 * Redirect URI policy: https, loopback http, or a private-use native scheme
	 * in reverse-domain form (RFC 8252 section 7.1) or of a known MCP client.
	 *
	 * @param string $uri URI.
	 */
	public static function redirect_uri_allowed( string $uri ): bool {
		if ( strlen( $uri ) > 500 || preg_match( '/[\s<>"]/', $uri ) ) {
			return false;
		}
		$parts = wp_parse_url( $uri );
		if ( ! $parts || empty( $parts['scheme'] ) ) {
			return false;
		}
		if ( isset( $parts['fragment'] ) || false !== strpos( $uri, '#' ) || isset( $parts['user'] ) || isset( $parts['pass'] ) ) {
			return false;
		}
		$scheme = strtolower( $parts['scheme'] );
		if ( 'https' === $scheme ) {
			return ! empty( $parts['host'] );
		}
		if ( 'http' === $scheme ) {
			return self::is_loopback_host( (string) ( $parts['host'] ?? '' ) );
		}
		$denied = array( 'javascript', 'data', 'vbscript', 'file', 'mailto', 'tel', 'sms', 'intent', 'jar', 'chrome', 'chrome-extension', 'res', 'about', 'blob', 'ftp', 'ws', 'wss' );
		if ( in_array( $scheme, $denied, true ) || 0 === strpos( $scheme, 'ms-' ) || ! preg_match( '/^[a-z][a-z0-9+.\-]{2,}$/', $scheme ) ) {
			return false;
		}
		// Private-use URI scheme for native apps: reverse domain (com.example.app) or a known MCP client.
		return false !== strpos( $scheme, '.' ) || in_array( $scheme, array( 'cursor', 'vscode', 'vscode-insiders', 'claude', 'windsurf', 'zed', 'raycast' ), true );
	}

	/**
	 * RFC 7591 dynamic client registration.
	 *
	 * @param \WP_REST_Request $request Request.
	 */
	public function rest_register( \WP_REST_Request $request ): \WP_REST_Response {
		if ( ! $this->settings->get( 'oauth_enabled', true ) || ! $this->settings->get( 'dcr_enabled', true ) ) {
			return $this->oauth_error( 'access_denied', 'Dynamic client registration is disabled.', 403 );
		}
		if ( ! $this->limiter->allow( 'dcr:' . Authenticator::client_ip(), 'dcr' ) ) {
			return $this->oauth_error( 'slow_down', 'Too many registrations.', 429 );
		}
		$body = $request->get_json_params();
		if ( ! is_array( $body ) ) {
			$body = $request->get_body_params();
		}
		$uris = isset( $body['redirect_uris'] ) && is_array( $body['redirect_uris'] ) ? array_values( array_filter( $body['redirect_uris'], 'is_string' ) ) : array();
		if ( empty( $uris ) || count( $uris ) > 10 ) {
			return $this->oauth_error( 'invalid_redirect_uri', 'redirect_uris must contain 1-10 URIs.' );
		}
		foreach ( $uris as $uri ) {
			if ( ! self::redirect_uri_allowed( $uri ) ) {
				return $this->oauth_error( 'invalid_redirect_uri', 'Redirect URI not allowed.' );
			}
		}
		// application_type ("native" or "web", sent by MCP 2026-07-28 clients) is
		// accepted and not stored: every client here is public and uses PKCE.
		$method = isset( $body['token_endpoint_auth_method'] ) ? self::str( $body['token_endpoint_auth_method'] ) : 'none';
		if ( 'none' !== $method ) {
			return $this->oauth_error( 'invalid_client_metadata', 'Only public clients (token_endpoint_auth_method=none) with PKCE are supported.' );
		}
		$name      = isset( $body['client_name'] ) ? mb_substr( sanitize_text_field( self::str( $body['client_name'] ) ), 0, 120 ) : 'MCP Client';
		$client_id = 'mcp_' . strtolower( wp_generate_password( 24, false, false ) );
		global $wpdb;
		// Drop self-registered clients that never got a token within an hour, so
		// repeated registrations cannot pile up.
		$ct = Installer::table( 'oauth_clients' );
		$tt = Installer::table( 'tokens' );
		$wpdb->query( $wpdb->prepare( "DELETE c FROM %i c LEFT JOIN %i t ON t.client_id = c.client_id WHERE c.created_via = 'dcr' AND t.id IS NULL AND c.created_at < %s", $ct, $tt, gmdate( 'Y-m-d H:i:s', time() - HOUR_IN_SECONDS ) ) ); // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- custom table cleanup.
		// At the cap, make room by removing the oldest self-registered clients that never got a token,
		// so a flood of registrations cannot lock out real apps.
		if ( ! $this->make_room( 'dcr' ) ) {
			return $this->oauth_error( 'slow_down', 'Too many registered clients. Remove unused ones under Connection.', 429 );
		}
		$wpdb->insert( // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery -- custom table write.
			Installer::table( 'oauth_clients' ),
			array(
				'client_id'     => $client_id,
				'client_name'   => $name ? $name : 'MCP Client',
				'redirect_uris' => wp_json_encode( $uris ),
				'client_uri'    => isset( $body['client_uri'] ) ? esc_url_raw( self::str( $body['client_uri'] ) ) : '',
				'created_at'    => Ids::now(),
				'created_via'   => 'dcr',
			)
		);
		$response = new \WP_REST_Response(
			array(
				'client_id'                  => $client_id,
				'client_id_issued_at'        => time(),
				'client_name'                => $name,
				'redirect_uris'              => $uris,
				'grant_types'                => array( 'authorization_code', 'refresh_token' ),
				'response_types'             => array( 'code' ),
				'token_endpoint_auth_method' => 'none',
			),
			201
		);
		$response->header( 'Cache-Control', 'no-store' );
		return $response;
	}

	/**
	 * Keep at most 499 self-registered clients of one kind (dcr or cimd) by
	 * removing the oldest ones that never got a token.
	 *
	 * @param string $via created_via value.
	 * @return bool False when there is still no room.
	 */
	private function make_room( string $via ): bool {
		global $wpdb;
		$ct   = Installer::table( 'oauth_clients' );
		$tt   = Installer::table( 'tokens' );
		$over = (int) $wpdb->get_var( $wpdb->prepare( 'SELECT COUNT(*) FROM %i WHERE created_via = %s', $ct, $via ) ) - 499; // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- custom table, limit check must be current.
		if ( $over <= 0 ) {
			return true;
		}
		$old = $wpdb->get_col( $wpdb->prepare( 'SELECT c.client_id FROM %i c LEFT JOIN %i t ON t.client_id = c.client_id WHERE c.created_via = %s AND t.id IS NULL ORDER BY c.id ASC LIMIT %d', $ct, $tt, $via, $over ) ); // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- custom table, must be current.
		foreach ( (array) $old as $old_id ) {
			$wpdb->delete( $ct, array( 'client_id' => (string) $old_id ) ); // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- custom table cleanup.
		}
		return count( (array) $old ) >= $over;
	}

	/**
	 * Validate authorize parameters.
	 *
	 * @param array<string, string> $p Params.
	 * @return array<string, mixed>|\WP_Error
	 */
	public function validate_authorize( array $p ) {
		$client = $this->get_client( self::str( $p['client_id'] ?? '' ) );
		if ( ! $client ) {
			return new \WP_Error( 'invalid_client', 'Unknown client.' );
		}
		$registered = json_decode( (string) $client->redirect_uris, true );
		$redirect   = self::str( $p['redirect_uri'] ?? '' );
		if ( ! is_array( $registered ) || ! self::redirect_matches( $redirect, $registered ) ) {
			return new \WP_Error( 'invalid_redirect_uri', 'redirect_uri does not match a registered URI.' );
		}
		// From here on errors can be returned to the client via redirect. For apps that
		// registered themselves this is only done once the user is signed in (see handle_authorize).
		$self_reg = in_array( (string) ( $client->created_via ?? '' ), array( 'dcr', 'cimd' ), true );
		if ( 'code' !== ( $p['response_type'] ?? '' ) ) {
			return new \WP_Error( 'unsupported_response_type', 'Only response_type=code is supported.', array( 'redirect' => $redirect, 'self_registered' => $self_reg ) );
		}
		$challenge = self::str( $p['code_challenge'] ?? '' );
		if ( ! preg_match( '/^[A-Za-z0-9\-._~]{43,128}$/', $challenge ) || 'S256' !== ( $p['code_challenge_method'] ?? '' ) ) {
			return new \WP_Error( 'invalid_request', 'PKCE with code_challenge_method=S256 is required.', array( 'redirect' => $redirect, 'self_registered' => $self_reg ) );
		}
		$resource = self::str( $p['resource'] ?? '' );
		if ( '' !== $resource && untrailingslashit( $resource ) !== untrailingslashit( rest_url( HANDYMCP_REST_NS . '/mcp' ) ) ) {
			return new \WP_Error( 'invalid_target', 'resource must be this site\'s MCP endpoint.', array( 'redirect' => $redirect, 'self_registered' => $self_reg ) );
		}
		$scopes = '' !== self::str( $p['scope'] ?? '' ) ? Scopes::parse( self::str( $p['scope'] ) ) : Scopes::default_oauth();
		if ( empty( $scopes ) ) {
			$scopes = array( 'read' );
		}
		$asked  = $scopes;
		$scopes = Scopes::offer( $scopes );
		if ( empty( $scopes ) ) {
			$scopes = array( 'read' );
		}
		return array(
			'client'    => $client,
			'redirect'  => $redirect,
			'challenge' => $challenge,
			'scopes'    => $scopes,
			'asked'     => $asked,
			'state'     => self::str( $p['state'] ?? '' ),
			'resource'  => self::str( $p['resource'] ?? '' ),
		);
	}

	/**
	 * Authorization endpoint with a WordPress-authenticated consent screen.
	 */
	private function handle_authorize(): void {
		if ( ! defined( 'DONOTCACHEPAGE' ) ) {
			define( 'DONOTCACHEPAGE', true ); // phpcs:ignore WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedConstantFound -- standard constant read by cache plugins.
		}
		nocache_headers();
		self::no_cache_headers();
		header( 'X-Frame-Options: DENY' );
		header( "Content-Security-Policy: frame-ancestors 'none'" );

		if ( ! $this->settings->get( 'oauth_enabled', true ) ) {
			wp_die( esc_html__( 'OAuth is disabled on this site.', 'handymcp' ), 403 );
		}

		$source = 'POST' === sanitize_text_field( wp_unslash( $_SERVER['REQUEST_METHOD'] ?? 'GET' ) ) ? $_POST : $_GET; // phpcs:ignore WordPress.Security.NonceVerification
		$params = array();
		foreach ( array( 'response_type', 'code_challenge', 'code_challenge_method', 'scope' ) as $key ) {
			$params[ $key ] = isset( $source[ $key ] ) && is_string( $source[ $key ] ) ? sanitize_text_field( wp_unslash( $source[ $key ] ) ) : '';
		}
		// state, client_id and resource go back to the client or are compared exactly, so they are kept
		// as sent, but only printable ASCII of a sane length is accepted. Every output escapes them.
		$limits = array( 'state' => 512, 'client_id' => 255, 'resource' => 500 );
		foreach ( $limits as $key => $max ) {
			$value = isset( $source[ $key ] ) && is_string( $source[ $key ] ) ? wp_unslash( $source[ $key ] ) : ''; // phpcs:ignore WordPress.Security.ValidatedSanitizedInput.InputNotSanitized -- validated against printable ASCII below.
			if ( ! preg_match( '/^[\x20-\x7E]{0,' . $max . '}$/D', $value ) ) {
				wp_die( esc_html( sprintf( 'Invalid %s parameter.', $key ) ), esc_html__( 'Authorization error', 'handymcp' ), array( 'response' => 400 ) );
			}
			$params[ $key ] = $value;
		}
		// Redirect URIs must be compared raw, not sanitized.
		$params['redirect_uri'] = isset( $source['redirect_uri'] ) ? trim( wp_unslash( self::str( $source['redirect_uri'] ) ) ) : '';

		$valid = $this->validate_authorize( $params );
		if ( is_wp_error( $valid ) ) {
			$data = $valid->get_error_data();
			// A self-registered app could use the error redirect to bounce visitors anywhere,
			// so before sign-in the error is shown here instead.
			if ( is_array( $data ) && ! empty( $data['redirect'] ) && ( empty( $data['self_registered'] ) || is_user_logged_in() ) ) {
				$this->redirect_to_client( $data['redirect'], array( 'error' => $valid->get_error_code(), 'error_description' => $valid->get_error_message(), 'state' => $params['state'], 'iss' => self::issuer() ) );
			}
			wp_die( esc_html( $valid->get_error_message() ), esc_html__( 'Authorization error', 'handymcp' ), array( 'response' => 400 ) );
		}

		if ( ! is_user_logged_in() ) {
			auth_redirect();
			exit;
		}
		$user = wp_get_current_user();
		if ( ! $this->auth->user_allowed( $user ) ) {
			wp_die( esc_html__( 'Your account is not allowed to authorize MCP clients.', 'handymcp' ), 403 );
		}

		if ( 'POST' === sanitize_text_field( wp_unslash( $_SERVER['REQUEST_METHOD'] ?? 'GET' ) ) ) {
			check_admin_referer( 'handymcp_oauth_consent' );
			$decision = isset( $_POST['decision'] ) ? sanitize_key( wp_unslash( $_POST['decision'] ) ) : 'deny';
			if ( 'approve' !== $decision ) {
				$this->redirect_to_client( $valid['redirect'], array( 'error' => 'access_denied', 'state' => $valid['state'], 'iss' => self::issuer() ) );
			}
			$granted = isset( $_POST['grant_scopes'] ) ? Scopes::sanitize( array_map( 'sanitize_text_field', wp_unslash( (array) $_POST['grant_scopes'] ) ) ) : array( 'read' );
			$granted = array_values( array_intersect( $granted, $valid['scopes'] ) );
			if ( ! in_array( 'read', $granted, true ) ) {
				array_unshift( $granted, 'read' );
			}
			$granted = Scopes::grant( $granted, (array) $valid['asked'] );
			$code = $this->create_code( $valid['client']->client_id, (int) $user->ID, $valid['redirect'], $valid['challenge'], $granted, $valid['resource'] );
			$this->redirect_to_client( $valid['redirect'], array( 'code' => $code, 'state' => $valid['state'], 'iss' => self::issuer() ) );
		}

		$this->render_consent( $valid, $params, $user );
		exit;
	}

	/**
	 * Redirect back to the client with query args.
	 *
	 * @param string               $redirect Redirect URI.
	 * @param array<string,string> $args     Args.
	 */
	private function redirect_to_client( string $redirect, array $args ): void {
		$args = array_filter( $args, static function ( $v ) {
			return '' !== $v && null !== $v;
		} );
		$sep = false === strpos( $redirect, '?' ) ? '?' : '&';
		$url = $redirect . $sep . http_build_query( $args, '', '&', PHP_QUERY_RFC3986 );
		// wp_redirect() (not wp_safe_redirect) because the target is a registered,
		// validated client redirect URI on another host or a native app scheme.
		wp_redirect( $url, 302, 'HandyMCP' ); // phpcs:ignore WordPress.Security.SafeRedirect.wp_redirect_wp_redirect -- validated client redirect URI.
		exit;
	}

	/**
	 * Store an authorization code (hashed) and return the raw value.
	 *
	 * @param string   $client_id  Client.
	 * @param int      $user_id    User.
	 * @param string   $redirect   Redirect URI.
	 * @param string   $challenge  PKCE challenge.
	 * @param string[] $scopes     Scopes.
	 * @param string   $resource   Resource indicator.
	 */
	public function create_code( string $client_id, int $user_id, string $redirect, string $challenge, array $scopes, string $resource = '' ): string {
		global $wpdb;
		$raw = Crypto::random_token( 'code', 24 );
		$wpdb->insert( // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery -- custom table write.
			Installer::table( 'oauth_codes' ),
			array(
				'code_hash'      => Crypto::hash_token( $raw ),
				'client_id'      => $client_id,
				'user_id'        => $user_id,
				'redirect_uri'   => $redirect,
				'code_challenge' => $challenge,
				'scopes'         => implode( ' ', $scopes ),
				'resource'       => mb_substr( $resource, 0, 255 ),
				'created_at'     => Ids::now(),
				'expires_at'     => gmdate( 'Y-m-d H:i:s', time() + 10 * MINUTE_IN_SECONDS ),
			)
		);
		return $raw;
	}

	/**
	 * Token endpoint.
	 *
	 * @param \WP_REST_Request $request Request.
	 */
	public function rest_token( \WP_REST_Request $request ): \WP_REST_Response {
		if ( ! $this->settings->get( 'oauth_enabled', true ) ) {
			return $this->oauth_error( 'access_denied', 'OAuth is disabled.', 403 );
		}
		$p     = array_merge( (array) $request->get_json_params(), (array) $request->get_body_params() );
		if ( isset( $p['client_id'] ) && self::is_cimd( self::str( $p['client_id'] ) ) ) {
			$p['client_id'] = self::cimd_id( self::str( $p['client_id'] ) );
		}
		$grant = self::str( $p['grant_type'] ?? '' );
		// Failed grants are counted per address and client, apart from failed bearer tokens.
		// A request with a valid refresh token is never blocked by someone else's failures.
		$this->grant_key = 'tokenfail:' . hash( 'sha256', Authenticator::client_ip() . '|' . self::str( $p['client_id'] ?? '' ) );
		if ( ! $this->limiter->allow( $this->grant_key, 'auth_fail', false ) ) {
			$rt = 'refresh_token' === $grant ? $this->tokens->find_raw( self::str( $p['refresh_token'] ?? '' ) ) : null;
			if ( ! $rt || 'rt' !== $rt->kind || ! $this->tokens->is_active( $rt ) ) {
				return $this->oauth_error( 'slow_down', 'Too many failed attempts.', 429 );
			}
		}
		if ( 'authorization_code' === $grant ) {
			return $this->grant_code( $p );
		}
		if ( 'refresh_token' === $grant ) {
			return $this->grant_refresh( $p );
		}
		return $this->oauth_error( 'unsupported_grant_type', 'Unsupported grant_type.' );
	}

	/**
	 * Authorization code grant with PKCE verification.
	 *
	 * @param array<string, mixed> $p Params.
	 */
	private function grant_code( array $p ): \WP_REST_Response {
		global $wpdb;
		$raw      = self::str( $p['code'] ?? '' );
		$verifier = self::str( $p['code_verifier'] ?? '' );
		$client   = self::str( $p['client_id'] ?? '' );
		$redirect = self::str( $p['redirect_uri'] ?? '' );
		$table    = Installer::table( 'oauth_codes' );
		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- custom table, auth lookup must not be cached.
		$row = $wpdb->get_row( $wpdb->prepare( 'SELECT * FROM %i WHERE code_hash = %s', $table, Crypto::hash_token( $raw ) ) );
		if ( ! $row ) {
			return $this->grant_fail( 'Invalid authorization code.' );
		}
		if ( ! $this->get_client( (string) $row->client_id ) ) {
			return $this->grant_fail( 'This client is no longer allowed.' );
		}
		if ( (int) $row->used ) {
			// Code replay: revoke the tokens issued from this code (and their refreshed successors) only.
			$this->tokens->revoke_family( self::code_family( (string) $row->code_hash ), 'code_replay' );
			return $this->grant_fail( 'Authorization code already used. Issued tokens were revoked.' );
		}
		// Single use: mark before any other check to win races.
		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- custom table write.
		$claimed = $wpdb->query( $wpdb->prepare( 'UPDATE %i SET used = 1 WHERE id = %d AND used = 0', $table, $row->id ) );
		if ( 1 !== (int) $claimed ) {
			return $this->grant_fail( 'Authorization code already used.' );
		}
		if ( strtotime( $row->expires_at . ' UTC' ) < time() ) {
			return $this->grant_fail( 'Authorization code expired.' );
		}
		if ( ! hash_equals( (string) $row->client_id, $client ) || ! hash_equals( (string) $row->redirect_uri, $redirect ) ) {
			return $this->grant_fail( 'client_id or redirect_uri mismatch.' );
		}
		$resource = self::str( $p['resource'] ?? '' );
		if ( '' !== $resource && untrailingslashit( $resource ) !== untrailingslashit( '' !== (string) $row->resource ? (string) $row->resource : rest_url( HANDYMCP_REST_NS . '/mcp' ) ) ) {
			return $this->grant_fail( 'resource does not match the authorization.' );
		}
		if ( ! preg_match( '/^[A-Za-z0-9\-._~]{43,128}$/', $verifier ) ) {
			return $this->grant_fail( 'Invalid code_verifier.' );
		}
		$computed = rtrim( strtr( base64_encode( hash( 'sha256', $verifier, true ) ), '+/', '-_' ), '=' ); // phpcs:ignore WordPress.PHP.DiscouragedPHPFunctions.obfuscation_base64_encode
		if ( ! hash_equals( (string) $row->code_challenge, $computed ) ) {
			return $this->grant_fail( 'PKCE verification failed.' );
		}
		$user = get_user_by( 'id', (int) $row->user_id );
		if ( ! $user || ! $this->auth->user_allowed( $user ) ) {
			return $this->grant_fail( 'User is no longer allowed.' );
		}
		$scopes = explode( ' ', (string) $row->scopes );
		return $this->issue_pair( (int) $user->ID, $scopes, (string) $row->client_id, self::code_family( (string) $row->code_hash ) );
	}

	/**
	 * Token family of the tokens issued from one authorization code. Derived from
	 * the stored code hash, so a replayed code revokes exactly those tokens.
	 *
	 * @param string $code_hash Stored hash of the code.
	 */
	private static function code_family( string $code_hash ): string {
		return 'code_' . substr( hash( 'sha256', 'family|' . $code_hash ), 0, 40 );
	}

	/**
	 * Refresh grant with rotation and reuse detection.
	 *
	 * @param array<string, mixed> $p Params.
	 */
	private function grant_refresh( array $p ): \WP_REST_Response {
		global $wpdb;
		$raw = self::str( $p['refresh_token'] ?? '' );
		$row = $this->tokens->find_raw( $raw );
		if ( ! $row || 'rt' !== $row->kind ) {
			return $this->grant_fail( 'Invalid refresh token.' );
		}
		// A public client that names itself must be the client the token was issued to.
		if ( ! empty( $p['client_id'] ) && ! hash_equals( (string) $row->client_id, self::str( $p['client_id'] ) ) ) {
			return $this->grant_fail( 'client_id mismatch.' );
		}
		$table = Installer::table( 'tokens' );
		if ( (int) $row->revoked && preg_match( '/^rotated:(\d+)(?::([0-9a-f]{16}))?(?::(n))?$/', (string) $row->revoked_reason, $m ) && time() - (int) $m[1] <= 10 && ( ! empty( $p['client_id'] ) || ( ! empty( $m[2] ) && hash_equals( $m[2], self::ip_tag() ) ) || ( empty( $p['client_id'] ) && 'n' === ( $m[3] ?? '' ) ) ) && ! $this->family_used_since( (string) $row->family, (int) $m[1], (int) $row->id ) && ! $this->tokens->family_hard_revoked( (string) $row->family ) ) {
			// Grace only for the same caller: the client named itself (client_id, already
			// checked against the token above), or the retry comes from the same address,
			// or (marker ":n") the first rotation also came without a client_id and this
			// retry presents the same refresh token without one too. ChatGPT retries from
			// a different address and never sends client_id; all clients here are public
			// (token_endpoint_auth_method=none), so nothing else could identify it.
			// Any other replay falls through and revokes the whole family.
			// Some clients (ChatGPT) retry a refresh with the token they just
			// rotated, e.g. after a network hiccup, and never received the new pair.
			// Inside a short grace window, issue a fresh pair and retire the unused
			// one from the first rotation, so only one chain stays alive.
			if ( ! $this->limiter->allow( 'refresh_retry:' . Authenticator::client_ip(), 'auth_fail' ) ) {
				return $this->oauth_error( 'slow_down', 'Too many refresh retries.', 429 );
			}
			$user = get_user_by( 'id', (int) $row->user_id );
			$same = ! empty( $m[2] ) && hash_equals( $m[2], self::ip_tag() );
			$sent = $this->retry_pair( (int) $row->id );
			if ( $sent && $user && $this->auth->user_allowed( $user ) ) {
				// The client lost the response: send the same pair again. No new token is
				// created, so a stolen refresh token cannot start a chain of its own.
				$wpdb->update( $table, array( 'revoked_reason' => 'rotated_retry' ), array( 'id' => (int) $row->id, 'revoked_reason' => (string) $row->revoked_reason ) ); // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- custom table write.
				delete_transient( 'handymcp_rt_retry_' . (int) $row->id );
				$res = new \WP_REST_Response( $sent );
				$res->header( 'Cache-Control', 'no-store' );
				$res->header( 'Pragma', 'no-cache' );
				return $res;
			}
			if ( $same && $user && $this->auth->user_allowed( $user ) && ( ! $row->client_id || $this->get_client( (string) $row->client_id ) ) ) {
				// Only one retry per token, claimed atomically.
				$claimed = $wpdb->update( $table, array( 'revoked_reason' => 'rotated_retry' ), array( 'id' => (int) $row->id, 'revoked_reason' => (string) $row->revoked_reason ) ); // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- Custom table of this plugin.
				if ( 1 !== (int) $claimed ) {
					return $this->grant_fail( 'Refresh token already used.' );
				}
				$wpdb->query( $wpdb->prepare( 'UPDATE %i SET revoked = 1, revoked_reason = %s, revoked_at = UTC_TIMESTAMP() WHERE family = %s AND id > %d AND revoked = 0', $table, 'superseded_by_retry', (string) $row->family, (int) $row->id ) ); // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- custom table write.
				return $this->issue_pair( (int) $user->ID, explode( ' ', (string) $row->scopes ), (string) $row->client_id, (string) $row->family );
			}
		}
		if ( (int) $row->revoked ) {
			// A rotated token is being replayed: kill the whole family.
			// Disconnects, logouts and resets by the site owner are on purpose: only a replayed renewal is worth a warning.
			$replayed = 0 === strpos( (string) $row->revoked_reason, 'rotated' ) || in_array( (string) $row->revoked_reason, array( 'refresh_replay_detected', 'superseded_by_retry' ), true );
			$this->tokens->revoke_family( (string) $row->family, 'refresh_replay_detected' );
			if ( $replayed ) {
				AppHealth::refused( (string) $row->client_id, 'replay' );
			}
			return $this->grant_fail( 'Refresh token reuse detected. All tokens in this session were revoked.' );
		}
		if ( $row->client_id && ! $this->get_client( (string) $row->client_id ) ) {
			return $this->grant_fail( 'This client is no longer allowed.' );
		}
		if ( ! $this->tokens->is_active( $row ) ) {
			AppHealth::refused( (string) $row->client_id, 'expired' );
			return $this->grant_fail( 'Refresh token expired.' );
		}
		$user = get_user_by( 'id', (int) $row->user_id );
		if ( ! $user || ! $this->auth->user_allowed( $user ) ) {
			$this->tokens->revoke_family( (string) $row->family, 'user_not_allowed' );
			return $this->grant_fail( 'User is no longer allowed.' );
		}
		// Single use, claimed atomically: of two requests with the same token, only one wins.
		// The loser is treated as a replay, so a stolen token used in parallel is detected.
		$claimed = $wpdb->query( $wpdb->prepare( 'UPDATE %i SET revoked = 1, revoked_reason = %s, revoked_at = UTC_TIMESTAMP() WHERE id = %d AND revoked = 0', $table, 'rotated:' . time() . ':' . self::ip_tag() . ( empty( $p['client_id'] ) ? ':n' : '' ), (int) $row->id ) ); // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- custom table write.
		if ( 1 !== (int) $claimed ) {
			$this->tokens->revoke_family( (string) $row->family, 'refresh_replay_detected' );
			AppHealth::refused( (string) $row->client_id, 'replay' );
			return $this->grant_fail( 'Refresh token reuse detected. All tokens in this session were revoked.' );
		}
		$scopes = explode( ' ', (string) $row->scopes );
		if ( ! empty( $p['scope'] ) ) {
			$scopes = array_values( array_intersect( Scopes::parse( self::str( $p['scope'] ) ), $scopes ) );
		}
		$res = $this->issue_pair( (int) $user->ID, $scopes, (string) $row->client_id, (string) $row->family );
		set_transient( 'handymcp_rt_retry_' . (int) $row->id, \HandyMCP\Support\Crypto::encrypt( (string) wp_json_encode( $res->get_data() ) ), 10 );
		return $res;
	}

	/**
	 * The token pair a rotation issued, kept encrypted for the 10 second retry window.
	 *
	 * @param int $id Id of the rotated refresh token.
	 * @return array<string, mixed>|null
	 */
	private function retry_pair( int $id ): ?array {
		$stored = get_transient( 'handymcp_rt_retry_' . $id );
		if ( ! is_string( $stored ) || '' === $stored ) {
			return null;
		}
		$plain = \HandyMCP\Support\Crypto::decrypt( $stored );
		$pair  = null === $plain ? null : json_decode( $plain, true );
		return is_array( $pair ) && ! empty( $pair['access_token'] ) && ! empty( $pair['refresh_token'] ) ? $pair : null;
	}

	/**
	 * Short keyed hash of the caller's address, stored with a rotation so the
	 * retry grace window only applies to the same caller.
	 */
	private static function ip_tag(): string {
		return substr( hash_hmac( 'sha256', Authenticator::client_ip(), wp_salt( 'auth' ) ), 0, 16 );
	}

	/**
	 * Has the family moved on since a rotation? True when a later token of the
	 * family was used for an MCP call or was itself rotated: then a replay of the
	 * old refresh token is not a lost response but an attack.
	 *
	 * @param string $family Family.
	 * @param int    $since  Unix time of the rotation.
	 * @param int    $after  Id of the rotated refresh token.
	 */
	private function family_used_since( string $family, int $since, int $after ): bool {
		global $wpdb;
		$t = Installer::table( 'tokens' );
		return (bool) $wpdb->get_var( $wpdb->prepare( 'SELECT COUNT(*) FROM %i WHERE family = %s AND id > %d AND ( ( use_count > 0 AND last_used_at >= %s ) OR revoked_reason LIKE %s )', $t, $family, $after, gmdate( 'Y-m-d H:i:s', $since ), 'rotated%' ) ); // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- custom table, auth check must not be cached.
	}

	/**
	 * Issue an access + refresh token pair.
	 *
	 * @param int      $user_id   User.
	 * @param string[] $scopes    Scopes.
	 * @param string   $client_id Client.
	 * @param string   $family    Family.
	 */
	private function issue_pair( int $user_id, array $scopes, string $client_id, string $family ): \WP_REST_Response {
		$client = $this->get_client( $client_id );
		$name   = $client ? (string) $client->client_name : $client_id;
		$at     = $this->tokens->issue( 'at', $user_id, $scopes, (int) $this->settings->get( 'access_token_ttl', 3600 ), $name, $client_id, $family );
		$rt     = $this->tokens->issue( 'rt', $user_id, $scopes, (int) $this->settings->get( 'refresh_token_ttl', 30 * DAY_IN_SECONDS ), $name, $client_id, $family );
		AppHealth::clear( $client_id );
		$res    = new \WP_REST_Response(
			array(
				'access_token'  => $at['token'],
				'token_type'    => 'Bearer',
				'expires_in'    => (int) $this->settings->get( 'access_token_ttl', 3600 ),
				'refresh_token' => $rt['token'],
				'scope'         => implode( ' ', Scopes::sanitize( $scopes ) ),
			)
		);
		$res->header( 'Cache-Control', 'no-store' );
		$res->header( 'Pragma', 'no-cache' );
		return $res;
	}

	/**
	 * RFC 7009 revocation (always 200).
	 *
	 * @param \WP_REST_Request $request Request.
	 */
	public function rest_revoke( \WP_REST_Request $request ): \WP_REST_Response {
		if ( ! $this->limiter->allow( 'authfail:' . Authenticator::client_ip(), 'auth_fail', false ) ) {
			return $this->oauth_error( 'slow_down', 'Too many failed attempts.', 429 );
		}
		$p   = array_merge( (array) $request->get_json_params(), (array) $request->get_body_params() );
		$row    = $this->tokens->find_raw( self::str( $p['token'] ?? '' ) );
		$client = isset( $p['client_id'] ) ? self::str( $p['client_id'] ) : '';
		if ( '' !== $client && self::is_cimd( $client ) ) {
			$client = self::cimd_id( $client );
		}
		if ( $row && ( '' === $client || hash_equals( (string) $row->client_id, $client ) ) ) {
			if ( 'rt' === $row->kind ) {
				$this->tokens->revoke_family( (string) $row->family, 'client_revoked' );
			} else {
				$this->tokens->revoke( (int) $row->id, 'client_revoked' );
			}
		}
		return new \WP_REST_Response( array(), 200 );
	}

	/**
	 * invalid_grant with limiter hit.
	 *
	 * @param string $message Message.
	 */
	private function grant_fail( string $message ): \WP_REST_Response {
		$key = '' !== $this->grant_key ? $this->grant_key : 'tokenfail:' . hash( 'sha256', Authenticator::client_ip() . '|' );
		if ( ! $this->limiter->allow( $key, 'auth_fail', false ) ) {
			return $this->oauth_error( 'slow_down', 'Too many failed attempts.', 429 );
		}
		$this->limiter->hit( $key, 'auth_fail' );
		return $this->oauth_error( 'invalid_grant', $message );
	}

	/**
	 * OAuth error body.
	 *
	 * @param string $code    Code.
	 * @param string $message Message.
	 * @param int    $status  HTTP status.
	 */
	private function oauth_error( string $code, string $message, int $status = 400 ): \WP_REST_Response {
		$res = new \WP_REST_Response( array( 'error' => $code, 'error_description' => $message ), $status );
		$res->header( 'Cache-Control', 'no-store' );
		return $res;
	}

	/**
	 * Has this user approved this client before (any token issued to them for it)?
	 * Write permissions start switched off for an app the user has never approved.
	 *
	 * @param int    $user_id   User.
	 * @param string $client_id Client.
	 */
	private function user_approved_client( int $user_id, string $client_id ): bool {
		global $wpdb;
		return (bool) $wpdb->get_var( $wpdb->prepare( 'SELECT id FROM %i WHERE user_id = %d AND client_id = %s LIMIT 1', Installer::table( 'tokens' ), $user_id, $client_id ) ); // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- custom table, must be current.
	}

	/**
	 * Scopes this user has granted this client before.
	 *
	 * @param int    $user_id   User.
	 * @param string $client_id Client.
	 * @return string[]
	 */
	private function user_approved_scopes( int $user_id, string $client_id ): array {
		global $wpdb;
		$rows = $wpdb->get_col( $wpdb->prepare( 'SELECT DISTINCT scopes FROM %i WHERE user_id = %d AND client_id = %s LIMIT 50', Installer::table( 'tokens' ), $user_id, $client_id ) ); // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- custom table, must be current.
		return array_values( array_unique( array_filter( explode( ' ', implode( ' ', (array) $rows ) ) ) ) );
	}

	/**
	 * Consent screen.
	 *
	 * @param array<string, mixed>  $valid  Validated request.
	 * @param array<string, string> $params Raw params (re-posted).
	 * @param \WP_User              $user   Current user.
	 */
	private function render_consent( array $valid, array $params, \WP_User $user ): void {
		$all      = Scopes::all();
		$host     = (string) wp_parse_url( $valid['redirect'], PHP_URL_HOST );
		$site     = get_bloginfo( 'name' );
		$dangers  = array( 'commerce:write', 'forms:write' );
		$approved = $this->user_approved_client( (int) $user->ID, (string) $valid['client']->client_id );
		$prior    = $this->user_approved_scopes( (int) $user->ID, (string) $valid['client']->client_id );
		$self_reg = in_array( (string) $valid['client']->created_via, array( 'dcr', 'cimd' ), true );
		status_header( 200 );
		header( 'Content-Type: text/html; charset=utf-8' );
		?>
<!doctype html>
<html <?php language_attributes(); ?>>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="robots" content="noindex,nofollow">
<title><?php echo esc_html__( 'Authorize MCP client', 'handymcp' ); ?> · <?php echo esc_html( $site ); ?></title>
<?php wp_register_style( 'handymcp-consent', HANDYMCP_URL . 'assets/consent.css', array(), HANDYMCP_VERSION ); wp_print_styles( 'handymcp-consent' ); ?>
</head>
<body class="handymcp-consent">
<main class="card" role="main">
	<?php
	$client_name = (string) $valid['client']->client_name;
	$icon        = get_site_icon_url( 96 );
	?>
	<div class="pair" aria-hidden="true">
		<span class="tile app"><?php echo esc_html( strtoupper( mb_substr( $client_name ? $client_name : 'A', 0, 1 ) ) ); ?></span>
		<span class="link"><i></i><i></i><i></i></span>
		<span class="tile site"><?php if ( $icon ) : ?><img src="<?php echo esc_url( $icon ); ?>" alt=""><?php else : ?><?php echo esc_html( strtoupper( mb_substr( $site, 0, 1 ) ) ); ?><?php endif; ?></span>
	</div>
	<h1>
		<?php
		/* translators: 1: app, 2: site */
		echo esc_html( sprintf( __( 'Connect %1$s to %2$s', 'handymcp' ), $client_name, $site ) );
		?>
	</h1>
	<div class="client-id">
		<?php $verified_host = 'cimd' === (string) $valid['client']->created_via ? (string) wp_parse_url( (string) $valid['client']->client_uri, PHP_URL_HOST ) : ''; ?>
		<?php if ( '' !== $verified_host ) : ?>
			<p class="verified"><?php esc_html_e( 'Verified app identity:', 'handymcp' ); ?> <strong><?php echo esc_html( $verified_host ); ?></strong></p>
		<?php endif; ?>
		<?php if ( $self_reg ) : ?>
			<p class="unverified"><?php esc_html_e( 'Unverified name, provided by the app', 'handymcp' ); ?></p>
		<?php endif; ?>
		<p class="host"><?php esc_html_e( 'After you allow access, you return to:', 'handymcp' ); ?> <strong><?php echo esc_html( '' !== $host ? $host : $valid['redirect'] ); ?></strong></p>
	</div>
	<p class="lead"><?php esc_html_e( 'You are giving an outside AI app access to this site. It will act as you, with your WordPress account, inside the permissions you choose below. Only continue if you started this connection and recognize the address above.', 'handymcp' ); ?></p>

	<div class="account">
		<?php echo wp_kses_post( (string) get_avatar( $user->ID, 36 ) ); ?>
		<div><strong><?php echo esc_html( $user->display_name ); ?></strong><span><?php echo esc_html( $user->user_login ); ?></span></div>
		<a href="<?php echo esc_url( wp_logout_url( add_query_arg( array_map( 'rawurlencode', array_filter( $params, 'strlen' ) ), $this->urls()['authorization_endpoint'] ) ) ); ?>"><?php esc_html_e( 'Not you?', 'handymcp' ); ?></a>
	</div>

	<form method="post" action="">
		<?php wp_nonce_field( 'handymcp_oauth_consent' ); ?>
		<?php foreach ( $params as $k => $v ) : ?>
			<input type="hidden" name="<?php echo esc_attr( $k ); ?>" value="<?php echo esc_attr( $v ); ?>">
		<?php endforeach; ?>
		<fieldset>
			<legend><?php esc_html_e( 'Permissions', 'handymcp' ); ?></legend>
			<?php foreach ( $valid['scopes'] as $scope ) : ?>
				<?php $danger = in_array( $scope, $dangers, true ); ?>
				<label class="perm<?php echo $danger ? ' danger' : ''; ?><?php echo 'read' === $scope ? ' locked' : ''; ?>">
					<span class="txt"><b><?php echo esc_html( Scopes::short( $scope ) ); ?><?php if ( $danger ) : ?> <em><?php esc_html_e( 'Sensitive', 'handymcp' ); ?></em><?php endif; ?><?php if ( 'read' === $scope ) : ?> <em class="req"><?php esc_html_e( 'Required', 'handymcp' ); ?></em><?php endif; ?></b><small><?php echo esc_html( $all[ $scope ] ?? '' ); ?></small></span>
					<span class="sw"><input type="checkbox" name="grant_scopes[]" value="<?php echo esc_attr( $scope ); ?>" <?php checked( 'read' === $scope || ( $approved && ( ! $danger || in_array( $scope, $prior, true ) ) ) ); ?> <?php disabled( 'read' === $scope ); ?>><i></i></span>
					<?php if ( 'read' === $scope ) : ?><input type="hidden" name="grant_scopes[]" value="read"><?php endif; ?>
				</label>
			<?php endforeach; ?>
		</fieldset>
		<details class="more">
			<summary><?php esc_html_e( 'Connection details', 'handymcp' ); ?></summary>
			<dl>
				<div><dt><?php esc_html_e( 'Returns to', 'handymcp' ); ?></dt><dd><?php echo esc_html( $valid['redirect'] ); ?></dd></div>
				<div><dt><?php esc_html_e( 'Registered', 'handymcp' ); ?></dt><dd><?php echo esc_html( ! empty( $valid['client']->created_at ) ? human_time_diff( strtotime( $valid['client']->created_at . ' UTC' ) ) . ' ' . __( 'ago', 'handymcp' ) : '-' ); ?></dd></div>
				<div><dt><?php esc_html_e( 'Client ID', 'handymcp' ); ?></dt><dd><code><?php echo esc_html( $valid['client']->client_id ); ?></code></dd></div>
			</dl>
		</details>
		<div class="actions">
			<button type="submit" name="decision" value="deny" class="btn"><?php esc_html_e( 'Cancel', 'handymcp' ); ?></button>
			<button type="submit" name="decision" value="approve" class="btn primary"><?php esc_html_e( 'Allow access', 'handymcp' ); ?></button>
		</div>
		<p class="note"><?php esc_html_e( 'The app can never do more than your account allows, and anything destructive asks first. You can disconnect it at any time from the WordPress dashboard.', 'handymcp' ); ?></p>
	</form>
</main>
</body>
</html>
		<?php
	}
}