# ZapaziMe Security Implementation Guide
## Overview
This document outlines the comprehensive security measures implemented to protect the ZapaziMe platform from spam, unauthorized access, and security threats.
## 1. Two-Factor Authentication (2FA)
### Implementation
- **Package**: `solution-forest/filament-email-2fa`
- **Type**: Email-based OTP (One-Time Password)
- **Status**: ✅ Implemented (Currently disabled in AdminPanelProvider - uncomment to enable)
### Features
- Email-based verification codes
- Device remember functionality (14 days)
- OTP lifetime: 5 minutes
- Automatic cleanup of expired codes
### Enabling 2FA
1. Uncomment the 2FA plugin in `AdminPanelProvider.php`:
```php
$this->get2FAPlugin(),
```
2. Users can enable 2FA from their profile page
3. On login, users will receive an email with a verification code
4. Trusted devices can be remembered for 14 days
## 2. Email Verification
### Implementation
- **Status**: ✅ Enabled
- **Location**: `AdminPanelProvider.php` - `->emailVerification()`
### Features
- Users must verify their email before accessing the system
- Verification emails sent automatically on registration
- Prevents spam accounts from accessing the platform
## 3. Account Lockout Protection
### Implementation
- **Location**: `User.php` model
- **Status**: ✅ Implemented
### Features
- **Failed Login Tracking**: Records failed login attempts
- **Auto-Lock**: Account locked after 5 failed attempts
- **Lock Duration**: 30 minutes
- **Auto-Unlock**: Automatically unlocks after timeout
- **IP Tracking**: Records last login IP address
### Database Fields
```php
- failed_login_attempts (integer)
- locked_until (timestamp)
- last_login_at (timestamp)
- last_login_ip (string)
```
### Methods
- `isLocked()`: Check if account is currently locked
- `recordFailedLogin()`: Increment failed attempts and lock if needed
- `recordSuccessfulLogin()`: Reset failed attempts and record login
## 4. Login Event Tracking
### Implementation
- **Listeners**:
- `RecordSuccessfulLogin`
- `RecordFailedLogin`
- **Status**: ✅ Implemented
### Features
- Automatic tracking of all login attempts
- Records successful logins with timestamp and IP
- Tracks failed login attempts
- Triggers account lockout when threshold reached
## 5. Rate Limiting
### Implementation
- **Middleware**: `ThrottleLoginAttempts`
- **Status**: ✅ Created (needs to be registered)
### Configuration
- **Limit**: 5 attempts per minute per email/IP combination
- **Window**: 60 seconds
- **Response**: 429 Too Many Requests
### To Enable
Add to `bootstrap/app.php` or route middleware:
```php
->withMiddleware(function (Middleware $middleware) {
$middleware->alias([
'throttle.login' => \App\Http\Middleware\ThrottleLoginAttempts::class,
]);
})
```
## 6. Session Security
### Features
- **Inactivity Guard**: Auto-logout after 30 minutes of inactivity
- **Session Timeout Warning**: 1-minute warning before logout
- **Activity Detection**: Monitors change, select, mousemove events
- **Disabled in Local**: For better development experience
## 7. Google reCAPTCHA (Recommended)
### Setup Instructions
1. **Get reCAPTCHA Keys**:
- Visit: https://www.google.com/recaptcha/admin
- Create a new site (reCAPTCHA v3 recommended)
- Get Site Key and Secret Key
2. **Add to `.env`**:
```env
RECAPTCHA_SITE_KEY=your_site_key_here
RECAPTCHA_SECRET_KEY=your_secret_key_here
```
3. **Install Package**:
```bash
composer require google/recaptcha
```
4. **Add to Registration Form**:
```php
// In your registration view
<script src="https://www.google.com/recaptcha/api.js" async defer></script>
<div class="g-recaptcha" data-sitekey="{{ config('services.recaptcha.site_key') }}"></div>
```
5. **Validate in Controller**:
```php
use ReCaptcha\ReCaptcha;
public function register(Request $request)
{
$recaptcha = new ReCaptcha(config('services.recaptcha.secret_key'));
$response = $recaptcha->verify($request->input('g-recaptcha-response'), $request->ip());
if (!$response->isSuccess()) {
return back()->withErrors(['captcha' => 'reCAPTCHA verification failed']);
}
// Continue with registration...
}
```
## 8. Additional Security Recommendations
### A. IP Whitelisting for Admin Panel
```php
// In AdminPanelProvider
->middleware([
\App\Http\Middleware\RestrictAdminAccess::class,
])
```
### B. HTTPS Enforcement
```php
// In AppServiceProvider
if (app()->environment('production')) {
URL::forceScheme('https');
}
```
### C. Security Headers
```php
// Add to middleware
return $response->withHeaders([
'X-Frame-Options' => 'SAMEORIGIN',
'X-Content-Type-Options' => 'nosniff',
'X-XSS-Protection' => '1; mode=block',
'Strict-Transport-Security' => 'max-age=31536000; includeSubDomains',
]);
```
### D. Database Encryption
```php
// For sensitive data
protected $casts = [
'sensitive_field' => 'encrypted',
];
```
## 9. Monitoring & Logging
### System Logs Table
- **Location**: `system_logs` table
- **Features**:
- Ticket-based error tracking
- Priority and severity levels
- Stack trace recording
- User and IP tracking
- Resolution workflow
### Security Events to Log
- Failed login attempts
- Account lockouts
- Password changes
- 2FA enable/disable
- Suspicious activity patterns
## 10. Migration Commands
### Run All Security Migrations
```bash
php artisan migrate
```
### Specific Migrations
```bash
# 2FA columns
php artisan migrate --path=database/migrations/2025_10_26_130000_add_two_factor_columns_to_users_table.php
# System logs
php artisan migrate --path=database/migrations/2025_01_24_140800_create_system_logs_table.php
```
## 11. Testing Security Features
### Test Account Lockout
```bash
# Attempt 5 failed logins
# Verify account is locked
# Wait 30 minutes or manually unlock in database
```
### Test Email Verification
```bash
# Register new user
# Check email for verification link
# Verify access is blocked until verified
```
### Test 2FA
```bash
# Enable 2FA in profile
# Logout and login again
# Check email for OTP code
# Verify code works
```
## 12. Security Checklist
- [x] Email verification enabled
- [x] Account lockout after failed attempts
- [x] Login event tracking
- [x] Session timeout (30 minutes)
- [x] 2FA infrastructure ready
- [ ] 2FA enabled (uncomment in AdminPanelProvider)
- [ ] reCAPTCHA on registration
- [ ] Rate limiting middleware registered
- [ ] HTTPS enforced in production
- [ ] Security headers added
- [ ] IP whitelisting for admin (optional)
- [ ] Regular security audits scheduled
## 13. Emergency Procedures
### Unlock User Account
```sql
UPDATE users
SET failed_login_attempts = 0, locked_until = NULL
WHERE email = 'user@example.com';
```
### Disable 2FA for User
```sql
UPDATE users
SET two_factor_secret = NULL,
two_factor_recovery_codes = NULL,
two_factor_confirmed_at = NULL
WHERE email = 'user@example.com';
```
### Clear All Failed Login Attempts
```sql
UPDATE users
SET failed_login_attempts = 0, locked_until = NULL;
```
## 14. Support & Maintenance
### Regular Tasks
- Review system logs weekly
- Monitor failed login patterns
- Update security packages monthly
- Review and update security policies quarterly
- Conduct security audits annually
### Contact
For security concerns, contact: security@zapazime.bg
---
**Last Updated**: October 26, 2025
**Version**: 1.0
**Status**: Production Ready