emdash 0.39.1 → 0.40.0

package/src/transfer/ops/time.ts

@@ -0,0 +1,54 @@
+/**
+ * Database-clock timestamps for transfer state. Every lease and expiry
+ * comparison runs in SQL against the database clock, never a worker clock,
+ * and every stored timestamp uses the sortable `YYYY-MM-DDTHH:MM:SS.sssZ`
+ * form so plain string comparison orders them.
+ */
+
+import { sql, type Kysely, type RawBuilder } from "kysely";
+
+import { isPostgres } from "../../database/dialect-helpers.js";
+import type { Database } from "../../database/types.js";
+
+type AnyKysely = Kysely<Database>;
+
+export function timestampOffset(db: AnyKysely, seconds: number): RawBuilder<string> {
+	if (!Number.isFinite(seconds)) throw new RangeError("Invalid timestamp offset");
+	if (isPostgres(db)) {
+		return sql<string>`to_char(
+			clock_timestamp() AT TIME ZONE 'UTC' + (${seconds} * interval '1 second'),
+			'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"'
+		)`;
+	}
+	return sql<string>`strftime('%Y-%m-%dT%H:%M:%fZ', 'now', ${`${seconds >= 0 ? "+" : ""}${seconds} seconds`})`;
+}
+
+export function timestampNow(db: AnyKysely): RawBuilder<string> {
+	return timestampOffset(db, 0);
+}
+
+/** `column <= now` */
+export function timestampIsDue(db: AnyKysely, column: string): RawBuilder<boolean> {
+	return isPostgres(db)
+		? sql<boolean>`${sql.ref(column)}::timestamptz <= clock_timestamp()`
+		: sql<boolean>`${sql.ref(column)} <= strftime('%Y-%m-%dT%H:%M:%fZ', 'now')`;
+}
+
+/** `column > now` */
+export function timestampIsLive(db: AnyKysely, column: string): RawBuilder<boolean> {
+	return isPostgres(db)
+		? sql<boolean>`${sql.ref(column)}::timestamptz > clock_timestamp()`
+		: sql<boolean>`${sql.ref(column)} > strftime('%Y-%m-%dT%H:%M:%fZ', 'now')`;
+}
+
+/** `column <= now - seconds` */
+export function timestampIsOlderThan(
+	db: AnyKysely,
+	column: string,
+	seconds: number,
+): RawBuilder<boolean> {
+	if (!Number.isFinite(seconds) || seconds < 0) throw new RangeError("Invalid timestamp age");
+	return isPostgres(db)
+		? sql<boolean>`${sql.ref(column)}::timestamptz <= clock_timestamp() - (${seconds} * interval '1 second')`
+		: sql<boolean>`${sql.ref(column)} <= strftime('%Y-%m-%dT%H:%M:%fZ', 'now', ${`-${seconds} seconds`})`;
+}

package/src/transfer/schema-importer.ts

@@ -0,0 +1,34 @@
+import type { CollectionRecord, FieldRecord } from "./format/kinds.js";
+
+export interface ImportCollectionOptions {
+	/**
+	 * Tolerate a partially completed earlier attempt: create tables and
+	 * indexes with `IF NOT EXISTS`, insert rows with `ON CONFLICT DO NOTHING`,
+	 * then assert that the stored rows equal the records.
+	 */
+	resume: true;
+}
+
+export interface ImportCollectionResult {
+	/** Whether this call created the collection row (false when resuming). */
+	collectionCreated: boolean;
+	fieldsCreated: number;
+}
+
+/**
+ * Writes one package collection and its fields with their exact ids and
+ * every column, creating the `ec_*` table and indexes the same way
+ * `SchemaRegistry` does and installing media-usage capture. The collection's
+ * `search_config` is written with `enabled: false`; the rebuild stage enables
+ * search after content is imported. Title and date fields are set after the
+ * fields exist.
+ *
+ * Implemented by `SchemaRegistry.importCollection`.
+ */
+export interface CollectionImporter {
+	importCollection(
+		collection: CollectionRecord,
+		fields: readonly FieldRecord[],
+		options: ImportCollectionOptions,
+	): Promise<ImportCollectionResult>;
+}

