<?php
// Merchant Integration · signing toolkit for PHP 7.4+ (built-in hash extension only).
// Signs requests you send to the Merchant API and verifies the Wallet API requests we send to you.
// Spec: Integration Guide › Authentication. Self-test against the published test vector:  php MerchantSign.php

final class MerchantSign
{
    public const HEADER_MERCHANT_CODE = 'X-Merchant-Code';
    public const HEADER_REQUEST_ID = 'X-Request-Id';
    public const HEADER_TIMESTAMP = 'X-Timestamp';
    public const HEADER_SIGNATURE = 'X-Signature';
    public const TIMESTAMP_WINDOW_MS = 300000; // |now - X-Timestamp| must be within 300 s

    public const OK = 'OK';
    public const INVALID_SIGNATURE = 'INVALID_SIGNATURE';
    public const TIMESTAMP_EXPIRED = 'TIMESTAMP_EXPIRED';

    /** Lower-case hex SHA-256 of the exact body bytes (empty body included). */
    public static function bodySha256(string $rawBody): string
    {
        return hash('sha256', $rawBody);
    }

    public static function stringToSign(string $method, string $path, string $merchantCode, string $timestamp, string $requestId, string $rawBody): string
    {
        return implode("\n", [strtoupper($method), $path, $merchantCode, $timestamp, $requestId, self::bodySha256($rawBody)]);
    }

    /** X-Signature: lower-case hex HMAC-SHA256(secretKey, stringToSign). */
    public static function sign(string $secretKey, string $method, string $path, string $merchantCode, string $timestamp, string $requestId, string $rawBody): string
    {
        return hash_hmac('sha256', self::stringToSign($method, $path, $merchantCode, $timestamp, $requestId, $rawBody), $secretKey);
    }

    /** A fresh X-Request-Id (32 hex characters). Use a new one for every request, retries included. */
    public static function newRequestId(): string
    {
        return bin2hex(random_bytes(16));
    }

    public static function nowMs(): int
    {
        return (int) floor(microtime(true) * 1000);
    }

    /** Headers for one signed request ("Name: value" lines for curl). Send exactly $rawBody — the bytes that were signed. */
    public static function signedHeaders(string $merchantCode, string $secretKey, string $method, string $path, string $rawBody, ?int $nowMs = null, ?string $requestId = null): array
    {
        $ts = (string) ($nowMs ?? self::nowMs());
        $rid = $requestId ?? self::newRequestId();
        return [
            'Content-Type: application/json; charset=utf-8',
            self::HEADER_MERCHANT_CODE . ': ' . $merchantCode,
            self::HEADER_REQUEST_ID . ': ' . $rid,
            self::HEADER_TIMESTAMP . ': ' . $ts,
            self::HEADER_SIGNATURE . ': ' . self::sign($secretKey, $method, $path, $merchantCode, $ts, $rid, $rawBody),
        ];
    }

    /**
     * Check one incoming request (our Wallet API calls to you). Returns OK, INVALID_SIGNATURE or TIMESTAMP_EXPIRED,
     * usable as the envelope code. $headers: name => value (any case), e.g. getallheaders(). Read the raw body with
     * file_get_contents('php://input') and verify BEFORE json_decode.
     */
    public static function verify(string $secretKey, string $merchantCode, array $headers, string $method, string $path, string $rawBody, ?int $nowMs = null): string
    {
        $h = array_change_key_case($headers, CASE_LOWER);
        $code = (string) ($h['x-merchant-code'] ?? '');
        $rid = (string) ($h['x-request-id'] ?? '');
        $ts = (string) ($h['x-timestamp'] ?? '');
        $sig = strtolower((string) ($h['x-signature'] ?? ''));
        if ($code === '' || $rid === '' || $ts === '' || $sig === '' || $code !== $merchantCode) {
            return self::INVALID_SIGNATURE;
        }
        if (!ctype_digit($ts)) {
            return self::TIMESTAMP_EXPIRED;
        }
        $now = $nowMs ?? self::nowMs();
        if (abs($now - (int) $ts) > self::TIMESTAMP_WINDOW_MS) {
            return self::TIMESTAMP_EXPIRED;
        }
        $want = self::sign($secretKey, $method, $path, $code, $ts, $rid, $rawBody);
        return hash_equals($want, $sig) ? self::OK : self::INVALID_SIGNATURE;
    }

    /** A response body: {code, message, data}. Business results are always HTTP 200. */
    public static function envelope(string $code, string $message = '', ?array $data = null): string
    {
        $out = ['code' => $code, 'message' => $message !== '' ? $message : $code];
        if ($data !== null) {
            $out['data'] = $data;
        }
        return json_encode($out, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE);
    }
}

if (PHP_SAPI === 'cli' && realpath($_SERVER['SCRIPT_FILENAME'] ?? '') === __FILE__) {
    $key = 'test-secret-key-0001'; $path = '/wallet/debit'; $code = 'M0001'; $ts = '1792000000000'; $rid = 'req-0001';
    $body = '{"txnId":"T7K2M9QXH4ZP8WNA","amount":"10.00"}';
    $check = function (bool $ok, string $what) { if (!$ok) { fwrite(STDERR, "FAIL: $what\n"); exit(1); } };
    $check(MerchantSign::bodySha256($body) === 'b8d0525520debc2d5e2c62e83d2303a4cd29ed0c18c4139e98196c76c14fc2b8', 'body hash');
    $sig = MerchantSign::sign($key, 'POST', $path, $code, $ts, $rid, $body);
    $check($sig === 'e5273ee9fb4c05408af2f8b32b26b4b98bc891fb77e5ffe5b46f9c112ebe6589', "signature $sig");
    $h = ['X-Merchant-Code' => $code, 'X-Request-Id' => $rid, 'X-Timestamp' => $ts, 'X-Signature' => $sig];
    $now = 1792000000000;
    $check(MerchantSign::verify($key, $code, $h, 'POST', $path, $body, $now) === MerchantSign::OK, 'verify');
    $check(MerchantSign::verify($key, $code, $h, 'POST', $path, str_replace('10.00', '10.01', $body), $now) === MerchantSign::INVALID_SIGNATURE, 'tampered');
    $check(MerchantSign::verify($key, 'M0002', $h, 'POST', $path, $body, $now) === MerchantSign::INVALID_SIGNATURE, 'other merchant');
    $check(MerchantSign::verify($key, $code, $h, 'POST', $path, $body, $now + MerchantSign::TIMESTAMP_WINDOW_MS + 1) === MerchantSign::TIMESTAMP_EXPIRED, 'stale');
    echo "MerchantSign.php: self-test passed $sig\n";
}