@fabrika/app 0.5.5 → 0.7.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,11 @@ import {
 	type TablePolicyArtifact,
 	type TupleShape,
 } from '@fabrika/auth-core'
+import { isPolicyOrigin } from '@fabrika/proxy-core/headers'
 import { z } from 'zod/v4'
-import { FORM_LIMITS } from './defaults'
+import { CHALLENGE_ACTION, 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 +38,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 +78,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 +110,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 +125,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 +156,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,7 +173,19 @@ 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'),
 	// A public SPA is a fixed static row: GET only, no body, no schemas.
 	z.strictObject({
 		...rowBase,
@@ -157,7 +198,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 +214,15 @@ 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 procedureChallenge = challenge.extend({ action: z.string().regex(CHALLENGE_ACTION) })
 
 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 +240,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 +276,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 +288,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 +324,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 })),
@@ -308,7 +373,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 +392,25 @@ 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' && artifact.declared?.[row.id]?.actions === undefined) {
+			context.addIssue({ code: 'custom', path: ['declared', row.id], message: 'a public procedure declares its workload actions' })
+		}
+	}
 })
 
 function mailLocales(kind: MessageKind) {