@fabrika/provider-zerops 0.3.2 → 0.4.0

package/src/installation/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/installation/placement-options.ts

@@ -1,10 +1,11 @@
 import { z } from 'zod'
 
 const scheme = z.enum(['http', 'https']).default('https')
+// Lowercased because every consumer compares origins as `URL` writes them, and `URL` lowercases the host.
 const bareHostname = z.string().refine(
 	(host) => !host.includes('/') && !host.includes(':'),
 	(host) => ({ message: `\`${host}\` is not a bare hostname — a platform host carries no scheme and no port` }),
-)
+).transform((host) => host.toLowerCase())
 const hosts = z.object({ iam: bareHostname, control: bareHostname, operations: bareHostname })
 
 export const parsePlatformScheme = (raw: string | undefined): 'http' | 'https' => {

package/src/installation/proxy-manifest.ts

@@ -4,30 +4,57 @@
 // ── 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 gates nothing. So the committed half cannot BE a manifest with empty hosts; it is a
+// 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 gates. True of every installation, so it is GENERATED into
+//              each answers on, and their service table. True of every installation, so it is GENERATED into
 //              `src/generated/` and reviewed in a diff.
 //   placement  the hostnames and the browser-facing scheme. `proxy-292c-8080.prg1.zerops.app` 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 gates. That is the point of the split: the
-// gate sets live in `@fabrika/control` (private) and reach a deployed installation as DATA, through the
+// 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 { AppGates } from '@fabrika/auth-core'
-import { parseProxyManifest, type ProxyManifest } from '@fabrika/proxy-core/manifest'
+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'
 
-/** One fronted app, in the form that is the same on every installation. */
+/** 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
@@ -43,8 +70,15 @@ export interface PlatformProxyApp {
 	readonly port: number
 	/** Where the proxy dials it over the project's private network. */
 	readonly upstream: string
-	/** Owned by the service's own gate module and copied in by the generator. Never written by hand. */
-	readonly gates: AppGates
+	/** 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. */
@@ -83,6 +117,64 @@ 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] }),
+	}
 }
 
 /**
@@ -94,20 +186,29 @@ export interface PlatformProxyComposition {
 export const resolvePlatformProxyManifest = (
 	template: PlatformProxyManifestTemplate,
 	composition: PlatformProxyComposition,
-): ProxyManifest => {
-	const apps = template.apps.map((app) => {
-		const placement = composition.placement[app.service]
-		return {
-			id: app.id,
-			hosts: [...placement.hosts],
-			upstream: placement.upstream ?? app.upstream,
-			gates: app.gates,
-			scheme: composition.scheme,
-		}
-	})
-	const manifest = parseProxyManifest({ apps })
-	if (manifest === null) {
+): 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 manifest
+	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/installation/secrets.ts

@@ -55,9 +55,9 @@ const generateEs256Jwk = (): JsonWebKey & { kid: string; alg: string; use: strin
 export interface InstallationSecrets {
 	/** IAM's token-signing material: a JSON array of ES256 private JWKs, index 0 active. */
 	readonly signingKeys: string
-	/** Gates IAM's management `/rpc/*` surface. Held by IAM, control and Operations. */
+	/** Authenticates IAM's management `/rpc/*` surface. Held by IAM, control and Operations. */
 	readonly rpcKey: string
-	/** Gates IAM's `/auth/mint/*` surface, which the proxy calls on the cold path. */
+	/** 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. The one value this command prints. */
 	readonly provisioningKey: string

package/src/installation/templates/README.md

