@fabrika/app 0.3.3 → 0.4.1

package/src/files/handle.ts

@@ -0,0 +1,77 @@
+// `ctx.files`: a handler's and a job's handle on the contract's file collections. Types only, so the browser-safe
+// contract can name them; `collections.ts` builds the handle. Every operation takes a `Ref` of the owner for one of the
+// collection's actions, so a file reaches what its owner reaches, as through the generated endpoints.
+
+import type { Unavailable } from '@fabrika/db/tables'
+import type { Ref } from '../implement/capability'
+
+/** A held file's state: served when `live`, `409` while `quarantined`, gone when `rejected`. */
+export type HeldFileStatus = 'live' | 'quarantined' | 'rejected'
+
+/** One file of an owner, as `list` answers it. */
+export interface ListedFile {
+	readonly id: string
+	/** The name the uploader gave it, metadata only. */
+	readonly name: string | null
+	/** The sniffed media type its bytes were checked against. */
+	readonly type: string
+	readonly size: number
+	readonly status: HeldFileStatus
+	readonly createdAt: Date
+}
+
+/** A page of an owner's files, oldest first; `next` is the `after` of the following page, `null` after the last. */
+export interface FileListing {
+	readonly items: readonly ListedFile[]
+	readonly next: string | null
+}
+
+export interface FileListPage {
+	/** The id of the last file of the previous page. */
+	readonly after?: string
+	/** 1–100, 50 by default. */
+	readonly limit?: number
+}
+
+/** A live file read whole: what an e-mail attaches. */
+export interface OpenedFile {
+	readonly id: string
+	readonly name: string | null
+	readonly type: string
+	readonly size: number
+	readonly bytes: Uint8Array
+}
+
+export interface OpenOptions {
+	/** The most bytes the caller holds in memory; a larger file is refused (413 `too_large`) before it is read. */
+	readonly maxBytes: number
+}
+
+/** What every site reaches of one collection: its owner's files. */
+export interface FileCollectionReader {
+	/**
+	 * The owner's held files, oldest first; `owner` is a `Ref` of the collection's owner for its `read` action. A
+	 * handler that must see the uploads holds that action.
+	 */
+	list(owner: Ref<string, string>, page?: FileListPage): Promise<FileListing>
+	/**
+	 * The live file `id` of the owner, read whole; `owner` is a `Ref` for the collection's `read` action. A file of
+	 * another owner, a rejected or a removed one is 404, a quarantined one 409 `quarantined`, one over `maxBytes` 413.
+	 */
+	open(owner: Ref<string, string>, id: string, options: OpenOptions): Promise<OpenedFile>
+}
+
+/** A site that writes also removes: a mutation, and a job inside `ctx.transaction`. */
+export interface FileCollectionHandle 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.
+	 */
+	removeAll(owner: Ref<string, string>): Promise<number>
+}
+
+/** A site that only reads: a query, and a job outside `ctx.transaction`. */
+export type FileCollectionReadHandle<Why extends string> = FileCollectionReader & { readonly removeAll: 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/files/scan.ts

@@ -0,0 +1,308 @@
+// The scan pass of `scan: true` collections: a framework job (`FILE_SCAN_JOB`) that takes a batch of quarantined files,
+// hands their objects to a `FileScanner`, and writes each verdict under the job's lease. It fails closed: a file goes
+// live only with a completed clean verdict over the exact bytes its upload recorded, and the download then serves only
+// that object version. An archive the scanner cannot read in full is rejected before it is scanned (`archive.ts`). No
+// scanner, a scanner error or a timeout leave files quarantined; a file that gets no verdict is retried later, alone,
+// and rejected after `SCAN_LIMITS.maxAttempts`. The scanner comes from the runtime adapter (`clamscan.ts` on Bun).
+
+import type { FileCollectionTable, QuarantinedFile } from '@fabrika/db/framework'
+import type { FileObjectStore } from '@fabrika/platform'
+import type { OperationsReporter } from '../jobs/report'
+import { type ArchiveRefusal, checkArchive } from './archive'
+import { ZIP_TYPES } from './sniff'
+
+/** The reserved name of the scan job: a `c.cron` job name cannot contain `-`, so no application job takes it. */
+export const FILE_SCAN_JOB = 'fabrika-file-scan'
+export const FILE_SCAN_SCHEDULE = '* * * * *'
+
+export const SCAN_LIMITS = {
+	/** One pass scans at most this many files, and at most `batchBytes` of them; the next pass takes the rest. */
+	batchFiles: 20,
+	batchBytes: 256 * 1024 * 1024,
+	/** The scanner's whole run — reading the objects, the scan, the cleanup — is stopped by then. */
+	scanTimeoutMs: 5 * 60_000,
+	/** The attempt's deadline; it outlasts the scanner's, so the verdicts are written before it. */
+	jobTimeoutMs: 10 * 60_000,
+	/** A file that got no verdict this many times is rejected. */
+	maxAttempts: 5,
+	/** The wait before the next try of a file without a verdict: doubled per try, at most `retryMaxMs`. */
+	retryBaseMs: 60_000,
+	retryMaxMs: 60 * 60_000,
+} as const
+
+/** What the scanner decided about one file. Only `clean` promotes; `infected` rejects; anything else is retried. */
+export type ScanVerdict = { readonly kind: 'clean' } | { readonly kind: 'infected'; readonly signature: string } | { readonly kind: 'unscanned' }
+
+/** Why a whole batch got no verdict. Fixed codes only: a scanner's own output is never reported. */
+export type ScanFailure =
+	| 'scanner_missing'
+	| 'signatures_missing'
+	| 'signatures_stale'
+	| 'scanner_failed'
+	| 'timeout'
+	| 'output_overflow'
+
+/** The failures of the scanner's own installation: no file is to blame, so none of them counts as a file's try. */
+const INSTALLATION_FAILURES: ReadonlySet<ScanFailure> = new Set(['scanner_missing', 'signatures_missing', 'signatures_stale'])
+
+export type ScanBatchResult =
+	| { readonly ok: true; readonly verdicts: ReadonlyMap<string, ScanVerdict> }
+	| { readonly ok: false; readonly failure: ScanFailure }
+
+export interface ScanObject {
+	/** The file's id: a UUID. */
+	readonly id: string
+	/**
+	 * The object's bytes. It throws when they are missing, differ from the upload's, are an archive the scanner cannot
+	 * read in full, or `signal` aborts.
+	 */
+	open(signal: AbortSignal): Promise<ReadableStream<Uint8Array>>
+}
+
+export interface FileScanner {
+	/**
+	 * A verdict per file id, or why the batch got none. A file whose `open` threw has no verdict. Stops once `signal`
+	 * aborts. Never throws.
+	 */
+	scan(objects: readonly ScanObject[], signal: AbortSignal): Promise<ScanBatchResult>
+}
+
+export interface ScanningCollection {
+	readonly name: string
+	readonly table: FileCollectionTable
+}
+
+interface Candidate {
+	readonly collection: ScanningCollection
+	readonly file: QuarantinedFile
+}
+
+/** How reading one file's object ended; only `verified` lets a clean verdict promote it, as that version. */
+type ReadState =
+	| { readonly kind: 'unread' }
+	| { readonly kind: 'verified'; readonly version: string }
+	| { readonly kind: 'missing' }
+	| { readonly kind: 'mismatch' }
+	| { readonly kind: 'unsafe'; readonly refusal: ArchiveRefusal }
+
+/** A signature name as Operations shows it: ClamAV's names are plain, anything else is not repeated. */
+function signatureName(signature: string): string {
+	return /^[A-Za-z0-9._:/-]{1,128}$/.test(signature) ? signature : 'unnamed'
+}
+
+const plural = (count: number, noun: string): string => `${count} ${noun}${count === 1 ? '' : 's'}`
+
+/** The next try of a file that has had `attempts` tries: one minute, doubled per try, at most an hour. */
+export function retryDelayMs(attempts: number): number {
+	return Math.min(SCAN_LIMITS.retryMaxMs, SCAN_LIMITS.retryBaseMs * 2 ** Math.max(0, attempts - 1))
+}
+
+/** The whole body, at most `size` bytes; the read stops, and the stream is cancelled, past it or on `signal`. */
+async function readExactly(body: ReadableStream<Uint8Array>, size: number, signal: AbortSignal): Promise<Uint8Array<ArrayBuffer> | null> {
+	const reader = body.getReader()
+	const aborted = new Promise<null>((resolve) => signal.addEventListener('abort', () => resolve(null), { once: true }))
+	const bytes = new Uint8Array(size)
+	let length = 0
+	try {
+		for (let next = await Promise.race([reader.read(), aborted]); next !== null && !next.done; next = await Promise.race([reader.read(), aborted])) {
+			if (length + next.value.byteLength > size) return null
+			bytes.set(next.value, length)
+			length += next.value.byteLength
+		}
+		return signal.aborted || length !== size ? null : bytes
+	} finally {
+		await reader.cancel().catch(() => undefined)
+	}
+}
+
+export interface ScanPassInput {
+	readonly collections: readonly ScanningCollection[]
+	readonly store: FileObjectStore
+	/** `null` when the runtime adapter supplies none: every quarantined file stays quarantined. */
+	readonly scanner: FileScanner | null
+	readonly reporter: OperationsReporter
+	readonly signal: AbortSignal
+	readonly now?: () => Date
+}
+
+/**
+ * The batch: the due files that waited longest first, across every scanning collection, so a busy collection or a
+ * stream of new uploads never holds back an older file. A file that has failed before is scanned alone, so it cannot
+ * take others down with it; new files go together, within the batch bounds.
+ */
+async function batch(collections: readonly ScanningCollection[], now: Date): Promise<Candidate[]> {
+	const due: Candidate[] = []
+	for (const collection of collections) {
+		for (const file of await collection.table.quarantined(SCAN_LIMITS.batchFiles, now)) due.push({ collection, file })
+	}
+	due.sort((left, right) => left.file.dueSince.getTime() - right.file.dueSince.getTime())
+	const [first] = due
+	if (first === undefined || first.file.scanAttempts > 0) return first === undefined ? [] : [first]
+	const candidates: Candidate[] = []
+	let bytes = 0
+	for (const candidate of due) {
+		const full = candidates.length >= SCAN_LIMITS.batchFiles || (candidates.length > 0 && bytes + candidate.file.size > SCAN_LIMITS.batchBytes)
+		if (full || candidate.file.scanAttempts > 0) break
+		candidates.push(candidate)
+		bytes += candidate.file.size
+	}
+	return candidates
+}
+
+function names(candidates: readonly Candidate[]): string {
+	return [...new Set(candidates.map((candidate) => `'${candidate.collection.name}'`))].join(', ')
+}
+
+class ScanPass {
+	readonly #input: ScanPassInput
+	readonly #states = new Map<string, ReadState>()
+	readonly #now: () => Date
+
+	constructor(input: ScanPassInput) {
+		this.#input = input
+		this.#now = input.now ?? (() => new Date())
+	}
+
+	/**
+	 * The object's bytes, read whole, checked against the upload's size and digest, and checked as an archive. Its
+	 * outcome is the file's read state; the bytes reach the scanner only when they are verified.
+	 */
+	async load(file: QuarantinedFile, signal: AbortSignal): Promise<Uint8Array<ArrayBuffer>> {
+		const object = await this.#input.store.read(file.objectKey, signal)
+		if (object === null) {
+			this.#states.set(file.id, { kind: 'missing' })
+			throw new Error('the object is missing')
+		}
+		const bytes = object.size === file.size ? await readExactly(object.body, file.size, signal) : null
+		if (object.size !== file.size) await object.body.cancel()
+		if (bytes === null || new Bun.CryptoHasher('sha256').update(bytes).digest('hex') !== file.sha256) {
+			if (!signal.aborted) this.#states.set(file.id, { kind: 'mismatch' })
+			throw new Error('the object differs from its upload')
+		}
+		const archive = checkArchive(bytes, ZIP_TYPES.includes(file.contentType))
+		if (!archive.ok) {
+			this.#states.set(file.id, { kind: 'unsafe', refusal: archive.refusal })
+			throw new Error('the scanner cannot read this archive in full')
+		}
+		this.#states.set(file.id, { kind: 'verified', version: object.version })
+		return bytes
+	}
+
+	async run(): Promise<void> {
+		const { scanner, signal } = this.#input
+		const candidates = await batch(this.#input.collections, this.#now())
+		if (candidates.length === 0) return
+		const none = new Map<string, ScanVerdict>()
+		if (scanner === null) {
+			console.error('fabrika: the file scan has no scanner; quarantined files stay quarantined')
+			await this.#failed('scanner_missing', candidates)
+			return
+		}
+		const objects = candidates.map(({ file }): ScanObject => ({
+			id: file.id,
+			open: async (stop) => new Blob([await this.load(file, stop)]).stream(),
+		}))
+		const result = await scanner.scan(objects, signal)
+		if (!result.ok) {
+			console.error(`fabrika: the file scan did not complete: ${result.failure}`)
+			await this.#failed(result.failure, candidates)
+			// A broken installation is no file's fault; a run that failed over its files counts a try for each.
+			return this.#settle(candidates, none, !INSTALLATION_FAILURES.has(result.failure))
+		}
+		await this.#settle(candidates, result.verdicts, true)
+	}
+
+	async #failed(failure: ScanFailure | 'delete_failed', files: readonly Candidate[]): Promise<void> {
+		await this.#input.reporter.report({
+			fingerprint: ['fabrika-file-scan-failed', failure],
+			type: 'FileScanFailed',
+			message: `the scan of ${plural(files.length, 'quarantined file')} of files ${names(files)} did not complete: ${failure}; they stay quarantined`,
+			tags: { code: failure },
+		})
+	}
+
+	/**
+	 * Each file's outcome, written under the lease; a write that fails throws, and the run fails with it. A file without
+	 * a decisive outcome is tried again later when `countTry`, and otherwise left as it is.
+	 */
+	async #settle(candidates: readonly Candidate[], verdicts: ReadonlyMap<string, ScanVerdict>, countTry: boolean): Promise<void> {
+		const unscanned: Candidate[] = []
+		for (const candidate of candidates) {
+			const { collection, file } = candidate
+			const state = this.#states.get(file.id) ?? { kind: 'unread' }
+			const verdict = verdicts.get(file.id) ?? { kind: 'unscanned' }
+			if (state.kind === 'missing') {
+				// Its object is gone: a rejection whose delete succeeded before its row was written, or a lost object.
+				await this.#reject(candidate, 'object_missing', `files '${collection.name}': file ${file.id} has no object to scan and is rejected`)
+			} else if (state.kind === 'unsafe') {
+				await this.#reject(candidate, `Fabrika.Archive.${state.refusal}`, `files '${collection.name}': file ${file.id} is rejected: ${state.refusal}`)
+			} else if (verdict.kind === 'infected') {
+				const signature = signatureName(verdict.signature)
+				await this.#reject(candidate, signature, `files '${collection.name}': file ${file.id} is rejected: ${signature}`)
+			} else if (state.kind === 'verified' && verdict.kind === 'clean') {
+				await collection.table.promote(file.id, file.sha256, state.version)
+			} else {
+				unscanned.push(candidate)
+			}
+		}
+		if (countTry) await this.#retryLater(unscanned)
+	}
+
+	/**
+	 * Deletes the object, then marks the row rejected. A failed delete leaves it quarantined, unserved, and waiting like
+	 * a retry, so the next try deletes it again and failing deletes never fill every batch.
+	 */
+	async #reject(candidate: Candidate, signature: string, message: string): Promise<void> {
+		const { collection, file } = candidate
+		try {
+			await this.#input.store.delete(file.objectKey)
+		} catch {
+			await this.#failed('delete_failed', [candidate])
+			const attempts = file.scanAttempts + 1
+			await collection.table.deferScan(file.id, attempts, new Date(this.#now().getTime() + retryDelayMs(attempts)))
+			return
+		}
+		await collection.table.reject(file.id)
+		await this.#input.reporter.report({
+			fingerprint: ['fabrika-file-rejected', collection.name],
+			type: 'FileRejected',
+			message,
+			tags: { collection: collection.name, file: file.id, signature },
+		})
+	}
+
+	/** A try without a verdict: the file waits, then is tried alone; past the last try it is rejected. */
+	async #retryLater(candidates: readonly Candidate[]): Promise<void> {
+		const counts = new Map<string, number>()
+		for (const candidate of candidates) {
+			const { collection, file } = candidate
+			const attempts = file.scanAttempts + 1
+			if (attempts >= SCAN_LIMITS.maxAttempts) {
+				await this.#reject(
+					candidate,
+					'Fabrika.Unscannable',
+					`files '${collection.name}': file ${file.id} got no verdict in ${plural(attempts, 'attempt')} and is rejected`,
+				)
+				continue
+			}
+			await collection.table.deferScan(file.id, attempts, new Date(this.#now().getTime() + retryDelayMs(attempts)))
+			counts.set(collection.name, (counts.get(collection.name) ?? 0) + 1)
+		}
+		for (const [collection, count] of counts) {
+			await this.#input.reporter.report({
+				fingerprint: ['fabrika-file-unscanned', collection],
+				type: 'FileUnscanned',
+				message: `files '${collection}': ${plural(count, 'file')} got no clean verdict; each is tried again later, alone`,
+				tags: { collection },
+			})
+		}
+	}
+}
+
+/**
+ * One pass. A verdict write that fails (the lease lost, the database gone) throws, so the runner reports the run as
+ * failed; everything the scanner decides is reported here and never throws.
+ */
+export function runScanPass(input: ScanPassInput): Promise<void> {
+	return new ScanPass(input).run()
+}

