@pellux/goodvibes-tui 0.20.3 → 0.22.0

package/src/input/onboarding/onboarding-wizard-cloudflare-step.ts

@@ -1,6 +1,6 @@
 import { CLOUDFLARE_COMPONENT_IDS, DEFAULT_CLOUDFLARE_COMPONENT_SELECTION } from '../../runtime/cloudflare-control-plane.ts';
 import { normalizeText } from './onboarding-wizard-helpers.ts';
-import type { OnboardingWizardController } from './onboarding-wizard.ts';
+import type { OnboardingWizardControllerLike } from './onboarding-wizard-types.ts';
 import type { OnboardingWizardFieldDefinition, OnboardingWizardStepDefinition } from './onboarding-wizard-types.ts';
 import {
   CLOUDFLARE_BATCH_MODE_OPTIONS,
@@ -14,7 +14,7 @@ import {
   getCloudflareSetupSource,
 } from './onboarding-wizard-cloudflare.ts';
 
-export function buildCloudflareStep(controller: OnboardingWizardController): OnboardingWizardStepDefinition {
+export function buildCloudflareStep(controller: OnboardingWizardControllerLike): OnboardingWizardStepDefinition {
   const config = controller.runtimeSnapshot?.config.cloudflare;
   const batch = controller.runtimeSnapshot?.config.batch;
   const enabledDefault = controller.isCapabilitySelected('cloudflare-batch') || config?.enabled === true;
@@ -257,6 +257,19 @@ export function buildCloudflareStep(controller: OnboardingWizardController): Onb
       );
     }
 
+    // Trust-proxy notice — shown when Tunnel is selected so the
+    // operator sees the security implication before applying.
+    const tunnelSelected = enabled && components.zeroTrustTunnel;
+    if (tunnelSelected) {
+      fields.push({
+        kind: 'status',
+        id: 'cloudflare.trust-proxy-notice',
+        label: 'trustProxy will be enabled for control plane and HTTP listener',
+        defaultValue: 'Notice',
+        hint: 'Selecting Zero Trust Tunnel auto-writes controlPlane.trustProxy=true and httpListener.trustProxy=true so the login rate-limiter keys on the real client IP (CF-Connecting-IP) rather than the tunnel egress address. RESIDUAL RISK: until the SDK validates CF-Connecting-IP against Cloudflare published IP ranges (handoff Item 5), a client that reaches the listener directly can spoof this header to bypass the per-IP rate-limiter. See docs/deployment-and-services.md for the full risk posture.',
+      });
+    }
+
     if (components.zeroTrustAccess) {
       fields.push(
         {
@@ -463,6 +476,7 @@ export function buildCloudflareStep(controller: OnboardingWizardController): Onb
       `Components: ${enabled ? componentCount : 0} selected`,
       `Token setup: ${enabled ? setupSource : 'not used'}`,
       `Provision on final apply: ${enabled ? controller.getStringFieldValue('cloudflare.provision-on-apply', 'no') : 'no'}`,
+      ...(enabled && components.zeroTrustTunnel ? ['trustProxy: enabled for control plane and HTTP listener (see security notice)'] : []),
     ],
     fields,
   };

package/src/input/onboarding/onboarding-wizard-cloudflare.ts

@@ -8,7 +8,7 @@ import {
   type CloudflareProvisionRequest,
 } from '../../runtime/cloudflare-control-plane.ts';
 import { buildGoodVibesSecretRef, normalizeText } from './onboarding-wizard-helpers.ts';
-import type { OnboardingWizardController } from './onboarding-wizard.ts';
+import type { OnboardingWizardControllerLike } from './onboarding-wizard-types.ts';
 import type { OnboardingWizardRadioOption } from './onboarding-wizard-types.ts';
 
 export const CLOUDFLARE_SETUP_SOURCE_OPTIONS: readonly OnboardingWizardRadioOption[] = [
@@ -90,7 +90,7 @@ export function cloudflareComponentLabel(component: CloudflareComponent): string
   return CLOUDFLARE_COMPONENT_LABELS[component];
 }
 
-export function isCloudflareConfigured(controller: OnboardingWizardController): boolean {
+export function isCloudflareConfigured(controller: OnboardingWizardControllerLike): boolean {
   const config = controller.runtimeSnapshot?.config.cloudflare;
   if (!config) return false;
   return config.enabled
@@ -100,11 +100,11 @@ export function isCloudflareConfigured(controller: OnboardingWizardController):
     || normalizeText(config.workerName).length > 0;
 }
 
-export function shouldShowCloudflareStep(controller: OnboardingWizardController): boolean {
+export function shouldShowCloudflareStep(controller: OnboardingWizardControllerLike): boolean {
   return controller.isCapabilitySelected('cloudflare-batch') || isCloudflareConfigured(controller);
 }
 
-export function getCloudflareSetupSource(controller: OnboardingWizardController): CloudflareSetupSource {
+export function getCloudflareSetupSource(controller: OnboardingWizardControllerLike): CloudflareSetupSource {
   const configuredTokenRef = controller.runtimeSnapshot?.config.cloudflare.apiTokenRef ?? '';
   const defaultValue = configuredTokenRef.startsWith('goodvibes://secrets/env/') ? 'operational-env' : 'save-only';
   const value = controller.getStringFieldValue('cloudflare.setup-source', defaultValue);
@@ -120,7 +120,7 @@ export function getCloudflareSetupSource(controller: OnboardingWizardController)
   return 'save-only';
 }
 
-export function getCloudflareComponentSelection(controller: OnboardingWizardController): Record<CloudflareComponent, boolean> {
+export function getCloudflareComponentSelection(controller: OnboardingWizardControllerLike): Record<CloudflareComponent, boolean> {
   const selected: Record<CloudflareComponent, boolean> = { ...DEFAULT_CLOUDFLARE_COMPONENT_SELECTION };
   const configured = controller.runtimeSnapshot?.config.cloudflare;
   for (const component of CLOUDFLARE_COMPONENT_IDS) {
@@ -132,11 +132,11 @@ export function getCloudflareComponentSelection(controller: OnboardingWizardCont
   return selected;
 }
 
-export function getSelectedCloudflareComponents(controller: OnboardingWizardController): CloudflareComponentSelection {
+export function getSelectedCloudflareComponents(controller: OnboardingWizardControllerLike): CloudflareComponentSelection {
   return getCloudflareComponentSelection(controller);
 }
 
-export function getCloudflareBatchMode(controller: OnboardingWizardController): CloudflareBatchMode {
+export function getCloudflareBatchMode(controller: OnboardingWizardControllerLike): CloudflareBatchMode {
   const value = controller.getStringFieldValue('cloudflare.batch-mode', controller.runtimeSnapshot?.config.batch.mode ?? 'off');
   return value === 'explicit' || value === 'eligible-by-default' ? value : 'off';
 }
@@ -146,7 +146,7 @@ export function buildCloudflareApiTokenRef(envName: string): string {
   return `goodvibes://secrets/env/${encodeURIComponent(normalized)}`;
 }
 
-export function buildCloudflareProvisionRequest(controller: OnboardingWizardController, options: {
+export function buildCloudflareProvisionRequest(controller: OnboardingWizardControllerLike, options: {
   readonly includeTransientSecrets?: boolean;
 } = {}): CloudflareProvisionRequest {
   const components = getCloudflareComponentSelection(controller);

package/src/input/onboarding/onboarding-wizard-external-surface-extra-specs.ts

@@ -1,4 +1,4 @@
-import type { ExternalSurfaceSpec } from './onboarding-wizard-external-surfaces.ts';
+import type { ExternalSurfaceSpec } from './onboarding-wizard-types.ts';
 
 export const WEBHOOK_SURFACE_SPEC: ExternalSurfaceSpec = {
   id: 'webhook',

package/src/input/onboarding/onboarding-wizard-external-surfaces.ts

@@ -8,36 +8,9 @@ import { DEFAULT_CONFIG, type ConfigKey } from '../../config/index.ts';
 import type { OnboardingSnapshotState } from '../../runtime/onboarding/index.ts';
 import { TELEGRAM_MODE_OPTIONS, WHATSAPP_PROVIDER_OPTIONS } from './onboarding-wizard-constants.ts';
 import { HOME_ASSISTANT_SURFACE_SPEC, WEBHOOK_SURFACE_SPEC } from './onboarding-wizard-external-surface-extra-specs.ts';
-import type { OnboardingWizardRadioOption } from './onboarding-wizard-types.ts';
+import type { ExternalSurfaceSetupFieldSpec, ExternalSurfaceSpec, OnboardingWizardRadioOption } from './onboarding-wizard-types.ts';
 
-export interface ExternalSurfaceSetupFieldSpec {
-  readonly id: string;
-  readonly configKey: ConfigKey;
-  readonly kind: 'text' | 'masked' | 'radio';
-  readonly valueType?: 'string' | 'number';
-  readonly label: string;
-  readonly hint: string;
-  readonly placeholder: string;
-  readonly options?: readonly OnboardingWizardRadioOption[];
-  readonly defaultNumber?: number;
-  readonly min?: number;
-  readonly max?: number;
-  readonly defaultValue: (snapshot: OnboardingSnapshotState | null) => string;
-}
-
-export interface ExternalSurfaceSpec {
-  readonly id: string;
-  readonly enabledFieldId: string;
-  readonly enabledConfigKey: ConfigKey;
-  readonly label: string;
-  readonly hint: string;
-  /**
-   * Existing SDK config key. In onboarding this maps to the per-surface
-   * auto-start choice, not to whether setup fields are shown.
-   */
-  readonly defaultEnabled: (snapshot: OnboardingSnapshotState | null) => boolean;
-  readonly fields: readonly ExternalSurfaceSetupFieldSpec[];
-}
+export type { ExternalSurfaceSetupFieldSpec, ExternalSurfaceSpec };
 
 function normalizeConfigValue(value: unknown): string {
   if (value === null || value === undefined) return '';

package/src/input/onboarding/onboarding-wizard-rules.ts

@@ -7,10 +7,10 @@ import {
   isExternalSurfaceSelectedByDefault,
 } from './onboarding-wizard-external-surfaces.ts';
 import { getExternalSurfaceSpecByFieldId, normalizeText, uniqueNonEmpty } from './onboarding-wizard-helpers.ts';
-import type { OnboardingWizardController } from './onboarding-wizard.ts';
+import type { OnboardingWizardControllerLike } from './onboarding-wizard-types.ts';
 
 export function getSharedIpDefault(
-  controller: OnboardingWizardController,
+  controller: OnboardingWizardControllerLike,
     enabled: { readonly controlPlane: boolean; readonly httpListener: boolean; readonly web: boolean },
   ): boolean {
     if (!controller.runtimeSnapshot) return true;
@@ -23,7 +23,7 @@ export function getSharedIpDefault(
   }
 
 export function getSharedIpHostDefault(
-  controller: OnboardingWizardController,
+  controller: OnboardingWizardControllerLike,
     enabled: { readonly controlPlane: boolean; readonly httpListener: boolean; readonly web: boolean },
   ): string {
     if (!controller.runtimeSnapshot) return '0.0.0.0';
@@ -35,7 +35,7 @@ export function getSharedIpHostDefault(
     return hosts[0] ?? '0.0.0.0';
   }
 
-export function toggleCapability(controller: OnboardingWizardController, capabilityId: OnboardingStep1CapabilityId): void {
+export function toggleCapability(controller: OnboardingWizardControllerLike, capabilityId: OnboardingStep1CapabilityId): void {
     if (capabilityId === 'local-tui-only') {
       for (const capability of controller.getCurrentCapabilities()) {
         controller.toggleState.set(`capabilities.${capability.id}`, capability.id === 'local-tui-only');
@@ -58,31 +58,31 @@ export function toggleCapability(controller: OnboardingWizardController, capabil
     if (!anyServerCapability) controller.toggleState.set('capabilities.local-tui-only', true);
   }
 
-export function selectAllServerCapabilities(controller: OnboardingWizardController): void {
+export function selectAllServerCapabilities(controller: OnboardingWizardControllerLike): void {
     for (const capability of controller.getCurrentCapabilities()) {
       controller.toggleState.set(`capabilities.${capability.id}`, capability.id !== 'local-tui-only');
     }
   }
 
-export function selectLocalTuiOnly(controller: OnboardingWizardController): void {
+export function selectLocalTuiOnly(controller: OnboardingWizardControllerLike): void {
     for (const capability of controller.getCurrentCapabilities()) {
       controller.toggleState.set(`capabilities.${capability.id}`, capability.id === 'local-tui-only');
     }
   }
 
-export function selectAllExternalSurfaces(controller: OnboardingWizardController): void {
+export function selectAllExternalSurfaces(controller: OnboardingWizardControllerLike): void {
     for (const surface of EXTERNAL_SURFACE_SPECS) {
       controller.toggleState.set(surface.enabledFieldId, true);
     }
   }
 
-export function clearExternalSurfaces(controller: OnboardingWizardController): void {
+export function clearExternalSurfaces(controller: OnboardingWizardControllerLike): void {
     for (const surface of EXTERNAL_SURFACE_SPECS) {
       controller.toggleState.set(surface.enabledFieldId, false);
     }
   }
 
-export function setCapabilityValue(controller: OnboardingWizardController, capabilityId: OnboardingStep1CapabilityId, selected: boolean): void {
+export function setCapabilityValue(controller: OnboardingWizardControllerLike, capabilityId: OnboardingStep1CapabilityId, selected: boolean): void {
     if (capabilityId === 'local-tui-only') {
       if (selected) {
         for (const capability of controller.getCurrentCapabilities()) {
@@ -112,20 +112,20 @@ export function setCapabilityValue(controller: OnboardingWizardController, capab
     if (!anyServerCapability) controller.toggleState.set('capabilities.local-tui-only', true);
   }
 
-export function isCapabilitySelected(controller: OnboardingWizardController, capabilityId: OnboardingStep1CapabilityId): boolean {
+export function isCapabilitySelected(controller: OnboardingWizardControllerLike, capabilityId: OnboardingStep1CapabilityId): boolean {
     return controller.getCapabilitySelectionState().some((capability) => capability.id === capabilityId && capability.selected);
   }
 
-export function hasServerCapabilitiesSelected(controller: OnboardingWizardController): boolean {
+export function hasServerCapabilitiesSelected(controller: OnboardingWizardControllerLike): boolean {
     return controller.getCapabilitySelectionState().some((capability) => capability.id !== 'local-tui-only' && capability.selected);
   }
 
-export function shouldEnableBrowserSurface(controller: OnboardingWizardController): boolean {
+export function shouldEnableBrowserSurface(controller: OnboardingWizardControllerLike): boolean {
     return controller.hasServerCapabilitiesSelected()
       && (controller.isCapabilitySelected('browser-access') || controller.isCapabilitySelected('network-access'));
   }
 
-export function hasSelectedInboundExternalSurface(controller: OnboardingWizardController): boolean {
+export function hasSelectedInboundExternalSurface(controller: OnboardingWizardControllerLike): boolean {
     if (!controller.isCapabilitySelected('external-integrations')) return false;
     return EXTERNAL_SURFACE_SPECS.some((surface) => (
       INBOUND_EXTERNAL_SURFACE_IDS.has(surface.id)
@@ -140,7 +140,7 @@ export function hasSelectedInboundExternalSurface(controller: OnboardingWizardCo
     ));
   }
 
-export function isRequiredExternalSetupField(controller: OnboardingWizardController, fieldId: string): boolean {
+export function isRequiredExternalSetupField(controller: OnboardingWizardControllerLike, fieldId: string): boolean {
     if (!REQUIRED_EXTERNAL_SETUP_FIELD_IDS.has(fieldId)) return false;
     const surface = getExternalSurfaceSpecByFieldId(fieldId);
     if (!surface) return false;
@@ -163,7 +163,7 @@ export function isRequiredExternalSetupField(controller: OnboardingWizardControl
     return true;
   }
 
-export function getSelectedSecretMedium(controller: OnboardingWizardController): 'secure' | 'plaintext' {
+export function getSelectedSecretMedium(controller: OnboardingWizardControllerLike): 'secure' | 'plaintext' {
     const policy = controller.getStringFieldValue(
       'external-services.secret-policy',
       controller.runtimeSnapshot?.runtimeDefaults.secretStoragePolicy ?? 'preferred_secure',
@@ -174,12 +174,12 @@ export function getSelectedSecretMedium(controller: OnboardingWizardController):
     return 'plaintext';
   }
 
-export function shouldEnableHttpListener(controller: OnboardingWizardController): boolean {
+export function shouldEnableHttpListener(controller: OnboardingWizardControllerLike): boolean {
     return controller.hasServerCapabilitiesSelected()
       && (controller.isCapabilitySelected('webhook-events') || controller.hasSelectedInboundExternalSurface());
   }
 
-export function shouldExposeHttpListenerNetworkFields(controller: OnboardingWizardController): boolean {
+export function shouldExposeHttpListenerNetworkFields(controller: OnboardingWizardControllerLike): boolean {
     return controller.hasServerCapabilitiesSelected()
       && (
         controller.isCapabilitySelected('webhook-events')
@@ -188,31 +188,31 @@ export function shouldExposeHttpListenerNetworkFields(controller: OnboardingWiza
       );
   }
 
-export function shouldExposeControlPlaneNetwork(controller: OnboardingWizardController): boolean {
+export function shouldExposeControlPlaneNetwork(controller: OnboardingWizardControllerLike): boolean {
     return controller.hasServerCapabilitiesSelected()
       && (controller.isCapabilitySelected('browser-access') || controller.isCapabilitySelected('network-access'));
   }
 
-export function requiresAuthBootstrap(controller: OnboardingWizardController): boolean {
+export function requiresAuthBootstrap(controller: OnboardingWizardControllerLike): boolean {
     return controller.hasServerCapabilitiesSelected()
       && (!controller.hasLocalAuthUser() || controller.hasBootstrapCredentialPresent());
   }
 
-export function hasAdminAuthUser(controller: OnboardingWizardController): boolean {
+export function hasAdminAuthUser(controller: OnboardingWizardControllerLike): boolean {
     return (controller.runtimeSnapshot?.auth.snapshot.users ?? [])
       .some((user) => user.roles.includes('admin'));
   }
 
-export function hasLocalAuthUser(controller: OnboardingWizardController): boolean {
+export function hasLocalAuthUser(controller: OnboardingWizardControllerLike): boolean {
     return (controller.runtimeSnapshot?.auth.snapshot.userCount ?? 0) > 0
       || (controller.runtimeSnapshot?.auth.snapshot.users ?? []).length > 0;
   }
 
-export function hasBootstrapCredentialPresent(controller: OnboardingWizardController): boolean {
+export function hasBootstrapCredentialPresent(controller: OnboardingWizardControllerLike): boolean {
     return controller.runtimeSnapshot?.auth.snapshot.bootstrapCredentialPresent === true;
   }
 
-export function getDefaultAdminUsername(controller: OnboardingWizardController): string {
+export function getDefaultAdminUsername(controller: OnboardingWizardControllerLike): string {
     const users = controller.runtimeSnapshot?.auth.snapshot.users ?? [];
     if (controller.hasBootstrapCredentialPresent()) {
       const existingAdmin = users.find((user) => user.roles.includes('admin'));
@@ -225,29 +225,29 @@ export function getDefaultAdminUsername(controller: OnboardingWizardController):
     return candidate ?? `goodvibes-admin-${users.length + 1}`;
   }
 
-export function getBooleanFieldValue(controller: OnboardingWizardController, fieldId: string, fallback: boolean): boolean {
+export function getBooleanFieldValue(controller: OnboardingWizardControllerLike, fieldId: string, fallback: boolean): boolean {
     return controller.toggleState.get(fieldId) ?? fallback;
   }
 
-export function getStringFieldValue(controller: OnboardingWizardController, fieldId: string, fallback: string): string {
+export function getStringFieldValue(controller: OnboardingWizardControllerLike, fieldId: string, fallback: string): string {
     const value = controller.textState.get(fieldId) ?? controller.radioState.get(fieldId);
     return normalizeText(value ?? fallback);
   }
 
-export function parseIntegerFieldValue(controller: OnboardingWizardController, fieldId: string, fallback: number): number | null {
+export function parseIntegerFieldValue(controller: OnboardingWizardControllerLike, fieldId: string, fallback: number): number | null {
     const raw = controller.getStringFieldValue(fieldId, String(fallback));
     if (!/^-?\d+$/.test(raw)) return null;
     const parsed = Number.parseInt(raw, 10);
     return Number.isInteger(parsed) ? parsed : null;
   }
 
-export function getPortFieldValue(controller: OnboardingWizardController, fieldId: string, fallback: number): number {
+export function getPortFieldValue(controller: OnboardingWizardControllerLike, fieldId: string, fallback: number): number {
     const parsed = controller.parseIntegerFieldValue(fieldId, fallback);
     if (parsed === null || parsed < 1 || parsed > 65535) return fallback;
     return parsed;
   }
 
-export function getNumberFieldValue(controller: OnboardingWizardController, fieldId: string, fallback: number, min?: number, max?: number): number {
+export function getNumberFieldValue(controller: OnboardingWizardControllerLike, fieldId: string, fallback: number, min?: number, max?: number): number {
     const parsed = controller.parseIntegerFieldValue(fieldId, fallback);
     if (parsed === null) return fallback;
     if (min !== undefined && parsed < min) return fallback;

package/src/input/onboarding/onboarding-wizard-state.ts

@@ -2,16 +2,16 @@ import type { ModelPickerTarget } from '../model-picker.ts';
 import type { OnboardingStep1CapabilityItem } from '../../runtime/onboarding/index.ts';
 import { DEFAULT_CAPABILITIES, NETWORK_HOST_FIELD_IDS } from './onboarding-wizard-constants.ts';
 import { areSelectionsEqual, clamp, cloneSelection, getExternalSurfaceSetupFieldSpec, isMalformedGoodVibesSecretReferenceValue, isValidHostValue, normalizeText } from './onboarding-wizard-helpers.ts';
-import type { OnboardingWizardController } from './onboarding-wizard.ts';
+import type { OnboardingWizardControllerLike } from './onboarding-wizard-types.ts';
 import type { OnboardingWizardFieldDefinition, OnboardingWizardModelSelection, OnboardingWizardStepDefinition } from './onboarding-wizard-types.ts';
 
-export function getToggleFieldCount(controller: OnboardingWizardController, stepIndex: number): number {
+export function getToggleFieldCount(controller: OnboardingWizardControllerLike, stepIndex: number): number {
     const step = controller.steps[stepIndex];
     if (!step) return 0;
     return step.fields.filter((field) => field.kind === 'checklist' || field.kind === 'acknowledgement').length;
   }
 
-export function getCompletedToggleCount(controller: OnboardingWizardController, stepIndex: number): number {
+export function getCompletedToggleCount(controller: OnboardingWizardControllerLike, stepIndex: number): number {
     const step = controller.steps[stepIndex];
     if (!step) return 0;
 
@@ -21,27 +21,27 @@ export function getCompletedToggleCount(controller: OnboardingWizardController,
     )).length;
   }
 
-export function getStepFieldCount(controller: OnboardingWizardController, stepIndex: number): number {
+export function getStepFieldCount(controller: OnboardingWizardControllerLike, stepIndex: number): number {
     return controller.steps[stepIndex]?.fields.length ?? 0;
   }
 
-export function getCompletedFieldCount(controller: OnboardingWizardController, stepIndex: number): number {
+export function getCompletedFieldCount(controller: OnboardingWizardControllerLike, stepIndex: number): number {
     const step = controller.steps[stepIndex];
     if (!step) return 0;
     return step.fields.filter((field) => controller.isFieldSatisfied(field)).length;
   }
 
-export function isStepDirty(controller: OnboardingWizardController, stepIndex: number): boolean {
+export function isStepDirty(controller: OnboardingWizardControllerLike, stepIndex: number): boolean {
     const stepId = controller.steps[stepIndex]?.id;
     return stepId ? controller.dirtyStepIds.has(stepId) : false;
   }
 
-export function isFieldDirty(controller: OnboardingWizardController, fieldId: string): boolean {
+export function isFieldDirty(controller: OnboardingWizardControllerLike, fieldId: string): boolean {
     const field = controller.getFieldById(fieldId);
     return field ? controller.isFieldDirtyByDefinition(field) : false;
   }
 
-export function getBlockingFieldLabels(controller: OnboardingWizardController): readonly string[] {
+export function getBlockingFieldLabels(controller: OnboardingWizardControllerLike): readonly string[] {
     const labels: string[] = [];
     if (controller.hydrationPending) {
       labels.push('Loading: Current runtime settings are still being collected.');
@@ -65,7 +65,7 @@ export function getBlockingFieldLabels(controller: OnboardingWizardController):
   }
 
 export function getFieldValidationError(
-  controller: OnboardingWizardController,
+  controller: OnboardingWizardControllerLike,
     step: OnboardingWizardStepDefinition,
     field: OnboardingWizardFieldDefinition,
   ): string | null {
@@ -127,7 +127,7 @@ export function getFieldValidationError(
     return null;
   }
 
-export function getFieldById(controller: OnboardingWizardController, fieldId: string): OnboardingWizardFieldDefinition | null {
+export function getFieldById(controller: OnboardingWizardControllerLike, fieldId: string): OnboardingWizardFieldDefinition | null {
     for (const step of controller.steps) {
       const field = step.fields.find((entry) => entry.id === fieldId);
       if (field) return field;
@@ -135,7 +135,7 @@ export function getFieldById(controller: OnboardingWizardController, fieldId: st
     return null;
   }
 
-export function ensureSelectionVisible(controller: OnboardingWizardController, visibleFields: number): void {
+export function ensureSelectionVisible(controller: OnboardingWizardControllerLike, visibleFields: number): void {
     const total = controller.currentStep.fields.length;
     if (total === 0) {
       controller.scrollOffsets[controller.stepIndex] = 0;
@@ -154,7 +154,7 @@ export function ensureSelectionVisible(controller: OnboardingWizardController, v
     controller.scrollOffsets[controller.stepIndex] = clamp(nextOffset, 0, maxStart);
   }
 
-export function reconcileStepCursor(controller: OnboardingWizardController, stepIndex: number): void {
+export function reconcileStepCursor(controller: OnboardingWizardControllerLike, stepIndex: number): void {
     const total = controller.steps[stepIndex]?.fields.length ?? 0;
     if (total === 0) {
       controller.scrollOffsets[stepIndex] = 0;
@@ -166,7 +166,7 @@ export function reconcileStepCursor(controller: OnboardingWizardController, step
     controller.scrollOffsets[stepIndex] = clamp(controller.scrollOffsets[stepIndex] ?? 0, 0, total - 1);
   }
 
-export function resetValuesFromCurrentDefinitions(controller: OnboardingWizardController): void {
+export function resetValuesFromCurrentDefinitions(controller: OnboardingWizardControllerLike): void {
     controller.toggleState.clear();
     controller.baselineToggleState.clear();
     controller.radioState.clear();
@@ -213,7 +213,7 @@ export function resetValuesFromCurrentDefinitions(controller: OnboardingWizardCo
     }
   }
 
-export function reconcileStateWithCurrentDefinitions(controller: OnboardingWizardController): void {
+export function reconcileStateWithCurrentDefinitions(controller: OnboardingWizardControllerLike): void {
     const nextToggleKeys = new Set<string>();
     const nextRadioKeys = new Set<string>();
     const nextTextKeys = new Set<string>();
@@ -282,7 +282,7 @@ export function reconcileStateWithCurrentDefinitions(controller: OnboardingWizar
     }
   }
 
-export function recalculateDirtyState(controller: OnboardingWizardController): void {
+export function recalculateDirtyState(controller: OnboardingWizardControllerLike): void {
     controller.reconcileStateWithCurrentDefinitions();
     controller.dirtyStepIds.clear();
 
@@ -293,7 +293,7 @@ export function recalculateDirtyState(controller: OnboardingWizardController): v
     }
   }
 
-export function isFieldDirtyByDefinition(controller: OnboardingWizardController, field: OnboardingWizardFieldDefinition): boolean {
+export function isFieldDirtyByDefinition(controller: OnboardingWizardControllerLike, field: OnboardingWizardFieldDefinition): boolean {
     if (field.kind === 'checklist' || field.kind === 'acknowledgement') {
       return (controller.toggleState.get(field.id) ?? field.defaultValue)
         !== (controller.baselineToggleState.get(field.id) ?? field.defaultValue);
@@ -317,7 +317,7 @@ export function isFieldDirtyByDefinition(controller: OnboardingWizardController,
     );
   }
 
-export function isFieldSatisfied(controller: OnboardingWizardController, field: OnboardingWizardFieldDefinition): boolean {
+export function isFieldSatisfied(controller: OnboardingWizardControllerLike, field: OnboardingWizardFieldDefinition): boolean {
     if (field.kind === 'checklist') {
       return true;
     }
@@ -341,20 +341,20 @@ export function isFieldSatisfied(controller: OnboardingWizardController, field:
     return selection.providerId.length > 0 || selection.modelId.length > 0;
   }
 
-export function getCurrentCapabilities(controller: OnboardingWizardController): readonly OnboardingStep1CapabilityItem[] {
+export function getCurrentCapabilities(controller: OnboardingWizardControllerLike): readonly OnboardingStep1CapabilityItem[] {
     return controller.runtimeDerived.step1Capabilities.length > 0
       ? controller.runtimeDerived.step1Capabilities
       : DEFAULT_CAPABILITIES;
   }
 
-export function getCapabilitySelectionState(controller: OnboardingWizardController): readonly OnboardingStep1CapabilityItem[] {
+export function getCapabilitySelectionState(controller: OnboardingWizardControllerLike): readonly OnboardingStep1CapabilityItem[] {
     return controller.getCurrentCapabilities().map((capability) => ({
       ...capability,
       selected: controller.toggleState.get(`capabilities.${capability.id}`) ?? capability.selected,
     }));
   }
 
-export function hasExistingAccessState(controller: OnboardingWizardController): boolean {
+export function hasExistingAccessState(controller: OnboardingWizardControllerLike): boolean {
     const auth = controller.runtimeSnapshot?.auth.snapshot;
     return controller.mode !== 'new'
       || (controller.runtimeSnapshot?.subscriptions.active.length ?? 0) > 0