@fabrika/installation-init 0.8.2 → 0.9.0-cloudflare.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/installation-init",
-	"version": "0.8.2",
+	"version": "0.9.0-cloudflare.1",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -12,12 +12,13 @@
 	},
 	"files": [
 		"src",
-		"!src/**/__tests__/**"
+		"!src/**/__tests__/**",
+		"types"
 	],
 	"exports": {
 		".": {
 			"bun": "./src/index.ts",
-			"types": "./src/index.ts",
+			"types": "./types/src/index.d.ts",
 			"default": "./src/index.ts"
 		}
 	},
@@ -27,8 +28,10 @@
 	},
 	"dependencies": {
 		"zod": "^3.25.76",
-		"@fabrika/app": "0.8.2",
-		"@fabrika/email": "0.8.2",
-		"@fabrika/iam-contract": "0.8.2"
+		"@fabrika/app": "0.9.0-cloudflare.1",
+		"@fabrika/auth-core": "0.9.0-cloudflare.1",
+		"@fabrika/email": "0.9.0-cloudflare.1",
+		"@fabrika/iam-contract": "0.9.0-cloudflare.1",
+		"@fabrika/proxy-core": "0.9.0-cloudflare.1"
 	}
 }

package/src/index.ts

@@ -22,7 +22,9 @@ export {
 } from './environment'
 export { ghRepoExists, hasGhCli } from './gh'
 export { action, detail, fail, info, ok, step, url, warn } from './log'
+export { type IamOAuthConfig, type McpClient, parseMcpClientsJson, platformIamOAuthConfig } from './mcp'
 export { type CommandEnv, describeArgument, readEnv, readFlag, requiredSetting, setting, shellWord } from './options'
