@fabrika/app 0.8.2 → 0.9.0-cloudflare.2

package/src/cloudflare.ts

@@ -1,17 +1,31 @@
 // ─── Cloudflare Workers adapter ──────────────────────────────────────
 
-import { DecodedIamMembership } from '@fabrika/auth'
-import type { IamMembershipRpc } from '@fabrika/auth-core'
-import { parseJwks } from '@fabrika/jwks'
+import {
+	type ApplicationObjects,
+	FABRIKA_APPLICATION_OBJECT,
+	FABRIKA_APPLICATION_OBJECTS,
+	FABRIKA_PROXY_SECRET,
+	OPS_PREFIX,
+	opsRefusal,
+	parseApplicationObjects,
+	parseOpsOperation,
+	PROXY_SECRET_HEADER,
+} from '@fabrika/auth-core'
+import { type ContractWorkerOptions, type ImplementationLoader, registerApplication, TICK_HEADER } from './cloudflare/application.js'
+import { method } from './cloudflare/bindings.js'
+import { CLOUDFLARE_APPLICATION_BINDING } from './cloudflare/names.js'
+import { jsonBody, objectNamed, opsAccess, opsAuthenticated } from './cloudflare/ops.js'
 import type { FetchService, RequestExecutionContext } from './fetch.js'
-import { boot, type ContractApp, type IamKeySource } from './implement/boot.js'
-import { CONNECT_BINDING_PREFIX, type ConnectFetch } from './implement/connect.js'
-import { type CrashEvents, environmentCrashReporter, reportSurvivedCrashes } from './implement/crashes.js'
-import type { SpaAssets } from './implement/dispatch.js'
-import { captureEnvironment } from './implement/environment.js'
-import type { ContractImplementation } from './implement/implement.js'
 
 export { markProductionProcess } from '@fabrika/db/production'
