@morphika/andami 0.2.8 → 0.2.10

package/app/api/admin/backups/export/route.ts

@@ -0,0 +1,76 @@
+import { NextRequest, NextResponse } from "next/server";
+import { Readable } from "node:stream";
+import { isAdminAuthenticated } from "../../../../../lib/auth";
+import { checkRateLimit, jsonError } from "../../../../../lib/security";
+import { createBackupStream } from "../../../../../lib/backup/export";
+import { logger } from "../../../../../lib/logger";
+
+/**
+ * GET /api/admin/backups/export — Stream a full site backup as a ZIP file.
+ *
+ * @deprecated V1 endpoint — routes all binary data through Vercel.
+ * Use `GET /api/admin/backups/prepare-export` (V2) instead, which returns
+ * lightweight JSON and lets the browser download assets directly from R2.
+ * This endpoint is kept for backwards compatibility with small sites and
+ * local development. Will be removed in a future version.
+ *
+ * The response is a streaming ZIP containing:
+ *   - manifest.json (backup metadata)
+ *   - sanity/*.json (all CMS documents)
+ *   - assets/** (all R2 files, preserving folder structure)
+ *
+ * Auth required. Rate limited to 1 per minute (backups are expensive).
+ * No CSRF check needed — GET request, no mutation.
+ */
+export async function GET(request: NextRequest) {
+  // L-9: instance-level kill switch for the V1 flow.
+  // Setting `BACKUPS_V1_DISABLED=true` in the instance env disables this
+  // endpoint cleanly with a 410 Gone. Hosts on Vercel Hobby that only
+  // want the V2 client-side flow can flip this without redeploying the
+  // framework. We accept both the `NEXT_PUBLIC_*` and server-only env
+  // names — either is fine since this endpoint runs server-side.
+  const v1Disabled =
+    process.env.BACKUPS_V1_DISABLED === "true" ||
+    process.env.NEXT_PUBLIC_BACKUPS_V1_DISABLED === "true";
+  if (v1Disabled) {
+    return jsonError(
+      "V1 backup export is disabled on this instance. Use the V2 client-side flow (GET /api/admin/backups/prepare-export).",
+      410
+    );
+  }
+
+  if (!(await isAdminAuthenticated())) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+
+  // Rate limit: 1 backup per minute per IP
+  const ip = request.headers.get("x-forwarded-for") || "unknown";
+  if (!checkRateLimit(`backup-export:${ip}`, 1, 60_000)) {
+    return jsonError("Backup already in progress. Please wait.", 429);
+  }
+
+  try {
+    logger.info("[Admin:Backup]", "Starting backup export...");
+
+    const { stream, filename } = await createBackupStream();
+
+    // Convert Node.js Readable to Web ReadableStream for the Response
+    const webStream = Readable.toWeb(stream) as ReadableStream;
+
+    return new Response(webStream, {
+      status: 200,
+      headers: {
+        "Content-Type": "application/zip",
+        "Content-Disposition": `attachment; filename="${filename}"`,
+        // No caching — each backup is unique
+        "Cache-Control": "no-store",
+      },
+    });
+  } catch (err) {
+    logger.error("[Admin:Backup]", "Backup export failed", err);
+    return jsonError(
+      err instanceof Error ? err.message : "Backup export failed",
+      500
+    );
+  }
+}

package/app/api/admin/backups/prepare-export/route.ts

