Initial commit

2026-03-23 21:37:59 +01:00
commit 2547717edb
2193 changed files with 972171 additions and 0 deletions
--- a/references/SECURITY_OVERVIEW.md
+++ b/references/SECURITY_OVERVIEW.md
@@ -0,0 +1,468 @@
+# Timebank.cc Security Overview
+
+This document provides a comprehensive overview of the authentication and security features implemented in the Timebank.cc application.
+
+## Multi-Guard Authentication System
+
+### Guard Architecture
+The application implements a sophisticated 4-guard authentication system:
+
+- **web**: Individual user accounts (`App\Models\User`) - Base authentication layer
+- **organization**: Non-profit organization profiles (`App\Models\Organization`) 
+- **bank**: Timebank operator profiles (`App\Models\Bank`)
+- **admin**: Administrative profiles (`App\Models\Admin`)
+
+### Profile Relationship Model
+Each User can be associated with multiple elevated profiles through relationships:
+```php
+// User Model Relationships
+$user->organizations()    // Many-to-many via organization_user table
+$user->banksManaged()     // Many-to-many via bank_user table  
+$user->admins()           // Many-to-many via admins_user table
+```
+
+### Guard Switching Mechanism
+
+#### SwitchGuardTrait Implementation
+Located in `app/Traits/SwitchGuardTrait.php`:
+
+```php
+function switchGuard($newGuard, $profile) {
+    // Logout from all other elevated guards
+    foreach (['admin', 'bank', 'organization'] as $guard) {
+        if ($guard !== $newGuard) {
+            Auth::guard($guard)->logout();
+        }
+    }
+    Auth::guard($newGuard)->login($profile);
+    session(['active_guard' => $newGuard]);
+}
+```
+
+**Security Features**:
+- **Mutual Exclusion**: Only one elevated guard active at a time
+- **Base Guard Preservation**: 'web' guard remains active as foundation
+- **Session State Management**: Active guard tracked in session
+
+#### Profile Switch Flow
+Complete authentication flow for elevated profiles:
+
+1. **Intent Registration**: Target profile stored in session
+2. **Relationship Verification**: System validates user association with target profile
+3. **Password Re-Authentication**: Separate password verification required for elevated access
+4. **Legacy Password Migration**: Automatic Cyclos password conversion if applicable
+5. **Guard Switch**: Authentication state transition using SwitchGuardTrait
+6. **Session Update**: Active profile context establishment
+7. **Event Broadcasting**: Real-time profile switch notification
+
+#### Direct Login Routes for Non-User Profiles
+Secure direct links to elevated profile logins for use in emails and external communications:
+
+**Route Structure:**
+```php
+// Organization
+GET /organization/{organizationId}/login
+Route name: 'organization.direct-login'
+
+// Bank
+GET /bank/{bankId}/login
+Route name: 'bank.direct-login'
+
+// Admin
+GET /admin/{adminId}/login
+Route name: 'admin.direct-login'
+```
+
+**Layered Authentication Flow:**
+1. **Profile Existence Validation**: System verifies target profile exists (404 if not found)
+2. **User Authentication Check**:
+   - If user not authenticated on 'web' guard → redirect to user login
+   - Stores return URL in `session('url.intended')` for post-login redirect
+   - Custom `LoginResponse` allows redirect back to profile switch after user auth
+3. **Relationship Authorization**: Verifies user owns/manages target profile (403 if denied)
+4. **Profile Switch**:
+   - **Organizations**: Direct guard switch without password (passwordless)
+   - **Banks/Admins**: Sets session variables for profile password page
+5. **Password Re-Authentication** (Banks/Admins only): Redirects to profile-specific password entry
+6. **Guard Switch & Redirect**: Switches guard and redirects to intended URL or main page
+
+**Security Features:**
+- **Multi-Layer Verification**: Requires both user authentication AND profile relationship
+- **Differentiated Authentication**:
+  - **Organizations**: Passwordless switch (matches in-app profile switching behavior)
+  - **Banks**: Separate password required for elevated financial privileges
+  - **Admins**: Separate password required for administrative access
+- **Session Isolation**: Each profile type uses dedicated session keys
+- **Intended URL Validation**: Only allows redirects to profile login routes during user auth phase
+- **Automatic Cleanup**: Session variables cleared after successful authentication
+- **Access Control**:
+  - Organizations: Verified via `organization_user` pivot table
+  - Banks: Verified via `bank_managers` pivot table
+  - Admins: Verified via `admin_user` pivot table
+
+**Session Variables Used:**
+```php
+// Common for all types
+'url.intended'                    // Laravel's intended URL (user login phase)
+'intended_profile_switch_type'    // Target profile type (Organization|Bank|Admin)
+'intended_profile_switch_id'      // Target profile ID
+
+// Profile-specific final redirects
+'organization_login_intended_url' // Post-organization-login destination
+'bank_login_intended_url'         // Post-bank-login destination
+'admin_login_intended_url'        // Post-admin-login destination
+```
+
+**Implementation Locations:**
+- Controllers: `OrganizationLoginController`, `BankLoginController`, `AdminLoginController`
+- Custom Response: `app/Http/Responses/LoginResponse.php` (handles user login redirects)
+- Routes: `routes/web.php` (lines 434, 448, 462)
+- Documentation: `references/PROFILE_DIRECT_LOGIN.md`
+
+**Use Case Examples:**
+```php
+// Email notification to organization manager
+route('organization.direct-login', [
+    'organizationId' => $org->id,
+    'intended' => route('event.approve', $event->id)
+])
+
+// Bank transaction alert
+route('bank.direct-login', [
+    'bankId' => $bank->id,
+    'intended' => route('transaction.review', $tx->id)
+])
+
+// Admin moderation request
+route('admin.direct-login', [
+    'adminId' => $admin->id,
+    'intended' => route('report.handle', $report->id)
+])
+```
+
+This feature maintains the security principle of layered authentication while providing seamless deep-linking capabilities for email workflows.
+
+### Session-Based Profile Management
+
+#### Global Helper Functions
+Located in `app/Helpers/ProfileHelper.php`:
+
+- **getActiveProfile()**: Retrieves current active profile model from session
+- **getActiveProfileType()**: Returns profile type name (User, Organization, Bank, Admin)
+- **userOwnsProfile()**: Verifies user ownership of profile through relationships
+
+#### Session Data Structure
+Active profile information stored in encrypted session:
+- Profile type (full class name)
+- Profile ID and name
+- Profile photo path
+- Last activity timestamp
+- Active guard identifier
+
+### Custom Middleware Stack
+
+#### SetActiveGuard Middleware
+Ensures Laravel uses the correct guard for each request based on session state.
+
+#### AuthAnyGuard Middleware
+Validates authentication across multiple specified guards, redirecting to login if none are authenticated.
+
+**Usage Pattern**: `middleware(['auth.any:admin,bank,organization,web'])`
+
+### Template Security Integration
+
+#### Custom Blade Directives
+Registered in `AppServiceProvider.php`:
+
+```blade
+@profile('admin')
+    <div>Admin-only content</div>
+@endprofile
+
+@usercan('manage users')
+    <button>Manage Users</button>
+@endusercan
+```
+
+These directives provide secure, session-aware template rendering based on active profile type and permissions.
+
+## Database-Level Security
+
+### Transaction Immutability
+**Critical Financial Security** implemented at MySQL user permission level:
+
+The application database user has restricted permissions where transactions can only be created (INSERT) and read (SELECT), but never modified (UPDATE) or deleted (DELETE). This ensures:
+
+- All transactions are permanent once created
+- Application cannot modify transaction history
+- Complete financial audit trail maintained
+- Prevents accidental or malicious transaction tampering
+
+### Model Security Patterns
+- **Mass Assignment Protection**: Models use selective `$fillable` arrays
+- **Hidden Attributes**: Sensitive fields (passwords, tokens) hidden from serialization
+- **Soft Deletes**: Critical models use soft deletion to preserve data integrity
+
+## Session Security & Timeout Management
+
+### Profile-Specific Timeout Policies
+The system supports configurable timeout periods per profile type:
+- Different timeout durations based on profile privilege level
+- More privileged profiles can have shorter timeout periods
+- Configurable through `config/timebank-cc.php`
+
+### Timeout Security Features
+Implemented in `CheckProfileInactivity` middleware:
+
+#### Graduated Timeout Behavior
+- **Standard Users**: Configurable full logout on timeout
+- **Elevated Profiles**: Configurable graceful demotion to User profile
+- **Security Principle**: Higher privilege levels can have shorter timeouts
+
+#### Activity Tracking Exclusions
+System excludes specific routes (heartbeat, livewire updates) from resetting activity timers to prevent artificial session extension.
+
+#### AJAX-Aware Timeout Responses
+Provides appropriate JSON responses for timeout events in AJAX requests with proper HTTP status codes.
+
+### Session Encryption & Storage
+- **Database Storage**: Sessions stored in database for scalability
+- **Encryption**: All session data encrypted
+- **Configurable Lifetime**: Base session lifetime configurable
+- **Secure Cookies**: HTTPS-only and HttpOnly flags in production
+
+## Livewire Method-Level Authorization
+
+### Protection Against Direct Method Invocation Attacks
+
+**Critical Security Feature** implemented across all admin management Livewire components to prevent unauthorized direct method calls.
+
+#### The Vulnerability
+
+Livewire components present a unique security challenge: the `mount()` method only executes once when the component loads. After that, any public method can be called directly via browser console:
+
+```javascript
+Livewire.find('component-id').call('methodName', parameters)
+```
+
+If authorization is only checked in `mount()`, attackers can bypass these checks by calling methods directly after the component loads.
+
+#### The Solution: RequiresAdminAuthorization Trait
+
+**File**: `app/Http/Livewire/Traits/RequiresAdminAuthorization.php`
+
+All sensitive admin operations use this trait which provides:
+- **ProfileAuthorizationHelper Integration**: Centralized authorization with database-level validation
+- **Cross-Guard Attack Prevention**: Validates authenticated guard matches profile type
+- **IDOR Prevention**: Prevents access to unauthorized profiles
+- **Bank Level Validation**: Only central bank (level=0) can access admin functions
+- **Performance Caching**: Request-scoped caching to avoid repeated checks
+
+#### Protected Components (27 Methods)
+
+1. **Posts/Manage.php** - 7 methods (create, edit, save, delete, undelete, publication control)
+2. **Categories/Manage.php** - 4 methods (create, update, delete operations)
+3. **Tags/Manage.php** - 3 methods (create, update, delete operations)
+4. **Tags/Create.php** - 1 method (create)
+5. **Profiles/Manage.php** - 5 methods (create, update, delete, restore, attach operations)
+6. **Profiles/Create.php** - 1 method (create) - **Critical vulnerability fixed**
+7. **Mailings/Manage.php** - 6 methods (create, save, send, delete operations) - **Bulk delete vulnerability fixed**
+
+#### Usage Pattern
+
+```php
+public function sensitiveOperation($id)
+{
+    // CRITICAL: Authorize admin access at method level
+    $this->authorizeAdminAccess();
+
+    // Now safe to perform the sensitive operation
+    Model::find($id)->update($data);
+}
+```
+
+#### Documentation
+
+See `references/LIVEWIRE_METHOD_AUTHORIZATION_SECURITY.md` for comprehensive documentation including:
+- Complete method inventory
+- Security architecture details
+- Testing requirements
+- Migration guide for new components
+
+## Role-Based Access Control (RBAC)
+
+### Spatie Permissions Integration
+Advanced permission system with hierarchical roles:
+
+#### Role Naming Convention
+```php
+// Pattern: {ProfileType}\{ProfileID}\{role-suffix}
+"Admin\{id}\admin"
+"Bank\{id}\bank-manager"
+"Organization\{id}\organization-manager"
+```
+
+#### Permission Categories
+Granular permissions for different functional areas:
+- **Content Management**: Posts, categories, tags
+- **Profile Management**: User profiles and accounts
+- **Transaction Management**: Financial operations
+- **System Administration**: Platform configuration
+
+#### Permission Checking Implementation
+Custom traits provide methods to verify permissions based on active profile context and role assignments.
+
+## Input Validation & Protection
+
+### CSRF Protection
+- **Implementation**: Laravel's built-in `VerifyCsrfToken` middleware
+- **Scope**: All state-changing requests protected
+- **No Exclusions**: Maximum security with no CSRF bypass routes
+
+### Hidden Captcha Protection
+Time-based form submission validation:
+- **Minimum Submission Time**: Prevents bot submissions
+- **Maximum Submission Time**: Prevents abandoned form attacks
+- **Configurable Timing**: Adjustable timing windows
+
+### Form Validation Security
+Multi-layer validation approach:
+
+#### Authorization Verification
+- Model class existence validation
+- Profile existence verification
+- User association checking through relationships
+- Hash-based verification for sensitive operations
+
+#### Hash-Based Security
+- **Email Verification**: SHA1 hash comparison prevents URL tampering
+- **Timing Attack Protection**: `hash_equals()` prevents timing analysis
+- **Association Validation**: Users must own profiles to perform actions
+
+## Legacy System Security
+
+### Cyclos Password Migration
+Secure migration from legacy Cyclos system:
+
+- **Backward Compatibility**: Supports existing SHA256+salt passwords
+- **Automatic Conversion**: Migrates to Laravel hashing on successful login
+- **One-Time Migration**: Salt removed after conversion
+- **Transparent Process**: Users unaware of password format changes
+
+## Real-Time Security
+
+### WebSocket Authentication
+Integration with Laravel Reverb and WireChat:
+
+#### Multi-Guard Support
+WireChat configured to work with all 4 authentication guards, ensuring real-time features respect the multi-profile system.
+
+#### Presence Tracking Security
+- **Guard-Aware Tracking**: Presence system tracks which guard user is active on
+- **Authentication Verification**: Presence updates only for authenticated users
+- **Profile Context**: Presence reflects current active profile type
+
+### Broadcasting Security
+- **Private Channels**: User-specific channels prevent unauthorized access
+- **Authentication Requirements**: Channels require proper authentication
+- **Event Data Security**: Only necessary profile information broadcast
+
+## Route Protection Strategies
+
+### Layered Middleware Protection
+Multiple middleware combinations for different security levels.
+
+#### Multi-Guard Routes
+Routes can specify multiple acceptable guards for flexible access control.
+
+#### Guard-Specific Routes
+Routes can require specific guard types for profile-type-restricted functionality.
+
+#### Enhanced Security Routes
+High-security routes can combine multiple middleware layers (authentication, session verification, email verification).
+
+## Activity Logging & Monitoring
+
+### Comprehensive Activity Tracking
+Using Spatie ActivityLog package:
+
+#### Profile Switch Logging
+All profile switches logged with:
+- Source and target profile information
+- Timestamp and user context
+- Previous login information
+- Custom log categories
+
+#### Selective Model Logging
+Models configured to log only sensitive attribute changes to balance security with performance.
+
+### Event Broadcasting System
+Profile switches and security events broadcast through:
+- **Private Channels**: User-specific channels prevent eavesdropping
+- **Secure Event Data**: Minimal necessary information broadcast
+- **Queue Processing**: Events processed through authenticated queue system
+
+## Profile Inactivity Management
+
+### Automated Inactivity Detection
+Configurable inactivity policies for:
+- **Search Visibility**: Hide inactive profiles from search results
+- **Messenger Access**: Remove inactive profiles from chat searches
+- **Profile Access**: Control profile page visibility
+- **Labeling**: Visual indicators for inactive status
+
+### Security Implications
+- **Privacy Protection**: Inactive profiles automatically hidden
+- **Reversible Process**: Profiles can be reactivated without data loss
+- **Configurable Behavior**: All inactivity policies configurable
+
+## Email Verification Security
+
+### Multi-Profile Email Verification
+Custom implementation supporting all profile types:
+
+#### Association Verification
+Strict verification that users own the profiles they're attempting to verify through proper relationship checking.
+
+#### Hash Verification Security
+Uses timing-attack-resistant hash comparison for email verification URLs.
+
+## Security Configuration Framework
+
+### Key Configuration Files
+- `config/auth.php`: Multi-guard authentication setup
+- `config/fortify.php`: Authentication feature configuration  
+- `config/permission.php`: Role-based access control settings
+- `config/hidden_captcha.php`: Bot protection timing configuration
+- `config/timebank-cc.php`: Profile timeout and security policies
+
+### Environment Security
+- **Database User Restrictions**: Limited MySQL permissions for application user
+- **Session Security**: Configurable encryption and storage options
+- **Rate Limiting**: Configurable throttling for authentication attempts
+- **Timeout Policies**: Profile-specific session timeout configuration
+
+## Security Best Practices
+
+### Defense in Depth
+- **Multiple Authentication Layers**: Guards + middleware + permissions + database restrictions
+- **Input Validation**: Request validation + model validation + business logic validation
+- **Session Security**: Encryption + timeouts + activity tracking + CSRF protection
+
+### Principle of Least Privilege
+- **Minimal Permissions**: Roles contain only necessary permissions
+- **Profile Isolation**: Elevated profiles automatically timeout to lower privilege
+- **Relationship Verification**: Strict ownership checks before profile access
+
+### Audit & Monitoring
+- **Complete Activity Logging**: All profile actions tracked with configurable retention
+- **Real-time Event Broadcasting**: Immediate notification of security events
+- **Comprehensive Error Logging**: Detailed logging without exposing sensitive data
+
+### Secure Defaults
+- **Encrypted Sessions**: All session data encrypted by default
+- **CSRF Protection**: Universal CSRF verification with no exclusions
+- **Email Verification**: Configurable verification requirements
+- **Password Confirmation**: Required for sensitive operations
+
+This security framework provides robust protection for the time banking platform while maintaining flexibility through comprehensive configuration options.