@bygghammar/cms-platform 0.3.1 → 0.4.0

package/package.json

@@ -1,13 +1,12 @@
 {
   "name": "@bygghammar/cms-platform",
-  "version": "0.3.1",
+  "version": "0.4.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,
   "license": "UNLICENSED",
   "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
+    "access": "public"
   },
   "files": [
     "src",
@@ -18,9 +17,6 @@
     "url": "git+https://github.com/byggis79/devsba.git",
     "directory": "packages/cms-platform"
   },
-  "publishConfig": {
-    "access": "public"
-  },
   "exports": {
     ".": "./src/index.ts",
     "./i18n": "./src/i18n/index.ts",
@@ -44,7 +40,34 @@
     "./blocks/registry": "./src/blocks/registry.tsx",
     "./trips": "./src/trips/index.ts",
     "./trips/TripSectionEditor": "./src/trips/TripSectionEditor.tsx",
-    "./navigation": "./src/navigation/index.ts"
+    "./navigation": "./src/navigation/index.ts",
+    "./forms/conditions": "./src/forms/conditions.ts",
+    "./forms/field-sets": "./src/forms/field-sets.ts",
+    "./forms/form-audit": "./src/forms/form-audit.ts",
+    "./forms/rich-text": "./src/forms/rich-text.tsx",
+    "./media/urls": "./src/media/urls.ts",
+    "./media/filename": "./src/media/filename.ts",
+    "./media/focus": "./src/media/focus.ts",
+    "./media/internal-paths": "./src/media/internal-paths.ts",
+    "./media/optimize": "./src/media/optimize.ts",
+    "./media/srcset": "./src/media/srcset.ts",
+    "./media/media-meta": "./src/media/media-meta.ts",
+    "./media/review-image": "./src/media/review-image.ts",
+    "./media/storage": "./src/media/storage.ts",
+    "./media/usage-types": "./src/media/usage-types.ts",
+    "./cms/version-diff": "./src/cms/version-diff.ts",
+    "./cms/shared-draft-store": "./src/cms/shared-draft-store.ts",
+    "./http/cache-policy": "./src/http/cache-policy.ts",
+    "./http/compression": "./src/http/compression.ts",
+    "./http/response-headers": "./src/http/response-headers.ts",
+    "./backup/datasets": "./src/backup/datasets.ts",
+    "./backup/export-core": "./src/backup/export-core.ts",
+    "./backup/restore-core": "./src/backup/restore-core.ts",
+    "./backup/media-export": "./src/backup/media-export.ts",
+    "./i18n/json": "./src/i18n/json.ts",
+    "./i18n/resolve-locale": "./src/i18n/resolve-locale.ts",
+    "./i18n/translation-meta": "./src/i18n/translation-meta.ts",
+    "./platform": "./src/platform/index.ts"
   },
   "dependencies": {
     "fflate": "^0.8.3"
@@ -54,6 +77,20 @@
     "lucide-react": ">=0.5.0",
     "react": ">=19",
     "react-dom": ">=19",
-    "sonner": ">=2"
+    "sonner": ">=2",
+    "@supabase/supabase-js": ">=2",
+    "@tanstack/react-start": ">=1",
+    "@tanstack/react-router": ">=1"
+  },
+  "peerDependenciesMeta": {
+    "@supabase/supabase-js": {
+      "optional": true
+    },
+    "@tanstack/react-start": {
+      "optional": true
+    },
+    "@tanstack/react-router": {
+      "optional": true
+    }
   }
-}
+}

package/src/backup/datasets.ts

