@fabrika/app 0.6.0 → 0.8.0

package/src/contract/artifact-schema.ts

@@ -6,13 +6,17 @@ import {
 	type ArrayShape,
 	type AttachmentShape,
 	BUILTIN_ROLE_KEYS,
+	CONTRACT_FORMAT,
 	type ContractArtifact,
 	CROSS_ORIGIN_KINDS,
 	displayNameProblem,
 	type EndpointRow,
+	FILE_RESPONSE_KINDS,
+	isOwnWorkloadName,
 	JOB_MAILERS,
 	LOCALES,
 	mailTemplateProblems,
+	MAX_CACHE_AGE_SECONDS,
 	type MessageKind,
 	type NumberShape,
 	type OutputShape,
@@ -22,8 +26,20 @@ import {
 	type TablePolicyArtifact,
 	type TupleShape,
 } from '@fabrika/auth-core'
+import { isPolicyOrigin, WORKER_BLOB_SOURCE } from '@fabrika/proxy-core/headers'
 import { z } from 'zod/v4'
-import { FORM_LIMITS } from './defaults'
+import {
+	ALTCHA_LIMITS,
+	altchaSolvable,
+	CHALLENGE_ACTION,
+	CHALLENGE_PREFIX,
+	challengePath,
+	challengeRowId,
+	JOB_LIMITS,
+	PROCEDURE_LIMITS,
+} from './defaults'
+import { TOKEN_MAX_DAYS } from './token'
+import { webhookSchemeSchema } from './webhook-scheme'
 
 const name = z.string().min(1)
 const nullableName = name.nullable()
@@ -31,7 +47,6 @@ const names = z.array(name)
 const record = <T extends z.core.$ZodType>(value: T) => z.record(z.string().min(1), value)
 /** A contract's actions are exact: IAM treats `*` as a pattern, which would widen every grant naming it. */
 const action = name.refine((value) => !value.includes('*'), 'an action is exact; * is not an action')
-const nullableAction = action.nullable()
 const actions = z.array(action)
 /** IAM's own role keys win over an application role of the same key at resolution. */
 const roleKey = name.refine((key) => !BUILTIN_ROLE_KEYS.includes(key), 'a built-in IAM role key is not a contract role name')
@@ -72,6 +87,8 @@ export const schemaShapeSchema: z.ZodType<SchemaShape> = z.lazy(() =>
 		z.strictObject({ type: z.literal('optional'), inner: schemaShapeSchema }),
 		z.strictObject({ type: z.literal('nullable'), inner: schemaShapeSchema }),
 		z.strictObject({ type: z.literal('union'), options: z.array(schemaShapeSchema) }),
+		z.strictObject({ type: z.literal('token'), purpose: name }),
+		z.strictObject({ type: z.literal('file'), kind: z.string().min(1) }),
 	])
 )
 
@@ -102,7 +119,9 @@ const attachmentShape: z.ZodType<AttachmentShape> = z.strictObject({
 })
 
 /** What a procedure answers: a schema shape, or an attachment's file. */
-export const outputShapeSchema: z.ZodType<OutputShape> = z.union([schemaShapeSchema, attachmentShape])
+const redirectShape = z.strictObject({ type: z.literal('redirect'), origins: z.array(z.string().startsWith('https://')) })
+
+export const outputShapeSchema: z.ZodType<OutputShape> = z.union([schemaShapeSchema, attachmentShape, redirectShape])
 
 const caller = z.union([z.enum(['human', 'machine', 'link']), z.templateLiteral(['app:', z.string().min(1)])])
 const rpcCaller = z.enum(['human', 'machine'])
@@ -115,9 +134,27 @@ const accessForm = z.discriminatedUnion('form', [
 	z.strictObject({ form: z.literal('app') }),
 ])
 
