@fabrika/provider-contract 0.0.1

package/package.json

@@ -0,0 +1,31 @@
+{
+	"name": "@fabrika/provider-contract",
+	"version": "0.0.1",
+	"type": "module",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/contember/fabrika-platform.git",
+		"directory": "packages/provider-contract"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"src",
+		"!src/**/__tests__/**"
+	],
+	"exports": {
+		".": {
+			"bun": "./src/index.ts",
+			"types": "./src/index.ts",
+			"default": "./src/index.ts"
+		}
+	},
+	"scripts": {
+		"typecheck": "tsc --noEmit",
+		"test": "bun test"
+	},
+	"dependencies": {
+		"@fabrika/auth-core": "^0.0.1"
+	}
+}

package/src/authoring.ts

@@ -0,0 +1,42 @@
+import type { AppSchema } from '@fabrika/auth-core'
+
+export const APP_PROVIDER = Symbol.for('@fabrika/provider-contract/app-provider')
+
+export interface ProviderAuthoredApp<Provider extends string = string> {
+	readonly [APP_PROVIDER]: Provider
+}
+
+export const authoredAppProvider = (value: unknown): string | undefined => {
+	if (typeof value !== 'object' || value === null) {
+		return undefined
+	}
+	const provider = Reflect.get(value, APP_PROVIDER)
+	return typeof provider === 'string' && provider !== '' ? provider : undefined
+}
+
+export const isProviderAuthoredApp = <Provider extends string>(
+	value: unknown,
+	provider: Provider,
+): value is ProviderAuthoredApp<Provider> => authoredAppProvider(value) === provider
+
+/** Provider-neutral build inputs and environment requirements declared by an app. */
+export interface AppPipeline {
+	/** Source directory relative to the app config file. Defaults to `.`. */
+	workerDir?: string
+	/** Shell command that builds the deployable artifact. */
+	build?: string
+	/** Secret names that must resolve before deployment. */
+	secrets?: string[]
+	/** Non-secret variable names that must resolve before deployment. */
+	vars?: string[]
+}
+
+/** App metadata shared by every provider-specific authoring config. */
+export interface AppConfigBase {
+	/** Stable app id, unique within one control plane. */
+	id: string
+	/** The app-owned authorization vocabulary reconciled into IAM. */
+	schema?: AppSchema
+	/** Provider-neutral build and environment requirements. */
+	pipeline?: AppPipeline
+}

package/src/control.ts

