@fabrika/provider-zerops 0.0.10 → 0.0.13

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/provider-zerops",
-	"version": "0.0.10",
+	"version": "0.0.13",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -32,9 +32,9 @@
 		"gen:schema": "bun scripts/generate-zerops-types.ts"
 	},
 	"dependencies": {
-		"@fabrika/auth": "^0.0.10",
-		"@fabrika/auth-core": "^0.0.10",
-		"@fabrika/provider-contract": "^0.0.10",
-		"@fabrika/proxy-contract": "^0.0.10"
+		"@fabrika/auth": "^0.0.13",
+		"@fabrika/auth-core": "^0.0.13",
+		"@fabrika/provider-contract": "^0.0.13",
+		"@fabrika/proxy-contract": "^0.0.13"
 	}
 }

package/src/api.ts

@@ -32,6 +32,15 @@ export type ZeropsAppVersionStatus =
 	| 'BACKUP'
 	| 'CANCELLED'
 
+/**
+ * `sensitive` on every user-data WRITE, create and update alike. Required by the platform — omitting it answers
+ * `400 invalidUserInput` with `{"sensitive":["field is required"]}` (measured live, 2026-08-18) — and
+ * `true` because most of what fabrika writes is a credential. It costs nothing to read: a sensitive
+ * variable's `content` still comes back verbatim from `GET /service-stack/{id}/env`, also measured, so the
+ * compare-before-write both `platform deploy` and the create-only credential slots depend on still works.
+ */
+const SENSITIVE_USER_DATA = true
+
 /** The one status that means "this version is live". */
 export const ZEROPS_ACTIVE: ZeropsAppVersionStatus = 'ACTIVE'
 
@@ -437,6 +446,12 @@ export interface ZeropsApi {
 	listProjectServices(input: { projectId: string; signal: AbortSignal }): Promise<ZeropsService[]>
 
 	// ── user-data: SERVICE-level environment variables (ADR-0004) ─────────────────
+	//
+	// EVERY WRITE HERE IS ASYNCHRONOUS. Create, replace and delete each answer with a PENDING
+	// `stack.updateUserData` process rather than the record, and while one is running the platform
+	// refuses the next operation on that service with `400 userDataSyncRunning`. So all three wait for
+	// their own process before returning: a caller that writes a variable and then builds — which is
+	// what every deploy does — must not have to know that.
 
 	/**
 	 * Every environment variable of ONE service, each with the record id `deleteServiceEnv` takes.
@@ -497,9 +512,14 @@ export interface ZeropsApi {
 	 * `compile.ts` writes `envIsolation` instead of inheriting it: a security-relevant field that never
 	 * reaches the wire is a field nobody can review.
 	 *
-	 * NOT EXPOSED, deliberately: `canCreateProjects` — a token that creates projects receives `OWNER` on
-	 * what it creates, which is exactly the scope this call exists to avoid — and `canViewFinances` /
-	 * `canEditFinances`. All three default to `false`, and fabrika has no use for any of them.
+	 * `canCreateProjects` IS EXPOSED, because a control plane that provisions app namespaces cannot work
+	 * without it: every namespace preset creates a project, and `POST /client/{id}/project/import` answers
+	 * `403 insufficientPermissions` to a token without the flag (measured live, 2026-08-18; ADR-0034).
+	 * The cost is real and bounded — the token receives `OWNER` on what it creates, and nothing else:
+	 * `roleCode` stays `NO_ACCESS`, so a project it never created and was never granted stays unreachable.
+	 *
+	 * NOT EXPOSED, deliberately: `canViewFinances` / `canEditFinances`. Both default to `false`, and
+	 * fabrika has no use for either.
 	 *
 	 * UNVERIFIED BEHAVIOUR: EVERYTHING AT RUNTIME. No token has ever been minted against a real account —
 	 * doing so is a mutation, not an inspection — so the shapes below are the published document's and the
@@ -517,6 +537,8 @@ export interface ZeropsApi {
 		projects: readonly { projectId: string; roleCode: ZeropsRoleCode }[]
 		/** The client-wide role. Defaults to `NO_ACCESS`, which is the entire point of a scoped token. */
 		roleCode?: ZeropsRoleCode
+		/** Let the token create projects, which it then OWNS. Required to provision app namespaces (ADR-0034). */
+		canCreateProjects?: boolean
 		signal: AbortSignal
 	}): Promise<ZeropsIntegrationToken>
 
