@fabrika/control-contract 0.2.0 → 0.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/control-contract",
-	"version": "0.2.0",
+	"version": "0.3.2",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -24,7 +24,9 @@
 		"typecheck": "tsc --noEmit"
 	},
 	"dependencies": {
-		"@fabrika/app": "^0.2.0",
-		"@fabrika/provider-contract": "^0.2.0"
+		"zod": "^3.25.76",
+		"@fabrika/auth-core": "^0.3.2",
+		"@fabrika/app": "^0.3.2",
+		"@fabrika/provider-contract": "^0.3.2"
 	}
 }

package/src/builder-bootstrap.ts

@@ -0,0 +1,71 @@
+import { z } from 'zod'
+
+export const BUILDER_APPROVAL_STORAGE_KEY = 'fabrika.builder.approval.v1'
+export const BUILDER_AUTHORIZE_PATH = '/builder/authorize'
+
+export interface BuilderApprovalState {
+	readonly attemptId: string
+	readonly approvalVerifier: string
+	readonly expiresAt: number
+}
+
+export interface BuilderInstallationDiscoveryDto {
+	readonly version: 1
+	readonly controlOrigin: string
+	readonly iamIssuer: string
+	readonly provider: string
+}
+
+/** Self-contained so the public capture page can embed this exact validator without external assets. */
+export function parseBuilderApprovalState(value: unknown, nowSeconds = Math.floor(Date.now() / 1000)): BuilderApprovalState | null {
+	if (typeof value !== 'object' || value === null || Array.isArray(value)) return null
+	if (Object.keys(value).length !== 3 || Object.keys(value).some((key) => !['attemptId', 'approvalVerifier', 'expiresAt'].includes(key))) return null
+	const attemptId: unknown = Reflect.get(value, 'attemptId')
+	const approvalVerifier: unknown = Reflect.get(value, 'approvalVerifier')
+	const expiresAt: unknown = Reflect.get(value, 'expiresAt')
+	if (typeof attemptId !== 'string' || !/^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(attemptId)) return null
+	if (typeof approvalVerifier !== 'string' || !/^[A-Za-z0-9_-]{43}$/.test(approvalVerifier)) return null
+	if (typeof expiresAt !== 'number' || !Number.isSafeInteger(expiresAt) || expiresAt <= nowSeconds || expiresAt > nowSeconds + 600) return null
+	return { attemptId, approvalVerifier, expiresAt }
+}
+
+/** Accept only a credential-free installation origin, never a redirect or a repository-selected path. */
+export function parseBuilderPublicOrigin(value: unknown): string | null {
+	if (typeof value !== 'string' || value.length > 2048) return null
+	try {
+		const url = new URL(value)
+		const local = url.hostname === 'localhost' || url.hostname.endsWith('.localhost') || url.hostname === '[::1]'
+			|| /^127(?:\.[0-9]{1,3}){3}$/.test(url.hostname)
+		if (url.protocol !== 'https:' && !(url.protocol === 'http:' && local)) return null
+		if (url.username !== '' || url.password !== '' || url.pathname !== '/' || url.search !== '' || url.hash !== '') return null
+		return url.origin
+	} catch {
+		return null
+	}
+}
+
+export function parseBuilderInstallationDiscovery(value: unknown): BuilderInstallationDiscoveryDto | null {
+	const result = builderInstallationDiscoverySchema.safeParse(value)
+	return result.success ? result.data : null
+}
+
+export const builderPublicOriginSchema = z.string().transform((value, ctx) => {
+	const origin = parseBuilderPublicOrigin(value)
+	if (origin !== null) return origin
+	ctx.addIssue({ code: 'custom', message: 'invalid builder public origin' })
+	return z.NEVER
+})
+
+export const builderInstallationDiscoverySchema = z.preprocess(
+	(value) => {
+		// Discovery requires four own fields, even when a prototype supplies otherwise valid values.
+		if (typeof value === 'object' && value !== null && Object.keys(value).length !== 4) return undefined
+		return value
+	},
+	z.object({
+		version: z.literal(1),
+		controlOrigin: builderPublicOriginSchema,
+		iamIssuer: builderPublicOriginSchema,
+		provider: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/),
+	}).strict(),
+)

