@aifabrix/builder 2.49.2 → 2.50.0

package/lib/programmatic/builder-api-route-dispatch.js

@@ -0,0 +1,82 @@
+/**
+ * Capability route execution for builder-api HTTP server.
+ *
+ * @fileoverview Keeps handleRequest under max-lines-per-function
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { executeCapabilityRequest } = require('./builder-api-request');
+
+/**
+ * @typedef {Object} DispatchCapabilityRouteOptions
+ * @property {import('http').IncomingMessage} req
+ * @property {import('http').ServerResponse} res
+ * @property {Function} sendJson
+ * @property {Function} sendProblem
+ * @property {Function} readJsonBody
+ * @property {Object} resolved
+ * @property {Object} query
+ * @property {string} requestId
+ * @property {string} pathname
+ * @property {Function} logRequestOutcome
+ */
+
+/**
+ * @param {DispatchCapabilityRouteOptions} options
+ */
+async function dispatchCapabilityRoute(options) {
+  const {
+    req,
+    res,
+    sendJson,
+    sendProblem,
+    readJsonBody,
+    resolved,
+    query,
+    requestId,
+    pathname,
+    logRequestOutcome
+  } = options;
+  try {
+    const outcome = await executeCapabilityRequest({
+      req,
+      capability: resolved.capability,
+      params: resolved.params,
+      routeKey: resolved.routeKey,
+      requestId,
+      readJsonBody,
+      query
+    });
+    sendJson(res, outcome.httpStatus, outcome.body, outcome.requestId);
+    logRequestOutcome({
+      requestId: outcome.requestId,
+      correlationId: outcome.body.correlationId,
+      route: resolved.routeKey,
+      method: req.method,
+      status: outcome.httpStatus,
+      systemKey: resolved.params.systemKey,
+      userId: outcome.userId
+    });
+  } catch (err) {
+    const status = err.statusCode || 500;
+    if (status === 409 && err.retryAfter) {
+      res.setHeader('Retry-After', String(err.retryAfter));
+    }
+    sendProblem(req, res, err, status, requestId, pathname);
+    logRequestOutcome({
+      requestId,
+      route: resolved.routeKey,
+      method: req.method,
+      status,
+      systemKey: resolved.params.systemKey,
+      error: err.message
+    });
+  }
+}
+
+module.exports = {
+  dispatchCapabilityRoute
+};

package/lib/programmatic/builder-api-runtime-config.js

@@ -0,0 +1,42 @@
+/**
+ * Docker dev-reload runtime config layout for builder-api.
+ *
+ * @fileoverview Ensures AIFABRIX_CONFIG parent directory exists before kv:// resolution
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const fs = require('../internal/fs-real-sync');
+const path = require('path');
+
+/**
+ * Create the directory containing `AIFABRIX_CONFIG` when set (dev-reload bind mount).
+ * Does not write config or secrets — operators link or copy `config.yaml` and `secrets.local.yaml`
+ * under that directory (gitignored under repo `.aifabrix/` or persistent `mount/aifabrix/`).
+ */
+function ensureBuilderApiRuntimeConfigDir() {
+  const raw = process.env.AIFABRIX_CONFIG;
+  if (!raw || typeof raw !== 'string' || !raw.trim()) {
+    return;
+  }
+  const configPath = path.resolve(raw.trim());
+  const dir = path.dirname(configPath);
+  if (fs.existsSync(dir)) {
+    return;
+  }
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+  } catch (err) {
+    // Named Docker volumes are often root-owned when compose runs without bind mount + UID mapping.
+    if (err && (err.code === 'EACCES' || err.code === 'EPERM')) {
+      return;
+    }
+    throw err;
+  }
+}
+
+module.exports = {
+  ensureBuilderApiRuntimeConfigDir
+};

package/lib/programmatic/builder-api-server.js

