Shield Kütüphanesi

Shield, KUT uygulamalarında istek hızı sınırlama, başarısız işlem takibi, geçici engelleme, doğrulama kararı, IP beyaz listesi ve kara liste yeteneklerini tek bir kütüphanede toplar. Veritabanına ihtiyaç duymaz; sayaçlarını proje kapsamında File veya Redis deposunda saklar.

Başlatma ve otomatik istek koruması

Shield::init();
Shield::guardRequest();

guardRequest(), Config/Security.php içindeki auto.policies listesini sırayla uygular. İstemci sınırı aşarsa controller ve model çalışmadan HTTP 429 yanıtı üretilir.

İşlem koruma

$decision = Shield::action('account.login')
    ->user(['username' => Post::username()])
    ->check();

if($decision->blocked())
{
    return Shield::respond($decision);
}

if($decision->challenged())
{
    // Uygulama reCAPTCHA, OTP veya kendi doğrulama akışını gösterebilir.
}

Başarısız işlem fail() ile sayılır; başarılı işlem ilgili sayaçları temizler:

if(! $credentialsAreValid)
{
    $decision = Shield::fail();
}
else
{
    Shield::clear('account.login');
}

Decision; allowed(), denied(), challenged(), blocked(), limit(), remaining(), resetAt(), retryAfter() ve reason() yöntemlerini sağlar. Shield doğrulama arayüzü üretmez; geliştirici kararın uygulamadaki karşılığını belirler.

Security.php yapılandırması

'shield' =>
[
    'enabled' => true,
    'headers' => true,
    'trustedProxies' => [],

    'features' =>
    [
        'rateLimit' => true,
        'challenge' => true,
        'whitelist' => true,
        'blacklist' => true
    ],

    'storage' =>
    [
        'driver' => 'file', // file veya redis
        'path' => null,
        'redis' => ['host' => '127.0.0.1', 'port' => 6379]
    ],

    'lists' =>
    [
        'whitelist' => ['enabled' => true, 'ips' => ['127.0.0.1', '::1']],
        'blacklist' => ['enabled' => true, 'ips' => []]
    ],

    'auto' =>
    [
        'enabled' => true,
        'policies' => ['request.burst', 'request.sustained']
    ],

    'policies' =>
    [
        'request.burst' =>
        [
            'limit' => 120,
            'window' => '10 seconds',
            'blockFor' => '30 seconds'
        ],
        'account.login' =>
        [
            'limit' => 8,
            'window' => '5 minutes',
            'challengeAfter' => 4,
            'blockFor' => '15 minutes'
        ]
    ]
]

Özellikler features altında ayrı ayrı etkinleştirilebilir. Politika adları noktalı yol biçimindedir. account.* gibi joker politika tanımları aynı gruptaki işlemlere ortak kural uygulayabilir.

Rate limit davranışı

• limit: pencere içinde izin verilen istek veya başarısız işlem sayısıdır.
• window: sayacın yenileneceği süredir.
• challengeAfter: engelden önce ek doğrulama önerilecek eşiktir; sıfırsa challenge kullanılmaz.
• blockFor: sınır aşıldıktan sonraki geçici engel süresidir.

Shield::protect('api.token', ['account' => $accountId]) tek çağrıda politika seçip sayacı artırır. Kimlik değerleri dosyalara açık biçimde yazılmaz; proje anahtarıyla HMAC üretilir.

HTTP yanıtları

respond() veya abort() kullanıldığında Shield uygun HTTP durumunu ve RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, Retry-After başlıklarını üretir. Hız sınırı için 429, kara liste için 403 kullanılır.

Whitelist ve blacklist

Listeler tek IP adresi veya IPv4/IPv6 CIDR aralığı kabul eder. Whitelist eşleşmesi bütün sayaçları atlar. Blacklist eşleşmesi isteği sayaçtan bağımsız olarak reddeder. Proxy başlıkları yalnız trustedProxies içinde tanımlı doğrudan vekillerden geldiğinde kabul edilir.

Depolama

File sürücüsü kayıtları container projesinin Storage/Shield dizininde atomik kilitlemeyle saklar. Redis sürücüsü çok sunuculu kurulumlarda atomik sayaç kullanır. Shield kayıtları genel Cache alanından ayrıdır; proje önbelleğinin temizlenmesi güvenlik sayaçlarını silmez.