# Multi-Guard Permission System Fixes - 2026-01-03

## Summary

Fixed critical permission checking errors in the multi-guard authentication system that were causing "Permission does not exist for guard" errors when users attempted to switch profiles or edit Organization/Bank profiles. All authorization security tests now passing (60/60).

## Issues Identified

### 1. CanOnWebGuard Middleware - Strict Permission Checking
**File**: `app/Http/Middleware/CanOnWebGuard.php:13`

**Problem**: Used `hasPermissionTo($permission, 'web')` which strictly validates that the permission record exists for the specific guard. This threw exceptions for permissions that exist as Gates but not as database records for the 'web' guard.

**Impact**:
- Routes with `user.can:manage organizations` middleware failed
- Organization/Bank profile editing pages returned 500 errors
- Session expiry on profile pages caused crashes

**Solution**: Changed to `can($permission)` method which works with both database permissions and Gate definitions, providing flexibility for the multi-guard system.

### 2. Gate Definitions - Missing Error Handling
**File**: `app/Providers/AuthServiceProvider.php:65-99`

**Problem**: Gate definitions for 'manage organizations', 'manage banks', 'manage admins' didn't have proper exception handling and instanceof checks.

**Impact**: Gates could throw exceptions when called with non-User instances (Organization/Bank/Admin models).

**Solution**: Added try-catch blocks and instanceof checks to ensure Gates only work with User models and gracefully return false for errors.

### 3. @usercan Blade Directive - Cross-Guard Permission Checking
**File**: `app/Providers/AppServiceProvider.php:106-130`

**Problem**: Directive checked active profile's permissions instead of the web user's permissions. In the multi-guard system, all permissions are stored on the 'web' guard only.

**Impact**: Navigation links disappeared when switched to Organization/Bank/Admin profiles because those models don't have permission records.

**Solution**: Rewrote directive to always check the web user's permissions using `can()` with proper error handling.

### 4. Profile Form Components - Middleware and Permission Checks
**Files**:
- `app/Http/Livewire/ProfileOrganization/UpdateProfileOrganizationForm.php`
- `app/Http/Livewire/ProfileBank/UpdateProfileBankForm.php`
- `app/Http/Livewire/ProfileUser/UpdateProfilePersonalForm.php`
- `app/Http/Livewire/Profile/UpdateSettingsForm.php`

**Problem**:
- Component middleware checked permissions on wrong guard
- Mount methods used `hasPermissionTo()` instead of `can()`

**Impact**: Could not access organization/bank profile edit pages even with proper permissions.

**Solution**:
- Commented out component middleware (moved authorization to mount() method)
- Changed all permission checks from `hasPermissionTo()` to `can()`
- Ensured all checks validate against web user, not active profile

### 5. Profile Switching Authorization - Cross-Guard Blocking
**File**: `app/Http/Livewire/SwitchProfile.php:193`

**Problem**: Used `ProfileAuthorizationHelper::can()` which enforces cross-guard protection. During profile switching, user is on 'web' guard trying to access 'admin'/'bank'/'organization' guard profile, so cross-guard check blocked the switch.

**Impact**: Users could not switch from User profile to Organization/Bank/Admin profiles, seeing "Unauthorized profile switch attempt" errors.

**Solution**: Created and used `ProfileAuthorizationHelper::userOwnsProfile()` method specifically for profile switching that checks ownership without cross-guard enforcement.

## Files Modified

### Core Authorization Infrastructure

1. **app/Http/Middleware/CanOnWebGuard.php** (lines 10-21)
   - Changed from `hasPermissionTo($permission, 'web')` to `can($permission)`
   - Added explanatory comments about multi-guard system

2. **app/Providers/AuthServiceProvider.php** (lines 65-99)
   - Updated Gate definitions for 'manage banks', 'manage organizations', 'manage admins'
   - Added try-catch blocks and instanceof checks
   - Changed from `hasPermissionTo()` to `can()`

3. **app/Providers/AppServiceProvider.php** (lines 106-130)
   - Completely rewrote `@usercan` directive
   - Now always checks web user permissions
   - Added exception handling for missing permissions

### Profile Management Components

4. **app/Http/Livewire/ProfileOrganization/UpdateProfileOrganizationForm.php**
   - Commented out `protected $middleware` (lines 29-34)
   - Updated mount() authorization to check web user (lines 68-76)

5. **app/Http/Livewire/ProfileBank/UpdateProfileBankForm.php**
   - Commented out `protected $middleware` (lines 28-32)
   - Updated mount() authorization to check web user (lines 67-75)

6. **app/Http/Livewire/ProfileUser/UpdateProfilePersonalForm.php**
   - Updated mount() authorization (lines 60-64)

