@fabrika/app 0.6.0 → 0.7.0

package/src/implement/public.ts

@@ -0,0 +1,142 @@
+// What a procedure admits before its handler runs, decided once at boot from the approved artifact: its buckets, a
+// public procedure's challenge, and its time limit. The buckets live in the application's database
+// (`@fabrika/db`'s `Admissions`, keyed by the endpoint id), so every instance shares them. Admission is not authorization: it bounds how much one client, one caller and everyone together send.
+
+import { type AdmissionRate, CLIENT_ADDRESS_HEADER, type ContractArtifact, type ProcedureArtifact } from '@fabrika/auth-core'
+import { createHash } from 'node:crypto'
+import { REQUEST_BUDGET_MS } from './bounded'
+import { type ChallengeFetch, type ChallengeVerifier, turnstileVerifier } from './challenge'
+import { clientBucket, clientKey } from './client-address'
+import type { RequestClient } from './types'
+
+/** The bucket every call of an endpoint takes from; a client's is `client:<digest>`, a caller's `caller:<digest>`. */
+export const ENDPOINT_BUCKET = 'endpoint'
+
+/** The longest `User-Agent` a handler reads: enough to tell browsers apart, too short to carry a payload. */
+export const MAX_USER_AGENT_LENGTH = 256
+
+/** A procedure's admission and time limit, from the approved artifact. */
+export interface ProcedureAdmission {
+	readonly rate: AdmissionRate
+	/** The challenge's verifier, with the secret its application variable holds; `null` without a challenge. */
+	readonly challenge: AdmittedChallenge | null
+	/** The one token the challenge does not record, so it passes again: `fabrika app dev`'s test widget's. */
+	readonly repeatableToken: string | null
+	/** How long the handler may run after the last body byte. */
+	readonly timeoutMs: number
+}
+
+/** A challenge's verifier and the widget action the verification expects back. */
+export interface AdmittedChallenge {
+	readonly verifier: ChallengeVerifier
+	readonly action: string
+}
+
+/** A procedure the artifact holds no rules for (a `defineContract` one): no bucket, the request budget. */
+export const DEFAULT_ADMISSION: ProcedureAdmission = Object.freeze({
+	rate: Object.freeze({ perClient: null, perCaller: null, perEndpoint: null, bytesPerHour: null }),
+	challenge: null,
+	repeatableToken: null,
+	timeoutMs: REQUEST_BUDGET_MS,
+})
+
+export interface AdmissionOptions {
+	readonly application: Readonly<Record<string, unknown>>
+	readonly challengeFetch?: ChallengeFetch
+	readonly repeatableChallengeToken?: string
+}
+
+/**
+ * The admission of endpoint `id`, or `null` after a problem: a challenge whose secret's application variable is not set
+ * keeps the application from booting, as a form's does.
+ */
+export function procedureAdmission(id: string, artifact: ContractArtifact, options: AdmissionOptions, problems: string[]): ProcedureAdmission | null {
+	const rules: ProcedureArtifact | undefined = artifact.procedures !== undefined && Object.hasOwn(artifact.procedures, id)
+		? artifact.procedures[id]
+		: undefined
+	if (rules === undefined) {
+		return DEFAULT_ADMISSION
+	}
+	let challenge: AdmittedChallenge | null = null
+	if (rules.challenge !== null) {
+		const secret = options.application[rules.challenge.secret]
+		if (typeof secret !== 'string' || secret.trim() === '') {
+			problems.push(
+				`procedure '${id}' verifies its ${rules.challenge.provider} challenge with the application variable ${rules.challenge.secret}, which is not set`,
+			)
+			return null
+		}
+		challenge = {
+			verifier: turnstileVerifier(secret.trim(), options.challengeFetch ?? ((request) => fetch(request))),
+			action: rules.challenge.action,
+		}
+	}
+	return Object.freeze({
+		rate: rules.rate,
+		challenge,
+		repeatableToken: challenge === null ? null : (options.repeatableChallengeToken ?? null),
+		timeoutMs: rules.timeoutMs,
+	})
+}
+
+/** The buckets a request takes from, in order: its client's or its caller's first, then the endpoint's. */
+export function bucketsOf(rate: AdmissionRate, request: Request, caller: string | null): { readonly bucket: string; readonly limit: number }[] {
+	const buckets: { readonly bucket: string; readonly limit: number }[] = []
+	if (rate.perClient !== null) {
+		buckets.push({ bucket: clientBucket(request), limit: rate.perClient })
+	}
+	if (rate.perCaller !== null && caller !== null) {
+		buckets.push({ bucket: `caller:${createHash('sha256').update(caller).digest('hex')}`, limit: rate.perCaller })
+	}
+	if (rate.perEndpoint !== null) {
+		buckets.push({ bucket: ENDPOINT_BUCKET, limit: rate.perEndpoint })
+	}
+	return buckets
+}
+
+/**
+ * Who sent the request, as the proxy saw it. The address is `X-Fabrika-Client-Ip`, which only the proxy sets, and only
+ * where the runtime adapter vouches that the proxy saw the visitor (`vouched`); behind a balancer whose range the
+ * platform does not trust it is `null`. Anything that is no IP address is `null` too.
+ */
+export function requestClient(request: Request, vouched: boolean): RequestClient {
+	const address = vouched ? request.headers.get(CLIENT_ADDRESS_HEADER)?.trim() ?? '' : ''
+	const agent = request.headers.get('User-Agent')
+	return Object.freeze({
+		ip: address === '' || clientKey(address) === 'unknown' ? null : address,
+		userAgent: agent === null || agent === '' ? null : agent.slice(0, MAX_USER_AGENT_LENGTH),
+	})
+}
+
+/**
+ * At most `limit` requests at once, beyond which the next is refused: the share of the connection pool all public
+ * procedures of an instance hold together, so a flood of anonymous calls leaves signed-in staff the rest.
+ */
+export class InFlightShare {
+	readonly #limit: number
+	#held = 0
+
+	constructor(limit: number) {
+		this.#limit = limit
+	}
+
+	/** A release to call once the request is answered, or `null` when the share is full. */
+	enter(): (() => void) | null {
+		if (this.#held >= this.#limit) {
+			return null
+		}
+		this.#held++
+		let released = false
+		return () => {
+			if (!released) {
+				released = true
+				this.#held--
+			}
+		}
+	}
+}
+
+/** A quarter of the pool, at least one connection. */
+export function publicShareOf(connections: number): number {
+	return Math.max(1, Math.floor(connections / 4))
+}

