<?php
/**
 * Webhook signature.
 *
 * @package FormPilot
 * @since   1.0.0
 */

declare( strict_types = 1 );

namespace FormPilot\Webhooks;

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

/**
 * Signs a payload so the receiver can tell it came from this site.
 *
 * The signature covers the timestamp *and* the body, not the body alone. A
 * signature over the body by itself is replayable forever: anyone who captures
 * one request can send it again, unchanged, and it still verifies. Binding the
 * time in lets the receiver refuse anything older than it is willing to accept.
 *
 * The receiving end verifies it by computing
 * `hash_hmac( 'sha256', "{$timestamp}.{$body}", $secret )` and comparing with a
 * constant time comparison — never with `==`, which leaks the answer through how
 * long it takes to fail.
 *
 * @since 1.0.0
 */
final class Signature {

	/**
	 * Header carrying the signature.
	 */
	public const HEADER = 'X-FormPilot-Signature';

	/**
	 * Header carrying the time the request was signed.
	 */
	public const TIMESTAMP_HEADER = 'X-FormPilot-Timestamp';

	/**
	 * Builds the signature of a payload.
	 *
	 * @param string $body      Exact bytes of the request body.
	 * @param string $secret    Shared key.
	 * @param int    $timestamp Unix time the request is being sent.
	 */
	public static function create( string $body, string $secret, int $timestamp ): string {
		return 'sha256=' . hash_hmac( 'sha256', $timestamp . '.' . $body, $secret );
	}

	/**
	 * Returns the headers a signed request carries.
	 *
	 * @param string $body      Exact bytes of the request body.
	 * @param string $secret    Shared key, empty to send nothing.
	 * @param int    $timestamp Unix time the request is being sent.
	 *
	 * @return array<string, string> Headers keyed by name.
	 */
	public static function headers( string $body, string $secret, int $timestamp ): array {
		if ( '' === $secret ) {
			return array();
		}

		return array(
			self::TIMESTAMP_HEADER => (string) $timestamp,
			self::HEADER           => self::create( $body, $secret, $timestamp ),
		);
	}
}