@fabrika/provider-zerops 0.2.0 → 0.3.1

package/src/installation/install-provisioning.ts

@@ -0,0 +1,185 @@
+import { waitForProcess, type ZeropsImportResult, type ZeropsService, type ZeropsServiceStatus } from '../index'
+import { PLATFORM_DEPLOY_ORDER, type PlatformDeployService, readServiceEnv, type ResolvedService } from './deploy'
+import { assertRunning, type InstallCollaborators } from './install-collaborators'
+import { GENERATED_SECRET_KEYS } from './install-environment'
+import { type CompiledDocument, type CompiledTopology, compileTopology, platformTopology } from './topology/topology'
+
+/** The one topology this command installs, so the project document and the services document cannot drift. */
+export const lightTopology = (environment: string): CompiledTopology =>
+	compileTopology(platformTopology({ env: environment, tier: 'light', publicAccess: 'zerops-subdomain' }), environment)
+
+/**
+ * The services-only provisioning document (WU2), compiled from the declaration the committed artifact
+ * is rendered from.
+ *
+ * Not read off disk: `gen:check` already proves
+ * `packages/platform-artifacts/generated/platform-light.services.provision.zerops-import.yaml` is this exact text, and a
+ * value needs no filesystem in a published package.
+ */
+export const provisioningDocument = (environment: string): CompiledDocument => {
+	const document = lightTopology(environment).servicesProvision
+	if (document === undefined) {
+		throw new Error('the light platform topology declares no services-only provisioning document')
+	}
+	return document
+}
+
+/** One service of the provisioning document that the project already has. */
+interface ExistingService {
+	readonly id: string
+	readonly status?: ZeropsServiceStatus
+}
+
+/**
+ * Every service of the provisioning document that the project already has, by hostname.
+ *
+ * The STATUS travels with the id because `NEW` is not a service this command may touch: measured live,
+ * a service holds NO environment at all — not even the platform's generated keys — until it leaves that
+ * state, so both a read and a write against one are meaningless rather than merely early.
+ */
+export const existingServices = (declared: readonly string[], services: readonly ZeropsService[]): Map<string, ExistingService> => {
+	const found = new Map<string, ExistingService>()
+	for (const hostname of declared) {
+		const matches = services.filter((service) => service.name === hostname)
+		if (matches.length > 1) {
+			throw new Error(`Zerops project has ${matches.length} services named \`${hostname}\``)
+		}
+		const match = matches[0]
+		if (match !== undefined && match.id !== '') {
+			found.set(hostname, { id: match.id, ...(match.status === undefined ? {} : { status: match.status }) })
+		}
+	}
+	return found
+}
+
+/**
+ * Refuse a service the platform is still creating.
+ *
+ * Not a wait: this command holds no process id for a service some earlier run imported, and a sleep
+ * would be a guess at a number the platform never promised. The whole light topology settles in about a
+ * minute, so "run it again shortly" is both true and cheap.
+ */
+export const assertNoServiceIsBeingCreated = (existing: ReadonlyMap<string, ExistingService>): void => {
+	const creating = [...existing].filter(([, service]) => service.status === 'NEW').map(([hostname]) => hostname)
+	if (creating.length > 0) {
+		throw new Error(
+			`Zerops is still creating ${creating.join(', ')} — a service reads NEW with no environment at all, so nothing can be `
+				+ 'read from it or written to it yet. The light topology settles in about a minute; run the install again then',
+		)
+	}
+}
+
+/**
+ * Refuse a project that already carries this installation's generated secrets.
+ *
+ * By KEY, never by value. Re-running a bring-up would roll a fresh vault KEK — whose loss is
+ * unrecoverable by design — and fresh signing keys, invalidating every live token, so the safe answer to
+ * "was this already installed?" is to stop and say so. `platform deploy` is the command for an
+ * installation that exists.
+ */
+export const assertNotAlreadyInstalled = async (
+	existing: ReadonlyMap<string, ExistingService>,
+	collaborators: InstallCollaborators,
+): Promise<void> => {
+	const placed: string[] = []
+	for (const hostname of PLATFORM_DEPLOY_ORDER) {
+		const service = existing.get(hostname)
+		if (service === undefined) {
+			continue
+		}
+		const live = await readServiceEnv(service.id, collaborators)
+		for (const key of GENERATED_SECRET_KEYS.get(hostname) ?? []) {
+			if (live.has(key)) {
+				placed.push(`${hostname}.${key}`)
+			}
+		}
+	}
+	if (placed.length > 0) {
+		throw new Error(
+			`this project already holds an installation's generated secrets — ${placed.join(', ')} ${placed.length === 1 ? 'is' : 'are'} already set. `
+				+ '`platform install` is a BRING-UP and would roll a new vault key and new signing keys over them, which is unrecoverable '
+				+ 'for the vault and logs everyone out. If every bootstrap variable was placed, use `fabrika platform deploy --provider=zerops` '
+				+ 'to update or finish deploying the installation; recover FABRIKA_IAM_PROVISIONING_KEY from `iam` or `control` and '
+				+ 'FABRIKA_ZEROPS_ACCESS_TOKEN from `control` in Zerops. Neither deploy nor init completes a partial bootstrap. '
+				+ 'For partial bootstrap, preserve the existing keys and arrange operator-owned recovery, or start a fresh installation in a separate empty project',
+		)
+	}
+}
+
+/**
+ * Import the topology, unless the project already has it.
+ *
+ * Three outcomes, and the middle one is the one that costs something to get wrong: re-applying a
+ * `startWithoutCode: true` document at a service that carries code activates an EMPTY app version and
+ * demotes the running one to `BACKUP` (`docs/reference/zerops-platform.md`). A PARTIAL set is refused
+ * rather than completed, because an import applies as one document and cannot skip the services that
+ * are already there.
+ */
+export const provision = async (
+	projectId: string,
+	document: CompiledDocument,
+	existing: ReadonlyMap<string, ExistingService>,
+	collaborators: InstallCollaborators,
+): Promise<void> => {
+	const { api, log, prompts, sleep, signal } = collaborators
+	const declared = document.document.services.map((service) => service.hostname)
+	if (existing.size === declared.length) {
+		log.info(`all ${declared.length} services already exist — skipping the import, which would activate an empty app version on each`)
+		return
+	}
+	if (existing.size > 0) {
+		const missing = declared.filter((hostname) => !existing.has(hostname))
+		throw new Error(
+			`Zerops project ${projectId} has ${[...existing.keys()].join(', ')} but not ${missing.join(', ')}. An import applies as ONE `
+				+ 'document, so completing it would re-apply `startWithoutCode` at the services that already exist and activate an empty app '
+				+ 'version on each. Create the missing services by hand, or start from an empty project',
+		)
+	}
+	if (!(await prompts.confirm(`Import ${declared.length} services (${declared.join(', ')}) into project ${projectId}?`, true))) {
+		throw new Error('declined: nothing has been created, and re-running the install is safe')
+	}
+	assertRunning(signal)
+	const result: ZeropsImportResult = await api.importServices({ projectId, yaml: document.yaml, signal })
+	const pending = result.services.flatMap((service) => service.processes.map((process) => ({ service: service.name, id: process.id })))
+	log.ok(`imported ${result.services.length} service(s); waiting for ${pending.length} process(es)`)
+	// WAIT BEFORE READING OR WRITING ANYTHING, and this is measured rather than careful.
+	//
+	// `importServices` returns immediately and the services are not usable yet. Live (2026-08-10, a
+	// project created empty): the four runtime services read `status: NEW` with ZERO environment keys the
+	// instant the call returned — not even the platform's own generated ones. The platform then creates
+	// them SEQUENTIALLY in the document's `priority` order, ~15 s apart, and a service gains its ten
+	// generated keys (`zeropsSubdomain` among them) only once it leaves `NEW`. So WU1's "zeropsSubdomain is
+	// present before any deploy" is true, and true only after that transition.
+	//
+	// Waiting on every process id the import handed back is the mechanism; a sleep would be a guess at a
+	// number the platform never promised. `waitForProcess`'s default budget is ~5 minutes per process
+	// against a measured ~60 s for the whole light topology, which is the slack that measurement asks for.
+	for (const process of pending) {
+		await waitForProcess({ api, processId: process.id, sleep, signal, label: `the ${process.service} import` })
+	}
+	log.ok(`every import process finished (${pending.length})`)
+}
+
+/** Resolve the four platform services by hostname, naming the whole set that is missing rather than the first. */
+export const resolvePlatformServices = async (
+	projectId: string,
+	{ api, signal }: InstallCollaborators,
+): Promise<Map<PlatformDeployService, ResolvedService>> => {
+	const services = await api.listProjectServices({ projectId, signal })
+	const resolved = new Map<PlatformDeployService, ResolvedService>()
+	const missing: string[] = []
+	for (const hostname of PLATFORM_DEPLOY_ORDER) {
+		const match = services.find((service) => service.name === hostname)
+		if (match === undefined || match.id === '') {
+			missing.push(hostname)
+			continue
+		}
+		resolved.set(hostname, { hostname, id: match.id })
+	}
+	if (missing.length > 0) {
+		throw new Error(`Zerops project ${projectId} has no ${missing.join(', ')} service after provisioning`)
+	}
+	return resolved
+}
+
+export { serviceOf } from './deploy'

