@aifabrix/builder 2.43.0 → 2.44.0

package/lib/api/dev.api.js

@@ -1,15 +1,15 @@
 /**
  * @fileoverview Builder Server (dev) API – issue-cert, settings, users, SSH keys, secrets.
  * First call: issue-cert is public (no client cert). All other routes require client certificate:
- * when clientKeyPem is provided, requests use mTLS (TLS client cert); otherwise X-Client-Cert header only.
+ * when clientKeyPem is provided and the URL is https, requests use mTLS (TLS client cert).
+ * For http:// URLs, mTLS is impossible; the same routes use X-Client-Cert only (same as when no key is passed).
  * @author AI Fabrix Team
  * @version 2.0.0
  */
 
-const https = require('https');
 const { makeApiCall } = require('../utils/api');
-
-const DEFAULT_TIMEOUT_MS = 15000;
+const { httpsJsonRequest, DEFAULT_TIMEOUT_MS, shouldUseMtlsForUrl } = require('./dev-server-https');
+const { requestWithClientCert } = require('./dev-mtls-request');
 
 /**
  * Encode PEM for use in X-Client-Cert header. HTTP header values must not contain newlines;
@@ -46,20 +46,48 @@ function buildUrl(baseUrl, path) {
   return `${baseUrl}${p}`;
 }
 
+function isHttpOrHttpsUrl(value) {
+  return typeof value === 'string' && (value.startsWith('http://') || value.startsWith('https://'));
+}
+
 /**
- * Make request to Builder Server. Throws on !success with message from response or error.
+ * Full URL for shared-secrets collection (GET list / POST add). DELETE uses this base + /:key.
+ * When secretsEndpointUrl is set (config aifabrix-secrets), uses it; if it is only a host base (path /), appends /api/dev/secrets.
+ * @param {string} serverUrl - Builder Server base URL
+ * @param {string} [secretsEndpointUrl] - Optional secrets API URL from config
+ * @returns {string}
+ */
+function resolveSecretsEndpoint(serverUrl, secretsEndpointUrl) {
+  if (secretsEndpointUrl && isHttpOrHttpsUrl(secretsEndpointUrl)) {
+    const normalized = normalizeBaseUrl(secretsEndpointUrl);
+    let u;
+    try {
+      u = new URL(normalized);
+    } catch {
+      return buildUrl(normalizeBaseUrl(serverUrl), '/api/dev/secrets');
+    }
+    if (u.pathname === '/' || u.pathname === '') {
+      return buildUrl(normalized, '/api/dev/secrets');
+    }
+    return normalized;
+  }
+  return buildUrl(normalizeBaseUrl(serverUrl), '/api/dev/secrets');
+}
+
+/**
+ * Builder Server request via global fetch (public CAs only).
  * @param {string} url - Full URL
- * @param {Object} options - Fetch options (method, headers, body)
- * @returns {Promise<Object>} result.data when success
+ * @param {Object} rest - method, headers, body
+ * @returns {Promise<Object>}
  */
