<?php
/**
 * Audio Validator
 *
 * Checks an uploaded voice clip before anything else touches it.
 *
 * @package Aisentic\Voice
 */

declare( strict_types = 1 );

namespace Aisentic\Voice;

use WP_Error;

defined( 'ABSPATH' ) || exit;

/**
 * Validates an uploaded audio clip.
 *
 * All checks read the file on disk. They never trust the file name or the
 * Content-Type the browser sent.
 * Why: a fake file can attack the site, and a large file costs credits.
 */
class Audio_Validator {

	/**
	 * Media types we accept, as finfo reports them.
	 *
	 * These are the types the browser recorder (MediaRecorder) makes in
	 * Chrome, Firefox and Safari. application/octet-stream is also allowed,
	 * because finfo reports it for some valid short clips. The magic-byte
	 * check (first bytes of the file) has already passed by then.
	 *
	 * @var string[]
	 */
	private const ALLOWED_MIMES = [
		'audio/webm',
		'video/webm', // Chrome labels audio-only WebM this way.
		'audio/ogg',
		'application/ogg',
		'audio/mp4',
		'audio/x-m4a',
		'video/mp4', // Safari records audio into an MP4 container.
		'audio/mpeg',
		'audio/wav',
		'audio/x-wav',
		'audio/wave',
		'application/octet-stream',
	];

	/**
	 * First bytes that prove a real container, keyed by a readable label.
	 *
	 * @var array<string,string>
	 */
	private const MAGIC = [
		'webm' => "\x1A\x45\xDF\xA3", // EBML (WebM / Matroska).
		'ogg'  => 'OggS',
		'riff' => 'RIFF',             // WAV.
		'id3'  => 'ID3',              // MP3 with tags.
	];

	/**
	 * Settings instance.
	 *
	 * @var object
	 */
	private $settings;

	/**
	 * Constructor.
	 *
	 * @param object $settings Settings instance.
	 */
	public function __construct( $settings ) {
		$this->settings = $settings;
	}

	/**
	 * Validate one uploaded file.
	 *
	 * @param array|null $file One entry from $_FILES.
	 * @return true|WP_Error True when the clip is safe to use.
	 */
	public function validate( $file ) {
		if ( ! is_array( $file ) || empty( $file['tmp_name'] ) ) {
			return new WP_Error( 'aisentic_voice_no_file', __( 'No audio was received.', 'aisentic' ), [ 'status' => 400 ] );
		}

		if ( isset( $file['error'] ) && UPLOAD_ERR_OK !== (int) $file['error'] ) {
			return new WP_Error( 'aisentic_voice_upload_error', __( 'The audio did not upload correctly.', 'aisentic' ), [ 'status' => 400 ] );
		}

		$path = (string) $file['tmp_name'];

		// Must be a genuine PHP upload, not an arbitrary server path handed to us.
		if ( ! $this->is_real_upload( $path ) ) {
			return new WP_Error( 'aisentic_voice_not_upload', __( 'That file was not uploaded.', 'aisentic' ), [ 'status' => 400 ] );
		}

		if ( ! is_readable( $path ) ) {
			return new WP_Error( 'aisentic_voice_unreadable', __( 'The audio could not be read.', 'aisentic' ), [ 'status' => 400 ] );
		}

		$size = (int) filesize( $path );

		if ( $size <= 0 ) {
			return new WP_Error( 'aisentic_voice_empty', __( 'The audio file is empty.', 'aisentic' ), [ 'status' => 400 ] );
		}

		$max_bytes = (int) $this->settings->get( 'voice.maxUploadBytes', 5242880 );

		if ( $size > $max_bytes ) {
			return new WP_Error(
				'aisentic_voice_too_large',
				sprintf(
					/* translators: %d: maximum size in megabytes. */
					__( 'The recording is too long. Keep it under %d MB.', 'aisentic' ),
					(int) round( $max_bytes / 1048576 )
				),
				[ 'status' => 400 ]
			);
		}

		// The first bytes of the file (magic bytes) are the main check.
		// Why: finfo says application/octet-stream for some valid short WebM
		// clips, so finfo alone would reject real recordings.
		if ( ! $this->has_audio_magic( $path ) ) {
			return new WP_Error(
				'aisentic_voice_bad_header',
				__( 'That file is not audio.', 'aisentic' ),
				[ 'status' => 400 ]
			);
		}

		// Reject audio that also has script code inside (a "polyglot" file).
		// Today the clip is deleted after the turn and is never public, so it
		// cannot run. This check keeps it safe if storage changes later.
		if ( $this->has_script_payload( $path ) ) {
			return new WP_Error(
				'aisentic_voice_script_payload',
				__( 'That file is not audio.', 'aisentic' ),
				[ 'status' => 400 ]
			);
		}

		// finfo is a second check. If finfo finds a type not in ALLOWED_MIMES,
		// reject the file. An empty result means finfo is missing, so we
		// rely on the magic-byte check only.
		$detected = $this->detect_mime( $path );

		if ( '' !== $detected && ! in_array( $detected, self::ALLOWED_MIMES, true ) ) {
			return new WP_Error(
				'aisentic_voice_bad_type',
				__( 'That file is not audio.', 'aisentic' ),
				[
					'status'   => 400,
					'detected' => $detected,
				]
			);
		}

		return true;
	}

