@fabrika/provider-zerops 0.4.2 → 0.4.4

package/src/installation/install-environment.ts

@@ -1,45 +1,61 @@
-import { encodeProxyManifestJson, FABRIKA_PROXY_MANIFEST_JSON } from '@fabrika/proxy-core/manifest'
+import { encodeProxyManifestJson } from '@fabrika/proxy-core/manifest'
 import type { ZeropsNamespaceProxySource } from '../index'
 import type { PlatformDeployService, ResolvedService } from './deploy'
 import { type PlatformHosts, platformOrigin } from './hosts'
 import { assertRunning, type InstallCollaborators } from './install-collaborators'
 import { FABRIKA_ZEROPS_PROXY_SOURCE_JSON, serializeNamespaceProxySource } from './installation-source'
 import type { InstallationSecrets } from './secrets'
+import type { PlatformTier } from './topology/topology'
 
 /** The private address the proxy dials IAM at inside the project, and pass 1's placeholder issuer. */
 export const PRIVATE_IAM_UPSTREAM = 'iam:3000'
 const PRIVATE_IAM_URL = `http://${PRIVATE_IAM_UPSTREAM}`
 
 /** The canonical fabrika PostgreSQL DSN on Zerops — see `src/topology/setups.ts` for why both suffixes exist. */
-const POSTGRES_URL = '${db_connectionTlsString}/${db_dbName}?sslmode=require'
+const postgresUrl = (service: string): string => `\${${service}_connectionTlsString}/\${${service}_dbName}?sslmode=require`
 
-/** The light tier's one object-storage service, as the platform's own `${service_variable}` references. */
-const STORAGE = {
-	bucket: '${storage_bucketName}',
-	accessKeyId: '${storage_accessKeyId}',
-	secretAccessKey: '${storage_secretAccessKey}',
-	endpoint: '${storage_apiUrl}',
-} as const
+/** An object-storage service's coordinates, as the platform's own `${service_variable}` references. */
+interface StorageReferences {
+	readonly bucket: string
+	readonly accessKeyId: string
+	readonly secretAccessKey: string
+	readonly endpoint: string
+}
+
+const storageOf = (service: string): StorageReferences => ({
+	bucket: `\${${service}_bucketName}`,
+	accessKeyId: `\${${service}_accessKeyId}`,
+	secretAccessKey: `\${${service}_secretAccessKey}`,
+	endpoint: `\${${service}_apiUrl}`,
+})
+
+/** IAM and control share `db` and `storage` on both tiers; `standard` gives Operations its own pair. */
+const OPERATIONS_DATA: Readonly<Record<PlatformTier, { readonly database: string; readonly storage: string }>> = {
+	light: { database: 'db', storage: 'storage' },
+	standard: { database: 'operationsdb', storage: 'operationsstorage' },
+}
 
 /**
- * The four variables pass 1 writes on the proxy, and nothing else.
+ * The three variables pass 1 writes on the proxy, and nothing else.
  *
- * The manifest is EMPTY on purpose: it is the only legal document that can be written before the hosts
- * exist, and the build bakes whatever is here (`src/topology/setups.ts`). `FABRIKA_IAM_ISSUER` is the private
- * address rather than the public issuer for the same reason — the public one is not known yet — and
- * `deployPlatform` corrects it in pass 2, before the manifest it belongs to is applied.
+ * `FABRIKA_IAM_ISSUER` is the private address rather than the public issuer because the public one is not known
+ * yet; `deployPlatform` corrects it in pass 2, before the manifest it belongs to is applied. The pass-1 manifest is
+ * `PASS_ONE_PROXY_MANIFEST`, which the proxy's archive carries.
  */
 export const passOneProxyEnv = (secrets: InstallationSecrets): ReadonlyMap<string, string> =>
 	new Map([
-		[FABRIKA_PROXY_MANIFEST_JSON, encodeProxyManifestJson({ apps: [] })],
 		['FABRIKA_IAM_ISSUER', PRIVATE_IAM_URL],
 		['FABRIKA_IAM_KEY', secrets.proxyKey],
 		['FABRIKA_PROXY_SESSION_OWNER_JSON', 'null'],
 	])
 
