<?php
// SPDX-License-Identifier: GPL-3.0-or-later
declare(strict_types=1);

namespace Aiwend\Provider;

/**
 * Last line of defence against a real AI-provider request leaving an integration-test site.
 *
 * Every provider transport calls assertAllowed() before it opens a connection (cURL or the
 * WordPress HTTP API). The guard is inert on ordinary sites: it only acts when the site's own
 * configuration says it is the dedicated integration-test installation.
 *
 * - normal: no test signal at all. Requests are not affected.
 * - verified test: AIWEND_ITEST is true, the database name and user are the same dedicated test
 *   identity, the marker has the expected shape and the install lives in the directory that belongs to that
 *   identity (aiwend_itest in tools/wp-itest, aiwend_itest_ms in tools/wp-itest-ms). Mixed identities, for example
 *   the multisite database in the single-site directory, are unverified and therefore blocked.
 * - unverified test: any test signal is present without the full identity. This is treated like
 *   a verified test site: blocked. A site that looks like a test site but cannot prove it never
 *   gets outbound provider traffic.
 *
 * There is deliberately no allow-list and no switch to turn the guard off: tests inject fake
 * transports or adapters instead. The simulate() seam used by unit tests can only add signals
 * (make the guard stricter); it can never allow a request that the real configuration blocks.
 */
final class OutboundGuard
{
    public const NORMAL = 'normal';
    public const VERIFIED_TEST = 'verified-test';
    public const UNVERIFIED_TEST = 'unverified-test';

    /** Dedicated test identity (database name = database user) => the only install directory it may live in. */
    private const IDENTITIES = ['aiwend_itest' => '/tools/wp-itest', 'aiwend_itest_ms' => '/tools/wp-itest-ms'];
    private const MARKER_PATTERN = '/^aiwend-itest-[0-9a-f]{32}$/';

    /** @var array<string, mixed> signals added by unit tests; can only block more, never less */
    private static array $simulated = [];

    /** @throws ProviderException kind unavailable, never dispatched, no credentials in the message */
    public static function assertAllowed(): void
    {
        if (self::mode() !== self::NORMAL) {
            // phpcs:ignore WordPress.Security.EscapeOutput.ExceptionNotEscaped -- exception messages go to logs and callers, never echoed; public errors are fixed codes
            throw new ProviderException(ProviderException::UNAVAILABLE, false, 'Outbound provider requests are blocked in the integration-test environment.');
        }
    }

    public static function blocked(): bool
    {
        return self::mode() !== self::NORMAL;
    }

    /** @param array<string, mixed>|null $constants null reads the real site constants */
    public static function mode(?array $constants = null): string
    {
        $real = $constants ?? self::currentConstants();
        $mode = self::classify($real);
        if ($constants === null && $mode === self::NORMAL && self::$simulated !== []) {
            $mode = self::classify(array_merge($real, self::$simulated));
        }
        return $mode;
    }

    /** Unit-test seam. Adds signals on top of the real configuration; see the class comment. */
    public static function simulate(array $constants): void
    {
        self::$simulated = $constants;
    }

    public static function reset(): void
    {
        self::$simulated = [];
    }

    /** @param array<string, mixed> $c */
    private static function classify(array $c): string
    {
        $flag = !empty($c['AIWEND_ITEST']);
        $db = (string) ($c['DB_NAME'] ?? '');
        $user = (string) ($c['DB_USER'] ?? '');
        $marker = isset($c['AIWEND_ITEST_MARKER']) ? (string) $c['AIWEND_ITEST_MARKER'] : null;
        $path = rtrim(str_replace('\\', '/', (string) ($c['ABSPATH'] ?? '')), '/');
        $inTestDir = false;
        foreach (self::IDENTITIES as $dir) {
            $inTestDir = $inTestDir || ($path !== '' && str_ends_with($path, $dir));
        }

        $signal = $flag || isset(self::IDENTITIES[$db]) || isset(self::IDENTITIES[$user]) || $marker !== null || $inTestDir;
        if (!$signal) {
            return self::NORMAL;
        }
        $verified = ($c['AIWEND_ITEST'] ?? null) === true && isset(self::IDENTITIES[$db]) && $db === $user
            && $marker !== null && preg_match(self::MARKER_PATTERN, $marker) === 1
            && $path !== '' && str_ends_with($path, self::IDENTITIES[$db]);
        return $verified ? self::VERIFIED_TEST : self::UNVERIFIED_TEST;
    }

    /** @return array<string, mixed> */
    private static function currentConstants(): array
    {
        $out = [];
        foreach (['AIWEND_ITEST', 'DB_NAME', 'DB_USER', 'AIWEND_ITEST_MARKER', 'ABSPATH'] as $name) {
            if (defined($name)) {
                $out[$name] = constant($name);
            }
        }
        return $out;
    }
}