7. **app/Http/Livewire/Profile/UpdateSettingsForm.php**
   - Updated mount() authorization for all profile types (lines 55-80)

### Profile Switching

8. **app/Http/Livewire/SwitchProfile.php** (line 193)
   - Changed from `ProfileAuthorizationHelper::can()` to `ProfileAuthorizationHelper::userOwnsProfile()`

### Test Suite

9. **tests/Feature/Security/Authorization/ProfileAuthorizationHelperTest.php**
   - Updated 5 tests to use `userOwnsProfile()` for cross-guard ownership checks
   - Clarified that direct Admin→Organization or Organization→Bank switching is not supported
   - Application flow requires going through User (web guard) for all profile switches

## Security Test Results

### Before Fixes
- Authorization tests: Multiple failures due to permission errors
- User experience: Could not switch profiles or edit Organization/Bank profiles

### After Fixes
All authorization security tests passing:

```
✓ 21 LivewireMethodAuthorizationTest - Livewire method-level authorization
✓ 21 ExportProfileDataAuthorizationTest - IDOR prevention and data export authorization
✓ 18 ProfileAuthorizationHelperTest - Multi-guard profile access validation

Total: 60/60 tests passing (100%)
```

## Architecture Clarifications

### Permission Storage Model
**Critical Understanding**: In the multi-guard authentication system, ALL permissions are stored only on the 'web' guard. Organization, Bank, and Admin models do NOT have their own permission records.

```php
// ✓ Correct: Always check web user
$webUser = Auth::guard('web')->user();
$webUser->can('manage organizations');

// ✗ Wrong: Organizations don't have permissions
$organization = Auth::guard('organization')->user();
$organization->can('manage organizations'); // Will fail
```

### Profile Switching Flow
**Correct Flow**: User (web guard) → Admin/Organization/Bank

**Incorrect Flow**: Admin → Organization (not supported)

Profile switching requires being authenticated on the 'web' guard first. To switch from Admin to Organization, the user must:
1. Switch back to User profile (web guard)
2. Then switch to Organization profile

This is enforced by `userOwnsProfile()` which only checks the web guard user.

### Method Usage Guide

**ProfileAuthorizationHelper Methods**:

1. **can($profile)** - For post-switch authorization
   - Use when: Validating access to profile that user is already switched to
   - Enforces: Guard matching (authenticated guard must match profile type)
   - Example: Livewire component checks in mount()

2. **userOwnsProfile($profile)** - For profile switching
   - Use when: Validating user can switch to a profile
   - Enforces: Relationship checking only (no guard matching)
   - Example: SwitchProfile component

3. **authorize($profile)** - Convenience wrapper
   - Same as `can()` but throws exception instead of returning boolean

## Security Improvements

1. **Consistent Permission Checking**: All permission checks now use `can()` which works with both database permissions and Gates
2. **Proper Error Handling**: All permission checks have try-catch blocks to gracefully handle missing permissions
3. **Clear Separation of Concerns**: Profile switching (`userOwnsProfile()`) vs post-switch authorization (`can()`)
4. **Multi-Guard Awareness**: All components now properly check web user permissions regardless of active profile
5. **Documentation**: Updated tests to reflect correct application architecture and flows

## Remaining Test Issues

Note: The broader security test suite has 83 failing tests, but these are **pre-existing failures** unrelated to this work:
- Direct Login Routes (20 failures) - Missing factories and routes
- Multi-Guard Authentication (2 failures) - Route-related issues
- Profile Switching (11 failures) - Session-related test issues
- IDOR tests (7 failures) - Missing factories
- XSS tests (5 failures) - Missing configurations
- SQL Injection tests (2 failures) - Missing factories

These failures are in tests that existed before this work and are not related to the permission system fixes.

## Testing Recommendations

1. **Manual Testing**: Verify profile switching works for all profile types
2. **Permission Testing**: Verify all navigation links appear correctly when switched to different profiles
3. **Form Testing**: Verify organization/bank profile edit pages load and save correctly
4. **Session Testing**: Verify behavior when session expires on profile pages

## Deployment Notes

### Required Steps
1. Clear all Laravel caches: `php artisan optimize:clear`
2. Verify web server has write access to storage directories
3. Monitor logs for any permission-related warnings

### No Migration Required
These changes only affect code, not database structure.

## References

- Multi-Guard Authentication: `references/SECURITY_OVERVIEW.md`
- Livewire Authorization: `references/LIVEWIRE_METHOD_AUTHORIZATION_SECURITY.md`
- ProfileAuthorizationHelper: `app/Helpers/ProfileAuthorizationHelper.php`