@fabrika/app 0.9.0-cloudflare.1 → 0.9.0-cloudflare.2

package/src/testing/endpoint-access.ts

@@ -20,6 +20,9 @@ import type { Tables } from '@fabrika/db'
 import { tablePolicies } from '@fabrika/db/tables'
 import { type IsolationWorlds, type SampleValue, SEEDED_OBJECT_VERSION, type TestDatabase, type WorldRow } from '@fabrika/db/testing'
 import { MemoryFileObjects } from '@fabrika/platform/testing'
+import { readFile } from 'node:fs/promises'
+import { basename } from 'node:path'
+import { fileURLToPath } from 'node:url'
 import { z } from 'zod/v4'
 import type { RpcFetch } from '../client/transport'
 import { compileContract } from '../contract/compile'
@@ -33,6 +36,7 @@ import {
 } from '../contract/defaults'
 import type { AnyContract } from '../contract/define'
 import type { FileScanner, ScanVerdict } from '../files/scan'
+import { bytesAreOfType, SNIFF_BYTES } from '../files/sniff'
 import type { ApplicationEnvironment, ContractImplementation } from '../implement/implement'
 import type { TestCaller, TestGrant } from './caller'
 import { standInIamKit } from './kit'
@@ -110,6 +114,54 @@ export interface EndpointAccessKit {
 	anyone(endpoint: string, input: Readonly<Record<string, unknown>>): Promise<ReachOutcome>
 }
 
