@aifabrix/builder 2.51.1 → 2.52.1

package/lib/channels/microsoft-copilot-channel-add.js

@@ -0,0 +1,138 @@
+/**
+ * microsoft-copilot channel-add helpers (Entra SSO form context for operator errors).
+ *
+ * @fileoverview Keep add-channel.js under size limits
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { resolveChannelAuthContext } = require('./channel-auth-context');
+const {
+  normalizeBaseChannelName,
+  resolveChannelDisplayName
+} = require('./channel-display-name');
+const { getDefaultChannelDescription } = require('./channel-targets');
+const { resolveAppDescription } = require('./channel-description');
+const { loadChannelPackageContext } = require('./channel-discovery');
+const { getInboundMicrosoftEntraIdProvider } = require('../api/token-providers.api');
+const { getKeycloakEntraIdentityProvider } = require('../api/keycloak.api');
+const { resolveChannelRuntimeValues } = require('./channel-runtime-resolver');
+const { assertOauthPluginVaultReferenceId } = require('./microsoft-copilot-entra-sso');
+
+/**
+ * @param {Object} options
+ * @returns {boolean}
+ */
+function hasOauthPluginVaultReference(options) {
+  return (
+    typeof options.oauthPluginVaultReferenceId === 'string' &&
+    Boolean(options.oauthPluginVaultReferenceId.trim())
+  );
+}
+
+/**
+ * Load Trust source + Keycloak Entra IdP for Copilot packaging (null on miss/error).
+ * @param {Object} ctx
+ * @returns {Promise<{ entraProvider: Object|null, entraIdentityProvider: Object|null }>}
+ */
+async function loadMicrosoftCopilotEntraContext(ctx) {
+  let entraProvider = null;
+  let entraIdentityProvider = null;
+  if (!ctx?.controllerUrl) {
+    return { entraProvider, entraIdentityProvider };
+  }
+  try {
+    entraProvider = await getInboundMicrosoftEntraIdProvider(ctx.controllerUrl, ctx.authConfig);
+  } catch {
+    entraProvider = null;
+  }
+  try {
+    entraIdentityProvider = await getKeycloakEntraIdentityProvider(
+      ctx.controllerUrl,
+      ctx.authConfig
+    );
+  } catch {
+    entraIdentityProvider = null;
+  }
+  return { entraProvider, entraIdentityProvider };
+}
+
+/**
+ * @param {Object} params
+ * @returns {Promise<Object>}
+ */
+async function resolveCopilotFormContextForError(params) {
+  const { options, ctx, name, baseName, description } = params;
+  let packageContext = null;
+  try {
+    packageContext = await loadChannelPackageContext({
+      dataplaneBaseUrl: ctx.dataplaneUrl,
+      authConfig: ctx.authConfig,
+      channelTarget: 'microsoft-copilot',
+      branding: { displayName: name, description }
+    });
+  } catch {
+    packageContext = null;
+  }
+  const { entraProvider, entraIdentityProvider } = await loadMicrosoftCopilotEntraContext(ctx);
+  return resolveChannelRuntimeValues({
+    dataplaneBaseUrl: ctx.dataplaneUrl,
+    channelTarget: 'microsoft-copilot',
+    appName: name,
+    baseName,
+    environment: ctx.environment,
+    appDescription: description,
+    packageContext,
+    entraProvider,
+    entraIdentityProvider,
+    oauthPluginVaultReferenceId: options.oauthPluginVaultReferenceId
+  });
+}
+
+/**
+ * @param {Object} params
+ * @throws {Error}
+ */
+async function assertMicrosoftCopilotOauthReference(params) {
+  const { options } = params;
+  if (hasOauthPluginVaultReference(options)) {
+    return;
+  }
+  const formContext = await resolveCopilotFormContextForError(params);
+  assertOauthPluginVaultReferenceId({ ...options, formContext });
+}
+
+/**
+ * Fail before force upload when Teams Entra SSO auth-config id is missing.
+ * @param {Object} options
+ * @throws {Error}
+ */
+async function assertMicrosoftCopilotOauthReferenceBeforeForce(options) {
+  if (hasOauthPluginVaultReference(options)) {
+    return;
+  }
+  const ctx = await resolveChannelAuthContext('microsoft-copilot', { silent: options.quiet });
+  const baseName = normalizeBaseChannelName(options.name);
+  const name = resolveChannelDisplayName(baseName, ctx.environment);
+  const rawDescription =
+    options.description && String(options.description).trim()
+      ? String(options.description).trim()
+      : getDefaultChannelDescription();
+  await assertMicrosoftCopilotOauthReference({
+    options,
+    ctx,
+    name,
+    baseName,
+    description: resolveAppDescription('microsoft-copilot', rawDescription)
+  });
+}
+
+module.exports = {
+  hasOauthPluginVaultReference,
+  loadMicrosoftCopilotEntraContext,
+  resolveCopilotFormContextForError,
+  assertMicrosoftCopilotOauthReference,
+  assertMicrosoftCopilotOauthReferenceBeforeForce
+};