package/src/installation/install.ts

@@ -0,0 +1,286 @@
+// Public hosts exist only after the proxy deploys HTTP ports. Pass 1 builds an empty-manifest proxy;
+// pass 2 writes the full environment and delegates the ordered deploy to `deployPlatform` (ADR-0027).
+// This is bring-up only: existing generated-secret keys and partial topologies are refused.
+
+import {
+	action as consoleAction,
+	confirm as promptConfirm,
+	info as consoleInfo,
+	ok as consoleOk,
+	step as consoleStep,
+	warn as consoleWarn,
+} from '@fabrika/installation-init'
+import type { SchemaReconciler } from '@fabrika/provider-contract'
+import { createZeropsApi, defaultSleep, type ZeropsNamespaceProxySource } from '../index'
+import {
+	deployPlatformService,
+	deployPreparedPlatform,
+	PLATFORM_CONCURRENT_DEPLOY,
+	PLATFORM_DEPLOY_ORDER,
+	PLATFORM_PROXY_SERVICE,
+	PLATFORM_SEQUENTIAL_DEPLOY,
+	readServiceEnv,
+	type ResolvedService,
+} from './deploy'
+import { PLATFORM_PROXY_MANIFEST_TEMPLATE } from './generated/platform-proxy-manifest'
+import { derivePlatformHosts, type PlatformHosts, platformOrigin, ZEROPS_SUBDOMAIN_VARIABLE } from './hosts'
+import { checkedEnvironmentName } from './init'
+import { assertRunning, type InstallCollaborators, type InstallPrompts } from './install-collaborators'
+import { installationServiceEnv, passOneProxyEnv, writeServiceEnv } from './install-environment'
+import { type PlatformInstallInput, UNATTENDED_FLAG } from './install-options'
+import { resolveInstallationProject } from './install-project'
+import {
+	assertNoServiceIsBeingCreated,
+	assertNotAlreadyInstalled,
+	existingServices,
+	provision,
+	provisioningDocument,
+	resolvePlatformServices,
+	serviceOf,
+} from './install-provisioning'
+import { prepareInstallationSource, prepareNamespaceProxySource, validateInstallationSetups } from './installation-source'
+import type { PreparedPlatformSource } from './platform-source'
+import { generateInstallationSecrets, type InstallationSecrets } from './secrets'
+
+export type { InstallCollaborators, InstallPrompts } from './install-collaborators'
+export { GENERATED_SECRET_KEYS, type InstallationEnvInput, installationServiceEnv } from './install-environment'
+
+/**
+ * Pass 1 — give the proxy its ports, so the installation has public hostnames.
+ *
+ * Returns the three derived hosts. `derivePlatformHosts` refuses to compose a hostname, so a proxy that
+ * did not publish its six listeners fails here rather than producing a manifest pointing at an address
+ * nobody answers.
+ */
+const passOne = async (
+	source: PreparedPlatformSource,
+	proxy: ResolvedService,
+	secrets: InstallationSecrets,
+	collaborators: InstallCollaborators,
+): Promise<PlatformHosts> => {
+	const { log, prompts } = collaborators
+	log.step('Pass 1 — build the proxy so the installation has public hostnames')
+	log.info('An empty manifest is a legal one: the proxy comes up answering 404 and publishes one hostname per HTTP port.')
+	if (!(await prompts.confirm(`Write 4 variables on \`proxy\` and build commit ${source.commitSha}? (about 4 minutes)`, true))) {
+		throw new Error('declined: no variable was written, and re-running the install is safe')
+	}
+	await writeServiceEnv(proxy, passOneProxyEnv(secrets), collaborators)
+	await deployPlatformService(proxy, { source, dryRun: false }, collaborators)
+
+	const proxyEnv = await readServiceEnv(proxy.id, collaborators)
+	const subdomains = proxyEnv.get(ZEROPS_SUBDOMAIN_VARIABLE)
+	if (subdomains === undefined || subdomains.trim() === '') {
+		throw new Error('the proxy published no Zerops subdomain after its first deploy — this installation has no address to be named by')
+	}
+	const listeners = PLATFORM_PROXY_MANIFEST_TEMPLATE.apps.map((app) => ({ service: app.service, port: app.port }))
+	return derivePlatformHosts(subdomains, listeners)
+}
+
+/**
+ * Bring up one Zerops platform installation, in a project the operator created empty or in one created
+ * here.
+ *
+ * Every step that leaves this machine is confirmed first, and declining any of them stops there with
+ * what to run instead. Nothing after the project step and before the import is a mutation, so a declined
+ * install leaves the project exactly as it was.
+ */
+export const runInstall = async (input: PlatformInstallInput, collaborators: InstallCollaborators): Promise<void> => {
+	const source = await collaborators.prepareSource(input.sourceDir, collaborators.signal)
+	try {
+		validateInstallationSetups(source, PLATFORM_DEPLOY_ORDER)
+		const proxySource = await prepareNamespaceProxySource(source)
+		await installPreparedPlatform(input, collaborators, source, proxySource)
+	} finally {
+		await source.dispose()
+	}
+}
+
+const installPreparedPlatform = async (
+	input: PlatformInstallInput,
+	collaborators: InstallCollaborators,
+	source: PreparedPlatformSource,
+	proxySource: ZeropsNamespaceProxySource,
+): Promise<void> => {
+	const { log, prompts, signal } = collaborators
+	assertRunning(signal)
+	// Refused HERE, before anything is contacted: `local` is the name every development bypass is gated
+	// on, and IAM and control both refuse to boot with it on a public origin.
+	const environment = checkedEnvironmentName(input.environment)
+
+	log.info(`fabrika platform install — the ${environment} Zerops installation, on the ${input.tier} tier`)
+	log.info('This CREATES an installation. It generates every credential it needs and prints one of them at the end.')
+
+	const project = await resolveInstallationProject(input, environment, collaborators)
+	log.ok(`project ${project.name} (${project.id})`)
+
+	log.step('Provision the topology')
+	const document = provisioningDocument(environment)
+	const declared = document.document.services.map((service) => service.hostname)
+	const existing = existingServices(declared, await collaborators.api.listProjectServices({ projectId: project.id, signal }))
+	assertNoServiceIsBeingCreated(existing)
+	await assertNotAlreadyInstalled(existing, collaborators)
+	await provision(project.id, document, existing, collaborators)
+	const services = await resolvePlatformServices(project.id, collaborators)
+
+	log.step("Generate this installation's secrets")
+	const secrets = generateInstallationSecrets()
+	log.ok(
+		'IAM signing keys (1 × ES256), the IAM RPC key, the proxy key, the provisioning key, the Operations sync key and the vault key',
+	)
+	log.info('None of them is written to disk. Only the provisioning key is printed, once, at the end.')
+
+	log.step("Mint the control plane's Zerops token")
+	log.info('An INTEGRATION token, client role NO_ACCESS with ADMIN on this one project — never the personal token you authenticated with.')
+	if (!(await prompts.confirm(`Mint an integration token named \`fabrika-${environment}\` on client ${input.clientId}?`, true))) {
+		throw new Error('declined: nothing was minted, and re-running the install is safe')
+	}
+	const token = await collaborators.api.createIntegrationToken({
+		clientId: input.clientId,
+		name: `fabrika-${environment}`,
+		projects: [{ projectId: project.id, roleCode: 'ADMIN' }],
+		roleCode: 'NO_ACCESS',
+		// An app namespace IS a project, so a control plane that cannot create one cannot deploy an
+		// application at all (ADR-0034). `NO_ACCESS` still keeps every project it did not create out of reach.
+		canCreateProjects: true,
+		signal,
+	})
+	if (token.token === '') {
+		throw new Error('Zerops minted an integration token with no value — the control plane cannot deploy anything without one')
+	}
+	log.ok(`integration token ${token.id} minted, ${token.projects.length} project grant(s)`)
+
+	const hosts = await passOne(source, serviceOf(services, PLATFORM_PROXY_SERVICE), secrets, collaborators)
+	log.ok(`iam ${hosts.iam}`)
+	log.ok(`console ${hosts.control}`)
+	log.ok(`operations ${hosts.operations}`)
+
+	log.step('Write every remaining variable')
+	const desired = installationServiceEnv({
+		environment,
+		scheme: input.scheme,
+		hosts,
+		clientId: input.clientId,
+		proxySource,
+		secrets,
+		zeropsAccessToken: token.token,
+		...(input.apiBaseUrl === undefined ? {} : { apiBaseUrl: input.apiBaseUrl }),
+	})
+	const total = [...desired.values()].reduce((sum, keys) => sum + keys.size, 0)
+	if (!(await prompts.confirm(`Write ${total} variables across ${desired.size} services?`, true))) {
+		throw new Error(
+			'declined: the proxy is built but the installation is not configured. Its generated proxy key is already placed, so '
+				+ 're-running `platform install` is refused. Neither `platform deploy` nor `platform init` completes a partial bootstrap. '
+				+ 'Preserve the existing keys and arrange operator-owned recovery, or start a fresh installation in a separate empty project',
+		)
+	}
+	for (const hostname of PLATFORM_DEPLOY_ORDER) {
+		await writeServiceEnv(serviceOf(services, hostname), desired.get(hostname) ?? new Map<string, string>(), collaborators)
+	}
+
+	log.step('Pass 2 — deploy the installation')
+	log.info(
+		'Every bootstrap variable is placed. If this deploy fails, read FABRIKA_IAM_PROVISIONING_KEY from `iam` or `control` '
+			+ 'and FABRIKA_ZEROPS_ACCESS_TOKEN from `control` in Zerops, then run `fabrika platform deploy --provider=zerops` with this project and source checkout.',
+	)
+	log.info(
+		`\`platform deploy\` owns the whole ordered sequence: ${PLATFORM_CONCURRENT_DEPLOY.join(' + ')} together, then ${
+			PLATFORM_SEQUENTIAL_DEPLOY.join(' → ')
+		} — the proxy ahead of control (ADR-0027).`,
+	)
+	if (!(await prompts.confirm('Deploy the installation now? (about 15 minutes)', true))) {
+		log.action('OPERATOR ACTION — every variable is placed; the installation is one command from running', [
+			`FABRIKA_ZEROPS_ACCESS_TOKEN=… FABRIKA_IAM_PROVISIONING_KEY=… fabrika platform deploy --provider=zerops --source-dir=. --project-id=${project.id} --env=${environment}`,
+		])
+	} else {
+		await deployPreparedPlatform(
+			{
+				project: { kind: 'id', projectId: project.id },
+				accessToken: input.accessToken,
+				environment,
+				scheme: input.scheme,
+				sourceDir: input.sourceDir,
+				iamAdminKey: secrets.provisioningKey,
+				dryRun: false,
+				...(input.apiBaseUrl === undefined ? {} : { apiBaseUrl: input.apiBaseUrl }),
+			},
+			collaborators,
+			source,
+		)
+	}
+
+	log.step('Hand off')
+	// The intentional secret-output exception: init needs the key IAM was seeded with, never a new value.
+	log.action('CAPTURE THIS NOW — the CLI keeps no copy; recover it from the `iam` or `control` service environment in Zerops', [
+		`FABRIKA_IAM_PROVISIONING_KEY=${secrets.provisioningKey}`,
+	])
+	log.info('`fabrika platform init --provider=zerops <installation>` asks for two required deployment secrets:')
+	log.info('  FABRIKA_IAM_PROVISIONING_KEY   the key above')
+	log.info('  FABRIKA_ZEROPS_ACCESS_TOKEN    the integration token just minted — read it back from the `control` service, never printed here')
+	log.info(`The console answers at ${platformOrigin(input.scheme, hosts.control)}, once someone can sign in: nobody can yet.`)
+	// Through the SAME boxed path as the key above, deliberately: `action` is already the one output
+	// that carries a secret value, so the ready-to-run command does not become a second place one is
+	// printed. `platform admin` is idempotent, so re-running it is safe.
+	log.action('ADMIT YOURSELF — the console has no administrator until this runs', [
+		`FABRIKA_IAM_PROVISIONING_KEY=${secrets.provisioningKey} fabrika platform admin --provider=zerops --email=<you> --iam-host=${hosts.iam}`,
+	])
+}
+
+/**
+ * How this command's confirmations are answered — and the refusal when nothing can answer them.
+ *
+ * The confirmations are the only thing standing between a stray invocation and an installation: this
+ * command generates six credentials, mints a Zerops token on the account and deploys. Every one of
+ * them defaults to yes, so a pipe carrying blank lines answers all six of them with nobody reading
+ * what they agree to. So a run with no terminal is refused unless the operator asked for it by name.
+ */
+export const installPrompts = (
+	input: PlatformInstallInput,
+	stdin: { readonly isTTY?: boolean },
+	announce: (line: string) => void,
+): InstallPrompts => {
+	if (input.unattended) {
+		// The flag IS the yes, given once for the whole sequence; nothing reads stdin after it. Each
+		// question is still printed with the answer it was given, so an unattended run leaves the same
+		// record of what was agreed to that an interactive one does.
+		return {
+			confirm: (question) => {
+				announce(`${question} yes (${UNATTENDED_FLAG})`)
+				return Promise.resolve(true)
+			},
+		}
+	}
+	if (stdin.isTTY !== true) {
+		throw new Error(
+			"stdin is not a terminal, so nobody is here to confirm what this command does — it generates this installation's "
+				+ 'credentials, mints a Zerops integration token and deploys. Run it from a terminal, or pass `'
+				+ UNATTENDED_FLAG
+				+ '` to answer every confirmation yes unattended',
+		)
+	}
+	return { confirm: (question, defaultYes) => promptConfirm(question, defaultYes) }
+}
+
+/** The real collaborators: a TTY for the confirmations, the Zerops API, and IAM's own schema reconciler. */
+export const consoleInstallCollaborators = (input: PlatformInstallInput, reconcileSchema: SchemaReconciler): InstallCollaborators => {
+	// First, before anything is built or contacted: a bring-up nobody can confirm does not start.
+	const prompts = installPrompts(input, process.stdin, (line) => consoleInfo(line))
+	return {
+		prepareSource: prepareInstallationSource,
+		uploadFetch: (url, init) => fetch(url, init),
+		api: createZeropsApi({
+			token: input.accessToken,
+			...(input.apiBaseUrl === undefined ? {} : { baseUrl: input.apiBaseUrl }),
+		}),
+		reconcileSchema,
+		sleep: defaultSleep,
+		log: {
+			step: (title) => consoleStep(title),
+			info: (message) => consoleInfo(message),
+			warn: (message) => consoleWarn(message),
+			ok: (message) => consoleOk(message),
+			action: (title, lines) => consoleAction(title, [...lines]),
+		},
+		prompts,
+		signal: new AbortController().signal,
+	}
+}

