@fabrika/app 0.8.2 → 0.9.0-cloudflare.1

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

@@ -24,6 +24,7 @@ import {
 	type SchemaShape,
 	type StringShape,
 	type TablePolicyArtifact,
+	terminalIdentifyProblem,
 	type TupleShape,
 } from '@fabrika/auth-core'
 import { isPolicyOrigin, WORKER_BLOB_SOURCE } from '@fabrika/proxy-core/headers'
@@ -425,6 +426,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,6 +13,7 @@ import {
 	type CapabilityAccessForm,
 	type CapabilityRequirement,
 	type ChallengeProvider,
+	compileEndpointTable,
 	CONTRACT_FORMAT,
 	type ContractArtifact,
 	type CspExtensions,
@@ -48,6 +49,7 @@ import {
 	type MessageKind,
 	type MountArtifact,
 	type OutputShape,
+	planEndpoint,
 	type ProcedureArtifact,
 	type ProcedureChallenge,
 	type RoleArtifact,
@@ -55,11 +57,14 @@ import {
 	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 +122,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_-]*)+$/
@@ -234,6 +238,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 +261,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 +269,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> = {}

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()),

package/src/contract/kit.ts

@@ -45,6 +45,7 @@ import {
 	type Schema,
 	type Surface,
 	surfaceKit,
+	terminalOf,
 	type WebhookMount,
 } from './define'
 import type {
@@ -73,13 +74,14 @@ type Owned<K extends string> = { readonly [P in K]?: never }
 
 /** The kit's types, computed once from the vocabulary, the tables' index, the imports and the token purposes. */
 export type KitOf<V, Ix, Imp extends KitImports, Tk extends TokenPurposes = Record<never, never>> = V extends
-	AppVocabulary<infer A, infer D, infer R, infer Dims, infer M> ? {
+	AppVocabulary<infer A, infer D, infer R, infer Dims, infer M, infer T> ? {
 		readonly action: A
 		readonly dimension: D
 		readonly creatable: CreatableDimension<Dims>
 		readonly role: R
 		readonly dimensions: Dims
 		readonly members: M
+		readonly terminal: [T] extends [never] ? false : true
 		readonly index: Ix
 		readonly tables: Ix extends { readonly tables: infer T } ? keyof T & string : never
 		readonly imports: Imp
@@ -555,6 +557,7 @@ function runtimeApp(vocabulary: AnyAppVocabulary, options: KitOptions | undefine
 					roles: vocabulary.roles,
 					...presentationOf(vocabulary),
 					...peopleOf(vocabulary),
+					...terminalOf(vocabulary),
 				},
 				dimensions: vocabulary.dimensions,
 				surface: declared,

package/src/contract/platform.ts

@@ -23,8 +23,8 @@ import {
 /**
  * The IAM vocabulary of a contract application, marked `contract` so IAM refuses every wildcard written for it: the
  * dimensions as scopes with their container, creator role and members actions; the actions; the roles, a membership
- * role with its scope and the roles that may assign it; the link mounts; the delegations; the workloads; and the locale,
- * display name and e-mail wording IAM names the application with. Every artifact
+ * role with its scope and the roles that may assign it; the link mounts; the delegations; the workloads; the locale,
+ * display name and e-mail wording IAM names the application with; and its terminal identification page. Every artifact
  * dimension is a scope, a file collection's `file:<name>` included, because access to a file is checked there.
  */
 export function schemaFromContract(artifact: ContractArtifact): AppSchema {
@@ -46,6 +46,7 @@ export function schemaFromContract(artifact: ContractArtifact): AppSchema {
 		...(artifact.mail === undefined ? {} : { mail: artifact.mail }),
 		...(artifact.members === undefined ? {} : { members: { manage: artifact.members.manage, list: artifact.members.list } }),
 		...(artifact.directory === 'labels' ? { directory: 'labels' } : {}),
+		...(artifact.terminal === undefined ? {} : { terminal: { identify: artifact.terminal.identify } }),
 	}
 }
 

package/src/contract/vocabulary.ts

@@ -2,20 +2,35 @@
 // nothing else, so the tables, the kit, the groups and the contract can each be typed by it without a cycle.
 // Browser-safe: plain data.
 
-import { type AppMembers, type DimensionDef, type Presentation, presentationOf, type RoleDefs, type Vocabulary, type WildcardMessage } from './define'
+import {
+	type AppMembers,
+	type DimensionDef,
+	type Presentation,
+	presentationOf,
+	type RoleDefs,
+	type TerminalDeclaration,
+	type Vocabulary,
+	type WildcardMessage,
+} from './define'
 
 /**
- * The vocabulary as `defineVocabulary` returned it, with its literal names, dimension definitions and the actions of its
- * people (`M`, `never` when it declares none).
+ * The vocabulary as `defineVocabulary` returned it, with its literal names, dimension definitions, the actions of its
+ * people (`M`, `never` when it declares none) and its terminal (`T`, `never` when it declares none).
  */
-export interface AppVocabulary<A extends string, D extends string, R extends string, Dims, M extends AppMembers<A> = never>
-	extends Vocabulary<A, D, R>
-{
+export interface AppVocabulary<
+	A extends string,
+	D extends string,
+	R extends string,
+	Dims,
+	M extends AppMembers<A> = never,
+	T extends TerminalDeclaration = never,
+> extends Vocabulary<A, D, R> {
 	readonly dimensions: Dims & { readonly [K in D]: DimensionDef<A, D, R> }
 	readonly members?: M
+	readonly terminal?: T
 }
 
-export type AnyAppVocabulary = AppVocabulary<string, string, string, unknown, AppMembers<string>>
+export type AnyAppVocabulary = AppVocabulary<string, string, string, unknown, AppMembers<string>, TerminalDeclaration>
 
 /**
  * Declares the dimensions, actions and roles, and how IAM names the application (`locale`, `displayName`). `src/vocabulary.ts` exports it; `defineTables`, `defineApp` and the
@@ -27,6 +42,7 @@ export function defineVocabulary<
 	const R extends string,
 	const Dims extends { readonly [K in D]: DimensionDef<NoInfer<A>, NoInfer<D>, NoInfer<R>> },
 	const M extends AppMembers<NoInfer<A>> = never,
+	const T extends TerminalDeclaration = never,
 >(
 	vocabulary: Presentation & {
 		readonly app: string
@@ -35,8 +51,9 @@ export function defineVocabulary<
 		readonly roles: RoleDefs<NoInfer<A>, NoInfer<D>, R>
 		readonly members?: M
 		readonly directory?: 'labels'
+		readonly terminal?: T
 	},
-): AppVocabulary<A, D, R, Dims, M> {
+): AppVocabulary<A, D, R, Dims, M, T> {
 	const people = vocabulary.members
 	return {
 		app: vocabulary.app,
@@ -46,5 +63,6 @@ export function defineVocabulary<
 		...presentationOf(vocabulary),
 		...(people === undefined ? {} : { members: people }),
 		...(vocabulary.directory === undefined ? {} : { directory: vocabulary.directory }),
+		...(vocabulary.terminal === undefined ? {} : { terminal: vocabulary.terminal }),
 	}
 }