package/src/transfer/site-id.ts

@@ -0,0 +1,30 @@
+import type { Kysely } from "kysely";
+import { ulid } from "ulidx";
+
+import { OptionsRepository } from "../database/repositories/options.js";
+import type { Database } from "../database/types.js";
+
+/**
+ * Option holding this installation's site id. Target-local: never exported
+ * and never overwritten by an import.
+ */
+export const SITE_ID_OPTION = "emdash:site_id";
+
+/**
+ * This installation's site id, created on first use. Concurrent first callers
+ * converge on one value: creation is an insert-if-absent, and a caller that
+ * loses the race reads the winner's value.
+ */
+export async function getOrCreateSiteId(db: Kysely<Database>): Promise<string> {
+	const options = new OptionsRepository(db);
+	const existing = await options.get(SITE_ID_OPTION);
+	if (typeof existing === "string" && existing.length > 0) return existing;
+
+	const candidate = ulid();
+	const result = await options.compareAndSet(SITE_ID_OPTION, null, candidate);
+	if (result.applied) return candidate;
+
+	const winner = await options.get(SITE_ID_OPTION);
+	if (typeof winner === "string" && winner.length > 0) return winner;
+	throw new Error("Site id option exists but is not a non-empty string");
+}

package/src/transfer/staging/assembler.ts

