@fabrika/app 0.3.3 → 0.4.0

package/src/bun.ts

@@ -1,9 +1,30 @@
 // ─── Bun process adapter ─────────────────────────────────────────────
 //
 // A long-running Bun process needs only request dispatch and explicit draining.
-// It does not emulate Worker cron, queues, or passThroughOnException().
+// It does not emulate Worker cron, queues, or passThroughOnException(). A
+// contract application is served through `serveContract`, from the generated
+// entrypoint.
 
-import type { FabrikaApp, RequestExecutionContext } from './app.js'
+import { HttpIamMembership } from '@fabrika/auth'
+import type { Database, PostgresOptions } from '@fabrika/db'
+import { isScopedDatabase } from '@fabrika/db/framework'
+import { parseJwks } from '@fabrika/jwks'
+import type { FileObjectStore } from '@fabrika/platform'
+import { applicationRuntimeUrl, S3BlobStore } from '@fabrika/platform-node'
+import { diskAssets } from './disk-assets.js'
+import type { FetchService, RequestExecutionContext } from './fetch.js'
+import { clamscanScanner } from './files/clamscan.js'
+import { boot, BootError, type IamKeySource } from './implement/boot.js'
+import { captureEnvironment } from './implement/environment.js'
+import { type ContractImplementation, isContractImplementation } from './implement/implement.js'
+import { issuerWorkloadTokens, type WorkloadTokenSource } from './implement/workload.js'
+import { JOB_CHECK_INTERVAL_MS, type JobRunOptions, type JobRunResult } from './jobs/runner.js'
+import { makeProcessUndumpable } from './undumpable.js'
+
+export { diskAssets } from './disk-assets.js'
+export { clamscanArguments, type ClamscanOptions, clamscanScanner } from './files/clamscan.js'
+
+export { markProductionProcess } from '@fabrika/db/production'
 
 export interface ManagedBunHandlerOptions {
 	/** Required sink for rejected background tasks. Do not log raw errors or secret-bearing values. */
@@ -25,7 +46,7 @@ export interface BunHandler {
 	drain(): Promise<void>
 }
 
-export function createBunHandler<Env>(app: FabrikaApp<Env>, env: Env, options: BunHandlerOptions): BunHandler {
+export function createBunHandler<Env>(app: FetchService<Env>, env: Env, options: BunHandlerOptions): BunHandler {
 	if (options.executionContext !== undefined) {
 		return {
 			fetch: (request) => app.fetch(request, env, options.executionContext),
@@ -61,3 +82,281 @@ export function createBunHandler<Env>(app: FabrikaApp<Env>, env: Env, options: B
 		},
 	}
 }
+
+// ─── Contract applications ───────────────────────────────────────────
+
+/** IAM's public key set at the issuer's `/.well-known/jwks.json`, for a process with no IAM binding. */
+export function issuerJwks(issuer: unknown): IamKeySource {
+	return {
+		async getJwks() {
+			if (typeof issuer !== 'string') {
+				throw new Error('FABRIKA_IAM_ISSUER is not set')
+			}
+			const response = await fetch(new URL('/.well-known/jwks.json', issuer), { headers: { accept: 'application/json' } })
+			const jwks = response.ok ? parseJwks(await response.json()) : null
+			if (jwks === null) {
+				throw new Error('the issuer published no usable key set')
+			}
+			return jwks
+		},
+	}
+}
+
+export interface ContractServer {
+	/** The port the server listens on; `PORT=0` picks a free one. */
+	readonly port: number
+	/** Stops accepting requests and waits for the ones in flight. */
+	stop(): Promise<void>
+}
+
+/**
+ * What the adapter takes from `@fabrika/db` before the application loads, so no application module can stand in for
+ * it: a replaced `Database.postgres` would receive the database URL.
+ */
+interface DataLayerOpeners {
+	readonly postgres: (options: PostgresOptions) => Database
+	readonly applicationSchema: (appId: string) => string
+}
+
+/** Loads `@fabrika/db` before the application: it captures its built-ins and freezes the Kysely compiler at load. */
+async function loadDataLayer(): Promise<DataLayerOpeners> {
+	const { Database, applicationSchema } = await import('@fabrika/db')
+	return { postgres: Database.postgres, applicationSchema }
+}
+
+/** The provisioning credential the platform writes; only the launcher reads it, and the application's process never holds it. */
+const PROVISIONING_DATABASE_URL = 'FABRIKA_APP_DATABASE_URL'
+/** The runtime role's credential, which the launcher derives and hands the application's process in its place. */
+const RUNTIME_DATABASE_URL = 'FABRIKA_APP_RUNTIME_DATABASE_URL'
+
+/**
+ * The application's connection: its runtime role `run_<FABRIKA_APP_ID>`, whose URL the launcher derived from the
+ * provisioning credential, on the schema `app_<FABRIKA_APP_ID>` its migrations created. A URL is a credential, so no
+ * message quotes it.
+ */
+function openApplicationDatabase(data: DataLayerOpeners, framework: Readonly<Record<string, string>>): Database {
+	const url = framework[RUNTIME_DATABASE_URL] ?? ''
+	const appId = framework['FABRIKA_APP_ID'] ?? ''
+	const problems: string[] = []
+	if (url.trim() === '') {
+		problems.push('FABRIKA_APP_DATABASE_URL is not set; the platform writes it for an application with a database')
+	}
+	let schema = ''
+	try {
+		schema = data.applicationSchema(appId)
+	} catch {
+		problems.push(`FABRIKA_APP_ID '${appId}' is not an application id (allowed: lowercase letters, digits and -, at most 59)`)
+	}
+	if (problems.length > 0) {
+		throw new BootError(problems)
+	}
+	return data.postgres({ url, schema })
+}
+
+/**
+ * Whether this process holds the provisioning credential: then it is the launcher, and the application never runs in
+ * it. The application's process gets the runtime credential instead.
+ */
+function holdsProvisioningCredential(env: Readonly<Record<string, string | undefined>>): boolean {
+	return (env[PROVISIONING_DATABASE_URL] ?? '') !== ''
+}
+
+const FORWARDED_SIGNALS = ['SIGTERM', 'SIGINT', 'SIGHUP'] as const
+
+/**
+ * The launcher: before any application module loads, derives the runtime role's credential from the provisioning one
+ * and runs this same command again with an environment that carries the runtime credential and not the provisioning
+ * one, so neither the application's process nor anything it spawns can read the latter, `/proc/self/environ`
+ * included; the launcher makes itself non-dumpable first, so its own `/proc/<pid>/environ` is not readable either. Stdio is inherited, signals are forwarded, and the child's exit becomes this process's.
+ */
+async function relaunchAsRuntime(env: Readonly<Record<string, string | undefined>>): Promise<never> {
+	let runtimeUrl: string
+	try {
+		runtimeUrl = applicationRuntimeUrl(env[PROVISIONING_DATABASE_URL] ?? '', env['FABRIKA_APP_ID'] ?? '')
+	} catch {
+		throw new BootError([
+			'FABRIKA_APP_DATABASE_URL is not a connection URL with a password, or FABRIKA_APP_ID is not an application id; the runtime role derives its credential from both',
+		])
+	}
+	const environment: Record<string, string> = {}
+	for (const [name, value] of Object.entries(env)) {
+		if (value !== undefined && name !== PROVISIONING_DATABASE_URL) environment[name] = value
+	}
+	environment[RUNTIME_DATABASE_URL] = runtimeUrl
+	// Otherwise the application could read this process's environment, the provisioning credential in it, through /proc.
+	makeProcessUndumpable()
+	const child = Bun.spawn([process.execPath, ...process.execArgv, ...process.argv.slice(1)], {
+		env: environment,
+		stdin: 'inherit',
+		stdout: 'inherit',
+		stderr: 'inherit',
+	})
+	for (const signal of FORWARDED_SIGNALS) {
+		process.on(signal, () => child.kill(signal))
+	}
+	await child.exited
+	if (child.signalCode !== null) {
+		for (const signal of FORWARDED_SIGNALS) process.removeAllListeners(signal)
+		process.kill(process.pid, child.signalCode)
+	}
+	process.exit(child.exitCode ?? 1)
+}
+
+const STORAGE_VARIABLES = {
+	endpoint: 'FABRIKA_APP_STORAGE_ENDPOINT',
+	bucket: 'FABRIKA_APP_STORAGE_BUCKET',
+	accessKeyId: 'FABRIKA_APP_STORAGE_ACCESS_KEY_ID',
+	secretAccessKey: 'FABRIKA_APP_STORAGE_SECRET_ACCESS_KEY',
+} as const
+
+/**
+ * The file collections' object storage (Zerops object storage, path-style), when the platform wrote its variables;
+ * a partial set stops the boot. The credentials are never quoted in a message.
+ */
+export function openFileStorage(framework: Readonly<Record<string, string>>): FileObjectStore | undefined {
+	const value = (name: string) => framework[name]?.trim() ?? ''
+	const names = Object.values(STORAGE_VARIABLES)
+	const missing = names.filter((name) => value(name) === '')
+	if (missing.length === names.length) {
+		return undefined
+	}
+	if (missing.length > 0) {
+		throw new BootError(missing.map((name) => `${name} is not set; the platform writes every FABRIKA_APP_STORAGE_* variable together`))
+	}
+	return S3BlobStore.connect({
+		endpoint: value(STORAGE_VARIABLES.endpoint),
+		bucket: value(STORAGE_VARIABLES.bucket),
+		accessKeyId: value(STORAGE_VARIABLES.accessKeyId),
+		secretAccessKey: value(STORAGE_VARIABLES.secretAccessKey),
+		region: 'us-east-1',
+		virtualHostedStyle: false,
+	})
+}
+
+/**
+ * IAM's membership transport, when the platform gives the process `FABRIKA_IAM_RPC_URL` (IAM's public origin) and
+ * `FABRIKA_IAM_RPC_KEY` (this environment's membership transport key); without both, there is none, and `boot` refuses
+ * a contract that needs one.
+ */
+function httpMembership(framework: Readonly<Record<string, string>>): HttpIamMembership | undefined {
+	const origin = framework['FABRIKA_IAM_RPC_URL']?.trim() ?? ''
+	const key = framework['FABRIKA_IAM_RPC_KEY']?.trim() ?? ''
+	return origin === '' || key === '' ? undefined : new HttpIamMembership({ origin, key })
+}
+
+/** IAM's public token exchange, at the issuer every deploy names; `boot` reports a missing issuer itself. */
+function workloadTokensOf(framework: Readonly<Record<string, string>>): WorkloadTokenSource | undefined {
+	const issuer = framework['FABRIKA_IAM_ISSUER']?.trim() ?? ''
+	return issuer === '' ? undefined : issuerWorkloadTokens(issuer)
+}
+
+/** The application module, imported only after the environment was captured: the generated entrypoint's `import()`. */
+export type ImplementationLoader = () => Promise<{ readonly default: ContractImplementation }>
+
+/**
+ * Captures the framework's variables and scrubs them from the process, then imports the application, boots it and
+ * serves it on `PORT` (default 3000), on every interface: the project's private network is how the proxy reaches
+ * it. Called only by the generated entrypoint, with `process.env`. SIGTERM drains. Given the provisioning credential,
+ * it is the launcher instead: it never loads the application and re-runs the entrypoint as the runtime role.
+ */
+export async function serveContract(load: ImplementationLoader, env: Readonly<Record<string, string | undefined>>): Promise<ContractServer> {
+	if (holdsProvisioningCredential(env)) {
+		return relaunchAsRuntime(env)
+	}
+	const environment = captureEnvironment(env)
+	const port = Number.parseInt(environment.application['PORT'] === undefined ? '3000' : String(environment.application['PORT']), 10)
+	if (!Number.isInteger(port) || port < 0 || port > 65535) {
+		throw new Error('PORT must be an integer between 0 and 65535')
+	}
+	const data = await loadDataLayer()
+	const { default: app } = await load()
+	const iam = issuerJwks(environment.framework['FABRIKA_IAM_ISSUER'])
+	const database = isScopedDatabase(app.database) ? openApplicationDatabase(data, environment.framework) : undefined
+	const membership = httpMembership(environment.framework)
+	// Zerops is where a Bun application runs, and a namespace there is one private network (ADR-0022 rule 5).
+	const files = openFileStorage(environment.framework)
+	const workloadTokens = workloadTokensOf(environment.framework)
+	const served = boot(app, {
+		environment,
+		iam,
+		assets: diskAssets(process.cwd()),
+		database,
+		files,
+		membership,
+		workloadTokens,
+		requireProxySecret: true,
+	})
+	// The work a request leaves running (a failure's report, a job a form kicked) is drained before the database closes.
+	const handler = createBunHandler({ fetch: (request, _env: undefined, exec) => served.fetch(request, exec) }, undefined, {
+		onBackgroundError: () => console.error('fabrika: a background task of a request failed'),
+	})
+	const server = Bun.serve({ port, hostname: '0.0.0.0', fetch: (request) => handler.fetch(request) })
+	// The crontab may never fire; the serving process notices a job that stopped succeeding without being invoked.
+	const check = () => void served.jobs.check()
+	const checks = served.jobs.names.length === 0 ? undefined : setInterval(check, JOB_CHECK_INTERVAL_MS)
+	if (checks !== undefined) {
+		check()
+	}
+	const stop = async (): Promise<void> => {
+		clearInterval(checks)
+		await server.stop(false)
+		await handler.drain()
+		await database?.close()
+	}
+	process.once('SIGTERM', () => void stop().then(() => process.exit(0)))
+	return { port: server.port ?? port, stop }
+}
+
+/** The application module at `path`, imported when the loader runs; its default export must be what `serve` returned. */
+export function implementationAt(path: string): ImplementationLoader {
+	return async () => {
+		const module: unknown = await import(path)
+		const value = typeof module === 'object' && module !== null ? Reflect.get(module, 'default') : undefined
+		if (!isContractImplementation(value)) {
+			throw new BootError([`${path} does not default-export serve(contract, { … })`])
+		}
+		return { default: value }
+	}
+}
+
+/**
+ * One run of the job `name` (`fabrika job run <name>`, the crontab's command): the framework's variables are captured
+ * and scrubbed before the application loads, exactly as `serveContract` does, then `boot` binds the job and the run
+ * takes its lease. The connection closes when the run ends. Given the provisioning credential, it re-runs the command
+ * as the runtime role, as `serveContract` does.
+ */
+export async function runContractJob(
+	load: ImplementationLoader,
+	env: Readonly<Record<string, string | undefined>>,
+	name: string,
+	options: JobRunOptions = {},
+): Promise<JobRunResult> {
+	if (holdsProvisioningCredential(env)) {
+		return relaunchAsRuntime(env)
+	}
+	const environment = captureEnvironment(env)
+	const data = await loadDataLayer()
+	const { default: app } = await load()
+	const iam = issuerJwks(environment.framework['FABRIKA_IAM_ISSUER'])
+	const database = isScopedDatabase(app.database) ? openApplicationDatabase(data, environment.framework) : undefined
+	try {
+		const workloadTokens = workloadTokensOf(environment.framework)
+		const membership = httpMembership(environment.framework)
+		const files = openFileStorage(environment.framework)
+		return await boot(app, {
+			environment,
+			iam,
+			assets: diskAssets(process.cwd()),
+			database,
+			files,
+			membership,
+			workloadTokens,
+			requireProxySecret: true,
+			// ClamAV on PATH, as the provider's build installs it for a `scan: true` collection; missing, the scan fails closed.
+			scanner: clamscanScanner(),
+		})
+			.jobs.run(name, options)
+	} finally {
+		await database?.close()
+	}
+}

package/src/client/caller.ts

@@ -0,0 +1,24 @@
+// The caller document every SPA mount serves at `<prefix>/__fabrika-me.json`: who the page's person is and what the
+// token says they hold. A page shows and hides by it; it decides nothing, because every endpoint checks again.
+
+import { z } from 'zod/v4'
+
+const ScopedActions = z.strictObject({ type: z.string(), value: z.string(), actions: z.array(z.string()) })
+
+const PageCallerSchema = z.strictObject({
+	label: z.string(),
+	email: z.string(),
+	actions: z.strictObject({
+		/** The actions held as a global grant, so in every value. */
+		app: z.array(z.string()),
+		/** Each scope value the person holds something in, with those actions; sorted by dimension, then value. */
+		scopes: z.array(ScopedActions),
+	}),
+})
+
+export type PageCaller = z.infer<typeof PageCallerSchema>
+
+/** The caller document as the framework answers it; throws on any other value. */
+export function parsePageCaller(value: unknown): PageCaller {
+	return PageCallerSchema.parse(value)
+}

package/src/client/contract.ts

@@ -0,0 +1,309 @@
+// The typed client of one contract mount: `api.notes.remove({ id })` POSTs the input to `/api/notes.remove`, the
+// path `compileContract` gives that procedure. Built from the contract value, so it can call only declared
+// procedures, and it checks each answer against the procedure's output schema before handing it out. An attachment
+// procedure answers a file, which `download(api.<procedure>, input)` fetches and saves.
+
+import { z } from 'zod/v4'
+import { type AttachmentBrand, attachmentOf } from '../contract/attachment'
+import { isProcedure, type ProcedureTreeDeclaration, type ProcedureType, SURFACE_SECTIONS } from '../contract/declaration'
+import { joinPath, LINK_API_SEGMENT } from '../contract/defaults'
+import type { AnyContract, InputSchema, Procedure, Schema, Surface } from '../contract/define'
+import { type FileClient, type FileTransport, type LinkCollections, type LinkFileClient, linkFiles, sessionFiles } from './files'
+import { type BounceConfig, type BounceOption, exchange, exchangeFile, resolveBounce, RpcError, type RpcFetch } from './transport'
+
+type SurfaceOf<C> = C extends { readonly surface: infer S } ? S : never
+
+/** The mounts a client calls: RPC mounts and link mounts. */
+export type ClientMount<C> =
+	& { [M in keyof SurfaceOf<C>]: SurfaceOf<C>[M] extends { readonly kind: 'rpc' | 'link' } ? M : never }[keyof SurfaceOf<C>]
+	& string
+
+/**
+ * One procedure: its input as the caller writes it (defaults optional), its output as parsed, and the output schema
+ * it parses with (`@fabrika/app/react` reads a cached answer back through it).
+ */
+export type ProcedureCall<I, O extends Schema> =
+	& ([I] extends [InputSchema] ? (input: z.input<I>) => Promise<z.output<O>> : (input?: Record<never, never>) => Promise<z.output<O>>)
+	& { readonly output: O }
+
+export type ClientTree<T> = {
+	readonly [K in keyof T]: T[K] extends Procedure<'query' | 'mutation', infer I, infer O, unknown>
+		? O extends AttachmentBrand ? AttachmentProcedure<I> : ProcedureCall<I, O>
+		: ClientTree<T[K]>
+}
+
+type FilesOf<C> = SurfaceOf<C> extends { readonly files: infer F } ? F : Record<never, never>
+
+/** `files.<name>` of every collection, for the signed-in callers of an RPC mount that admits people. */
+type SessionFiles<C, Callers> = Callers extends readonly (infer Caller)[] ? 'human' extends Caller ? [keyof FilesOf<C>] extends [never] ? unknown
+		: { readonly files: { readonly [N in keyof FilesOf<C>]: FileClient } }
+	: unknown
+	: unknown
+
+/** `files.<name>` of every `link: true` collection, for a link mount's holders. */
+type HolderFiles<C, M> = [LinkCollections<FilesOf<C>, M>] extends [never] ? unknown
+	: { readonly files: { readonly [N in LinkCollections<FilesOf<C>, M>]: LinkFileClient } }
+
+type MountOf<C, M> = SurfaceOf<C>[M & keyof SurfaceOf<C>]
+
+/** One function per procedure, an `AttachmentProcedure` per attachment, and `files` where the mount's callers reach collections. */
+export type ContractClient<C, M> = MountOf<C, M> extends { readonly kind: 'link'; readonly procedures: infer T } ? ClientTree<T> & HolderFiles<C, M>
+	: MountOf<C, M> extends { readonly callers: infer Callers; readonly procedures: infer T } ? ClientTree<T> & SessionFiles<C, Callers>
+	: never
+
+/** The answer of a client procedure: `ResultOf<typeof api.tasks.get>`; an attachment procedure answers a `File`. */
+export type ResultOf<F> = F extends (...args: never[]) => Promise<infer R> ? R : F extends AttachmentProcedure<unknown> ? File : never
+
+/** The input of a client procedure as the caller writes it: `InputOf<typeof api.tasks.create>`. */
+export type InputOf<F> = F extends (...args: infer A) => Promise<unknown> ? A[0]
+	: F extends AttachmentProcedure<infer I> ? DownloadInput<I>[0]
+	: never
+
+export interface ClientOptions {
+	/** The application's origin; procedure paths are joined to it. Defaults to the page's own origin. */
+	readonly baseUrl?: string
+	/** Override `fetch` (tests, a script). Defaults to the global `fetch`. */
+	readonly fetch?: RpcFetch
+	/**
+	 * A `px_` key, sent as `Authorization: Bearer`. A request with a key carries no cookie. In a browser the key goes
+	 * only to the page's own origin.
+	 */
+	readonly key?: string
+	/** On a 401 that carries a login URL, send the browser to sign in instead of throwing. */
+	readonly bounceOnAuth?: BounceOption
+}
+
+/** A link mount's caller is the holder of its share key, which every request presents. */
+export interface LinkClientOptions extends ClientOptions {
+	readonly key: string
+}
+
+type OptionsFor<C, M> = SurfaceOf<C>[M & keyof SurfaceOf<C>] extends { readonly kind: 'link' } ? [options: LinkClientOptions]
+	: [options?: ClientOptions]
+
+interface CallTarget {
+	readonly id: string
+	readonly url: string
+	readonly type: ProcedureType
+	readonly input: Schema | null
+	readonly output: Schema
+}
+
+/**
+ * What a value of a client tree is, kept beside it so the value stays a plain function or record: a procedure's
+ * `<mount>.<path>`, its type and input schema, or a group's prefix. `@fabrika/app/react` keys its cache by it.
+ */
+export interface ClientNode {
+	readonly mount: string
+	/** The dotted path below the mount; `''` for the client itself. */
+	readonly path: string
+	readonly procedure: { readonly type: ProcedureType; readonly input: Schema | null } | null
+}
+
+const clientNodes = new WeakMap<object, ClientNode>()
+
+/** The node a value of a client tree is, or `null` for any other value. */
+export function clientNodeOf(value: unknown): ClientNode | null {
+	return (typeof value === 'function' || (typeof value === 'object' && value !== null)) ? (clientNodes.get(value) ?? null) : null
+}
+
+/** The request of one procedure call: its input as JSON, with the key as a bearer or the page's session. */
+function requestOf(options: ClientOptions, input: unknown): () => RequestInit {
+	return () => {
+		const headers = new Headers({ 'Content-Type': 'application/json' })
+		if (options.key !== undefined) {
+			headers.set('Authorization', `Bearer ${options.key}`)
+		}
+		return { method: 'POST', credentials: options.key === undefined ? 'same-origin' : 'omit', headers, body: JSON.stringify(input ?? {}) }
+	}
+}
+
+function caller(target: CallTarget, at: TreeAt, options: ClientOptions, bounce: BounceConfig | null) {
+	const call = async (input?: unknown): Promise<unknown> => {
+		const result = await exchange(options.fetch ?? fetch, target.url, requestOf(options, input), bounce)
+		const parsed = z.safeParse(target.output, result)
+		if (!parsed.success) {
+			throw new RpcError({ type: 'invalid-response', message: `'${target.id}' answered a value its output schema refuses`, httpStatus: 200 })
+		}
+		return parsed.data
+	}
+	Object.defineProperty(call, 'output', { value: target.output, enumerable: true })
+	clientNodes.set(call, { mount: at.mount, path: at.path, procedure: { type: target.type, input: target.input } })
+	return call
+}
+
+interface TreeAt {
+	readonly mount: string
+	/** The origin the paths are joined to, without a trailing `/`. */
+	readonly origin: string
+	readonly base: string
+	readonly path: string
+}
+
+function clientTree(
+	tree: ProcedureTreeDeclaration<Schema, unknown>,
+	at: TreeAt,
+	make: (target: CallTarget, at: TreeAt) => unknown,
+): Record<string, unknown> {
+	const client: Record<string, unknown> = {}
+	for (const [name, node] of Object.entries(tree)) {
+		const path = at.path === '' ? name : `${at.path}.${name}`
+		client[name] = isProcedure(node)
+			? make({ id: `${at.mount}.${path}`, url: `${at.origin}${joinPath(at.base, path)}`, type: node.type, input: node.input, output: node.output }, {
+				...at,
+				path,
+			})
+			: clientTree(node, { ...at, path }, make)
+	}
+	const group = Object.freeze(client)
+	clientNodes.set(group, { mount: at.mount, path: at.path, procedure: null })
+	return group
+}
+
+declare const attachmentInput: unique symbol
+
+/**
+ * An attachment procedure of a client: not a function, because its answer is a file. `download(api.<procedure>,
+ * input)` fetches and saves it.
+ */
+export interface AttachmentProcedure<I> {
+	/** `<mount>.<path>` */
+	readonly id: string
+	/** The file name the contract declares. */
+	readonly filename: string
+	/** Carries the input schema for `download`; never present at runtime. */
+	readonly [attachmentInput]?: I
+}
+
+/** The request each attachment procedure sends, kept beside it so the value itself carries no key. */
+const downloads = new WeakMap<object, { readonly url: string; readonly options: ClientOptions; readonly bounce: BounceConfig | null }>()
+
+function attachmentProcedure(
+	target: CallTarget,
+	filename: string,
+	options: ClientOptions,
+	bounce: BounceConfig | null,
+): AttachmentProcedure<unknown> {
+	const procedure = Object.freeze({ id: target.id, filename })
+	downloads.set(procedure, { url: target.url, options, bounce })
+	return procedure
+}
+
+/** The input `download` takes: the procedure's, or none. */
+export type DownloadInput<I> = [I] extends [InputSchema] ? [input: z.input<I>] : [input?: Record<never, never>]
+
+/**
+ * Calls an attachment procedure and saves its file: in a browser the page offers it as a download under the declared
+ * name. Answers the file, also where there is no page to save it from (a script, a test). A refusal is an `RpcError`.
+ */
+export async function download<I>(procedure: AttachmentProcedure<I>, ...input: DownloadInput<I>): Promise<File> {
+	const request = downloads.get(procedure)
+	if (request === undefined) {
+		throw new Error(`'${procedure.id}' is not an attachment procedure of a client`)
+	}
+	const { body } = await exchangeFile(request.options.fetch ?? fetch, request.url, requestOf(request.options, input[0]), request.bounce)
+	const file = new File([body], procedure.filename, { type: body.type })
+	saveFile(file)
+	return file
+}
+
+function saveFile(file: File): void {
+	if (typeof document === 'undefined') {
+		return
+	}
+	const url = URL.createObjectURL(file)
+	const link = document.createElement('a')
+	link.href = url
+	link.download = file.name
+	// A detached link downloads in every current browser; the page's document stays untouched.
+	link.click()
+	setTimeout(() => URL.revokeObjectURL(url), 0)
+}
+
+/** A function for every procedure of `tree` and a group for every nested tree: every declared call exists. */
+function coversTree(value: unknown, tree: ProcedureTreeDeclaration<Schema, unknown>): boolean {
+	if (typeof value !== 'object' || value === null) {
+		return false
+	}
+	return Object.entries(tree).every(([name, node]) => {
+		const member: unknown = Reflect.get(value, name)
+		if (!isProcedure(node)) {
+			return coversTree(member, node)
+		}
+		return attachmentOf(node.output) === null
+			? typeof member === 'function' && Reflect.get(member, 'output') === node.output
+			: typeof member === 'object' && member !== null && downloads.has(member)
+	})
+}
+
+/** A client of every collection in `names` under `files`, or no `files` at all. */
+function coversFiles(value: unknown, names: readonly string[]): boolean {
+	if (typeof value !== 'object' || value === null) {
+		return false
+	}
+	const files: unknown = Reflect.get(value, 'files')
+	if (names.length === 0) {
+		return true
+	}
+	return typeof files === 'object' && files !== null && names.every((name) => typeof Reflect.get(files, name) === 'object')
+}
+
+/** The page's origin when the client runs in a browser, else `null`. */
+function pageOrigin(): string | null {
+	const location: unknown = Reflect.get(globalThis, 'location')
+	const origin: unknown = typeof location === 'object' && location !== null ? Reflect.get(location, 'origin') : undefined
+	return typeof origin === 'string' ? origin : null
+}
+
+/**
+ * The client of mount `mount` of `contract`: one function per declared procedure. A link mount's client sends its
+ * share key as a bearer, so `options.key` is required there.
+ */
+export function createClient<const C extends AnyContract, const M extends ClientMount<C>>(
+	contract: C,
+	mount: M,
+	...rest: OptionsFor<C, M>
+): ContractClient<C, M> {
+	const options: ClientOptions = rest[0] ?? {}
+	const surface: Surface = contract.surface
+	const node = SURFACE_SECTIONS.some((section) => section === mount) ? undefined : surface[mount]
+	if (typeof node !== 'object' || !('kind' in node) || (node.kind !== 'rpc' && node.kind !== 'link')) {
+		throw new Error(`'${mount}' is not an RPC or link mount of the contract`)
+	}
+	if (node.kind === 'link' && (options.key === undefined || options.key === '')) {
+		throw new Error(`'${mount}' is a link mount; its client needs the share key`)
+	}
+	const base = node.kind === 'link' ? joinPath(node.prefix, LINK_API_SEGMENT) : node.prefix
+	const bounce = resolveBounce(`${contract.vocabulary.app}:${mount}`, options.bounceOnAuth)
+	const origin = (options.baseUrl ?? '').replace(/\/+$/, '')
+	const page = pageOrigin()
+	// A page's key goes only to the page's own application; a script names the application it calls.
+	if (options.key !== undefined && page !== null && origin !== '' && new URL(origin, page).origin !== page) {
+		throw new Error(`a client with a key in a browser calls only ${page}; baseUrl '${origin}' is another origin`)
+	}
+	const procedures = clientTree(node.procedures, { mount, origin, base, path: '' }, (target, at) => {
+		const mark = attachmentOf(target.output)
+		return mark === null ? caller(target, at, options, bounce) : attachmentProcedure(target, mark.declaration.filename, options, bounce)
+	})
+	const transport: FileTransport = { origin, fetch: options.fetch ?? fetch, key: options.key, bounce }
+	const collections = Object.entries(surface.files ?? {}).flatMap(([name, collection]): (readonly [string, FileClient | LinkFileClient])[] => {
+		if (node.kind === 'link') {
+			const serves = collection.link === true || (Array.isArray(collection.link) && collection.link.includes(mount))
+			return serves ? [[name, linkFiles(transport, node.prefix, mount, name)]] : []
+		}
+		return node.callers.includes('human') ? [[name, sessionFiles(transport, name)]] : []
+	})
+	if (collections.length > 0 && Object.hasOwn(node.procedures, 'files')) {
+		throw new Error(`'${mount}' has a procedure group named files, which the client of its file collections takes`)
+	}
+	const client = collections.length === 0 ? procedures : Object.freeze({ ...procedures, files: Object.freeze(Object.fromEntries(collections)) })
+	// The client with its file collections is the mount's root too: `@fabrika/app/react` keys a provider by it.
+	if (client !== procedures) clientNodes.set(client, { mount, path: '', procedure: null })
+	// The tree was built from this mount's declaration; the check ties the value to the type the contract derives.
+	const names = collections.map(([name]) => name)
+	const covers = (value: unknown): value is ContractClient<C, M> => coversTree(value, node.procedures) && coversFiles(value, names)
+	if (!covers(client)) {
+		throw new Error(`the client of '${mount}' does not cover its procedures`)
+	}
+	return client
+}