ai-stylegallery/prp/authentication-authorization.md

Authentication and Authorization Specification

Overview

Comprehensive authentication and authorization system using Laravel Sanctum for API authentication and Filament for admin panel access control, with role-based permissions and security best practices.

Authentication Architecture

Laravel Sanctum Integration

Purpose: Provides API authentication for SPA applications

Token Management:

• Token Storage: Database storage with automatic expiration
• Token Types: Personal access tokens with configurable abilities
• Security: CSRF protection and secure token generation

Frontend Integration:

// Login process
axios.post('/login', credentials)
  .then(response => {
    // Store token securely
    localStorage.setItem('api_token', response.data.token);
    // Set default authorization header
    axios.defaults.headers.common['Authorization'] = `Bearer ${response.data.token}`;
  });

Session-Based Authentication

Purpose: Traditional web session management for admin panel

Implementation:

• Laravel Breeze scaffolding for basic auth
• Session cookies for state management
• CSRF protection for form submissions

User Model and Roles

User Model

Location: app/Models/User.php

Key Attributes:

// Authentication
email: string (unique)              // Primary login identifier
password: string (hashed)           // Secure password hash
email_verified_at: timestamp        // Email verification status

// Authorization
role_id: bigint unsigned (nullable) // Foreign key to roles table

// Two-Factor Authentication
two_factor_secret: text (nullable)  // TOTP secret key
two_factor_recovery_codes: text (nullable)  // Backup recovery codes
two_factor_confirmed_at: timestamp (nullable)  // 2FA confirmation

// Preferences
email_notifications_enabled: boolean (default: true)  // Notification preferences
theme_preference: string (default: 'light')           // UI theme
locale: string (default: 'en')                        // Language preference

Role-Based Access Control

Role Model:

// Simple role system
id: bigint unsigned auto_increment primary key
name: varchar(255) unique          // Role identifier ('admin', 'user')
created_at, updated_at: timestamps

Predefined Roles:

• admin: Full system access, user management, configuration
• user: Standard user access, personal gallery management

Role Assignment:

// Default role assignment (in migration)
$usersTable->foreignId('role_id')->constrained()->default(2); // Defaults to 'user' role

// Role checking
$user->role->name === 'admin'
$user->role?->name === 'admin' // Safe null checking

Authorization Mechanisms

API Authorization

Protected Routes:

// routes/api.php
Route::middleware('auth:sanctum')->group(function () {
    Route::post('/api/images/keep', [ImageController::class, 'keepImage']);
    Route::delete('/api/images/{image}', [ImageController::class, 'deleteImage']);
    Route::get('/api/user', function (Request $request) {
        return $request->user();
    });
});

Middleware Stack:

1. auth:sanctum: Validates bearer token
2. Custom Logic: Additional business rule validation

Admin Panel Authorization

Filament Integration:

• Built-in authentication for /admin routes
• Session-based admin access
• Automatic logout on inactivity

Access Control:

// Filament panel configuration
->requirePasswordResetAfterLogin(false)
->passwordReset()
->emailVerification()
->twoFactorAuthentication()

Security Measures

Password Security

Hashing Algorithm:

• Laravel default: bcrypt with cost factor 12
• Future migration path to Argon2

Password Requirements:

• Minimum 8 characters
• Mixed case letters
• Numbers and special characters
• Not in common password lists

Two-Factor Authentication

Implementation:

• TOTP (Time-based One-Time Password) standard
• Google Authenticator, Authy compatibility
• Recovery codes for account recovery

Setup Flow:

1. User enables 2FA in profile settings
2. QR code generated for authenticator app
3. User confirms setup with first TOTP code
4. Recovery codes generated and displayed once

Verification:

// Middleware for 2FA verification
if ($user->two_factor_secret && !$user->two_factor_confirmed_at) {
    return redirect()->route('two-factor.challenge');
}

Session Security

Configuration:

// config/session.php
'secure' => env('SESSION_SECURE_COOKIE', true),    // HTTPS only
'http_only' => true,                               // Prevent XSS access
'same_site' => 'lax',                              // CSRF protection
'expire_on_close' => false,                        // Persistent sessions
'lifetime' => 120,                                 // 2 hour timeout

