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

package/src/disk-assets.ts

@@ -4,8 +4,12 @@
 import { rawRequestTarget } from '@fabrika/auth-core'
 import { join, resolve, sep } from 'node:path'
 import type { SpaAssets } from './implement/dispatch.js'
+import { isPageRoute } from './spa-fallback.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 function diskAssets(root: string): SpaAssets {
 	return {
 		async serve(mount, request) {
@@ -15,8 +19,9 @@ export function diskAssets(root: string): SpaAssets {
 			// The path is canonical, so every segment decodes and none is `.` or `..`.
 			const file = join(dir, ...relative.split('/').filter((segment) => segment !== '').map((segment) => decodeURIComponent(segment)))
 			const candidate = file.startsWith(`${dir}${sep}`) ? Bun.file(file) : null
-			const served = candidate !== null && (await candidate.exists()) ? candidate : Bun.file(join(dir, 'index.html'))
-			if (!(await served.exists())) {
+			const found = candidate !== null && (await candidate.exists()) ? candidate : null
+			const served = found ?? (isPageRoute(request) ? Bun.file(join(dir, 'index.html')) : null)
+			if (served === null || !(await served.exists())) {
 				return new Response('Not found', { status: 404 })
 			}
 			return new Response(served)

package/src/implement/boot.ts

@@ -65,7 +65,7 @@ import {
 	type ServedSite,
 	type SpaAssets,
 } from './dispatch'
-import { installEgressGuard, platformCall, platformFacility } from './egress'
+import { type HostResolver, installEgressGuard, platformCall, platformFacility, publicEgressRules, type SiteEgress, siteEgress } from './egress'
 import type { CapturedEnvironment } from './environment'
 import { FailureReports } from './failures'
 import { applicationPolicy } from './headers'
@@ -124,6 +124,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. */
@@ -460,8 +465,8 @@ function boundHandler(
 }
 
 /** The origins a staged-kit site's handler reaches, a kit without tables included; nothing for a bare handler. */
-function egressOf(bound: BoundHandler): { readonly egress?: readonly string[] } {
-	return !bound.site || bound.declaration === null ? {} : { egress: bound.declaration.egress }
+function egressOf(bound: BoundHandler): { readonly egress?: SiteEgress } {
+	return !bound.site || bound.declaration === null ? {} : { egress: siteEgress(bound.declaration.egress, null) }
 }
 
 /** A staged-kit contract's endpoint gets `ctx.links` only for the link mount it declares it `issues`. */
@@ -899,6 +904,7 @@ function bootOnce(app: ContractImplementation, options: BootOptions, binding: Bi
 		mail,
 		tokens,
 		url,
+		publicEgress: publicEgressRules(options.environment.framework, options.resolveHost ?? null),
 	}, problems)
 	for (const id of jobs.declared) {
 		declared.add(id)

package/src/implement/capability.ts

@@ -34,6 +34,9 @@ export const CAPABILITY_REFUSALS = {
 	undeclared_binding: 'the site named a webhook it does not declare in binds',
 	undeclared_signs: 'the site signed a token of a purpose it does not declare in signs, or for longer than the purpose allows',
 	undeclared_egress: 'the site called an origin it does not declare in egress',
+	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",
+	oversized_egress: "a response to the site's public egress was larger than it reads",
 	wrong_binding: 'a webhook binding was handed a capability of another kind or dimension than the webhook is bound to',
 	missing_id: 'the job named an object without an id',
 	wrong_capability: 'an operation was handed a capability of another dimension or action than it needs',

package/src/implement/dispatch.ts

@@ -84,7 +84,7 @@ import {
 } from './capability'
 import type { ChallengeIssuer, ChallengeVerifier } from './challenge'
 import { connectContext, type ImportWire } from './connect'
-import { runAsSite } from './egress'
+import { runAsSite, type SiteEgress, siteEgress } from './egress'
 import type { FailureReports } from './failures'
 import { ServerFault } from './faults'
 import { type HeaderPolicy, withHeaderPolicy } from './headers'
@@ -167,7 +167,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. */
@@ -1087,7 +1087,7 @@ export class ContractRuntime {
 							kick: kicks.kick,
 						})
 						const args = { input, ctx, ...(query === undefined ? {} : { query }) }
-						return await runAsSite(`'${served.row.id}'`, served.site.declaration.egress, async () => await served.handler(args))
+						return await runAsSite(`'${served.row.id}'`, siteEgress(served.site.declaration.egress, null), async () => await served.handler(args))
 					})
 				} finally {
 					frame.end()
@@ -1234,7 +1234,7 @@ export class ContractRuntime {
 						if (site === undefined) {
 							await served.handler(args)
 						} else {
-							await runAsSite(`webhook '${served.webhook}'`, site.egress, async () => await served.handler(args))
+							await runAsSite(`webhook '${served.webhook}'`, siteEgress(site.egress, null), async () => await served.handler(args))
 						}
 					})
 				} finally {

package/src/implement/egress.ts

@@ -1,23 +1,107 @@
-// `egress`: while a site's handler runs, the global `fetch` reaches only the HTTPS origins the site declares. It stops a
-// mistake and makes a bypass conspicuous; it is not a sandbox (ADR-0012 §8): code that kept the `fetch` it found before
-// boot, or opens its own sockets, escapes it. The framework's own facilities (mail, connectors, IAM, the object store)
-// run outside the site's scope, under their own declarations.
+// `egress`: while a site's handler runs, the global `fetch` reaches only the HTTPS origins the site declares, or, for a
+// cron job that declares `egress: 'public'`, only public hosts (ADR-0070). It stops a mistake and makes a bypass
+// conspicuous; it is not a sandbox (ADR-0012 §8): code that kept the `fetch` it found before boot, or opens its own
+// sockets, escapes it. The framework's own facilities (mail, connectors, IAM, the object store) run outside the site's
+// scope, under their own declarations.
 
+import {
+	type DeclaredEgress,
+	FABRIKA_EGRESS_REFUSED_HOSTS,
+	isPublicAddress,
+	normalizedHost,
+	PUBLIC_EGRESS,
+	publicEgressRefusal,
+} from '@fabrika/auth-core'
 import { AsyncLocalStorage } from 'node:async_hooks'
 import { CapabilityRefusedError } from './capability'
 
+/** 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 const PUBLIC_EGRESS_LIMITS = {
+	/** One request, its redirects and the reading of its body included: the abort also stops a body still streaming. */
+	timeoutMs: 60_000,
+	/** One response's body as the handler reads it; a larger one is refused, by its `Content-Length` or while it streams. */
+	maxResponseBytes: 16 * 1024 * 1024,
+	/** The redirects one request follows when its `redirect` mode is `follow`, each hop checked again. */
+	maxRedirects: 10,
+} as const
+
 interface EgressScope {
 	/** The site, as a refusal names it. */
 	readonly site: string
 	readonly origins: ReadonlySet<string>
+	/** Public egress: `null` for a site that declares origins, or none. */
+	readonly open: PublicEgressRules | null
 }
 
 const scope = new AsyncLocalStorage<EgressScope>()
 const guards = new WeakSet<object>()
 
 /** Runs a site's handler: every `fetch` it starts reaches only `egress`. */
-export function runAsSite<T>(site: string, egress: readonly string[], work: () => Promise<T>): Promise<T> {
-	return scope.run({ site, origins: new Set(egress) }, work)
+export function runAsSite<T>(site: string, egress: SiteEgress, work: () => Promise<T>): Promise<T> {
+	return isOrigins(egress)
+		? scope.run({ site, origins: new Set(egress), open: null }, work)
+		: scope.run({ site, origins: new Set(), open: egress }, work)
+}
+
+/**
+ * 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 function siteEgress(declared: DeclaredEgress, rules: PublicEgressRules | null): SiteEgress {
+	return declared === PUBLIC_EGRESS ? (rules ?? []) : declared
+}
+
+function isOrigins(egress: SiteEgress): egress is readonly string[] {
+	return Array.isArray(egress)
+}
+
+/**
+ * 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 function publicEgressRules(framework: Readonly<Record<string, string>>, resolve: HostResolver | null): PublicEgressRules {
+	const hosts = new Set<string>()
+	for (const [name, value] of Object.entries(framework)) {
+		if (name === FABRIKA_EGRESS_REFUSED_HOSTS) {
+			for (const host of value.split(',')) {
+				const normalized = normalizedHost(host.trim())
+				if (normalized !== '') hosts.add(normalized)
+			}
+			continue
+		}
+		const host = urlHost(value)
+		if (host !== null) hosts.add(host)
+	}
+	return { refusedHosts: hosts, resolve }
+}
+
+/** The host of a framework variable's value when it is an http(s) URL, such as an origin or a DSN; `null` otherwise. */
+function urlHost(value: string): string | null {
+	const text = value.trim()
+	if (!/^https?:\/\//i.test(text)) return null
+	try {
+		return normalizedHost(new URL(text).hostname)
+	} catch {
+		return null
+	}
 }
 
 /**
@@ -41,6 +125,8 @@ export function platformCall<T>(work: () => T): T {
 	return scope.exit(work)
 }
 
+type Fetch = (input: string, init: RequestInit) => Promise<Response>
+
 /**
  * Wraps the global `fetch` in the guard, once: a `fetch` that is already a guard stays. A test that replaces `fetch`
  * after boot replaces the guard with it.
@@ -50,15 +136,20 @@ export function installEgressGuard(): void {
 	if (guards.has(current)) {
 		return
 	}
+	const send: Fetch = (input, init) => current(input, init)
 	const guarded = Object.assign(
 		(input: string | URL | Request, init?: RequestInit): Promise<Response> => {
 			const running = scope.getStore()
 			if (running === undefined) {
 				return current(input, init)
 			}
+			if (running.open !== null) {
+				return publicFetch(send, running.site, running.open, input, init)
+			}
 			const origin = originOf(input)
 			if (origin !== null && running.origins.has(origin)) {
-				return current(input, init)
+				// Only the standard fields: a runtime's own (Bun's `unix`, `proxy`, `tls`) would send the request elsewhere.
+				return current(input, standardInit(init))
 			}
 			return Promise.reject(
 				new CapabilityRefusedError(
@@ -69,12 +160,47 @@ export function installEgressGuard(): void {
 				),
 			)
 		},
-		{ preconnect: current.preconnect },
+		{
+			// Inside a site's scope a preconnect reaches only a declared origin; public egress, which cannot check a hop
+			// before it connects, refuses every one.
+			preconnect: (...args: Parameters<typeof current.preconnect>): void => {
+				const running = scope.getStore()
+				if (running !== undefined) {
+					const origin = originOf(args[0])
+					if (running.open !== null || origin === null || !running.origins.has(origin)) {
+						throw new CapabilityRefusedError(
+							running.open === null ? 'undeclared_egress' : 'refused_egress',
+							`${running.site} preconnects to ${origin ?? 'a URL that is not absolute'}, which its egress does not reach`,
+						)
+					}
+				}
+				if (typeof current.preconnect === 'function') current.preconnect(...args)
+			},
+		},
 	)
 	guards.add(guarded)
 	globalThis.fetch = guarded
 }
 
+/** `init` with the fields of the Fetch standard only. */
+function standardInit(init: RequestInit | undefined): RequestInit | undefined {
+	if (init === undefined) return undefined
+	return {
+		...(init.method === undefined ? {} : { method: init.method }),
+		...(init.headers === undefined ? {} : { headers: init.headers }),
+		...(init.body === undefined ? {} : { body: init.body }),
+		...(init.redirect === undefined ? {} : { redirect: init.redirect }),
+		...(init.signal === undefined ? {} : { signal: init.signal }),
+		...(init.keepalive === undefined ? {} : { keepalive: init.keepalive }),
+		...(init.integrity === undefined ? {} : { integrity: init.integrity }),
+		...(init.referrer === undefined ? {} : { referrer: init.referrer }),
+		...(init.referrerPolicy === undefined ? {} : { referrerPolicy: init.referrerPolicy }),
+		...(init.cache === undefined ? {} : { cache: init.cache }),
+		...(init.credentials === undefined ? {} : { credentials: init.credentials }),
+		...(init.mode === undefined ? {} : { mode: init.mode }),
+	}
+}
+
 function originOf(input: string | URL | Request): string | null {
 	try {
 		return new URL(typeof input === 'string' ? input : input instanceof URL ? input.href : input.url).origin
@@ -82,3 +208,210 @@ function originOf(input: string | URL | Request): string | null {
 		return null
 	}
 }
+
+const REDIRECTS: ReadonlySet<number> = new Set([301, 302, 303, 307, 308])
+/** The headers a redirect that turns a request into a `GET` drops with its body (Fetch, "HTTP-redirect fetch"). */
+const BODY_HEADERS = ['content-type', 'content-length', 'content-encoding', 'content-language', 'content-location']
+/**
+ * The request headers public egress never sends, on any hop: the Fetch standard's forbidden request headers (`Host`
+ * among them, which would route a request for a public name to another site at the same address), the forwarding
+ * headers a proxy trusts, and the platform's own `X-Fabrika-*`.
+ */
+const FORBIDDEN_HEADERS = [
+	'accept-charset',
+	'accept-encoding',
+	'access-control-request-headers',
+	'access-control-request-method',
+	'connection',
+	'content-length',
+	'cookie2',
+	'date',
+	'dnt',
+	'expect',
+	'forwarded',
+	'host',
+	'keep-alive',
+	'origin',
+	'referer',
+	'set-cookie',
+	'te',
+	'trailer',
+	'transfer-encoding',
+	'upgrade',
+	'via',
+	'x-http-method',
+	'x-http-method-override',
+	'x-method-override',
+	'x-real-ip',
+]
+const FORBIDDEN_HEADER_PREFIXES = ['proxy-', 'sec-', 'x-forwarded-', 'x-fabrika-']
+
+function withoutForbiddenHeaders(headers: Headers): Headers {
+	for (const name of [...headers.keys()]) {
+		if (FORBIDDEN_HEADERS.includes(name) || FORBIDDEN_HEADER_PREFIXES.some((prefix) => name.startsWith(prefix))) {
+			headers.delete(name)
+		}
+	}
+	return headers
+}
+
+/** The credentials a redirect to another origin drops. */
+const CREDENTIAL_HEADERS = ['authorization', 'proxy-authorization', 'cookie']
+
+/**
+ * One request under public egress. Every hop is sent with `redirect: 'manual'`, so the runtime follows no redirect the
+ * guard has not checked: the caller's `follow` is done here, at most `maxRedirects` hops, each host checked again;
+ * `manual` hands the caller the redirect, whose next `fetch` passes the guard again; `error` refuses one. The request
+ * is bounded in time and its answer's body in size.
+ */
+async function publicFetch(
+	send: Fetch,
+	site: string,
+	rules: PublicEgressRules,
+	input: string | URL | Request,
+	init?: RequestInit,
+): Promise<Response> {
+	const request = new Request(input, init)
+	// A timer the guard clears once the body is read, not `AbortSignal.timeout`: on workerd an uncleared timer keeps the
+	// Durable Object awake until it fires.
+	const deadline = new AbortController()
+	const timer = setTimeout(() => deadline.abort(new DOMException('public egress request timed out', 'TimeoutError')), PUBLIC_EGRESS_LIMITS.timeoutMs)
+	const done = (): void => clearTimeout(timer)
+	try {
+		return await follow(send, site, rules, request, AbortSignal.any([request.signal, deadline.signal]), done)
+	} catch (error) {
+		done()
+		throw error
+	}
+}
+
+/** The hops of one request; `done` clears its deadline once its last answer's body is read. */
+async function follow(
+	send: Fetch,
+	site: string,
+	rules: PublicEgressRules,
+	request: Request,
+	signal: AbortSignal,
+	done: () => void,
+): Promise<Response> {
+	const mode = request.redirect
+	let url = new URL(request.url)
+	let method = request.method
+	const headers = withoutForbiddenHeaders(new Headers(request.headers))
+	// Read once, so that a 307 or a 308 sends it again.
+	let body: ArrayBuffer | null = request.body === null ? null : await request.arrayBuffer()
+	for (let hop = 0;; hop++) {
+		await admit(site, rules, url)
+		const response = await send(url.href, { method, headers: new Headers(headers), body, redirect: 'manual', signal })
+		const location = REDIRECTS.has(response.status) ? response.headers.get('location') : null
+		if (location === null || mode === 'manual') {
+			return await capped(site, response, url, hop > 0, done)
+		}
+		await response.body?.cancel()
+		if (mode === 'error') {
+			throw new TypeError(`${site}: ${url.origin} redirects, and the request's redirect mode is 'error'`)
+		}
+		if (hop >= PUBLIC_EGRESS_LIMITS.maxRedirects) {
+			throw new TypeError(`${site}: more than ${PUBLIC_EGRESS_LIMITS.maxRedirects} redirects, the last from ${url.origin}`)
+		}
+		const next = new URL(location, url)
+		const toGet = (response.status === 303 && method !== 'GET' && method !== 'HEAD')
+			|| ((response.status === 301 || response.status === 302) && method === 'POST')
+		if (toGet) {
+			method = 'GET'
+			body = null
+			for (const name of BODY_HEADERS) headers.delete(name)
+		}
+		if (next.origin !== url.origin) {
+			for (const name of CREDENTIAL_HEADERS) headers.delete(name)
+		}
+		url = next
+	}
+}
+
+/** Refuses a hop public egress does not reach: by the URL, by the installation's hosts, by what its name resolves to. */
+async function admit(site: string, rules: PublicEgressRules, url: URL): Promise<void> {
+	const refusal = publicEgressRefusal(url, rules.refusedHosts)
+	if (refusal !== null) {
+		throw new CapabilityRefusedError('refused_egress', `${site} calls ${url.origin}, which public egress refuses: ${refusal}`)
+	}
+	const resolve = rules.resolve
+	if (resolve === null) {
+		return
+	}
+	const host = normalizedHost(url.hostname)
+	const addresses = await platformCall(() => resolve(host))
+	const internal = addresses.find((address) => !isPublicAddress(address))
+	if (addresses.length === 0 || internal !== undefined) {
+		throw new CapabilityRefusedError(
+			'refused_egress',
+			`${site} calls ${url.origin}, which public egress refuses: ${
+				internal === undefined ? `${host} resolves to no address` : `${host} resolves to ${internal}, which is not a public address`
+			}`,
+		)
+	}
+}
+
+/**
+ * `response` with its body bounded by `maxResponseBytes`, and the URL and redirect flag of the request it answers,
+ * which a response the guard builds would otherwise lose.
+ */
+async function capped(site: string, response: Response, url: URL, redirected: boolean, done: () => void): Promise<Response> {
+	const max = PUBLIC_EGRESS_LIMITS.maxResponseBytes
+	const tooLarge = () =>
+		new CapabilityRefusedError(
+			'oversized_egress',
+			`${site}: ${url.origin} answers more than ${max} bytes, the most public egress reads of one response`,
+		)
+	const declared = Number(response.headers.get('content-length') ?? '0')
+	if (Number.isFinite(declared) && declared > max) {
+		await response.body?.cancel()
+		throw tooLarge()
+	}
+	if (response.body === null || response.status < 200 || response.status > 599) {
+		done()
+		return withRequestUrl(response, url, redirected)
+	}
+	const reader = response.body.getReader()
+	let seen = 0
+	const bound = new ReadableStream<Uint8Array>({
+		async pull(controller) {
+			const read = await reader.read().catch((error: unknown) => {
+				done()
+				throw error
+			})
+			if (read.done) {
+				done()
+				controller.close()
+				return
+			}
+			seen += read.value.byteLength
+			if (seen > max) {
+				done()
+				await reader.cancel()
+				controller.error(tooLarge())
+				return
+			}
+			controller.enqueue(read.value)
+		},
+		async cancel(reason) {
+			done()
+			await reader.cancel(reason)
+		},
+	})
+	const answer = new Response(bound, {
+		status: response.status,
+		statusText: response.statusText,
+		headers: response.headers,
+	})
+	return withRequestUrl(answer, url, redirected)
+}
+
+function withRequestUrl(response: Response, url: URL, redirected: boolean): Response {
+	try {
+		Object.defineProperties(response, { url: { value: url.href }, redirected: { value: redirected } })
+	} catch {
+		// A runtime whose responses refuse own properties keeps its own `url`; the body bound holds either way.
+	}
+	return response
+}

package/src/implement/invocation.ts

@@ -3,7 +3,7 @@
 // commits it after the handler returned and its output passed validation, and rolls it back otherwise. Every handle
 // is bound to the invocation: called from another request, another `boot`, or after it ended, it refuses.
 
-import { type ContractArtifact, JOB_MAILERS, type JobMailer } from '@fabrika/auth-core'
+import { type ContractArtifact, type DeclaredEgress, JOB_MAILERS, type JobMailer, PUBLIC_EGRESS } from '@fabrika/auth-core'
 import {
 	type DataAccess,
 	type DataHandles,
@@ -34,8 +34,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. */
@@ -166,10 +166,11 @@ export function parseDeclaration(where: string, declared: unknown, kind: DataKin
 		problems.push(`${where}: signs is not a list of token purposes`)
 	}
 	const egressField = ownField(declared, 'egress')
-	const egress = Array.isArray(egressField) ? egressField.filter((origin): origin is string => typeof origin === 'string') : []
-	if (egressField !== undefined && (!Array.isArray(egressField) || egress.length !== egressField.length)) {
-		problems.push(`${where}: egress is not a list of origins`)
+	const origins = Array.isArray(egressField) ? egressField.filter((origin): origin is string => typeof origin === 'string') : []
+	if (egressField !== undefined && egressField !== PUBLIC_EGRESS && (!Array.isArray(egressField) || origins.length !== egressField.length)) {
+		problems.push(`${where}: egress is not a list of origins or '${PUBLIC_EGRESS}'`)
 	}
+	const egress: DeclaredEgress = egressField === PUBLIC_EGRESS ? PUBLIC_EGRESS : Object.freeze([...new Set(origins)].sort())
 	return Object.freeze({
 		sql: sql === 'read' || sql === 'write' ? sql : null,
 		unscoped: Object.freeze(unscoped),
@@ -179,7 +180,7 @@ export function parseDeclaration(where: string, declared: unknown, kind: DataKin
 		kicks: Object.freeze([...new Set(kicks)].sort()),
 		binds: typeof binds === 'string' ? binds : null,
 		signs: Object.freeze([...new Set(signs)].sort()),
-		egress: Object.freeze([...new Set(egress)].sort()),
+		egress,
 	})
 }
 
@@ -224,7 +225,7 @@ export function approvedReach(site: string, artifact: ContractArtifact): SiteDec
 			kicks: Object.freeze([...(reach.kicks ?? [])]),
 			binds: reach.binds ?? null,
 			signs: Object.freeze([...(reach.signs ?? [])]),
-			egress: Object.freeze([...(reach.egress ?? [])]),
+			egress: reach.egress === PUBLIC_EGRESS ? PUBLIC_EGRESS : Object.freeze([...(reach.egress ?? [])]),
 		})
 }
 
@@ -243,7 +244,7 @@ function describeDeclaration(declaration: SiteDeclaration): string {
 		...(declaration.kicks.length === 0 ? {} : { kicks: declaration.kicks }),
 		...(declaration.binds === null ? {} : { binds: declaration.binds }),
 		...(declaration.signs.length === 0 ? {} : { signs: declaration.signs }),
-		...(declaration.egress.length === 0 ? {} : { egress: declaration.egress }),
+		...(declaration.egress !== PUBLIC_EGRESS && declaration.egress.length === 0 ? {} : { egress: declaration.egress }),
 	})
 }
 

package/src/jobs/runner.ts

@@ -22,7 +22,7 @@ import {
 	runInRequest,
 	type Within,
 } from '../implement/capability'
-import { runAsSite } from '../implement/egress'
+import { type PublicEgressRules, runAsSite, siteEgress } from '../implement/egress'
 import { failureCode, type FailureReason, failureReason } from '../implement/failures'
 import { ServerFault } from '../implement/faults'
 import type { ContractDatabase } from '../implement/implement'
@@ -188,6 +188,8 @@ interface RunnerContext {
 	/** The environment's signed tokens: `ctx.tokens` of a job that declares `signs`. */
 	readonly tokens: SignedTokens | null
 	readonly url: AppUrl
+	/** What a job that declares `egress: 'public'` reaches; such a job reaches nothing without it. */
+	readonly publicEgress: PublicEgressRules | null
 }
 
 /** Where `fabrika app dev` shows what a handler threw, on the developer's own machine; nothing else sets one. */
@@ -227,6 +229,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
 }
 
 interface BoundFrameworkJob {
@@ -326,6 +330,7 @@ export function bindJobs(input: JobBindingInput, problems: string[]): BoundJobs
 		mail: input.mail,
 		tokens: input.tokens ?? null,
 		url: input.url ?? appUrl(input.artifact, null),
+		publicEgress: input.publicEgress ?? null,
 		// A job's kicks run only after the job is bound, so `kick` below is defined by then.
 		kick: (name: string) => kick(name),
 	})