@@ -560,6 +582,8 @@ export interface ZeropsApiOptions {
 	/** Override for a different region's API host. */
 	baseUrl?: string
 	fetchImpl?: FetchLike
+	/** How the user-data writes wait for their platform process. Tests pass a sleeper that does not sleep. */
+	sleep?: Sleeper
 }
 
 /** Read a property off an unknown value without asserting anything about the value's shape. */
@@ -781,10 +805,29 @@ const apiError = (label: string, status: number, body: unknown, redactDetail: bo
 	return new ZeropsApiError(`zerops: ${label} failed (${status})${detail === '' ? '' : ` — ${detail.slice(0, 300)}`}`, status, code)
 }
 
+const timerSleep: Sleeper = (ms, signal) =>
+	new Promise<void>((resolve) => {
+		if (signal.aborted) {
+			resolve()
+			return
+		}
+		const timer = setTimeout(() => {
+			signal.removeEventListener('abort', onAbort)
+			resolve()
+		}, ms)
+		const onAbort = (): void => {
+			clearTimeout(timer)
+			resolve()
+		}
+		signal.addEventListener('abort', onAbort, { once: true })
+	})
+
 /** Build the real client. Every request carries the bearer and the run's signal. */
 export const createZeropsApi = (options: ZeropsApiOptions): ZeropsApi => {
 	const base = (options.baseUrl ?? ZEROPS_API_BASE).replace(/\/+$/, '')
 	const doFetch = options.fetchImpl ?? fetch
+	// Its own, rather than `collaborators`' — that module imports this one, so taking the value back would close a cycle.
+	const sleep = options.sleep ?? timerSleep
 	const abortError = (): DOMException => new DOMException('The operation was aborted', 'AbortError')
 	const isAbortError = (error: unknown): boolean => error instanceof Error && error.name === 'AbortError'
 	const SERVICE_ENV_RESPONSE_MAX_BYTES = 8 * 1024 * 1024
@@ -959,6 +1002,30 @@ export const createZeropsApi = (options: ZeropsApiOptions): ZeropsApi => {
 		return items.map(readServiceEnv)
 	}
 
+	const getProcess: ZeropsApi['getProcess'] = async ({ processId, signal }) =>
+		readProcess(await request('get process', 'GET', `/process/${processId}`, { signal }))
+
+	/**
+	 * Wait out the `stack.updateUserData` process every user-data write answers with.
+	 *
+	 * While one runs the platform refuses the NEXT operation on that service with `400
+	 * userDataSyncRunning` — which is how a deploy that wrote an app's environment and then asked for a
+	 * build failed, one second before the sync it had started finished. Measured live: PENDING → RUNNING →
+	 * FINISHED in about three seconds, on a deployed service and on one that has never had code alike.
+	 *
+	 * The response is recognised by `actionName`, not by having an `id`: a user-data RECORD carries an id
+	 * too, and polling `/process/{recordId}` would hang instead of failing. An unrecognised response is
+	 * left alone — nothing then says the write is still settling.
+	 */
+	const awaitUserDataSync = async (payload: unknown, label: string, signal: AbortSignal): Promise<void> => {
+		const processId = str(payload, 'id')
+		const action = str(payload, 'actionName')
+		if (processId === undefined || processId.trim() === '' || action === undefined || action.trim() === '') {
+			return
+		}
+		await waitForProcess({ api: { getProcess }, processId, sleep, signal, label })
+	}
+
 	return {
 		importServices: async ({ projectId, yaml, signal }) =>
 			readImportResult(await request('service-stack import', 'POST', `/project/${projectId}/service-stack/import`, { body: { yaml }, signal })),
@@ -1001,10 +1068,13 @@ export const createZeropsApi = (options: ZeropsApiOptions): ZeropsApi => {
 
 		buildAndDeployAppVersion: async ({ appVersionId, zeropsYaml, zeropsYamlSetup, signal }) => {
 			const body = zeropsYamlSetup === undefined ? { zeropsYaml } : { zeropsYaml, zeropsYamlSetup }
+			// `redactDetail`, not `omitErrorResponseDetails`: this request body is the app's COMMITTED
+			// descriptor and this response carries no upload URL, so there is nothing here to protect by
+			// dropping the code as well — and a bare `(400)` is what made `userDataSyncRunning` cost a day.
 			const payload = await request('build and deploy app-version', 'PUT', `/app-version/${appVersionId}/build-and-deploy`, {
 				body,
 				signal,
-				omitErrorResponseDetails: true,
+				redactDetail: true,
 			})
 			const processId = requiredString(payload, 'id', 'build and deploy app-version')
 			const responseAppVersionId = str(prop(payload, 'appVersion'), 'id')
@@ -1041,7 +1111,7 @@ export const createZeropsApi = (options: ZeropsApiOptions): ZeropsApi => {
 			await request('cancel-build', 'PUT', `/app-version/${appVersionId}/cancel-build`, { signal })
 		},
 
-		getProcess: async ({ processId, signal }) => readProcess(await request('get process', 'GET', `/process/${processId}`, { signal })),
+		getProcess,
 
 		enableSubdomainAccess: async ({ serviceId, signal }) => {
 			// No body: the operation takes none, and sending one would add a content-type the platform did not ask for.
@@ -1085,9 +1155,10 @@ export const createZeropsApi = (options: ZeropsApiOptions): ZeropsApi => {
 		listServiceEnv,
 
 		createServiceEnv: async ({ serviceId, key, value, signal }) => {
+			let started: unknown
 			try {
-				await request('create-only service env', 'POST', `/service-stack/${serviceId}/user-data`, {
-					body: { key, content: value },
+				started = await request('create-only service env', 'POST', `/service-stack/${serviceId}/user-data`, {
+					body: { key, content: value, sensitive: SENSITIVE_USER_DATA },
 					signal,
 					omitErrorResponseDetails: true,
 				})
@@ -1095,16 +1166,19 @@ export const createZeropsApi = (options: ZeropsApiOptions): ZeropsApi => {
 				if (error instanceof Error && error.name === 'AbortError') throw error
 				throw new Error('zerops: create-only service env failed')
 			}
+			await awaitUserDataSync(started, `the user-data sync on service ${serviceId}`, signal)
 		},
 
 		putServiceEnv: async ({ serviceId, key, value, signal }) => {
+			const label = `the user-data sync on service ${serviceId}`
 			// `redactDetail` on both writes: this is the one place a secret VALUE is in the request body.
 			try {
-				await request('create service env', 'POST', `/service-stack/${serviceId}/user-data`, {
-					body: { key, content: value },
+				const created = await request('create service env', 'POST', `/service-stack/${serviceId}/user-data`, {
+					body: { key, content: value, sensitive: SENSITIVE_USER_DATA },
 					signal,
 					redactDetail: true,
 				})
+				await awaitUserDataSync(created, label, signal)
 				return
 			} catch (error) {
 				if (!(error instanceof ZeropsApiError) || error.code !== USER_DATA_DUPLICATE_KEY) {
@@ -1121,17 +1195,23 @@ export const createZeropsApi = (options: ZeropsApiOptions): ZeropsApi => {
 					`zerops: service ${serviceId} already defines \`${key}\` outside the environment API — it cannot be written`,
 				)
 			}
-			await request('update service env', 'PUT', `/user-data/${existing.id}`, { body: { key, content: value }, signal, redactDetail: true })
+			const updated = await request('update service env', 'PUT', `/user-data/${existing.id}`, {
+				body: { key, content: value, sensitive: SENSITIVE_USER_DATA },
+				signal,
+				redactDetail: true,
+			})
+			await awaitUserDataSync(updated, label, signal)
 		},
 
 		deleteServiceEnv: async ({ envId, signal }) => {
-			await request('delete service env', 'DELETE', `/user-data/${envId}`, { signal })
+			const deleted = await request('delete service env', 'DELETE', `/user-data/${envId}`, { signal })
+			await awaitUserDataSync(deleted, `the user-data sync for record ${envId}`, signal)
 		},
 
 		getProjectEnv: async ({ projectEnvId, signal }) =>
 			readServiceEnv(await request('get project env', 'GET', `/project-env/${projectEnvId}`, { signal })),
 
-		createIntegrationToken: async ({ clientId, name, projects, roleCode, signal }) =>
+		createIntegrationToken: async ({ clientId, name, projects, roleCode, canCreateProjects, signal }) =>
 			// `redactDetail`: unlike every other write here the SECRET is in the RESPONSE, not the request, so
 			// this is the one error envelope that could quote a minted token back at us.
 			readIntegrationToken(
@@ -1139,6 +1219,9 @@ export const createZeropsApi = (options: ZeropsApiOptions): ZeropsApi => {
 					body: {
 						name,
 						roleCode: roleCode ?? 'NO_ACCESS',
+						// Always sent, like `roleCode`: a security-relevant field that never reaches the wire is a
+						// field nobody can review.
+						canCreateProjects: canCreateProjects ?? false,
 						projects: projects.map((grant) => ({ projectId: grant.projectId, roleCode: grant.roleCode })),
 					},
 					signal,

package/src/control.ts

@@ -92,6 +92,8 @@ export interface ZeropsBeforeDeployInput {
 	readonly target: ZeropsStoredTarget & {
 		readonly projectId: string
 		readonly proxyServiceId: string
+		/** The namespace proxy has no Git integration, so its pipeline must be told what to build. */
+		readonly proxyBuildFromGit: string
 	}
 	readonly artifact: FabrikaManifest
 	readonly api: ZeropsApi
@@ -175,7 +177,7 @@ const decodeNamespace = (
 const resolvedEnvironment = (
 	environment: ProviderEnvironment,
 	options: { requireReady: boolean },
-): DecodedZeropsEnvironment & { projectId: string; proxyServiceId?: string } => {
+): DecodedZeropsEnvironment & { projectId: string; proxyServiceId?: string; proxyBuildFromGit?: string } => {
 	const decoded = decodeEnvironment(environment)
 	const projectId = decoded.namespaceTarget.projectId
 	if (projectId === undefined) {
@@ -188,10 +190,15 @@ const resolvedEnvironment = (
 	if (options.requireReady && proxyServiceId === undefined) {
 		throw new Error(`Zerops deployment namespace \`${decoded.namespace.id}\` has no proxy service id`)
 	}
+	const proxyBuildFromGit = decoded.namespaceTarget.proxyBuildFromGit
+	if (options.requireReady && proxyBuildFromGit === undefined) {
+		throw new Error(`Zerops deployment namespace \`${decoded.namespace.id}\` has no proxy build source`)
+	}
 	return {
 		...decoded,
 		projectId,
 		...(proxyServiceId === undefined ? {} : { proxyServiceId }),
+		...(proxyBuildFromGit === undefined ? {} : { proxyBuildFromGit }),
 	}
 }
 
@@ -443,6 +450,10 @@ export const createZeropsControlProvider = (options: ZeropsControlProviderOption
 			if (proxyServiceId === undefined) {
 				throw new Error(`Zerops deployment namespace \`${placement.namespace.id}\` has no proxy service id`)
 			}
+			const proxyBuildFromGit = placement.proxyBuildFromGit
+			if (proxyBuildFromGit === undefined) {
+				throw new Error(`Zerops deployment namespace \`${placement.namespace.id}\` has no proxy build source`)
+			}
 			const artifact = decodeEnvelope('artifact', registration.environment.artifact, zeropsArtifactCodec)
 			await verifyZeropsArtifactSourceDescriptor(artifact.target.sourceDescriptor)
 			let source: ZeropsRuntimeTarget['source']
@@ -468,6 +479,7 @@ export const createZeropsControlProvider = (options: ZeropsControlProviderOption
 						serviceId: placement.target.serviceId,
 						projectId: placement.projectId,
 						proxyServiceId,
+						proxyBuildFromGit,
 					},
 					artifact,
 					api,

package/src/manifest.ts

@@ -17,7 +17,7 @@ const SHA256_PATTERN = /^[0-9a-f]{64}$/
  * asserts the two never diverge.
  */
 const SHARED_POSTGRES_CONNECTION_STRING: ZeropsSharedPostgresBinding['connectionString'] =
-	'${postgres_connectionString}/${postgres_dbName}?sslmode=require'
+	'${postgres_connectionTlsString}/${postgres_dbName}?sslmode=require'
 
 export interface FabrikaImportDocument {
 	readonly project?: { readonly [key: string]: JsonValue }

package/src/namespace.ts

@@ -34,21 +34,24 @@ export const ZEROPS_NAMESPACE_POSTGRES_HOSTNAME = 'postgres'
 export const ZEROPS_NAMESPACE_IAM_URL_VARIABLE = 'FABRIKA_IAM_URL'
 export const ZEROPS_NAMESPACE_IAM_KEY_VARIABLE = 'FABRIKA_IAM_KEY'
 /**
- * How an app reaches the namespace-owned PostgreSQL service — database and TLS mode NAMED, not defaulted.
+ * How an app reaches the namespace-owned PostgreSQL service — port, database and TLS mode NAMED, not
+ * defaulted. Every part settled against a live account, none of it safe to infer:
  *
- * Three facts settled against a live account, none of them safe to infer:
- *
- *   • `${x_connectionString}` is `postgresql://${user}:${password}@${hostname}:${port}` — no database
- *     path. With none, the libpq/postgres.js convention falls back to the USER name.
+ *   • `${x_connectionTlsString}` is `postgresql://${user}:${password}@${hostname}:${portTls}` — no
+ *     database path. With none, the libpq/postgres.js convention falls back to the USER name.
  *   • `dbName` and `user` are both literally `db` on EVERY PostgreSQL service, whatever its hostname
  *     (checked on a service named `wu2db`). So the fallback lands right today — by construction rather
  *     than by luck, but still by a rule nobody wrote down. `/${x_dbName}` says it out loud.
- *   • Port 5432 speaks TLS. `sslmode=require` connects with `pg_stat_ssl.ssl = true`; `sslmode=disable`
- *     connects in the clear. `verify-full` fails (`self signed certificate`), so `require` is the
- *     strongest mode available and the one worth pinning — the alternative is whatever the driver
- *     happens to default to.
+ *   • THE TLS PORT, NOT THE DIRECT ONE, and this is the one that changed. `postgresql:single@18`
+ *     speaks TLS on both; `postgresql:ha@18` speaks it ONLY on `portTls` and answers `sslmode=require`
+ *     on the direct port with "Server does not support SSL". A namespace picks `ha` for `prod` and
+ *     `single` everywhere else, so a DSN naming the direct port is one preset away from failing.
+ *   • `portTls` preserves SESSION state on both — same backend pid across statements, `SET SESSION`
+ *     kept, advisory lock held and visible — so the migration runner's session-level lock is safe
+ *     there. It is a TLS endpoint, not the transaction pool the port number suggests.
+ *   • `verify-full` fails (`self signed certificate`), so `require` is the strongest mode available.
  */
-export const ZEROPS_SHARED_POSTGRES_CONNECTION_STRING = '${postgres_connectionString}/${postgres_dbName}?sslmode=require'
+export const ZEROPS_SHARED_POSTGRES_CONNECTION_STRING = '${postgres_connectionTlsString}/${postgres_dbName}?sslmode=require'
 
 const PROXY_TYPE = 'alpine@3.21'
 const EMPTY_PROXY_MANIFEST = encodeProxyManifestJson({ apps: [] })

package/src/provider.ts

@@ -11,6 +11,7 @@
 
 import { createProvider, type ProviderDeploySession, type ProviderModule, type TypedProviderRun } from '@fabrika/provider-contract'
 import {
+	waitForProcess,
 	ZEROPS_ACTIVE,
 	ZEROPS_PROCESS_FINISHED,
 	ZEROPS_PROCESS_TERMINAL,
@@ -273,6 +274,17 @@ const runStep = async (spec: ZeropsJobSpec, env: StepEnv): Promise<void> => {
 			// `override: true` on every service (written by the compiler) is what makes re-applying safe.
 			const result = await zerops.api.importServices({ projectId: target.projectId, yaml: compiled.yaml, signal })
 			log(`  imported: ${result.services.map((service) => `${service.name} (${service.id})`).join(', ') || '(none reported)'}`)
+			// An import ANSWERS before its services exist. Triggering a pipeline on a service Zerops is
+			// still creating answers 400 `projectImportInvalidParameter`, which is what the first deploy
+			// into a fresh namespace hit; a re-apply onto services that already exist reports none.
+			const pending = result.services.flatMap((service) => service.processes.map((process) => ({ service: service.name, id: process.id })))
+			for (const process of pending) {
+				assertRunning(signal)
+				await waitForProcess({ api: zerops.api, processId: process.id, sleep: zerops.sleep, signal, label: `the ${process.service} import` })
+			}
+			if (pending.length > 0) {
+				log(`  awaited ${pending.length} import process(es)`)
+			}
 			return
 		}
 

package/src/types.ts

@@ -95,7 +95,7 @@ export interface ZeropsProxySpec {
 export interface ZeropsSharedPostgresBinding {
 	readonly resourceKey: 'service:postgres'
 	readonly hostname: 'postgres'
-	readonly connectionString: '${postgres_connectionString}/${postgres_dbName}?sslmode=require'
+	readonly connectionString: '${postgres_connectionTlsString}/${postgres_dbName}?sslmode=require'
 }
 
 export type ZeropsNamespaceResourceRequirement = ZeropsSharedPostgresBinding