+export { assertPinnedTag } from './pin'
 export { confirm } from './prompt'
 export {
 	branchProtectionCommand,
@@ -36,6 +38,21 @@ export {
 	type ProtectionOutcome,
 	protectSidecarBranch,
 } from './protection'
+export {
+	type PlatformHosts,
+	type PlatformOAuthResourceTemplate,
+	type PlatformOAuthScopeGrant,
+	platformOrigin,
+	type PlatformProxyApp,
+	platformProxyAppFor,
+	type PlatformProxyComposition,
+	type PlatformProxyManifest,
+	type PlatformProxyManifestTemplate,
+	type PlatformProxyPlacement,
+	type PlatformProxyService,
+	platformServiceTableDigest,
+	resolvePlatformProxyManifest,
+} from './proxy-manifest'
 export {
 	INITIAL_SCAFFOLD_COMMIT_MESSAGE,
 	REFRESH_SCAFFOLD_COMMIT_MESSAGE,
@@ -44,4 +61,20 @@ export {
 	type SidecarScaffoldInput,
 	type SidecarScaffoldResult,
 } from './scaffold'
+export { generateInstallationSecrets, generateSigningKeys, generateVaultKey, type InstallationSecrets, randomPxKey, randomSecret } from './secrets'
+export { checkedSecretsFilePath, renderSecretsFile, SECRETS_FILE_FLAG, SECRETS_FILE_VARIABLE, writeSecretsFile } from './secrets-file'
+export {
+	deployedServiceEnvironment,
+	type DeployedServiceInput,
+	deriveIamProxySecret,
+	IAM_OAUTH_CONFIG_VARIABLE,
+	INSTALLATION_SECRET_VARIABLES,
+	installationServiceEnvironment,
+	type InstallationServiceInput,
+	type PlatformData,
+	type PlatformPlacementInput,
+	type PlatformService,
+	type PlatformServiceEnvironment,
+	type PlatformStorage,
+} from './service-environment'
 export { attempt, capture, probe, run, type ShellAttempt, type ShellStep } from './shell'

package/src/mcp.ts

@@ -0,0 +1,102 @@
+// MCP authoring, opt-in per installation (ADR-0049).
+//
+// The operator names the MCP clients it trusts; everything else is derived. One input turns on BOTH
+// halves, so they cannot disagree: the console's `oauth` row with its registered resource in the proxy
+// manifest, and IAM's `FABRIKA_IAM_OAUTH_CONFIG`, which issues tokens for exactly that resource.
+
+import { type OAuthManagedClient, type OAuthResourceDto, parseOAuthManagedClient } from '@fabrika/iam-contract'
+import { platformOAuthResourceUris, type PlatformProxyComposition, type PlatformProxyManifestTemplate } from './proxy-manifest'
+
+/** One operator-registered MCP client: its CIMD identity, plus where IAM fetches it when that differs. */
+export interface McpClient extends OAuthManagedClient {
+	readonly metadataUrl?: string
+}
+
+/** The document IAM parses from `FABRIKA_IAM_OAUTH_CONFIG`. */
+export interface IamOAuthConfig {
+	readonly clients: readonly McpClient[]
+	readonly resources: readonly OAuthResourceDto[]
+}
+
+const CLIENT_KEYS = ['provider', 'clientId', 'redirectUris', 'metadataUrl']
+/** IAM's own ceiling: it refuses to boot with more. */
+const MAX_CLIENTS = 16
+
+const isObject = (value: unknown): value is Record<string, unknown> => typeof value === 'object' && value !== null && !Array.isArray(value)
+
+const isHttpsUrl = (value: string): boolean => {
+	try {
+		const url = new URL(value)
+		return url.protocol === 'https:' && url.username === '' && url.password === '' && url.hash === ''
+	} catch {
+		return false
+	}
+}
+
+const parseClient = (value: unknown, index: number): McpClient => {
+	const client = parseOAuthManagedClient(value)
+	if (client === null || !isObject(value) || !Object.keys(value).every((key) => CLIENT_KEYS.includes(key))) {
+		throw new Error(`MCP client ${index} must be { provider: 'claude' | 'chatgpt', clientId: <https URL>, redirectUris: [...], metadataUrl? }`)
+	}
+	const metadataUrl = value['metadataUrl']
+	if (metadataUrl === undefined) {
+		return client
+	}
+	if (typeof metadataUrl !== 'string' || !isHttpsUrl(metadataUrl)) {
+		throw new Error(`MCP client ${index}: metadataUrl must be an https URL`)
+	}
+	return { ...client, metadataUrl }
+}
+
+/**
+ * Parse the operator's MCP client list — a JSON array. Anything malformed, an empty list or a repeated
+ * client id is refused here, before a deploy writes a value IAM would refuse to boot with.
+ */
+export const parseMcpClientsJson = (raw: string): readonly McpClient[] => {
+	let value: unknown
+	try {
+		value = JSON.parse(raw)
+	} catch {
+		throw new Error('the MCP client list is not valid JSON')
+	}
+	if (!Array.isArray(value) || value.length === 0) {
+		throw new Error('the MCP client list must be a non-empty JSON array')
+	}
+	if (value.length > MAX_CLIENTS) {
+		throw new Error(`the MCP client list names more than ${MAX_CLIENTS} clients, which IAM refuses`)
+	}
+	const clients = value.map(parseClient)
+	const ids = new Set(clients.map((client) => client.clientId))
+	if (ids.size !== clients.length) {
+		throw new Error('the MCP client list names one client id twice')
+	}
+	return clients
+}
+
+/** IAM's OAuth configuration for one placed installation: the clients, and one resource per app that serves one. */
+export const platformIamOAuthConfig = (
+	template: PlatformProxyManifestTemplate,
+	composition: PlatformProxyComposition,
+	clients: readonly McpClient[],
+): IamOAuthConfig => {
+	const resources: OAuthResourceDto[] = []
+	for (const app of template.apps) {
+		if (app.oauthResource === undefined) {
+			continue
+		}
+		const { resource } = platformOAuthResourceUris(composition, composition.placement[app.service].hosts, app.oauthResource)
+		resources.push({
+			app: app.id,
+			resource,
+			defaultScopes: [...app.oauthResource.scopes],
+			scopeGrants: app.oauthResource.scopeGrants.map((grant) => ({
+				scope: grant.scope,
+				permissions: grant.actions.map((action) => ({ action })),
+			})),
+		})
+	}
+	if (resources.length === 0) {
+		throw new Error('the platform proxy manifest template declares no OAuth resource for MCP clients to reach')
+	}
+	return { clients, resources }
+}

package/src/pin.ts

@@ -0,0 +1,26 @@
+// The one rule about a sidecar's pin: it names a published TAG of `contember/fabrika-platform`, never a
+// branch. A namespace proxy and an installation both build from tags, so a moving ref would make "which
+// version is this installation running" unanswerable (ADR-0025).
+
+/**
+ * A published release tag: `v` and a semantic version.
+ *
+ * The same shape `scripts/release.ts` accepts, restated rather than imported — that script is not a
+ * package and this check has to hold in a published tarball.
+ */
+const TAG_PATTERN = /^v(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/
+
+/** The pinned ref, or an error naming what was found. A branch is refused, deliberately and loudly. */
+export const assertPinnedTag = (ref: string): string => {
+	const trimmed = ref.trim()
+	if (trimmed === '') {
+		throw new Error('a published fabrika tag is required, for example v0.1.0')
+	}
+	if (!TAG_PATTERN.test(trimmed)) {
+		throw new Error(
+			`\`${trimmed}\` is not a published tag. A sidecar repository pins a TAG such as v0.1.0 and never a branch: `
+				+ 'an installation that tracked a moving ref could not say which version it runs (ADR-0025)',
+		)
+	}
+	return trimmed
+}

package/src/proxy-manifest.ts

@@ -0,0 +1,221 @@
+// The proxy manifest a platform installation is configured with, split into the half that is the same
+// on every installation and the half that is one account's.
+//
+// ── Why a template rather than a `ProxyManifest` with the hosts left out ──────────────────────────
+//
+// `parseProxyManifest` refuses an app that declares no hosts, and rightly — a host-less app is fronted
+// by nothing and protects nothing. So the committed half cannot BE a manifest with empty hosts; it is a
+// type of its own, and `resolvePlatformProxyManifest` is the one way to turn it into the document the
+// proxy parses.
+//
+// ── The split ────────────────────────────────────────────────────────────────────────────────────
+//
+//   template   which apps exist, their ids, the private service each is dialed at, the public listener
+//              each answers on, and their service table. True of every installation of one provider, so the
+//              provider ships it GENERATED (Zerops: `provider-zerops/src/installation/generated/`) and reviewed in
+//              a diff.
+//   placement  the hostnames and the browser-facing scheme. A generated cloud hostname names one
+//              account's project, and a production installation binds custom domains instead, so
+//              whoever is deploying supplies these.
+//
+// Nothing in this file imports the packages that OWN the tables. That is the point of the split:
+// they live in the private service packages and reach a deployed installation as DATA, through the
+// generated artifact, so the published deploy path never depends on a package it cannot resolve.
+
+import { type InstallationEndpointTable, installationTableDigest } from '@fabrika/auth-core'
+import {
+	type InstallationProxyApp,
+	isApplicationEntry,
+	type OAuthProtectedResource,
+	parseProxyManifest,
+	serviceProxyTable,
+} from '@fabrika/proxy-core/manifest'
+
+/** The platform services an installation's proxy fronts. Each name is a service hostname in the topology. */
+export type PlatformProxyService = 'iam' | 'control' | 'operations'
+
+/** The public hostname of each platform service, without a scheme and without a port. */
+export type PlatformHosts = Readonly<Record<PlatformProxyService, string>>
+
+/** `https://<host>` — the origin a browser, a token's `iss` and a return-origin registry all use. */
+export const platformOrigin = (scheme: 'http' | 'https', host: string): string => `${scheme}://${host}`
+
+/** What one OAuth scope lets a token do: the owning app's actions, resolved by IAM at the token endpoint. */
+export interface PlatformOAuthScopeGrant {
+	readonly scope: string
+	readonly actions: readonly string[]
+}
+
+/**
+ * A path an app serves to OAuth clients, protected only on an installation that enables it.
+ *
+ * The resource URI is the app's public origin plus `path`, so the template holds the path and a deploy
+ * binds the origin. Copied from the owning service module by the generator, like `table`.
+ */
+export interface PlatformOAuthResourceTemplate {
+	readonly path: string
+	readonly scopes: readonly string[]
+	readonly scopeGrants: readonly PlatformOAuthScopeGrant[]
+}
+
+/**
+ * One fronted app, in the form that is the same on every installation: protected by its service contract (ADR-0022
+ * "Installation entries"), copied in by the generator and never written by hand.
+ */
+export interface PlatformProxyApp {
+	/** The IAM app id. It is the audience of every token the proxy mints for this app's host. */
+	readonly id: string
+	/** The topology service that answers for it. */
+	readonly service: PlatformProxyService
+	/**
+	 * The proxy's public listener this app answers on.
+	 *
+	 * On a `zerops-subdomain` installation a port IS a hostname — Zerops mints one generated host per
+	 * HTTP port — so this is the only installation-independent half of `hosts`. A custom-domain
+	 * installation ignores it: every domain arrives on one listener and the `Host` header decides.
+	 */
+	readonly port: number
+	/** Where the proxy dials it over the project's private network. */
+	readonly upstream: string
+	/** The service's rows; with an `oauthResource`, the table served when the composition names an authorization server. */
+	readonly table: InstallationEndpointTable
+	/** Present only on an app that can serve OAuth clients; off unless the composition names an authorization server. */
+	readonly oauthResource?: PlatformOAuthResourceTemplate
+	/**
+	 * Present exactly with `oauthResource`: the service's table when it serves no OAuth client. The service picks the
+	 * same one, by the digest the deploy writes beside it (`platformServiceTableDigest`).
+	 */
+	readonly tableWithoutOAuth?: InstallationEndpointTable
+}
+
+/** Everything about an installation's manifest that does not depend on WHICH installation it is. */
+export interface PlatformProxyManifestTemplate {
+	readonly apps: readonly PlatformProxyApp[]
+}
+
+/**
+ * The template's entry for one platform service.
+ *
+ * The app IDS live in the template, so a caller that needs one — the deploy's schema reconcile needs
+ * the console's — reads it from there rather than restating a literal that could drift from the
+ * document the proxy is actually configured with.
+ */
+export const platformProxyAppFor = (
+	template: PlatformProxyManifestTemplate,
+	service: PlatformProxyService,
+): PlatformProxyApp => {
+	const app = template.apps.find((candidate) => candidate.service === service)
+	if (app === undefined) {
+		throw new Error(`the platform proxy manifest template fronts no \`${service}\` service`)
+	}
+	return app
+}
+
+/** Where one app answers in a particular composition. */
+export interface PlatformProxyPlacement {
+	/** Public hostnames, without a port — `parseProxyManifest` refuses a `:port` suffix. */
+	readonly hosts: readonly string[]
+	/** Overrides the private dial address. The local composition runs IAM on a port of its own. */
+	readonly upstream?: string
+}
+
+/** One composition of the platform: a deployed installation, or the local Docker stack. */
+export interface PlatformProxyComposition {
+	/** The scheme the BROWSER speaks to these apps — configuration, never a header (see `ProxyApp.scheme`). */
+	readonly scheme: 'http' | 'https'
+	readonly placement: Readonly<Record<PlatformProxyService, PlatformProxyPlacement>>
+	/**
+	 * The public IAM origin that issues OAuth tokens. Present only when the installation enables MCP
+	 * authoring; absent leaves every `oauthResource` unregistered and serves each service's table without OAuth.
+	 */
+	readonly authorizationServer?: string
+	/** The port browsers reach every app on, when it is not the scheme's default. The local composition's is 18080. */
+	readonly publicPort?: number
+}
+
+/**
+ * The RFC 8707 resource URI and RFC 9728 metadata URL of an app's OAuth resource, bound to the app's
+ * FIRST host: the proxy refuses a resource on a host the app does not answer on.
+ */
+export const platformOAuthResourceUris = (
+	composition: Pick<PlatformProxyComposition, 'scheme' | 'publicPort'>,
+	hosts: readonly string[],
+	template: PlatformOAuthResourceTemplate,
+): { readonly resource: string; readonly resourceMetadata: string } => {
+	const host = hosts[0]
+	if (host === undefined) {
+		throw new Error('an OAuth resource needs a host to stand on')
+	}
+	const origin = composition.publicPort === undefined
+		? `${composition.scheme}://${host}`
+		: `${composition.scheme}://${host}:${composition.publicPort}`
+	return {
+		resource: `${origin}${template.path}`,
+		resourceMetadata: `${origin}/.well-known/oauth-protected-resource${template.path}`,
+	}
+}
+
+const registeredResource = (
+	hosts: readonly string[],
+	template: PlatformOAuthResourceTemplate,
+	composition: PlatformProxyComposition,
+	authorizationServer: string,
+): OAuthProtectedResource => ({
+	...platformOAuthResourceUris(composition, hosts, template),
+	authorizationServers: [authorizationServer],
+	scopesSupported: [...template.scopes],
+})
+
+/** Only an installation that names an authorization server registers the resource and serves its OAuth rows. */
+const resolvedApp = (app: PlatformProxyApp, composition: PlatformProxyComposition): InstallationProxyApp => {
+	const placement = composition.placement[app.service]
+	const hosts = [...placement.hosts]
+	const registered = app.oauthResource === undefined || composition.authorizationServer === undefined
+		? undefined
+		: registeredResource(hosts, app.oauthResource, composition, composition.authorizationServer)
+	const table = registered === undefined ? (app.tableWithoutOAuth ?? app.table) : app.table
+	return {
+		id: app.id,
+		hosts,
+		upstream: placement.upstream ?? app.upstream,
+		scheme: composition.scheme,
+		...serviceProxyTable(table, { oauth: registered !== undefined }),
+		...(registered === undefined ? {} : { oauthResources: [registered] }),
+	}
+}
+
+/**
+ * Bind a template to one composition and get the document the proxy actually parses.
+ *
+ * The result is returned THROUGH `parseProxyManifest`, so a duplicate id, a repeated host or a `:port`
+ * suffix is refused right here instead of at a deployed proxy's next build.
+ */
+export const resolvePlatformProxyManifest = (
+	template: PlatformProxyManifestTemplate,
+	composition: PlatformProxyComposition,
+): PlatformProxyManifest => {
+	const manifest = parseProxyManifest({ apps: template.apps.map((app) => resolvedApp(app, composition)) })
+	// Every platform service is an installation entry, never an application.
+	const services = manifest?.apps.flatMap((app) => isApplicationEntry(app) ? [] : [app]) ?? []
+	if (manifest === null || services.length !== manifest.apps.length) {
+		throw new Error('the resolved platform proxy manifest is not one the proxy would accept')
+	}
+	return { apps: services }
+}
+
+/** The platform proxy's manifest: one installation entry per platform service. */
+export interface PlatformProxyManifest {
+	apps: InstallationProxyApp[]
+}
+
+/**
+ * `FABRIKA_SERVICE_TABLE_DIGEST` for a service: the digest of the table this manifest publishes for it, which the
+ * service compares with its own and refuses to start under another.
+ */
+export const platformServiceTableDigest = (manifest: PlatformProxyManifest, appId: string): string => {
+	const entry = manifest.apps.find((app) => app.id === appId)
+	if (entry === undefined) {
+		throw new Error(`the platform proxy manifest fronts no \`${appId}\``)
+	}
+	return installationTableDigest(entry)
+}

package/src/secrets-file.ts

@@ -0,0 +1,61 @@
+// The operator's local copy of every credential a bring-up creates.
+//
+// A cloud that stores a credential write-only hands nothing back, so this file is the copy the command
+// writes before the first credential 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'
+
+/** `--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 a 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
+}
+
+/**
+ * The file's text: comment lines, then shell-sourceable assignments, named as the commands that read
+ * them name them. `header` is the provider's own lines, each written as a `#` comment.
+ */
+export const renderSecretsFile = (header: readonly string[], assignments: readonly (readonly [string, string])[]): string => {
+	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 [
+		...header.map((line) => `# ${line}`),
+		'# 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/secrets.ts

@@ -0,0 +1,78 @@
+// The credentials a platform installation is seeded with, and their shapes.
+//
+// The shapes are not free choices. Each one is what the consuming code already parses:
+//
+//   • `FABRIKA_IAM_SIGNING_KEYS` is a JSON array of PRIVATE JWKs, index 0 the active signer
+//     (`@fabrika/iam`'s `Signer.fromPrivateJwks`). ES256 / P-256, RFC 7638 thumbprint `kid`.
+//   • A `px_` key is IAM's own credential spelling, and every shared secret must be at least 32
+//     characters or the service refuses to boot — 32 random bytes at base64url is 43.
+//   • The vault KEK is 32 RAW BYTES at base64, not base64url: `@fabrika/control` imports it as an
+//     AES key, and base64url is a different alphabet.
+//
+// Nothing here re-reads an existing value: whether a run generates or reuses one is the provider's flow.
+
+import { createHash, generateKeyPairSync, randomBytes } from 'node:crypto'
+
+/**
+ * A 256-bit secret in base64url, never starting with `-` or `_`.
+ *
+ * The re-roll is copied from `@fabrika/local-stack`'s `prepare.ts` and it is not superstition: a
+ * credential beginning with `-` reads as a FLAG to anything that later takes it on a command line, no
+ * matter how it is quoted. One rolled password beginning with `-` made `mc alias set` print its usage
+ * and loop forever. It costs nothing and removes a bug that appears about one install in sixteen.
+ */
+export const randomSecret = (): string => {
+	for (;;) {
+		const value = randomBytes(32).toString('base64url')
+		if (!value.startsWith('-') && !value.startsWith('_')) {
+			return value
+		}
+	}
+}
+
+/** The `px_` prefix IAM's own credentials carry, so a key looks like what it is wherever it turns up. */
+export const randomPxKey = (): string => `px_${randomSecret()}`
+
+/** The control plane's vault KEK. base64, NOT base64url: the vault imports these bytes as an AES key. */
+export const generateVaultKey = (): string => randomBytes(32).toString('base64')
+
+/**
+ * One ES256 (EC P-256) private JWK with an RFC 7638 thumbprint `kid`, shaped exactly as IAM's
+ * `Signer.fromPrivateJwks` loads it.
+ */
+const generateEs256Jwk = (): JsonWebKey & { kid: string; alg: string; use: string } => {
+	const { privateKey } = generateKeyPairSync('ec', { namedCurve: 'P-256' })
+	const jwk = privateKey.export({ format: 'jwk' })
+	// RFC 7638 thumbprint over the canonical EC members, in lexicographic order (crv, kty, x, y).
+	const thumbprint = createHash('sha256').update(JSON.stringify({ crv: jwk.crv, kty: jwk.kty, x: jwk.x, y: jwk.y })).digest('base64url')
+	return { ...jwk, kid: thumbprint, alg: 'ES256', use: 'sig' }
+}
+
+/** IAM's token-signing material: a JSON array with one ES256 private JWK, index 0 the active signer. */
+export const generateSigningKeys = (): string => JSON.stringify([generateEs256Jwk()])
+
+/** Everything a container installation is seeded with. Several of these are shared by more than one service. */
+export interface InstallationSecrets {
+	/** IAM's token-signing material: a JSON array of ES256 private JWKs, index 0 active. */
+	readonly signingKeys: string
+	/** Authenticates IAM's management `/rpc/*` surface. Held by IAM, control and Operations. */
+	readonly rpcKey: string
+	/** Authenticates IAM's `/auth/mint/*` surface, which the proxy calls on the cold path. */
+	readonly proxyKey: string
+	/** The `px_` admin bearer IAM admits as a synthetic global admin. `platform init` and `admin` take it. */
+	readonly provisioningKey: string
+	/** The catalog credential control and Operations share. No `px_` prefix — it is not an IAM credential. */
+	readonly operationsSyncKey: string
+	/** The control plane's vault KEK: 32 raw bytes at base64. Its loss is unrecoverable by design. */
+	readonly vaultKey: string
+}
+
+/** Roll one installation's secrets. Pure entropy in, no I/O, nothing persisted. */
+export const generateInstallationSecrets = (): InstallationSecrets => ({
+	signingKeys: generateSigningKeys(),
+	rpcKey: randomPxKey(),
+	proxyKey: randomPxKey(),
+	provisioningKey: randomPxKey(),
+	operationsSyncKey: randomSecret(),
+	vaultKey: generateVaultKey(),
+})