@aifabrix/builder 2.53.1 → 2.55.0

package/lib/channels/mcp-client/config-merge.js

@@ -0,0 +1,148 @@
+/**
+ * Structural merge / remove for editor MCP config files.
+ *
+ * @fileoverview Preserve unrelated servers; never log secrets
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * @param {string} filePath
+ * @returns {string}
+ */
+function backupPath(filePath) {
+  return `${filePath}.bak`;
+}
+
+/**
+ * @param {string} filePath
+ * @param {string} contents
+ * @returns {void}
+ */
+function writeBackup(filePath, contents) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(backupPath(filePath), contents, 'utf8');
+}
+
+/**
+ * @param {string} filePath
+ * @param {Object} [deps]
+ * @returns {{ config: Object, recovered: boolean, existed: boolean, raw: string }}
+ */
+function readMcpConfig(filePath, deps = {}) {
+  const readFile = deps.readFileSync || ((p) => fs.readFileSync(p, 'utf8'));
+  const exists = deps.existsSync || ((p) => fs.existsSync(p));
+  if (!exists(filePath)) {
+    return { config: {}, recovered: false, existed: false, raw: '' };
+  }
+  const raw = readFile(filePath);
+  if (!raw || !String(raw).trim()) {
+    return { config: {}, recovered: false, existed: true, raw };
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+      return { config: parsed, recovered: false, existed: true, raw };
+    }
+  } catch {
+    writeBackup(`${filePath}.invalid`, raw);
+  }
+  return { config: {}, recovered: true, existed: true, raw };
+}
+
+/**
+ * @param {Object} config
+ * @param {Object} profile
+ * @param {Object} entry
+ * @returns {Object}
+ */
+function mergeServerEntry(config, profile, entry) {
+  const serversKey = profile.config.serversKey;
+  const serverKey = profile.config.serverKey;
+  const next = { ...config };
+  const servers = { ...(next[serversKey] && typeof next[serversKey] === 'object' ? next[serversKey] : {}) };
+  const previous = servers[serverKey] && typeof servers[serverKey] === 'object' ? servers[serverKey] : {};
+  servers[serverKey] = { ...previous, ...entry };
+  next[serversKey] = servers;
+  return next;
+}
+
+/**
+ * @param {Object} config
+ * @param {Object} profile
+ * @returns {Object}
+ */
+function removeServerEntry(config, profile) {
+  const serversKey = profile.config.serversKey;
+  const serverKey = profile.config.serverKey;
+  const next = { ...config };
+  const servers = { ...(next[serversKey] && typeof next[serversKey] === 'object' ? next[serversKey] : {}) };
+  delete servers[serverKey];
+  if (Object.keys(servers).length === 0) {
+    delete next[serversKey];
+  } else {
+    next[serversKey] = servers;
+  }
+  return next;
+}
+
+/**
+ * @param {string} filePath
+ * @param {Object} config
+ * @param {Object} [deps]
+ * @returns {void}
+ */
+function writeMcpConfig(filePath, config, deps = {}) {
+  const writeFile = deps.writeFileSync || ((p, contents) => fs.writeFileSync(p, contents, 'utf8'));
+  const mkdir = deps.mkdirSync || ((p, opts) => fs.mkdirSync(p, opts));
+  mkdir(path.dirname(filePath), { recursive: true });
+  writeFile(filePath, `${JSON.stringify(config, null, 2)}\n`);
+}
+
+/**
+ * @param {Object} params
+ * @returns {{ filePath: string, config: Object, recovered: boolean }}
+ */
+function mergeMcpClientConfig(params) {
+  const { profile, filePath, entry, deps = {} } = params;
+  const read = readMcpConfig(filePath, deps);
+  if (read.existed && read.raw) {
+    writeBackup(filePath, read.raw);
+  }
+  const config = mergeServerEntry(read.config, profile, entry);
+  writeMcpConfig(filePath, config, deps);
+  return { filePath, config, recovered: read.recovered };
+}
+
+/**
+ * Remove only the AI Fabrix server key.
+ * @param {Object} params
+ * @returns {{ filePath: string, config: Object, removed: boolean }}
+ */
+function removeMcpClientConfig(params) {
+  const { profile, filePath, deps = {} } = params;
+  const read = readMcpConfig(filePath, deps);
+  const servers = read.config[profile.config.serversKey] || {};
+  const removed = Boolean(servers[profile.config.serverKey]);
+  if (!removed) {
+    return { filePath, config: read.config, removed: false };
+  }
+  if (read.existed && read.raw) {
+    writeBackup(filePath, read.raw);
+  }
+  const config = removeServerEntry(read.config, profile);
+  writeMcpConfig(filePath, config, deps);
+  return { filePath, config, removed: true };
+}
+
+module.exports = {
+  backupPath,
+  readMcpConfig,
+  mergeServerEntry,
+  removeServerEntry,
+  mergeMcpClientConfig,
+  removeMcpClientConfig
+};