package/src/builder-connections.ts

@@ -0,0 +1,86 @@
+import { z } from 'zod'
+import type { AppDto } from './index.js'
+
+export const BUILDER_CONNECTION_ATTEMPT_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/
+export const BUILDER_APPROVAL_VERIFIER = /^[A-Za-z0-9_-]{43}$/
+export const BUILDER_CONNECTION_IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/
+
+export interface BuilderConnectionEnvironmentDto {
+	readonly env: string
+	readonly namespaceId: string | null
+	readonly domain: string | null
+	readonly publicOrigin: string | null
+	readonly triggerRef: string | null
+}
+
+export interface BuilderConnectionReceiptDto {
+	readonly version: 1
+	readonly attemptId: string
+	readonly provider: string
+	readonly app: AppDto
+	readonly environment: BuilderConnectionEnvironmentDto
+	readonly createdAt: number
+}
+
+export interface CreateBuilderConnectionReceiptRequest {
+	readonly attemptId: string
+	readonly approvalVerifier: string
+	readonly appId: string
+	readonly environment: BuilderConnectionEnvironmentDto
+}
+
+export interface GetBuilderConnectionReceiptRequest {
+	readonly attemptId: string
+}
+
+/** Decode the persisted/wire snapshot without accepting provider envelopes or credential fields. */
+export function parseBuilderConnectionReceipt(value: unknown): BuilderConnectionReceiptDto {
+	const result = builderConnectionReceiptSchema.safeParse(value)
+	if (result.success) return result.data
+	const issues = result.error.issues
+	const objectIssue = (path: string) =>
+		issues.some((issue) => issue.path.join('.') === path && (issue.code === 'invalid_type' || issue.code === 'unrecognized_keys'))
+	if (objectIssue('')) throw new Error('invalid builder connection receipt object')
+	if (issues.some((issue) => issue.path[0] === 'version')) throw new Error('unsupported builder connection receipt version')
+	if (objectIssue('app') || objectIssue('environment')) throw new Error('invalid builder connection receipt object')
+	if (issues.some((issue) => issue.path.join('.') === 'app.githubInstallationId')) throw new Error('invalid githubInstallationId')
+	const issue = issues[0]
+	throw new Error(`invalid receipt ${issue?.path.at(-1) ?? 'object'}`)
+}
+
+const receiptTimestampSchema = z.number().int().safe().nonnegative()
+const receiptIdentifierSchema = z.string().regex(BUILDER_CONNECTION_IDENTIFIER)
+
+export const builderConnectionAppSchema = z.object({
+	id: receiptIdentifierSchema,
+	repoUrl: z.string(),
+	defaultBranch: z.string(),
+	workerDir: z.string().nullable(),
+	buildCmd: z.string().nullable(),
+	configPath: z.string().nullable(),
+	githubConnectionId: z.string().nullable().optional(),
+	githubInstallationId: receiptTimestampSchema.nullable(),
+	createdAt: receiptTimestampSchema,
+}).strict().transform(({ githubConnectionId, githubInstallationId, createdAt, ...app }) => ({
+	...app,
+	...(githubConnectionId === undefined ? {} : { githubConnectionId }),
+	githubInstallationId,
+	createdAt,
+}))
+
+export const builderConnectionEnvironmentSchema = z.object({
+	env: receiptIdentifierSchema,
+	namespaceId: z.string().min(1).max(128).nullable(),
+	domain: z.string().min(1).max(253).nullable(),
+	publicOrigin: z.string().min(1).max(2048).nullable(),
+	triggerRef: z.string().min(1).max(1024).nullable(),
+}).strict()
+
+export const builderConnectionReceiptSchema = z.object({
+	version: z.literal(1),
+	attemptId: z.string().regex(BUILDER_CONNECTION_ATTEMPT_ID),
+	provider: receiptIdentifierSchema,
+	app: builderConnectionAppSchema,
+	environment: builderConnectionEnvironmentSchema,
+	createdAt: receiptTimestampSchema,
+}).strict()

