@aifabrix/builder 2.2.0 → 2.3.2

package/lib/secrets.js

@@ -32,6 +32,7 @@ const {
   buildHostnameToServiceMap,
   resolveUrlPort
 } = require('./utils/secrets-utils');
+const { decryptSecret, isEncrypted } = require('./utils/secrets-encryption');
 
 /**
  * Loads environment configuration for docker/local context
@@ -43,16 +44,59 @@ function loadEnvConfig() {
   return yaml.load(content);
 }
 
+/**
+ * Decrypts encrypted values in secrets object
+ * Checks for secure:// prefix and decrypts using encryption key from config
+ *
+ * @async
+ * @function decryptSecretsObject
+ * @param {Object} secrets - Secrets object with potentially encrypted values
+ * @returns {Promise<Object>} Secrets object with decrypted values
+ * @throws {Error} If decryption fails or encryption key is missing
+ */
+async function decryptSecretsObject(secrets) {
+  if (!secrets || typeof secrets !== 'object') {
+    return secrets;
+  }
+
+  const encryptionKey = await config.getSecretsEncryptionKey();
+  if (!encryptionKey) {
+    // No encryption key set, check if any values are encrypted
+    const hasEncrypted = Object.values(secrets).some(value => isEncrypted(value));
+    if (hasEncrypted) {
+      throw new Error('Encrypted secrets found but no encryption key configured. Run "aifabrix secure --secrets-encryption <key>" to set encryption key.');
+    }
+    // No encrypted values, return as-is
+    return secrets;
+  }
+
+  const decryptedSecrets = {};
+  for (const [key, value] of Object.entries(secrets)) {
+    if (isEncrypted(value)) {
+      try {
+        decryptedSecrets[key] = decryptSecret(value, encryptionKey);
+      } catch (error) {
+        throw new Error(`Failed to decrypt secret '${key}': ${error.message}`);
+      }
+    } else {
+      decryptedSecrets[key] = value;
+    }
+  }
+
+  return decryptedSecrets;
+}
+
 /**
  * Loads secrets with cascading lookup
  * Supports both user secrets (~/.aifabrix/secrets.local.yaml) and project overrides
  * User's file takes priority, then falls back to build.secrets from variables.yaml
+ * Automatically decrypts values with secure:// prefix
  *
  * @async
  * @function loadSecrets
  * @param {string} [secretsPath] - Path to secrets file (optional, for explicit override)
  * @param {string} [appName] - Application name (optional, for variables.yaml lookup)
- * @returns {Promise<Object>} Loaded secrets object
+ * @returns {Promise<Object>} Loaded secrets object with decrypted values
  * @throws {Error} If no secrets file found and no fallback available
  *
  * @example
@@ -60,6 +104,8 @@ function loadEnvConfig() {
  * // Returns: { 'postgres-passwordKeyVault': 'admin123', ... }
  */
 async function loadSecrets(secretsPath, appName) {
+  let secrets;
+
   // If explicit path provided, use it (backward compatibility)
   if (secretsPath) {
     const resolvedPath = resolveSecretsPath(secretsPath);
@@ -68,34 +114,35 @@ async function loadSecrets(secretsPath, appName) {
     }
 
     const content = fs.readFileSync(resolvedPath, 'utf8');
-    const secrets = yaml.load(content);
+    secrets = yaml.load(content);
 
     if (!secrets || typeof secrets !== 'object') {
       throw new Error(`Invalid secrets file format: ${resolvedPath}`);
     }
+  } else {
+    // Cascading lookup: user's file first
+    let mergedSecrets = loadUserSecrets();
 
-    return secrets;
-  }
-
-  // Cascading lookup: user's file first
-  let mergedSecrets = loadUserSecrets();
+    // Then check build.secrets from variables.yaml if appName provided
+    if (appName) {
+      mergedSecrets = await loadBuildSecrets(mergedSecrets, appName);
+    }
 
-  // Then check build.secrets from variables.yaml if appName provided
-  if (appName) {
-    mergedSecrets = await loadBuildSecrets(mergedSecrets, appName);
-  }
+    // If still no secrets found, try default location
+    if (Object.keys(mergedSecrets).length === 0) {
+      mergedSecrets = loadDefaultSecrets();
+    }
 
-  // If still no secrets found, try default location
-  if (Object.keys(mergedSecrets).length === 0) {
-    mergedSecrets = loadDefaultSecrets();
-  }
+    // If still empty, throw error
+    if (Object.keys(mergedSecrets).length === 0) {
+      throw new Error('No secrets file found. Please create ~/.aifabrix/secrets.local.yaml or configure build.secrets in variables.yaml');
+    }
 
-  // If still empty, throw error
-  if (Object.keys(mergedSecrets).length === 0) {
-    throw new Error('No secrets file found. Please create ~/.aifabrix/secrets.local.yaml or configure build.secrets in variables.yaml');
+    secrets = mergedSecrets;
   }
 
-  return mergedSecrets;
+  // Decrypt encrypted values
+  return await decryptSecretsObject(secrets);
 }
 
 /**
@@ -110,6 +157,7 @@ async function loadSecrets(secretsPath, appName) {
  * @param {Object|string|null} [secretsFilePaths] - Paths object with userPath and buildPath, or string path (for backward compatibility)
  * @param {string} [secretsFilePaths.userPath] - User's secrets file path
  * @param {string|null} [secretsFilePaths.buildPath] - App's build.secrets file path (if configured)
+ * @param {string} [appName] - Application name (optional, for error messages)
  * @returns {Promise<string>} Resolved environment content
  * @throws {Error} If kv:// reference cannot be resolved
  *
@@ -117,7 +165,7 @@ async function loadSecrets(secretsPath, appName) {
  * const resolved = await resolveKvReferences(template, secrets, 'local');
  * // Returns: 'DATABASE_URL=postgresql://user:pass@localhost:5432/db'
  */