package/lib/channels/mcp-client/ensure-client.js

@@ -0,0 +1,231 @@
+/**
+ * Ensure the per-installation Integration Client for an MCP client profile.
+ *
+ * Create when missing; merge redirect URIs; never rotate the secret.
+ *
+ * @fileoverview Reuse existing Integration Client APIs only
+ */
+
+'use strict';
+
+const {
+  createIntegrationClient,
+  listIntegrationClients,
+  getIntegrationClient,
+  updateIntegrationClientRedirectUris
+} = require('../../api/integration-clients.api');
+const {
+  unwrapIntegrationClientList
+} = require('../chatgpt-callback');
+const {
+  normalizeMcpClientRedirectUris,
+  mergeRedirectUriList
+} = require('./redirect-uris');
+
+/**
+ * @param {string} message
+ * @param {string} [boundary]
+ * @returns {Error}
+ */
+function createMcpClientEnsureError(message, boundary) {
+  const error = new Error(message);
+  error.boundary = boundary || 'oauth';
+  return error;
+}
+
+/**
+ * @param {Object} response
+ * @returns {Object}
+ */
+function unwrapRecord(response) {
+  const body = response && response.data !== undefined ? response.data : response || {};
+  const inner = body.data !== undefined && body.data !== null ? body.data : body;
+  return inner.integrationClient || inner;
+}
+
+/**
+ * @param {Error|Object} errorOrResponse
+ * @returns {boolean}
+ */
+function isForbidden(errorOrResponse) {
+  const status = errorOrResponse && errorOrResponse.status;
+  if (status === 403) {
+    return true;
+  }
+  const message = errorOrResponse && errorOrResponse.message
+    ? String(errorOrResponse.message)
+    : '';
+  return /\b403\b/.test(message) || /forbidden|not allowed|integration-client:/i.test(message);
+}
+
+/**
+ * @param {Error|Object} errorOrResponse
+ * @returns {boolean}
+ */
+function isLoopbackRejected(errorOrResponse) {
+  const status = errorOrResponse && errorOrResponse.status;
+  const message = errorOrResponse && errorOrResponse.message
+    ? String(errorOrResponse.message)
+    : String(errorOrResponse || '');
+  if (status !== 400 && !/\b400\b/.test(message)) {
+    return false;
+  }
+  return /localhost|127\.0\.0\.1|loopback|http:\/\//i.test(message);
+}
+
+/**
+ * @param {Object} ctx
+ * @param {string} key
+ * @param {Object} deps
+ * @returns {Promise<Object|null>}
+ */
+async function findClientByKey(ctx, key, deps) {
+  const listFn = deps.listIntegrationClients || listIntegrationClients;
+  const response = await listFn(ctx.controllerUrl, ctx.authConfig, { pageSize: 100 });
+  if (response && response.success === false) {
+    if (response.status === 403 || isForbidden(response)) {
+      throw createMcpClientEnsureError(
+        'Missing integration-client:read. Cannot list Integration Clients.',
+        'permissions'
+      );
+    }
+    throw createMcpClientEnsureError(
+      response.formattedError || response.error || 'Failed to list integration clients.'
+    );
+  }
+  return unwrapIntegrationClientList(response).find((row) => row && row.key === key) || null;
+}
+
+/**
+ * @param {Object} ctx
+ * @param {Object} match
+ * @param {Object} deps
+ * @returns {Promise<Object>}
+ */
+async function loadClientDetail(ctx, match, deps) {
+  const getFn = deps.getIntegrationClient || getIntegrationClient;
+  const detail = await getFn(ctx.controllerUrl, ctx.authConfig, match.id);
+  const record = unwrapRecord(detail);
+  return { ...match, ...record, id: match.id };
+}
+
+/**
+ * @param {Object} params
+ * @returns {Object}
+ */
+function createClientBody(params) {
+  const { profile, redirectUris } = params;
+  return {
+    key: profile.oauth.integrationClientKey,
+    displayName: profile.displayName,
+    redirectUris,
+    keycloakClientId: profile.oauth.keycloakClientId,
+    description: `Developer MCP client (${profile.key})`
+  };
+}
+
+/**
+ * @param {Object} response
+ * @returns {string|undefined}
+ */
+function oneTimeSecret(response) {
+  const record = unwrapRecord(response);
+  const secret = record && record.clientSecret;
+  return typeof secret === 'string' && secret.trim() ? secret : undefined;
+}
+
+/**
+ * @param {Object} ctx
+ * @param {Object} profile
+ * @param {string[]} redirectUris
+ * @param {Object} deps
+ * @returns {Promise<{ client: Object, created: boolean, clientSecret?: string }>}
+ */
+async function createClient(ctx, profile, redirectUris, deps) {
+  const createFn = deps.createIntegrationClient || createIntegrationClient;
+  try {
+    const response = await createFn(ctx.controllerUrl, ctx.authConfig, createClientBody({
+      profile,
+      redirectUris
+    }));
+    if (response && response.success === false) {
+      throw Object.assign(new Error(response.formattedError || response.error || 'Create failed'), {
+        status: response.status
+      });
+    }
+    const record = unwrapRecord(response);
+    return { client: record, created: true, clientSecret: oneTimeSecret(response) };
+  } catch (error) {
+    if (isForbidden(error)) {
+      throw createMcpClientEnsureError(
+        'Missing integration-client:create. Cannot provision the MCP client.',
+        'permissions'
+      );
+    }
+    if (isLoopbackRejected(error)) {
+      throw createMcpClientEnsureError(
+        'Keycloak rejected a loopback HTTP redirect URI. Do not fall back to API keys.',
+        'oauth'
+      );
+    }
+    throw error;
+  }
+}
+
+/**
+ * @param {Object} params
+ * @returns {Promise<{ ok: boolean, added: boolean }>}
+ */
+async function mergeRedirects(params) {
+  const { ctx, client, redirectUris, deps } = params;
+  const updateFn = deps.updateIntegrationClientRedirectUris || updateIntegrationClientRedirectUris;
+  const merged = mergeRedirectUriList(client.redirectUris, redirectUris);
+  try {
+    const response = await updateFn(ctx.controllerUrl, ctx.authConfig, client.id, {
+      redirectUris: merged.uris
+    });
+    if (response && response.success === false) {
+      throw Object.assign(new Error(response.formattedError || response.error || 'Update failed'), {
+        status: response.status
+      });
+    }
+  } catch (error) {
+    if (isForbidden(error)) {
+      throw createMcpClientEnsureError(
+        'Missing integration-client:update. Cannot merge redirect URIs.',
+        'permissions'
+      );
+    }
+    if (isLoopbackRejected(error)) {
+      throw createMcpClientEnsureError(
+        'Keycloak rejected a loopback HTTP redirect URI. Do not fall back to API keys.',
+        'oauth'
+      );
+    }
+    throw error;
+  }
+  return { ok: true, added: merged.added, redirectUris: merged.uris };
+}
+
+/**
+ * Create or reuse the Integration Client. Never calls regenerate-secret.
+ * @param {Object} params
+ * @returns {Promise<{ client: Object, created: boolean, added: boolean, clientSecret?: string }>}
+ */
+async function ensureMcpClientIntegrationClient(params) {
+  const { ctx, profile, deps = {} } = params;
+  const redirectUris = normalizeMcpClientRedirectUris(profile.oauth.redirectUris);
+  const match = await findClientByKey(ctx, profile.oauth.integrationClientKey, deps);
+  if (!match || !match.id) {
+    const created = await createClient(ctx, profile, redirectUris, deps);
+    return { ...created, added: true };
+  }
+  const client = await loadClientDetail(ctx, match, deps);
+  const merged = await mergeRedirects({ ctx, client, redirectUris, deps });
+  return { client: { ...client, redirectUris: merged.redirectUris }, created: false, added: merged.added };
+}
+
+module.exports = {
+  ensureMcpClientIntegrationClient,
+  createMcpClientEnsureError
+};

