<?php
/**
 * Signature on a response one Shiftora site sends another.
 *
 * @package Shiftora\Api\Auth
 */

declare(strict_types=1);

namespace Shiftora\Api\Auth;

// Prevent direct file access.
if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * Requests are signed so the receiver can trust them; this does the same for the answer,
 * so a pull cannot be fed rows by something that is not the paired site. The HMAC covers
 * the status, the body hash, a timestamp and the signature of the request being answered,
 * which stops a captured response from being replayed against a different request.
 *
 * The key is the connection secret. Requests name the connection by X-Shiftora-Key-Id (a
 * hash) once the peer accepts it, so the secret is not on the wire, and certificates are
 * verified for public hosts. With both in place an attacker needs the stored secret, not
 * just the traffic. A peer on an earlier build is still sent the token, and then only TLS
 * verification stands between a network attacker and the key.
 */
final class ResponseSignature {

	public const TIMESTAMP_HEADER = 'X-Shiftora-Response-Timestamp';
	public const SIGNATURE_HEADER = 'X-Shiftora-Response-Signature';

	/** Capability a site advertises when it signs its responses. */
	public const CAPABILITY = 'signs_responses';

	/** Seconds a response timestamp may differ from this site's clock. Matches the request window. */
	public const WINDOW = 300;

	/**
	 * Routes whose body is written while it is read from disk, so no hash exists when the
	 * headers go out. Their chunks carry their own SHA-256 and are written through the
	 * uploads guard.
	 */
	public const UNSIGNED_ROUTES = [ '/export/file-batch', '/export/media-stream' ];

	/** Utility class. */
	private function __construct() {}

	/** The hex HMAC for a response. */
	public static function sign( string $secret, string $request_signature, int $status, string $body, int $timestamp ): string {
		return hash_hmac( 'sha256', self::payload( $request_signature, $status, $body, (string) $timestamp ), $secret, false );
	}

	/** Whether the signature and timestamp match the response, in constant time. */
	public static function verify( string $secret, string $request_signature, int $status, string $body, string $timestamp, string $signature, ?int $now = null ): bool {
		if ( ! ctype_digit( $timestamp ) || abs( (int) $timestamp - ( $now ?? time() ) ) > self::WINDOW ) {
			return false;
		}

		return hash_equals( self::sign( $secret, $request_signature, $status, $body, (int) $timestamp ), $signature );
	}

	/** Whether a route (or a URL ending in one) is answered with a signature. */
	public static function covers( string $route_or_url ): bool {
		$path = (string) strtok( $route_or_url, '?' );
		foreach ( self::UNSIGNED_ROUTES as $unsigned ) {
			if ( str_ends_with( $path, $unsigned ) ) {
				return false;
			}
		}

		return true;
	}

	/**
	 * The body a caller reads out of an admin-ajax envelope: the `data` member, encoded again.
	 * Both ends build it here, so the signature is of the same bytes whatever the transport did.
	 */
	public static function envelope_body( mixed $data ): string {
		return is_array( $data ) ? (string) wp_json_encode( $data ) : (string) ( $data ?? '' );
	}

	private static function payload( string $request_signature, int $status, string $body, string $timestamp ): string {
		return "RESPONSE\n" . $status . "\n" . $request_signature . "\n" . $timestamp . "\n" . hash( 'sha256', $body, false );
	}
}