@@ -0,0 +1,224 @@
+import type { ProviderManagedEnvironment, ProviderRunEvents } from './deploy'
+import type { JsonValue, ProviderEnvelope } from './json'
+
+/** Provider-neutral coordinates for obtaining one app revision. */
+export interface ProviderSource {
+	readonly repoUrl: string
+	readonly ref: string
+	readonly workerDir?: string
+	readonly buildCommand?: string
+	readonly configPath?: string
+	readonly githubInstallationId?: number
+}
+
+/** App data needed by a control provider. */
+export interface ProviderApp {
+	readonly id: string
+	readonly source: ProviderSource
+}
+
+/** One provider-owned placement boundary shared by zero or more app environments. */
+export interface ProviderDeploymentNamespace {
+	readonly id: string
+	readonly env: string
+	readonly exclusiveAppId?: string
+	readonly target: ProviderEnvelope
+}
+
+/** Persisted deploy data for one app environment. */
+export interface ProviderEnvironment {
+	readonly appId: string
+	readonly env: string
+	readonly domain?: string
+	/** Canonical externally reachable HTTP(S) origin; independent of provider domain routing. */
+	readonly publicOrigin?: string
+	readonly namespace?: ProviderDeploymentNamespace
+	readonly target: ProviderEnvelope
+	readonly artifact: ProviderEnvelope
+}
+
+/** Raw registration data passed to provider-owned validation and normalization. */
+export interface ProviderRegistrationInput {
+	readonly app: ProviderApp
+	readonly environment: ProviderEnvironment
+}
+
+/** Canonical registration returned after provider-owned validation and normalization. */
+export type ProviderRegistration = ProviderRegistrationInput
+
+/** One control-plane deploy invocation. */
+export interface ProviderDeployInput {
+	readonly runId: string
+	readonly app: ProviderApp
+	readonly environment: ProviderEnvironment
+	readonly secrets: Readonly<Record<string, string>>
+	readonly vars: Readonly<Record<string, string>>
+	/** Platform-owned runtime configuration, separate from operator-managed application vars. */
+	readonly managedEnvironment: ProviderManagedEnvironment
+	/**
+	 * Every origin IAM may hand this app a session at (ADR-0021). App-wide, not per-environment:
+	 * IAM's registry is keyed by app id, so the set is assembled from every environment of the app.
+	 * Absent when the app has no public origin at all, which leaves IAM's registry untouched.
+	 */
+	readonly returnOrigins?: readonly string[]
+	readonly dryRun: boolean
+	/** Optional short-lived, run-scoped Operations artifact destination. */
+	readonly artifactUpload?: {
+		readonly url: string
+		readonly bearer: string
+		readonly appId: string
+		readonly environment: string
+		readonly serviceKey: string
+		readonly release: string
+		readonly runId: string
+	}
+	readonly signal: AbortSignal
+	readonly events: ProviderRunEvents
+}
+
+/** A terminal provider operation result. */
+export interface ProviderTerminalOutcome {
+	readonly state: 'succeeded' | 'failed'
+	readonly exitCode?: number
+	/** Whether provider-local release artifacts reached Operations. */
+	readonly artifactState?: 'complete' | 'incomplete' | 'not_applicable'
+}
+
+/** A platform-owned run that can be cancelled or reconciled. */
+export interface ProviderRunReference {
+	readonly runId: string
+	readonly externalId: string
+	readonly environment: ProviderEnvironment
+}
+
+export type ProviderCancelInput = ProviderRunReference
+
+export interface ProviderReconcileInput extends ProviderRunReference {
+	/** See `ProviderDeployInput.returnOrigins`; a provider that finishes a resumed deploy projects the same set. */
+	readonly returnOrigins?: readonly string[]
+}
+
+/** The latest state reported while reconciling a platform-owned run. */
+export interface ProviderReconcileOutcome {
+	readonly state: 'running' | 'succeeded' | 'failed'
+	readonly exitCode?: number
+}
+
+/** Write one secret value to provider-managed storage. */
+export interface ProviderSecretPutInput {
+	readonly environment: ProviderEnvironment
+	readonly name: string
+	readonly value: string
+}
+
+/** Remove one secret value from provider-managed storage. */
+export interface ProviderSecretDeleteInput {
+	readonly environment: ProviderEnvironment
+	readonly name: string
+}
+
+/** Opaque reference persisted by core instead of the provider-managed secret value. */
+export interface ProviderSecretPutResult {
+	readonly valueRef: string
+}
+
+/** Optional edit-time secret storage owned by a provider. */
+export interface ProviderManagedSecrets {
+	put(input: ProviderSecretPutInput): Promise<ProviderSecretPutResult>
+	delete(input: ProviderSecretDeleteInput): Promise<void>
+}
+
+/** Persist a canonical namespace target immediately after one external mutation succeeds. */
+export interface ProviderNamespaceEvents {
+	checkpoint(namespace: ProviderDeploymentNamespace): Promise<void>
+}
+
+/** One idempotent namespace lifecycle invocation. */
+export interface ProviderNamespaceMutationInput {
+	readonly namespace: ProviderDeploymentNamespace
+	readonly signal: AbortSignal
+	readonly events: ProviderNamespaceEvents
+}
+
+/** One registration whose provider coordinates do not exist until namespace services are prepared. */
+export interface ProviderRegistrationPreparationInput {
+	readonly registration: ProviderRegistration
+	readonly signal: AbortSignal
+}
+
+/** One provider-defined operator choice. Core does not interpret its id or description. */
+export interface ProviderNamespacePreset {
+	readonly id: string
+	readonly label: string
+	readonly description: string
+	readonly requiresExclusiveApp: boolean
+}
+
+/** Provider-neutral coordinates plus opaque provider options for a namespace preview. */
+export interface ProviderNamespacePlanInput {
+	readonly id: string
+	readonly env: string
+	readonly preset: string
+	readonly exclusiveAppId?: string
+	readonly options?: JsonValue
+}
+
+/** One safe, human-readable provider fact. Values must never contain credentials. */
+export interface ProviderNamespaceFact {
+	readonly label: string
+	readonly value: string
+}
+
+/** Provider-owned operator copy for a planned or persisted namespace. */
+export interface ProviderNamespacePresentation {
+	readonly preset: string
+	readonly title: string
+	readonly facts: readonly ProviderNamespaceFact[]
+	readonly instructions: readonly string[]
+}
+
+/** A mutation-free preview that can be submitted unchanged to namespace creation. */
+export interface ProviderNamespacePlan {
+	readonly namespace: ProviderDeploymentNamespace
+	readonly presentation: ProviderNamespacePresentation
+}
+
+/** Optional operator surface for providers that offer opinionated namespace presets. */
+export interface ProviderNamespaceOperator {
+	readonly presets: readonly ProviderNamespacePreset[]
+	plan(input: ProviderNamespacePlanInput): ProviderNamespacePlan
+	present(namespace: ProviderDeploymentNamespace): ProviderNamespacePresentation
+}
+
+/** Optional placement lifecycle owned by providers that use deployment namespaces. */
+export interface ProviderNamespaceCapabilities {
+	normalize(namespace: ProviderDeploymentNamespace): ProviderDeploymentNamespace
+	/** Namespace-owned resources that must be reserved before provisioning starts. */
+	namespaceResourceClaims(namespace: ProviderDeploymentNamespace): readonly string[]
+	/** App-owned resources derived from one canonical normalized registration. */
+	registrationResourceClaims(registration: ProviderRegistration): readonly string[]
+	/**
+	 * Materialize app-owned provider resources and return their canonical coordinates.
+	 * Core acquires every registration resource claim before invoking this mutation.
+	 */
+	prepareRegistration?(input: ProviderRegistrationPreparationInput): Promise<ProviderRegistration>
+	provision(input: ProviderNamespaceMutationInput): Promise<ProviderDeploymentNamespace>
+	reconcile(input: ProviderNamespaceMutationInput): Promise<ProviderDeploymentNamespace>
+	readonly operator?: ProviderNamespaceOperator
+}
+
+/**
+ * The control-plane capability bundle selected statically by one composition root.
+ *
+ * Core owns no provider registry. The selected provider validates registration envelopes and owns
+ * every provider-specific deploy lifecycle capability.
+ */
+export interface ControlProvider {
+	readonly id: string
+	normalizeRegistration(input: ProviderRegistrationInput): ProviderRegistration
+	deploy(input: ProviderDeployInput): Promise<ProviderTerminalOutcome>
+	cancel?(input: ProviderCancelInput): Promise<void>
+	reconcile?(input: ProviderReconcileInput): Promise<ProviderReconcileOutcome>
+	readonly secrets?: ProviderManagedSecrets
+	readonly namespaces?: ProviderNamespaceCapabilities
+}