-async function request(url, options = {}) {
+async function requestViaFetchApi(url, rest) {
   const fetchOptions = {
-    method: options.method || 'GET',
-    headers: { 'Content-Type': 'application/json', ...options.headers },
+    method: rest.method || 'GET',
+    headers: { 'Content-Type': 'application/json', ...rest.headers },
     signal: AbortSignal.timeout(DEFAULT_TIMEOUT_MS)
   };
-  if (options.body !== undefined) {
-    fetchOptions.body = typeof options.body === 'string' ? options.body : JSON.stringify(options.body);
+  if (rest.body !== undefined) {
+    fetchOptions.body = typeof rest.body === 'string' ? rest.body : JSON.stringify(rest.body);
   }
   const result = await makeApiCall(url, fetchOptions);
   if (!result.success) {
@@ -67,103 +95,36 @@ async function request(url, options = {}) {
     const err = new Error(msg);
     err.status = result.status;
     err.errorData = result.errorData;
+    if (result.originalError) {
+      err.cause = result.originalError;
+    }
     throw err;
   }
   return result.data;
 }
 
 /**
- * Build request options and TLS agent for mTLS request.
+ * Make request to Builder Server. Throws on !success with message from response or error.
+ * When options.serverCaPem is set, uses Node https with merged CA (Node ignores Windows user ROOT for fetch).
  * @param {string} url - Full URL
- * @param {Object} options - { method, headers, body }
- * @param {string} certPem - PEM client certificate
- * @param {string} keyPem - PEM client key
- * @returns {{ urlObj: URL, method: string, headers: Object, body: string|undefined, agent: https.Agent }}
- */
-function buildMtlsRequestOptions(url, options, certPem, keyPem) {
-  const urlObj = new URL(url);
-  const method = (options.method || 'GET').toUpperCase();
-  const headers = { 'Content-Type': 'application/json', ...options.headers };
-  let body = options.body;
-  if (body !== undefined && typeof body !== 'string') {
-    body = JSON.stringify(body);
-  }
-  if (body) {
-    headers['Content-Length'] = Buffer.byteLength(body, 'utf8');
-  }
-  const tlsOptions = { cert: certPem, key: keyPem, rejectUnauthorized: true };
-  const agent = new https.Agent(tlsOptions);
-  return { urlObj, method, headers, body, agent, tlsOptions };
-}
-
-/**
- * Handle mTLS response: collect body, parse JSON, resolve or reject.
- * @param {import('http').IncomingMessage} res - HTTP response
- * @param {Function} resolve - Promise resolve
- * @param {Function} reject - Promise reject
+ * @param {Object} options - Fetch options (method, headers, body, serverCaPem)
+ * @returns {Promise<Object>} result.data when success
  */
-function handleMtlsResponse(res, resolve, reject) {
-  const chunks = [];
-  res.on('data', (c) => chunks.push(c));
-  res.on('end', () => {
-    const raw = Buffer.concat(chunks).toString('utf8');
-    let data;
+async function request(url, options = {}) {
+  const { serverCaPem, ...rest } = options;
+  const pem = serverCaPem && typeof serverCaPem === 'string' && serverCaPem.trim() ? serverCaPem.trim() : null;
+  let useMergedCaHttps = false;
+  if (pem) {
     try {
-      data = raw ? JSON.parse(raw) : {};
+      useMergedCaHttps = new URL(url).protocol === 'https:';
     } catch {
-      data = raw;
-    }
-    if (res.statusCode < 200 || res.statusCode >= 300) {
-      const msg = (data && (data.message || data.error)) || res.statusMessage || `Request failed (${res.statusCode})`;
-      const err = new Error(msg);
-      err.status = res.statusCode;
-      err.errorData = data;
-      reject(err);
-    } else {
-      resolve(data);
+      useMergedCaHttps = false;
     }
-  });
-}
-
-/**
- * Make request with mTLS (TLS client certificate). Uses Node https module so the client cert
- * is presented in the TLS handshake. Also sends X-Client-Cert header for backends that read it.
- * @param {string} url - Full URL (https only)
- * @param {Object} options - { method, headers, body }
- * @param {string} certPem - PEM-encoded client certificate
- * @param {string} keyPem - PEM-encoded client private key
- * @returns {Promise<Object>} response data when success
- */
-function requestWithCertImpl(url, options, certPem, keyPem) {
-  return new Promise((resolve, reject) => {
-    const urlObj = new URL(url);
-    if (urlObj.protocol !== 'https:') {
-      reject(new Error('mTLS request requires https URL'));
-      return;
-    }
-    const { method, headers, body, agent, tlsOptions } = buildMtlsRequestOptions(url, options, certPem, keyPem);
-    const req = https.request(
-      {
-        hostname: urlObj.hostname,
-        port: urlObj.port || 443,
-        path: urlObj.pathname + urlObj.search,
-        method,
-        headers,
-        agent,
-        ...tlsOptions
-      },
-      (res) => handleMtlsResponse(res, resolve, reject)
-    );
-    req.on('error', reject);
-    req.setTimeout(DEFAULT_TIMEOUT_MS, () => {
-      req.destroy();
-      reject(new Error(`Request timed out after ${DEFAULT_TIMEOUT_MS}ms`));
-    });
-    if (body) {
-      req.write(body, 'utf8');
-    }
-    req.end();
-  });
+  }
+  if (pem && useMergedCaHttps) {
+    return httpsJsonRequest(url, rest, pem);
+  }
+  return requestViaFetchApi(url, rest);
 }
 
 /**
@@ -171,44 +132,47 @@ function requestWithCertImpl(url, options, certPem, keyPem) {
  * @requiresPermission {BuilderServer} Public (no auth required)
  * @param {string} serverUrl - Builder Server base URL
  * @param {Object} body - IssueCertDto: developerId, pin, csr
+ * @param {string} [serverCaPem] - Dev root CA PEM when Node must trust a private CA (e.g. after install-ca)
  * @returns {Promise<Object>} IssueCertResponseDto: certificate, validDays, validNotAfter
  */
-async function issueCert(serverUrl, body) {
+async function issueCert(serverUrl, body, serverCaPem) {
   const base = normalizeBaseUrl(serverUrl);
-  return request(buildUrl(base, '/api/dev/issue-cert'), { method: 'POST', body });
+  return request(buildUrl(base, '/api/dev/issue-cert'), { method: 'POST', body, serverCaPem });
 }
 
 /**
  * Get health. GET /health (public)
  * @requiresPermission {BuilderServer} Public (no auth required)
  * @param {string} serverUrl - Builder Server base URL
+ * @param {string} [serverCaPem] - Dev root CA PEM when verifying a private CA
  * @returns {Promise<Object>} HealthResponseDto: status, checks (dataDir, encryptionKey, ca, users, tokens)
  */
-async function getHealth(serverUrl) {
+async function getHealth(serverUrl, serverCaPem) {
   const base = normalizeBaseUrl(serverUrl);
-  return request(buildUrl(base, '/health'));
+  return request(buildUrl(base, '/health'), { method: 'GET', serverCaPem });
 }
 
 /**
  * Get developer settings (cert-authenticated). GET /api/dev/settings
- * When clientKeyPem is provided, uses mTLS (TLS client cert); otherwise X-Client-Cert header only.
+ * When clientKeyPem is provided and server URL is https, uses mTLS; otherwise X-Client-Cert header only.
  * @requiresPermission {BuilderServer} Client certificate (X-Client-Cert or mTLS)
  * @param {string} serverUrl - Builder Server base URL
  * @param {string} clientCertPem - PEM-encoded client certificate
  * @param {string} [clientKeyPem] - PEM-encoded client private key (enables mTLS when provided)
+ * @param {string} [serverCaPem] - Dev root CA PEM for server certificate verification
  * @returns {Promise<Object>} SettingsResponseDto
  */
-async function getSettings(serverUrl, clientCertPem, clientKeyPem) {
+async function getSettings(serverUrl, clientCertPem, clientKeyPem, serverCaPem) {
   if (!clientCertPem || typeof clientCertPem !== 'string') {
     throw new Error('Client certificate PEM is required for getSettings');
   }
   const base = normalizeBaseUrl(serverUrl);
   const url = buildUrl(base, '/api/dev/settings');
   const reqOptions = { method: 'GET', headers: { 'X-Client-Cert': encodeCertForHeader(clientCertPem) } };
-  if (clientKeyPem && typeof clientKeyPem === 'string') {
-    return requestWithCertImpl(url, reqOptions, clientCertPem, clientKeyPem);
+  if (shouldUseMtlsForUrl(url, clientKeyPem)) {
+    return requestWithClientCert(url, reqOptions, clientCertPem, clientKeyPem, serverCaPem);
   }
-  return request(url, reqOptions);
+  return request(url, { ...reqOptions, serverCaPem });
 }
 
 /**
@@ -216,13 +180,15 @@ async function getSettings(serverUrl, clientCertPem, clientKeyPem) {
  * @requiresPermission {BuilderServer} Client certificate (X-Client-Cert)
  * @param {string} serverUrl - Builder Server base URL
  * @param {string} clientCertPem - PEM client certificate
+ * @param {string} [serverCaPem] - Dev root CA PEM
  * @returns {Promise<Object[]>} Array of UserResponseDto (empty when none)
  */
-async function listUsers(serverUrl, clientCertPem) {
+async function listUsers(serverUrl, clientCertPem, serverCaPem) {
   const base = normalizeBaseUrl(serverUrl);
   const data = await request(buildUrl(base, '/api/dev/users'), {
     method: 'GET',
-    headers: { 'X-Client-Cert': encodeCertForHeader(clientCertPem) }
+    headers: { 'X-Client-Cert': encodeCertForHeader(clientCertPem) },
+    serverCaPem
   });
   return Array.isArray(data) ? data : [];
 }
@@ -232,15 +198,17 @@ async function listUsers(serverUrl, clientCertPem) {
  * @requiresPermission {BuilderServer} Client certificate (X-Client-Cert)
  * @param {string} serverUrl - Builder Server base URL
  * @param {string} clientCertPem - PEM client certificate
- * @param {Object} body - CreateUserDto: developerId, name, email, optional groups
+ * @param {Object} body - CreateUserDto: developerId, name, email, optional groups (admin | secret-manager | developer | docker)
+ * @param {string} [serverCaPem] - Dev root CA PEM
  * @returns {Promise<Object>} UserResponseDto
  */
-async function createUser(serverUrl, clientCertPem, body) {
+async function createUser(serverUrl, clientCertPem, body, serverCaPem) {
   const base = normalizeBaseUrl(serverUrl);
   return request(buildUrl(base, '/api/dev/users'), {
     method: 'POST',
     headers: { 'X-Client-Cert': encodeCertForHeader(clientCertPem) },
-    body
+    body,
+    serverCaPem
   });
 }
 
@@ -250,15 +218,17 @@ async function createUser(serverUrl, clientCertPem, body) {
  * @param {string} serverUrl - Builder Server base URL
  * @param {string} clientCertPem - PEM client certificate
  * @param {string} id - Developer ID
- * @param {Object} body - UpdateUserDto: at least one of name, email, groups
+ * @param {Object} body - UpdateUserDto: at least one of name, email, groups (same group tokens as create)
+ * @param {string} [serverCaPem] - Dev root CA PEM
  * @returns {Promise<Object>} UserResponseDto
  */
-async function updateUser(serverUrl, clientCertPem, id, body) {
+async function updateUser(serverUrl, clientCertPem, id, body, serverCaPem) {
   const base = normalizeBaseUrl(serverUrl);
   return request(buildUrl(base, `/api/dev/users/${encodeURIComponent(id)}`), {
     method: 'PATCH',
     headers: { 'X-Client-Cert': encodeCertForHeader(clientCertPem) },
-    body
+    body,
+    serverCaPem
   });
 }
 
@@ -268,13 +238,15 @@ async function updateUser(serverUrl, clientCertPem, id, body) {
  * @param {string} serverUrl - Builder Server base URL
  * @param {string} clientCertPem - PEM client certificate
  * @param {string} id - Developer ID
+ * @param {string} [serverCaPem] - Dev root CA PEM
  * @returns {Promise<Object>} DeletedResponseDto
  */
-async function deleteUser(serverUrl, clientCertPem, id) {
+async function deleteUser(serverUrl, clientCertPem, id, serverCaPem) {
   const base = normalizeBaseUrl(serverUrl);
   return request(buildUrl(base, `/api/dev/users/${encodeURIComponent(id)}`), {
     method: 'DELETE',
-    headers: { 'X-Client-Cert': encodeCertForHeader(clientCertPem) }
+    headers: { 'X-Client-Cert': encodeCertForHeader(clientCertPem) },
+    serverCaPem
   });
 }
 
@@ -284,13 +256,15 @@ async function deleteUser(serverUrl, clientCertPem, id) {
  * @param {string} serverUrl - Builder Server base URL
  * @param {string} clientCertPem - PEM client certificate
  * @param {string} id - Developer ID
+ * @param {string} [serverCaPem] - Dev root CA PEM
  * @returns {Promise<Object>} CreatePinResponseDto: pin, expiresAt
  */
-async function createPin(serverUrl, clientCertPem, id) {
+async function createPin(serverUrl, clientCertPem, id, serverCaPem) {
   const base = normalizeBaseUrl(serverUrl);
   return request(buildUrl(base, `/api/dev/users/${encodeURIComponent(id)}/pin`), {
     method: 'POST',
-    headers: { 'X-Client-Cert': encodeCertForHeader(clientCertPem) }
+    headers: { 'X-Client-Cert': encodeCertForHeader(clientCertPem) },
+    serverCaPem
   });
 }
 
@@ -300,29 +274,32 @@ async function createPin(serverUrl, clientCertPem, id) {
  * @param {string} serverUrl - Builder Server base URL
  * @param {string} clientCertPem - PEM client certificate
  * @param {string} id - Developer ID
+ * @param {string} [serverCaPem] - Dev root CA PEM
  * @returns {Promise<Object[]>} Array of SshKeyItemDto
  */
-async function listSshKeys(serverUrl, clientCertPem, id) {
+async function listSshKeys(serverUrl, clientCertPem, id, serverCaPem) {
   const base = normalizeBaseUrl(serverUrl);
   const data = await request(buildUrl(base, `/api/dev/users/${encodeURIComponent(id)}/ssh-keys`), {
     method: 'GET',
-    headers: { 'X-Client-Cert': encodeCertForHeader(clientCertPem) }
+    headers: { 'X-Client-Cert': encodeCertForHeader(clientCertPem) },
+    serverCaPem
   });
   return Array.isArray(data) ? data : [];
 }
 
 /**
  * Add SSH public key for developer. POST /api/dev/users/:id/ssh-keys
- * When clientKeyPem is provided, uses mTLS (TLS client cert); otherwise X-Client-Cert header only.
+ * When clientKeyPem is provided and server URL is https, uses mTLS; otherwise X-Client-Cert header only.
  * @requiresPermission {BuilderServer} Client certificate (X-Client-Cert or mTLS)
  * @param {string} serverUrl - Builder Server base URL
  * @param {string} clientCertPem - PEM client certificate
  * @param {string} id - Developer ID
  * @param {Object} body - AddSshKeyDto: publicKey, optional label
  * @param {string} [clientKeyPem] - PEM-encoded client private key (enables mTLS when provided)
+ * @param {string} [serverCaPem] - Dev root CA PEM
  * @returns {Promise<Object>} SshKeyItemDto
  */
-async function addSshKey(serverUrl, clientCertPem, id, body, clientKeyPem) {
+async function addSshKey(serverUrl, clientCertPem, id, body, clientKeyPem, serverCaPem) {
   const base = normalizeBaseUrl(serverUrl);
   const url = buildUrl(base, `/api/dev/users/${encodeURIComponent(id)}/ssh-keys`);
   const reqOptions = {
@@ -330,10 +307,10 @@ async function addSshKey(serverUrl, clientCertPem, id, body, clientKeyPem) {
     headers: { 'X-Client-Cert': encodeCertForHeader(clientCertPem) },
     body
   };
-  if (clientKeyPem && typeof clientKeyPem === 'string') {
-    return requestWithCertImpl(url, reqOptions, clientCertPem, clientKeyPem);
+  if (shouldUseMtlsForUrl(url, clientKeyPem)) {
+    return requestWithClientCert(url, reqOptions, clientCertPem, clientKeyPem, serverCaPem);
   }
-  return request(url, reqOptions);
+  return request(url, { ...reqOptions, serverCaPem });
 }
 
 /**
@@ -343,62 +320,73 @@ async function addSshKey(serverUrl, clientCertPem, id, body, clientKeyPem) {
  * @param {string} clientCertPem - PEM client certificate
  * @param {string} id - Developer ID
  * @param {string} fingerprint - Key fingerprint
+ * @param {string} [serverCaPem] - Dev root CA PEM
  * @returns {Promise<Object>} DeletedResponseDto
  */
-async function removeSshKey(serverUrl, clientCertPem, id, fingerprint) {
+async function removeSshKey(serverUrl, clientCertPem, id, fingerprint, serverCaPem) {
   const base = normalizeBaseUrl(serverUrl);
   return request(buildUrl(base, `/api/dev/users/${encodeURIComponent(id)}/ssh-keys/${encodeURIComponent(fingerprint)}`), {
     method: 'DELETE',
-    headers: { 'X-Client-Cert': encodeCertForHeader(clientCertPem) }
+    headers: { 'X-Client-Cert': encodeCertForHeader(clientCertPem) },
+    serverCaPem
   });
 }
 
 /**
- * List secrets. GET /api/dev/secrets
+ * List secrets. GET shared-secrets endpoint (default {serverUrl}/api/dev/secrets, or secretsEndpointUrl from config).
  * @requiresPermission {BuilderServer} Client certificate (X-Client-Cert)
  * @param {string} serverUrl - Builder Server base URL
  * @param {string} clientCertPem - PEM client certificate
+ * @param {string} [serverCaPem] - Dev root CA PEM
+ * @param {string} [secretsEndpointUrl] - Optional full or base secrets URL (aifabrix-secrets when https)
  * @returns {Promise<Object[]>} Array of SecretItemDto: name, value
  */
-async function listSecrets(serverUrl, clientCertPem) {
-  const base = normalizeBaseUrl(serverUrl);
-  const data = await request(buildUrl(base, '/api/dev/secrets'), {
+async function listSecrets(serverUrl, clientCertPem, serverCaPem, secretsEndpointUrl) {
+  const endpoint = resolveSecretsEndpoint(serverUrl, secretsEndpointUrl);
+  const data = await request(endpoint, {
     method: 'GET',
-    headers: { 'X-Client-Cert': encodeCertForHeader(clientCertPem) }
+    headers: { 'X-Client-Cert': encodeCertForHeader(clientCertPem) },
+    serverCaPem
   });
   return Array.isArray(data) ? data : [];
 }
 
 /**
- * Add or update secret. POST /api/dev/secrets
+ * Add or update secret. POST shared-secrets endpoint.
  * @requiresPermission {BuilderServer} Client certificate (X-Client-Cert)
  * @param {string} serverUrl - Builder Server base URL
  * @param {string} clientCertPem - PEM client certificate
  * @param {Object} body - AddSecretDto: key, value
+ * @param {string} [serverCaPem] - Dev root CA PEM
+ * @param {string} [secretsEndpointUrl] - Optional secrets URL from config (aifabrix-secrets when https)
  * @returns {Promise<Object>} AddSecretResponseDto
  */
-async function addSecret(serverUrl, clientCertPem, body) {
-  const base = normalizeBaseUrl(serverUrl);
-  return request(buildUrl(base, '/api/dev/secrets'), {
+async function addSecret(serverUrl, clientCertPem, body, serverCaPem, secretsEndpointUrl) {
+  const endpoint = resolveSecretsEndpoint(serverUrl, secretsEndpointUrl);
+  return request(endpoint, {
     method: 'POST',
     headers: { 'X-Client-Cert': encodeCertForHeader(clientCertPem) },
-    body
+    body,
+    serverCaPem
   });
 }
 
 /**
- * Delete secret by key. DELETE /api/dev/secrets/:key
+ * Delete secret by key. DELETE {endpoint}/:key
  * @requiresPermission {BuilderServer} Client certificate (X-Client-Cert)
  * @param {string} serverUrl - Builder Server base URL
  * @param {string} clientCertPem - PEM client certificate
  * @param {string} key - Secret key
+ * @param {string} [serverCaPem] - Dev root CA PEM
+ * @param {string} [secretsEndpointUrl] - Optional secrets URL from config (aifabrix-secrets when https)
  * @returns {Promise<Object>} DeleteSecretResponseDto
  */
-async function deleteSecret(serverUrl, clientCertPem, key) {
-  const base = normalizeBaseUrl(serverUrl);
-  return request(buildUrl(base, `/api/dev/secrets/${encodeURIComponent(key)}`), {
+async function deleteSecret(serverUrl, clientCertPem, key, serverCaPem, secretsEndpointUrl) {
+  const endpoint = resolveSecretsEndpoint(serverUrl, secretsEndpointUrl);
+  return request(buildUrl(endpoint, `/${encodeURIComponent(key)}`), {
     method: 'DELETE',
-    headers: { 'X-Client-Cert': encodeCertForHeader(clientCertPem) }
+    headers: { 'X-Client-Cert': encodeCertForHeader(clientCertPem) },
+    serverCaPem
   });
 }
 
@@ -419,5 +407,6 @@ module.exports = {
   deleteSecret,
   normalizeBaseUrl,
   buildUrl,
-  encodeCertForHeader
+  encodeCertForHeader,
+  resolveSecretsEndpoint
 };

package/lib/api/index.js

@@ -65,7 +65,6 @@ class ApiClient {
         headers['Authorization'] = `Bearer ${this.authConfig.token}`;
       }
     }
-
     return headers;
   }
 

package/lib/api/pipeline.api.js

@@ -5,6 +5,33 @@
  */
 
 const { ApiClient } = require('./index');
+const { postValidationRunAndOptionalPoll } = require('./validation-runner');
+
+/**
+ * @param {Object} opts
+ * @param {'externalSystem'|'externalDataSource'} opts.validationScope
+ * @param {string} opts.systemKey
+ * @param {string} [opts.datasourceKey]
+ * @param {Object} [opts.testData]
+ * @returns {Object}
+ */
+function buildValidationRunPayloadTestBody({ validationScope, systemKey, datasourceKey, testData = {} }) {
+  const body = {
+    validationScope,
+    runType: 'test',
+    systemIdOrKey: systemKey
+  };
+  if (testData.payloadTemplate !== undefined && testData.payloadTemplate !== null) {
+    body.payloadTemplate = testData.payloadTemplate;
+  }
+  if (testData.includeDebug === true) {
+    body.includeDebug = true;
+  }
+  if (validationScope === 'externalDataSource') {
+    body.datasourceKey = datasourceKey;
+  }
+  return body;
+}
 
 /**
  * Validate deployment configuration
@@ -127,8 +154,10 @@ async function validatePipelineConfig(dataplaneUrl, authConfig, { config }) {
 }
 
 /**
- * Test external system (all datasources) via dataplane pipeline endpoint
- * POST /api/v1/pipeline/{systemKey}/test
+ * Test external system (all datasources) via unified validation API
+ * POST /api/v1/validation/run (validationScope=externalSystem, runType=test).
+ * Omits **payloadTemplate** unless `testData.payloadTemplate` is set so the dataplane runs the
+ * validation-engine path (not payload-template-only). Pass `payloadTemplate` explicitly for template tests.
  * @requiresPermission {Dataplane} external-system:publish. Auth: Bearer or x-client-token only.
  * @async
  * @function testSystemViaPipeline
@@ -144,17 +173,27 @@ async function validatePipelineConfig(dataplaneUrl, authConfig, { config }) {
  * @throws {Error} If test fails
  */
 async function testSystemViaPipeline(dataplaneUrl, systemKey, authConfig, testData = {}, options = {}) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
-  const requestOptions = { body: testData };
-  if (options.timeout) {
-    requestOptions.timeout = options.timeout;
-  }
-  return await client.post(`/api/v1/pipeline/${systemKey}/test`, requestOptions);
+  const body = buildValidationRunPayloadTestBody({
+    validationScope: 'externalSystem',
+    systemKey,
+    testData
+  });
+  const timeoutMs = Number.isFinite(options.timeout) ? options.timeout : 30000;
+  const res = await postValidationRunAndOptionalPoll({
+    dataplaneUrl,
+    authConfig,
+    body,
+    timeoutMs,
+    useAsync: true,
+    noAsync: false
+  });
+  if (res.apiError) return res.apiError;
+  return { success: true, data: res.envelope, status: 200 };
 }
 
 /**
- * Test datasource via dataplane pipeline endpoint
- * POST /api/v1/pipeline/{systemKey}/{datasourceKey}/test (Dataplane OpenAPI operationId: testExternalDataSourceViaPipeline)
+ * Test datasource via unified validation API
+ * POST /api/v1/validation/run (validationScope=externalDataSource, datasourceKeys, payloadTemplate)
  * Supports client credentials for CI/CD.
  * @requiresPermission {Dataplane} external-system:publish or external-data-source:read. Auth: Bearer or x-client-token only.
  * @async
@@ -172,15 +211,23 @@ async function testSystemViaPipeline(dataplaneUrl, systemKey, authConfig, testDa
  * @throws {Error} If test fails
  */
 async function testDatasourceViaPipeline({ dataplaneUrl, systemKey, datasourceKey, authConfig, testData, options = {} }) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
-  const requestOptions = {
-    body: testData
-  };
-  // Pass through timeout if provided (will be handled by underlying fetch implementation)
-  if (options.timeout) {
-    requestOptions.timeout = options.timeout;
-  }
-  return await client.post(`/api/v1/pipeline/${systemKey}/${datasourceKey}/test`, requestOptions);
+  const body = buildValidationRunPayloadTestBody({
+    validationScope: 'externalDataSource',
+    systemKey,
+    datasourceKey,
+    testData
+  });
+  const timeoutMs = Number.isFinite(options.timeout) ? options.timeout : 30000;
+  const res = await postValidationRunAndOptionalPoll({
+    dataplaneUrl,
+    authConfig,
+    body,
+    timeoutMs,
+    useAsync: true,
+    noAsync: false
+  });
+  if (res.apiError) return res.apiError;
+  return { success: true, data: res.envelope, status: 200 };
 }
 
 /**
@@ -195,7 +242,7 @@ async function testDatasourceViaPipeline({ dataplaneUrl, systemKey, datasourceKe
  * @param {Object} authConfig - Authentication configuration (must include token for Bearer; client id/secret rejected)
  * @param {Object} payload - { version, application, dataSources }; optional status (default "draft")
  * @param {string} [payload.status="draft"] - "draft" or "published"; Builder uses "draft"
- * @returns {Promise<Object>} Publication result (system, datasources, warnings); no uploadId
+ * @returns {Promise<Object>} API envelope `{ success, data }` where `data` is PublicationResult (uploadId, system, datasources, generateMcpContract, …)
  * @throws {Error} If upload fails
  */
 async function uploadApplicationViaPipeline(dataplaneUrl, authConfig, payload) {

package/lib/api/types/dev.types.js

@@ -27,10 +27,11 @@
  * @typedef {Object} SettingsResponseDto
  * @property {string} user-mutagen-folder - Server path to workspace root (no app segment)
  * @property {string} secrets-encryption - Encryption key (hex)
- * @property {string} aifabrix-secrets - Path or URL for secrets
+ * @property {string} aifabrix-secrets - Local filesystem path or https URL for shared secrets (file vs remote API)
  * @property {string} aifabrix-env-config - Env config path
  * @property {string} remote-server - Builder-server base URL
  * @property {string} docker-endpoint - Docker API endpoint
+ * @property {boolean} [docker-tls-skip-verify] - When true and ca.pem is absent, Docker uses DOCKER_TLS_VERIFY=0; if ca.pem exists, daemon is always verified
  * @property {string} sync-ssh-user - SSH user for Mutagen
  * @property {string} sync-ssh-host - SSH host for Mutagen
  */
@@ -44,7 +45,7 @@
  * @property {string} createdAt - ISO 8601
  * @property {boolean} certificateIssued - Whether cert was issued
  * @property {string} [certificateValidNotAfter] - Cert validity end (optional)
- * @property {string[]} groups - Access groups (admin, secret-manager, developer)
+ * @property {string[]} groups - Access groups (admin, secret-manager, developer, docker)
  */
 
 /**
@@ -53,7 +54,7 @@
  * @property {string} developerId - Unique developer ID (numeric string)
  * @property {string} name - Display name
  * @property {string} email - Email
- * @property {string[]} [groups] - Default [developer]
+ * @property {string[]} [groups] - Default [developer]; tokens: admin, secret-manager, developer, docker
  */
 
 /**