@fabrika/provider-zerops 0.4.4 → 0.4.6

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/provider-zerops",
-	"version": "0.4.4",
+	"version": "0.4.6",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -43,13 +43,13 @@
 	},
 	"dependencies": {
 		"zod": "^3.25.76",
-		"@fabrika/auth": "^0.4.4",
-		"@fabrika/auth-core": "^0.4.4",
-		"@fabrika/iam-contract": "^0.4.4",
-		"@fabrika/installation-init": "^0.4.4",
-		"@fabrika/operations-contract": "^0.4.4",
-		"@fabrika/provider-contract": "^0.4.4",
-		"@fabrika/proxy-core": "^0.4.4",
+		"@fabrika/auth": "^0.4.6",
+		"@fabrika/auth-core": "^0.4.6",
+		"@fabrika/iam-contract": "^0.4.6",
+		"@fabrika/installation-init": "^0.4.6",
+		"@fabrika/operations-contract": "^0.4.6",
+		"@fabrika/provider-contract": "^0.4.6",
+		"@fabrika/proxy-core": "^0.4.6",
 		"yaml": "^2.9.1"
 	}
 }

package/src/control.ts

@@ -49,7 +49,7 @@ import {
 	zeropsNamespaceTargetCodec,
 } from './namespace'
 import { createZeropsDeployer, ZEROPS_VERSION_DEADLINE_MS } from './provider'
-import { allowedReferenceHosts, foreignReferenceHost, serviceReferenceHosts } from './service-references'
+import { allowedReferenceHosts, assertNoPlatformOnlyReference, foreignReferenceHost, serviceReferenceHosts } from './service-references'
 import { normalizeZeropsSourceRepository } from './source'
 import type { ZeropsSourcePort, ZeropsSourcePrivateBinding } from './source/port'
 import type { ZeropsRunState, ZeropsRuntimeTarget } from './types'
