@fabrika/app 0.8.2 → 0.9.0-cloudflare.2

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/failures.ts

@@ -2,7 +2,7 @@
 // fixed codes and bounded identifiers only, never an error's name or message: application code, drivers and even the
 // framework's own refusals can put request data there. The event adds what was thrown as its cause chain, scrubbed of
 // the environment's secrets and of credential patterns, a framework failure's message replaced by its catalog text
-// (ADR-0059).
+// (ADR-0059). A writing invocation that held its Durable Object's transaction too long is an event on the same budget.
 
 import { CAPABILITY_ERRORS, CapabilityError, QUERY_REFUSALS, QueryRefusedError } from '@fabrika/db/framework'
 import { isStructuralError } from '../errors'
@@ -127,4 +127,20 @@ export class FailureReports {
 			error: failure.error,
 		})
 	}
+
+	/**
+	 * A writing invocation that held its object's transaction past `@fabrika/db`'s report threshold, which already
+	 * logged it. Never rejects; the delivery may outlive the response like a failure's.
+	 */
+	held(endpoint: string, heldMs: number): Promise<void> {
+		if (this.#reporter === null || !this.#budget.admit()) {
+			return Promise.resolve()
+		}
+		return this.#reporter.report({
+			fingerprint: ['fabrika-transaction-held', endpoint],
+			type: 'TransactionHeld',
+			message: `endpoint '${endpoint}' held its object's transaction for ${heldMs} ms`,
+			tags: { endpoint, code: 'transaction_held', held_ms: String(heldMs) },
+		})
+	}
 }

package/src/implement/faults.ts

@@ -19,6 +19,7 @@ export const SERVER_FAULTS = {
 	webhook_unverifiable: 'a webhook verifies a signature over its public URL (Twilio), and the environment has no FABRIKA_APP_ORIGIN',
 	webhook_claim_lost: "a delivery's claim expired and another copy of the delivery took it over before this one committed; nothing it wrote is kept",
 	workload_unauthorized: "the workload's key or token does not carry the authority its declaration needs",
+	terminal_refused: "IAM refused the application's own credential for an identification at a terminal",
 	request_cancelled: 'the request was cancelled or outlived its budget before its transaction committed; nothing it wrote is kept',
 	file_object_missing: "a file's object is missing from storage",
 	file_object_mismatch: "a file's object has another size than its row records",

package/src/implement/index.ts

@@ -53,6 +53,7 @@ export type {
 } from './membership'
 export type { AppPrincipal, LinkHolder, Principal, PrincipalOf, PublicPrincipal, ServicePrincipal, UserPrincipal } from './principal'
 export { type AppDeps, defineDeps, serve, type ServeOptions } from './serve'
+export type { AssertedIdentity, OpenIdentification, TerminalIdentification } from './terminals'
 export type {
 	AccessContext,
 	ConnectCall,

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 }),
 	})
 }
 
