emdash 0.39.0 → 0.40.0

package/src/transfer/container/tar.ts

@@ -0,0 +1,242 @@
+/**
+ * The `.emdash` single-file container: an uncompressed tar of the package
+ * files, `manifest.json` first. The container is transport only — the package
+ * digest covers the manifest, which pins every file — so these helpers never
+ * need to trust the archive: every entry must be a regular file at a valid
+ * package path, appear once, and carry exactly its declared size.
+ *
+ * Runs in browsers, Node, and Workers (web streams only).
+ */
+
+import { createTarDecoder, createTarPacker } from "modern-tar";
+
+import { TransferError } from "../errors.js";
+import { TRANSFER_LIMITS } from "../format/limits.js";
+import { MANIFEST_PATH, parsePackagePath, type PackagePath } from "../format/paths.js";
+
+export const SITE_PACKAGE_FILE_EXTENSION = ".emdash";
+export const SITE_PACKAGE_MEDIA_TYPE = "application/x-tar";
+
+/** Upper bound on archive entries: every indexed file, the index chunks, and the manifest. */
+const MAX_ENTRIES = TRANSFER_LIMITS.totalFiles + TRANSFER_LIMITS.indexChunks + 1;
+
+const DIRECTORY_ENTRY_PATTERN = /^(?:index|media|records(?:\/[a-z_]+)?)\/?$/;
+const FIXED_MTIME = new Date(0);
+
+function containerError(message: string, detail?: Record<string, string | number>): TransferError {
+	return new TransferError("TRANSFER_CONTAINER_INVALID", message, detail ? { detail } : {});
+}
+
+export interface PackageFileSource {
+	path: string;
+	bytes: number;
+	body: () =>
+		| Promise<ReadableStream<Uint8Array> | Uint8Array>
+		| ReadableStream<Uint8Array>
+		| Uint8Array;
+}
+
+function toStream(body: ReadableStream<Uint8Array> | Uint8Array): ReadableStream<Uint8Array> {
+	if (!(body instanceof Uint8Array)) return body;
+	return new ReadableStream<Uint8Array>({
+		start(controller) {
+			if (body.byteLength > 0) controller.enqueue(body);
+			controller.close();
+		},
+	});
+}
+
+function sizeGuard(path: string, expected: number): TransformStream<Uint8Array, Uint8Array> {
+	let seen = 0;
+	return new TransformStream<Uint8Array, Uint8Array>({
+		transform(chunk, controller) {
+			seen += chunk.byteLength;
+			if (seen > expected) throw containerError("Entry is larger than declared", { path });
+			controller.enqueue(chunk);
+		},
+		flush() {
+			if (seen !== expected) throw containerError("Entry is smaller than declared", { path });
+		},
+	});
+}
+
+/**
+ * Stream a container from package files. `manifest.json` must come first;
+ * every path must be a valid package path and appear once, and each body must
+ * produce exactly `bytes` bytes. Entries get a fixed mtime and mode so the
+ * same files always produce the same archive bytes.
+ */
+export function packSitePackage(
+	files: AsyncIterable<PackageFileSource> | Iterable<PackageFileSource>,
+): ReadableStream<Uint8Array> {
+	const { readable, controller } = createTarPacker();
+	void (async () => {
+		const seen = new Set<string>();
+		try {
+			for await (const file of files) {
+				if (seen.size === 0 && file.path !== MANIFEST_PATH) {
+					throw containerError("The manifest must be the first entry");
+				}
+				if (!parsePackagePath(file.path)) {
+					throw containerError("Invalid package path", { path: file.path });
+				}
+				if (seen.has(file.path))
+					throw containerError("Duplicate package path", { path: file.path });
+				if (seen.size >= MAX_ENTRIES) throw containerError("Too many entries");
+				if (!Number.isSafeInteger(file.bytes) || file.bytes < 0) {
+					throw containerError("Invalid entry size", { path: file.path });
+				}
+				seen.add(file.path);
+				const entry = controller.add({
+					name: file.path,
+					size: file.bytes,
+					type: "file",
+					mode: 0o644,
+					mtime: FIXED_MTIME,
+				});
+				await toStream(await file.body())
+					.pipeThrough(sizeGuard(file.path, file.bytes))
+					.pipeTo(entry);
+			}
+			if (seen.size === 0) throw containerError("The manifest must be the first entry");
+			controller.finalize();
+		} catch (error) {
+			controller.error(error);
+		}
+	})();
+	return readable;
+}
+
+export interface UnpackedPackageFile {
+	path: string;
+	parsed: PackagePath;
+	bytes: number;
+	body: ReadableStream<Uint8Array>;
+}
+
+export interface UnpackOptions {
+	/** Declared size for a path (from the manifest/index), checked against the entry header. */
+	expectedBytes?: (path: string) => number | undefined;
+}
+
+/**
+ * Read a container entry by entry. `onFile` receives each file in archive
+ * order and may read its body; an unread body is skipped. If `onFile` takes a
+ * reader it must read the body to the end or release the lock.
+ * Rejects symlinks, hard links, and other non-file entries; paths that are
+ * not package paths (absolute, `..`, anything undeclared by the format);
+ * duplicates; a first entry other than `manifest.json`; and size mismatches.
+ * Directory entries for the package's own directories are skipped.
+ */
+export async function unpackSitePackage(
+	archive: ReadableStream<Uint8Array>,
+	onFile: (file: UnpackedPackageFile) => Promise<void>,
+	options: UnpackOptions = {},
+): Promise<{ files: number }> {
+	const seen = new Set<string>();
+	let callbackError: unknown;
+	const entries = archive.pipeThrough(createTarDecoder({ strict: true }));
+	const reader = entries.getReader();
+	try {
+		for (;;) {
+			const { done, value: entry } = await reader.read();
+			if (done) break;
+			const { header } = entry;
+			const type = header.type ?? "file";
+			const name = header.name.startsWith("./") ? header.name.slice(2) : header.name;
+
+			if (type === "directory" && DIRECTORY_ENTRY_PATTERN.test(name)) {
+				await entry.body.cancel();
+				continue;
+			}
+			if (type !== "file") {
+				await entry.body.cancel();
+				throw containerError("Container entries must be regular files", { path: name });
+			}
+			const parsed = parsePackagePath(name);
+			if (!parsed) {
+				await entry.body.cancel();
+				throw containerError("Invalid package path", { path: name.slice(0, 256) });
+			}
+			if (seen.size === 0 && parsed.type !== "manifest") {
+				await entry.body.cancel();
+				throw containerError("The manifest must be the first entry");
+			}
+			if (seen.has(name)) {
+				await entry.body.cancel();
+				throw containerError("Duplicate package path", { path: name });
+			}
+			if (seen.size >= MAX_ENTRIES) {
+				await entry.body.cancel();
+				throw containerError("Too many entries");
+			}
+			const expected = options.expectedBytes?.(name);
+			if (expected !== undefined && expected !== header.size) {
+				await entry.body.cancel();
+				throw containerError("Entry size does not match the declared size", { path: name });
+			}
+			if (parsed.type === "manifest" && header.size > TRANSFER_LIMITS.manifestBytes) {
+				await entry.body.cancel();
+				throw new TransferError("TRANSFER_LIMIT_EXCEEDED", "Manifest is too large");
+			}
+			seen.add(name);
+
+			const body = entry.body.pipeThrough(sizeGuard(name, header.size));
+			let consumed = false;
+			const tracked = body.pipeThrough(
+				new TransformStream<Uint8Array, Uint8Array>({
+					flush() {
+						consumed = true;
+					},
+				}),
+			);
+			try {
+				await onFile({ path: name, parsed, bytes: header.size, body: tracked });
+			} catch (error) {
+				callbackError = error;
+				await tracked.cancel().catch(() => undefined);
+				throw error;
+			}
+			if (!consumed) {
+				if (tracked.locked) {
+					throw containerError("An entry body was left locked without being read", {
+						path: name,
+					});
+				}
+				await tracked.cancel();
+			}
+		}
+	} catch (error) {
+		await reader.cancel().catch(() => undefined);
+		if (error === callbackError || error instanceof TransferError) throw error;
+		throw new TransferError("TRANSFER_CONTAINER_INVALID", "Container could not be read", {
+			cause: error,
+		});
+	} finally {
+		reader.releaseLock();
+	}
+	if (seen.size === 0) throw containerError("The manifest must be the first entry");
+	return { files: seen.size };
+}
+
+/** Buffer every file of a small container into memory (tests, small tools). */
+export async function readSitePackageArchive(
+	archive: ReadableStream<Uint8Array> | Uint8Array,
+	options: UnpackOptions & { maxTotalBytes?: number } = {},
+): Promise<Map<string, Uint8Array>> {
+	const files = new Map<string, Uint8Array>();
+	const maxTotal = options.maxTotalBytes ?? 256 * 1024 * 1024;
+	let total = 0;
+	await unpackSitePackage(
+		toStream(archive),
+		async (file) => {
+			total += file.bytes;
+			if (total > maxTotal) {
+				throw new TransferError("TRANSFER_LIMIT_EXCEEDED", "Container is too large to buffer");
+			}
+			files.set(file.path, new Uint8Array(await new Response(file.body).arrayBuffer()));
+		},
+		options,
+	);
+	return files;
+}