+export {
+	type ApplicationMigration,
+	type ApplicationState,
+	type ApplicationStorage,
+	type ContractWorkerOptions,
+	FabrikaApplication,
+	type ImplementationLoader,
+} from './cloudflare/application.js'
 
 /** Minimal structural view of a Workers `ExecutionContext`. */
 export interface CloudflareExecutionContext extends RequestExecutionContext {
@@ -58,166 +72,105 @@ export function createCloudflareWorker<Env>(
 
 // ─── Contract applications ───────────────────────────────────────────
 
-/** The framework's bindings: IAM's application entrypoint and the Workers Assets of the SPA. No handler sees them. */
-const FRAMEWORK_BINDINGS: ReadonlySet<string> = new Set(['IAM', 'ASSETS'])
-
-function method(target: unknown, name: string): ((...args: unknown[]) => unknown) | null {
-	if (typeof target !== 'object' || target === null || !(name in target)) {
-		return null
-	}
-	const found: unknown = Reflect.get(target, name)
-	return typeof found === 'function' ? (...args) => Reflect.apply(found, target, args) : null
-}
-
-function bindingKeySource(binding: unknown): IamKeySource {
-	const getJwks = method(binding, 'getJwks')
-	if (getJwks === null) {
-		throw new Error('the IAM binding is missing (env.IAM); the platform binds it to every application Worker')
-	}
-	return {
-		async getJwks() {
-			const jwks = parseJwks(await getJwks())
-			if (jwks === null) {
-				throw new Error('IAM returned no usable key set')
-			}
-			return jwks
-		},
+/** The environment's proxy secret, which every request the Worker forwards to its object carries. */
+function proxySecretOf(env: Readonly<Record<string, unknown>>): string {
+	const secret = env[FABRIKA_PROXY_SECRET]
+	if (typeof secret !== 'string' || secret === '') {
+		throw new Error(`${FABRIKA_PROXY_SECRET} is not set; the application's Worker forwards nothing to its object without it`)
 	}
+	return secret
 }
 
 /**
- * IAM's membership operations on the `IAM` binding (`PropustkaApplication`), every answer decoded like the HTTP
- * transport's. A binding without them is no membership transport, and `boot` refuses a contract that needs one.
+ * The object of ordinary traffic and the objects an ops request may name, all in the environment's own namespace.
+ * Without either variable (an older deploy) the one object is `application`.
  */
-function bindingMembership(binding: unknown): IamMembershipRpc | undefined {
-	const methods = ['requestDelegation', 'createScope', 'assignMember', 'revokeMember', 'listMembers', 'issueLink', 'revokeLink'] as const
-	if (!methods.every((name) => method(binding, name) !== null)) {
-		return undefined
+function applicationObjects(env: Readonly<Record<string, unknown>>): ApplicationObjects {
+	const object = env[FABRIKA_APPLICATION_OBJECT]
+	const objects = env[FABRIKA_APPLICATION_OBJECTS]
+	const parsed = parseApplicationObjects(typeof object === 'string' ? object : undefined, typeof objects === 'string' ? objects : undefined)
+	if (parsed === null) {
+		throw new Error(`${FABRIKA_APPLICATION_OBJECT} and ${FABRIKA_APPLICATION_OBJECTS} name no valid set of objects; a deploy writes both`)
 	}
-	return new DecodedIamMembership(async (name, input) => {
-		const call = method(binding, name)
-		if (call === null) {
-			throw new Error(`the IAM binding has no ${name}`)
-		}
-		return await call(input)
-	})
+	return parsed
 }
 
-function bindingAssets(binding: unknown): SpaAssets | undefined {
-	const fetchAsset = method(binding, 'fetch')
-	if (fetchAsset === null) {
-		return undefined
+/** The object `name` of the environment's namespace (`FABRIKA_APPLICATION`), as a fetch. */
+function applicationObject(env: Readonly<Record<string, unknown>>, name: string): (request: Request) => Promise<Response> {
+	const namespace = env[CLOUDFLARE_APPLICATION_BINDING]
+	const idFromName = method(namespace, 'idFromName')
+	const get = method(namespace, 'get')
+	if (idFromName === null || get === null) {
+		throw new Error(`the ${CLOUDFLARE_APPLICATION_BINDING} binding is missing; the provider binds the application's Durable Object to its Worker`)
 	}
-	return {
-		async serve(_mount, request) {
-			const response: unknown = await fetchAsset(request)
-			if (!(response instanceof Response)) {
-				throw new Error('the ASSETS binding answered something that is not a Response')
-			}
-			return response
-		},
+	const stub: unknown = get(idFromName(name))
+	// Read, not tested with `in`: a stub answers `fetch` without owning the property.
+	const fetchObject: unknown = typeof stub === 'object' && stub !== null ? Reflect.get(stub, 'fetch') : undefined
+	if (typeof fetchObject !== 'function') {
+		throw new Error(`the ${CLOUDFLARE_APPLICATION_BINDING} binding answered no object`)
+	}
+	return async (request) => {
+		const response: unknown = await Reflect.apply(fetchObject, stub, [request])
+		if (!(response instanceof Response)) {
+			throw new Error("the application's object answered something that is not a Response")
+		}
+		return response
 	}
 }
 
 /**
- * The service bindings to owners' proxy Workers (`FABRIKA_CONNECT_<IMPORT>`), which `captureEnvironment` keeps from
- * the application because no `FABRIKA_*` value reaches it. A binding routes by itself: the URL it is called with
- * carries the owner's host, which the proxy Worker selects the application by.
+ * An ops request reaches the object its body names, when the environment lists it (ADR-0069 §1). Every refusal here
+ * is the same answer the object gives, and the object checks everything again.
  */
-function connectBindings(env: Readonly<Record<string, unknown>>): Record<string, ConnectFetch> {
-	const bindings: Record<string, ConnectFetch> = {}
-	for (const [name, binding] of Object.entries(env)) {
-		// Read, not tested with `in`: a binding stub may answer `fetch` without owning the property (Lopata's does not).
-		const fetchOwner: unknown = name.startsWith(CONNECT_BINDING_PREFIX) && typeof binding === 'object' && binding !== null
-			? Reflect.get(binding, 'fetch')
-			: undefined
-		if (typeof fetchOwner === 'function') {
-			bindings[name] = async (request) => {
-				const response: unknown = await Reflect.apply(fetchOwner, binding, [request])
-				if (!(response instanceof Response)) {
-					throw new Error(`the ${name} binding answered something that is not a Response`)
-				}
-				return response
-			}
-		}
+async function forwardOps(request: Request, env: Readonly<Record<string, unknown>>): Promise<Response> {
+	const access = opsAccess(env)
+	// Receiver authentication of Control's key, as the object runs it; no enforcement decision. It runs before the body is
+	// read or any object looked up, so an unauthenticated caller wakes no object and learns nothing of the names.
+	if (access === null || !opsAuthenticated(request, access)) {
+		return opsRefusal()
 	}
-	return bindings
-}
-
-/** The application module, imported only after the environment was captured: the generated entrypoint's `import()`. */
-export type ImplementationLoader = () => Promise<{ readonly default: ContractImplementation }>
-
-export interface ContractWorkerOptions {
-	/** Where the isolate hears of an unhandled rejection; the global `unhandledrejection` event by default. */
-	readonly rejections?: CrashEvents
-	/** What posts a report to Operations' ingest; `fetch` by default. */
-	readonly operationsFetch?: (request: Request) => Promise<Response>
+	const operation = parseOpsOperation(new URL(request.url).pathname)
+	const object = operation === null ? null : objectNamed(operation, await jsonBody(request.clone()))
+	if (object === null || !access.objects.objects.includes(object)) {
+		return opsRefusal()
+	}
+	return await applicationObject(env, object)(request)
 }
 
-/** The isolate's `unhandledrejection` event. Listening leaves the runtime's own handling, its log line, in place. */
-function globalRejectionEvents(): CrashEvents {
-	return {
-		listen(listener) {
-			const rejection = (event: Event) => listener('unhandled_rejection', Reflect.get(event, 'reason'))
-			globalThis.addEventListener('unhandledrejection', rejection)
-			return () => globalThis.removeEventListener('unhandledrejection', rejection)
-		},
-	}
+export interface ContractWorker {
+	fetch(request: Request, env: Readonly<Record<string, unknown>>, exec: CloudflareExecutionContext): Promise<Response>
+	scheduled(controller: CloudflareScheduledController, env: Readonly<Record<string, unknown>>, exec: CloudflareExecutionContext): Promise<void>
 }
 
 /**
- * A Worker module for a contract application, called only by the generated entrypoint. A Worker receives its
- * environment with the first request, so the framework captures it, scrubs the process environment and only then
- * imports the application and boots it, once per environment object. With an Operations DSN, the first failed boot
- * of an isolate is reported, and once one booted, every unhandled rejection of the isolate is, within a budget.
+ * The Worker module of a contract application, called only by the generated entrypoint, which also exports
+ * `FabrikaApplication`. The application runs in the environment's Durable Object (ADR-0065): `fetch` forwards every
+ * request to it with the proxy secret, the proxy's own headers unchanged, and `scheduled` forwards the minute tick.
+ * An ops request goes to the object its body names instead (ADR-0069). The object captures the environment, imports
+ * the application and boots it.
  */
-export function createContractWorker(load: ImplementationLoader, options: ContractWorkerOptions = {}): {
-	fetch(request: Request, env: Readonly<Record<string, unknown>>, exec: CloudflareExecutionContext): Promise<Response>
-} {
-	const booted = new WeakMap<object, Promise<ContractApp>>()
-	let bootFailureReported = false
-	let watchingRejections = false
-	const bootFor = async (env: Readonly<Record<string, unknown>>, exec: CloudflareExecutionContext): Promise<ContractApp> => {
-		const variables = Object.fromEntries(Object.entries(env).filter(([name]) => !FRAMEWORK_BINDINGS.has(name)))
-		const environment = captureEnvironment(variables)
-		const crashes = environmentCrashReporter(environment, options.operationsFetch)
-		let contractApp: ContractApp
-		try {
-			const { default: app } = await load()
-			contractApp = boot(app, {
-				environment,
-				iam: bindingKeySource(env['IAM']),
-				assets: bindingAssets(env['ASSETS']),
-				membership: bindingMembership(env['IAM']),
-				connectBindings: connectBindings(env),
-				// The proxy Worker sets `X-Fabrika-Client-Ip` from `CF-Connecting-IP`, the visitor Cloudflare saw.
-				clientAddress: 'vouched',
-				...(options.operationsFetch === undefined ? {} : { operationsFetch: options.operationsFetch }),
-			})
-		} catch (error) {
-			// Every request of a failed isolate boots again; one report says it.
-			if (crashes !== null && !bootFailureReported) {
-				bootFailureReported = true
-				exec.waitUntil(crashes.report('boot_failed', error))
-			}
-			throw error
-		}
-		if (crashes !== null && !watchingRejections) {
-			watchingRejections = true
-			reportSurvivedCrashes(options.rejections ?? globalRejectionEvents(), crashes)
-		}
-		return contractApp
-	}
+export function createContractWorker(load: ImplementationLoader, options: ContractWorkerOptions = {}): ContractWorker {
+	registerApplication(load, options)
 	return {
-		async fetch(request, env, exec) {
-			let contractApp = booted.get(env)
-			if (contractApp === undefined) {
-				contractApp = bootFor(env, exec)
-				booted.set(env, contractApp)
-				// A failed boot is not cached: the next request boots again and fails with the same problems.
-				contractApp.catch(() => booted.delete(env))
+		async fetch(request, env) {
+			const headers = new Headers(request.headers)
+			headers.delete(TICK_HEADER)
+			headers.set(PROXY_SECRET_HEADER, proxySecretOf(env))
+			const forwarded = new Request(request, { headers })
+			if (new URL(request.url).pathname.startsWith(OPS_PREFIX)) {
+				return await forwardOps(forwarded, env)
+			}
+			return await applicationObject(env, applicationObjects(env).object)(forwarded)
+		},
+		async scheduled(controller, env) {
+			const tick = new Request('https://application.invalid/', {
+				method: 'POST',
+				headers: { [PROXY_SECRET_HEADER]: proxySecretOf(env), [TICK_HEADER]: String(controller.scheduledTime) },
+			})
+			const response = await applicationObject(env, applicationObjects(env).object)(tick)
+			if (!response.ok) {
+				throw new Error(`the application's object answered the minute tick with ${response.status}`)
 			}
-			return (await contractApp).fetch(request, exec)
 		},
 	}
 }

package/src/contract/app-id.ts

@@ -0,0 +1,5 @@
+// A leaf module: the contract (client side included) and the build recipe both read the id rule, and the contract must
+// not reach the recipe's server-side modules through it.
+
+/** The contract's application id rule; an id that holds to it reaches a generated script unquoted. */
+export const CONTRACT_APP_ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/

package/src/contract/artifact-schema.ts

@@ -14,16 +14,19 @@ import {
 	FILE_RESPONSE_KINDS,
 	isOwnWorkloadName,
 	JOB_MAILERS,
+	JOB_SITE_PREFIX,
 	LOCALES,
 	mailTemplateProblems,
 	MAX_CACHE_AGE_SECONDS,
 	type MessageKind,
 	type NumberShape,
 	type OutputShape,
+	PUBLIC_EGRESS,
 	type RecordShape,
 	type SchemaShape,
 	type StringShape,
 	type TablePolicyArtifact,
+	terminalIdentifyProblem,
 	type TupleShape,
 } from '@fabrika/auth-core'
 import { isPolicyOrigin, WORKER_BLOB_SOURCE } from '@fabrika/proxy-core/headers'
@@ -410,9 +413,12 @@ export const contractArtifactSchema: z.ZodType<ContractArtifact> = z.strictObjec
 		kicks: z.array(name).nonempty().optional(),
 		binds: name.optional(),
 		signs: z.array(name).nonempty().optional(),
-		egress: z.array(z.string().refine((origin) => isPolicyOrigin(origin))).nonempty().optional(),
+		egress: z.union([z.array(z.string().refine((origin) => isPolicyOrigin(origin))).nonempty(), z.literal(PUBLIC_EGRESS)]).optional(),
 	})).superRefine((declared, context) => {
 		for (const [site, reach] of Object.entries(declared)) {
+			if (reach.egress === PUBLIC_EGRESS && !site.startsWith(JOB_SITE_PREFIX)) {
+				context.addIssue({ code: 'custom', path: [site, 'egress'], message: "egress: 'public' belongs to a cron job, keyed by job:<name>" })
+			}
 			if (reach.actions !== undefined && !isOwnWorkloadName('public', site)) {
 				context.addIssue({ code: 'custom', path: [site, 'actions'], message: 'workload actions belong to a public procedure, keyed by its endpoint id' })
 			}
@@ -425,6 +431,7 @@ export const contractArtifactSchema: z.ZodType<ContractArtifact> = z.strictObjec
 		.optional(),
 	members: z.strictObject({ manage: action, list: action }).optional(),
 	directory: z.literal('labels').optional(),
+	terminal: z.strictObject({ identify: z.string().refine((path) => terminalIdentifyProblem(path) === null, 'not an identification path') }).optional(),
 	procedures: record(z.strictObject({
 		rate: z.strictObject({
 			perClient: bucket,

package/src/contract/build.ts

@@ -13,10 +13,12 @@ import {
 	type CapabilityAccessForm,
 	type CapabilityRequirement,
 	type ChallengeProvider,
+	compileEndpointTable,
 	CONTRACT_FORMAT,
 	type ContractArtifact,
 	type CspExtensions,
 	type CspSource,
+	type DeclaredEgress,
 	type DeclaredReach,
 	type DimensionArtifact,
 	directoryReach,
@@ -48,18 +50,23 @@ import {
 	type MessageKind,
 	type MountArtifact,
 	type OutputShape,
+	planEndpoint,
 	type ProcedureArtifact,
 	type ProcedureChallenge,
+	PUBLIC_EGRESS,
 	type RoleArtifact,
 	type SchemaShape,
 	type ScopeBinding,
 	tableActions,
 	type TablePolicyArtifact,
+	type TerminalArtifact,
+	terminalIdentifyProblem,
 	type TokenPurposeArtifact,
 	type WebhookScheme,
 } from '@fabrika/auth-core'
 import { isPolicyOrigin, MAX_CSP_ORIGINS, WORKER_BLOB_SOURCE } from '@fabrika/proxy-core/headers'
 import { z } from 'zod/v4'
+import { CONTRACT_APP_ID_PATTERN as APP_ID } from './app-id'
 import { contractArtifactSchema } from './artifact-schema'
 import {
 	type AccessDeclaration,
@@ -117,7 +124,6 @@ import { ContractError, Problems } from './problems'
 import { TOKEN_MAX_DAYS } from './token'
 import { hmacSchemeSchema, WEBHOOK_SCHEME_ALLOWED, webhookSchemeSchema } from './webhook-scheme'
 
-const APP_ID = /^[a-z0-9][a-z0-9-]*$/
 const NAME = /^[A-Za-z][A-Za-z0-9_]*$/
 const DIMENSION = /^[a-z][A-Za-z0-9_]*$/
 const ACTION = /^[A-Za-z][A-Za-z0-9_-]*(?:\.[A-Za-z][A-Za-z0-9_-]*)+$/
@@ -143,7 +149,7 @@ const FRAMEWORK_TABLE_PREFIX = 'fabrika_'
 /** The most origins one site calls: a site that reaches more is an integration hub, which a connector import serves. */
 const MAX_EGRESS_ORIGINS = 16
 const DECLARED_ALLOWED =
-	"sql: 'read' | 'write', unscoped: { <table>: 'read' | 'write' }, connect: ['<import>'], issues: '<link mount>', mailer: 'installation' | 'own', kicks: ['<cron job>'], binds: '<webhook>', signs: ['<token purpose>'], egress: ['https://<host>']"
+	"sql: 'read' | 'write', unscoped: { <table>: 'read' | 'write' }, connect: ['<import>'], issues: '<link mount>', mailer: 'installation' | 'own', kicks: ['<cron job>'], binds: '<webhook>', signs: ['<token purpose>'], egress: ['https://<host>'] | 'public' (a cron job)"
 const CSP_FIELDS = ['connectSrc', 'imgSrc', 'frameAncestors', 'scriptSrc', 'frameSrc', 'styleSrc', 'fontSrc']
 /** An environment variable an application reads; a challenge names its secret by one. */
 const APPLICATION_VARIABLE = /^[A-Z][A-Z0-9_]*$/
@@ -234,6 +240,7 @@ class ArtifactBuilder {
 		const displayName = this.#displayName()
 		const mail = this.#mail()
 		const people = this.#people()
+		const terminal = this.#terminal()
 		const artifact: ContractArtifact = {
 			format: CONTRACT_FORMAT,
 			app: contract.app,
@@ -256,6 +263,7 @@ class ArtifactBuilder {
 			...(displayName === null ? {} : { displayName }),
 			...(mail === null ? {} : { mail }),
 			...people,
+			...(terminal === null ? {} : { terminal }),
 			...(Object.keys(this.#procedureRules).length === 0 ? {} : { procedures: this.#procedureRules }),
 			...(Object.keys(tokens).length === 0 ? {} : { tokens }),
 		}
@@ -263,10 +271,38 @@ class ArtifactBuilder {
 			assertNoAmbiguity(artifact)
 		} catch (error) {
 			this.#problem('endpoints', error instanceof Error ? error.message : String(error))
+			return artifact
+		}
+		if (terminal !== null) {
+			this.#checkIdentifyPage(artifact, terminal)
 		}
 		return artifact
 	}
 
+	/** The terminal's identification page, when its path is one. */
+	#terminal(): TerminalArtifact | null {
+		const terminal = this.#contract.terminal
+		if (terminal === undefined) return null
+		const problem = terminalIdentifyProblem(terminal.identify)
+		if (problem !== null) {
+			this.#problem('terminal.identify', `'${terminal.identify}' ${problem}`)
+			return null
+		}
+		return { identify: terminal.identify }
+	}
+
+	/**
+	 * Nobody is signed in on the identification page, so a public SPA mount must serve it: under a credentialed one, the
+	 * proxy would bounce the terminal's browser back to sign-in, which sends it to the page again.
+	 */
+	#checkIdentifyPage(artifact: ContractArtifact, terminal: TerminalArtifact): void {
+		const plan = planEndpoint(compileEndpointTable(artifact), 'GET', terminal.identify)
+		if (plan.outcome !== 'endpoint' || plan.endpoint.kind !== 'public-spa') {
+			const served = plan.outcome === 'endpoint' ? `'${plan.endpoint.id}' (${plan.endpoint.kind})` : 'no endpoint'
+			this.#problem('terminal.identify', `'${terminal.identify}' is served by ${served}; serve it from an spa mount with access: { public: true }`)
+		}
+	}
+
 	/** The member directory each endpoint reads, recorded so the approval and the digest cover the reach. */
 	#directories(dimensions: ContractArtifact['dimensions']): Record<string, EndpointDirectory> {
 		const directories: Record<string, EndpointDirectory> = {}
@@ -2072,7 +2108,7 @@ class ArtifactBuilder {
 			...(kicks.length === 0 ? {} : { kicks }),
 			...(binds === undefined ? {} : { binds }),
 			...(signs.length === 0 ? {} : { signs }),
-			...(egress.length === 0 ? {} : { egress }),
+			...(egress === null ? {} : { egress }),
 		}
 		if (place.kind !== 'rpc') {
 			this.#rpcOnly(where, 'connect', value['connect'])
@@ -2271,12 +2307,13 @@ class ArtifactBuilder {
 
 	/**
 	 * The HTTPS origins a site's code calls: a credentialed procedure of an RPC mount, a webhook or a job, never a public,
-	 * export or link procedure. Each is an exact origin with no path or wildcard, once; `[]` when it declares none or after
-	 * a problem.
+	 * export or link procedure. Each is an exact origin with no path or wildcard, once. Or `'public'`, every public host
+	 * (ADR-0070), which only a cron job declares: it calls outside any transaction, and its schedule, not a caller,
+	 * decides when. `null` when it declares none or after a problem.
 	 */
-	#egress(where: string, value: unknown, place: DeclaringSite): string[] {
+	#egress(where: string, value: unknown, place: DeclaringSite): DeclaredEgress | null {
 		if (value === undefined) {
-			return []
+			return null
 		}
 		const refusedBy = place.kind === 'export'
 			? 'an export procedure'
@@ -2287,15 +2324,35 @@ class ArtifactBuilder {
 			: null
 		if (refusedBy !== null) {
 			this.#problem(where, `declares egress, which ${refusedBy} never does: a credentialed procedure, a webhook or a job calls out`)
-			return []
+			return null
+		}
+		if (value === PUBLIC_EGRESS) {
+			if (place.kind !== 'job') {
+				this.#problem(
+					where,
+					`declares egress: '${PUBLIC_EGRESS}', which only a cron job declares: a procedure or a webhook names its origins (allowed: egress: ['https://api.example.com'])`,
+				)
+				return null
+			}
+			return PUBLIC_EGRESS
 		}
 		if (!Array.isArray(value) || value.length === 0 || !value.every((origin) => typeof origin === 'string')) {
-			this.#problem(where, "egress is not a list of origins (allowed: egress: ['https://api.example.com'])")
-			return []
+			this.#problem(
+				where,
+				place.kind === 'job'
+					? "egress is not a list of origins or 'public' (allowed: egress: ['https://api.example.com'] or egress: 'public')"
+					: "egress is not a list of origins (allowed: egress: ['https://api.example.com'])",
+			)
+			return null
 		}
 		const origins: string[] = value.filter((origin) => typeof origin === 'string')
 		if (origins.length > MAX_EGRESS_ORIGINS) {
-			this.#problem(where, `${origins.length} egress origins exceed the limit of ${MAX_EGRESS_ORIGINS}`)
+			this.#problem(
+				where,
+				`${origins.length} egress origins exceed the limit of ${MAX_EGRESS_ORIGINS}${
+					place.kind === 'job' ? " (a cron job that calls the websites its operators name declares egress: 'public')" : ''
+				}`,
+			)
 		}
 		for (const origin of origins) {
 			if (!isPolicyOrigin(origin)) {

package/src/contract/compile.ts

@@ -81,6 +81,7 @@ export function describeContract(contract: AnyContract): ContractDeclaration<Sch
 		...(vocabulary.mail === undefined ? {} : { mail: vocabulary.mail }),
 		...(vocabulary.members === undefined ? {} : { members: vocabulary.members }),
 		...(vocabulary.directory === undefined ? {} : { directory: vocabulary.directory }),
+		...(vocabulary.terminal === undefined ? {} : { terminal: { identify: vocabulary.terminal.identify } }),
 	}
 }
 

package/src/contract/context.ts

@@ -25,6 +25,7 @@ import type { StoredFilesHandle, StoredFilesReadHandle } from '../files/handle'
 import type { AppCapability, Ref, Within } from '../implement/capability'
 import type { ApplicationDirectory, LinkIssuing, MemberDirectory, MemberLookup, MemberManagement } from '../implement/membership'
 import type { AppPrincipal, PrincipalOf, PublicPrincipal, ServicePrincipal } from '../implement/principal'
+import type { TerminalIdentification } from '../implement/terminals'
 import type { CapabilityOf, ConnectCall, RequestContext } from '../implement/types'
 import type { WebhookDelivery, WebhookPrincipal } from '../implement/webhook'
 import type { AppMail, JobContext } from '../jobs/types'
@@ -56,6 +57,8 @@ export interface KitTypes {
 	readonly dimensions: unknown
 	/** The actions of the application's own people, as written; `never` when the vocabulary declares none. */
 	readonly members: { readonly manage: string; readonly list: string }
+	/** Whether the vocabulary declares `terminal: { identify }`, which gives `ctx.terminals`. */
+	readonly terminal: boolean
 	readonly index: AnyDbIndex
 	/** The table names of `src/db/tables.ts`. */
 	readonly tables: string
@@ -357,6 +360,10 @@ type ConnectContext<K extends KitTypes, Cn extends readonly string[]> = [Cn] ext
 	? { readonly connect: Unavailable<"declare connect: ['<connector>'] on this endpoint to call another application"> }
 	: { readonly connect: { readonly [N in Cn[number]]: ConnectorOf<K['imports'][N]> } }
 
+/** `ctx.terminals`, where the vocabulary declares the terminal identification page. */
+type TerminalsContext<K extends KitTypes> = K['terminal'] extends true ? { readonly terminals: TerminalIdentification }
+	: { readonly terminals: Unavailable<"the application declares no terminal: terminal: { identify: '/identify' } in the vocabulary"> }
+
 /** What the handler of an RPC endpoint receives, for mount callers `Caller`, kind `Kind` and its declaration. */
 export type EndpointContext<
 	K extends KitTypes,
@@ -370,6 +377,7 @@ export type EndpointContext<
 	& MembersContext<K, Acc>
 	& LinksContext<Acc, Of<D, 'issues'>>
 	& ConnectContext<K, Of<D, 'connect'>>
+	& TerminalsContext<K>
 	& SqlContext<Of<D, 'sql'>, K['index']>
 	& FilesContext<K['index'], Kind>
 	& { readonly db: DataOf<K['index'], EndpointData<K['index'], Kind, Acc, Of<D, 'unscoped'>>> }
@@ -396,6 +404,7 @@ export type PublicContext<K extends KitTypes, Kind extends DataKind, Acts extend
 		readonly files: Kind extends 'query' ? StoredFilesReadHandle : StoredFilesHandle
 		readonly sql: Unavailable<'a public procedure reaches its actions only: it declares no sql'>
 	}
+	& TerminalsContext<K>
 	& {
 		readonly db: DataOf<
 			K['index'],

package/src/contract/declaration.ts

@@ -26,6 +26,8 @@ export interface ContractDeclaration<S> {
 	readonly members?: { readonly manage: string; readonly list: string }
 	/** `'labels'` only; `buildArtifact` refuses another value, and refuses it without `members`. */
 	readonly directory?: string
+	/** The identification page of a terminal; `buildArtifact` refuses a path a public SPA mount does not serve. */
+	readonly terminal?: { readonly identify: string }
 }
 
 /**

package/src/contract/define.ts

@@ -26,6 +26,11 @@ import type { TokenPurposes } from './token'
 
 export type Path = `/${string}`
 
+/** Whether `value` is written as a `Path`; what `buildArtifact` refuses of one is a separate check. */
+export function isPath(value: string): value is Path {
+	return value.startsWith('/')
+}
+
 /** A job attempt's time limit: 15 minutes by default, at most a day. A job reads no body, so it has no `maxBytes`. */
 export interface JobLimitsOption {
 	readonly timeoutMs?: number
@@ -92,7 +97,7 @@ export interface RoleDef<A extends string, D extends string, R extends string> {
 	readonly external?: true
 }
 
-export interface Vocabulary<A extends string, D extends string, R extends string> extends Presentation, AppPeople<A> {
+export interface Vocabulary<A extends string, D extends string, R extends string> extends Presentation, AppPeople<A>, AppTerminal {
 	readonly app: string
 	readonly dimensions: { readonly [K in D]: DimensionDef<A, D, R> }
 	readonly actions: { readonly [K in A]: string }
@@ -124,6 +129,26 @@ export function peopleOf<A extends string>(vocabulary: AppPeople<A>): AppPeople<
 	}
 }
 
+/** The page that identifies a person at an enrolled terminal (ADR-0067). */
+export interface TerminalDeclaration {
+	/** An absolute path on the application's own origin, served by a public SPA mount; IAM appends `?identification=<id>`. */
+	readonly identify: Path
+}
+
+/**
+ * `terminal: { identify: '/identify' }`: the application identifies a person at an enrolled terminal on that page and
+ * asserts who stands there (`ctx.terminals`). IAM sends a terminal's browser there only for an application its
+ * administrator lists on the terminal. A reviewed declaration.
+ */
+export interface AppTerminal {
+	readonly terminal?: TerminalDeclaration
+}
+
+/** A vocabulary's terminal, copied field by field: it exists only when declared. */
+export function terminalOf(vocabulary: AppTerminal): AppTerminal {
+	return vocabulary.terminal === undefined ? {} : { terminal: { identify: vocabulary.terminal.identify } }
+}
+
 /** How IAM names the application to a person: on its sign-in, password and invitation pages, and in its e-mails. */
 export interface Presentation {
 	/** The language of those pages and e-mails; absent, the installation's default. */
@@ -535,7 +560,7 @@ export function defineContract<
 	const Dims extends { readonly [K in D]: DimensionDef<NoInfer<A>, NoInfer<D>, NoInfer<R>> },
 	const S extends Surface,
 >(
-	vocabulary: Presentation & AppPeople<NoInfer<A>> & {
+	vocabulary: Presentation & AppPeople<NoInfer<A>> & AppTerminal & {
 		readonly app: string
 		readonly dimensions: Dims & { readonly [K in D]: DimensionDef<NoInfer<A>, NoInfer<D>, NoInfer<R>> }
 		readonly actions: { readonly [K in A]: K extends `${string}*${string}` ? WildcardMessage : string }
@@ -551,6 +576,7 @@ export function defineContract<
 			roles: vocabulary.roles,
 			...presentationOf(vocabulary),
 			...peopleOf(vocabulary),
+			...terminalOf(vocabulary),
 		},
 		dimensions: vocabulary.dimensions,
 		surface: surface(surfaceKit()),