<?php
/**
 * EquaSign cryptography: master key (KEK), encryption at rest, hashes,
 * opaque tokens, constant-time comparison.
 *
 * Principles:
 *  - The KEK is read from wp-config.php (EQUASIGN_KEK constant). When absent,
 *    the vault is unavailable: we refuse to encrypt, never a silent throwaway
 *    key. The KEK must never be lost or changed after the first encryption
 *    (otherwise data at rest becomes unreadable).
 *  - Authenticated encryption: AES-256-GCM if the CPU exposes it (sodium),
 *    otherwise XChaCha20-Poly1305-IETF. The algorithm used is recorded in a
 *    one-byte header at the start of the blob, for deterministic decryption.
 *
 * @package EquaSign
 */

defined( 'ABSPATH' ) || exit;

class EquaSign_Crypto {

	/** Algorithm header: AES-256-GCM. */
	const ALGO_AES = "\x01";

	/** Algorithm header: XChaCha20-Poly1305-IETF. */
	const ALGO_XCHACHA = "\x02";

	/** Key derivation context (BLAKE2b), frozen. */
	const KDF_CONTEXT = 'equasign-kek-v1';

	/**
	 * Is the KEK present in configuration?
	 *
	 * @return bool
	 */
	public static function kek_present() {
		return defined( 'EQUASIGN_KEK' ) && is_string( EQUASIGN_KEK ) && '' !== trim( EQUASIGN_KEK );
	}

	/**
	 * 32-byte symmetric key derived from the wp-config KEK, in a stable way.
	 *
	 * We derive (BLAKE2b) rather than requiring a precise format: any
	 * sufficiently strong secret string yields a reproducible 32-byte key.
	 *
	 * @return string 32 raw bytes.
	 * @throws RuntimeException If the KEK is absent.
	 */
	private static function key() {
		if ( ! self::kek_present() ) {
			throw new RuntimeException( 'EQUASIGN_KEK missing: vault unavailable.' );
		}
		return sodium_crypto_generichash( self::KDF_CONTEXT . '|' . EQUASIGN_KEK, '', 32 );
	}

	/**
	 * Is AES-256-GCM available on this platform?
	 *
	 * @return bool
	 */
	private static function aes_available() {
		return function_exists( 'sodium_crypto_aead_aes256gcm_is_available' )
			&& sodium_crypto_aead_aes256gcm_is_available();
	}

	/**
	 * Whether a real, working secure memory wipe is available.
	 *
	 * sodium_memzero() is the ONE primitive WordPress's bundled sodium_compat polyfill
	 * refuses to implement: on a host WITHOUT the native ext-sodium it throws SodiumException
	 * by design (identical on WP 6.0 and 7.0). Every other primitive EquaSign uses (BLAKE2b
	 * KDF, AES-256-GCM, XChaCha20-Poly1305, Ed25519) works under the polyfill. We probe once
	 * — function_exists() is not enough because the polyfill DEFINES sodium_memzero() and then
	 * throws — and cache the result.
	 *
	 * @return bool
	 */
	public static function secure_wipe_available() {
		static $ok = null;
		if ( null === $ok ) {
			if ( ! function_exists( 'sodium_memzero' ) ) {
				$ok = false;
			} else {
				$probe = 'x';
				try {
					sodium_memzero( $probe );
					$ok = true;
				} catch ( \Throwable $e ) {
					$ok = false;
				}
			}
		}
		return $ok;
	}

	/**
	 * Best-effort secure wipe of a sensitive value (defence in depth), passed by reference.
	 *
	 * Wiping is NOT a property of the seal or of the encryption: the sealed dossier and the
	 * encrypted blob are exactly as valid whether or not the wipe ran. So on a polyfill-only
	 * host (no ext-sodium) we degrade to a plain overwrite instead of letting SodiumException
	 * escape the crypto path (which previously surfaced as a misleading "vault unavailable").
	 * The operator is told via an admin notice — this is a silent no-op at the CODE level, not
	 * a silent degradation. Encrypted-data format is unchanged; no migration.
	 *
	 * @param string $ref Sensitive value; zeroed in place when possible, else overwritten.
	 * @return void
	 */
	public static function wipe( &$ref ) {
		if ( self::secure_wipe_available() ) {
			try {
				sodium_memzero( $ref );
				return;
			} catch ( \Throwable $e ) {
				// Fall through to the plain overwrite; never surface the exception.
				$ok = null;
			}
		}
		if ( is_string( $ref ) ) {
			$ref = str_repeat( "\0", strlen( $ref ) );
		}
		$ref = '';
	}

