@fabrika/app 0.6.0 → 0.8.0

package/src/implement/capability.ts

@@ -15,6 +15,8 @@ import {
 	MAX_WITHIN_VALUES,
 	type Ref as RefCapability,
 	type RefGrant,
+	type RowGrant,
+	type RowRef as RowRefCapability,
 	type Within as WithinCapability,
 	type WithinGrant,
 } from '@fabrika/db/capability'
@@ -28,8 +30,13 @@ export const CAPABILITY_REFUSALS = {
 	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',
+	undeclared_kick: 'the site kicked a job it does not declare in kicks',
+	undeclared_binding: 'the site named a webhook it does not declare in binds',
+	undeclared_signs: 'the site signed a token of a purpose it does not declare in signs, or for longer than the purpose allows',
+	undeclared_egress: 'the site called an origin it does not declare in egress',
+	wrong_binding: 'a webhook binding was handed a capability of another kind or dimension than the webhook is bound to',
 	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',
+	wrong_capability: 'an operation was handed a capability of another dimension or action than it needs',
 } as const
 
 export type CapabilityRefusal = keyof typeof CAPABILITY_REFUSALS
@@ -173,6 +180,7 @@ interface Bound {
 let readRef: (value: unknown) => Bound | undefined = () => undefined
 let readWithin: (value: unknown) => Bound | undefined = () => undefined
 let readApp: (value: unknown) => Bound | undefined = () => undefined
+let readRow: (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> {
@@ -344,10 +352,70 @@ export class AppCapability<A extends string> implements AppCapabilityType<A> {
 	}
 }
 
+interface RowFacts {
+	readonly table: string
+	readonly action: string
+	readonly principal: string
+	readonly id: string
+	readonly chain: Chain
+}
+
+/**
+ * One row a claim leased, for one action, in one job attempt: `row.ref`, which `tx.db.on(row.ref)` finishes the row
+ * through. `chain` holds the row's containment columns as it was claimed.
+ */
+export class RowRef<T extends string, A extends string> implements RowRefCapability<T, A> {
+	declare readonly '~capability': { readonly kind: 'row'; readonly table: T; readonly action: A }
+	readonly #facts: RowFacts
+	readonly #frame: RequestFrame
+	readonly #issuer: object
+
+	constructor(token: typeof MINT, issuer: object, frame: RequestFrame, grant: Omit<RowGrant, 'kind'>) {
+		if (token !== MINT) {
+			throw new CapabilityRefusedError('not_minted', 'a row capability is minted by the framework only: claim the row')
+		}
+		this.#facts = freeze({ table: grant.table, action: grant.action, principal: grant.principal, id: grant.id, chain: chainOf(grant.chain) })
+		this.#frame = frame
+		this.#issuer = issuer
+	}
+
+	get table(): string {
+		return this.#facts.table
+	}
+
+	get action(): string {
+		return this.#facts.action
+	}
+
+	/** The row's key. */
+	get value(): string {
+		return this.#facts.id
+	}
+
+	static {
+		readRow = (value) => {
+			if (typeof value !== 'object' || value === null || !(#facts in value)) {
+				return undefined
+			}
+			const facts = value.#facts
+			const grant: RowGrant = freeze({
+				kind: 'row',
+				table: facts.table,
+				action: facts.action,
+				principal: facts.principal,
+				id: facts.id,
+				chain: mapOf(facts.chain),
+			})
+			return { grant, frame: value.#frame, issuer: value.#issuer }
+		}
+	}
+}
+
 // Application code could otherwise redefine a getter that the framework or a handler reads.
 freeze(Ref.prototype)
 freeze(Within.prototype)
 freeze(AppCapability.prototype)
+freeze(RowRef.prototype)
 
 /** Makes the capabilities one authority accepts; a runtime's is held by the `boot` call that made it alone. */
 export interface CapabilityMint {
@@ -410,7 +478,7 @@ export function createCapabilityIssuer(): CapabilityIssuer {
 	})
 	const authority: CapabilityAuthority = freeze({
 		resolve(capability: unknown): CapabilityGrant {
-			const bound = readRef(capability) ?? readWithin(capability) ?? readApp(capability)
+			const bound = readRef(capability) ?? readWithin(capability) ?? readApp(capability) ?? readRow(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')
 			}
@@ -431,6 +499,14 @@ export function createCapabilityIssuer(): CapabilityIssuer {
 			return grant
 		},
 
+		row(grant: Omit<RowGrant, 'kind'>): RowRef<string, string> {
+			const frame = currentRequest.getStore()
+			if (frame === undefined || frame.ended) {
+				throw new CapabilityRefusedError('ended', 'a claimed row is minted only inside the job attempt that claims it')
+			}
+			return new RowRef(MINT, issuer, frame, grant)
+		},
+
 		fence(): LeaseFence | null {
 			return currentRequest.getStore()?.fence ?? null
 		},

package/src/implement/challenge.ts

@@ -1,10 +1,15 @@
 // 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
+// names; an ALTCHA challenge the application issues and verifies itself, with the HMAC key that variable holds, and asks
+// no one. 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 type { AltchaChallenge, ChallengeProvider } from '@fabrika/auth-core'
+import { createChallenge, randomInt, verifySolution } from 'altcha-lib'
+import { deriveKey } from 'altcha-lib/algorithms/web/pbkdf2'
+import { createHmac } from 'node:crypto'
 import { z } from 'zod/v4'
+import { ALTCHA_LIMITS } from '../contract/defaults'
 import { readBoundedBytes } from './bounded'
 
 export const TURNSTILE_VERIFY_URL = 'https://challenges.cloudflare.com/turnstile/v0/siteverify'
@@ -37,11 +42,23 @@ export interface ChallengeCheck {
 	readonly action: string
 }
 
+/**
+ * A verification's answer. A passed one names what the dispatcher records it by: the token itself, or, for ALTCHA, the
+ * signature of the challenge it solved, since one solution can be encoded as many tokens. Its record lasts at least
+ * as long as this token could pass again, even if the issuer's configured lifetime has since changed.
+ */
+export type ChallengeVerdict =
+	| { readonly outcome: 'passed'; readonly replayKey: string; readonly recordMs: number }
+	| { readonly outcome: Exclude<ChallengeOutcome, 'passed'> }
+
 export interface ChallengeVerifier {
 	readonly provider: ChallengeProvider
-	verify(check: ChallengeCheck): Promise<ChallengeOutcome>
+	verify(check: ChallengeCheck): Promise<ChallengeVerdict>
 }
 
+const verdictOf = (outcome: ChallengeOutcome, replayKey: string, recordMs: number): ChallengeVerdict =>
+	outcome === 'passed' ? { outcome, replayKey, recordMs } : { outcome }
+
 /** 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}}$`)
 
@@ -61,55 +78,60 @@ const SECRET_ERRORS = ['missing-input-secret', 'invalid-input-secret']
 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,
-					}),
-					check,
-				)
-				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'
+		async verify(check: ChallengeCheck): Promise<ChallengeVerdict> {
+			return verdictOf(await siteverify(secret, fetch, now, check), check.token, CHALLENGE_LIMITS.maxAgeMs + CHALLENGE_LIMITS.maxSkewMs)
 		},
 	}
 	return Object.freeze(verifier)
 }
 
+/** Turnstile's answer for `check`, under one deadline and a byte budget. */
+async function siteverify(secret: string, fetch: ChallengeFetch, now: () => number, 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,
+			}),
+			check,
+		)
+		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'
+}
+
 function parseAnswer(raw: Uint8Array<ArrayBuffer>): z.infer<typeof siteverifyAnswer> | null {
 	try {
 		const parsed = siteverifyAnswer.safeParse(JSON.parse(new TextDecoder().decode(raw)))
@@ -118,3 +140,137 @@ function parseAnswer(raw: Uint8Array<ArrayBuffer>): z.infer<typeof siteverifyAns
 		return null
 	}
 }
+
+/**
+ * How hard an ALTCHA challenge is to solve: PBKDF2 attempts of `cost` iterations, up to a count drawn between
+ * `minCounter` and `maxCounter`. The contract's by default; a test kit and `fabrika app dev` make it cheap.
+ */
+export interface ChallengeWork {
+	readonly cost: number
+	readonly minCounter: number
+	readonly maxCounter: number
+}
+
+/** The cheapest work: the test kit's and `fabrika app dev`'s, so a test solves a challenge in milliseconds. */
+export const MINIMAL_CHALLENGE_WORK: ChallengeWork = Object.freeze({ cost: 1, minCounter: 1, maxCounter: 10 })
+
+/** What the issuing endpoint answers: the signed parameters, which the widget solves and sends back with its solution. */
+export interface IssuedChallenge {
+	readonly parameters: Readonly<Record<string, unknown>>
+	readonly signature?: string
+}
+
+export interface ChallengeIssuer {
+	/** A fresh challenge for this host and the procedure's action. */
+	issue(hostname: string): Promise<IssuedChallenge>
+}
+
+const HEX = /^[0-9a-f]+$/
+const hex = (length: number) => z.string().length(length).regex(HEX)
+
+// Strict: exactly what `issue` signs, so a payload of another shape (the widget's `test` mode, a server-signed one) never
+// reaches the verification.
+const altchaPayload = z.strictObject({
+	challenge: z.strictObject({
+		parameters: z.strictObject({
+			algorithm: z.literal(ALTCHA_LIMITS.algorithm),
+			nonce: hex(32),
+			salt: hex(32),
+			cost: z.int().positive(),
+			keyLength: z.literal(32),
+			keyPrefix: hex(32),
+			keySignature: hex(64),
+			expiresAt: z.int().positive(),
+			data: z.strictObject({ action: z.string(), host: z.string() }),
+		}),
+		signature: hex(64),
+	}),
+	solution: z.strictObject({ counter: z.int().nonnegative(), derivedKey: hex(64), time: z.number().nonnegative().optional() }),
+})
+
+type AltchaPayload = z.infer<typeof altchaPayload>
+
+/** A payload as the widget sends it: base64 of its JSON, within the bound. */
+const PAYLOAD = new RegExp(`^[A-Za-z0-9+/]{1,${ALTCHA_LIMITS.maxTokenLength}}={0,2}$`)
+
+/**
+ * The two HMAC keys of an ALTCHA challenge, each derived from the application's key for one use: one signs the
+ * parameters, the other the solution the server knows, so neither signature can stand in for the other.
+ */
+function altchaKeys(secret: string): { readonly signature: string; readonly key: string } {
+	const derive = (use: string) => createHmac('sha256', secret).update(`fabrika-altcha-${use}`).digest('hex')
+	return { signature: derive('challenge'), key: derive('solution') }
+}
+
+function parsePayload(token: string): AltchaPayload | null {
+	if (token.length > ALTCHA_LIMITS.maxTokenLength || !PAYLOAD.test(token)) {
+		return null
+	}
+	try {
+		const parsed = altchaPayload.safeParse(JSON.parse(atob(token)))
+		return parsed.success ? parsed.data : null
+	} catch {
+		return null
+	}
+}
+
+/**
+ * The issuer and the verifier of one public procedure's ALTCHA challenge, with the HMAC key its application variable
+ * holds. A challenge carries the action and the host it was issued for and expires `maxAgeMs` after it was issued; the
+ * server picks the attempt that solves it and signs that attempt's key, so verifying is two HMACs and no proof of work.
+ * Nothing leaves the process. `now` is the clock a challenge's expiry is set with; altcha-lib reads it on the real clock,
+ * and so does the verifier, so the two never disagree.
+ */
+export function altchaChallenge(
+	secret: string,
+	rules: Pick<AltchaChallenge, 'action' | 'cost' | 'maxAgeMs'>,
+	work: ChallengeWork | null = null,
+	now: () => number = Date.now,
+): { readonly issuer: ChallengeIssuer; readonly verifier: ChallengeVerifier } {
+	const keys = altchaKeys(secret)
+	const effort = work ?? { cost: rules.cost, minCounter: ALTCHA_LIMITS.minCounter, maxCounter: ALTCHA_LIMITS.maxCounter }
+	const issuer: ChallengeIssuer = {
+		async issue(hostname: string): Promise<IssuedChallenge> {
+			const challenge = await createChallenge({
+				algorithm: ALTCHA_LIMITS.algorithm,
+				cost: effort.cost,
+				counter: randomInt(effort.maxCounter, effort.minCounter),
+				expiresAt: Math.floor((now() + rules.maxAgeMs) / 1000),
+				data: { action: rules.action, host: hostname },
+				deriveKey,
+				hmacSignatureSecret: keys.signature,
+				hmacKeySignatureSecret: keys.key,
+			})
+			return { parameters: { ...challenge.parameters }, ...(challenge.signature === undefined ? {} : { signature: challenge.signature }) }
+		},
+	}
+	const verifier: ChallengeVerifier = {
+		provider: 'altcha',
+		async verify(check: ChallengeCheck): Promise<ChallengeVerdict> {
+			const payload = parsePayload(check.token)
+			if (payload === null) {
+				return { outcome: 'failed' }
+			}
+			const { parameters } = payload.challenge
+			// The signature covers these; they are read before it only to answer without the HMAC.
+			if (parameters.data.action !== check.action || parameters.data.host !== check.hostname || parameters.expiresAt * 1000 < Date.now()) {
+				return { outcome: 'failed' }
+			}
+			try {
+				const result = await verifySolution({
+					challenge: payload.challenge,
+					solution: payload.solution,
+					deriveKey,
+					hmacSignatureSecret: keys.signature,
+					hmacKeySignatureSecret: keys.key,
+				})
+				// A previous deployment may have issued longer-lived challenges with this same key.
+				const recordMs = Math.max(0, parameters.expiresAt * 1000 - Date.now()) + CHALLENGE_LIMITS.maxSkewMs
+				return verdictOf(result.verified ? 'passed' : 'failed', payload.challenge.signature, recordMs)
+			} catch {
+				return { outcome: 'failed' }
+			}
+		},
+	}
+	return Object.freeze({ issuer: Object.freeze(issuer), verifier: Object.freeze(verifier) })
+}

package/src/implement/{form-admission.ts → client-address.ts}

@@ -1,13 +1,9 @@
-// A form's admission: which bucket a request takes from, and what a submission carries beside its row. The buckets
-// live in the application's database (`@fabrika/db`'s `FormAdmissions`), so every instance shares them. Admission is
-// not authorization: a form is anonymous, and this only bounds how much one client and all clients together submit.
+// The client a per-client bucket counts. The buckets live in the application's database (`@fabrika/db`'s
+// `Admissions`), so every instance shares them. Admission is not authorization: it only bounds how much one client
+// calls a public procedure.
 
 import { CLIENT_ADDRESS_HEADER } from '@fabrika/auth-core'
 import { createHash } from 'node:crypto'
-import { FORM_CHALLENGE_FIELD } from '../contract/defaults'
-
-/** The bucket of a form's accepted submissions; a client's bucket is `client:<digest>`, so the two never meet. */
-export const ACCEPTED_BUCKET = 'accepted'
 
 /** Longest header value read; an IPv6 address with a zone id fits with room to spare. */
 const MAX_ADDRESS_LENGTH = 64
@@ -87,34 +83,3 @@ export function clientKey(header: string | null): string {
 export function clientBucket(request: Request): string {
 	return `client:${createHash('sha256').update(clientKey(request.headers.get(CLIENT_ADDRESS_HEADER))).digest('hex')}`
 }
-
-/** What the form declared beside its row: its honeypot field and whether a challenge token travels in the input. */
-export interface SubmissionFields {
-	readonly honeypot: string | null
-	readonly challenge: boolean
-}
-
-export interface Submission {
-	/** The honeypot was filled: the answer is the constant one, and nothing is written. */
-	readonly trapped: boolean
-	/** The challenge token, when the form declares a challenge. */
-	readonly token: string | null
-	/** The columns the inbox row gets: the input without the honeypot and the token. */
-	readonly row: Readonly<Record<string, unknown>>
-}
-
-export function submissionOf(input: Readonly<Record<string, unknown>>, fields: SubmissionFields): Submission {
-	const row: Record<string, unknown> = {}
-	for (const [name, value] of Object.entries(input)) {
-		if (name !== fields.honeypot && !(fields.challenge && name === FORM_CHALLENGE_FIELD)) {
-			row[name] = value
-		}
-	}
-	const trap = fields.honeypot === null ? undefined : input[fields.honeypot]
-	const token = fields.challenge ? input[FORM_CHALLENGE_FIELD] : undefined
-	return {
-		trapped: typeof trap === 'string' && trap !== '',
-		token: typeof token === 'string' ? token : null,
-		row,
-	}
-}