package/src/deploy.ts

@@ -0,0 +1,85 @@
+import type { ProviderEnvelope } from './json'
+
+/** One provider-owned unit of deploy work. Core treats `kind` as an open string. */
+export interface ProviderJobSpec {
+	readonly id: string
+	readonly kind: string
+	readonly description: string
+	readonly dependsOn?: readonly string[]
+}
+
+/** Shared deploy state used for whole runs and individual steps. */
+export type ProviderRunStatus = 'pending' | 'running' | 'succeeded' | 'failed' | 'skipped'
+
+/** A provider job plus its observed runtime state. */
+export interface ProviderDeployStep {
+	readonly spec: ProviderJobSpec
+	readonly status: ProviderRunStatus
+	readonly error?: string
+	readonly startedAt?: number
+	readonly finishedAt?: number
+}
+
+/** The ordered work derived by a provider before it starts mutation. */
+export interface ProviderDeployPlan {
+	readonly appId: string
+	readonly env: string
+	readonly steps: readonly ProviderJobSpec[]
+}
+
+/** A provider-owned deploy session opened from one target and artifact. */
+export interface ProviderDeploySession {
+	readonly plan: ProviderDeployPlan
+	execute(stepId: string): Promise<void>
+}
+
+/** The final provider-neutral representation of a deploy execution. */
+export interface ProviderDeployResult {
+	readonly appId: string
+	readonly env: string
+	readonly status: ProviderRunStatus
+	readonly plan: ProviderDeployPlan
+	readonly steps: readonly ProviderDeployStep[]
+}
+
+/** Events whose persistence and presentation belong to the control plane. */
+export interface ProviderRunEvents {
+	log(line: string): void
+	externalId(id: string): Promise<void>
+}
+
+/** Complete platform-owned runtime state. A null value removes the key from persistent targets. */
+export type ProviderManagedEnvironment = Readonly<Record<string, string | null>>
+
+/** Universal inputs shared by every provider deploy. */
+export interface ProviderRunBase {
+	readonly appId: string
+	readonly env: string
+	readonly domain?: string
+	/**
+	 * Every origin IAM may hand this app a session at, as known by the control plane. App-wide rather
+	 * than per-environment, because IAM's registry is keyed by app id and a deploy of one environment
+	 * must not un-register the others.
+	 */
+	readonly returnOrigins?: readonly string[]
+	readonly cwd: string
+	readonly secrets: Readonly<Record<string, string>>
+	readonly vars: Readonly<Record<string, string>>
+	/** Platform-owned runtime configuration, separate from operator-managed application vars. */
+	readonly managedEnvironment: ProviderManagedEnvironment
+	readonly dryRun: boolean
+	readonly signal: AbortSignal
+	readonly events: ProviderRunEvents
+}
+
+/** The run shape seen by a provider after its envelopes have been decoded. */
+export interface TypedProviderRun<TTarget, TArtifact> extends ProviderRunBase {
+	readonly target: TTarget
+	readonly artifact: TArtifact
+}
+
+/** The provider-neutral run shape stored and passed by the control plane. */
+export interface RuntimeProviderRun extends ProviderRunBase {
+	readonly target: ProviderEnvelope
+	readonly artifact: ProviderEnvelope
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from './authoring'
+export * from './control'
+export * from './deploy'
+export * from './json'
+export * from './provider'
+export * from './schema'

package/src/json.ts

@@ -0,0 +1,16 @@
+/** A value that can cross the provider persistence boundary without provider-specific types. */
+export type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue }
+
+/** Persisted provider data. The provider owns the payload schema and its version. */
+export interface ProviderEnvelope {
+	readonly provider: string
+	readonly version: number
+	readonly payload: JsonValue
+}
+
+/** Converts one provider-owned value to and from its versioned JSON payload. */
+export interface ProviderCodec<T> {
+	readonly version: number
+	encode(value: T): JsonValue
+	decode(payload: JsonValue): T
+}

