@aifabrix/builder 2.46.0 → 2.47.0

package/lib/channels/channel-credential.js

@@ -0,0 +1,200 @@
+/**
+ * Channel credential matrix and provisioning (plan 152).
+ *
+ * @fileoverview Ensure channel credentials exist; push secrets from integration env
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const path = require('path');
+const { listCredentials } = require('../api/credentials.api');
+const { credentialSelection } = require('../api/wizard.api');
+const { pushCredentialSecrets } = require('../utils/credential-secrets-env');
+const { getIntegrationPath } = require('../utils/paths');
+const {
+  auditCredentialCreated,
+  auditCredentialUpdated,
+  auditFailed
+} = require('./channel-audit');
+
+/** @type {Record<string, { method: string, displayName: string, credentialConfig: Object }>} */
+const CREDENTIAL_SPECS = {
+  slack: {
+    method: 'hmac',
+    credentialConfig: {
+      type: 'hmac',
+      signingSecret: 'pending-channel-install',
+      algorithm: 'sha256',
+      signatureHeader: 'X-Slack-Signature',
+      timestampHeader: 'X-Slack-Request-Timestamp',
+      signaturePrefix: 'v0=',
+      timestampMaxAge: 300
+    }
+  },
+  'teams-bot': {
+    method: 'oidc',
+    credentialConfig: {
+      type: 'oidc',
+      openIdConfigUrl: 'https://login.botframework.com/v1/.well-known/openid_configuration',
+      clientId: 'pending-channel-install',
+      validateSignature: true,
+      algorithms: ['RS256'],
+      clockSkewSeconds: 300
+    }
+  },
+  'microsoft-copilot': {
+    method: 'oauth2',
+    credentialConfig: {
+      type: 'oauth2',
+      grantType: 'client_credentials',
+      tokenUrl: 'https://login.microsoftonline.com/common/oauth2/v2.0/token',
+      clientId: 'pending-channel-install',
+      clientSecret: 'pending-channel-install'
+    }
+  },
+  chatgpt: {
+    method: 'apiKey',
+    credentialConfig: {
+      type: 'apiKey',
+      apiKey: 'pending-channel-install',
+      headerName: 'Authorization',
+      prefix: 'Bearer'
+    }
+  },
+  'web-embed': {
+    method: 'apiKey',
+    credentialConfig: {
+      type: 'apiKey',
+      apiKey: 'pending-channel-install',
+      headerName: 'Authorization',
+      prefix: 'Bearer'
+    }
+  }
+};
+
+/**
+ * @param {Object} response
+ * @returns {Object[]}
+ */
+function extractCredentials(response) {
+  const body = response?.data ?? response;
+  const data = body?.data ?? body;
+  const items = data?.credentials ?? data?.items ?? (Array.isArray(data) ? data : []);
+  return Array.isArray(items) ? items : [];
+}
+
+/**
+ * @param {string} channelTarget
+ * @param {typeof import('./channel-targets').CHANNEL_TARGETS[string]} target
+ * @returns {{ method: ChannelCredentialMethod, displayName: string, credentialConfig: Object }}
+ */
+function buildCredentialSpec(channelTarget, target) {
+  const base = CREDENTIAL_SPECS[channelTarget];
+  if (!base) {
+    throw new Error(`No credential spec for channel target "${channelTarget}"`);
+  }
+  return {
+    method: base.method,
+    displayName: `${target.key} assistant channel`,
+    credentialConfig: base.credentialConfig
+  };
+}
+
+/**
+ * @async
+ * @param {Object} ctx
+ * @param {string} credentialKey
+ * @returns {Promise<Object|null>}
+ */
+async function findCredentialByKey(ctx, credentialKey) {
+  const response = await listCredentials(ctx.dataplaneUrl, ctx.authConfig, { pageSize: 200 });
+  const items = extractCredentials(response);
+  return items.find((item) => item.key === credentialKey || item.credentialKey === credentialKey) || null;
+}
+
+/**
+ * @async
+ * @param {Object} ctx
+ * @param {string} channelTarget
+ * @param {Object} target
+ * @returns {Promise<Object>}
+ */
+async function createChannelCredential(ctx, channelTarget, target) {
+  const spec = buildCredentialSpec(channelTarget, target);
+  const payload = {
+    action: 'create',
+    credentialConfig: {
+      key: target.credentialKey,
+      displayName: spec.displayName,
+      description: 'Assistant channel credential (secrets via kv:// env.template)',
+      credentialConfig: spec.credentialConfig,
+      isActive: true
+    }
+  };
+  const response = await credentialSelection(ctx.dataplaneUrl, ctx.authConfig, payload);
+  auditCredentialCreated(channelTarget, { credentialKey: target.credentialKey, method: spec.method });
+  return { created: true, credentialIdOrKey: response?.data?.credentialIdOrKey || target.credentialKey };
+}
+
+/**
+ * @async
+ * @param {Object} ctx
+ * @param {string} channelTarget
+ * @returns {Promise<{ pushed: number }>}
+ */
+async function pushIntegrationSecrets(ctx, channelTarget) {
+  const integrationDir = getIntegrationPath(channelTarget);
+  const envPath = path.join(integrationDir, '.env');
+  const result = await pushCredentialSecrets(ctx.dataplaneUrl, ctx.authConfig, {
+    envFilePath: envPath,
+    appName: channelTarget,
+    quiet: true
+  });
+  return { pushed: result?.pushed ?? 0, skipped: result?.skipped === true };
+}
+
+/**
+ * Ensure channel credential record exists; optionally push secrets from integration/.env.
+ * Does not rotate secrets when force is set (plan 152 V1).
+ *
+ * @async
+ * @param {Object} params
+ * @param {Object} params.ctx
+ * @param {string} params.channelTarget
+ * @param {Object} params.target
+ * @param {boolean} [params.force]
+ * @returns {Promise<Object>}
+ */
+async function ensureChannelCredential(params) {
+  const { ctx, channelTarget, target, force = false } = params;
+  const existing = await findCredentialByKey(ctx, target.credentialKey);
+  if (existing) {
+    auditCredentialUpdated(channelTarget, {
+      credentialKey: target.credentialKey,
+      rotated: false,
+      force: force === true
+    });
+    const secretPush = await pushIntegrationSecrets(ctx, channelTarget);
+    return { existed: true, credentialKey: target.credentialKey, secretPush };
+  }
+
+  try {
+    const created = await createChannelCredential(ctx, channelTarget, target);
+    const secretPush = await pushIntegrationSecrets(ctx, channelTarget);
+    return { ...created, credentialKey: target.credentialKey, secretPush };
+  } catch (err) {
+    auditFailed(channelTarget, { phase: 'credential', error: err.message });
+    throw err;
+  }
+}
+
+module.exports = {
+  buildCredentialSpec,
+  extractCredentials,
+  findCredentialByKey,
+  createChannelCredential,
+  pushIntegrationSecrets,
+  ensureChannelCredential
+};