package/src/installation/installation-source.ts

@@ -0,0 +1,42 @@
+import { realpath } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+import {
+	decodeZeropsNamespaceProxySource,
+	normalizeZeropsSourceRepository,
+	prepareZeropsDescriptor,
+	verifyZeropsNamespaceProxySource,
+	type ZeropsNamespaceProxySource,
+} from '../index'
+import { FABRIKA_REPOSITORY_URL } from './install-options'
+import { type PreparedPlatformSource, preparePlatformSource } from './platform-source'
+
+export type PlatformSourcePreparer = (sourceDir: string, signal: AbortSignal) => Promise<PreparedPlatformSource>
+
+export const prepareInstallationSource: PlatformSourcePreparer = async (sourceDir, signal) => {
+	const workspace = await realpath(fileURLToPath(new URL('../../../../', import.meta.url)))
+	if (await realpath(sourceDir) !== workspace) {
+		throw new Error(
+			'--source-dir must be the full checkout containing this installation module; run bun packages/cli/src/index.ts from that checkout instead of a packaged CLI',
+		)
+	}
+	return preparePlatformSource(sourceDir, signal)
+}
+
+export const validateInstallationSetups = (source: PreparedPlatformSource, setups: readonly string[]): void => {
+	for (const setup of setups) prepareZeropsDescriptor(source.descriptor.contents, setup)
+}
+
+export const FABRIKA_ZEROPS_PROXY_SOURCE_JSON = 'FABRIKA_ZEROPS_PROXY_SOURCE_JSON'
+
+// Zerops interpolates environment values; JSON escapes preserve descriptor bytes after parsing.
+export const serializeNamespaceProxySource = (source: ZeropsNamespaceProxySource): string => JSON.stringify(source).replaceAll('$', '\\u0024')
+
+export const prepareNamespaceProxySource = async (source: PreparedPlatformSource): Promise<ZeropsNamespaceProxySource> => {
+	const identity = decodeZeropsNamespaceProxySource({
+		repository: normalizeZeropsSourceRepository(FABRIKA_REPOSITORY_URL),
+		commitSha: source.commitSha,
+		descriptor: source.descriptor,
+	})
+	await verifyZeropsNamespaceProxySource(identity)
+	return identity
+}

