@fabrika/app 0.6.0 → 0.8.0

package/src/contract/define.ts

@@ -1,15 +1,14 @@
 // `defineContract`: the application's whole access surface as data. Browser-safe: it builds plain objects and
 // holds zod schemas; it validates nothing at runtime, `compileContract` does.
 
-import type { BuiltinRoleKey, ChallengeProvider, Locale, MailTemplates, RpcCaller } from '@fabrika/auth-core'
+import type { BuiltinRoleKey, ChallengeProvider, Locale, MailTemplates, RpcCaller, WebhookScheme } from '@fabrika/auth-core'
 import type { z } from 'zod/v4'
 import {
 	type CronDeclaration,
 	type CspDeclaration,
 	type ExportAccessDeclaration,
 	type ExportDeclaration,
-	type FilesDeclaration,
-	type FormMountDeclaration,
+	type FileKindDeclaration,
 	type HealthMountDeclaration,
 	type ImportDeclaration,
 	type LinkAccessDeclaration,
@@ -23,9 +22,15 @@ import {
 	unknownOptions,
 	type WebhookMountDeclaration,
 } from './declaration'
+import type { TokenPurposes } from './token'
 
 export type Path = `/${string}`
 
+/** A job attempt's time limit: 15 minutes by default, at most a day. A job reads no body, so it has no `maxBytes`. */
+export interface JobLimitsOption {
+	readonly timeoutMs?: number
+}
+
 /** Any zod 4 schema. `compileContract` refuses every form outside the contract subset. */
 export type Schema = z.core.$ZodType
 
@@ -179,7 +184,10 @@ export interface AppAccess<A extends string> {
 export interface LinkAccess<A extends string> {
 	readonly action: A
 }
-/** An SPA anyone opens, with no session; the page reaches only the anonymous endpoints. */
+/**
+ * Anyone opens it, with no session: an SPA whose page reaches only the anonymous endpoints, or a procedure whose
+ * handler runs as its own workload, holding the `actions` declared beside it.
+ */
 export interface PublicAccess {
 	readonly public: true
 }
@@ -190,12 +198,27 @@ export type InputOf<I> = [I] extends [InputSchema] ? z.output<I> : Record<never,
 /** Input fields of string type: the only fields a scope value can be read from. */
 export type StringField<In> = { [K in keyof In]-?: In[K] extends string ? K : never }[keyof In] & string
 
+/** One of several capabilities: an action listed over a dimension, or held on or in the value an input field names. */
+export type CapabilityAccess<A extends string, D extends string, In> =
+	| OverAccess<A, D>
+	| InAccess<A, D, StringField<In>>
+	| OnAccess<A, D, StringField<In>>
+
+/**
+ * Several capabilities, by the name the handler reads each under (`ctx.capabilities.<name>`): an operation that reads
+ * one dimension and writes another holds both, each checked and minted as its own access form would be.
+ */
+export interface CapabilitiesAccess<C> {
+	readonly capabilities: C
+}
+
 export type QueryAccess<A extends string, D extends string, In> =
 	| MemberAccess
 	| OverAccess<A, D>
 	| InAccess<A, D, StringField<In>>
 	| OnAccess<A, D, StringField<In>>
 	| AppAccess<A>
+	| CapabilitiesAccess<{ readonly [name: string]: CapabilityAccess<A, D, In> }>
 
 export type MutationAccess<A extends string, D extends string, CD extends string, In> = QueryAccess<A, D, In> | CreatesAccess<A, CD>
 
@@ -220,11 +243,10 @@ export interface ProcedureDef<I, O, Acc> extends Owned<'~kind' | 'type'> {
 	readonly input?: I & NotLoose<I>
 	readonly output: O & NotLoose<O>
 	readonly access: Acc
-	/** A page on one of the environment's listed origins may call it, with a key (ADR-0022). An RPC procedure only. */
-	readonly crossOrigin?: true
 }
 
-export interface RpcMount<C extends readonly [RpcCaller, ...RpcCaller[]], T extends ProcedureTree> extends RpcMountDeclaration<Schema> {
+/** `C` names the callers of its credentialed procedures; `readonly []` when every procedure is public. */
+export interface RpcMount<C extends readonly RpcCaller[], T extends ProcedureTree> extends RpcMountDeclaration<Schema> {
 	readonly callers: C
 	readonly procedures: T
 }
@@ -242,31 +264,17 @@ export interface SpaMount<Acc extends SpaAccessDeclaration> extends SpaMountDecl
 
 export type HealthMount = HealthMountDeclaration
 
-export interface FormMount<I extends Schema, T extends string = string> extends FormMountDeclaration<Schema> {
-	readonly input: I
-	readonly then?: T
-}
-
 export interface WebhookMount<B extends string, Acts extends string, I extends Schema> extends WebhookMountDeclaration<Schema> {
 	readonly boundTo: B
 	readonly actions: readonly Acts[]
 	readonly input: I
 }
 
-/** `L` is which link mounts' holders reach the collection: the typed client gives a link mount's holders only those. */
-/** `link` of `c.files`: every link mount bound to the owner's dimension, none, or the named ones. */
-export type LinkServing = boolean | readonly string[]
-
-export interface FileCollection<A extends string, L extends LinkServing = LinkServing> extends FilesDeclaration {
-	readonly read: A
-	readonly write: A
-	readonly delete: A
-	readonly link?: L
-}
+/** A file kind `c.files({ types, maxBytes, scan? })` declares: what a file column of that kind holds. */
+export interface FileKind extends FileKindDeclaration {}
 
-export interface CronJob<Acts extends string, Sc extends string> extends CronDeclaration {
+export interface CronJob<Acts extends string> extends CronDeclaration {
 	readonly actions: readonly Acts[]
-	readonly scope: Sc
 }
 
 export interface Export<T extends QueryTree> extends ExportDeclaration<Schema> {
@@ -274,74 +282,59 @@ export interface Export<T extends QueryTree> extends ExportDeclaration<Schema> {
 }
 
 export type AnyMount =
-	| RpcMount<readonly [RpcCaller, ...RpcCaller[]], ProcedureTree>
+	| RpcMount<readonly RpcCaller[], ProcedureTree>
 	| LinkMount<string, string, string, LinkProcedureTree>
 	| SpaMount<SpaAccessDeclaration>
 	| HealthMount
-	| FormMount<Schema>
 	| WebhookMount<string, string, Schema>
 
 /** What the callback of `defineContract` returns: mounts by name, and the sections `SURFACE_SECTIONS` names. */
 export interface SurfaceSections {
-	readonly files?: { readonly [name: string]: FileCollection<string> }
-	readonly jobs?: { readonly [name: string]: CronJob<string, string> }
+	readonly files?: { readonly [name: string]: FileKind }
+	readonly jobs?: { readonly [name: string]: CronJob<string> }
 	readonly exports?: { readonly [name: string]: Export<QueryTree> }
 	readonly imports?: { readonly [name: string]: ImportDeclaration }
 	readonly csp?: CspDeclaration
+	/** The token purposes; a kit contract takes them from `defineApp`'s options. */
+	readonly tokens?: TokenPurposes
 }
 
 export interface Surface extends SurfaceSections {
 	readonly [name: string]: AnyMount | SurfaceSections[keyof SurfaceSections]
 }
 
-/** What a form's `then` must be instead: the refusal, at the form's own line. */
-export type FormJobMessage = "then names a job of the contract's jobs section"
+/** A public procedure's challenge, by provider: Turnstile, verified at Cloudflare, or ALTCHA, which the application issues and verifies. */
+export type ChallengeOption = TurnstileChallengeOption | AltchaChallengeOption
 
-/** Each form's `then` names a job of the same surface's `jobs` section. */
-export type FormJobs<S> = {
-	readonly [K in keyof S]: S[K] extends { readonly kind: 'form'; readonly then?: infer T }
-		? [T] extends [string] ? { readonly then?: (S extends { readonly jobs: infer J } ? keyof J & string : never) | FormJobMessage }
-		: unknown
-		: unknown
-}
-
-/** A form's challenge: the provider and the application variables that hold its secret and its public site key. */
-export interface FormChallengeOption {
+interface ChallengeOptionBase {
 	readonly provider: ChallengeProvider
+	/** The application variable that holds the provider's secret (Turnstile's) or the HMAC key (ALTCHA's): a name, never the value. */
 	readonly secret: string
+	/**
+	 * The widget's `action`, which the verification expects back: at most 32 letters, digits, `_` and `-`. The endpoint id
+	 * with `_` for `.` by default (`api_visitors_register`).
+	 */
+	readonly action?: string
+}
+
+export interface TurnstileChallengeOption extends ChallengeOptionBase {
+	readonly provider: 'turnstile'
 	/** Served by every SPA mount at `<prefix>/__fabrika-config.json`, so the page renders the widget with it. */
 	readonly siteKey?: string
 }
 
-/** A file field of a form: the collection its file lands in (a `scan: true` one), and whether a submission must carry it. */
-export interface FormFileOption {
-	readonly collection: string
-	/** `true`: a submission without the file is refused (400). Absent or `false`: the column gets `null`. */
-	readonly required?: boolean
+/** The page fetches its challenge from `GET /__fabrika/challenge/<action>` (`challengeUrl` of `@fabrika/app/client`). */
+export interface AltchaChallengeOption extends ChallengeOptionBase {
+	readonly provider: 'altcha'
+	/**
+	 * The PBKDF2 iterations of one attempt, 1000 to 18000; 5000 by default. A browser makes up to 10000 attempts, about
+	 * 5000 on average, and the build refuses a cost a slow phone would not solve within 90 s or half of `maxAgeMs`.
+	 */
+	readonly cost?: number
+	/** How long a challenge may be solved and submitted, in ms, 60 s to an hour; ten minutes by default. */
+	readonly maxAgeMs?: number
 }
 
-/** What `c.form(path, options)` takes. */
-export type FormOptions<I, T> =
-	& {
-		readonly input: I & NotLoose<I>
-		readonly appendTo: string
-		readonly maxBytes?: number
-		/** Per minute; `bytesPerHour` only on a form with files, the bytes all its submissions write per hour. */
-		readonly rate?: { readonly perClient?: number; readonly perForm?: number; readonly bytesPerHour?: number }
-		readonly honeypot?: string
-		readonly challenge?: FormChallengeOption
-		/** The cron job each accepted submission kicks, in the background of the constant answer. */
-		readonly then?: T
-		/** A page on another origin may submit it: `true` from the environment's listed origins, `'*'` from any. */
-		readonly crossOrigin?: true | '*'
-		/**
-		 * Files a submission carries beside its input, by field. The form becomes `multipart/form-data` and needs a
-		 * challenge; each file waits, owned by nobody, until the job that drains the inbox attaches it.
-		 */
-		readonly files?: { readonly [field: string]: FormFileOption }
-	}
-	& Owned<'kind' | 'path'>
-
 export interface LinkKit<A extends string> {
 	query<const Acc extends LinkAccess<A>, O extends Schema, I extends InputSchema | null = null>(
 		def: ProcedureDef<I, O, Acc>,
@@ -383,40 +376,40 @@ export interface Kit<A extends string, D extends string, CD extends string> {
 			readonly dir: string
 			readonly access: Acc
 			/** Application variables whose values the pages read from `<prefix>/__fabrika-config.json`: public values only. */
-			readonly public?: readonly [string, ...string[]]
+			readonly browserConfig?: readonly [string, ...string[]]
 		} & Owned<'kind' | 'prefix'>,
 	): SpaMount<Acc>
 	health(path: Path): HealthMount
-	form<I extends InputSchema, const T extends string = never>(path: Path, options: FormOptions<I, T>): FormMount<I, NoInfer<T>>
 	webhook<const B extends D | 'app', const Acts extends readonly [A, ...A[]], I extends InputSchema>(
 		path: Path,
 		options: {
-			readonly scheme: 'github-sha256'
+			readonly scheme: WebhookScheme
 			readonly boundTo: B
 			readonly actions: Acts
 			readonly input: I & NotLoose<I>
-			readonly maxBytes?: number
+			/** A delivery's body (1 MiB by default and at most) and its handler's time (10 s by default, at most 60 s). */
+			readonly limits?: { readonly maxBytes?: number; readonly timeoutMs?: number }
 		} & Owned<'kind' | 'path'>,
 	): WebhookMount<B, Acts[number], I>
-	files<const L extends boolean | readonly [string, ...string[]] = false>(
-		collection: {
-			readonly owner: string
-			readonly read: A
-			readonly write: A
-			readonly delete: A
-			readonly maxBytes: number
-			readonly types: readonly [string, ...string[]]
-			readonly maxPerOwner?: number
-			/** `true`: every link mount bound to the owner's dimension serves the files; a list: the named link mounts only. */
-			readonly link?: L
-			/** Each upload is scanned for malware and served only after a clean verdict; until then it answers 409. */
-			readonly scan?: boolean
-		} & Owned<'kind'>,
-	): FileCollection<A, L>
-	cron<const Acts extends readonly [A, ...A[]], const Sc extends D | 'app'>(
+	/**
+	 * A file kind: the media types its files may be, the largest one, and whether each waits for a clean scan. A table's
+	 * file column holds files of it (`files: { <column>: '<kind>' }`), and the table's actions are their authority.
+	 */
+	files(
+		kind:
+			& {
+				readonly types: readonly [string, ...string[]]
+				readonly maxBytes: number
+				/** Each file is scanned for malware and served only after a clean verdict; until then it answers 409. */
+				readonly scan?: boolean
+			}
+			& Owned<'kind'>,
+	): FileKind
+	/** A job of the whole application, holding `actions`; it runs on its schedule (UTC, five fields) and when kicked. */
+	cron<const Acts extends readonly [A, ...A[]]>(
 		schedule: string,
-		options: { readonly actions: Acts; readonly scope: Sc; readonly timeout?: string; readonly retries?: number } & Owned<'kind' | 'schedule'>,
-	): CronJob<Acts[number], Sc>
+		options: { readonly actions: Acts; readonly limits?: JobLimitsOption; readonly retries?: number } & Owned<'kind' | 'schedule'>,
+	): CronJob<Acts[number]>
 	export<const T extends QueryTree>(
 		definition: {
 			readonly version: number
@@ -452,7 +445,6 @@ function procedure<T extends ProcedureType, I extends InputSchema | null, O exte
 		input: def.input ?? null,
 		output: def.output,
 		access: def.access,
-		...(def.crossOrigin === undefined ? {} : { crossOrigin: def.crossOrigin }),
 		unknownOptions: unknownOptions(def, 'procedure'),
 	}
 }
@@ -492,24 +484,10 @@ export function surfaceKit<A extends string, D extends string, CD extends string
 			prefix,
 			dir: options.dir,
 			access: options.access,
-			public: options.public,
+			browserConfig: options.browserConfig,
 			unknownOptions: unknownOptions(options, 'spa'),
 		}),
 		health: (path) => ({ kind: 'health', path }),
-		form: (path, options) => ({
-			kind: 'form',
-			path,
-			input: options.input,
-			appendTo: options.appendTo,
-			maxBytes: options.maxBytes,
-			rate: options.rate,
-			honeypot: options.honeypot,
-			challenge: options.challenge,
-			then: options.then,
-			...(options.crossOrigin === undefined ? {} : { crossOrigin: options.crossOrigin }),
-			...(options.files === undefined ? {} : { files: options.files }),
-			unknownOptions: unknownOptions(options, 'form'),
-		}),
 		webhook: (path, options) => ({
 			kind: 'webhook',
 			path,
@@ -517,28 +495,21 @@ export function surfaceKit<A extends string, D extends string, CD extends string
 			boundTo: options.boundTo,
 			actions: options.actions,
 			input: options.input,
-			maxBytes: options.maxBytes,
+			...(options.limits === undefined ? {} : { limits: options.limits }),
 			unknownOptions: unknownOptions(options, 'webhook'),
 		}),
-		files: (collection) => ({
-			kind: 'files',
-			owner: collection.owner,
-			read: collection.read,
-			write: collection.write,
-			delete: collection.delete,
-			maxBytes: collection.maxBytes,
-			types: collection.types,
-			maxPerOwner: collection.maxPerOwner,
-			link: collection.link,
-			scan: collection.scan,
-			unknownOptions: unknownOptions(collection, 'files'),
+		files: (kind) => ({
+			kind: 'file-kind',
+			types: kind.types,
+			maxBytes: kind.maxBytes,
+			scan: kind.scan,
+			unknownOptions: unknownOptions(kind, 'fileKind'),
 		}),
 		cron: (schedule, options) => ({
 			kind: 'cron',
 			schedule,
 			actions: options.actions,
-			scope: options.scope,
-			timeout: options.timeout,
+			...(options.limits === undefined ? {} : { limits: options.limits }),
 			retries: options.retries,
 			unknownOptions: unknownOptions(options, 'cron'),
 		}),
@@ -562,7 +533,7 @@ export function defineContract<
 	const D extends string,
 	const R extends string,
 	const Dims extends { readonly [K in D]: DimensionDef<NoInfer<A>, NoInfer<D>, NoInfer<R>> },
-	const S extends Surface & FormJobs<S>,
+	const S extends Surface,
 >(
 	vocabulary: Presentation & AppPeople<NoInfer<A>> & {
 		readonly app: string

package/src/contract/file.ts

@@ -0,0 +1,78 @@
+// `file('<kind>')`: a stored file of a declared kind, as a procedure's input field or its whole output. In an input it
+// is a top-level field, optional, or a bounded array of them: the client sends it as a multipart part of its own, and
+// the handler receives a file reference to the file the framework staged. As an output it is the file the procedure
+// answers: the handler returns a reference it read, and the framework streams the file. The value is a zod schema of a
+// file reference, marked with its kind.
+
+import { z } from 'zod/v4'
+import type { Schema } from './define'
+
+const FILE = Symbol('fabrika.file')
+
+/** A stored file's states: written, waiting for a scan, served, or refused by the scan. */
+export type FileStatus = 'pending' | 'quarantined' | 'live' | 'rejected'
+
+/**
+ * What a handler holds of a stored file: its metadata, never its bytes. A file column read through `ctx.db`, an input
+ * file and `ctx.files.put` answer one; only one this request holds is written into a column, served or opened.
+ */
+export interface FileRef {
+	readonly id: string
+	readonly name: string | null
+	readonly type: string
+	readonly size: number
+	readonly status: FileStatus
+}
+
+/** What `file()` adds to its schema: the kind of file it holds. */
+export interface FileMark {
+	readonly kind: string
+}
+
+/** A file field or output of kind `K`. */
+export type FileSchema<K extends string = string> = z.ZodType<FileRef, FileRef> & FileBrand<K>
+
+/** What tells a file schema from a JSON one in the types. */
+export interface FileBrand<K extends string> {
+	readonly [FILE]: FileMark & { readonly '~kind'?: K }
+}
+
+/** The marks `file` made: a property another module set on a schema is no file. */
+const marks = new WeakSet<object>()
+
+/** A value a file field admits on its way in: a reference the framework made, or (in a browser) the `Blob` it sends. */
+function isFileValue(value: unknown): boolean {
+	if (typeof Blob !== 'undefined' && value instanceof Blob) {
+		return true
+	}
+	return typeof value === 'object' && value !== null && typeof Reflect.get(value, 'id') === 'string'
+}
+
+/**
+ * A file of kind `kind` (`c.files({ … })` of the contract): an input field (top level, `z.optional`, or `z.array(…).max(n)`)
+ * or a procedure's output. `compileContract` and the checker refuse it anywhere else.
+ */
+export function file<const K extends string>(kind: K): FileSchema<K> {
+	const mark: FileMark = Object.freeze({ kind })
+	marks.add(mark)
+	const schema: z.ZodType<FileRef, FileRef> = z.custom<FileRef>(isFileValue, { message: `a file of kind '${kind}'` })
+	return Object.assign(schema, { [FILE]: mark })
+}
+
+/** The mark of a `file()` schema, or `null` for any other schema. */
+export function fileOf(schema: Schema | z.core.$ZodType): FileMark | null {
+	const mark: unknown = Reflect.get(schema, FILE)
+	return isMark(mark) ? mark : null
+}
+
+function isMark(value: unknown): value is FileMark {
+	return typeof value === 'object' && value !== null && marks.has(value)
+}
+
+type ClientValue<V> = V extends FileRef ? Blob : V extends readonly FileRef[] ? readonly Blob[] : V
+
+/**
+ * An input as a client sends it: each file field takes the `Blob` (or `File`) the page holds, which the client sends as
+ * a part of its own. An input without a file field is the input itself.
+ */
+export type ClientInput<T> = [Extract<T[keyof T], FileRef | readonly FileRef[]>] extends [never] ? T : { [K in keyof T]: ClientValue<T[K]> }