create-nextblock 0.16.4 → 0.17.0

package/templates/nextblock-template/lib/email/branding-format.ts

@@ -1,123 +1,123 @@
-// Pure, dependency-free rendering of the transactional-email brand header. Kept separate
-// from branding.ts (which is `server-only` and hits the DB) so this string logic — the
-// part worth unit-testing — imports nothing server-side and runs anywhere.
-
-// Tenant branding used to white-label every transactional email.
-//   - logoUrl  — an ABSOLUTE, email-safe logo URL, or `null` when none is configured.
-//   - siteName — the site name, used as the logo `alt` text and the no-logo text banner.
-export interface EmailBranding {
-  logoUrl: string | null;
-  siteName: string;
-}
-
-/**
- * Marker an app-rendered email template drops where the brand header belongs.
- * `applyEmailBranding` swaps it for the resolved logo (or text banner). This is a plain
- * literal — NOT a Supabase/GoTrue `{{ .Var }}` merge tag — because it is substituted by
- * our own nodemailer pipeline, never by Supabase.
- */
-export const EMAIL_BRAND_HEADER_TOKEN = '{{brand_header}}';
-
-/** Hard width cap so an oversized custom logo can't blow out Gmail/Outlook layouts. */
-export const EMAIL_LOGO_MAX_WIDTH = 150;
-
-// The pre-white-label hardcoded logo. The app templates no longer embed it, but any stray
-// occurrence in an outbound email is swapped for the tenant header defensively.
-const LEGACY_LOGO_IMG_RE =
-  /<img\b[^>]*\bsrc=["'][^"']*nextblock-logo-small\.webp["'][^>]*>/gi;
-
-function escapeHtml(value: string): string {
-  return value
-    .replace(/&/g, '&amp;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;')
-    .replace(/'/g, '&#39;');
-}
-
-/**
- * Render the branded header block: an email-safe logo `<img>` (hard-capped at 150px so a
- * large custom logo can't break the layout) when a logo exists, otherwise a clean, styled
- * text banner showing the site name.
- */
-export function renderEmailBrandHeader(branding: EmailBranding): string {
-  const name = escapeHtml(branding.siteName);
-
-  if (branding.logoUrl) {
-    const src = escapeHtml(branding.logoUrl);
-    return (
-      '<div style="text-align:center;padding:0 0 24px;">' +
-      `<img src="${src}" alt="${name}" width="${EMAIL_LOGO_MAX_WIDTH}" ` +
-      `style="display:block;margin:0 auto;width:${EMAIL_LOGO_MAX_WIDTH}px;` +
-      'max-width:100%;height:auto;border:0;outline:none;text-decoration:none;" />' +
-      '</div>'
-    );
-  }
-
-  // No logo → strip the image entirely and fall back to a text banner with the site name.
-  return (
-    '<div style="text-align:center;padding:0 0 24px;">' +
-    '<span style="display:inline-block;font-family:-apple-system,BlinkMacSystemFont,' +
-    "'Segoe UI',Roboto,Helvetica,Arial,sans-serif;font-size:22px;line-height:1.2;" +
-    `font-weight:700;color:#0f172a;letter-spacing:-0.01em;">${name}</span>` +
-    '</div>'
-  );
-}
-
-/**
- * Intercept a fully-rendered email body and apply tenant branding:
- *   1. Replace the `{{brand_header}}` token (used by our app-rendered templates).
- *   2. Defensively swap any stray hardcoded legacy NextBlock logo `<img>` for the header.
- * Purely a string transform so it is trivially unit-testable and side-effect free.
- */
-export function applyEmailBranding(html: string, branding: EmailBranding): string {
-  const header = renderEmailBrandHeader(branding);
-  let out = html;
-  if (out.includes(EMAIL_BRAND_HEADER_TOKEN)) {
-    out = out.split(EMAIL_BRAND_HEADER_TOKEN).join(header);
-  }
-  out = out.replace(LEGACY_LOGO_IMG_RE, header);
-  return out;
-}
-
-// The `variants` JSONB the upload pipeline writes for a media row (camelCase keys).
-interface MediaVariant {
-  objectKey?: string | null;
-  variantLabel?: string | null;
-  fileType?: string | null;
-}
-
-// The subset of a media row the email logo resolver needs.
-export interface LogoMediaLike {
-  object_key?: string | null;
-  file_path?: string | null;
-  variants?: unknown;
-}
-
-/** Label the upload pipeline gives the untouched original file among a media row's variants. */
-export const ORIGINAL_UPLOAD_VARIANT_LABEL = 'original_uploaded';
-
-/**
- * Pick the storage key to use for a logo IN EMAIL.
- *
- * The image pipeline stores the AVIF derivative as `object_key` — that's what the website
- * (navbar, blocks) renders for performance — and keeps the ORIGINAL uploaded file among
- * `variants` under the label `original_uploaded`. Email clients, Outlook especially, can't
- * render AVIF (or WebP), so for email we prefer that untouched original. Fall back to
- * `object_key`/`file_path` only when no original variant was kept (e.g. the seeded default
- * logo, which has no variants). This keeps the site on AVIF while email uses the original.
- */
-export function pickEmailLogoObjectKey(media: LogoMediaLike | null | undefined): string | null {
-  if (!media) return null;
-  const variants = Array.isArray(media.variants) ? (media.variants as MediaVariant[]) : [];
-  const original = variants.find(
-    (v) =>
-      v &&
-      typeof v === 'object' &&
-      v.variantLabel === ORIGINAL_UPLOAD_VARIANT_LABEL &&
-      typeof v.objectKey === 'string' &&
-      v.objectKey.length > 0,
-  );
-  if (original?.objectKey) return original.objectKey;
-  return media.object_key ?? media.file_path ?? null;
-}
+// Pure, dependency-free rendering of the transactional-email brand header. Kept separate
+// from branding.ts (which is `server-only` and hits the DB) so this string logic — the
+// part worth unit-testing — imports nothing server-side and runs anywhere.
+
+// Tenant branding used to white-label every transactional email.
+//   - logoUrl  — an ABSOLUTE, email-safe logo URL, or `null` when none is configured.
+//   - siteName — the site name, used as the logo `alt` text and the no-logo text banner.
+export interface EmailBranding {
+  logoUrl: string | null;
+  siteName: string;
+}
+
+/**
+ * Marker an app-rendered email template drops where the brand header belongs.
+ * `applyEmailBranding` swaps it for the resolved logo (or text banner). This is a plain
+ * literal — NOT a Supabase/GoTrue `{{ .Var }}` merge tag — because it is substituted by
+ * our own nodemailer pipeline, never by Supabase.
+ */
+export const EMAIL_BRAND_HEADER_TOKEN = '{{brand_header}}';
+
+/** Hard width cap so an oversized custom logo can't blow out Gmail/Outlook layouts. */
+export const EMAIL_LOGO_MAX_WIDTH = 150;
+
+// The pre-white-label hardcoded logo. The app templates no longer embed it, but any stray
+// occurrence in an outbound email is swapped for the tenant header defensively.
+const LEGACY_LOGO_IMG_RE =
+  /<img\b[^>]*\bsrc=["'][^"']*nextblock-logo-small\.webp["'][^>]*>/gi;
+
+function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+/**
+ * Render the branded header block: an email-safe logo `<img>` (hard-capped at 150px so a
+ * large custom logo can't break the layout) when a logo exists, otherwise a clean, styled
+ * text banner showing the site name.
+ */
+export function renderEmailBrandHeader(branding: EmailBranding): string {
+  const name = escapeHtml(branding.siteName);
+
+  if (branding.logoUrl) {
+    const src = escapeHtml(branding.logoUrl);
+    return (
+      '<div style="text-align:center;padding:0 0 24px;">' +
+      `<img src="${src}" alt="${name}" width="${EMAIL_LOGO_MAX_WIDTH}" ` +
+      `style="display:block;margin:0 auto;width:${EMAIL_LOGO_MAX_WIDTH}px;` +
+      'max-width:100%;height:auto;border:0;outline:none;text-decoration:none;" />' +
+      '</div>'
+    );
+  }
+
+  // No logo → strip the image entirely and fall back to a text banner with the site name.
+  return (
+    '<div style="text-align:center;padding:0 0 24px;">' +
+    '<span style="display:inline-block;font-family:-apple-system,BlinkMacSystemFont,' +
+    "'Segoe UI',Roboto,Helvetica,Arial,sans-serif;font-size:22px;line-height:1.2;" +
+    `font-weight:700;color:#0f172a;letter-spacing:-0.01em;">${name}</span>` +
+    '</div>'
+  );
+}
+
+/**
+ * Intercept a fully-rendered email body and apply tenant branding:
+ *   1. Replace the `{{brand_header}}` token (used by our app-rendered templates).
+ *   2. Defensively swap any stray hardcoded legacy NextBlock logo `<img>` for the header.
+ * Purely a string transform so it is trivially unit-testable and side-effect free.
+ */
+export function applyEmailBranding(html: string, branding: EmailBranding): string {
+  const header = renderEmailBrandHeader(branding);
+  let out = html;
+  if (out.includes(EMAIL_BRAND_HEADER_TOKEN)) {
+    out = out.split(EMAIL_BRAND_HEADER_TOKEN).join(header);
+  }
+  out = out.replace(LEGACY_LOGO_IMG_RE, header);
+  return out;
+}
+
+// The `variants` JSONB the upload pipeline writes for a media row (camelCase keys).
+interface MediaVariant {
+  objectKey?: string | null;
+  variantLabel?: string | null;
+  fileType?: string | null;
+}
+
+// The subset of a media row the email logo resolver needs.
+export interface LogoMediaLike {
+  object_key?: string | null;
+  file_path?: string | null;
+  variants?: unknown;
+}
+
+/** Label the upload pipeline gives the untouched original file among a media row's variants. */
+export const ORIGINAL_UPLOAD_VARIANT_LABEL = 'original_uploaded';
+
+/**
+ * Pick the storage key to use for a logo IN EMAIL.
+ *
+ * The image pipeline stores the AVIF derivative as `object_key` — that's what the website
+ * (navbar, blocks) renders for performance — and keeps the ORIGINAL uploaded file among
+ * `variants` under the label `original_uploaded`. Email clients, Outlook especially, can't
+ * render AVIF (or WebP), so for email we prefer that untouched original. Fall back to
+ * `object_key`/`file_path` only when no original variant was kept (e.g. the seeded default
+ * logo, which has no variants). This keeps the site on AVIF while email uses the original.
+ */
+export function pickEmailLogoObjectKey(media: LogoMediaLike | null | undefined): string | null {
+  if (!media) return null;
+  const variants = Array.isArray(media.variants) ? (media.variants as MediaVariant[]) : [];
+  const original = variants.find(
+    (v) =>
+      v &&
+      typeof v === 'object' &&
+      v.variantLabel === ORIGINAL_UPLOAD_VARIANT_LABEL &&
+      typeof v.objectKey === 'string' &&
+      v.objectKey.length > 0,
+  );
+  if (original?.objectKey) return original.objectKey;
+  return media.object_key ?? media.file_path ?? null;
+}

package/templates/nextblock-template/lib/email/branding.ts

@@ -1,76 +1,76 @@
-import 'server-only';
-
-import { getServiceRoleSupabaseClient } from '@nextblock-cms/db/server';
-
-import { getSiteSettings } from '../../app/lib/site-settings';
-import { DEFAULT_SITE_TITLE } from '../../app/lib/seo';
-import { resolveMediaUrl } from '../media/resolveMediaUrl';
-import { resolveMediaBaseUrl } from '../storage/provider';
-import { resolveSiteUrl } from '../site-url';
-import { resolveActiveLogo } from '../logos/active-logo';
-import { pickEmailLogoObjectKey } from './branding-format';
-import type { EmailBranding, LogoMediaLike } from './branding-format';
-
-// Server-side resolution of the tenant branding that white-labels every transactional
-// email. The mailer choke point (app/actions/email.ts) and the auth-email logo endpoint
-// (app/api/brand/email-logo) both read this, so every dispatched pipeline — 2FA codes,
-// form/interaction notifications, the SMTP test, feedback, and the Supabase auth emails —
-// shows the operator's own logo instead of a hardcoded NextBlock one.
-//
-// The pure header-rendering helpers live in ./branding-format (no server-only imports, so
-// they're unit-testable); re-export them here so callers have a single import surface.
-export {
-  EMAIL_BRAND_HEADER_TOKEN,
-  EMAIL_LOGO_MAX_WIDTH,
-  applyEmailBranding,
-  renderEmailBrandHeader,
-} from './branding-format';
-export type { EmailBranding } from './branding-format';
-
-/**
- * Resolve the tenant's active logo to an ABSOLUTE URL usable in an email `<img>`.
- * The newest `logos` row wins (the table has no is_active flag). Returns `null` when
- * there is no logo, no linked media, or the URL cannot be resolved — the caller then
- * renders a text banner instead.
- */
-async function resolveActiveLogoUrl(): Promise<string | null> {
-  try {
-    const supabase = getServiceRoleSupabaseClient();
-    // Honor the admin-pinned active logo (site_settings.active_logo_id), else newest.
-    const logo = await resolveActiveLogo(supabase);
-    const media = (logo as { media?: LogoMediaLike | null } | null)?.media ?? null;
-    // Prefer the original uploaded file over the AVIF `object_key` (email can't render AVIF).
-    const objectKey = pickEmailLogoObjectKey(media);
-    if (!objectKey) return null;
-
-    // Pass the resolved base explicitly so the native-Supabase storage URL is honored
-    // even when NEXT_PUBLIC_R2_BASE_URL isn't set.
-    const resolved = resolveMediaUrl(objectKey, resolveMediaBaseUrl());
-    if (!resolved) return null;
-    if (resolved.startsWith('http://') || resolved.startsWith('https://')) {
-      return resolved;
-    }
-    // Relative result (a bundled `/images/*` key, or the no-storage-base case): make it
-    // absolute against the public site origin so email clients can fetch it.
-    const origin = resolveSiteUrl();
-    return `${origin}${resolved.startsWith('/') ? '' : '/'}${resolved}`;
-  } catch {
-    // Service role unavailable or table missing (pre-setup) — treat as "no logo".
-    return null;
-  }
-}
-
-/**
- * Resolve tenant email branding. Read fresh on each call (no React `cache`, so it is safe
- * from fire-and-forget dispatch paths where the request scope may already be torn down);
- * the underlying site-settings read is already cross-request cached via `unstable_cache`,
- * and a fresh read each time is what keeps the logo "change at will".
- */
-export async function resolveEmailBranding(): Promise<EmailBranding> {
-  const [settings, logoUrl] = await Promise.all([
-    getSiteSettings().catch(() => null),
-    resolveActiveLogoUrl(),
-  ]);
-  const siteName = settings?.siteTitle?.trim() || DEFAULT_SITE_TITLE;
-  return { logoUrl, siteName };
-}
+import 'server-only';
+
+import { getServiceRoleSupabaseClient } from '@nextblock-cms/db/server';
+
+import { getSiteSettings } from '../../app/lib/site-settings';
+import { DEFAULT_SITE_TITLE } from '../../app/lib/seo';
+import { resolveMediaUrl } from '../media/resolveMediaUrl';
+import { resolveMediaBaseUrl } from '../storage/provider';
+import { resolveSiteUrl } from '../site-url';
+import { resolveActiveLogo } from '../logos/active-logo';
+import { pickEmailLogoObjectKey } from './branding-format';
+import type { EmailBranding, LogoMediaLike } from './branding-format';
+
+// Server-side resolution of the tenant branding that white-labels every transactional
+// email. The mailer choke point (app/actions/email.ts) and the auth-email logo endpoint
+// (app/api/brand/email-logo) both read this, so every dispatched pipeline — 2FA codes,
+// form/interaction notifications, the SMTP test, feedback, and the Supabase auth emails —
+// shows the operator's own logo instead of a hardcoded NextBlock one.
+//
+// The pure header-rendering helpers live in ./branding-format (no server-only imports, so
+// they're unit-testable); re-export them here so callers have a single import surface.
+export {
+  EMAIL_BRAND_HEADER_TOKEN,
+  EMAIL_LOGO_MAX_WIDTH,
+  applyEmailBranding,
+  renderEmailBrandHeader,
+} from './branding-format';
+export type { EmailBranding } from './branding-format';
+
+/**
+ * Resolve the tenant's active logo to an ABSOLUTE URL usable in an email `<img>`.
+ * The newest `logos` row wins (the table has no is_active flag). Returns `null` when
+ * there is no logo, no linked media, or the URL cannot be resolved — the caller then
+ * renders a text banner instead.
+ */
+async function resolveActiveLogoUrl(): Promise<string | null> {
+  try {
+    const supabase = getServiceRoleSupabaseClient();
+    // Honor the admin-pinned active logo (site_settings.active_logo_id), else newest.
+    const logo = await resolveActiveLogo(supabase);
+    const media = (logo as { media?: LogoMediaLike | null } | null)?.media ?? null;
+    // Prefer the original uploaded file over the AVIF `object_key` (email can't render AVIF).
+    const objectKey = pickEmailLogoObjectKey(media);
+    if (!objectKey) return null;
+
+    // Pass the resolved base explicitly so the native-Supabase storage URL is honored
+    // even when NEXT_PUBLIC_R2_BASE_URL isn't set.
+    const resolved = resolveMediaUrl(objectKey, resolveMediaBaseUrl());
+    if (!resolved) return null;
+    if (resolved.startsWith('http://') || resolved.startsWith('https://')) {
+      return resolved;
+    }
+    // Relative result (a bundled `/images/*` key, or the no-storage-base case): make it
+    // absolute against the public site origin so email clients can fetch it.
+    const origin = resolveSiteUrl();
+    return `${origin}${resolved.startsWith('/') ? '' : '/'}${resolved}`;
+  } catch {
+    // Service role unavailable or table missing (pre-setup) — treat as "no logo".
+    return null;
+  }
+}
+
+/**
+ * Resolve tenant email branding. Read fresh on each call (no React `cache`, so it is safe
+ * from fire-and-forget dispatch paths where the request scope may already be torn down);
+ * the underlying site-settings read is already cross-request cached via `unstable_cache`,
+ * and a fresh read each time is what keeps the logo "change at will".
+ */
+export async function resolveEmailBranding(): Promise<EmailBranding> {
+  const [settings, logoUrl] = await Promise.all([
+    getSiteSettings().catch(() => null),
+    resolveActiveLogoUrl(),
+  ]);
+  const siteName = settings?.siteTitle?.trim() || DEFAULT_SITE_TITLE;
+  return { logoUrl, siteName };
+}

package/templates/nextblock-template/lib/full-backup/manifest.test.ts

@@ -1,121 +1,121 @@
-import { describe, expect, it } from "vitest";
-
-import {
-  FULL_BACKUP_ARCHIVE_TYPE,
-  FULL_BACKUP_CONFIRMATION,
-  FULL_BACKUP_CONTENT_PATH,
-  FULL_BACKUP_DATABASE_PATH,
-  FULL_BACKUP_STORAGE_PREFIX,
-  archivePathForObjectKey,
-  isValidFullBackupConfirmation,
-  objectKeyFromArchivePath,
-  parseFullBackupManifest,
-  replaceMediaBaseUrlInJson,
-  replaceMediaBaseUrlInString,
-} from "./manifest";
-
-function buildManifest(overrides: Record<string, unknown> = {}) {
-  return JSON.stringify({
-    type: FULL_BACKUP_ARCHIVE_TYPE,
-    version: 1,
-    exported_at: "2026-05-27T00:00:00.000Z",
-    app: {
-      name: "nextblock",
-      version: "0.3.0",
-    },
-    database: {
-      path: FULL_BACKUP_DATABASE_PATH,
-      created_with: "pg_dump",
-    },
-    content: {
-      path: FULL_BACKUP_CONTENT_PATH,
-      type: "nextblock-content-backup-v1",
-    },
-    storage: {
-      bucket: "old-bucket",
-      source_base_url: "https://old-assets.example.com",
-      public_url: null,
-      objects: [
-        {
-          key: "uploads/products/shirt.webp",
-          archive_path: archivePathForObjectKey("uploads/products/shirt.webp"),
-          size: 123,
-          etag: "\"abc\"",
-          content_type: "image/webp",
-          last_modified: "2026-05-27T00:00:00.000Z",
-        },
-      ],
-    },
-    ...overrides,
-  });
-}
-
-describe("full backup manifest helpers", () => {
-  it("encodes and decodes R2 object keys without changing addresses", () => {
-    const objectKey = "uploads/products/shirt.webp";
-    const archivePath = archivePathForObjectKey(objectKey);
-
-    expect(archivePath.startsWith(FULL_BACKUP_STORAGE_PREFIX)).toBe(true);
-    expect(objectKeyFromArchivePath(archivePath)).toBe(objectKey);
-  });
-
-  it("rejects archive object paths that escape the storage prefix", () => {
-    expect(() => objectKeyFromArchivePath("../database/dump.sql")).toThrow(
-      "Archive object path must be inside storage/objects."
-    );
-  });
-
-  it("validates manifest object path and key pairs", () => {
-    const manifest = parseFullBackupManifest(buildManifest());
-
-    expect(manifest.storage.objects).toHaveLength(1);
-    expect(manifest.storage.objects[0].key).toBe("uploads/products/shirt.webp");
-  });
-
-  it("rejects mismatched manifest object paths", () => {
-    const manifest = JSON.parse(buildManifest());
-    manifest.storage.objects[0].archive_path = archivePathForObjectKey("uploads/other.webp");
-
-    expect(() => parseFullBackupManifest(JSON.stringify(manifest))).toThrow(
-      "has a mismatched archive path"
-    );
-  });
-
-  it("rewrites old media base URLs inside strings and JSON content", () => {
-    const html =
-      '<img src="https://old-assets.example.com/uploads/products/shirt.webp" alt="Shirt">';
-    expect(
-      replaceMediaBaseUrlInString(
-        html,
-        "https://old-assets.example.com/",
-        "https://new-assets.example.com/"
-      )
-    ).toContain("https://new-assets.example.com/uploads/products/shirt.webp");
-
-    expect(
-      replaceMediaBaseUrlInJson(
-        {
-          html_content: html,
-          nested: ["https://old-assets.example.com/uploads/hero.webp"],
-        },
-        "https://old-assets.example.com",
-        "https://new-assets.example.com"
-      )
-    ).toEqual({
-      html_content:
-        '<img src="https://new-assets.example.com/uploads/products/shirt.webp" alt="Shirt">',
-      nested: ["https://new-assets.example.com/uploads/hero.webp"],
-    });
-  });
-
-  it("keeps exact URLs when no destination rewrite is requested", () => {
-    const value = "https://old-assets.example.com/uploads/hero.webp";
-
-    expect(replaceMediaBaseUrlInString(value, "", "https://new-assets.example.com")).toBe(value);
-  });
-
-  it("requires the typed destructive restore confirmation", () => {
-    expect(isValidFullBackupConfirmation(FULL_BACKUP_CONFIRMATION)).toBe(true);
-    expect(isValidFullBackupConfirmation("restore full backup")).toBe(false);
-  });
-});
+import { describe, expect, it } from "vitest";
+
+import {
+  FULL_BACKUP_ARCHIVE_TYPE,
+  FULL_BACKUP_CONFIRMATION,
+  FULL_BACKUP_CONTENT_PATH,
+  FULL_BACKUP_DATABASE_PATH,
+  FULL_BACKUP_STORAGE_PREFIX,
+  archivePathForObjectKey,
+  isValidFullBackupConfirmation,
+  objectKeyFromArchivePath,
+  parseFullBackupManifest,
+  replaceMediaBaseUrlInJson,
+  replaceMediaBaseUrlInString,
+} from "./manifest";
+
+function buildManifest(overrides: Record<string, unknown> = {}) {
+  return JSON.stringify({
+    type: FULL_BACKUP_ARCHIVE_TYPE,
+    version: 1,
+    exported_at: "2026-05-27T00:00:00.000Z",
+    app: {
+      name: "nextblock",
+      version: "0.3.0",
+    },
+    database: {
+      path: FULL_BACKUP_DATABASE_PATH,
+      created_with: "pg_dump",
+    },
+    content: {
+      path: FULL_BACKUP_CONTENT_PATH,
+      type: "nextblock-content-backup-v1",
+    },
+    storage: {
+      bucket: "old-bucket",
+      source_base_url: "https://old-assets.example.com",
+      public_url: null,
+      objects: [
+        {
+          key: "uploads/products/shirt.webp",
+          archive_path: archivePathForObjectKey("uploads/products/shirt.webp"),
+          size: 123,
+          etag: "\"abc\"",
+          content_type: "image/webp",
+          last_modified: "2026-05-27T00:00:00.000Z",
+        },
+      ],
+    },
+    ...overrides,
+  });
+}
+
+describe("full backup manifest helpers", () => {
+  it("encodes and decodes R2 object keys without changing addresses", () => {
+    const objectKey = "uploads/products/shirt.webp";
+    const archivePath = archivePathForObjectKey(objectKey);
+
+    expect(archivePath.startsWith(FULL_BACKUP_STORAGE_PREFIX)).toBe(true);
+    expect(objectKeyFromArchivePath(archivePath)).toBe(objectKey);
+  });
+
+  it("rejects archive object paths that escape the storage prefix", () => {
+    expect(() => objectKeyFromArchivePath("../database/dump.sql")).toThrow(
+      "Archive object path must be inside storage/objects."
+    );
+  });
+
+  it("validates manifest object path and key pairs", () => {
+    const manifest = parseFullBackupManifest(buildManifest());
+
+    expect(manifest.storage.objects).toHaveLength(1);
+    expect(manifest.storage.objects[0].key).toBe("uploads/products/shirt.webp");
+  });
+
+  it("rejects mismatched manifest object paths", () => {
+    const manifest = JSON.parse(buildManifest());
+    manifest.storage.objects[0].archive_path = archivePathForObjectKey("uploads/other.webp");
+
+    expect(() => parseFullBackupManifest(JSON.stringify(manifest))).toThrow(
+      "has a mismatched archive path"
+    );
+  });
+
+  it("rewrites old media base URLs inside strings and JSON content", () => {
+    const html =
+      '<img src="https://old-assets.example.com/uploads/products/shirt.webp" alt="Shirt">';
+    expect(
+      replaceMediaBaseUrlInString(
+        html,
+        "https://old-assets.example.com/",
+        "https://new-assets.example.com/"
+      )
+    ).toContain("https://new-assets.example.com/uploads/products/shirt.webp");
+
+    expect(
+      replaceMediaBaseUrlInJson(
+        {
+          html_content: html,
+          nested: ["https://old-assets.example.com/uploads/hero.webp"],
+        },
+        "https://old-assets.example.com",
+        "https://new-assets.example.com"
+      )
+    ).toEqual({
+      html_content:
+        '<img src="https://new-assets.example.com/uploads/products/shirt.webp" alt="Shirt">',
+      nested: ["https://new-assets.example.com/uploads/hero.webp"],
+    });
+  });
+
+  it("keeps exact URLs when no destination rewrite is requested", () => {
+    const value = "https://old-assets.example.com/uploads/hero.webp";
+
+    expect(replaceMediaBaseUrlInString(value, "", "https://new-assets.example.com")).toBe(value);
+  });
+
+  it("requires the typed destructive restore confirmation", () => {
+    expect(isValidFullBackupConfirmation(FULL_BACKUP_CONFIRMATION)).toBe(true);
+    expect(isValidFullBackupConfirmation("restore full backup")).toBe(false);
+  });
+});