package/src/files/sniff.ts

@@ -0,0 +1,70 @@
+// The type of an upload, read from its first bytes. The request's `Content-Type` only says what the client claims;
+// a file is stored only when its bytes are that type. A collection may admit only the types listed here, because
+// the framework cannot verify any other.
+
+/** How many leading bytes an upload is judged by. */
+export const SNIFF_BYTES = 512
+
+interface Signature {
+	readonly types: readonly string[]
+	matches(head: Uint8Array): boolean
+}
+
+function bytesAt(head: Uint8Array, offset: number, expected: readonly number[]): boolean {
+	return head.byteLength >= offset + expected.length && expected.every((byte, index) => head[offset + index] === byte)
+}
+
+function asciiAt(head: Uint8Array, offset: number, text: string): boolean {
+	return bytesAt(head, offset, [...text].map((char) => char.charCodeAt(0)))
+}
+
+const ZIP = [0x50, 0x4b, 0x03, 0x04]
+
+/** The ZIP-based types: a ZIP archive, and an Office Open XML document, which is one. */
+export const ZIP_TYPES: readonly string[] = [
+	'application/zip',
+	'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+	'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+	'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+]
+
+const BINARY_SIGNATURES: readonly Signature[] = [
+	{ types: ['image/png'], matches: (head) => bytesAt(head, 0, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]) },
+	{ types: ['image/jpeg'], matches: (head) => bytesAt(head, 0, [0xff, 0xd8, 0xff]) },
+	{ types: ['image/gif'], matches: (head) => asciiAt(head, 0, 'GIF87a') || asciiAt(head, 0, 'GIF89a') },
+	{ types: ['image/webp'], matches: (head) => asciiAt(head, 0, 'RIFF') && asciiAt(head, 8, 'WEBP') },
+	{ types: ['application/pdf'], matches: (head) => asciiAt(head, 0, '%PDF-') },
+	{ types: ['application/gzip'], matches: (head) => bytesAt(head, 0, [0x1f, 0x8b]) },
+	{
+		// An Office Open XML document is a zip archive; its bytes cannot tell it from any other.
+		types: ZIP_TYPES,
+		matches: (head) => bytesAt(head, 0, ZIP),
+	},
+]
+
+/** Types judged as text: UTF-8 without NUL bytes, and no binary signature. SVG is text, and always an attachment. */
+const TEXT_TYPES: readonly string[] = ['text/plain', 'text/csv', 'text/markdown', 'application/json', 'image/svg+xml']
+
+export const SNIFFABLE_TYPES: readonly string[] = [...BINARY_SIGNATURES.flatMap((signature) => signature.types), ...TEXT_TYPES]
+
+function isText(head: Uint8Array): boolean {
+	if (head.includes(0) || BINARY_SIGNATURES.some((signature) => signature.matches(head))) {
+		return false
+	}
+	try {
+		// `stream: true` tolerates a character the sniff window cut in half.
+		new TextDecoder('utf-8', { fatal: true }).decode(head, { stream: true })
+		return true
+	} catch {
+		return false
+	}
+}
+
+/** Whether the first bytes of an upload are of `type`; always false for a type the framework cannot verify. */
+export function bytesAreOfType(type: string, head: Uint8Array): boolean {
+	const signature = BINARY_SIGNATURES.find((candidate) => candidate.types.includes(type))
+	if (signature !== undefined) {
+		return signature.matches(head)
+	}
+	return TEXT_TYPES.includes(type) && isText(head)
+}