Admin Session Management:

• Shorter session lifetime for admin users
• Automatic logout on suspicious activity
• Session fixation protection

Permission System

Image Ownership

Business Rules:

• Users can only modify their own images
• Temporary images are tied to processing session
• Public images visible to all authenticated users

Implementation:

// ImageController@deleteImage
public function deleteImage(Image $image)
{
    // Implicit authorization via route model binding
    // User must own the image or be admin
    $this->authorize('delete', $image);
    // or explicit check
    if ($image->user_id !== auth()->id() && !auth()->user()->isAdmin()) {
        abort(403);
    }
}

Admin Permissions

Admin-Only Operations:

• User management (create, edit, delete users)
• System configuration changes
• Plugin and API provider management
• Style and AI model configuration
• Application settings modification

Permission Checking:

// Policy-based authorization
class ImagePolicy
{
    public function delete(User $user, Image $image): bool
    {
        return $user->id === $image->user_id || $user->role->name === 'admin';
    }
}

// Controller usage
$this->authorize('delete', $image);

Security Headers and CSRF Protection

Security Headers

Content Security Policy:

// app/Http/Middleware/SetContentSecurityPolicy.php
$contentSecurityPolicy = [
    'default-src' => ['self'],
    'script-src' => ['self', 'unsafe-inline', 'unsafe-eval'],
    'style-src' => ['self', 'unsafe-inline'],
    'img-src' => ['self', 'data:', 'https:'],
    'connect-src' => ['self', 'ws:', 'wss:'],
];

Other Security Headers:

• X-Frame-Options: SAMEORIGIN - Prevent clickjacking
• X-Content-Type-Options: nosniff - Prevent MIME sniffing
• Referrer-Policy: strict-origin-when-cross-origin - Control referrer info
• Permissions-Policy: camera=(), microphone=(), geolocation=() - Disable unnecessary permissions

CSRF Protection

Laravel CSRF:

• Automatic token generation for forms
• Middleware validation on state-changing requests
• Exception for API routes (handled by Sanctum)

Custom CSRF:

// Verify CSRF token manually if needed
if (!hash_equals($request->session()->token(), $request->input('_token'))) {
    abort(419, 'CSRF token mismatch');
}

Authentication Flows

User Registration

Flow:

1. User submits registration form
2. Validation (email format, password strength, uniqueness)
3. Account creation with default 'user' role
4. Email verification (if enabled)
5. Welcome email sent

Validation Rules:

'email' => 'required|email|unique:users|max:255',
'password' => 'required|min:8|confirmed',
'name' => 'required|string|max:255',

User Login

Flow:

1. User submits credentials
2. Rate limiting applied (5 attempts per minute)
3. Credentials verified against database
4. 2FA challenge if enabled
5. Session/token created
6. Redirect to appropriate interface

Rate Limiting:

// Throttle login attempts
RateLimiter::tooManyAttempts($key, 5) // 5 attempts
RateLimiter::hit($key, 60) // Lock for 60 seconds

Password Reset

Secure Token Flow:

1. User requests password reset
2. Secure token generated and emailed
3. Token validated on reset form
4. Password updated with new hash
5. Old tokens invalidated

Token Security:

• Cryptographically secure random tokens
• Short expiration time (1 hour)
• Single-use tokens

Admin Authentication

Admin Panel Access

Route Protection:

// Admin routes protected by Filament middleware
Route::prefix('admin')->name('admin.')->middleware([
    'auth:sanctum', // API authentication
    // Filament middleware stack
])->group(function () {
    // Admin routes
});

Role-Based Access:

• Only users with 'admin' role can access admin panel
• Automatic redirect for unauthorized users
• Session management for admin activities

Admin User Management

User CRUD Operations:

• Create new users with role assignment
• Edit user details and permissions
• Disable/enable user accounts
• Reset passwords securely

Bulk Operations:

• Mass role assignment
• Account activation/deactivation
• Email notifications for status changes

