@aifabrix/builder 2.7.0 → 2.9.0

package/lib/utils/external-system-validators.js

@@ -0,0 +1,245 @@
+/**
+ * External System Validation Helpers
+ *
+ * Provides validation functions for external system field mappings and schemas.
+ *
+ * @fileoverview Validation helpers for external system testing
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const Ajv = require('ajv');
+
+/**
+ * Validates field mapping expression syntax (pipe-based DSL)
+ * @param {string} expression - Field mapping expression
+ * @returns {Object} Validation result with isValid and error message
+ */
+function validateFieldMappingExpression(expression) {
+  if (!expression || typeof expression !== 'string') {
+    return { isValid: false, error: 'Expression must be a non-empty string' };
+  }
+
+  // Pattern: {{path.to.field}} | transformation1 | transformation2
+  const expressionPattern = /^\s*\{\{[^}]+\}\}(\s*\|\s*[a-zA-Z0-9_]+(\s*\([^)]*\))?)*\s*$/;
+
+  if (!expressionPattern.test(expression)) {
+    return {
+      isValid: false,
+      error: 'Invalid expression format. Expected: {{path.to.field}} | toUpper | trim'
+    };
+  }
+
+  // Extract path and transformations
+  const pathMatch = expression.match(/\{\{([^}]+)\}\}/);
+  if (!pathMatch) {
+    return { isValid: false, error: 'Path must be wrapped in {{}}' };
+  }
+
+  // Validate transformations (optional)
+  const transformations = expression.split('|').slice(1).map(t => t.trim());
+  const validTransformations = ['toUpper', 'toLower', 'trim', 'default', 'toNumber', 'toString'];
+  for (const trans of transformations) {
+    const transName = trans.split('(')[0].trim();
+    if (!validTransformations.includes(transName)) {
+      return {
+        isValid: false,
+        error: `Unknown transformation: ${transName}. Valid: ${validTransformations.join(', ')}`
+      };
+    }
+  }
+
+  return { isValid: true, error: null };
+}
+
+/**
+ * Validates field mappings against test payload
+ * @param {Object} datasource - Datasource configuration
+ * @param {Object} testPayload - Test payload object
+ * @returns {Object} Validation results
+ */
+function validateFieldMappings(datasource, testPayload) {
+  const results = {
+    valid: true,
+    errors: [],
+    warnings: [],
+    mappedFields: {}
+  };
+
+  if (!datasource.fieldMappings || !datasource.fieldMappings.fields) {
+    results.warnings.push('No field mappings defined');
+    return results;
+  }
+
+  const fields = datasource.fieldMappings.fields;
+  const payloadTemplate = testPayload.payloadTemplate || testPayload;
+
+  // Validate each field mapping expression
+  for (const [fieldName, fieldConfig] of Object.entries(fields)) {
+    if (!fieldConfig.expression) {
+      results.errors.push(`Field '${fieldName}' missing expression`);
+      results.valid = false;
+      continue;
+    }
+
+    // Validate expression syntax
+    const exprValidation = validateFieldMappingExpression(fieldConfig.expression);
+    if (!exprValidation.isValid) {
+      results.errors.push(`Field '${fieldName}': ${exprValidation.error}`);
+      results.valid = false;
+      continue;
+    }
+
+    // Try to extract path from expression
+    const pathMatch = fieldConfig.expression.match(/\{\{([^}]+)\}\}/);
+    if (pathMatch) {
+      const fieldPath = pathMatch[1].trim();
+      // Check if path exists in payload (simple check)
+      const pathParts = fieldPath.split('.');
+      let current = payloadTemplate;
+      let pathExists = true;
+
+      for (const part of pathParts) {
+        if (current && typeof current === 'object' && part in current) {
+          current = current[part];
+        } else {
+          pathExists = false;
+          break;
+        }
+      }
+
+      if (!pathExists) {
+        results.warnings.push(`Field '${fieldName}': Path '${fieldPath}' may not exist in payload`);
+      } else {
+        results.mappedFields[fieldName] = fieldConfig.expression;
+      }
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Validates metadata schema against test payload
+ * @param {Object} datasource - Datasource configuration
+ * @param {Object} testPayload - Test payload object
+ * @returns {Object} Validation results
+ */
+function validateMetadataSchema(datasource, testPayload) {
+  const results = {
+    valid: true,
+    errors: [],
+    warnings: []
+  };
+
+  if (!datasource.metadataSchema) {
+    results.warnings.push('No metadata schema defined');
+    return results;
+  }
+
+  const payloadTemplate = testPayload.payloadTemplate || testPayload;
+
+  try {
+    const ajv = new Ajv({ allErrors: true, strict: false });
+    const validate = ajv.compile(datasource.metadataSchema);
+    const valid = validate(payloadTemplate);
+
+    if (!valid) {
+      results.valid = false;
+      results.errors = validate.errors.map(err => {
+        const path = err.instancePath || err.schemaPath;
+        return `${path} ${err.message}`;
+      });
+    }
+  } catch (error) {
+    results.valid = false;
+    results.errors.push(`Schema validation error: ${error.message}`);
+  }
+
+  return results;
+}
+
+/**
+ * Normalizes schema to handle nullable without type
+ * @param {Object} schema - Schema to normalize
+ * @returns {Object} Normalized schema
+ */
+function normalizeSchema(schema) {
+  if (typeof schema !== 'object' || schema === null) {
+    return schema;
+  }
+
+  const normalized = Array.isArray(schema) ? [...schema] : { ...schema };
+
+  if (normalized.nullable === true && !normalized.type) {
+    normalized.type = ['null', 'string', 'number', 'boolean', 'object', 'array'];
+  }
+
+  for (const key in normalized) {
+    if (typeof normalized[key] === 'object' && normalized[key] !== null) {
+      normalized[key] = normalizeSchema(normalized[key]);
+    }
+  }
+
+  return normalized;
+}
+
+/**
+ * Validates JSON against schema
+ * @param {Object} data - Data to validate
+ * @param {Object} schema - JSON schema
+ * @returns {Object} Validation results
+ */
+function validateAgainstSchema(data, schema) {
+  const ajv = new Ajv({
+    allErrors: true,
+    strict: false,
+    allowUnionTypes: true,
+    validateSchema: false
+  });
+  // Remove $schema for draft-2020-12 to avoid AJV issues
+  const schemaCopy = { ...schema };
+  if (schemaCopy.$schema && schemaCopy.$schema.includes('2020-12')) {
+    delete schemaCopy.$schema;
+  }
+  // Normalize schema to handle nullable without type
+  const normalizedSchema = normalizeSchema(schemaCopy);
+  const validate = ajv.compile(normalizedSchema);
+  const valid = validate(data);
+
+  if (!valid) {
+    // Filter out additionalProperties errors for required properties that aren't defined in schema
+    // This handles schema inconsistencies where authentication is required but not defined in properties
+    const filteredErrors = validate.errors.filter(err => {
+      if (err.keyword === 'additionalProperties' && err.params?.additionalProperty === 'authentication') {
+        // Check if authentication is in required array
+        const required = normalizedSchema.required || [];
+        if (required.includes('authentication')) {
+          return false; // Ignore this error since authentication is required but not defined
+        }
+      }
+      return true;
+    });
+
+    return {
+      valid: filteredErrors.length === 0,
+      errors: filteredErrors.map(err => {
+        const path = err.instancePath || err.schemaPath;
+        return `${path} ${err.message}`;
+      })
+    };
+  }
+
+  return {
+    valid: true,
+    errors: []
+  };
+}
+
+module.exports = {
+  validateFieldMappingExpression,
+  validateFieldMappings,
+  validateMetadataSchema,
+  validateAgainstSchema
+};
+

package/lib/utils/paths.js

@@ -91,9 +91,159 @@ function getDevDirectory(appName, developerId) {
   return baseDir;
 }
 
+/**
+ * Gets the application path (builder or integration folder)
+ * @param {string} appName - Application name
+ * @param {string} [appType] - Application type ('external' or other)
+ * @returns {string} Absolute path to application directory
+ */
+function getAppPath(appName, appType) {
+  if (!appName || typeof appName !== 'string') {
+    throw new Error('App name is required and must be a string');
+  }
+
+  const baseDir = appType === 'external' ? 'integration' : 'builder';
+  return path.join(process.cwd(), baseDir, appName);
+}
+
+/**
+ * Gets the integration folder path for external systems
+ * @param {string} appName - Application name
+ * @returns {string} Absolute path to integration directory
+ */
+function getIntegrationPath(appName) {
+  if (!appName || typeof appName !== 'string') {
+    throw new Error('App name is required and must be a string');
+  }
+  return path.join(process.cwd(), 'integration', appName);
+}
+
+/**
+ * Gets the builder folder path for regular applications
+ * @param {string} appName - Application name
+ * @returns {string} Absolute path to builder directory
+ */
+function getBuilderPath(appName) {
+  if (!appName || typeof appName !== 'string') {
+    throw new Error('App name is required and must be a string');
+  }
+  return path.join(process.cwd(), 'builder', appName);
+}
+
+/**
+ * Resolves the deployment JSON file path for an application
+ * Uses consistent naming: <app-name>-deploy.json
+ * Supports backward compatibility with aifabrix-deploy.json
+ *
+ * @param {string} appName - Application name
+ * @param {string} [appType] - Application type ('external' or other)
+ * @param {boolean} [preferNew] - If true, only return new naming (no backward compat)
+ * @returns {string} Absolute path to deployment JSON file
+ */
+function getDeployJsonPath(appName, appType, preferNew = false) {
+  if (!appName || typeof appName !== 'string') {
+    throw new Error('App name is required and must be a string');
+  }
+
+  const appPath = getAppPath(appName, appType);
+  const newPath = path.join(appPath, `${appName}-deploy.json`);
+
+  // If preferNew is true, always return new naming
+  if (preferNew) {
+    return newPath;
+  }
+
+  // Check if new naming exists, otherwise fall back to old naming for backward compatibility
+  const oldPath = path.join(appPath, 'aifabrix-deploy.json');
+  if (fs.existsSync(newPath)) {
+    return newPath;
+  }
+
+  // Fall back to old naming for backward compatibility
+  if (fs.existsSync(oldPath)) {
+    return oldPath;
+  }
+
+  // If neither exists, return new naming (for generation)
+  return newPath;
+}
+
+/**
+ * Detects if an app is external type by checking variables.yaml
+ * Checks both integration/ and builder/ folders for backward compatibility
+ *
+ * @param {string} appName - Application name
+ * @returns {Promise<{isExternal: boolean, appPath: string, appType: string}>}
+ */
+async function detectAppType(appName) {
+  if (!appName || typeof appName !== 'string') {
+    throw new Error('App name is required and must be a string');
+  }
+
+  // Check integration folder first (new structure)
+  const integrationPath = getIntegrationPath(appName);
+  const integrationVariablesPath = path.join(integrationPath, 'variables.yaml');
+
+  if (fs.existsSync(integrationVariablesPath)) {
+    try {
+      const content = fs.readFileSync(integrationVariablesPath, 'utf8');
+      const variables = yaml.load(content);
+      if (variables.app && variables.app.type === 'external') {
+        return {
+          isExternal: true,
+          appPath: integrationPath,
+          appType: 'external',
+          baseDir: 'integration'
+        };
+      }
+    } catch {
+      // Ignore errors, continue to check builder folder
+    }
+  }
+
+  // Check builder folder (backward compatibility)
+  const builderPath = getBuilderPath(appName);
+  const builderVariablesPath = path.join(builderPath, 'variables.yaml');
+
+  if (fs.existsSync(builderVariablesPath)) {
+    try {
+      const content = fs.readFileSync(builderVariablesPath, 'utf8');
+      const variables = yaml.load(content);
+      const isExternal = variables.app && variables.app.type === 'external';
+      return {
+        isExternal,
+        appPath: builderPath,
+        appType: isExternal ? 'external' : 'regular',
+        baseDir: 'builder'
+      };
+    } catch {
+      // If we can't read it, assume regular app in builder folder
+      return {
+        isExternal: false,
+        appPath: builderPath,
+        appType: 'regular',
+        baseDir: 'builder'
+      };
+    }
+  }
+
+  // Default to builder folder if neither exists
+  return {
+    isExternal: false,
+    appPath: builderPath,
+    appType: 'regular',
+    baseDir: 'builder'
+  };
+}
+
 module.exports = {
   getAifabrixHome,
   getApplicationsBaseDir,
-  getDevDirectory
+  getDevDirectory,
+  getAppPath,
+  getIntegrationPath,
+  getBuilderPath,
+  getDeployJsonPath,
+  detectAppType
 };
 

package/lib/utils/schema-resolver.js

@@ -12,6 +12,7 @@
 const fs = require('fs');
 const path = require('path');
 const yaml = require('js-yaml');
+const { detectAppType } = require('./paths');
 
 /**
  * Resolves schemaBasePath from application variables.yaml
@@ -32,7 +33,9 @@ async function resolveSchemaBasePath(appName) {
     throw new Error('App name is required and must be a string');
   }
 
-  const variablesPath = path.join(process.cwd(), 'builder', appName, 'variables.yaml');
+  // Detect app type and get correct path (integration or builder)
+  const { appPath } = await detectAppType(appName);
+  const variablesPath = path.join(appPath, 'variables.yaml');
 
   if (!fs.existsSync(variablesPath)) {
     throw new Error(`variables.yaml not found: ${variablesPath}`);
@@ -104,7 +107,9 @@ async function resolveExternalFiles(appName) {
     throw new Error('App name is required and must be a string');
   }
 
-  const variablesPath = path.join(process.cwd(), 'builder', appName, 'variables.yaml');
+  // Detect app type and get correct path (integration or builder)
+  const { appPath } = await detectAppType(appName);
+  const variablesPath = path.join(appPath, 'variables.yaml');
 
   if (!fs.existsSync(variablesPath)) {
     throw new Error(`variables.yaml not found: ${variablesPath}`);

package/lib/utils/token-encryption.js

@@ -0,0 +1,68 @@
+/**
+ * AI Fabrix Builder Token Encryption Utilities
+ *
+ * This module provides encryption and decryption functions for authentication tokens
+ * using AES-256-GCM algorithm for ISO 27001 compliance.
+ * Reuses the same encryption infrastructure as secrets encryption.
+ *
+ * @fileoverview Token encryption utilities for AI Fabrix Builder
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const { encryptSecret, decryptSecret, isEncrypted } = require('./secrets-encryption');
+
+/**
+ * Encrypts a token value using AES-256-GCM
+ * Returns encrypted value in format: secure://<iv>:<ciphertext>:<authTag>
+ * All components are base64 encoded
+ *
+ * @function encryptToken
+ * @param {string} value - Plaintext token value to encrypt
+ * @param {string} key - Encryption key (hex or base64, 32 bytes)
+ * @returns {string} Encrypted value with secure:// prefix
+ * @throws {Error} If encryption fails or key is invalid
+ *
+ * @example
+ * const encrypted = encryptToken('my-token', 'a1b2c3...');
+ * // Returns: 'secure://<iv>:<ciphertext>:<authTag>'
+ */
+function encryptToken(value, key) {
+  return encryptSecret(value, key);
+}
+
+/**
+ * Decrypts an encrypted token value
+ * Handles secure:// prefixed values and extracts IV, ciphertext, and auth tag
+ *
+ * @function decryptToken
+ * @param {string} encryptedValue - Encrypted value with secure:// prefix
+ * @param {string} key - Encryption key (hex or base64, 32 bytes)
+ * @returns {string} Decrypted plaintext value
+ * @throws {Error} If decryption fails, key is invalid, or format is incorrect
+ *
+ * @example
+ * const decrypted = decryptToken('secure://<iv>:<ciphertext>:<authTag>', 'a1b2c3...');
+ * // Returns: 'my-token'
+ */
+function decryptToken(encryptedValue, key) {
+  return decryptSecret(encryptedValue, key);
+}
+
+/**
+ * Checks if a token value is encrypted (starts with secure://)
+ *
+ * @function isTokenEncrypted
+ * @param {string} value - Value to check
+ * @returns {boolean} True if value is encrypted
+ */
+function isTokenEncrypted(value) {
+  return isEncrypted(value);
+}
+
+module.exports = {
+  encryptToken,
+  decryptToken,
+  isTokenEncrypted
+};
+

package/lib/validator.js

@@ -14,9 +14,12 @@ const path = require('path');
 const yaml = require('js-yaml');
 const Ajv = require('ajv');
 const applicationSchema = require('./schema/application-schema.json');
+const externalSystemSchema = require('./schema/external-system.schema.json');
+const externalDataSourceSchema = require('./schema/external-datasource.schema.json');
 const { transformVariablesForValidation } = require('./utils/variable-transformer');
 const { checkEnvironment } = require('./utils/environment-checker');
 const { formatValidationErrors } = require('./utils/error-formatter');
+const { detectAppType } = require('./utils/paths');
 
 /**
  * Validates variables.yaml file against application schema
@@ -37,7 +40,9 @@ async function validateVariables(appName) {
     throw new Error('App name is required and must be a string');
   }
 
-  const variablesPath = path.join(process.cwd(), 'builder', appName, 'variables.yaml');
+  // Detect app type and get correct path (integration or builder)
+  const { appPath } = await detectAppType(appName);
+  const variablesPath = path.join(appPath, 'variables.yaml');
 
   if (!fs.existsSync(variablesPath)) {
     throw new Error(`variables.yaml not found: ${variablesPath}`);
@@ -56,13 +61,45 @@ async function validateVariables(appName) {
   const transformed = transformVariablesForValidation(variables, appName);
 
   const ajv = new Ajv({ allErrors: true, strict: false });
+  // Register external schemas with their $id (GitHub raw URLs)
+  // Create copies to avoid modifying the original schemas
+  const externalSystemSchemaCopy = { ...externalSystemSchema };
+  const externalDataSourceSchemaCopy = { ...externalDataSourceSchema };
+  // Remove $schema for draft-2020-12 to avoid AJV issues
+  if (externalDataSourceSchemaCopy.$schema && externalDataSourceSchemaCopy.$schema.includes('2020-12')) {
+    delete externalDataSourceSchemaCopy.$schema;
+  }
+  ajv.addSchema(externalSystemSchemaCopy, externalSystemSchema.$id);
+  ajv.addSchema(externalDataSourceSchemaCopy, externalDataSourceSchema.$id);
   const validate = ajv.compile(applicationSchema);
   const valid = validate(transformed);
 
+  // Additional explicit validation for external type
+  const errors = valid ? [] : formatValidationErrors(validate.errors);
+  const warnings = [];
+
+  // If type is external, perform additional checks
+  if (variables.app && variables.app.type === 'external') {
+    // Check for externalIntegration block
+    if (!variables.externalIntegration) {
+      errors.push('externalIntegration block is required when app.type is "external"');
+    } else {
+      // Validate externalIntegration structure
+      if (!variables.externalIntegration.schemaBasePath) {
+        errors.push('externalIntegration.schemaBasePath is required');
+      }
+      if (!variables.externalIntegration.systems || !Array.isArray(variables.externalIntegration.systems) || variables.externalIntegration.systems.length === 0) {
+        errors.push('externalIntegration.systems must be a non-empty array');
+      }
+      // Note: dataSources can be empty, so we don't validate that here
+      // File existence is validated during build/deploy, not during schema validation
+    }
+  }
+
   return {
-    valid,
-    errors: valid ? [] : formatValidationErrors(validate.errors),
-    warnings: []
+    valid: valid && errors.length === 0,
+    errors,
+    warnings
   };
 }
 
@@ -220,7 +257,7 @@ async function validateEnvTemplate(appName) {
 
 /**
  * Validates deployment JSON against application schema
- * Ensures generated aifabrix-deploy.json matches the schema structure
+ * Ensures generated <app-name>-deploy.json matches the schema structure
  *
  * @function validateDeploymentJson
  * @param {Object} deployment - Deployment JSON object to validate
@@ -239,6 +276,16 @@ function validateDeploymentJson(deployment) {
   }
 
   const ajv = new Ajv({ allErrors: true, strict: false });
+  // Register external schemas with their $id (GitHub raw URLs)
+  // Create copies to avoid modifying the original schemas
+  const externalSystemSchemaCopy = { ...externalSystemSchema };
+  const externalDataSourceSchemaCopy = { ...externalDataSourceSchema };
+  // Remove $schema for draft-2020-12 to avoid AJV issues
+  if (externalDataSourceSchemaCopy.$schema && externalDataSourceSchemaCopy.$schema.includes('2020-12')) {
+    delete externalDataSourceSchemaCopy.$schema;
+  }
+  ajv.addSchema(externalSystemSchemaCopy, externalSystemSchema.$id);
+  ajv.addSchema(externalDataSourceSchemaCopy, externalDataSourceSchema.$id);
   const validate = ajv.compile(applicationSchema);
   const valid = validate(deployment);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aifabrix/builder",
-  "version": "2.7.0",
+  "version": "2.9.0",
   "description": "AI Fabrix Local Fabric & Deployment SDK",
   "main": "lib/index.js",
   "bin": {