@fabrika/app 0.8.2 → 0.9.0-cloudflare.1

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}`)
+	}
+}

package/src/implement/workload.ts

@@ -16,6 +16,7 @@ import {
 } from '@fabrika/auth-core'
 import type { TokenVerifier } from '@fabrika/jwks'
 import { z } from 'zod/v4'
+import { deadline } from './bounded'
 
 export type WorkloadKindOf = OwnWorkloadKind
 
@@ -39,20 +40,30 @@ export function issuerWorkloadTokens(
 ): WorkloadTokenSource {
 	return {
 		async exchange(input) {
-			const response = await fetcher(
-				new Request(new URL(WORKLOAD_TOKEN_PATH, issuer), {
-					method: 'POST',
-					headers: { authorization: `Bearer ${input.key}`, 'content-type': 'application/json' },
-					body: JSON.stringify({ app: input.app }),
-					redirect: 'manual',
-					signal: AbortSignal.timeout(EXCHANGE_TIMEOUT_MS),
-				}),
-			)
-			const parsed = response.status === 200 ? mintResultSchema.safeParse(await response.json()) : null
-			if (parsed === null || !parsed.success) {
-				throw new Error(`IAM answered the workload token exchange with ${response.status}`)
+			const timer = deadline(EXCHANGE_TIMEOUT_MS)
+			try {
+				const response = await fetcher(
+					new Request(new URL(WORKLOAD_TOKEN_PATH, issuer), {
+						method: 'POST',
+						headers: { authorization: `Bearer ${input.key}`, 'content-type': 'application/json' },
+						body: JSON.stringify({ app: input.app }),
+						redirect: 'manual',
+						signal: timer.signal,
+					}),
+				)
+				if (response.status !== 200) {
+					// Nothing reads a refusal's body, and once the deadline is cleared nothing else would end its stream.
+					await response.body?.cancel().catch(() => {})
+					throw new Error(`IAM answered the workload token exchange with ${response.status}`)
+				}
+				const parsed = mintResultSchema.safeParse(await response.json())
+				if (!parsed.success) {
+					throw new Error(`IAM answered the workload token exchange with ${response.status}`)
+				}
+				return parsed.data
+			} finally {
+				timer.clear()
 			}
-			return parsed.data
 		},
 	}
 }

package/src/jobs/report.ts

@@ -3,6 +3,7 @@
 // groups a framework report by its fingerprint and raises its new-issue and regression alerts, so each kind of
 // failure becomes one issue. What was thrown travels scrubbed as the report's cause chain (ADR-0059).
 
+import { deadline } from '../implement/bounded'
 import { exceptionChain, type ReportedException } from './exception'
 import type { Scrubber } from './scrub'
 
@@ -136,6 +137,7 @@ export function crashEnvelope(kind: CrashKind, error: unknown, options: Envelope
 
 async function deliver(options: OperationsReporterOptions, body: string): Promise<void> {
 	const send = options.fetch ?? ((request: Request) => fetch(request))
+	const timer = deadline(DELIVERY_TIMEOUT_MS)
 	const request = new Request(options.target.envelopeUrl, {
 		method: 'POST',
 		headers: {
@@ -143,7 +145,7 @@ async function deliver(options: OperationsReporterOptions, body: string): Promis
 			'x-sentry-auth': `Sentry sentry_version=7, sentry_key=${options.target.publicKey}`,
 		},
 		body,
-		signal: AbortSignal.timeout(DELIVERY_TIMEOUT_MS),
+		signal: timer.signal,
 	})
 	try {
 		const response = await send(request)
@@ -154,6 +156,8 @@ async function deliver(options: OperationsReporterOptions, body: string): Promis
 	} catch {
 		// The error may quote the ingest URL with its key.
 		console.error('fabrika: a report to Operations could not be delivered')
+	} finally {
+		timer.clear()
 	}
 }
 

package/src/jobs/runner.ts

@@ -10,6 +10,7 @@ import { type ContractArtifact, JOB_SITE_PREFIX, type JobArtifact, type JobMaile
 import type { CapabilityAuthority } from '@fabrika/db/capability'
 import { type DataAccess, type FrameworkTables, type JobLeases, type LeaseFence, LeaseLostError, type Session } from '@fabrika/db/framework'
 import { EmailDeliveryError, type EmailSenderCapabilities, mayRetryDelivery } from '@fabrika/email'
+import { uuidv7 } from '@fabrika/platform'
 import { NotFoundError } from '../errors'
 import { FileWork, type StoredFileKinds, storedFilesHandle } from '../files/kinds'
 import {
@@ -117,6 +118,8 @@ export interface FrameworkJob {
 export interface ContractJobs {
 	/** The contract's `c.cron` jobs; `run` also takes the name of a framework job the contract needs. */
 	readonly names: readonly string[]
+	/** Every job bound to run, the framework's included, with its schedule: what a minute tick runs when due. */
+	readonly scheduled: readonly { readonly name: string; readonly schedule: CronSchedule }[]
 	run(name: string, options?: JobRunOptions): Promise<JobRunResult>
 	/**
 	 * Registers every job (its first-seen time), reports a run that crashed and a job that has not succeeded within
@@ -328,6 +331,7 @@ export function bindJobs(input: JobBindingInput, problems: string[]): BoundJobs
 	})
 	const jobs: ContractJobs = Object.freeze({
 		names,
+		scheduled: Object.freeze([...bound.values(), ...frameworkJobs.values()].map(({ name, schedule }) => ({ name, schedule }))),
 		run(name: string, options: JobRunOptions = {}): Promise<JobRunResult> {
 			const own = frameworkJobs.get(name)
 			if (own !== undefined && framework !== null) {
@@ -432,7 +436,7 @@ function jobLinks(where: string, site: string, declaration: SiteDeclaration | nu
 	return { name, prefix: mount.prefix, dimension: mount.dimension, issuedBy: mount.issuedBy }
 }
 
-const attemptId = (): string => Bun.randomUUIDv7()
+const attemptId = (): string => uuidv7()
 
 /** Exponential from one second, capped at five minutes, with half of it jittered. */
 function backoffMs(attempt: number, random: number): number {
@@ -898,25 +902,37 @@ function kitJobContext(
 		db: siteData(reads, (action) => reads.app(app(action))),
 		sql: site.sql === null ? undeclaredSql(job, 'job') : jobSqlOutsideTransaction(job),
 		files: putAndOpen(boundTo(frame, () => false, 'ctx.files')),
-		transaction: async <R>(work: (tx: object) => Promise<R>): Promise<R> => {
+		transaction: async <R>(body: (tx: object) => Promise<R>): Promise<R> => {
 			// Outside its attempt there is no lease to fence the transaction with, so it never opens.
 			boundTo(frame, () => false)()
-			return data.transaction(async (session) => {
-				let open = true
-				const writes = jobHandles(frame, data, site, principal, 'mutation', async () => session, () => !open, undefined, binding)
-				try {
-					const sql = site.sql === null ? undeclaredSql(job, 'job', 'tx.sql') : jobSql(frame, data, site.sql, session, () => !open)
-					// Located in this transaction, so an object it wrote is found before the commit.
-					const located = (action: string, dimension: string, id: string) => {
-						boundTo(frame, () => !open, 'tx.ref')()
-						return ref(action, dimension, id, session)
+			// Its own files: a rollback releases only what this transaction staged, never a file of a concurrent one.
+			const own = new FileWork(frame, frame.id)
+			let rolledBack = false
+			try {
+				return await data.transaction(async (session) => {
+					let open = true
+					const writes = jobHandles(frame, data, site, principal, 'mutation', async () => session, () => !open, undefined, binding)
+					try {
+						const sql = site.sql === null ? undeclaredSql(job, 'job', 'tx.sql') : jobSql(frame, data, site.sql, session, () => !open)
+						// Located in this transaction, so an object it wrote is found before the commit.
+						const located = (action: string, dimension: string, id: string) => {
+							boundTo(frame, () => !open, 'tx.ref')()
+							return ref(action, dimension, id, session)
+						}
+						const files = storedFilesHandle(kinds, own, { where: job, check: boundTo(frame, () => !open, 'tx.files'), writes: true })
+						return await body(Object.freeze({ db: siteData(writes, (action) => writes.app(app(action))), sql, files, ref: located }))
+					} catch (error) {
+						rolledBack = true
+						throw error
+					} finally {
+						open = false
 					}
-					const files = putAndOpen(boundTo(frame, () => !open, 'tx.files'))
-					return await work(Object.freeze({ db: siteData(writes, (action) => writes.app(app(action))), sql, files, ref: located }))
-				} finally {
-					open = false
-				}
-			})
+				})
+			} catch (error) {
+				// A transaction the work threw out of is a known rollback; a failed commit is not, and the sweep decides.
+				if (rolledBack) await kinds?.release(own)
+				throw error
+			}
 		},
 	}
 }

package/src/jobs/schedule.ts

@@ -1,5 +1,6 @@
 // The five-field cron expressions of `c.cron`, read in UTC: which minutes a job is due, so the runner can tell how
-// long ago it should last have succeeded. The crontab, not this module, triggers a run.
+// long ago it should last have succeeded. On Bun the crontab triggers a run; on Cloudflare the application's object
+// runs, at each minute tick, the jobs `isDueAt` that minute.
 
 interface Field {
 	readonly min: number
@@ -96,6 +97,11 @@ function dayMatches(schedule: CronSchedule, day: Date): boolean {
 	return schedule.eitherDay ? byMonth || byWeek : byMonth && byWeek
 }
 
+/** Whether the schedule is due in the UTC minute that holds `at`: what a Worker's minute tick runs (ADR-0065). */
+export function isDueAt(schedule: CronSchedule, at: Date): boolean {
+	return schedule.minutes.has(at.getUTCMinutes()) && schedule.hours.has(at.getUTCHours()) && dayMatches(schedule, at)
+}
+
 const descending = (values: ReadonlySet<number>): number[] => [...values].sort((left, right) => right - left)
 
 /** The latest `count` due minutes at or before `at`, newest first; fewer when the schedule is that rare. */

package/src/jobs/scrub.ts

@@ -1,7 +1,16 @@
 // What an error report must not carry (ADR-0059): the values of the application's secrets, and anything shaped like a
 // credential — a JWT, an `Authorization` scheme or header, a URL's userinfo, a sensitive query parameter.
 
-import { FABRIKA_CONTRACT_DIGEST, FABRIKA_IAM_APP_ID, FABRIKA_IAM_ISSUER, PLATFORM_RECEIVERS, platformTransportVariables } from '@fabrika/auth-core'
+import {
+	FABRIKA_APPLICATION_OBJECT,
+	FABRIKA_APPLICATION_OBJECTS,
+	FABRIKA_CONTRACT_DIGEST,
+	FABRIKA_IAM_APP_ID,
+	FABRIKA_IAM_ISSUER,
+	FABRIKA_OPS_KEY_DIGESTS,
+	PLATFORM_RECEIVERS,
+	platformTransportVariables,
+} from '@fabrika/auth-core'
 import type { CapturedEnvironment } from '../implement/environment'
 
 export const REDACTED = '[redacted]'
@@ -21,6 +30,10 @@ const PUBLIC_FRAMEWORK_VARIABLES: ReadonlySet<string> = new Set([
 	FABRIKA_CONTRACT_DIGEST,
 	FABRIKA_IAM_APP_ID,
 	FABRIKA_IAM_ISSUER,
+	// Digests of the ops keys, which are no credential; the object names are words (`application`) a message carries.
+	FABRIKA_OPS_KEY_DIGESTS,
+	FABRIKA_APPLICATION_OBJECT,
+	FABRIKA_APPLICATION_OBJECTS,
 	...PLATFORM_RECEIVERS.map((receiver) => platformTransportVariables(receiver).url),
 ])