package/src/installation/log.ts

@@ -0,0 +1,77 @@
+/**
+ * Progress reporting for `fabrika platform deploy --provider=zerops` and for `platform init`.
+ *
+ * HARD RULE, the same one `@fabrika/installation-init`'s `log.ts` states: **nothing here ever
+ * prints a secret VALUE, and there is deliberately no helper that accepts one.** Callers may pass a
+ * variable NAME, a count, or a "✓ written" confirmation. The Zerops access token and the IAM
+ * provisioning key are the two credentials this command holds; neither has a formatting path.
+ *
+ * A caught error is never passed through here either — `ZeropsApiError` (`src/api/errors.ts`)
+ * already redacts the platform's message on the calls that carry a value, but a raw error from
+ * anywhere else may quote a URL with an embedded token. Log a short sentence, never an error object.
+ *
+ * Only INTERFACES and test doubles live here. The console bindings live with the flow that uses them,
+ * so nothing on the deploy path imports the interactive `platform init` machinery.
+ */
+
+/** Where the command's progress goes. Injected so a test can read the transcript instead of stdout. */
+export interface DeployLog {
+	/** A numbered stage of the sequence. */
+	step(title: string): void
+	/** A detail line under the current stage. */
+	info(message: string): void
+	/** Something the operator should notice but which does not stop the deploy. */
+	warn(message: string): void
+}
+
+/** The real console log. Stateful only in its step counter. */
+export const consoleDeployLog = (): DeployLog => {
+	let step = 0
+	return {
+		step(title: string): void {
+			step += 1
+			console.info(`\n[${step}] ${title}`)
+		},
+		info(message: string): void {
+			console.info(`    ${message}`)
+		},
+		warn(message: string): void {
+			console.warn(`    ! ${message}`)
+		},
+	}
+}
+
+/** A log that records every line, for tests and for `--dry-run` assertions. */
+export const recordingDeployLog = (): DeployLog & { readonly lines: readonly string[] } => {
+	const lines: string[] = []
+	return {
+		lines,
+		step: (title) => void lines.push(`step: ${title}`),
+		info: (message) => void lines.push(`info: ${message}`),
+		warn: (message) => void lines.push(`warn: ${message}`),
+	}
+}
+
+/**
+ * What `platform init` reports. Two lines more than a deploy: a confirmation of something that
+ * happened, and the boxed hand-off an operator must not scroll past.
+ */
+export interface InitLog extends DeployLog {
+	/** Something outward-facing succeeded. Names a key or a repository, never a value. */
+	ok(message: string): void
+	/** A boxed OPERATOR ACTION — what to run when a confirmation was declined, or what is left to do. */
+	action(title: string, lines: readonly string[]): void
+}
+
+/** A log that records every line, so a test can assert on the transcript — including what is NOT in it. */
+export const recordingInitLog = (): InitLog & { readonly lines: readonly string[] } => {
+	const lines: string[] = []
+	return {
+		lines,
+		step: (title) => void lines.push(`step: ${title}`),
+		info: (message) => void lines.push(`info: ${message}`),
+		warn: (message) => void lines.push(`warn: ${message}`),
+		ok: (message) => void lines.push(`ok: ${message}`),
+		action: (title, actionLines) => void lines.push(`action: ${title}${actionLines.map((line) => `\n  ${line}`).join('')}`),
+	}
+}

