@fabrika/app 0.6.0 → 0.8.0

package/src/testing/kit.ts

@@ -9,9 +9,12 @@ import {
 	CLIENT_ADDRESS_HEADER,
 	type ContractArtifact,
 	contractDigest,
+	contractWorkloads,
+	FABRIKA_APP_ORIGIN,
 	FABRIKA_CONTRACT_DIGEST,
 	FABRIKA_IAM_APP_ID,
 	FABRIKA_IAM_ISSUER,
+	FABRIKA_TOKEN_KEYS,
 	type IamMembershipRpc,
 	isNormalizedMailbox,
 	type Jwks,
@@ -32,18 +35,22 @@ import { type IamGateway, REQUEST_ID_HEADER, stripFabrikaCookies } from '@fabrik
 import { exportJWK, generateKeyPair, SignJWT } from 'jose'
 import { existsSync } from 'node:fs'
 import { resolve } from 'node:path'
+import type { z } from 'zod/v4'
+import { challengeUrl } from '../client/contract'
 import type { RpcFetch } from '../client/transport'
 import { compileContract } from '../contract/compile'
 import type { AnyContract, DimensionOf } from '../contract/define'
+import type { TokenPurpose } from '../contract/token'
 import { diskAssets } from '../disk-assets'
 import type { RequestExecutionContext } from '../fetch'
-import type { FILE_SWEEP_JOB } from '../files/collections'
+import type { FILE_SWEEP_JOB } from '../files/kinds'
 import type { FILE_SCAN_JOB, FileScanner } from '../files/scan'
 import { boot, type BootOptions, type ContractApp } from '../implement/boot'
-import type { ChallengeFetch } from '../implement/challenge'
+import { type ChallengeFetch, MINIMAL_CHALLENGE_WORK } from '../implement/challenge'
 import { type ConnectFetch, connectVariables } from '../implement/connect'
 import type { SpaAssets } from '../implement/dispatch'
 import type { ApplicationEnvironment, ContractImplementation } from '../implement/implement'
+import { readTokenKeys, SignedTokens } from '../implement/tokens'
 import type { WorkloadKindOf, WorkloadTokenSource } from '../implement/workload'
 import type { MailKeyScope } from '../jobs/mail'
 import type { HandlerErrorSink } from '../jobs/runner'
@@ -58,6 +65,7 @@ import {
 	type TestGrant,
 	type TestScope,
 } from './caller'
+import { solveChallengeAt } from './challenge'
 import {
 	credentialCallers,
 	type JobCredential,
@@ -80,6 +88,11 @@ type MintRefusal = { readonly ok: false; readonly reason: 'disabled' | 'token_to
 export interface TestKitOptions {
 	/** The application's own variables, as `deps` receives them. */
 	readonly env?: ApplicationEnvironment
+	/**
+	 * The address the kit's proxy reports for every request, as the platform's proxy reports the visitor's
+	 * (`X-Fabrika-Client-Ip`): what `ctx.client.ip` reads and a per-client bucket counts. `192.0.2.1` by default.
+	 */
+	readonly clientIp?: string
 	/**
 	 * The application root an SPA mount's `dir` is relative to; the working directory when omitted. A mount whose built
 	 * directory exists there is served from it as the deploy serves it: a file by its path, every other path by the
@@ -90,9 +103,9 @@ export interface TestKitOptions {
 	readonly assets?: SpaAssets
 	/** The connection a `scoped(tables)` database is bound to, as the runtime adapter supplies it to `boot`. */
 	readonly database?: Database
-	/** The object storage of the file collections, as the runtime adapter supplies it to `boot`. */
+	/** The object storage of the stored files, as the runtime adapter supplies it to `boot`. */
 	readonly files?: FileObjectStore
-	/** The scanner of the scan job of `scan: true` collections; without it, the job leaves every upload quarantined. */
+	/** The scanner of the scan job of `scan: true` file kinds; without it, the job leaves every such file quarantined. */
 	readonly scanner?: FileScanner
 	/**
 	 * IAM's membership operations in place of the kit's own stand-in: `boot` asks it as the adapter's transport, and the
@@ -104,7 +117,7 @@ export interface TestKitOptions {
 	 * framework variables, and how a request reaches it — usually the owner kit's `fetch`.
 	 */
 	readonly connect?: Readonly<Record<string, TestConnection>>
-	/** What answers a form's challenge verification in place of the provider: a stand-in for its siteverify. */
+	/** What answers a public procedure's challenge verification in place of the provider: a stand-in for its siteverify. */
 	readonly challengeFetch?: ChallengeFetch
 	/** What a job's handler threw, shown on the developer's own machine: `fabrika app dev` sets it, a test need not. */
 	readonly revealHandlerErrors?: HandlerErrorSink
@@ -116,7 +129,7 @@ export interface TestKitOptions {
 	 */
 	readonly mail?: MemoryEmailSender | 'none'
 	/**
-	 * The origins the environment lists for the contract's `crossOrigin` endpoints, as an operator sets them in
+	 * The origins the environment lists for the contract's endpoints that admit `origins: 'listed'`, as an operator sets them in
 	 * Control; a page on one of them may call such an endpoint with a key. None when omitted.
 	 */
 	readonly crossOrigins?: readonly string[]
@@ -161,12 +174,12 @@ export interface TestKit<C extends AnyContract> {
 	acceptInvitation(invitationId: string, person?: LabelledTestCaller): LabelledTestCaller
 	/**
 	 * Runs the cron job `name` once, as `fabrika job run <name>` does: under its lease, with the actions IAM signs for
-	 * its key, its writes fenced. It first waits for the runs a form's or a mutation's `then` kicked, so it never races them.
-	 * `FILE_SCAN_JOB` runs the scan of `scan: true` collections with the kit's `scanner`, `FILE_SWEEP_JOB` the sweep of
-	 * removed and orphaned files. Needs the application's data layer on Postgres.
+	 * its key, its writes fenced. It first waits for the runs a site's `ctx.kick` sent, so it never races them.
+	 * `FILE_SCAN_JOB` runs the scan of `scan: true` file kinds with the kit's `scanner`, `FILE_SWEEP_JOB` the sweep of
+	 * unreferenced files. Needs the application's data layer on Postgres.
 	 */
 	runJob(name: JobName<C> | typeof FILE_SCAN_JOB | typeof FILE_SWEEP_JOB, options?: JobRunOptions): Promise<JobRunResult>
-	/** Waits for the work requests left running: the runs a form's or a mutation's `then` kicked, a failure's report. */
+	/** Waits for the work requests left running: the runs a site's `ctx.kick` sent, a failure's report. */
 	drain(): Promise<void>
 	/**
 	 * The stand-in for every job's transport: what reached it (`accepted`, `handoffs`) and its faults (`refuse`,
@@ -176,11 +189,30 @@ export interface TestKit<C extends AnyContract> {
 	readonly mail: MemoryEmailSender
 	/** Whose keys this kit's prefix separates: `mailKeyPrefix(kit.mailKeyScope)` is what a job's key gets in front. */
 	readonly mailKeyScope: MailKeyScope
+	/**
+	 * A token of `purpose`, signed with the key the kit handed the application, as a site's `ctx.tokens.sign` signs it:
+	 * what a test sends where an input carries `signedToken('<purpose>')`.
+	 */
+	signToken<const P extends TokenPurposeName<C>>(purpose: P, claims: TokenClaimsInput<C, P>, options: { readonly days: number }): string
+	/**
+	 * A solved ALTCHA challenge of `procedure`, a procedure of a client over this kit whose challenge is
+	 * `provider: 'altcha'`: what the page sends as `challengeToken`. Each one passes once. The kit issues the cheapest
+	 * challenge whatever the contract's `cost`, so solving one takes milliseconds.
+	 */
+	solveChallenge(procedure: object): Promise<string>
 }
 
 /** The names of the contract's cron jobs. */
 export type JobName<C> = C extends { readonly surface: { readonly jobs: infer J } } ? keyof J & string : never
 
+type TokensOf<C> = C extends { readonly surface: { readonly tokens: infer T } } ? T : Record<never, never>
+
+/** The token purposes of the contract's kit. */
+export type TokenPurposeName<C> = keyof TokensOf<C> & string
+
+/** What a token of purpose `P` carries, as a site passes it to `sign`. */
+export type TokenClaimsInput<C, P extends string> = TokensOf<C> extends { readonly [K in P]: TokenPurpose<infer Claims> } ? z.input<Claims> : never
+
 /** Each SPA mount from its built directory under `root` when one exists, as the deploy serves it; an empty page otherwise. */
 function builtAssets(root: string): SpaAssets {
 	const disk = diskAssets(root)
@@ -190,13 +222,27 @@ function builtAssets(root: string): SpaAssets {
 	}
 }
 
-function toRequest(origin: string, input: RequestInfo | URL, init: RequestInit | undefined): Request {
+function toRequest(origin: string, input: RequestInfo | URL, init: RequestInit | undefined): Promise<Request> {
 	if (!(input instanceof Request)) {
-		return new Request(new URL(input, origin), init)
+		return withLength(new Request(new URL(input, origin), init), init?.body)
 	}
 	// Never `new Request(request, …)`: Bun would buffer the body the application must meet as a stream.
 	const base = { method: input.method, headers: input.headers, body: input.body, signal: input.signal, redirect: input.redirect }
-	return init === undefined ? input : new Request(input.url, { ...base, ...init })
+	return init === undefined ? Promise.resolve(input) : withLength(new Request(input.url, { ...base, ...init }), init.body)
+}
+
+/**
+ * `request` as a browser sends a body it knows the length of (a string, a form, bytes): with `Content-Length`, which a
+ * `bytesPerHour` budget charges. A stream goes without one, as `fetch` sends it chunked, and is charged the body limit.
+ */
+async function withLength(request: Request, body: BodyInit | null | undefined): Promise<Request> {
+	if (body === undefined || body === null || body instanceof ReadableStream || request.headers.has('Content-Length')) {
+		return request
+	}
+	const headers = new Headers(request.headers)
+	const bytes = await request.arrayBuffer()
+	headers.set('Content-Length', String(bytes.byteLength))
+	return new Request(request.url, { method: request.method, headers, body: bytes, signal: request.signal, redirect: request.redirect })
 }
 
 /**
@@ -207,6 +253,9 @@ function withHeaders(request: Request, headers: Headers): Request {
 	return new Request(request.url, { method: request.method, headers, body: request.body, signal: request.signal, redirect: request.redirect })
 }
 
+/** The client every request of a kit comes from, unless `clientIp` names another: TEST-NET-1 (RFC 5737). */
+const TEST_CLIENT_IP = '192.0.2.1'
+
 /** Every header only the proxy may assert, deleted before the decision as Caddy and the proxy Worker delete them. */
 function stripClientAsserted(headers: Headers): void {
 	for (const header of [...headers.keys()]) {
@@ -283,7 +332,7 @@ export function bootTestKit<C extends AnyContract>(
 		connectVariablesOf[variables.key] = connection.key
 		connectBindings[variables.binding] = connection.fetch
 	}
-	// The kit stands in for Control too: every job and webhook gets a key, which its stand-in IAM signs the declared actions for.
+	// The kit stands in for Control too: every workload gets a key, which its stand-in IAM signs the declared actions for.
 	const workloadVariables: Record<string, string> = {}
 	const workloadsByKey = new Map<string, { readonly kind: WorkloadKindOf; readonly name: string; readonly actions: readonly string[] }>()
 	// A job's key and the tokens signed for it are its credential at the stand-in IAM's link operations, as at IAM's.
@@ -292,13 +341,7 @@ export function bootTestKit<C extends AnyContract>(
 		const job = Object.hasOwn(artifact.jobs, name) ? artifact.jobs[name] : undefined
 		return job === undefined ? undefined : { id: `job-${name}`, actions: job.actions, issues: artifact.declared?.[`job:${name}`]?.issues ?? null }
 	}
-	const declaredWorkloads = [
-		...Object.entries(artifact.jobs).map(([workload, job]) => ({ kind: 'job' as const, name: workload, actions: job.actions })),
-		...Object.entries(artifact.mounts).flatMap(([workload, mount]) =>
-			mount.kind === 'webhook' ? [{ kind: 'webhook' as const, name: workload, actions: mount.actions }] : []
-		),
-	]
-	for (const workload of declaredWorkloads) {
+	for (const workload of contractWorkloads(artifact)) {
 		const key = `${API_KEY_PREFIX}test_${crypto.randomUUID().replaceAll('-', '')}`
 		workloadVariables[workloadKeyVariable(workload.kind, workload.name)] = key
 		workloadsByKey.set(key, workload)
@@ -347,6 +390,19 @@ export function bootTestKit<C extends AnyContract>(
 	const membership = options.membership ?? standIn?.rpc
 	const mail = options.mail === undefined || options.mail === 'none' ? new MemoryEmailSender() : options.mail
 	const mailKeyScope: MailKeyScope = Object.freeze({ issuer: TEST_ISSUER, appId })
+	// The kit stands in for Control's token key too: one random key, which signs and verifies.
+	const tokenKey = `${crypto.randomUUID().replaceAll('-', '').slice(0, 12)}:${
+		Buffer.from(crypto.getRandomValues(new Uint8Array(32))).toString('base64url')
+	}`
+	const tokenVariables: Record<string, string> = artifact.tokens === undefined ? {} : { [FABRIKA_TOKEN_KEYS]: tokenKey }
+	const kitTokens = new SignedTokens(
+		new Map(
+			Object.entries(app.contract.surface.tokens ?? {}).map(([purpose, declared]) => [purpose, { claims: declared.claims, maxDays: declared.maxDays }]),
+		),
+		readTokenKeys({ [FABRIKA_TOKEN_KEYS]: tokenKey }, { ...artifact, tokens: artifact.tokens ?? {} }, []),
+	)
+	const signToken = (purpose: string, claims: unknown, signOptions: { readonly days: number }): string =>
+		kitTokens.context('the test kit', [purpose]).sign(purpose, claims, signOptions)
 	const application: ContractApp = boot(app, {
 		environment: {
 			// The deploy writes the approved contract's digest; the kit's contract is the approved one by definition.
@@ -354,8 +410,11 @@ export function bootTestKit<C extends AnyContract>(
 				[FABRIKA_IAM_APP_ID]: appId,
 				[FABRIKA_IAM_ISSUER]: TEST_ISSUER,
 				[FABRIKA_CONTRACT_DIGEST]: contractDigest(artifact),
+				// The deploy writes the environment's public origin; the kit's is its own.
+				[FABRIKA_APP_ORIGIN]: origin,
 				...connectVariablesOf,
 				...workloadVariables,
+				...tokenVariables,
 			},
 			application: options.env ?? {},
 		},
@@ -365,12 +424,15 @@ export function bootTestKit<C extends AnyContract>(
 		files: options.files,
 		...(options.scanner === undefined ? {} : { scanner: options.scanner }),
 		...(options.challengeFetch === undefined ? {} : { challengeFetch: options.challengeFetch }),
+		challengeWork: MINIMAL_CHALLENGE_WORK,
 		...dev,
 		...(options.revealHandlerErrors === undefined ? {} : { revealHandlerErrors: options.revealHandlerErrors }),
 		membership,
 		connectBindings,
 		workloadTokens,
 		mailStandIn: options.mail === 'none' ? 'none' : mail,
+		// The kit's proxy sets `X-Fabrika-Client-Ip` from the request it was handed, as the Worker sets it from Cloudflare's.
+		clientAddress: 'vouched',
 	})
 
 	let issued = 0
@@ -543,7 +605,7 @@ export function bootTestKit<C extends AnyContract>(
 		...(options.crossOrigins === undefined ? {} : { crossOrigins: options.crossOrigins }),
 	})
 
-	// What requests leave running: a job a form's or a mutation's `then` kicked, or a failure's report.
+	// What requests leave running: a job a site's `ctx.kick` sent, or a failure's report.
 	const background = new Set<Promise<void>>()
 	const exec: RequestExecutionContext = {
 		waitUntil(promise) {
@@ -554,7 +616,7 @@ export function bootTestKit<C extends AnyContract>(
 	}
 
 	const kitFetch: RpcFetch = async (input, init) => {
-		const request = toRequest(origin, input, init)
+		const request = await toRequest(origin, input, init)
 		if (new URL(request.url).origin !== origin) {
 			throw new TypeError(`the test kit serves only ${origin}, not ${new URL(request.url).origin}`)
 		}
@@ -572,6 +634,7 @@ export function bootTestKit<C extends AnyContract>(
 		for (const [header, value] of outcome.asserted) {
 			headers.set(header, value)
 		}
+		headers.set(CLIENT_ADDRESS_HEADER, options.clientIp ?? TEST_CLIENT_IP)
 		const answer = await application.fetch(withHeaders(request, headers), exec)
 		const decorated = new Headers(answer.headers)
 		outcome.decorate(decorated)
@@ -582,8 +645,8 @@ export function bootTestKit<C extends AnyContract>(
 		if (caller !== undefined && caller.cookie === null) {
 			throw new Error(`a browser carries a session; pass the ${caller.kind}'s key to createClient instead`)
 		}
-		return (input, init) => {
-			const request = toRequest(origin, input, init)
+		return async (input, init) => {
+			const request = await toRequest(origin, input, init)
 			// Bun's Request does not keep its credentials mode, so `init` is the only reliable reading of it.
 			const credentials = init?.credentials ?? (input instanceof Request ? input.credentials : undefined)
 			const headers = new Headers(request.headers)
@@ -647,6 +710,8 @@ export function bootTestKit<C extends AnyContract>(
 			acceptInvitation,
 			mail,
 			mailKeyScope,
+			signToken,
+			solveChallenge: (procedure: object) => solveChallengeAt(kitFetch, new URL(challengeUrl(procedure), origin).href),
 		}),
 		standIn,
 		callerOf: (value) => [...memberships.keys()].find((caller) => caller === value),

package/src/testing/policy-isolation.ts

@@ -5,12 +5,14 @@
 // application's handlers and stores never run. Each attempt seeds two fresh rows that share no scope value and asks as
 // a caller holding every action of the table in the scope of one of them.
 
+import { tableActions, type TablePolicyArtifact } from '@fabrika/auth-core'
 import { scoped, type Tables } from '@fabrika/db'
 import { tablePolicies } from '@fabrika/db/tables'
-import { type IsolationWorlds, type SampleValue, tableProbe, type TestDatabase, withoutInboxes } from '@fabrika/db/testing'
+import { type IsolationWorlds, type SampleValue, tableProbe, type TestDatabase } from '@fabrika/db/testing'
+import { MemoryFileObjects } from '@fabrika/platform/testing'
 import { z } from 'zod/v4'
 import { createClient } from '../client/contract'
-import { type AnyContract, defineContract, type Vocabulary } from '../contract/define'
+import { type AnyContract, defineContract, type FileKind } from '../contract/define'
 import { implement } from '../implement/implement'
 import type { TestGrant } from './caller'
 import { testKit } from './kit'
@@ -141,6 +143,20 @@ interface ProbeActions {
 	readonly insert: string | null
 	readonly update: string | null
 	readonly delete: string | null
+	/** Every read action of the table: an action besides them is another action. */
+	readonly reads: readonly string[]
+}
+
+/** The actions a probe holds: the first of each operation, as the generated cases name them. */
+function probeActions(actions: TablePolicyArtifact['actions']): ProbeActions {
+	const reads = tableActions(actions.read)
+	return {
+		read: reads[0] ?? '',
+		insert: tableActions(actions.insert)[0] ?? null,
+		update: tableActions(actions.update)[0] ?? null,
+		delete: tableActions(actions.delete)[0] ?? null,
+		reads,
+	}
 }
 
 function isCapabilityError(error: unknown): boolean {
@@ -155,14 +171,20 @@ async function attempt<T extends object>(run: () => Promise<T>, failed: (status:
 	}
 }
 
+/** The file kinds `contract` declares: each probe declares them too, so the file columns of the tables name declared kinds. */
+function fileKindsOf(contract: AnyContract): Readonly<Record<string, FileKind>> {
+	return Object.fromEntries(Object.entries(contract.surface.files ?? {}).filter((entry): entry is [string, FileKind] => entry[1].kind === 'file-kind'))
+}
+
 /** A write's outcome: 200 when it ran, the status otherwise. */
 async function wrote(run: () => Promise<unknown>): Promise<IsolationOutcome> {
 	return { status: await statusOf(run()) }
 }
 
-function dimensionProbe(vocabulary: Vocabulary<string, string, string>, dimension: string, list: string, actions: ProbeActions) {
+function dimensionProbe(contract: AnyContract, dimension: string, list: string, actions: ProbeActions) {
 	const { read } = actions
-	return defineContract(vocabulary, (c) => ({
+	return defineContract(contract.vocabulary, (c) => ({
+		files: fileKindsOf(contract),
 		probe: c.rpc('/probe', { callers: ['human'] }, {
 			get: c.query({ input: ById, output: Columns, access: { action: read, on: dimension, from: 'id' } }),
 			list: c.query({ output: Keys, access: { action: read, over: list } }),
@@ -176,9 +198,10 @@ function dimensionProbe(vocabulary: Vocabulary<string, string, string>, dimensio
 	}))
 }
 
-function childProbe(vocabulary: Vocabulary<string, string, string>, parent: string, list: string, actions: ProbeActions) {
+function childProbe(contract: AnyContract, parent: string, list: string, actions: ProbeActions) {
 	const { read } = actions
-	return defineContract(vocabulary, (c) => ({
+	return defineContract(contract.vocabulary, (c) => ({
+		files: fileKindsOf(contract),
 		probe: c.rpc('/probe', { callers: ['human'] }, {
 			get: c.query({ input: ChildByKey, output: Columns, access: { action: read, on: parent, from: 'parent' } }),
 			list: c.query({ output: Keys, access: { action: read, over: list } }),
@@ -195,12 +218,13 @@ function childProbe(vocabulary: Vocabulary<string, string, string>, parent: stri
 
 /** An action the table names besides its read action, or `null` when it names none. */
 function otherAction(actions: ProbeActions): string | null {
-	return [actions.insert, actions.update, actions.delete].find((action) => action !== null && action !== actions.read) ?? null
+	return [actions.insert, actions.update, actions.delete].find((action) => action !== null && !actions.reads.includes(action)) ?? null
 }
 
-function appProbe(vocabulary: Vocabulary<string, string, string>, actions: ProbeActions) {
+function appProbe(contract: AnyContract, actions: ProbeActions) {
 	const { read } = actions
-	return defineContract(vocabulary, (c) => ({
+	return defineContract(contract.vocabulary, (c) => ({
+		files: fileKindsOf(contract),
 		probe: c.rpc('/probe', { callers: ['human'] }, {
 			get: c.query({ input: ById, output: Columns, access: { action: read, app: true } }),
 			list: c.query({ output: Keys, access: { action: read, app: true } }),
@@ -214,8 +238,9 @@ function appProbe(vocabulary: Vocabulary<string, string, string>, actions: Probe
 }
 
 /** Scoped sites over an application table: `over` the vocabulary's first dimension, of its read action and of another. */
-function scopedAppProbe(vocabulary: Vocabulary<string, string, string>, actions: ProbeActions, dimension: string) {
-	return defineContract(vocabulary, (c) => ({
+function scopedAppProbe(contract: AnyContract, actions: ProbeActions, dimension: string) {
+	return defineContract(contract.vocabulary, (c) => ({
+		files: fileKindsOf(contract),
 		probe: c.rpc('/probe', { callers: ['human'] }, {
 			list: c.query({ output: Keys, access: { action: actions.read, over: dimension } }),
 			listWithOther: c.query({ output: Refused, access: { action: otherAction(actions) ?? actions.read, over: dimension } }),
@@ -241,8 +266,8 @@ export function appPolicyIsolationKit<C extends AnyContract, DB, P>(
 	if (scope.mode !== 'app') {
 		throw new Error(`${table} is a ${scope.mode} table; policyIsolationKit probes a dimension or child table`)
 	}
-	const actions: ProbeActions = policy.actions
-	const layer = scoped(withoutInboxes(tables))
+	const actions = probeActions(policy.actions)
+	const layer = scoped(tables)
 	const probe = tableProbe(layer, table)
 	const expectVersion = policy.version === null ? undefined : 1
 	const staged = new Map<string, Readonly<Record<string, SampleValue>>>()
@@ -275,7 +300,7 @@ export function appPolicyIsolationKit<C extends AnyContract, DB, P>(
 			throw error
 		}
 	}
-	const probeContract = appProbe(contract.vocabulary, actions)
+	const probeContract = appProbe(contract, actions)
 	const kit = testKit(
 		implement(probeContract, {
 			database: layer,
@@ -301,7 +326,7 @@ export function appPolicyIsolationKit<C extends AnyContract, DB, P>(
 				},
 			}),
 		}),
-		{ database: postgres.database },
+		{ database: postgres.database, files: new MemoryFileObjects() },
 	)
 	const held = [...new Set([actions.read, actions.insert, actions.update, actions.delete].filter((action) => action !== null))]
 	const dimension = scopeTypeOf(contract.vocabulary.dimensions)
@@ -310,7 +335,7 @@ export function appPolicyIsolationKit<C extends AnyContract, DB, P>(
 		if (!Object.hasOwn(contract.vocabulary.dimensions, dimension)) {
 			throw new Error(`the vocabulary declares no dimension, so no scoped site reads ${table}`)
 		}
-		scopedSites ??= scopedAppKit(scopedAppProbe(contract.vocabulary, actions, dimension), tables, table, scope.key, postgres)
+		scopedSites ??= scopedAppKit(scopedAppProbe(contract, actions, dimension), tables, table, scope.key, postgres)
 		return scopedSites.as(action, dimension)
 	}
 	const grantsOf = (caller: AppCaller): TestGrant<AnyContract>[] =>
@@ -389,8 +414,9 @@ export function appPolicyIsolationKit<C extends AnyContract, DB, P>(
 }
 
 /** `app` endpoints of one action over a dimension or child table: what its `appRead` and `appCount` reach. */
-function appReachProbe(vocabulary: Vocabulary<string, string, string>, action: string) {
-	return defineContract(vocabulary, (c) => ({
+function appReachProbe(contract: AnyContract, action: string) {
+	return defineContract(contract.vocabulary, (c) => ({
+		files: fileKindsOf(contract),
 		probe: c.rpc('/probe', { callers: ['human'] }, {
 			list: c.query({ output: Keys, access: { action, app: true } }),
 			count: c.query({ output: Count, access: { action, app: true } }),
@@ -430,8 +456,8 @@ function appReachKit<DB, P>(
 	}
 	const kits = new Map<string, ReturnType<typeof appReachClient>>()
 	const appReachClient = (action: string) => {
-		const probeContract = appReachProbe(contract.vocabulary, action)
-		const layer = scoped(withoutInboxes(tables))
+		const probeContract = appReachProbe(contract, action)
+		const layer = scoped(tables)
 		const probe = tableProbe(layer, table)
 		const kit = testKit(
 			implement(probeContract, {
@@ -447,7 +473,7 @@ function appReachKit<DB, P>(
 					},
 				}),
 			}),
-			{ database: postgres.database },
+			{ database: postgres.database, files: new MemoryFileObjects() },
 		)
 		return createClient(probeContract, 'probe', { fetch: kit.browser(kit.testCaller([{ action }])) })
 	}
@@ -505,7 +531,7 @@ function scopedAppKit<DB, P>(
 	key: string,
 	postgres: TestDatabase,
 ) {
-	const layer = scoped(withoutInboxes(tables))
+	const layer = scoped(tables)
 	const probe = tableProbe(layer, table)
 	const kit = testKit(
 		implement(probeContract, {
@@ -528,7 +554,7 @@ function scopedAppKit<DB, P>(
 				},
 			}),
 		}),
-		{ database: postgres.database },
+		{ database: postgres.database, files: new MemoryFileObjects() },
 	)
 	return {
 		as: (action: string, dimension: string) =>
@@ -557,9 +583,9 @@ export function policyIsolationKit<C extends AnyContract, DB, P>(
 	if (scope.mode !== 'dimension' && scope.mode !== 'child') {
 		throw new Error(`${table} is a ${scope.mode} table; no store reaches it, so it has no isolation tests`)
 	}
-	const actions: ProbeActions = policy.actions
+	const actions = probeActions(policy.actions)
 	// The probe serves no form, so it compiles against the policies without the forms' inboxes.
-	const layer = scoped(withoutInboxes(tables))
+	const layer = scoped(tables)
 	const probe = tableProbe(layer, table)
 	const expectVersion = policy.version === null ? undefined : 1
 	const pending = new Map<string, Readonly<Record<string, SampleValue>>>()
@@ -603,7 +629,7 @@ export function policyIsolationKit<C extends AnyContract, DB, P>(
 	if (scope.mode === 'dimension') {
 		const dimension = scope.dimension
 		const list = scope.container?.dimension ?? dimension
-		const probeContract = dimensionProbe(contract.vocabulary, dimension, list, actions)
+		const probeContract = dimensionProbe(contract, dimension, list, actions)
 		const kit = testKit(
 			implement(probeContract, {
 				database: layer,
@@ -630,7 +656,7 @@ export function policyIsolationKit<C extends AnyContract, DB, P>(
 					},
 				}),
 			}),
-			{ database: postgres.database },
+			{ database: postgres.database, files: new MemoryFileObjects() },
 		)
 		const session = (worlds: IsolationWorlds) => createClient(probeContract, 'probe', { fetch: kit.browser(kit.testCaller(grantsIn(worlds))) })
 		const keyOf = (worlds: IsolationWorlds, row: ChildIsolationRow): string => {
@@ -705,7 +731,7 @@ export function policyIsolationKit<C extends AnyContract, DB, P>(
 	}
 	const parent = parentPolicy.scope.dimension
 	const list = parentPolicy.scope.container?.dimension ?? parent
-	const probeContract = childProbe(contract.vocabulary, parent, list, actions)
+	const probeContract = childProbe(contract, parent, list, actions)
 	const kit = testKit(
 		implement(probeContract, {
 			database: layer,
@@ -733,7 +759,7 @@ export function policyIsolationKit<C extends AnyContract, DB, P>(
 				},
 			}),
 		}),
-		{ database: postgres.database },
+		{ database: postgres.database, files: new MemoryFileObjects() },
 	)
 	const session = (worlds: IsolationWorlds) => createClient(probeContract, 'probe', { fetch: kit.browser(kit.testCaller(grantsIn(worlds))) })
 	/** The parent and key a request names: a crossed row is the other key under the caller's own parent. */

package/src/testing/proxy.ts

@@ -7,6 +7,7 @@ import {
 	createVerifyService,
 	DEFAULT_VERIFY_PATH,
 	type DelegationIssuer,
+	FORWARD_AUTHORIZATION_HEADER,
 	FORWARDED_HOST_HEADER,
 	FORWARDED_METHOD_HEADER,
 	FORWARDED_PROTO_HEADER,
@@ -26,7 +27,10 @@ export type ProxyOutcome =
 		readonly outcome: 'forward'
 		/** Every header only the proxy may assert, with the value the decision gave it. */
 		readonly asserted: ReadonlyMap<string, string>
-		/** Whether the request's own `Authorization` reaches the application: not on an anonymous endpoint. */
+		/**
+		 * Whether the request's own `Authorization` reaches the application: not on an anonymous endpoint, except a webhook
+		 * row the decision marked to pass it on.
+		 */
 		readonly keepsAuthorization: boolean
 		/** What the application's answer is given for an admitted cross-origin request, over its own headers. */
 		readonly decorate: (headers: Headers) => void
@@ -104,7 +108,7 @@ export function endpointProxy(options: EndpointProxyOptions): TestProxy {
 		return {
 			outcome: 'forward',
 			asserted,
-			keepsAuthorization: asserted.has(PROXY_TOKEN_HEADER),
+			keepsAuthorization: asserted.has(PROXY_TOKEN_HEADER) || verification.headers.get(FORWARD_AUTHORIZATION_HEADER) === '1',
 			decorate: (answer) => {
 				if (allowOrigin !== null) applyCrossOriginHeaders(answer, crossOriginHeaders(allowOrigin))
 			},

package/src/testing/sample-file.ts

@@ -0,0 +1,30 @@
+// A small file the testing kits write: the leading bytes `files/sniff.ts` accepts for its type, then a text marker.
+
+const randomHex = (): string => crypto.randomUUID().replaceAll('-', '').slice(0, 8)
+
+const ascii = (text: string): number[] => [...text].map((char) => char.charCodeAt(0))
+const ZIP_HEAD = [0x50, 0x4b, 0x03, 0x04]
+
+/** The leading bytes `files/sniff.ts` accepts for each binary type it verifies; a text type needs none. */
+const SAMPLE_HEADS: Readonly<Record<string, readonly number[]>> = {
+	'image/png': [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a],
+	'image/jpeg': [0xff, 0xd8, 0xff, 0xe0],
+	'image/gif': ascii('GIF89a'),
+	'image/webp': [...ascii('RIFF'), 0, 0, 0, 0, ...ascii('WEBP')],
+	'application/pdf': ascii('%PDF-1.7\n'),
+	'application/gzip': [0x1f, 0x8b, 0x08],
+	'application/zip': ZIP_HEAD,
+	'application/vnd.openxmlformats-officedocument.wordprocessingml.document': ZIP_HEAD,
+	'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': ZIP_HEAD,
+	'application/vnd.openxmlformats-officedocument.presentationml.presentation': ZIP_HEAD,
+}
+const TEXT_TYPES: ReadonlySet<string> = new Set(['text/plain', 'text/csv', 'text/markdown', 'application/json', 'image/svg+xml'])
+
+/** A file of the first of `types` the kit can write; `name` (a collection or a kind) names it in the error when none is. */
+export function sampleFile(name: string, types: readonly string[]): { readonly type: string; readonly bytes: Uint8Array<ArrayBuffer> } {
+	for (const type of types) {
+		const head = SAMPLE_HEADS[type] ?? (TEXT_TYPES.has(type) ? [] : undefined)
+		if (head !== undefined) return { type, bytes: new Uint8Array([...head, ...ascii(`fabrika test file ${randomHex()}`)]) }
+	}
+	throw new Error(`files.${name}: none of its types is one the testing kit can write a file of`)
+}