@fabrika/app 0.6.0 → 0.7.0

package/src/implement/egress.ts

@@ -0,0 +1,84 @@
+// `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.
+
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { CapabilityRefusedError } from './capability'
+
+interface EgressScope {
+	/** The site, as a refusal names it. */
+	readonly site: string
+	readonly origins: ReadonlySet<string>
+}
+
+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)
+}
+
+/**
+ * `facility` with each of its methods run outside any site's scope: a framework facility a handler calls, whose own
+ * requests are the platform's, not the site's.
+ */
+export function platformFacility<T extends object>(facility: T): T {
+	return new Proxy(facility, {
+		get(target, property) {
+			const value: unknown = Reflect.get(target, property, target)
+			if (typeof value !== 'function') {
+				return value
+			}
+			return (...args: unknown[]): unknown => scope.exit(() => Reflect.apply(value, target, args))
+		},
+	})
+}
+
+/** `work`, outside any site's scope: a framework call that happens to run inside a handler. */
+export function platformCall<T>(work: () => T): T {
+	return scope.exit(work)
+}
+
+/**
+ * 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.
+ */
+export function installEgressGuard(): void {
+	const current = globalThis.fetch
+	if (guards.has(current)) {
+		return
+	}
+	const guarded = Object.assign(
+		(input: string | URL | Request, init?: RequestInit): Promise<Response> => {
+			const running = scope.getStore()
+			if (running === undefined) {
+				return current(input, init)
+			}
+			const origin = originOf(input)
+			if (origin !== null && running.origins.has(origin)) {
+				return current(input, init)
+			}
+			return Promise.reject(
+				new CapabilityRefusedError(
+					'undeclared_egress',
+					origin === null
+						? `${running.site} called fetch with a URL that is not absolute`
+						: `${running.site} calls ${origin}, which it does not declare (egress: ['${origin}'])`,
+				),
+			)
+		},
+		{ preconnect: current.preconnect },
+	)
+	guards.add(guarded)
+	globalThis.fetch = guarded
+}
+
+function originOf(input: string | URL | Request): string | null {
+	try {
+		return new URL(typeof input === 'string' ? input : input instanceof URL ? input.href : input.url).origin
+	} catch {
+		return null
+	}
+}

package/src/implement/faults.ts

@@ -16,18 +16,28 @@ export const SERVER_FAULTS = {
 	output_refused: 'the handler returned a value its output schema refuses',
 	contract_inconsistent: 'the compiled endpoint misses what its kind needs (a path parameter, a body limit or a capability kind)',
 	webhook_binding_mismatch: "a webhook binding reaches another dimension than the webhook's",
+	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",
 	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",
 	file_key_taken: "a new file's object key already held an object this upload did not write",
-	file_collection_unknown: 'ctx.files named a collection the contract does not declare',
+	file_kind_unknown: 'ctx.files.put or a file field named a file kind the contract does not declare',
+	file_put: 'ctx.files.put was called without the options it takes ({ type, name? })',
+	file_output_kind: 'the handler answered a file of another kind than its output declares',
 	file_sweep_failed: "the sweep could not delete a removed or orphaned file's object or row; the next run retries it",
 	challenge_unavailable: "a form's challenge provider could not be reached in time or did not answer as it documents",
 	challenge_misconfigured: "a form's challenge provider refused the application's secret",
 	attachment_rows: 'the handler returned more rows than its attachment declares (maxRows)',
 	attachment_cell: 'a cell of the attachment is longer than one cell may hold',
 	attachment_size: 'the encoded attachment is larger than it declares (maxBytes); no body was sent',
+	redirect_refused:
+		"the handler redirected to a target that is neither its own origin's path, an origin its redirect() lists, nor a URL a verified token of the request carries",
+	token_claims_refused: "the claims a site signed are not what the token purpose's claims schema admits",
+	token_keys_missing: 'a site signed a token, and the environment holds no token key',
+	url_unbuildable:
+		'ctx.url named no procedure of the contract, passed a parameter its HTTP shape does not read, or the environment has no public origin',
 } as const
 
 export type ServerFaultReason = keyof typeof SERVER_FAULTS

package/src/implement/index.ts

@@ -10,8 +10,8 @@ export {
 	type EmailSenderCapabilities,
 	mayRetryDelivery,
 } from '@fabrika/email'
-export { FILE_SWEEP_JOB } from '../files/collections'
 export type { FileCollectionHandle, FileCollectionReader, FileListing, ListedFile, OpenedFile } from '../files/handle'
