<?php
/**
 * The API key and secret a Kordiam site authenticates with.
 *
 * @package Kordiam
 */

declare( strict_types=1 );

namespace Kordiam\Auth;

use Kordiam\Contracts\TokenStore;
use Kordiam\Support\Options;

// Exit if accessed directly.
if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * Generates and verifies the long-lived credentials exchanged for access tokens.
 */
final class Credentials {

	/**
	 * Option key holding the API key.
	 *
	 * @var string
	 */
	public const KEY_OPTION = 'api_key';

	/**
	 * Option key holding the API secret.
	 *
	 * @var string
	 */
	public const SECRET_OPTION = 'api_secret';

	/**
	 * Random bytes behind a generated API key.
	 *
	 * @var int
	 */
	private const KEY_BYTES = 16;

	/**
	 * Random bytes behind a generated API secret.
	 *
	 * @var int
	 */
	private const SECRET_BYTES = 32;

	/**
	 * Blocking instantiation: this class is a namespaced function group.
	 */
	private function __construct() {
	}

	/**
	 * Creating credentials if the site has none.
	 *
	 * @return bool Whether a new pair was created.
	 *
	 * @throws \Exception When the system CSPRNG is unavailable.
	 */
	public static function ensure(): bool {
		if ( self::exist() ) {
			return false;
		}

		Options::set( self::KEY_OPTION, self::random( self::KEY_BYTES ) );
		Options::set( self::SECRET_OPTION, self::random( self::SECRET_BYTES ) );

		return true;
	}

	/**
	 * Replacing the credentials with a fresh pair and revoking every access token.
	 *
	 * @param TokenStore|null $tokens Store to revoke through, or null for a default one.
	 *
	 * @throws \Exception When the system CSPRNG is unavailable.
	 */
	public static function regenerate( ?TokenStore $tokens = null ): void {
		Options::set( self::KEY_OPTION, self::random( self::KEY_BYTES ) );
		Options::set( self::SECRET_OPTION, self::random( self::SECRET_BYTES ) );

		$tokens = $tokens ?? new TokenRepository();

		$tokens->revoke_all();
	}

	/**
	 * Getting the stored API key.
	 *
	 * @return string API key, or an empty string when the site has none.
	 */
	public static function key(): string {
		return Options::get_string( self::KEY_OPTION );
	}

	/**
	 * Getting the stored API secret.
	 *
	 * @return string API secret, or an empty string when the site has none.
	 */
	public static function secret(): string {
		return Options::get_string( self::SECRET_OPTION );
	}

	/**
	 * Checking whether the site has a credential pair.
	 *
	 * @return bool Whether both values are present.
	 */
	public static function exist(): bool {
		return '' !== self::key() && '' !== self::secret();
	}

	/**
	 * Verifying a presented key and secret.
	 *
	 * A site without credentials matches nothing (two empty strings would compare equal).
	 * Both comparisons always run, so timing does not reveal which half was wrong.
	 *
	 * @param string $key    Presented API key.
	 * @param string $secret Presented API secret.
	 *
	 * @return bool Whether both match what is stored.
	 */
	public static function match( string $key, string $secret ): bool {
		if ( ! self::exist() ) {
			return false;
		}

		$key_matches    = hash_equals( self::key(), $key );
		$secret_matches = hash_equals( self::secret(), $secret );

		return $key_matches && $secret_matches;
	}

	/**
	 * Generating a random hexadecimal value.
	 *
	 * @param int $bytes Number of random bytes behind the value.
	 *
	 * @return string Lowercase hexadecimal, twice $bytes long.
	 *
	 * @throws \Exception When the system CSPRNG is unavailable.
	 */
	private static function random( int $bytes ): string {
		return bin2hex( random_bytes( $bytes ) );
	}
}