feat(auth): complete registration anti-spam and quota hardening

docs/registration-antispam.md

@@ -0,0 +1,202 @@
+# Registration Anti-Spam + Email Quota Protection
+
+This document describes how the Skinbase email-first registration hardening works.
+
+## Scope
+
+Applies to the flow:
+
+- `GET /register`
+- `POST /register`
+- `GET /register/notice`
+- `POST /register/resend-verification`
+- `GET /verify/{token}`
+- `GET/POST /setup/password`
+- `GET/POST /setup/username`
+
+Primary implementation:
+
+- `app/Http/Controllers/Auth/RegisteredUserController.php`
+- `app/Http/Controllers/Auth/RegistrationVerificationController.php`
+
+## Security Controls
+
+### 1) IP Rate Limiting
+
+Defined in `app/Providers/AppServiceProvider.php`:
+
+- `register-ip`: per-minute IP limit
+- `register-ip-daily`: per-day IP limit
+- `register` (legacy resend route): per-minute IP + per-email key
+
+Applied on `POST /register` in `routes/auth.php`:
+
+- `throttle:register-ip`
+- `throttle:register-ip-daily`
+
+### 2) Per-Email Cooldown
+
+Cooldown is enforced by user fields:
+
+- `users.last_verification_sent_at`
+- `users.verification_send_count_24h`
+- `users.verification_send_window_started_at`
+
+On repeated requests within cooldown:
+
+- No additional verification email is queued
+- Generic success message is returned
+
+### 3) Progressive CAPTCHA (Turnstile)
+
+Service:
+
+- `app/Services/Security/TurnstileVerifier.php`
+
+Controller logic (`RegisteredUserController::shouldRequireTurnstile`):
+
+- Requires Turnstile for suspicious IP activity (attempt threshold)
+- Also requires Turnstile when registration rate-limit state is detected
+
+UI behavior (`resources/views/auth/register.blade.php`):
+
+- Turnstile widget is only rendered when required
+
+### 4) Disposable Domain Block
+
+Service:
+
+- `app/Services/Auth/DisposableEmailService.php`
+
+Config source:
+
+- `config/disposable_email_domains.php`
+
+Behavior:
+
+- Blocks known disposable domains (supports wildcard matching)
+- Returns friendly validation error
+
+### 5) Queue + Throttle + Quota Circuit Breaker
+
+Queue job:
+
+- `app/Jobs/SendVerificationEmailJob.php`
+
+Behavior:
+
+- Registration controller dispatches `SendVerificationEmailJob`
+- Job applies global send throttling via `RateLimiter`
+- Job checks monthly quota via `RegistrationEmailQuotaService`
+- If quota exceeded: send is blocked (fail closed), event marked blocked
+
+Quota service/model/table:
+
+- `app/Services/Auth/RegistrationEmailQuotaService.php`
+- `app/Models/SystemEmailQuota.php`
+- `system_email_quota`
+
+Send event audit:
+
+- `app/Models/EmailSendEvent.php`
+- `email_send_events`
+
+### 6) Generic Responses (Anti-Enumeration)
+
+The registration entry point uses a standard success message:
+
+- `If that email is valid, we sent a verification link.`
+
+This message is returned for:
+
+- Unknown emails
+- Existing verified emails
+- Cooldown cases
+- Quota-blocked paths
+
+### 7) Verification Token Hardening
+
+Service:
+
+- `app/Services/Auth/RegistrationVerificationTokenService.php`
+
+Protections:
+
+- Token generated with high entropy (`Str::random(64)`)
+- Stored hashed (`sha256`) in `user_verification_tokens`
+- Expires using configured TTL
+- Validation uses hash lookup + constant-time compare (`hash_equals`)
+- Token deleted after successful verification (one-time use)
+
+Verification endpoint:
+
+- `app/Http/Controllers/Auth/RegistrationVerificationController.php`
+
+## Configuration
+
+Main registration config:
+
+- `config/registration.php`
+
+Key settings:
+
+- `ip_per_minute_limit`
+- `ip_per_day_limit`
+- `email_per_minute_limit`
+- `email_cooldown_minutes`
+- `verify_token_ttl_hours`
+- `enable_turnstile`
+- `disposable_domains_enabled`
+- `turnstile_suspicious_attempts`
+- `turnstile_attempt_window_minutes`
+- `email_global_send_per_minute`
+- `monthly_email_limit`
+- `generic_success_message`
+
+Turnstile config:
+
+- `config/services.php` under `turnstile`
+
+Environment examples:
+
+- `.env.example` contains all registration anti-spam keys
+
+## Database Objects
+
+Added for anti-spam/quota support:
+
+- Migration: `2026_02_21_000001_add_registration_antispam_fields_to_users_table.php`
+- Migration: `2026_02_21_000002_create_email_send_events_table.php`
+- Migration: `2026_02_21_000003_create_system_email_quota_table.php`
+- Migration: `2026_02_20_191000_add_registration_phase1_schema.php` (creates `user_verification_tokens`)
+- Migration: `2026_02_21_000004_rename_token_to_token_hash_in_user_verification_tokens.php` (schema hardening)
+- Migration: `2026_02_21_000005_ensure_user_verification_tokens_table_exists.php` (rollout safety)
+
+## Test Coverage
+
+Primary tests:
+
+- `tests/Feature/Auth/RegistrationAntiSpamTest.php`
+- `tests/Feature/Auth/RegistrationNoticeResendTest.php`
+- `tests/Feature/Auth/RegistrationQuotaCircuitBreakerTest.php`
+- `tests/Feature/Auth/RegistrationTokenVerificationTest.php`
+- `tests/Feature/Auth/RegistrationFlowChecklistTest.php`
+- `tests/Feature/Auth/RegistrationVerificationMailTest.php`
+
+Covered scenarios:
+
+- IP rate-limit returns `429`
+- Cooldown suppresses extra sends
+- Disposable domains blocked
+- Quota exceeded blocks send and keeps generic success UX
+- Turnstile required on abuse/rate-limit state
+- Tokens hashed, expire, and are one-time
+- Responses avoid account enumeration
+
+## Operations Notes
+
+- Keep disposable domain list maintained in `config/disposable_email_domains.php`.
+- Ensure queue workers process the `mail` queue.
+- Monitor `email_send_events` for blocked/sent patterns.
+- Set `REGISTRATION_MONTHLY_EMAIL_LIMIT` based on provider quota.
+- Configure `TURNSTILE_SITE_KEY` and `TURNSTILE_SECRET_KEY` in production.