package/src/transfer/domain.ts

@@ -0,0 +1,248 @@
+/**
+ * Is the target's portable domain empty enough to import into?
+ *
+ * Setup always applies a seed (the project's seed file or the built-in
+ * default), so a brand-new site is never row-empty. The domain counts as
+ * empty when it holds no content and no user-made schema: no term
+ * assignments, relations, content references, bylines or byline fields,
+ * media or media folders, revisions, SEO rows, comments or reactions,
+ * redirects, or user sections, and only seeded collections and block types,
+ * no collection with a row in its content table (trash included). Everything
+ * else a seed leaves is scaffold:
+ * - the seeded collections;
+ * - the seeded block types (`source = 'seed'`) and their versions;
+ * - taxonomy definitions attached only to those collections or to
+ *   collections that do not exist, and their unassigned terms;
+ * - menus and their items, widget areas and their widgets;
+ * - sections with `source = 'theme'` (seeded theme sections).
+ *
+ * The importer's `clear_scaffold` stage deletes exactly the reported
+ * `seededScaffold` items, in order: terms before their definitions, menu
+ * items before menus, widgets before widget areas, and block types after the
+ * collections whose fields name them.
+ */
+
+import { sql, type Kysely } from "kysely";
+
+import type { Database } from "../database/types.js";
+import { validateIdentifier } from "../database/validate.js";
+
+export type ScaffoldItem =
+	| { type: "collection"; id: string; slug: string }
+	| { type: "term"; id: string; name: string; slug: string; locale: string }
+	| { type: "taxonomy_def"; id: string; name: string; locale: string }
+	| { type: "menu_item"; id: string; menuId: string; label: string }
+	| { type: "menu"; id: string; name: string; locale: string }
+	| { type: "widget"; id: string; areaId: string; widgetType: string }
+	| { type: "widget_area"; id: string; name: string }
+	| { type: "section"; id: string; slug: string }
+	| { type: "block_type"; id: string; slug: string };
+
+export type DomainBlocker =
+	| { code: "table_not_empty"; table: string }
+	| { code: "collection_not_seeded"; id: string; slug: string }
+	| { code: "block_type_not_seeded"; id: string; slug: string }
+	| { code: "collection_has_entries"; id: string; slug: string }
+	| { code: "taxonomy_def_not_scaffold"; id: string; name: string };
+
+export interface PortableDomainInspection {
+	empty: boolean;
+	seededScaffold: ScaffoldItem[];
+	blockers: DomainBlocker[];
+}
+
+/** Tables that must hold no rows at all (sections are checked separately). */
+const MUST_BE_EMPTY = [
+	"content_taxonomies",
+	"_emdash_relations",
+	"_emdash_content_references",
+	"_emdash_bylines",
+	"_emdash_byline_fields",
+	"_emdash_byline_field_values",
+	"_emdash_byline_field_group_values",
+	"_emdash_content_bylines",
+	"media",
+	"media_folders",
+	"revisions",
+	"_emdash_seo",
+	"_emdash_comments",
+	"_emdash_comment_reactions",
+	"_emdash_redirects",
+] as const;
+
+function isSeededSource(source: string | null): boolean {
+	return source === "seed" || (source?.startsWith("template:") ?? false);
+}
+
+function parseCollections(value: string | null): string[] | null {
+	if (value === null) return [];
+	try {
+		const parsed: unknown = JSON.parse(value);
+		if (!Array.isArray(parsed)) return null;
+		return parsed.every((item): item is string => typeof item === "string") ? parsed : null;
+	} catch {
+		return null;
+	}
+}
+
+export async function inspectPortableDomain(
+	db: Kysely<Database>,
+): Promise<PortableDomainInspection> {
+	const blockers: DomainBlocker[] = [];
+	const seededScaffold: ScaffoldItem[] = [];
+
+	const probes = MUST_BE_EMPTY.map(
+		(table, index) => sql`(SELECT 1 FROM ${sql.ref(table)} LIMIT 1) AS ${sql.ref(`t${index}`)}`,
+	);
+	probes.push(
+		sql`(SELECT 1 FROM _emdash_sections WHERE source <> 'theme' LIMIT 1) AS ${sql.ref("user_sections")}`,
+	);
+	const occupied = await sql<Record<string, unknown>>`SELECT ${sql.join(probes)}`.execute(db);
+	const flags = occupied.rows[0] ?? {};
+	MUST_BE_EMPTY.forEach((table, index) => {
+		if (flags[`t${index}`] != null) blockers.push({ code: "table_not_empty", table });
+	});
+	if (flags.user_sections != null)
+		blockers.push({ code: "table_not_empty", table: "_emdash_sections" });
+
+	const collections = await db
+		.selectFrom("_emdash_collections")
+		.select(["id", "slug", "source"])
+		.orderBy("slug")
+		.execute();
+	const seeded = collections.filter((collection) => isSeededSource(collection.source));
+	for (const collection of collections) {
+		if (!isSeededSource(collection.source)) {
+			blockers.push({ code: "collection_not_seeded", id: collection.id, slug: collection.slug });
+		}
+	}
+
+	if (seeded.length > 0) {
+		const contentProbes = seeded.map((collection, index) => {
+			validateIdentifier(collection.slug, "collection slug");
+			return sql`(SELECT 1 FROM ${sql.ref(`ec_${collection.slug}`)} LIMIT 1) AS ${sql.ref(`c${index}`)}`;
+		});
+		const content = await sql<Record<string, unknown>>`SELECT ${sql.join(contentProbes)}`.execute(
+			db,
+		);
+		const contentFlags = content.rows[0] ?? {};
+		seeded.forEach((collection, index) => {
+			if (contentFlags[`c${index}`] != null) {
+				blockers.push({ code: "collection_has_entries", id: collection.id, slug: collection.slug });
+			} else {
+				seededScaffold.push({ type: "collection", id: collection.id, slug: collection.slug });
+			}
+		});
+	}
+
+	const scaffoldSlugs = new Set(
+		seededScaffold.flatMap((item) => (item.type === "collection" ? [item.slug] : [])),
+	);
+	const existingSlugs = new Set(collections.map((collection) => collection.slug));
+	const taxonomyDefs = await db
+		.selectFrom("_emdash_taxonomy_defs")
+		.select(["id", "name", "locale", "collections"])
+		.orderBy("id")
+		.execute();
+	const scaffoldDefs: ScaffoldItem[] = [];
+	for (const def of taxonomyDefs) {
+		const attached = parseCollections(def.collections);
+		if (attached?.every((slug) => scaffoldSlugs.has(slug) || !existingSlugs.has(slug))) {
+			scaffoldDefs.push({ type: "taxonomy_def", id: def.id, name: def.name, locale: def.locale });
+		} else {
+			blockers.push({ code: "taxonomy_def_not_scaffold", id: def.id, name: def.name });
+		}
+	}
+
+	const blockTypes = await db
+		.selectFrom("_emdash_block_types")
+		.select(["id", "slug", "source"])
+		.orderBy("slug")
+		.execute();
+	for (const blockType of blockTypes) {
+		if (blockType.source !== "seed") {
+			blockers.push({ code: "block_type_not_seeded", id: blockType.id, slug: blockType.slug });
+		}
+	}
+
+	// Terms, menu items, and widgets are only scaffold on a site without content;
+	// on any other site the blockers already say it is not empty.
+	if (blockers.length > 0) return { empty: false, seededScaffold, blockers };
+
+	const terms = await db
+		.selectFrom("taxonomies")
+		.select(["id", "name", "slug", "locale"])
+		.orderBy("id")
+		.execute();
+	for (const term of terms) {
+		seededScaffold.push({
+			type: "term",
+			id: term.id,
+			name: term.name,
+			slug: term.slug,
+			locale: term.locale,
+		});
+	}
+	seededScaffold.push(...scaffoldDefs);
+
+	const menuItems = await db
+		.selectFrom("_emdash_menu_items")
+		.select(["id", "menu_id", "label"])
+		.orderBy("id")
+		.execute();
+	for (const item of menuItems) {
+		seededScaffold.push({
+			type: "menu_item",
+			id: item.id,
+			menuId: item.menu_id,
+			label: item.label,
+		});
+	}
+
+	const menus = await db
+		.selectFrom("_emdash_menus")
+		.select(["id", "name", "locale"])
+		.orderBy("id")
+		.execute();
+	for (const menu of menus) {
+		seededScaffold.push({ type: "menu", id: menu.id, name: menu.name, locale: menu.locale });
+	}
+
+	const widgets = await db
+		.selectFrom("_emdash_widgets")
+		.select(["id", "area_id", "type"])
+		.orderBy("id")
+		.execute();
+	for (const widget of widgets) {
+		seededScaffold.push({
+			type: "widget",
+			id: widget.id,
+			areaId: widget.area_id,
+			widgetType: widget.type,
+		});
+	}
+
+	const areas = await db
+		.selectFrom("_emdash_widget_areas")
+		.select(["id", "name"])
+		.orderBy("id")
+		.execute();
+	for (const area of areas)
+		seededScaffold.push({ type: "widget_area", id: area.id, name: area.name });
+
+	const sections = await db
+		.selectFrom("_emdash_sections")
+		.select(["id", "slug"])
+		.where("source", "=", "theme")
+		.orderBy("id")
+		.execute();
+	for (const section of sections) {
+		seededScaffold.push({ type: "section", id: section.id, slug: section.slug });
+	}
+
+	for (const blockType of blockTypes) {
+		seededScaffold.push({ type: "block_type", id: blockType.id, slug: blockType.slug });
+	}
+
+	return { empty: true, seededScaffold, blockers };
+}