package/lib/channels/channel-display-name.js

@@ -0,0 +1,64 @@
+/**
+ * Environment-scoped assistant channel display names (plan 152).
+ *
+ * @fileoverview Base name (e.g. Elsa) → Elsa (dev) | Elsa (tst) | Elsa in production
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const ENV_SUFFIX_PATTERN = /\s+\((dev|tst|test|pro|prod|production)\)$/i;
+
+/**
+ * Strip a trailing environment suffix so --name can be re-run safely.
+ * @param {string} name
+ * @returns {string}
+ */
+function normalizeBaseChannelName(name) {
+  if (!name || typeof name !== 'string') {
+    throw new Error('Channel base name is required');
+  }
+  const trimmed = name.trim();
+  if (!trimmed) {
+    throw new Error('Channel base name is required');
+  }
+  return trimmed.replace(ENV_SUFFIX_PATTERN, '').trim();
+}
+
+/**
+ * @param {string} environment
+ * @returns {boolean}
+ */
+function isProductionEnvironment(environment) {
+  const env = String(environment || '').toLowerCase();
+  return env === 'pro' || env === 'prod' || env === 'production';
+}
+
+/**
+ * Resolve customer-visible channel name for the active environment.
+ * @param {string} baseName - Canonical product name (e.g. Elsa)
+ * @param {string} environment - dev | tst | pro
+ * @returns {string}
+ */
+function resolveChannelDisplayName(baseName, environment) {
+  const base = normalizeBaseChannelName(baseName);
+  const env = String(environment || 'dev').toLowerCase();
+
+  if (isProductionEnvironment(env)) {
+    return base;
+  }
+  if (env === 'dev') {
+    return `${base} (dev)`;
+  }
+  if (env === 'tst' || env === 'test') {
+    return `${base} (tst)`;
+  }
+  return `${base} (${env})`;
+}
+
+module.exports = {
+  normalizeBaseChannelName,
+  isProductionEnvironment,
+  resolveChannelDisplayName
+};

