@fabrika/app 0.3.2 → 0.4.0

package/src/implement/bounded.ts

@@ -0,0 +1,72 @@
+// Reading a body with a byte budget, and a handler's time budget. A body over the budget, or one whose reader the
+// deadline cancels, is never buffered whole: the stream is cancelled and nothing of it is kept.
+
+/**
+ * How long a request handler runs before its `ctx.signal` aborts and its transaction cannot commit. It equals
+ * `Bun.serve`'s default `idleTimeout`, which already closes a connection the server sends nothing on for that long, so
+ * both runtimes stop a handler at the same point.
+ */
+export const REQUEST_BUDGET_MS = 10_000
+
+/** A handler's `ctx.signal`: aborted when the client leaves (`request.signal`) or once `budgetMs` passed. */
+export function handlerSignal(request: Request, budgetMs: number = REQUEST_BUDGET_MS): AbortSignal {
+	return AbortSignal.any([request.signal, AbortSignal.timeout(budgetMs)])
+}
+
+export interface BoundedRead {
+	readonly maxBytes: number
+	/** `Content-Length`, when the sender declared one: a larger value is refused before anything is read. */
+	readonly declaredLength?: string | null
+	/** Aborting it cancels the stream; the read then rejects. */
+	readonly signal?: AbortSignal
+}
+
+/** The body's bytes, or `null` when it is larger than `maxBytes`. Rejects when `signal` aborts the read. */
+export async function readBoundedBytes(stream: ReadableStream<Uint8Array> | null, options: BoundedRead): Promise<Uint8Array<ArrayBuffer> | null> {
+	const declared = Number(options.declaredLength ?? '')
+	if (options.declaredLength !== undefined && options.declaredLength !== null && Number.isFinite(declared) && declared > options.maxBytes) {
+		await stream?.cancel()
+		return null
+	}
+	const reader = stream?.getReader()
+	if (reader === undefined) {
+		return new Uint8Array()
+	}
+	const { signal } = options
+	const aborted = (): boolean => signal?.aborted === true
+	const cancel = () => {
+		reader.cancel().catch(() => {})
+	}
+	signal?.addEventListener('abort', cancel, { once: true })
+	try {
+		const chunks: Uint8Array[] = []
+		let size = 0
+		for (;;) {
+			if (aborted()) {
+				throw new Error('the read was aborted')
+			}
+			const { done, value } = await reader.read()
+			if (aborted()) {
+				throw new Error('the read was aborted')
+			}
+			if (done) {
+				break
+			}
+			size += value.byteLength
+			if (size > options.maxBytes) {
+				await reader.cancel()
+				return null
+			}
+			chunks.push(value)
+		}
+		const body = new Uint8Array(size)
+		let offset = 0
+		for (const chunk of chunks) {
+			body.set(chunk, offset)
+			offset += chunk.byteLength
+		}
+		return body
+	} finally {
+		signal?.removeEventListener('abort', cancel)
+	}
+}

package/src/implement/browser-config.ts