+export { FILE_SWEEP_JOB } from '../files/kinds'
 export {
 	FILE_SCAN_JOB,
 	type FileScanner,
@@ -51,7 +51,7 @@ export type {
 	MemberManagement,
 	MemberTarget,
 } from './membership'
-export type { AppPrincipal, LinkHolder, Principal, PrincipalOf, ServicePrincipal, UserPrincipal } from './principal'
+export type { AppPrincipal, LinkHolder, Principal, PrincipalOf, PublicPrincipal, ServicePrincipal, UserPrincipal } from './principal'
 export { type AppDeps, defineDeps, serve, type ServeOptions } from './serve'
 export type {
 	AccessContext,
@@ -63,6 +63,7 @@ export type {
 	Handler,
 	HandlerInput,
 	HandlersOf,
+	RequestClient,
 	RequestContext,
 	WebhookHandler,
 } from './types'

package/src/implement/invocation.ts

@@ -8,6 +8,7 @@ import {
 	type DataAccess,
 	type DataHandles,
 	type DataSite,
+	type FileBinding,
 	type InvocationTransaction,
 	type QueryRefusal,
 	QueryRefusedError,
@@ -17,7 +18,6 @@ import {
 import type { DataKind, UnscopedMode } from '@fabrika/db/tables'
 import type { SqlMode } from '../contract/context'
 import { DECLARED_FIELDS } from '../contract/declaration'
-import type { FileSite } from '../files/collections'
 import { CapabilityRefusedError, isActiveRequest, type RequestFrame } from './capability'
 import { ServerFault } from './faults'
 
@@ -27,8 +27,20 @@ export interface SiteDeclaration {
 	readonly unscoped: Readonly<Record<string, UnscopedMode>>
 	readonly connect: readonly string[]
 	readonly issues: string | null
-	readonly then: string | null
 	readonly mailer: JobMailer | null
+	/** The cron jobs `ctx.kick` may name. */
+	readonly kicks: readonly string[]
+	/** The webhook whose bindings `ctx.webhooks` creates and removes. */
+	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[]
+}
+
+/** A public procedure's reach: the texts the verified signed tokens of its request carry, which name the rows it changes. */
+export interface PublicReach {
+	readonly carried: ReadonlySet<string>
 }
 
 export type SiteFunction = (args: { readonly input?: unknown; readonly ctx: object }) => unknown
@@ -61,8 +73,11 @@ const NO_DECLARATION: SiteDeclaration = Object.freeze({
 	unscoped: Object.freeze({}),
 	connect: Object.freeze([]),
 	issues: null,
-	then: null,
 	mailer: null,
+	kicks: Object.freeze([]),
+	binds: null,
+	signs: Object.freeze([]),
+	egress: Object.freeze([]),
 })
 
 function isPlainObject(value: unknown): value is Readonly<Record<string, unknown>> {
@@ -131,22 +146,40 @@ export function parseDeclaration(where: string, declared: unknown, kind: DataKin
 	if (issues !== undefined && typeof issues !== 'string') {
 		problems.push(`${where}: issues is not the name of a link mount`)
 	}
-	const then = ownField(declared, 'then')
-	if (then !== undefined && typeof then !== 'string') {
-		problems.push(`${where}: then is not the name of a job`)
-	}
 	const mailerField = ownField(declared, 'mailer')
 	const mailer = JOB_MAILERS.find((transport) => transport === mailerField) ?? null
 	if (mailerField !== undefined && mailer === null) {
 		problems.push(`${where}: mailer is not 'installation' or 'own'`)
 	}
+	const kicksField = ownField(declared, 'kicks')
+	const kicks = Array.isArray(kicksField) ? kicksField.filter((name): name is string => typeof name === 'string') : []
+	if (kicksField !== undefined && (!Array.isArray(kicksField) || kicks.length !== kicksField.length)) {
+		problems.push(`${where}: kicks is not a list of job names`)
+	}
+	const binds = ownField(declared, 'binds')
+	if (binds !== undefined && typeof binds !== 'string') {
+		problems.push(`${where}: binds is not the name of a webhook`)
+	}
+	const signsField = ownField(declared, 'signs')
+	const signs = Array.isArray(signsField) ? signsField.filter((purpose): purpose is string => typeof purpose === 'string') : []
+	if (signsField !== undefined && (!Array.isArray(signsField) || signs.length !== signsField.length)) {
+		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`)
+	}
 	return Object.freeze({
 		sql: sql === 'read' || sql === 'write' ? sql : null,
 		unscoped: Object.freeze(unscoped),
 		connect: Object.freeze(connectors),
 		issues: typeof issues === 'string' ? issues : null,
-		then: typeof then === 'string' ? then : null,
 		mailer,
+		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()),
 	})
 }
 
@@ -187,14 +220,17 @@ export function approvedReach(site: string, artifact: ContractArtifact): SiteDec
 			unscoped: Object.freeze({ ...reach.unscoped }),
 			connect: Object.freeze([...reach.connect]),
 			issues: reach.issues,
-			then: reach.then ?? null,
 			mailer: reach.mailer ?? null,
+			kicks: Object.freeze([...(reach.kicks ?? [])]),
+			binds: reach.binds ?? null,
+			signs: Object.freeze([...(reach.signs ?? [])]),
+			egress: Object.freeze([...(reach.egress ?? [])]),
 		})
 }
 
 /**
- * A declaration as one comparable line: its fields in a fixed order, its tables and connectors sorted; `then` and
- * `mailer` only when declared.
+ * A declaration as one comparable line: its fields in a fixed order, its tables and connectors sorted; each optional
+ * field only when declared.
  */
 function describeDeclaration(declaration: SiteDeclaration): string {
 	const unscoped = Object.entries(declaration.unscoped).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
@@ -203,8 +239,11 @@ function describeDeclaration(declaration: SiteDeclaration): string {
 		unscoped,
 		connect: [...declaration.connect].sort(),
 		issues: declaration.issues,
-		...(declaration.then === null ? {} : { then: declaration.then }),
 		...(declaration.mailer === null ? {} : { mailer: declaration.mailer }),
+		...(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 }),
 	})
 }
 
@@ -235,8 +274,17 @@ export class Invocation {
 		this.#transaction = data.invocation(readOnly)
 	}
 
-	/** The handles of the site, all of them running in this invocation's transaction. */
-	handles(kind: DataKind, declaration: SiteDeclaration, principal: string): DataHandles {
+	/**
+	 * The handles of the site, all of them running in this invocation's transaction. A public procedure's (`reach` its
+	 * carried texts) insert and read under its actions only, and update or remove only a row a verified token names.
+	 */
+	handles(
+		kind: DataKind,
+		declaration: SiteDeclaration,
+		principal: string,
+		reach: PublicReach | 'declared' = 'declared',
+		files?: FileBinding,
+	): DataHandles {
 		const transaction = this.#transaction
 		const site: DataSite = {
 			kind,
@@ -244,6 +292,8 @@ export class Invocation {
 			principal,
 			check: boundTo(this.#frame, () => transaction.ended),
 			session: () => transaction.session(),
+			...(reach === 'declared' ? {} : { public: true, carried: reach.carried }),
+			...(files === undefined ? {} : { files }),
 		}
 		return this.#data.handles(site)
 	}
@@ -259,16 +309,16 @@ export class Invocation {
 		})
 	}
 
-	/** Where `ctx.files` runs: this invocation's transaction, bound like every handle; a query's only reads. */
-	fileSite(where: string, kind: DataKind): Omit<FileSite, 'frame'> {
+	/** The check of `ctx.files`: bound to this invocation's transaction, like every handle. */
+	fileCheck(): () => void {
 		const transaction = this.#transaction
-		return {
-			where,
-			check: boundTo(this.#frame, () => transaction.ended, 'ctx.files'),
-			session: () => transaction.session(),
-			readOnly: kind === 'mutation' && !transaction.readOnly ? null : 'a query reads only; remove files in a mutation',
-			attaches: false,
-		}
+		return boundTo(this.#frame, () => transaction.ended, 'ctx.files')
+	}
+
+	/** Where the framework writes for this site (a webhook binding): this invocation's transaction, bound like every handle. */
+	frameworkSite(handle: string): { readonly check: () => void; readonly session: () => Promise<Session> } {
+		const transaction = this.#transaction
+		return { check: boundTo(this.#frame, () => transaction.ended, handle), session: () => transaction.session() }
 	}
 
 	/** Commits; a request the caller abandoned meanwhile rolls back instead. */
@@ -297,14 +347,24 @@ export interface AccessCapabilities {
 	readonly app?: unknown
 }
 
-/** `ctx.db` of an endpoint, by its access form: the API matrix of `docs/reference/application-runtime.md`. */
+/**
+ * `ctx.db` of an endpoint, by its access form: the API matrix of `docs/reference/application-runtime.md`. An endpoint of
+ * several capabilities binds each, as a job binds what it minted: `ctx.db.on(ref)`, `.in(ref)`, `.over(within)`.
+ */
 export function endpointData(
 	handles: DataHandles,
-	form: 'on' | 'in' | 'over' | 'creates' | 'app' | 'member',
+	form: 'on' | 'in' | 'over' | 'creates' | 'app' | 'member' | 'capabilities',
 	access: AccessCapabilities,
 ): object {
 	const shared = { reference: handles.reference, ...(handles.unscoped === undefined ? {} : { unscoped: handles.unscoped }) }
 	switch (form) {
+		case 'capabilities':
+			return Object.freeze({
+				on: (ref: unknown) => handles.target(ref, 'on'),
+				in: (ref: unknown) => handles.target(ref, 'in'),
+				over: (within: unknown) => handles.within(within),
+				...shared,
+			})
 		case 'on':
 			return Object.freeze({ target: handles.target(access.target, 'on'), app: handles.app(access.target), ...shared })
 		case 'in':
@@ -321,17 +381,34 @@ export function endpointData(
 }
 
 /** `ctx.db` of a job or a webhook: each capability it minted or received binds the same handles an endpoint gets. */
-export function siteData(handles: DataHandles): object {
+export function siteData(handles: DataHandles, app: (action: string) => object): object {
 	return Object.freeze({
 		on: (ref: unknown) => handles.target(ref, 'on'),
 		in: (ref: unknown) => handles.target(ref, 'in'),
 		over: (within: unknown) => handles.within(within),
+		app,
 		reference: handles.reference,
 		...(handles.unscoped === undefined ? {} : { unscoped: handles.unscoped }),
 	})
 }
 
-/** The handles of a job attempt, outside its fenced transaction (`'job'`, each read on its own) or inside it. */
+/**
+ * `ctx.app` and `ctx.db.app` of a webhook bound to a dimension. The types already refuse them; at run time they exist
+ * only to refuse by name.
+ */
+export function boundWebhookApp(webhook: string): (action: string) => never {
+	return () => {
+		throw new CapabilityRefusedError(
+			'undeclared_action',
+			`webhook '${webhook}' is bound to a dimension and acts on its bound value: use ctx.refs and ctx.db.on(ref)`,
+		)
+	}
+}
+
+/**
+ * The handles of a job attempt, outside its fenced transaction (`'job'`, each read on its own) or inside it. `tickMs`,
+ * the job's schedule period, is a queue claim's first backoff.
+ */
 export function jobHandles(
 	frame: RequestFrame,
 	data: DataAccess,
@@ -340,8 +417,18 @@ export function jobHandles(
 	kind: 'job' | 'mutation',
 	session: () => Promise<Session>,
 	ended: () => boolean,
+	tickMs?: number,
+	files?: FileBinding,
 ): DataHandles {
-	return data.handles({ kind, unscoped: declaration.unscoped, principal, check: boundTo(frame, ended), session })
+	return data.handles({
+		kind,
+		unscoped: declaration.unscoped,
+		principal,
+		check: boundTo(frame, ended),
+		session,
+		...(tickMs === undefined ? {} : { tickMs }),
+		...(files === undefined ? {} : { files }),
+	})
 }
 
 /**
@@ -366,14 +453,27 @@ export function jobSqlOutsideTransaction(job: string): SqlTag {
 	return refusingSql('sql_outside_transaction', `${job} runs ctx.sql inside ctx.transaction((tx) => …), as tx.sql`)
 }
 
-/** `ctx.files` of a contract that declares no file collection: every name is refused. */
-export function noFileCollections(where: string): (collection: string) => never {
-	return (collection) => {
-		throw new ServerFault('file_collection_unknown', `${where}: ctx.files('${String(collection)}') names a collection, and the contract declares none`)
-	}
-}
-
 /** `tx.sql` of a job site that declares it: its statements run in the attempt's fenced transaction. */
 export function jobSql(frame: RequestFrame, data: DataAccess, mode: SqlMode, session: Session, ended: () => boolean): SqlTag {
 	return data.sql({ mode, check: boundTo(frame, ended, 'tx.sql'), session: async () => session, fail: () => session.fail() })
 }
+
+/**
+ * `ctx.kick` of one invocation: it names only a declared job, and records it; the dispatcher sends each recorded job once,
+ * after the commit, and nothing on a rollback.
+ */
+export function kickRecorder(
+	site: string,
+	declared: readonly string[],
+): { readonly kick: (job: string) => void; readonly kicked: () => readonly string[] } {
+	const kicked = new Set<string>()
+	return {
+		kick: (job: string) => {
+			if (!declared.includes(job)) {
+				throw new CapabilityRefusedError('undeclared_kick', `${site} does not declare kicks: ['${String(job)}']`)
+			}
+			kicked.add(job)
+		},
+		kicked: () => [...kicked],
+	}
+}

package/src/implement/params.ts

@@ -0,0 +1,88 @@
+// Flat scalar parameters: a GET procedure's input and a POST's `query` from the URL, and a native form's urlencoded body.
+// Each parameter becomes the value its field's schema reads: a string as it is, a number, a boolean and `null` only in
+// their canonical spelling, so one value has one URL. A name sent twice is refused; an unknown name is the strict
+// input's to refuse.
+
+import type { SchemaShape } from '@fabrika/auth-core'
+import { BadRequestError, HttpError } from '../errors'
+
+/** The longest URL a procedure reads its parameters from. */
+export const MAX_URL_LENGTH = 8192
+
+/** The parameters of `params` as the object `shape`'s fields read them; `shape` is a flat object, or `null` for none. */
+export function paramsObject(params: URLSearchParams, shape: SchemaShape | null): Record<string, unknown> {
+	const fields = shape?.type === 'object' ? shape.fields : {}
+	const read: Record<string, unknown> = {}
+	for (const [name, value] of params) {
+		if (Object.hasOwn(read, name)) {
+			throw new BadRequestError(`the parameter '${name}' is sent twice`)
+		}
+		const field = Object.hasOwn(fields, name) ? fields[name] : undefined
+		read[name] = field === undefined ? value : scalarOf(field, value)
+	}
+	return read
+}
+
+/** The URL's parameters of a request, within `MAX_URL_LENGTH`. */
+export function urlParams(request: Request): URLSearchParams {
+	if (request.url.length > MAX_URL_LENGTH) {
+		throw new HttpError(414, 'url_too_long', `The URL is longer than ${MAX_URL_LENGTH} characters`)
+	}
+	return new URL(request.url).searchParams
+}
+
+/** A parameter's value as `shape` reads it; a value no alternative spells canonically stays text, for the schema to refuse. */
+function scalarOf(shape: SchemaShape, value: string): unknown {
+	switch (shape.type) {
+		case 'optional':
+			return scalarOf(shape.inner, value)
+		case 'nullable':
+			return value === 'null' && !readsText(shape.inner) ? null : scalarOf(shape.inner, value)
+		case 'number':
+			return canonicalNumber(value) ?? value
+		case 'boolean':
+			return value === 'true' ? true : value === 'false' ? false : value
+		case 'null':
+			return value === 'null' ? null : value
+		case 'literal':
+			return typeof shape.value === 'string' ? value : scalarOf(literalShape(shape.value), value)
+		case 'union':
+			for (const option of shape.options) {
+				const read = scalarOf(option, value)
+				if (read !== value || readsText(option)) return read
+			}
+			return value
+		default:
+			return value
+	}
+}
+
+function literalShape(value: number | boolean | null): SchemaShape {
+	if (value === null) return { type: 'null' }
+	if (typeof value === 'boolean') return { type: 'boolean' }
+	return { type: 'number', int: false, min: null, exclusiveMin: false, max: null, exclusiveMax: false, multipleOf: null }
+}
+
+/** Whether the shape reads text as itself, so `null` and `true` stay strings there. */
+function readsText(shape: SchemaShape): boolean {
+	switch (shape.type) {
+		case 'string':
+		case 'enum':
+			return true
+		case 'literal':
+			return typeof shape.value === 'string'
+		case 'optional':
+		case 'nullable':
+			return readsText(shape.inner)
+		case 'union':
+			return shape.options.some(readsText)
+		default:
+			return false
+	}
+}
+
+/** `value` as a number when it is that number's canonical spelling (`1.5`, `-3`, never `01`, `1e3` or `+2`). */
+function canonicalNumber(value: string): number | null {
+	const number = Number(value)
+	return value !== '' && Number.isFinite(number) && String(number) === value ? number : null
+}

package/src/implement/principal.ts

@@ -35,6 +35,13 @@ export interface AppPrincipal<Id extends string = string> {
 
 export type Principal = UserPrincipal | ServicePrincipal | LinkHolder | AppPrincipal
 
+/** Whoever called a public procedure: nobody the platform knows. The handler runs as the endpoint's own workload. */
+export interface PublicPrincipal {
+	readonly kind: 'public'
+	/** The endpoint id, which is the workload's name: `<mount>.<group>.<procedure>`. */
+	readonly endpoint: string
+}
+
 export type PrincipalOf<C> = C extends 'human' ? UserPrincipal
 	: C extends 'machine' ? ServicePrincipal
 	: C extends 'link' ? LinkHolder