Todo/PWA_AUTH_GUIDE.md

# PWA Authentication Guide

## Overview

The Ultimate Lists App PWA has been updated to handle authentication properly in offline scenarios. This guide explains how the service worker manages authentication-related requests and what users can expect when offline.

## Service Worker Updates

### Cache Version

The service worker cache has been updated to version 2 (`ultimate-lists-v2`) to ensure proper cache invalidation and updates.

### Authentication Pages Caching

The following authentication-related pages are now cached during service worker installation:

- `/auth/login` - Login page
- `/auth/register` - Registration page  
- `/auth/error` - Authentication error page

This allows users to view these pages even when offline, though actual authentication requires an internet connection.

### Authentication Request Handling

#### API Authentication Requests (`/api/auth/*`)

Authentication API calls (login, register, session validation) always require a network connection. When offline:

- The service worker returns a 503 Service Unavailable response
- A JSON error message explains that authentication requires internet connectivity
- The error message: "Authentication requires an internet connection. Please check your connection and try again."

#### Authentication Pages (`/auth/*`)

Authentication pages use a cache-first strategy with network fallback:

1. Try to fetch the latest version from the network
2. Cache successful responses for offline access
3. If offline, serve the cached version
4. If no cached version exists, redirect to the offline page

### Authentication Error Handling

The service worker now properly handles authentication errors (401, 403):

- Authentication errors are **not cached**
- This prevents stale authentication states from being served
- Users always get fresh authentication status from the server

### Offline Page Enhancements

The offline page (`/app/offline/page.tsx`) has been enhanced with:

1. **Online Detection**: Automatically detects when the connection is restored
2. **Auto-redirect**: Redirects to the home page when back online
3. **Authentication Notice**: Displays a clear message that login/registration requires internet
4. **Visual Feedback**: Shows different states for offline vs. back online

## User Experience

### When Online

- All authentication features work normally
- Login, registration, and session management function as expected
- Pages are cached for faster subsequent loads

### When Offline

#### Authenticated Users

- Can view cached lists and tasks
- Can make changes that will sync when back online
- Session remains valid (until expiration)
- Cannot perform new authentication actions

#### Unauthenticated Users

- Can view cached authentication pages (login/register forms)
- Cannot actually log in or register (requires internet)
- See clear error messages explaining the need for connectivity
- Are directed to the offline page with authentication guidance

## Testing Offline Behavior

### Manual Testing

1. **Test Offline Login Attempt**:
   - Open the app while online
   - Navigate to `/auth/login`
   - Disconnect from the internet (or use DevTools offline mode)
   - Try to submit login credentials
   - Verify error message appears

2. **Test Cached Authentication Pages**:
   - Visit `/auth/login` while online
   - Disconnect from the internet
   - Refresh the page
   - Verify the login page loads from cache

3. **Test Online Detection**:
   - Navigate to `/offline` while offline
   - Reconnect to the internet
   - Verify automatic redirect to home page

### Chrome DevTools Testing

1. Open Chrome DevTools (F12)
2. Go to Application tab → Service Workers
3. Check "Offline" to simulate offline mode
4. Test authentication flows
5. Verify cache contents in Application → Cache Storage

## Technical Implementation

### Service Worker Strategy

```javascript
// Authentication API calls - Network only
if (url.pathname.startsWith('/api/auth/')) {
  // Always try network, return 503 if offline
}

// Authentication pages - Cache-first with network fallback
if (url.pathname.startsWith('/auth/')) {
  // Try network, fall back to cache, then offline page
}
```

### Error Response Format

When authentication API calls fail offline:

```json
{
  "error": "Authentication requires an internet connection. Please check your connection and try again."
}
```

### Cache Strategy Summary

| Resource Type | Strategy | Offline Behavior |
|--------------|----------|------------------|
| Authentication API | Network only | Return 503 error |
| Authentication Pages | Cache-first | Serve cached version |
| Static Assets | Cache-first | Serve cached version |
| API Responses | Stale-while-revalidate | Serve cached, update in background |
| Regular Pages | Stale-while-revalidate | Serve cached or offline page |

## Security Considerations

1. **No Credential Caching**: User credentials are never cached by the service worker
2. **Session Validation**: Sessions are validated server-side on each request
3. **Error State Handling**: Authentication errors (401, 403) are not cached
4. **Secure Token Storage**: Session tokens are managed by NextAuth.js, not the service worker

## Future Enhancements

Potential improvements for authentication in offline scenarios:

- Queue authentication attempts for when connection is restored
- Show estimated time until session expiration
- Provide offline-specific UI hints for authenticated users
- Implement background sync for authentication state updates

## Troubleshooting

### Service Worker Not Updating

If changes aren't reflected:

1. Unregister the old service worker in DevTools
2. Clear cache storage
3. Hard refresh the page (Ctrl+Shift+R)

### Authentication Not Working Offline

This is expected behavior. Authentication requires:

- Active internet connection
- Server communication for credential validation
- Session token generation and validation

### Cached Pages Showing Old Content

The service worker updates cached pages when online. To force an update:

1. Ensure you're online
2. The service worker checks for updates every minute
3. Or manually update in DevTools → Application → Service Workers → Update