@@ -0,0 +1,54 @@
+// What an SPA mount answers at `<prefix>/__fabrika-config.json`: the browser's Operations settings and the public
+// values the contract names, and nothing else of the environment.
+
+import type { ContractArtifact } from '@fabrika/auth-core'
+import type { CapturedEnvironment } from './environment'
+
+export interface BrowserConfig {
+	/** The Operations ingest DSN (a public key), or `null` without one. */
+	readonly dsn: string | null
+	readonly release: string | null
+	/**
+	 * Every form challenge's site key, and the variables the mount lists in `public`, by variable name. Absent when
+	 * there is none, so the file of an application without them holds the two Operations values only.
+	 */
+	readonly public?: Readonly<Record<string, string>>
+}
+
+/**
+ * The browser config of each SPA mount, by mount name: the Operations settings, and the public variables the contract
+ * names. A named variable that is not set is a boot problem.
+ */
+export function browserConfigs(
+	artifact: ContractArtifact,
+	environment: CapturedEnvironment,
+	operations: Pick<BrowserConfig, 'dsn' | 'release'>,
+	problems: string[],
+): ReadonlyMap<string, BrowserConfig> {
+	// A value is served as the environment holds it; only a blank one counts as unset.
+	const valueOf = (name: string): string | null => {
+		const value: unknown = environment.application[name]
+		return typeof value === 'string' && value.trim() !== '' ? value : null
+	}
+	const siteKeys: Record<string, string> = {}
+	for (const [form, mount] of Object.entries(artifact.mounts)) {
+		const challenge = mount.kind === 'form' ? mount.challenge : undefined
+		if (challenge?.siteKey === undefined) continue
+		const value = valueOf(challenge.siteKey)
+		if (value === null) problems.push(`form '${form}' names its ${challenge.provider} site key in ${challenge.siteKey}, which is not set`)
+		else siteKeys[challenge.siteKey] = value
+	}
+	const configs = new Map<string, BrowserConfig>()
+	for (const [name, mount] of Object.entries(artifact.mounts)) {
+		if (mount.kind !== 'spa') continue
+		const own: Record<string, string> = {}
+		for (const variable of mount.public ?? []) {
+			const value = valueOf(variable)
+			if (value === null) problems.push(`mount '${name}' serves the public variable ${variable}, which is not set`)
+			else own[variable] = value
+		}
+		const served = { ...siteKeys, ...own }
+		configs.set(name, Object.freeze(Object.keys(served).length === 0 ? { ...operations } : { ...operations, public: Object.freeze(served) }))
+	}
+	return configs
+}

package/src/implement/capability.ts