@@ -0,0 +1,56 @@
+import { NextRequest, NextResponse } from "next/server";
+import { isAdminAuthenticated } from "../../../../../lib/auth";
+import { checkRateLimit, jsonError } from "../../../../../lib/security";
+import { prepareExportData } from "../../../../../lib/backup/export";
+import { logger } from "../../../../../lib/logger";
+
+/**
+ * GET /api/admin/backups/prepare-export — V2 client-side export data.
+ *
+ * Returns all data needed for the browser to build the backup ZIP locally:
+ *   - manifest: backup metadata
+ *   - documents: all Sanity documents (R2 credentials stripped)
+ *   - assets: R2 public URL + flat file list for direct browser download
+ *
+ * The browser then:
+ *   1. Downloads each asset directly from R2 CDN
+ *   2. Builds the ZIP in memory with JSZip
+ *   3. Triggers a browser download
+ *
+ * This keeps all binary asset traffic off Vercel — the response is
+ * lightweight JSON (typically 50–500 KB). Completes in <2 seconds.
+ *
+ * Auth required. Rate limited to 1 per minute.
+ */
+export async function GET(request: NextRequest) {
+  if (!(await isAdminAuthenticated())) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+
+  // Rate limit: 1 per minute per IP
+  const ip = request.headers.get("x-forwarded-for") || "unknown";
+  if (!checkRateLimit(`backup-prepare-export:${ip}`, 1, 60_000)) {
+    return jsonError("Export already in progress. Please wait.", 429);
+  }
+
+  try {
+    logger.info("[Admin:Backup]", "Preparing V2 export data...");
+
+    const data = await prepareExportData();
+
+    logger.info(
+      "[Admin:Backup]",
+      `V2 export prepared: ${data.documents.pages.length} pages, ${data.assets.files.length} assets`
+    );
+
+    return NextResponse.json(data, {
+      headers: { "Cache-Control": "no-store" },
+    });
+  } catch (err) {
+    logger.error("[Admin:Backup]", "Prepare export failed", err);
+    return jsonError(
+      err instanceof Error ? err.message : "Prepare export failed",
+      500
+    );
+  }
+}

package/app/api/admin/backups/restore/route.ts