@@ -0,0 +1,230 @@
+/**
+ * Builder API HTTP server (plan 154.0 — pre-Nest unified router).
+ *
+ * @fileoverview Full V1 route set via capability registry
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const http = require('http');
+const { URL } = require('url');
+const { randomUUID } = require('crypto');
+const { CAPABILITIES, getCapabilityByHandlerId } = require('./capability-registry');
+const { BASE, matchRoutePattern } = require('./http-route-match');
+const { buildOpenApiSpec } = require('./openapi-spec');
+const { writeAccessLog } = require('./access-log');
+const { dispatchCapabilityRoute } = require('./builder-api-route-dispatch');
+const { renderBuilderApiRedocHtml, resolvePublicBaseUrl } = require('./openapi-docs-serving');
+const { buildProblemDetails, writeProblemDetails } = require('./http-problem-details');
+
+/**
+ * @param {import('http').ServerResponse} res
+ * @param {number} status
+ * @param {Object} body
+ * @param {string} [requestId]
+ */
+function sendJson(res, status, body, requestId) {
+  const payload =
+    body && typeof body.openapi === 'string'
+      ? body
+      : { ...body, requestId: requestId || body.requestId };
+  res.writeHead(status, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify(payload));
+}
+
+/**
+ * @param {import('http').IncomingMessage} req
+ * @param {import('http').ServerResponse} res
+ * @param {unknown} error
+ * @param {number} status
+ * @param {string} requestId
+ * @param {string} pathname
+ */
+function sendProblem(req, res, error, status, requestId, pathname) {
+  const body = buildProblemDetails(error, status, req, requestId, pathname);
+  writeProblemDetails(res, status, body);
+}
+
+/**
+ * @param {import('http').IncomingMessage} req
+ * @returns {Promise<Object>}
+ */
+function readJsonBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let size = 0;
+    const max = Number(process.env.MAX_BODY_BYTES || 10 * 1024 * 1024);
+    req.on('data', (chunk) => {
+      size += chunk.length;
+      if (size > max) {
+        reject(Object.assign(new Error('Request body too large'), { statusCode: 413 }));
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on('end', () => {
+      if (chunks.length === 0) {
+        resolve({});
+        return;
+      }
+      try {
+        resolve(JSON.parse(Buffer.concat(chunks).toString('utf8')));
+      } catch {
+        reject(Object.assign(new Error('Invalid JSON body'), { statusCode: 400 }));
+      }
+    });
+    req.on('error', reject);
+  });
+}
+
+/**
+ * @param {string} method
+ * @param {string} pathname
+ * @returns {{ capability: Object, params: Object, routeKey: string }|null}
+ */
+function resolveCapabilityRoute(method, pathname) {
+  for (const capability of CAPABILITIES) {
+    if (capability.method !== method) {
+      continue;
+    }
+    const params = matchRoutePattern(capability.route, pathname);
+    if (params) {
+      return { capability, params, routeKey: `${method} ${capability.route}` };
+    }
+  }
+  return null;
+}
+
+/**
+ * @param {import('http').ServerResponse} res
+ * @param {number} status
+ * @param {string} html
+ * @param {string} [requestId]
+ */
+function sendHtml(res, status, html, requestId) {
+  const headers = {
+    'Content-Type': 'text/html; charset=utf-8',
+    'Cache-Control': 'public, max-age=60'
+  };
+  if (requestId) {
+    headers['X-Request-Id'] = requestId;
+  }
+  res.writeHead(status, headers);
+  res.end(html);
+}
+
+/**
+ * @param {string} pathname
+ * @returns {boolean}
+ */
+function isRedocHtmlPath(pathname) {
+  return pathname === '/api/docs' || pathname === `${BASE}/api-docs`;
+}
+
+/**
+ * @param {string} pathname
+ * @returns {boolean}
+ */
+function isOpenApiJsonPath(pathname) {
+  return pathname === `${BASE}/api-docs/openapi.json`;
+}
+
+/**
+ * @param {import('http').IncomingMessage} req
+ * @param {import('http').ServerResponse} res
+ * @param {string} pathname
+ * @param {string} requestId
+ */
+function handleOpenApiDocs(req, res, pathname, requestId) {
+  if (req.method !== 'GET') {
+    sendProblem(req, res, 'Method not allowed', 405, requestId, pathname);
+    return;
+  }
+  if (isOpenApiJsonPath(pathname)) {
+    const publicBaseUrl = resolvePublicBaseUrl(req);
+    sendJson(res, 200, buildOpenApiSpec({ publicBaseUrl }), requestId);
+    return;
+  }
+  if (isRedocHtmlPath(pathname)) {
+    sendHtml(res, 200, renderBuilderApiRedocHtml(req), requestId);
+  }
+}
+
+/**
+ * @param {Object} entry
+ */
+function logRequestOutcome(entry) {
+  if (process.env.BUILDER_API_ACCESS_LOG === '0') {
+    return;
+  }
+  writeAccessLog(entry);
+}
+
+/**
+ * @param {import('http').IncomingMessage} req
+ * @param {import('http').ServerResponse} res
+ */
+async function handleRequest(req, res) {
+  const requestId = req.headers['x-request-id'] || randomUUID();
+  const url = new URL(req.url || '/', `http://${req.headers.host || 'localhost'}`);
+  const pathname = url.pathname;
+
+  if (isRedocHtmlPath(pathname) || isOpenApiJsonPath(pathname)) {
+    handleOpenApiDocs(req, res, pathname, requestId);
+    logRequestOutcome({
+      requestId,
+      route: pathname,
+      method: req.method,
+      status: 200,
+      userId: 'anonymous'
+    });
+    return;
+  }
+
+  const resolved = resolveCapabilityRoute(req.method || 'GET', pathname);
+  if (!resolved || !getCapabilityByHandlerId(resolved.capability.handlerId)) {
+    sendProblem(req, res, 'Not found', 404, requestId, pathname);
+    logRequestOutcome({ requestId, route: pathname, method: req.method, status: 404, userId: 'anonymous' });
+    return;
+  }
+
+  const query = Object.fromEntries(url.searchParams.entries());
+  await dispatchCapabilityRoute({
+    req,
+    res,
+    sendJson,
+    sendProblem,
+    readJsonBody,
+    resolved,
+    query,
+    requestId,
+    pathname,
+    logRequestOutcome
+  });
+}
+
+/**
+ * @param {number} [port]
+ * @returns {import('http').Server}
+ */
+function createBuilderApiServer(port = Number(process.env.PORT || 3005)) {
+  const server = http.createServer((req, res) => {
+    handleRequest(req, res).catch((err) => {
+      const requestId = req.headers['x-request-id'] || randomUUID();
+      const pathname = String(req.url || '/').split('?')[0];
+      sendProblem(req, res, err, err.statusCode || 500, requestId, pathname);
+    });
+  });
+  server.listen(port);
+  return server;
+}
+
+module.exports = {
+  createBuilderApiServer,
+  handleRequest,
+  sendJson,
+  sendProblem,
+  BASE
+};

