# KYC Session Management

## Overview

The KYC system now includes automatic session management that allows users to maintain their access to the KYC form without needing to re-enter their access token after refreshing the page.

## Features

### Automatic Session Creation
- When a user accesses the KYC form with a valid token, a session is automatically created
- The session includes the access token and an expiration timestamp
- Default session timeout is 60 minutes (configurable)

### Session Persistence
- Users can refresh the page without losing their session
- Access to `/kyc/form` without token parameter works when session is valid
- The session automatically extends when the user is active on the form
- Session extension happens every 5 minutes if the user has been active in the last 10 minutes

### Session Expiration
- Sessions automatically expire after the configured timeout period
- Expired sessions require users to re-enter their access token
- Clear visual indicators show session status and remaining time

### Security Features
- Sessions are tied to the specific KYC process
- Session data is encrypted and stored securely
- Automatic cleanup of expired sessions
- Session extension only occurs for active users

## Configuration

### Environment Variables

Add the following to your `.env` file:

```env
KYC_SESSION_TIMEOUT_MINUTES=60
```

### Configuration File

The session timeout is configured in `config/kyc.php`:

```php
'session_timeout_minutes' => env('KYC_SESSION_TIMEOUT_MINUTES', 60),
```

## User Experience

### Session Active
When a session is active, users see:
- Green notification bar showing remaining session time
- "Extend Session" button for manual extension
- Automatic session extension during form interaction

### Session Expired
When a session expires, users see:
- Red notification bar indicating session expiration
- Clear instructions to refresh with access token
- Form becomes inaccessible until token is re-entered

### Session Extension
- Automatic extension every 5 minutes for active users
- Manual extension via "Extend Session" button
- Visual feedback when session is extended

## Technical Implementation

### Session Storage
- `kyc_access_token`: The encrypted access token
- `kyc_session_expires_at`: Session expiration timestamp
- `kyc_form_data_*`: Form data for persistence

### Session Validation
The system checks session validity on each request:
- Verifies token exists in session
- Checks expiration timestamp
- Validates token against KYC process

### Session Extension
- Monitors user activity (mouse, keyboard, touch events)
- Extends session automatically for active users
- Updates expiration timestamp in session

### Session Cleanup
- Automatic cleanup of expired sessions
- Manual cleanup after form submission
- Session data removal on logout

## API Methods

### KycForm Component Methods

```php
// Check if session is valid
public function isKycSessionValid(): bool

// Extend session timeout
public function extendKycSession(): void

// Clear session data
public function clearKycSession(): void

// Get remaining session time
public function getRemainingSessionTime(): int

// Extend session on user activity
public function extendSessionOnActivity(): void

// Check session status
public function checkSessionStatus(): array

// Clean up session after submission
public function cleanupSessionOnSubmit(): void
```

## Routes

The system supports two access methods:

- `GET /kyc/form/{token}` - Access with token parameter (creates session)
- `GET /kyc/form` - Session-based access (requires valid session)

## JavaScript Integration

The system includes JavaScript for automatic session management:

- Activity monitoring (mouse, keyboard, touch events)
- Automatic session extension every 5 minutes
- Session status updates via Livewire events
- Cleanup on page unload

## Testing

Run the session management tests:

```bash
php artisan test tests/Feature/KycSessionManagementTest.php
```

## Security Considerations

1. **Session Isolation**: Each KYC process has its own session
2. **Token Encryption**: Access tokens are encrypted in session storage
3. **Automatic Expiration**: Sessions expire automatically to prevent indefinite access
4. **Activity Monitoring**: Only active users get session extensions
5. **Secure Cleanup**: Session data is properly cleaned up on expiration

## Troubleshooting

### Session Not Persisting
- Check session configuration in `config/session.php`
- Verify session driver is properly configured
- Check for session conflicts

### Session Expiring Too Quickly
- Adjust `KYC_SESSION_TIMEOUT_MINUTES` in configuration
- Check user activity monitoring
- Verify JavaScript is loading properly

### Session Extension Not Working
- Check browser console for JavaScript errors
- Verify Livewire is properly configured
- Check network connectivity for AJAX requests

## Migration Notes

This feature is backward compatible and doesn't require database migrations. Existing KYC processes will continue to work normally, with the added benefit of session management for new access attempts.