@@ -0,0 +1,131 @@
+import { NextRequest, NextResponse } from "next/server";
+import { isAdminAuthenticated } from "../../../../../lib/auth";
+import { validateCsrf, csrfErrorResponse } from "../../../../../lib/csrf";
+import { checkRateLimit, jsonError } from "../../../../../lib/security";
+import { restoreFromBackup } from "../../../../../lib/backup/restore";
+import { logger } from "../../../../../lib/logger";
+
+/** Max upload size: 500 MB */
+const MAX_RESTORE_SIZE = 500 * 1024 * 1024;
+
+/**
+ * POST /api/admin/backups/restore — Restore site from a backup ZIP.
+ *
+ * @deprecated V1 endpoint — receives the entire ZIP (including binary assets)
+ * through Vercel, hitting the 4.5 MB body limit and 10s function timeout.
+ * Use `POST /api/admin/backups/restore-data` (V2) instead, which accepts
+ * only JSON documents. The browser uploads assets directly to R2 via
+ * presigned PUT URLs. This endpoint is kept for backwards compatibility.
+ * Will be removed in a future version.
+ *
+ * Accepts multipart/form-data with a single "file" field containing
+ * the .zip backup archive. Performs a full wipe-and-replace:
+ *   1. Validates the backup manifest
+ *   2. Wipes all Sanity documents
+ *   3. Restores documents from the backup
+ *   4. Wipes and re-uploads R2 assets (if R2 is connected)
+ *
+ * Auth + CSRF required. Rate limited to 1 per 5 minutes.
+ */
+export async function POST(request: NextRequest) {
+  // L-9: instance-level kill switch for the V1 flow — same env var used
+  // by `GET /api/admin/backups/export`. Returns 410 Gone so the admin UI
+  // can surface a clear "V1 disabled" message rather than a confusing
+  // 401/405 when a user tries to hit the legacy route.
+  const v1Disabled =
+    process.env.BACKUPS_V1_DISABLED === "true" ||
+    process.env.NEXT_PUBLIC_BACKUPS_V1_DISABLED === "true";
+  if (v1Disabled) {
+    return jsonError(
+      "V1 backup restore is disabled on this instance. Use the V2 client-side flow (POST /api/admin/backups/restore-data).",
+      410
+    );
+  }
+
+  if (!(await isAdminAuthenticated())) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  if (!validateCsrf(request)) {
+    return csrfErrorResponse();
+  }
+
+  // Rate limit: 1 restore per 5 minutes per IP
+  const ip = request.headers.get("x-forwarded-for") || "unknown";
+  if (!checkRateLimit(`backup-restore:${ip}`, 1, 300_000)) {
+    return jsonError(
+      "A restore is already in progress or was recently completed. Please wait 5 minutes.",
+      429
+    );
+  }
+
+  try {
+    // Parse multipart form data
+    const contentType = request.headers.get("content-type") || "";
+    if (!contentType.includes("multipart/form-data")) {
+      return jsonError(
+        "Expected multipart/form-data with a ZIP file",
+        400
+      );
+    }
+
+    // Check Content-Length before reading the body
+    const contentLength = request.headers.get("content-length");
+    if (contentLength) {
+      const size = parseInt(contentLength, 10);
+      if (!isNaN(size) && size > MAX_RESTORE_SIZE) {
+        return jsonError(
+          `Backup file too large. Maximum size is ${MAX_RESTORE_SIZE / 1024 / 1024} MB.`,
+          413
+        );
+      }
+    }
+
+    const formData = await request.formData();
+    const file = formData.get("file");
+
+    if (!file || !(file instanceof File)) {
+      return jsonError(
+        'Missing "file" field in form data. Upload the backup .zip file.',
+        400
+      );
+    }
+
+    // Validate file size
+    if (file.size > MAX_RESTORE_SIZE) {
+      return jsonError(
+        `Backup file too large (${(file.size / 1024 / 1024).toFixed(1)} MB). Maximum is ${MAX_RESTORE_SIZE / 1024 / 1024} MB.`,
+        413
+      );
+    }
+
+    // Validate file type (basic check)
+    if (!file.name.endsWith(".zip") && file.type !== "application/zip") {
+      return jsonError("Only .zip backup files are accepted", 400);
+    }
+
+    logger.info(
+      "[Admin:Backup]",
+      `Starting restore from "${file.name}" (${(file.size / 1024 / 1024).toFixed(1)} MB)`
+    );
+
+    // Read the file into a Buffer
+    const arrayBuffer = await file.arrayBuffer();
+    const zipBuffer = Buffer.from(arrayBuffer);
+
+    // Run the restore
+    const result = await restoreFromBackup(zipBuffer);
+
+    logger.info(
+      "[Admin:Backup]",
+      `Restore completed in ${(result.duration_ms / 1000).toFixed(1)}s`
+    );
+
+    return NextResponse.json(result);
+  } catch (err) {
+    logger.error("[Admin:Backup]", "Restore failed", err);
+    return jsonError(
+      err instanceof Error ? err.message : "Restore failed",
+      500
+    );
+  }
+}

package/app/api/admin/backups/restore-data/route.ts

