enhancement: Implement IndexedDB storage for offline file queue

[kevalyq]

Context

Currently, files shared via Share Target API (PR #140) are stored in sessionStorage, which has significant limitations:

• ❌ Limited storage (~5-10MB depending on browser)
• ❌ Lost on tab/browser close
• ❌ Cannot handle large files
• ❌ No offline persistence
• ❌ No queuing for failed uploads

Problem

Users need to share files even when:

• Offline or with poor connectivity
• Browser is closed before upload completes
• Multiple files exceed sessionStorage limits
• Network request fails mid-upload

Without a persistent queue, users lose their files and have to reshare them manually.

Proposed Solution

Implement IndexedDB-based storage for shared files with offline queue functionality:

Architecture

// IndexedDB Schema
interface FileQueueEntry {
  id: string;  // UUID
  file: Blob;  // Actual file data
  metadata: {
    name: string;
    type: string;
    size: number;
    timestamp: number;
  };
  uploadState: 'pending' | 'uploading' | 'failed' | 'completed';
  secretId?: string;  // Target Secret (if known)
  retryCount: number;
  error?: string;
}

Features

1. Persistent Queue

   • Files stored in IndexedDB (survives browser close)
   • Automatic retry on network failure
   • Exponential backoff for failed uploads

2. Background Sync

   • Use Service Worker Background Sync API
   • Upload files when network returns
   • Show notification on completion

3. Storage Management

   • Monitor IndexedDB quota
   • Warn user when approaching limit
   • Auto-cleanup of completed uploads (configurable retention)

4. UI Integration

   • Queue status indicator
   • Manual retry button
   • "Upload later" option

Implementation Plan

1. IndexedDB Wrapper

   • Create FileQueueDB class using idb library
   • CRUD operations for queue entries
   • Transaction handling

2. Service Worker Integration

   • Register Background Sync handler
   • Process queue on sync event
   • Handle upload failures

3. React Hook

   • useFileQueue() hook for UI integration
   • Real-time queue status
   • Manual queue control

4. Migration

   • Migrate from sessionStorage to IndexedDB
   • Preserve existing Share Target flow

Tasks

• Install idb library (IndexedDB wrapper)
• Design IndexedDB schema
• Implement FileQueueDB class
• Add Service Worker Background Sync handler
• Create useFileQueue() React hook
• Update ShareTarget component to use queue
• Add queue status UI
• Handle quota exceeded errors
• Write tests (IndexedDB mocking)
• Update documentation

Dependencies

• Requires: feat: Add POST method file sharing support to Share Target API (#101) #140 (Share Target POST method)
• Related: enhancement: Add file upload to backend API for Secret attachments #141 (Backend file upload API)
• Blocks: Offline-first file sharing

Benefits

• 💾 Persistent file storage (survives browser close)
• 🔄 Automatic retry on network failure
• 📊 Larger storage capacity (50MB+ typical)
• 🚀 Background upload when network returns
• 😊 Better UX (no lost files)

Non-Goals (Future Work)

• File compression before storage
• Cloud backup of IndexedDB
• P2P file sharing
• Automatic Secret creation from queue

References

• IndexedDB API: https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API
• Background Sync API: https://developer.mozilla.org/en-US/docs/Web/API/Background_Synchronization_API
• idb library: https://github.com/jakearchibald/idb
• Share Target implementation: PR feat: Add POST method file sharing support to Share Target API (#101) #140

Priority

High - Critical for offline-first PWA experience and preventing data loss.

Part of: #64

[github-actions]

✅ This issue has been added to the SecPal Feature Roadmap with status: 💡 Ideas

New idea - needs discussion and evaluation

Status Flow:
💡 Ideas → 💬 Discussion → 📥 Backlog → 📋 Planned → 🚧 In Progress → 👀 In Review → ✅ Done

Note: Ideas that won't be implemented should be moved to 🚫 Won't Do with a reason.