@@ -0,0 +1,249 @@
+/**
+ * Client-safe description of what a backup archive can contain.
+ *
+ * Used by both the backoffice UI and the server-side export/import engine so
+ * the two can never drift apart.
+ */
+
+/**
+ * Archive layout version. Format 2 adds accounts, email configuration,
+ * verified media and secret sanitising. Format 1 archives are rejected.
+ */
+export const ARCHIVE_FORMAT_VERSION = 2;
+/** Bump when the database schema changes in a way that breaks old archives. */
+export const SCHEMA_VERSION = 2;
+
+export {
+  ALLOWED_MEDIA_EXTENSIONS,
+  isAllowedMediaFile,
+  hasAllowedMediaExtension,
+  verifyMediaFile,
+  isSafeArchivePath,
+  sanitizeSecrets,
+  rewriteMediaUrls,
+  neutralizeInjection,
+} from "./safety";
+
+export type TableSpec = {
+  table: string;
+  /** Primary key column(s) used for upserts. */
+  pk: string;
+  /**
+   * Conflict target for upserts. Defaults to `pk`, but tables that carry a
+   * business key (pages.key, forms.key, …) must conflict on that instead, or
+   * archives with different UUIDs collide on the unique index.
+   */
+  conflict?: string;
+  /**
+   * Columns that reference rows created later in the import order.
+   * They are stripped on the first pass and written in a second pass.
+   */
+  deferred?: string[];
+  /** Tables that must have imported cleanly before this one is attempted. */
+  requires?: string[];
+  /** Credential-like values in these JSON columns are stripped on export. */
+  sanitize?: string[];
+  /**
+   * Nullable foreign keys checked against the archive itself. A non-null value
+   * whose parent row is absent fails analysis before anything is restored.
+   */
+  references?: { column: string; table: string; pk?: string }[];
+};
+
+/** Business keys used to detect that an archive comes from another database. */
+export const LINEAGE_KEYS: Record<string, string> = {
+  pages: "key",
+  global_sections: "key",
+  forms: "key",
+  content_sections: "key",
+  page_seo: "page_key",
+  redirects: "from_path",
+  locale_domains: "locale",
+};
+
+export type DatasetGroup = {
+  id: string;
+  label: string;
+  description: string;
+  tables: TableSpec[];
+  /** Rows are only ever inserted — never updated or deleted. */
+  insertOnly?: boolean;
+  /** Special payloads that are not plain tables. */
+  special?: "mediaFiles" | "authUsers";
+  /** Not selected when the user picks "recommended". */
+  heavy?: boolean;
+};
+
+export const DATASET_GROUPS: DatasetGroup[] = [
+  {
+    id: "content",
+    label: "Content & pages",
+    description:
+      "Pages, page versions, publications, sections, global sections and block templates.",
+    tables: [
+      { table: "pages", pk: "id", conflict: "key", deferred: ["current_version_id"] },
+      { table: "page_versions", pk: "id", conflict: "page_id,version_no", requires: ["pages"] },
+      { table: "page_publications", pk: "id", requires: ["pages", "page_versions"] },
+      { table: "content_sections", pk: "key", conflict: "key" },
+      { table: "global_sections", pk: "id", conflict: "key", deferred: ["current_version_id"] },
+      {
+        table: "global_section_versions",
+        pk: "id",
+        conflict: "section_id,version_no",
+        requires: ["global_sections"],
+      },
+      { table: "block_templates", pk: "id" },
+    ],
+  },
+  {
+    id: "seo",
+    label: "SEO & routing",
+    description: "Page SEO, redirects, language domains and tracking/code injections.",
+    tables: [
+      { table: "page_seo", pk: "page_key", conflict: "page_key" },
+      { table: "redirects", pk: "id", conflict: "from_path" },
+      { table: "locale_domains", pk: "locale", conflict: "locale" },
+      { table: "site_injections", pk: "id" },
+    ],
+  },
+  {
+    id: "forms",
+    label: "Forms",
+    description: "Form definitions, their version history and global form settings.",
+    tables: [
+      { table: "forms", pk: "id", conflict: "key" },
+      { table: "form_versions", pk: "id", conflict: "form_key,version_no", requires: ["forms"] },
+      { table: "form_settings", pk: "id" },
+    ],
+  },
+
+  {
+    id: "customer",
+    label: "Customer data",
+    description:
+      "Form submissions, partial submissions and delivery attempts. Always insert-only — never overwritten or deleted.",
+    insertOnly: true,
+    tables: [
+      { table: "form_submissions", pk: "id", requires: ["forms"] },
+      { table: "form_partials", pk: "id", conflict: "form_key,client_token", requires: ["forms"] },
+      {
+        table: "form_delivery_attempts",
+        pk: "id",
+        requires: ["forms", "form_submissions"],
+      },
+    ],
+  },
+
+  {
+    id: "mediaMeta",
+    label: "Media metadata",
+    description: "Alt texts, titles, descriptions, focus points and the media bin index.",
+    tables: [
+      { table: "media_meta", pk: "path" },
+      { table: "media_focus", pk: "path" },
+      { table: "media_trash", pk: "id" },
+    ],
+  },
+  {
+    id: "mediaFiles",
+    label: "Media files",
+    description: "The actual images and videos. This is by far the largest part of an archive.",
+    special: "mediaFiles",
+    heavy: true,
+    tables: [],
+  },
+  {
+    id: "users",
+    label: "Users & roles",
+    description:
+      "Accounts and their role assignments. Passwords can never be exported — restored users must reset theirs.",
+    special: "authUsers",
+    tables: [
+      { table: "app_users", pk: "id" },
+      { table: "user_roles", pk: "id", conflict: "user_id,role", requires: ["app_users"] },
+    ],
+  },
+  {
+    id: "email",
+    label: "Email configuration",
+    description:
+      "Sending providers and global email settings. Only the names of secrets are stored — never their values.",
+    tables: [
+      { table: "email_providers", pk: "id", sanitize: ["config", "notes"] },
+      {
+        table: "email_settings",
+        pk: "id",
+        requires: ["email_providers"],
+        sanitize: ["*"],
+        references: [
+          { column: "default_provider_id", table: "email_providers" },
+          { column: "fallback_provider_id", table: "email_providers" },
+        ],
+      },
+    ],
+  },
+  {
+    id: "logs",
+    label: "Logs",
+    description: "Audit log and outgoing email history.",
+    insertOnly: true,
+    heavy: true,
+    tables: [
+      { table: "audit_logs", pk: "id" },
+      { table: "email_logs", pk: "id" },
+    ],
+  },
+];
+
+export const ALL_GROUP_IDS = DATASET_GROUPS.map((g) => g.id);
+export const DEFAULT_GROUP_IDS = DATASET_GROUPS.filter((g) => !g.heavy).map((g) => g.id);
+
+export function groupById(id: string): DatasetGroup | undefined {
+  return DATASET_GROUPS.find((g) => g.id === id);
+}
+
+/** Import order across all groups, respecting foreign keys. */
+export const IMPORT_ORDER: string[] = [
+  "app_users",
+  "user_roles",
+  "pages",
+  "page_versions",
+  "page_publications",
+  "global_sections",
+  "global_section_versions",
+  "content_sections",
+  "block_templates",
+  "page_seo",
+  "redirects",
+  "locale_domains",
+  "site_injections",
+  "email_providers",
+  "email_settings",
+  "forms",
+  "form_versions",
+  "form_settings",
+  "form_submissions",
+  "form_partials",
+  "form_delivery_attempts",
+  "media_meta",
+  "media_focus",
+  "media_trash",
+  "audit_logs",
+  "email_logs",
+];
+
+export type ArchiveManifest = {
+  format: number;
+  schemaVersion: number;
+  createdAt: string;
+  createdBy: string | null;
+  site: string | null;
+  groups: string[];
+  counts: Record<string, number>;
+  mediaFiles: number;
+  mediaBytes: number;
+  /** Files found in the library but excluded because they are not media. */
+  quarantinedMedia?: string[];
+};
+
+export type ImportMode = "merge" | "replace";

