timebank-cc-public/references/SECURITY_OVERVIEW.md

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:

// 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:

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:

// 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:

// 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:

// 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:

@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:

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

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

// 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.