@bygghammar/cms-platform 0.38.1 → 0.40.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.40.0
+
+- New `backoffice/shell`: shared `BackofficeShell` (auth gate, no-access screen,
+  sidebar, sign-in form), a feature-flag driven `backofficeNav(siteConfig)` model
+  and `backofficeRedirectHost` for the admin-domain guard. A site's backoffice
+  layout route is now a thin adapter that supplies its auth client and admin check.
+
+## 0.39.0
+
+- New `server/backup-core`: superadmin verification, dataset counting, archive build, analysis and restore (database + media) now live in the package. Hosts pass a service-role client factory.
+
 ## 0.38.1
 
 - Type fix in `server/forms-submissions-core` (per-form rollup form names).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bygghammar/cms-platform",
-  "version": "0.38.1",
+  "version": "0.40.0",
   "description": "Shared CMS platform: blocks, block types, i18n core, UI primitives and design-token contract used by every Bygghammar/Voyara site.",
   "type": "module",
   "sideEffects": false,
@@ -153,7 +153,9 @@
     "./server/smtp": "./src/server/smtp.ts",
     "./server/email-send-core": "./src/server/email-send-core.ts",
     "./server/forms-delivery-core": "./src/server/forms-delivery-core.ts",
-    "./server/forms-submissions-core": "./src/server/forms-submissions-core.ts"
+    "./server/forms-submissions-core": "./src/server/forms-submissions-core.ts",
+    "./server/backup-core": "./src/server/backup-core.ts",
+    "./backoffice/shell": "./src/backoffice/shell/index.ts"
   },
   "dependencies": {
     "fflate": "^0.8.3"

package/src/backoffice/shell/BackofficeShell.tsx

@@ -0,0 +1,311 @@
+/**
+ * Shared backoffice shell: auth gate, no-access screen, sidebar and content slot.
+ *
+ * A host route supplies its auth client, an admin check and the nav model; the
+ * layout, states and sign-in form are identical for every site.
+ */
+import { Link, useNavigate, useRouterState } from "@tanstack/react-router";
+import { ExternalLink, LogOut } from "lucide-react";
+import { useEffect, useState, type FormEvent, type ReactNode } from "react";
+import { toast } from "sonner";
+
+import { isBackofficeNavigationActive } from "../../navigation";
+import type { BackofficeNavItem } from "./nav-model";
+
+export type ShellAuthUser = { email?: string | null } | null;
+
+export type ShellAuthAdapter = {
+  /** Current session user, or null when signed out. */
+  getUser: () => Promise<ShellAuthUser>;
+  /** Subscribe to session changes; returns an unsubscribe function. */
+  onUserChange: (handler: (user: ShellAuthUser) => void) => () => void;
+  signIn: (email: string, password: string) => Promise<{ error?: string | null }>;
+  signOut: () => Promise<unknown>;
+  /** True only for a genuine hosted misconfiguration (not "signed out"). */
+  isConfigBroken?: () => boolean;
+};
+
+export type BackofficeShellProps = {
+  /** Site name shown in the sidebar header. */
+  siteName: string;
+  /** Backoffice base path, e.g. `/kontoret`. */
+  backofficePath: string;
+  nav: BackofficeNavItem[];
+  auth: ShellAuthAdapter;
+  /** Resolves whether the signed-in user may use the backoffice. */
+  checkIsAdmin: () => Promise<boolean>;
+  /** localStorage key for the "remember me" email. */
+  rememberKey?: string;
+  /** Route content — normally `<Outlet />`. */
+  children: ReactNode;
+};
+
+type State =
+  | { kind: "loading" }
+  | { kind: "signed-out" }
+  | { kind: "config-error" }
+  | { kind: "not-admin"; email: string }
+  | { kind: "admin"; email: string };
+
+export function BackofficeShell(props: BackofficeShellProps) {
+  const { auth, checkIsAdmin } = props;
+  const [state, setState] = useState<State>({ kind: "loading" });
+
+  useEffect(() => {
+    let alive = true;
+
+    const resolve = async (user: ShellAuthUser) => {
+      if (!alive) return;
+      if (!user) {
+        setState(auth.isConfigBroken?.() ? { kind: "config-error" } : { kind: "signed-out" });
+        return;
+      }
+      try {
+        const ok = await checkIsAdmin();
+        if (!alive) return;
+        setState(
+          ok
+            ? { kind: "admin", email: user.email ?? "" }
+            : { kind: "not-admin", email: user.email ?? "" },
+        );
+      } catch {
+        if (alive) setState({ kind: "signed-out" });
+      }
+    };
+
+    void auth.getUser().then(resolve);
+    const unsubscribe = auth.onUserChange(resolve);
+
+    return () => {
+      alive = false;
+      unsubscribe();
+    };
+  }, [auth, checkIsAdmin]);
+
+  if (state.kind === "loading") {
+    return (
+      <main className="min-h-screen bg-ink text-paper grid place-items-center">
+        <div className="text-sm uppercase tracking-[0.22em] text-paper/60">Loading…</div>
+      </main>
+    );
+  }
+
+  if (state.kind === "config-error") {
+    return (
+      <main className="min-h-screen bg-ink text-paper grid place-items-center px-6">
+        <div className="max-w-md text-center">
+          <h1 className="font-serif text-3xl">Authentication unavailable</h1>
+          <p className="mt-4 text-paper/70">
+            The backend configuration for this environment is missing or invalid, so the backoffice
+            cannot verify your account. The public website is unaffected. Check the deployment
+            configuration and reload this page.
+          </p>
+        </div>
+      </main>
+    );
+  }
+
+  if (state.kind === "signed-out") {
+    return <AuthGate auth={auth} rememberKey={props.rememberKey ?? "cms.backoffice.remember"} />;
+  }
+
+  if (state.kind === "not-admin") {
+    return (
+      <main className="min-h-screen bg-ink text-paper grid place-items-center px-6">
+        <div className="max-w-md text-center">
+          <h1 className="font-serif text-3xl">No access</h1>
+          <p className="mt-4 text-paper/70">
+            The account <span className="text-paper">{state.email}</span> does not have
+            administrator access to the backoffice.
+          </p>
+          <button
+            className="mt-8 inline-flex items-center border border-paper px-6 py-3 text-xs uppercase tracking-[0.22em] hover:bg-paper hover:text-ink transition-colors"
+            onClick={() => void auth.signOut()}
+          >
+            Sign out
+          </button>
+        </div>
+      </main>
+    );
+  }
+
+  return <Shell {...props} email={state.email} />;
+}
+
+function Shell({
+  siteName,
+  nav,
+  auth,
+  children,
+}: BackofficeShellProps & { email: string }) {
+  const pathname = useRouterState({ select: (r) => r.location.pathname });
+
+  return (
+    <div className="min-h-screen bg-muted text-ink grid grid-cols-1 md:grid-cols-[240px_1fr]">
+      <aside className="bg-ink text-paper md:min-h-screen flex md:flex-col">
+        <div className="p-6 border-b border-paper/10">
+          <div className="text-[0.7rem] uppercase tracking-[0.22em] text-paper/60">Backoffice</div>
+          <div className="mt-1 font-serif text-lg">{siteName} Backoffice</div>
+        </div>
+        <nav className="flex md:flex-col overflow-x-auto md:overflow-visible p-2 md:p-4 gap-1 flex-1">
+          {nav.map((n) => (
+            <Link
+              key={n.to}
+              to={n.to}
+              className={[
+                "flex items-center gap-3 px-4 py-2.5 text-sm transition-colors whitespace-nowrap",
+                isBackofficeNavigationActive(pathname, { to: n.to, exact: n.exact })
+                  ? "bg-paper text-ink"
+                  : "text-paper/75 hover:text-paper hover:bg-paper/10",
+              ].join(" ")}
+            >
+              <n.icon className="size-4" />
+              {n.label}
+            </Link>
+          ))}
+          <a
+            href="/"
+            target="_blank"
+            rel="noreferrer"
+            className="mt-2 md:mt-3 md:border-t md:border-paper/10 md:pt-3 flex items-center gap-3 px-4 py-2.5 text-sm whitespace-nowrap text-paper/75 transition-colors hover:text-paper hover:bg-paper/10"
+          >
+            <ExternalLink className="size-4" />
+            View website
+          </a>
+        </nav>
+        <SignedInPanel auth={auth} />
+      </aside>
+      <div className="flex-1 min-w-0">{children}</div>
+    </div>
+  );
+}
+
+function SignedInPanel({ auth }: { auth: ShellAuthAdapter }) {
+  const [email, setEmail] = useState("");
+
+  useEffect(() => {
+    let alive = true;
+    void auth.getUser().then((user) => {
+      if (alive) setEmail(user?.email ?? "");
+    });
+    return () => {
+      alive = false;
+    };
+  }, [auth]);
+
+  return (
+    <div className="p-4 border-t border-paper/10 hidden md:block">
+      <div className="text-[0.65rem] uppercase tracking-[0.22em] text-paper/50">Signed in</div>
+      <div className="mt-1 text-sm text-paper truncate" title={email}>
+        {email}
+      </div>
+      <button
+        className="mt-4 inline-flex items-center gap-2 text-xs uppercase tracking-[0.22em] text-paper/70 hover:text-paper"
+        onClick={async () => {
+          await auth.signOut();
+          toast.success("Signed out");
+        }}
+      >
+        <LogOut className="size-3.5" />
+        Sign out
+      </button>
+    </div>
+  );
+}
+
+function AuthGate({ auth, rememberKey }: { auth: ShellAuthAdapter; rememberKey: string }) {
+  const [email, setEmail] = useState("");
+  const [password, setPassword] = useState("");
+  const [remember, setRemember] = useState(false);
+  const [busy, setBusy] = useState(false);
+  const navigate = useNavigate();
+
+  useEffect(() => {
+    const saved = window.localStorage.getItem(rememberKey);
+    if (saved) {
+      setEmail(saved);
+      setRemember(true);
+    }
+  }, [rememberKey]);
+
+  const submit = async (e: FormEvent) => {
+    e.preventDefault();
+    setBusy(true);
+    try {
+      const { error } = await auth.signIn(email, password);
+      if (error) throw new Error(error);
+      if (remember) window.localStorage.setItem(rememberKey, email);
+      else window.localStorage.removeItem(rememberKey);
+      toast.success("Signed in");
+    } catch (err) {
+      toast.error(err instanceof Error ? err.message : "Something went wrong");
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  return (
+    <main className="min-h-screen bg-ink text-paper grid place-items-center px-6 py-16">
+      <div className="w-full max-w-sm">
+        <div className="text-[0.7rem] uppercase tracking-[0.22em] text-paper/60">Backoffice</div>
+        <h1 className="mt-3 font-serif text-3xl">Sign in</h1>
+        <p className="mt-3 text-sm text-paper/60">
+          Only authorized administrators can access the backoffice.
+        </p>
+
+        <form onSubmit={submit} className="mt-8 space-y-4">
+          <label className="block">
+            <span className="text-[0.65rem] uppercase tracking-[0.22em] text-paper/60">Email</span>
+            <input
+              type="email"
+              required
+              value={email}
+              onChange={(e) => setEmail(e.target.value)}
+              className="mt-2 w-full bg-transparent border border-paper/25 px-4 py-3 text-paper placeholder:text-paper/40 focus:border-sea focus:outline-none"
+              autoComplete="email"
+            />
+          </label>
+          <label className="block">
+            <span className="text-[0.65rem] uppercase tracking-[0.22em] text-paper/60">
+              Password
+            </span>
+            <input
+              type="password"
+              required
+              minLength={8}
+              value={password}
+              onChange={(e) => setPassword(e.target.value)}
+              className="mt-2 w-full bg-transparent border border-paper/25 px-4 py-3 text-paper placeholder:text-paper/40 focus:border-sea focus:outline-none"
+              autoComplete="current-password"
+            />
+          </label>
+          <label className="flex items-center gap-3 text-xs text-paper/70 select-none cursor-pointer">
+            <input
+              type="checkbox"
+              checked={remember}
+              onChange={(e) => setRemember(e.target.checked)}
+              className="size-4 accent-sea bg-transparent border border-paper/25"
+            />
+            Remember me
+          </label>
+          <button
+            type="submit"
+            disabled={busy}
+            className="mt-2 w-full inline-flex items-center justify-center border border-paper bg-paper text-ink px-6 py-3 text-xs uppercase tracking-[0.22em] hover:bg-transparent hover:text-paper transition-colors disabled:opacity-60"
+          >
+            {busy ? "Working…" : "Sign in"}
+          </button>
+        </form>
+
+        <div className="mt-10 text-center">
+          <button
+            onClick={() => navigate({ to: "/" })}
+            className="text-xs uppercase tracking-[0.22em] text-paper/50 hover:text-paper"
+          >
+            ← Back to website
+          </button>
+        </div>
+      </div>
+    </main>
+  );
+}

package/src/backoffice/shell/domain-guard.ts

@@ -0,0 +1,38 @@
+/**
+ * Admin-domain guard for the backoffice route.
+ *
+ * Returns the host the backoffice should be served from, or null when the
+ * current host is fine (local dev, Lovable preview, or already the admin host).
+ */
+const DEV_HOST_SUFFIXES = [".lovable.app", ".lovableproject.com"];
+
+function normalizeHost(value: string): string {
+  return value
+    .replace(/^https?:\/\//, "")
+    .replace(/\/+$/, "")
+    .replace(/^www\./, "")
+    .toLowerCase();
+}
+
+/** True for hosts where the admin-domain guard must not apply. */
+export function isDevelopmentHost(host: string): boolean {
+  const h = normalizeHost(host);
+  return (
+    DEV_HOST_SUFFIXES.some((suffix) => h.endsWith(suffix)) ||
+    h === "localhost" ||
+    h.startsWith("localhost:") ||
+    h.startsWith("127.0.0.1")
+  );
+}
+
+/** Resolve the admin host to redirect to, or null to stay put. */
+export function backofficeRedirectHost(
+  currentHost: string,
+  adminDomain: string | null | undefined,
+): string | null {
+  if (!currentHost || isDevelopmentHost(currentHost)) return null;
+  const current = normalizeHost(currentHost);
+  const admin = normalizeHost(adminDomain ?? "");
+  if (!admin || current === admin) return null;
+  return admin;
+}

package/src/backoffice/shell/index.ts

@@ -0,0 +1,9 @@
+export { BackofficeShell } from "./BackofficeShell";
+export type {
+  BackofficeShellProps,
+  ShellAuthAdapter,
+  ShellAuthUser,
+} from "./BackofficeShell";
+export { backofficeNav } from "./nav-model";
+export type { BackofficeNavItem, BackofficeNavKey, BackofficeNavOptions } from "./nav-model";
+export { backofficeRedirectHost, isDevelopmentHost } from "./domain-guard";

package/src/backoffice/shell/nav-model.ts

@@ -0,0 +1,102 @@
+/**
+ * Backoffice navigation model.
+ *
+ * The nav is derived from `SiteConfig` (backoffice base path + feature flags)
+ * so every site gets the same sidebar without copying a list of links.
+ * A host may override labels or drop/add items through `options`.
+ */
+import type { LucideProps } from "lucide-react";
+import {
+  Blocks,
+  Calendar,
+  ClipboardList,
+  FileText,
+  Globe,
+  GraduationCap,
+  ImageIcon,
+  Layers,
+  LayoutDashboard,
+  LayoutList,
+  MessageSquareQuote,
+  ShieldCheck,
+} from "lucide-react";
+
+import type { SiteConfig } from "../../config/site-config";
+import type { BackofficeNavigationItem } from "../../navigation";
+
+export type BackofficeNavKey =
+  | "dashboard"
+  | "pages"
+  | "global-sections"
+  | "blocks"
+  | "sections"
+  | "media"
+  | "seo"
+  | "domains"
+  | "trips"
+  | "courses"
+  | "forms"
+  | "reviews"
+  | "admin";
+
+export type BackofficeNavItem = BackofficeNavigationItem<LucideProps>;
+
+type Definition = {
+  key: BackofficeNavKey;
+  path: string;
+  label: string;
+  icon: BackofficeNavItem["icon"];
+  exact?: boolean;
+  /** Feature flag that has to be enabled for the item to appear. */
+  feature?: keyof SiteConfig["features"];
+};
+
+const DEFINITIONS: readonly Definition[] = [
+  { key: "dashboard", path: "", label: "Dashboard", icon: LayoutDashboard, exact: true },
+  { key: "pages", path: "/pages-builder", label: "Page builder", icon: Blocks },
+  { key: "global-sections", path: "/global-sections", label: "Global Sections", icon: Layers },
+  { key: "blocks", path: "/blocks", label: "Block library", icon: Blocks },
+  { key: "sections", path: "/sections", label: "Shared content", icon: LayoutList },
+  { key: "media", path: "/media", label: "Media", icon: ImageIcon },
+  { key: "seo", path: "/seo", label: "SEO", icon: FileText },
+  { key: "domains", path: "/domains", label: "Domains", icon: Globe, feature: "domains" },
+  { key: "trips", path: "/trips", label: "Trips", icon: Calendar, feature: "trips" },
+  { key: "courses", path: "/kurser", label: "Courses", icon: GraduationCap, feature: "courses" },
+  { key: "forms", path: "/forms", label: "Forms", icon: ClipboardList, feature: "forms" },
+  {
+    key: "reviews",
+    path: "/recensioner",
+    label: "Reviews",
+    icon: MessageSquareQuote,
+    feature: "reviews",
+  },
+  { key: "admin", path: "/admin", label: "Admin", icon: ShieldCheck },
+];
+
+export type BackofficeNavOptions = {
+  /** Per-key label overrides, e.g. `{ trips: "Cruises" }`. */
+  labels?: Partial<Record<BackofficeNavKey, string>>;
+  /** Keys to hide regardless of feature flags. */
+  hide?: readonly BackofficeNavKey[];
+};
+
+/** Build the sidebar model for a site. */
+export function backofficeNav(
+  config: SiteConfig,
+  options: BackofficeNavOptions = {},
+): BackofficeNavItem[] {
+  const base = config.backofficePath.replace(/\/+$/, "");
+  const hidden = new Set(options.hide ?? []);
+
+  return DEFINITIONS.filter((d) => {
+    if (hidden.has(d.key)) return false;
+    if (d.feature && config.features[d.feature] !== true) return false;
+    return true;
+  }).map((d) => ({
+    key: d.key,
+    to: `${base}${d.path}` || "/",
+    label: options.labels?.[d.key] ?? d.label,
+    icon: d.icon,
+    exact: d.exact === true,
+  }));
+}

package/src/server/backup-core.ts

@@ -0,0 +1,731 @@
+import { zipSync, unzipSync, strToU8, strFromU8 } from "fflate";
+import { createClient, type SupabaseClient } from "@supabase/supabase-js";
+
+import { getMediaStorage } from "../media/storage";
+import {
+  ARCHIVE_FORMAT_VERSION,
+  IMPORT_ORDER,
+  LINEAGE_KEYS,
+  SCHEMA_VERSION,
+  groupById,
+  type ArchiveManifest,
+  type ImportMode,
+  type TableSpec,
+} from "../backup/datasets";
+import {
+  hasAllowedMediaExtension,
+  isSafeArchivePath,
+  neutralizeInjection,
+  rewriteMediaUrls,
+  sanitizeSecrets,
+  verifyMediaFile,
+} from "../backup/safety";
+
+/** Host plumbing the backup core needs: a service-role client factory. */
+export type BackupDeps = {
+  adminClient: () => Promise<SupabaseClient>;
+};
+
+const PAGE_SIZE = 1000;
+const WRITE_CHUNK = 400;
+
+/** Apply a table's export sanitiser: `["*"]` scrubs the whole row. */
+function sanitizeRow(spec: TableSpec, row: Record<string, unknown>): Record<string, unknown> {
+  const cols = spec.sanitize;
+  if (!cols?.length) return row;
+  if (cols.includes("*")) return sanitizeSecrets(row);
+  const out = { ...row };
+  for (const c of cols) if (c in out) out[c] = sanitizeSecrets(out[c]);
+  return out;
+}
+
+/* ------------------------------------------------------------------ auth */
+
+export type Caller = { userId: string; email: string | null; supabase: SupabaseClient };
+
+function newKeyFetch(key: string): typeof fetch {
+  return (input, init) => {
+    const h = new Headers(init?.headers);
+    if (key.startsWith("sb_") && h.get("Authorization") === `Bearer ${key}`)
+      h.delete("Authorization");
+    h.set("apikey", key);
+    return fetch(input, { ...init, headers: h });
+  };
+}
+
+/**
+ * Verify the request's bearer token and that the caller is a superadmin.
+ * Throws a Response so route handlers can return the right status code.
+ */
+export async function requireSuperadminFromRequestCore(request: Request): Promise<Caller> {
+  const url = process.env["SUPABASE_URL"];
+  const key = process.env["SUPABASE_PUBLISHABLE_KEY"];
+  if (!url || !key) throw new Response("Server not configured", { status: 500 });
+
+  const header = request.headers.get("authorization") ?? "";
+  if (!header.startsWith("Bearer ")) throw new Response("Unauthorized", { status: 401 });
+  const token = header.slice(7);
+  if (token.split(".").length !== 3) throw new Response("Unauthorized", { status: 401 });
+
+  const supabase = createClient(url, key, {
+    global: { fetch: newKeyFetch(key), headers: { Authorization: `Bearer ${token}` } },
+    auth: { storage: undefined, persistSession: false, autoRefreshToken: false },
+  });
+
+  const { data, error } = await supabase.auth.getClaims(token);
+  if (error || !data?.claims?.sub) throw new Response("Unauthorized", { status: 401 });
+
+  const userId = data.claims.sub as string;
+  const { data: isSuper, error: roleErr } = await supabase.rpc("has_role", {
+    _user_id: userId,
+    _role: "superadmin",
+  });
+  if (roleErr) throw new Response("Forbidden", { status: 403 });
+  if (!isSuper) throw new Response("Forbidden — superadmin only", { status: 403 });
+
+  return { userId, email: (data.claims.email as string) ?? null, supabase };
+}
+
+async function audit(
+  deps: BackupDeps,
+  caller: Caller,
+  action: string,
+  meta: Record<string, unknown>,
+) {
+  try {
+    const supabaseAdmin = await deps.adminClient();
+    await supabaseAdmin.from("audit_logs").insert({
+      actor_id: caller.userId,
+      actor_email: caller.email,
+      action,
+      entity: "backup",
+      entity_id: null,
+      meta: meta as never,
+    });
+  } catch (e) {
+    console.warn("[backup] audit failed", e);
+  }
+}
+
+/* ---------------------------------------------------------------- export */
+
+async function readAll(deps: BackupDeps, table: string): Promise<Record<string, unknown>[]> {
+  const supabaseAdmin = await deps.adminClient();
+  const rows: Record<string, unknown>[] = [];
+  for (let from = 0; ; from += PAGE_SIZE) {
+    const { data, error } = await supabaseAdmin
+      .from(table as never)
+      .select("*")
+      .range(from, from + PAGE_SIZE - 1);
+    if (error) throw new Error(`${table}: ${error.message}`);
+    const batch = (data ?? []) as unknown as Record<string, unknown>[];
+    rows.push(...batch);
+    if (batch.length < PAGE_SIZE) break;
+  }
+  return rows;
+}
+
+export async function countRowsCore(
+  deps: BackupDeps,
+  groupIds: string[],
+  caller?: Caller,
+): Promise<{
+  counts: Record<string, number>;
+  mediaFiles: number;
+  mediaBytes: number;
+  mediaError?: string;
+}> {
+  const supabaseAdmin = await deps.adminClient();
+  const counts: Record<string, number> = {};
+  let mediaFiles = 0;
+  let mediaBytes = 0;
+  let mediaError: string | undefined;
+
+  for (const id of groupIds) {
+    const group = groupById(id);
+    if (!group) continue;
+    for (const spec of group.tables) {
+      const { count, error } = await supabaseAdmin
+        .from(spec.table as never)
+        .select("*", { count: "exact", head: true });
+      counts[spec.table] = error ? 0 : (count ?? 0);
+    }
+    if (group.special === "mediaFiles") {
+      try {
+        // Use the service-role client so storage listing works server-side.
+        // This is an estimate: names are filtered here, contents are verified
+        // when the archive is actually built.
+        const files = (
+          await getMediaStorage(
+            caller?.supabase ?? (supabaseAdmin as unknown as SupabaseClient),
+          ).list()
+        ).filter((f) => hasAllowedMediaExtension(f.name));
+        mediaFiles = files.length;
+        mediaBytes = files.reduce((s, f) => s + (f.size ?? 0), 0);
+      } catch (e) {
+        mediaError = e instanceof Error ? e.message : "Could not list media files";
+      }
+    }
+    if (group.special === "authUsers") {
+      const { data } = await supabaseAdmin.auth.admin.listUsers({ page: 1, perPage: 1000 });
+      counts["auth_users"] = data?.users.length ?? 0;
+    }
+  }
+  return { counts, mediaFiles, mediaBytes, ...(mediaError ? { mediaError } : {}) };
+}
+
+export async function buildArchiveCore(
+  deps: BackupDeps,
+  caller: Caller,
+  groupIds: string[],
+  site: string | null,
+  options: { deferMediaToBrowser?: boolean } = {},
+): Promise<Uint8Array> {
+  const supabaseAdmin = await deps.adminClient();
+  const files: Record<string, Uint8Array> = {};
+  const counts: Record<string, number> = {};
+  let mediaFiles = 0;
+  let mediaBytes = 0;
+  const quarantined: string[] = [];
+
+  for (const id of groupIds) {
+    const group = groupById(id);
+    if (!group) continue;
+
+    for (const spec of group.tables) {
+      const rows = (await readAll(deps, spec.table)).map((r) => sanitizeRow(spec, r));
+      counts[spec.table] = rows.length;
+      files[`data/${spec.table}.json`] = strToU8(JSON.stringify(rows));
+    }
+
+    if (group.special === "authUsers") {
+      const { data } = await supabaseAdmin.auth.admin.listUsers({ page: 1, perPage: 1000 });
+      const users = (data?.users ?? []).map((u) => ({
+        id: u.id,
+        email: u.email,
+        email_confirmed_at: u.email_confirmed_at,
+        created_at: u.created_at,
+        // Metadata is user-supplied and can hold tokens; scrub it.
+        user_metadata: sanitizeSecrets(u.user_metadata),
+      }));
+      counts["auth_users"] = users.length;
+      files["data/auth_users.json"] = strToU8(JSON.stringify(users));
+    }
+
+    if (group.special === "mediaFiles") {
+      if (options.deferMediaToBrowser) continue;
+      const storage = getMediaStorage(supabaseAdmin as unknown as SupabaseClient);
+      const list = await storage.list();
+      for (const f of list) {
+        // Names that are not media, or unsafe archive paths, never enter the zip.
+        if (!hasAllowedMediaExtension(f.name) || !isSafeArchivePath(f.name)) {
+          quarantined.push(f.name);
+          continue;
+        }
+        try {
+          const bytes = await storage.download(f.name);
+          // The file's own bytes decide: HTML renamed to .jpg is excluded.
+          const verdict = verifyMediaFile(f.name, bytes);
+          if (!verdict.ok) {
+            quarantined.push(`${f.name} (${verdict.reason})`);
+            continue;
+          }
+          files[`media/${f.name}`] = bytes;
+          mediaFiles += 1;
+          mediaBytes += bytes.byteLength;
+        } catch (e) {
+          console.warn("[backup] could not read media file", f.name, e);
+        }
+      }
+    }
+  }
+
+  const manifest: ArchiveManifest = {
+    format: ARCHIVE_FORMAT_VERSION,
+    schemaVersion: SCHEMA_VERSION,
+    createdAt: new Date().toISOString(),
+    createdBy: caller.email,
+    site,
+    groups: groupIds,
+    counts,
+    mediaFiles,
+    mediaBytes,
+    quarantinedMedia: quarantined,
+  };
+  files["manifest.json"] = strToU8(JSON.stringify(manifest, null, 2));
+
+  await audit(deps, caller, "backup.export", {
+    groups: groupIds,
+    counts,
+    mediaFiles,
+    mediaBytes,
+    quarantinedMedia: quarantined.length,
+    mediaDeferredToBrowser: options.deferMediaToBrowser === true,
+  });
+
+  return zipSync(files, { level: 6 });
+}
+
+/* ---------------------------------------------------------------- import */
+
+export type ArchiveAnalysis = {
+  manifest: ArchiveManifest;
+  compatible: boolean;
+  problems: string[];
+  /** Media actually present in the archive (verified, not manifest-reported). */
+  mediaFiles: number;
+  mediaBytes: number;
+  /** Archive entries that are not real media and will not be restored. */
+  quarantinedMedia: string[];
+  datasets: {
+    group: string;
+    label: string;
+    insertOnly: boolean;
+    tables: { table: string; incoming: number; existing: number }[];
+    mediaFiles?: number;
+    mediaBytes?: number;
+  }[];
+};
+
+/**
+ * Count and measure the media payload actually contained in an archive.
+ * Entries that are not verified media, or whose path is unsafe, are
+ * quarantined: never counted, never written back to the library.
+ */
+function measureMedia(entries: Record<string, Uint8Array>): {
+  files: number;
+  bytes: number;
+  quarantined: string[];
+} {
+  let files = 0;
+  let bytes = 0;
+  const quarantined: string[] = [];
+  for (const [key, value] of Object.entries(entries)) {
+    if (!key.startsWith("media/")) continue;
+    const name = key.slice("media/".length);
+    if (!name) continue;
+    if (!isSafeArchivePath(name)) {
+      quarantined.push(`${name} (unsafe path)`);
+      continue;
+    }
+    const verdict = verifyMediaFile(name, value);
+    if (!verdict.ok) {
+      quarantined.push(`${name} (${verdict.reason})`);
+      continue;
+    }
+    files += 1;
+    bytes += value.byteLength;
+  }
+  return { files, bytes, quarantined };
+}
+
+function parseArchive(bytes: Uint8Array) {
+  const entries = unzipSync(bytes);
+  const manifestRaw = entries["manifest.json"];
+  if (!manifestRaw) throw new Error("Not a valid backup archive — manifest.json is missing.");
+  for (const key of Object.keys(entries)) {
+    if (!isSafeArchivePath(key)) {
+      throw new Error(`Unsafe entry in archive: ${key}`);
+    }
+  }
+  const manifest = JSON.parse(strFromU8(manifestRaw)) as ArchiveManifest;
+  return { entries, manifest };
+}
+
+function tableRows(entries: Record<string, Uint8Array>, table: string): Record<string, unknown>[] {
+  const raw = entries[`data/${table}.json`];
+  if (!raw) return [];
+  return JSON.parse(strFromU8(raw)) as Record<string, unknown>[];
+}
+
+export async function analyzeArchiveCore(deps: BackupDeps, bytes: Uint8Array): Promise<ArchiveAnalysis> {
+  const supabaseAdmin = await deps.adminClient();
+  const { entries, manifest } = parseArchive(bytes);
+  const problems: string[] = [];
+
+  if (manifest.format !== ARCHIVE_FORMAT_VERSION) {
+    problems.push(
+      `Archive format ${manifest.format} does not match this site (${ARCHIVE_FORMAT_VERSION}).`,
+    );
+  }
+  if (manifest.schemaVersion !== SCHEMA_VERSION) {
+    problems.push(
+      `Archive was made for database version ${manifest.schemaVersion}, this site runs version ${SCHEMA_VERSION}.`,
+    );
+  }
+
+  const media = measureMedia(entries);
+
+  const datasets: ArchiveAnalysis["datasets"] = [];
+  for (const id of manifest.groups ?? []) {
+    const group = groupById(id);
+    if (!group) {
+      problems.push(`Unknown dataset "${id}" in the archive — it will be skipped.`);
+      continue;
+    }
+    const tables: { table: string; incoming: number; existing: number }[] = [];
+    for (const spec of group.tables) {
+      const incoming = tableRows(entries, spec.table).length;
+      const { count } = await supabaseAdmin
+        .from(spec.table as never)
+        .select("*", { count: "exact", head: true });
+      tables.push({ table: spec.table, incoming, existing: count ?? 0 });
+    }
+    datasets.push({
+      group: id,
+      label: group.label,
+      insertOnly: Boolean(group.insertOnly),
+      tables,
+      ...(group.special === "mediaFiles"
+        ? { mediaFiles: media.files, mediaBytes: media.bytes }
+        : {}),
+    });
+  }
+
+  // Verify the archive's real media payload against what the export recorded,
+  // so both sides of the round trip report the same usage for marked items.
+  if ((manifest.groups ?? []).includes("mediaFiles")) {
+    if (typeof manifest.mediaFiles === "number" && manifest.mediaFiles !== media.files) {
+      problems.push(
+        `Media file count mismatch — the archive lists ${manifest.mediaFiles.toLocaleString()} files but contains ${media.files.toLocaleString()}.`,
+      );
+    }
+    if (typeof manifest.mediaBytes === "number" && manifest.mediaBytes !== media.bytes) {
+      problems.push(
+        `Media size mismatch — the archive lists ${manifest.mediaBytes.toLocaleString()} bytes but contains ${media.bytes.toLocaleString()}.`,
+      );
+    }
+  }
+
+  return {
+    manifest,
+    compatible: problems.length === 0,
+    problems,
+    mediaFiles: media.files,
+    mediaBytes: media.bytes,
+    quarantinedMedia: media.quarantined,
+    datasets,
+  };
+}
+
+export type ImportResult = {
+  /** False when any row, table or media file could not be restored. */
+  ok: boolean;
+  applied: {
+    table: string;
+    inserted: number;
+    skipped: number;
+    mode: ImportMode;
+    /** Primary keys of rows that could not be written. */
+    failedKeys: string[];
+  }[];
+  /** Tables that were not attempted because a table they depend on failed. */
+  aborted: string[];
+  mediaRestored: number;
+  /** Bytes actually written back to storage. */
+  mediaBytesRestored: number;
+  /** Media payload present in the archive for the selected groups. */
+  mediaFilesInArchive: number;
+  mediaBytesInArchive: number;
+  /** Archive entries that were not media and were deliberately not restored. */
+  quarantinedMedia: string[];
+  warnings: string[];
+};
+
+export async function importArchiveCore(
+  deps: BackupDeps,
+  caller: Caller,
+  bytes: Uint8Array,
+  opts: {
+    groups: string[];
+    mode: ImportMode;
+    includeMedia: boolean;
+    /** When set, hosted media URLs in content are rewritten to this base. */
+    rewriteMediaBase?: string | null;
+    /** Keep restored tracking/code injections switched on. Off by default. */
+    keepInjectionsEnabled?: boolean;
+  },
+): Promise<ImportResult> {
+  const supabaseAdmin = await deps.adminClient();
+  const { entries, manifest } = parseArchive(bytes);
+
+  if (manifest.format !== ARCHIVE_FORMAT_VERSION) {
+    throw new Error(
+      `Incompatible archive — this site reads format ${ARCHIVE_FORMAT_VERSION} archives, this one is format ${manifest.format}. Re-export it from the site that produced it.`,
+    );
+  }
+  if (manifest.schemaVersion !== SCHEMA_VERSION) {
+    throw new Error(
+      `Incompatible archive — it was made for database version ${manifest.schemaVersion}, this site runs version ${SCHEMA_VERSION}.`,
+    );
+  }
+
+  const selected = opts.groups.filter((g) => (manifest.groups ?? []).includes(g));
+  const specs = new Map<string, { spec: TableSpec; insertOnly: boolean }>();
+  for (const id of selected) {
+    const group = groupById(id);
+    if (!group) continue;
+    for (const spec of group.tables)
+      specs.set(spec.table, { spec, insertOnly: Boolean(group.insertOnly) });
+  }
+
+  // Lineage guard: in Merge mode an archive from another database would try to
+  // change the primary key of rows that child tables already reference.
+  if (opts.mode === "merge") {
+    const clashes: string[] = [];
+    for (const [table, keyCol] of Object.entries(LINEAGE_KEYS)) {
+      if (!specs.has(table)) continue;
+      const rows = tableRows(entries, table);
+      if (!rows.length) continue;
+      const spec = specs.get(table)!.spec;
+      if (spec.pk === keyCol) continue; // key *is* the primary key — safe
+      const incoming = new Map(rows.map((r) => [String(r[keyCol]), String(r[spec.pk])]));
+      const { data } = await supabaseAdmin
+        .from(table as never)
+        .select(`${spec.pk},${keyCol}` as never);
+      for (const existing of (data ?? []) as unknown as Record<string, unknown>[]) {
+        const key = String(existing[keyCol]);
+        const incomingId = incoming.get(key);
+        if (incomingId && incomingId !== String(existing[spec.pk])) {
+          clashes.push(`${table}.${keyCol}="${key}"`);
+        }
+      }
+    }
+    if (clashes.length) {
+      throw new Error(
+        `Different database lineage — use Replace on an empty/test database. ` +
+          `${clashes.length} rows already exist here under a different id: ${clashes.slice(0, 5).join(", ")}` +
+          `${clashes.length > 5 ? " …" : ""}`,
+      );
+    }
+  }
+
+  const applied: ImportResult["applied"] = [];
+  const aborted: string[] = [];
+  const warnings: string[] = [];
+  const failedTables = new Set<string>();
+  const deferredWork: {
+    table: string;
+    pk: string;
+    rows: Record<string, unknown>[];
+    cols: string[];
+  }[] = [];
+
+  const base = opts.rewriteMediaBase?.trim();
+  const prepare = (table: string, row: Record<string, unknown>) => {
+    let out = base ? rewriteMediaUrls(row, base) : row;
+    if (table === "site_injections") {
+      out = neutralizeInjection(out, Boolean(opts.keepInjectionsEnabled));
+    }
+    return out;
+  };
+
+  for (const table of IMPORT_ORDER) {
+    const entry = specs.get(table);
+    if (!entry) continue;
+
+    // Never write into a table whose parent failed — it can only cascade.
+    const blockedBy = (entry.spec.requires ?? []).filter((t) => failedTables.has(t));
+    if (blockedBy.length) {
+      aborted.push(table);
+      failedTables.add(table);
+      warnings.push(`${table}: skipped because ${blockedBy.join(", ")} did not restore cleanly.`);
+      continue;
+    }
+
+    let rows = tableRows(entries, table);
+
+    // Older/companion payload: rebuild account rows from the auth user list so
+    // role assignments have a parent row to reference.
+    if (table === "app_users" && !rows.length) {
+      const auth = tableRows(entries, "auth_users");
+      rows = auth.map((u) => ({
+        id: u["id"],
+        email: u["email"] ?? null,
+        display_name:
+          (u["user_metadata"] as Record<string, unknown> | null)?.["full_name"] ??
+          (u["user_metadata"] as Record<string, unknown> | null)?.["name"] ??
+          null,
+        created_at: u["created_at"] ?? new Date().toISOString(),
+      }));
+    }
+
+    if (!rows.length) continue;
+
+    const insertOnly = entry.insertOnly;
+    const mode: ImportMode = insertOnly ? "merge" : opts.mode;
+    const conflict = entry.spec.conflict ?? entry.spec.pk;
+
+    if (mode === "replace" && !insertOnly) {
+      const { error } = await supabaseAdmin
+        .from(table as never)
+        .delete()
+        .not(entry.spec.pk, "is", null);
+      if (error) {
+        warnings.push(`Could not clear ${table}: ${error.message}`);
+        failedTables.add(table);
+      }
+    }
+
+    const deferred = entry.spec.deferred ?? [];
+    const payload = rows.map((r) => {
+      const copy = prepare(table, { ...r });
+      for (const c of deferred) copy[c] = null;
+      return copy;
+    });
+    if (deferred.length) {
+      deferredWork.push({ table, pk: entry.spec.pk, rows, cols: deferred });
+    }
+
+    const write = async (chunk: Record<string, unknown>[]) => {
+      const q = insertOnly
+        ? supabaseAdmin
+            .from(table as never)
+            .upsert(chunk as never, { onConflict: conflict, ignoreDuplicates: true })
+        : supabaseAdmin.from(table as never).upsert(chunk as never, { onConflict: conflict });
+      return (await q).error;
+    };
+
+    let inserted = 0;
+    let skipped = 0;
+    const failedKeys: string[] = [];
+    for (let i = 0; i < payload.length; i += WRITE_CHUNK) {
+      const chunk = payload.slice(i, i + WRITE_CHUNK);
+      const error = await write(chunk);
+      if (!error) {
+        inserted += chunk.length;
+        continue;
+      }
+      // One bad row must not discard the rest of the batch — retry row by row.
+      warnings.push(`${table}: batch failed (${error.message}) — retrying row by row.`);
+      for (const row of chunk) {
+        const rowError = await write([row]);
+        if (rowError) {
+          skipped += 1;
+          failedKeys.push(String(row[entry.spec.pk] ?? "(unknown)"));
+          warnings.push(`${table} ${String(row[entry.spec.pk] ?? "?")}: ${rowError.message}`);
+        } else {
+          inserted += 1;
+        }
+      }
+    }
+    if (skipped) failedTables.add(table);
+    applied.push({ table, inserted, skipped, mode, failedKeys });
+  }
+
+  // Second pass for self-referencing columns (e.g. pages.current_version_id).
+  for (const job of deferredWork) {
+    for (const row of job.rows) {
+      const patch: Record<string, unknown> = {};
+      let has = false;
+      for (const c of job.cols) {
+        if (row[c] != null) {
+          patch[c] = row[c];
+          has = true;
+        }
+      }
+      if (!has) continue;
+      const { error } = await supabaseAdmin
+        .from(job.table as never)
+        .update(patch as never)
+        .eq(job.pk, row[job.pk] as never);
+      if (error) {
+        warnings.push(`${job.table} link: ${error.message}`);
+        failedTables.add(job.table);
+      }
+    }
+  }
+
+  const archiveMedia = selected.includes("mediaFiles")
+    ? measureMedia(entries)
+    : { files: 0, bytes: 0, quarantined: [] as string[] };
+
+  let mediaRestored = 0;
+  let mediaBytesRestored = 0;
+  if (opts.includeMedia && selected.includes("mediaFiles")) {
+    const storage = getMediaStorage(caller.supabase);
+    for (const key of Object.keys(entries)) {
+      if (!key.startsWith("media/")) continue;
+      const name = key.slice("media/".length);
+      if (!name) continue;
+      // Entries whose own bytes are not verified media (e.g. saved HTML pages)
+      // are never written back: serving them from the media origin is unsafe.
+      const bytes = entries[key]!;
+      if (!isSafeArchivePath(name) || !verifyMediaFile(name, bytes).ok) continue;
+
+      try {
+        await storage.upload(name, bytes, contentTypeFor(name), { upsert: true });
+        mediaRestored += 1;
+        mediaBytesRestored += bytes.byteLength;
+      } catch (e) {
+        warnings.push(`media ${name}: ${e instanceof Error ? e.message : String(e)}`);
+      }
+    }
+    if (mediaRestored !== archiveMedia.files || mediaBytesRestored !== archiveMedia.bytes) {
+      warnings.push(
+        `Media restore incomplete — ${mediaRestored.toLocaleString()}/${archiveMedia.files.toLocaleString()} files (${mediaBytesRestored.toLocaleString()}/${archiveMedia.bytes.toLocaleString()} bytes) written.`,
+      );
+      failedTables.add("media");
+    }
+  }
+  if (archiveMedia.quarantined.length) {
+    warnings.push(
+      `${archiveMedia.quarantined.length} archive entries were not media and were not restored: ${archiveMedia.quarantined
+        .slice(0, 5)
+        .join(", ")}${archiveMedia.quarantined.length > 5 ? " …" : ""}`,
+    );
+  }
+
+  if (selected.includes("users")) {
+    warnings.push(
+      "Sign-in credentials cannot be restored — accounts and roles are back, but every user must set a new password.",
+    );
+  }
+
+  const ok = failedTables.size === 0 && aborted.length === 0;
+
+  await audit(deps, caller, "backup.import", {
+    groups: selected,
+    mode: opts.mode,
+    ok,
+    applied,
+    aborted,
+    rewriteMediaBase: base ?? null,
+    mediaRestored,
+    mediaBytesRestored,
+    mediaFilesInArchive: archiveMedia.files,
+    mediaBytesInArchive: archiveMedia.bytes,
+    quarantinedMedia: archiveMedia.quarantined.length,
+    warnings: warnings.slice(0, 20),
+  });
+
+  return {
+    ok,
+    applied,
+    aborted,
+    mediaRestored,
+    mediaBytesRestored,
+    mediaFilesInArchive: archiveMedia.files,
+    mediaBytesInArchive: archiveMedia.bytes,
+    quarantinedMedia: archiveMedia.quarantined,
+    warnings,
+  };
+}
+
+function contentTypeFor(name: string): string {
+  const ext = name.slice(name.lastIndexOf(".")).toLowerCase();
+  const map: Record<string, string> = {
+    ".webp": "image/webp",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".png": "image/png",
+    ".gif": "image/gif",
+    ".svg": "image/svg+xml",
+    ".avif": "image/avif",
+    ".mp4": "video/mp4",
+    ".webm": "video/webm",
+    ".mov": "video/quicktime",
+    ".pdf": "application/pdf",
+  };
+  return map[ext] ?? "application/octet-stream";
+}