+const capabilityForm = z.discriminatedUnion('form', [
+	z.strictObject({ form: z.literal('over'), dimension: name }),
+	z.strictObject({ form: z.literal('in'), dimension: name, from: name }),
+	z.strictObject({ form: z.literal('on'), dimension: name, from: name }),
+])
+
 const requirement = z.discriminatedUnion('kind', [
 	z.strictObject({ kind: z.literal('member') }),
 	z.strictObject({ kind: z.literal('action'), action, access: accessForm }),
+	z.strictObject({
+		kind: z.literal('capabilities'),
+		capabilities: record(z.strictObject({ action, access: capabilityForm })).refine(
+			(capabilities) => Object.keys(capabilities).length >= 2,
+			'several capabilities are at least two',
+		),
+	}),
+])
+
+const endpointCacheSchema = z.union([
+	z.literal('immutable'),
+	z.strictObject({ maxAgeSeconds: z.int().min(1).max(MAX_CACHE_AGE_SECONDS) }),
 ])
 
 const rowBase = {
@@ -128,6 +165,7 @@ const rowBase = {
 	admission: z.strictObject({ contentTypes: z.tuple([name], name), maxBytes: z.int().positive().nullable() }).nullable(),
 	input: schemaShapeSchema.nullable(),
 	output: outputShapeSchema.nullable(),
+	response: z.literal('file').optional(),
 }
 
 const endpointRow: z.ZodType<EndpointRow> = z.union([
@@ -144,6 +182,31 @@ const endpointRow: z.ZodType<EndpointRow> = z.union([
 		callers: z.tuple([]),
 		requirement: z.null(),
 		crossOrigin: z.enum(['environment', 'any']).optional(),
+		authorization: z.literal('forward').optional(),
+	}).refine((row) => row.authorization === undefined || row.kind === 'webhook', "only a webhook forwards the request's Authorization"),
+	// A public procedure is a mount's procedure anyone calls: it admits a body and answers its output.
+	z.strictObject({
+		...rowBase,
+		kind: z.literal('public'),
+		source: z.strictObject({ kind: z.literal('mount'), name }),
+		output: outputShapeSchema,
+		callers: z.tuple([]),
+		requirement: z.null(),
+		crossOrigin: z.enum(['environment', 'any']).optional(),
+		cache: endpointCacheSchema.optional(),
+	}).refine((row) => row.cache === undefined || row.method === 'GET', 'only a GET answer is cached'),
+	// The framework's own GET that issues the ALTCHA challenge of the public procedure its source names: no body, no schemas.
+	z.strictObject({
+		...rowBase,
+		kind: z.literal('public'),
+		source: z.strictObject({ kind: z.literal('challenge'), name }),
+		method: z.literal('GET'),
+		admission: z.null(),
+		input: z.null(),
+		output: z.null(),
+		callers: z.tuple([]),
+		requirement: z.null(),
+		crossOrigin: z.enum(['environment', 'any']).optional(),
 	}),
 	// A public SPA is a fixed static row: GET only, no body, no schemas.
 	z.strictObject({
@@ -157,7 +220,11 @@ const endpointRow: z.ZodType<EndpointRow> = z.union([
 		requirement: z.null(),
 	}),
 ]).refine(
-	// Only an RPC procedure and a form open to another origin, and only a form to any (ADR-0022).
+	// Only a procedure answers a stored file, and exactly when its output is one.
+	(row) => (row.response === 'file') === (row.output?.type === 'file') && (row.response === undefined || FILE_RESPONSE_KINDS.includes(row.kind)),
+	'only a procedure whose output is a file answers a stored file',
+).refine(
+	// Only an RPC procedure, a public procedure and a form open to another origin, and only the anonymous two to any (ADR-0022).
 	(row) =>
 		!('crossOrigin' in row) || row.crossOrigin === undefined
 		|| (CROSS_ORIGIN_KINDS.includes(row.kind) && (row.crossOrigin !== 'any' || ANY_ORIGIN_KINDS.includes(row.kind))),
@@ -169,11 +236,25 @@ const scopeBinding = z.discriminatedUnion('kind', [
 	z.strictObject({ kind: z.literal('dimension'), dimension: name }),
 ])
 
-const formRate = z.int().positive().max(FORM_LIMITS.maxPerMinute)
+/** A form's rate, per minute, as the releases that declared forms (up to 0.5) bounded it. */
+const formRate = z.int().positive().max(10_000)
 const applicationVariable = z.string().regex(/^[A-Z][A-Z0-9_]*$/)
+const bucket = z.int().positive().max(PROCEDURE_LIMITS.maxPerMinute).nullable()
+const challenge = z.strictObject({ provider: z.literal('turnstile'), secret: applicationVariable, siteKey: applicationVariable.optional() })
+const challengeActionSchema = z.string().regex(CHALLENGE_ACTION)
+const procedureChallenge = z.discriminatedUnion('provider', [
+	challenge.extend({ action: challengeActionSchema }),
+	z.strictObject({
+		provider: z.literal('altcha'),
+		secret: applicationVariable,
+		action: challengeActionSchema,
+		cost: z.int().min(ALTCHA_LIMITS.minCost).max(ALTCHA_LIMITS.maxCost),
+		maxAgeMs: z.int().min(ALTCHA_LIMITS.minMaxAgeMs).max(ALTCHA_LIMITS.maxMaxAgeMs),
+	}).refine((challenge) => altchaSolvable(challenge.cost, challenge.maxAgeMs), 'a slow phone does not solve this challenge in time'),
+])
 
 const mount = z.discriminatedUnion('kind', [
-	z.strictObject({ kind: z.literal('rpc'), prefix: name, callers: z.tuple([rpcCaller], rpcCaller) }),
+	z.strictObject({ kind: z.literal('rpc'), prefix: name, callers: z.array(rpcCaller), compatibility: z.literal('backward').optional() }),
 	z.strictObject({
 		kind: z.literal('link'),
 		prefix: name,
@@ -191,15 +272,28 @@ const mount = z.discriminatedUnion('kind', [
 		appendTo: name,
 		rate: z.strictObject({ perClient: formRate.optional(), perForm: formRate.optional(), bytesPerHour: z.int().positive().optional() }).optional(),
 		honeypot: name.optional(),
-		challenge: z.strictObject({ provider: z.literal('turnstile'), secret: applicationVariable, siteKey: applicationVariable.optional() }).optional(),
+		challenge: challenge.optional(),
 		then: name.optional(),
 		files: z.record(name, z.strictObject({ collection: name, required: z.boolean() })).optional(),
 	}),
-	z.strictObject({ kind: z.literal('webhook'), path: name, scheme: z.literal('github-sha256'), boundTo: scopeBinding, actions }),
+	z.strictObject({
+		kind: z.literal('webhook'),
+		path: name,
+		scheme: webhookSchemeSchema,
+		boundTo: scopeBinding,
+		actions,
+		timeoutMs: z.int().positive().max(PROCEDURE_LIMITS.maxTimeoutMs),
+	}),
 ])
 
 const cspSource = z.strictObject({ origin: name, purpose: name })
 
+/** One action as its text (every release's form), or several distinct ones as a list of at least two. */
+const tableAction = z.union([
+	action,
+	z.array(action).min(2).refine((list) => new Set(list).size === list.length, 'a table operation names each action once'),
+])
+
 const tablePolicy: z.ZodType<TablePolicyArtifact> = z.strictObject({
 	scope: z.discriminatedUnion('mode', [
 		z.strictObject({
@@ -214,10 +308,10 @@ const tablePolicy: z.ZodType<TablePolicyArtifact> = z.strictObject({
 		z.strictObject({ mode: z.literal('app'), reason: name, key: name }),
 	]),
 	actions: z.strictObject({
-		read: action,
-		insert: nullableAction,
-		update: nullableAction,
-		delete: nullableAction,
+		read: tableAction,
+		insert: tableAction.nullable(),
+		update: tableAction.nullable(),
+		delete: tableAction.nullable(),
 		appRead: z.array(action).nonempty().optional(),
 		appCount: z.array(action).nonempty().optional(),
 	}),
@@ -226,9 +320,11 @@ const tablePolicy: z.ZodType<TablePolicyArtifact> = z.strictObject({
 	version: nullableName,
 	createdBy: nullableName,
 	columns: record(z.strictObject({ read: action.optional(), write: action.optional() })),
+	files: z.record(name, name).optional(),
 })
 
 export const contractArtifactSchema: z.ZodType<ContractArtifact> = z.strictObject({
+	format: z.literal(CONTRACT_FORMAT),
 	app: name,
 	dimensions: record(z.strictObject({
 		in: nullableName,
@@ -260,11 +356,12 @@ export const contractArtifactSchema: z.ZodType<ContractArtifact> = z.strictObjec
 		link: z.union([z.boolean(), z.array(name).nonempty()]),
 		scan: z.literal(true).optional(),
 	})),
+	fileKinds: z.record(name, z.strictObject({ types: names, maxBytes: z.int().positive(), scan: z.literal(true).optional() })).optional(),
 	jobs: record(z.strictObject({
 		schedule: name,
 		actions,
 		scope: scopeBinding,
-		timeout: nullableName,
+		timeoutMs: z.int().positive().max(JOB_LIMITS.maxTimeoutMs),
 		retries: z.int().nonnegative(),
 	})),
 	exports: record(z.strictObject({ version: z.int().positive(), consumers: names, audience: name })),
@@ -285,6 +382,7 @@ export const contractArtifactSchema: z.ZodType<ContractArtifact> = z.strictObjec
 		frameSrc: z.array(cspSource).nonempty().optional(),
 		styleSrc: z.array(cspSource).nonempty().optional(),
 		fontSrc: z.array(cspSource).nonempty().optional(),
+		workerSrc: z.tuple([z.strictObject({ origin: z.literal(WORKER_BLOB_SOURCE), purpose: z.string().min(1) })]).optional(),
 	}),
 	tables: record(tablePolicy),
 	endpoints: z.array(endpointRow).superRefine((rows, context) => {
@@ -308,7 +406,18 @@ export const contractArtifactSchema: z.ZodType<ContractArtifact> = z.strictObjec
 		issues: nullableName,
 		then: name.optional(),
 		mailer: z.enum(JOB_MAILERS).optional(),
-	})).optional(),
+		actions: actions.nonempty().optional(),
+		kicks: z.array(name).nonempty().optional(),
+		binds: name.optional(),
+		signs: z.array(name).nonempty().optional(),
+		egress: z.array(z.string().refine((origin) => isPolicyOrigin(origin))).nonempty().optional(),
+	})).superRefine((declared, context) => {
+		for (const [site, reach] of Object.entries(declared)) {
+			if (reach.actions !== undefined && !isOwnWorkloadName('public', site)) {
+				context.addIssue({ code: 'custom', path: [site, 'actions'], message: 'workload actions belong to a public procedure, keyed by its endpoint id' })
+			}
+		}
+	}).optional(),
 	directories: record(z.strictObject({ dimension: name, lists: z.boolean() })).optional(),
 	locale: z.enum(LOCALES).optional(),
 	displayName: z.string().refine((value) => displayNameProblem(value) === null, 'not a display name').optional(),
@@ -316,6 +425,51 @@ export const contractArtifactSchema: z.ZodType<ContractArtifact> = z.strictObjec
 		.optional(),
 	members: z.strictObject({ manage: action, list: action }).optional(),
 	directory: z.literal('labels').optional(),
+	procedures: record(z.strictObject({
+		rate: z.strictObject({
+			perClient: bucket,
+			perCaller: bucket,
+			perEndpoint: bucket,
+			bytesPerHour: z.int().positive().max(PROCEDURE_LIMITS.maxBytesPerHour).nullable(),
+		}),
+		challenge: procedureChallenge.nullable(),
+		timeoutMs: z.int().positive().max(PROCEDURE_LIMITS.maxTimeoutMs),
+		query: schemaShapeSchema.optional(),
+		changesStateOnGet: z.literal(true).optional(),
+	})).optional(),
+	tokens: record(z.strictObject({ claims: schemaShapeSchema, maxDays: z.int().positive().max(TOKEN_MAX_DAYS) })).optional(),
+}).superRefine((artifact, context) => {
+	for (const row of artifact.endpoints) {
+		if (row.kind === 'public' && row.source.kind !== 'challenge' && artifact.declared?.[row.id]?.actions === undefined) {
+			context.addIssue({ code: 'custom', path: ['declared', row.id], message: 'a public procedure declares its workload actions' })
+		}
+	}
+	// Every ALTCHA challenge has exactly its own issuer, under its action, from the procedure's origins, with its own buckets.
+	const rows = new Map(artifact.endpoints.map((row) => [row.id, row]))
+	const issuers = artifact.endpoints.filter((row) => row.source.kind === 'challenge')
+	for (const [id, rules] of Object.entries(artifact.procedures ?? {})) {
+		if (rules.challenge?.provider !== 'altcha') continue
+		const issuer = rows.get(challengeRowId(id))
+		const procedure = rows.get(id)
+		if (
+			issuer === undefined || procedure === undefined || issuer.source.kind !== 'challenge' || issuer.source.name !== id
+			|| issuer.path !== challengePath(rules.challenge.action) || issuer.crossOrigin !== procedure.crossOrigin
+			|| artifact.procedures?.[issuer.id]?.challenge !== null
+		) {
+			context.addIssue({ code: 'custom', path: ['procedures', id, 'challenge'], message: 'an ALTCHA challenge has its own issuer row' })
+		}
+	}
+	for (const issuer of issuers) {
+		if (issuer.id !== challengeRowId(issuer.source.name) || artifact.procedures?.[issuer.source.name]?.challenge?.provider !== 'altcha') {
+			context.addIssue({ code: 'custom', path: ['endpoints'], message: `'${issuer.id}' issues the challenge of no ALTCHA procedure` })
+		}
+	}
+	if (issuers.length > 0 && !artifact.reservedPrefixes.includes(CHALLENGE_PREFIX)) {
+		context.addIssue({ code: 'custom', path: ['reservedPrefixes'], message: `an issuer row reserves ${CHALLENGE_PREFIX}` })
+	}
+	if ((artifact.csp.workerSrc !== undefined) !== issuers.length > 0) {
+		context.addIssue({ code: 'custom', path: ['csp', 'workerSrc'], message: 'workerSrc admits the workers of an ALTCHA challenge, and only those' })
+	}
 })
 
 function mailLocales(kind: MessageKind) {