@@ -321,6 +322,14 @@ export class Invocation {
 		return { check: boundTo(this.#frame, () => transaction.ended, handle), session: () => transaction.session() }
 	}
 
+	/**
+	 * Runs `work`, from the handler to `commit`, in this invocation's transaction. On SQLite it encloses `work`, and a
+	 * hold past `@fabrika/db`'s report threshold reaches `held`, logged under `site`.
+	 */
+	enclose<T>(work: () => Promise<T>, site: string, held: (heldMs: number) => void): Promise<T> {
+		return this.#transaction.enclose(work, { site, held })
+	}
+
 	/** Commits; a request the caller abandoned meanwhile rolls back instead. */
 	async commit(signal: AbortSignal | null): Promise<void> {
 		if (signal?.aborted === true) {

package/src/implement/principal.ts

@@ -1,6 +1,15 @@
 // Who called: the caller kind a verified token presents, and the principal a handler sees for it.
 
-import { type AccessTokenClaims, APP_CALLER_PREFIX, type Caller, callerOf, matchAction, OAUTH_CALLER, type PermissionEntry } from '@fabrika/auth-core'
+import {
+	type AccessTokenClaims,
+	APP_CALLER_PREFIX,
+	type Caller,
+	callerOf,
+	matchAction,
+	OAUTH_CALLER,
+	type PermissionEntry,
+	type TerminalTokenClaims,
+} from '@fabrika/auth-core'
 import type { PageCaller } from '../client/caller'
 
 /** A person: the IAM session, or a `px_` key bound to a user principal. */
@@ -11,6 +20,11 @@ export interface UserPrincipal {
 	readonly label: string
 	/** The mailbox IAM recorded for the person, lower-cased: the one to mail, not proof of possession. Only a person has one. */
 	readonly email: string
+	/**
+	 * The enrolled terminal the person signed in on, when an application asserted them there (ADR-0067); absent for every
+	 * other sign-in. Information for the handler: what the session may do is in its permissions already.
+	 */
+	readonly terminal?: TerminalTokenClaims
 }
 
 /** A machine: a `px_` key bound to a service principal. */
@@ -65,7 +79,16 @@ export function presentedBy(claims: AccessTokenClaims): Presented | Unpresented
 	switch (caller) {
 		case 'human':
 			if (claims.email === undefined) return 'no_mailbox'
-			return { caller, principal: { kind: 'user', id: claims.sub, label: claims.label ?? claims.sub, email: claims.email } }
+			return {
+				caller,
+				principal: {
+					kind: 'user',
+					id: claims.sub,
+					label: claims.label ?? claims.sub,
+					email: claims.email,
+					...(claims.terminal === undefined ? {} : { terminal: Object.freeze({ id: claims.terminal.id, label: claims.terminal.label }) }),
+				},
+			}
 		case 'machine':
 			return { caller, principal: { kind: 'service', id: claims.sub, label: claims.label ?? claims.sub } }
 		case 'link':

package/src/implement/terminals.ts

@@ -0,0 +1,93 @@
+// `ctx.terminals`: the identification of a person at an enrolled terminal (ADR-0067). The application's identification
+// page sends what the person entered to its own procedure, which asks IAM through these calls. The framework presents
+// the request's credential (a public procedure's workload token), and IAM takes the asserting application from the
+// verified transport. Throttling guesses is the application's: `inspect` hands it the terminal to key them on.
+
+import type { IamTerminalRpc, IdentificationTerminal, MembershipCaller, TerminalFailure } from '@fabrika/auth-core'
+import { ServerFault } from './faults'
+
+/** An identification id longer than this is none IAM issued, so no call is made for it. */
+const MAX_IDENTIFICATION_ID_LENGTH = 200
+
+/** An open identification: the terminal it was opened on and when it expires (unix seconds). */
+export interface OpenIdentification {
+	readonly terminal: IdentificationTerminal
+	readonly expiresAt: number
+}
+
+/**
+ * IAM's answer to an assertion: the URL the browser goes to next, or why IAM refused. `not_found` is an identification
+ * that is unknown, expired, used, cancelled or no longer open to this application; `invalid_principal` a principal
+ * that cannot sign in on a terminal (unknown, disabled, not a person, or external).
+ */
+export type AssertedIdentity =
+	| { readonly ok: true; readonly completionUrl: string }
+	| { readonly ok: false; readonly reason: 'not_found' | 'invalid_principal' }
+
+/** `ctx.terminals` of an application that declares `terminal: { identify }`. */
+export interface TerminalIdentification {
+	/** The open identification `id` (the page's `identification` query parameter), or null when there is none. */
+	inspect(id: string): Promise<OpenIdentification | null>
+	/**
+	 * The application's word that `principalId` stands at the identification's terminal. IAM uses the identification up
+	 * and, on `ok`, the handler sends the browser to `completionUrl`: IAM signs the person in there, and only on the
+	 * terminal's own browser.
+	 */
+	assert(id: string, principalId: string): Promise<AssertedIdentity>
+	/** Ends an identification the person abandoned; one that is no longer open is already ended. */
+	cancel(id: string): Promise<void>
+}
+
+/** `ctx.terminals` for one request: every call carries the request's credential and correlation id. */
+export function terminalIdentification(rpc: IamTerminalRpc, caller: MembershipCaller): TerminalIdentification {
+	return Object.freeze({
+		async inspect(id: string): Promise<OpenIdentification | null> {
+			if (!isIdentificationId(id)) return null
+			const result = await ask(() => rpc.inspectIdentification({ ...caller, id }), 'inspect an identification')
+			if (!result.ok) return null
+			return Object.freeze({ terminal: Object.freeze({ id: result.terminal.id, label: result.terminal.label }), expiresAt: result.expiresAt })
+		},
+		async assert(id: string, principalId: string): Promise<AssertedIdentity> {
+			if (!isIdentificationId(id)) return { ok: false, reason: 'not_found' }
+			const result = await ask(() => rpc.assertIdentity({ ...caller, id, principalId }), 'assert an identity')
+			return result.ok ? { ok: true, completionUrl: result.completionUrl } : { ok: false, reason: result.reason }
+		},
+		async cancel(id: string): Promise<void> {
+			if (isIdentificationId(id)) {
+				await ask(() => rpc.cancelIdentification({ ...caller, id }), 'cancel an identification')
+			}
+		},
+	})
+}
+
+function isIdentificationId(id: string): boolean {
+	return id !== '' && id.length <= MAX_IDENTIFICATION_ID_LENGTH
+}
+
+/**
+ * Runs one IAM call. A transport failure is a 503 that names nothing; IAM refusing the application's own credential is
+ * a server fault, because the visitor cannot change it. What remains is the handler's answer.
+ */
+async function ask<T extends { readonly ok: true }>(
+	work: () => Promise<T | TerminalFailure>,
+	operation: string,
+): Promise<T | { readonly ok: false; readonly reason: 'not_found' | 'invalid_principal' }> {
+	let result: T | TerminalFailure
+	try {
+		result = await work()
+	} catch {
+		throw new ServerFault('iam_unavailable', `IAM could not be asked to ${operation}`, 503)
+	}
+	if (result.ok) {
+		return result
+	}
+	switch (result.reason) {
+		case 'not_found':
+		case 'invalid_principal':
+			return { ok: false, reason: result.reason }
+		case 'missing_token':
+		case 'invalid_token':
+		case 'not_allowed':
+			throw new ServerFault('terminal_refused', `IAM refused the application's credential to ${operation}: ${result.reason}`)
+	}
+}