package/lib/channels/mcp-client/paths.js

@@ -0,0 +1,53 @@
+/**
+ * Resolve editor MCP config paths for installation profiles.
+ *
+ * @fileoverview User vs project mcp.json locations
+ */
+
+'use strict';
+
+const os = require('os');
+const path = require('path');
+
+/**
+ * @param {Object} [deps]
+ * @returns {string}
+ */
+function vscodeUserMcpPath(deps = {}) {
+  const homedir = (deps.homedir || os.homedir)();
+  const env = deps.env || process.env;
+  const platform = deps.platform || process.platform;
+  if (platform === 'darwin') {
+    return path.join(homedir, 'Library', 'Application Support', 'Code', 'User', 'mcp.json');
+  }
+  if (platform === 'win32') {
+    const appData = env.APPDATA || path.join(homedir, 'AppData', 'Roaming');
+    return path.join(appData, 'Code', 'User', 'mcp.json');
+  }
+  const xdg = env.XDG_CONFIG_HOME || path.join(homedir, '.config');
+  return path.join(xdg, 'Code', 'User', 'mcp.json');
+}
+
+/**
+ * @param {Object} profile
+ * @param {Object} [deps]
+ * @returns {string}
+ */
+function resolveMcpConfigPath(profile, deps = {}) {
+  const homedir = deps.homedir || os.homedir;
+  const cwd = deps.cwd || process.cwd;
+  const relative = profile.config.relativePath;
+  if (profile.config.scope === 'project') {
+    return path.join(cwd(), relative);
+  }
+  const key = profile.key;
+  if (key === 'vscode' || key === 'github-copilot') {
+    return vscodeUserMcpPath(deps);
+  }
+  return path.join(homedir(), relative);
+}
+
+module.exports = {
+  vscodeUserMcpPath,
+  resolveMcpConfigPath
+};

