<?php
/**
 * Verified private local directories for media drafts and recovery.
 *
 * @package AffStackDevImageManager
 */

namespace AffStackDev\ImageManager;

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

/**
 * Private folders outside the web roots, for media previews and recovery files: created and checked before anything is
 * written.
 */
final class Private_Storage {
	/** Validate a real server path; HTML sanitization must not rewrite filesystem names. */
	private static function web_roots(): array {
		$roots = array( ABSPATH );
        // phpcs:ignore WordPress.Security.ValidatedSanitizedInput.InputNotSanitized -- Type checked, unslashed, then canonicalized by realpath below; never emitted or used for a write.
		$document_root = isset( $_SERVER['DOCUMENT_ROOT'] ) && is_string( $_SERVER['DOCUMENT_ROOT'] ) ? wp_unslash( $_SERVER['DOCUMENT_ROOT'] ) : '';
		if ( '' !== $document_root && ! str_contains( $document_root, "\0" ) ) {
			$roots[] = $document_root;
		}
		$out = array();
		foreach ( $roots as  $root ) {
			$real = realpath( $root );
			if ( false !== $real ) {
				$out[] = rtrim( wp_normalize_path( $real ), '/' );
			}
		}
		return array_unique( $out );
	}

	/**
	 * Refuse a path that is a web root, inside one or above one.
	 *
	 * @param string $path The folder to check.
	 * @throws \RuntimeException With private_storage_web_visible when the path can be reached from the web.
	 */
	private static function outside_web_roots( string $path ): void {
		$path = rtrim( wp_normalize_path( $path ), '/' );
		if ( '' === $path ) {
			throw new \RuntimeException( 'private_storage_web_visible' );
		}
		foreach ( self::web_roots() as  $root ) {
			// Also refuse ancestors: a mistaken setting must not chmod the web root's parent.
			if ( $path === $root || str_starts_with( $path . '/', $root . '/' ) || str_starts_with( $root . '/', $path . '/' ) ) {
				throw new \RuntimeException( 'private_storage_web_visible' );
			}
		}
	}

	/**
	 * No file contents may be written until this returns successfully.
	 *
	 * @param string $base   The private folder's absolute path.
	 * @param bool   $create Whether to create it when it is missing.
	 * @return string The checked folder's path.
	 * @throws \RuntimeException With a reason code as its message when the step cannot be done.
	 */
	public static function directory( string $base, bool $create = true ): string {
		// PHP's Windows chmod flags cannot establish a private Windows ACL.
		if ( '\\' === DIRECTORY_SEPARATOR ) {
			throw new \RuntimeException( 'private_storage_permissions' );
		}
		if ( '' === $base || '/' !== $base[0] || preg_match( '/[\x00-\x1f\x7f]/', $base ) || in_array( '..', explode( '/', $base ), true ) || in_array( '.', explode( '/', $base ), true ) ) {
			throw new \RuntimeException( 'private_storage_path' );
		}
		$base = rtrim( $base, '/' );
		if ( '' === $base || is_link( $base ) ) {
			throw new \RuntimeException( 'private_storage_path' );
		}

		// Resolve the nearest existing parent before creating or chmodding anything.
		$parent = $base;
		$suffix = array();
		while ( ! file_exists( $parent ) && ! is_link( $parent ) ) {
			array_unshift( $suffix, basename( $parent ) );
			$next = dirname( $parent );
			if ( $next === $parent ) {
				throw new \RuntimeException( 'private_storage_path' );
			}
			$parent = $next;
		}
		$real_parent = realpath( $parent );
		if ( false === $real_parent || ! is_dir( $real_parent ) ) {
			throw new \RuntimeException( 'private_storage_path' );
		}
		$expected = rtrim( wp_normalize_path( $real_parent ), '/' ) . ( $suffix ? '/' . implode( '/', $suffix ) : '' );
		self::outside_web_roots( $expected );
		foreach ( array( sys_get_temp_dir(), get_temp_dir() ) as  $temporary_root ) {
			$temporary_real = realpath( $temporary_root );
			if ( false !== $temporary_real && $expected === rtrim( wp_normalize_path( $temporary_real ), '/' ) ) {
				throw new \RuntimeException( 'private_storage_path' );
			}
		}
		if ( ! is_dir( $base ) ) {
            // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_mkdir -- Private local POSIX mode must apply at creation, before any preview or backup bytes exist; no credential prompts in workers.
			if ( ! $create || ( ! @mkdir( $base, 0700, true ) && ! is_dir( $base ) ) ) {
				throw new \RuntimeException( 'private_storage_create_failed' );
			}
		}
		clearstatcache( true, $base );
		$real = realpath( $base );
		if ( is_link( $base ) || false === $real || wp_normalize_path( $real ) !== $expected ) {
			throw new \RuntimeException( 'private_storage_path' );
		}
		self::outside_web_roots( $real );
		if ( function_exists( 'posix_geteuid' ) && fileowner( $real ) !== posix_geteuid() ) {
			throw new \RuntimeException( 'private_storage_permissions' );
		}
		if ( $create ) {
            // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_chmod -- Enforce and verify owner-only local permissions; a remote filesystem abstraction cannot secure OS locks/private local staging.
			if ( ! @chmod( $real, 0700 ) ) {
				throw new \RuntimeException( 'private_storage_permissions' );
			}
		}
		clearstatcache( true, $real );
		$permissions = fileperms( $real );
        // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_is_writable -- This exact local directory is used by native codecs, streams and flock; remote writability is insufficient.
		if ( false === $permissions || 0700 !== ( $permissions & 0777 ) || ! is_writable( $real ) ) {
			throw new \RuntimeException( 'private_storage_permissions' );
		}
		return rtrim( wp_normalize_path( $real ), '/' );
	}