package/src/builder-pairing.ts

@@ -0,0 +1,24 @@
+export type {
+	ApproveDeviceAuthorizationResult,
+	DenyDeviceAuthorizationResult,
+	DeviceAuthorizationFailure,
+	DeviceAuthorizationReceipt,
+	DeviceAuthorizationRequest,
+	InspectDeviceAuthorizationResult,
+	ListOwnDeviceAuthorizationsResult,
+	RevokeKeyResult,
+} from '@fabrika/auth-core'
+
+export interface BuilderPairingProofRequest {
+	readonly attemptId: string
+	readonly approvalVerifier: string
+}
+
+export interface ListOwnBuilderPairingsRequest {
+	readonly before?: string
+	readonly limit?: number
+}
+
+export interface RevokeBuilderPairingRequest {
+	readonly credentialId: string
+}

package/src/index.ts

@@ -1,4 +1,9 @@
 import type { JsonValue, ProviderEnvelope } from '@fabrika/provider-contract'
+import { z } from 'zod'
+
+export * from './builder-bootstrap.js'
+export * from './builder-connections.js'
+export * from './builder-pairing.js'
 
 export type { JsonValue }
 
@@ -15,6 +20,12 @@ export interface CursorList<T> {
 
 export type ProviderEnvelopeDto = ProviderEnvelope
 
+/** What the console needs to know about the installation it runs in. */
+export interface InstallationDto {
+	/** The id of the one provider bundle this installation composes (ADR-0011). */
+	readonly provider: string
+}
+
 export interface GitHubSourceRepositoryDto {
 	readonly owner: string
 	readonly name: string
@@ -79,9 +90,7 @@ export interface GitHubSourceConnectionConnectedDto extends GitHubSourceConnecti
 
 export type GitHubSourceConnectionWorkflowDto = Exclude<GitHubSourceConnectionStatusDto, GitHubSourceConnectionConnectedDto>
 
-export const GITHUB_SOURCE_CONNECTION_DEFAULT_PAGE_SIZE = 50
-export const GITHUB_SOURCE_CONNECTION_MAX_PAGE_SIZE = 100
-export const GITHUB_SOURCE_CONNECTION_PAGE_CURSOR_MAX_LENGTH = 512
+export * from './source-connection-list.js'
 
 export interface GitHubSourceConnectionListInput {
 	readonly cursor?: string
@@ -95,32 +104,6 @@ export interface GitHubSourceConnectionListResponse {
 	readonly workflow: GitHubSourceConnectionWorkflowDto | null
 }
 
-export function decodeGitHubSourceConnectionListInput(value: unknown): GitHubSourceConnectionListInput {
-	if (typeof value !== 'object' || value === null || Array.isArray(value)) {
-		throw new Error('source connection list input must be an object')
-	}
-	const unknownField = Object.keys(value).find((key) => key !== 'cursor' && key !== 'limit')
-	if (unknownField !== undefined) throw new Error('source connection list input contains an unknown field')
-	const cursorValue = Reflect.get(value, 'cursor')
-	if (
-		cursorValue !== undefined
-		&& (typeof cursorValue !== 'string' || cursorValue.length === 0 || cursorValue.length > GITHUB_SOURCE_CONNECTION_PAGE_CURSOR_MAX_LENGTH)
-	) {
-		throw new Error(`source connection list cursor must be a non-empty string of at most ${GITHUB_SOURCE_CONNECTION_PAGE_CURSOR_MAX_LENGTH} characters`)
-	}
-	const limitValue = Reflect.get(value, 'limit')
-	if (
-		limitValue !== undefined
-		&& (typeof limitValue !== 'number' || !Number.isSafeInteger(limitValue) || limitValue < 1 || limitValue > GITHUB_SOURCE_CONNECTION_MAX_PAGE_SIZE)
-	) {
-		throw new Error(`source connection list limit must be an integer from 1 to ${GITHUB_SOURCE_CONNECTION_MAX_PAGE_SIZE}`)
-	}
-	return {
-		...(cursorValue !== undefined ? { cursor: cursorValue } : {}),
-		...(limitValue !== undefined ? { limit: limitValue } : {}),
-	}
-}
-
 export interface GitHubSourceConnectionRepairRequiredDto extends GitHubSourceConnectionBaseDto {
 	readonly state: 'repair-required'
 	readonly connectionId: string
@@ -150,12 +133,14 @@ export interface StartGitHubSourceConnectionResponse {
 	readonly continuePath: string
 }
 
-/** One redacted line of deploy output exposed by the control API. */
-export interface RunLogLine {
-	readonly ts: number
-	readonly stream: 'stdout' | 'stderr' | 'meta'
-	readonly text: string
-}
+/** One redacted line of deploy output: the runner's NDJSON log line and the control API's view of it. */
+export const runLogLineSchema = z.object({
+	ts: z.number().finite(),
+	stream: z.enum(['stdout', 'stderr', 'meta']),
+	text: z.string(),
+})
+
+export type RunLogLine = z.infer<typeof runLogLineSchema>
 
 /** Backward-compatible short name for browser consumers. */
 export type LogLine = RunLogLine
@@ -182,7 +167,9 @@ export interface AppOptionalFields {
 	workerDir?: string | null
 	buildCmd?: string | null
 	configPath?: string | null
+	/** Must equal the installation of the repository owner's GitHub connection. */
 	githubInstallationId?: number | null
+	/** Bind the app to the repository owner's GitHub connection (one per owner). */
 	resolveInstallationId?: boolean
 }
 
@@ -212,22 +199,6 @@ export interface PutAppEnvRequest {
 	artifact: ProviderEnvelopeDto
 }
 
-export interface CloudflareTargetEnvelope extends ProviderEnvelopeDto {
-	provider: 'cloudflare'
-	version: 1
-	payload: {
-		stateNamespace?: string
-	}
-}
-
-export interface CloudflareArtifactEnvelope extends ProviderEnvelopeDto {
-	provider: 'cloudflare'
-	version: 1
-	payload: {
-		configPath: string
-	}
-}
-
 export type DeploymentNamespaceState = 'pending' | 'provisioning' | 'ready' | 'failed'
 
 export interface DeploymentNamespaceDto {
@@ -341,17 +312,26 @@ export interface PlanDeploymentNamespaceResponse {
 	readonly presentation: DeploymentNamespacePresentationDto
 }
 
+/**
+ * Where an app secret's value is kept: `vault` (control's vault), `provider` (the provider's own storage),
+ * or `legacy` — a row from before secrets were vault-only, which no deploy resolves until it is set again.
+ */
+export type AppSecretStorage = 'vault' | 'provider' | 'legacy'
+
 export interface AppSecretDto {
 	appId: string
 	env: string | null
 	name: string
-	valueRef: string
+	storage: AppSecretStorage
+	/** The `vault:` ref; null for any other storage, whose stored ref control cannot vouch for. */
+	valueRef: string | null
 	createdAt: number
 }
 
+/** The plaintext is write-only: control seals it and stores only the resulting ref. */
 export interface PutAppSecretRequest {
 	name: string
-	valueRef: string
+	value: string
 	env?: string | null
 }
 

package/src/rpc.ts

@@ -1,4 +1,15 @@
 import type { RpcProcedureContract } from '@fabrika/app'
+import type { BuilderConnectionReceiptDto, CreateBuilderConnectionReceiptRequest, GetBuilderConnectionReceiptRequest } from './builder-connections.js'
+import type {
+	ApproveDeviceAuthorizationResult,
+	BuilderPairingProofRequest,
+	DenyDeviceAuthorizationResult,
+	InspectDeviceAuthorizationResult,
+	ListOwnBuilderPairingsRequest,
+	ListOwnDeviceAuthorizationsResult,
+	RevokeBuilderPairingRequest,
+	RevokeKeyResult,
+} from './builder-pairing.js'
 import type {
 	AdoptDeploymentNamespaceRequest,
 	AppDto,
@@ -12,6 +23,7 @@ import type {
 	GitHubSourceConnectionListInput,
 	GitHubSourceConnectionListResponse,
 	GitHubSourceConnectionStatusDto,
+	InstallationDto,
 	ListResponse,
 	PlanDeploymentNamespaceRequest,
 	PlanDeploymentNamespaceResponse,
@@ -24,7 +36,6 @@ import type {
 	RunDto,
 	RunLogResponse,
 	RunTailResponse,
-	SetSecretValueRequest,
 	StartGitHubSourceConnectionRequest,
 	StartGitHubSourceConnectionResponse,
 	TriggerDeployRequest,
@@ -105,7 +116,6 @@ export interface GitHubSourceConnectionInput {
 
 /** Provider-neutral admin seam. A statically composed provider implements these GitHub operations. */
 export interface GitHubSourceConnectionRpcContract {
-	status: RpcProcedure<void, GitHubSourceConnectionStatusDto>
 	list: RpcProcedure<GitHubSourceConnectionListInput, GitHubSourceConnectionListResponse>
 	start: RpcProcedure<StartGitHubSourceConnectionRequest, StartGitHubSourceConnectionResponse>
 	verifyInstallation: RpcProcedure<GitHubSourceConnectionInput, GitHubSourceConnectionStatusDto>
@@ -113,8 +123,20 @@ export interface GitHubSourceConnectionRpcContract {
 	reconcile: RpcProcedure<GitHubSourceConnectionInput, GitHubSourceConnectionStatusDto>
 }
 
-/** Portable Delivery control API, implemented alongside the backward-compatible REST transport. */
+/** Portable Delivery control API shared by browser and machine callers. */
 export interface ControlRpcContract {
+	installation: RpcProcedure<void, InstallationDto>
+	builderPairing: {
+		inspect: RpcProcedure<BuilderPairingProofRequest, InspectDeviceAuthorizationResult>
+		approve: RpcProcedure<BuilderPairingProofRequest, ApproveDeviceAuthorizationResult>
+		deny: RpcProcedure<BuilderPairingProofRequest, DenyDeviceAuthorizationResult>
+		listOwn: RpcProcedure<ListOwnBuilderPairingsRequest, ListOwnDeviceAuthorizationsResult>
+		revoke: RpcProcedure<RevokeBuilderPairingRequest, RevokeKeyResult>
+	}
+	builderConnections: {
+		createReceipt: RpcProcedure<CreateBuilderConnectionReceiptRequest, BuilderConnectionReceiptDto>
+		getReceipt: RpcProcedure<GetBuilderConnectionReceiptRequest, BuilderConnectionReceiptDto>
+	}
 	sourceConnection: GitHubSourceConnectionRpcContract
 	apps: {
 		list: RpcProcedure<void, ListResponse<AppDto>>

package/src/source-connection-list.ts

@@ -0,0 +1,13 @@
+import { z } from 'zod'
+
+export const GITHUB_SOURCE_CONNECTION_DEFAULT_PAGE_SIZE = 50
+export const GITHUB_SOURCE_CONNECTION_MAX_PAGE_SIZE = 100
+export const GITHUB_SOURCE_CONNECTION_PAGE_CURSOR_MAX_LENGTH = 512
+
+export const githubSourceConnectionListInputSchema = z.object({
+	cursor: z.string().min(1).max(GITHUB_SOURCE_CONNECTION_PAGE_CURSOR_MAX_LENGTH).optional(),
+	limit: z.number().int().safe().min(1).max(GITHUB_SOURCE_CONNECTION_MAX_PAGE_SIZE).optional(),
+}).strict().transform(({ cursor, limit }) => ({
+	...(cursor === undefined ? {} : { cursor }),
+	...(limit === undefined ? {} : { limit }),
+}))