package/lib/channels/mcp-client/profiles.js

@@ -0,0 +1,122 @@
+/**
+ * MCP client installation profile loader (schema-validated).
+ *
+ * @fileoverview Load cursor / vscode / github-copilot profiles from channel templates
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const Ajv = require('ajv');
+const schema = require('../../schema/mcp-client-profile.schema.json');
+
+const BUILDER_ROOT = path.join(__dirname, '..', '..', '..');
+const PROFILE_DIR = path.join(BUILDER_ROOT, 'templates', 'channels', 'mcp-client', 'profiles');
+
+const ajv = new Ajv({ allErrors: true, strict: false });
+const validateProfile = ajv.compile(schema);
+
+/**
+ * @param {string} message
+ * @returns {Error}
+ */
+function createMcpClientProfileError(message) {
+  const error = new Error(message);
+  error.boundary = 'usage';
+  return error;
+}
+
+/**
+ * @returns {string[]}
+ */
+function listMcpClientProfileKeys() {
+  return fs
+    .readdirSync(PROFILE_DIR)
+    .filter((name) => name.endsWith('.json'))
+    .map((name) => path.basename(name, '.json'))
+    .sort();
+}
+
+/**
+ * @returns {{ name: string, value: string }[]}
+ */
+function listMcpClientProfileChoices() {
+  return listMcpClientProfileKeys().map((key) => {
+    const profile = loadMcpClientProfile(key);
+    return { name: profile.displayName, value: profile.key };
+  });
+}
+
+/**
+ * @param {Object} profile
+ * @param {string} key
+ * @returns {void}
+ */
+function assertValidProfile(profile, key) {
+  if (validateProfile(profile)) {
+    return;
+  }
+  const details = (validateProfile.errors || [])
+    .map((err) => `${err.instancePath || '/'} ${err.message}`)
+    .join('; ');
+  throw createMcpClientProfileError(`MCP client profile "${key}" is invalid: ${details}`);
+}
+
+/**
+ * @param {string} key
+ * @returns {Object}
+ */
+function loadMcpClientProfile(key) {
+  const trimmed = typeof key === 'string' ? key.trim() : '';
+  if (!trimmed) {
+    throw createMcpClientProfileError(
+      [
+        'MCP client needs --target <profile> (cursor, vscode, or github-copilot).',
+        '  $ aifabrix channel add mcp-client --target cursor --name "Onni"'
+      ].join('\n')
+    );
+  }
+  const filePath = path.join(PROFILE_DIR, `${trimmed}.json`);
+  if (!fs.existsSync(filePath)) {
+    const known = listMcpClientProfileKeys().join(', ');
+    throw createMcpClientProfileError(
+      `Unknown MCP client profile: ${trimmed}\nSupported profiles: ${known}`
+    );
+  }
+  const profile = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  assertValidProfile(profile, trimmed);
+  if (profile.key !== trimmed) {
+    throw createMcpClientProfileError(
+      `MCP client profile "${trimmed}" key mismatch (found "${profile.key}").`
+    );
+  }
+  return profile;
+}
+
+/**
+ * @param {Object} [options]
+ * @returns {string}
+ */
+function resolveMcpClientProfileKey(options = {}) {
+  const raw = options.target || options.profile || options.mcpClientProfile;
+  return raw && String(raw).trim() ? String(raw).trim() : '';
+}
+
+/**
+ * @param {Object} [options]
+ * @returns {Object}
+ */
+function requireMcpClientProfile(options = {}) {
+  return loadMcpClientProfile(resolveMcpClientProfileKey(options));
+}
+
+module.exports = {
+  PROFILE_DIR,
+  listMcpClientProfileKeys,
+  listMcpClientProfileChoices,
+  loadMcpClientProfile,
+  resolveMcpClientProfileKey,
+  requireMcpClientProfile,
+  assertValidProfile
+};

