@bygghammar/cms-platform 0.38.1 → 0.39.0

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 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.39.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,8 @@
     "./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"
   },
   "dependencies": {
     "fflate": "^0.8.3"

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";
+}