API Security

Token Management

Token Creation:

// Create personal access token
$token = $user->createToken('api-token', ['read', 'write']);
$plainTextToken = $token->plainTextToken;

Token Abilities:

• read: View images and styles
• write: Upload images and apply styles
• admin: Full administrative access

Token Expiration:

// Create expiring token
$token = $user->createToken('temp-token', ['read'], now()->addHour());

API Rate Limiting

Current Implementation: No explicit rate limiting (rely on external services)

Recommended Limits:

// Per-user rate limits
'api:images:upload' => '5,1',      // 5 uploads per minute
'api:images:style-change' => '3,1', // 3 style changes per minute
'api:admin:*' => '60,1',           // 60 admin actions per minute

Security Monitoring

Audit Logging

Authentication Events:

• Login attempts (success/failure)
• Password changes
• 2FA setup/removal
• Role changes
• Admin actions

Security Events:

• Suspicious login attempts
• Multiple failed authentication attempts
• Admin privilege escalation
• API abuse detection

Intrusion Detection

Failed Login Monitoring:

• Track failed attempts by IP/user
• Automatic account lockout after threshold
• Admin notification for repeated failures

Session Monitoring:

• Concurrent session detection
• Session hijacking prevention
• Unusual activity flagging

Data Protection

Password Storage

• Algorithm: bcrypt with configurable cost
• Salt: Automatic per-password salt generation
• Upgrade Path: Automatic rehash on successful login

Sensitive Data

• API Tokens: Encrypted storage in database
• 2FA Secrets: Encrypted TOTP secrets
• Configuration: Environment variables for sensitive settings

Data Backup Security

• Encrypted database backups
• Secure backup storage locations
• Access logging for backup operations

Compliance Considerations

GDPR Compliance

Data Handling:

• User consent for data processing
• Right to data portability
• Right to be forgotten (account deletion)
• Data processing activity logs

Privacy Features:

• Granular privacy settings
• Data export functionality
• Secure account deletion process

Security Standards

OWASP Compliance:

• Protection against common web vulnerabilities
• Secure coding practices
• Regular security assessments

Industry Standards:

• HTTPS enforcement
• Secure cookie handling
• Input validation and sanitization

Future Security Enhancements

Advanced Authentication

OAuth Integration:

• Social login providers (Google, GitHub)
• Single sign-on capabilities
• Third-party application access

Biometric Authentication:

• WebAuthn/FIDO2 support
• Hardware security key support
• Mobile authenticator integration

Advanced Authorization

Permission-Based Access:

• Granular permissions beyond roles
• Resource-based permissions
• Dynamic permission assignment

Multi-Tenancy:

• Organization-based access control
• Team-based permissions
• Resource isolation

Enhanced Security

Advanced Monitoring:

• Real-time threat detection
• Automated security responses
• Security information and event management (SIEM)

Zero-Trust Architecture:

• Continuous authentication
• Micro-segmentation
• Least privilege access

Deployment Security

Environment Security

Development:

• Debug mode disabled
• Verbose error reporting off
• Test credentials and data

Production:

• HTTPS enforcement
• Secure headers enabled
• Production credentials only

Infrastructure Security

Server Hardening:

• Minimal attack surface
• Regular security updates
• Firewall configuration

Database Security:

• Encrypted database connections
• Minimal privilege accounts
• Regular backup testing

Testing Security Features

Authentication Tests

Unit Tests:

• Password hashing verification
• Token generation and validation
• Role assignment and checking

Integration Tests:

• Complete login/logout flow
• API authentication middleware
• Admin panel access control

Security Tests:

• SQL injection prevention
• XSS vulnerability testing
• CSRF protection validation

Troubleshooting Security

Common Issues

Token Expiration:

• Automatic token refresh mechanisms
• Graceful handling of expired sessions
• User notification and re-authentication

Permission Errors:

• Clear error messages for users
• Detailed logging for administrators
• Permission debugging tools

Session Issues:

• Session fixation protection
• Secure session handling
• Cross-site request forgery prevention