+export interface EndpointAccessOptions {
+	/**
+	 * The file every case of an endpoint sends in a file field instead of the kit's sample, by endpoint id and input
+	 * field: a file of the application's repository that a handler inspecting the content accepts (a valid package). Its
+	 * type is the first of the field's kind that its bytes are; a file of none of them throws. `files` of the fixtures.
+	 */
+	readonly files?: Readonly<Record<string, Readonly<Record<string, URL>>>>
+	/**
+	 * The error types of the refusals (400) an endpoint's handler answers its own object with when the case's input meets
+	 * no domain rule the kit can satisfy, by endpoint id: such a 400 is the handler's own answer, so the request passed
+	 * the access form, and the endpoint's own case gets it as `{ status: 400 }` instead of failing; so does the other
+	 * scope's request a leak case makes first. The own scope's answer of a leak case, and a global or capability case,
+	 * still throw on it (an answer that holds nothing proves no isolation), so does any other 400, and an input the schema
+	 * refuses (`validation`) always does. `refusals` of the fixtures.
+	 */
+	readonly refusals?: Readonly<Record<string, readonly string[]>>
+	/**
+	 * Known values for text columns of the row the endpoint addresses (the row of the table that owns its dimension), by
+	 * endpoint id: the value in the own scope's row, and `<value>-other` in the other scope's, which counts among the
+	 * other scope's values a leak shows. For a handler whose rule ties a column to the input or a file fixture (a package
+	 * that names the skill's slug). `pins` of the fixtures.
+	 */
+	readonly pins?: Readonly<Record<string, Readonly<Record<string, string>>>>
+}
+
+/**
+ * Whether a request takes a refusal the fixtures declare for its endpoint as the handler's answer: an own case's, and the
+ * other scope's request a leak case makes first, whose answer is not the one checked.
+ */
+type Refusals = 'declared' | 'none'
+
+/**
+ * The pins of a case's endpoint (column → the own scope's value of a text column), and the removals of the case: rows
+ * seeded with pins are removed once the case is over, so the next case can pin the same values under a unique index.
+ */
+interface Pinning {
+	readonly pins: Readonly<Record<string, string>>
+	readonly removals: (() => Promise<void>)[]
+}
+
+const NO_PINNING: Pinning = { pins: {}, removals: [] }
+
+/** Seeded worlds, their removal taken by the case when they hold pinned values. */
+const pinned = <W extends { readonly remove: () => Promise<void> }>(worlds: W, pinning: Pinning): W => {
+	if (Object.keys(pinning.pins).length > 0) pinning.removals.push(worlds.remove)
+	return worlds
+}
+
 interface ActionEndpoint {
 	readonly id: string
 	/** The link mount of a link procedure; `null` for every other endpoint. */
@@ -285,7 +337,12 @@ export const managerGrants = (
  * The endpoint access kit of `app`, whose data layer is `scoped(tables)`, over `postgres`. It boots `app` once, so the
  * application's layer is bound here and nowhere else in the process.
  */
-export function endpointAccessKit<DB, P>(app: ContractImplementation<AnyContract>, tables: Tables<DB, P>, postgres: TestDatabase): EndpointAccessKit {
+export function endpointAccessKit<DB, P>(
+	app: ContractImplementation<AnyContract>,
+	tables: Tables<DB, P>,
+	postgres: TestDatabase,
+	options: EndpointAccessOptions = {},
+): EndpointAccessKit {
 	// The objects of the files the cases seed live in memory; their rows are the application's own tables.
 	const objects = new MemoryFileObjects()
 	const { kit, standIn } = standInIamKit(app, {
@@ -404,16 +461,20 @@ export function endpointAccessKit<DB, P>(app: ContractImplementation<AnyContract
 		throw new Error(`${row.id} admits neither a human nor a machine caller`)
 	}
 
-	/** A case's request by a new caller holding `grants`, its generated fields filled for `chain` and that caller. */
+	/**
+	 * A case's request by a new caller holding `grants`, its generated fields filled for `chain` and that caller. Only an
+	 * own case passes `refusals: 'declared'`.
+	 */
 	const ask = async (
 		row: ActionEndpoint,
 		grants: readonly Grant[],
 		input: Readonly<Record<string, unknown>>,
 		chain: Chain,
+		refusals: Refusals = 'none',
 	): Promise<{ readonly status: number; readonly text: string; readonly marks: readonly string[] }> => {
 		const asker = callerFor(row, grants)
 		const asked = withGenerated(row, input, chain, asker.caller)
-		return { ...(await askAs(row, asker.fetch, asked.input)), marks: asked.marks }
+		return { ...(await askAs(row, asker.fetch, asked.input, refusals)), marks: asked.marks }
 	}
 
 	// A seeded file column references an empty object, which a handler that serves or opens the file reads here.
@@ -427,7 +488,7 @@ export function endpointAccessKit<DB, P>(app: ContractImplementation<AnyContract
 	}
 
 	/** The request of a case: a GET's input in its URL, a file field's marker as a file of its kind in a multipart body. */
-	const requestOf = (row: ActionEndpoint, body: Readonly<Record<string, unknown>>): readonly [string, RequestInit] => {
+	const requestOf = async (row: ActionEndpoint, body: Readonly<Record<string, unknown>>): Promise<readonly [string, RequestInit]> => {
 		if (row.method === 'GET') {
 			const params = new URLSearchParams(Object.entries(body).map(([name, value]) => [name, value === null ? 'null' : String(value)]))
 			return [params.size === 0 ? row.path : `${row.path}?${params}`, { method: 'GET' }]
@@ -446,7 +507,7 @@ export function endpointAccessKit<DB, P>(app: ContractImplementation<AnyContract
 			for (const item of Array.isArray(value) ? value : [value]) {
 				const kind = fileKindOf(item)
 				if (kind === undefined) throw new Error(`${row.id}: the file field ${name} holds ${JSON.stringify(item)}, not a generated file`)
-				files.push([name, generatedFile(kind)])
+				files.push([name, await generatedFile(row.id, name, kind)])
 			}
 		}
 		const form = new FormData()
@@ -455,30 +516,69 @@ export function endpointAccessKit<DB, P>(app: ContractImplementation<AnyContract
 		return [row.path, { method: 'POST', body: form }]
 	}
 
-	const generatedFile = (kind: string): File => {
-		const sample = sampleFile(kind, kit.artifact.fileKinds?.[kind]?.types ?? [])
-		return new File([sample.bytes], `generated-${kind}`, { type: sample.type })
+	/** The file a case sends in `field`: the author's file fixture of the endpoint's field, else a sample of `kind`. */
+	const generatedFile = async (endpoint: string, field: string, kind: string): Promise<File> => {
+		const types = kit.artifact.fileKinds?.[kind]?.types ?? []
+		const fixture = options.files?.[endpoint]?.[field]
+		if (fixture === undefined) {
+			const sample = sampleFile(kind, types)
+			return new File([sample.bytes], `generated-${kind}`, { type: sample.type })
+		}
+		const path = fileURLToPath(fixture)
+		const bytes = await fixtureBytes(endpoint, field, path)
+		const type = types.find((candidate) => bytesAreOfType(candidate, bytes.subarray(0, SNIFF_BYTES)))
+		if (type === undefined) {
+			throw new Error(`${endpoint}: the file of ${field}, ${path}, is none of the types of files.${kind} (${types.join(', ')})`)
+		}
+		return new File([bytes], basename(path), { type })
+	}
+
+	// A file fixture is read once; every case sends the same bytes.
+	const fixtureFiles = new Map<string, Uint8Array<ArrayBuffer>>()
+	const fixtureBytes = async (endpoint: string, field: string, path: string): Promise<Uint8Array<ArrayBuffer>> => {
+		const known = fixtureFiles.get(path)
+		if (known !== undefined) return known
+		let bytes: Uint8Array<ArrayBuffer>
+		try {
+			bytes = new Uint8Array(await readFile(path))
+		} catch {
+			throw new Error(`${endpoint}: the file of ${field} in the fixtures, ${path}, cannot be read; add it to the repository or correct its path`)
+		}
+		fixtureFiles.set(path, bytes)
+		return bytes
 	}
 
 	const askAs = async (
 		row: ActionEndpoint,
 		fetch: RpcFetch,
 		body: Readonly<Record<string, unknown>>,
+		refusals: Refusals = 'none',
 	): Promise<{ readonly status: number; readonly text: string }> => {
 		stockSeededObjects()
-		const [url, init] = requestOf(row, body)
+		const [url, init] = await requestOf(row, body)
 		const response = await fetch(url, init)
 		const text = await response.text()
 		// A 400 hides what the case is about: input is parsed before the access form runs, and a handler's refusal of
 		// the input it was given is no answer to another scope. Either is what the generator could not build.
 		if (response.status === 400) {
 			const type = errorType(text)
+			const declared = type !== undefined && type !== 'validation' && options.refusals?.[row.id]?.includes(type) === true
+			// The own case may take it: it shows the access form let the caller through. The answer a leak case checks, or a
+			// global case's, would pass holding nothing, which proves nothing.
+			if (declared && refusals === 'declared') {
+				return { status: response.status, text }
+			}
+			if (declared) {
+				throw new Error(
+					`${row.id}: the handler answered its declared refusal (400 ${type}), which only the own case takes; this case proves nothing on it until the fixtures give what the handler needs (pins, files, fixtures) (${text})`,
+				)
+			}
 			throw new Error(
 				type === 'validation'
 					? `${row.id}: the case's input does not match the endpoint's input schema; correct its fixture (${text})`
 					: `${row.id}: the handler refused the case's input (400 ${
 						type ?? 'without a type'
-					}); the case cannot reach what it tests until its fixtures give what the handler needs: a picked person in members, a row of its object in rows, the state in seeds or the whole input in fixtures (${text})`,
+					}); the case cannot reach what it tests until its fixtures give what the handler needs: a picked person in members, a row of its object in rows, the state in seeds, a file it accepts in files, the whole input in fixtures, or the refusal it answers in refusals (${text})`,
 			)
 		}
 		return { status: response.status, text }
@@ -494,6 +594,7 @@ export function endpointAccessKit<DB, P>(app: ContractImplementation<AnyContract
 		field: SchemaShape | undefined,
 		seed: Seed,
 		input: Readonly<Record<string, unknown>>,
+		pinning: Pinning = NO_PINNING,
 	): Promise<Scopes> => {
 		const named = rowFields(input)
 		const owner = ownerOf(dimension)
@@ -514,7 +615,7 @@ export function endpointAccessKit<DB, P>(app: ContractImplementation<AnyContract
 				},
 			}
 		}
-		const worlds = await postgres.seedWorlds(tables, owner, seed)
+		const worlds = pinned(await postgres.seedWorlds(tables, owner, seed, pinning.pins), pinning)
 		const own = await rowsIn(worlds.own, named)
 		const other = await rowsIn(worlds.other, named)
 		return {
@@ -569,14 +670,17 @@ export function endpointAccessKit<DB, P>(app: ContractImplementation<AnyContract
 	 * For a report `in` `dimension`: one row in each scope of every table that lies in it, the table that owns it with
 	 * `seed`. Each side's targets are its rows' values of `dimension`, and each caller holds all of them.
 	 */
-	const inScopesOf = async (action: string, dimension: string, field: SchemaShape | undefined, seed: Seed) => {
+	const inScopesOf = async (action: string, dimension: string, field: SchemaShape | undefined, seed: Seed, pinning: Pinning = NO_PINNING) => {
 		const own: InTarget[] = []
 		const other: InTarget[] = []
 		const values: string[] = []
 		for (const name of tableNames) {
 			const mode = policies[name]?.scope.mode
 			if (mode !== 'dimension' && mode !== 'child') continue
-			const worlds = await postgres.seedWorlds(tables, name, name === ownerOf(dimension) ? seed : {})
+			const owned = name === ownerOf(dimension)
+			const worlds = owned
+				? pinned(await postgres.seedWorlds(tables, name, seed, pinning.pins), pinning)
+				: await postgres.seedWorlds(tables, name)
 			const ownAt = worlds.own.chain.findIndex((link) => link.type === dimension)
 			const otherAt = worlds.other.chain.findIndex((link) => link.type === dimension)
 			const ownValue = worlds.own.chain[ownAt]?.value
@@ -588,7 +692,7 @@ export function endpointAccessKit<DB, P>(app: ContractImplementation<AnyContract
 			}
 		}
 		if (own.length === 0) {
-			const scopes = await scopesOf(action, dimension, field, seed, {})
+			const scopes = await scopesOf(action, dimension, field, seed, {}, pinning)
 			return { own: [scopes.own], other: [scopes.other], values: scopes.other.values }
 		}
 		return { own, other, values }
@@ -711,6 +815,7 @@ export function endpointAccessKit<DB, P>(app: ContractImplementation<AnyContract
 		mount: string,
 		seed: Seed,
 		input: Readonly<Record<string, unknown>>,
+		pinning: Pinning,
 	): Promise<{ readonly fetch: RpcFetch; readonly rows: Readonly<Record<string, string>> }> => {
 		const access = row.access
 		if (access.form !== 'on') {
@@ -720,7 +825,7 @@ export function endpointAccessKit<DB, P>(app: ContractImplementation<AnyContract
 		if (owner === undefined) {
 			throw new Error(`${row.id}: no table owns ${access.dimension}, so no link can be bound to one`)
 		}
-		const { own } = await postgres.seedWorlds(tables, owner, seed)
+		const { own } = pinned(await postgres.seedWorlds(tables, owner, seed, pinning.pins), pinning)
 		const holder = kit.testCaller([{ action: row.action, scope: { type: access.dimension, value: own.key } }], {
 			kind: 'link',
 			link: { mount, chain: own.chain },
@@ -737,6 +842,9 @@ export function endpointAccessKit<DB, P>(app: ContractImplementation<AnyContract
 	// the call and the runs it kicked are over. A list per call, so a concurrent case never removes the rows another
 	// was given; the generated cases run one after another, since a row a required foreign key needed is shared.
 	const accessKitOf = (removals: (() => Promise<void>)[]): EndpointAccessKit => {
+		/** The pins of `endpoint`, whose seeded rows this call removes once it is over. */
+		const pinningOf = (endpoint: string): Pinning => ({ pins: options.pins?.[endpoint] ?? {}, removals })
+
 		/** One row of each application table `appRows` names, for this call only. */
 		const seedAppRows = async (appRows: AppRows): Promise<void> => {
 			if (Object.keys(appRows).length === 0) return
@@ -750,7 +858,7 @@ export function endpointAccessKit<DB, P>(app: ContractImplementation<AnyContract
 				if (access.form !== 'on' && access.form !== 'in') {
 					throw new Error(`${endpoint} has the access form ${access.form}; only on and in name an object or a scope value`)
 				}
-				const scopes = await scopesOf(action, access.dimension, fieldOf(row.input, access.from), seed, input)
+				const scopes = await scopesOf(action, access.dimension, fieldOf(row.input, access.from), seed, input, pinningOf(endpoint))
 				const asked = addressing(input, access.from, scopes.other)
 				const { status } = await ask(row, holding(row, input, scopes.own.grants, scopes.own.chain), asked, scopes.own.chain)
 				return { status }
@@ -760,12 +868,12 @@ export function endpointAccessKit<DB, P>(app: ContractImplementation<AnyContract
 				const { action, access } = row
 				if (access.form === 'in') {
 					await seedAppRows(appRows)
-					const scopes = await inScopesOf(action, access.dimension, fieldOf(row.input, access.from), seed)
+					const scopes = await inScopesOf(action, access.dimension, fieldOf(row.input, access.from), seed, pinningOf(endpoint))
 					const grants = (targets: readonly InTarget[]): Grant[] =>
 						targets.flatMap(({ target, chain }) => holding(row, input, [{ action, scope: { type: access.dimension, value: target } }], chain))
 					const marks: string[] = []
 					for (const side of scopes.other) {
-						const answer = await ask(row, grants(scopes.other), addressing(input, access.from, side), side.chain)
+						const answer = await ask(row, grants(scopes.other), addressing(input, access.from, side), side.chain, 'declared')
 						marks.push(...answer.marks)
 					}
 					const answers = []
@@ -779,14 +887,17 @@ export function endpointAccessKit<DB, P>(app: ContractImplementation<AnyContract
 				}
 				await seedAppRows(appRows)
 				const scopes = access.form === 'on'
-					? await scopesOf(action, access.dimension, fieldOf(row.input, access.from), seed, input)
+					? await scopesOf(action, access.dimension, fieldOf(row.input, access.from), seed, input, pinningOf(endpoint))
 					: await listScopesOf(action, access.dimension)
 				const from = access.form === 'on' ? access.from : null
+				// The other scope asks first, to fill whatever a handler keeps between requests; its pins differ from the own
+				// scope's, so a refusal the fixtures declare is its answer too. The own scope's answer is the one checked.
 				const other = await ask(
 					row,
 					holding(row, input, scopes.other.grants, scopes.other.chain),
 					addressing(input, from, scopes.other),
 					scopes.other.chain,
+					'declared',
 				)
 				const answer = await ask(
 					row,
@@ -804,16 +915,17 @@ export function endpointAccessKit<DB, P>(app: ContractImplementation<AnyContract
 				}
 				await seedAppRows(appRows)
 				if (row.link !== null) {
-					const holder = await linkHolder(row, row.link, seed, input)
-					const { status } = await askAs(row, holder.fetch, { ...input, ...holder.rows })
+					const holder = await linkHolder(row, row.link, seed, input, pinningOf(endpoint))
+					const { status } = await askAs(row, holder.fetch, { ...input, ...holder.rows }, 'declared')
 					return { status }
 				}
-				const scopes = await scopesOf(action, access.dimension, fieldOf(row.input, access.from), seed, input)
+				const scopes = await scopesOf(action, access.dimension, fieldOf(row.input, access.from), seed, input, pinningOf(endpoint))
 				const { status } = await ask(
 					row,
 					holding(row, input, scopes.own.grants, scopes.own.chain),
 					addressing(input, access.from, scopes.own),
 					scopes.own.chain,
+					'declared',
 				)
 				return { status }
 			},
@@ -864,7 +976,7 @@ export function endpointAccessKit<DB, P>(app: ContractImplementation<AnyContract
 				}
 				const { access } = named
 				if (access.form === 'on' || access.form === 'in') {
-					const scopes = await scopesOf(named.action, access.dimension, fieldOf(named.input, access.from), seed, input)
+					const scopes = await scopesOf(named.action, access.dimension, fieldOf(named.input, access.from), seed, input, pinningOf(endpoint))
 					asked = addressing(asked, access.from, scopes.other)
 					grants.push(...scopes.own.grants)
 				}

package/src/testing/isolation.ts

@@ -6,7 +6,14 @@ import { refuseInProduction } from '@fabrika/db/production'
 
 refuseInProduction('@fabrika/app/testing/isolation')
 
-export { type DeniedOutcome, type EndpointAccessKit, endpointAccessKit, type LeakOutcome, type ReachOutcome } from './endpoint-access'
+export {
+	type DeniedOutcome,
+	type EndpointAccessKit,
+	endpointAccessKit,
+	type EndpointAccessOptions,
+	type LeakOutcome,
+	type ReachOutcome,
+} from './endpoint-access'
 export {
 	type AppCaller,
 	type AppCountOutcome,

package/types/src/build.d.ts

@@ -10,7 +10,7 @@ export declare const GENERATED_MIGRATIONS_FILE = "fabrika/migrations.generated.t
 export declare const MIGRATIONS_DIRECTORY = "db/migrations";
 export type EntryRuntime = 'bun' | 'cloudflare';
 export * from './build-recipe.js';
-export { CLOUDFLARE_APPLICATION_BINDING, CLOUDFLARE_APPLICATION_CLASS, CLOUDFLARE_FILES_BINDING } from './cloudflare/names.js';
+export { CLOUDFLARE_APPLICATION_BINDING, CLOUDFLARE_APPLICATION_CLASS, CLOUDFLARE_ASSETS_BINDING, CLOUDFLARE_FILES_BINDING, } from './cloudflare/names.js';
 /** The entrypoint source for one runtime. */
 export declare function generatedEntry(runtime: EntryRuntime): string;
 /** Writes the entrypoint under `root` and returns its path; the Cloudflare one also writes the migrations module it imports. */

package/types/src/cloudflare/bindings.d.ts

@@ -18,6 +18,12 @@ export declare function bindingTerminals(binding: unknown): IamTerminalRpc | und
  * An answer that is not IAM's decided outcome throws: "IAM could not be asked".
  */
 export declare function bindingWorkloadTokens(binding: unknown): WorkloadTokenSource | undefined;
+/**
+ * The SPA and link mounts' files from the Workers Assets binding, whose directory mirrors the request paths: the mount
+ * `/admin` reads `admin/…` of it, the root mount the rest (the Cloudflare deploy stages each mount's `dir` there). A page
+ * route that names no file (`isPageRoute`) gets the mount's `index.html`, as `diskAssets` serves it: Workers Assets
+ * answers `<prefix>/` with it. A missing asset stays 404.
+ */
 export declare function bindingAssets(binding: unknown): SpaAssets | undefined;
 /**
  * The service bindings to owners' proxy Workers (`FABRIKA_CONNECT_<IMPORT>`), which `captureEnvironment` keeps from

package/types/src/cloudflare/names.d.ts

@@ -4,3 +4,8 @@ export declare const CLOUDFLARE_APPLICATION_CLASS = "FabrikaApplication";
 export declare const CLOUDFLARE_APPLICATION_BINDING = "FABRIKA_APPLICATION";
 /** The R2 bucket binding of the environment's stored files. */
 export declare const CLOUDFLARE_FILES_BINDING = "FABRIKA_FILES";
+/**
+ * The Workers Assets binding the SPA and link mounts serve their files from. Its directory mirrors the request paths:
+ * the mount `/admin` serves `<directory>/admin/…`, the root mount `<directory>/…`.
+ */
+export declare const CLOUDFLARE_ASSETS_BINDING = "ASSETS";

package/types/src/contract/group.d.ts

@@ -74,7 +74,15 @@ export type SignsField<Sg, Purposes extends string> = {
  * `fetch` refuses any other while the site runs; a public procedure declares none.
  */
 export interface EgressField {
-    readonly egress?: readonly `https://${string}`[];
+    readonly egress?: readonly `https://${string}`[] | Unavailable<"egress: 'public' is a cron job's only: record a row and kick a job that declares it">;
+}
+/**
+ * A cron job's `egress`: its exact HTTPS origins, or `'public'`, every public host over HTTPS or HTTP on its default
+ * port, for a job that calls the websites its operators name (ADR-0070). The guard refuses IP addresses, local and
+ * internal names and the installation's own hosts, checks each redirect, and bounds each request's time and body.
+ */
+export interface JobEgressField {
+    readonly egress?: readonly `https://${string}`[] | 'public';
 }
 /** Each purpose `signs` names is one of `defineApp`'s `tokens`. */
 type KnownPurposes<Sg, Purposes extends string> = Sg extends readonly (infer P extends string)[] ? [Exclude<P, Purposes>] extends [never] ? LiteralList<Sg> : Unavailable<`signs names ${ListOf<Exclude<P, Purposes>>}, which defineApp's tokens do not declare`> : unknown;

package/types/src/contract/kit.d.ts

@@ -4,7 +4,7 @@ import type { z } from 'zod/v4';
 import type { Declared, JobKitContext, KickContext, KitImports, KitTypes, NoTablesIndex, SqlMode, TokensContext, WebhookKitContext } from './context';
 import { type ExportAccessDeclaration, type ImportDeclaration, type LinkAccessDeclaration, type ProcedureType } from './declaration';
 import { type Contract, type CreatableDimension, type CronJob, type Export, type InputSchema, type JobLimitsOption, type Kit, type LinkMount, type NotLoose, type Path, type ProcedureTree, type RpcMount, type Schema, type Surface, type WebhookMount } from './define';
-import type { DeclaredFields, EgressField, Endpoint, ExportKit, Group, GroupBuild, GroupInput, GroupKit, KicksField, LimitsOption, LinkGroupKit, ListOf, PendingIn, SignsField } from './group';
+import type { DeclaredFields, EgressField, Endpoint, ExportKit, Group, GroupBuild, GroupInput, GroupKit, JobEgressField, KicksField, LimitsOption, LinkGroupKit, ListOf, PendingIn, SignsField } from './group';
 import type { TokenPurposes } from './token';
 import type { AnyAppVocabulary, AppVocabulary } from './vocabulary';
 /** Fields a builder sets itself: an options object that carries one does not type-check. */
@@ -31,7 +31,7 @@ export type CronOptions<Acts, S, U, Is, Ix extends AnyDbIndex, M = never, Ks = n
     readonly actions: Acts;
     readonly limits?: JobLimitsOption;
     readonly retries?: number;
-} & DeclaredFields<S, U, never, Is, Ix> & MailerField<M> & KicksField<Ks> & SignsField<Sg, Purposes> & EgressField;
+} & DeclaredFields<S, U, never, Is, Ix> & MailerField<M> & KicksField<Ks> & SignsField<Sg, Purposes> & JobEgressField;
 /** The mail transport a job reaches, inferred from its optional field and then required, like a declared field. */
 type MailerField<M> = {
     /** `'installation'`: the installation's mail transport; `'own'`: the application's own. */

package/types/src/disk-assets.d.ts

@@ -1,3 +1,6 @@
 import type { SpaAssets } from './implement/dispatch.js';
-/** Serves each SPA mount from its build directory under `root`; a path that names no file gets the SPA's `index.html`. */
+/**
+ * Serves each SPA mount from its build directory under `root`; a page route that names no file gets the SPA's
+ * `index.html` (`isPageRoute`), and a missing asset is 404.
+ */
 export declare function diskAssets(root: string): SpaAssets;

package/types/src/implement/boot.d.ts

@@ -9,6 +9,7 @@ import { type ContractJobs, type HandlerErrorSink } from '../jobs/runner';
 import type { ChallengeFetch, ChallengeWork } from './challenge';
 import { type ConnectFetch } from './connect';
 import { type SpaAssets } from './dispatch';
+import { type HostResolver } from './egress';
 import type { CapturedEnvironment } from './environment';
 import type { ContractImplementation } from './implement';
 import { type WorkloadTokenSource } from './workload';
@@ -57,6 +58,11 @@ export interface BootOptions {
      * with a job or a webhook does not boot.
      */
     readonly workloadTokens?: WorkloadTokenSource;
+    /**
+     * Resolves a host name to its addresses, which the Bun adapter supplies (`node:dns`): a cron job's public egress then
+     * refuses a public name of a private address before each hop. A Worker exposes no resolution and passes none.
+     */
+    readonly resolveHost?: HostResolver;
     /** What posts a report to Operations' ingest; `fetch` by default. */
     readonly operationsFetch?: (request: Request) => Promise<Response>;
     /** What asks a public procedure's challenge provider to verify a token; `fetch` by default. */

package/types/src/implement/capability.d.ts

@@ -11,6 +11,8 @@ export declare const CAPABILITY_REFUSALS: {
     readonly undeclared_binding: "the site named a webhook it does not declare in binds";
     readonly undeclared_signs: "the site signed a token of a purpose it does not declare in signs, or for longer than the purpose allows";
     readonly undeclared_egress: "the site called an origin it does not declare in egress";
+    readonly refused_egress: "the site's public egress refused the host: an IP address, a local or internal name, a non-default port, a host of this installation, or a name that resolves to a private address";
+    readonly oversized_egress: "a response to the site's public egress was larger than it reads";
     readonly wrong_binding: "a webhook binding was handed a capability of another kind or dimension than the webhook is bound to";
     readonly missing_id: "the job named an object without an id";
     readonly wrong_capability: "an operation was handed a capability of another dimension or action than it needs";

package/types/src/implement/dispatch.d.ts

@@ -11,6 +11,7 @@ import type { BrowserConfig } from './browser-config';
 import { type CapabilityMint } from './capability';
 import type { ChallengeIssuer } from './challenge';
 import { type ImportWire } from './connect';
+import { type SiteEgress } from './egress';
 import type { FailureReports } from './failures';
 import { type HeaderPolicy } from './headers';
 import type { ContractDatabase } from './implement';
@@ -66,7 +67,7 @@ export type ServedEndpoint = {
     /** A staged-kit site, which gets `ctx.db`; a handler `implement` bound has none. */
     readonly site?: ServedSite;
     /** The origins a staged-kit site's `fetch` reaches while its handler runs; absent for a handler `implement` bound. */
-    readonly egress?: readonly string[];
+    readonly egress?: SiteEgress;
     /** Its buckets and time limit; without them (a generated endpoint) no bucket and the request budget. */
     readonly admission?: ProcedureAdmission;
     /** A POST's `query`, parsed from the URL beside the body: its schema and its shape. */

package/types/src/implement/egress.d.ts

@@ -1,5 +1,40 @@
+import { type DeclaredEgress } from '@fabrika/auth-core';
+/** The addresses a host name resolves to, where the runtime exposes resolution: Bun's `node:dns`, never a Worker. */
+export type HostResolver = (hostname: string) => Promise<readonly string[]>;
+/** What public egress refuses beyond what a URL alone shows (`publicEgressRefusal`). */
+export interface PublicEgressRules {
+    /** The installation's own hosts, normalized: every host a framework variable names, and `FABRIKA_EGRESS_REFUSED_HOSTS`. */
+    readonly refusedHosts: ReadonlySet<string>;
+    /** Resolves each hop's host before it is sent, so a public name of a private address is refused; `null` on Cloudflare. */
+    readonly resolve: HostResolver | null;
+}
+/** What one site's `fetch` reaches: its declared origins, or the rules of public egress. */
+export type SiteEgress = readonly string[] | PublicEgressRules;
+/**
+ * The bounds of one request under public egress, the redirects it follows included. The handler's own signal still
+ * aborts it sooner (`ctx.signal`, an `AbortSignal.timeout` of its own).
+ */
+export declare const PUBLIC_EGRESS_LIMITS: {
+    /** One request, its redirects and the reading of its body included: the abort also stops a body still streaming. */
+    readonly timeoutMs: 60000;
+    /** One response's body as the handler reads it; a larger one is refused, by its `Content-Length` or while it streams. */
+    readonly maxResponseBytes: number;
+    /** The redirects one request follows when its `redirect` mode is `follow`, each hop checked again. */
+    readonly maxRedirects: 10;
+};
 /** Runs a site's handler: every `fetch` it starts reaches only `egress`. */
-export declare function runAsSite<T>(site: string, egress: readonly string[], work: () => Promise<T>): Promise<T>;
+export declare function runAsSite<T>(site: string, egress: SiteEgress, work: () => Promise<T>): Promise<T>;
+/**
+ * The egress a site runs with: its declared origins, or `rules` for `'public'`. Only a cron job's runner holds rules; a
+ * site run without them reaches nothing, though the build lets no other site declare `'public'`.
+ */
+export declare function siteEgress(declared: DeclaredEgress, rules: PublicEgressRules | null): SiteEgress;
+/**
+ * The rules of public egress in one environment: the hosts its framework variables name (IAM, Operations, its own
+ * origin, the platform's receivers, the object store), the installation hosts Control hands it, and the resolver the
+ * runtime adapter supplies.
+ */
+export declare function publicEgressRules(framework: Readonly<Record<string, string>>, resolve: HostResolver | null): PublicEgressRules;
 /**
  * `facility` with each of its methods run outside any site's scope: a framework facility a handler calls, whose own
  * requests are the platform's, not the site's.

package/types/src/implement/invocation.d.ts

@@ -1,4 +1,4 @@
-import { type ContractArtifact, type JobMailer } from '@fabrika/auth-core';
+import { type ContractArtifact, type DeclaredEgress, type JobMailer } from '@fabrika/auth-core';
 import { type DataAccess, type DataHandles, type FileBinding, type Session, type SqlTag } from '@fabrika/db/framework';
 import type { DataKind, UnscopedMode } from '@fabrika/db/tables';
 import type { SqlMode } from '../contract/context';
@@ -16,8 +16,8 @@ export interface SiteDeclaration {
     readonly binds: string | null;
     /** The token purposes `ctx.tokens.sign` may sign. */
     readonly signs: readonly string[];
-    /** The HTTPS origins the global `fetch` reaches while the site's handler runs. */
-    readonly egress: readonly string[];
+    /** The HTTPS origins the global `fetch` reaches while the site's handler runs, or `'public'`: every public host (a cron job). */
+    readonly egress: DeclaredEgress;
 }
 /** A public procedure's reach: the texts the verified signed tokens of its request carry, which name the rows it changes. */
 export interface PublicReach {

package/types/src/jobs/runner.d.ts

@@ -4,6 +4,7 @@ import type { CapabilityAuthority } from '@fabrika/db/capability';
 import { type DataAccess, type FrameworkTables } from '@fabrika/db/framework';
 import { type StoredFileKinds } from '../files/kinds';
 import { type CapabilityMint } from '../implement/capability';
+import { type PublicEgressRules } from '../implement/egress';
 import type { ContractDatabase } from '../implement/implement';
 import type { SignedTokens } from '../implement/tokens';
 import { type AppUrl } from '../implement/urls';
@@ -130,6 +131,8 @@ export interface JobBindingInput {
     readonly tokens?: SignedTokens;
     /** `ctx.url`: absolute links to the application's own procedures; without it every link is refused. */
     readonly url?: AppUrl;
+    /** The rules of public egress, which `boot` reads from the environment; without them a public job reaches nothing. */
+    readonly publicEgress?: PublicEgressRules;
 }
 export interface BoundJobs {
     readonly jobs: ContractJobs;

package/types/src/spa-fallback.d.ts

@@ -0,0 +1,2 @@
+/** A GET or HEAD whose last path segment has no extension, or one that asks for HTML (a navigation to `/notes/v1.2`). */
+export declare function isPageRoute(request: Request): boolean;

package/types/src/testing/endpoint-access.d.ts

@@ -78,6 +78,30 @@ export interface EndpointAccessKit {
      */
     anyone(endpoint: string, input: Readonly<Record<string, unknown>>): Promise<ReachOutcome>;
 }
+export interface EndpointAccessOptions {
+    /**
+     * The file every case of an endpoint sends in a file field instead of the kit's sample, by endpoint id and input
+     * field: a file of the application's repository that a handler inspecting the content accepts (a valid package). Its
+     * type is the first of the field's kind that its bytes are; a file of none of them throws. `files` of the fixtures.
+     */
+    readonly files?: Readonly<Record<string, Readonly<Record<string, URL>>>>;
+    /**
+     * The error types of the refusals (400) an endpoint's handler answers its own object with when the case's input meets
+     * no domain rule the kit can satisfy, by endpoint id: such a 400 is the handler's own answer, so the request passed
+     * the access form, and the endpoint's own case gets it as `{ status: 400 }` instead of failing; so does the other
+     * scope's request a leak case makes first. The own scope's answer of a leak case, and a global or capability case,
+     * still throw on it (an answer that holds nothing proves no isolation), so does any other 400, and an input the schema
+     * refuses (`validation`) always does. `refusals` of the fixtures.
+     */
+    readonly refusals?: Readonly<Record<string, readonly string[]>>;
+    /**
+     * Known values for text columns of the row the endpoint addresses (the row of the table that owns its dimension), by
+     * endpoint id: the value in the own scope's row, and `<value>-other` in the other scope's, which counts among the
+     * other scope's values a leak shows. For a handler whose rule ties a column to the input or a file fixture (a package
+     * that names the skill's slug). `pins` of the fixtures.
+     */
+    readonly pins?: Readonly<Record<string, Readonly<Record<string, string>>>>;
+}
 export type Grant = {
     readonly action: string;
     readonly scope: {
@@ -104,4 +128,4 @@ export declare const managerGrants: (artifact: Pick<ContractArtifact, "roles">,
  * The endpoint access kit of `app`, whose data layer is `scoped(tables)`, over `postgres`. It boots `app` once, so the
  * application's layer is bound here and nowhere else in the process.
  */
-export declare function endpointAccessKit<DB, P>(app: ContractImplementation<AnyContract>, tables: Tables<DB, P>, postgres: TestDatabase): EndpointAccessKit;
+export declare function endpointAccessKit<DB, P>(app: ContractImplementation<AnyContract>, tables: Tables<DB, P>, postgres: TestDatabase, options?: EndpointAccessOptions): EndpointAccessKit;

package/types/src/testing/isolation.d.ts

@@ -1,3 +1,3 @@
-export { type DeniedOutcome, type EndpointAccessKit, endpointAccessKit, type LeakOutcome, type ReachOutcome } from './endpoint-access';
+export { type DeniedOutcome, type EndpointAccessKit, endpointAccessKit, type EndpointAccessOptions, type LeakOutcome, type ReachOutcome, } from './endpoint-access';
 export { type AppCaller, type AppCountOutcome, type AppIsolationKit, appPolicyIsolationKit, type ChildIsolationRow, type CountOutcome, type IsolationOutcome, type IsolationRow, type ListOutcome, type MisuseOutcome, type PolicyIsolationKit, policyIsolationKit, type ReadOutcome, } from './policy-isolation';
 export { afterAll, describe, expect, test } from './runner';