@@ -466,6 +466,8 @@ export const createZeropsControlProvider = (options: ZeropsControlProviderOption
 				assertAuthoredManagedName(input.name)
 				assertNoFrameworkReference(input.name)
 				assertNoFrameworkReference(input.value)
+				assertNoPlatformOnlyReference(input.name)
+				assertNoPlatformOnlyReference(input.value)
 				assertOwnReferencesOnly(input.environment, input.name, input.value)
 				const target = decodeEnvironment(input.environment).target
 				try {

package/src/exposure.ts

@@ -7,6 +7,7 @@ import type { ZeropsImportResult } from './api'
 /**
  * The provenance marker: a service variable on the deploy service listing the object-storage service ids the platform
  * created, each from an import that carried `objectStoragePolicy: private`. A bucket adopted by hostname has none.
+ * The import's answer is the only evidence of creation, so `apply-import` records it here before any other step runs.
  */
 export const STORAGE_PROVENANCE_KEY = 'FABRIKA_STORAGE_PROVENANCE'
 
@@ -30,6 +31,17 @@ export const createdServices = (result: ZeropsImportResult): ReadonlyMap<string,
 			.map((service) => [service.name, service.id]),
 	)
 
+/** How the deploy service holds the marker: a release up to v0.4.2 wrote it sensitive, which reads back without its value. */
+export type StorageProvenanceMarker = 'absent' | 'readable' | 'sensitive'
+
+/** The refusal of a bucket no evidence names, with the two remedies an operator has without sudo. */
+export const unprovenBucketReason = (input: { bucketId: string; deployService: string; marker: StorageProvenanceMarker }): string => {
+	const unreadable = input.marker === 'sensitive'
+		? `; \`${STORAGE_PROVENANCE_KEY}\` on \`${input.deployService}\` was written sensitive by an earlier release and cannot be read`
+		: ''
+	return `is a bucket the platform did not create private (no provenance${unreadable}). If a Fabrika import created it (its \`${CREATE_ACTION}\` process ran under the platform's Zerops token), set \`${STORAGE_PROVENANCE_KEY}\` on \`${input.deployService}\` to \`${input.bucketId}\`, not sensitive; otherwise delete the bucket and deploy again`
+}
+
 export interface ExposureFinding {
 	readonly hostname: string
 	readonly reason: string

package/src/manifest.ts

@@ -19,7 +19,7 @@ import {
 	type ZeropsRuntimePackage,
 } from './execution'
 import { assertAuthoredManagedDocument, assertAuthoredManagedInputs } from './managed-env'
-import { allowedReferenceHosts, foreignReferenceHost } from './service-references'
+import { allowedReferenceHosts, foreignReferenceHost, platformOnlyServiceReference } from './service-references'
 import type { ZeropsAppConfig, ZeropsNamespaceResourceRequirement, ZeropsProxySpec, ZeropsSharedPostgresBinding } from './types'
 
 export const FABRIKA_MANIFEST_VERSION = 3
@@ -32,11 +32,13 @@ const SHA256_PATTERN = /^[0-9a-f]{64}$/
  *
  * Restated here rather than imported from `./namespace` — that module imports THIS one, and the
  * literal is part of the manifest's parse contract, so it belongs on the parsing side. The reasoning
- * for the database path and the TLS mode lives with `ZEROPS_SHARED_POSTGRES_CONNECTION_STRING`; a test
- * asserts the two never diverge.
+ * for the port, the database path and the TLS mode lives with `ZEROPS_SHARED_POSTGRES_CONNECTION_STRING`;
+ * a test asserts the two never diverge.
  */
 const SHARED_POSTGRES_CONNECTION_STRING: ZeropsSharedPostgresBinding['connectionString'] =
-	'${postgres_connectionTlsString}/${postgres_dbName}?sslmode=require'
+	'${postgres_connectionString}/${postgres_dbName}?sslmode=disable'
+/** The form an artifact built before the binding moved to the direct port carries: still decoded, as the current form. */
+const LEGACY_SHARED_POSTGRES_CONNECTION_STRING = '${postgres_connectionTlsString}/${postgres_dbName}?sslmode=require'
 
 export interface FabrikaImportDocument {
 	readonly project?: { readonly [key: string]: JsonValue }
@@ -122,7 +124,8 @@ const manifestProxySchema = z.object({
 const namespaceResourcesSchema = z.array(z.object({
 	resourceKey: z.literal('service:postgres'),
 	hostname: z.literal('postgres'),
-	connectionString: z.literal(SHARED_POSTGRES_CONNECTION_STRING),
+	connectionString: z.union([z.literal(SHARED_POSTGRES_CONNECTION_STRING), z.literal(LEGACY_SHARED_POSTGRES_CONNECTION_STRING)])
+		.transform((): ZeropsSharedPostgresBinding['connectionString'] => SHARED_POSTGRES_CONNECTION_STRING),
 })).max(1)
 
 const manifestAppSchema = z.object({
@@ -245,27 +248,34 @@ const importServiceSchema = z.intersection(
 const importProjectSchema = z.intersection(z.record(manifestJsonSchema), z.object({ envIsolation: z.literal(ENV_ISOLATION) }))
 	.superRefine(forbidFields(['envVariables'], 'invalid fabrika manifest: Zerops import contains a forbidden project environment field'))
 
-/** The first foreign host referenced by any string leaf OR key of `value`, however deeply nested. */
-const foreignReferenceInValue = (value: unknown, allowed: ReadonlySet<string>): string | null => {
+/** The first match of `find` in any string leaf OR key of `value`, however deeply nested. */
+const firstInValue = (value: unknown, find: (text: string) => string | null): string | null => {
 	if (typeof value === 'string') {
-		return foreignReferenceHost(value, allowed)
+		return find(value)
 	}
 	if (Array.isArray(value)) {
 		for (const entry of value) {
-			const host = foreignReferenceInValue(entry, allowed)
-			if (host !== null) return host
+			const found = firstInValue(entry, find)
+			if (found !== null) return found
 		}
 		return null
 	}
 	if (typeof value === 'object' && value !== null) {
 		for (const [key, entry] of Object.entries(value)) {
-			const host = foreignReferenceHost(key, allowed) ?? foreignReferenceInValue(entry, allowed)
-			if (host !== null) return host
+			const found = find(key) ?? firstInValue(entry, find)
+			if (found !== null) return found
 		}
 	}
 	return null
 }
 
+/** The first foreign host referenced by any string leaf OR key of `value`, however deeply nested. */
+const foreignReferenceInValue = (value: unknown, allowed: ReadonlySet<string>): string | null =>
+	firstInValue(value, (text) => foreignReferenceHost(text, allowed))
+
+const platformOnlyReferenceMessage = (where: string, reference: string): string =>
+	`invalid fabrika manifest: ${where} references \`${reference}\`, the PostgreSQL superuser's password, which only the platform uses (ADR-0017)`
+
 const importDocumentSchema = z.object({ project: importProjectSchema.optional(), services: z.array(importServiceSchema).min(1) })
 	.strict()
 	.superRefine(({ services }, ctx) => {
@@ -288,6 +298,11 @@ const importDocumentSchema = z.object({ project: importProjectSchema.optional(),
 				})
 				return
 			}
+			const platformOnly = firstInValue(service, platformOnlyServiceReference)
+			if (platformOnly !== null) {
+				ctx.addIssue({ code: 'custom', message: platformOnlyReferenceMessage(`Zerops service \`${service.hostname}\``, platformOnly) })
+				return
+			}
 		}
 	})
 
@@ -386,8 +401,18 @@ const isDescriptorSetup = (value: JsonValue, setup: string): value is { readonly
 	typeof value === 'object' && value !== null && !Array.isArray(value) && value['setup'] === setup
 
 /**
- * The `${host_…}` reference `FABRIKA_APP_DATABASE_URL` is generated from: the namespace's shared PostgreSQL, or the
- * application's one PostgreSQL service. Two candidates would make the generated migration pick one.
+ * `FABRIKA_APP_DATABASE_URL`, the provisioning credential of the application's role family (ADR-0017), as `${host_…}`
+ * references: the service's superuser, because its own user `db` can neither create roles nor create in the database
+ * (measured 2026-10-15). The direct port, because pgBouncer on `portTls` admits only the service's own users and refuses
+ * the roles the migration creates, which reuse this URL's host, port and options. `disable`, because `ha` offers no TLS
+ * on that port and `Bun.SQL`'s `prefer` does not fall back to plaintext; the port stays inside the project's network.
+ */
+const zeropsProvisioningDatabaseUrl = (host: string): string =>
+	`postgresql://\${${host}_superUser}:\${${host}_superUserPassword}@\${${host}_hostname}:\${${host}_port}/\${${host}_dbName}?sslmode=disable`
+
+/**
+ * The PostgreSQL service `FABRIKA_APP_DATABASE_URL` is generated for: the namespace's shared one, or the application's
+ * one PostgreSQL service. Two candidates would make the generated migration pick one.
  */
 const applicationDatabaseUrl = (
 	services: FabrikaManifestImportDocument['services'],
@@ -398,9 +423,8 @@ const applicationDatabaseUrl = (
 	if (own.length + (shared === undefined ? 0 : 1) > 1) {
 		throw new Error('invalid fabrika manifest: a contract application has one PostgreSQL database; it declares more than one')
 	}
-	if (shared !== undefined) return shared.connectionString
-	const host = own[0]
-	return host === undefined ? null : `\${${host}_connectionTlsString}/\${${host}_dbName}?sslmode=require`
+	const host = shared?.hostname ?? own[0]
+	return host === undefined ? null : zeropsProvisioningDatabaseUrl(host)
 }
 
 /** The hostname the `FABRIKA_APP_STORAGE_*` references name: the application's one object-storage service. */
@@ -524,13 +548,13 @@ export function parseFabrikaManifest(value: unknown, expected: ManifestExpectati
 	}
 	// Only the selected setup and what it extends reach this app's service, so a sibling setup for another
 	// placement may reference services this app does not own.
-	const foreignInDescriptor = foreignReferenceInValue(
-		executionZeropsDocument(parsedDescriptor, selectedSetup),
-		allowedReferenceHosts(serviceHostnames),
-	)
+	const executed = executionZeropsDocument(parsedDescriptor, selectedSetup)
+	const foreignInDescriptor = foreignReferenceInValue(executed, allowedReferenceHosts(serviceHostnames))
 	if (foreignInDescriptor !== null) {
 		throw new Error(`invalid fabrika manifest: zerops.yaml references service \`${foreignInDescriptor}\`, which this app does not own`)
 	}
+	const platformOnlyInDescriptor = firstInValue(executed, platformOnlyServiceReference)
+	if (platformOnlyInDescriptor !== null) throw new Error(platformOnlyReferenceMessage('zerops.yaml', platformOnlyInDescriptor))
 	if (contract === undefined && (proxy !== undefined || schema?.contract === true)) {
 		// An endpoint table without the contract would deploy a contract application with an authored run section.
 		throw new Error('invalid fabrika manifest: a contract application carries its contract (`target.contract`), which locks its setup down')

package/src/namespace/constants.ts

@@ -10,21 +10,21 @@ export const ZEROPS_NAMESPACE_IAM_KEY_VARIABLE = 'FABRIKA_IAM_KEY'
 export const ZEROPS_NAMESPACE_SUBDOMAIN_VARIABLE = 'zeropsSubdomain'
 
 /**
- * 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:
+ * How an app reaches the namespace-owned PostgreSQL service as its own user `db` — port, database and TLS mode NAMED,
+ * not defaulted. Every part settled against a live account, none of it safe to infer:
  *
- *   • `${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.
- *   • 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.
+ *   • `${x_connectionString}` is `postgresql://${user}:${password}@${hostname}:${port}` — 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`). `/${x_dbName}` says it out loud rather than relying on that fallback.
+ *   • THE DIRECT PORT, NOT `portTls`. `portTls` (6432) is pgBouncer with a static user list: only `db`, `postgres` and
+ *     `zps` log in there, and a role fabrika creates is refused (`08P01`, measured 2026-10-15). A contract
+ *     application's runtime role reuses its database URL's host and port, so only the direct port serves it.
+ *   • `sslmode=disable`, the one mode that connects on both service types: `postgresql:ha@18` answers `require` on the
+ *     direct port with "Server does not support SSL", and `Bun.SQL`'s `prefer` waits out its 30 s connection timeout
+ *     against a server without TLS instead of falling back. The direct port stays inside the project's network.
+ *
+ * A contract application does not connect with this: its `FABRIKA_APP_DATABASE_URL` names the service's superuser,
+ * the provisioning credential of its role family (ADR-0017, `zeropsProvisioningDatabaseUrl` in `../manifest.ts`).
  */
-export const ZEROPS_SHARED_POSTGRES_CONNECTION_STRING = '${postgres_connectionTlsString}/${postgres_dbName}?sslmode=require'
+export const ZEROPS_SHARED_POSTGRES_CONNECTION_STRING = '${postgres_connectionString}/${postgres_dbName}?sslmode=disable'

package/src/provider.ts

@@ -45,6 +45,8 @@ import {
 	isObjectStorageType,
 	parseStorageProvenance,
 	STORAGE_PROVENANCE_KEY,
+	type StorageProvenanceMarker,
+	unprovenBucketReason,
 } from './exposure'
 import {
 	assertAuthoredManagedDocument,
@@ -66,7 +68,7 @@ import {
 	verifyZeropsArtifactSourceDescriptor,
 } from './manifest'
 import { buildZeropsPlan, resolveDeployHostname, type ZeropsStep } from './plan'
-import { allowedReferenceHosts, foreignReferenceHost } from './service-references'
+import { allowedReferenceHosts, assertNoPlatformOnlyReference, foreignReferenceHost } from './service-references'
 import { isZeropsUploadDestination } from './source'
 import type { ZeropsRunState, ZeropsRuntimeSource, ZeropsRuntimeTarget } from './types'
 import { deleteVersion } from './version-attempt'
@@ -236,13 +238,16 @@ export function interpolateManifest(
 			if (foreign !== null) {
 				throw new Error(`zerops: manifest variable \`${name}\` references service \`${foreign}\`, which this app does not own`)
 			}
+			assertNoPlatformOnlyReference(value)
 			return value
 		})
+		if (substituted === text) return substituted
 		// Adjacent values can spell a reference neither of them carries alone.
-		const foreign = substituted === text ? null : foreignReferenceHost(substituted, hosts)
+		const foreign = foreignReferenceHost(substituted, hosts)
 		if (foreign !== null) {
 			throw new Error(`zerops: a substituted value references service \`${foreign}\`, which this app does not own`)
 		}
+		assertNoPlatformOnlyReference(substituted)
 		return substituted
 	}
 	const services = document.services.map((service) => substituteRecord(service, resolve))
@@ -450,6 +455,44 @@ const awaitVersion = async (env: StepEnv, appVersionId: string, processId: strin
 	}
 }
 
+const declaredBuckets = (artifact: FabrikaManifest): string[] =>
+	artifact.target.importDocument.services.filter((service) => isObjectStorageType(service.type)).map((service) => service.hostname)
+
+interface CreatedBucket {
+	readonly hostname: string
+	readonly id: string
+}
+
+/** The declared buckets this import reports creating. */
+const createdBucketsOf = (artifact: FabrikaManifest, created: ReadonlyMap<string, string>): CreatedBucket[] =>
+	declaredBuckets(artifact).flatMap((hostname) => {
+		const id = created.get(hostname)
+		return id === undefined ? [] : [{ hostname, id }]
+	})
+
+/**
+ * Record this import's buckets in the provenance marker before any other step can fail: the import's answer is the only
+ * evidence of creation, since a re-apply reports nothing for a service that exists. Merged here, never narrowed;
+ * `write-service-env` sets the verified set. A sensitive marker of an earlier release cannot be merged and is replaced.
+ */
+const recordCreatedBuckets = async (env: StepEnv, buckets: readonly CreatedBucket[], signal: AbortSignal): Promise<void> => {
+	const { zerops, log, run } = env
+	const serviceId = run.target.serviceId
+	try {
+		const records = await zerops.api.listServiceEnv({ serviceId, signal })
+		const recorded = parseStorageProvenance(readableContent(records.find((record) => record.key === STORAGE_PROVENANCE_KEY)))
+		if (buckets.every((bucket) => recorded.has(bucket.id))) return
+		const value = formatStorageProvenance([...recorded, ...buckets.map((bucket) => bucket.id)])
+		await zerops.api.putServiceEnv({ serviceId, key: STORAGE_PROVENANCE_KEY, value, sensitive: false, signal })
+		log(`  ${STORAGE_PROVENANCE_KEY}: recorded the bucket(s) this import created`)
+	} catch (error) {
+		// The run log is then the one record of the evidence; the refusal a later run raises names the remedy.
+		const named = buckets.map((bucket) => `\`${bucket.hostname}\` (${bucket.id})`).join(', ')
+		log(`  [warn] this import created bucket(s) ${named}, but ${STORAGE_PROVENANCE_KEY} on ${serviceId} could not record them`)
+		throw error
+	}
+}
+
 /**
  * The exposure read-back (ADR-0043): before a version can activate, every declared service must read
  * `subdomainAccess: false`, and every object-storage service must be one this import created or the provenance
@@ -463,10 +506,14 @@ const verifyExposure = async (env: StepEnv): Promise<void> => {
 		return
 	}
 	const created = env.attempt.created ?? new Map<string, string>()
-	const buckets = artifact.target.importDocument.services.filter((service) => isObjectStorageType(service.type)).map((service) => service.hostname)
+	const buckets = declaredBuckets(artifact)
 	const records = buckets.length === 0 ? [] : await zerops.api.listServiceEnv({ serviceId: target.serviceId, signal })
-	const marker = readableContent(records.find((record) => record.key === STORAGE_PROVENANCE_KEY))
-	const known = new Set([...parseStorageProvenance(marker), ...(target.createdBuckets ?? [])])
+	const marker = records.find((record) => record.key === STORAGE_PROVENANCE_KEY)
+	const markerState: StorageProvenanceMarker = marker === undefined ? 'absent' : marker.sensitive ? 'sensitive' : 'readable'
+	if (markerState === 'sensitive') {
+		log(`  [warn] ${STORAGE_PROVENANCE_KEY} was written sensitive by an earlier release; it names no bucket until it is rewritten readable`)
+	}
+	const known = new Set([...parseStorageProvenance(readableContent(marker)), ...(target.createdBuckets ?? [])])
 	const findings: ExposureFinding[] = []
 	const bucketIds: string[] = []
 	for (const hostname of manifestServiceHostnames(artifact)) {
@@ -488,7 +535,10 @@ const verifyExposure = async (env: StepEnv): Promise<void> => {
 		if (created.get(hostname) === service.id || known.has(service.id)) {
 			bucketIds.push(service.id)
 		} else {
-			findings.push({ hostname, reason: 'is a bucket the platform did not create private (no provenance); create it through a Fabrika import' })
+			findings.push({
+				hostname,
+				reason: unprovenBucketReason({ bucketId: service.id, deployService: artifact.target.deployService, marker: markerState }),
+			})
 		}
 	}
 	if (findings.length > 0) {
@@ -612,17 +662,27 @@ const runStep = async (spec: ZeropsStep, env: StepEnv): Promise<void> => {
 			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)'}`)
 			attempt.created = createdServices(result)
+			const createdBuckets = createdBucketsOf(artifact, attempt.created)
+			// A cancel may not separate a created bucket from its evidence; only a lost lease stops the step then.
+			const settling = createdBuckets.length === 0 ? signal : followLeaseLoss(signal)
 			// 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` })
+				assertRunning(settling)
+				await waitForProcess({
+					api: zerops.api,
+					processId: process.id,
+					sleep: zerops.sleep,
+					signal: settling,
+					label: `the ${process.service} import`,
+				})
 			}
 			if (pending.length > 0) {
 				log(`  awaited ${pending.length} import process(es)`)
 			}
+			if (createdBuckets.length > 0) await recordCreatedBuckets(env, createdBuckets, settling)
 			return
 		}
 

package/src/service-references.ts

@@ -2,11 +2,17 @@
  * `${<host>_<KEY>}` — Zerops resolves it across services regardless of `envIsolation`, so the host is the boundary.
  * `${RUNTIME_<host>_<KEY>}`, the build-time bridge, counts as a reference to that host until measured otherwise.
  */
-const SERVICE_REFERENCE = /\$\{(?:RUNTIME_)?([a-z0-9]{1,25})_[A-Za-z0-9_]+\}/g
+const SERVICE_REFERENCE = /\$\{(?:RUNTIME_)?([a-z0-9]{1,25})_([A-Za-z0-9_]+)\}/g
 
 /** Namespace services every app in it may reference; the proxy is deliberately not one of them. */
 const SHARED_NAMESPACE_HOSTNAMES: readonly string[] = ['postgres']
 
+/**
+ * Service variables only the platform references: a PostgreSQL service's superuser is the provisioning credential of an
+ * application's database roles (ADR-0017), and on Zerops it shares the container's environment with application code.
+ */
+const PLATFORM_ONLY_SERVICE_KEYS: ReadonlySet<string> = new Set(['superuserpassword'])
+
 /** Hosts named by cross-service references in `text`, deduplicated, in order of first appearance. */
 export function serviceReferenceHosts(text: string): string[] {
 	const hosts: string[] = []
@@ -26,3 +32,23 @@ export function allowedReferenceHosts(ownHostnames: readonly string[]): Readonly
 export function foreignReferenceHost(text: string, allowed: ReadonlySet<string>): string | null {
 	return serviceReferenceHosts(text).find((host) => !allowed.has(host)) ?? null
 }
+
+/**
+ * The first reference in `text` to a service variable only the platform may reference, or null. The key is compared
+ * without case, because whether Zerops resolves one case-insensitively is not measured.
+ */
+export function platformOnlyServiceReference(text: string): string | null {
+	for (const match of text.matchAll(SERVICE_REFERENCE)) {
+		const key = match[2]
+		if (key !== undefined && PLATFORM_ONLY_SERVICE_KEYS.has(key.toLowerCase())) return match[0]
+	}
+	return null
+}
+
+/** Refuse an application value that references a platform-only service variable, naming only the reference. */
+export function assertNoPlatformOnlyReference(text: string): void {
+	const reference = platformOnlyServiceReference(text)
+	if (reference !== null) {
+		throw new Error(`zerops: application configuration references \`${reference}\`, the PostgreSQL superuser's password, which only the platform uses`)
+	}
+}

package/src/types.ts

@@ -92,13 +92,14 @@ export interface ZeropsProxySpec extends Pick<ContractProxyApp, 'endpoints' | 'r
 /**
  * A typed reference to the namespace-owned PostgreSQL service; it never contains its credential.
  *
- * The reference names its DATABASE and its TLS MODE rather than inheriting either from the driver — see
- * `ZEROPS_SHARED_POSTGRES_CONNECTION_STRING` in `./namespace.ts` for what the account proved about both.
+ * The reference names its PORT, its DATABASE and its TLS MODE rather than inheriting any from the driver — see
+ * `ZEROPS_SHARED_POSTGRES_CONNECTION_STRING` in `./namespace.ts` for what the account proved about each. It is the
+ * service user's; a contract application's `FABRIKA_APP_DATABASE_URL` is generated from `hostname` instead.
  */
 export interface ZeropsSharedPostgresBinding {
 	readonly resourceKey: 'service:postgres'
 	readonly hostname: 'postgres'
-	readonly connectionString: '${postgres_connectionTlsString}/${postgres_dbName}?sslmode=require'
+	readonly connectionString: '${postgres_connectionString}/${postgres_dbName}?sslmode=disable'
 }
 
 export type ZeropsNamespaceResourceRequirement = ZeropsSharedPostgresBinding