@@ -0,0 +1,424 @@
+import { NextRequest, NextResponse } from "next/server";
+import { isAdminAuthenticated } from "../../../../../lib/auth";
+import { validateCsrf, csrfErrorResponse } from "../../../../../lib/csrf";
+import {
+  checkRateLimit,
+  jsonError,
+  isValidAssetPath,
+  isBodyTooLarge,
+  MAX_PAGE_BODY_SIZE,
+} from "../../../../../lib/security";
+import { validateManifest } from "../../../../../lib/backup/manifest";
+import { wipeAllDocuments, restoreDocuments, type AndamiDocType } from "../../../../../lib/backup/sanity-ops";
+import {
+  getR2Config,
+  createS3Client,
+  deleteAllR2Files,
+  generatePresignedUploadUrls,
+  type PresignedUpload,
+} from "../../../../../lib/backup/r2-helpers";
+import { isBackupAssetFile } from "../../../../../lib/storage/types";
+import { logger } from "../../../../../lib/logger";
+
+/**
+ * Bounds for the presigned PUT URL TTL requested by the client (M-8).
+ *
+ * The server always clamps the requested TTL to a safe range:
+ * - `MIN_UPLOAD_TTL_SECONDS` (5 min): the minimum useful upload window.
+ *   Anything shorter and even medium assets can time out mid-flight.
+ * - `MAX_UPLOAD_TTL_SECONDS` (1 hour): matches S3/R2's maximum presigned
+ *   URL TTL for SigV4 credentials. Beyond 1h the signature is rejected.
+ * - `DEFAULT_UPLOAD_TTL_SECONDS` (30 min): safe default for typical
+ *   portfolio sites with 100–200 assets at ~1 MB each over home fiber.
+ */
+const MIN_UPLOAD_TTL_SECONDS = 300;
+const MAX_UPLOAD_TTL_SECONDS = 3600;
+const DEFAULT_UPLOAD_TTL_SECONDS = 1800;
+
+/** Max number of asset keys the client can request presigning for in one call. */
+const MAX_ASSET_KEYS = 5000;
+
+/**
+ * Map of document-section keys in the request body to Sanity `_type` values.
+ * Defined at module scope so both the early validator and the restore loop
+ * share one source of truth.
+ */
+const DOC_MAP: { key: string; type: AndamiDocType }[] = [
+  { key: "pages", type: "page" },
+  { key: "siteSettings", type: "siteSettings" },
+  { key: "siteStyles", type: "siteStyles" },
+  { key: "assetRegistry", type: "assetRegistry" },
+  { key: "customSections", type: "customSection" },
+];
+
+/**
+ * POST /api/admin/backups/restore-data — V2 Sanity-only restore.
+ *
+ * Receives only Sanity documents (JSON), performs wipe + restore, and
+ * optionally pre-signs all asset upload URLs server-side so the browser
+ * can push binaries straight to R2 without invoking Vercel once per file.
+ *
+ * Request body (JSON, typically 50 KB–5 MB — hard cap = MAX_PAGE_BODY_SIZE):
+ * {
+ *   manifest: BackupManifest,
+ *   documents: { pages, siteSettings, siteStyles, assetRegistry, customSections },
+ *   wipe_r2: boolean,                                 // whether to wipe existing R2 assets
+ *   assets?: Array<{ key: string, size: number }>,    // keys to pre-sign
+ *   upload_ttl_seconds?: number                        // clamped to [MIN..MAX]
+ * }
+ *
+ * Response:
+ * {
+ *   success: boolean,
+ *   sanity: { wiped: Record<string, number>, restored: Record<string, number> },
+ *   r2_wiped: number | null,
+ *   upload_urls?: Array<{ key: string, uploadUrl: string, contentType: string }>,
+ *   upload_ttl_seconds?: number,
+ *   duration_ms: number
+ * }
+ *
+ * This endpoint is lightweight — body is JSON only (well within Vercel's
+ * 4.5 MB limit, and we enforce a stricter 5 MB application-level cap via
+ * `MAX_PAGE_BODY_SIZE` to prevent huge bodies from burning CPU on a parse
+ * that will fail anyway). Generating hundreds of presigned URLs is pure
+ * local HMAC (~a few hundred ms of CPU).
+ *
+ * Auth + CSRF required. Rate limited to 1 per 5 minutes.
+ */
+export async function POST(request: NextRequest) {
+  if (!(await isAdminAuthenticated())) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  if (!validateCsrf(request)) {
+    return csrfErrorResponse();
+  }
+
+  // M-2: reject oversize bodies up front so we don't spend CPU on
+  // `request.json()` for a payload we'll refuse anyway. Vercel's platform
+  // cap is ~4.5 MB; our app cap is MAX_PAGE_BODY_SIZE (5 MB — matches page
+  // builder saves, which is the largest JSON body in the framework).
+  if (isBodyTooLarge(request, MAX_PAGE_BODY_SIZE)) {
+    return jsonError(
+      `Request body too large. Max ${MAX_PAGE_BODY_SIZE} bytes.`,
+      413
+    );
+  }
+
+  // Rate limit: 1 restore per 5 minutes per IP
+  const ip = request.headers.get("x-forwarded-for") || "unknown";
+  if (!checkRateLimit(`backup-restore-data:${ip}`, 1, 300_000)) {
+    return jsonError(
+      "A restore is already in progress or was recently completed. Please wait 5 minutes.",
+      429
+    );
+  }
+
+  const startTime = Date.now();
+
+  try {
+    // ── Parse JSON body ──
+    const contentType = request.headers.get("content-type") || "";
+    if (!contentType.includes("application/json")) {
+      return jsonError("Expected application/json", 400);
+    }
+
+    const body = await request.json();
+
+    // ── Validate manifest ──
+    if (!body.manifest) {
+      return jsonError("Missing manifest in request body", 400);
+    }
+    const manifest = validateManifest(body.manifest);
+
+    // ── Validate documents ──
+    if (!body.documents || typeof body.documents !== "object") {
+      return jsonError("Missing documents in request body", 400);
+    }
+
+    const { documents } = body;
+    const wipeR2 = body.wipe_r2 === true;
+
+    // ── L-5: shape validation per section ──
+    // Before we touch Sanity we verify that each section is the expected
+    // shape: a list for plural sections and either a single object or null
+    // for singleton sections. Without this guard a client could send a
+    // string / number / boolean and `restoreDocuments` would happily no-op
+    // it — meaning a mistyped field silently drops documents during restore.
+    // Erroring out with a 400 here is much friendlier than completing the
+    // wipe and discovering the docs were never restored.
+    const PLURAL_SECTIONS = ["pages", "customSections"] as const;
+    const SINGLETON_SECTIONS = [
+      "siteSettings",
+      "siteStyles",
+      "assetRegistry",
+    ] as const;
+
+    for (const key of PLURAL_SECTIONS) {
+      const data = documents[key];
+      if (data === null || data === undefined) continue;
+      if (!Array.isArray(data)) {
+        return jsonError(
+          `Invalid documents payload: '${key}' must be an array or null, received '${typeof data}'.`,
+          400
+        );
+      }
+    }
+    for (const key of SINGLETON_SECTIONS) {
+      const data = documents[key];
+      if (data === null || data === undefined) continue;
+      if (typeof data !== "object" || Array.isArray(data)) {
+        return jsonError(
+          `Invalid documents payload: '${key}' must be an object or null, received '${
+            Array.isArray(data) ? "array" : typeof data
+          }'.`,
+          400
+        );
+      }
+    }
+
+    // ── M-4: early `_type` validation per section ──
+    // `restoreDocuments` already carries a safety net that skips docs
+    // whose `_type` doesn't match the batch type, but by the time we get
+    // there we've already wiped Sanity. Catching the mismatch _before_
+    // wiping saves CPU and gives the admin a clean error instead of a
+    // half-wiped dataset.
+    //
+    // We only fail the request if the discriminator is present AND wrong.
+    // Missing `_type` is acceptable — `restoreDocuments` will backfill it.
+    for (const { key, type } of DOC_MAP) {
+      const data = documents[key];
+      if (data === null || data === undefined) continue;
+      const docsInSection = Array.isArray(data) ? data : [data];
+      for (const rawDoc of docsInSection) {
+        if (!rawDoc || typeof rawDoc !== "object") continue;
+        const docType = (rawDoc as { _type?: unknown })._type;
+        if (typeof docType === "string" && docType !== type) {
+          const docId =
+            typeof (rawDoc as { _id?: unknown })._id === "string"
+              ? (rawDoc as { _id: string })._id
+              : "(no-id)";
+          logger.warn(
+            "[Admin:Backup]",
+            `Rejecting body: documents.${key} contains a '${docType}' doc (${docId}); expected '${type}'`
+          );
+          return jsonError(
+            `Invalid documents payload: '${key}' section contains a document with _type='${docType}' but expected '${type}'.`,
+            400
+          );
+        }
+      }
+    }
+
+    // ── L-7: non-blocking manifest count verification ──
+    // Compare what the manifest claims against what's actually in the body.
+    // We do NOT abort on mismatch — a legitimate editing workflow (e.g. the
+    // admin pruned content between export and restore) can produce fewer
+    // docs than the manifest recorded. But we warn to server logs and
+    // accumulate a `manifest_mismatches` array that ships in the response
+    // so the UI can flag it. Manifest field names use snake_case; body
+    // sections use camelCase — so we translate here.
+    const manifestMismatches: Array<{ section: string; manifest: number; actual: number }> = [];
+    const manifestCounts = manifest.documents;
+    const sectionPairs: Array<[keyof typeof manifestCounts, string]> = [
+      ["pages", "pages"],
+      ["custom_sections", "customSections"],
+      ["site_settings", "siteSettings"],
+      ["site_styles", "siteStyles"],
+      ["asset_registry", "assetRegistry"],
+    ];
+    for (const [manifestKey, bodyKey] of sectionPairs) {
+      const manifestCount = manifestCounts[manifestKey];
+      const bodyValue = documents[bodyKey];
+      let actualCount = 0;
+      if (Array.isArray(bodyValue)) {
+        actualCount = bodyValue.length;
+      } else if (bodyValue && typeof bodyValue === "object") {
+        actualCount = 1;
+      }
+      if (manifestCount !== actualCount) {
+        manifestMismatches.push({
+          section: bodyKey,
+          manifest: manifestCount,
+          actual: actualCount,
+        });
+      }
+    }
+    if (manifestMismatches.length > 0) {
+      logger.warn(
+        "[Admin:Backup]",
+        `Manifest/body count mismatch — continuing restore: ${JSON.stringify(
+          manifestMismatches
+        )}`
+      );
+    }
+
+    // ── Validate & sanitize the optional asset key list ──
+    // The browser passes this so we can pre-sign upload URLs in one go.
+    // Reject clearly-invalid keys defensively so a compromised or buggy
+    // client can't get presigned URLs for things like "../../etc/passwd".
+    const rawAssets = Array.isArray(body.assets) ? body.assets : [];
+    if (rawAssets.length > MAX_ASSET_KEYS) {
+      return jsonError(
+        `Too many assets in request (${rawAssets.length}). Max ${MAX_ASSET_KEYS}.`,
+        400
+      );
+    }
+
+    // ── M-8: resolve + clamp presigned-URL TTL ──
+    // Accept a client-requested `upload_ttl_seconds` but clamp to a safe
+    // range. Slow connections benefit from a longer TTL; very long TTLs
+    // weaken the security posture of leaked URLs, so the server makes
+    // the final call.
+    let uploadTtlSeconds = DEFAULT_UPLOAD_TTL_SECONDS;
+    const requestedTtlRaw = body.upload_ttl_seconds;
+    if (typeof requestedTtlRaw === "number" && Number.isFinite(requestedTtlRaw)) {
+      uploadTtlSeconds = Math.round(
+        Math.min(
+          MAX_UPLOAD_TTL_SECONDS,
+          Math.max(MIN_UPLOAD_TTL_SECONDS, requestedTtlRaw)
+        )
+      );
+    }
+    const assetKeys: string[] = [];
+    const rejectedKeys: string[] = [];
+    for (const entry of rawAssets) {
+      const key = entry && typeof entry === "object" && typeof (entry as { key?: unknown }).key === "string"
+        ? ((entry as { key: string }).key).trim()
+        : "";
+      if (!key) continue;
+      // Path safety + extension allow-list (media + fonts + PDF).
+      if (!isValidAssetPath(key) || !isBackupAssetFile(key)) {
+        rejectedKeys.push(key);
+        continue;
+      }
+      assetKeys.push(key);
+    }
+
+    logger.info(
+      "[Admin:Backup]",
+      `Starting V2 restore (wipe_r2=${wipeR2}, assets=${assetKeys.length}${
+        rejectedKeys.length > 0 ? `, rejected=${rejectedKeys.length}` : ""
+      })...`
+    );
+
+    // ── Phase 1: Wipe all existing Sanity documents ──
+    logger.info("[Admin:Backup]", "Wiping existing Sanity documents...");
+    const wiped = await wipeAllDocuments();
+
+    // ── Phase 2: Restore documents from backup ──
+    logger.info("[Admin:Backup]", "Restoring Sanity documents...");
+    const restored: Record<string, number> = {};
+
+    for (const { key, type } of DOC_MAP) {
+      const data = documents[key];
+      if (data !== null && data !== undefined) {
+        restored[type] = await restoreDocuments(type, data);
+      } else {
+        restored[type] = 0;
+      }
+    }
+
+    // ── Phase 3 (optional): Wipe R2 assets + pre-sign upload URLs ──
+    // Both operations share the same R2 config, so we fetch/build the S3
+    // client once and reuse it.
+    let r2Wiped: number | null = null;
+    let uploadUrls: PresignedUpload[] | undefined;
+
+    const needsR2 = wipeR2 || assetKeys.length > 0;
+    if (needsR2) {
+      const r2Config = await getR2Config();
+      if (r2Config) {
+        const s3 = createS3Client(r2Config);
+
+        if (wipeR2) {
+          try {
+            logger.info("[Admin:Backup]", "Wiping existing R2 assets...");
+            r2Wiped = await deleteAllR2Files(s3, r2Config.bucketName);
+            logger.info(
+              "[Admin:Backup]",
+              `Deleted ${r2Wiped} existing R2 file(s)`
+            );
+          } catch (err) {
+            logger.error(
+              "[Admin:Backup]",
+              "Failed to wipe R2 bucket",
+              err
+            );
+            // Don't fail the entire restore — Sanity docs are already restored.
+            // The client will upload over existing files.
+            r2Wiped = -1; // Signal that wipe was attempted but failed
+          }
+        }
+
+        if (assetKeys.length > 0) {
+          try {
+            logger.info(
+              "[Admin:Backup]",
+              `Generating ${assetKeys.length} presigned upload URL(s) (TTL=${uploadTtlSeconds}s)...`
+            );
+            uploadUrls = await generatePresignedUploadUrls(
+              s3,
+              r2Config.bucketName,
+              assetKeys,
+              uploadTtlSeconds
+            );
+          } catch (err) {
+            logger.error(
+              "[Admin:Backup]",
+              "Failed to generate presigned upload URLs",
+              err
+            );
+            // Leave uploadUrls undefined — the client will surface this.
+          }
+        }
+      } else {
+        logger.info(
+          "[Admin:Backup]",
+          "R2 not connected — skipping wipe and presign"
+        );
+      }
+    }
+
+    // ── Done ──
+    const durationMs = Date.now() - startTime;
+    logger.info(
+      "[Admin:Backup]",
+      `V2 restore completed in ${(durationMs / 1000).toFixed(1)}s`
+    );
+
+    return NextResponse.json({
+      success: true,
+      sanity: { wiped, restored },
+      r2_wiped: r2Wiped,
+      upload_urls: uploadUrls,
+      upload_ttl_seconds: uploadUrls ? uploadTtlSeconds : undefined,
+      // L-7: ship the non-blocking manifest/body count mismatch array so
+      // the UI can surface a friendly "heads up — the backup claimed N
+      // docs but only M were restored" note. Empty array means fully
+      // consistent.
+      manifest_mismatches: manifestMismatches,
+      duration_ms: durationMs,
+    });
+  } catch (err) {
+    // L-4: sanitize the error surface returned to the client.
+    //
+    // In development we keep the raw message because it's invaluable while
+    // iterating locally. In production we always return a generic message
+    // and emit a correlation id (`requestId`) that the server-side log line
+    // below carries — admins who hit this can paste the id to the dev team
+    // and we can look up the full stack without the client ever seeing it.
+    const requestId = crypto.randomUUID();
+    logger.error(
+      "[Admin:Backup]",
+      `V2 restore failed (requestId=${requestId})`,
+      err
+    );
+    const isDev = process.env.NODE_ENV !== "production";
+    const clientMessage = isDev
+      ? err instanceof Error
+        ? err.message
+        : "Restore failed"
+      : `Restore failed. If this persists, contact support with requestId=${requestId}.`;
+    return jsonError(clientMessage, 500);
+  }
+}