@@ -0,0 +1,439 @@
+// `Ref` and `Within`: the capabilities the framework mints after an access check. A handler receives them in `ctx`;
+// it can neither construct one nor use one outside the request that obtained it. `@fabrika/db` checks the kind, the
+// dimension and the action of every capability it is handed, and asks the runtime's authority whether it is authentic.
+// Each `boot` makes its own issuer: its stores accept only what its own dispatcher and job runner minted, so a mint
+// that application code makes, or a second runtime it boots, reaches none of them.
+
+import {
+	type AppCapability as AppCapabilityType,
+	type AppGrant,
+	type CapabilityAuthority,
+	type CapabilityGrant,
+	type ContainerGrant,
+	describeGrant,
+	type LeaseFence,
+	MAX_WITHIN_VALUES,
+	type Ref as RefCapability,
+	type RefGrant,
+	type Within as WithinCapability,
+	type WithinGrant,
+} from '@fabrika/db/capability'
+import { AsyncLocalStorage } from 'node:async_hooks'
+
+/** Why a capability or a handle was refused, as a closed catalog with the fixed text a log may print. */
+export const CAPABILITY_REFUSALS = {
+	not_minted: 'a value the framework did not mint was used as a capability; pass the ctx.target or ctx.within of this request',
+	ended: 'a capability or handle was used after its request, invocation or attempt ended',
+	foreign_work: 'a capability or handle was used from other work than the request it belongs to',
+	wrong_target: "an IAM request was not passed this request's ctx.target",
+	undeclared_action: "the job's declaration or its token does not carry the action",
+	undeclared_dimension: 'the job named a dimension the contract does not declare',
+	missing_id: 'the job named an object without an id',
+	wrong_capability: 'a file collection was handed a capability of another dimension or action than the operation needs',
+} as const
+
+export type CapabilityRefusal = keyof typeof CAPABILITY_REFUSALS
+
+/** A capability that is forged, from a request that has ended, or from another request than the current one. */
+export class CapabilityRefusedError extends Error {
+	override readonly name = 'CapabilityRefusedError'
+	/** What a log may say; the message is for the author's own run. */
+	readonly reason: CapabilityRefusal
+
+	constructor(reason: CapabilityRefusal, message: string) {
+		super(message)
+		this.reason = reason
+	}
+}
+
+/** A `Within` that would carry more scope values than one statement may bind; the caller is refused, not truncated. */
+export class CapabilityLimitError extends Error {
+	override readonly name = 'CapabilityLimitError'
+}
+
+/**
+ * One request's lifetime, or one job attempt's. A capability minted in it is usable only while it runs, and only
+ * inside it; a job attempt's writes also need its lease (`fence`).
+ */
+export class RequestFrame {
+	readonly id: string
+	readonly fence: LeaseFence | null
+	/** An export's request: the data layer runs its every statement `READ ONLY` and refuses every write. */
+	readonly readOnly: boolean
+	/** The endpoint the request is served by; `ctx.connect` checks it against each import's `usedBy`. */
+	readonly endpoint: string | null
+	#ended = false
+
+	constructor(
+		id: string,
+		options: { readonly fence?: LeaseFence | null; readonly readOnly?: boolean; readonly endpoint?: string | null } = {},
+	) {
+		this.id = id
+		this.fence = options.fence ?? null
+		this.readOnly = options.readOnly ?? false
+		this.endpoint = options.endpoint ?? null
+	}
+
+	get ended(): boolean {
+		return this.#ended
+	}
+
+	end(): void {
+		this.#ended = true
+	}
+}
+
+const currentRequest = new AsyncLocalStorage<RequestFrame>()
+
+/** Run `work` as the request `frame`: every capability check inside it compares against this frame. */
+export function runInRequest<T>(frame: RequestFrame, work: () => Promise<T>): Promise<T> {
+	return currentRequest.run(frame, work)
+}
+
+/** Whether `frame` is the request running now. */
+export function isActiveRequest(frame: RequestFrame): boolean {
+	return currentRequest.getStore() === frame
+}
+
+/** Whether the request running now may only read; `@fabrika/db` asks it before every statement. */
+export function requestIsReadOnly(): boolean {
+	return currentRequest.getStore()?.readOnly === true
+}
+
+/** The module-private token that makes a `Ref` or a `Within` constructible by the framework only. */
+const MINT: unique symbol = Symbol('fabrika.capability.mint')
+
+// Captured when the module loads, before application code: a later patch to Map, Object or Reflect does not change
+// how a chain is copied.
+const CapturedMap = Map
+const mapSet = Map.prototype.set
+const mapForEach: (this: ReadonlyMap<string, string>, callback: (value: string, key: string) => void) => void = Map.prototype.forEach
+const apply = Reflect.apply
+const freeze = Object.freeze
+
+type Chain = readonly (readonly [dimension: string, value: string])[]
+
+function chainOf(map: ReadonlyMap<string, string>): Chain {
+	const links: (readonly [string, string])[] = []
+	apply(mapForEach, map, [
+		(value: string, key: string) => {
+			links[links.length] = freeze([key, value])
+		},
+	])
+	return freeze(links)
+}
+
+/** A fresh Map of the chain: whoever holds it may change it, and the next resolution is a new copy again. */
+function mapOf(chain: Chain): Map<string, string> {
+	const map = new CapturedMap<string, string>()
+	for (let index = 0; index < chain.length; index++) {
+		const link = chain[index]
+		if (link !== undefined) {
+			apply(mapSet, map, [link[0], link[1]])
+		}
+	}
+	return map
+}
+
+function copyOf(values: readonly string[]): readonly string[] {
+	const copy: string[] = []
+	for (let index = 0; index < values.length; index++) {
+		copy[index] = values[index] ?? ''
+	}
+	return freeze(copy)
+}
+
+/** A frozen copy of the container grants, by index: a later patch to Array methods does not change what was minted. */
+function containerGrantsOf(containers: readonly ContainerGrant[]): readonly ContainerGrant[] {
+	const copy: ContainerGrant[] = []
+	for (let index = 0; index < containers.length; index++) {
+		const container = containers[index]
+		if (container !== undefined) {
+			copy[copy.length] = freeze({ dimension: container.dimension, values: copyOf(container.values) })
+		}
+	}
+	return freeze(copy)
+}
+
+interface RefFacts {
+	readonly dimension: string
+	readonly action: string
+	readonly principal: string
+	readonly id: string
+	readonly chain: Chain
+}
+
+interface Bound {
+	readonly grant: CapabilityGrant
+	readonly frame: RequestFrame
+	/** The issuer that minted it; only that issuer's authority accepts it. */
+	readonly issuer: object
+}
+
+let readRef: (value: unknown) => Bound | undefined = () => undefined
+let readWithin: (value: unknown) => Bound | undefined = () => undefined
+let readApp: (value: unknown) => Bound | undefined = () => undefined
+
+/** One authorized object for one action, in one request. `chain` holds the containers the object lies in. */
+export class Ref<D extends string, A extends string> implements RefCapability<D, A> {
+	declare readonly '~capability': { readonly kind: 'ref'; readonly dimension: D; readonly action: A }
+	readonly #dimension: D
+	readonly #action: A
+	readonly #facts: RefFacts
+	readonly #frame: RequestFrame
+	readonly #issuer: object
+
+	constructor(
+		token: typeof MINT,
+		issuer: object,
+		frame: RequestFrame,
+		dimension: D,
+		action: A,
+		principal: string,
+		id: string,
+		chain: ReadonlyMap<string, string>,
+	) {
+		if (token !== MINT) {
+			throw new CapabilityRefusedError('not_minted', 'a Ref is minted by the framework only; declare the access form in fabrika.contract.ts')
+		}
+		this.#dimension = dimension
+		this.#action = action
+		this.#facts = freeze({ dimension, action, principal, id, chain: chainOf(chain) })
+		this.#frame = frame
+		this.#issuer = issuer
+	}
+
+	get dimension(): D {
+		return this.#dimension
+	}
+
+	get action(): A {
+		return this.#action
+	}
+
+	/** The object's id: the value of its dimension. */
+	get value(): string {
+		return this.#facts.id
+	}
+
+	/** The containers of the object, by dimension (`workspace → w1` for a note); a copy. */
+	get chain(): ReadonlyMap<string, string> {
+		return mapOf(this.#facts.chain)
+	}
+
+	static {
+		readRef = (value) => {
+			if (typeof value !== 'object' || value === null || !(#facts in value)) {
+				return undefined
+			}
+			const facts = value.#facts
+			const grant: RefGrant = freeze({
+				kind: 'ref',
+				dimension: facts.dimension,
+				action: facts.action,
+				principal: facts.principal,
+				id: facts.id,
+				chain: mapOf(facts.chain),
+			})
+			return { grant, frame: value.#frame, issuer: value.#issuer }
+		}
+	}
+}
+
+/**
+ * The values of one dimension in which the caller holds one action, in one request; `all` for a global grant. The
+ * containers whose grants also authorise it stay separate, so the data layer matches them against each row's chain.
+ */
+export class Within<D extends string, A extends string> implements WithinCapability<D, A> {
+	declare readonly '~capability': { readonly kind: 'within'; readonly dimension: D; readonly action: A }
+	readonly #dimension: D
+	readonly #action: A
+	readonly #grant: WithinGrant
+	readonly #frame: RequestFrame
+	readonly #issuer: object
+
+	constructor(
+		token: typeof MINT,
+		issuer: object,
+		frame: RequestFrame,
+		dimension: D,
+		action: A,
+		principal: string,
+		values: readonly string[] | 'all',
+		containers: readonly ContainerGrant[],
+	) {
+		if (token !== MINT) {
+			throw new CapabilityRefusedError('not_minted', 'a Within is minted by the framework only; declare the access form in fabrika.contract.ts')
+		}
+		const held = values === 'all' ? freeze([]) : containerGrantsOf(containers)
+		let count = values === 'all' ? 0 : values.length
+		for (let index = 0; index < held.length; index++) {
+			count += held[index]?.values.length ?? 0
+		}
+		if (count > MAX_WITHIN_VALUES) {
+			throw new CapabilityLimitError(
+				`the caller holds '${action}' in ${count} scope values for a ${dimension} list; a Within carries at most ${MAX_WITHIN_VALUES}`,
+			)
+		}
+		this.#dimension = dimension
+		this.#action = action
+		this.#grant = freeze({
+			kind: 'within',
+			dimension,
+			action,
+			principal,
+			values: values === 'all' ? 'all' : copyOf(values),
+			containers: held,
+		})
+		this.#frame = frame
+		this.#issuer = issuer
+	}
+
+	get dimension(): D {
+		return this.#dimension
+	}
+
+	get action(): A {
+		return this.#action
+	}
+
+	/** The values of this dimension itself. */
+	get values(): readonly string[] | 'all' {
+		return this.#grant.values
+	}
+
+	/** The containers in which the caller also holds the action: `organization → [o1]` for a workspace list. */
+	get containers(): readonly ContainerGrant[] {
+		return this.#grant.containers
+	}
+
+	static {
+		readWithin = (value) =>
+			typeof value === 'object' && value !== null && #grant in value ? { grant: value.#grant, frame: value.#frame, issuer: value.#issuer } : undefined
+	}
+}
+
+/**
+ * One action held as a global grant, in one request: what an `app` endpoint's `ctx.db.app` is built from. The proxy
+ * admitted the request only for a caller who holds the action without a scope.
+ */
+export class AppCapability<A extends string> implements AppCapabilityType<A> {
+	declare readonly '~capability': { readonly kind: 'app'; readonly action: A }
+	readonly #action: A
+	readonly #grant: AppGrant
+	readonly #frame: RequestFrame
+	readonly #issuer: object
+
+	constructor(token: typeof MINT, issuer: object, frame: RequestFrame, action: A, principal: string) {
+		if (token !== MINT) {
+			throw new CapabilityRefusedError('not_minted', 'an app capability is minted by the framework only; declare access: { action, app: true }')
+		}
+		this.#action = action
+		this.#grant = freeze({ kind: 'app', action, principal })
+		this.#frame = frame
+		this.#issuer = issuer
+	}
+
+	get action(): A {
+		return this.#action
+	}
+
+	static {
+		readApp = (value) =>
+			typeof value === 'object' && value !== null && #grant in value ? { grant: value.#grant, frame: value.#frame, issuer: value.#issuer } : undefined
+	}
+}
+
+// Application code could otherwise redefine a getter that the framework or a handler reads.
+freeze(Ref.prototype)
+freeze(Within.prototype)
+freeze(AppCapability.prototype)
+
+/** Makes the capabilities one authority accepts; a runtime's is held by the `boot` call that made it alone. */
+export interface CapabilityMint {
+	ref<D extends string, A extends string>(
+		frame: RequestFrame,
+		dimension: D,
+		action: A,
+		principal: string,
+		id: string,
+		chain: ReadonlyMap<string, string>,
+	): Ref<D, A>
+	within<D extends string, A extends string>(
+		frame: RequestFrame,
+		dimension: D,
+		action: A,
+		principal: string,
+		values: readonly string[] | 'all',
+		containers?: readonly ContainerGrant[],
+	): Within<D, A>
+	app<A extends string>(frame: RequestFrame, action: A, principal: string): AppCapability<A>
+}
+
+/** A mint and the one authority that accepts what it mints. */
+export interface CapabilityIssuer {
+	readonly mint: CapabilityMint
+	readonly authority: CapabilityAuthority
+}
+
+/**
+ * A new issuer: its authority refuses every capability another issuer minted. Every `boot` makes one and binds its
+ * data layer and its deps to the authority; a test that needs a capability no access check gave makes another, whose
+ * capabilities reach only stores bound to that issuer's authority.
+ */
+export function createCapabilityIssuer(): CapabilityIssuer {
+	const issuer = freeze({})
+	const mint: CapabilityMint = freeze({
+		ref<D extends string, A extends string>(
+			frame: RequestFrame,
+			dimension: D,
+			action: A,
+			principal: string,
+			id: string,
+			chain: ReadonlyMap<string, string>,
+		): Ref<D, A> {
+			return new Ref(MINT, issuer, frame, dimension, action, principal, id, chain)
+		},
+		within<D extends string, A extends string>(
+			frame: RequestFrame,
+			dimension: D,
+			action: A,
+			principal: string,
+			values: readonly string[] | 'all',
+			containers: readonly ContainerGrant[] = [],
+		): Within<D, A> {
+			return new Within(MINT, issuer, frame, dimension, action, principal, values, containers)
+		},
+		app<A extends string>(frame: RequestFrame, action: A, principal: string): AppCapability<A> {
+			return new AppCapability(MINT, issuer, frame, action, principal)
+		},
+	})
+	const authority: CapabilityAuthority = freeze({
+		resolve(capability: unknown): CapabilityGrant {
+			const bound = readRef(capability) ?? readWithin(capability) ?? readApp(capability)
+			if (bound === undefined || bound.issuer !== issuer) {
+				throw new CapabilityRefusedError('not_minted', 'not a capability the framework minted: pass the ctx.target or ctx.within of this request')
+			}
+			const { grant, frame } = bound
+			const what = `${describeGrant(grant)} for '${grant.action}'`
+			if (frame.ended) {
+				throw new CapabilityRefusedError(
+					'ended',
+					`the capability (${what}) belongs to request ${frame.id}, which has ended; never keep a capability past its request`,
+				)
+			}
+			if (currentRequest.getStore() !== frame) {
+				throw new CapabilityRefusedError(
+					'foreign_work',
+					`the capability (${what}) belongs to request ${frame.id}, not to the one running now; never share a capability`,
+				)
+			}
+			return grant
+		},
+
+		fence(): LeaseFence | null {
+			return currentRequest.getStore()?.fence ?? null
+		},
+	})
+	return freeze({ mint, authority })
+}

package/src/implement/challenge.ts

@@ -0,0 +1,115 @@
+// A form's challenge, verified on the server before its row is written. The provider list is closed: Turnstile's
+// siteverify is the only endpoint the framework asks, with the secret from the application variable the contract
+// names. A token verifies only for this host and this form's action, while it is fresh; the dispatcher then records
+// it, so its second use is a replay whatever the provider says.
+
+import type { ChallengeProvider } from '@fabrika/auth-core'
+import { z } from 'zod/v4'
+import { readBoundedBytes } from './bounded'
+
+export const TURNSTILE_VERIFY_URL = 'https://challenges.cloudflare.com/turnstile/v0/siteverify'
+
+export const CHALLENGE_LIMITS = {
+	/** The provider's answer, the body read included. */
+	timeoutMs: 5000,
+	maxAnswerBytes: 16 * 1024,
+	/** Turnstile's tokens are at most 2048 characters. */
+	maxTokenLength: 2048,
+	/** A token is valid for 300 s after the widget issued it; a recorded one is kept as long, plus the skew. */
+	maxAgeMs: 300_000,
+	maxSkewMs: 60_000,
+} as const
+
+export type ChallengeFetch = (request: Request) => Promise<Response>
+
+/** `failed` is the visitor's (400); `unavailable` and `misconfigured` are the platform's or the operator's (503). */
+export type ChallengeOutcome = 'passed' | 'failed' | 'unavailable' | 'misconfigured'
+
+export interface ChallengeCheck {
+	readonly token: string
+	/** The host the form was submitted to: the page the widget ran on must be on it. */
+	readonly hostname: string
+	/** The form's name, which its widget renders as `action`. */
+	readonly action: string
+}
+
+export interface ChallengeVerifier {
+	readonly provider: ChallengeProvider
+	verify(check: ChallengeCheck): Promise<ChallengeOutcome>
+}
+
+/** A token as the widget issues it: printable ASCII without spaces, within the provider's length. */
+const TOKEN = new RegExp(`^[\\x21-\\x7e]{1,${CHALLENGE_LIMITS.maxTokenLength}}$`)
+
+// Not strict: siteverify adds fields (`cdata`, `metadata`) the decision does not read.
+const siteverifyAnswer = z.object({
+	success: z.boolean(),
+	'error-codes': z.array(z.string()).optional(),
+	challenge_ts: z.string().optional(),
+	hostname: z.string().optional(),
+	action: z.string().optional(),
+})
+
+/** Error codes that say the secret, not the visitor's token, is wrong. */
+const SECRET_ERRORS = ['missing-input-secret', 'invalid-input-secret']
+
+/** Turnstile's siteverify under one deadline and a byte budget; `now` is the clock a token's age is read with. */
+export function turnstileVerifier(secret: string, fetch: ChallengeFetch, now: () => number = Date.now): ChallengeVerifier {
+	const verifier: ChallengeVerifier = {
+		provider: 'turnstile',
+		async verify(check: ChallengeCheck): Promise<ChallengeOutcome> {
+			if (!TOKEN.test(check.token)) {
+				return 'failed'
+			}
+			const deadline = new AbortController()
+			const timer = setTimeout(() => deadline.abort(), CHALLENGE_LIMITS.timeoutMs)
+			let raw: Uint8Array<ArrayBuffer> | null
+			try {
+				const response = await fetch(
+					new Request(TURNSTILE_VERIFY_URL, {
+						method: 'POST',
+						headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+						body: new URLSearchParams({ secret, response: check.token }),
+						redirect: 'manual',
+						signal: deadline.signal,
+					}),
+				)
+				const type = response.headers.get('Content-Type')?.split(';')[0]?.trim().toLowerCase()
+				if (response.status !== 200 || type !== 'application/json') {
+					await response.body?.cancel()
+					return 'unavailable'
+				}
+				raw = await readBoundedBytes(response.body, { maxBytes: CHALLENGE_LIMITS.maxAnswerBytes, signal: deadline.signal })
+			} catch {
+				return 'unavailable'
+			} finally {
+				clearTimeout(timer)
+			}
+			const answer = raw === null ? null : parseAnswer(raw)
+			if (answer === null) {
+				return 'unavailable'
+			}
+			if (!answer.success) {
+				const codes = answer['error-codes'] ?? []
+				if (codes.some((code) => SECRET_ERRORS.includes(code))) {
+					return 'misconfigured'
+				}
+				return codes.includes('internal-error') ? 'unavailable' : 'failed'
+			}
+			const issued = Date.parse(answer.challenge_ts ?? '')
+			const age = now() - issued
+			const fresh = Number.isFinite(issued) && age <= CHALLENGE_LIMITS.maxAgeMs && age >= -CHALLENGE_LIMITS.maxSkewMs
+			return fresh && answer.hostname === check.hostname && answer.action === check.action ? 'passed' : 'failed'
+		},
+	}
+	return Object.freeze(verifier)
+}
+
+function parseAnswer(raw: Uint8Array<ArrayBuffer>): z.infer<typeof siteverifyAnswer> | null {
+	try {
+		const parsed = siteverifyAnswer.safeParse(JSON.parse(new TextDecoder().decode(raw)))
+		return parsed.success ? parsed.data : null
+	} catch {
+		return null
+	}
+}