	/**
	 * Encrypts data for storage at rest.
	 *
	 * Blob format: [1 algo byte][nonce][ciphertext+tag].
	 *
	 * @param string $plaintext Plaintext data (binary accepted).
	 * @return string Encrypted blob (binary).
	 * @throws RuntimeException If the KEK is absent.
	 */
	public static function encrypt( $plaintext ) {
		$key = self::key();

		if ( self::aes_available() ) {
			$nonce      = random_bytes( SODIUM_CRYPTO_AEAD_AES256GCM_NPUBBYTES );
			$ciphertext = sodium_crypto_aead_aes256gcm_encrypt( $plaintext, '', $nonce, $key );
			$blob       = self::ALGO_AES . $nonce . $ciphertext;
		} else {
			$nonce      = random_bytes( SODIUM_CRYPTO_AEAD_XCHACHA20POLY1305_IETF_NPUBBYTES );
			$ciphertext = sodium_crypto_aead_xchacha20poly1305_ietf_encrypt( $plaintext, '', $nonce, $key );
			$blob       = self::ALGO_XCHACHA . $nonce . $ciphertext;
		}

		self::wipe( $key );
		return $blob;
	}

	/**
	 * Decrypts a blob produced by encrypt().
	 *
	 * @param string $blob Encrypted blob.
	 * @return string|false Plaintext data, or false on failure/tampering.
	 * @throws RuntimeException If the KEK is absent.
	 */
	public static function decrypt( $blob ) {
		if ( ! is_string( $blob ) || strlen( $blob ) < 2 ) {
			return false;
		}
		$key  = self::key();
		$algo = $blob[0];

		try {
			if ( self::ALGO_AES === $algo ) {
				$n          = SODIUM_CRYPTO_AEAD_AES256GCM_NPUBBYTES;
				$nonce      = substr( $blob, 1, $n );
				$ciphertext = substr( $blob, 1 + $n );
				$plaintext  = sodium_crypto_aead_aes256gcm_decrypt( $ciphertext, '', $nonce, $key );
			} elseif ( self::ALGO_XCHACHA === $algo ) {
				$n          = SODIUM_CRYPTO_AEAD_XCHACHA20POLY1305_IETF_NPUBBYTES;
				$nonce      = substr( $blob, 1, $n );
				$ciphertext = substr( $blob, 1 + $n );
				$plaintext  = sodium_crypto_aead_xchacha20poly1305_ietf_decrypt( $ciphertext, '', $nonce, $key );
			} else {
				$plaintext = false;
			}
		} catch ( SodiumException $e ) {
			$plaintext = false;
		}

		self::wipe( $key );
		return $plaintext;
	}

	/**
	 * Encrypts then base64-encodes (for storage in an option / text column).
	 *
	 * @param string $plaintext Plaintext data.
	 * @return string Base64.
	 */
	public static function encrypt_b64( $plaintext ) {
		return base64_encode( self::encrypt( $plaintext ) );
	}

	/**
	 * Decrypts a value produced by encrypt_b64().
	 *
	 * @param string $b64 Base64.
	 * @return string|false
	 */
	public static function decrypt_b64( $b64 ) {
		$blob = base64_decode( (string) $b64, true );
		if ( false === $blob ) {
			return false;
		}
		return self::decrypt( $blob );
	}

	/**
	 * SHA-256 hash (hex) of data. Core of tamper-evidence.
	 *
	 * @param string $data Binary data.
	 * @return string 64 hexadecimal characters.
	 */
	public static function sha256( $data ) {
		return hash( 'sha256', $data );
	}

	/**
	 * Generates an unguessable URL-safe opaque token.
	 *
	 * @param int $bytes Number of entropy bytes (default 32 -> ~43 base64url chars).
	 * @return string Token (>=32 characters for 24+ bytes).
	 */
	public static function opaque_token( $bytes = 32 ) {
		$raw = random_bytes( max( 24, (int) $bytes ) );
		// URL-safe Base64 without padding: characters [A-Za-z0-9_-].
		return sodium_bin2base64( $raw, SODIUM_BASE64_VARIANT_URLSAFE_NO_PADDING );
	}

	/**
	 * Constant-time comparison (anti-timing) of two strings.
	 *
	 * @param string $a Reference.
	 * @param string $b Candidate.
	 * @return bool
	 */
	public static function compare( $a, $b ) {
		return is_string( $a ) && is_string( $b ) && hash_equals( $a, $b );
	}
}