package/src/backup/export-core.ts

@@ -0,0 +1,350 @@
+/**
+ * Pure helpers for building a self-contained migration package.
+ *
+ * A migration package is a superset of a backup archive: same portable table
+ * data, plus a versioned manifest with per-file checksums, expected row counts
+ * and provenance. Secrets never enter it.
+ */
+import { createHash } from "node:crypto";
+
+import { ARCHIVE_FORMAT_VERSION, SCHEMA_VERSION, type ArchiveManifest } from "./datasets";
+import {
+  verifyMediaFile,
+  isSafeArchivePath,
+  sanitizeSecrets,
+  isPlainObject,
+  toJsonSafe,
+} from "./safety";
+
+/** Bump when the package layout changes in a way older tools cannot read. */
+export const MIGRATION_PACKAGE_VERSION = 2;
+
+export type MediaChecksum = { path: string; bytes: number; sha256: string };
+
+export type MigrationManifest = {
+  packageVersion: number;
+  archiveFormat: number;
+  sourceSchemaVersion: number;
+  exportedAt: string;
+  source: string | null;
+  groups: string[];
+  /** Expected row count per table, asserted by `verify`. */
+  counts: Record<string, number>;
+  users: number;
+  media: { files: number; bytes: number };
+  checksums: MediaChecksum[];
+  /** Names only — values are never exported. */
+  secretRefs: string[];
+  /** Fields whose credential identifiers were redacted and must be reconfigured. */
+  redacted?: string[];
+  rejected: string[];
+};
+
+export function sha256(bytes: Uint8Array): string {
+  return createHash("sha256").update(Buffer.from(bytes)).digest("hex");
+}
+
+/**
+ * Keys whose values must never leave the source system. Matching values are
+ * replaced by a `secret:NAME` reference so the target knows what to configure.
+ */
+export const SECRET_KEY_RE =
+  /(password|passwd|secret|token|api[_-]?key|apikey|private[_-]?key|credential|service[_-]?role|smtp_pass|authorization|bearer|cookie|hash)/i;
+
+/**
+ * Keys that hold only the *name* of a secret (an environment-variable name),
+ * never its value. These must survive the export unchanged, otherwise the
+ * self-hosted mail system cannot find its credentials.
+ */
+export const SECRET_NAME_KEY_RE =
+  /(secret_name|secret_ref_name|_secret_ref|ref_name|key_id|_name)$/i;
+
+/** Translation metadata (`svHash`, `enHash`, …) is content, not a credential. */
+export const TRANSLATION_HASH_KEY_RE = /^[a-z]{2}(-[A-Za-z]{2,4})?hash$/i;
+
+export function isSecretNameKey(key: string): boolean {
+  return SECRET_NAME_KEY_RE.test(key) || TRANSLATION_HASH_KEY_RE.test(key);
+}
+
+export type SecretScanResult<T> = { value: T; refs: string[] };
+
+/** Recursively replace secret-like values with reference names. */
+export function stripSecrets<T>(value: T, path: string[] = []): SecretScanResult<T> {
+  const refs: string[] = [];
+
+  const walk = (v: unknown, keys: string[]): unknown => {
+    if (v instanceof Date) return v.toISOString();
+    if (Array.isArray(v)) return v.map((item, i) => walk(item, [...keys, String(i)]));
+    if (v && typeof v === "object") {
+      if (!isPlainObject(v)) return toJsonSafe(v);
+      const out: Record<string, unknown> = {};
+      for (const [k, item] of Object.entries(v)) {
+        if (
+          SECRET_KEY_RE.test(k) &&
+          !isSecretNameKey(k) &&
+          item != null &&
+          !isPlainObject(item) &&
+          !Array.isArray(item)
+        ) {
+          const ref = [...keys, k].join(".");
+          refs.push(ref);
+          out[k] = `secret:${k.toUpperCase()}`;
+          continue;
+        }
+        out[k] = walk(item, [...keys, k]);
+      }
+      return out;
+    }
+    return toJsonSafe(v);
+  };
+
+  return { value: walk(sanitizeSecrets(value), path) as T, refs };
+}
+
+/* ------------------------------------------------- credential surrogates */
+
+/** Prefix of every non-live client-token surrogate written by the exporter. */
+export const CLIENT_TOKEN_SURROGATE_PREFIX = "migrated:";
+
+/** Deterministic, unique, non-live replacement for a live client token. */
+export function surrogateClientToken(rowId: unknown, fallback: number): string {
+  const id = typeof rowId === "string" && rowId.trim() ? rowId.trim() : `row-${fallback}`;
+  return `${CLIENT_TOKEN_SURROGATE_PREFIX}${id}`;
+}
+
+/**
+ * Replace live partial-submission client tokens with surrogates. Every row is
+ * preserved; the values stay NOT NULL and unique per (form_key, client_token).
+ */
+export function sanitizePartialTokens(rows: Record<string, unknown>[]): Record<string, unknown>[] {
+  return rows.map((row, i) => ({ ...row, client_token: surrogateClientToken(row["id"], i) }));
+}
+
+/** Placeholder written where a credential identifier used to be. */
+export const REDACTED = "redacted:configure-on-server";
+
+/** AWS access-key-ID shaped identifiers (SES SMTP usernames included). */
+export const ACCESS_KEY_ID_RE =
+  /^(?:AKIA|ASIA|AIDA|AROA|AGPA|AIPA|ANPA|ANVA|ABIA|ACCA)[A-Z0-9]{12,}$/;
+
+export function looksLikeCredentialIdentifier(value: unknown): boolean {
+  if (typeof value !== "string") return false;
+  const v = value.trim();
+  if (!v) return false;
+  if (ACCESS_KEY_ID_RE.test(v)) return true;
+  // Opaque machine credential: long, no spaces, no @ (so real usernames and
+  // e-mail addresses are kept).
+  return v.length >= 20 && !/[\s@]/.test(v) && /[A-Z0-9]/.test(v) && !/^[a-z._-]+$/.test(v);
+}
+
+/**
+ * Redact credential identifiers (e.g. SES SMTP usernames) from email provider
+ * configuration. Values are never logged — only the field path is reported.
+ */
+export function redactProviderCredentials(rows: Record<string, unknown>[]): {
+  rows: Record<string, unknown>[];
+  redacted: string[];
+} {
+  const redacted: string[] = [];
+  const out = rows.map((row) => {
+    const config = row["config"];
+    if (!isPlainObject(config)) return row;
+    const next: Record<string, unknown> = { ...config };
+    for (const key of ["username", "user", "smtp_username", "access_key_id", "accessKeyId"]) {
+      if (key in next && looksLikeCredentialIdentifier(next[key])) {
+        next[key] = REDACTED;
+        redacted.push(`email_providers.config.${key}`);
+      }
+    }
+    return { ...row, config: next };
+  });
+  return { rows: out, redacted: [...new Set(redacted)] };
+}
+
+/* ------------------------------------------------------ credential audit */
+
+const PRIVATE_KEY_RE = /-----BEGIN [A-Z ]*PRIVATE KEY-----/;
+const BCRYPT_RE = /^\$2[aby]?\$\d{2}\$[./A-Za-z0-9]{53}$/;
+const ARGON_RE = /^\$argon2[a-z]{0,2}\$/;
+const JWT_RE = /^ey[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}$/;
+const CREDENTIALED_URL_RE = /\b[a-z+]{2,12}:\/\/[^\s/:@]+:[^\s/@]+@/i;
+const API_KEY_RE =
+  /\b(sk_live_[A-Za-z0-9]{10,}|rk_live_[A-Za-z0-9]{10,}|gh[pousr]_[A-Za-z0-9]{20,}|sb_secret_[A-Za-z0-9_-]{10,}|xox[baprs]-[A-Za-z0-9-]{10,})\b/;
+
+/**
+ * Scan the data about to be written (or just read back) for values that must
+ * never appear in a migration package. Returns human-readable problems; the
+ * offending values themselves are never included.
+ */
+export function auditExportedData(data: Map<string, Record<string, unknown>[]>): string[] {
+  const problems: string[] = [];
+
+  const partials = data.get("form_partials") ?? [];
+  partials.forEach((row, i) => {
+    const token = row["client_token"];
+    if (typeof token !== "string" || !token.startsWith(CLIENT_TOKEN_SURROGATE_PREFIX)) {
+      problems.push(
+        `form_partials[${i}].client_token is a live token — it must be replaced by a surrogate.`,
+      );
+    }
+  });
+
+  for (const [table, rows] of data) {
+    rows.forEach((row, i) => {
+      const walk = (value: unknown, path: string): void => {
+        if (Array.isArray(value)) {
+          value.forEach((item, j) => walk(item, `${path}[${j}]`));
+          return;
+        }
+        if (value && typeof value === "object") {
+          if (!isPlainObject(value)) return;
+          for (const [k, item] of Object.entries(value)) {
+            const child = `${path}.${k}`;
+            if (isSecretNameKey(k)) continue;
+            if (
+              typeof item === "string" &&
+              item &&
+              !item.startsWith("secret:") &&
+              !item.startsWith(REDACTED) &&
+              !item.startsWith(CLIENT_TOKEN_SURROGATE_PREFIX) &&
+              SECRET_KEY_RE.test(k)
+            ) {
+              problems.push(`${child} contains a credential value.`);
+              continue;
+            }
+            if (
+              table === "email_providers" &&
+              /(^|\.)config\./.test(child) &&
+              /^(username|user|smtp_username|access_key_id|accessKeyId)$/.test(k) &&
+              looksLikeCredentialIdentifier(item)
+            ) {
+              problems.push(`${child} looks like a credential identifier.`);
+              continue;
+            }
+            walk(item, child);
+          }
+          return;
+        }
+        if (typeof value !== "string" || !value) return;
+        if (PRIVATE_KEY_RE.test(value)) problems.push(`${path} contains a private key.`);
+        else if (BCRYPT_RE.test(value) || ARGON_RE.test(value))
+          problems.push(`${path} contains a password hash.`);
+        else if (JWT_RE.test(value)) problems.push(`${path} contains a JSON Web Token.`);
+        else if (API_KEY_RE.test(value)) problems.push(`${path} contains an API key.`);
+        else if (CREDENTIALED_URL_RE.test(value))
+          problems.push(`${path} contains a credentialed URL.`);
+      };
+      walk(row, `${table}[${i}]`);
+    });
+  }
+
+  return [...new Set(problems)];
+}
+
+/** Tables that must never be exported, whatever a caller asks for. */
+export const EXCLUDED_TABLE_RE =
+  /^(auth|storage|realtime|vault|supabase_functions|pgsodium|net)[._]/i;
+
+export function isExportableTable(table: string): boolean {
+  return !EXCLUDED_TABLE_RE.test(table);
+}
+
+export type MediaCandidate = { path: string; bytes: Uint8Array };
+
+export type MediaScan = {
+  accepted: { path: string; bytes: Uint8Array; sha256: string }[];
+  rejected: string[];
+  totalBytes: number;
+};
+
+/**
+ * Validate media before it enters the package: safe path, allowed extension,
+ * real file signature (no HTML disguised as an image), no duplicate paths.
+ */
+export function scanMedia(files: MediaCandidate[]): MediaScan {
+  const accepted: MediaScan["accepted"] = [];
+  const rejected: string[] = [];
+  const seen = new Set<string>();
+  let totalBytes = 0;
+
+  for (const file of files) {
+    if (!isSafeArchivePath(file.path)) {
+      rejected.push(`${file.path} (unsafe path)`);
+      continue;
+    }
+    if (seen.has(file.path)) {
+      rejected.push(`${file.path} (duplicate path)`);
+      continue;
+    }
+    const verdict = verifyMediaFile(file.path, file.bytes);
+    if (!verdict.ok) {
+      rejected.push(`${file.path} (${verdict.reason})`);
+      continue;
+    }
+    seen.add(file.path);
+    accepted.push({ path: file.path, bytes: file.bytes, sha256: sha256(file.bytes) });
+    totalBytes += file.bytes.byteLength;
+  }
+
+  return { accepted, rejected, totalBytes };
+}
+
+export type BuildManifestInput = {
+  source: string | null;
+  groups: string[];
+  counts: Record<string, number>;
+  users: number;
+  media: MediaScan;
+  secretRefs: string[];
+  redacted?: string[];
+  archiveManifest?: Pick<ArchiveManifest, "schemaVersion"> | null;
+  now?: () => Date;
+};
+
+export function buildMigrationManifest(input: BuildManifestInput): MigrationManifest {
+  const now = (input.now ?? (() => new Date()))().toISOString();
+  return {
+    packageVersion: MIGRATION_PACKAGE_VERSION,
+    archiveFormat: ARCHIVE_FORMAT_VERSION,
+    sourceSchemaVersion: input.archiveManifest?.schemaVersion ?? SCHEMA_VERSION,
+    exportedAt: now,
+    source: input.source,
+    groups: [...input.groups],
+    counts: { ...input.counts },
+    users: input.users,
+    media: { files: input.media.accepted.length, bytes: input.media.totalBytes },
+    checksums: input.media.accepted.map((f) => ({
+      path: f.path,
+      bytes: f.bytes.byteLength,
+      sha256: f.sha256,
+    })),
+    secretRefs: [...new Set(input.secretRefs)].sort(),
+    redacted: [...new Set(input.redacted ?? [])].sort(),
+    rejected: [...input.media.rejected],
+  };
+}
+
+/** Verify the checksums in a manifest against the files actually present. */
+export function checkChecksums(
+  manifest: MigrationManifest,
+  files: Map<string, Uint8Array>,
+): string[] {
+  const problems: string[] = [];
+  for (const entry of manifest.checksums) {
+    const bytes = files.get(entry.path);
+    if (!bytes) {
+      problems.push(`missing media file: ${entry.path}`);
+      continue;
+    }
+    if (bytes.byteLength !== entry.bytes) {
+      problems.push(`size mismatch: ${entry.path}`);
+      continue;
+    }
+    if (sha256(bytes) !== entry.sha256) problems.push(`checksum mismatch: ${entry.path}`);
+  }
+  for (const path of files.keys()) {
+    if (!manifest.checksums.some((c) => c.path === path))
+      problems.push(`unlisted media file: ${path}`);
+  }
+  return problems;
+}