package/src/implement/tokens.ts

@@ -0,0 +1,219 @@
+// Signed tokens at runtime: the keys `FABRIKA_TOKEN_KEYS` hands the environment, `ctx.tokens.sign` of a site that
+// declares `signs`, and the verification of each token field of a procedure's input and `http.query` as they are parsed.
+// A token is `<key id>.<payload>.<signature>`: the payload is the purpose, the expiry and the claims as base64url JSON,
+// and the signature an HMAC-SHA256 over the key id and the payload, so a token of one purpose never passes as another.
+
+import { type ContractArtifact, FABRIKA_TOKEN_KEYS, type SchemaShape } from '@fabrika/auth-core'
+import { createHmac, timingSafeEqual } from 'node:crypto'
+import { z } from 'zod/v4'
+import type { Schema } from '../contract/define'
+import { BadRequestError } from '../errors'
+import { CapabilityRefusedError } from './capability'
+import { ServerFault } from './faults'
+
+const DAY_SECONDS = 86_400
+const KEY_ID = /^[A-Za-z0-9_-]{8,64}$/
+const BASE64URL = /^[A-Za-z0-9_-]+$/
+/** A key below this many bytes is refused at boot: an HMAC key shorter than its hash is guessable sooner. */
+const MIN_SECRET_BYTES = 32
+
+/** One key of the environment: its id, which each token it signs carries, and its secret. */
+export interface TokenKey {
+	readonly id: string
+	readonly secret: Uint8Array
+}
+
+/** A purpose as the runtime holds it: the claims schema the application declared, and the longest lifetime. */
+export interface RuntimePurpose {
+	readonly claims: Schema
+	readonly maxDays: number
+}
+
+/**
+ * The keys of `FABRIKA_TOKEN_KEYS`: `<kid>:<secret>` entries joined by `,`, the signing key first. Required when the
+ * contract declares a token purpose; refused at boot when malformed. `null` without purposes or after a problem.
+ */
+export function readTokenKeys(
+	framework: Readonly<Record<string, string>>,
+	artifact: ContractArtifact,
+	problems: string[],
+): readonly TokenKey[] | null {
+	const value = framework[FABRIKA_TOKEN_KEYS]?.trim() ?? ''
+	if (artifact.tokens === undefined || Object.keys(artifact.tokens).length === 0) {
+		return null
+	}
+	if (value === '') {
+		problems.push(`${FABRIKA_TOKEN_KEYS} is not set; the contract declares token purposes, and the deploy writes their keys`)
+		return null
+	}
+	const keys: TokenKey[] = []
+	for (const entry of value.split(',')) {
+		const separator = entry.indexOf(':')
+		const id = entry.slice(0, separator)
+		const encoded = entry.slice(separator + 1)
+		const secret = separator < 0 || !BASE64URL.test(encoded) ? null : new Uint8Array(Buffer.from(encoded, 'base64url'))
+		if (!KEY_ID.test(id) || secret === null || secret.byteLength < MIN_SECRET_BYTES || keys.some((key) => key.id === id)) {
+			problems.push(`${FABRIKA_TOKEN_KEYS} is not a list of <key id>:<secret> entries, each id once and each secret at least ${MIN_SECRET_BYTES} bytes`)
+			return null
+		}
+		keys.push({ id, secret })
+	}
+	return keys
+}
+
+/** The claims a verified token carried, and every text in them: a redirect target or a row id the request may use. */
+export interface VerifiedTokens {
+	readonly carried: ReadonlySet<string>
+}
+
+export const NO_VERIFIED_TOKENS: VerifiedTokens = Object.freeze({ carried: new Set<string>() })
+
+/**
+ * The environment's signed tokens. `purposes` are the application's declared claims schemas, by purpose; `keys` are
+ * `null` when the contract declares none, so a sign or a verification refuses.
+ */
+export class SignedTokens {
+	readonly #purposes: ReadonlyMap<string, RuntimePurpose>
+	readonly #keys: readonly TokenKey[]
+	readonly #now: () => number
+
+	constructor(purposes: ReadonlyMap<string, RuntimePurpose>, keys: readonly TokenKey[] | null, now: () => number = Date.now) {
+		this.#purposes = purposes
+		this.#keys = keys ?? []
+		this.#now = now
+	}
+
+	/**
+	 * `ctx.tokens` of a site: signs a token of a purpose `signs` names, valid for `days` (at most the purpose's
+	 * `maxDays`). The claims are parsed by the purpose's schema first, so a token never carries what a verifier refuses.
+	 */
+	context(site: string, signs: readonly string[]): { readonly sign: (purpose: string, claims: unknown, options: unknown) => string } {
+		return Object.freeze({
+			sign: (purpose: string, claims: unknown, options: unknown): string => this.#sign(site, signs, purpose, claims, options),
+		})
+	}
+
+	#sign(site: string, signs: readonly string[], purpose: string, claims: unknown, options: unknown): string {
+		const declared = signs.includes(purpose) ? this.#purposes.get(purpose) : undefined
+		if (declared === undefined) {
+			throw new CapabilityRefusedError('undeclared_signs', `${site} does not declare signs: ['${String(purpose)}']`)
+		}
+		const days: unknown = typeof options === 'object' && options !== null ? Reflect.get(options, 'days') : undefined
+		if (typeof days !== 'number' || !Number.isSafeInteger(days) || days < 1 || days > declared.maxDays) {
+			throw new CapabilityRefusedError(
+				'undeclared_signs',
+				`${site} signed a '${purpose}' token for ${String(days)} days; the purpose allows 1 to ${declared.maxDays}`,
+			)
+		}
+		const parsed = z.safeParse(declared.claims, claims)
+		if (!parsed.success) {
+			throw new ServerFault('token_claims_refused', `${site} signed a '${purpose}' token whose claims its schema refuses`)
+		}
+		const [key] = this.#keys
+		if (key === undefined) {
+			throw new ServerFault('token_keys_missing', `${site} signed a '${purpose}' token, and the environment holds no token key`)
+		}
+		const expiresAt = Math.floor(this.#now() / 1000) + days * DAY_SECONDS
+		const payload = Buffer.from(JSON.stringify({ p: purpose, x: expiresAt, c: parsed.data })).toString('base64url')
+		return `${key.id}.${payload}.${signature(key, payload)}`
+	}
+
+	/**
+	 * The claims of `token` when it is a token of `purpose` this environment signed and it has not expired; a 400
+	 * otherwise, which says only that it is not valid, so a caller learns nothing about the keys.
+	 */
+	verify(purpose: string, token: string): Readonly<Record<string, unknown>> {
+		const [id = '', payload = '', given = '', ...rest] = token.split('.')
+		const key = this.#keys.find((candidate) => candidate.id === id)
+		const declared = this.#purposes.get(purpose)
+		if (rest.length > 0 || key === undefined || declared === undefined || !BASE64URL.test(payload) || !BASE64URL.test(given)) {
+			throw invalid()
+		}
+		const expected = Buffer.from(signature(key, payload), 'base64url')
+		const presented = Buffer.from(given, 'base64url')
+		if (presented.byteLength !== expected.byteLength || !timingSafeEqual(presented, expected)) {
+			throw invalid()
+		}
+		const body = parsePayload(payload)
+		if (body === null || body.p !== purpose) {
+			throw invalid()
+		}
+		if (body.x <= Math.floor(this.#now() / 1000)) {
+			throw new BadRequestError('The signed token has expired')
+		}
+		const claims = z.safeParse(declared.claims, body.c)
+		if (!claims.success || !isRecord(claims.data)) {
+			throw invalid()
+		}
+		return Object.freeze(claims.data)
+	}
+
+	/**
+	 * Each top-level signed token field of `value` (by `shape`, the approved input or query) replaced by its verified
+	 * claims, and every text those claims carry.
+	 */
+	verifyFields(shape: SchemaShape | null, value: Readonly<Record<string, unknown>>, into: Set<string>): Readonly<Record<string, unknown>> {
+		const fields = tokenFields(shape)
+		if (fields.size === 0) {
+			return value
+		}
+		const verified: Record<string, unknown> = { ...value }
+		for (const [field, purpose] of fields) {
+			const text = value[field]
+			if (typeof text === 'string') {
+				const claims = this.verify(purpose, text)
+				collectTexts(claims, into)
+				verified[field] = claims
+			}
+		}
+		return Object.freeze(verified)
+	}
+}
+
+/** The top-level fields of an object shape that carry a signed token, optional or not, with their purposes. */
+export function tokenFields(shape: SchemaShape | null): ReadonlyMap<string, string> {
+	const fields = new Map<string, string>()
+	if (shape?.type !== 'object') {
+		return fields
+	}
+	for (const [name, field] of Object.entries(shape.fields)) {
+		const inner = field.type === 'optional' ? field.inner : field
+		if (inner.type === 'token') {
+			fields.set(name, inner.purpose)
+		}
+	}
+	return fields
+}
+
+function signature(key: TokenKey, payload: string): string {
+	return createHmac('sha256', key.secret).update(`${key.id}.${payload}`).digest('base64url')
+}
+
+function invalid(): BadRequestError {
+	return new BadRequestError('The signed token is not valid')
+}
+
+const payloadSchema = z.strictObject({ p: z.string(), x: z.int(), c: z.unknown() })
+
+function parsePayload(payload: string): z.output<typeof payloadSchema> | null {
+	try {
+		const parsed = z.safeParse(payloadSchema, JSON.parse(Buffer.from(payload, 'base64url').toString('utf8')))
+		return parsed.success ? parsed.data : null
+	} catch {
+		return null
+	}
+}
+
+function collectTexts(value: unknown, into: Set<string>): void {
+	if (typeof value === 'string') {
+		into.add(value)
+	} else if (Array.isArray(value)) {
+		for (const item of value) collectTexts(item, into)
+	} else if (isRecord(value)) {
+		for (const item of Object.values(value)) collectTexts(item, into)
+	}
+}
+
+function isRecord(value: unknown): value is Readonly<Record<string, unknown>> {
+	return typeof value === 'object' && value !== null && !Array.isArray(value)
+}

package/src/implement/types.ts

@@ -10,17 +10,31 @@ import type { AppCapability, Ref, Within } from './capability'
 import type { ConnectResult } from './connect'
 import type { LinkIssuing, MemberDirectory, MemberLookup, MemberManagement } from './membership'
 import type { AppPrincipal, LinkHolder, PrincipalOf, ServicePrincipal } from './principal'
+import type { AppUrl } from './urls'
 import type { WebhookDelivery, WebhookPrincipal } from './webhook'
 
-/** What every handler gets: who called, this request's id, and the signal that ends it. */
+/** What every handler gets: who called, this request's id, the client the proxy saw, and the signal that ends it. */
 export interface RequestContext<P> {
 	readonly principal: P
 	readonly requestId: string
 	/**
-	 * Aborts when the client leaves or the request outlives `REQUEST_BUDGET_MS`; its transaction then rolls back. Pass
-	 * it to every outbound call, so the call stops with the request.
+	 * Aborts when the client leaves or the request outlives its time limit (`limits.timeoutMs`, `REQUEST_BUDGET_MS` by
+	 * default); its transaction then rolls back. Pass it to every outbound call, so the call stops with the request.
 	 */
 	readonly signal: AbortSignal
+	/** The client the proxy saw. Information to record, never a check. */
+	readonly client: RequestClient
+	/** An absolute link to a procedure of this application: `ctx.url('api.mail.unsubscribe', { query: { t } })`. */
+	readonly url: AppUrl
+}
+
+/**
+ * The client of a request: its address as the proxy saw it, `null` where the platform cannot vouch for it (behind a
+ * balancer whose range it does not trust); its `User-Agent`, cut to `MAX_USER_AGENT_LENGTH`, `null` when it sends none.
+ */
+export interface RequestClient {
+	readonly ip: string | null
+	readonly userAgent: string | null
 }
 
 /** The capability an access form hands. `{ member: true }` hands none. */
@@ -30,6 +44,13 @@ export type AccessContext<Acc> = Acc extends MemberAccess ? unknown
 	: Acc extends { readonly action: infer A extends string; readonly on: infer D extends string } ? { readonly target: Ref<D, A> }
 	: Acc extends { readonly action: infer A extends string; readonly creates: infer D extends string } ? { readonly created: Ref<D, A> }
 	: Acc extends { readonly action: infer A extends string; readonly app: true } ? { readonly app: AppCapability<A> }
+	: Acc extends { readonly capabilities: infer C } ? { readonly capabilities: { readonly [N in keyof C]: CapabilityOf<C[N]> } }
+	: never
+
+/** The capability one of several hands: a `Within` for `over`, a `Ref` for `on` and `in`. */
+export type CapabilityOf<F> = F extends { readonly action: infer A extends string; readonly over: infer D extends string } ? Within<D, A>
+	: F extends { readonly action: infer A extends string; readonly in: infer D extends string } ? Ref<D, A>
+	: F extends { readonly action: infer A extends string; readonly on: infer D extends string } ? Ref<D, A>
 	: never
 
 type DimensionsOf<C> = C extends { readonly dimensions: infer Dims } ? Dims : never

package/src/implement/urls.ts

@@ -0,0 +1,78 @@
+// `ctx.url('<endpoint id>', { input?, query? })`: an absolute link to one of the application's own procedures, for a
+// mail, a redirect or an answer. The origin is the environment's canonical one (`FABRIKA_APP_ORIGIN`, which a deploy
+// writes), the path the endpoint's, and the parameters what its HTTP shape reads from the URL: the input of a `GET`,
+// the `query` of a `POST`. Each value is spelled as the procedure reads it back (`params.ts`).
+
+import { type ContractArtifact, type EndpointRow, FABRIKA_APP_ORIGIN } from '@fabrika/auth-core'
+import { ServerFault } from './faults'
+
+/** A value a URL parameter carries; an absent one is left out. */
+export type UrlValue = string | number | boolean | null | undefined
+
+export interface UrlParameters {
+	/** A `GET` procedure's input, each field a parameter. */
+	readonly input?: Readonly<Record<string, UrlValue>>
+	/** A `POST` procedure's `http.query`. */
+	readonly query?: Readonly<Record<string, UrlValue>>
+}
+
+/** `ctx.url`: the absolute URL of a procedure of this contract, with the parameters its HTTP shape reads from the URL. */
+export type AppUrl = (endpoint: string, parameters?: UrlParameters) => string
+
+/** The environment's canonical origin, or `null` where the deploy wrote none; a malformed one is a boot problem. */
+export function readAppOrigin(framework: Readonly<Record<string, string>>, problems: string[]): string | null {
+	const value = framework[FABRIKA_APP_ORIGIN]?.trim() ?? ''
+	if (value === '') {
+		return null
+	}
+	try {
+		const url = new URL(value)
+		if ((url.protocol === 'https:' || url.protocol === 'http:') && url.origin === value) {
+			return value
+		}
+	} catch {
+		// Reported below, as every other malformed value.
+	}
+	problems.push(`${FABRIKA_APP_ORIGIN} '${value}' is not an origin (allowed: https://<host>)`)
+	return null
+}
+
+/** `ctx.url` over the approved artifact's procedure rows. */
+export function appUrl(artifact: ContractArtifact, origin: string | null): AppUrl {
+	const procedures = new Map(artifact.endpoints.filter(isProcedureRow).map((row) => [row.id, row]))
+	return (endpoint, parameters = {}) => {
+		const row = procedures.get(endpoint)
+		if (row === undefined) {
+			throw new ServerFault('url_unbuildable', `ctx.url names '${String(endpoint)}', which is no procedure of the contract`)
+		}
+		if (origin === null) {
+			throw new ServerFault('url_unbuildable', `ctx.url needs ${FABRIKA_APP_ORIGIN}, and the environment has no public origin`)
+		}
+		const reads = row.method === 'GET' ? 'input' : 'query'
+		const other = reads === 'input' ? parameters.query : parameters.input
+		const hasQuery = artifact.procedures?.[endpoint]?.query !== undefined
+		if (other !== undefined || (reads === 'query' && parameters.query !== undefined && !hasQuery)) {
+			throw new ServerFault(
+				'url_unbuildable',
+				`ctx.url('${endpoint}') passes parameters its HTTP shape does not read from the URL (allowed: ${
+					reads === 'input' ? 'input of a GET' : 'query of a POST that declares http.query'
+				})`,
+			)
+		}
+		const search = new URLSearchParams()
+		for (const [name, value] of Object.entries(parameters[reads] ?? {})) {
+			if (value === undefined) continue
+			if (value !== null && typeof value !== 'string' && typeof value !== 'number' && typeof value !== 'boolean') {
+				throw new ServerFault('url_unbuildable', `ctx.url('${endpoint}') parameter '${name}' is no scalar`)
+			}
+			search.set(name, value === null ? 'null' : String(value))
+		}
+		const text = search.toString()
+		return `${origin}${row.path}${text === '' ? '' : `?${text}`}`
+	}
+}
+
+/** A row a procedure of an RPC or link mount answers: never a generated, file or platform row. */
+function isProcedureRow(row: EndpointRow): boolean {
+	return (row.kind === 'query' || row.kind === 'mutation' || row.kind === 'public') && row.source.kind === 'mount'
+}