@fabrika/app 0.5.4 → 0.5.5

package/src/contract/defaults.ts

@@ -27,6 +27,33 @@ export const FORM_LIMITS = {
 /** The input field that carries a form's challenge token; a form with a challenge declares it as a string. */
 export const FORM_CHALLENGE_FIELD = 'challengeToken'
 
+/**
+ * A form that takes files is `multipart/form-data`: its input travels as JSON in the first part, named `input`, and each
+ * file in a part named after its field. The proxy admits only that type for such a form.
+ */
+export { FORM_MULTIPART_TYPE } from '@fabrika/auth-core'
+export const FORM_INPUT_PART = 'input'
+
+/**
+ * The bounds of a form's files: at most `maxFields` file fields, a file each; a received file waits `holdMs` for the
+ * job that drains the inbox to attach it, then the sweep deletes it; a submission's body must arrive within
+ * `timeoutMs`; a part's headers hold at most `maxPartHeaderBytes`.
+ */
+export const FORM_FILE_LIMITS = {
+	maxFields: 4,
+	holdMs: 7 * 24 * 60 * 60 * 1000,
+	timeoutMs: 5 * 60 * 1000,
+	maxPartHeaderBytes: 8 * 1024,
+	/**
+	 * A form with files accepts this many submissions per minute unless it declares `rate.perForm`, and its files write
+	 * at most `bytesPerHour` per hour unless it declares `rate.bytesPerHour` (at most `maxBytesPerHour`). Each file
+	 * reserves its collection's `maxBytes` before its first byte is written, and gives back what it did not use.
+	 */
+	perForm: 20,
+	bytesPerHour: 512 * 1024 * 1024,
+	maxBytesPerHour: 64 * 1024 * 1024 * 1024,
+} as const
+
 /** Each challenge provider's fixed browser origins: its widget's script and its frame. */
 export const CHALLENGE_ORIGINS: Readonly<Record<ChallengeProvider, { readonly scriptSrc: readonly string[]; readonly frameSrc: readonly string[] }>> =
 	{

package/src/contract/define.ts

@@ -313,19 +313,32 @@ export interface FormChallengeOption {
 	readonly siteKey?: string
 }
 
+/** A file field of a form: the collection its file lands in (a `scan: true` one), and whether a submission must carry it. */
+export interface FormFileOption {
+	readonly collection: string
+	/** `true`: a submission without the file is refused (400). Absent or `false`: the column gets `null`. */
+	readonly required?: boolean
+}
+
 /** What `c.form(path, options)` takes. */
 export type FormOptions<I, T> =
 	& {
 		readonly input: I & NotLoose<I>
 		readonly appendTo: string
 		readonly maxBytes?: number
-		readonly rate?: { readonly perClient?: number; readonly perForm?: number }
+		/** Per minute; `bytesPerHour` only on a form with files, the bytes all its submissions write per hour. */
+		readonly rate?: { readonly perClient?: number; readonly perForm?: number; readonly bytesPerHour?: number }
 		readonly honeypot?: string
 		readonly challenge?: FormChallengeOption
 		/** The cron job each accepted submission kicks, in the background of the constant answer. */
 		readonly then?: T
 		/** A page on another origin may submit it: `true` from the environment's listed origins, `'*'` from any. */
 		readonly crossOrigin?: true | '*'
+		/**
+		 * Files a submission carries beside its input, by field. The form becomes `multipart/form-data` and needs a
+		 * challenge; each file waits, owned by nobody, until the job that drains the inbox attaches it.
+		 */
+		readonly files?: { readonly [field: string]: FormFileOption }
 	}
 	& Owned<'kind' | 'path'>
 
@@ -494,6 +507,7 @@ export function surfaceKit<A extends string, D extends string, CD extends string
 			challenge: options.challenge,
 			then: options.then,
 			...(options.crossOrigin === undefined ? {} : { crossOrigin: options.crossOrigin }),
+			...(options.files === undefined ? {} : { files: options.files }),
 			unknownOptions: unknownOptions(options, 'form'),
 		}),
 		webhook: (path, options) => ({

package/src/contract/kit.ts

@@ -34,6 +34,7 @@ import {
 	type CronJob,
 	type Export,
 	type FormChallengeOption,
+	type FormFileOption,
 	type FormJobs,
 	type FormMount,
 	type FormOptions,
@@ -192,11 +193,14 @@ type InboxTarget<Ix extends AnyDbIndex, T, Fields, H, Ch> = unknown extends OneN
 	: OneName<T, LiteralInbox>
 
 type ExtraFields<T extends string, Extra extends string, Columns extends string> = [Extra] extends [never] ? unknown
-	: Unavailable<`the inbox ${T} has no column ${ListOf<Extra>}: each input field is named like its column (columns: ${ListOf<Columns>})`>
+	: Unavailable<`the inbox ${T} has no column ${ListOf<Extra>}: each input and file field is named like its column (columns: ${ListOf<Columns>})`>
 
 /** The challenge token's field, exempt from the inbox's columns where the form declares a challenge. */
 type ChallengeField<Ch> = [Ch] extends [never] ? never : typeof FORM_CHALLENGE_FIELD
 
+/** A form's file fields: each is a column of its inbox too, which receives the held file's id. */
+type FileFields<F> = [F] extends [never] ? never : keyof F
+
 /** The builders of the contract's callback: the mounts that take no handler, and `rpc`, which mounts groups. */
 export interface ContractKit<K extends KitTypes> extends Pick<Kit<K['action'], K['dimension'], K['creatable']>, 'spa' | 'health' | 'files'> {
 	/** A form that appends each submission to its inbox `appendTo`, one column per input field, and answers a constant. */
@@ -206,12 +210,14 @@ export interface ContractKit<K extends KitTypes> extends Pick<Kit<K['action'], K
 		const H extends string = never,
 		const Ch extends FormChallengeOption = never,
 		const Then extends string = never,
+		const F extends { readonly [field: string]: FormFileOption } = never,
 	>(
 		path: Path,
 		options: FormOptions<I, Then> & {
-			readonly appendTo: T & NoInfer<InboxTarget<K['index'], T, keyof z.output<I>, H, ChallengeField<Ch>>>
+			readonly appendTo: T & NoInfer<InboxTarget<K['index'], T, keyof z.output<I> | FileFields<F>, H, ChallengeField<Ch>>>
 			readonly honeypot?: H & NoInfer<OneName<H, LiteralHoneypot>>
 			readonly challenge?: Ch
+			readonly files?: F
 		},
 	): FormMount<I, NoInfer<Then>>
 	/** The groups' endpoints at `POST <prefix>/<group>.<endpoint>`, to the callers the groups name. */

package/src/files/collections.ts

@@ -10,10 +10,13 @@ import {
 	type FileCollectionTable,
 	fileTableName,
 	fileTablesOf,
+	type FormFiles,
+	frameworkTablesOf,
 	isScopedDatabase,
 	QueryRefusedError,
 	type Session,
 	type StoredFile,
+	type WrittenFormFile,
 } from '@fabrika/db/framework'
 import { type FileObjectStore, type StoredObject, uuidv7 } from '@fabrika/platform'
 import { z } from 'zod/v4'
@@ -25,7 +28,7 @@ import { NO_FACILITIES, type ServedEndpoint } from '../implement/dispatch'
 import { ServerFault } from '../implement/faults'
 import type { ContractDatabase, ImplementationDatabase } from '../implement/implement'
 import type { OperationsReporter } from '../jobs/report'
-import type { FileCollectionHandle, FileCollections as FilesOfSite, FileListing, FileListPage, OpenedFile, OpenOptions } from './handle'
+import type { FileCollectionJobHandle, FileCollections as FilesOfSite, FileListing, FileListPage, OpenedFile, OpenOptions } from './handle'
 import { type FileScanner, runScanPass } from './scan'
 import { bytesAreOfType, SNIFF_BYTES, SNIFFABLE_TYPES } from './sniff'
 import { FileDownload } from './treatment'
@@ -63,6 +66,8 @@ export interface FileSite {
 	readonly session: () => Promise<Session>
 	/** `null` where `removeAll` runs (a mutation, a job's transaction); otherwise why it does not. */
 	readonly readOnly: string | null
+	/** Whether `attach` runs here: only in a job's transaction, the job that drains a form's inbox. */
+	readonly attaches: boolean
 }
 
 interface Collection {
@@ -84,11 +89,27 @@ function mediaType(header: string | null): string | null {
 
 /** The client's file name, metadata only: at most 255 code points, never half a character, no control characters. */
 export function originalName(request: Request): string | null {
-	const raw = new URL(request.url).searchParams.get('name') ?? ''
+	return cleanName(new URL(request.url).searchParams.get('name') ?? '')
+}
+
+function cleanName(raw: string): string | null {
 	const name = Array.from(raw.replace(/\p{Cc}/gu, '').trim()).slice(0, MAX_NAME_CODE_POINTS).join('')
 	return name === '' ? null : name
 }
 
+/** One file part of a form's submission, as the multipart reader hands it over. */
+export interface FormFilePart {
+	readonly filename: string | null
+	/** The media type the part declares; the bytes must be of it. */
+	readonly contentType: string | null
+	readonly body: ReadableStream<Uint8Array>
+}
+
+/** A form's file whose object is written under its pending row: what the inbox append holds, or a failure cleans up. */
+export interface ReceivedFormFile extends WrittenFormFile {
+	readonly objectKey: string
+}
+
 /** The first `size` bytes of `body`, and a stream that yields the whole body again. */
 async function readHead(
 	body: ReadableStream<Uint8Array>,
@@ -135,8 +156,8 @@ async function readHead(
 	return { head: buffered.subarray(0, size), stream }
 }
 
-/** The body as it is stored: hashed on the way, and failed once `timeoutMs` passes before it ends. */
-function digesting(body: ReadableStream<Uint8Array>, timeoutMs: number): {
+/** The body as it is stored: hashed on the way, and failed once `timeoutMs` (`null`: no timer) passes before it ends. */
+function digesting(body: ReadableStream<Uint8Array>, timeoutMs: number | null): {
 	readonly stream: ReadableStream<Uint8Array>
 	digest(): string
 	timedOut(): boolean
@@ -148,10 +169,12 @@ function digesting(body: ReadableStream<Uint8Array>, timeoutMs: number): {
 	const stream = body.pipeThrough(
 		new TransformStream<Uint8Array, Uint8Array>({
 			start(controller) {
-				timer = setTimeout(() => {
-					expired = true
-					controller.error(new Error('the upload did not finish in time'))
-				}, timeoutMs)
+				if (timeoutMs !== null) {
+					timer = setTimeout(() => {
+						expired = true
+						controller.error(new Error('the upload did not finish in time'))
+					}, timeoutMs)
+				}
 			},
 			transform(chunk, controller) {
 				hasher.update(chunk)
@@ -194,17 +217,36 @@ export class FileCollections {
 	readonly #store: FileObjectStore
 	readonly #capabilities: CapabilityAuthority
 	readonly #mint: CapabilityMint
-
-	constructor(collections: readonly Collection[], store: FileObjectStore, capabilities: CapabilityAuthority, mint: CapabilityMint) {
+	/** The files forms received, before they have an owner (`fabrika_form_files`). */
+	readonly #formFiles: FormFiles
+
+	constructor(
+		collections: readonly Collection[],
+		store: FileObjectStore,
+		capabilities: CapabilityAuthority,
+		mint: CapabilityMint,
+		formFiles: FormFiles,
+	) {
 		this.#collections = collections
 		this.#byDimension = new Map(collections.map((collection) => [collection.dimension, collection]))
 		this.#store = store
 		this.#capabilities = capabilities
 		this.#mint = mint
+		this.#formFiles = formFiles
+	}
+
+	/** Whether the contract declares the collection `name`, so a form's file can land in it. */
+	has(name: string): boolean {
+		return this.#collections.some((collection) => collection.name === name)
+	}
+
+	/** The largest file collection `name` admits; 0 for a collection it does not serve. */
+	maxBytesOf(name: string): number {
+		return this.#collections.find((collection) => collection.name === name)?.artifact.maxBytes ?? 0
 	}
 
 	/** `ctx.files` of one site: each collection's handle, by its name. */
-	site(site: FileSite): FilesOfSite<FileCollectionHandle> {
+	site(site: FileSite): FilesOfSite<FileCollectionJobHandle> {
 		const handles = new Map(this.#collections.map((collection) => [collection.name, this.#handle(collection, site)]))
 		return (name) => {
 			site.check()
@@ -219,7 +261,7 @@ export class FileCollections {
 		}
 	}
 
-	#handle(collection: Collection, site: FileSite): FileCollectionHandle {
+	#handle(collection: Collection, site: FileSite): FileCollectionJobHandle {
 		return Object.freeze({
 			list: async (owner: unknown, page: FileListPage = {}) => {
 				site.check()
@@ -239,9 +281,138 @@ export class FileCollections {
 				this.#ownerGrant(collection, site, owner, ['delete'])
 				return await collection.table.removeOwned(owner, new Date(), await site.session())
 			},
+			attach: async (owner: unknown, id: unknown) => {
+				site.check()
+				if (!site.attaches) {
+					throw new QueryRefusedError(
+						'undeclared_reach',
+						`${site.where}: files '${collection.name}' attach runs only in a job's ctx.transaction((tx) => …), as tx.files`,
+					)
+				}
+				const grant = this.#ownerGrant(collection, site, owner, ['write'])
+				if (typeof id !== 'string') {
+					throw new QueryRefusedError('invalid_argument', `${site.where}: files '${collection.name}' attach takes the id of a form's file`)
+				}
+				return await this.#attach(collection, grant, owner, id, await site.session())
+			},
 		})
 	}
 
+	/**
+	 * Moves the file a form received under `id` into the collection, owned by `owner`, in `session`: the transaction
+	 * that wrote the owner, so a rollback leaves the file held. A scanning collection holds it `quarantined` until the
+	 * scan job's verdict. `false` when no held file of this collection has the id (never received, of another collection,
+	 * or its hold ended); `true` again for a file this owner attached before, so a retried attempt answers alike.
+	 */
+	async #attach(collection: Collection, grant: RefGrant, owner: unknown, id: string, session: Session): Promise<boolean> {
+		const claimed = await this.#formFiles.claim(collection.name, id, session)
+		if (claimed === null) {
+			const located = UUID.test(id) ? await collection.table.locate(id, session) : null
+			return located !== null && located.get(grant.dimension) === grant.id
+				&& [...grant.chain].every(([dimension, value]) => located.get(dimension) === value)
+		}
+		// Thrown, not answered: the transaction rolls back, and the claimed file stays held for a later attempt.
+		const limit = collection.artifact.maxPerOwner
+		if ((await collection.table.adopt(owner, claimed, session, limit)) === 'limit') {
+			throw tooMany(collection)
+		}
+		// Counted again: an upload of a person may have passed its own count beside this one.
+		if (limit !== null && (await collection.table.countHeld(owner, session)) > limit) {
+			throw tooMany(collection)
+		}
+		return true
+	}
+
+	/**
+	 * Receives one file of a form's submission into collection `name`: the part's declared type must be one the
+	 * collection admits and its first bytes that type, its row in `fabrika_form_files` is written pending before its
+	 * object `<name>/<id>`, and the object stops at the collection's `maxBytes`. Answers `null` for an empty part without
+	 * a file name: a file input the visitor left empty. Whatever fails after the row cleans the object and the row up.
+	 */
+	async receiveFormFile(form: string, name: string, part: FormFilePart): Promise<ReceivedFormFile | null> {
+		const collection = this.#collections.find((candidate) => candidate.name === name)
+		if (collection === undefined) {
+			await part.body.cancel()
+			throw new ServerFault('contract_inconsistent', `form '${form}' takes a file into files '${name}', which is not served`)
+		}
+		const { artifact } = collection
+		const { head, stream } = await readHead(part.body, SNIFF_BYTES)
+		if (head.byteLength === 0 && (part.filename === null || part.filename === '')) {
+			// The part ended with no byte: it was read to its end, and the next part may follow.
+			return null
+		}
+		const type = part.contentType
+		if (type === null || !artifact.types.includes(type)) {
+			await stream.cancel()
+			throw new HttpError(415, 'unsupported_media_type', `files '${name}' admits ${artifact.types.join(', ')}`)
+		}
+		if (!bytesAreOfType(type, head)) {
+			await stream.cancel()
+			throw new HttpError(415, 'unsupported_media_type', `The bytes of the file are not ${type}`)
+		}
+		if (head.byteLength === 0 && artifact.scan === true) {
+			await stream.cancel()
+			throw new HttpError(400, 'empty', `files '${name}' scans its files and admits no empty file`)
+		}
+		const id = uuidv7()
+		const objectKey = `${name}/${id}`
+		await this.#formFiles.stage({ id, form, collection: name, objectKey, contentType: type, originalName: cleanName(part.filename ?? '') })
+		// The form's own deadline bounds the whole body, so the digest needs no timer of its own.
+		const body = digesting(stream, null)
+		try {
+			const { size } = await this.#store.write(objectKey, body.stream, { contentType: type, maxBytes: artifact.maxBytes })
+			return Object.freeze({ id, objectKey, size, sha256: body.digest() })
+		} catch (error) {
+			if (isNamed(error, 'ObjectExistsError')) {
+				// The key holds an object this submission did not write: never delete it, only the pending row.
+				await this.#formFiles.abandon(id)
+				throw new ServerFault('file_key_taken', `files '${name}' found an object already under a new file's key`)
+			}
+			await this.releaseFormFiles([{ id, objectKey }])
+			if (isNamed(error, 'ObjectTooLargeError')) {
+				throw tooLarge(collection)
+			}
+			throw error
+		} finally {
+			body.stop()
+		}
+	}
+
+	/**
+	 * Deletes the objects of files a submission received and then their pending rows: it did not commit. A failed step is
+	 * logged by its name and left for the sweep, which deletes a pending row after `PENDING_GRACE_MS`.
+	 */
+	async releaseFormFiles(files: readonly { readonly id: string; readonly objectKey: string }[]): Promise<void> {
+		for (const file of files) {
+			let step: FileCleanupStep = 'object_delete_failed'
+			try {
+				await this.#store.delete(file.objectKey)
+				step = 'row_delete_failed'
+				await this.#formFiles.abandon(file.id)
+			} catch {
+				console.error(`fabrika: form files cleanup: ${step}`)
+			}
+		}
+	}
+
+	/** One batch of the form files whose hold ended or whose submission never committed: the object, then the row. */
+	async #sweepFormFiles(): Promise<'more' | 'done' | 'failed'> {
+		let step: FileCleanupStep = 'rows_read_failed'
+		try {
+			const batch = await this.#formFiles.removable(SWEEP_BATCH, PENDING_GRACE_MS)
+			for (const file of batch) {
+				step = 'object_delete_failed'
+				await this.#store.delete(file.objectKey)
+				step = 'row_delete_failed'
+				await this.#formFiles.purge(file.id, PENDING_GRACE_MS)
+			}
+			return batch.length === SWEEP_BATCH ? 'more' : 'done'
+		} catch {
+			console.error(`fabrika: form files sweep: ${step}`)
+			return 'failed'
+		}
+	}
+
 	/**
 	 * The grant of `owner`: a `Ref` of the collection's owner, of the work running now, for one of the collection's
 	 * `actions`: `read` lists and opens, `delete` removes. A write capability alone reads no file's name or bytes.
@@ -322,12 +493,12 @@ export class FileCollections {
 	locating(database: ContractDatabase): ContractDatabase {
 		return {
 			tables: database.tables,
-			locate: (dimension, id) => {
+			locate: (dimension, id, using) => {
 				const collection = this.#byDimension.get(dimension)
 				if (collection === undefined) {
-					return database.locate(dimension, id)
+					return database.locate(dimension, id, using)
 				}
-				return UUID.test(id) ? collection.table.locate(id) : Promise.resolve(null)
+				return UUID.test(id) ? collection.table.locate(id, using) : Promise.resolve(null)
 			},
 		}
 	}
@@ -575,6 +746,14 @@ export class FileCollections {
 				failed.push(collection.name)
 			}
 		}
+		// A form's file nobody attached before its hold ended, or whose submission never committed.
+		let held: 'more' | 'done' | 'failed' = 'more'
+		while (held === 'more' && !signal.aborted) {
+			held = await this.#sweepFormFiles()
+		}
+		if (held === 'failed') {
+			failed.push('received by forms')
+		}
 		if (failed.length > 0) {
 			throw new ServerFault('file_sweep_failed', `the sweep of files ${failed.map((name) => `'${name}'`).join(', ')} failed; the next run retries it`)
 		}
@@ -665,5 +844,5 @@ export function fileCollections(
 			problems.push(error instanceof Error ? error.message : `files '${name}' cannot be served`)
 		}
 	}
-	return store === undefined ? null : new FileCollections(collections, store, capabilities, mint)
+	return store === undefined ? null : new FileCollections(collections, store, capabilities, mint, frameworkTablesOf(database).formFiles)
 }

package/src/files/handle.ts

@@ -62,7 +62,7 @@ export interface FileCollectionReader {
 }
 
 /** A site that writes also removes: a mutation, and a job inside `ctx.transaction`. */
-export interface FileCollectionHandle extends FileCollectionReader {
+export interface FileCollectionWriter extends FileCollectionReader {
 	/**
 	 * Marks every file of the owner removed, in this site's transaction, and answers how many; `owner` is a `Ref` for the
 	 * collection's `delete` action. The framework's sweep deletes their objects after the commit.
@@ -70,8 +70,27 @@ export interface FileCollectionHandle extends FileCollectionReader {
 	removeAll(owner: Ref<string, string>): Promise<number>
 }
 
+/** A mutation's handle: it writes, and attaches nothing, since only the job that drains a form's inbox does. */
+export type FileCollectionHandle = FileCollectionWriter & {
+	readonly attach: Unavailable<"only a job attaches a form's file, inside ctx.transaction((tx) => …), as tx.files">
+}
+
+/** A job's transaction also attaches the files a form received: the job that drains the form's inbox. */
+export interface FileCollectionJobHandle extends FileCollectionWriter {
+	/**
+	 * Attaches the file a form received under `id` (the id its inbox column holds) to `owner`, a `Ref` for the
+	 * collection's `write` action, in this site's transaction: the one that wrote the owner, located with `tx.ref`. A
+	 * scanning collection holds it `quarantined` until the scan job's verdict. `false` when no file of this collection
+	 * waits under the id (none was sent, or its hold of 7 days ended); `true` again for one this owner attached before.
+	 */
+	attach(owner: Ref<string, string>, id: string): Promise<boolean>
+}
+
 /** A site that only reads: a query, and a job outside `ctx.transaction`. */
-export type FileCollectionReadHandle<Why extends string> = FileCollectionReader & { readonly removeAll: Unavailable<Why> }
+export type FileCollectionReadHandle<Why extends string> = FileCollectionReader & {
+	readonly removeAll: Unavailable<Why>
+	readonly attach: Unavailable<Why>
+}
 
 /** `ctx.files(<collection>)`: the handle of one collection of the contract, by its name in `files`. */
 export type FileCollections<H> = (collection: string) => H

package/src/implement/anonymous.ts

@@ -6,15 +6,28 @@ import { LINK_BOOTSTRAP_FILE, SHARE_KEY_GLOBAL } from '../contract/defaults'
 import { HttpError } from '../errors'
 import { readBoundedBytes } from './bounded'
 
-/** The body as bytes, read until `maxBytes`; a longer one stops the read and is a 413. */
+/**
+ * The body as bytes, read until `maxBytes`; a longer one stops the read and is a 413. A body whose stream fails before
+ * its end (the client closed the connection) is the sender's 400 `aborted`, never a failure of the application.
+ */
 export async function readBoundedBody(request: Request, maxBytes: number): Promise<Uint8Array<ArrayBuffer>> {
-	const body = await readBoundedBytes(request.body, { maxBytes, declaredLength: request.headers.get('Content-Length') })
+	let body: Uint8Array<ArrayBuffer> | null
+	try {
+		body = await readBoundedBytes(request.body, { maxBytes, declaredLength: request.headers.get('Content-Length') })
+	} catch {
+		throw abortedBody()
+	}
 	if (body === null) {
 		throw new HttpError(413, 'too_large', `The body is larger than ${maxBytes} bytes`)
 	}
 	return body
 }
 
+/** What a request answers whose body did not arrive whole: nobody reads it, and no failure is reported. */
+export function abortedBody(): HttpError {
+	return new HttpError(400, 'aborted', 'The body could not be read to its end')
+}
+
 /**
  * Runs before any other script of the share SPA: it takes the key out of the fragment, removes the fragment from the
  * address with `history.replaceState`, and keeps the key in a closure. Telemetry that reads `location` later finds

package/src/implement/boot.ts

@@ -41,11 +41,11 @@ import type { FileObjectStore } from '@fabrika/platform'
 import { compileContract } from '../contract/compile'
 import { exportDescription } from '../contract/connect'
 import { isProcedure, type ProcedureDeclaration, type ProcedureTreeDeclaration, SURFACE_SECTIONS } from '../contract/declaration'
-import { exportBase, FORM_CHALLENGE_FIELD, FORM_LIMITS, spaPrefixRowId } from '../contract/defaults'
+import { exportBase, FORM_CHALLENGE_FIELD, FORM_FILE_LIMITS, FORM_LIMITS, spaPrefixRowId } from '../contract/defaults'
 import type { Schema } from '../contract/define'
 import { kitOriginOf } from '../contract/handled'
 import type { RequestExecutionContext } from '../fetch'
-import { FILE_SWEEP_JOB, FILE_SWEEP_SCHEDULE, FILE_SWEEP_TIMEOUT_MS, fileCollections } from '../files/collections'
+import { FILE_SWEEP_JOB, FILE_SWEEP_SCHEDULE, FILE_SWEEP_TIMEOUT_MS, type FileCollections, fileCollections } from '../files/collections'
 import { FILE_SCAN_JOB, FILE_SCAN_SCHEDULE, type FileScanner, SCAN_LIMITS } from '../files/scan'
 import { type MailStandIn, resolveMailTransports } from '../jobs/mail'
 import { logReporter, type OperationsReporter, operationsReporter, operationsSettings, type ReportSource } from '../jobs/report'
@@ -126,6 +126,8 @@ export interface BootOptions {
 	 * Turnstile's always-passing test widget hands out for every submission. Every other token stays single use.
 	 */
 	readonly repeatableChallengeToken?: string
+	/** How long a form's multipart body may take to arrive; `FORM_FILE_LIMITS.timeoutMs` unless a framework test shortens it. */
+	readonly formFileTimeoutMs?: number
 	/**
 	 * The developer's own machine only (`fabrika app dev`): what a job's handler threw, which every log of a deployed
 	 * application withholds because it may carry a credential.
@@ -518,7 +520,8 @@ function frameworkProblems(artifact: ContractArtifact, framework: FrameworkTable
 			const fields = (input?.type === 'object' ? Object.keys(input.fields) : []).filter((field) =>
 				field !== submitted.honeypot && !(submitted.challenge && field === FORM_CHALLENGE_FIELD)
 			)
-			problems.push(...framework.inboxProblems(name, fields))
+			// A file field's column receives the id of the file the submission carried.
+			problems.push(...framework.inboxProblems(name, [...fields, ...Object.keys(mount.files ?? {})]))
 		}
 	}
 }
@@ -535,11 +538,26 @@ function submissionFieldsOf(mount: FormMountArtifact): SubmissionFields {
  * A form's admission from its approved mount: the declared rate or the defaults, and a challenge verified with the
  * secret the application variable it names holds. Without that variable the application does not boot.
  */
-function formAdmission(name: string, artifact: ContractArtifact, options: BootOptions, problems: string[]): FormAdmission | null {
+function formAdmission(
+	name: string,
+	artifact: ContractArtifact,
+	options: BootOptions,
+	files: FileCollections | null,
+	problems: string[],
+): FormAdmission | null {
 	const mount = artifact.mounts[name]
 	if (mount?.kind !== 'form') {
 		return null
 	}
+	const fileFields = new Map(Object.entries(mount.files ?? {}))
+	for (const [field, file] of fileFields) {
+		if (files === null || !files.has(file.collection)) {
+			problems.push(`form '${name}' takes its file '${field}' into files '${file.collection}', which this runtime does not serve`)
+		}
+	}
+	if (fileFields.size > 0 && mount.challenge === undefined) {
+		problems.push(`form '${name}' takes files and declares no challenge; an anonymous upload needs a solved one`)
+	}
 	let challenge: ChallengeVerifier | null = null
 	if (mount.challenge !== undefined) {
 		const secret: unknown = options.environment.application[mount.challenge.secret]
@@ -553,8 +571,15 @@ function formAdmission(name: string, artifact: ContractArtifact, options: BootOp
 	}
 	return Object.freeze({
 		perClient: mount.rate?.perClient ?? FORM_LIMITS.perClient,
-		perForm: mount.rate?.perForm ?? FORM_LIMITS.perForm,
+		// A form with files accepts fewer submissions by default: each may write its collections' maxBytes.
+		perForm: mount.rate?.perForm ?? (fileFields.size === 0 ? FORM_LIMITS.perForm : FORM_FILE_LIMITS.perForm),
 		fields: Object.freeze(submissionFieldsOf(mount)),
+		files: fileFields.size === 0 || files === null ? null : {
+			fields: fileFields,
+			collections: files,
+			bytesPerHour: mount.rate?.bytesPerHour ?? FORM_FILE_LIMITS.bytesPerHour,
+			timeoutMs: options.formFileTimeoutMs ?? FORM_FILE_LIMITS.timeoutMs,
+		},
 		challenge,
 		repeatableToken: challenge === null ? null : (options.repeatableChallengeToken ?? null),
 	})
@@ -719,7 +744,7 @@ export function boot(app: ContractImplementation, options: BootOptions): Contrac
 			}
 		} else if (mount.kind === 'form') {
 			const row = rows.get(name)
-			const admission = formAdmission(name, artifact, options, problems)
+			const admission = formAdmission(name, artifact, options, files, problems)
 			const approved = artifact.mounts[name]
 			const then = approved?.kind === 'form' ? (approved.then ?? null) : null
 			if (row !== undefined && admission !== null) {