package/src/files/treatment.ts

@@ -0,0 +1,48 @@
+// The file treatment (ADR-0022 rule 2): the header policy a download carries instead of the application's. Only
+// the inert images are shown inline; every other type, SVG and HTML included, is an attachment, and nothing a
+// download contains can run as this origin. The proxy applies the same definition, from `@fabrika/proxy-core/headers`.
+
+import { applyFileTreatment, fileDisposition, withResponseHeaders } from '@fabrika/proxy-core/headers'
+
+/** A file the download endpoint answers. `ContractRuntime` turns it into the response, with the file treatment. */
+export class FileDownload {
+	readonly body: ReadableStream<Uint8Array>
+	readonly size: number
+	/** The type recorded at upload, which its bytes were checked against; never a type a request sent. */
+	readonly contentType: string
+	readonly name: string | null
+
+	constructor(file: { readonly body: ReadableStream<Uint8Array>; readonly size: number; readonly contentType: string; readonly name: string | null }) {
+		this.body = file.body
+		this.size = file.size
+		this.contentType = file.contentType
+		this.name = file.name
+	}
+}
+
+/** `filename*` per RFC 8187: percent-encoded UTF-8, so no name can end the header or add a parameter. */
+function filenameParameter(name: string): string {
+	const encoded = encodeURIComponent(name).replace(/['()*]/g, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`)
+	return `; filename*=UTF-8''${encoded}`
+}
+
+export function contentDisposition(contentType: string, name: string | null): string {
+	return `${fileDisposition(contentType)}${name === null ? '' : filenameParameter(name)}`
+}
+
+export function fileResponse(file: FileDownload): Response {
+	const headers = new Headers({
+		'Content-Type': file.contentType,
+		'Content-Length': String(file.size),
+		'Content-Disposition': contentDisposition(file.contentType, file.name),
+		// A Range request gets the whole file: ignoring Range is always a valid answer, and no partial path exists to get wrong.
+		'Accept-Ranges': 'none',
+	})
+	applyFileTreatment(headers)
+	return new Response(file.body, { status: 200, headers })
+}
+
+/** An error of a download endpoint, with the file treatment in place of the header policy. */
+export function withFileTreatment(response: Response): Response {
+	return withResponseHeaders(response, applyFileTreatment)
+}

package/src/from-row.ts

@@ -0,0 +1,53 @@
+// `fromRow(Schema, row)`: a database row as an endpoint's output object; `fromPage(Schema, page)` maps a list's page.
+// The row's snake_case columns become the schema's camelCase fields, a `Date` becomes its ISO text (its day for a
+// `z.iso.date()` field), every column the schema does not declare is dropped, and the schema parses what is left — so a
+// literal-string field the row types as plain text is checked, not trusted. A `date` column already arrives as
+// `YYYY-MM-DD` text from the data layer.
+
+import { z } from 'zod/v4'
+import { project } from './implement/project'
+
+/** `companyId` → `company_id`: the column a field is read from. */
+export type Snake<S extends string> = S extends `${infer Head}${infer Tail}`
+	? `${Head extends Lowercase<Head> ? Head : `_${Lowercase<Head>}`}${Snake<Tail>}`
+	: S
+
+/** A row value a field accepts: text for a literal string (the schema checks it), a `Date` for ISO text. */
+type Widened<V> = V extends string ? string | Date : V
+
+/** The row `fromRow` takes for `S`: one column per declared field; any other column is allowed and dropped. */
+export type RowInput<S extends z.ZodObject> = { readonly [K in keyof z.input<S> as Snake<K & string>]: Widened<z.input<S>[K]> }
+
+function camel(column: string): string {
+	return column.replace(/_([a-z0-9])/g, (_match, next: string) => next.toUpperCase())
+}
+
+/**
+ * A `Date` as its field reads it: the day (`YYYY-MM-DD`, in UTC, as the data layer reads a `date` column) for a
+ * `z.iso.date()` field, ISO 8601 text otherwise.
+ */
+function dateText(schema: z.ZodObject, field: string, value: Date): string {
+	let declared: z.core.$ZodType | undefined = Object.hasOwn(schema.shape, field) ? schema.shape[field] : undefined
+	while (declared instanceof z.ZodOptional || declared instanceof z.ZodNullable || declared instanceof z.ZodDefault) {
+		declared = declared.unwrap()
+	}
+	return declared instanceof z.ZodISODate ? value.toISOString().slice(0, 10) : value.toISOString()
+}
+
+/** The row as `schema`'s output; a row the schema refuses throws, as a handler's bug. */
+export function fromRow<const S extends z.ZodObject>(schema: S, row: RowInput<S>): z.output<S> {
+	const fields: Record<string, unknown> = {}
+	for (const [column, value] of Object.entries(row)) {
+		const field = camel(column)
+		Object.defineProperty(fields, field, { value: value instanceof Date ? dateText(schema, field, value) : value, enumerable: true })
+	}
+	return z.parse(schema, project(schema, fields))
+}
+
+/** A list's page as a page output: each row through `fromRow`, and `next` as the list answered it. */
+export function fromPage<const S extends z.ZodObject>(
+	schema: S,
+	page: { readonly items: readonly RowInput<S>[]; readonly next: string | null },
+): { items: z.output<S>[]; next: string | null } {
+	return { items: page.items.map((row) => fromRow(schema, row)), next: page.next }
+}

package/src/implement/anonymous.ts

@@ -0,0 +1,102 @@
+// What the anonymous kinds need beyond the request pipeline: a body read under its limit (the proxy never sees a
+// body, so the framework enforces it), the share SPA's fragment bootstrap and GitHub's delivery signature. A form's
+// admission is `form-admission.ts`.
+
+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. */
+export async function readBoundedBody(request: Request, maxBytes: number): Promise<Uint8Array<ArrayBuffer>> {
+	const body = await readBoundedBytes(request.body, { maxBytes, declaredLength: request.headers.get('Content-Length') })
+	if (body === null) {
+		throw new HttpError(413, 'too_large', `The body is larger than ${maxBytes} bytes`)
+	}
+	return body
+}
+
+/**
+ * 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
+ * no key; the SPA reads it through `shareKey()` of `@fabrika/app/client`.
+ */
+export const LINK_BOOTSTRAP_SCRIPT = `(function () {
+	var fragment = window.location.hash.slice(1)
+	var key = /^px_[A-Za-z0-9_-]+$/.test(fragment) ? fragment : null
+	if (window.location.hash !== '') {
+		window.history.replaceState(window.history.state, '', window.location.pathname + window.location.search)
+	}
+	Object.defineProperty(window, '${SHARE_KEY_GLOBAL}', {
+		value: function () {
+			return key
+		},
+		writable: false,
+		configurable: false,
+		enumerable: false,
+	})
+})()
+`
+
+/** The share SPA's bootstrap path under the link prefix. */
+export function bootstrapPath(prefix: string): string {
+	return `${prefix}/${LINK_BOOTSTRAP_FILE}`
+}
+
+export function bootstrapResponse(): Response {
+	return new Response(LINK_BOOTSTRAP_SCRIPT, { status: 200, headers: { 'Content-Type': 'text/javascript; charset=utf-8' } })
+}
+
+/**
+ * The share SPA's document with the bootstrap as its first script: right after `<head>`, so it runs before every
+ * module script and every script the document loads. A response that is not HTML passes unchanged.
+ */
+export async function withBootstrap(response: Response, prefix: string): Promise<Response> {
+	const type = response.headers.get('Content-Type')?.split(';')[0]?.trim().toLowerCase()
+	if (type !== 'text/html') {
+		return response
+	}
+	const html = await response.text()
+	const tag = `<script src="${bootstrapPath(prefix)}"></script>`
+	const head = /<head(?:\s[^>]*)?>/i.exec(html)
+	const injected = head === null ? `${tag}${html}` : `${html.slice(0, head.index + head[0].length)}${tag}${html.slice(head.index + head[0].length)}`
+	const headers = new Headers(response.headers)
+	headers.delete('Content-Length')
+	return new Response(injected, { status: response.status, statusText: response.statusText, headers })
+}
+
+const SIGNATURE_PREFIX = 'sha256='
+const HEX = /^[0-9a-f]{64}$/
+
+/** Whether `X-Hub-Signature-256` is GitHub's HMAC-SHA256 of the raw body under `secret`, compared in constant time. */
+export async function verifyGithubSignature(header: string | null, secret: string, body: Uint8Array<ArrayBuffer>): Promise<boolean> {
+	if (header === null || !header.startsWith(SIGNATURE_PREFIX)) {
+		return false
+	}
+	const hex = header.slice(SIGNATURE_PREFIX.length).toLowerCase()
+	if (!HEX.test(hex)) {
+		return false
+	}
+	const signature = new Uint8Array(32)
+	for (let index = 0; index < 32; index++) {
+		signature[index] = Number.parseInt(hex.slice(index * 2, index * 2 + 2), 16)
+	}
+	const key = await crypto.subtle.importKey('raw', new TextEncoder().encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['verify'])
+	return crypto.subtle.verify('HMAC', key, signature, body)
+}
+
+/** The GitHub account a payload names, as a binding records it: `installation:<id>` or `repository:<id>`. */
+export function githubAccounts(payload: unknown): readonly string[] {
+	const accounts: string[] = []
+	for (const kind of ['installation', 'repository'] as const) {
+		const holder = ownField(payload, kind)
+		const id = ownField(holder, 'id')
+		if (typeof id === 'number' && Number.isSafeInteger(id) && id > 0) {
+			accounts.push(`${kind}:${id}`)
+		}
+	}
+	return accounts
+}
+
+function ownField(value: unknown, name: string): unknown {
+	return typeof value === 'object' && value !== null && Object.hasOwn(value, name) ? Reflect.get(value, name) : undefined
+}