feat(#3299): runtime configuration engine with Zod validation

workspaces/boost/plugins/boost-backend/config.d.ts

@@ -0,0 +1,146 @@
+/*
+ * Copyright Red Hat, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Configuration schema for the boost backend plugin.
+ *
+ * Mirrors the field definitions in `src/config/schemas.ts`.
+ * Keep both in sync when adding or changing config fields.
+ */
+export interface Config {
+  boost?: {
+    /** Model connection configuration. */
+    model?: {
+      /**
+       * Base URL for the AI model endpoint.
+       * @visibility frontend
+       * @configScope db-overridable
+       */
+      baseUrl?: string;
+      /**
+       * Name of the AI model to use.
+       * @visibility frontend
+       * @configScope db-overridable
+       */
+      name?: string;
+    };
+
+    /**
+     * System prompt for AI conversations.
+     * @configScope db-overridable
+     */
+    systemPrompt?: string;
+
+    /** Security configuration. */
+    security?: {
+      /**
+       * Security mode for the boost plugin.
+       * @configScope yaml-only
+       */
+      mode?: 'development-only-no-auth' | 'plugin-only' | 'full';
+    };
+
+    /** Feature flags. */
+    features?: {
+      /**
+       * Enable agent creation feature.
+       * @visibility frontend
+       * @configScope db-overridable
+       */
+      agentCreation?: boolean;
+      /**
+       * Enable skills marketplace feature.
+       * @visibility frontend
+       * @configScope db-overridable
+       */
+      skillsMarketplace?: boolean;
+    };
+
+    /** Agent approval configuration. */
+    agentApproval?: {
+      /**
+       * Agent approval mode: built-in or SonataFlow-managed.
+       * @configScope db-overridable
+       */
+      mode?: 'built-in' | 'sonataflow';
+      /** SonataFlow integration. */
+      sonataflow?: {
+        /**
+         * SonataFlow workflow endpoint for agent approval.
+         * @configScope yaml-only
+         */
+        endpoint?: string;
+      };
+    };
+
+    /** Skills marketplace configuration. */
+    skillsMarketplace?: {
+      /**
+       * Skills catalog backend URL.
+       * @configScope yaml-only
+       */
+      endpoint?: string;
+      /**
+       * Enable or disable skills marketplace.
+       * @visibility frontend
+       * @configScope db-overridable
+       */
+      enabled?: boolean;
+    };
+
+    /** Kagenti provider configuration. */
+    kagenti?: {
+      /** Authentication configuration. */
+      auth?: {
+        /** RFC 8693 token exchange. */
+        tokenExchange?: {
+          /**
+           * Enable RFC 8693 token exchange for Kagenti.
+           * @configScope yaml-only
+           */
+          enabled?: boolean;
+          /**
+           * Target audience for exchanged token.
+           * @configScope yaml-only
+           */
+          audience?: string;
+          /**
+           * Header containing user OIDC token.
+           * @configScope yaml-only
+           */
+          userTokenHeader?: string;
+        };
+      };
+    };
+
+    /** DevSpaces integration. */
+    devSpaces?: {
+      /**
+       * DevSpaces integration credentials.
+       * @visibility secret
+       * @configScope db-overridable
+       */
+      credentials?: string;
+    };
+
+    /**
+     * Secret used for encrypting sensitive config values stored in the database.
+     * Must be a high-entropy string (e.g., 32+ random characters).
+     * @visibility secret
+     */
+    encryptionSecret?: string;
+  };
+}

workspaces/boost/plugins/boost-backend/package.json

@@ -36,7 +36,9 @@
     "@backstage/plugin-permission-node": "^0.10.11",
     "@red-hat-developer-hub/backstage-plugin-boost-common": "workspace:^",
     "@red-hat-developer-hub/backstage-plugin-boost-node": "workspace:^",
-    "express": "^4.21.1"
+    "express": "^4.21.1",
+    "knex": "^3.1.0",
+    "zod": "^3.23.8"
   },
   "devDependencies": {
     "@backstage/cli": "^0.34.5",

workspaces/boost/plugins/boost-backend/report.api.md

@@ -6,13 +6,35 @@
 import type { AgenticProvider } from '@red-hat-developer-hub/backstage-plugin-boost-common';
 import { BackendFeature } from '@backstage/backend-plugin-api';
 import { BasicPermission } from '@backstage/plugin-permission-common';
+import type { CacheService } from '@backstage/backend-plugin-api';
+import type { DatabaseService } from '@backstage/backend-plugin-api';
 import type { HttpAuthService } from '@backstage/backend-plugin-api';
 import type { LoggerService } from '@backstage/backend-plugin-api';
 import type { PermissionsService } from '@backstage/backend-plugin-api';
 import type { ProviderDescriptor } from '@red-hat-developer-hub/backstage-plugin-boost-common';
 import type { Request as Request_2 } from 'express';
 import type { RequestHandler } from 'express';
+import type { RootConfigService } from '@backstage/backend-plugin-api';
 import { ServiceFactory } from '@backstage/backend-plugin-api';
+import { z } from 'zod';
+
+// @public
+export class AdminConfigService {
+  constructor(options: AdminConfigServiceOptions);
+  getAllOverrides(): Promise<Map<string, unknown>>;
+  getOverride(key: BoostConfigKey): Promise<unknown | undefined>;
+  removeOverride(key: BoostConfigKey): Promise<void>;
+  setOverride(key: BoostConfigKey, value: unknown): Promise<void>;
+  validateStoredValues(): Promise<string[]>;
+}
+
+// @public
+export interface AdminConfigServiceOptions {
+  // (undocumented)
+  database: DatabaseService;
+  // (undocumented)
+  logger: LoggerService;
+}
 
 // @public
 export function authorizeLifecycleAction(
@@ -27,23 +49,123 @@ export interface AuthorizeLifecycleActionOptions {
   permissions: PermissionsService;
 }
 
+// @public
+export const BOOST_CONFIG_SCHEMA_VERSION = 1;
+
 // @public
 export const boostAiProviderServiceFactory: ServiceFactory<
   AgenticProvider,
   'plugin',
   'singleton'
 >;
 
+// @public
+export const boostConfigFields: {
+  readonly 'boost.model.baseUrl': {
+    readonly schema: z.ZodString;
+    readonly configScope: ConfigScope;
+    readonly description: 'Base URL for the AI model endpoint';
+  };
+  readonly 'boost.model.name': {
+    readonly schema: z.ZodString;
+    readonly configScope: ConfigScope;
+    readonly description: 'Name of the AI model to use';
+  };
+  readonly 'boost.systemPrompt': {
+    readonly schema: z.ZodOptional<z.ZodString>;
+    readonly configScope: ConfigScope;
+    readonly description: 'System prompt for AI conversations';
+  };
+  readonly 'boost.security.mode': {
+    readonly schema: z.ZodEnum<
+      ['development-only-no-auth', 'plugin-only', 'full']
+    >;
+    readonly configScope: ConfigScope;
+    readonly description: 'Security mode for the boost plugin';
+  };
+  readonly 'boost.features.agentCreation': {
+    readonly schema: z.ZodOptional<z.ZodBoolean>;
+    readonly configScope: ConfigScope;
+    readonly description: 'Enable agent creation feature';
+  };
+  readonly 'boost.features.skillsMarketplace': {
+    readonly schema: z.ZodOptional<z.ZodBoolean>;
+    readonly configScope: ConfigScope;
+    readonly description: 'Enable skills marketplace feature';
+  };
+  readonly 'boost.agentApproval.mode': {
+    readonly schema: z.ZodOptional<z.ZodEnum<['built-in', 'sonataflow']>>;
+    readonly configScope: ConfigScope;
+    readonly description: 'Agent approval mode: built-in or SonataFlow-managed';
+  };
+  readonly 'boost.agentApproval.sonataflow.endpoint': {
+    readonly schema: z.ZodOptional<z.ZodString>;
+    readonly configScope: ConfigScope;
+    readonly description: 'SonataFlow workflow endpoint for agent approval';
+  };
+  readonly 'boost.skillsMarketplace.endpoint': {
+    readonly schema: z.ZodOptional<z.ZodString>;
+    readonly configScope: ConfigScope;
+    readonly description: 'Skills catalog backend URL';
+  };
+  readonly 'boost.skillsMarketplace.enabled': {
+    readonly schema: z.ZodOptional<z.ZodBoolean>;
+    readonly configScope: ConfigScope;
+    readonly description: 'Enable or disable skills marketplace';
+  };
+  readonly 'boost.kagenti.auth.tokenExchange.enabled': {
+    readonly schema: z.ZodOptional<z.ZodBoolean>;
+    readonly configScope: ConfigScope;
+    readonly description: 'Enable RFC 8693 token exchange for Kagenti';
+  };
+  readonly 'boost.kagenti.auth.tokenExchange.audience': {
+    readonly schema: z.ZodOptional<z.ZodString>;
+    readonly configScope: ConfigScope;
+    readonly description: 'Target audience for exchanged token';
+  };
+  readonly 'boost.kagenti.auth.tokenExchange.userTokenHeader': {
+    readonly schema: z.ZodOptional<z.ZodString>;
+    readonly configScope: ConfigScope;
+    readonly description: 'Header containing user OIDC token';
+  };
+  readonly 'boost.devSpaces.credentials': {
+    readonly schema: z.ZodOptional<z.ZodString>;
+    readonly configScope: ConfigScope;
+    readonly description: 'DevSpaces integration credentials';
+    readonly sensitive: true;
+  };
+};
+
+// @public
+export type BoostConfigKey = keyof typeof boostConfigFields;
+
 // @public
 const boostPlugin: BackendFeature;
 export default boostPlugin;
 
+// @public
+export interface ConfigFieldMeta<T extends z.ZodTypeAny = z.ZodTypeAny> {
+  configScope: ConfigScope;
+  description: string;
+  schema: T;
+  sensitive?: boolean;
+}
+
+// @public
+export type ConfigScope = 'yaml-only' | 'db-overridable' | 'db-only';
+
 // @public
 export function createAgentResourceLoader(): ResourceLoader;
 
 // @public
 export function createToolResourceLoader(): ResourceLoader;
 
+// @public
+export function isDbWritable(key: BoostConfigKey): boolean;
+
+// @public
+export function isSensitiveField(key: BoostConfigKey): boolean;
+
 // @public
 export class ProviderManager {
   getActiveProvider(): AgenticProvider;
@@ -62,9 +184,35 @@ export type ResourceLoader = (req: Request_2) => Promise<
   | undefined
 >;
 
+// @public
+export class RuntimeConfigResolver {
+  constructor(options: RuntimeConfigResolverOptions);
+  invalidate(): Promise<void>;
+  resolve(key: BoostConfigKey): Promise<unknown | undefined>;
+  resolveAll(): Promise<Map<string, unknown>>;
+}
+
+// @public
+export interface RuntimeConfigResolverOptions {
+  // (undocumented)
+  adminConfigService: AdminConfigService;
+  // (undocumented)
+  cache: CacheService;
+  // (undocumented)
+  config: RootConfigService;
+  // (undocumented)
+  logger: LoggerService;
+}
+
 // @public
 export type SecurityMode = 'development-only-no-auth' | 'plugin-only' | 'full';
 
+// @public
+export function validateConfigValue(
+  key: BoostConfigKey,
+  value: unknown,
+): unknown;
+
 // @public
 export function validateSecurityMode(
   mode: string | undefined,