<?php
/**
 * Base class every individual security check extends.
 *
 * @package AardwolfSecurityScanner
 */

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

/**
 * Class Aardwolf_Check.
 *
 * Concrete checks implement run() and return an Aardwolf_Check_Result. The
 * helper factory methods keep result construction terse and consistent.
 */
abstract class Aardwolf_Check {

	/**
	 * Unique identifier for the check (used as a key, so keep it stable).
	 *
	 * @return string
	 */
	abstract public function id();

	/**
	 * Human readable label.
	 *
	 * @return string
	 */
	abstract public function label();

	/**
	 * Category the check belongs to (used to group the report).
	 *
	 * @return string
	 */
	abstract public function category();

	/**
	 * Execute the check.
	 *
	 * @return Aardwolf_Check_Result
	 */
	abstract public function run();

	/**
	 * Title to show when the check fails or warns. The default label() is
	 * phrased as the healthy/passing state (e.g. "Usernames are not publicly
	 * enumerable"), which reads as a contradiction next to a red failure. Checks
	 * override this to state the actual problem (e.g. "Usernames are publicly
	 * enumerable"). Falls back to label() when not overridden.
	 *
	 * @return string
	 */
	public function problem_label() {
		$map = array(
			'core_update'         => __( 'WordPress core is out of date', 'aardwolf-security-scanner' ),
			'plugin_updates'      => __( 'Plugins need updating', 'aardwolf-security-scanner' ),
			'theme_updates'       => __( 'Themes need updating', 'aardwolf-security-scanner' ),
			'unused_extensions'   => __( 'Dormant (inactive) plugins or themes are present', 'aardwolf-security-scanner' ),
			'admin_username'      => __( 'A default "admin" account exists', 'aardwolf-security-scanner' ),
			'user_enumeration'    => __( 'Usernames are publicly enumerable', 'aardwolf-security-scanner' ),
			'open_registration'   => __( 'Registration can create over-privileged accounts', 'aardwolf-security-scanner' ),
			'login_protection'    => __( 'No login brute-force protection detected', 'aardwolf-security-scanner' ),
			'file_editor'         => __( 'The dashboard file editor is enabled', 'aardwolf-security-scanner' ),
			'debug_mode'          => __( 'Debug output may be exposed', 'aardwolf-security-scanner' ),
			'security_keys'       => __( 'Secret keys and salts are weak or missing', 'aardwolf-security-scanner' ),
			'table_prefix'        => __( 'The default database table prefix is in use', 'aardwolf-security-scanner' ),
			'force_ssl_admin'     => __( 'Admin and login are not forced over HTTPS', 'aardwolf-security-scanner' ),
			'file_permissions'    => __( 'Critical file permissions are too permissive', 'aardwolf-security-scanner' ),
			'xmlrpc'              => __( 'XML-RPC is exposed', 'aardwolf-security-scanner' ),
			'readme_exposed'      => __( 'The version-leaking readme.html is public', 'aardwolf-security-scanner' ),
			'version_disclosure'  => __( 'The WordPress version is publicly advertised', 'aardwolf-security-scanner' ),
			'directory_listing'   => __( 'Directory browsing is enabled', 'aardwolf-security-scanner' ),
			'sensitive_files'     => __( 'Sensitive files are exposed at the web root', 'aardwolf-security-scanner' ),
			'https'               => __( 'The site is not served over HTTPS', 'aardwolf-security-scanner' ),
			'php_version'         => __( 'The PHP version is outdated or unsupported', 'aardwolf-security-scanner' ),
			'security_headers'    => __( 'Recommended security headers are missing', 'aardwolf-security-scanner' ),
			'vulnerable_plugins'  => __( 'An installed plugin has been removed from the directory', 'aardwolf-security-scanner' ),
		);

		return isset( $map[ $this->id() ] ) ? $map[ $this->id() ] : $this->label();
	}

	// -------------------------------------------------------------------------
	// Result factory helpers.
	// -------------------------------------------------------------------------

	/**
	 * Build a passing result.
	 *
	 * @param string $summary Explanation of what was verified.
	 * @return Aardwolf_Check_Result
	 */
	protected function pass( $summary ) {
		return new Aardwolf_Check_Result(
			array(
				'id'       => $this->id(),
				'label'    => $this->label(),
				'category' => $this->category(),
				'status'   => Aardwolf_Check_Result::STATUS_PASS,
				'severity' => Aardwolf_Check_Result::SEVERITY_INFO,
				'summary'  => $summary,
			)
		);
	}

	/**
	 * Build a warning result.
	 *
	 * @param string $severity    Severity constant.
	 * @param string $summary     What was found.
	 * @param string $remediation How to fix it.
	 * @param string $reference   Optional URL.
	 * @return Aardwolf_Check_Result
	 */
	protected function warn( $severity, $summary, $remediation, $reference = '' ) {
		return new Aardwolf_Check_Result(
			array(
				'id'          => $this->id(),
				'label'       => $this->problem_label(),
				'category'    => $this->category(),
				'status'      => Aardwolf_Check_Result::STATUS_WARN,
				'severity'    => $severity,
				'summary'     => $summary,
				'remediation' => $remediation,
				'reference'   => $reference,
			)
		);
	}

	/**
	 * Build a failing result.
	 *
	 * @param string $severity    Severity constant.
	 * @param string $summary     What was found.
	 * @param string $remediation How to fix it.
	 * @param string $reference   Optional URL.
	 * @return Aardwolf_Check_Result
	 */
	protected function fail( $severity, $summary, $remediation, $reference = '' ) {
		return new Aardwolf_Check_Result(
			array(
				'id'          => $this->id(),
				'label'       => $this->problem_label(),
				'category'    => $this->category(),
				'status'      => Aardwolf_Check_Result::STATUS_FAIL,
				'severity'    => $severity,
				'summary'     => $summary,
				'remediation' => $remediation,
				'reference'   => $reference,
			)
		);
	}

	/**
	 * Build an informational result (neither pass nor problem).
	 *
	 * @param string $summary     What was found.
	 * @param string $remediation Optional guidance.
	 * @return Aardwolf_Check_Result
	 */
	protected function info( $summary, $remediation = '' ) {
		return new Aardwolf_Check_Result(
			array(
				'id'          => $this->id(),
				'label'       => $this->label(),
				'category'    => $this->category(),
				'status'      => Aardwolf_Check_Result::STATUS_INFO,
				'severity'    => Aardwolf_Check_Result::SEVERITY_INFO,
				'summary'     => $summary,
				'remediation' => $remediation,
			)
		);
	}

	/**
	 * Perform a lightweight self-request to the site and return the response.
	 * Shared by checks that need to inspect HTTP responses (headers, exposed
	 * files, etc.). Loopback requests are used so the check works even on
	 * sites that are not publicly reachable yet.
	 *
	 * @param string $path Relative path (e.g. '/readme.html').
	 * @param array  $args Optional wp_remote_get() args.
	 * @return array|WP_Error Response array or error.
	 */
	protected function request( $path = '/', $args = array() ) {
		$url = home_url( $path );

		$defaults = array(
			'timeout'     => 10,
			'redirection' => 0,
			// Do not fail the whole scan on a self-signed cert during testing.
			'sslverify'   => apply_filters( 'aardwolf_sc_sslverify', true ),
			'headers'     => array(
				'User-Agent' => 'Aardwolf-Security-Scanner/' . AARDWOLF_SC_VERSION,
			),
		);

		return wp_remote_get( $url, array_merge( $defaults, $args ) );
	}
}