package/src/provider.ts

@@ -0,0 +1,78 @@
+import type { ProviderDeploySession, RuntimeProviderRun, TypedProviderRun } from './deploy'
+import type { ProviderCodec, ProviderEnvelope } from './json'
+
+/** A provider implementation with its target and artifact types preserved. */
+export interface ProviderDefinition<TId extends string, TTarget, TArtifact> {
+	readonly id: TId
+	readonly target: ProviderCodec<TTarget>
+	readonly artifact: ProviderCodec<TArtifact>
+	open(run: TypedProviderRun<TTarget, TArtifact>): Promise<ProviderDeploySession>
+}
+
+/** The opaque interface consumed by a provider-specific composition root. */
+export interface RuntimeProvider {
+	readonly id: string
+	open(run: RuntimeProviderRun): Promise<ProviderDeploySession>
+}
+
+/**
+ * A provider module exposes typed encoders to its authoring side and an opaque runtime adapter to
+ * its control-plane side.
+ */
+export interface ProviderModule<TId extends string, TTarget, TArtifact> {
+	readonly id: TId
+	encodeTarget(value: TTarget): ProviderEnvelope
+	encodeArtifact(value: TArtifact): ProviderEnvelope
+	readonly runtime: RuntimeProvider
+}
+
+const decodeEnvelope = <T>(kind: string, provider: string, envelope: ProviderEnvelope, codec: ProviderCodec<T>): T => {
+	if (envelope.provider !== provider) {
+		throw new Error(`${kind} belongs to provider "${envelope.provider}", expected "${provider}"`)
+	}
+	if (envelope.version !== codec.version) {
+		throw new Error(`${kind} schema version ${envelope.version} is not supported by provider "${provider}"`)
+	}
+	return codec.decode(envelope.payload)
+}
+
+/**
+ * Closes over a provider's concrete types and exposes only JSON envelopes at runtime.
+ *
+ * A new provider calls this factory in its own package. No central platform map or discriminated
+ * union changes when a provider id is added.
+ */
+export const createProvider = <TId extends string, TTarget, TArtifact>(
+	definition: ProviderDefinition<TId, TTarget, TArtifact>,
+): ProviderModule<TId, TTarget, TArtifact> => {
+	const envelope = <T>(codec: ProviderCodec<T>, value: T): ProviderEnvelope => ({
+		provider: definition.id,
+		version: codec.version,
+		payload: codec.encode(value),
+	})
+
+	return {
+		id: definition.id,
+		encodeTarget: (value) => envelope(definition.target, value),
+		encodeArtifact: (value) => envelope(definition.artifact, value),
+		runtime: {
+			id: definition.id,
+			open: async (run) =>
+				definition.open({
+					appId: run.appId,
+					env: run.env,
+					domain: run.domain,
+					returnOrigins: run.returnOrigins,
+					cwd: run.cwd,
+					secrets: run.secrets,
+					vars: run.vars,
+					managedEnvironment: run.managedEnvironment,
+					dryRun: run.dryRun,
+					signal: run.signal,
+					events: run.events,
+					target: decodeEnvelope('target', definition.id, run.target, definition.target),
+					artifact: decodeEnvelope('artifact', definition.id, run.artifact, definition.artifact),
+				}),
+		},
+	}
+}

package/src/schema.ts

@@ -0,0 +1,19 @@
+import type { AppSchema } from '@fabrika/auth-core'
+
+/** Inputs needed to reconcile one app's authorization vocabulary into IAM. */
+export interface SchemaReconcileInput {
+	url: string
+	app: string
+	schema: AppSchema
+	/**
+	 * Every origin IAM may hand this app a session at, as known by the control plane. Omitted leaves
+	 * IAM's registry alone; a supplied set replaces it. It travels beside the schema and never inside
+	 * it — an app declares its vocabulary, the control plane declares where the app lives.
+	 */
+	returnOrigins?: readonly string[]
+	adminKey?: string
+	signal: AbortSignal
+}
+
+/** Provider-neutral port for authorization schema reconciliation. */
+export type SchemaReconciler = (input: SchemaReconcileInput) => Promise<void>