package/lib/channels/microsoft-copilot-entra-sso-form.js

@@ -0,0 +1,180 @@
+/**
+ * Microsoft Copilot Entra SSO form field resolution + template rendering.
+ *
+ * @fileoverview Template-backed Teams Entra SSO registration guidance
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const fs = require('../internal/fs-real-sync');
+const path = require('path');
+const Handlebars = require('handlebars');
+const { BUILDER_ROOT } = require('./channel-integration-template');
+
+const ENTRA_SSO_REGISTRATION_URL =
+  'https://dev.teams.microsoft.com/tools/entra-configuration';
+const TEMPLATES_DIR = path.join(BUILDER_ROOT, 'templates', 'channels', 'microsoft-copilot');
+
+/**
+ * @param {string} issuer
+ * @returns {string|null}
+ */
+function extractTenantIdFromIssuer(issuer) {
+  if (typeof issuer !== 'string' || !issuer.trim()) {
+    return null;
+  }
+  const match = issuer.match(
+    /login\.microsoftonline\.com\/([0-9a-fA-F-]{36})(?:\/|$)/i
+  );
+  return match ? match[1] : null;
+}
+
+/**
+ * @param {string} [url]
+ * @returns {string|null}
+ */
+function originFromUrl(url) {
+  if (typeof url !== 'string' || !url.trim()) {
+    return null;
+  }
+  try {
+    const parsed = new URL(url.trim());
+    return `${parsed.protocol}//${parsed.host}`;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Prefer Keycloak status enterpriseAppId (Entra SSO application/client id).
+ * @param {Object|null} entraIdentityProvider
+ * @param {Object|null} entraProvider
+ * @param {Object|null} auth
+ * @returns {string|null}
+ */
+function resolveEntraSsoClientId(entraIdentityProvider, entraProvider, auth) {
+  if (
+    entraIdentityProvider &&
+    typeof entraIdentityProvider.enterpriseAppId === 'string' &&
+    entraIdentityProvider.enterpriseAppId.trim()
+  ) {
+    return entraIdentityProvider.enterpriseAppId.trim();
+  }
+  if (entraProvider && typeof entraProvider.clientId === 'string' && entraProvider.clientId.trim()) {
+    return entraProvider.clientId.trim();
+  }
+  if (auth && typeof auth.clientId === 'string' && auth.clientId.trim()) {
+    return auth.clientId.trim();
+  }
+  return null;
+}
+
+/**
+ * @param {Object} resolved
+ * @param {Object|null} entraIdentityProvider
+ * @param {Object|null} entraProvider
+ * @param {Object|null} auth
+ * @returns {string|null}
+ */
+function resolveEntraTenantId(resolved, entraIdentityProvider, entraProvider, auth) {
+  if (
+    entraIdentityProvider &&
+    typeof entraIdentityProvider.tenantId === 'string' &&
+    entraIdentityProvider.tenantId.trim()
+  ) {
+    return entraIdentityProvider.tenantId.trim();
+  }
+  return extractTenantIdFromIssuer(
+    resolved.entraIssuer || entraProvider?.issuer || auth?.issuer || null
+  );
+}
+
+/**
+ * @param {Object} resolved
+ * @param {Object} [params]
+ * @returns {void}
+ */
+function applyCopilotEntraSsoFormFields(resolved, params = {}) {
+  const entraProvider = params.entraProvider || null;
+  const entraIdentityProvider = params.entraIdentityProvider || null;
+  const auth = resolved.discoveryAuthentication || null;
+  resolved.entraSsoRegistrationUrl = ENTRA_SSO_REGISTRATION_URL;
+  resolved.entraSsoBaseUrl =
+    originFromUrl(resolved.dataplaneBaseUrl) || originFromUrl(resolved.mcpUrl) || null;
+  resolved.entraSsoClientId = resolveEntraSsoClientId(
+    entraIdentityProvider,
+    entraProvider,
+    auth
+  );
+  const scopes = Array.isArray(resolved.scopes) ? resolved.scopes : [];
+  resolved.entraSsoScope = scopes.length > 0 ? scopes.join(', ') : null;
+  resolved.entraTenantId = resolveEntraTenantId(
+    resolved,
+    entraIdentityProvider,
+    entraProvider,
+    auth
+  );
+  if (entraIdentityProvider?.enterpriseAppId) {
+    resolved.entraEnterpriseAppId = String(entraIdentityProvider.enterpriseAppId).trim();
+  }
+}
+
+/**
+ * @param {string} fileName
+ * @returns {string}
+ */
+function readCopilotTemplate(fileName) {
+  const templatePath = path.join(TEMPLATES_DIR, fileName);
+  if (!fs.existsSync(templatePath)) {
+    throw new Error(`Microsoft Copilot template not found: ${templatePath}`);
+  }
+  return fs.readFileSync(templatePath, 'utf8');
+}
+
+/**
+ * @param {string} fileName
+ * @param {Object} context
+ * @returns {string}
+ */
+function renderCopilotChannelTemplate(fileName, context) {
+  const hb = Handlebars.create();
+  hb.registerPartial('entraSsoRegistration', readCopilotTemplate('entra-sso-registration.template.md.hbs'));
+  const template = hb.compile(readCopilotTemplate(fileName));
+  return template(context).trim();
+}
+
+/**
+ * Operator-facing error when Teams Entra SSO auth-config id is missing.
+ * Prose lives in templates — not inline CLI copy.
+ * @param {Object|string} [context]
+ * @returns {string}
+ */
+function formatOauthPluginVaultReferenceRequiredError(context = {}) {
+  const values = typeof context === 'string' ? { appName: context, baseName: context } : context || {};
+  const appName =
+    (typeof values.appName === 'string' && values.appName.trim()) ||
+    (typeof values.baseName === 'string' && values.baseName.trim()) ||
+    'Your Assistant';
+  const baseName =
+    (typeof values.baseName === 'string' && values.baseName.trim()) || appName;
+  return renderCopilotChannelTemplate('oauth-plugin-vault-required.template.md.hbs', {
+    ...values,
+    appName,
+    baseName,
+    channelTarget: 'microsoft-copilot',
+    entraSsoRegistrationUrl: values.entraSsoRegistrationUrl || ENTRA_SSO_REGISTRATION_URL
+  });
+}
+
+module.exports = {
+  ENTRA_SSO_REGISTRATION_URL,
+  extractTenantIdFromIssuer,
+  originFromUrl,
+  resolveEntraSsoClientId,
+  resolveEntraTenantId,
+  applyCopilotEntraSsoFormFields,
+  renderCopilotChannelTemplate,
+  formatOauthPluginVaultReferenceRequiredError
+};

package/lib/channels/microsoft-copilot-entra-sso.js

@@ -0,0 +1,264 @@
+/**
+ * Microsoft Copilot Entra SSO / trustedIssuer packaging helpers (plan 169.0).
+ *
+ * @fileoverview Readiness, scopes, and auth selection for microsoft-copilot
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const TRUSTED_ISSUER = 'trustedIssuer';
+const CUSTOMER_OAUTH = 'customerOAuth';
+const OPENID_ONLY = new Set(['openid', 'profile', 'offline_access']);
+
+/**
+ * @param {*} value
+ * @returns {boolean}
+ */
+function isPresent(value) {
+  return value !== undefined && value !== null && value !== '';
+}
+
+/**
+ * @param {string} channelTarget
+ * @returns {boolean}
+ */
+function skipsChannelOauthCredential(channelTarget) {
+  return channelTarget === 'microsoft-copilot';
+}
+
+/**
+ * @param {unknown} scopes
+ * @returns {string[]}
+ */
+function normalizeScopeList(scopes) {
+  if (!Array.isArray(scopes)) {
+    return [];
+  }
+  return scopes.map((s) => String(s).trim()).filter(Boolean);
+}
+
+/**
+ * True when scopes are empty or only OIDC login scopes (insufficient for Runtime MCP).
+ * @param {string[]} scopes
+ * @returns {boolean}
+ */
+function isOpenIdOnlyOrEmptyScopes(scopes) {
+  const list = normalizeScopeList(scopes);
+  if (list.length === 0) {
+    return true;
+  }
+  return list.every((scope) => OPENID_ONLY.has(scope));
+}
+
+/**
+ * @param {Object|null|undefined} auth
+ * @returns {string|null}
+ */
+function resolveRecommendedCapability(auth) {
+  const value = auth && typeof auth.recommendedCapability === 'string'
+    ? auth.recommendedCapability.trim()
+    : '';
+  return value || null;
+}
+
+/**
+ * Map adapter auth for Copilot packaging: keep trustedIssuer public fields;
+ * drop Keycloak/customerOAuth AS metadata from the package surface.
+ * @param {Object|null} auth
+ * @returns {Object|null}
+ */
+function mapCopilotPackageAuthentication(auth) {
+  if (!auth || typeof auth !== 'object') {
+    return null;
+  }
+  const recommended = resolveRecommendedCapability(auth);
+  const base = {
+    recommendedCapability: recommended,
+    issuer: auth.issuer || null,
+    openidConfigurationUrl: auth.openidConfigurationUrl || null,
+    protectedResourceMetadataUrl: auth.protectedResourceMetadataUrl || null,
+    resource: auth.resource || auth.apiResource || null,
+    operatorNote: auth.operatorNote || null,
+    pkceRequired: auth.pkceRequired === true,
+    audience: isPresent(auth.audience) ? auth.audience : null,
+    scopes: normalizeScopeList(auth.scopes || auth.allowedScopes)
+  };
+  if (recommended === TRUSTED_ISSUER) {
+    return {
+      ...base,
+      authorizationServerMetadataUrl: null,
+      clientRegistrationModes: []
+    };
+  }
+  return {
+    ...base,
+    authorizationServerMetadataUrl: auth.authorizationServerMetadataUrl || null,
+    clientRegistrationModes: Array.isArray(auth.clientRegistrationModes)
+      ? [...auth.clientRegistrationModes]
+      : []
+  };
+}
+
+/**
+ * Resolve Runtime MCP Entra scopes — never default to openid/profile/offline_access.
+ * @param {Object} params
+ * @param {string[]} [params.explicitScopes]
+ * @param {Object|null} [params.packageContext]
+ * @param {Object|null} [params.entraProvider]
+ * @returns {string[]}
+ */
+function resolveCopilotEntraScopes(params) {
+  const explicit = normalizeScopeList(params.explicitScopes);
+  if (explicit.length > 0 && !isOpenIdOnlyOrEmptyScopes(explicit)) {
+    return explicit;
+  }
+  const fromProvider = normalizeScopeList(params.entraProvider?.allowedScopes);
+  if (fromProvider.length > 0 && !isOpenIdOnlyOrEmptyScopes(fromProvider)) {
+    return fromProvider;
+  }
+  const auth = params.packageContext?.authentication || null;
+  const fromAuth = normalizeScopeList(auth?.scopes || auth?.allowedScopes);
+  if (fromAuth.length > 0 && !isOpenIdOnlyOrEmptyScopes(fromAuth)) {
+    return fromAuth;
+  }
+  const resource = typeof auth?.resource === 'string' ? auth.resource.trim() : '';
+  if (resource.startsWith('api://')) {
+    return [resource];
+  }
+  return [];
+}
+
+/**
+ * @param {Object} params
+ * @returns {string|null}
+ */
+function firstCopilotEntraBlocker(params) {
+  const {
+    discoveryReady,
+    discoveryBlocker,
+    recommended,
+    referenceId,
+    issuer,
+    audience,
+    scopes
+  } = params;
+  if (!discoveryReady) {
+    return discoveryBlocker || 'remoteMcpUnavailable';
+  }
+  if (recommended !== TRUSTED_ISSUER) {
+    return recommended === CUSTOMER_OAUTH
+      ? 'customerOAuthNotAllowed'
+      : 'trustedIssuerRequired';
+  }
+  if (!referenceId) {
+    return 'oauthPluginVaultReferenceRequired';
+  }
+  if (!issuer) {
+    return 'entraIssuerRequired';
+  }
+  if (!isPresent(audience)) {
+    return 'runtimeMcpAudienceRequired';
+  }
+  if (isOpenIdOnlyOrEmptyScopes(scopes)) {
+    return 'runtimeMcpScopeRequired';
+  }
+  return null;
+}
+
+/**
+ * @param {Object|null} auth
+ * @param {Object|null} entraProvider
+ * @returns {{ audience: * , issuer: string|null }}
+ */
+function resolveAudienceAndIssuer(auth, entraProvider) {
+  const audience = isPresent(entraProvider?.audience)
+    ? entraProvider.audience
+    : isPresent(auth?.audience)
+      ? auth.audience
+      : null;
+  const issuer =
+    (entraProvider && entraProvider.issuer) || (auth && auth.issuer) || null;
+  return { audience, issuer };
+}
+
+/**
+ * @param {Object} params
+ * @returns {{ installReady: boolean, blocker: string|null, packageAuthentication: Object|null }}
+ */
+function evaluateCopilotEntraSsoReadiness(params) {
+  const packageContext = params.packageContext || null;
+  const auth = mapCopilotPackageAuthentication(packageContext?.authentication || null);
+  const recommended = resolveRecommendedCapability(auth);
+  const referenceId =
+    typeof params.oauthPluginVaultReferenceId === 'string'
+      ? params.oauthPluginVaultReferenceId.trim()
+      : '';
+  const scopes = normalizeScopeList(params.scopes);
+  const { audience, issuer } = resolveAudienceAndIssuer(auth, params.entraProvider || null);
+
+  if (auth) {
+    auth.issuer = issuer;
+    auth.audience = audience;
+    auth.scopes = scopes;
+  }
+
+  const blocker = firstCopilotEntraBlocker({
+    discoveryReady: packageContext?.installReady === true,
+    discoveryBlocker: packageContext?.blocker || null,
+    recommended,
+    referenceId,
+    issuer,
+    audience,
+    scopes
+  });
+  return {
+    installReady: blocker === null,
+    blocker,
+    packageAuthentication: auth
+  };
+}
+
+const {
+  formatOauthPluginVaultReferenceRequiredError
+} = require('./microsoft-copilot-entra-sso-form');
+
+/**
+ * @param {Object} [options]
+ * @throws {Error}
+ */
+function assertOauthPluginVaultReferenceId(options = {}) {
+  const ref = options.oauthPluginVaultReferenceId;
+  if (typeof ref === 'string' && ref.trim()) {
+    return;
+  }
+  throw new Error(formatOauthPluginVaultReferenceRequiredError(options.formContext || options));
+}
+
+/**
+ * @param {Object} [runtimeValues]
+ * @throws {Error}
+ */
+function assertCopilotPackageOauthPluginVaultReference(runtimeValues = {}) {
+  const ref = runtimeValues.oauthPluginVaultReferenceId;
+  if (typeof ref === 'string' && ref.trim()) {
+    return;
+  }
+  throw new Error(formatOauthPluginVaultReferenceRequiredError(runtimeValues));
+}
+
+module.exports = {
+  TRUSTED_ISSUER,
+  CUSTOMER_OAUTH,
+  skipsChannelOauthCredential,
+  normalizeScopeList,
+  isOpenIdOnlyOrEmptyScopes,
+  resolveRecommendedCapability,
+  mapCopilotPackageAuthentication,
+  resolveCopilotEntraScopes,
+  evaluateCopilotEntraSsoReadiness,
+  formatOauthPluginVaultReferenceRequiredError,
+  assertOauthPluginVaultReferenceId,
+  assertCopilotPackageOauthPluginVaultReference
+};

package/lib/channels/microsoft-copilot-icons.js

@@ -0,0 +1,74 @@
+/**
+ * Valid Microsoft Teams / Copilot package icons (192×192 color, 32×32 outline).
+ *
+ * Defaults from templates/channels/brand (plan 167.0):
+ * - color-192.png ← light/192 (color app icon)
+ * - outline-32.png ← mono-white/32 (Teams outline)
+ * Variant packs: light/, dark/, mono-white/ at 32–512.
+ *
+ * @fileoverview Loads AI Fabrix brand PNGs from templates/channels/brand
+ * @author AI Fabrix Team
+ * @version 2.1.0
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('../internal/fs-real-sync');
+const { BUILDER_ROOT } = require('./channel-integration-template');
+
+const BRAND_DIR = path.join(BUILDER_ROOT, 'templates', 'channels', 'brand');
+const DEFAULT_COLOR_PATH = path.join(BRAND_DIR, 'color-192.png');
+const DEFAULT_OUTLINE_PATH = path.join(BRAND_DIR, 'outline-32.png');
+
+/**
+ * @param {string} filePath
+ * @returns {Buffer}
+ */
+function readPngFile(filePath) {
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`Brand icon not found: ${filePath}`);
+  }
+  return fs.readFileSync(filePath);
+}
+
+/**
+ * @param {{ colorPath?: string, outlinePath?: string }} [options]
+ * @returns {{ color: Buffer, outline: Buffer }}
+ */
+function getMicrosoftCopilotIcons(options = {}) {
+  const colorPath =
+    typeof options.colorPath === 'string' && options.colorPath.trim()
+      ? options.colorPath.trim()
+      : DEFAULT_COLOR_PATH;
+  const outlinePath =
+    typeof options.outlinePath === 'string' && options.outlinePath.trim()
+      ? options.outlinePath.trim()
+      : DEFAULT_OUTLINE_PATH;
+  return {
+    color: readPngFile(colorPath),
+    outline: readPngFile(outlinePath)
+  };
+}
+
+/**
+ * Read PNG IHDR width/height without external deps.
+ * @param {Buffer} buf
+ * @returns {{ width: number, height: number } | null}
+ */
+function readPngDimensions(buf) {
+  if (!Buffer.isBuffer(buf) || buf.length < 24) return null;
+  if (buf.toString('hex', 0, 8) !== '89504e470d0a1a0a') return null;
+  return {
+    width: buf.readUInt32BE(16),
+    height: buf.readUInt32BE(20)
+  };
+}
+
+module.exports = {
+  getMicrosoftCopilotIcons,
+  readPngDimensions,
+  BRAND_DIR,
+  DEFAULT_COLOR_PATH,
+  DEFAULT_OUTLINE_PATH
+};