@@ -30,7 +30,7 @@ resolve the project and its services
 ```
 
 That order is a security property, not just a dependency: a fabrika application enforces nothing by
-itself, so the enforcement proxy is deployed **before** the control plane whose gates just changed. It
+itself, so the enforcement proxy is deployed **before** the control plane whose endpoint table just changed. It
 therefore lives in code with a test, rather than in a workflow file that can be edited. The Cloudflare
 sidecar repository keeps its order in the workflow instead; the two providers differ deliberately.
 
@@ -45,7 +45,7 @@ permissive manifest.
 branch. The workflow refuses anything that does not look like a tag.
 
 That tag decides everything this pipeline DOES: the deploy order, the proxy manifest it composes (the
-gate rules that enforce the whole installation), the console schema it reconciles, and every variable
+endpoint tables that enforce the whole installation), the console schema it reconciles, and every variable
 it writes.
 
 The workflow runs with `--source-dir=.` from the selected checkout and uploads one exact committed
@@ -81,21 +81,30 @@ installation already holds.
 
 **Variables** — the rest of the configuration, all non-secret.
 
-| Variable                           | Required | What it is                                                                                         |
-| ---------------------------------- | -------- | -------------------------------------------------------------------------------------------------- |
-| `FABRIKA_ZEROPS_PROJECT_ID`        | yes      | The Zerops project holding the four platform runtime services.                                     |
-| `FABRIKA_PLATFORM_ENVIRONMENT`     | yes      | The name this installation calls itself; written to every service as `ENVIRONMENT`. Never `local`. |
-| `FABRIKA_PLATFORM_SCHEME`          | yes      | `https` for anything reachable from a browser.                                                     |
-| `FABRIKA_PLATFORM_IAM_HOST`        | no       | Where IAM answers publicly.                                                                        |
-| `FABRIKA_PLATFORM_CONSOLE_HOST`    | no       | Where the console answers publicly.                                                                |
-| `FABRIKA_PLATFORM_OPERATIONS_HOST` | no       | Where Operations ingest answers publicly.                                                          |
-| `FABRIKA_ZEROPS_API_URL`           | no       | Region API base, when this installation is not on the default one.                                 |
+| Variable                            | Required | What it is                                                                                         |
+| ----------------------------------- | -------- | -------------------------------------------------------------------------------------------------- |
+| `FABRIKA_ZEROPS_PROJECT_ID`         | yes      | The Zerops project holding the four platform runtime services.                                     |
+| `FABRIKA_PLATFORM_ENVIRONMENT`      | yes      | The name this installation calls itself; written to every service as `ENVIRONMENT`. Never `local`. |
+| `FABRIKA_PLATFORM_SCHEME`           | yes      | `https` for anything reachable from a browser.                                                     |
+| `FABRIKA_PLATFORM_IAM_HOST`         | no       | Where IAM answers publicly.                                                                        |
+| `FABRIKA_PLATFORM_CONSOLE_HOST`     | no       | Where the console answers publicly.                                                                |
+| `FABRIKA_PLATFORM_OPERATIONS_HOST`  | no       | Where Operations ingest answers publicly.                                                          |
+| `FABRIKA_ZEROPS_API_URL`            | no       | Region API base, when this installation is not on the default one.                                 |
+| `FABRIKA_PLATFORM_MCP_CLIENTS_JSON` | no       | The MCP clients that may author applications (JSON array). Unset leaves MCP authoring off.         |
 
 The three host variables go together: **all three, or none.** Naming none derives them from the
 proxy's generated Zerops subdomains, and the deploy publishes that subdomain. Naming all three makes
 this a custom-domain installation — the domains are bound to the project balancer out of band, and the
 deploy publishes no subdomain, because that would add a second public address nobody asked for.
 
+`FABRIKA_PLATFORM_MCP_CLIENTS_JSON` turns on MCP authoring (ADR-0049). A workflow generated before
+that variable existed does not forward it, and `platform upgrade` never rewrites the workflow — add
+this line to the `env:` of the _Deploy the platform_ step in `.github/workflows/platform.yml`:
+
+```yaml
+FABRIKA_PLATFORM_MCP_CLIENTS_JSON: ${{ vars.FABRIKA_PLATFORM_MCP_CLIENTS_JSON }}
+```
+
 There is deliberately **no bootstrap-admin variable here.** This pipeline writes no credential and no
 admission list — it configures where the installation answers and deploys it. Who may administer the
 installation is IAM's to say, and it is said through IAM's own admin surface. Nothing about this

package/src/installation/templates/platform.yml

@@ -129,6 +129,8 @@ jobs:
           FABRIKA_PLATFORM_OPERATIONS_HOST: ${{ vars.FABRIKA_PLATFORM_OPERATIONS_HOST }}
           # Only for an installation outside the default region.
           FABRIKA_ZEROPS_API_URL: ${{ vars.FABRIKA_ZEROPS_API_URL }}
+          # MCP authoring (ADR-0049): a JSON array of the MCP clients this installation trusts. Unset = off.
+          FABRIKA_PLATFORM_MCP_CLIENTS_JSON: ${{ vars.FABRIKA_PLATFORM_MCP_CLIENTS_JSON }}
         run: fabrika platform deploy --provider=zerops --source-dir=. ${{ inputs.dry_run && '--dry-run' || '' }}
 
       - name: Summary

package/src/installation/topology/setups.ts

@@ -174,9 +174,9 @@ const WORKSPACE_DEPLOY_FILES = ['package.json', 'bun.lock', 'node_modules', 'pac
  *
  * Secrets (`envSecrets`): `FABRIKA_IAM_SIGNING_KEYS` (ES256 private JWKs — an empty value is refused at
  * boot rather than silently issuing ephemeral tokens), `OIDC_CLIENT_SECRET` when OIDC is enabled,
- * `FABRIKA_EMAIL_RESEND_API_KEY` when Resend is enabled, `FABRIKA_IAM_RPC_KEY` (gates
+ * `FABRIKA_EMAIL_RESEND_API_KEY` when Resend is enabled, `FABRIKA_IAM_RPC_KEY` (authenticates
  * the management `/rpc/*` surface; unset 404s it, which is the fail-closed default), `FABRIKA_IAM_PROXY_KEY`
- * (gates `/auth/mint/*`, which the proxy calls on the cold path — a SEPARATE secret by least privilege,
+ * (authenticates `/auth/mint/*`, which the proxy calls on the cold path — a SEPARATE secret by least privilege,
  * since the proxy is the only publicly routed component and must not also be able to write audit rows),
  * `FABRIKA_IAM_PROVISIONING_KEY`. Both shared secrets must be at least 32 characters; a shorter one fails
  * the boot rather than standing in front of an internet-reachable surface while looking configured.
@@ -318,7 +318,7 @@ const operations: ZeropsYamlSetupSpec = {
 
 /**
  * The auth enforcement proxy — Caddy for HTTP correctness, a compiled Bun auth service for every
- * authorization decision (ADR-0022, as amended by ADR-0022: gates are NEVER compiled into Caddy routes).
+ * authorization decision (ADR-0022: the endpoint table is NEVER compiled into Caddy routes).
  *
  * This is the only setup deployed into BOTH projects, and the only publicly routed service in either.
  *
@@ -330,7 +330,7 @@ const operations: ZeropsYamlSetupSpec = {
  *
  * ── How the manifest reaches the build, and what is unverified about it ───────────────────────────
  *
- * `proxy.manifest.json` tells the proxy which apps it fronts, at which upstream, under which gates. It
+ * `proxy.manifest.json` tells the proxy which apps it fronts, at which upstream, under which endpoint table. It
  * is baked into the artifact at BUILD time, which is what `docs/backlog/08` chose ("redeploy") over
  * pushing to Caddy's admin API. But on Zerops fabrika has no filesystem in the deploy path — a Zerops
  * deploy is five HTTP calls (ADR-0003) — so the driver cannot write a file into the build the way the
@@ -427,7 +427,7 @@ const proxy: ZeropsYamlSetupSpec = {
 		base: 'alpine@3.21',
 		ports: PROXY_PUBLIC_PORTS.map((port) => ({ port, httpSupport: true })),
 		// Deliberately NOT one of the public ports: a health path on a public listener would be one path per
-		// proxy that answers 200 without consulting the gates, and would shadow an app path of the same name.
+		// proxy that answers 200 without consulting the endpoint table, and would shadow an app path of the same name.
 		healthCheck: { httpGet: { port: PROXY_HEALTH_PORT, path: '/healthz' }, ...LIVENESS },
 		envVariables: {
 			FABRIKA_PROXY_MANIFEST: '/var/www/proxy.manifest.json',

package/src/managed-env.ts

@@ -1,3 +1,12 @@
+import {
+	FRAMEWORK_VARIABLE_PREFIXES,
+	type FrameworkVariableName,
+	frameworkVariableReference,
+	isConnectKeyVariable,
+	isConnectUrlVariable,
+	isFrameworkVariableName,
+	isWorkloadKeyVariable,
+} from '@fabrika/auth-core'
 import type { JsonValue } from '@fabrika/provider-contract'
 import { z } from 'zod'
 import { renderYaml } from './compile'
@@ -9,30 +18,45 @@ import {
 	selectZeropsDescriptorSetup,
 } from './descriptor'
 
-export type ManagedKey =
+/** The framework-only names Control hands every Zerops deploy; the rest of the list is the provider's own. */
+export type ManagedKey = Extract<
+	FrameworkVariableName,
 	| 'FABRIKA_RELEASE'
 	| 'FABRIKA_OPERATIONS_DSN'
 	| 'FABRIKA_IAM_ISSUER'
