<?php
/**
 * The site's own endpoints, for the browser.
 *
 * @package SharelyAI
 */

namespace SharelyAI;

defined( 'ABSPATH' ) || exit;

/**
 * One route: who this visitor is, as far as Sharely is concerned.
 *
 * The Ask panel streams from the platform directly, because a streamed answer
 * relayed through PHP is a PHP process held open for the length of the answer
 * — on shared hosting that is how a site runs out of workers. So the browser
 * needs a token of its own, and this is where it gets one.
 *
 * What it hands over is deliberately small: a short-lived token carrying the
 * visitor's roles, the space their conversation belongs to, and the two URLs
 * needed to reach the agent. Never the API key, which can read and write the
 * whole workspace and never leaves the server.
 *
 * Uncacheable, and it says so three ways. The search page itself stays fully
 * cacheable because nothing visitor-specific is rendered into it — this one
 * request is the only part that varies per visitor, which is the whole reason
 * it is a separate request.
 */
final class Rest {

	public const NAMESPACE = 'sharelyai/v1';

	/**
	 * How many spaces one unrecognised caller may make us create per window.
	 *
	 * A browser is unrecognised exactly once: it is given a cookie and comes
	 * back with it, and every later call is served from a transient without
	 * touching the platform. Anything still unrecognised on its twenty-first
	 * call inside an hour is not keeping cookies, and each of those calls
	 * creates a user space in the workspace that nobody will ever use again.
	 *
	 * Twenty rather than two because the count is per address, and an office,
	 * a school or a phone network is one address for everybody behind it. The
	 * number is a ceiling on waste, not a guess at honest traffic — and the
	 * filter is there for the site where even this is too tight.
	 */
	private const NEW_VISITORS = 20;

	/**
	 * The window the ceiling applies over, in seconds.
	 */
	private const WINDOW = HOUR_IN_SECONDS;

	/**
	 * Constructor.
	 *
	 * @param Connection $connection Which workspace.
	 */
	public function __construct( private Connection $connection ) {}

	/**
	 * Registers the route.
	 */
	public function register(): void {
		add_action( 'rest_api_init', array( $this, 'routes' ) );
	}

	/**
	 * The routes this plugin serves.
	 */
	public function routes(): void {
		register_rest_route(
			self::NAMESPACE,
			'/token',
			array(
				'methods'             => \WP_REST_Server::READABLE,
				'callback'            => array( $this, 'token' ),
				// Public by design: the Ask panel is for visitors, and a
				// visitor is usually not signed in. The token it returns can
				// only see what this visitor's roles may see.
				'permission_callback' => '__return_true',
			)
		);
	}

	/**
	 * The visitor's identity, or a plain refusal.
	 *
	 * @return \WP_REST_Response
	 */
	public function token(): \WP_REST_Response {
		if ( ! $this->connection->is_connected() || ! (bool) $this->connection->get( 'ask_enabled', true ) ) {
			return self::uncacheable(
				new \WP_REST_Response( array( 'error' => 'ask_unavailable' ), 404 )
			);
		}

		if ( ! $this->recognised() && ! Throttle::allow( 'token', self::limit(), self::WINDOW ) ) {
			// Deliberately the same body as every other refusal. A caller
			// being throttled is told to come back later by the status and
			// the header; it is not told how the limit works.
			$response = new \WP_REST_Response( array( 'error' => 'ask_unavailable' ), 429 );
			$response->header( 'Retry-After', (string) self::WINDOW );
			return self::uncacheable( $response );
		}

		$space = ( new VisitorToken( $this->connection ) )->space();
		if ( ! $space['ok'] ) {
			// The reason is for the log, not for the page: a visitor can do
			// nothing with it, and it names the workspace's internals.
			return self::uncacheable(
				new \WP_REST_Response( array( 'error' => 'ask_unavailable' ), 503 )
			);
		}

		return self::uncacheable(
			new \WP_REST_Response(
				array(
					'workspaceId' => $this->connection->workspace_id(),
					'baseUrl'     => $this->connection->api_base(),
					'token'       => $space['token'],
					'spaceId'     => $space['space_id'],
				),
				200
			)
		);
	}

	/**
	 * Whether we have met this caller before.
	 *
	 * A signed-in visitor is known by their user id, which needs no cookie and
	 * cannot be multiplied by discarding one. Everybody else is known by the
	 * cookie `VisitorToken` sets, and the shape is checked rather than the
	 * mere presence: a cookie of the wrong shape is ignored there too, so a
	 * caller could otherwise send one byte of junk and look familiar.
	 */
	private function recognised(): bool {
		if ( is_user_logged_in() ) {
			return true;
		}

		// phpcs:ignore WordPress.Security.ValidatedSanitizedInput.InputNotValidated -- sanitized here and matched against a fixed charset.
		$cookie = isset( $_COOKIE[ VisitorToken::COOKIE ] ) ? sanitize_text_field( wp_unslash( $_COOKIE[ VisitorToken::COOKIE ] ) ) : '';

		return 1 === preg_match( '/^[a-f0-9]{32}$/', $cookie );
	}

	/**
	 * The ceiling, after the site has had its say.
	 */
	private static function limit(): int {
		/**
		 * Filters how many new visitor spaces one address may create per hour.
		 *
		 * Zero turns the limit off, which is the right setting only where
		 * something in front of WordPress is already doing this job.
		 *
		 * @param int $limit The default ceiling.
		 */
		return (int) apply_filters( 'sharelyai_token_rate_limit', self::NEW_VISITORS );
	}

	/**
	 * Says "do not keep this" to every layer that might.
	 *
	 * A CDN or a page cache that held one visitor's token and served it to the
	 * next would hand them somebody else's roles.
	 *
	 * @param \WP_REST_Response $response The response.
	 */
	private static function uncacheable( \WP_REST_Response $response ): \WP_REST_Response {
		$response->header( 'Cache-Control', 'no-store, no-cache, must-revalidate, private' );
		$response->header( 'Pragma', 'no-cache' );
		$response->header( 'Expires', '0' );
		nocache_headers();
		return $response;
	}
}