feat(backup): automatic daily OPFS snapshot and silent Drive upload

.fallowrc.json

@@ -160,6 +160,36 @@
         "functions": ["TransactionsPage"],
         "maxCrap": 45,
         "reason": "Page composition wiring search/pagination/delete hooks plus the empty-state and infinite-scroll-sentinel ternaries; coverage-blind CRAP, not accidental complexity."
+      },
+      {
+        "files": ["src/components/more/backup/AutoBackupStatus.tsx"],
+        "functions": ["AutoBackupStatus"],
+        "maxCrap": 120,
+        "reason": "Quiet status row rendering: safety-copy line, Drive line, anomaly escape hatch, actionable-passphrase row, and the restore-history dialog are each an independent presence check; coverage-blind CRAP on a presentational component, not accidental complexity."
+      },
+      {
+        "files": ["src/lib/snapshotStore.ts"],
+        "functions": ["commitSnapshot"],
+        "maxCrap": 120,
+        "reason": "Write, reread-and-verify, delete-on-failure, build manifest, commit last, prune orphans -- a single-transaction commit protocol where the correctness argument depends on this exact order in one function."
+      },
+      {
+        "files": ["src/lib/autoBackup.ts"],
+        "functions": ["runTier1", "runAutoBackupBody", "runTier2", "degradeForQuota"],
+        "maxCrap": 100,
+        "reason": "Daily-gate/skip-unchanged/anomaly-guard/quota-degrade branching is the issue's specified auto-backup state machine; each branch is a distinct real-world outcome (unchanged, collapsed, degrade tier 1/2/3, offline, no-passphrase, session-expired), not accidental complexity."
+      },
+      {
+        "files": ["src/hooks/useAppStartup.ts"],
+        "functions": ["<arrow>"],
+        "maxCrap": 100,
+        "reason": "Startup sequencing: persisted-storage warning, data-loss detection, and the empty-list-with-snapshot restore offer all gate on the same boot state; matches the useExpenseFormController.ts <arrow> precedent above."
+      },
+      {
+        "files": ["src/components/DataLossDialog.tsx"],
+        "functions": ["DataLossDialog"],
+        "maxCrap": 35,
+        "reason": "lastSeenExpenseCount-present-vs-null and snapshot-present-vs-absent JSX branches; coverage-blind CRAP on an alert dialog, matches the DeleteCategoryDialog precedent above."
       }
     ]
   },

docs/features/drive-backup.md

@@ -1,10 +1,12 @@
 # 🔄 Google Drive Backup & Enhanced Export System
 
-**Status:** Spec Confirmed — Ready for Implementation  
-**Version:** 0.2.0  
-**Date:** 2026-03-02  
+**Status:** Implemented — Phases 1-4 shipped (client-side encryption, silent OAuth refresh,
+automatic daily Tier 1/Tier 2 backup, and one-tap restore); Phase 5 (browse/import from Drive UI)
+remains future scope.  
+**Version:** 0.3.0  
+**Date:** 2026-08-28  
 **Target Release:** Feature Set 3  
-**Active Phases:** Phase 1 (Backup Reminders) + Phase 2 (Simplified Export)
+**Active Phases:** All of Phase 1-4
 
 ---
 
@@ -86,15 +88,17 @@ Enhance the existing export/import system with:
 - Account management: View status, change folder, unlink account
 - Graceful fallback to device export if Drive or auth fails
 
-**🔒 Future Scope: Client-Side Encryption**
+**🔒 Client-Side Encryption (Shipped)**
 
-- Encrypt backup JSON locally using Web Crypto API before upload (Explore other AES etc ways.)
-- Zero knowledge
-- Only the user can decrypt (key derived from a user-defined passphrase or device key)
-- Even if Google Drive is compromised/leaked, data is unreadable
-- Decrypt locally on import (no server involved)
-- Requires user-selected folder (not `appDataFolder`) so user can manage encrypted files
-- Incremental: encryption layer added on top of existing Drive upload
+- Every file that leaves the origin sandbox (Drive uploads, manual exports) is encrypted with
+  AES-GCM-256, key derived via PBKDF2-SHA256 (600k iterations) from a user-defined passphrase —
+  see `src/lib/backup.ts`.
+- Zero knowledge: only the user's passphrase can decrypt; Google never sees plaintext.
+- Decrypted locally on import — no server involved.
+- The automatic local OPFS snapshot (Tier 1 of the auto-backup feature, see
+  `src/lib/snapshotStore.ts` / `src/lib/autoBackup.ts`) is deliberately **plaintext** — it never
+  leaves the origin sandbox, the same boundary that already protects the unencrypted IndexedDB it
+  copies from.
 
 ---
 