package/lib/programmatic/builder-help-authentication-catalog.js

@@ -0,0 +1,282 @@
+/**
+ * Authentication catalog for builder-api LLM help (external-system.schema.json).
+ *
+ * @fileoverview authType modes and credential.method templates for UI handoff guidance
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const SCHEMA_DIR = path.join(__dirname, '..', 'schema');
+const SYSTEM_SCHEMA_PATH = path.join(SCHEMA_DIR, 'external-system.schema.json');
+const CREDENTIAL_REGISTRY_PATH = path.join(SCHEMA_DIR, 'type', 'credential-field-registry.json');
+
+/** @type {Object|null} */
+let cachedCatalog = null;
+
+/** @type {Readonly<Record<string, string>>} */
+const METHOD_UI_LABELS = Object.freeze({
+  oauth2: 'OAuth 2.0',
+  aad: 'Azure AD (aad)',
+  apikey: 'API Key',
+  bearerToken: 'Bearer token',
+  basic: 'Basic Auth',
+  queryParam: 'Query parameter',
+  oidc: 'OpenID Connect (OIDC)',
+  hmac: 'HMAC',
+  none: 'None'
+});
+
+/** @type {Readonly<Record<string, string>>} */
+const METHOD_REGISTRY_KEY = Object.freeze({
+  oauth2: 'oauth2',
+  aad: 'oauth2',
+  apikey: 'apiKey',
+  bearerToken: 'bearerToken',
+  basic: 'basicAuth',
+  queryParam: 'queryParam',
+  oidc: 'oidc',
+  hmac: 'hmac',
+  none: 'none'
+});
+
+/** @type {Readonly<Object>} */
+const MANIFEST_AUTH_SPLIT = Object.freeze({
+  variables: {
+    manifestPath: 'authentication.credential.variables',
+    purpose:
+      'Non-secret configuration (baseUrl, tokenUrl, headerName, prefix, testEndpoint, and similar). Set in the manifest authentication section before upload.',
+    publishedBehavior:
+      'Upload publishes variables to dataplane. They appear pre-filled in Connected Systems Authentication — the user does not re-enter them.',
+    agentRule:
+      'Ensure variables are complete in the manifest during editing. After upload, do not ask the user to supply non-secret variable values again.'
+  },
+  security: {
+    manifestPath: 'authentication.credential.security',
+    purpose:
+      'Secret placeholders only. Manifest values must be kv:// references (unresolved in Builder API scope).',
+    publishedBehavior:
+      'Upload creates the credential template. The user adds live secret values in Authentication UI — typically only the token or apiKey.',
+    agentRule:
+      'After upload, ask the user only for requiredSecretKeys. This is the minimum post-upload handoff.'
+  }
+});
+
+/** @type {Readonly<Record<string, string>>} */
+const METHOD_USER_HANDOFF = Object.freeze({
+  oauth2:
+    'User adds clientSecret (and clientId if empty). baseUrl, tokenUrl, grantType, and scope are already published from manifest variables.',
+  aad:
+    'User adds clientSecret (and clientId if empty). baseUrl, tokenUrl, tenantId, and grantType are already published from manifest variables.',
+  apikey:
+    'User adds only the API key token. baseUrl, headerName, prefix, and testEndpoint are already published from manifest variables.',
+  bearerToken:
+    'User adds only the bearer token. baseUrl, headerName, prefix, and testEndpoint are already published from manifest variables.',
+  basic:
+    'User adds username and password. baseUrl and testEndpoint are already published from manifest variables.',
+  queryParam:
+    'User adds only the paramValue secret. baseUrl, paramName, and testEndpoint are already published from manifest variables.',
+  oidc:
+    'openIdConfigUrl and clientId are already published from manifest variables. User confirms or completes any remaining OIDC fields shown in UI.',
+  hmac:
+    'User adds signingSecret. Algorithm and signature header settings are already published from manifest variables.',
+  none: 'No credential secrets required for this method.'
+});
+
+/** @type {ReadonlyArray<Object>} */
+const AUTH_TYPES = Object.freeze([
+  {
+    authType: 'credential',
+    manifestPath: 'authentication.credential',
+    uiTab: 'authentication',
+    description:
+      'Local credential template from external-system.schema.json. Non-secret variables are published on upload; user adds live secrets in Authentication UI only.',
+    userAction:
+      'Open Authentication tab. Non-secret fields are already pre-filled from manifest variables. User adds only the required secret values (for example apiKey token, clientSecret).',
+    builderApiScope:
+      'Set authentication.credential.variables in the manifest before upload. Keep kv:// placeholders in security; upload does not resolve secrets. User replaces placeholders with live values in the UI.'
+  },
+  {
+    authType: 'apiProvider',
+    manifestPath: 'authentication.apiProvider.apiProviderKey',
+    uiTab: 'authentication',
+    description:
+      'Delegated authentication via a Miso API Provider — no dataplane-local vendor secrets.',
+    userAction:
+      'Open Authentication tab and link or select the API Provider referenced by apiProviderKey in the manifest.',
+    builderApiScope:
+      'Upload publishes the apiProviderKey reference only. User completes provider binding in the UI.'
+  },
+  {
+    authType: 'none',
+    manifestPath: 'authentication.authType',
+    uiTab: null,
+    description: 'No authentication block secrets. System does not use a local credential template.',
+    userAction:
+      'Skip credential entry unless the integration still needs network-level auth configured elsewhere.',
+    builderApiScope: 'No post-upload secret handoff for authType none unless live tests fail for other reasons.'
+  }
+]);
+
+/**
+ * @returns {Object}
+ */
+function loadSystemSchema() {
+  return JSON.parse(fs.readFileSync(SYSTEM_SCHEMA_PATH, 'utf8'));
+}
+
+/**
+ * @returns {Object}
+ */
+function loadCredentialRegistry() {
+  return JSON.parse(fs.readFileSync(CREDENTIAL_REGISTRY_PATH, 'utf8'));
+}
+
+/**
+ * @param {string|null|undefined} text
+ * @returns {string|null}
+ */
+function sanitizeHelpText(text) {
+  if (!text) {
+    return null;
+  }
+  const cleaned = String(text)
+    .replace(/https?:\/\/[^\s)]+/gi, '')
+    .replace(/\s{2,}/g, ' ')
+    .trim();
+  return cleaned || null;
+}
+
+/**
+ * @param {string} method
+ * @param {Object} registry
+ * @returns {string}
+ */
+function resolveUiLabel(method, registry) {
+  if (METHOD_UI_LABELS[method]) {
+    return METHOD_UI_LABELS[method];
+  }
+  const registryKey = METHOD_REGISTRY_KEY[method];
+  const entry = registryKey ? registry.credentialTypes?.[registryKey] : null;
+  if (entry?.display?.label) {
+    return entry.display.label;
+  }
+  return method;
+}
+
+/**
+ * @param {string} method
+ * @param {Object} methodDef
+ * @returns {Object}
+ */
+function summarizeMethodFields(method, methodDef) {
+  const variables = (methodDef.variables || []).map((item) => ({
+    key: item.key,
+    required: item.required === true,
+    description: sanitizeHelpText(item.description)
+  }));
+  const security = (methodDef.security || []).map((item) => ({
+    key: item.key,
+    required: item.required === true,
+    encrypted: true
+  }));
+  return {
+    method,
+    uiLabel: METHOD_UI_LABELS[method] || method,
+    variableKeys: variables.map((item) => item.key),
+    requiredVariableKeys: variables.filter((item) => item.required).map((item) => item.key),
+    secretKeys: security.map((item) => item.key),
+    requiredSecretKeys: security.filter((item) => item.required).map((item) => item.key),
+    variables,
+    security,
+    userHandoff: METHOD_USER_HANDOFF[method] || 'User completes secret fields shown for this method in Authentication.',
+    manifestPath: 'authentication.credential.method',
+    schemaDefKey: 'authenticationVariablesByMethod'
+  };
+}
+
+/**
+ * @returns {Object}
+ */
+function buildAuthenticationCatalog() {
+  if (cachedCatalog) {
+    return cachedCatalog;
+  }
+  const schema = loadSystemSchema();
+  const registry = loadCredentialRegistry();
+  const methodsByDef = schema.$defs?.authenticationVariablesByMethod || {};
+  const methodEnum =
+    schema.$defs?.credentialTemplate?.properties?.method?.enum ||
+    Object.keys(methodsByDef).sort();
+
+  const credentialMethods = methodEnum
+    .filter((method) => methodsByDef[method])
+    .map((method) => {
+      const summary = summarizeMethodFields(method, methodsByDef[method]);
+      summary.uiLabel = resolveUiLabel(method, registry);
+      return summary;
+    });
+
+  cachedCatalog = {
+    schemaSource: 'external-system.schema.json',
+    manifestSectionKey: 'system.authentication',
+    datasourceNote:
+      'Authentication is declared on the external system manifest (system.authentication), not on individual datasource manifests. Datasources inherit the linked system credential during sync and CIP execution.',
+    manifestAuthSplit: MANIFEST_AUTH_SPLIT,
+    authTypes: AUTH_TYPES,
+    credentialMethods,
+    agentHandoffSteps: [
+      'Read workspace section system.authentication (or the published system manifest) before prompting the user.',
+      'Identify authentication.authType: credential, apiProvider, or none.',
+      'When authType is credential, ensure authentication.credential.variables holds all non-secret config before upload (baseUrl, headerName, tokenUrl, and similar).',
+      'Upload publishes variables pre-filled in Authentication UI. Ask the user only for requiredSecretKeys — not for variables already in the manifest.',
+      'When authType is apiProvider, direct the user to link apiProviderKey in Authentication — do not ask for vendor API keys in Builder API scope.',
+      'When authType is none, skip secret handoff unless E2E still fails for unrelated configuration.',
+      'Provide the Connected Systems Authentication URL using connectedSystemUi urlTemplates plus the published systemKey.'
+    ]
+  };
+  return cachedCatalog;
+}
+
+/**
+ * @param {Object} query
+ * @returns {Object|null}
+ */
+function buildAuthenticationHandoffForManifest(query) {
+  const authType = query.authType ? String(query.authType) : null;
+  const method = query.credentialMethod ? String(query.credentialMethod) : null;
+  if (!authType && !method) {
+    return null;
+  }
+  const catalog = buildAuthenticationCatalog();
+  const authTypeEntry = authType ? catalog.authTypes.find((entry) => entry.authType === authType) : null;
+  const methodEntry = method
+    ? catalog.credentialMethods.find((entry) => entry.method === method)
+    : null;
+  if (!authTypeEntry && !methodEntry) {
+    return null;
+  }
+  return {
+    authType: authTypeEntry || null,
+    credentialMethod: methodEntry || null,
+    promptHints: [
+      authTypeEntry ? authTypeEntry.userAction : null,
+      'Non-secret authentication.credential.variables are already published and pre-filled in the UI.',
+      methodEntry ? methodEntry.userHandoff : null,
+      methodEntry && methodEntry.requiredSecretKeys.length
+        ? `User adds only these secret fields: ${methodEntry.requiredSecretKeys.join(', ')}`
+        : null
+    ].filter(Boolean)
+  };
+}
+
+module.exports = {
+  AUTH_TYPES,
+  METHOD_UI_LABELS,
+  buildAuthenticationCatalog,
+  buildAuthenticationHandoffForManifest
+};