	/**
	 * Look for script markers in the first part of the file.
	 *
	 * @param string $path Absolute path.
	 * @return bool True when the clip carries script source.
	 */
	private function has_script_payload( string $path ): bool {
		$handle = fopen( $path, 'rb' ); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_fopen -- Reading an upload before WP touches it.
		if ( false === $handle ) {
			return true; // Cannot read it, so do not trust it.
		}

		$head = (string) fread( $handle, 4096 ); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_fread -- See above.
		fclose( $handle ); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_fclose -- See above.

		foreach ( [ '<?php', '<?=', '<script', '#!/' ] as $marker ) {
			if ( false !== stripos( $head, $marker ) ) {
				return true;
			}
		}

		return false;
	}

	/**
	 * Is this a file PHP received as an upload in this request?
	 *
	 * A separate method so a test can replace it.
	 *
	 * @param string $path Absolute path.
	 * @return bool
	 */
	protected function is_real_upload( string $path ): bool {
		return is_uploaded_file( $path );
	}

	/**
	 * Read the media type from the file contents.
	 *
	 * @param string $path Absolute path.
	 * @return string Detected media type, or an empty string.
	 */
	protected function detect_mime( string $path ): string {
		if ( function_exists( 'finfo_open' ) ) {
			$finfo = finfo_open( FILEINFO_MIME_TYPE );
			if ( false !== $finfo ) {
				$mime = finfo_file( $finfo, $path );
				finfo_close( $finfo );
				if ( is_string( $mime ) && '' !== $mime ) {
					return strtolower( $mime );
				}
			}
		}

		// finfo is missing. Return empty. validate() still has the magic-byte
		// check.
		return '';
	}

	/**
	 * Check the first bytes match a container we accept.
	 *
	 * @param string $path Absolute path.
	 * @return bool
	 */
	private function has_audio_magic( string $path ): bool {
		$handle = fopen( $path, 'rb' ); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_fopen -- Reading an upload before WP touches it.
		if ( false === $handle ) {
			return false;
		}

		$head = (string) fread( $handle, 12 ); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_fread -- See above.
		fclose( $handle ); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_fclose -- See above.

		foreach ( self::MAGIC as $kind => $bytes ) {
			if ( 0 !== strncmp( $head, $bytes, strlen( $bytes ) ) ) {
				continue;
			}

			// RIFF is also AVI, WebP and others. Only RIFF....WAVE is audio.
			if ( 'riff' === $kind ) {
				return 'WAVE' === substr( $head, 8, 4 );
			}

			return true;
		}

		// MP4/M4A: bytes 4-8 are 'ftyp'.
		if ( 'ftyp' === substr( $head, 4, 4 ) ) {
			return true;
		}

		// Bare MP3 frame sync.
		if ( strlen( $head ) > 1 && "\xFF" === $head[0] && ( ord( $head[1] ) & 0xE0 ) === 0xE0 ) {
			return true;
		}

		return false;
	}
}