# hCaptcha & Form Güvenliği

TYPO3 formlarına captcha koruması ekleyerek spam gönderimlerini engellemeyi kapsar.

---

## hCaptcha Nedir?

hCaptcha, Google reCAPTCHA'nın gizlilik odaklı bir alternatifidir. TYPO3 formlarına entegre edilerek bot ve spam koruması sağlar.

---

## Kurulum

### Extension Yükleme

Bu projede **dreistromland/typo3-hcaptcha** (waldhacker fork, güncel bakım) kullanılır:

```bash
# hCaptcha extension'ını yükle
ddev composer require dreistromland/typo3-hcaptcha

# Veritabanı güncelle
ddev exec vendor/bin/typo3 extension:setup

# Cache temizle
ddev exec vendor/bin/typo3 cache:flush
```

### hCaptcha API Anahtarları

1. [hCaptcha Dashboard](https://dashboard.hcaptcha.com/) adresine kayıt olun
2. **Public Key** (Site Key) ve **Private Key** (Secret Key) alın

---

## Yapılandırma

### Extension Configuration

**Admin Tools > Settings > Extension Configuration > hcaptcha**

| Alan | Değer |
|------|-------|
| Public Key | hCaptcha Dashboard'dan alınan site/public key |
| Private Key | hCaptcha Dashboard'dan alınan secret key |

### PHP ile Yapılandırma

`config/system/additional.php` (bu projede örnek yapı mevcut):

```php
$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['hcaptcha'] = array_merge(
    $GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['hcaptcha'] ?? [],
    [
        'publicKey' => getenv('HCAPTCHA_PUBLIC_KEY') ?: '',
        'privateKey' => getenv('HCAPTCHA_PRIVATE_KEY') ?: '',
    ]
);
```

Ortam değişkenleri: `HCAPTCHA_PUBLIC_KEY`, `HCAPTCHA_PRIVATE_KEY`. Boş bırakılırsa Backend > Extension Configuration üzerinden doldurulmalıdır.

---

## Form Framework Entegrasyonu

### Bu projede hazır şablon

- **Backend:** Web > Form modülü > **Create new form** > şablondan **"Contact (hCaptcha)"** seçin. Form ad, e-posta, mesaj ve hCaptcha alanlarını içerir; kaydedip içerik elemanı olarak kullanabilirsiniz.
- Şablon dosyası: `packages/testproject/Configuration/Form/ContactFormWithHcaptcha.yaml`
- TypoScript ile `EXT:testproject/Configuration/Form/CustomFormSetup.yaml` kayıtlıdır (Form.typoscript).

### Form YAML örneği (manuel form için)

```yaml
renderables:
  -
    type: Page
    identifier: page-1
    label: 'İletişim Formu'
    renderables:
      -
        type: Text
        identifier: name
        label: 'Adınız'
        properties:
          fluidAdditionalAttributes:
            required: required
        validators:
          -
            identifier: NotEmpty
      -
        type: Text
        identifier: email
        label: 'E-posta Adresiniz'
        validators:
          -
            identifier: NotEmpty
          -
            identifier: EmailAddress
      -
        type: Textarea
        identifier: message
        label: 'Mesajınız'
        properties:
          rows: 5
        validators:
          -
            identifier: NotEmpty
      -
        type: Hcaptcha
        identifier: hcaptcha-1
        label: 'Robot Kontrolü'
        validators:
          -
            identifier: Hcaptcha
```

---

## Honeypot Tekniği (Ek Koruma)

TYPO3 Form Framework yerleşik honeypot desteği sunar. Varsayılan Form setup'ta honeypot zaten açıktır; form şablonunda `renderingOptions.honeypot.enable: true` kullanılabilir.

### Form YAML'ında

```yaml
renderingOptions:
  honeypot:
    enable: true

finishers:
  -
    identifier: EmailToReceiver
    options:
      recipientAddress: info@example.com
      senderAddress: '{email}'
      subject: 'Yeni İletişim Formu'
```

### TypoScript ile (bu projede mevcut)

```typoscript
plugin.tx_form.settings.yamlConfigurations {
    100 = EXT:testproject/Configuration/Form/CustomFormSetup.yaml
}
```

---

## Rate Limiting

Bu projede `config/system/additional.php` içinde form gönderim hız sınırı (IP başına dakikada deneme) tanımlıdır:

```php
$GLOBALS['TYPO3_CONF_VARS']['FE']['lockIP'] = 4;
$GLOBALS['TYPO3_CONF_VARS']['FE']['lockIPv6'] = 4;
```

İsterseniz değeri 2 veya daha düşük yaparak sıkılaştırabilirsiniz.

---

## CSRF Koruması

TYPO3 formları otomatik olarak CSRF token koruması sağlar. Ek yapılandırma gerektirmez.

Fluid formlarında CSRF token otomatik eklenir:

```html
<f:form action="submit" method="post">
    <!-- CSRF token otomatik eklenir -->
    <f:form.textfield name="email" />
    <f:form.submit value="Gönder" />
</f:form>
```

---

## Kaynaklar

- [dreistromland/typo3-hcaptcha](https://packagist.org/packages/dreistromland/typo3-hcaptcha) (bu projede kullanılan paket)
- [hCaptcha for EXT:form (TYPO3 docs)](https://docs.typo3.org/p/waldhacker/hcaptcha/main/en-us/)
- [TYPO3 Form Framework](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ApiOverview/FormFramework/)
- [hCaptcha Resmi Site](https://www.hcaptcha.com/)
