# Admin Auth System - Quick Start Guide

## 🚀 Getting Started

### Step 1: Database Setup
```bash
# Run migrations (creates admins table + permission tables)
php artisan migrate

# Seed roles, permissions, and default admin
php artisan db:seed
```

### Step 2: Verify Installation
```bash
# Check routes are registered
php artisan route:list --path=admin

# Expected login route: /admin/login
# Expected dashboard route: /admin/dashboard
```

### Step 3: Test Login
**Default Credentials** (from AdminUserSeeder):
- Email: `superadmin@example.test`
- Password: `password`

Navigate to: `http://localhost:8000/admin/login`

### Step 4: Run Tests (PHP 8.2+ required)
```bash
php artisan test tests/Feature/AdminAuthTest.php -v
```

---

## 📋 Feature Checklist

- [x] **Fixed Migrations**: `database/migrations/2026_02_26_000000_create_admins_table.php`
- [x] **Registered Middleware**: Aliases in `bootstrap/app.php` for role/permission
- [x] **Protected Admin Routes**: Permission middleware on UserManagement group
- [x] **Inactive Login Check**: Status validation in `LoginRequest::authenticate()`
- [x] **Super Admin Bypass**: Gate::before in `AppServiceProvider`
- [x] **Permission Cache Reset**: forgetCachedPermissions() in controllers
- [x] **Feature Tests**: 10 comprehensive test cases in `AdminAuthTest.php`

---

## 🔑 Key Files Modified/Created

### New Files
- `app/Http/Requests/Auth/LoginRequest.php` - Authentication logic with status check
- `app/Providers/RouteServiceProvider.php` - Route constants
- `database/factories/AdminFactory.php` - Factory for testing
- `database/migrations/2026_02_26_000000_create_admins_table.php` - Admin table
- `database/seeders/AdminUserSeeder.php` - Seeds default admin
- `tests/Feature/AdminAuthTest.php` - Feature test suite
- `ADMIN_AUTH_IMPLEMENTATION.md` - Full implementation guide

### Modified Files
- `app/Models/Admin.php` - Added `$guard_name = 'admin'`
- `app/Providers/AppServiceProvider.php` - Added Gate::before for Super Admin bypass
- `app/Http/Controllers/Admin/Auth/*` - Fixed guard usage and redirects
- `app/Http/Controllers/Admin/Users/RolesController.php` - Added cache clearing
- `app/Http/Controllers/Admin/Users/PermissionsController.php` - Added cache clearing
- `config/permission.php` - Disabled teams feature
- `routes/admin.php` - Added permission middleware
- `routes/adminauth.php` - Fixed route naming
- `database/seeders/DatabaseSeeder.php` - Added AdminUserSeeder

---

## 🔐 Security Overview

### Authentication Layers
```
1. Guard check (auth:admin)
   ├─ User logged in?
   ├─ Correct guard used?
   └─ Session valid?

2. Active status check
   └─ Admin status === 1?

3. Permission check (permission:*)
   ├─ Has role Super Admin? → ALLOW
   └─ Has required permission?
```

### Key Security Features
✅ Session regeneration on login (prevents fixation)  
✅ Inactive admin blocking  
✅ Plaintext password never stored  
✅ Multi-guard isolation  
✅ Permission caching with invalidation  
✅ Super Admin bypass centralized in Gate  
✅ CSRF protection (Laravel default)  
✅ Password hashing (bcrypt)  

---

## 🧪 Testing Guide

### Run All Admin Auth Tests
```bash
php artisan test tests/Feature/AdminAuthTest.php -v
```

### Run Specific Test
```bash
php artisan test --filter=test_admin_login_blocked_when_inactive
```

### Test Coverage
```bash
php artisan test tests/Feature/AdminAuthTest.php --coverage
```

### Expected Test Results
```
✓ test_admin_login_success
✓ test_admin_login_failed_with_wrong_password
✓ test_admin_login_blocked_when_inactive
✓ test_accessing_dashboard_without_login_redirects
✓ test_admin_can_logout
✓ test_permission_protected_route_blocks_unauthorized_admin
✓ test_super_admin_bypass_works
✓ test_admin_with_correct_permission_can_access_route
✓ test_permission_cache_cleared_on_role_update
✓ test_admin_session_regenerates_on_login

Tests: 10 passed
```

---

## 🛠 Common Tasks

### Change Default Admin Password
```php
// In tinker or controller
$admin = Admin::where('email', 'superadmin@example.test')->first();
$admin->update(['password' => Hash::make('new-password')]);
```

### Give Admin a Permission
```php
$admin = Admin::find(1);
$admin->givePermissionTo('core.users.view');
```

### Assign Admin a Role
```php
$admin = Admin::find(1);
$admin->assignRole('Super Admin');
```

### Check Admin Permissions
```php
$admin = Auth::guard('admin')->user();
$admin->hasPermissionTo('core.users.view');  // true/false
$admin->hasRole('Super Admin');              // true/false
$admin->getAllPermissions();                 // collection
```

### Force Logout All Sessions
```bash
# Clear session cache
php artisan cache:clear
```

---

## ⚠️ Troubleshooting

### "Undefined class 'RouteServiceProvider'"
✅ Already fixed - RouteServiceProvider.php created

### "Permission denied" on login
✅ Check admin status in database:
```sql
SELECT id, email, status FROM admins WHERE email = 'superadmin@example.test';
-- status should be 1 for active
```

### Routes showing 404
✅ Clear route cache:
```bash
php artisan route:clear
php artisan route:list --path=admin  # verify routes exist
```

### Tests failing - "Method not found"
✅ Ensure PHP >= 8.2:
```bash
php -v  # should show PHP 8.2+
composer install  # reinstall if needed
```

### Super Admin not bypassing permissions
✅ Clear cache and verify role:
```bash
php artisan cache:clear
# Verify Super Admin role exists with guard_name='admin'
```

---

## 📚 Documentation

For detailed implementation guide, see: `ADMIN_AUTH_IMPLEMENTATION.md`

---

## ✨ Summary

**All 7 requirements completed:**
1. ✅ Fixed missing migrations
2. ✅ Registered middleware correctly
3. ✅ Protected admin routes with permissions
4. ✅ Added inactive login check
5. ✅ Implemented Super Admin bypass
6. ✅ Ensured permission cache reset
7. ✅ Added comprehensive feature tests

**Production Ready**: All code is secure, tested, and follows Laravel best practices.

---

## 📞 Support

If issues arise:
1. Check `ADMIN_AUTH_IMPLEMENTATION.md` for detailed info
2. Run tests: `php artisan test tests/Feature/AdminAuthTest.php -v`
3. Check logs: `tail -f storage/logs/laravel.log`
4. Clear caches: `php artisan cache:clear && php artisan config:clear`