package/lib/channels/channel-external-system.js

@@ -0,0 +1,106 @@
+/**
+ * External system channel config helpers (plan 152).
+ *
+ * @fileoverview Patch config.extensions.channel on deployed communication systems
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { getExternalSystem, updateExternalSystem } = require('../api/external-systems.api');
+const { unwrapApiData } = require('../utils/external-system-readiness-core');
+
+/**
+ * @param {Object|null} system
+ * @returns {Object|null}
+ */
+function getExistingChannelExtension(system) {
+  if (!system || typeof system !== 'object') return null;
+  const channel = system.config?.extensions?.channel;
+  return channel && typeof channel === 'object' ? channel : null;
+}
+
+/**
+ * @param {Object} params
+ * @param {typeof import('./channel-targets').CHANNEL_TARGETS[string]} target
+ * @param {string} params.name
+ * @param {string} params.baseName
+ * @param {string} params.description
+ * @param {string} params.artifactHash
+ * @param {string} params.status
+ * @returns {Object}
+ */
+function buildChannelExtensionBlock(params, target) {
+  return {
+    type: target.channelType,
+    name: params.name,
+    baseName: params.baseName,
+    description: params.description,
+    capabilities: [...target.capabilities],
+    status: params.status,
+    artifactHash: params.artifactHash,
+    credentialKey: target.credentialKey
+  };
+}
+
+/**
+ * @param {Object} system
+ * @param {Object} channelBlock
+ * @returns {Object}
+ */
+function mergeChannelIntoSystem(system, channelBlock) {
+  const config = system.config && typeof system.config === 'object' ? { ...system.config } : {};
+  const extensions =
+    config.extensions && typeof config.extensions === 'object' ? { ...config.extensions } : {};
+  extensions.channel = channelBlock;
+  config.extensions = extensions;
+  return { ...system, config, displayName: channelBlock.name };
+}
+
+/**
+ * @async
+ * @param {Object} ctx
+ * @param {string} ctx.dataplaneUrl
+ * @param {Object} ctx.authConfig
+ * @param {string} ctx.channelTarget
+ * @returns {Promise<Object>}
+ */
+async function fetchCommunicationSystem(ctx) {
+  const res = await getExternalSystem(ctx.dataplaneUrl, ctx.channelTarget, ctx.authConfig);
+  const system = unwrapApiData(res);
+  if (!system || typeof system !== 'object') {
+    throw new Error(
+      `Communication external system "${ctx.channelTarget}" was not found. ` +
+        `Run: aifabrix deploy ${ctx.channelTarget}`
+    );
+  }
+  const kind = system.systemKind || system.systemKindKey;
+  if (kind && kind !== 'communication') {
+    throw new Error(
+      `External system "${ctx.channelTarget}" is not systemKind communication (found: ${kind}).`
+    );
+  }
+  return system;
+}
+
+/**
+ * @async
+ * @param {Object} ctx
+ * @param {Object} channelBlock
+ * @returns {Promise<Object>}
+ */
+async function patchChannelExtension(ctx, channelBlock) {
+  const system = await fetchCommunicationSystem(ctx);
+  const merged = mergeChannelIntoSystem(system, channelBlock);
+  const res = await updateExternalSystem(ctx.dataplaneUrl, ctx.channelTarget, ctx.authConfig, merged);
+  return unwrapApiData(res) || merged;
+}
+
+module.exports = {
+  getExistingChannelExtension,
+  buildChannelExtensionBlock,
+  mergeChannelIntoSystem,
+  fetchCommunicationSystem,
+  patchChannelExtension
+};

package/lib/channels/channel-integration-generator.js

