@fabrika/app 0.3.3 → 0.4.0

package/src/contract/platform.ts

@@ -0,0 +1,113 @@
+// What a contract compiles to for IAM (ADR-0012 §4): the vocabulary the deploy reconciles. The proxy reads the
+// endpoint table itself (`contractProxyTable` in `@fabrika/proxy-core/manifest`).
+
+import {
+	APP_CALLER_PREFIX,
+	type AppDelegationDef,
+	type AppLinkMountDef,
+	type AppSchema,
+	type AppScopeDef,
+	type AppWorkloadDef,
+	type ContractArtifact,
+	type DimensionArtifact,
+	directoryLookups,
+	endpointDelegation,
+	type EndpointRow,
+	JOB_SITE_PREFIX,
+	type LinkMountArtifact,
+	type RoleArtifact,
+	type RoleDef,
+} from '@fabrika/auth-core'
+
+/**
+ * The IAM vocabulary of a contract application, marked `contract` so IAM refuses every wildcard written for it: the
+ * dimensions as scopes with their container, creator role and members actions; the actions; the roles, a membership
+ * role with its scope and the roles that may assign it; the link mounts; the delegations; the workloads; and the locale,
+ * display name and e-mail wording IAM names the application with. Every artifact
+ * dimension is a scope, a file collection's `file:<name>` included, because access to a file is checked there.
+ */
+export function schemaFromContract(artifact: ContractArtifact): AppSchema {
+	return {
+		scopes: Object.entries(artifact.dimensions).sort(([a], [b]) => byCodeUnit(a, b)).map(([type, dimension]) =>
+			scopeDef(type, dimension, directoryLookups(artifact, type))
+		),
+		actions: Object.entries(artifact.actions).sort(([a], [b]) => byCodeUnit(a, b)).map(([action, description]) => ({ action, description })),
+		roles: Object.fromEntries(Object.entries(artifact.roles).map(([key, role]) => [key, roleDef(key, role)])),
+		contract: true,
+		links: Object.fromEntries(Object.entries(artifact.mounts).flatMap(([name, mount]) => (mount.kind === 'link' ? [[name, linkDef(mount)]] : []))),
+		delegations: Object.fromEntries(artifact.endpoints.flatMap((row) => {
+			const delegation = delegationOf(artifact, row)
+			return delegation === null ? [] : [[row.id, delegation]]
+		})),
+		workloads: workloadsOf(artifact),
+		...(artifact.locale === undefined ? {} : { locale: artifact.locale }),
+		...(artifact.displayName === undefined ? {} : { displayName: artifact.displayName }),
+		...(artifact.mail === undefined ? {} : { mail: artifact.mail }),
+		...(artifact.members === undefined ? {} : { members: { manage: artifact.members.manage, list: artifact.members.list } }),
+		...(artifact.directory === 'labels' ? { directory: 'labels' } : {}),
+	}
+}
+
+/**
+ * Every job and webhook with its exact actions, a job with the link mount it declares it `issues`, and every consumer of
+ * an export with the actions of the export rows it may call: what each workload key carries (ADR-0022 "Principal kinds").
+ */
+function workloadsOf(artifact: ContractArtifact): AppWorkloadDef[] {
+	const jobs = Object.entries(artifact.jobs).map(([name, job]): AppWorkloadDef => {
+		const issues = artifact.declared?.[`${JOB_SITE_PREFIX}${name}`]?.issues ?? null
+		return { kind: 'job', name, actions: [...job.actions].sort(byCodeUnit), ...(issues === null ? {} : { issues }) }
+	})
+	const webhooks = Object.entries(artifact.mounts).flatMap(([name, mount]): AppWorkloadDef[] =>
+		mount.kind === 'webhook' ? [{ kind: 'webhook', name, actions: [...mount.actions].sort(byCodeUnit) }] : []
+	)
+	const consumers = new Map<string, Set<string>>()
+	for (const row of artifact.endpoints) {
+		if (row.source.kind !== 'export' || row.requirement?.kind !== 'action') continue
+		for (const caller of row.callers) {
+			if (!caller.startsWith(APP_CALLER_PREFIX)) continue
+			const consumer = caller.slice(APP_CALLER_PREFIX.length)
+			consumers.set(consumer, (consumers.get(consumer) ?? new Set<string>()).add(row.requirement.action))
+		}
+	}
+	const apps = [...consumers].map(([name, actions]): AppWorkloadDef => ({ kind: 'app', name, actions: [...actions].sort(byCodeUnit) }))
+	return [...jobs, ...webhooks, ...apps].sort((a, b) => byCodeUnit(`${a.kind}:${a.name}`, `${b.kind}:${b.name}`))
+}
+
+/** Key order differs between the two producers of an artifact; the schema must not. */
+function byCodeUnit(a: string, b: string): number {
+	return a < b ? -1 : a > b ? 1 : 0
+}
+
+function scopeDef(type: string, dimension: DimensionArtifact, lookups: readonly string[]): AppScopeDef {
+	return {
+		type,
+		...(dimension.in === null ? {} : { in: dimension.in }),
+		...(dimension.creator === null ? {} : { creator: dimension.creator }),
+		...(dimension.members === null ? {} : { members: { manage: dimension.members.manage, list: dimension.members.list } }),
+		...(dimension.directory === 'labels' ? { directory: 'labels' } : {}),
+		...(lookups.length === 0 ? {} : { lookups: [...lookups] }),
+	}
+}
+
+function roleDef(key: string, role: RoleArtifact): RoleDef {
+	// `external` is carried on every role, so IAM refuses one on a role that is not a membership role instead of never seeing it.
+	return {
+		name: key,
+		permissions: [...role.grants],
+		...(role.member === null ? {} : { member: { scope: role.member.scope, assignableBy: [...role.member.assignableBy] } }),
+		...(role.external === true ? { external: true } : {}),
+	}
+}
+
+function linkDef(mount: LinkMountArtifact): AppLinkMountDef {
+	return { dimension: mount.dimension, grants: [...mount.grants], issuedBy: mount.issuedBy, maxDays: mount.maxDays }
+}
+
+/** The grant IAM issues for an endpoint that spends membership authority; `endpointDelegation` decides which do. */
+function delegationOf(artifact: ContractArtifact, row: EndpointRow): AppDelegationDef | null {
+	const purpose = endpointDelegation(artifact, row)
+	if (purpose === null || row.requirement?.kind !== 'action' || row.requirement.access.form === 'app') {
+		return null
+	}
+	return { action: row.requirement.action, dimension: row.requirement.access.dimension, purpose }
+}

