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

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

{
  "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