@@ -0,0 +1,274 @@
+/**
+ * Generate integration/<channelTarget>/ for communication external systems (plan 152).
+ *
+ * @fileoverview Builder generator for channel deploy step 1 scaffolds
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { getChannelTarget } = require('./channel-targets');
+const { getIntegrationPath } = require('../utils/paths');
+
+/** @type {Record<string, Object>} */
+const AUTH_BLOCKS = {
+  slack: {
+    authType: 'credential',
+    credential: {
+      credentialKey: 'slack-app',
+      displayName: 'Slack assistant channel',
+      method: 'hmac',
+      variables: {},
+      security: {
+        signingSecret: 'kv://slack/signingSecret',
+        clientId: 'kv://slack/clientId',
+        clientSecret: 'kv://slack/clientSecret'
+      },
+      writeOnce: true
+    }
+  },
+  'teams-bot': {
+    authType: 'credential',
+    credential: {
+      credentialKey: 'teams-bot',
+      displayName: 'Microsoft Teams assistant bot',
+      method: 'oidc',
+      variables: {
+        openIdConfigUrl: 'https://login.botframework.com/v1/.well-known/openid_configuration',
+        clientId: 'kv://teams-bot/botAppId',
+        expectedIssuer: 'https://api.botframework.com'
+      },
+      security: {},
+      writeOnce: true
+    }
+  },
+  'microsoft-copilot': {
+    authType: 'credential',
+    credential: {
+      credentialKey: 'microsoft-copilot-channel',
+      displayName: 'Microsoft Copilot assistant channel',
+      method: 'oauth2',
+      variables: {
+        tokenUrl: 'https://login.microsoftonline.com/common/oauth2/v2.0/token',
+        grantType: 'client_credentials'
+      },
+      security: {
+        clientId: 'kv://microsoft-copilot/clientId',
+        clientSecret: 'kv://microsoft-copilot/clientSecret'
+      },
+      writeOnce: true
+    }
+  },
+  chatgpt: {
+    authType: 'credential',
+    credential: {
+      credentialKey: 'chatgpt-channel',
+      displayName: 'ChatGPT assistant channel',
+      method: 'apikey',
+      variables: {},
+      security: {
+        apiKey: 'kv://chatgpt/apiKey'
+      },
+      writeOnce: true
+    }
+  },
+  'web-embed': {
+    authType: 'credential',
+    credential: {
+      credentialKey: 'web-embed-channel',
+      displayName: 'Web embed assistant channel',
+      method: 'apikey',
+      variables: {},
+      security: {
+        apiKey: 'kv://web-embed/apiKey'
+      },
+      writeOnce: true
+    }
+  }
+};
+
+/**
+ * @param {string} channelTarget
+ * @param {typeof import('./channel-targets').CHANNEL_TARGETS[string]} target
+ * @returns {Object}
+ */
+function buildAuthenticationBlock(channelTarget, target) {
+  const block = AUTH_BLOCKS[channelTarget];
+  if (!block) {
+    throw new Error(`No authentication block for channel target "${channelTarget}"`);
+  }
+  const auth = JSON.parse(JSON.stringify(block));
+  auth.credential.credentialKey = target.credentialKey;
+  return auth;
+}
+
+/**
+ * @param {string} channelTarget
+ * @returns {Object}
+ */
+function buildSystemJson(channelTarget) {
+  const target = getChannelTarget(channelTarget);
+  const system = {
+    key: channelTarget,
+    displayName: 'Microsoft Teams assistant bot',
+    description: 'Bot Framework assistant channel (not full Teams / Graph integration)',
+    type: 'custom',
+    systemKind: 'communication',
+    enabled: true,
+    authentication: buildAuthenticationBlock(channelTarget, target),
+    configuration: [],
+    dataSources: []
+  };
+
+  if (channelTarget === 'teams-bot') {
+    system.displayName = 'Microsoft Teams assistant bot';
+    system.endpoints = [
+      {
+        type: 'messages',
+        path: '/messages',
+        router: 'teams_bot_router',
+        description: 'Bot Framework messaging endpoint',
+        active: true
+      },
+      {
+        type: 'notifications',
+        path: '/notifications',
+        router: 'teams_notifications_router',
+        description: 'Proactive notification endpoint',
+        active: true
+      },
+      {
+        type: 'config',
+        path: '/bot-config',
+        router: 'teams_config_router',
+        description: 'Bot configuration endpoint',
+        active: true
+      }
+    ];
+    system.endpointsActive = true;
+  } else {
+    system.displayName = `${target.key} assistant channel`;
+    system.description = 'Communication external system for assistant channel install (plan 152)';
+  }
+
+  return system;
+}
+
+/**
+ * @param {string} channelTarget
+ * @returns {Object}
+ */
+function buildApplicationJson(channelTarget) {
+  const target = getChannelTarget(channelTarget);
+  const systemFile = `${channelTarget}-system.json`;
+  return {
+    app: {
+      key: channelTarget,
+      displayName: `${target.key} assistant channel`,
+      description: 'Assistant communication channel — deploy then app add-channel',
+      type: 'external'
+    },
+    externalIntegration: {
+      schemaBasePath: './',
+      systems: [systemFile],
+      dataSources: [],
+      autopublish: true,
+      version: '1.0.0'
+    }
+  };
+}
+
+/**
+ * @param {string} channelTarget
+ * @returns {string}
+ */
+function buildEnvTemplate(channelTarget) {
+  const kvPrefix = channelTarget === 'web-embed' ? 'web-embed' : channelTarget;
+  const lines = [
+    `# ${channelTarget} assistant channel — resolve secrets before deploy/add-channel`,
+    '# kv:// paths are pushed via aifabrix credential push or add-channel secret sync',
+    ''
+  ];
+  if (channelTarget === 'slack') {
+    lines.push('KV_SLACK_SIGNINGSECRET=kv://slack/signingSecret');
+    lines.push('KV_SLACK_CLIENTID=kv://slack/clientId');
+    lines.push('KV_SLACK_CLIENTSECRET=kv://slack/clientSecret');
+  } else if (channelTarget === 'teams-bot') {
+    lines.push('KV_TEAMS_BOT_BOTAPPID=kv://teams-bot/botAppId');
+  } else if (channelTarget === 'microsoft-copilot') {
+    lines.push('KV_MICROSOFT_COPILOT_CLIENTID=kv://microsoft-copilot/clientId');
+    lines.push('KV_MICROSOFT_COPILOT_CLIENTSECRET=kv://microsoft-copilot/clientSecret');
+  } else {
+    lines.push(`KV_${kvPrefix.toUpperCase().replace(/-/g, '_')}_APIKEY=kv://${kvPrefix}/apiKey`);
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+/**
+ * @param {string} channelTarget
+ * @param {Object} [options]
+ * @param {boolean} [options.force]
+ * @param {boolean} [options.allowExperimental]
+ * @param {string} [options.projectRoot]
+ * @returns {{ integrationDir: string, files: string[] }}
+ */
+function scaffoldChannelIntegration(channelTarget, options = {}) {
+  const target = getChannelTarget(channelTarget);
+  if (target.experimental && !options.allowExperimental) {
+    throw new Error(
+      `Channel target "${channelTarget}" is experimental. Pass --allow-experimental to scaffold.`
+    );
+  }
+
+  const integrationDir = options.projectRoot
+    ? path.join(path.resolve(options.projectRoot), 'integration', channelTarget)
+    : getIntegrationPath(channelTarget);
+  if (fs.existsSync(integrationDir) && !options.force) {
+    throw new Error(
+      `Integration folder already exists: ${integrationDir}. Use --force to overwrite generated files.`
+    );
+  }
+
+  fs.mkdirSync(integrationDir, { recursive: true });
+  const systemPath = path.join(integrationDir, `${channelTarget}-system.json`);
+  const appPath = path.join(integrationDir, 'application.json');
+  const envPath = path.join(integrationDir, 'env.template');
+  const readmePath = path.join(integrationDir, 'README.md');
+
+  fs.writeFileSync(systemPath, `${JSON.stringify(buildSystemJson(channelTarget), null, 2)}\n`, 'utf8');
+  fs.writeFileSync(appPath, `${JSON.stringify(buildApplicationJson(channelTarget), null, 2)}\n`, 'utf8');
+  fs.writeFileSync(envPath, buildEnvTemplate(channelTarget), 'utf8');
+  fs.writeFileSync(
+    readmePath,
+    [
+      `# ${channelTarget} assistant channel`,
+      '',
+      '## Two-step install',
+      '',
+      '```bash',
+      `aifabrix deploy ${channelTarget}`,
+      `aifabrix app add-channel ${channelTarget} --name "Your Assistant"`,
+      '```',
+      '',
+      'Generated by `aifabrix channel scaffold`. Secrets belong in kv:// env.template only.',
+      ''
+    ].join('\n'),
+    'utf8'
+  );
+
+  return {
+    integrationDir,
+    files: [systemPath, appPath, envPath, readmePath]
+  };
+}
+
+module.exports = {
+  buildSystemJson,
+  buildApplicationJson,
+  buildEnvTemplate,
+  scaffoldChannelIntegration
+};