# CAPTCHA Protection Plugin pentru PanelDNS

Plugin complet de protecție CAPTCHA pentru sistemul PanelDNS, cu suport pentru 6 provideri diferiți și funcții avansate de securitate.

## 📋 Caracteristici

### 🛡️ 6 Provideri CAPTCHA Suportați

1. **hCaptcha** - Privacy-focused alternative to reCAPTCHA
   - Website: https://www.hcaptcha.com/
   - Free tier: 1M requests/month

2. **reCAPTCHA v2 (Checkbox)** - Classic "I'm not a robot" checkbox
   - Website: https://www.google.com/recaptcha
   - Free, unlimited requests

3. **reCAPTCHA v2 (Invisible)** - Seamless background verification
   - Website: https://www.google.com/recaptcha
   - Free, unlimited requests

4. **reCAPTCHA v3 (Score-based)** - Risk analysis without user interaction
   - Website: https://www.google.com/recaptcha
   - Free, 1M requests/month
   - Score threshold configurabil (0.0 - 1.0)

5. **Cloudflare Turnstile** - Fast and privacy-friendly
   - Website: https://www.cloudflare.com/products/turnstile/
   - Free, unlimited requests

6. **TrustIP** - Advanced bot detection via IP analysis
   - Website: https://trustip.io/
   - API key required

### ✨ Funcționalități Avansate

- ✅ **Multi-Location Support** - Activare/dezactivare independentă pe login, register, contact, forgot password, API
- 📊 **Statistici Detaliate** - Tracking complet cu response time, success rate, provider usage
- 🚫 **Rate Limiting** - Blocare automată IP după X încercări eșuate
- 🤍 **IP Whitelist** - Excepții pentru IP-uri de încredere
- 🔄 **Fallback Provider** - Backup automat la alt provider în caz de eroare
- 🧪 **Testing Mode** - Mod dezvoltare cu verificări automate
- 🎨 **Blade Components** - Integrare ușoară în formulare: `<x-captcha location="login" />`
- 🛡️ **Middleware** - Protecție la nivel de rută: `->middleware('captcha:login')`

## 📦 Instalare

### Pasul 1: Încarcă Plugin-ul

1. Accesează **Admin > Plugins**
2. Click pe butonul **"Upload Plugin"**
3. Selectează fișierul `captcha-plugin.zip`
4. Așteaptă confirmarea: "Plugin instalat cu succes!"

### Pasul 2: Activează Plugin-ul

1. În lista de plugin-uri, găsește **"CAPTCHA Protection"**
2. Click pe butonul **"Activează"**
3. Plugin-ul va rula migrațiile automat și va crea tabelele necesare:
   - `captcha_settings` - Configurații
   - `captcha_statistics` - Statistici de utilizare
   - `captcha_rate_limits` - Rate limiting per IP

### Pasul 3: Configurare

1. Accesează **Admin > CAPTCHA**
2. Selectează provider-ul dorit
3. Adaugă API keys:
   - **Site Key** - Cheia publică
   - **Secret Key** - Cheia secretă
   - **API Key** - Doar pentru TrustIP

4. Configurează locațiile unde să fie activ CAPTCHA
5. Setează opțiuni avansate:
   - Threshold pentru reCAPTCHA v3 (recomandat: 0.5)
   - Fallback provider
   - IP whitelist
   - Rate limiting

## 🔑 Obținere API Keys

### hCaptcha
1. Vizitează https://dashboard.hcaptcha.com/signup
2. Creează cont gratuit
3. Add New Site
4. Copiază **Site Key** și **Secret Key**

### Google reCAPTCHA (v2 și v3)
1. Vizitează https://www.google.com/recaptcha/admin
2. Înregistrează un nou site
3. Alege tipul: reCAPTCHA v2 sau v3
4. Adaugă domeniul tău
5. Copiază **Site Key** și **Secret Key**

### Cloudflare Turnstile
1. Vizitează https://dash.cloudflare.com/
2. Mergi la Turnstile
3. Create Site
4. Copiază **Site Key** și **Secret Key**

### TrustIP
1. Vizitează https://trustip.io/
2. Creează cont
3. Generează API Key din dashboard
4. În PanelDNS, adaugă **API Key** în câmpul dedicat

## 🎯 Utilizare

### În Blade Templates

Adaugă componenta CAPTCHA în orice formular:

```blade
<form method="POST" action="/login">
    @csrf
    
    <!-- Câmpurile tale -->
    <input type="email" name="email">
    <input type="password" name="password">
    
    <!-- CAPTCHA Component -->
    <x-captcha location="login" />
    
    <button type="submit">Login</button>
</form>
```

Locații disponibile:
- `login` - Formular de autentificare
- `register` - Formular de înregistrare
- `contact` - Formular de contact
- `forgot_password` - Reset parolă
- `api` - Endpoint-uri API

