@fabrika/builder 0.2.0 → 0.3.1

package/decisions/technologies/zerops-fabrika-auth.md

@@ -0,0 +1,53 @@
+---
+id: zerops-fabrika-auth
+kind: technology
+title: Fabrika IAM with proxy-only enforcement on Zerops
+slot: authz
+provides: [authentication, authorization, proxy-enforcement]
+requires: [zerops-platform]
+recommends: []
+conflicts: [propustka, cloudflare-access, auth-password-kv]
+npm: ["@fabrika/auth@^0.0.4", "@fabrika/auth-core@^0.0.4"]
+status: wip
+sources:
+  - where: "packages/auth/CLAUDE.md + src/index.ts + src/iam.ts in fabrika-platform"
+    read: "Verify-only SDK, real IAM requirements, negative versus unavailable results."
+  - where: "examples/zerops-app/fabrika.gates.ts + fabrika.schema.ts + src/authz.ts in fabrika-platform"
+    read: "Proxy gate declarations, app vocabulary and the example's direct JWKS verification."
+  - where: "docs/decisions/0022-the-proxy-is-the-only-enforcement-point.md + 0023-one-session-per-host.md in fabrika-platform"
+    read: "Single gate evaluator, per-host session handoff and application-owned object authorization."
+---
+
+# Fabrika IAM with proxy-only enforcement
+
+Declare the application's `AppSchema` vocabulary and ordered `AppGates` in source.
+Attach the gates to `target.proxy` in `fabrika.config.ts`. Control reconciles the
+schema and registers deployment return origins; the application does not assert
+its own trusted return origins through its schema.
+
+The proxy alone evaluates gates, handles login and the reserved
+`/__fabrika/auth/callback` route, and injects `X-Fabrika-Token`. App services remain
+private. Never implement another gate evaluator in the app, frontend or Caddy
+route configuration.
+
+The application verifies the injected token's signature, issuer, audience and
+expiry against IAM's JWKS. Prefer the `@fabrika/auth` SDK's `createIam` and
+`authenticate` contract where its IAM binding is available; read the installed
+types when composing the HTTP transport. The public notes example demonstrates
+direct JWKS verification with `@fabrika/auth-core` claim parsing. Neither path
+trusts an unverified header or gives the app a session-to-token exchange.
+
+Keep per-object authorization in feature handlers using the verified context and
+validated object scope (`can`, `requirePermission`, or the example's `Caller`).
+Public-gated routes use an anonymous context with no permissions. Preserve SDK
+failure semantics: a decided invalid credential differs from IAM unavailability,
+which refuses with 503 rather than pretending the credential was checked.
+
+## Local authentication is the same model
+
+Run real IAM and the proxy locally. IAM's own `LOCAL_DEV_LOGIN` mechanism can
+create a real local session; it is not an application dev flag. Restricted-role
+tests need real IAM principals and grants, not the bootstrap admin for every
+scenario. Never synthesize a caller, mint tokens in the app, add `FakeIamClient`,
+or disable gates to make local previews work. Credentials and raw request headers
+must not enter logs or committed fixtures.

package/decisions/technologies/zerops-platform.md

@@ -0,0 +1,64 @@
+---
+id: zerops-platform
+kind: technology
+title: Zerops through the Fabrika provider
+slot: platform
+provides: [platform, private-services, managed-deploy]
+requires: [bun, postgres]
+recommends: []
+conflicts: [cloudflare]
+npm: ["@fabrika/provider-zerops@^0.0.4", "@fabrika/app@^0.0.4"]
+status: wip
+sources:
+  - where: "examples/zerops-app/fabrika.config.ts + zerops.yaml in fabrika-platform"
+    read: "Current defineApp shape, private runtime, database references and repository-root build descriptor."
+  - where: "packages/provider-zerops/src/types.ts + src/index.ts in fabrika-platform"
+    read: "Provider-owned authoring contract and exports; verify installed versions before use."
+  - where: "docs/reference/zerops-platform.md in fabrika-platform"
+    read: "Live-verified routing, PostgreSQL TLS, sizing and probe constraints."
+---
+
+# Zerops through the Fabrika provider
+
+Use this for applications deployed by an existing Fabrika installation. Import
+`defineApp`, `ZeropsResourceContext` and `ZeropsServiceSpec` from
+`@fabrika/provider-zerops`. Keep `fabrika.config.ts` as the app's deploy source of
+truth: stable `id`, `schema`, `pipeline` and `target` with `platform: 'zerops'`.
+
+## Application contract
+
+- Declare services through `target.services(ctx)`. Select the runtime explicitly
+  with `target.deployService` when declaring multiple services. Set
+  `target.zeropsSetup` to the matching setup in repository-root `zerops.yaml`.
+- Declare `target.proxy: { upstream, gates }` with the private runtime address.
+  Set runtime `enableSubdomainAccess: false`; only the namespace proxy has public
+  routing. A custom domain belongs on the proxy, never the app service.
+- Leave project placement to Control's environment/namespace registry. Keep
+  provider tokens and concrete project coordinates out of application source.
+- Use the public example's Bun adapter (`@fabrika/app/bun`) for the long-running
+  Fetch application. Serve built SPA assets from the private application; preserve
+  API errors instead of falling through to `index.html`.
+- Commit `zerops.yaml` and the Bun lockfile at the app repository root. Zerops
+  performs its build; the descriptor declares build/deploy files, start command,
+  ports and probes. Probe durations are Go duration strings bounded to 10s–1h.
+- Run repeatable, concurrency-safe PostgreSQL migrations in `run.initCommands`,
+  which runs on every container start. A readiness check gates deployment;
+  `run.healthCheck` is the separate runtime liveness mechanism.
+
+## Data and configuration
+
+The default public config declares an app-owned PostgreSQL service. A cheap
+namespace can instead supply the typed shared PostgreSQL binding: consult
+`examples/zerops-app/fabrika.cheap.config.ts` and its matching descriptor before
+selecting that variant. Preserve the administrator's namespace assignment.
+
+Use the provider's PostgreSQL TLS reference including the database name and
+`sslmode=require`; do not infer a connection string from a hostname. Service names
+must satisfy `^[a-z0-9]{1,25}$` and references may address only owned services and
+declared namespace resources.
+
+The provider owns isolation fields. Secret values live at service level in Zerops,
+not in config, YAML or project-level environment variables. `pipeline.secrets`
+names requirements; it does not add a deploy-time secret synchronization step.
+Control supplies reserved managed variables such as `FABRIKA_IAM_ISSUER`,
+`FABRIKA_OPERATIONS_DSN` and `FABRIKA_RELEASE`; do not redeclare them.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/builder",
-	"version": "0.2.0",
+	"version": "0.3.1",
 	"type": "module",
 	"description": "Local-first guided application design and agent-assisted implementation.",
 	"license": "MIT",
@@ -16,6 +16,9 @@
 		"index.ts",
 		"cli/src",
 		"daemon/src",
+		"shared/index.ts",
+		"shared/phases.ts",
+		"shared/urls.ts",
 		"ui/dist",
 		"skill",
 		"decisions",
@@ -40,12 +43,17 @@
 		"build": "bun ui/build.ts",
 		"release:prepare": "bun run build",
 		"typecheck": "tsc --noEmit",
-		"test": "bun test --preload ./daemon/test/preload.ts cli/test daemon/test ui/test"
+		"test": "bun test --isolate --preload ./daemon/test/preload.ts cli/test daemon/test ui/test shared"
 	},
 	"dependencies": {
-		"@fabrika/annotations": "^0.2.0",
-		"@fabrika/canvas-kernel": "^0.2.0",
-		"@fabrika/daemon-kit": "^0.2.0",
+		"zod": "^3.25.76",
+		"@fabrika/annotations": "^0.3.1",
+		"@fabrika/app": "^0.3.1",
+		"@fabrika/auth-core": "^0.3.1",
+		"@fabrika/canvas-kernel": "^0.3.1",
+		"@fabrika/control-contract": "^0.3.1",
+		"@fabrika/daemon-kit": "^0.3.1",
+		"@fabrika/provider-zerops": "^0.3.1",
 		"preact": "^10.25.0"
 	}
 }