+	| 'FABRIKA_IAM_APP_ID'
 	| 'FABRIKA_APP_ID'
 	| 'FABRIKA_ENVIRONMENT'
 	| 'FABRIKA_SERVICE_KEY'
+	| 'FABRIKA_PROXY_SECRET'
+	| 'FABRIKA_IAM_RPC_URL'
+	| 'FABRIKA_IAM_RPC_KEY'
+>
 
 export const MANAGED_KEYS: readonly ManagedKey[] = [
 	'FABRIKA_RELEASE',
 	'FABRIKA_OPERATIONS_DSN',
 	'FABRIKA_IAM_ISSUER',
+	'FABRIKA_IAM_APP_ID',
 	'FABRIKA_APP_ID',
 	'FABRIKA_ENVIRONMENT',
 	'FABRIKA_SERVICE_KEY',
+	'FABRIKA_PROXY_SECRET',
+	'FABRIKA_IAM_RPC_URL',
+	'FABRIKA_IAM_RPC_KEY',
 ]
 
 /** The managed keys written as service variables; `FABRIKA_RELEASE` travels only in the execution descriptor (ADR-0044). */
 export const SERVICE_MANAGED_KEYS: readonly Exclude<ManagedKey, 'FABRIKA_RELEASE'>[] = [
 	'FABRIKA_OPERATIONS_DSN',
 	'FABRIKA_IAM_ISSUER',
+	'FABRIKA_IAM_APP_ID',
 	'FABRIKA_APP_ID',
 	'FABRIKA_ENVIRONMENT',
 	'FABRIKA_SERVICE_KEY',
+	'FABRIKA_PROXY_SECRET',
+	'FABRIKA_IAM_RPC_URL',
+	'FABRIKA_IAM_RPC_KEY',
 ]
 
 export type ManagedValues = Record<ManagedKey, string | null>