@@ -481,17 +485,16 @@ function shouldShowReminderBanner(settings: BackupSettings): boolean {
 - [ ] Test token auto-refresh (wait ~1hr or force expiry)
 - [ ] Test offline behavior (graceful failure message)
 
-### **Phase 4: Client-Side Encryption (Future Scope)**
+### **Phase 4: Client-Side Encryption (Shipped)**
 
-**Effort:** 6-8 hours  
-**Goal:** Zero-knowledge backups — even Google cannot read exported files
-
-- Encrypt JSON locally using Web Crypto API (AES-GCM) before Drive upload
-- Key derived from user passphrase (PBKDF2)
-- Encrypted file uploaded to user-selected Drive folder
-- On import: detect encrypted file, prompt passphrase, decrypt locally
-- No passphrase stored anywhere — user is responsible
-- Works for device export too (optional encrypted local backup)
+- Encrypted locally using Web Crypto API (AES-GCM-256) before Drive upload
+- Key derived from user passphrase (PBKDF2-SHA256, 600k iterations)
+- Encrypted file uploaded to the `ExTrack Backups` Drive folder
+- On import: detect encrypted file, decrypt with stored or manually-entered passphrase
+- Passphrase stored in the same IndexedDB database as the data it protects — see
+  `src/lib/backup.ts` for the deliberate reasoning (the automatic OPFS snapshot stays plaintext
+  for the same reason: encrypting it would add no attacker resistance, only a failure mode)
+- Also protects the automatic daily device export (see `src/lib/autoBackup.ts`)
 
 ### **Phase 5: Import from Drive** (Future Scope)
 
@@ -541,7 +544,7 @@ Before implementation, confirm:
 | 3   | Drive folder              | **User-selected folder** via Google Picker (not `appDataFolder`)                                                                   |
 | 4   | Token storage             | IndexedDB plaintext for now                                                                                                        |
 | 5   | Token lifetime            | Access token: ~1hr; Refresh token: long-lived (until revoked)                                                                      |
-| 6   | File encryption           | Future scope (Phase 4) — AES-GCM via Web Crypto API, user passphrase                                                               |
+| 6   | File encryption           | Shipped — AES-GCM-256 via Web Crypto API, user passphrase (PBKDF2-SHA256, 600k iterations)                                          |
 | 7   | Multiple backups          | User-managed in their chosen folder; no auto-cleanup by app                                                                        |
 | 8   | CSV for Drive             | Not supported — Drive is JSON only; CSV available for device export                                                                |
 | 9   | Import source             | Device (JSON only), Drive import is future scope (Phase 5)                                                                         |
@@ -568,11 +571,13 @@ Before implementation, confirm:
 1. ✅ ~~Review plan and confirm approach~~
 2. ✅ ~~Answer open questions~~
 3. ✅ ~~Prioritize phases~~
-4. **Implement Phase 1** — Backup reminder system + BackupSettings UI
-5. **Implement Phase 2** — Simplified export dialog
-6. Test Phase 1 + 2 together end-to-end
-7. Plan Phase 3 (Drive integration) after Phase 1+2 are stable
+4. ✅ ~~Implement Phase 1~~ — Backup reminder system + BackupSettings UI
+5. ✅ ~~Implement Phase 2~~ — Simplified export dialog
+6. ✅ ~~Implement Phase 3~~ — Google Drive integration
+7. ✅ ~~Implement Phase 4~~ — Client-side encryption + automatic daily Tier 1/Tier 2 backup
+8. Phase 5 (browse/import from Drive UI) remains future scope
 
 ---
 
-**Spec confirmed. Ready to implement Phase 1 + Phase 2.**
+**Phases 1-4 shipped.** See `src/lib/autoBackup.ts`, `src/lib/snapshotStore.ts`, and
+`tests/e2e/auto-backup.spec.ts` for the automatic-backup layer.

src/App.tsx

@@ -1,6 +1,7 @@
 import { Toaster as Sonner } from "@/components/ui/sonner";
 import { TooltipProvider } from "@/components/ui/tooltip";
 import { BrowserRouter, Routes, Route, useNavigate } from "react-router";
+import { toast } from "sonner";
 import { ThemeProvider } from "@/contexts/ThemeContext";
 import { AppLayout } from "@/components/layout/AppLayout";
 import { ReloadPrompt } from "@/components/ReloadPrompt";
@@ -10,6 +11,8 @@ import { lazy } from "react";
 import { initializeDatabase } from "@/db/expenseTrackerDb";
 import { userPreferences } from "@/db/userPreferences";
 import { useAppStartup } from "@/hooks/useAppStartup";
+import { markAutoBackup } from "@/lib/backup";
+import { restoreSnapshot } from "@/lib/autoBackup";
 
 import HomePage from "./pages/HomePage";
 
@@ -31,7 +34,8 @@ const BulkAddPage = lazy(() => import("@/pages/BulkAddPage"));
 
 function AppContent() {
   const navigate = useNavigate();
-  const { lossCount, setLossCount, lossDialogOpen, setLossDialogOpen } = useAppStartup();
+  const { lossCount, setLossCount, lossDialogOpen, setLossDialogOpen, restoreOffer, setRestoreOffer } =
+    useAppStartup();
 
   return (
     <AppLayout>
@@ -50,25 +54,48 @@ function AppContent() {
         <Route path="/settings/about" element={<AboutPage />} />
         <Route path="*" element={<NotFound />} />
       </Routes>
-      {lossCount !== null && (
+      {(lossCount !== null || restoreOffer !== null) && (
         <DataLossDialog
           open={lossDialogOpen}
           lastSeenExpenseCount={lossCount}
+          snapshot={restoreOffer}
           onStartFresh={() => {
             const freshNow = new Date().toISOString();
             userPreferences.setInstallMarker({
               installedAt: freshNow,
               lastSeenAt: freshNow,
               lastSeenExpenseCount: 0,
             });
+            if (restoreOffer) markAutoBackup({ restoreOfferDeclinedFor: restoreOffer.name });
             setLossDialogOpen(false);
             setLossCount(null);
+            setRestoreOffer(null);
             void initializeDatabase();
           }}
           onRestore={() => {
             setLossDialogOpen(false);
             navigate("/settings/data");
           }}
+          onRestoreSnapshot={
+            restoreOffer
+              ? () => {
+                  const offer = restoreOffer;
+                  void restoreSnapshot(offer.name)
+                    .then(({ expenseCount }) => {
+                      setLossDialogOpen(false);
+                      setLossCount(null);
+                      setRestoreOffer(null);
+                      toast.success(
+                        `Restored ${expenseCount} expenses. Currency and theme settings are not part of a safety copy.`,
+                      );
+                      navigate("/transactions");
+                    })
+                    .catch((err: unknown) => {
+                      toast.error(err instanceof Error ? err.message : "Restore failed");
+                    });
+                }
+              : undefined
+          }
         />
       )}
       <BackupReminderPrompt />

src/components/BackupReminderPrompt.tsx

@@ -5,6 +5,7 @@ import {
   getDaysSinceLastBackup,
   markBackupReminderBannerShown,
   shouldShowBackupReminderBanner,
+  toDateKey,
 } from "@/lib/backup";
 import { type BackupReminderSchedule } from "@/db/userPreferences";
 import { BackupReminderBanner } from "@/components/BackupReminderBanner";
@@ -37,8 +38,24 @@ function getLastBackupText(daysSinceLastBackup: number | null): string {
   return `Last backup: ${daysSinceLastBackup} day${daysSinceLastBackup === 1 ? "" : "s"} ago.`;
 }
 
+const AUTO_BACKUP_FAILURE_THRESHOLD = 3;
+
 function getInitialPromptState(): PromptState {
   const preferences = getBackupReminderPreferences();
+
+  // Sustained automatic-backup failure escalates to this same banner surface, gated by the
+  // existing once-a-day bannerLastShownDate check — one banner, not a daily nag on top of it.
+  if (
+    preferences.autoBackupFailures >= AUTO_BACKUP_FAILURE_THRESHOLD &&
+    preferences.bannerLastShownDate !== toDateKey(new Date())
+  ) {
+    return {
+      visible: true,
+      schedule: preferences.reminderSchedule,
+      message: "Automatic backup has failed for 3 days in a row. Check your connection or Drive link.",
+    };
+  }
+
   const visible = shouldShowBackupReminderBanner(preferences);
 
   if (!visible) {

src/components/DataLossDialog.tsx

@@ -1,3 +1,4 @@
+import { format } from "date-fns";
 import {
   AlertDialog,
   AlertDialogAction,
@@ -8,18 +9,27 @@ import {
   AlertDialogTitle,
 } from "@/components/ui/alert-dialog";
 
+interface SnapshotOffer {
+  writtenAt: string;
+  expenseCount: number;
+}
+
 interface DataLossDialogProps {
   open: boolean;
-  lastSeenExpenseCount: number;
+  lastSeenExpenseCount: number | null;
+  snapshot?: SnapshotOffer | null;
   onStartFresh: () => void;
   onRestore: () => void;
+  onRestoreSnapshot?: () => void;
 }
 
 export function DataLossDialog({
   open,
   lastSeenExpenseCount,
+  snapshot = null,
   onStartFresh,
   onRestore,
+  onRestoreSnapshot,
 }: DataLossDialogProps) {
   return (
     <AlertDialog open={open}>
@@ -29,25 +39,47 @@ export function DataLossDialog({
           <AlertDialogDescription asChild className="text-left">
             <div className="space-y-3 pt-2">
               <div className="text-sm text-foreground">
-                This device previously held <span className="font-medium">{lastSeenExpenseCount}</span>{" "}
-                expense{lastSeenExpenseCount === 1 ? "" : "s"}, but the browser&apos;s storage for
-                this app is now empty.
-              </div>
-              <div className="text-xs text-muted-foreground">
-                This usually means the browser cleared its storage. If you have a backup file or a
-                Google Drive backup, restore it now — starting fresh discards the chance to recover
-                this device's copy.
+                {lastSeenExpenseCount !== null ? (
+                  <>
+                    This device previously held{" "}
+                    <span className="font-medium">{lastSeenExpenseCount}</span> expense
+                    {lastSeenExpenseCount === 1 ? "" : "s"}, but the browser&apos;s storage for this
+                    app is now empty.
+                  </>
+                ) : (
+                  "Your expense list is empty."
+                )}
               </div>
+              {snapshot ? (
+                <div className="text-xs text-muted-foreground">
+                  We found a local safety copy from{" "}
+                  {format(new Date(snapshot.writtenAt), "MMM d, h:mm a")} with{" "}
+                  <span className="font-medium">{snapshot.expenseCount}</span> expenses. Restore it?
+                </div>
+              ) : (
+                <div className="text-xs text-muted-foreground">
+                  This usually means the browser cleared its storage. If you have a backup file or a
+                  Google Drive backup, restore it now — starting fresh discards the chance to recover
+                  this device's copy.
+                </div>
+              )}
             </div>
           </AlertDialogDescription>
         </AlertDialogHeader>
         <AlertDialogFooter>
-          <AlertDialogAction onClick={onStartFresh} className="bg-secondary text-secondary-foreground hover:bg-secondary/80">
+          <AlertDialogAction
+            onClick={onStartFresh}
+            className="bg-secondary text-secondary-foreground hover:bg-secondary/80"
+          >
             Start fresh
           </AlertDialogAction>
-          <AlertDialogAction onClick={onRestore}>
-            Restore from backup
-          </AlertDialogAction>
+          {snapshot ? (
+            <AlertDialogAction onClick={onRestoreSnapshot}>
+              Restore {snapshot.expenseCount} expenses
+            </AlertDialogAction>
+          ) : (
+            <AlertDialogAction onClick={onRestore}>Restore from backup</AlertDialogAction>
+          )}
         </AlertDialogFooter>
       </AlertDialogContent>
     </AlertDialog>

src/components/more/BackupCard.tsx

@@ -3,6 +3,7 @@ import { useDriveConnection } from "@/hooks/useDriveConnection";
 import { useBackupReminderSchedule } from "@/hooks/useBackupReminderSchedule";
 import { ReminderScheduleSelect } from "@/components/more/backup/ReminderScheduleSelect";
 import { DriveConnectionRow } from "@/components/more/backup/DriveConnectionRow";
+import { AutoBackupStatus } from "@/components/more/backup/AutoBackupStatus";
 
 interface BackupCardProps {
   openOnMount?: boolean;
@@ -16,7 +17,8 @@ export function BackupCard({ openOnMount = false, onBackupSuccess }: BackupCardP
   return (
     <div className="space-y-1">
       <h2 className="text-sm font-semibold">Backup</h2>
-      <p className="text-xs text-muted-foreground pb-3">{lastBackupText}</p>
+      <p className="text-xs text-muted-foreground pb-1">{lastBackupText}</p>
+      <AutoBackupStatus />
 
       {/* Reminder frequency row */}
       <div className="flex items-center justify-between py-2">