package/lib/channels/mcp-client/redirect-uris.js

@@ -0,0 +1,99 @@
+/**
+ * MCP client redirect URI validation (HTTPS plus loopback HTTP).
+ *
+ * @fileoverview Do not reuse ChatGPT HTTPS-only callback assert
+ */
+
+'use strict';
+
+const { mergeRedirectUris } = require('../chatgpt-callback');
+
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '::1', '[::1]']);
+
+/**
+ * @param {string} message
+ * @returns {Error}
+ */
+function createMcpClientRedirectError(message) {
+  const error = new Error(`MCP client callback: ${message}`);
+  error.boundary = 'callback';
+  return error;
+}
+
+/**
+ * @param {string} hostname
+ * @returns {boolean}
+ */
+function isLoopbackHost(hostname) {
+  const host = String(hostname || '').toLowerCase().replace(/^\[|\]$/g, '');
+  return LOOPBACK_HOSTS.has(host) || LOOPBACK_HOSTS.has(hostname);
+}
+
+/**
+ * Allow HTTPS anywhere and HTTP on loopback only.
+ * @param {string|undefined} value
+ * @returns {string}
+ */
+function assertMcpClientRedirectUri(value) {
+  const trimmed = typeof value === 'string' ? value.trim() : '';
+  if (!trimmed) {
+    throw createMcpClientRedirectError('Redirect URI is required.');
+  }
+  let parsed;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    throw createMcpClientRedirectError(`Redirect URI is not a valid URL: ${trimmed}`);
+  }
+  if (parsed.protocol === 'https:') {
+    return trimmed;
+  }
+  if (parsed.protocol === 'http:' && isLoopbackHost(parsed.hostname)) {
+    return trimmed;
+  }
+  throw createMcpClientRedirectError(
+    `Redirect URI must be HTTPS or loopback HTTP: ${trimmed}`
+  );
+}
+
+/**
+ * @param {string[]|undefined} values
+ * @returns {string[]}
+ */
+function normalizeMcpClientRedirectUris(values) {
+  const unique = [];
+  for (const value of Array.isArray(values) ? values : []) {
+    const uri = assertMcpClientRedirectUri(value);
+    if (!unique.includes(uri)) {
+      unique.push(uri);
+    }
+  }
+  if (unique.length === 0) {
+    throw createMcpClientRedirectError('At least one redirect URI is required.');
+  }
+  return unique;
+}
+
+/**
+ * @param {string[]|undefined} existing
+ * @param {string[]} nextUris
+ * @returns {{ uris: string[], added: boolean }}
+ */
+function mergeRedirectUriList(existing, nextUris) {
+  let uris = Array.isArray(existing) ? [...existing] : [];
+  let added = false;
+  for (const nextUri of nextUris) {
+    const merged = mergeRedirectUris(uris, nextUri);
+    uris = merged.uris;
+    added = added || merged.added;
+  }
+  return { uris, added };
+}
+
+module.exports = {
+  LOOPBACK_HOSTS,
+  assertMcpClientRedirectUri,
+  normalizeMcpClientRedirectUris,
+  mergeRedirectUris,
+  mergeRedirectUriList
+};

