@fabrika/provider-zerops 0.0.8 → 0.0.9

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/provider-zerops",
-	"version": "0.0.8",
+	"version": "0.0.9",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -32,9 +32,9 @@
 		"gen:schema": "bun scripts/generate-zerops-types.ts"
 	},
 	"dependencies": {
-		"@fabrika/auth": "^0.0.8",
-		"@fabrika/auth-core": "^0.0.8",
-		"@fabrika/provider-contract": "^0.0.8",
-		"@fabrika/proxy-contract": "^0.0.8"
+		"@fabrika/auth": "^0.0.9",
+		"@fabrika/auth-core": "^0.0.9",
+		"@fabrika/provider-contract": "^0.0.9",
+		"@fabrika/proxy-contract": "^0.0.9"
 	}
 }

package/src/api.ts

@@ -445,6 +445,8 @@ export interface ZeropsApi {
 	 * NOT `GET /service-stack/{id}/user-data`, which answers `400 serviceStackNotFound` on every
 	 * service, deployed or not — see `docs/reference/zerops-platform.md`. The `/env` reading omits
 	 * variables the service's own `zerops.yaml` declares (`type: ENV`); fabrika never writes those.
+	 * The OpenAPI publishes no lookup/pagination terms and live probes found query terms ignored, so the
+	 * implementation reads one full response under a byte bound rather than imposing an entry-count cap.
 	 */
 	listServiceEnv(input: { serviceId: string; signal: AbortSignal }): Promise<ZeropsServiceEnv[]>
 
@@ -785,6 +787,58 @@ export const createZeropsApi = (options: ZeropsApiOptions): ZeropsApi => {
 	const doFetch = options.fetchImpl ?? fetch
 	const abortError = (): DOMException => new DOMException('The operation was aborted', 'AbortError')
 	const isAbortError = (error: unknown): boolean => error instanceof Error && error.name === 'AbortError'
+	const SERVICE_ENV_RESPONSE_MAX_BYTES = 8 * 1024 * 1024
+	class ResponseByteBoundError extends Error {}
+
+	const boundedJson = async (response: Response, label: string, maxBytes: number, signal: AbortSignal): Promise<unknown> => {
+		if (signal.aborted) {
+			void response.body?.cancel().catch(() => {})
+			throw abortError()
+		}
+		const contentLength = response.headers.get('content-length')
+		if (contentLength !== null) {
+			const declaredBytes = Number(contentLength)
+			if (Number.isFinite(declaredBytes) && declaredBytes > maxBytes) {
+				void response.body?.cancel().catch(() => {})
+				throw new ResponseByteBoundError(`zerops: ${label} response exceeded its byte bound`)
+			}
+		}
+		if (response.body === null) return null
+		const reader = response.body.getReader()
+		let abortRead = (): void => {}
+		const aborted = new Promise<never>((_resolve, reject) => {
+			abortRead = (): void => {
+				void reader.cancel().catch(() => {})
+				reject(abortError())
+			}
+			signal.addEventListener('abort', abortRead, { once: true })
+			if (signal.aborted) abortRead()
+		})
+		const chunks: Uint8Array[] = []
+		let receivedBytes = 0
+		try {
+			while (true) {
+				const next = await Promise.race([reader.read(), aborted])
+				if (signal.aborted) throw abortError()
+				if (next.done) break
+				receivedBytes += next.value.byteLength
+				if (receivedBytes > maxBytes) {
+					void reader.cancel().catch(() => {})
+					throw new ResponseByteBoundError(`zerops: ${label} response exceeded its byte bound`)
+				}
+				chunks.push(next.value)
+			}
+		} finally {
+			signal.removeEventListener('abort', abortRead)
+		}
+		const bytes = new Uint8Array(receivedBytes)
+		let offset = 0
+		for (const chunk of chunks) {
+			bytes.set(chunk, offset)
+			offset += chunk.byteLength
+		}
+		return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes))
+	}
 
 	const request = async (
 		label: string,
@@ -797,7 +851,13 @@ export const createZeropsApi = (options: ZeropsApiOptions): ZeropsApi => {
 		 * `omitErrorResponseDetails` also drops the code for upload flows whose response may carry a
 		 * credential; nothing from that response body may reach an error.
 		 */
-		init: { body?: unknown; signal: AbortSignal; redactDetail?: boolean; omitErrorResponseDetails?: boolean },
+		init: {
+			body?: unknown
+			signal: AbortSignal
+			redactDetail?: boolean
+			omitErrorResponseDetails?: boolean
+			responseMaxBytes?: number
+		},
 	): Promise<unknown> => {
 		if (init.signal.aborted) {
 			throw abortError()
@@ -820,9 +880,12 @@ export const createZeropsApi = (options: ZeropsApiOptions): ZeropsApi => {
 		}
 		let payload: unknown
 		try {
-			payload = await response.json()
+			payload = init.responseMaxBytes === undefined
+				? await response.json()
+				: await boundedJson(response, label, init.responseMaxBytes, init.signal)
 		} catch (error) {
 			if (init.signal.aborted || isAbortError(error)) throw abortError()
+			if (error instanceof ResponseByteBoundError) throw error
 			payload = null
 		}
 		if (!response.ok) {
@@ -887,8 +950,13 @@ export const createZeropsApi = (options: ZeropsApiOptions): ZeropsApi => {
 	 * that hands it over on every service is `/env` (`/user-data` answers 400 unconditionally).
 	 */
 	const listServiceEnv: ZeropsApi['listServiceEnv'] = async ({ serviceId, signal }) => {
-		const payload = await request('list service env', 'GET', `/service-stack/${serviceId}/env`, { signal })
-		return arr(payload, 'items').map(readServiceEnv)
+		const payload = await request('list service env', 'GET', `/service-stack/${serviceId}/env`, {
+			signal,
+			responseMaxBytes: SERVICE_ENV_RESPONSE_MAX_BYTES,
+		})
+		const items = prop(payload, 'items')
+		if (!Array.isArray(items)) throw invalidResponse('list service env')
+		return items.map(readServiceEnv)
 	}
 
 	return {

package/src/control.ts

@@ -10,6 +10,8 @@ import type {
 	ProviderReconcileOutcome,
 	ProviderRegistration,
 	ProviderRegistrationInput,
+	ProviderSourceResolution,
+	ProviderSourceResolutionInput,
 	ProviderTerminalOutcome,
 	RuntimeProvider,
 	RuntimeProviderRun,
@@ -35,8 +37,8 @@ import {
 	zeropsArtifactCodec,
 } from './manifest'
 import { createZeropsNamespaceCapabilities, type ZeropsNamespaceTarget, zeropsNamespaceTargetCodec } from './namespace'
-import { createZeropsProvider } from './provider'
-import { normalizeZeropsSourceRepository, type ZeropsSourceClient } from './source'
+import { createZeropsProvider, type ZeropsSourceTransportBinding } from './provider'
+import { normalizeZeropsSourceRepository, type ZeropsSourceClient, type ZeropsSourceClientV2, type ZeropsSourceResolveResult } from './source'
 import type { ZeropsRunState, ZeropsRuntimeTarget } from './types'
 
 /** Provider coordinates that are safe to persist. Credentials are composed only for a live run. */
@@ -109,7 +111,7 @@ export interface ZeropsControlProviderOptions {
 	readonly propustkaUrl?: string
 	readonly adminKey?: string
 	readonly api?: ZeropsApi
-	readonly source: ZeropsSourceClient
+	readonly source: ZeropsSourceClient & Partial<ZeropsSourceClientV2>
 	readonly reconcileSchema?: SchemaReconciler
 	readonly sleep?: Sleeper
 	readonly sourceCancelSleep?: Sleeper
@@ -123,6 +125,19 @@ export interface ZeropsControlProviderOptions {
 	}
 }
 
+export interface ZeropsBoundSourceResolutionInput extends ProviderSourceResolutionInput {
+	readonly sourceBinding: ZeropsSourceTransportBinding
+}
+
+export interface ZeropsBoundDeployInput extends ProviderDeployInput {
+	readonly sourceBinding: ZeropsSourceTransportBinding
+}
+
+export interface ZeropsControlProvider extends ControlProvider {
+	resolveSourceWithBinding(input: ZeropsBoundSourceResolutionInput): Promise<ProviderSourceResolution>
+	deployWithBinding(input: ZeropsBoundDeployInput): Promise<ProviderTerminalOutcome>
+}
+
 interface DecodedZeropsEnvironment {
 	readonly target: ZeropsStoredTarget
 	readonly namespace: ProviderDeploymentNamespace
@@ -184,6 +199,9 @@ const normalizeRegistration = (input: ProviderRegistrationInput): ProviderRegist
 	if (input.app.id !== input.environment.appId) {
 		throw new Error(`Zerops environment belongs to app \`${input.environment.appId}\`, expected \`${input.app.id}\``)
 	}
+	if ((input.app.source.githubConnectionId === undefined) !== (input.app.source.githubInstallationId === undefined)) {
+		throw new Error('Zerops private source requires both connection and installation coordinates')
+	}
 	const decoded = decodeEnvironment(input.environment)
 	const artifact = parseFabrikaManifest(
 		decodeEnvelope('artifact', input.environment.artifact, zeropsArtifactCodec),
@@ -252,11 +270,12 @@ const buildTriggeredState = (
 })
 
 /** Build the complete Zerops lifecycle bundle without importing control-plane persistence. */
-export const createZeropsControlProvider = (options: ZeropsControlProviderOptions): ControlProvider => {
+export const createZeropsControlProvider = (options: ZeropsControlProviderOptions): ZeropsControlProvider => {
 	if (options.accessToken === '') {
 		throw new Error('Zerops access token must be a non-empty string')
 	}
 	const api = options.api ?? createZeropsApi({ token: options.accessToken, baseUrl: options.apiBaseUrl })
+	const sourceBindings = new Map<string, ZeropsSourceTransportBinding>()
 	const runtimeProvider = createZeropsProvider((target) => {
 		const defaults = defaultZeropsCollaborators(target)
 		return {
@@ -266,6 +285,13 @@ export const createZeropsControlProvider = (options: ZeropsControlProviderOption
 			reconcileSchema: options.reconcileSchema ?? defaults.reconcileSchema,
 			sleep: options.sleep ?? defaultSleep,
 		}
+	}, {
+		bindingForRun: (runId) => sourceBindings.get(runId),
+		uploadV2: async (input) => {
+			const uploadV2 = options.source.uploadV2
+			if (uploadV2 === undefined) throw new Error('Zerops keyed source transport is unavailable')
+			return uploadV2.call(options.source, input)
+		},
 	})
 	const namespaceCapabilities = options.namespaces === undefined
 		? undefined
@@ -349,35 +375,68 @@ export const createZeropsControlProvider = (options: ZeropsControlProviderOption
 		return { state: 'running' }
 	}
 
-	return {
+	const assertSourceBinding = (
+		input: Pick<ProviderDeployInput, 'app'>,
+		binding: ZeropsSourceTransportBinding | undefined,
+	): void => {
+		const connectionId = input.app.source.githubConnectionId
+		const installationId = input.app.source.githubInstallationId
+		if (binding === undefined) {
+			if (connectionId !== undefined || installationId !== undefined) {
+				throw new Error('Zerops private source requires an explicit transport binding')
+			}
+			return
+		}
+		if (connectionId !== binding.connectionId || installationId !== binding.installationId) {
+			throw new Error('Zerops source transport binding has different application coordinates')
+		}
+	}
+
+	const resolveSource = async (
+		input: ProviderSourceResolutionInput,
+		binding?: ZeropsSourceTransportBinding,
+	): Promise<ProviderSourceResolution> => {
+		assertSourceBinding(input, binding)
+		const registration = normalizeRegistration({ app: input.app, environment: input.environment })
+		const artifact = decodeEnvelope('artifact', registration.environment.artifact, zeropsArtifactCodec)
+		await verifyZeropsArtifactSourceDescriptor(artifact.target.sourceDescriptor)
+		const base = {
+			runId: input.runId,
+			repository: normalizeZeropsSourceRepository(registration.app.source.repoUrl),
+			requestedRef: registration.app.source.ref,
+			...(input.expectedCommitSha === undefined ? {} : { expectedCommitSha: input.expectedCommitSha }),
+			descriptorSha256: artifact.target.sourceDescriptor.sha256,
+			signal: input.signal,
+		}
+		let result: ZeropsSourceResolveResult
+		if (binding?.transportKind === 'keyed-v2') {
+			const resolveV2 = options.source.resolveV2
+			if (resolveV2 === undefined) throw new Error('Zerops keyed source transport is unavailable')
+			result = await resolveV2.call(options.source, {
+				...base,
+				privateBinding: { connectionId: binding.connectionId, installationId: binding.installationId },
+			})
+		} else {
+			result = await options.source.resolve({
+				...base,
+				...(binding === undefined ? {} : { githubInstallationId: binding.installationId }),
+			})
+		}
+		if (
+			result.runId !== input.runId
+			|| result.descriptorSha256 !== artifact.target.sourceDescriptor.sha256
+			|| (input.expectedCommitSha !== undefined && result.commitSha !== input.expectedCommitSha)
+		) throw new Error('Zerops source resolution returned different coordinates')
+		return { commitSha: result.commitSha }
+	}
+
+	const controlProvider: ZeropsControlProvider = {
 		id: 'zerops',
 		normalizeRegistration,
-		resolveSource: async (input) => {
-			const registration = normalizeRegistration({ app: input.app, environment: input.environment })
-			const artifact = decodeEnvelope('artifact', registration.environment.artifact, zeropsArtifactCodec)
-			await verifyZeropsArtifactSourceDescriptor(artifact.target.sourceDescriptor)
-			const repository = normalizeZeropsSourceRepository(registration.app.source.repoUrl)
-			const result = await options.source.resolve({
-				runId: input.runId,
-				repository,
-				requestedRef: registration.app.source.ref,
-				...(input.expectedCommitSha === undefined ? {} : { expectedCommitSha: input.expectedCommitSha }),
-				...(registration.app.source.githubInstallationId === undefined
-					? {}
-					: { githubInstallationId: registration.app.source.githubInstallationId }),
-				descriptorSha256: artifact.target.sourceDescriptor.sha256,
-				signal: input.signal,
-			})
-			if (
-				result.runId !== input.runId
-				|| result.descriptorSha256 !== artifact.target.sourceDescriptor.sha256
-				|| (input.expectedCommitSha !== undefined && result.commitSha !== input.expectedCommitSha)
-			) {
-				throw new Error('Zerops source resolution returned different coordinates')
-			}
-			return { commitSha: result.commitSha }
-		},
+		resolveSource: (input) => resolveSource(input),
+		resolveSourceWithBinding: (input) => resolveSource(input, input.sourceBinding),
 		deploy: async (input: ProviderDeployInput): Promise<ProviderTerminalOutcome> => {
+			assertSourceBinding(input, sourceBindings.get(input.runId))
 			const registration = normalizeRegistration({ app: input.app, environment: input.environment })
 			const placement = resolvedEnvironment(registration.environment, { requireReady: true })
 			const proxyServiceId = placement.proxyServiceId
@@ -469,6 +528,17 @@ export const createZeropsControlProvider = (options: ZeropsControlProviderOption
 				artifact: registration.environment.artifact,
 			})
 		},
+		deployWithBinding: async (input) => {
+			const { sourceBinding, ...deployInput } = input
+			assertSourceBinding(deployInput, sourceBinding)
+			if (sourceBindings.has(input.runId)) throw new Error('Zerops source transport binding is already active for this run')
+			sourceBindings.set(input.runId, sourceBinding)
+			try {
+				return await controlProvider.deploy(deployInput)
+			} finally {
+				if (sourceBindings.get(input.runId) === sourceBinding) sourceBindings.delete(input.runId)
+			}
+		},
 		cancel: async (input) => {
 			resolvedEnvironment(input.environment, { requireReady: false })
 			const state = parseRunState(input.providerState, input.externalId)
@@ -646,4 +716,5 @@ export const createZeropsControlProvider = (options: ZeropsControlProviderOption
 				},
 			}),
 	}
+	return controlProvider
 }

package/src/index.ts

@@ -98,54 +98,82 @@ export {
 	buildZeropsSourceCancelRequest,
 	buildZeropsSourceCancelResponse,
 	buildZeropsSourceCredentialActivateRequest,
+	buildZeropsSourceCredentialActivateRequestV2,
 	buildZeropsSourceCredentialActivateResponse,
+	buildZeropsSourceCredentialActivateResponseV2,
 	buildZeropsSourceCredentialBundle,
+	buildZeropsSourceCredentialBundleV2,
 	buildZeropsSourceCredentialStatusRequest,
+	buildZeropsSourceCredentialStatusRequestV2,
 	buildZeropsSourceCredentialStatusResponse,
+	buildZeropsSourceCredentialStatusResponseV2,
 	buildZeropsSourceErrorEnvelope,
 	buildZeropsSourceInstallationsVerifyRequest,
 	buildZeropsSourceInstallationsVerifyResponse,
 	buildZeropsSourceResolveInstallationRequest,
 	buildZeropsSourceResolveInstallationResponse,
 	buildZeropsSourceResolveRequest,
+	buildZeropsSourceResolveRequestV2,
 	buildZeropsSourceResolveResponse,
+	buildZeropsSourceResolveResponseV2,
 	buildZeropsSourceUploadRequest,
+	buildZeropsSourceUploadRequestV2,
 	buildZeropsSourceUploadResponse,
+	buildZeropsSourceUploadResponseV2,
 	buildZeropsSourceWebhookConfigureRequest,
 	buildZeropsSourceWebhookConfigureResponse,
 	decodeZeropsSourceCancelRequest,
 	decodeZeropsSourceCancelResponse,
 	decodeZeropsSourceCredentialActivateRequest,
+	decodeZeropsSourceCredentialActivateRequestV2,
 	decodeZeropsSourceCredentialActivateResponse,
+	decodeZeropsSourceCredentialActivateResponseV2,
 	decodeZeropsSourceCredentialBundle,
+	decodeZeropsSourceCredentialBundleV2,
 	decodeZeropsSourceCredentialStatusRequest,
+	decodeZeropsSourceCredentialStatusRequestV2,
 	decodeZeropsSourceCredentialStatusResponse,
+	decodeZeropsSourceCredentialStatusResponseV2,
 	decodeZeropsSourceErrorEnvelope,
 	decodeZeropsSourceInstallationsVerifyRequest,
 	decodeZeropsSourceInstallationsVerifyResponse,
 	decodeZeropsSourceResolveInstallationRequest,
 	decodeZeropsSourceResolveInstallationResponse,
 	decodeZeropsSourceResolveRequest,
+	decodeZeropsSourceResolveRequestV2,
 	decodeZeropsSourceResolveResponse,
+	decodeZeropsSourceResolveResponseV2,
 	decodeZeropsSourceUploadRequest,
+	decodeZeropsSourceUploadRequestV2,
 	decodeZeropsSourceUploadResponse,
+	decodeZeropsSourceUploadResponseV2,
 	decodeZeropsSourceWebhookConfigureRequest,
 	decodeZeropsSourceWebhookConfigureResponse,
 	normalizeZeropsSourceRepository,
 	serializeZeropsSourceCredentialBundle,
+	serializeZeropsSourceCredentialBundleV2,
 	sha256ZeropsSourceCredentialBundle,
+	sha256ZeropsSourceCredentialBundleV2,
 	ZEROPS_SOURCE_CANCEL_PATH,
 	ZEROPS_SOURCE_CREDENTIAL_ACTIVATE_PATH,
+	ZEROPS_SOURCE_CREDENTIAL_ACTIVATE_PATH_V2,
 	ZEROPS_SOURCE_CREDENTIAL_BUNDLE_VERSION,
+	ZEROPS_SOURCE_CREDENTIAL_BUNDLE_VERSION_V2,
+	ZEROPS_SOURCE_CREDENTIAL_ENV_V2_PREFIX,
 	ZEROPS_SOURCE_CREDENTIAL_STATUS_PATH,
+	ZEROPS_SOURCE_CREDENTIAL_STATUS_PATH_V2,
 	ZEROPS_SOURCE_ERROR_CODES,
 	ZEROPS_SOURCE_ERROR_STAGES,
 	ZEROPS_SOURCE_INSTALLATIONS_VERIFY_PATH,
 	ZEROPS_SOURCE_PROTOCOL_VERSION,
+	ZEROPS_SOURCE_PROTOCOL_VERSION_V2,
 	ZEROPS_SOURCE_RESOLVE_INSTALLATION_PATH,
 	ZEROPS_SOURCE_RESOLVE_PATH,
+	ZEROPS_SOURCE_RESOLVE_PATH_V2,
 	ZEROPS_SOURCE_UPLOAD_PATH,
+	ZEROPS_SOURCE_UPLOAD_PATH_V2,
 	ZEROPS_SOURCE_WEBHOOK_CONFIGURE_PATH,
+	zeropsSourceCredentialEnvV2,
 } from './source'
 export type {
 	ZeropsSourceCancelInput,
@@ -153,16 +181,25 @@ export type {
 	ZeropsSourceCancelResponseV1,
 	ZeropsSourceCancelResult,
 	ZeropsSourceClient,
+	ZeropsSourceClientV2,
 	ZeropsSourceCredentialActivateInput,
 	ZeropsSourceCredentialActivateRequestV1,
+	ZeropsSourceCredentialActivateRequestV2,
 	ZeropsSourceCredentialActivateResponseV1,
+	ZeropsSourceCredentialActivateResponseV2,
 	ZeropsSourceCredentialActiveStatusResponseV1,
+	ZeropsSourceCredentialActiveStatusResponseV2,
 	ZeropsSourceCredentialAnonymousStatusResponseV1,
+	ZeropsSourceCredentialAnonymousStatusResponseV2,
 	ZeropsSourceCredentialBundleV1,
+	ZeropsSourceCredentialBundleV2,
 	ZeropsSourceCredentialManager,
+	ZeropsSourceCredentialManagerV2,
 	ZeropsSourceCredentialStatusInput,
 	ZeropsSourceCredentialStatusRequestV1,
+	ZeropsSourceCredentialStatusRequestV2,
 	ZeropsSourceCredentialStatusResponseV1,
+	ZeropsSourceCredentialStatusResponseV2,
 	ZeropsSourceDescriptor,
 	ZeropsSourceErrorCode,
 	ZeropsSourceErrorEnvelope,
@@ -173,16 +210,23 @@ export type {
 	ZeropsSourceInstallationsVerifyRequestV1,
 	ZeropsSourceInstallationsVerifyResponseV1,
 	ZeropsSourceInstallationVerificationV1,
+	ZeropsSourcePrivateBindingV2,
 	ZeropsSourceRepository,
 	ZeropsSourceResolveInput,
+	ZeropsSourceResolveInputV2,
 	ZeropsSourceResolveInstallationRequestV1,
 	ZeropsSourceResolveInstallationResponseV1,
 	ZeropsSourceResolveRequestV1,
+	ZeropsSourceResolveRequestV2,
 	ZeropsSourceResolveResponseV1,
+	ZeropsSourceResolveResponseV2,
 	ZeropsSourceResolveResult,
 	ZeropsSourceUploadInput,
+	ZeropsSourceUploadInputV2,
 	ZeropsSourceUploadRequestV1,
+	ZeropsSourceUploadRequestV2,
 	ZeropsSourceUploadResponseV1,
+	ZeropsSourceUploadResponseV2,
 	ZeropsSourceUploadResult,
 	ZeropsSourceWebhookConfigureInput,
 	ZeropsSourceWebhookConfigureRequestV1,

package/src/provider.ts

@@ -30,12 +30,24 @@ import {
 	zeropsArtifactCodec,
 } from './manifest'
 import { buildZeropsPlan, resolveDeployHostname, type ZeropsJobSpec, type ZeropsPlan } from './plan'
+import type { ZeropsSourceUploadInputV2, ZeropsSourceUploadResult } from './source'
 import type { ZeropsRunState, ZeropsRuntimeSource, ZeropsRuntimeTarget } from './types'
 
 export const CANCELLED = 'deploy cancelled'
 
 type ZeropsRun = TypedProviderRun<ZeropsRuntimeTarget, FabrikaManifest>
 
+export interface ZeropsSourceTransportBinding {
+	readonly connectionId: string
+	readonly installationId: number
+	readonly transportKind: 'legacy-v1' | 'keyed-v2'
+}
+
+export interface ZeropsSourceTransportRouting {
+	bindingForRun(runId: string): ZeropsSourceTransportBinding | undefined
+	uploadV2(input: ZeropsSourceUploadInputV2): Promise<ZeropsSourceUploadResult>
+}
+
 /** How often `await-deploy` asks Zerops for the version's status. */
 const POLL_INTERVAL_MS = 3000
 
@@ -94,6 +106,7 @@ interface StepEnv {
 	log: (line: string) => void
 	signal: AbortSignal
 	dryRun: boolean
+	sourceTransport?: ZeropsSourceTransportRouting
 	/** Set by `trigger-deploy`, read by `await-deploy` — the only state that crosses a step boundary. */
 	state: { appVersionId?: string; processId?: string }
 }
@@ -276,7 +289,7 @@ const runStep = async (spec: ZeropsJobSpec, env: StepEnv): Promise<void> => {
 			let buildTriggerRequested = false
 			try {
 				await run.events.externalId(version.id, runState(version.id, 'version_created'))
-				const uploaded = await source.client.upload({
+				const uploadInput = {
 					runId: source.runtime.runId,
 					appVersionId: version.id,
 					repository: source.runtime.repository,
@@ -290,7 +303,22 @@ const runStep = async (spec: ZeropsJobSpec, env: StepEnv): Promise<void> => {
 						sha256: artifact.target.sourceDescriptor.sha256,
 					},
 					signal,
-				})
+				}
+				const sourceTransport = env.sourceTransport
+				const binding = sourceTransport?.bindingForRun(source.runtime.runId)
+				if (binding !== undefined && source.runtime.githubInstallationId !== binding.installationId) {
+					throw new Error('zerops: source transport binding has different installation coordinates')
+				}
+				let uploaded: ZeropsSourceUploadResult
+				if (binding?.transportKind === 'keyed-v2') {
+					if (sourceTransport === undefined) throw new Error('zerops: keyed source transport is unavailable')
+					uploaded = await sourceTransport.uploadV2({
+						...uploadInput,
+						privateBinding: { connectionId: binding.connectionId, installationId: binding.installationId },
+					})
+				} else {
+					uploaded = await source.client.upload(uploadInput)
+				}
 				if (
 					uploaded.runId !== source.runtime.runId
 					|| uploaded.appVersionId !== version.id
@@ -404,6 +432,7 @@ export type ZeropsProvider = ProviderModule<'zerops', ZeropsRuntimeTarget, Fabri
 /** Construct an independently testable Zerops provider against one collaborator factory. */
 export const createZeropsProvider = (
 	collaborators: ZeropsCollaboratorFactory = defaultZeropsCollaborators,
+	sourceTransport?: ZeropsSourceTransportRouting,
 ): ZeropsProvider =>
 	createProvider({
 		id: 'zerops',
@@ -431,6 +460,7 @@ export const createZeropsProvider = (
 				log: run.events.log,
 				signal: run.signal,
 				dryRun: run.dryRun,
+				...(sourceTransport === undefined ? {} : { sourceTransport }),
 				state: {},
 			}
 			const byId = new Map(plan.steps.map((step): [string, ZeropsJobSpec] => [step.id, step]))

package/src/source-connection.ts

@@ -2,11 +2,19 @@ import type { ZeropsApi, ZeropsService, ZeropsServiceEnv } from './api'
 import {
 	buildZeropsSourceCredentialBundle,
 	decodeZeropsSourceCredentialBundle,
+	decodeZeropsSourceCredentialBundleV2,
 	serializeZeropsSourceCredentialBundle,
 	sha256ZeropsSourceCredentialBundle,
+	sha256ZeropsSourceCredentialBundleV2,
+	ZEROPS_SOURCE_CREDENTIAL_BUNDLE_VERSION_V2,
+	ZEROPS_SOURCE_PROTOCOL_VERSION_V2,
 	type ZeropsSourceCredentialActivateResponseV1,
+	type ZeropsSourceCredentialActivateResponseV2,
+	zeropsSourceCredentialEnvV2,
 	type ZeropsSourceCredentialManager,
+	type ZeropsSourceCredentialManagerV2,
 	type ZeropsSourceCredentialStatusResponseV1,
+	type ZeropsSourceCredentialStatusResponseV2,
 	type ZeropsSourceGitHubAppIdentityV1,
 	type ZeropsSourceInstallationsVerifyInput,
 	type ZeropsSourceInstallationsVerifyResponseV1,
@@ -19,7 +27,6 @@ export const ZEROPS_SOURCE_LEGACY_APP_ID_ENV = 'GITHUB_APP_ID'
 export const ZEROPS_SOURCE_LEGACY_PRIVATE_KEY_ENV = 'GITHUB_APP_PRIVATE_KEY'
 
 const SOURCE_HOSTNAME = 'source'
-const MAX_ENV_ENTRIES = 256
 const PROJECT_ID_PATTERN = /^[A-Za-z0-9._:-]{1,128}$/
 const DEFAULT_REREAD_ATTEMPTS = 5
 const DEFAULT_REREAD_DELAY_MS = 250
@@ -62,16 +69,23 @@ export interface SourceConnectionAdmin {
 	inspect(signal: AbortSignal): Promise<SourceConnectionInspection>
 	adoptExisting(input: SourceConnectionAdoptExistingInput): Promise<ZeropsSourceCredentialActivateResponseV1>
 	activate(input: SourceConnectionActivateInput): Promise<ZeropsSourceCredentialActivateResponseV1>
+	activateV2?(input: SourceConnectionActivateInput): Promise<ZeropsSourceCredentialActivateResponseV2>
 	status(input: SourceConnectionStatusInput): Promise<SourceConnectionStatus>
+	statusV2?(input: SourceConnectionStatusInput): Promise<SourceConnectionStatus>
 	configureWebhook(input: ZeropsSourceWebhookConfigureInput): Promise<ZeropsSourceWebhookConfigureResponseV1>
 	verifyInstallations(input: ZeropsSourceInstallationsVerifyInput): Promise<ZeropsSourceInstallationsVerifyResponseV1>
 }
 
+interface CompleteSourceConnectionAdmin extends SourceConnectionAdmin {
+	activateV2(input: SourceConnectionActivateInput): Promise<ZeropsSourceCredentialActivateResponseV2>
+	statusV2(input: SourceConnectionStatusInput): Promise<SourceConnectionStatus>
+}
+
 export type SourceConnectionZeropsApi = Pick<ZeropsApi, 'findService' | 'listServiceEnv' | 'createServiceEnv'>
 
 export interface ZeropsSourceConnectionAdminOptions {
 	readonly api: SourceConnectionZeropsApi
-	readonly source: ZeropsSourceCredentialManager
+	readonly source: ZeropsSourceCredentialManager & Partial<ZeropsSourceCredentialManagerV2>
 	readonly projectId: string
 	readonly reread?: {
 		readonly attempts?: number
@@ -102,7 +116,16 @@ interface DurableInspection {
 	readonly bundle?: string
 }
 
-export function createZeropsSourceConnectionAdmin(options: ZeropsSourceConnectionAdminOptions): SourceConnectionAdmin {
+interface DurableInspectionV2 {
+	readonly public:
+		| { readonly state: 'anonymous' }
+		| { readonly state: 'durable'; readonly credentialSha256: string }
+	readonly service: ZeropsService
+	readonly environmentKey: string
+	readonly bundle?: string
+}
+
+export function createZeropsSourceConnectionAdmin(options: ZeropsSourceConnectionAdminOptions): CompleteSourceConnectionAdmin {
 	if (!PROJECT_ID_PATTERN.test(options.projectId)) throw new SourceConnectionAdminError('invalid_configuration')
 	const attempts = options.reread?.attempts ?? DEFAULT_REREAD_ATTEMPTS
 	const delayMs = options.reread?.delayMs ?? DEFAULT_REREAD_DELAY_MS
@@ -111,7 +134,7 @@ export function createZeropsSourceConnectionAdmin(options: ZeropsSourceConnectio
 	}
 	const sleep = options.reread?.sleep ?? defaultSleep
 
-	const inspectInternal = async (signal: AbortSignal): Promise<DurableInspection> => {
+	const readEnvironment = async (signal: AbortSignal): Promise<{ service: ZeropsService; environment: ZeropsServiceEnv[] }> => {
 		throwIfAborted(signal)
 		const service = await exactSourceService(options.api, options.projectId, signal)
 		let environment: ZeropsServiceEnv[]
@@ -122,10 +145,26 @@ export function createZeropsSourceConnectionAdmin(options: ZeropsSourceConnectio
 			throw new SourceConnectionAdminError('credential_persistence')
 		}
 		throwIfAborted(signal)
-		return await withDigest(classify(service, environment))
+		return { service, environment }
 	}
 
-	const admin: SourceConnectionAdmin = {
+	const inspectInternal = async (signal: AbortSignal): Promise<DurableInspection> => {
+		const current = await readEnvironment(signal)
+		return await withDigest(classify(current.service, current.environment))
+	}
+
+	const inspectV2Internal = async (connectionId: string, signal: AbortSignal): Promise<DurableInspectionV2> => {
+		let environmentKey: string
+		try {
+			environmentKey = await zeropsSourceCredentialEnvV2(connectionId)
+		} catch {
+			throw new SourceConnectionAdminError('credential_conflict')
+		}
+		const current = await readEnvironment(signal)
+		return await classifyV2(current.service, current.environment, environmentKey, connectionId)
+	}
+
+	const admin: CompleteSourceConnectionAdmin = {
 		inspect: async (signal) => (await inspectInternal(signal)).public,
 
 		adoptExisting: async (input) => {
@@ -212,6 +251,68 @@ export function createZeropsSourceConnectionAdmin(options: ZeropsSourceConnectio
 			return activated
 		},
 
+		activateV2: async (input) => {
+			if (options.source.activateV2 === undefined || options.source.statusV2 === undefined) {
+				throw new SourceConnectionAdminError('credential_activation')
+			}
+			const activateV2 = options.source.activateV2.bind(options.source)
+			const statusV2 = options.source.statusV2.bind(options.source)
+			let digest: string
+			try {
+				const bundle = decodeZeropsSourceCredentialBundleV2(input.credentialBundle)
+				if (bundle.connectionId !== input.connectionId) throw new Error('connection mismatch')
+				digest = await sha256ZeropsSourceCredentialBundleV2(input.credentialBundle)
+			} catch {
+				throw new SourceConnectionAdminError('credential_conflict')
+			}
+			if (digest !== input.credentialSha256) throw new SourceConnectionAdminError('credential_conflict')
+			const initial = await inspectV2Internal(input.connectionId, input.signal)
+			if (initial.public.state === 'durable') {
+				if (initial.bundle !== input.credentialBundle || initial.public.credentialSha256 !== digest) {
+					throw new SourceConnectionAdminError('credential_conflict')
+				}
+			} else {
+				try {
+					await options.api.createServiceEnv({
+						serviceId: initial.service.id,
+						key: initial.environmentKey,
+						value: input.credentialBundle,
+						signal: input.signal,
+					})
+				} catch (error) {
+					if (isAbort(error, input.signal)) throw error
+				}
+				await proveDurableV2(input, digest, attempts, delayMs, sleep, inspectV2Internal)
+			}
+			let activated: ZeropsSourceCredentialActivateResponseV2
+			try {
+				activated = await activateV2(input)
+			} catch (error) {
+				if (isAbort(error, input.signal)) throw error
+				let status: ZeropsSourceCredentialStatusResponseV2
+				try {
+					status = await statusV2({ connectionId: input.connectionId, signal: input.signal })
+				} catch (statusError) {
+					if (isAbort(statusError, input.signal)) throw statusError
+					throw new SourceConnectionAdminError('credential_activation')
+				}
+				if (
+					status.state !== 'active' || status.connectionId !== input.connectionId || status.credentialSha256 !== digest
+				) throw new SourceConnectionAdminError('credential_activation')
+				activated = {
+					protocolVersion: ZEROPS_SOURCE_PROTOCOL_VERSION_V2,
+					connectionId: input.connectionId,
+					credentialVersion: ZEROPS_SOURCE_CREDENTIAL_BUNDLE_VERSION_V2,
+					credentialSha256: status.credentialSha256,
+					githubApp: status.githubApp,
+				}
+			}
+			if (activated.connectionId !== input.connectionId || activated.credentialSha256 !== digest) {
+				throw new SourceConnectionAdminError('credential_activation')
+			}
+			return activated
+		},
+
 		status: async (input) => {
 			const durable = await inspectInternal(input.signal)
 			if (durable.public.state !== 'durable') return durable.public
@@ -231,8 +332,30 @@ export function createZeropsSourceConnectionAdmin(options: ZeropsSourceConnectio
 			return { state: 'active', credentialSha256: runtime.credentialSha256, githubApp: runtime.githubApp }
 		},
 
+		statusV2: async (input) => {
+			const durable = await inspectV2Internal(input.connectionId, input.signal)
+			if (durable.public.state !== 'durable') return durable.public
+			const statusV2 = options.source.statusV2
+			if (statusV2 === undefined) throw new SourceConnectionAdminError('credential_activation')
+			const readStatusV2 = statusV2.bind(options.source)
+			let runtime: ZeropsSourceCredentialStatusResponseV2
+			try {
+				runtime = await readStatusV2(input)
+			} catch (error) {
+				if (isAbort(error, input.signal)) throw error
+				throw new SourceConnectionAdminError('credential_activation')
+			}
+			if (runtime.connectionId !== input.connectionId || runtime.state === 'anonymous') {
+				return { state: 'activation-required', credentialSha256: durable.public.credentialSha256 }
+			}
+			if (runtime.credentialSha256 !== durable.public.credentialSha256) {
+				throw new SourceConnectionAdminError('credential_conflict')
+			}
+			return { state: 'active', credentialSha256: runtime.credentialSha256, githubApp: runtime.githubApp }
+		},
+
 		configureWebhook: async (input) => {
-			await requireDurableDigest(input.credentialSha256, input.signal, inspectInternal)
+			await requireDurableDigest(input.connectionId, input.credentialSha256, input.signal, inspectInternal, inspectV2Internal)
 			try {
 				const response = await options.source.configureWebhook(input)
 				if (
@@ -248,7 +371,7 @@ export function createZeropsSourceConnectionAdmin(options: ZeropsSourceConnectio
 		},
 
 		verifyInstallations: async (input) => {
-			await requireDurableDigest(input.credentialSha256, input.signal, inspectInternal)
+			await requireDurableDigest(input.connectionId, input.credentialSha256, input.signal, inspectInternal, inspectV2Internal)
 			try {
 				const response = await options.source.verifyInstallations(input)
 				if (response.connectionId !== input.connectionId || response.credentialSha256 !== input.credentialSha256) {
@@ -272,10 +395,17 @@ async function adoptionConnectionId(projectId: string, credentialSha256: string)
 }
 
 async function requireDurableDigest(
+	connectionId: string,
 	digest: string,
 	signal: AbortSignal,
 	inspect: (signal: AbortSignal) => Promise<DurableInspection>,
+	inspectV2: (connectionId: string, signal: AbortSignal) => Promise<DurableInspectionV2>,
 ): Promise<void> {
+	const keyed = await inspectV2(connectionId, signal)
+	if (keyed.public.state === 'durable') {
+		if (keyed.public.credentialSha256 === digest) return
+		throw new SourceConnectionAdminError('credential_conflict')
+	}
 	const durable = await inspect(signal)
 	if (durable.public.state !== 'durable' || durable.public.credentialSha256 !== digest) {
 		throw new SourceConnectionAdminError('credential_conflict')
@@ -298,7 +428,6 @@ async function exactSourceService(api: SourceConnectionZeropsApi, projectId: str
 }
 
 function classify(service: ZeropsService, environment: readonly ZeropsServiceEnv[]): DurableInspection {
-	if (environment.length > MAX_ENV_ENTRIES) throw new SourceConnectionAdminError('source_mismatch')
 	const bundleEntries = environment.filter((entry) => entry.key === ZEROPS_SOURCE_CREDENTIAL_ENV)
 	const legacyIdEntries = environment.filter((entry) => entry.key === ZEROPS_SOURCE_LEGACY_APP_ID_ENV)
 	const legacyKeyEntries = environment.filter((entry) => entry.key === ZEROPS_SOURCE_LEGACY_PRIVATE_KEY_ENV)
@@ -337,6 +466,31 @@ function classify(service: ZeropsService, environment: readonly ZeropsServiceEnv
 	return { public: { state: 'legacy-partial' }, service }
 }
 
+async function classifyV2(
+	service: ZeropsService,
+	environment: readonly ZeropsServiceEnv[],
+	environmentKey: string,
+	connectionId: string,
+): Promise<DurableInspectionV2> {
+	const entries = environment.filter((entry) => entry.key === environmentKey)
+	if (entries.length > 1) throw new SourceConnectionAdminError('credential_conflict')
+	if (entries.length === 0) return { public: { state: 'anonymous' }, service, environmentKey }
+	const bundle = entries[0]?.content
+	if (bundle === undefined) throw new SourceConnectionAdminError('credential_conflict')
+	try {
+		const decoded = decodeZeropsSourceCredentialBundleV2(bundle)
+		if (decoded.connectionId !== connectionId) throw new Error('connection mismatch')
+		return {
+			public: { state: 'durable', credentialSha256: await sha256ZeropsSourceCredentialBundleV2(bundle) },
+			service,
+			environmentKey,
+			bundle,
+		}
+	} catch {
+		throw new SourceConnectionAdminError('credential_conflict')
+	}
+}
+
 async function withDigest(inspection: DurableInspection): Promise<DurableInspection> {
 	if (inspection.public.state !== 'durable' || inspection.bundle === undefined) return inspection
 	return {
@@ -366,6 +520,25 @@ async function proveDurable(
 	throw new SourceConnectionAdminError('credential_persistence')
 }
 
+async function proveDurableV2(
+	input: SourceConnectionActivateInput,
+	digest: string,
+	attempts: number,
+	delayMs: number,
+	sleep: (delayMs: number, signal: AbortSignal) => Promise<void>,
+	inspect: (connectionId: string, signal: AbortSignal) => Promise<DurableInspectionV2>,
+): Promise<void> {
+	for (let attempt = 0; attempt < attempts; attempt++) {
+		const durable = await inspect(input.connectionId, input.signal)
+		if (durable.public.state === 'durable') {
+			if (durable.bundle === input.credentialBundle && durable.public.credentialSha256 === digest) return
+			throw new SourceConnectionAdminError('credential_conflict')
+		}
+		if (attempt + 1 < attempts) await sleep(delayMs, input.signal)
+	}
+	throw new SourceConnectionAdminError('credential_persistence')
+}
+
 const defaultSleep = (delayMs: number, signal: AbortSignal): Promise<void> => {
 	throwIfAborted(signal)
 	return new Promise((resolve, reject) => {

package/src/source.ts

@@ -8,6 +8,13 @@ export const ZEROPS_SOURCE_CREDENTIAL_STATUS_PATH = '/v1/source/credentials/stat
 export const ZEROPS_SOURCE_WEBHOOK_CONFIGURE_PATH = '/v1/source/github/webhook/configure'
 export const ZEROPS_SOURCE_INSTALLATIONS_VERIFY_PATH = '/v1/source/github/installations/verify'
 export const ZEROPS_SOURCE_CREDENTIAL_BUNDLE_VERSION = 1
+export const ZEROPS_SOURCE_PROTOCOL_VERSION_V2 = 2
+export const ZEROPS_SOURCE_RESOLVE_PATH_V2 = '/v2/source/resolve'
+export const ZEROPS_SOURCE_UPLOAD_PATH_V2 = '/v2/source/upload'
+export const ZEROPS_SOURCE_CREDENTIAL_ACTIVATE_PATH_V2 = '/v2/source/credentials/activate'
+export const ZEROPS_SOURCE_CREDENTIAL_STATUS_PATH_V2 = '/v2/source/credentials/status'
+export const ZEROPS_SOURCE_CREDENTIAL_BUNDLE_VERSION_V2 = 2
+export const ZEROPS_SOURCE_CREDENTIAL_ENV_V2_PREFIX = 'GITHUB_APP_CREDENTIALS_V2_'
 
 const MAX_ID_LENGTH = 128
 const MAX_REF_LENGTH = 255
@@ -32,6 +39,13 @@ export interface ZeropsSourceCredentialBundleV1 {
 	readonly privateKeyPem: string
 }
 
+export interface ZeropsSourceCredentialBundleV2 {
+	readonly version: typeof ZEROPS_SOURCE_CREDENTIAL_BUNDLE_VERSION_V2
+	readonly connectionId: string
+	readonly githubAppId: string
+	readonly privateKeyPem: string
+}
+
 export interface ZeropsSourceGitHubAppIdentityV1 {
 	readonly id: number
 	readonly slug: string
@@ -82,6 +96,41 @@ export type ZeropsSourceCredentialStatusResponseV1 =
 	| ZeropsSourceCredentialAnonymousStatusResponseV1
 	| ZeropsSourceCredentialActiveStatusResponseV1
 
+export interface ZeropsSourceCredentialActivateRequestV2 {
+	readonly protocolVersion: typeof ZEROPS_SOURCE_PROTOCOL_VERSION_V2
+	readonly connectionId: string
+	/** Canonical JSON that is byte-identical to the durable source environment value. */
+	readonly credentialBundle: string
+	readonly credentialSha256: string
+}
+
+export interface ZeropsSourceCredentialActivateResponseV2 {
+	readonly protocolVersion: typeof ZEROPS_SOURCE_PROTOCOL_VERSION_V2
+	readonly connectionId: string
+	readonly credentialVersion: typeof ZEROPS_SOURCE_CREDENTIAL_BUNDLE_VERSION_V2
+	readonly credentialSha256: string
+	readonly githubApp: ZeropsSourceGitHubAppIdentityV1
+}
+
+export interface ZeropsSourceCredentialStatusRequestV2 {
+	readonly protocolVersion: typeof ZEROPS_SOURCE_PROTOCOL_VERSION_V2
+	readonly connectionId: string
+}
+
+export interface ZeropsSourceCredentialAnonymousStatusResponseV2 {
+	readonly protocolVersion: typeof ZEROPS_SOURCE_PROTOCOL_VERSION_V2
+	readonly connectionId: string
+	readonly state: 'anonymous'
+}
+
+export interface ZeropsSourceCredentialActiveStatusResponseV2 extends ZeropsSourceCredentialActivateResponseV2 {
+	readonly state: 'active'
+}
+
+export type ZeropsSourceCredentialStatusResponseV2 =
+	| ZeropsSourceCredentialAnonymousStatusResponseV2
+	| ZeropsSourceCredentialActiveStatusResponseV2
+
 export interface ZeropsSourceWebhookConfigureInput {
 	readonly connectionId: string
 	readonly credentialSha256: string
@@ -195,6 +244,47 @@ export interface ZeropsSourceUploadResponseV1 {
 	descriptorSha256: string
 }
 
+export interface ZeropsSourcePrivateBindingV2 {
+	readonly connectionId: string
+	readonly installationId: number
+}
+
+export interface ZeropsSourceResolveRequestV2 {
+	readonly protocolVersion: typeof ZEROPS_SOURCE_PROTOCOL_VERSION_V2
+	readonly runId: string
+	readonly repository: ZeropsSourceRepository
+	readonly requestedRef: string
+	readonly expectedCommitSha?: string
+	readonly privateBinding?: ZeropsSourcePrivateBindingV2
+	readonly descriptorSha256: string
+}
+
+export interface ZeropsSourceResolveResponseV2 {
+	readonly protocolVersion: typeof ZEROPS_SOURCE_PROTOCOL_VERSION_V2
+	readonly runId: string
+	readonly commitSha: string
+	readonly descriptorSha256: string
+}
+
+export interface ZeropsSourceUploadRequestV2 {
+	readonly protocolVersion: typeof ZEROPS_SOURCE_PROTOCOL_VERSION_V2
+	readonly runId: string
+	readonly appVersionId: string
+	readonly repository: ZeropsSourceRepository
+	readonly commitSha: string
+	readonly privateBinding?: ZeropsSourcePrivateBindingV2
+	readonly uploadUrl: string
+	readonly descriptor: ZeropsSourceDescriptor
+}
+
+export interface ZeropsSourceUploadResponseV2 {
+	readonly protocolVersion: typeof ZEROPS_SOURCE_PROTOCOL_VERSION_V2
+	readonly runId: string
+	readonly appVersionId: string
+	readonly commitSha: string
+	readonly descriptorSha256: string
+}
+
 export interface ZeropsSourceCancelRequestV1 {
 	protocolVersion: typeof ZEROPS_SOURCE_PROTOCOL_VERSION
 	runId: string
@@ -303,6 +393,27 @@ export interface ZeropsSourceUploadInput {
 	signal: AbortSignal
 }
 
+export interface ZeropsSourceResolveInputV2 {
+	readonly runId: string
+	readonly repository: ZeropsSourceRepository
+	readonly requestedRef: string
+	readonly expectedCommitSha?: string
+	readonly privateBinding?: ZeropsSourcePrivateBindingV2
+	readonly descriptorSha256: string
+	readonly signal: AbortSignal
+}
+
+export interface ZeropsSourceUploadInputV2 {
+	readonly runId: string
+	readonly appVersionId: string
+	readonly repository: ZeropsSourceRepository
+	readonly commitSha: string
+	readonly privateBinding?: ZeropsSourcePrivateBindingV2
+	readonly uploadUrl: string
+	readonly descriptor: ZeropsSourceDescriptor
+	readonly signal: AbortSignal
+}
+
 export interface ZeropsSourceUploadResult {
 	runId: string
 	appVersionId: string
@@ -323,6 +434,12 @@ export interface ZeropsSourceClient {
 	cancel(input: ZeropsSourceCancelInput): Promise<void>
 }
 
+/** Keyed source operations are additive so legacy client implementations remain valid. */
+export interface ZeropsSourceClientV2 {
+	resolveV2(input: ZeropsSourceResolveInputV2): Promise<ZeropsSourceResolveResult>
+	uploadV2(input: ZeropsSourceUploadInputV2): Promise<ZeropsSourceUploadResult>
+}
+
 export interface ZeropsSourceCredentialActivateInput {
 	readonly connectionId: string
 	readonly credentialBundle: string
@@ -343,6 +460,12 @@ export interface ZeropsSourceCredentialManager {
 	verifyInstallations(input: ZeropsSourceInstallationsVerifyInput): Promise<ZeropsSourceInstallationsVerifyResponseV1>
 }
 
+/** Keyed credential operations are additive so legacy credential managers remain valid. */
+export interface ZeropsSourceCredentialManagerV2 {
+	activateV2(input: ZeropsSourceCredentialActivateInput): Promise<ZeropsSourceCredentialActivateResponseV2>
+	statusV2(input: ZeropsSourceCredentialStatusInput): Promise<ZeropsSourceCredentialStatusResponseV2>
+}
+
 const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === 'object' && value !== null && !Array.isArray(value)
 
 const record = (value: unknown, label: string): Record<string, unknown> => {
@@ -363,6 +486,11 @@ const protocolVersion = (value: Record<string, unknown>, label: string): typeof
 	return ZEROPS_SOURCE_PROTOCOL_VERSION
 }
 
+const protocolVersionV2 = (value: Record<string, unknown>, label: string): typeof ZEROPS_SOURCE_PROTOCOL_VERSION_V2 => {
+	if (value['protocolVersion'] !== ZEROPS_SOURCE_PROTOCOL_VERSION_V2) throw new Error(`${label} has an unsupported protocolVersion`)
+	return ZEROPS_SOURCE_PROTOCOL_VERSION_V2
+}
+
 const boundedString = (value: unknown, label: string, maximum: number): string => {
 	if (typeof value !== 'string' || value.length === 0 || value.length > maximum) {
 		throw new Error(`${label} must be a non-empty string of at most ${maximum} characters`)
@@ -428,6 +556,24 @@ const sourceCredentialBundleValue = (value: unknown): ZeropsSourceCredentialBund
 	return { version: ZEROPS_SOURCE_CREDENTIAL_BUNDLE_VERSION, githubAppId, privateKeyPem }
 }
 
+const sourceCredentialBundleValueV2 = (value: unknown): ZeropsSourceCredentialBundleV2 => {
+	const parsed = record(value, 'source credential bundle v2')
+	exactKeys(parsed, ['version', 'connectionId', 'githubAppId', 'privateKeyPem'], 'source credential bundle v2')
+	if (parsed['version'] !== ZEROPS_SOURCE_CREDENTIAL_BUNDLE_VERSION_V2) {
+		throw new Error('source credential bundle v2 has an unsupported version')
+	}
+	const connectionId = identifier(parsed['connectionId'], 'source credential bundle v2.connectionId')
+	const githubAppId = boundedString(parsed['githubAppId'], 'source credential bundle v2.githubAppId', 32)
+	if (!GITHUB_APP_ID_PATTERN.test(githubAppId)) throw new Error('source credential bundle v2.githubAppId is invalid')
+	const privateKeyPem = boundedString(
+		parsed['privateKeyPem'],
+		'source credential bundle v2.privateKeyPem',
+		MAX_GITHUB_APP_PRIVATE_KEY_LENGTH,
+	)
+	if (!isCanonicalPrivateKeyPem(privateKeyPem)) throw new Error('source credential bundle v2.privateKeyPem is invalid')
+	return { version: ZEROPS_SOURCE_CREDENTIAL_BUNDLE_VERSION_V2, connectionId, githubAppId, privateKeyPem }
+}
+
 const isCanonicalPrivateKeyPem = (value: string): boolean => {
 	const match = /^-----BEGIN (RSA PRIVATE KEY|PRIVATE KEY)-----\n([A-Za-z0-9+/=\n]+)\n-----END (RSA PRIVATE KEY|PRIVATE KEY)-----\n?$/.exec(value)
 	if (match === null || match[1] !== match[3]) return false
@@ -478,6 +624,51 @@ export async function sha256ZeropsSourceCredentialBundle(value: string): Promise
 	return [...digest].map((byte) => byte.toString(16).padStart(2, '0')).join('')
 }
 
+export function buildZeropsSourceCredentialBundleV2(
+	input: Omit<ZeropsSourceCredentialBundleV2, 'version'>,
+): ZeropsSourceCredentialBundleV2 {
+	return sourceCredentialBundleValueV2({ version: ZEROPS_SOURCE_CREDENTIAL_BUNDLE_VERSION_V2, ...input })
+}
+
+export function serializeZeropsSourceCredentialBundleV2(bundle: ZeropsSourceCredentialBundleV2): string {
+	const parsed = sourceCredentialBundleValueV2(bundle)
+	return JSON.stringify({
+		version: parsed.version,
+		connectionId: parsed.connectionId,
+		githubAppId: parsed.githubAppId,
+		privateKeyPem: parsed.privateKeyPem,
+	})
+}
+
+export function decodeZeropsSourceCredentialBundleV2(value: unknown): ZeropsSourceCredentialBundleV2 {
+	if (typeof value !== 'string' || new TextEncoder().encode(value).byteLength > MAX_SOURCE_CREDENTIAL_BUNDLE_BYTES) {
+		throw new Error('source credential bundle v2 must be bounded canonical JSON')
+	}
+	let decoded: unknown
+	try {
+		decoded = JSON.parse(value)
+	} catch {
+		throw new Error('source credential bundle v2 must be bounded canonical JSON')
+	}
+	const bundle = sourceCredentialBundleValueV2(decoded)
+	if (serializeZeropsSourceCredentialBundleV2(bundle) !== value) {
+		throw new Error('source credential bundle v2 must be bounded canonical JSON')
+	}
+	return bundle
+}
+
+export async function sha256ZeropsSourceCredentialBundleV2(value: string): Promise<string> {
+	decodeZeropsSourceCredentialBundleV2(value)
+	const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(value)))
+	return [...digest].map((byte) => byte.toString(16).padStart(2, '0')).join('')
+}
+
+export async function zeropsSourceCredentialEnvV2(connectionId: string): Promise<string> {
+	const canonicalConnectionId = identifier(connectionId, 'source credential connectionId')
+	const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(canonicalConnectionId)))
+	return `${ZEROPS_SOURCE_CREDENTIAL_ENV_V2_PREFIX}${[...digest].map((byte) => byte.toString(16).padStart(2, '0')).join('')}`
+}
+
 const installationId = (value: unknown, label: string): number => {
 	if (typeof value !== 'number' || !Number.isSafeInteger(value) || value <= 0) throw new Error(`${label} must be a positive safe integer`)
 	return value
@@ -487,6 +678,18 @@ const optionalCommitSha = (value: unknown, label: string): string | undefined =>
 
 const optionalInstallationId = (value: unknown, label: string): number | undefined => value === undefined ? undefined : installationId(value, label)
 
+const privateBindingV2 = (value: unknown, label: string): ZeropsSourcePrivateBindingV2 => {
+	const parsed = record(value, label)
+	exactKeys(parsed, ['connectionId', 'installationId'], label)
+	return {
+		connectionId: identifier(parsed['connectionId'], `${label}.connectionId`),
+		installationId: installationId(parsed['installationId'], `${label}.installationId`),
+	}
+}
+
+const optionalPrivateBindingV2 = (value: unknown, label: string): ZeropsSourcePrivateBindingV2 | undefined =>
+	value === undefined ? undefined : privateBindingV2(value, label)
+
 const repository = (value: unknown, label: string): ZeropsSourceRepository => {
 	const parsed = record(value, label)
 	exactKeys(parsed, ['owner', 'name'], label)
@@ -716,6 +919,117 @@ export function buildZeropsSourceCredentialStatusResponse(
 	return decodeZeropsSourceCredentialStatusResponse({ protocolVersion: ZEROPS_SOURCE_PROTOCOL_VERSION, ...input })
 }
 
+export function decodeZeropsSourceCredentialActivateRequestV2(value: unknown): ZeropsSourceCredentialActivateRequestV2 {
+	const parsed = record(value, 'source credential activate request v2')
+	exactKeys(
+		parsed,
+		['protocolVersion', 'connectionId', 'credentialBundle', 'credentialSha256'],
+		'source credential activate request v2',
+	)
+	const connectionId = identifier(parsed['connectionId'], 'source credential activate request v2.connectionId')
+	const credentialBundle = boundedString(
+		parsed['credentialBundle'],
+		'source credential activate request v2.credentialBundle',
+		MAX_SOURCE_CREDENTIAL_BUNDLE_BYTES,
+	)
+	const bundle = decodeZeropsSourceCredentialBundleV2(credentialBundle)
+	if (bundle.connectionId !== connectionId) throw new Error('source credential activate request v2 connectionId does not match its bundle')
+	return {
+		protocolVersion: protocolVersionV2(parsed, 'source credential activate request v2'),
+		connectionId,
+		credentialBundle,
+		credentialSha256: sha256(parsed['credentialSha256'], 'source credential activate request v2.credentialSha256'),
+	}
+}
+
+export function buildZeropsSourceCredentialActivateRequestV2(
+	input: ZeropsSourceCredentialActivateInput,
+): ZeropsSourceCredentialActivateRequestV2 {
+	return decodeZeropsSourceCredentialActivateRequestV2({
+		protocolVersion: ZEROPS_SOURCE_PROTOCOL_VERSION_V2,
+		connectionId: input.connectionId,
+		credentialBundle: input.credentialBundle,
+		credentialSha256: input.credentialSha256,
+	})
+}
+
+export function decodeZeropsSourceCredentialActivateResponseV2(value: unknown): ZeropsSourceCredentialActivateResponseV2 {
+	const parsed = record(value, 'source credential activate response v2')
+	exactKeys(
+		parsed,
+		['protocolVersion', 'connectionId', 'credentialVersion', 'credentialSha256', 'githubApp'],
+		'source credential activate response v2',
+	)
+	if (parsed['credentialVersion'] !== ZEROPS_SOURCE_CREDENTIAL_BUNDLE_VERSION_V2) {
+		throw new Error('source credential activate response v2 has an unsupported credentialVersion')
+	}
+	return {
+		protocolVersion: protocolVersionV2(parsed, 'source credential activate response v2'),
+		connectionId: identifier(parsed['connectionId'], 'source credential activate response v2.connectionId'),
+		credentialVersion: ZEROPS_SOURCE_CREDENTIAL_BUNDLE_VERSION_V2,
+		credentialSha256: sha256(parsed['credentialSha256'], 'source credential activate response v2.credentialSha256'),
+		githubApp: githubAppIdentity(parsed['githubApp'], 'source credential activate response v2.githubApp'),
+	}
+}
+
+export function buildZeropsSourceCredentialActivateResponseV2(
+	input: Omit<ZeropsSourceCredentialActivateResponseV2, 'protocolVersion'>,
+): ZeropsSourceCredentialActivateResponseV2 {
+	return decodeZeropsSourceCredentialActivateResponseV2({ protocolVersion: ZEROPS_SOURCE_PROTOCOL_VERSION_V2, ...input })
+}
+
+export function decodeZeropsSourceCredentialStatusRequestV2(value: unknown): ZeropsSourceCredentialStatusRequestV2 {
+	const parsed = record(value, 'source credential status request v2')
+	exactKeys(parsed, ['protocolVersion', 'connectionId'], 'source credential status request v2')
+	return {
+		protocolVersion: protocolVersionV2(parsed, 'source credential status request v2'),
+		connectionId: identifier(parsed['connectionId'], 'source credential status request v2.connectionId'),
+	}
+}
+
+export function buildZeropsSourceCredentialStatusRequestV2(
+	input: ZeropsSourceCredentialStatusInput,
+): ZeropsSourceCredentialStatusRequestV2 {
+	return decodeZeropsSourceCredentialStatusRequestV2({
+		protocolVersion: ZEROPS_SOURCE_PROTOCOL_VERSION_V2,
+		connectionId: input.connectionId,
+	})
+}
+
+export function decodeZeropsSourceCredentialStatusResponseV2(value: unknown): ZeropsSourceCredentialStatusResponseV2 {
+	const parsed = record(value, 'source credential status response v2')
+	if (parsed['state'] === 'anonymous') {
+		exactKeys(parsed, ['protocolVersion', 'connectionId', 'state'], 'source credential status response v2')
+		return {
+			protocolVersion: protocolVersionV2(parsed, 'source credential status response v2'),
+			connectionId: identifier(parsed['connectionId'], 'source credential status response v2.connectionId'),
+			state: 'anonymous',
+		}
+	}
+	if (parsed['state'] !== 'active') throw new Error('source credential status response v2.state is invalid')
+	exactKeys(
+		parsed,
+		['protocolVersion', 'connectionId', 'state', 'credentialVersion', 'credentialSha256', 'githubApp'],
+		'source credential status response v2',
+	)
+	const active = decodeZeropsSourceCredentialActivateResponseV2({
+		protocolVersion: parsed['protocolVersion'],
+		connectionId: parsed['connectionId'],
+		credentialVersion: parsed['credentialVersion'],
+		credentialSha256: parsed['credentialSha256'],
+		githubApp: parsed['githubApp'],
+	})
+	return { ...active, state: 'active' }
+}
+
+export function buildZeropsSourceCredentialStatusResponseV2(
+	input:
+		| { readonly connectionId: string; readonly state: 'anonymous' }
+		| Omit<ZeropsSourceCredentialActiveStatusResponseV2, 'protocolVersion'>,
+): ZeropsSourceCredentialStatusResponseV2 {
+	return decodeZeropsSourceCredentialStatusResponseV2({ protocolVersion: ZEROPS_SOURCE_PROTOCOL_VERSION_V2, ...input })
+}
+
 const webhookUrl = (value: unknown, label: string): string => {
 	const candidate = boundedString(value, label, MAX_WEBHOOK_URL_LENGTH)
 	let parsed: URL
@@ -988,6 +1302,104 @@ export function buildZeropsSourceUploadResponse(result: ZeropsSourceUploadResult
 	return decodeZeropsSourceUploadResponse({ protocolVersion: ZEROPS_SOURCE_PROTOCOL_VERSION, ...result })
 }
 
+export function decodeZeropsSourceResolveRequestV2(value: unknown): ZeropsSourceResolveRequestV2 {
+	const parsed = record(value, 'source resolve request v2')
+	optionalFields(
+		parsed,
+		['protocolVersion', 'runId', 'repository', 'requestedRef', 'descriptorSha256'],
+		['expectedCommitSha', 'privateBinding'],
+		'source resolve request v2',
+	)
+	const expected = optionalCommitSha(parsed['expectedCommitSha'], 'source resolve request v2.expectedCommitSha')
+	const binding = optionalPrivateBindingV2(parsed['privateBinding'], 'source resolve request v2.privateBinding')
+	return {
+		protocolVersion: protocolVersionV2(parsed, 'source resolve request v2'),
+		runId: identifier(parsed['runId'], 'source resolve request v2.runId'),
+		repository: repository(parsed['repository'], 'source resolve request v2.repository'),
+		requestedRef: ref(parsed['requestedRef'], 'source resolve request v2.requestedRef'),
+		...(expected !== undefined ? { expectedCommitSha: expected } : {}),
+		...(binding !== undefined ? { privateBinding: binding } : {}),
+		descriptorSha256: sha256(parsed['descriptorSha256'], 'source resolve request v2.descriptorSha256'),
+	}
+}
+
+export function buildZeropsSourceResolveRequestV2(input: ZeropsSourceResolveInputV2): ZeropsSourceResolveRequestV2 {
+	return decodeZeropsSourceResolveRequestV2({
+		protocolVersion: ZEROPS_SOURCE_PROTOCOL_VERSION_V2,
+		runId: input.runId,
+		repository: input.repository,
+		requestedRef: input.requestedRef,
+		...(input.expectedCommitSha !== undefined ? { expectedCommitSha: input.expectedCommitSha } : {}),
+		...(input.privateBinding !== undefined ? { privateBinding: input.privateBinding } : {}),
+		descriptorSha256: input.descriptorSha256,
+	})
+}
+
+export function decodeZeropsSourceResolveResponseV2(value: unknown): ZeropsSourceResolveResponseV2 {
+	const parsed = record(value, 'source resolve response v2')
+	exactKeys(parsed, ['protocolVersion', 'runId', 'commitSha', 'descriptorSha256'], 'source resolve response v2')
+	return {
+		protocolVersion: protocolVersionV2(parsed, 'source resolve response v2'),
+		runId: identifier(parsed['runId'], 'source resolve response v2.runId'),
+		commitSha: commitSha(parsed['commitSha'], 'source resolve response v2.commitSha'),
+		descriptorSha256: sha256(parsed['descriptorSha256'], 'source resolve response v2.descriptorSha256'),
+	}
+}
+
+export function buildZeropsSourceResolveResponseV2(result: ZeropsSourceResolveResult): ZeropsSourceResolveResponseV2 {
+	return decodeZeropsSourceResolveResponseV2({ protocolVersion: ZEROPS_SOURCE_PROTOCOL_VERSION_V2, ...result })
+}
+
+export function decodeZeropsSourceUploadRequestV2(value: unknown): ZeropsSourceUploadRequestV2 {
+	const parsed = record(value, 'source upload request v2')
+	optionalFields(
+		parsed,
+		['protocolVersion', 'runId', 'appVersionId', 'repository', 'commitSha', 'uploadUrl', 'descriptor'],
+		['privateBinding'],
+		'source upload request v2',
+	)
+	const binding = optionalPrivateBindingV2(parsed['privateBinding'], 'source upload request v2.privateBinding')
+	return {
+		protocolVersion: protocolVersionV2(parsed, 'source upload request v2'),
+		runId: identifier(parsed['runId'], 'source upload request v2.runId'),
+		appVersionId: identifier(parsed['appVersionId'], 'source upload request v2.appVersionId'),
+		repository: repository(parsed['repository'], 'source upload request v2.repository'),
+		commitSha: commitSha(parsed['commitSha'], 'source upload request v2.commitSha'),
+		...(binding !== undefined ? { privateBinding: binding } : {}),
+		uploadUrl: uploadUrl(parsed['uploadUrl'], 'source upload request v2.uploadUrl'),
+		descriptor: descriptor(parsed['descriptor'], 'source upload request v2.descriptor'),
+	}
+}
+
+export function buildZeropsSourceUploadRequestV2(input: ZeropsSourceUploadInputV2): ZeropsSourceUploadRequestV2 {
+	return decodeZeropsSourceUploadRequestV2({
+		protocolVersion: ZEROPS_SOURCE_PROTOCOL_VERSION_V2,
+		runId: input.runId,
+		appVersionId: input.appVersionId,
+		repository: input.repository,
+		commitSha: input.commitSha,
+		...(input.privateBinding !== undefined ? { privateBinding: input.privateBinding } : {}),
+		uploadUrl: input.uploadUrl,
+		descriptor: input.descriptor,
+	})
+}
+
+export function decodeZeropsSourceUploadResponseV2(value: unknown): ZeropsSourceUploadResponseV2 {
+	const parsed = record(value, 'source upload response v2')
+	exactKeys(parsed, ['protocolVersion', 'runId', 'appVersionId', 'commitSha', 'descriptorSha256'], 'source upload response v2')
+	return {
+		protocolVersion: protocolVersionV2(parsed, 'source upload response v2'),
+		runId: identifier(parsed['runId'], 'source upload response v2.runId'),
+		appVersionId: identifier(parsed['appVersionId'], 'source upload response v2.appVersionId'),
+		commitSha: commitSha(parsed['commitSha'], 'source upload response v2.commitSha'),
+		descriptorSha256: sha256(parsed['descriptorSha256'], 'source upload response v2.descriptorSha256'),
+	}
+}
+
+export function buildZeropsSourceUploadResponseV2(result: ZeropsSourceUploadResult): ZeropsSourceUploadResponseV2 {
+	return decodeZeropsSourceUploadResponseV2({ protocolVersion: ZEROPS_SOURCE_PROTOCOL_VERSION_V2, ...result })
+}
+
 export function decodeZeropsSourceCancelRequest(value: unknown): ZeropsSourceCancelRequestV1 {
 	const parsed = record(value, 'source cancel request')
 	exactKeys(parsed, ['protocolVersion', 'runId', 'appVersionId'], 'source cancel request')