<?php
/**
 * Installation Lockdown.
 *
 * Stops new code arriving: no plugin or theme installed, from the WordPress.org directory or from an
 * uploaded ZIP, and none replaced by uploading a ZIP over it. Updates keep working.
 *
 * Denied in map_meta_cap with do_not_allow rather than in user_has_cap: upload_plugins and
 * upload_themes are meta capabilities core maps to install_plugins / install_themes, so a
 * user_has_cap filter cannot deny them without denying installs too.
 *
 * Multisite super admins are left alone (Shazzad's call, 2026-09-22). On a network only they can
 * install anything, from Network Admin, and the lock is for the people a site is handed to, not the
 * network's owner. has_cap() would let them past everything but do_not_allow, so skipping them here
 * keeps the behaviour 1.7 had by accident, now on purpose.
 *
 * One exception: the plugin details view (plugin-install.php?tab=plugin-information, the "View
 * details" modal core links to from update rows and "Requires:" lines) is gated on install_plugins,
 * so it keeps that capability for that read-only GET request. Links are never hidden (Shazzad's call,
 * 2026-09-22). Installing still fails from there: the Install Now button posts to admin-ajax.php or
 * update.php, a separate request that gets no exception.
 *
 * Update capabilities are deliberately never denied. Without update_plugins / update_themes WordPress
 * hides every pending update — security releases included — and refuses to apply them, which the
 * wordpress.org plugin review team ruled out on 2026-09-14.
 *
 * Deliberately implemented by filtering capabilities rather than by defining DISALLOW_FILE_MODS.
 * The constant is all-or-nothing, cannot be scoped, and — living in wp-config.php — cannot be
 * switched off from the admin, which strands the person who enabled it. This can always be
 * turned back off from the settings screen, which is guarded by manage_options and is never
 * touched by the lockdown.
 *
 * Honest limits, stated in the readme too: this is enforced in PHP. Anyone with filesystem,
 * database or WP-CLI access can bypass it. It guards against accident and casual change. It is
 * not a security boundary.
 *
 * @package Adminkeep
 */

namespace Adminkeep\Feature;

use Adminkeep\Feature;

defined( 'ABSPATH' ) || exit;

/**
 * Capability-level lock on installing and uploading.
 */
class InstallLock implements Feature {

	/**
	 * Capabilities that add something new to the site. The only ones denied while locked.
	 *
	 * @var string[]
	 */
	const ADDITIVE_CAPS = array(
		'install_plugins',
		'upload_plugins',
		'install_themes',
		'upload_themes',
	);

	/**
	 * Feature id.
	 *
	 * @return string
	 */
	public function id() {
		return 'install_lock';
	}

	/**
	 * Label.
	 *
	 * @return string
	 */
	public function label() {
		return __( 'Installation Lockdown', 'adminkeep' );
	}

	/**
	 * Description.
	 *
	 * @return string
	 */
	public function description() {
		return __( 'Stop anyone installing plugins and themes, from WordPress.org or from a ZIP file, or replacing one by uploading a ZIP. Updates keep working, activating what is already installed still works, and you can switch this off again at any time.', 'adminkeep' );
	}

	/**
	 * Settings schema.
	 *
	 * @return array
	 */
	public function settings_schema() {
		return array();
	}

	/**
	 * Field label. Render-time only, so translation is safe here.
	 *
	 * @param string $key Field key.
	 * @return string
	 */
	public function field_label( $key ) {
		return '';
	}

	/**
	 * A word for what this feature is doing right now.
	 *
	 * @return string
	 */
	public function state_label() {
		return __( 'No installs', 'adminkeep' );
	}

	/**
	 * What switching this on actually does. Shown on the settings screen.
	 *
	 * @return string[]
	 */
	public function how_it_works() {
		return array(
			__( 'Denies installing plugins and themes: nothing from the WordPress.org directory, nothing from a ZIP file, and no replacing an installed plugin or theme by uploading one. On a multisite network, super admins are not affected.', 'adminkeep' ),
			__( 'Plugin details ("View details") still open, so you can read a changelog before updating.', 'adminkeep' ),
			__( 'Updates are untouched: update notifications, manual updates and auto-updates all keep working, so security releases still reach the site.', 'adminkeep' ),
			__( 'Activating and deactivating what is already installed still works.', 'adminkeep' ),
			__( 'Always reversible from this screen. It deliberately does not use DISALLOW_FILE_MODS, which lives in wp-config.php and cannot be undone from the admin.', 'adminkeep' ),
			__( 'Enforced in PHP: filesystem, database or WP-CLI access can bypass it. A policy guard against accidents, not a security boundary.', 'adminkeep' ),
		);
	}

	/**
	 * Register hooks.
	 *
	 * @param array $settings Resolved settings.
	 * @return void
	 */
	public function boot( array $settings ) {
		add_filter( 'map_meta_cap', array( $this, 'filter_meta_caps' ), 100, 3 );
	}

	/**
	 * The capabilities this lock denies.
	 *
	 * @return string[]
	 */
	public function denied_caps() {
		return self::ADDITIVE_CAPS;
	}

	/**
	 * Deny the locked capabilities, whoever asks.
	 *
	 * @param string[] $caps    Primitive capabilities the requested one maps to.
	 * @param string   $cap     Requested capability.
	 * @param int      $user_id User the check is for.
	 * @return string[]
	 */
	public function filter_meta_caps( $caps, $cap, $user_id = 0 ) {
		if ( ! in_array( $cap, $this->denied_caps(), true ) ) {
			return $caps;
		}

		if ( is_multisite() && is_super_admin( $user_id ) ) {
			return $caps;
		}

		if ( 'install_plugins' === $cap && $this->is_details_view() ) {
			return $caps;
		}

		return array( 'do_not_allow' );
	}

	/**
	 * Whether this request only displays plugin details.
	 *
	 * @return bool
	 */
	private function is_details_view() {
		global $pagenow;

		if ( ! is_admin() || 'plugin-install.php' !== $pagenow ) {
			return false;
		}

		$method = isset( $_SERVER['REQUEST_METHOD'] ) ? strtoupper( sanitize_key( wp_unslash( $_SERVER['REQUEST_METHOD'] ) ) ) : '';

		// phpcs:ignore WordPress.Security.NonceVerification.Recommended -- Read-only routing check.
		$tab = isset( $_GET['tab'] ) ? sanitize_key( wp_unslash( $_GET['tab'] ) ) : '';

		return 'GET' === $method && 'plugin-information' === $tab;
	}
}