482 lines
16 KiB
Markdown
482 lines
16 KiB
Markdown
# Story 1.2: Authentication & Role System
|
|
|
|
## Status
|
|
Draft
|
|
|
|
## Epic Reference
|
|
**Epic 1:** Core Foundation & Infrastructure
|
|
|
|
## Story
|
|
**As an** admin,
|
|
**I want** a secure authentication system with Admin/Client roles,
|
|
**So that** only authorized users can access the platform with appropriate permissions.
|
|
|
|
## Acceptance Criteria
|
|
|
|
### Functional Requirements
|
|
1. [ ] Fortify configured with custom Volt views
|
|
2. [ ] Login page with bilingual support (Arabic/English)
|
|
3. [ ] Session timeout after 2 hours of inactivity
|
|
4. [ ] Rate limiting on login attempts (5 attempts per minute)
|
|
5. [ ] Admin role with full access to all features
|
|
6. [ ] Client role with restricted access (own data only)
|
|
7. [ ] Registration feature DISABLED (admin creates all accounts)
|
|
|
|
### Security Requirements
|
|
8. [ ] CSRF protection enabled on all forms
|
|
9. [ ] Password hashing using bcrypt
|
|
10. [ ] Custom middleware for admin authorization
|
|
11. [ ] Secure session configuration
|
|
12. [ ] Remember me functionality (optional)
|
|
|
|
### Integration Requirements
|
|
13. [ ] Login redirects to appropriate dashboard:
|
|
- Admin users → `/admin/dashboard` (placeholder until Epic 6)
|
|
- Client users → `/client/dashboard` (placeholder until Epic 7)
|
|
14. [ ] Logout clears session properly and redirects to login page
|
|
15. [ ] Admin middleware protects admin-only routes (return 403 for unauthorized)
|
|
16. [ ] Failed login attempts logged to `admin_logs` table
|
|
17. [ ] Deactivated users cannot log in
|
|
|
|
### Quality Requirements
|
|
18. [ ] Login form validates inputs properly
|
|
19. [ ] Error messages are clear and bilingual
|
|
20. [ ] All test scenarios in "Testing" section pass
|
|
21. [ ] No security vulnerabilities
|
|
|
|
## Tasks / Subtasks
|
|
|
|
- [ ] **Task 1: Configure Fortify** (AC: 1, 7)
|
|
- [ ] Update `config/fortify.php` to disable registration feature
|
|
- [ ] Keep `resetPasswords` enabled (admin-triggered only via future Epic)
|
|
- [ ] Keep `emailVerification`, `updateProfileInformation`, `updatePasswords` enabled
|
|
- [ ] Keep `twoFactorAuthentication` enabled with confirm options
|
|
|
|
- [ ] **Task 2: Add User Model Helper Methods** (AC: 5, 6)
|
|
- [ ] Add `isAdmin(): bool` method to `app/Models/User.php`
|
|
- [ ] Add `isClient(): bool` method to `app/Models/User.php`
|
|
- [ ] Add `isIndividual(): bool` method to `app/Models/User.php`
|
|
- [ ] Add `isCompany(): bool` method to `app/Models/User.php`
|
|
|
|
- [ ] **Task 3: Create Custom Middleware** (AC: 10, 15, 17)
|
|
- [ ] Create `app/Http/Middleware/EnsureUserIsAdmin.php`
|
|
- [ ] Create `app/Http/Middleware/EnsureUserIsActive.php`
|
|
- [ ] Register middleware aliases in `bootstrap/app.php` as `admin` and `active`
|
|
- [ ] Add `SetLocale` middleware to web group (for bilingual support)
|
|
|
|
- [ ] **Task 4: Create Login Volt Component** (AC: 1, 2, 8, 12, 18, 19)
|
|
- [ ] Create `resources/views/livewire/auth/login.blade.php` as class-based Volt component
|
|
- [ ] Implement form with email and password fields using Flux UI components
|
|
- [ ] Add remember me checkbox
|
|
- [ ] Add CSRF token via `@csrf` or Livewire handling
|
|
- [ ] Display validation errors in current locale
|
|
- [ ] Add language switcher or respect current locale
|
|
|
|
- [ ] **Task 5: Configure Login Redirect Logic** (AC: 13, 14)
|
|
- [ ] Update `FortifyServiceProvider` to set custom login view
|
|
- [ ] Create `app/Actions/Fortify/RedirectIfAuthenticated.php` or configure in `AuthenticatedSessionController`
|
|
- [ ] Implement redirect logic: admin → `/admin/dashboard`, client → `/client/dashboard`
|
|
- [ ] Create placeholder routes for dashboards (return simple "Dashboard coming soon" view)
|
|
- [ ] Implement logout redirect to login page
|
|
|
|
- [ ] **Task 6: Implement Session and Rate Limiting** (AC: 3, 4)
|
|
- [ ] Set `SESSION_LIFETIME=120` in `.env` (2 hours)
|
|
- [ ] Verify Fortify's built-in rate limiting (5 attempts per minute)
|
|
- [ ] Ensure rate limit error message uses translation key
|
|
|
|
- [ ] **Task 7: Implement Login Attempt Logging** (AC: 16)
|
|
- [ ] Create listener for `Illuminate\Auth\Events\Failed` event
|
|
- [ ] Log failed attempts to `admin_logs` table with IP address
|
|
- [ ] Register listener in `EventServiceProvider` or `AppServiceProvider`
|
|
|
|
- [ ] **Task 8: Implement Deactivated User Check** (AC: 17)
|
|
- [ ] Add check in `EnsureUserIsActive` middleware
|
|
- [ ] Or customize Fortify's `authenticateUsing` callback to reject deactivated users
|
|
- [ ] Return bilingual error message for deactivated accounts
|
|
|
|
- [ ] **Task 9: Write Tests** (AC: 20)
|
|
- [ ] Create `tests/Feature/Auth/LoginTest.php` with all login flow tests
|
|
- [ ] Create `tests/Feature/Auth/AuthorizationTest.php` for middleware tests
|
|
- [ ] Create `tests/Unit/Models/UserHelperMethodsTest.php` for isAdmin/isClient tests
|
|
- [ ] Run all tests and ensure they pass
|
|
|
|
- [ ] **Task 10: Final Verification** (AC: 21)
|
|
- [ ] Run `vendor/bin/pint` to format code
|
|
- [ ] Verify no security vulnerabilities (CSRF, session fixation, etc.)
|
|
- [ ] Test full login flow in browser for both admin and client users
|
|
|
|
## Dev Notes
|
|
|
|
### Relevant Source Tree
|
|
```
|
|
app/
|
|
├── Actions/
|
|
│ └── Fortify/ # Existing - authentication logic
|
|
│ ├── CreateNewUser.php # Existing
|
|
│ ├── ResetUserPassword.php # Existing
|
|
│ └── UpdateUserPassword.php # Existing
|
|
├── Http/
|
|
│ └── Middleware/ # Create these
|
|
│ ├── SetLocale.php
|
|
│ ├── EnsureUserIsAdmin.php
|
|
│ └── EnsureUserIsActive.php
|
|
├── Models/
|
|
│ └── User.php # Existing - add helper methods
|
|
├── Providers/
|
|
│ └── FortifyServiceProvider.php # Existing - configure views
|
|
bootstrap/
|
|
└── app.php # Register middleware aliases
|
|
config/
|
|
├── fortify.php # Configure features
|
|
└── session.php # Session configuration
|
|
resources/
|
|
└── views/
|
|
└── livewire/
|
|
└── auth/
|
|
└── login.blade.php # Create - Volt component
|
|
lang/
|
|
├── ar/
|
|
│ └── auth.php # Translation strings
|
|
└── en/
|
|
└── auth.php # Translation strings
|
|
tests/
|
|
├── Feature/
|
|
│ └── Auth/
|
|
│ ├── LoginTest.php
|
|
│ └── AuthorizationTest.php
|
|
└── Unit/
|
|
└── Models/
|
|
└── UserHelperMethodsTest.php
|
|
```
|
|
|
|
### User Model Helper Methods (Add to User.php)
|
|
```php
|
|
// app/Models/User.php
|
|
use App\Enums\UserType;
|
|
use App\Enums\UserStatus;
|
|
|
|
public function isAdmin(): bool
|
|
{
|
|
return $this->user_type === UserType::Admin;
|
|
}
|
|
|
|
public function isClient(): bool
|
|
{
|
|
return in_array($this->user_type, [UserType::Individual, UserType::Company]);
|
|
}
|
|
|
|
public function isIndividual(): bool
|
|
{
|
|
return $this->user_type === UserType::Individual;
|
|
}
|
|
|
|
public function isCompany(): bool
|
|
{
|
|
return $this->user_type === UserType::Company;
|
|
}
|
|
|
|
public function isActive(): bool
|
|
{
|
|
return $this->status === UserStatus::Active;
|
|
}
|
|
```
|
|
|
|
### Middleware Implementation (from Architecture Section 7.3)
|
|
```php
|
|
// app/Http/Middleware/EnsureUserIsAdmin.php
|
|
class EnsureUserIsAdmin
|
|
{
|
|
public function handle(Request $request, Closure $next): Response
|
|
{
|
|
if (!$request->user()?->isAdmin()) {
|
|
abort(403, __('messages.unauthorized'));
|
|
}
|
|
|
|
return $next($request);
|
|
}
|
|
}
|
|
|
|
// app/Http/Middleware/EnsureUserIsActive.php
|
|
class EnsureUserIsActive
|
|
{
|
|
public function handle(Request $request, Closure $next): Response
|
|
{
|
|
if ($request->user()?->status === UserStatus::Deactivated) {
|
|
Auth::logout();
|
|
$request->session()->invalidate();
|
|
$request->session()->regenerateToken();
|
|
|
|
return redirect()->route('login')
|
|
->with('error', __('auth.account_deactivated'));
|
|
}
|
|
|
|
return $next($request);
|
|
}
|
|
}
|
|
```
|
|
|
|
### Middleware Registration (bootstrap/app.php)
|
|
```php
|
|
// bootstrap/app.php
|
|
->withMiddleware(function (Middleware $middleware) {
|
|
$middleware->web(append: [
|
|
\App\Http\Middleware\SetLocale::class,
|
|
]);
|
|
|
|
$middleware->alias([
|
|
'admin' => \App\Http\Middleware\EnsureUserIsAdmin::class,
|
|
'active' => \App\Http\Middleware\EnsureUserIsActive::class,
|
|
]);
|
|
})
|
|
```
|
|
|
|
### Fortify Configuration
|
|
```php
|
|
// config/fortify.php
|
|
'features' => [
|
|
// Features::registration(), // DISABLED - admin creates accounts
|
|
Features::resetPasswords(),
|
|
Features::emailVerification(),
|
|
Features::updateProfileInformation(),
|
|
Features::updatePasswords(),
|
|
Features::twoFactorAuthentication([
|
|
'confirm' => true,
|
|
'confirmPassword' => true,
|
|
]),
|
|
],
|
|
```
|
|
|
|
### FortifyServiceProvider Setup
|
|
```php
|
|
// app/Providers/FortifyServiceProvider.php
|
|
public function boot(): void
|
|
{
|
|
// Custom login view
|
|
Fortify::loginView(fn () => view('livewire.auth.login'));
|
|
|
|
// Custom authentication logic (optional - for deactivated check)
|
|
Fortify::authenticateUsing(function (Request $request) {
|
|
$user = User::where('email', $request->email)->first();
|
|
|
|
if ($user &&
|
|
Hash::check($request->password, $user->password) &&
|
|
$user->status === UserStatus::Active) {
|
|
return $user;
|
|
}
|
|
|
|
return null;
|
|
});
|
|
}
|
|
```
|
|
|
|
### Login Redirect Logic
|
|
```php
|
|
// app/Providers/FortifyServiceProvider.php or custom response
|
|
// After successful login, redirect based on role:
|
|
if ($user->isAdmin()) {
|
|
return redirect('/admin/dashboard');
|
|
}
|
|
return redirect('/client/dashboard');
|
|
```
|
|
|
|
### Placeholder Dashboard Routes
|
|
```php
|
|
// routes/web.php
|
|
Route::middleware(['auth', 'active'])->group(function () {
|
|
// Admin routes
|
|
Route::middleware('admin')->prefix('admin')->group(function () {
|
|
Route::view('/dashboard', 'livewire.admin.dashboard-placeholder')
|
|
->name('admin.dashboard');
|
|
});
|
|
|
|
// Client routes
|
|
Route::prefix('client')->group(function () {
|
|
Route::view('/dashboard', 'livewire.client.dashboard-placeholder')
|
|
->name('client.dashboard');
|
|
});
|
|
});
|
|
```
|
|
|
|
### Environment Configuration
|
|
```env
|
|
SESSION_LIFETIME=120 # 2 hours in minutes
|
|
SESSION_EXPIRE_ON_CLOSE=false
|
|
```
|
|
|
|
### Translation Keys (lang/en/auth.php and lang/ar/auth.php)
|
|
```php
|
|
// lang/en/auth.php
|
|
return [
|
|
'failed' => 'These credentials do not match our records.',
|
|
'password' => 'The provided password is incorrect.',
|
|
'throttle' => 'Too many login attempts. Please try again in :seconds seconds.',
|
|
'account_deactivated' => 'Your account has been deactivated. Please contact the administrator.',
|
|
];
|
|
|
|
// lang/ar/auth.php
|
|
return [
|
|
'failed' => 'بيانات الاعتماد هذه لا تتطابق مع سجلاتنا.',
|
|
'password' => 'كلمة المرور المقدمة غير صحيحة.',
|
|
'throttle' => 'محاولات تسجيل دخول كثيرة جداً. يرجى المحاولة مرة أخرى بعد :seconds ثانية.',
|
|
'account_deactivated' => 'تم تعطيل حسابك. يرجى الاتصال بالمسؤول.',
|
|
];
|
|
```
|
|
|
|
### Edge Case Behavior
|
|
|
|
**Rate Limiting (5 attempts per minute):**
|
|
- Fortify handles this automatically via `RateLimiter`
|
|
- After 5 failed attempts, shows throttle message in current locale
|
|
- Lockout duration: 60 seconds
|
|
|
|
**Session Timeout (2 hours inactivity):**
|
|
- Configured via `SESSION_LIFETIME=120`
|
|
- When session expires, redirect to login page
|
|
- Intended URL preserved for redirect after re-authentication
|
|
|
|
**Deactivated Account Login Attempt:**
|
|
- Check in `Fortify::authenticateUsing()` callback
|
|
- Reject with `auth.account_deactivated` message
|
|
- User never gets authenticated
|
|
|
|
### Flux UI Components for Login Form
|
|
```blade
|
|
<flux:input type="email" wire:model="email" label="{{ __('Email') }}" required />
|
|
<flux:input type="password" wire:model="password" label="{{ __('Password') }}" required />
|
|
<flux:checkbox wire:model="remember" label="{{ __('Remember me') }}" />
|
|
<flux:button type="submit" variant="primary">{{ __('Login') }}</flux:button>
|
|
```
|
|
|
|
## Testing
|
|
|
|
### Test Location
|
|
- Feature tests: `tests/Feature/Auth/`
|
|
- Unit tests: `tests/Unit/Models/`
|
|
|
|
### Testing Framework
|
|
Pest 4 with Volt testing support
|
|
|
|
### Feature Tests (tests/Feature/Auth/LoginTest.php)
|
|
|
|
**Login Flow:**
|
|
- [ ] `test_login_page_renders_correctly` - Login page displays
|
|
- [ ] `test_user_can_login_with_valid_credentials` - Valid credentials authenticate
|
|
- [ ] `test_admin_redirects_to_admin_dashboard` - Admin → `/admin/dashboard`
|
|
- [ ] `test_client_redirects_to_client_dashboard` - Client → `/client/dashboard`
|
|
- [ ] `test_invalid_credentials_show_error` - Wrong password shows error
|
|
- [ ] `test_nonexistent_user_shows_error` - Unknown email shows generic error (no enumeration)
|
|
- [ ] `test_deactivated_user_cannot_login` - Deactivated account rejected
|
|
|
|
**Rate Limiting:**
|
|
- [ ] `test_rate_limiting_blocks_after_five_attempts` - 6th attempt blocked
|
|
- [ ] `test_rate_limit_resets_after_cooldown` - Can retry after 60 seconds
|
|
|
|
**Session Management:**
|
|
- [ ] `test_logout_clears_session` - Logout destroys session
|
|
- [ ] `test_authenticated_user_cannot_access_login_page` - Redirect to dashboard
|
|
|
|
### Feature Tests (tests/Feature/Auth/AuthorizationTest.php)
|
|
|
|
**Middleware:**
|
|
- [ ] `test_admin_can_access_admin_routes` - Admin passes `admin` middleware
|
|
- [ ] `test_client_cannot_access_admin_routes` - Client gets 403
|
|
- [ ] `test_unauthenticated_user_redirected_to_login` - Guest redirected
|
|
- [ ] `test_deactivated_user_logged_out_on_request` - Active middleware works
|
|
|
|
### Unit Tests (tests/Unit/Models/UserHelperMethodsTest.php)
|
|
|
|
**Helper Methods:**
|
|
- [ ] `test_isAdmin_returns_true_for_admin_user`
|
|
- [ ] `test_isAdmin_returns_false_for_client_user`
|
|
- [ ] `test_isClient_returns_true_for_individual_user`
|
|
- [ ] `test_isClient_returns_true_for_company_user`
|
|
- [ ] `test_isClient_returns_false_for_admin_user`
|
|
- [ ] `test_isActive_returns_true_for_active_user`
|
|
- [ ] `test_isActive_returns_false_for_deactivated_user`
|
|
|
|
### Test Patterns
|
|
```php
|
|
// tests/Feature/Auth/LoginTest.php
|
|
use App\Models\User;
|
|
use App\Enums\UserType;
|
|
use App\Enums\UserStatus;
|
|
use Livewire\Volt\Volt;
|
|
|
|
test('admin redirects to admin dashboard after login', function () {
|
|
$admin = User::factory()->create([
|
|
'user_type' => UserType::Admin,
|
|
'status' => UserStatus::Active,
|
|
]);
|
|
|
|
$response = $this->post('/login', [
|
|
'email' => $admin->email,
|
|
'password' => 'password',
|
|
]);
|
|
|
|
$response->assertRedirect('/admin/dashboard');
|
|
$this->assertAuthenticatedAs($admin);
|
|
});
|
|
|
|
test('deactivated user cannot login', function () {
|
|
$user = User::factory()->create([
|
|
'status' => UserStatus::Deactivated,
|
|
]);
|
|
|
|
$response = $this->post('/login', [
|
|
'email' => $user->email,
|
|
'password' => 'password',
|
|
]);
|
|
|
|
$this->assertGuest();
|
|
});
|
|
|
|
test('client cannot access admin routes', function () {
|
|
$client = User::factory()->create([
|
|
'user_type' => UserType::Individual,
|
|
]);
|
|
|
|
$this->actingAs($client)
|
|
->get('/admin/dashboard')
|
|
->assertForbidden();
|
|
});
|
|
```
|
|
|
|
## Definition of Done
|
|
|
|
- [ ] Login page renders correctly in both languages
|
|
- [ ] Users can log in with valid credentials
|
|
- [ ] Invalid credentials show proper error (bilingual)
|
|
- [ ] Deactivated users cannot log in
|
|
- [ ] Rate limiting prevents brute force (5 attempts/minute)
|
|
- [ ] Session expires after 2 hours inactivity
|
|
- [ ] Admin routes protected by `admin` middleware (403 for clients)
|
|
- [ ] Failed login attempts logged to `admin_logs`
|
|
- [ ] All Feature and Unit tests pass
|
|
- [ ] Code formatted with `vendor/bin/pint`
|
|
|
|
## Dependencies
|
|
|
|
- **Story 1.1:** Database schema - provides `users` table with `user_type` enum, `status` enum, and `preferred_language` field
|
|
- **Story 1.3:** Bilingual infrastructure - provides translation files and locale switching (can be developed in parallel)
|
|
|
|
## Risk Assessment
|
|
|
|
| Risk | Impact | Likelihood | Mitigation |
|
|
|------|--------|------------|------------|
|
|
| Security misconfiguration | High | Low | Use Laravel's built-in security features |
|
|
| Rate limiting bypass | Medium | Low | Use Fortify's built-in rate limiter |
|
|
| Session hijacking | High | Low | Use secure session configuration |
|
|
| Middleware registration issues | Low | Medium | Follow architecture Section 7.4 exactly |
|
|
|
|
### Rollback Plan
|
|
- Restore default Fortify configuration
|
|
- Remove custom middleware
|
|
- Revert User model changes
|
|
|
|
## Change Log
|
|
|
|
| Date | Version | Description | Author |
|
|
|------|---------|-------------|--------|
|
|
| Dec 21, 2025 | 1.0 | Initial story draft | SM Agent |
|
|
| Dec 21, 2025 | 2.0 | Complete rewrite: Added Status, Tasks/Subtasks, Dev Notes with Source Tree, fixed middleware naming (admin vs can:admin), fixed redirect paths (/client/dashboard), added User helper methods, aligned with architecture Section 7, added Change Log | Validation Task |
|