	/**
	 * Move one upload into a private folder through WordPress's own uploader (wp_handle_upload()): its upload filters,
	 * its type check and its move apply, under the name given here. The stored file is then readable by its owner only.
	 *
	 * @param array      $file  One file's upload array (name, type, tmp_name, error, size).
	 * @param string     $dir   A folder directory() checked.
	 * @param string     $name  The stored file's name: sanitized and new in that folder.
	 * @param array|null $mimes The types allowed (extension => MIME type), or null for the site's allowed types.
	 * @return string The stored file's path.
	 * @throws \RuntimeException With private_storage_upload when WordPress refuses the upload or stores it elsewhere.
	 */
	public static function receive_upload( array $file, string $dir, string $name, ?array $mimes = null ): string {
		require_once ABSPATH . 'wp-admin/includes/file.php';
		$dir          = rtrim( wp_normalize_path( $dir ), '/' );
		$file['name'] = $name;
		// Only for this call: WordPress's uploader writes into this private folder and keeps the name chosen here.
		$target = static function ( $uploads ) use ( $dir ) {
			return array_merge(
				(array) $uploads,
				array(
					'path'    => $dir,
					'url'     => '',
					'subdir'  => '',
					'basedir' => $dir,
					'baseurl' => '',
					'error'   => false,
				)
			);
		};
		$named = static function () use ( $name ) {
			return $name;
		};
		add_filter( 'upload_dir', $target, PHP_INT_MAX );
		try {
			$done = wp_handle_upload(
				$file,
				array(
					'test_form'                => false, // The caller checked its own form's nonce.
					'mimes'                    => $mimes,
					'unique_filename_callback' => $named,
				)
			);
		} finally {
			remove_filter( 'upload_dir', $target, PHP_INT_MAX );
		}
		$path = is_array( $done ) && empty( $done['error'] ) && is_string( $done['file'] ?? null ) ? wp_normalize_path( $done['file'] ) : '';
		if ( $dir . '/' . $name !== $path || is_link( $path ) || ! is_file( $path ) ) {
			if ( '' !== $path && ! is_link( $path ) && is_file( $path ) ) {
				wp_delete_file( $path );
			}
			throw new \RuntimeException( 'private_storage_upload' );
		}
		// phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_chmod -- Enforce owner-only local permissions on a private staged file.
		@chmod( $path, 0600 );
		return $path;
	}
}