+/** EMPTY on purpose: the only legal document before the hosts exist. The proxy comes up answering 404. */
+export const PASS_ONE_PROXY_MANIFEST = encodeProxyManifestJson({ apps: [] })
+
 /** What `installationServiceEnv` needs. Everything in it is settled before the first write. */
 export interface InstallationEnvInput {
 	readonly environment: string
+	readonly tier: PlatformTier
 	readonly scheme: 'http' | 'https'
 	readonly hosts: PlatformHosts
 	readonly clientId: string
@@ -72,17 +88,21 @@ export const installationServiceEnv = (input: InstallationEnvInput): ReadonlyMap
 	const { secrets } = input
 	const iamOrigin = platformOrigin(input.scheme, input.hosts.iam)
 	const operationsOrigin = platformOrigin(input.scheme, input.hosts.operations)
+	const platformDatabase = postgresUrl('db')
+	const runLogs = storageOf('storage')
+	const operationsData = OPERATIONS_DATA[input.tier]
+	const operationsBlobs = storageOf(operationsData.storage)
 	const control = new Map([
-		['FABRIKA_CONTROL_DATABASE_URL', POSTGRES_URL],
+		['FABRIKA_CONTROL_DATABASE_URL', platformDatabase],
 		['ENVIRONMENT', input.environment],
 		// A bare HOST, not an origin: `controlPublicOrigin` accepts either.
 		['FABRIKA_CONTROL_DOMAIN', input.hosts.control],
 		['FABRIKA_IAM_ISSUER', iamOrigin],
 		['OPERATIONS_ARTIFACT_ORIGIN', operationsOrigin],
-		['FABRIKA_CONTROL_RUN_LOGS_BUCKET', STORAGE.bucket],
-		['FABRIKA_CONTROL_RUN_LOGS_ACCESS_KEY_ID', STORAGE.accessKeyId],
-		['FABRIKA_CONTROL_RUN_LOGS_SECRET_ACCESS_KEY', STORAGE.secretAccessKey],
-		['FABRIKA_CONTROL_RUN_LOGS_ENDPOINT', STORAGE.endpoint],
+		['FABRIKA_CONTROL_RUN_LOGS_BUCKET', runLogs.bucket],
+		['FABRIKA_CONTROL_RUN_LOGS_ACCESS_KEY_ID', runLogs.accessKeyId],
+		['FABRIKA_CONTROL_RUN_LOGS_SECRET_ACCESS_KEY', runLogs.secretAccessKey],
+		['FABRIKA_CONTROL_RUN_LOGS_ENDPOINT', runLogs.endpoint],
 		['FABRIKA_IAM_RPC_KEY', secrets.rpcKey],
 		['OPERATIONS_SYNC_KEY', secrets.operationsSyncKey],
 		['FABRIKA_CONTROL_VAULT_KEY', secrets.vaultKey],
@@ -104,7 +124,7 @@ export const installationServiceEnv = (input: InstallationEnvInput): ReadonlyMap
 		[
 			'iam',
 			new Map([
-				['FABRIKA_IAM_DATABASE_URL', POSTGRES_URL],
+				['FABRIKA_IAM_DATABASE_URL', platformDatabase],
 				['ENVIRONMENT', input.environment],
 				['ISSUER', iamOrigin],
 				// Password only, by decision: OIDC needs an identity provider the operator has not been
@@ -121,11 +141,11 @@ export const installationServiceEnv = (input: InstallationEnvInput): ReadonlyMap
 		[
 			'operations',
 			new Map([
-				['FABRIKA_OPERATIONS_DATABASE_URL', POSTGRES_URL],
-				['FABRIKA_OPERATIONS_BLOB_BUCKET', STORAGE.bucket],
-				['FABRIKA_OPERATIONS_BLOB_ACCESS_KEY_ID', STORAGE.accessKeyId],
-				['FABRIKA_OPERATIONS_BLOB_SECRET_ACCESS_KEY', STORAGE.secretAccessKey],
-				['FABRIKA_OPERATIONS_BLOB_ENDPOINT', STORAGE.endpoint],
+				['FABRIKA_OPERATIONS_DATABASE_URL', postgresUrl(operationsData.database)],
+				['FABRIKA_OPERATIONS_BLOB_BUCKET', operationsBlobs.bucket],
+				['FABRIKA_OPERATIONS_BLOB_ACCESS_KEY_ID', operationsBlobs.accessKeyId],
+				['FABRIKA_OPERATIONS_BLOB_SECRET_ACCESS_KEY', operationsBlobs.secretAccessKey],
+				['FABRIKA_OPERATIONS_BLOB_ENDPOINT', operationsBlobs.endpoint],
 				['FABRIKA_OPERATIONS_PUBLIC_HOST', input.hosts.operations],
 				['ENVIRONMENT', input.environment],
 				['FABRIKA_IAM_ISSUER', iamOrigin],
@@ -175,18 +195,20 @@ export const GENERATED_SECRET_KEYS: ReadonlyMap<PlatformDeployService, readonly
 /**
  * Write a set of variables, reporting the KEYS — never a value, not even in a debug line.
  *
- * Write-first and unconditional: half of these are generated secrets, and a read-compare-write over a
- * value the platform may or may not hand back verbatim would make the outcome depend on something
- * nobody has pinned. `PUT /user-data/{id}` replaces in place, so a repeat costs a call and nothing else.
+ * Write-first and unconditional: a generated secret cannot be read back to compare, and `PUT
+ * /user-data/{id}` replaces in place, so a repeat costs a call and nothing else. Exactly the generated
+ * secrets are written sensitive; everything else stays readable, because `platform deploy` compares
+ * and merges it later.
  */
 export const writeServiceEnv = async (
 	service: ResolvedService,
 	desired: ReadonlyMap<string, string>,
 	{ api, log, signal }: InstallCollaborators,
 ): Promise<void> => {
+	const secrets = GENERATED_SECRET_KEYS.get(service.hostname) ?? []
 	for (const [key, value] of desired) {
 		assertRunning(signal)
-		await api.putServiceEnv({ serviceId: service.id, key, value, signal })
+		await api.putServiceEnv({ serviceId: service.id, key, value, sensitive: secrets.includes(key), signal })
 	}
 	log.ok(`${service.hostname}: wrote ${[...desired.keys()].join(', ')}`)
 }

package/src/installation/install-options.ts

@@ -9,11 +9,12 @@
 // and the variable that would supply it, so a mistyped install fails before it contacts anything.
 
 import { describeArgument, readEnv, readFlag, requiredSetting, setting, UNATTENDED_FLAG } from '@fabrika/installation-init'
+import { checkedSecretsFilePath, SECRETS_FILE_FLAG, SECRETS_FILE_VARIABLE } from './install-secrets'
 import { parsePlatformScheme } from './placement-options'
 import { readInstallationSourceDir } from './source-options'
+import type { PlatformTier } from './topology/topology'
 
-/** The only tier a bootstrap can install. See `assertInstallableTier`. */
-export type InstallablePlatformTier = 'light'
+const PLATFORM_TIERS: readonly PlatformTier[] = ['light', 'standard']
 
 /**
  * Where the installation's project comes from.
@@ -43,7 +44,9 @@ export interface PlatformInstallInput {
 	/** The scheme a browser speaks to this installation. */
 	readonly scheme: 'http' | 'https'
 	readonly sourceDir: string
-	readonly tier: InstallablePlatformTier
+	/** Where every credential this run creates is written, mode 0600, before the first is placed. */
+	readonly secretsFile: string
+	readonly tier: PlatformTier
 	/** `--yes`: answer every confirmation yes, for a bring-up with nobody at the keyboard. */
 	readonly unattended: boolean
 }
@@ -51,7 +54,7 @@ export interface PlatformInstallInput {
 /** The canonical public release repository used for namespace proxy source identities. */
 export const FABRIKA_REPOSITORY_URL = 'https://github.com/contember/fabrika-platform'
 
-const FLAGS = ['--project-id', '--project-name', '--client-id', '--env', '--scheme', '--source-dir', '--tier'] as const
+const FLAGS = ['--project-id', '--project-name', '--client-id', '--env', '--scheme', '--source-dir', '--tier', SECRETS_FILE_FLAG] as const
 
 /** `--create-project`: bring the project up too, instead of naming one the operator made. */
 export const CREATE_PROJECT_FLAG = '--create-project'
@@ -74,22 +77,16 @@ const assertKnownArguments = (argv: readonly string[]): void => {
 	}
 }
 
-/**
- * The tier this command can bring up.
- *
- * Only `light`, and that is a property of the topology rather than a limitation of the flow: the light
- * tier is the only one that emits a services-only provisioning document, because it is the only one an
- * operator installs into a project they created themselves. The standard tier is TWO projects that
- * fabrika creates, which is a different command with a different failure mode.
- */
-const assertInstallableTier = (raw: string | undefined): InstallablePlatformTier => {
-	if (raw === undefined || raw === 'light') {
+/** The platform tier to bring up. `light` stays the default, so an existing invocation installs what it did. */
+const readTier = (raw: string | undefined): PlatformTier => {
+	if (raw === undefined) {
 		return 'light'
 	}
-	throw new Error(
-		`--tier=${raw} cannot be installed into a project you created: only the light tier emits a services-only `
-			+ 'provisioning document. The standard tier is two projects fabrika creates itself',
-	)
+	const tier = PLATFORM_TIERS.find((candidate) => candidate === raw)
+	if (tier === undefined) {
+		throw new Error(`--tier=${raw} is not a platform tier — pass --tier=light or --tier=standard`)
+	}
+	return tier
 }
 
 const readScheme = (argv: readonly string[], env: Record<string, string | undefined>): 'http' | 'https' => {
@@ -149,7 +146,11 @@ export const parsePlatformInstallArgs = (
 		environment: readEnvironment(argv, env),
 		scheme: readScheme(argv, env),
 		sourceDir,
-		tier: assertInstallableTier(setting(argv, env, '--tier', 'FABRIKA_PLATFORM_TIER')),
+		secretsFile: checkedSecretsFilePath(
+			requiredSetting(setting(argv, env, SECRETS_FILE_FLAG, SECRETS_FILE_VARIABLE), SECRETS_FILE_FLAG, SECRETS_FILE_VARIABLE),
+			sourceDir,
+		),
+		tier: readTier(setting(argv, env, '--tier', 'FABRIKA_PLATFORM_TIER')),
 		unattended: argv.includes(UNATTENDED_FLAG),
 		...(apiBaseUrl === undefined ? {} : { apiBaseUrl }),
 	}

package/src/installation/install-project.ts

@@ -1,10 +1,12 @@
 import { ENV_ISOLATION, renderYaml, type ZeropsProjectMode, type ZeropsProjectStatus } from '../index'
 import { assertRunning, type InstallCollaborators } from './install-collaborators'
 import type { PlatformInstallInput } from './install-options'
-import { lightTopology } from './install-provisioning'
+import { installationTopology } from './install-provisioning'
+import { assertPersonalAccessToken } from './install-token'
+import type { PlatformTier } from './topology/topology'
 
-/** The project compute tier each installable platform tier requires. `corePackage` is upgrade-only. */
-const REQUIRED_PROJECT_MODE: ZeropsProjectMode = 'LIGHT'
+/** The project compute tier each platform tier requires. `corePackage` is upgrade-only. */
+const REQUIRED_PROJECT_MODE: Readonly<Record<PlatformTier, ZeropsProjectMode>> = { light: 'LIGHT', standard: 'SERIOUS' }
 
 /** The one project state this command may install into. */
 const PROJECT_ACTIVE: ZeropsProjectStatus = 'ACTIVE'
@@ -32,15 +34,16 @@ const PROJECT_READ_FAILURES = 3
  * The document `--create-project` applies, carrying a `project:` block and NO services.
  *
  * Taken from the same declaration the provisioning import is compiled from, so `envIsolation: service`
- * and `corePackage: LIGHT` — the two settings a project accepts at CREATION only and never afterwards —
+ * and `corePackage` — the two settings a project accepts at CREATION only and never afterwards —
  * have exactly one source. Only the name is this run's. `renderImportYaml` is not the renderer here
  * because it refuses a document with no services, and this one deliberately has none: the services arrive
  * through the services-only import, into the project this creates.
  */
-const createProjectYaml = (environment: string, projectName: string): string => {
-	const declared = lightTopology(environment).provision.document.project
-	if (declared === undefined || declared.corePackage !== REQUIRED_PROJECT_MODE || declared.envIsolation !== ENV_ISOLATION) {
-		throw new Error(`the light platform topology declares no \`${REQUIRED_PROJECT_MODE}\` project with \`envIsolation: ${ENV_ISOLATION}\` to create`)
+const createProjectYaml = (environment: string, tier: PlatformTier, projectName: string): string => {
+	const declared = installationTopology(environment, tier).provision.document.project
+	const mode = REQUIRED_PROJECT_MODE[tier]
+	if (declared === undefined || declared.corePackage !== mode || declared.envIsolation !== ENV_ISOLATION) {
+		throw new Error(`the ${tier} platform topology declares no \`${mode}\` project with \`envIsolation: ${ENV_ISOLATION}\` to create`)
 	}
 	return renderYaml({ project: { ...declared, name: projectName }, services: [] })
 }
@@ -122,7 +125,7 @@ const createProject = async (
 	assertRunning(signal)
 	const result = await api.importProject({
 		clientId: input.clientId,
-		yaml: createProjectYaml(environment, projectName),
+		yaml: createProjectYaml(environment, input.tier, projectName),
 		signal,
 	})
 	if (result.projectId === '') {
@@ -143,18 +146,19 @@ const resolveProject = async (
 	{ api, log, signal }: InstallCollaborators,
 ): Promise<{ id: string; name: string }> => {
 	const project = await api.getProject({ projectId, signal })
+	const mode = REQUIRED_PROJECT_MODE[input.tier]
 	if (project.id === '') {
 		throw new Error(`Zerops project ${projectId} could not be read with this token`)
 	}
 	if (project.mode === undefined) {
 		// Not a mismatch, so not a refusal: the client narrows an unknown value to absent, and blocking an
 		// install on a field the API did not state would be refusing on an absence of evidence.
-		log.warn(`Zerops did not state project ${project.name}'s mode; the ${input.tier} tier expects ${REQUIRED_PROJECT_MODE}`)
-	} else if (project.mode !== REQUIRED_PROJECT_MODE) {
+		log.warn(`Zerops did not state project ${project.name}'s mode; the ${input.tier} tier expects ${mode}`)
+	} else if (project.mode !== mode) {
 		throw new Error(
-			`Zerops project ${project.name} is ${project.mode} and the ${input.tier} tier needs ${REQUIRED_PROJECT_MODE}. \`corePackage\` is `
+			`Zerops project ${project.name} is ${project.mode} and the ${input.tier} tier needs ${mode}. \`corePackage\` is `
 				+ 'upgrade-only and its upgrade is partly destructive, so this is not something an install may change — create the project '
-				+ `with core package ${REQUIRED_PROJECT_MODE}, or install a tier that matches`,
+				+ `with core package ${mode}, or install a tier that matches`,
 		)
 	}
 	return { id: project.id, name: project.name }
@@ -163,7 +167,7 @@ const resolveProject = async (
 /**
  * Settle which project this run installs into — the operator's, or one created here.
  *
- * ONE confirmation either way, and both cover the read that follows: a created project is read back
+ * ONE confirmation either way, and both cover the token check and the read that follows: a created project is read back
  * through the same `resolveProject` an operator-made one goes through, so the core package is checked on
  * the project that will actually be installed into rather than on the document that asked for it.
  */
@@ -183,19 +187,23 @@ export const resolveInstallationProject = async (
 		) {
 			throw new Error('declined: nothing was contacted, and re-running the install is safe')
 		}
+		await assertPersonalAccessToken(collaborators)
 		return resolveProject(input, source.projectId, collaborators)
 	}
 	log.step('Create the project this installation is brought up in')
 	log.info('`envIsolation` and `corePackage` are settable at project CREATION only, which is why the project is created from here.')
 	if (
 		!(await prompts.confirm(
-			`CREATE Zerops project \`${source.projectName}\` (core package ${REQUIRED_PROJECT_MODE}, envIsolation ${ENV_ISOLATION}) on client `
+			`Check the token, then CREATE Zerops project \`${source.projectName}\` (core package ${
+				REQUIRED_PROJECT_MODE[input.tier]
+			}, envIsolation ${ENV_ISOLATION}) on client `
 				+ `${input.clientId}, then read it back?`,
 			true,
 		))
 	) {
 		throw new Error('declined: no project was created, and re-running the install is safe')
 	}
+	await assertPersonalAccessToken(collaborators)
 	const projectId = await createProject(input, environment, source.projectName, collaborators)
 	return resolveProject(input, projectId, collaborators)
 }

package/src/installation/install-provisioning.ts

@@ -2,24 +2,24 @@ import { waitForProcess, type ZeropsImportResult, type ZeropsService, type Zerop
 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'
+import { type CompiledDocument, type CompiledTopology, compileTopology, type PlatformTier, 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 topology this command installs for a tier, so the project document and the services document cannot drift. */
+export const installationTopology = (environment: string, tier: PlatformTier): CompiledTopology =>
+	compileTopology(platformTopology({ env: environment, tier, 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.
+ * `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
+export const provisioningDocument = (environment: string, tier: PlatformTier): CompiledDocument => {
+	const document = installationTopology(environment, tier).servicesProvision
 	if (document === undefined) {
-		throw new Error('the light platform topology declares no services-only provisioning document')
+		throw new Error(`the ${tier} platform topology declares no services-only provisioning document`)
 	}
 	return document
 }
@@ -64,7 +64,7 @@ export const assertNoServiceIsBeingCreated = (existing: ReadonlyMap<string, Exis
 	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',
+				+ 'read from it or written to it yet. The topology settles in a few minutes; run the install again then',
 		)
 	}
 }
@@ -99,8 +99,8 @@ export const assertNotAlreadyInstalled = async (
 			`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. '
+				+ 'to update or finish deploying the installation, with the credentials from the secrets file the first install wrote. '
+				+ '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',
 		)
 	}

package/src/installation/install-secrets.ts

@@ -0,0 +1,89 @@
+// The local copy of every credential `platform install` creates.
+//
+// The services hold the same values in Zerops, but stored SENSITIVE, and Zerops hands a sensitive value
+// back only to a token in sudo mode (measured 2026-10-15). So the operator's copy is the one this
+// command writes, before the first of them is placed: a run that fails later loses nothing.
+
+import { existsSync } from 'node:fs'
+import { open } from 'node:fs/promises'
+import { isAbsolute, relative, resolve } from 'node:path'
+import type { InstallationSecrets } from './secrets'
+
+/** `--secrets-file`: where the local copy goes. A new file, outside the source checkout. */
+export const SECRETS_FILE_FLAG = '--secrets-file'
+export const SECRETS_FILE_VARIABLE = 'FABRIKA_PLATFORM_SECRETS_FILE'
+
+/**
+ * Settle the path before anything is contacted.
+ *
+ * Refused when it exists, because overwriting one would destroy another installation's only copy, and
+ * when it is inside the source checkout, where it would dirty the checkout `platform deploy` uploads
+ * and could be committed.
+ */
+export const checkedSecretsFilePath = (path: string, sourceDir: string): string => {
+	const absolute = resolve(path)
+	const fromSource = relative(resolve(sourceDir), absolute)
+	if (fromSource === '' || (!fromSource.startsWith('..') && !isAbsolute(fromSource))) {
+		throw new Error(`${SECRETS_FILE_FLAG}=${path} is inside the source checkout — name a path outside it, so it is never uploaded or committed`)
+	}
+	if (existsSync(absolute)) {
+		throw new Error(`${SECRETS_FILE_FLAG}=${path} already exists — it may be another installation's only copy; name a new file`)
+	}
+	return absolute
+}
+
+/** What the file records beside the credentials, so it identifies its installation on its own. */
+export interface InstallationSecretsRecord {
+	readonly environment: string
+	readonly projectId: string
+	readonly clientId: string
+	readonly secrets: InstallationSecrets
+	/** The integration token minted for the control plane. */
+	readonly zeropsAccessToken: string
+}
+
+/**
+ * The file's text: shell-sourceable assignments, named as the commands that read them name them.
+ *
+ * `FABRIKA_ZEROPS_ACCESS_TOKEN` is the INTEGRATION token, which is what `platform init` and
+ * `platform deploy` take; the personal token the install ran with is not written.
+ */
+export const renderSecretsFile = (record: InstallationSecretsRecord): string => {
+	const { secrets } = record
+	const assignments: readonly (readonly [string, string])[] = [
+		['FABRIKA_ZEROPS_PROJECT_ID', record.projectId],
+		['FABRIKA_ZEROPS_CLIENT_ID', record.clientId],
+		['FABRIKA_IAM_PROVISIONING_KEY', secrets.provisioningKey],
+		['FABRIKA_ZEROPS_ACCESS_TOKEN', record.zeropsAccessToken],
+		['FABRIKA_IAM_RPC_KEY', secrets.rpcKey],
+		['FABRIKA_IAM_PROXY_KEY', secrets.proxyKey],
+		['OPERATIONS_SYNC_KEY', secrets.operationsSyncKey],
+		['FABRIKA_CONTROL_VAULT_KEY', secrets.vaultKey],
+		['FABRIKA_IAM_SIGNING_KEYS', secrets.signingKeys],
+	]
+	const lines = assignments.map(([name, value]) => {
+		// Single quotes keep every character literal; none of these values can contain one.
+		if (value.includes("'") || value.includes('\n')) {
+			throw new Error(`${name} cannot be written to the secrets file as one quoted line`)
+		}
+		return `${name}='${value}'`
+	})
+	return [
+		`# fabrika on Zerops — installation \`${record.environment}\`, project ${record.projectId}.`,
+		'# Written by `fabrika platform install`. Every value below is a credential: keep this file private.',
+		'# Zerops holds the same values as sensitive variables and does not hand them back.',
+		'# Load it in a subshell: ( set -a && . <this file> && set +a && fabrika … )',
+		...lines,
+		'',
+	].join('\n')
+}
+
+/** Create the file with mode 0600, failing rather than replacing one that appeared since the check. */
+export const writeSecretsFile = async (path: string, text: string): Promise<void> => {
+	const file = await open(path, 'wx', 0o600)
+	try {
+		await file.writeFile(text)
+	} finally {
+		await file.close()
+	}
+}

package/src/installation/install-token.ts

@@ -0,0 +1,37 @@
+import { ZeropsApiError } from '../index'
+import type { InstallCollaborators } from './install-collaborators'
+
+/** The platform's answer when an integration token without delegation asks to mint another one. */
+const MINT_REFUSED_TO_INTEGRATION_TOKEN = 'notAllowedForIntegrationTokenWithoutDelegation'
+
+/** How `/user/info` names an integration token. Reported by an operator, not measured here. */
+const INTEGRATION_TOKEN_EMAIL = /^token-[^@]+@zerops\.io$/i
+
+const PERSONAL_TOKEN_REQUIRED = 'FABRIKA_ZEROPS_ACCESS_TOKEN is a Zerops integration token (`/user/info` names it `token-…@zerops.io`), '
+	+ 'and an integration token may not mint the one the control plane needs. Generate a personal access token in the Zerops GUI, '
+	+ 'as a user who is OWNER on the client'
+
+/**
+ * Refuse an integration token before anything is created.
+ *
+ * The install mints an integration token at step 4, and an integration token is refused that mint. Without
+ * this read the mistake costs a billed project and six imported services first.
+ */
+export const assertPersonalAccessToken = async ({ api, signal }: InstallCollaborators): Promise<void> => {
+	const identity = await api.getUserInfo({ signal })
+	if (INTEGRATION_TOKEN_EMAIL.test(identity.email)) {
+		throw new Error(`${PERSONAL_TOKEN_REQUIRED}. Nothing was created`)
+	}
+}
+
+/** Translate the mint's refusal of an integration token into the fix and the way back into this project. */
+export const explainMintFailure = (failure: unknown, projectId: string): unknown => {
+	if (!(failure instanceof ZeropsApiError) || failure.code !== MINT_REFUSED_TO_INTEGRATION_TOKEN) {
+		return failure
+	}
+	return new Error(
+		`${PERSONAL_TOKEN_REQUIRED}. No generated secret was placed yet: re-run the install with the personal token and `
+			+ `--project-id=${projectId} instead of --create-project; it keeps the services already imported`,
+		{ cause: failure },
+	)
+}