package/src/transfer/errors.ts

@@ -0,0 +1,134 @@
+/**
+ * Stable error codes for site transfer (export, analysis, import).
+ *
+ * Every code is `SCREAMING_SNAKE_CASE` with the `TRANSFER_` prefix and has a
+ * fixed HTTP status. `mapErrorStatus` in `api/errors.ts` consults
+ * {@link transferErrorStatus} first, so handlers can return these codes in an
+ * `ApiResult` and `unwrapResult` picks the right status.
+ */
+
+import { z } from "zod";
+
+export const TransferErrorCode = {
+	TRANSFER_IMPORT_IN_PROGRESS: "TRANSFER_IMPORT_IN_PROGRESS",
+	TRANSFER_FENCE_CHECK_FAILED: "TRANSFER_FENCE_CHECK_FAILED",
+	TRANSFER_EXPORT_CONCURRENT_WRITES: "TRANSFER_EXPORT_CONCURRENT_WRITES",
+	TRANSFER_OPERATION_NOT_FOUND: "TRANSFER_OPERATION_NOT_FOUND",
+	TRANSFER_INVALID_STATE: "TRANSFER_INVALID_STATE",
+	TRANSFER_LEASE_ACTIVE: "TRANSFER_LEASE_ACTIVE",
+	TRANSFER_LEASE_LOST: "TRANSFER_LEASE_LOST",
+	TRANSFER_RUNTIME_MISMATCH: "TRANSFER_RUNTIME_MISMATCH",
+	TRANSFER_IDEMPOTENCY_CONFLICT: "TRANSFER_IDEMPOTENCY_CONFLICT",
+	TRANSFER_TARGET_NOT_EMPTY: "TRANSFER_TARGET_NOT_EMPTY",
+	TRANSFER_EXPIRED: "TRANSFER_EXPIRED",
+	TRANSFER_MANIFEST_INVALID: "TRANSFER_MANIFEST_INVALID",
+	TRANSFER_UNSUPPORTED_FORMAT: "TRANSFER_UNSUPPORTED_FORMAT",
+	TRANSFER_UNSUPPORTED_FEATURE: "TRANSFER_UNSUPPORTED_FEATURE",
+	TRANSFER_PATH_INVALID: "TRANSFER_PATH_INVALID",
+	TRANSFER_FILE_NOT_DECLARED: "TRANSFER_FILE_NOT_DECLARED",
+	TRANSFER_FILE_MISSING: "TRANSFER_FILE_MISSING",
+	TRANSFER_FILE_SIZE_MISMATCH: "TRANSFER_FILE_SIZE_MISMATCH",
+	TRANSFER_FILE_DIGEST_MISMATCH: "TRANSFER_FILE_DIGEST_MISMATCH",
+	TRANSFER_CONTAINER_INVALID: "TRANSFER_CONTAINER_INVALID",
+	TRANSFER_LIMIT_EXCEEDED: "TRANSFER_LIMIT_EXCEEDED",
+	TRANSFER_RECORD_INVALID: "TRANSFER_RECORD_INVALID",
+	TRANSFER_REFERENCE_INVALID: "TRANSFER_REFERENCE_INVALID",
+	TRANSFER_MEDIA_REF_INVALID: "TRANSFER_MEDIA_REF_INVALID",
+	TRANSFER_MEDIA_BLOB_MISSING: "TRANSFER_MEDIA_BLOB_MISSING",
+	TRANSFER_SCHEMA_UNCLASSIFIED: "TRANSFER_SCHEMA_UNCLASSIFIED",
+	TRANSFER_PACKAGE_DIGEST_MISMATCH: "TRANSFER_PACKAGE_DIGEST_MISMATCH",
+	TRANSFER_PLAN_DIGEST_MISMATCH: "TRANSFER_PLAN_DIGEST_MISMATCH",
+	TRANSFER_PLAN_BLOCKED: "TRANSFER_PLAN_BLOCKED",
+	TRANSFER_DECISIONS_INVALID: "TRANSFER_DECISIONS_INVALID",
+	TRANSFER_VERIFICATION_FAILED: "TRANSFER_VERIFICATION_FAILED",
+	TRANSFER_APPROVAL_REQUIRED: "TRANSFER_APPROVAL_REQUIRED",
+	TRANSFER_APPROVAL_INVALID: "TRANSFER_APPROVAL_INVALID",
+	TRANSFER_STORAGE_ERROR: "TRANSFER_STORAGE_ERROR",
+	TRANSFER_EXPORT_ERROR: "TRANSFER_EXPORT_ERROR",
+	TRANSFER_ANALYZE_ERROR: "TRANSFER_ANALYZE_ERROR",
+	TRANSFER_IMPORT_ERROR: "TRANSFER_IMPORT_ERROR",
+} as const;
+
+export type TransferErrorCode = (typeof TransferErrorCode)[keyof typeof TransferErrorCode];
+
+export const TRANSFER_ERROR_STATUS: Readonly<Record<TransferErrorCode, number>> = Object.freeze({
+	TRANSFER_IMPORT_IN_PROGRESS: 503,
+	TRANSFER_FENCE_CHECK_FAILED: 503,
+	TRANSFER_EXPORT_CONCURRENT_WRITES: 409,
+	TRANSFER_OPERATION_NOT_FOUND: 404,
+	TRANSFER_INVALID_STATE: 409,
+	TRANSFER_LEASE_ACTIVE: 409,
+	TRANSFER_LEASE_LOST: 409,
+	TRANSFER_RUNTIME_MISMATCH: 409,
+	TRANSFER_IDEMPOTENCY_CONFLICT: 409,
+	TRANSFER_TARGET_NOT_EMPTY: 409,
+	TRANSFER_EXPIRED: 410,
+	TRANSFER_MANIFEST_INVALID: 422,
+	TRANSFER_UNSUPPORTED_FORMAT: 422,
+	TRANSFER_UNSUPPORTED_FEATURE: 422,
+	TRANSFER_PATH_INVALID: 422,
+	TRANSFER_FILE_NOT_DECLARED: 422,
+	TRANSFER_FILE_MISSING: 422,
+	TRANSFER_FILE_SIZE_MISMATCH: 422,
+	TRANSFER_FILE_DIGEST_MISMATCH: 422,
+	TRANSFER_CONTAINER_INVALID: 422,
+	TRANSFER_LIMIT_EXCEEDED: 413,
+	TRANSFER_RECORD_INVALID: 422,
+	TRANSFER_REFERENCE_INVALID: 422,
+	TRANSFER_MEDIA_REF_INVALID: 422,
+	TRANSFER_MEDIA_BLOB_MISSING: 422,
+	TRANSFER_SCHEMA_UNCLASSIFIED: 500,
+	TRANSFER_PACKAGE_DIGEST_MISMATCH: 409,
+	TRANSFER_PLAN_DIGEST_MISMATCH: 409,
+	TRANSFER_PLAN_BLOCKED: 409,
+	TRANSFER_DECISIONS_INVALID: 422,
+	TRANSFER_VERIFICATION_FAILED: 422,
+	TRANSFER_APPROVAL_REQUIRED: 403,
+	TRANSFER_APPROVAL_INVALID: 403,
+	TRANSFER_STORAGE_ERROR: 500,
+	TRANSFER_EXPORT_ERROR: 500,
+	TRANSFER_ANALYZE_ERROR: 500,
+	TRANSFER_IMPORT_ERROR: 500,
+});
+
+export function isTransferErrorCode(code: string | undefined): code is TransferErrorCode {
+	return code !== undefined && Object.hasOwn(TRANSFER_ERROR_STATUS, code);
+}
+
+export function transferErrorStatus(code: string | undefined): number | undefined {
+	return isTransferErrorCode(code) ? TRANSFER_ERROR_STATUS[code] : undefined;
+}
+
+/**
+ * JSON-safe, bounded detail attached to a transfer error. Never put record
+ * contents, credentials, or storage keys here: details reach API clients and
+ * operation rows.
+ */
+export type TransferErrorDetail = Readonly<Record<string, string | number | boolean | null>>;
+
+export const transferErrorDetailSchema = z.record(
+	z.string(),
+	z.union([z.string(), z.number(), z.boolean(), z.null()]),
+);
+
+export class TransferError extends Error {
+	readonly code: TransferErrorCode;
+	readonly status: number;
+	readonly detail: TransferErrorDetail | undefined;
+
+	constructor(
+		code: TransferErrorCode,
+		message: string,
+		options: { detail?: TransferErrorDetail; cause?: unknown } = {},
+	) {
+		super(message, options.cause === undefined ? undefined : { cause: options.cause });
+		this.name = "TransferError";
+		this.code = code;
+		this.status = TRANSFER_ERROR_STATUS[code];
+		this.detail = options.detail;
+	}
+}
+
+export function isTransferError(error: unknown): error is TransferError {
+	return error instanceof TransferError;
+}