package/src/contract/problems.ts

@@ -0,0 +1,30 @@
+/** Every reason a contract does not compile, each with where it is and the allowed form. */
+export class ContractError extends Error {
+	override readonly name = 'ContractError'
+	readonly problems: readonly string[]
+
+	constructor(problems: readonly string[]) {
+		super(`the contract does not compile:\n- ${problems.join('\n- ')}`)
+		this.problems = problems
+	}
+}
+
+/** Collects problems so that one compile reports all of them, not the first. */
+export class Problems {
+	readonly #problems: string[] = []
+
+	add(where: string, problem: string): void {
+		this.#problems.push(`${where}: ${problem}`)
+	}
+
+	throwIfAny(): void {
+		if (this.#problems.length > 0) {
+			throw new ContractError([...this.#problems])
+		}
+	}
+}
+
+/** A builder of the staged kit whose signature is fixed and whose runtime a later work unit of the sprint adds. */
+export function notImplemented(what: string, unit: string): never {
+	throw new Error(`${what} is not implemented (${unit})`)
+}

package/src/contract/schema-from-shape.ts

@@ -0,0 +1,152 @@
+// A `SchemaShape` turned back into a zod schema, and the part of a validation issue's path that the shape declares.
+// A connector validates against schemas built here from the snapshot's description, never against the application's
+// own schema objects, which application code could change after `boot` checked them.
+
+import type { SchemaShape, StringShape } from '@fabrika/auth-core'
+import { z } from 'zod/v4'
+
+/** The zod schema that admits what `shape` describes; `describeSchema` reads it back into the same shape. */
+export function schemaFromShape(shape: SchemaShape): z.ZodType {
+	switch (shape.type) {
+		case 'string':
+			return stringSchema(shape)
+		case 'number': {
+			let schema = shape.int ? z.int() : z.number()
+			if (shape.min !== null) {
+				schema = shape.exclusiveMin ? schema.gt(shape.min) : schema.gte(shape.min)
+			}
+			if (shape.max !== null) {
+				schema = shape.exclusiveMax ? schema.lt(shape.max) : schema.lte(shape.max)
+			}
+			return shape.multipleOf === null ? schema : schema.multipleOf(shape.multipleOf)
+		}
+		case 'boolean':
+			return z.boolean()
+		case 'null':
+			return z.null()
+		case 'literal':
+			return z.literal(shape.value)
+		case 'enum': {
+			const [first, ...rest] = shape.values
+			return first === undefined ? z.never() : z.enum([first, ...rest])
+		}
+		case 'array': {
+			let schema = z.array(schemaFromShape(shape.items))
+			if (shape.minItems !== null) {
+				schema = schema.min(shape.minItems)
+			}
+			return shape.maxItems === null ? schema : schema.max(shape.maxItems)
+		}
+		case 'tuple': {
+			const [first, ...rest] = shape.items.map(schemaFromShape)
+			if (first === undefined) {
+				// A tuple of no fixed items and a rest admits what an array of the rest admits.
+				return shape.rest === null ? z.tuple([]) : z.array(schemaFromShape(shape.rest))
+			}
+			return shape.rest === null ? z.tuple([first, ...rest]) : z.tuple([first, ...rest], schemaFromShape(shape.rest))
+		}
+		case 'record':
+			return z.record(recordKey(shape.key), schemaFromShape(shape.value))
+		case 'object':
+			return z.strictObject(Object.fromEntries(Object.entries(shape.fields).map(([name, field]) => [name, schemaFromShape(field)])))
+		case 'optional':
+			return z.optional(schemaFromShape(shape.inner))
+		case 'nullable':
+			return z.nullable(schemaFromShape(shape.inner))
+		case 'union':
+			return z.union(shape.options.map(schemaFromShape))
+	}
+}
+
+/** A record's keys are strings: a string, a string literal, an enum or a union of them; any other key admits nothing. */
+function recordKey(shape: SchemaShape): z.ZodType<string, string> {
+	switch (shape.type) {
+		case 'string':
+			return stringSchema(shape)
+		case 'enum': {
+			const [first, ...rest] = shape.values
+			return first === undefined ? z.never() : z.enum([first, ...rest])
+		}
+		case 'literal':
+			return typeof shape.value === 'string' ? z.literal(shape.value) : z.never()
+		case 'union':
+			return z.union(shape.options.map(recordKey))
+		default:
+			return z.never()
+	}
+}
+
+function stringSchema(shape: StringShape): z.ZodType<string, string> {
+	let schema: z.ZodString | z.ZodStringFormat = formatSchema(shape.format)
+	if (shape.minLength !== null) {
+		schema = schema.min(shape.minLength)
+	}
+	if (shape.maxLength !== null) {
+		schema = schema.max(shape.maxLength)
+	}
+	if (shape.pattern !== null) {
+		schema = schema.regex(new RegExp(shape.pattern))
+	}
+	if (shape.startsWith !== null) {
+		schema = schema.startsWith(shape.startsWith)
+	}
+	if (shape.endsWith !== null) {
+		schema = schema.endsWith(shape.endsWith)
+	}
+	return shape.includes === null ? schema : schema.includes(shape.includes)
+}
+
+function formatSchema(format: StringShape['format']): z.ZodString | z.ZodStringFormat {
+	switch (format) {
+		case null:
+			return z.string()
+		case 'uuid':
+			return z.uuid()
+		case 'email':
+			return z.email()
+		case 'url':
+			return z.url()
+		case 'datetime':
+			return z.iso.datetime()
+		case 'date':
+			return z.iso.date()
+		case 'time':
+			return z.iso.time()
+		case 'duration':
+			return z.iso.duration()
+	}
+}
+
+/**
+ * The path of a validation issue as far as `shape` declares it: field names the schema names, `[]` for an array item,
+ * a tuple position, `{}` for a record value. Record keys and array indexes come from the value, which another
+ * application wrote, so they never reach a message or a log.
+ */
+export function declaredPath(shape: SchemaShape, path: readonly PropertyKey[]): string {
+	let current: SchemaShape = shape
+	let rendered = ''
+	for (const segment of path) {
+		while (current.type === 'optional' || current.type === 'nullable') {
+			current = current.inner
+		}
+		if (current.type === 'object' && typeof segment === 'string' && Object.hasOwn(current.fields, segment)) {
+			rendered += rendered === '' ? segment : `.${segment}`
+			current = current.fields[segment] ?? current
+		} else if (current.type === 'array') {
+			rendered += '[]'
+			current = current.items
+		} else if (current.type === 'tuple' && typeof segment === 'number' && segment < current.items.length) {
+			rendered += `[${segment}]`
+			current = current.items[segment] ?? current
+		} else if (current.type === 'tuple' && current.rest !== null) {
+			rendered += '[]'
+			current = current.rest
+		} else if (current.type === 'record') {
+			rendered += '{}'
+			current = current.value
+		} else {
+			break
+		}
+	}
+	return rendered === '' ? '(root)' : rendered
+}