### Protecție Middleware

Protejează rutele direct cu middleware:

```php
Route::post('/login', [AuthController::class, 'login'])
    ->middleware('captcha:login');

Route::post('/register', [AuthController::class, 'register'])
    ->middleware('captcha:register');

Route::post('/api/sensitive', [ApiController::class, 'sensitive'])
    ->middleware('captcha:api');
```

### Verificare Programatică

Poți verifica CAPTCHA manual în controllere:

```php
use CaptchaPlugin\Services\CaptchaService;

class AuthController extends Controller
{
    public function login(Request $request, CaptchaService $captcha)
    {
        // Verifică CAPTCHA
        $result = $captcha->verify(
            $request->input('captcha_response'),
            'login',
            $request->ip()
        );
        
        if (!$result['success']) {
            return back()->withErrors([
                'captcha' => $result['message']
            ]);
        }
        
        // Continuă cu autentificarea
    }
}
```

## 📊 Statistici și Monitorizare

Accesează **Admin > CAPTCHA > Statistici** pentru:

- ✅ Success rate per provider
- ⏱️ Response time mediu
- 📈 Grafice utilizare în timp
- 🌍 Analiză per locație
- 🚫 IP-uri blocate
- 📊 Top failed IPs

## 🔧 Configurare Avansată

### Rate Limiting

Configurează în `config/captcha.php`:

```php
'rate_limit' => [
    'enabled' => true,
    'max_attempts' => 5,           // Maxim 5 încercări
    'decay_minutes' => 15,         // În 15 minute
    'block_duration_minutes' => 30, // Blocare 30 minute
],
```

### IP Whitelist

Adaugă IP-uri în whitelist pentru a evita CAPTCHA:

```php
'whitelist_ips' => [
    '127.0.0.1',
    '::1',
    '192.168.1.100',  // Server intern
],
```

### Fallback Provider

Configurează backup în caz de eroare:

```php
'fallback_enabled' => true,
'fallback_provider' => 'hcaptcha',
'fallback_site_key' => 'your-fallback-site-key',
'fallback_secret_key' => 'your-fallback-secret-key',
```

### Testing Mode

Activează pentru dezvoltare (toate verificările trec automat):

```php
'testing_mode' => env('CAPTCHA_TESTING_MODE', false),
```

În `.env`:
```
CAPTCHA_TESTING_MODE=true
```

## 🛠️ Troubleshooting

### CAPTCHA nu apare în formular
- Verifică că plugin-ul este **activat**
- Verifică că locația este **activată** în setări
- Verifică că IP-ul tău nu este în **whitelist**
- Verifică consola browser pentru erori JavaScript

### "Invalid site key" error
- Verifică că Site Key-ul este corect pentru provider-ul selectat
- Verifică că domeniul este adăugat în dashboard-ul provider-ului
- Pentru reCAPTCHA v2/v3, verifică că ai selectat versiunea corectă

### Rate limiting prea agresiv
- Crește `max_attempts` în configurare
- Crește `decay_minutes` pentru o fereastră mai mare
- Adaugă IP-uri de încredere în whitelist

### Statistici nu se salvează
- Verifică că tabelul `captcha_statistics` există
- Rulează migrațiile manual: `php artisan migrate`
- Verifică permisiunile pe baza de date

## 📝 Cerințe Tehnice

- PHP 8.1 sau superior
- Laravel 10.0 sau superior
- MySQL 5.7+ sau MariaDB 10.3+
- Extensii PHP: `json`, `curl`, `openssl`

## 🔄 Update Plugin

Pentru a actualiza plugin-ul:

1. Dezactivează plugin-ul vechi
2. **NU** șterge (datele vor fi păstrate)
3. Încarcă noua versiune
4. Activează din nou

Datele din baza de date (setări, statistici) vor fi păstrate automat.

## 🗑️ Dezinstalare Completă

**ATENȚIE**: Această operație șterge toate datele!

1. Accesează **Admin > Plugins**
2. Dezactivează plugin-ul CAPTCHA
3. Click pe **"Șterge"**
4. Confirmă acțiunea

Vor fi șterse:
- Tabelele `captcha_settings`, `captcha_statistics`, `captcha_rate_limits`
- Fișierele de configurare publicate
- View-urile publicate

## 📞 Suport

Pentru probleme sau întrebări:
- Email: support@paneldns.com
- Documentație: https://docs.paneldns.com/plugins/captcha
- GitHub Issues: https://github.com/paneldns/captcha-plugin

## 📄 Licență

Acest plugin este licențiat sub **MIT License**.

## 👨‍💻 Autor

Dezvoltat de **PanelDNS Team** - https://paneldns.com

---

**Versiune**: 1.0.0  
**Data lansării**: November 2025  
**Compatibil cu**: PanelDNS 2.0+
