<?php
/**
 * Visitor attachments — stored where the web server will not serve them.
 *
 * WHY THIS CLASS EXISTS, AND WHY IT IS WRITTEN THIS CAREFULLY
 *
 * A picture a visitor sends is **personal data**, and the WordPress Media Library is the wrong place for
 * it: anything under `wp-content/uploads/` is published at a URL that anyone who has the address can
 * open, with no login. A photo of a fault, of a homework sheet or of a person is not something to leave
 * at a public address and then mention in a privacy policy as a footnote.
 *
 * So attachments live in `{uploads}/mybot-private/`, which is:
 *
 *   - **not linked from anywhere** — no Media Library entry, no attachment page, no sitemap;
 *   - **denied by the web server** where the server reads `.htaccess` (Apache), and **unguessable**
 *     everywhere else — every file is named from 16 random bytes, so the only practical way to read one
 *     is the permission-checked route in `mybot/v1/attachment`, which asks for `manage_options`;
 *   - **deleted with the conversation** — the retention job removes the files of the rows it removes,
 *     because a deleted row with a file left behind is exactly the kind of quiet leak this project
 *     records (docs/08 muc 6.31).
 *
 * ⚠️ **Two honest limits, stated here rather than discovered later:**
 *
 *   1. **Nginx does not read `.htaccess`.** On such a host the file is not `403`; it is unguessable, which
 *      is a weaker promise. The plugin cannot configure the web server from inside WordPress, so the
 *      README says this plainly instead of claiming privacy the host does not deliver.
 *   2. The picture is sent **base64 inside the chat request** and never re-published: `url()` does not
 *      exist here on purpose, so no other code can accidentally print a public address for it.
 *
 * @package AI House
 */

defined( 'ABSPATH' ) || exit;

/**
 * Class MYBOT_Attachments
 */
class MYBOT_Attachments {

	/**
	 * Largest accepted picture, in bytes.
	 *
	 * 4 MB is the ceiling AFTER the widget has shrunk the picture (a 1024px JPEG is 150–400 KB). It is a
	 * ceiling for the honest browser, not for a script: the widget's own limit is smaller, and this one
	 * is what stops a hand-made request from filling the disk.
	 *
	 * @var int
	 */
	const MAX_BYTES = 4194304;

	/**
	 * Longest side of the picture the widget prepares, in pixels.
	 *
	 * A phone photo is 3–8 MB and 4000 px wide, and the model is charged for it **by area**: a 1024 px
	 * picture costs roughly 1,000 tokens, a 4000 px one roughly sixteen times that, for detail nobody
	 * asked about. The browser shrinks the picture before it is sent (which is also what keeps a phone
	 * on mobile data from spending a minute uploading), and this number is sent to the widget rather
	 * than written there, so the server's ceiling and the browser's habit cannot drift apart.
	 *
	 * It is NOT a check on the way in: `store()` validates bytes and type, not dimensions, because a
	 * hand-made request with a large but perfectly valid picture should be stored rather than refused.
	 *
	 * @var int
	 */
	const MAX_SIDE = 1024;

	/**
	 * Accepted image types, and the extension each is written with.
	 *
	 * The extension is DERIVED from the detected type, never from the name the browser sent: a
	 * `picture.jpg` that is really a PHP script must not be written as `.jpg` and then, on some future
	 * misconfiguration, be treated as something a server runs.
	 *
	 * @var array
	 */
	const MIMES = array(
		'image/jpeg' => 'jpg',
		'image/png'  => 'png',
		'image/webp' => 'webp',
	);

	/**
	 * The private directory for this site.
	 *
	 * @return string Absolute path, without a trailing slash.
	 */
	public static function dir() {
		$uploads = wp_upload_dir();

		return rtrim( (string) $uploads['basedir'], '/\\' ) . '/mybot-private';
	}

