@fabrika/provider-zerops 0.3.2 → 0.4.0

package/src/exposure.ts

@@ -0,0 +1,95 @@
+// What a deploy reads back before it lets Zerops activate a version (ADR-0043). An import cannot turn subdomain
+// access on, but an earlier enable survives it, and Zerops has no API to read a bucket policy back. So every declared
+// service must read `subdomainAccess: false`, and every bucket must be one the platform created private.
+
+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.
+ */
+export const STORAGE_PROVENANCE_KEY = 'FABRIKA_STORAGE_PROVENANCE'
+
+const OBJECT_STORAGE_TYPES: ReadonlySet<string> = new Set(['object-storage', 'objectstorage'])
+
+export const isObjectStorageType = (type: string): boolean => OBJECT_STORAGE_TYPES.has(type)
+
+/** The action of the process an import starts for a service it creates (verified live, 2026-10-02). */
+const CREATE_ACTION = 'stack.create'
+
+export const parseStorageProvenance = (value: string | undefined): ReadonlySet<string> =>
+	new Set((value ?? '').split(',').filter((entry) => entry !== ''))
+
+export const formatStorageProvenance = (ids: Iterable<string>): string => [...new Set(ids)].sort().join(',')
+
+/** Hostname → service id of every service this import result reports creating. */
+export const createdServices = (result: ZeropsImportResult): ReadonlyMap<string, string> =>
+	new Map(
+		result.services
+			.filter((service) => service.processes.some((process) => process.actionName === CREATE_ACTION))
+			.map((service) => [service.name, service.id]),
+	)
+
+export interface ExposureFinding {
+	readonly hostname: string
+	readonly reason: string
+}
+
+export const formatExposureFindings = (findings: readonly ExposureFinding[]): string =>
+	`zerops: activation refused; ${findings.map((finding) => `service \`${finding.hostname}\` ${finding.reason}`).join('; ')}`
+
+export interface ExposureAlert {
+	readonly appId: string
+	readonly env: string
+	readonly release: string | null
+	readonly findings: readonly ExposureFinding[]
+}
+
+const DSN_PUBLIC_KEY = /^[0-9a-f]{32}$/
+const DSN_PROJECT = /^\/([1-9][0-9]{0,18})$/
+
+/**
+ * The Operations ingest request that raises the alert: an error event in the application's own Operations project,
+ * which its `new_issue` alert rules deliver. Null for a DSN of any other form. The public key is not a secret, but it
+ * travels only in this request.
+ */
+export function exposureAlertRequest(dsn: string, alert: ExposureAlert, eventId: string): { url: string; body: string } | null {
+	let url: URL
+	try {
+		url = new URL(dsn)
+	} catch {
+		return null
+	}
+	const project = DSN_PROJECT.exec(url.pathname)?.[1]
+	if ((url.protocol !== 'https:' && url.protocol !== 'http:') || !DSN_PUBLIC_KEY.test(url.username) || url.password !== '' || project === undefined) {
+		return null
+	}
+	const endpoint = new URL(`/api/${project}/envelope/`, url.origin)
+	endpoint.searchParams.set('sentry_key', url.username)
+	const event = {
+		event_id: eventId,
+		level: 'fatal',
+		platform: 'other',
+		environment: alert.env,
+		...(alert.release === null ? {} : { release: alert.release }),
+		exception: { values: [{ type: 'FabrikaExposureRefused', value: formatExposureFindings(alert.findings) }] },
+		fingerprint: ['fabrika-exposure-refused', alert.appId, alert.env, ...alert.findings.map((finding) => finding.hostname).sort()],
+	}
+	const body = [JSON.stringify({ event_id: eventId }), JSON.stringify({ type: 'event' }), JSON.stringify(event)].join('\n')
+	return { url: endpoint.toString(), body: `${body}\n` }
+}
+
+export type ExposureAlerter = (input: { readonly dsn: string; readonly alert: ExposureAlert; readonly signal: AbortSignal }) => Promise<void>
+
+/** Send the alert. The caller treats a failure as non-fatal: the refusal stands either way. */
+export const sendExposureAlert: ExposureAlerter = async ({ dsn, alert, signal }) => {
+	const request = exposureAlertRequest(dsn, alert, crypto.randomUUID().replaceAll('-', ''))
+	if (request === null) throw new Error('zerops: the Operations DSN has an unexpected form')
+	const response = await fetch(request.url, {
+		method: 'POST',
+		headers: { 'content-type': 'application/x-sentry-envelope' },
+		body: request.body,
+		signal: AbortSignal.any([signal, AbortSignal.timeout(5000)]),
+	})
+	if (!response.ok) throw new Error(`zerops: the Operations ingest answered ${response.status}`)
+}

package/src/installation/deploy-options.ts

@@ -13,6 +13,7 @@
 // error naming both the flag and the variable that would supply it.
 
 import { describeArgument, readEnv, requiredSetting, setting } from '@fabrika/installation-init'
+import { type McpClient, parseMcpClientsJson } from './mcp'
 import { parsePlatformHosts, parsePlatformScheme } from './placement-options'
 import { readInstallationSourceDir } from './source-options'
 
@@ -35,6 +36,8 @@ export interface PlatformDeployInput {
 	/** The scheme a browser speaks to this installation. `https` unless a local composition says otherwise. */
 	readonly scheme: 'http' | 'https'
 	readonly sourceDir: string
+	/** The MCP clients this installation trusts. Absent leaves MCP authoring off (ADR-0049). */
+	readonly mcpClients?: readonly McpClient[]
 	/** IAM-issued `px_` admin key, used only to reconcile the console's schema. Environment only. */
 	readonly iamAdminKey: string
 	/** Read everything, write nothing, trigger nothing. */
@@ -51,6 +54,7 @@ const FLAGS = [
 	'--operations-host',
 	'--scheme',
 	'--source-dir',
+	'--mcp-clients',
 ] as const
 
 const assertKnownArguments = (argv: readonly string[]): void => {
@@ -109,6 +113,12 @@ export const parsePlatformDeployArgs = (
 	const dryRun = argv.includes('--dry-run')
 	const hosts = readHosts(argv, env)
 	const apiBaseUrl = readEnv(env, 'FABRIKA_ZEROPS_API_URL')
+	const mcpClients = setting(argv, env, '--mcp-clients', 'FABRIKA_PLATFORM_MCP_CLIENTS_JSON')
+	const scheme = readScheme(argv, env)
+	// Control reads a bare `FABRIKA_CONTROL_DOMAIN` as https, so an http resource would never match its own.
+	if (mcpClients !== undefined && scheme === 'http') {
+		throw new Error('MCP clients need --scheme=https: an OAuth resource on plain http would not match the one Control serves')
+	}
 	return {
 		project: readProject(argv, env),
 		// A dry run reads, and reading still needs a token; it is the one credential it cannot do without.
@@ -118,10 +128,11 @@ export const parsePlatformDeployArgs = (
 		iamAdminKey: dryRun
 			? readEnv(env, 'FABRIKA_IAM_PROVISIONING_KEY') ?? ''
 			: requiredSetting(readEnv(env, 'FABRIKA_IAM_PROVISIONING_KEY'), '(no flag)', 'FABRIKA_IAM_PROVISIONING_KEY'),
-		scheme: readScheme(argv, env),
+		scheme,
 		dryRun,
 		...(hosts === undefined ? {} : { hosts }),
 		sourceDir,
 		...(apiBaseUrl === undefined ? {} : { apiBaseUrl }),
+		...(mcpClients === undefined ? {} : { mcpClients: parseMcpClientsJson(mcpClients) }),
 	}
 }

package/src/installation/deploy.ts

@@ -10,7 +10,7 @@
 //     deploying control at a new version while the previous, more permissive manifest is still in
 //     front of it leaves `/api/*` open for the length of the deploy. The sequence is therefore
 //     (IAM + Operations) → **proxy** → control: the two that order nothing against each
-//     other built at once, with the enforcement point ahead of the service whose gates just widened.
+//     other built at once, with the enforcement point ahead of the service whose table just widened.
 //     `__tests__/deploy.test.ts` pins it.
 //
 // Bringing `fabrika-test` to HEAD on 2026-08-05 took `zops push` from a laptop, once per service, in a
@@ -34,7 +34,7 @@
 // "deploy" means, and the platform keeps the previous version serving whenever the new one fails its
 // readiness gate.
 
-import { readEnvironmentName } from '@fabrika/auth-core'
+import { FABRIKA_SERVICE_TABLE_DIGEST, readEnvironmentName } from '@fabrika/auth-core'
 import type { SchemaReconciler } from '@fabrika/provider-contract'
 import { encodeProxyManifestJson, FABRIKA_PROXY_MANIFEST_JSON } from '@fabrika/proxy-core/manifest'
 import {
@@ -62,9 +62,10 @@ import {
 } from './installation-source'
 import type { DeployLog } from './log'
 import { mergePlatformProxyManifest, readLiveProxyManifest } from './manifest'
+import { type IamOAuthConfig, platformIamOAuthConfig } from './mcp'
 import type { PreparedPlatformSource } from './platform-source'
 import { type PlatformUploadFetch, uploadPlatformArchive } from './platform-upload'
-import { platformProxyAppFor, resolvePlatformProxyManifest } from './proxy-manifest'
+import { platformProxyAppFor, type PlatformProxyComposition, platformServiceTableDigest, resolvePlatformProxyManifest } from './proxy-manifest'
 
 /**
  * The four services this command touches, in the order it RESOLVES and WRITES them.
@@ -93,7 +94,7 @@ export type PlatformDeployService = (typeof PLATFORM_DEPLOY_ORDER)[number]
  *
  * What is NOT arbitrary stays: every environment write happens before any of these starts, the proxy
  * is deployed after both, and control after the proxy (ADR-0022 — the enforcement point ahead of
- * the service whose gates just widened). `deploy-order.test.ts` in `@fabrika/platform-artifacts` and
+ * the service whose table just widened). `deploy-order.test.ts` in `@fabrika/platform-artifacts` and
  * `__tests__/deploy.test.ts` fail if that sequence changes.
  */
 export const PLATFORM_CONCURRENT_DEPLOY = ['iam', 'operations'] as const