@@ -41,31 +65,91 @@ const managedValuesSchema = z.object({
 	FABRIKA_RELEASE: z.string().nullable(),
 	FABRIKA_OPERATIONS_DSN: z.string().nullable(),
 	FABRIKA_IAM_ISSUER: z.string().nullable(),
+	FABRIKA_IAM_APP_ID: z.string().nullable(),
 	FABRIKA_APP_ID: z.string().nullable(),
 	FABRIKA_ENVIRONMENT: z.string().nullable(),
 	FABRIKA_SERVICE_KEY: z.string().nullable(),
+	FABRIKA_PROXY_SECRET: z.string().nullable(),
+	// IAM's membership transport (ADR-0022 rule 6): its public origin and this environment's key, or both null.
+	FABRIKA_IAM_RPC_URL: z.string().nullable(),
+	FABRIKA_IAM_RPC_KEY: z.string().nullable(),
 }).strict()
 
 export function parseManagedValues(value: unknown): ManagedValues {
 	const result = managedValuesSchema.safeParse(value)
-	if (!result.success) throw new Error('zerops: managed environment must name exactly the six managed keys')
+	if (!result.success) throw new Error('zerops: managed environment must name exactly the ten managed keys')
 	return result.data
 }
 
-const isManagedKey = (name: string): boolean => MANAGED_KEYS.some((key) => key === name)
+/**
+ * What Control hands a deploy: the ten managed keys, the key of each job and webhook of the approved contract, and the
+ * key and owner origin of each connector import.
+ */
+export interface ManagedEnvironment {
+	readonly values: ManagedValues
+	/** `FABRIKA_<KIND>_<NAME>_KEY` → the workload's `px_` key, and `FABRIKA_CONNECT_<IMPORT>_KEY` / `_URL`. */
+	readonly familyVariables: Readonly<Record<string, string>>
+}
+
+const keySchema = z.string().startsWith('px_').min(4)
+const originSchema = z.string().refine((value) => {
+	try {
+		return new URL(value).origin === value && value.startsWith('https://')
+	} catch {
+		return false
+	}
+})
+
+export function parseManagedEnvironment(value: Readonly<Record<string, string | null>>): ManagedEnvironment {
+	const managed: Record<string, string | null> = {}
+	const familyVariables: Record<string, string> = {}
+	for (const [name, entry] of Object.entries(value)) {
+		if (!isFrameworkFamilyVariable(name)) {
+			managed[name] = entry
+			continue
+		}
+		const origin = isConnectUrlVariable(name)
+		if (!origin && !isWorkloadKeyVariable(name) && !isConnectKeyVariable(name)) {
+			throw new Error(`zerops: ${name} is not a variable a deploy writes`)
+		}
+		const parsed = (origin ? originSchema : keySchema).safeParse(entry)
+		if (!parsed.success) {
+			throw new Error(`zerops: ${name} must be ${origin ? 'an https origin' : 'a px_ key'}`)
+		}
+		familyVariables[name] = parsed.data
+	}
+	return { values: parseManagedValues(managed), familyVariables }
+}
+
+/** A service variable only the platform writes per workload or import: a stale one is removed with it. */
+export function isFrameworkFamilyVariable(name: string): boolean {
+	return FRAMEWORK_VARIABLE_PREFIXES.some((prefix) => name.startsWith(prefix))
+}
 
 const refuse = (): never => {
 	throw new Error('zerops: application configuration uses a Fabrika-managed environment name')
 }
 