-async function resolveKvReferences(envTemplate, secrets, environment = 'local', secretsFilePaths = null) {
+async function resolveKvReferences(envTemplate, secrets, environment = 'local', secretsFilePaths = null, appName = null) {
   const envConfig = loadEnvConfig();
   const envVars = envConfig.environments[environment] || envConfig.environments.local;
 
@@ -152,7 +200,8 @@ async function resolveKvReferences(envTemplate, secrets, environment = 'local',
         fileInfo = `\n\nSecrets file location: ${paths.join(' and ')}`;
       }
     }
-    throw new Error(`Missing secrets: ${missingSecrets.join(', ')}${fileInfo}`);
+    const resolveCommand = appName ? `aifabrix resolve ${appName}` : 'aifabrix resolve <app-name>';
+    throw new Error(`Missing secrets: ${missingSecrets.join(', ')}${fileInfo}\n\nRun "${resolveCommand}" to generate missing secrets.`);
   }
 
   // Now replace kv:// references, and handle ${VAR} inside the secret values
@@ -290,7 +339,7 @@ async function generateEnvFile(appName, secretsPath, environment = 'local', forc
   const template = loadEnvTemplate(templatePath);
 
   // Resolve secrets paths to show in error messages (use actual paths that loadSecrets would use)
-  const secretsPaths = getActualSecretsPath(secretsPath, appName);
+  const secretsPaths = await getActualSecretsPath(secretsPath, appName);
 
   if (force) {
     // Use userPath for generating missing secrets (priority file)
@@ -298,7 +347,7 @@ async function generateEnvFile(appName, secretsPath, environment = 'local', forc
   }
 
   const secrets = await loadSecrets(secretsPath, appName);
-  let resolved = await resolveKvReferences(template, secrets, environment, secretsPaths);
+  let resolved = await resolveKvReferences(template, secrets, environment, secretsPaths, appName);
 
   // Resolve service ports in URLs for docker environment
   if (environment === 'docker') {
@@ -308,7 +357,9 @@ async function generateEnvFile(appName, secretsPath, environment = 'local', forc
   // For local environment, update infrastructure ports to use dev-specific ports
   if (environment === 'local') {
     const devId = await config.getDeveloperId();
-    const ports = devConfig.getDevPorts(devId);
+    // Convert string developer ID to number for getDevPorts
+    const devIdNum = parseInt(devId, 10);
+    const ports = devConfig.getDevPorts(devIdNum);
 
     // Update DATABASE_PORT if present
     resolved = resolved.replace(/^DATABASE_PORT\s*=\s*.*$/m, `DATABASE_PORT=${ports.postgres}`);

package/lib/templates.js

@@ -49,7 +49,7 @@ function generateVariablesYaml(appName, config) {
     build: {
       language: config.language || 'typescript',
       envOutputPath: null,
-      context: `../${appName}`,
+      context: null, // Defaults to dev directory in build process
       dockerfile: '',
       secrets: null
     },

package/lib/utils/build-copy.js

@@ -22,7 +22,7 @@ const os = require('os');
  * @async
  * @function copyBuilderToDevDirectory
  * @param {string} appName - Application name
- * @param {number} developerId - Developer ID
+ * @param {number|string} developerId - Developer ID
  * @returns {Promise<string>} Path to developer-specific directory
  * @throws {Error} If copying fails
  *
@@ -39,7 +39,8 @@ async function copyBuilderToDevDirectory(appName, developerId) {
   }
 
   // Get base directory (applications or applications-dev-{id})
-  const baseDir = developerId === 0
+  const idNum = typeof developerId === 'string' ? parseInt(developerId, 10) : developerId;
+  const baseDir = idNum === 0
     ? path.join(os.homedir(), '.aifabrix', 'applications')
     : path.join(os.homedir(), '.aifabrix', `applications-dev-${developerId}`);
 
@@ -64,7 +65,7 @@ async function copyBuilderToDevDirectory(appName, developerId) {
   await fs.mkdir(devDir, { recursive: true });
 
   // Copy files based on developer ID
-  if (developerId === 0) {
+  if (idNum === 0) {
     // Dev 0: Copy contents from builder/{appName}/ directly to applications/
     await copyDirectory(builderPath, devDir);
   } else {
@@ -112,11 +113,12 @@ async function copyDirectory(sourceDir, targetDir) {
 /**
  * Gets developer-specific directory path for an application
  * @param {string} appName - Application name
- * @param {number} developerId - Developer ID
+ * @param {number|string} developerId - Developer ID
  * @returns {string} Path to developer-specific directory
  */
 function getDevDirectory(appName, developerId) {
-  if (developerId === 0) {
+  const idNum = typeof developerId === 'string' ? parseInt(developerId, 10) : developerId;
+  if (idNum === 0) {
     // Dev 0: all apps go directly to applications/ (no subdirectory)
     return path.join(os.homedir(), '.aifabrix', 'applications');
   }
@@ -125,6 +127,23 @@ function getDevDirectory(appName, developerId) {
 
 }
 
+/**
+ * Copies app source files from apps directory to dev directory
+ * Used when old context format is detected to ensure source files are available
+ * @async
+ * @param {string} appsSourcePath - Path to apps/{appName} directory
+ * @param {string} devDir - Target dev directory
+ * @throws {Error} If copying fails
+ */
+async function copyAppSourceFiles(appsSourcePath, devDir) {
+  if (!fsSync.existsSync(appsSourcePath)) {
+    return; // Nothing to copy
+  }
+
+  // Copy all files from apps directory to dev directory
+  await copyDirectory(appsSourcePath, devDir);
+}
+
 /**
  * Checks if developer-specific directory exists
  * @param {string} appName - Application name
@@ -138,6 +157,7 @@ function devDirectoryExists(appName, developerId) {
 
 module.exports = {
   copyBuilderToDevDirectory,
+  copyAppSourceFiles,
   getDevDirectory,
   devDirectoryExists
 };

package/lib/utils/cli-utils.js

@@ -60,11 +60,12 @@ function formatError(error) {
   } else if (errorMsg.includes('permission')) {
     messages.push('   Permission denied.');
     messages.push('   Make sure you have the necessary permissions to run Docker commands.');
-  } else if (errorMsg.includes('Azure CLI') || errorMsg.includes('az --version')) {
-    messages.push('   Azure CLI is not installed.');
+  } else if (errorMsg.includes('Azure CLI is not installed') || errorMsg.includes('az --version failed') || (errorMsg.includes('az') && errorMsg.includes('failed'))) {
+    // Specific error for missing Azure CLI installation or Azure CLI command failures
+    messages.push('   Azure CLI is not installed or not working properly.');
     messages.push('   Install from: https://docs.microsoft.com/cli/azure/install-azure-cli');
     messages.push('   Run: az login');
-  } else if (errorMsg.includes('authenticate') || errorMsg.includes('ACR')) {
+  } else if (errorMsg.includes('authenticate') || errorMsg.includes('ACR') || errorMsg.includes('Authentication required')) {
     messages.push('   Azure Container Registry authentication failed.');
     messages.push('   Run: az acr login --name <registry-name>');
     messages.push('   Or login to Azure: az login');
@@ -74,6 +75,30 @@ function formatError(error) {
   } else if (errorMsg.includes('Registry URL is required')) {
     messages.push('   Registry URL is required.');
     messages.push('   Provide via --registry flag or configure in variables.yaml under image.registry');
+  } else if (errorMsg.includes('Missing secrets')) {
+    // Extract the missing secrets list and file info from the error message
+    const missingSecretsMatch = errorMsg.match(/Missing secrets: ([^\n]+)/);
+    const fileInfoMatch = errorMsg.match(/Secrets file location: ([^\n]+)/);
+    const resolveMatch = errorMsg.match(/Run "aifabrix resolve ([^"]+)"/);
+
+    if (missingSecretsMatch) {
+      messages.push(`   Missing secrets: ${missingSecretsMatch[1]}`);
+    } else {
+      messages.push('   Missing secrets in secrets file.');
+    }
+
+    if (fileInfoMatch) {
+      messages.push(`   Secrets file location: ${fileInfoMatch[1]}`);
+    }
+
+    // Always show resolve command suggestion
+    if (resolveMatch) {
+      // Extract app name from error message if available
+      messages.push(`   Run: aifabrix resolve ${resolveMatch[1]} to generate missing secrets.`);
+    } else {
+      // Generic suggestion if app name not in error message
+      messages.push('   Run: aifabrix resolve <app-name> to generate missing secrets.');
+    }
   } else if (errorMsg.includes('Deployment failed after')) {
     // Handle deployment retry errors - extract the actual error message
     const match = errorMsg.match(/Deployment failed after \d+ attempts: (.+)/);

package/lib/utils/compose-generator.js

@@ -307,12 +307,13 @@ async function generateDockerCompose(appName, appConfig, options) {
 
   // Get developer ID and network name
   const devId = await config.getDeveloperId();
+  const idNum = typeof devId === 'string' ? parseInt(devId, 10) : devId;
   // Dev 0: infra-aifabrix-network (no dev-0 suffix)
   // Dev > 0: infra-dev{id}-aifabrix-network
-  const networkName = devId === 0 ? 'infra-aifabrix-network' : `infra-dev${devId}-aifabrix-network`;
+  const networkName = idNum === 0 ? 'infra-aifabrix-network' : `infra-dev${devId}-aifabrix-network`;
   // Dev 0: aifabrix-{appName} (no dev-0 suffix)
   // Dev > 0: aifabrix-dev{id}-{appName}
-  const containerName = devId === 0 ? `aifabrix-${appName}` : `aifabrix-dev${devId}-${appName}`;
+  const containerName = idNum === 0 ? `aifabrix-${appName}` : `aifabrix-dev${devId}-${appName}`;
 
   const serviceConfig = buildServiceConfig(appName, appConfig, port);
   const volumesConfig = buildVolumesConfig(appName);
@@ -323,9 +324,21 @@ async function generateDockerCompose(appName, appConfig, options) {
   const envFilePath = path.join(devDir, '.env');
   const envFileAbsolutePath = envFilePath.replace(/\\/g, '/'); // Use forward slashes for Docker
 
-  // Read database passwords from .env file
+  // Read database passwords from .env file only if database is required
   const databases = networksConfig.databases || [];
-  const databasePasswords = await readDatabasePasswords(envFilePath, databases, appName);
+  const requiresDatabase = serviceConfig.requiresDatabase || false;
+  let databasePasswords;
+
+  if (requiresDatabase || databases.length > 0) {
+    // Only read passwords if database is actually required
+    databasePasswords = await readDatabasePasswords(envFilePath, databases, appName);
+  } else {
+    // Return empty passwords when database is not required
+    databasePasswords = {
+      map: {},
+      array: []
+    };
+  }
 
   const templateData = {
     ...serviceConfig,

package/lib/utils/dev-config.js

@@ -27,7 +27,7 @@ const BASE_PORTS = {
  * Developer ID: 0 = default infra (base ports), > 0 = developer-specific (offset ports)
  *
  * @function getDevPorts
- * @param {number} developerId - Developer ID (0 = default infra, 1, 2, 3, etc. = developer-specific)
+ * @param {number} developerId - Developer ID (0 = default infra, 1, 2, 3, etc. = developer-specific). Must be a number.
  * @returns {Object} Object with calculated ports for all services
  *
  * @example
@@ -37,27 +37,28 @@ const BASE_PORTS = {
  * // Returns: { app: 3100, postgres: 5532, redis: 6479, pgadmin: 5150, redisCommander: 8181 }
  */
 function getDevPorts(developerId) {
-  // Validate type first - must be a number
+  // Only accept numbers, reject strings and other types
   if (typeof developerId !== 'number') {
     throw new Error('Developer ID must be a positive number');
   }
 
-  // Handle NaN, undefined, null - throw error (don't default)
-  if (isNaN(developerId) || developerId === undefined || developerId === null) {
+  // Handle invalids
+  if (developerId === undefined || developerId === null || Number.isNaN(developerId)) {
     throw new Error('Developer ID must be a positive number');
   }
-
   if (developerId < 0 || !Number.isInteger(developerId)) {
     throw new Error('Developer ID must be a positive number');
   }
 
+  const idNum = developerId;
+
   // Developer ID 0 = default infra (base ports, no offset)
-  if (developerId === 0) {
+  if (idNum === 0) {
     return { ...BASE_PORTS };
   }
 
   // Developer ID > 0 = developer-specific (add offset)
-  const offset = developerId * 100;
+  const offset = idNum * 100;
 
   return {
     app: BASE_PORTS.app + offset,

package/lib/utils/docker-build.js

@@ -78,6 +78,30 @@ async function executeDockerBuild(imageName, dockerfilePath, contextPath, tag) {
     spinner: 'dots'
   }).start();
 
+  // Ensure paths are absolute and normalized
+  const fsSync = require('fs');
+  const path = require('path');
+
+  dockerfilePath = path.resolve(dockerfilePath);
+  contextPath = path.resolve(contextPath);
+
+  // Validate paths exist (skip in test environments)
+  const isTestEnv = process.env.NODE_ENV === 'test' ||
+                    process.env.JEST_WORKER_ID !== undefined ||
+                    typeof jest !== 'undefined';
+
+  if (!isTestEnv) {
+    if (!fsSync.existsSync(dockerfilePath)) {
+      spinner.fail('Build failed');
+      throw new Error(`Dockerfile not found: ${dockerfilePath}`);
+    }
+
+    if (!fsSync.existsSync(contextPath)) {
+      spinner.fail('Build failed');
+      throw new Error(`Build context path does not exist: ${contextPath}`);
+    }
+  }
+
   return new Promise((resolve, reject) => {
     // Use spawn for streaming output
     const dockerProcess = spawn('docker', [

package/lib/utils/infra-containers.js

@@ -20,14 +20,15 @@ const execAsync = promisify(exec);
  * @private
  * @async
  * @param {string} serviceName - Service name
- * @param {number} [devId] - Developer ID (optional, will be loaded from config if not provided)
+ * @param {number|string} [devId] - Developer ID (optional, will be loaded from config if not provided)
  * @returns {Promise<string|null>} Container name or null if not found
  */
 async function findContainer(serviceName, devId = null) {
   try {
     const developerId = devId || await config.getDeveloperId();
+    const idNum = typeof developerId === 'string' ? parseInt(developerId, 10) : developerId;
     // Dev 0: aifabrix-{serviceName}, Dev > 0: aifabrix-dev{id}-{serviceName}
-    const containerNamePattern = developerId === 0
+    const containerNamePattern = idNum === 0
       ? `aifabrix-${serviceName}`
       : `aifabrix-dev${developerId}-${serviceName}`;
     let { stdout } = await execAsync(`docker ps --filter "name=${containerNamePattern}" --format "{{.Names}}"`);

package/lib/utils/secrets-encryption.js

@@ -0,0 +1,203 @@
+/**
+ * AI Fabrix Builder Secrets Encryption Utilities
+ *
+ * This module provides encryption and decryption functions for secrets
+ * using AES-256-GCM algorithm for ISO 27001 compliance.
+ *
+ * @fileoverview Secrets encryption utilities for AI Fabrix Builder
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const crypto = require('crypto');
+
+const ALGORITHM = 'aes-256-gcm';
+const IV_LENGTH = 12; // 96 bits for GCM
+const AUTH_TAG_LENGTH = 16; // 128 bits
+const KEY_LENGTH = 32; // 256 bits for AES-256
+
+/**
+ * Validates encryption key format
+ * Key must be 32 bytes (256 bits) for AES-256
+ * Accepts hex string (64 chars) or base64 string (44 chars)
+ *
+ * @function validateEncryptionKey
+ * @param {string} key - Encryption key to validate
+ * @returns {boolean} True if key is valid
+ * @throws {Error} If key format is invalid
+ */
+function validateEncryptionKey(key) {
+  if (!key || typeof key !== 'string') {
+    throw new Error('Encryption key is required and must be a string');
+  }
+
+  // Try to parse as hex (64 characters = 32 bytes)
+  if (key.length === 64 && /^[0-9a-fA-F]+$/.test(key)) {
+    return true;
+  }
+
+  // Try to parse as base64 (44 characters = 32 bytes)
+  if (key.length === 44) {
+    try {
+      const buffer = Buffer.from(key, 'base64');
+      if (buffer.length === KEY_LENGTH) {
+        return true;
+      }
+    } catch (error) {
+      // Not valid base64
+    }
+  }
+
+  throw new Error(`Encryption key must be 32 bytes (64 hex characters or 44 base64 characters). Got ${key.length} characters`);
+}
+
+/**
+ * Normalizes encryption key to Buffer
+ * Converts hex or base64 string to 32-byte buffer
+ *
+ * @function normalizeKey
+ * @param {string} key - Encryption key (hex or base64)
+ * @returns {Buffer} 32-byte key buffer
+ */
+function normalizeKey(key) {
+  validateEncryptionKey(key);
+
+  // Try hex first (64 characters)
+  if (key.length === 64 && /^[0-9a-fA-F]+$/.test(key)) {
+    return Buffer.from(key, 'hex');
+  }
+
+  // Try base64 (44 characters)
+  if (key.length === 44) {
+    const buffer = Buffer.from(key, 'base64');
+    if (buffer.length === KEY_LENGTH) {
+      return buffer;
+    }
+  }
+
+  throw new Error('Invalid encryption key format');
+}
+
+/**
+ * Encrypts a secret value using AES-256-GCM
+ * Returns encrypted value in format: secure://<iv>:<ciphertext>:<authTag>
+ * All components are base64 encoded
+ *
+ * @function encryptSecret
+ * @param {string} value - Plaintext secret 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 = encryptSecret('my-secret', 'a1b2c3...');
+ * // Returns: 'secure://<iv>:<ciphertext>:<authTag>'
+ */
+function encryptSecret(value, key) {
+  if (typeof value !== 'string') {
+    throw new Error('Value is required and must be a string');
+  }
+
+  const keyBuffer = normalizeKey(key);
+
+  // Generate random IV
+  const iv = crypto.randomBytes(IV_LENGTH);
+
+  // Create cipher
+  const cipher = crypto.createCipheriv(ALGORITHM, keyBuffer, iv);
+
+  // Encrypt
+  let ciphertext = cipher.update(value, 'utf8', 'base64');
+  ciphertext += cipher.final('base64');
+
+  // Get authentication tag
+  const authTag = cipher.getAuthTag();
+
+  // Format: secure://<iv>:<ciphertext>:<authTag>
+  return `secure://${iv.toString('base64')}:${ciphertext}:${authTag.toString('base64')}`;
+}
+
+/**
+ * Decrypts an encrypted secret value
+ * Handles secure:// prefixed values and extracts IV, ciphertext, and auth tag
+ *
+ * @function decryptSecret
+ * @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 = decryptSecret('secure://<iv>:<ciphertext>:<authTag>', 'a1b2c3...');
+ * // Returns: 'my-secret'
+ */
+function decryptSecret(encryptedValue, key) {
+  if (!encryptedValue || typeof encryptedValue !== 'string') {
+    throw new Error('Encrypted value is required and must be a string');
+  }
+
+  if (!encryptedValue.startsWith('secure://')) {
+    throw new Error('Encrypted value must start with secure:// prefix');
+  }
+
+  const keyBuffer = normalizeKey(key);
+
+  // Remove secure:// prefix
+  const parts = encryptedValue.substring(9).split(':');
+  if (parts.length !== 3) {
+    throw new Error('Invalid encrypted value format. Expected: secure://<iv>:<ciphertext>:<authTag>');
+  }
+
+  const [ivBase64, ciphertext, authTagBase64] = parts;
+
+  try {
+    // Decode IV and auth tag
+    const iv = Buffer.from(ivBase64, 'base64');
+    const authTag = Buffer.from(authTagBase64, 'base64');
+
+    // Validate lengths
+    if (iv.length !== IV_LENGTH) {
+      throw new Error(`Invalid IV length: expected ${IV_LENGTH} bytes, got ${iv.length}`);
+    }
+
+    if (authTag.length !== AUTH_TAG_LENGTH) {
+      throw new Error(`Invalid auth tag length: expected ${AUTH_TAG_LENGTH} bytes, got ${authTag.length}`);
+    }
+
+    // Create decipher
+    const decipher = crypto.createDecipheriv(ALGORITHM, keyBuffer, iv);
+    decipher.setAuthTag(authTag);
+
+    // Decrypt
+    let plaintext = decipher.update(ciphertext, 'base64', 'utf8');
+    plaintext += decipher.final('utf8');
+
+    return plaintext;
+  } catch (error) {
+    // Don't expose sensitive details in error messages
+    if (error.message.includes('Unsupported state') || error.message.includes('bad decrypt')) {
+      throw new Error('Decryption failed: invalid key or corrupted data');
+    }
+    throw error;
+  }
+}
+
+/**
+ * Checks if a value is encrypted (starts with secure://)
+ *
+ * @function isEncrypted
+ * @param {string} value - Value to check
+ * @returns {boolean} True if value is encrypted
+ */
+function isEncrypted(value) {
+  return typeof value === 'string' && value.startsWith('secure://');
+}
+
+module.exports = {
+  encryptSecret,
+  decryptSecret,
+  isEncrypted,
+  validateEncryptionKey,
+  normalizeKey
+};
+