package/shared/index.ts

@@ -0,0 +1,365 @@
+import { type BuilderConnectionReceiptDto, builderConnectionReceiptSchema } from '@fabrika/control-contract'
+import { z } from 'zod'
+import { PHASE_IDS } from './phases'
+import { parseBuilderOrigin, parseBuilderPreviewUrl } from './urls'
+
+export { parseBuilderOrigin, parseBuilderPreviewUrl } from './urls'
+
+export interface BuilderProjectConnection {
+	controlOrigin: string
+	iamIssuer: string
+	receipt: BuilderConnectionReceiptDto
+}
+
+export interface BuilderProjectConfig {
+	profile: string
+	sessionId: string
+	createdAt: string
+	connection?: BuilderProjectConnection
+	previewUrl?: string
+}
+
+export type BuilderPairingState =
+	// Only the browser approval proof belongs in this URL's fragment; redemption credentials stay daemon-local.
+	| { status: 'pending'; authorizationUrl: string; expiresAt: number }
+	| { status: 'approved' }
+	| { status: 'failed'; message: string }
+	| { status: 'expired' }
+	| { status: 'cancelled' }
+	| { status: 'recovery_required'; message: string }
+	| { status: 'connected' }
+
+export interface BuilderDeploymentState {
+	status: 'preparing' | 'pending' | 'running' | 'succeeded' | 'failed' | 'cancelled'
+	runId: string | null
+	commitSha: string | null
+	message: string | null
+	appUrl: string | null
+	consoleUrl: string | null
+}
+
+export interface BuilderPlatformStatus {
+	sessionId: string
+	projectRoot: string
+	connection: BuilderProjectConnection | null
+	credential: { available: boolean; expiresAt: number | null }
+	pairing: BuilderPairingState | null
+	previewUrl: string | null
+	deployment: BuilderDeploymentState | null
+}
+
+export interface RegisterProjectInput {
+	projectRoot: string
+}
+
+export interface ConnectProjectInput {
+	controlOrigin: string
+}
+
+export interface PreviewProjectInput {
+	url: string | null
+}
+
+export interface BuilderErrorResponse {
+	error: { code: string; message: string }
+}
+
+// These legacy daemon projections deliberately recover malformed optional fields.
+const wireNumberSchema = z.union([z.number(), z.nan()])
+const optionalTextSchema = z.string().optional().catch(undefined)
+const phaseIdSchema = z.enum(PHASE_IDS)
+export const phaseStateSchema = z.object({
+	current: phaseIdSchema,
+	index: wireNumberSchema,
+	completed: z.array(phaseIdSchema),
+	reads: z.array(z.string()),
+	produces: z.array(z.string()),
+	gate: z.boolean(),
+	satisfied: z.boolean(),
+})
+export const uiPhaseStateSchema = phaseStateSchema.extend({ gateName: z.string().nullable().optional().catch(undefined) })
+	.transform(({ gateName, ...state }) => ({ ...state, ...(gateName === undefined ? {} : { gateName }) }))
+export const healthInfoSchema = z.object({
+	ok: z.literal(true),
+	version: optionalTextSchema,
+	pid: wireNumberSchema.optional().catch(undefined),
+	dataDir: optionalTextSchema,
+	sessionsDir: z.string(),
+	sessions: z.union([wireNumberSchema, z.array(z.string())]).optional().catch(undefined),
+}).transform(({ ok, version, pid, dataDir, sessionsDir, sessions }) => ({
+	ok,
+	...(version === undefined ? {} : { version }),
+	...(pid === undefined ? {} : { pid }),
+	...(dataDir === undefined ? {} : { dataDir }),
+	sessionsDir,
+	...(sessions === undefined ? {} : { sessions }),
+}))
+export const uiHealthSchema = z.object({
+	ok: z.literal(true),
+	version: optionalTextSchema,
+	sessions: z.array(z.string()).optional().catch(undefined),
+})
+	.transform(({ ok, version, sessions }) => ({ ok, ...(version === undefined ? {} : { version }), ...(sessions === undefined ? {} : { sessions }) }))
+export const activeDaemonSchema = z.object({ ok: z.literal(true), sessionsDir: z.string() })
+export const builderPlatformErrorSchema = z.object({ error: z.object({ code: z.literal('builder_platform'), message: z.string().max(1000) }) })
+export const planResultSchema = z.object({
+	ok: z.boolean(),
+	browserUrl: optionalTextSchema,
+	revision: wireNumberSchema.optional().catch(undefined),
+	isNew: z.boolean().optional().catch(undefined),
+	canvasFiles: z.array(z.string()).optional().catch(undefined),
+	gate: optionalTextSchema,
+	error: optionalTextSchema,
+	errors: z.record(z.string()).optional().catch(undefined),
+}).transform(({ ok, browserUrl, revision, isNew, canvasFiles, gate, error, errors }) => ({
+	ok,
+	...(browserUrl === undefined ? {} : { browserUrl }),
+	...(revision === undefined ? {} : { revision }),
+	...(isNew === undefined ? {} : { isNew }),
+	...(canvasFiles === undefined ? {} : { canvasFiles }),
+	...(gate === undefined ? {} : { gate }),
+	...(error === undefined ? {} : { error }),
+	...(errors === undefined ? {} : { errors }),
+}))
+export const buildEventSchema = z.object({
+	status: z.enum(['queued', 'running', 'passed', 'failed', 'blocked', 'info']),
+	issue: optionalTextSchema,
+	message: optionalTextSchema,
+	at: optionalTextSchema,
+	data: z.record(z.unknown()).optional().catch(undefined),
+}).transform(({ status, issue, message, at, data }) => ({
+	status,
+	...(issue === undefined ? {} : { issue }),
+	...(message === undefined ? {} : { message }),
+	...(at === undefined ? {} : { at }),
+	...(data === undefined ? {} : { data }),
+}))
+export const planInputSchema = z.object({
+	view: optionalTextSchema,
+	directory: optionalTextSchema,
+	projectRoot: optionalTextSchema,
+	gate: optionalTextSchema,
+	label: optionalTextSchema,
+	response: optionalTextSchema,
+})
+export const feedbackTextSchema = z.object({ feedback: z.string().catch('') })
+export const consumedFeedbackSchema = feedbackTextSchema.extend({ found: z.literal(true) })
+export const submitFeedbackSchema = feedbackTextSchema.extend({ type: z.literal('submit') })
+export const feedbackRevisionSchema = z.object({
+	revision: wireNumberSchema,
+	hasFeedback: z.unknown().transform(value => value === true),
+	feedbackConsumed: z.unknown().transform(value => value === true),
+})
+export const feedbackMetaSchema = z.object({
+	revisions: z.array(feedbackRevisionSchema.nullable().catch(null)).transform(items => items.filter(item => item !== null)),
+})
+export const canvasFileSchema = z.union([
+	z.string().transform(filename => ({ filename })),
+	z.object({
+		filename: z.string(),
+		label: optionalTextSchema,
+		diffStats: z.object({ added: wireNumberSchema, removed: wireNumberSchema }).optional().catch(undefined),
+	}).transform(({ filename, label, diffStats }) => ({
+		filename,
+		...(label === undefined ? {} : { label }),
+		...(diffStats === undefined ? {} : { diffStats }),
+	})),
+]).refine(value => value.filename.length > 0)
+export const canvasFilesSchema = z.array(canvasFileSchema.nullable().catch(null))
+	.transform(items => items.filter(item => item !== null)).catch([])
+const canvasScopeSchema = z.discriminatedUnion('kind', [
+	z.object({ kind: z.literal('directory') }),
+	z.object({ kind: z.literal('view'), filename: z.string() }),
+])
+export const revisionMetaSchema = feedbackRevisionSchema.extend({
+	label: z.string().nullable().catch(null),
+	canvasFiles: canvasFilesSchema,
+	createdAt: optionalTextSchema,
+	canvasScope: canvasScopeSchema.optional().catch(undefined),
+}).transform(({ createdAt, canvasScope, ...revision }) => ({
+	...revision,
+	...(createdAt === undefined ? {} : { createdAt }),
+	...(canvasScope === undefined ? {} : { canvasScope }),
+})).refine(value => value.revision > 0)
+export const sessionMetaSchema = z.object({
+	projectRoot: optionalTextSchema,
+	label: optionalTextSchema,
+	gate: z.string().nullable().catch(null),
+	currentRevision: wireNumberSchema.catch(0),
+	canvasFiles: canvasFilesSchema,
+	revisions: z.array(revisionMetaSchema.nullable().catch(null)).transform(items => items.filter(item => item !== null)).catch([]),
+}).transform(({ projectRoot, label, ...meta }) => ({
+	...meta,
+	...(projectRoot === undefined ? {} : { projectRoot }),
+	...(label === undefined ? {} : { label }),
+}))
+export const sessionSummarySchema = z.object({ id: z.string(), label: optionalTextSchema })
+	.transform(({ id, label }) => ({ id, ...(label === undefined ? {} : { label }) }))
+export const sessionsSchema = z.array(sessionSummarySchema.nullable().catch(null)).transform(items => items.filter(item => item !== null)).catch([])
+export const skeletonSchema = z.object({
+	file: z.string(),
+	name: z.string(),
+	seeds: z.array(z.string()),
+	roles: z.array(z.string()),
+	steps: wireNumberSchema,
+	invariants: wireNumberSchema,
+	pending: wireNumberSchema,
+	url: optionalTextSchema,
+	feature: optionalTextSchema,
+}).transform(({ url, feature, ...skeleton }) => ({
+	...skeleton,
+	...(url === undefined ? {} : { url }),
+	...(feature === undefined ? {} : { feature }),
+}))
+export const skeletonsSchema = z.object({
+	skeletons: z.array(skeletonSchema.nullable().catch(null)).transform(items => items.filter(item => item !== null)),
+})
+export const artifactResponseSchema = z.object({ content: z.string() })
+export const responsesEnvelopeSchema = z.object({ responses: z.unknown() })
+export const wsMessageSchema = z.discriminatedUnion('type', [
+	z.object({
+		type: z.literal('plan-updated'),
+		currentRevision: wireNumberSchema,
+		canvasFiles: z.array(z.unknown()).transform(value => canvasFilesSchema.parse(value)).optional().catch(undefined),
+		gate: z.string().nullable().optional().catch(undefined),
+	}),
+	z.object({ type: z.literal('revision-updated'), currentRevision: wireNumberSchema }),
+	z.object({ type: z.literal('watcher-status'), watching: z.boolean() }),
+	z.object({ type: z.literal('phase-updated') }),
+	z.object({ type: z.literal('submit-ack'), revision: wireNumberSchema }),
+]).transform(message => {
+	if (message.type !== 'plan-updated') return message
+	const { canvasFiles, gate, ...rest } = message
+	return { ...rest, ...(canvasFiles === undefined ? {} : { canvasFiles }), ...(gate === undefined ? {} : { gate }) }
+})
+
+const nonemptyStringSchema = z.string().refine(value => value.trim().length > 0)
+const timestampSchema = z.number().finite().nonnegative()
+const originSchema = z.string().transform((value, ctx) => {
+	try {
+		return parseBuilderOrigin(value)
+	} catch {
+		ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Invalid builder origin' })
+		return z.NEVER
+	}
+})
+const previewUrlSchema = z.string().transform((value, ctx) => {
+	try {
+		return parseBuilderPreviewUrl(value)
+	} catch {
+		ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Invalid preview URL' })
+		return z.NEVER
+	}
+})
+export const builderProjectConnectionSchema = z.object({
+	controlOrigin: originSchema,
+	iamIssuer: originSchema,
+	receipt: builderConnectionReceiptSchema,
+}).strict()
+export const builderProjectConfigSchema = z.object({
+	profile: nonemptyStringSchema,
+	sessionId: nonemptyStringSchema,
+	createdAt: nonemptyStringSchema.refine(value => Number.isFinite(Date.parse(value))),
+	connection: builderProjectConnectionSchema.optional(),
+	previewUrl: previewUrlSchema.optional(),
+}).strict().superRefine((value, ctx) => {
+	for (const key of ['connection', 'previewUrl']) {
+		if (Object.hasOwn(value, key) && Reflect.get(value, key) === undefined) {
+			ctx.addIssue({ code: z.ZodIssueCode.custom, path: [key], message: 'Present field must not be undefined' })
+		}
+	}
+})
+export const builderPairingStateSchema = z.discriminatedUnion('status', [
+	z.object({
+		status: z.literal('pending'),
+		authorizationUrl: previewUrlSchema.refine(value => {
+			try {
+				parseBuilderOrigin(new URL(value).origin)
+				return true
+			} catch {
+				return false
+			}
+		}),
+		expiresAt: timestampSchema,
+	}).strict(),
+	z.object({ status: z.literal('approved') }).strict(),
+	z.object({ status: z.literal('failed'), message: nonemptyStringSchema }).strict(),
+	z.object({ status: z.literal('expired') }).strict(),
+	z.object({ status: z.literal('cancelled') }).strict(),
+	z.object({ status: z.literal('recovery_required'), message: nonemptyStringSchema }).strict(),
+	z.object({ status: z.literal('connected') }).strict(),
+])
+export const builderDeploymentStateSchema = z.object({
+	status: z.enum(['preparing', 'pending', 'running', 'succeeded', 'failed', 'cancelled']),
+	runId: nonemptyStringSchema.nullable(),
+	commitSha: nonemptyStringSchema.nullable(),
+	message: nonemptyStringSchema.nullable(),
+	appUrl: previewUrlSchema.nullable(),
+	consoleUrl: previewUrlSchema.nullable(),
+}).strict()
+export const builderPlatformStatusSchema = z.object({
+	sessionId: nonemptyStringSchema,
+	projectRoot: nonemptyStringSchema,
+	connection: builderProjectConnectionSchema.nullable(),
+	credential: z.object({ available: z.boolean(), expiresAt: timestampSchema.nullable() }).strict(),
+	pairing: builderPairingStateSchema.nullable(),
+	previewUrl: previewUrlSchema.nullable(),
+	deployment: builderDeploymentStateSchema.nullable(),
+}).strict()
+export const registerProjectInputSchema = z.object({ projectRoot: nonemptyStringSchema }).strict()
+export const connectProjectInputSchema = z.object({ controlOrigin: originSchema }).strict()
+export const previewProjectInputSchema = z.object({ url: previewUrlSchema.nullable() }).strict()
+
+export function parseBuilderProjectConnection(value: unknown): BuilderProjectConnection {
+	const result = builderProjectConnectionSchema.safeParse(value)
+	if (!result.success) throw new Error('Invalid project connection')
+	return result.data
+}
+
+export function parseBuilderProjectConfig(value: unknown): BuilderProjectConfig {
+	const result = builderProjectConfigSchema.safeParse(value)
+	if (!result.success) throw new Error('Invalid project config')
+	return result.data
+}
+
+export function parseBuilderPairingState(value: unknown): BuilderPairingState {
+	const result = builderPairingStateSchema.safeParse(value)
+	if (!result.success) throw new Error('Invalid pairing state')
+	return result.data
+}
+
+export function parseBuilderDeploymentState(value: unknown): BuilderDeploymentState {
+	const result = builderDeploymentStateSchema.safeParse(value)
+	if (!result.success) throw new Error('Invalid deployment state')
+	return result.data
+}
+
+export function parseBuilderPlatformStatus(value: unknown): BuilderPlatformStatus {
+	const result = builderPlatformStatusSchema.safeParse(value)
+	if (!result.success) throw new Error('Invalid platform status')
+	return result.data
+}
+
+export function parseRegisterProjectInput(value: unknown): RegisterProjectInput {
+	const result = registerProjectInputSchema.safeParse(value)
+	if (!result.success) throw new Error('Invalid register input')
+	return result.data
+}
+
+export function parseConnectProjectInput(value: unknown): ConnectProjectInput {
+	const result = connectProjectInputSchema.safeParse(value)
+	if (!result.success) throw new Error('Invalid connect input')
+	return result.data
+}
+
+export function parsePreviewProjectInput(value: unknown): PreviewProjectInput {
+	const result = previewProjectInputSchema.safeParse(value)
+	if (!result.success) throw new Error('Invalid preview input')
+	return result.data
+}
+
+export function builderProjectPath(id: string, suffix: 'register' | 'platform' | 'connect' | 'disconnect' | 'deploy' | 'preview'): string {
+	const result = nonemptyStringSchema.safeParse(id)
+	if (!result.success) throw new Error('project id must be a non-empty string')
+	return `/api/project/${encodeURIComponent(result.data)}/${suffix}`
+}