@aifabrix/builder 2.40.2 → 2.42.0

package/lib/utils/credential-secrets-env.js

@@ -0,0 +1,357 @@
+/**
+ * Collect KV_* env vars as secret store items and push to dataplane.
+ * Reads integration .env, resolves kv:// in values, scans payload for kv:// refs,
+ * and pushes plain values to POST /api/v1/credential/secret.
+ *
+ * @fileoverview Credential secrets push from .env and payload (Dataplane)
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const fs = require('fs');
+const { loadSecrets } = require('../core/secrets');
+const { storeCredentialSecrets } = require('../api/credential.api');
+
+const KV_PREFIX = 'KV_';
+const KV_REF_PATTERN = /kv:\/\/([a-zA-Z0-9_\-/]+)/g;
+
+/**
+ * Converts systemKey to KV_* prefix (e.g. hubspot -> HUBSPOT, my-hubspot -> MY_HUBSPOT).
+ * @param {string} systemKey - System key
+ * @returns {string}
+ */
+function systemKeyToKvPrefix(systemKey) {
+  if (!systemKey || typeof systemKey !== 'string') return '';
+  return systemKey.replace(/-/g, '_').toUpperCase();
+}
+
+/**
+ * Maps authentication security key (camelCase) to env VAR (UPPERCASE, no underscores).
+ * Used for canonical KV_<APPKEY>_<VAR> names (e.g. clientId → CLIENTID).
+ * @param {string} securityKey - Security key (e.g. 'clientId', 'clientSecret')
+ * @returns {string}
+ */
+function securityKeyToVar(securityKey) {
+  if (!securityKey || typeof securityKey !== 'string') return '';
+  return securityKey.replace(/_/g, '').toUpperCase();
+}
+
+/** Known single-segment variable suffixes (uppercase) for inferring var vs namespace in env keys */
+const VAR_SUFFIXES = new Set(['ID', 'SECRET', 'KEY', 'TOKEN', 'URL', 'USERNAME', 'PASSWORD']);
+
+/**
+ * Converts var segment(s) from env key to path-style camelCase (e.g. CLIENT_ID → clientId, CLIENTID → clientId).
+ * @param {string[]} varSegments - One or two segments (e.g. ['CLIENT', 'ID'], ['CLIENTID'])
+ * @returns {string}
+ */
+function varSegmentsToCamelCase(varSegments) {
+  if (!varSegments || varSegments.length === 0) return '';
+  if (varSegments.length === 1) {
+    const s = varSegments[0].toLowerCase();
+    if (s.endsWith('id') && s.length > 2) return s.slice(0, -2) + 'Id';
+    if (s.endsWith('secret') && s.length > 6) return s.slice(0, -6) + 'Secret';
+    if (s.endsWith('key') && s.length > 3) return s.slice(0, -3) + 'Key';
+    if (s.endsWith('token') && s.length > 5) return s.slice(0, -5) + 'Token';
+    if (s.endsWith('url') && s.length > 3) return s.slice(0, -3) + 'Url';
+    return s;
+  }
+  return varSegments.map((seg, i) => {
+    const lower = seg.toLowerCase();
+    return i === 0 ? lower : lower.charAt(0).toUpperCase() + lower.slice(1);
+  }).join('');
+}
+
+/**
+ * Builds kv path from segments when systemKey is provided (path = kv://systemKey/variable).
+ * @param {string[]} segments - Parsed segments after KV_ prefix
+ * @param {string} systemKey - System key (e.g. 'microsoft-teams')
+ * @returns {string|null}
+ */
+function kvPathWithSystemKey(segments, systemKey) {
+  const prefixInKey = systemKey.replace(/-/g, '_').toUpperCase();
+  const prefixSegs = prefixInKey.split('_').filter(Boolean);
+  if (segments.length <= prefixSegs.length) return null;
+  const prefixMatch = prefixSegs.every((p, i) => segments[i] === p);
+  if (!prefixMatch) return null;
+  const varSegments = segments.slice(prefixSegs.length);
+  const pathVar = varSegmentsToCamelCase(varSegments);
+  return pathVar ? `kv://${systemKey}/${pathVar}` : null;
+}
+
+/**
+ * Builds kv path from segments when systemKey is not provided (infers namespace and variable).
+ * @param {string[]} segments - Parsed segments after KV_ prefix
+ * @returns {string|null}
+ */
+function kvPathInferred(segments) {
+  if (segments.length === 1) return `kv://${segments[0].toLowerCase()}`;
+  const varSegmentCount = (segments.length >= 2 && VAR_SUFFIXES.has(segments[segments.length - 1])) ? 2 : 1;
+  const namespace = segments.slice(0, -varSegmentCount).map(s => s.toLowerCase()).join('-');
+  const varSegments = segments.slice(-varSegmentCount);
+  const pathVar = varSegmentsToCamelCase(varSegments);
+  return (namespace && pathVar) ? `kv://${namespace}/${pathVar}` : null;
+}
+
+/**
+ * Converts KV_* env key to kv:// path in format kv://&lt;system-key&gt;/&lt;variable&gt;.
+ * System-key uses hyphens (e.g. microsoft-teams); variable is camelCase (e.g. clientId).
+ * When systemKey is provided, uses it as the path namespace; otherwise infers from segments.
+ *
+ * @param {string} envKey - Env var name (e.g. KV_MICROSOFT_TEAMS_CLIENT_ID)
+ * @param {string} [systemKey] - Optional system key (e.g. 'microsoft-teams'); when provided, path is kv://systemKey/variable
+ * @returns {string|null} kv:// path or null if invalid
+ */
+function kvEnvKeyToPath(envKey, systemKey) {
+  if (!envKey || typeof envKey !== 'string' || !envKey.toUpperCase().startsWith(KV_PREFIX)) return null;
+  const rest = envKey.slice(KV_PREFIX.length).trim();
+  if (!rest) return null;
+  const segments = rest.split('_').filter(Boolean);
+  if (segments.length === 0) return null;
+
+  const hasSystemKey = typeof systemKey === 'string' && systemKey.length > 0;
+  if (hasSystemKey) return kvPathWithSystemKey(segments, systemKey);
+  return kvPathInferred(segments);
+}
+
+/**
+ * Collects KV_* entries from env map as secret items (key = kv path, value = raw).
+ * When value is a kv:// path, uses it as the key so it matches payload paths (e.g. kv://microsoft-teams/clientId).
+ * Otherwise derives path from env key via kvEnvKeyToPath(envKey).
+ *
+ * @param {Object.<string, string>} envMap - Key-value map from .env
+ * @returns {Array<{ key: string, value: string }>} Items (key = kv://..., value = raw)
+ */
+function collectKvEnvVarsAsSecretItems(envMap) {
+  if (!envMap || typeof envMap !== 'object') {
+    return [];
+  }
+  const items = [];
+  for (const [envKey, rawValue] of Object.entries(envMap)) {
+    const value = typeof rawValue === 'string' ? rawValue.trim() : '';
+    if (value === '') continue;
+    let kvPath = null;
+    if (value.startsWith('kv://') && isValidKvPath(value)) {
+      kvPath = value;
+    }
+    if (!kvPath) kvPath = kvEnvKeyToPath(envKey);
+    if (!kvPath) continue;
+    items.push({ key: kvPath, value });
+  }
+  return items;
+}
+
+/**
+ * Resolves a single value if it is a kv:// reference using secrets map.
+ * Supports path-style keys (e.g. secrets/foo) and hyphen-style (secrets-foo).
+ *
+ * @param {Object} secrets - Loaded secrets object
+ * @param {string} value - Value (may be "kv://..." or plain)
+ * @returns {string|null} Resolved plain value or null if unresolved
+ */
+function resolveKvValue(secrets, value) {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  if (!trimmed.startsWith('kv://')) {
+    return trimmed;
+  }
+  const pathMatch = trimmed.match(/^kv:\/\/([a-zA-Z0-9_\-/]+)$/);
+  if (!pathMatch) return null;
+  const pathKey = pathMatch[1];
+  const resolved = secrets[pathKey];
+  if (resolved === undefined) return null;
+  return typeof resolved === 'string' ? resolved : String(resolved);
+}
+
+/**
+ * Recursively collects all kv:// references from a JSON-serializable payload.
+ *
+ * @param {Object|Array|string|number|boolean|null} obj - Upload payload (application + dataSources)
+ * @param {Set<string>} [acc] - Accumulator set (internal)
+ * @returns {string[]} Unique kv:// refs (e.g. ["kv://secrets/foo"])
+ */
+function collectKvRefsFromPayload(obj, acc = new Set()) {
+  if (obj === null || obj === undefined) {
+    return Array.from(acc);
+  }
+  if (typeof obj === 'string') {
+    let m;
+    KV_REF_PATTERN.lastIndex = 0;
+    while ((m = KV_REF_PATTERN.exec(obj)) !== null) {
+      acc.add(`kv://${m[1]}`);
+    }
+    return Array.from(acc);
+  }
+  if (Array.isArray(obj)) {
+    for (const item of obj) {
+      collectKvRefsFromPayload(item, acc);
+    }
+    return Array.from(acc);
+  }
+  if (typeof obj === 'object') {
+    for (const v of Object.values(obj)) {
+      collectKvRefsFromPayload(v, acc);
+    }
+    return Array.from(acc);
+  }
+  return Array.from(acc);
+}
+
+/**
+ * Validates that key is a well-formed kv path (kv:// with alphanumeric/hyphen/slash segments).
+ *
+ * @param {string} key - kv:// path
+ * @returns {boolean}
+ */
+function isValidKvPath(key) {
+  return typeof key === 'string' && /^kv:\/\/[a-z0-9][a-z0-9\-/]*$/i.test(key.trim());
+}
+
+/**
+ * Builds secret items from .env file (KV_* vars, values resolved).
+ * @param {string} envFilePath - Path to .env
+ * @param {Object} secrets - Loaded secrets
+ * @param {Map<string, string>} itemsByKey - Mutable map to add items to
+ */
+function buildItemsFromEnv(envFilePath, secrets, itemsByKey) {
+  if (!envFilePath || typeof envFilePath !== 'string' || !fs.existsSync(envFilePath)) return;
+  try {
+    const content = fs.readFileSync(envFilePath, 'utf8');
+    const envMap = parseEnvToMap(content);
+    const fromEnv = collectKvEnvVarsAsSecretItems(envMap);
+    for (const { key, value } of fromEnv) {
+      const resolved = resolveKvValue(secrets, value);
+      if (resolved !== null && resolved !== undefined && isValidKvPath(key)) itemsByKey.set(key, resolved);
+    }
+  } catch {
+    // Best-effort: continue without .env items
+  }
+}
+
+/**
+ * Builds secret items from payload kv:// refs not already in itemsByKey.
+ * @param {Object} payload - Upload payload
+ * @param {Object} secrets - Loaded secrets
+ * @param {Map<string, string>} itemsByKey - Mutable map to add items to
+ */
+function buildItemsFromPayload(payload, secrets, itemsByKey) {
+  if (!payload || typeof payload !== 'object') return;
+  const refs = collectKvRefsFromPayload(payload);
+  const existingKeys = new Set(itemsByKey.keys());
+  for (const ref of refs) {
+    if (existingKeys.has(ref)) continue;
+    const pathKey = ref.replace(/^kv:\/\//, '');
+    const resolved = secrets[pathKey];
+    if (resolved !== null && resolved !== undefined && isValidKvPath(ref)) {
+      itemsByKey.set(ref, typeof resolved === 'string' ? resolved : String(resolved));
+    }
+  }
+}
+
+/**
+ * Derives stored count from API response.
+ * @param {Object} res - Response from storeCredentialSecrets
+ * @param {number} fallback - Fallback when stored not in response
+ * @returns {number}
+ */
+function storedCountFromResponse(res, fallback) {
+  if (res && typeof res.stored === 'number') return res.stored;
+  if (res && res.data && res.data.stored !== undefined && res.data.stored !== null) return res.data.stored;
+  return fallback;
+}
+
+/**
+ * Sends items to dataplane credential API; returns pushed count or warning.
+ * @param {string} dataplaneUrl - Dataplane URL
+ * @param {Object} authConfig - Auth config
+ * @param {Array<{ key: string, value: string }>} items - Items to send
+ * @returns {Promise<{ pushed: number, warning?: string }>}
+ */
+async function sendCredentialSecrets(dataplaneUrl, authConfig, items) {
+  try {
+    const res = await storeCredentialSecrets(dataplaneUrl, authConfig, items);
+    const failed = res && (res.success === false || res.data?.success === false);
+    if (failed) {
+      const status = res.status ?? res.statusCode;
+      if (status === 403 || status === 401) {
+        return { pushed: 0, warning: 'Could not push credential secrets (permission denied or unauthenticated). Ensure dataplane role has credential:create if you use KV_* in .env.' };
+      }
+      const errMsg = res.formattedError || res.data?.formattedError || res.error || res.data?.error || 'Failed to push credential secrets to dataplane.';
+      return { pushed: 0, warning: errMsg };
+    }
+    return { pushed: storedCountFromResponse(res, items.length) };
+  } catch (err) {
+    return { pushed: 0, warning: err.message || 'Failed to push credential secrets to dataplane.' };
+  }
+}
+
+/**
+ * Pushes credential secrets to dataplane: from .env (KV_*) and from payload kv:// refs.
+ * Resolves all kv:// in values via loadSecrets; sends only plain values. Best-effort:
+ * on 403/401 logs warning and returns; never logs secret values.
+ *
+ * @param {string} dataplaneUrl - Dataplane base URL
+ * @param {Object} authConfig - Auth config (Bearer)
+ * @param {Object} options - Options
+ * @param {string} [options.envFilePath] - Path to .env (integration/<systemKey>/.env)
+ * @param {string} [options.appName] - App/system name for loadSecrets context
+ * @param {Object} [options.payload] - Upload payload { application, dataSources } for kv scan
+ * @returns {Promise<{ pushed: number, keys?: string[], skipped?: boolean, warning?: string }>} Count pushed, keys (on success), skipped (when nothing to push), optional warning
+ */
+async function pushCredentialSecrets(dataplaneUrl, authConfig, options = {}) {
+  const { envFilePath, appName, payload } = options;
+  let secrets;
+  try {
+    secrets = await loadSecrets(undefined, appName);
+  } catch {
+    secrets = {};
+  }
+  const itemsByKey = new Map();
+  buildItemsFromEnv(envFilePath, secrets, itemsByKey);
+  buildItemsFromPayload(payload, secrets, itemsByKey);
+
+  const items = Array.from(itemsByKey.entries())
+    .filter(([k]) => isValidKvPath(k))
+    .map(([key, value]) => ({ key, value }));
+
+  if (items.length === 0) return { pushed: 0, skipped: true };
+  const sendResult = await sendCredentialSecrets(dataplaneUrl, authConfig, items);
+  if (sendResult.pushed > 0) {
+    sendResult.keys = items.map(i => i.key.replace(/^kv:\/\//, ''));
+  }
+  return sendResult;
+}
+
+/**
+ * Parses .env-style content into key-value map (first = separates key and value).
+ *
+ * @param {string} content - Raw .env content
+ * @returns {Object.<string, string>}
+ */
+function parseEnvToMap(content) {
+  if (!content || typeof content !== 'string') return {};
+  const map = {};
+  const lines = content.split(/\r?\n/);
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const eq = trimmed.indexOf('=');
+    if (eq > 0) {
+      const key = trimmed.substring(0, eq).trim();
+      const value = trimmed.substring(eq + 1);
+      map[key] = value;
+    }
+  }
+  return map;
+}
+
+module.exports = {
+  collectKvEnvVarsAsSecretItems,
+  collectKvRefsFromPayload,
+  pushCredentialSecrets,
+  kvEnvKeyToPath,
+  systemKeyToKvPrefix,
+  securityKeyToVar,
+  isValidKvPath,
+  resolveKvValue,
+  parseEnvToMap
+};

package/lib/utils/dataplane-pipeline-warning.js

@@ -0,0 +1,28 @@
+/**
+ * Shared warning message for Dataplane pipeline API usage (upload / validate / publish).
+ * Used by upload command and datasource upload so users know configuration is sent to Dataplane.
+ *
+ * @fileoverview Dataplane pipeline usage warning
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const chalk = require('chalk');
+const logger = require('./logger');
+
+/** Message shown when CLI is about to call Dataplane pipeline upload or publish APIs. */
+const DATAPLANE_PIPELINE_WARNING =
+  'Configuration will be sent to the Dataplane pipeline API. Ensure you are targeting the correct environment and have the required permissions.';
+
+/**
+ * Log the Dataplane pipeline warning (yellow) to the console.
+ * Call before uploadApplicationViaPipeline or publishDatasourceViaPipeline.
+ */
+function logDataplanePipelineWarning() {
+  logger.log(chalk.yellow(`⚠ ${DATAPLANE_PIPELINE_WARNING}`));
+}
+
+module.exports = {
+  DATAPLANE_PIPELINE_WARNING,
+  logDataplanePipelineWarning
+};

package/lib/utils/deployment-validation-helpers.js

@@ -34,7 +34,7 @@ function processSuccessfulValidation(responseData) {
 function processValidationFailure(responseData) {
   const errorMessage = responseData.errors && responseData.errors.length > 0
     ? `Validation failed: ${responseData.errors.join(', ')}`
-    : 'Validation failed: Invalid configuration';
+    : (responseData.error || responseData.formattedError || 'Validation failed: Invalid configuration');
   const error = new Error(errorMessage);
   error.status = 400;
   error.data = responseData;
@@ -78,13 +78,13 @@ function handleValidationResponse(response) {
     if (responseData.valid === true) {
       return processSuccessfulValidation(responseData);
     }
-    // Handle validation failure (valid: false)
-    if (responseData.valid === false) {
+    // Handle validation failure (valid: false or success: false in body)
+    if (responseData.valid === false || responseData.success === false) {
       processValidationFailure(responseData);
     }
   }
 
-  // Handle validation errors (non-success responses)
+  // Handle validation errors (non-success HTTP responses)
   if (!response.success) {
     processValidationError(response);
   }

package/lib/utils/dev-ca-install.js

@@ -0,0 +1,139 @@
+/**
+ * Dev CA Install – SSL untrusted detection, fetch CA from Builder Server, install into OS trust store.
+ * Used by `aifabrix dev init` when the server certificate is self-signed. Only /install-ca uses
+ * rejectUnauthorized: false; all other requests use default TLS verification.
+ *
+ * @fileoverview CA install utilities for development Builder Server
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const fs = require('fs').promises;
+const path = require('path');
+const https = require('https');
+const os = require('os');
+const { execFileSync } = require('child_process');
+const readline = require('readline');
+const chalk = require('chalk');
+
+const SSL_UNTRUSTED_CODES = [
+  'UNABLE_TO_VERIFY_LEAF_SIGNATURE',
+  'DEPTH_ZERO_SELF_SIGNED_CERT',
+  'CERT_UNTRUSTED',
+  'SELF_SIGNED_CERT_IN_CHAIN',
+  'UNABLE_TO_GET_ISSUER_CERT',
+  'UNABLE_TO_GET_ISSUER_CERT_LOCALLY'
+];
+
+/**
+ * Returns true if the error indicates an untrusted/self-signed server certificate.
+ * @param {Error} err - Thrown error (e.g. from devApi.getHealth)
+ * @returns {boolean}
+ */
+function isSslUntrustedError(err) {
+  const code = err?.code || err?.cause?.code;
+  const msg = (err?.message || '').toUpperCase();
+  return SSL_UNTRUSTED_CODES.some(c => code === c || msg.includes(c));
+}
+
+/**
+ * Fetch CA PEM from Builder Server via GET {baseUrl}/install-ca.
+ * Uses rejectUnauthorized: false only for this endpoint (dev setup).
+ * @param {string} baseUrl - Builder Server base URL (no trailing slash)
+ * @returns {Promise<Buffer>} CA certificate PEM
+ */
+function fetchInstallCa(baseUrl) {
+  return new Promise((resolve, reject) => {
+    const url = `${baseUrl.replace(/\/+$/, '')}/install-ca`;
+    const urlObj = new URL(url);
+    if (urlObj.protocol !== 'https:') {
+      reject(new Error('install-ca requires https URL'));
+      return;
+    }
+    const agent = new https.Agent({ rejectUnauthorized: false });
+    const req = https.get(
+      url,
+      { agent },
+      (res) => {
+        if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+          req.destroy();
+          fetchInstallCa(res.headers.location).then(resolve).catch(reject);
+          return;
+        }
+        const chunks = [];
+        res.on('data', c => chunks.push(c));
+        res.on('end', () => {
+          const body = Buffer.concat(chunks).toString('utf8');
+          if (!body || !body.includes('-----BEGIN CERTIFICATE-----')) {
+            reject(new Error('Invalid CA response: expected PEM certificate'));
+            return;
+          }
+          resolve(Buffer.from(body, 'utf8'));
+        });
+      }
+    );
+    req.on('error', reject);
+  });
+}
+
+/**
+ * Install CA PEM into OS trust store (platform-specific).
+ * @param {Buffer|string} caPem - CA certificate PEM
+ * @param {string} baseUrl - Builder Server base URL (for help link)
+ * @returns {Promise<void>}
+ */
+async function installCaPlatform(caPem, baseUrl) {
+  const pem = Buffer.isBuffer(caPem) ? caPem.toString('utf8') : String(caPem);
+  const tmpDir = os.tmpdir();
+  const tmpPath = path.join(tmpDir, 'aifabrix-root-ca.crt');
+  await fs.writeFile(tmpPath, pem, { mode: 0o644 });
+
+  try {
+    if (process.platform === 'win32') {
+      execFileSync('certutil', ['-addstore', '-user', 'ROOT', tmpPath], { stdio: 'inherit' });
+    } else if (process.platform === 'darwin') {
+      const keychain = path.join(os.homedir(), 'Library', 'Keychains', 'login.keychain-db');
+      execFileSync('security', ['add-trusted-cert', '-d', '-r', 'trustRoot', '-k', keychain, tmpPath], { stdio: 'inherit' });
+    } else if (process.platform === 'linux') {
+      const certPath = '/usr/local/share/ca-certificates/aifabrix-root-ca.crt';
+      try {
+        await fs.writeFile(certPath, pem, { mode: 0o644 });
+        execFileSync('update-ca-certificates', [], { stdio: 'inherit' });
+      } catch (e) {
+        if (e.code === 'EACCES' || (e.status !== undefined && e.status !== null && e.status !== 0)) {
+          const helpUrl = `${baseUrl.replace(/\/+$/, '')}/install-ca-help`;
+          throw new Error(
+            `Linux CA install requires sudo. Save CA manually from ${helpUrl} to ${certPath} and run: sudo update-ca-certificates`
+          );
+        }
+        throw e;
+      }
+    } else {
+      throw new Error(`Unsupported platform: ${process.platform}`);
+    }
+  } finally {
+    await fs.unlink(tmpPath).catch(() => {});
+  }
+}
+
+/**
+ * Prompt user: "Download and install the development CA? (y/n)"
+ * @returns {Promise<boolean>}
+ */
+function promptInstallCa() {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise(resolve => {
+    rl.question(chalk.yellow('Server certificate not trusted. Download and install the development CA? (y/n) '), answer => {
+      rl.close();
+      const normalized = (answer || '').trim().toLowerCase();
+      resolve(normalized === 'y' || normalized === 'yes');
+    });
+  });
+}
+
+module.exports = {
+  isSslUntrustedError,
+  fetchInstallCa,
+  installCaPlatform,
+  promptInstallCa
+};

package/lib/utils/dev-cert-helper.js

@@ -0,0 +1,122 @@
+/**
+ * @fileoverview Helper for generating CSR and saving dev certificates (Builder Server onboarding)
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const os = require('os');
+
+/**
+ * Generate a key pair and CSR for developer certificate. Uses OpenSSL when available.
+ * CN in CSR is set to dev-<developerId> per Builder Server convention.
+ * @param {string} developerId - Developer ID (e.g. "01")
+ * @returns {{ csrPem: string, keyPem: string }} PEM-encoded CSR and private key
+ * @throws {Error} If OpenSSL is not available or generation fails
+ */
+function generateCSR(developerId) {
+  if (!developerId || typeof developerId !== 'string') {
+    throw new Error('developerId is required and must be a string');
+  }
+  const cn = `dev-${developerId}`;
+  const tmpDir = path.join(os.tmpdir(), `aifabrix-csr-${Date.now()}`);
+  fs.mkdirSync(tmpDir, { recursive: true });
+  const keyPath = path.join(tmpDir, 'key.pem');
+  const csrPath = path.join(tmpDir, 'csr.pem');
+  try {
+    execSync(
+      `openssl req -new -newkey rsa:2048 -keyout "${keyPath}" -nodes -subj "/CN=${cn}" -out "${csrPath}"`,
+      { stdio: 'pipe', encoding: 'utf8' }
+    );
+    const keyPem = fs.readFileSync(keyPath, 'utf8');
+    const csrPem = fs.readFileSync(csrPath, 'utf8');
+    return { csrPem, keyPem };
+  } catch (err) {
+    if (err.message && (err.message.includes('openssl') || err.message.includes('ENOENT'))) {
+      throw new Error(
+        'OpenSSL is required for certificate generation. Install OpenSSL and ensure it is on PATH, or use a system that provides it (e.g. Git for Windows).'
+      );
+    }
+    throw new Error(`CSR generation failed: ${err.message}`);
+  } finally {
+    try {
+      fs.unlinkSync(keyPath);
+      fs.unlinkSync(csrPath);
+      fs.rmdirSync(tmpDir);
+    } catch {
+      // ignore cleanup errors
+    }
+  }
+}
+
+/**
+ * Return path to the directory where dev certificates are stored for a developer.
+ * @param {string} configDir - Config directory (e.g. from getConfigDirForPaths())
+ * @param {string} developerId - Developer ID
+ * @returns {string} Absolute path to certs/<developerId>/
+ */
+function getCertDir(configDir, developerId) {
+  return path.join(configDir, 'certs', developerId);
+}
+
+/**
+ * Read client certificate PEM from cert dir (cert.pem).
+ * @param {string} certDir - Directory containing cert.pem
+ * @returns {string|null} PEM content or null if not found
+ */
+function readClientCertPem(certDir) {
+  const certPath = path.join(certDir, 'cert.pem');
+  try {
+    return fs.readFileSync(certPath, 'utf8');
+  } catch (e) {
+    if (e.code === 'ENOENT') return null;
+    throw e;
+  }
+}
+
+/**
+ * Read client private key PEM from cert dir (key.pem). Used for mTLS (e.g. getSettings).
+ * @param {string} certDir - Directory containing key.pem
+ * @returns {string|null} PEM content or null if not found
+ */
+function readClientKeyPem(certDir) {
+  const keyPath = path.join(certDir, 'key.pem');
+  try {
+    return fs.readFileSync(keyPath, 'utf8');
+  } catch (e) {
+    if (e.code === 'ENOENT') return null;
+    throw e;
+  }
+}
+
+/**
+ * Get certificate validity end (notAfter) from cert.pem in certDir using OpenSSL.
+ * @param {string} certDir - Directory containing cert.pem
+ * @returns {Date|null} Expiry date or null if cert missing/invalid or OpenSSL fails
+ */
+function getCertValidNotAfter(certDir) {
+  const certPath = path.join(certDir, 'cert.pem');
+  try {
+    if (!fs.existsSync(certPath)) return null;
+    const out = execSync(
+      `openssl x509 -enddate -noout -in "${certPath}"`,
+      { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }
+    );
+    const match = out.match(/notAfter=(.+)/);
+    if (!match) return null;
+    const date = new Date(match[1].trim());
+    return isNaN(date.getTime()) ? null : date;
+  } catch {
+    return null;
+  }
+}
+
+module.exports = {
+  generateCSR,
+  getCertDir,
+  readClientCertPem,
+  readClientKeyPem,
+  getCertValidNotAfter
+};