@@ -268,29 +269,36 @@ const resolvePlacement = (input: PlatformDeployInput, proxyEnv: ReadonlyMap<stri
 	return { hosts: derivePlatformHosts(subdomains, listeners), scheme: input.scheme, zeropsSubdomain: true }
 }
 
+const IAM_OAUTH_CONFIG = 'FABRIKA_IAM_OAUTH_CONFIG'
+
 /**
  * The per-installation configuration each service needs, derived from the resolved hosts.
  *
  * The namespace source default comes from the verified snapshot. Values are compared but never logged.
+ * IAM's OAuth configuration is written only when MCP authoring is enabled; without it the variable is
+ * left as it is, and the manifest — whose `/mcp` row then admits no OAuth token — is what turns MCP off.
  */
 const desiredServiceEnv = (
 	environment: string,
 	placement: PlatformPlacement,
 	manifestJson: string,
 	proxySource: ZeropsNamespaceProxySource,
+	oauthConfig: IamOAuthConfig | undefined,
+	controlTableDigest: string,
 ): ReadonlyMap<PlatformDeployService, ReadonlyMap<string, string>> => {
 	const iamOrigin = platformOrigin(placement.scheme, placement.hosts.iam)
 	const operationsOrigin = platformOrigin(placement.scheme, placement.hosts.operations)
+	const iam = new Map([
+		['ENVIRONMENT', environment],
+		// The `iss` of every minted token AND the OIDC redirect base, so it must be the address
+		// routed to the proxy in front of this service.
+		['ISSUER', iamOrigin],
+	])
+	if (oauthConfig !== undefined) {
+		iam.set(IAM_OAUTH_CONFIG, JSON.stringify(oauthConfig))
+	}
 	return new Map<PlatformDeployService, ReadonlyMap<string, string>>([
-		[
-			'iam',
-			new Map([
-				['ENVIRONMENT', environment],
-				// The `iss` of every minted token AND the OIDC redirect base, so it must be the address
-				// routed to the proxy in front of this service.
-				['ISSUER', iamOrigin],
-			]),
-		],
+		['iam', iam],
 		[
 			'operations',
 			new Map([
@@ -316,9 +324,11 @@ const desiredServiceEnv = (
 				[FABRIKA_ZEROPS_PROXY_SOURCE_JSON, serializeNamespaceProxySource(proxySource)],
 				['ENVIRONMENT', environment],
 				['FABRIKA_IAM_ISSUER', iamOrigin],
-				// A bare host: `controlPublicOrigin` accepts either spelling, and this is also what the
-				// same-origin check on both first-party gateways is decided against.
+				// A bare host: `controlPublicOrigin` accepts either spelling.
 				['FABRIKA_CONTROL_DOMAIN', placement.hosts.control],
+				// The digest of the console table the proxy above publishes: Control picks its own table, MCP or not,
+				// by it, and refuses to start under another, so the two cannot disagree at runtime.
+				[FABRIKA_SERVICE_TABLE_DIGEST, controlTableDigest],
 				['OPERATIONS_ARTIFACT_ORIGIN', operationsOrigin],
 				// The public IAM origin an APPLICATION project's proxy reaches — there is no private
 				// network between projects (ADR-0006).
@@ -589,14 +599,24 @@ export const deployPreparedPlatform = async (
 	log.info(`iam ${placement.hosts.iam} · operations ${placement.hosts.operations}`)
 
 	log.step('Compose the proxy manifest')
-	const platformManifest = resolvePlatformProxyManifest(PLATFORM_PROXY_MANIFEST_TEMPLATE, {
+	const composition: PlatformProxyComposition = {
 		scheme: placement.scheme,
 		placement: {
 			iam: { hosts: [placement.hosts.iam] },
 			control: { hosts: [placement.hosts.control] },
 			operations: { hosts: [placement.hosts.operations] },
 		},
-	})
+		...(input.mcpClients === undefined ? {} : { authorizationServer: platformOrigin(placement.scheme, placement.hosts.iam) }),
+	}
+	const platformManifest = resolvePlatformProxyManifest(PLATFORM_PROXY_MANIFEST_TEMPLATE, composition)
+	const oauthConfig = input.mcpClients === undefined
+		? undefined
+		: platformIamOAuthConfig(PLATFORM_PROXY_MANIFEST_TEMPLATE, composition, input.mcpClients)
+	log.info(
+		oauthConfig === undefined
+			? 'MCP authoring: off'
+			: `MCP authoring: on, ${oauthConfig.clients.length} client(s), resource(s) ${oauthConfig.resources.map((entry) => entry.resource).join(', ')}`,
+	)
 	const merged = mergePlatformProxyManifest(platformManifest, readLiveProxyManifest(proxyEnv.get(FABRIKA_PROXY_MANIFEST_JSON)))
 	log.info(`${merged.manifest.apps.length} app(s): ${merged.manifest.apps.map((app) => app.id).join(', ')}`)
 	if (merged.carried.length > 0) {
@@ -610,11 +630,15 @@ export const deployPreparedPlatform = async (
 	}
 
 	log.step('Write the service environment')
-	const desired = desiredServiceEnv(environment, placement, encodeProxyManifestJson(merged.manifest), proxySource)
+	const controlTableDigest = platformServiceTableDigest(platformManifest, platformProxyAppFor(PLATFORM_PROXY_MANIFEST_TEMPLATE, 'control').id)
+	const desired = desiredServiceEnv(environment, placement, encodeProxyManifestJson(merged.manifest), proxySource, oauthConfig, controlTableDigest)
 	for (const hostname of PLATFORM_DEPLOY_ORDER) {
 		const service = serviceOf(services, hostname)
 		const live = hostname === PLATFORM_PROXY_SERVICE ? proxyEnv : await readServiceEnv(service.id, collaborators)
 		const keys = desired.get(hostname) ?? new Map<string, string>()
+		if (hostname === 'iam' && oauthConfig === undefined && (live.get(IAM_OAUTH_CONFIG) ?? '').trim() !== '') {
+			log.warn(`iam: MCP authoring is off but ${IAM_OAUTH_CONFIG} is still set; IAM keeps issuing MCP tokens until it is removed`)
+		}
 		const written = await applyServiceEnv(service, keys, live, input, collaborators)
 		log.info(
 			written.length === 0

package/src/installation/generated/platform-console-schema.ts

@@ -22,6 +22,10 @@ export const PLATFORM_CONSOLE_APP_SCHEMA: AppSchema = {
 		{ action: 'namespace.manage', description: 'Manage deployment namespaces' },
 		{ action: 'secret.manage', description: 'Manage secret values + their references' },
 		{ action: 'source.connection.manage', description: 'Manage the platform GitHub source connection' },
+		{ action: 'source.workspace.read', description: 'Read own Git workspaces on an authoring target' },
+		{ action: 'source.workspace.write', description: 'Create and commit to own Git workspaces on an authoring target' },
+		{ action: 'source.pull-request.create', description: 'Open a pull request from an own Git workspace' },
+		{ action: 'access.approve', description: 'Approve an access change and protect an environment (a person in the console only)' },
 		{ action: 'operations.read', description: 'Read Operations errors and activity' },
 		{ action: 'operations.triage', description: 'Triage Operations errors' },
 		{ action: 'operations.manage', description: 'Manage Operations sources, alerts, and retention' },