+/** Refuse every framework-only name (ADR-0043), not only the ones a deploy writes today. */
 export function assertAuthoredManagedName(name: string): void {
-	if (isManagedKey(name)) refuse()
+	if (isFrameworkVariableName(name)) refuse()
 }
 
 type AuthoredDocumentValue = string | number | boolean | null | readonly AuthoredDocumentValue[] | { readonly [key: string]: AuthoredDocumentValue }
 const isSequence = (value: AuthoredDocumentValue): value is readonly AuthoredDocumentValue[] => Array.isArray(value)
 
-/** Refuse a managed name as a key of any `envVariables`/`envSecrets` mapping, at any depth. */
+/** Refuse a value that references a framework-only variable (`${RUNTIME_FABRIKA_PROXY_SECRET}`), naming only the reference. */
+export function assertNoFrameworkReference(text: string): void {
+	const reference = frameworkVariableReference(text)
+	if (reference !== null) {
+		throw new Error(`zerops: application configuration references the Fabrika-managed variable \`${reference}\``)
+	}
+}
+
+/**
+ * Refuse, in any `envVariables`/`envSecrets` mapping at any depth, a managed name as a key and a reference to one in a
+ * key or a value: Zerops resolves the reference into a variable the application controls, and lifts it into a build.
+ */
 export function assertAuthoredManagedDocument(value: AuthoredDocumentValue): void {
 	const visit = (entry: AuthoredDocumentValue, environmentMapping: boolean): void => {
 		if (isSequence(entry)) {
@@ -74,7 +158,11 @@ export function assertAuthoredManagedDocument(value: AuthoredDocumentValue): voi
 		}
 		if (typeof entry !== 'object' || entry === null) return
 		for (const [key, item] of Object.entries(entry)) {
-			if (environmentMapping) assertAuthoredManagedName(key)
+			if (environmentMapping) {
+				assertAuthoredManagedName(key)
+				assertNoFrameworkReference(key)
+				if (typeof item === 'string') assertNoFrameworkReference(item)
+			}
 			visit(item, key === 'envVariables' || key === 'envSecrets')
 		}
 	}