feat: add backup recovery, setup wizard and user-view guards

frontend/app/lib/user-view-policy.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from "vitest";
+import { getEffectiveRole, isAdminPage } from "./user-view-policy";
+
+describe("user view preview policy", () => {
+  it("downgrades only the displayed administrator role during preview", () => {
+    expect(getEffectiveRole("admin", true)).toBe("user");
+    expect(getEffectiveRole("admin", false)).toBe("admin");
+    for (const role of ["user", null, undefined]) {
+      expect(getEffectiveRole(role, true)).toBe(role);
+      expect(getEffectiveRole(role, false)).toBe(role);
+    }
+  });
+  it("covers configuration, nested admin pages, user management and setup", () => {
+    for (const path of [
+      "/admin",
+      "/admin/",
+      "/admin/backups",
+      "/admin/recaps",
+      "/users",
+      "/users/42",
+      "/setup",
+      "/admin?section=site",
+      "/%61dmin/diagnostics",
+    ]) {
+      expect(isAdminPage(path), path).toBe(true);
+    }
+  });
+  it("does not restrict normal member pages or similarly named paths", () => {
+    for (const path of [
+      "/",
+      "/profile",
+      "/profile/invites",
+      "/portal/issues",
+      "/requests/3580",
+      "/insights",
+      "/administrator",
+      "/users-guide",
+    ]) {
+      expect(isAdminPage(path), path).toBe(false);
+    }
+  });
+  it("keeps public first-install setup separate from admin authentication", () => {
+    expect(isAdminPage("/setup", false)).toBe(false);
+    expect(isAdminPage("/admin/backups", false)).toBe(true);
+  });
+});

frontend/app/lib/user-view-policy.ts

@@ -0,0 +1,16 @@
+// Preview never promotes a user or changes server-side account permissions.
+export function getEffectiveRole(role: string | null | undefined, preview: boolean) {
+  return preview && role === "admin" ? "user" : role;
+}
+
+export function isAdminPage(pathname: string, includeSetup = true): boolean {
+  let path = pathname.split(/[?#]/, 1)[0];
+  try {
+    path = decodeURIComponent(path);
+  } catch {
+    // Let the router handle malformed URLs; never infer a more privileged role.
+  }
+  path = path.replace(/\/{2,}/g, "/");
+  const roots = includeSetup ? ["/admin", "/users", "/setup"] : ["/admin", "/users"];
+  return roots.some((root) => path === root || path.startsWith(`${root}/`));
+}

frontend/app/lib/viewMode.ts

@@ -1,13 +1,19 @@
 "use client";
 
-import { useEffect, useState } from "react";
+import { useEffect, useSyncExternalStore } from "react";
+import { getEffectiveRole } from "./user-view-policy";
 
 const USER_VIEW_STORAGE_KEY = "magent_user_view_preview";
 const USER_VIEW_EVENT = "magent:user-view-change";
+let fallbackPreview = false;
 
 const readUserViewPreview = () => {
   if (typeof window === "undefined") return false;
-  return window.sessionStorage.getItem(USER_VIEW_STORAGE_KEY) === "1";
+  try {
+    return window.sessionStorage.getItem(USER_VIEW_STORAGE_KEY) === "1";
+  } catch {
+    return fallbackPreview;
+  }
 };
 
 const applyDocumentMode = (enabled: boolean) => {
@@ -17,32 +23,46 @@ const applyDocumentMode = (enabled: boolean) => {
 
 export const setUserViewPreview = (enabled: boolean) => {
   if (typeof window === "undefined") return;
-  if (enabled) {
-    window.sessionStorage.setItem(USER_VIEW_STORAGE_KEY, "1");
-  } else {
-    window.sessionStorage.removeItem(USER_VIEW_STORAGE_KEY);
+  fallbackPreview = enabled;
+  try {
+    if (enabled) {
+      window.sessionStorage.setItem(USER_VIEW_STORAGE_KEY, "1");
+    } else {
+      window.sessionStorage.removeItem(USER_VIEW_STORAGE_KEY);
+    }
+  } catch {
+    // Preview still works for this document when browser storage is unavailable.
   }
   applyDocumentMode(enabled);
   window.dispatchEvent(new CustomEvent(USER_VIEW_EVENT, { detail: { enabled } }));
 };
 
-export const useUserViewPreview = () => {
-  const [enabled, setEnabled] = useState(false);
+const subscribe = (notify: () => void) => {
+  window.addEventListener(USER_VIEW_EVENT, notify);
+  window.addEventListener("storage", notify);
+  return () => {
+    window.removeEventListener(USER_VIEW_EVENT, notify);
+    window.removeEventListener("storage", notify);
+  };
+};
+
+// Unknown during server rendering/initial hydration: admin pages must not mount
+// and fetch privileged data before the saved per-tab preview mode is known.
+const serverSnapshot = (): boolean | null => null;
+
+export const useUserViewState = () => {
+  const value = useSyncExternalStore(subscribe, readUserViewPreview, serverSnapshot);
 
   useEffect(() => {
-    const sync = () => {
-      const nextValue = readUserViewPreview();
-      applyDocumentMode(nextValue);
-      setEnabled(nextValue);
-    };
-    sync();
-    window.addEventListener(USER_VIEW_EVENT, sync);
-    window.addEventListener("storage", sync);
-    return () => {
-      window.removeEventListener(USER_VIEW_EVENT, sync);
-      window.removeEventListener("storage", sync);
-    };
-  }, []);
+    if (value !== null) applyDocumentMode(value);
+  }, [value]);
 
-  return enabled;
+  return { enabled: value === true, ready: value !== null };
+};
+
+export const useUserViewPreview = () => useUserViewState().enabled;
+
+export const useEffectiveRole = (role?: string | null) => {
+  const { enabled, ready } = useUserViewState();
+  return getEffectiveRole(role, !ready || enabled);
 };