@@ -0,0 +1,217 @@
+/**
+ * In-memory package assembly for small packages (fixtures, tests, tools):
+ * feed records in package order and blobs in any order, then `finish` writes
+ * the index chunks and the manifest. The server-side exporter works in
+ * bounded steps instead and does not use this.
+ */
+
+import { TransferError } from "../errors.js";
+import { compareUtf16 } from "../format/canonical.js";
+import { sha256Hex, type Sha256Digest } from "../format/digest.js";
+import { KIND_FEATURE, requiredFeaturesFor, type SitePackageFeature } from "../format/features.js";
+import {
+	compareStreamOrder,
+	recordKindIndex,
+	type RecordKind,
+	type SitePackageRecord,
+} from "../format/kinds.js";
+import { TRANSFER_LIMITS } from "../format/limits.js";
+import type { PackageFileEntry, SitePackageManifest } from "../format/manifest.js";
+import { encodeRecordLine } from "../format/records.js";
+import type { ExportTransformation } from "../format/transformations.js";
+import {
+	SITE_PACKAGE_FORMAT,
+	SITE_PACKAGE_FORMAT_VERSION,
+	SITE_PACKAGE_PROFILE,
+} from "../format/version.js";
+import type { StagedPackageWriter } from "./package.js";
+
+const encoder = new TextEncoder();
+
+export interface PackageMetadata {
+	packageId: string;
+	originSiteId: string;
+	createdAt: string;
+	createdByEmDashVersion: string;
+	defaultLocale: string;
+	/** Features beyond those implied by the records (e.g. an empty `comments`). */
+	extraFeatures?: readonly SitePackageFeature[];
+	transformations?: readonly ExportTransformation[];
+	fenceAttempts?: number;
+}
+
+export interface AssembledPackage {
+	manifest: SitePackageManifest;
+	digest: Sha256Digest;
+}
+
+interface PendingChunk {
+	kind: RecordKind;
+	lines: string[];
+	bytes: number;
+	records: SitePackageRecord[];
+}
+
+export class PackageAssembler {
+	readonly #writer: StagedPackageWriter;
+	readonly #files: PackageFileEntry[] = [];
+	readonly #counts = new Map<RecordKind, { count: number; chunks: number }>();
+	readonly #blobs = new Map<string, number>();
+	readonly #locales = new Set<string>();
+	#hasTrash = false;
+	#pending: PendingChunk | null = null;
+	#lastKind: RecordKind | null = null;
+	#lastKey: { id: string; depth?: number } | null = null;
+	#finished = false;
+
+	constructor(writer: StagedPackageWriter) {
+		this.#writer = writer;
+	}
+
+	/**
+	 * Add the next record. Kinds must arrive in `RECORD_KINDS` order and
+	 * records within a kind in stream order; pass `depth` for topological kinds.
+	 */
+	async addRecord(record: SitePackageRecord, options: { depth?: number } = {}): Promise<void> {
+		this.assertOpen();
+		const kind = record.kind;
+		if (this.#lastKind !== null && recordKindIndex(kind) < recordKindIndex(this.#lastKind)) {
+			throw new TransferError("TRANSFER_RECORD_INVALID", "Record kinds out of package order", {
+				detail: { kind },
+			});
+		}
+		const key = { id: record.id, depth: options.depth };
+		if (
+			this.#lastKind === kind &&
+			this.#lastKey &&
+			compareStreamOrder(kind, this.#lastKey, key) >= 0
+		) {
+			throw new TransferError("TRANSFER_RECORD_INVALID", "Records out of stream order", {
+				detail: { kind, id: record.id },
+			});
+		}
+		if (this.#lastKind !== kind) await this.flush();
+		this.#lastKind = kind;
+		this.#lastKey = key;
+
+		if ("locale" in record && typeof record.locale === "string") this.#locales.add(record.locale);
+		if (record.kind === "entry" && record.deletedAt !== undefined) this.#hasTrash = true;
+
+		const line = encodeRecordLine(record);
+		const lineBytes = encoder.encode(line).byteLength + 1;
+		const pending = this.#pending;
+		if (
+			pending &&
+			(pending.lines.length >= TRANSFER_LIMITS.chunkRecords ||
+				pending.bytes + lineBytes > TRANSFER_LIMITS.chunkBytes)
+		) {
+			await this.flush();
+		}
+		this.#pending ??= { kind, lines: [], bytes: 0, records: [] };
+		this.#pending.lines.push(line);
+		this.#pending.bytes += lineBytes;
+		this.#pending.records.push(record);
+	}
+
+	/** Store a blob (deduplicated by digest); returns its hex SHA-256. */
+	async addBlob(bytes: Uint8Array): Promise<string> {
+		this.assertOpen();
+		const sha256 = await sha256Hex(bytes);
+		if (!this.#blobs.has(sha256)) {
+			this.#files.push(await this.#writer.writeBlob(sha256, bytes, bytes.byteLength));
+			this.#blobs.set(sha256, bytes.byteLength);
+		}
+		return sha256;
+	}
+
+	async finish(metadata: PackageMetadata): Promise<AssembledPackage> {
+		this.assertOpen();
+		await this.flush();
+		this.#finished = true;
+
+		const features = new Set<SitePackageFeature>(metadata.extraFeatures ?? []);
+		for (const kind of this.#counts.keys()) features.add(KIND_FEATURE[kind]);
+		if (this.#blobs.size > 0) features.add("media");
+		if (this.#locales.size > 1) features.add("i18n");
+		if (this.#hasTrash) features.add("trash");
+		const featureList = [...features].toSorted(compareUtf16);
+
+		const files = this.#files.toSorted((a, b) => compareUtf16(a.path, b.path));
+		const chunks: PackageFileEntry[][] = [];
+		let current: PackageFileEntry[] = [];
+		let currentBytes = 0;
+		for (const entry of files) {
+			const size = encoder.encode(JSON.stringify(entry)).byteLength + 1;
+			if (
+				current.length >= TRANSFER_LIMITS.chunkRecords ||
+				(current.length > 0 && currentBytes + size > TRANSFER_LIMITS.chunkBytes)
+			) {
+				chunks.push(current);
+				current = [];
+				currentBytes = 0;
+			}
+			current.push(entry);
+			currentBytes += size;
+		}
+		if (current.length > 0) chunks.push(current);
+		const index = [];
+		for (const [seq, entries] of chunks.entries()) {
+			index.push(await this.#writer.writeIndexChunk(seq, entries));
+		}
+
+		const locales = new Set(this.#locales);
+		locales.add(metadata.defaultLocale);
+		const manifest: SitePackageManifest = {
+			format: SITE_PACKAGE_FORMAT,
+			formatVersion: SITE_PACKAGE_FORMAT_VERSION,
+			packageId: metadata.packageId,
+			originSiteId: metadata.originSiteId,
+			createdAt: metadata.createdAt,
+			createdByEmDashVersion: metadata.createdByEmDashVersion,
+			profile: SITE_PACKAGE_PROFILE,
+			features: featureList,
+			requiredFeatures: requiredFeaturesFor(featureList),
+			locales: {
+				default: metadata.defaultLocale,
+				used: [...locales].toSorted(compareUtf16),
+			},
+			records: Object.fromEntries(this.#counts),
+			media: {
+				count: this.#blobs.size,
+				totalBytes: [...this.#blobs.values()].reduce((sum, bytes) => sum + bytes, 0),
+			},
+			files: {
+				count: files.length,
+				totalBytes: files.reduce((sum, file) => sum + file.bytes, 0),
+			},
+			index,
+			transformations: (metadata.transformations ?? []).toSorted(
+				(a, b) => compareUtf16(a.code, b.code) || compareUtf16(a.kind, b.kind),
+			),
+			fence: { attempts: metadata.fenceAttempts ?? 1 },
+		};
+		const digest = await this.#writer.writeManifest(manifest);
+		return { manifest, digest };
+	}
+
+	private async flush(): Promise<void> {
+		const pending = this.#pending;
+		if (!pending) return;
+		this.#pending = null;
+		const summary = this.#counts.get(pending.kind) ?? { count: 0, chunks: 0 };
+		const entry = await this.#writer.writeRecordChunk(
+			pending.kind,
+			summary.chunks,
+			pending.records,
+		);
+		this.#files.push(entry);
+		this.#counts.set(pending.kind, {
+			count: summary.count + pending.records.length,
+			chunks: summary.chunks + 1,
+		});
+	}
+
+	private assertOpen(): void {
+		if (this.#finished) throw new Error("Package assembler already finished");
+	}
+}

package/src/transfer/staging/keys.ts

@@ -0,0 +1,94 @@
+/**
+ * Storage layout for staged packages.
+ *
+ * ```
+ * transfers/imports/<operationId>-<secret>/<package path>
+ * transfers/exports/<operationId>-<secret>/<package path>
+ * transfers/<kind>/<operationId>-<secret>/_plan.json
+ * ```
+ *
+ * `secret` is the operation's 128-bit `staging_secret`, so a staged object's
+ * key cannot be guessed from an operation id. The public media route must
+ * refuse every key under `transfers/` ({@link isTransferStorageKey}).
+ */
+
+import { TransferError } from "../errors.js";
+import { isPackagePath } from "../format/paths.js";
+import type { TransferOperationKind } from "../ops/states.js";
+
+export const TRANSFER_STORAGE_PREFIX = "transfers/";
+
+/** Staged files that are not part of the package itself. */
+export const STAGING_AUX_FILES = Object.freeze({
+	plan: "_plan.json",
+});
+
+export type StagingAuxFile = keyof typeof STAGING_AUX_FILES;
+
+const OPERATION_ID_PATTERN = /^[0-9A-HJKMNP-TV-Z]{26}$/;
+const SECRET_PATTERN = /^[0-9a-f]{32}$/;
+
+export function stagingPrefix(
+	kind: TransferOperationKind,
+	operationId: string,
+	stagingSecret: string,
+): string {
+	if (!OPERATION_ID_PATTERN.test(operationId) || !SECRET_PATTERN.test(stagingSecret)) {
+		throw new TransferError("TRANSFER_STORAGE_ERROR", "Invalid staging location");
+	}
+	return `${TRANSFER_STORAGE_PREFIX}${kind}s/${operationId}-${stagingSecret}/`;
+}
+
+/** Storage key of a package file under `prefix`. Rejects anything but a package path. */
+export function stagingKey(prefix: string, path: string): string {
+	if (!isPackagePath(path)) {
+		throw new TransferError("TRANSFER_PATH_INVALID", "Invalid package path", { detail: { path } });
+	}
+	return `${prefix}${path}`;
+}
+
+export function stagingAuxKey(prefix: string, file: StagingAuxFile): string {
+	return `${prefix}${STAGING_AUX_FILES[file]}`;
+}
+
+/**
+ * Normalize a storage key for prefix guards, or return null when the key is
+ * not a plain relative key: a leading `/` or `\`, any backslash, an empty
+ * segment, or a `.`/`..` segment. The result is lowercased because some
+ * storage backends treat keys case-insensitively. Guards must refuse keys
+ * this returns null for.
+ */
+export function normalizeStorageKeyForGuard(key: string): string | null {
+	if (key.length === 0 || key.includes("\\")) return null;
+	const segments = key.split("/");
+	for (const segment of segments) {
+		if (segment === "" || segment === "." || segment === "..") return null;
+	}
+	return key.toLowerCase();
+}
+
+/** Prefixes the public media route must never serve. */
+export const PRIVATE_STORAGE_PREFIXES: readonly string[] = Object.freeze([
+	"backups/",
+	TRANSFER_STORAGE_PREFIX,
+]);
+
+/**
+ * Whether a public route must refuse `key`: it is not a plain relative key
+ * or it falls under one of `prefixes`.
+ */
+export function isRefusedStorageKey(
+	key: string,
+	prefixes: readonly string[] = PRIVATE_STORAGE_PREFIXES,
+): boolean {
+	const normalized = normalizeStorageKeyForGuard(key);
+	return normalized === null || prefixes.some((prefix) => normalized.startsWith(prefix));
+}
+
+/**
+ * Whether a storage key is (or may resolve to) transfer staging. Also true
+ * for keys {@link normalizeStorageKeyForGuard} rejects.
+ */
+export function isTransferStorageKey(key: string): boolean {
+	return isRefusedStorageKey(key, [TRANSFER_STORAGE_PREFIX]);
+}

package/src/transfer/staging/package.ts

@@ -0,0 +1,229 @@
+/**
+ * Staged package reader and writer.
+ *
+ * The writer stores package files under a {@link TransferStage}, returning
+ * the index entry (size and digest) for each. The reader parses and validates
+ * what is staged: the manifest, index chunks (checked against the digests the
+ * manifest pins), record chunks (every line strictly validated), and blobs.
+ */
+
+import { TransferError } from "../errors.js";
+import { canonicalJson } from "../format/canonical.js";
+import { packageDigest, sha256Hex, type Sha256Digest } from "../format/digest.js";
+import type { RecordKind, RecordOfKind } from "../format/kinds.js";
+import { TRANSFER_LIMITS } from "../format/limits.js";
+import {
+	parseIndexLine,
+	parseManifest,
+	serializeManifest,
+	type IndexChunkRef,
+	type PackageFileEntry,
+	type SitePackageManifest,
+} from "../format/manifest.js";
+import { indexChunkPath, MANIFEST_PATH, mediaBlobPath, recordChunkPath } from "../format/paths.js";
+import {
+	decodeRecordLine,
+	encodeChunk,
+	encodeRecordLine,
+	splitChunkLines,
+} from "../format/records.js";
+import { readStreamBytes, TransferStage, type ExpectedFile } from "./stage.js";
+
+const encoder = new TextEncoder();
+
+export class StagedPackageWriter {
+	constructor(readonly stage: TransferStage) {}
+
+	/** Store bytes at a package path; returns its index entry (without `records`). */
+	async writeFile(path: string, bytes: Uint8Array): Promise<PackageFileEntry> {
+		const sha256 = await sha256Hex(bytes);
+		await this.stage.putVerified(path, bytes, bytes.byteLength, sha256);
+		return { path, bytes: bytes.byteLength, sha256 };
+	}
+
+	/** Encode and store one record chunk. Records must already be in stream order. */
+	async writeRecordChunk<K extends RecordKind>(
+		kind: K,
+		seq: number,
+		records: readonly RecordOfKind<K>[],
+	): Promise<PackageFileEntry> {
+		const path = recordChunkPath(kind, seq);
+		for (const record of records) {
+			if (record.kind !== kind) {
+				throw new TransferError("TRANSFER_RECORD_INVALID", "Record kind does not match its chunk", {
+					detail: { path, id: record.id },
+				});
+			}
+		}
+		const lines = records.map((record) => encodeRecordLine(record));
+		const entry = await this.writeFile(path, encodeChunk(lines, path));
+		return { ...entry, records: records.length };
+	}
+
+	/** Encode and store one index chunk. */
+	async writeIndexChunk(seq: number, entries: readonly PackageFileEntry[]): Promise<IndexChunkRef> {
+		const path = indexChunkPath(seq);
+		const lines = entries.map((entry) => canonicalJson(entry));
+		const file = await this.writeFile(path, encodeChunk(lines, path));
+		return { path, bytes: file.bytes, sha256: file.sha256, entries: entries.length };
+	}
+
+	/** Store a media blob, verifying the declared size and digest as it streams. */
+	async writeBlob(
+		sha256: string,
+		body: ReadableStream<Uint8Array> | Uint8Array,
+		bytes: number,
+	): Promise<PackageFileEntry> {
+		const path = mediaBlobPath(sha256);
+		await this.stage.putVerified(path, body, bytes, sha256);
+		return { path, bytes, sha256 };
+	}
+
+	/** Store the manifest; returns its package digest. */
+	async writeManifest(manifest: SitePackageManifest): Promise<Sha256Digest> {
+		const text = serializeManifest(parseManifest(serializeManifest(manifest)));
+		const bytes = encoder.encode(text);
+		await this.stage.putVerified(MANIFEST_PATH, bytes, bytes.byteLength, await sha256Hex(bytes));
+		return packageDigest(manifest);
+	}
+}
+
+export interface StagedRecord<K extends RecordKind> {
+	record: RecordOfKind<K>;
+	/** Canonical line without newline; its SHA-256 is the record hash. */
+	line: string;
+	seq: number;
+	/** Zero-based line number within the chunk. */
+	index: number;
+}
+
+/** Size and digest a staged file must have when read, or null when it is not verified. */
+export type StagedFileDigests = (path: string) => Promise<ExpectedFile | null>;
+
+export class StagedPackageReader {
+	#manifest: SitePackageManifest | undefined;
+
+	/**
+	 * With `digests`, every record chunk read is checked against the size and
+	 * digest it was verified with, and a chunk that is not verified is missing.
+	 */
+	constructor(
+		readonly stage: TransferStage,
+		private readonly digests?: StagedFileDigests,
+	) {}
+
+	/** The parsed, validated manifest (read once). */
+	async manifest(): Promise<SitePackageManifest> {
+		if (!this.#manifest) {
+			const bytes = await this.stage.readBytes(MANIFEST_PATH, TRANSFER_LIMITS.manifestBytes);
+			this.#manifest = parseManifest(bytes);
+		}
+		return this.#manifest;
+	}
+
+	async digest(): Promise<Sha256Digest> {
+		return packageDigest(await this.manifest());
+	}
+
+	/** Entries of one index chunk, verified against the digest the manifest pins. */
+	async indexChunk(seq: number): Promise<PackageFileEntry[]> {
+		const manifest = await this.manifest();
+		const ref = manifest.index[seq];
+		if (!ref) {
+			throw new TransferError("TRANSFER_FILE_MISSING", "Index chunk is not declared", {
+				detail: { seq },
+			});
+		}
+		const bytes = await this.readVerified(ref.path, ref);
+		const entries = splitChunkLines(bytes, ref.path).map((line) => parseIndexLine(line));
+		if (entries.length !== ref.entries) {
+			throw new TransferError("TRANSFER_MANIFEST_INVALID", "Index chunk entry count mismatch", {
+				detail: { path: ref.path },
+			});
+		}
+		return entries;
+	}
+
+	/** Every index entry in path order, starting at index chunk `fromSeq`. */
+	async *index(fromSeq = 0): AsyncGenerator<{ seq: number; entry: PackageFileEntry }> {
+		const manifest = await this.manifest();
+		for (let seq = fromSeq; seq < manifest.index.length; seq++) {
+			for (const entry of await this.indexChunk(seq)) yield { seq, entry };
+		}
+	}
+
+	/**
+	 * Records of one chunk, each strictly validated. Pass `expected` (from the
+	 * index) to also verify the chunk's size and digest; otherwise the reader's
+	 * `digests`, when it has them, supply it.
+	 */
+	async readChunk<K extends RecordKind>(
+		kind: K,
+		seq: number,
+		expected?: ExpectedFile,
+	): Promise<Array<StagedRecord<K>>> {
+		const path = recordChunkPath(kind, seq);
+		const file = expected ?? (await this.expectedFile(path));
+		const bytes = file
+			? await this.readVerified(path, file)
+			: await this.stage.readBytes(path, TRANSFER_LIMITS.chunkBytes);
+		return splitChunkLines(bytes, path).map((line, index) => {
+			const decoded = decodeRecordLine(kind, line, { path, line: index + 1 });
+			return { record: decoded.record, line: decoded.line, seq, index };
+		});
+	}
+
+	/** Records of `kind` in stream order, starting at chunk `fromSeq`. */
+	async *records<K extends RecordKind>(kind: K, fromSeq = 0): AsyncGenerator<StagedRecord<K>> {
+		const manifest = await this.manifest();
+		const chunks = manifest.records[kind]?.chunks ?? 0;
+		for (let seq = fromSeq; seq < chunks; seq++) {
+			yield* await this.readChunk(kind, seq);
+		}
+	}
+
+	async blob(sha256: string): Promise<ReadableStream<Uint8Array>> {
+		return (await this.stage.open(mediaBlobPath(sha256))).body;
+	}
+
+	private async expectedFile(path: string): Promise<ExpectedFile | undefined> {
+		if (!this.digests) return undefined;
+		const expected = await this.digests(path);
+		if (!expected) {
+			throw new TransferError("TRANSFER_FILE_MISSING", "Staged file is not verified", {
+				detail: { path },
+			});
+		}
+		return expected;
+	}
+
+	private async readVerified(path: string, expected: ExpectedFile): Promise<Uint8Array> {
+		const file = await this.stage.open(path);
+		let bytes: Uint8Array;
+		try {
+			bytes = await readStreamBytes(file.body, Math.max(expected.bytes, 0));
+		} catch (error) {
+			if (error instanceof TransferError && error.code === "TRANSFER_LIMIT_EXCEEDED") {
+				throw new TransferError("TRANSFER_FILE_SIZE_MISMATCH", "Staged file size does not match", {
+					detail: { path },
+				});
+			}
+			throw error;
+		}
+		if (bytes.byteLength !== expected.bytes) {
+			throw new TransferError("TRANSFER_FILE_SIZE_MISMATCH", "Staged file size does not match", {
+				detail: { path },
+			});
+		}
+		if ((await sha256Hex(bytes)) !== expected.sha256) {
+			throw new TransferError(
+				"TRANSFER_FILE_DIGEST_MISMATCH",
+				"Staged file digest does not match",
+				{
+					detail: { path },
+				},
+			);
+		}
+		return bytes;
+	}
+}