namespace Deal.Api.Configuration;

/// <summary>
/// Настройки доверия прокси-заголовкам (план Task 12; замечание ревью T4/T11 к Ruling 5/10): секция
/// <c>ForwardedHeaders</c> конфигурации (appsettings.json + переменные окружения <c>ForwardedHeaders__*</c>).
/// </summary>
/// <remarks>
/// В PROD наружу смотрит только Caddy (compose-prod, Task 14), core принимает соединения от него:
/// без обработки X-Forwarded-For/X-Forwarded-Proto RemoteIpAddress (HttpContext.Connection)
/// всех запросов — адрес Caddy, и audit-IP (ClientIp эндпоинтов, Ruling 4) и rate-limit-по-IP
/// (политики Ruling 5, LoginAttemptGuard) схлопываются в один бакет прокси. UseForwardedHeaders
/// доверяет заголовкам только клиентов из <see cref="KnownProxies"/> (IP-адреса) и
/// <see cref="KnownNetworks"/> (подсети CIDR).
/// <para>
/// <c>Enabled=false</c> — код-дефолт и значение dev/тестов: прокси в dev-стеке нет (compose.dev —
/// core наружу напрямую :5080), curl-приёмки от заголовков не зависят. PROD включает env
/// (<c>ForwardedHeaders__Enabled=true</c>) и перечисляет Caddy: KnownProxies (его IP) либо KnownNetworks
/// (узкий CIDR compose-сети). Пустые KnownProxies/KnownNetworks у ForwardedHeadersMiddleware означают
/// «доверять любому клиенту» — Program.BuildForwardedHeadersOptions не допускает пустоту и добавляет
/// loopback-фолбэк (dev-прокси на хосте: vite/локальный Caddy); явное перечисление в конфиге замещает его.
/// </para>
/// </remarks>
public sealed class ForwardedHeadersConfig
{
    /// <summary>
    /// Включена ли обработка прокси-заголовков (dev/тесты — false; PROD за Caddy — true).
    /// </summary>
    public bool Enabled { get; set; }

    /// <summary>
    /// Доверенные прокси-адреса: IP клиентов, которым можно верить в X-Forwarded-For/Proto.
    /// </summary>
    public string[] KnownProxies { get; set; } = [];

    /// <summary>
    /// Доверенные подсети прокси в CIDR (например "172.16.0.0/12" — compose-сеть PROD).
    /// </summary>
    public string[] KnownNetworks { get; set; } = [];
}