Core/Http/Security — form kalkanı, dış API koruması ve makine anahtar deposu

Doğrulanan kod tabanı: d49b4413 (dal feat/fw-license-master) · Tarih: 2026-10-05 · Yayın: 0.9.7 = bu commit + sonrası; belge yalnız doğrulama anındaki kodu anlatır
Kaynak klasör: Core/Http/Security/ — 14 *.php (5 kök + 8 Handlers/ + 1 bin/).
Envanter: 14 dosyanın 14'ü aşağıda anlatıldı.

1. Ne işe yarar, kim kullanır

Security/, tarayıcıdan gelen formu gönderim anında denetleyen form kalkanı
(FormService → Handlers/*) ile, dışarıdan gelen makine trafiğini denetleyen
API korumasını (ApiGuard + MachineApiRegistry + MachineApiKeyStore)
bir arada tutar. FormService ince bir ağ geçididir; asıl iş
FormGuardHandler ile Handlers/ altındaki denetleyicilerdedir.

Kimler çağırır:
Core/Http/Engine/Traits/Request/ValidationTrait.php (form()/rawAll() →
FormService::runSecurityChecks()),
Core/Routes/Mappings/web.php (ApiGuard middleware),
Core/Render görselleri (UrlSafetyHandler),
operatör (CLI: Security/bin/keys.php).

2. Klasör/dosya envanteri (14/14)

2.1 Kök (5)

Dosya	Görev	Önemli public yöntemler
`Security/FormService.php`	İnce ağ geçidi; `token()`/`honeypotName()` üretir, ağır işi `FormGuardHandler`'a yollar.	`token(): array`, `honeypotName(): string`, `runSecurityChecks(array $data,array $options=[]): array`
`Security/ApiGuard.php`	Dış API middleware'i: proje anahtarı → yapılandırma → IP → kimlik → kapsam → gövde → hız sınırı → denetim.	`handle(): void`
`Security/UrlSafetyService.php`	URL güvenlik servisi (görsel URL'leri için üst katman).	`validate(string $url, ?string $title=''): array`
`Security/MachineApiRegistry.php`	Makine API yollarının kapsam beyan kaydı (tohum + runtime). `final`.	`declarations(): array`, `declare(string $path,string $scope='default',bool $enforce=self::ENFORCE_DEFAULT,bool $ipExempt=false): void`, `match(?string $uri=null): ?array`, `isDeclared(?string $uri=null): bool`, `normalize(?string $uri): ?string`
`Security/MachineApiKeyStore.php`	Anahtar tanım normalizasyonu, `hash_equals` karşılaştırma, kimlik/scope yürütmesi. `final`.	`normalizeDefinitions(mixed): array`, `normalizeScopes(mixed): array`, `normalizeRate(mixed): ?array`, `normalizeTime(mixed): ?int`, `resolve(array $tanimlar,string $given): ?array`, `isRevoked(array,?int $now=null): bool`, `isExpired(array,?int $now=null): bool`, `generate(int $bytes=32): array`, `generateId(string $scope='default',array $mevcut=[]): string`, `rememberIdentity(array): void`, `currentIdentity(): ?array`, `forgetIdentity(): void`, `assertScope(?string $action): bool`

2.2 `Handlers/` (8)

Dosya	Görev	Önemli public yöntemler
`Handlers/CsrfHandler.php`	CSRF token üretimi/doğrulama (1 saat geçerli).	`generate(): array`, `validate(string $token): bool`, `verify(array $data): array`
`Handlers/BotHandler.php`	Honeypot alan adı + kullanıcı aracısı denetimi.	`getDynamicName(): string`, `validateHoneypot(array $data,string $field='website'): bool`, `validateUserAgent(): bool`, `static isSuspiciousUserAgent(string $ua): bool`
`Handlers/FormGuardHandler.php`	Kademeli ceza + sayaç kayıt defteri (F-10…F-14).	`const SAYAC_SINIRSIZ_FORM`, `const SAYAC_ORIJIN_YOK`, `const SAYAC_GET_CIKIS`, `artirLogOnlySayac(string): void`, `static logOnlySayacOku(?string $anahtar=null): int\\|array`, `audit(array $data,array $options=[]): array`
`Handlers/OriginHandler.php`	`Origin`/`Referer` doğrulama.	`validate(array $allowedOrigins=[],bool $strict=false): bool`
`Handlers/InjectionHandler.php`	XSS/enjeksiyon deseni taraması.	`detectXss(array $data): bool`
`Handlers/SanitizationHandler.php`	Girdi temizleme.	`trimData(array): array`, `stripTags(array,array $fields=[]): array`, `clean(?string): string`
`Handlers/FileSecurityHandler.php`	Yüklenen dosya güvenliği (Http katmanı; ayrıntılı doğrulama `Packages/RbnFile`'da).	`validateRequestFiles(array $files): array`
`Handlers/UrlSafetyHandler.php`	URL analizi: ana domain, IP, yasak desen, görsel ölçüsü.	`analyze(string $url, ?string $title=''): array`

2.3 `bin/` (1)

Dosya	Görev	Önemli public yöntemler
`Security/bin/keys.php`	`external-api` anahtar yönetimi CLI'si: `list/create/revoke/rotate`. Anahtar tanımlarını `external-api.php` dosyasına yeniden yazar.	— (CLI betiği; `MachineApiKeyStore` statiklerini kullanır)

Kapsama: 14/14.

3. Akış

3.1 Form gönderimi denetimi

ValidationTrait::form()/rawAll()          Engine/Traits/Request/ValidationTrait.php:140, 264
 └─ FormService::runSecurityChecks($_POST, $options)     FormService.php
     └─ FormGuardHandler::audit($data, $options)          FormGuardHandler.php
         ├─ CsrfHandler::verify()        → token 1 saat, hash_equals   CsrfHandler.php:22, 61
         ├─ BotHandler::validateHoneypot() + validateUserAgent()      BotHandler.php
         ├─ OriginHandler::validate()    → Origin/Referer               OriginHandler.php
         ├─ InjectionHandler::detectXss()                              InjectionHandler.php
         ├─ SanitizationHandler::trimData()/stripTags()                SanitizationHandler.php
         └─ kademeli ceza: KADEMELI_CEZA_DAKIKA dizisine göre sayaç artar
            (yazılamazsa LOG-ONLY sayaç artar → fail-open)

3.2 Dış API isteği

Mappings/web.php: ApiGuard middleware
 └─ ApiGuard::handle()                       ApiGuard.php:40
     ├─ project_key() boş → 400 NO_PROJECT   :42-45
     ├─ resolveProjectConfig('external-api') → yoksa 403 NOT_CONFIGURED / DISABLED  :49-56
     ├─ ipKontrol(): allowed_origins boşsa veya '*' ise DENETİM YAPILMAZ  :90-99
     ├─ kimlikDogrula(): başlık X-RBN-API-KEY, yoksa input('token')  :110-187
     │    ├─ allow_query_token=false ise sorgudan gelen anahtar reddedilir  :124-129
     │    ├─ keys[] → MachineApiKeyStore::resolve() (hash_equals)  :139-165
     │    ├─ iptal/süre → 401  :149-156
     │    ├─ düz api_key dalı → hash_equals  :169-173
     │    └─ MachineApiKeyStore::rememberIdentity() + kapsamKontrol()  :160-162
     ├─ MachineApiRegistry::match() → kapsam beyanı (runtime `declare()` ile büyür)
     ├─ govdeKontrol() (LOG-ONLY)   :228-252
     ├─ hizSiniri() (dosya sayacı, LOG-ONLY, fail-open)  :262-333
     └─ denetim('allow') → logs kanalı 'machine-api'  :390-408

4. Yapılandırma / ayar anahtarları

Anahtar	Yer	Varsayılan / not
`external-api.php` proje ayarı	`ApiGuard.php:49`	`enabled`, `allowed_origins`, `allow_query_token` (varsayılan `true`), `api_key`, `keys[]`
`keys[]` alanları	`bin/keys.php:165`	`id`, `hash` (`sha256:<hex>`), `scopes`, `rate{max,per}`, `body_max`, `expires_at`, `revoked_at`, `label`
`MachineApiRegistry::SEED`	`MachineApiRegistry.php:~90-103`	`path`→`scope`; `ENFORCE_DEFAULT` log-only
`FormGuardHandler` kademeli ceza	`FormGuardHandler.php:27`	`KADEMELI_CEZA_DAKIKA = [15, 60, 1440, 1440]`
`FormGuardHandler::SAYAC_*`	`:53,56,74`	`form_without_rate_limit`, `origin_referer_missing`, `logout_get_deprecated`
`security.form_input_mode`	`../Engine/README.md` §4	Kalkanın açılıp kapanması buradan karar verilir

5. Tuzaklar ve kurallar

?token= kapatılmaz (proje sahibi kararı): yalnız LOG-ONLY uyarı ve
allow_query_token ayarı (ApiGuard.php:26, 124-136).
Gövde ve hız sınırı LOG-ONLY'dur (enforce=false); sayaç dosyası
yazılamazsa fail-open (ApiGuard.php:262).
Çözülemeyen middleware fail-closed'dır — bu katmanda değil, rota
katmanındadır: Core/Routes/Engine/Dispatcher.php:107.
CSRF'de geliştirici muafiyeti yok. Tüm roller için doğrulama aynı ve
zorunludur (CsrfHandler.php:68).
Token 1 saat geçerli; süre dolunca validate() oturumu temizler
(CsrfHandler.php:55).
IP denetimi allowed_origins boşsa veya '*' ise hiç yapılmaz
(ApiGuard.php:90) — bu, "denetim yapıldı" anlamına gelmez.
Çift çalıştırma tuzağı yok: FormGuardHandler::audit() tek giriş
noktasıdır; ValidationTrait rawAll() yolunda denetimleri kendisi çağırır
(ValidationTrait.php:264).
Webp/URL güvenliği iki katmanlıdır: UrlSafetyService →
UrlSafetyHandler::analyze(); ikisi de allow-list mantığıyla çalışır,
kara liste değil.

6. Örnek (gerçek koddan)

Form kalkanı kullanımı (ValidationTrait.php:125 sözleşmesi):

$data = request()->form([
    'email'   => 'required|email',
    'website' => 'nullable',      // honeypot
], ['csrf' => true]);

FormService doğrudan da çağrılabilir (View katmanından):

$token = $this->service('http.form')->token();

7. İlgili belgeler

README.md — Core/Http kök dosyaları
Engine.md — form()/rawAll() çağıran taraf ve RedirectTrait
../Routes/README.md — ApiGuard'ın middleware olarak bağlandığı yer
Render katmanı (Core/Render/) — görsel URL'lerinin tüketildiği yer (⏳ ayrı görev, belgesi henüz yazılmadı)
../../kavramlar/02-yapilandirma.md — security.* anahtarları
../../acik-sorular.md §3 (security.form_input_mode = log ölçüm turu)