	/**
	 * Creates the directory, and the two files that keep it private.
	 *
	 * @return true|WP_Error
	 */
	public static function ensure() {
		$dir = self::dir();

		if ( ! is_dir( $dir ) && ! wp_mkdir_p( $dir ) ) {
			return new WP_Error(
				'mybot_attach_dir',
				__( 'The folder for visitor pictures could not be created on this server.', 'aihouse' )
			);
		}

		/*
		 * Deny everything, both spellings: `Require` is Apache 2.4 and `Deny` is 2.2. The directives are
		 * wrapped in `<IfModule>` so a host that does not know them does not answer 500 for the whole
		 * directory — a broken `.htaccess` inside uploads can take a site down.
		 */
		$htaccess = $dir . '/.htaccess';

		if ( ! file_exists( $htaccess ) ) {
			$rules = "# AI House: visitor pictures are served only through the plugin's own route.\n"
				. "<IfModule mod_authz_core.c>\n\tRequire all denied\n</IfModule>\n"
				. "<IfModule !mod_authz_core.c>\n\tDeny from all\n</IfModule>\n";

			// phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_file_put_contents
			file_put_contents( $htaccess, $rules );
		}

		$index = $dir . '/index.php';

		if ( ! file_exists( $index ) ) {
			// phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_file_put_contents
			file_put_contents( $index, "<?php\n// Silence is golden.\n" );
		}

		return true;
	}

	/**
	 * Stores one picture that arrived as a data URI.
	 *
	 * @param string $data_uri `data:image/jpeg;base64,…` exactly as the browser produced it.
	 * @return array|WP_Error The stored record, or a WP_Error whose code the widget translates.
	 */
	public static function store( $data_uri ) {
		$data_uri = trim( (string) $data_uri );

		if ( ! preg_match( '#^data:([a-z]+/[a-z0-9.+-]+);base64,(.+)$#is', $data_uri, $matches ) ) {
			return new WP_Error( 'mybot_attach_format', __( 'That picture did not arrive in a form this plugin can read.', 'aihouse' ) );
		}

		$mime = strtolower( $matches[1] );

		if ( ! isset( self::MIMES[ $mime ] ) ) {
			return new WP_Error( 'mybot_attach_type', __( 'Only JPEG, PNG and WebP pictures can be sent.', 'aihouse' ) );
		}

		/*
		 * ⚠️ The ceiling is checked on the STRING before it is decoded (1.18.1).
		 *
		 * `base64_decode()` of a 50 MB payload allocates ~37 MB of memory, and the size check that follows it
		 * would then reject the picture having already paid for it. A public route must not let a stranger
		 * choose how much memory the server spends before the first refusal: base64 is 4 characters for every
		 * 3 bytes, so the string is measured against the ceiling with the padding allowed for, and the exact
		 * check still happens on the bytes afterwards — both, in that order.
		 */
		if ( strlen( $matches[2] ) > (int) ceil( self::MAX_BYTES * 4 / 3 ) + 4 ) {
			return new WP_Error( 'mybot_attach_size', __( 'That picture is too large to send.', 'aihouse' ) );
		}

		// phpcs:ignore WordPress.PHP.DiscouragedPHPFunctions.obfuscation_base64_decode -- a picture to be measured, not code to be run.
		$binary = base64_decode( $matches[2], true );

		if ( false === $binary || '' === $binary ) {
			return new WP_Error( 'mybot_attach_decode', __( 'That picture could not be read.', 'aihouse' ) );
		}

		if ( strlen( $binary ) > self::MAX_BYTES ) {
			return new WP_Error( 'mybot_attach_size', __( 'That picture is too large to send.', 'aihouse' ) );
		}

		/*
		 * Ask the BYTES what they are, not the label that came with them. `getimagesizefromstring()` fails
		 * on anything that is not a real image, which is the only check that matters for a file written to
		 * the disk on the strength of a browser's word.
		 */
		$size = @getimagesizefromstring( $binary ); // phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged

		if ( ! is_array( $size ) || empty( $size[0] ) || empty( $size[1] ) ) {
			return new WP_Error( 'mybot_attach_not_image', __( 'That file is not a picture this plugin can read.', 'aihouse' ) );
		}

		$ready = self::ensure();

		if ( is_wp_error( $ready ) ) {
			return $ready;
		}

		try {
			$name = bin2hex( random_bytes( 16 ) ) . '.' . self::MIMES[ $mime ];
		} catch ( Exception $e ) {
			// random_bytes needs a working source of randomness; without one there is no safe name.
			return new WP_Error( 'mybot_attach_random', __( 'This server could not produce a safe file name for the picture.', 'aihouse' ) );
		}

		// phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_file_put_contents
		$written = file_put_contents( self::dir() . '/' . $name, $binary, LOCK_EX );

		if ( false === $written ) {
			return new WP_Error( 'mybot_attach_write', __( 'The picture could not be saved on this server.', 'aihouse' ) );
		}

		return array(
			'kind'   => 'image',
			'file'   => $name,
			'mime'   => $mime,
			'bytes'  => strlen( $binary ),
			'width'  => (int) $size[0],
			'height' => (int) $size[1],
		);
	}