package/src/installation/machine-key.ts

@@ -0,0 +1,65 @@
+// The block `platform admin` and `platform init` both end with: what `fabrika control key issue`
+// needs, and where an operator goes to find each part of it.
+//
+// It lives here, in the Zerops package rather than in `@fabrika/installation-init`, because only the
+// PLACES are worth printing and every place is Zerops-shaped — a service's env in a Zerops project,
+// the sidecar repository's Environment. The variable names are IAM's, but a Cloudflare installation
+// would have to name entirely different locations for them.
+//
+// ── It is PASTEABLE, which decides its shape ──────────────────────────────────────────────────────
+//
+// The acceptance is a fresh shell holding nothing: paste the block, supply the two keys, mint a key on
+// the first try. So the origin is an `export` — a bare `NAME=value` sets a shell variable the child
+// process never sees — and EVERY other line is a `#` comment. The command line is commented too, and
+// that is not timidity: `--label=<name>` is a shell redirection, and `[--expires-in=<seconds>]` ends in
+// a `>` that would create a file called `]` in whatever directory the operator pasted into.
+//
+// HARD RULE: no function here takes a key. The block is composed from an ORIGIN and variable NAMES,
+// so a caller that is holding the real values (both verbs are) cannot leak one through it.
+
+/** What the calling verb knows about this installation. Both fields are omitted when it would guess. */
+export interface MachineKeyNextStep {
+	/** IAM's PUBLIC origin — the address `FABRIKA_IAM_RPC_URL` takes. */
+	readonly iamOrigin?: string
+	/** The sidecar GitHub Environment that also holds the provisioning key, when its name is known. */
+	readonly sidecarEnvironment?: string
+}
+
+/** The boxed hand-off's title. Exported so a test names it once. */
+export const MACHINE_KEY_NEXT_STEP_TITLE = 'NEXT — mint a machine key for `fabrika control`'
+
+/** The command the block leads to, with the two flags `key issue` requires. */
+export const MACHINE_KEY_ISSUE_COMMAND = 'fabrika control key issue --label=<name> --permissions=<a,b,c> [--expires-in=<seconds>]'
+
+const WIDEST_NAME = 'FABRIKA_IAM_PROVISIONING_KEY'.length + 1
+
+/** A variable an operator must SUPPLY: a comment, never an assignment, so pasting the block is safe. */
+const readFrom = (variable: string, where: string): string => `# ${variable.padEnd(WIDEST_NAME)}read from: ${where}`
+
+/** A continuation of the line above, indented under its `read from:` column. */
+const continued = (rest: string): string => `# ${' '.repeat(WIDEST_NAME + 'read from: '.length)}${rest}`
+
+/**
+ * The lines of the block, in the order an operator uses them.
+ *
+ * The origin is the one VALUE printed, because it is not a credential: it is where the installation
+ * answers, and the rebuild that motivated this block failed precisely because an operator guessed it.
+ * The two keys are named and located; a value for either would come from the environment anyway.
+ */
+export const machineKeyNextStepLines = (step: MachineKeyNextStep = {}): readonly string[] => [
+	step.iamOrigin === undefined
+		// Never a guessed origin: the control service records the real one, and reading it is one command.
+		? readFrom('FABRIKA_IAM_RPC_URL', "`control`'s own FABRIKA_IAM_ISSUER, in the Zerops project")
+		: `export FABRIKA_IAM_RPC_URL=${step.iamOrigin}`,
+	readFrom('FABRIKA_IAM_RPC_KEY', "the `iam` or `control` service's env, in the Zerops project"),
+	readFrom('FABRIKA_IAM_PROVISIONING_KEY', 'the same env — the copy anyone with the project can read;'),
+	continued(
+		step.sidecarEnvironment === undefined
+			? "the sidecar repository's Environment holds the copy the pipeline uses"
+			: `the sidecar's \`${step.sidecarEnvironment}\` Environment holds the copy the pipeline uses`,
+	),
+	'# then, with the label and the permissions filled in:',
+	`#   ${MACHINE_KEY_ISSUE_COMMAND}`,
+	'# Both keys are environment-only and have no flag; this block prints NAMES, never values.',
+	'# A private hostname such as http://iam:3000 answers only inside the project — use the origin above.',
+]