@@ -698,7 +703,7 @@ async function attemptOnce(
 			if (site === null) {
 				await job.handler({ ctx })
 			} else {
-				await runAsSite(`job '${job.name}'`, site.egress, async () => await job.handler({ ctx }))
+				await runAsSite(`job '${job.name}'`, siteEgress(site.egress, context.publicEgress), async () => await job.handler({ ctx }))
 			}
 			kicked.push(...kicks.kicked())
 		}).then(() => null, (error: unknown) => {

package/src/spa-fallback.ts

@@ -0,0 +1,12 @@
+// Which request an SPA mount answers with its `index.html` when it names no file: a route of the page, not a missing
+// asset. Both asset servers apply it (`diskAssets`, `bindingAssets`), so a missing script stays a 404 and never arrives
+// as an HTML page with a 200.
+
+import { rawRequestTarget } from '@fabrika/auth-core'
+
+/** A GET or HEAD whose last path segment has no extension, or one that asks for HTML (a navigation to `/notes/v1.2`). */
+export function isPageRoute(request: Request): boolean {
+	if (request.method !== 'GET' && request.method !== 'HEAD') return false
+	const last = rawRequestTarget(request.url).pathname.split('/').pop() ?? ''
+	return !last.includes('.') || (request.headers.get('Accept') ?? '').includes('text/html')
+}