package/lib/channels/mcp-client/runtime.js

@@ -0,0 +1,59 @@
+/**
+ * Runtime values for the generic developer MCP client channel.
+ *
+ * @fileoverview Same Runtime MCP as ChatGPT; OAuth profile from the installation profile
+ */
+
+'use strict';
+
+const {
+  CHATGPT_RUNTIME_SYSTEM_KEY,
+  CHATGPT_RUNTIME_TRANSPORT,
+  CHATGPT_RUNTIME_AUTH_MODE
+} = require('../chatgpt-runtime-contract');
+
+/**
+ * @param {string} controllerUrl
+ * @param {string} dataplaneBaseUrl
+ * @returns {string}
+ */
+function authorizationServerBase(controllerUrl, dataplaneBaseUrl) {
+  const candidate = controllerUrl || dataplaneBaseUrl;
+  try {
+    return `${new URL(candidate).origin}/auth/realms/aifabrix`;
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * @param {Object} resolved
+ * @param {Object} params
+ * @returns {void}
+ */
+function applyMcpClientRuntimeValues(resolved, params) {
+  resolved.runtimeSystemKey = CHATGPT_RUNTIME_SYSTEM_KEY;
+  resolved.runtimeTransport = CHATGPT_RUNTIME_TRANSPORT;
+  resolved.runtimeAuthMode = CHATGPT_RUNTIME_AUTH_MODE;
+  resolved.layerBToolNames = Array.isArray(params.layerBToolNames) ? [...params.layerBToolNames] : [];
+  resolved.scopes = Array.isArray(params.scopes) ? [...params.scopes] : [];
+  resolved.scopesJson = JSON.stringify(resolved.scopes);
+  const profile = params.mcpClientProfile;
+  if (!profile) {
+    return;
+  }
+  const clientId = profile.oauth.keycloakClientId;
+  const controllerUrl = typeof params.controllerUrl === 'string' ? params.controllerUrl.trim() : '';
+  resolved.mcpClientProfileKey = profile.key;
+  resolved.mcpClientDisplayName = profile.displayName;
+  resolved.oauth2ProfileId = clientId;
+  resolved.oauth2ProfilePath = `/external-access/oauth2-profiles/${clientId}`;
+  if (controllerUrl) {
+    resolved.oauth2ProfileUrl = `${controllerUrl.replace(/\/$/, '')}${resolved.oauth2ProfilePath}`;
+  }
+  resolved.authorizationServerBase = authorizationServerBase(controllerUrl, resolved.dataplaneBaseUrl);
+}
+
+module.exports = {
+  applyMcpClientRuntimeValues
+};