	/**
	 * The absolute path of a stored file, or '' when the name is not one this class writes.
	 *
	 * The name is validated rather than trusted: it arrives from a database column that a filter or a
	 * migration could have written, and `../` in it would reach the whole filesystem.
	 *
	 * @param string $file Stored file name.
	 * @return string
	 */
	public static function path( $file ) {
		$file = (string) $file;

		if ( ! preg_match( '/^[a-f0-9]{32}\.(jpg|png|webp)$/', $file ) ) {
			return '';
		}

		return self::dir() . '/' . $file;
	}

	/**
	 * One attachment of a row, by position, with its record validated (1.14.0).
	 *
	 * The `index` a screen sends is a small integer that could be anything, so it is looked up rather
	 * than used: an index that does not exist answers an empty array, and the file name it returns has
	 * been through `path()` — which means it is a name this class writes, not a name somebody sent.
	 *
	 * @param string $json  Stored value.
	 * @param int    $index Position in the row's list.
	 * @return array The record, or array() when there is nothing at that position.
	 */
	public static function record( $json, $index ) {
		$records = self::from_json( $json );
		$index   = absint( $index );

		if ( ! isset( $records[ $index ] ) || ! is_array( $records[ $index ] ) ) {
			return array();
		}

		$record = $records[ $index ];
		$file   = isset( $record['file'] ) ? (string) $record['file'] : '';

		if ( '' === self::path( $file ) ) {
			return array();
		}

		return array(
			'kind'   => isset( $record['kind'] ) ? (string) $record['kind'] : 'image',
			'file'   => $file,
			'mime'   => isset( $record['mime'] ) ? (string) $record['mime'] : 'application/octet-stream',
			'bytes'  => isset( $record['bytes'] ) ? (int) $record['bytes'] : 0,
			'width'  => isset( $record['width'] ) ? (int) $record['width'] : 0,
			'height' => isset( $record['height'] ) ? (int) $record['height'] : 0,
		);
	}

	/**
	 * Encodes records for the `attachments` column.
	 *
	 * @param array $records Records.
	 * @return string JSON, or '' when there is nothing.
	 */
	public static function to_json( $records ) {
		$records = array_values( array_filter( (array) $records, 'is_array' ) );

		if ( empty( $records ) ) {
			return '';
		}

		return (string) wp_json_encode( $records );
	}

	/**
	 * Decodes the `attachments` column.
	 *
	 * @param string $json Stored value.
	 * @return array
	 */
	public static function from_json( $json ) {
		$decoded = json_decode( (string) $json, true );

		return is_array( $decoded ) ? array_values( array_filter( $decoded, 'is_array' ) ) : array();
	}

	/**
	 * Deletes the files behind one row's attachments.
	 *
	 * @param string $json Stored value.
	 * @return int Number of files removed.
	 */
	public static function delete_json( $json ) {
		$removed = 0;

		foreach ( self::from_json( $json ) as $record ) {
			$path = self::path( isset( $record['file'] ) ? (string) $record['file'] : '' );

			if ( '' !== $path && file_exists( $path ) ) {
				// phpcs:ignore WordPress.WP.AlternativeFunctions.unlink_unlink
				if ( unlink( $path ) ) {
					++$removed;
				}
			}
		}

		return $removed;
	}

	/**
	 * What the admin screens may show about one row's attachments — never the file name.
	 *
	 * The name is deliberately dropped: the only reader of a picture is the permission-checked route, and
	 * a name that travels into a screen, a log line or the Supabase mirror is a locator that no longer
	 * needs the permission check to be useful.
	 *
	 * @param string $json Stored value.
	 * @return array
	 */
	public static function describe( $json ) {
		$out = array();

		foreach ( self::from_json( $json ) as $index => $record ) {
			$out[] = array(
				'index'  => (int) $index,
				'kind'   => isset( $record['kind'] ) ? (string) $record['kind'] : 'image',
				'mime'   => isset( $record['mime'] ) ? (string) $record['mime'] : '',
				'bytes'  => isset( $record['bytes'] ) ? (int) $record['bytes'] : 0,
				'width'  => isset( $record['width'] ) ? (int) $record['width'] : 0,
				'height' => isset( $record['height'] ) ? (int) $record['height'] : 0,
			);
		}

		return $out;
	}
}