@aifabrix/builder 2.52.0 → 2.52.1

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

@@ -0,0 +1,197 @@
+/**
+ * Validate Microsoft Copilot package source files before ZIP.
+ *
+ * @fileoverview Schema-oriented checks for Teams + declarative agent + AI plugin manifests
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const {
+  TEAMS_NAME_SHORT_MAX,
+  TEAMS_NAME_FULL_MAX,
+  TEAMS_DESCRIPTION_SHORT_MAX,
+  TEAMS_DESCRIPTION_FULL_MAX,
+  PLUGIN_NAME_FOR_HUMAN_MAX,
+  PLUGIN_DESCRIPTION_FOR_HUMAN_MAX
+} = require('./microsoft-copilot-limits');
+const { readPngDimensions } = require('./microsoft-copilot-icons');
+
+const ALLOWED_AUTH_TYPES = new Set(['None', 'OAuthPluginVault', 'ApiKeyPluginVault']);
+
+/**
+ * @param {unknown} value
+ * @param {string} label
+ * @param {number} max
+ * @param {string[]} errors
+ */
+function assertMaxLength(value, label, max, errors) {
+  if (typeof value !== 'string') {
+    errors.push(`${label} must be a string`);
+    return;
+  }
+  if (value.length > max) {
+    errors.push(`${label} exceeds ${max} characters (got ${value.length})`);
+  }
+}
+
+/**
+ * @param {Record<string, string>} sourceFiles
+ * @returns {{ manifest: Object|null, agent: Object|null, plugin: Object|null, errors: string[] }}
+ */
+function parsePackageJsonFiles(sourceFiles) {
+  const errors = [];
+  const parsed = { manifest: null, agent: null, plugin: null };
+  try {
+    parsed.manifest = JSON.parse(sourceFiles['manifest.json'] || '');
+  } catch {
+    errors.push('manifest.json is not valid JSON');
+  }
+  try {
+    parsed.agent = JSON.parse(sourceFiles['declarativeAgent.json'] || '');
+  } catch {
+    errors.push('declarativeAgent.json is not valid JSON');
+  }
+  try {
+    parsed.plugin = JSON.parse(sourceFiles['ai-plugin.json'] || '');
+  } catch {
+    errors.push('ai-plugin.json is not valid JSON');
+  }
+  return { ...parsed, errors };
+}
+
+/**
+ * @param {Object|null} manifest
+ * @param {string[]} errors
+ */
+function validateTeamsManifest(manifest, errors) {
+  if (!manifest) return;
+  assertMaxLength(manifest?.name?.short, 'manifest.name.short', TEAMS_NAME_SHORT_MAX, errors);
+  assertMaxLength(manifest?.name?.full, 'manifest.name.full', TEAMS_NAME_FULL_MAX, errors);
+  assertMaxLength(
+    manifest?.description?.short,
+    'manifest.description.short',
+    TEAMS_DESCRIPTION_SHORT_MAX,
+    errors
+  );
+  assertMaxLength(
+    manifest?.description?.full,
+    'manifest.description.full',
+    TEAMS_DESCRIPTION_FULL_MAX,
+    errors
+  );
+  if (!manifest.copilotAgents?.declarativeAgents?.length) {
+    errors.push('manifest.copilotAgents.declarativeAgents is required');
+  }
+}
+
+/**
+ * @param {Object|null} agent
+ * @param {string[]} errors
+ */
+function validateDeclarativeAgent(agent, errors) {
+  if (!agent) return;
+  if (agent.version !== 'v1.4') {
+    errors.push('declarativeAgent.version must be "v1.4"');
+  }
+  if (!agent.id || !agent.name || !agent.description || !agent.instructions) {
+    errors.push('declarativeAgent requires id, name, description, and instructions');
+  }
+}
+
+/**
+ * @param {Object|null} plugin
+ * @param {string[]} errors
+ */
+function validateAiPlugin(plugin, errors) {
+  if (!plugin) return;
+  if (plugin.schema_version !== 'v2.4') {
+    errors.push('ai-plugin.schema_version must be "v2.4"');
+  }
+  assertMaxLength(plugin.name_for_human, 'ai-plugin.name_for_human', PLUGIN_NAME_FOR_HUMAN_MAX, errors);
+  assertMaxLength(
+    plugin.description_for_human,
+    'ai-plugin.description_for_human',
+    PLUGIN_DESCRIPTION_FOR_HUMAN_MAX,
+    errors
+  );
+  if (!plugin.namespace || !/^[A-Za-z0-9-]+$/.test(plugin.namespace)) {
+    errors.push('ai-plugin.namespace is required (alphanumeric and hyphen only)');
+  }
+  validateAiPluginRuntime(plugin, errors);
+}
+
+/**
+ * @param {Object} plugin
+ * @param {string[]} errors
+ */
+function validateAiPluginRuntime(plugin, errors) {
+  const runtime = Array.isArray(plugin.runtimes) ? plugin.runtimes[0] : null;
+  if (!runtime || runtime.type !== 'RemoteMCPServer') {
+    errors.push('ai-plugin.runtimes[0].type must be RemoteMCPServer');
+    return;
+  }
+  if (!ALLOWED_AUTH_TYPES.has(runtime.auth?.type)) {
+    errors.push(
+      `ai-plugin.runtimes[0].auth.type must be one of ${[...ALLOWED_AUTH_TYPES].join(', ')}`
+    );
+  }
+  if (runtime.auth?.type === 'OAuthPluginVault') {
+    const ref = runtime.auth.reference_id;
+    if (typeof ref !== 'string' || !ref.trim()) {
+      errors.push(
+        'OAuthPluginVault.reference_id is required — pass --oauth-plugin-vault-reference-id ' +
+          'with the Teams Developer Portal Entra SSO auth-config id'
+      );
+    }
+  }
+  if (runtime.auth?.type === 'None') {
+    errors.push(
+      'ai-plugin.runtimes[0].auth.type None is not allowed; use OAuthPluginVault (Microsoft token / Entra)'
+    );
+  }
+  const desc = runtime.spec?.mcp_tool_description;
+  if (desc && (desc.mode || desc.layerBToolNames)) {
+    errors.push(
+      'ai-plugin mcp_tool_description must not use mode/layerBToolNames; omit for dynamic discovery or use tools/file'
+    );
+  }
+}
+
+/**
+ * @param {{ color: Buffer, outline: Buffer }} icons
+ * @param {string[]} errors
+ */
+function validatePackageIcons(icons, errors) {
+  const colorDims = readPngDimensions(icons.color);
+  const outlineDims = readPngDimensions(icons.outline);
+  if (!colorDims || colorDims.width !== 192 || colorDims.height !== 192) {
+    errors.push('color.png must be a 192x192 PNG');
+  }
+  if (!outlineDims || outlineDims.width !== 32 || outlineDims.height !== 32) {
+    errors.push('outline.png must be a 32x32 PNG');
+  }
+}
+
+/**
+ * @param {Record<string, string>} sourceFiles
+ * @param {{ color: Buffer, outline: Buffer }} icons
+ * @throws {Error}
+ */
+function assertValidMicrosoftCopilotPackage(sourceFiles, icons) {
+  const parsed = parsePackageJsonFiles(sourceFiles);
+  const errors = [...parsed.errors];
+  validateTeamsManifest(parsed.manifest, errors);
+  validateDeclarativeAgent(parsed.agent, errors);
+  validateAiPlugin(parsed.plugin, errors);
+  validatePackageIcons(icons, errors);
+  if (errors.length) {
+    throw new Error(`Microsoft Copilot package validation failed:\n- ${errors.join('\n- ')}`);
+  }
+}
+
+module.exports = {
+  assertValidMicrosoftCopilotPackage,
+  ALLOWED_AUTH_TYPES
+};

package/lib/cli/index.js

@@ -67,6 +67,8 @@ function setupCoreCliCommands(program) {
   setupChannelCommands(program);
   setupDatasourceCommands(program);
   setupManifestCommands(program);
+  const { setupIntegrationDefinitionCommands } = require('../commands/integration-definition');
+  setupIntegrationDefinitionCommands(program);
 }
 
 /**

package/lib/cli/infra-guided.js

@@ -331,23 +331,30 @@ async function runGuidedDownInfra(appName, options, infraMod, appLib) {
   logger.log(SEPARATOR);
   logger.log('');
 
+  const targetDeveloperId = options && options.developerId;
   const spin = startSpinner('Stopping infrastructure...');
   await withMutedLogger(async() => {
     if (typeof appName === 'string' && appName.trim().length > 0) {
-      await appLib.downApp(appName, { volumes: !!options.volumes });
+      await appLib.downApp(appName, {
+        volumes: !!options.volumes,
+        developerId: targetDeveloperId
+      });
       return;
     }
-    if (options.volumes) await infraMod.stopInfraWithVolumes();
-    else await infraMod.stopInfra();
+    if (options.volumes) await infraMod.stopInfraWithVolumes(targetDeveloperId);
+    else await infraMod.stopInfra(targetDeveloperId);
   });
   stopSpinnerSuccess(spin, 'Infrastructure stopped');
 
-  const developerId = await config.getDeveloperId();
-  const idNum = typeof developerId === 'string' ? parseInt(developerId, 10) : developerId;
+  const developerId = String(
+    targetDeveloperId !== undefined && targetDeveloperId !== null && targetDeveloperId !== ''
+      ? targetDeveloperId
+      : await config.getDeveloperId()
+  );
   const cfg = await config.getConfig();
 
   logFooterStart('Stopped');
-  logSection('Developer', `dev${String(idNum).padStart(2, '0')} (id: ${idNum})`);
+  logSection('Developer', `dev${developerId.padStart(2, '0')} (id: ${developerId})`);
   logStoppedServices(cfg);
   if (options.volumes) {
     logger.log(chalk.yellow('⚠ Volumes removed: all local data deleted'));

package/lib/cli/setup-infra.js

@@ -31,6 +31,9 @@ const {
   getRestartableInfraServiceNames,
   buildRestartInfraHelpLines
 } = require('../constants/infra-compose-service-names');
+const {
+  resolveTransientDeveloperIdFromOptions
+} = require('../utils/transient-developer-id');
 
 const {
   computeEffectiveInfraOptionalFlags,
@@ -97,6 +100,18 @@ async function applyDeveloperIdFromUpInfra(options) {
   return id;
 }
 
+const DOWN_INFRA_HELP_AFTER = `
+Examples:
+  $ aifabrix down-infra
+  $ aifabrix down-infra --volumes
+  $ aifabrix down-infra --developer-id 02
+  $ aifabrix down-infra -d 02 --volumes
+  $ aifabrix down-infra myapp --developer-id 02
+
+--developer-id / -d target another developer's stack for this command only.
+They do not change developer-id in config.
+`;
+
 /**
  * @param {Object} options
  * @param {Object} cfg - Mutable config from getConfig()
@@ -302,20 +317,32 @@ function setupUpBuilderApiCommand(program) {
 function setupDownInfraCommand(program) {
   program.command('down-infra [service|app]')
     .description('Stop all infra, or stop one app; use -v to remove volumes')
+    .addHelpText('after', DOWN_INFRA_HELP_AFTER)
     .option('-v, --volumes', 'Remove volumes (deletes all data)')
     .option('--verbose', 'Show full orchestration output (default is guided summary)')
+    .option(
+      '-d, --developer <id>',
+      'Target developer ID for this stop only (does not change config)'
+    )
+    .option(
+      '--developer-id <id>',
+      'Same as --developer; target another developer without changing config'
+    )
     .action(async(appName, options) => {
       try {
+        const developerId = resolveTransientDeveloperIdFromOptions(options);
+        const opts = { ...options, developerId };
         if (!options.verbose) {
-          await runGuidedDownInfra(appName, options, infra, appLib);
+          await runGuidedDownInfra(appName, opts, infra, appLib);
           return;
         }
 
         if (typeof appName === 'string' && appName.trim().length > 0) {
-          await appLib.downApp(appName, { volumes: !!options.volumes });
+          await appLib.downApp(appName, { volumes: !!options.volumes, developerId });
+        } else if (options.volumes) {
+          await infra.stopInfraWithVolumes(developerId);
         } else {
-          if (options.volumes) await infra.stopInfraWithVolumes();
-          else await infra.stopInfra();
+          await infra.stopInfra(developerId);
         }
       } catch (error) {
         handleCommandError(error, 'down-infra');

package/lib/commands/channel-add-setup.js

@@ -18,26 +18,36 @@ const { addChannelCommand } = require('../channels/add-channel');
 const CHANNEL_ADD_HELP_AFTER = `
 ${formatSupportedChannelTargetsHelp()}
 
+One command covers scaffold → upload → install:
+  $ aifabrix channel add slack --name "Elsa" --probe
+
 Examples:
-  # After upload/deploy of the communication external system
   $ aifabrix channel add slack --name "Elsa"
   $ aifabrix channel add teams-bot --name "Elsa" --description "Enterprise AI assistant for employees"
   $ aifabrix channel add chatgpt --name "Your Assistant"
-  $ aifabrix channel add microsoft-copilot --name "Your Assistant"
+  $ aifabrix channel add microsoft-copilot --name "Your Assistant" \\
+      --oauth-plugin-vault-reference-id "<Teams-Entra-SSO-auth-config-id>"
 
   # Slack slash-command prefix (registers /{prefix}-help in manifest)
   $ aifabrix channel add slack --name "Elsa" --command-prefix af
 
-  # Generate artifacts only; no dataplane patch
+  # Generate artifacts only; no dataplane patch / upload
   $ aifabrix channel add slack --name "Elsa" --dry-run
 
-  # Regenerate artifacts and patch config (does not rotate secrets)
+  # Re-upload communication system + regenerate channel config (does not rotate secrets)
   $ aifabrix channel add slack --name "Elsa" --force
 
   # Validate callbacks and assistant catalog after install
   $ aifabrix channel add slack --name "Elsa" --probe
 
-Prerequisites: aifabrix upload <target> (or deploy) and aifabrix login
+Behavior:
+  - Scaffolds integration/<target>/ when missing (does not overwrite existing files)
+  - Uploads when the system is not on the dataplane; with --force uploads every time
+  - Then configures the channel install (artifacts, credentials, admin guide)
+  - microsoft-copilot uses Entra SSO (trustedIssuer); pass --oauth-plugin-vault-reference-id
+    from Teams Developer Portal. Does not create Fabrix oauth2 channel credentials.
+
+Requires: aifabrix login
 `;
 
 /**
@@ -64,6 +74,7 @@ async function runChannelAddAction(channelTarget, options, meta = {}) {
     icon: options.icon,
     template: options.template,
     commandPrefix: options.commandPrefix,
+    oauthPluginVaultReferenceId: options.oauthPluginVaultReferenceId,
     dryRun: options.dryRun === true,
     force: options.force === true,
     probe: options.probe === true
@@ -77,7 +88,7 @@ async function runChannelAddAction(channelTarget, options, meta = {}) {
  */
 function registerChannelAddCommand(parent, meta = {}) {
   const description =
-    'Configure channel install (manifest, credentials, admin guide) after upload/deploy';
+    'Scaffold (if needed), upload (if needed/--force), then configure channel install';
   const commandName = meta.commandName || 'add <channelTarget>';
   const cmd = meta.hidden
     ? parent.command(commandName, { hidden: true })
@@ -88,12 +99,19 @@ function registerChannelAddCommand(parent, meta = {}) {
     .option('-d, --description <text>', 'Channel description (default generated)')
     .option('--icon <path>', 'Path to channel icon asset')
     .option('--template <name>', 'Template override (default from channel target)')
-    .option('--dry-run', 'Generate artifacts only; do not patch external system or credentials')
-    .option('--force', 'Regenerate artifacts and patch config (does not rotate secrets)')
+    .option('--dry-run', 'Generate artifacts only; do not upload, patch, or set credentials')
+    .option(
+      '--force',
+      'Re-upload communication system and regenerate channel config (does not rotate secrets)'
+    )
     .option(
       '--command-prefix <key>',
       'Slack slash alias prefix (default af) — registers /{prefix}-help etc. in manifest'
     )
+    .option(
+      '--oauth-plugin-vault-reference-id <id>',
+      'Teams Developer Portal Entra SSO OAuth auth-config id (microsoft-copilot)'
+    )
     .option('--probe', 'After install, validate callbacks and assistant catalog')
     .addHelpText('after', CHANNEL_ADD_HELP_AFTER)
     .action(async(channelTarget, options) => {
@@ -101,7 +119,8 @@ function registerChannelAddCommand(parent, meta = {}) {
         await runChannelAddAction(channelTarget, options, meta);
       } catch (error) {
         if (!error.message?.includes('Authentication required')) {
-          logger.error(formatBlockingError('Channel install failed:'), error.message);
+          const detail = error.message || String(error);
+          logger.error(formatBlockingError(`Channel install failed:\n${detail}`));
         }
         process.exit(1);
       }

package/lib/commands/channel.js

@@ -25,15 +25,20 @@ const { registerChannelAddCommand } = require('./channel-add-setup');
 
 const CHANNEL_HELP_AFTER = `
 Subcommands:
-  scaffold <target>   Create integration/<target>/ files locally (step 1)
-  add <target>        Channel install guide + manifest/credential patch (step 3)
+  add <target>        One command: scaffold (if needed) → upload (if needed/--force) → install
+  scaffold <target>   Optional: create integration/<target>/ files only (local)
 
 ${formatSupportedChannelTargetsHelp()}
 
-Typical flow (channels are connected systems, not controller apps):
+Typical flow:
+  aifabrix channel add slack --name "Elsa" --probe
+
+  # Force re-upload of the communication system, then reinstall channel
+  aifabrix channel add slack --name "Elsa" --force --probe
+
+Optional low-level steps (usually unnecessary):
   aifabrix channel scaffold slack
   aifabrix upload slack --force
-  aifabrix channel add slack --name "Elsa" --probe
 
 Controller pipeline apps only: aifabrix app register · aifabrix app list
 
@@ -43,10 +48,10 @@ Requires: aifabrix login (for add)
 const CHANNEL_SCAFFOLD_HELP_AFTER = `
 ${formatSupportedChannelTargetsHelp()}
 
-Typical flow:
-  aifabrix channel scaffold slack
-  aifabrix upload slack --force
+Prefer one command (scaffold + upload + install):
   aifabrix channel add slack --name "Your Assistant" --probe
+
+scaffold alone only writes local files under integration/<target>/.
 `;
 
 /**
@@ -56,7 +61,7 @@ function setupChannelCommands(program) {
   const channel = program
     .command('channel')
     .description(
-      'Assistant channels (Slack, Teams, Copilot, ChatGPT) — scaffold integration and install'
+      'Assistant channels — one-command add (scaffold → upload → install), plus optional scaffold'
     )
     .addHelpText('after', CHANNEL_HELP_AFTER);
 
@@ -86,8 +91,7 @@ function setupChannelCommands(program) {
           logger.log(metadata(file));
         }
         logger.log('');
-        logger.log(chalk.white('Next steps:'));
-        logger.log(chalk.gray(`  aifabrix upload ${channelTarget} --force`));
+        logger.log(chalk.white('Next step (recommended):'));
         logger.log(
           chalk.gray(`  aifabrix channel add ${channelTarget} --name "Your Assistant" --probe`)
         );

package/lib/commands/integration-definition.js

@@ -0,0 +1,158 @@
+/**
+ * CLI: integration-definition validate | apply
+ * @fileoverview BT → Builder BID commands (no section PATCH orchestration)
+ */
+
+'use strict';
+
+/* eslint-disable no-console */
+
+const chalk = require('chalk');
+const fs = require('fs');
+const path = require('path');
+const {
+  applyIntegrationDefinition,
+  validateIntegrationDefinition,
+  withDefinitionHash
+} = require('../integration-definition');
+const { handleCommandError } = require('../utils/cli-utils');
+const {
+  formatSuccessLine,
+  formatBlockingError,
+  failureGlyph
+} = require('../utils/cli-layout-chalk');
+
+const PARENT_HELP_AFTER = `
+
+Examples:
+  $ aifabrix integration-definition validate ./bid.json
+  $ aifabrix integration-definition apply ./bid.json --dry-run
+
+BID is the minimal business create language (systemKind, resourceType, propertyKeys).
+Apply materializes integration/<systemKey>/ package files (EDS/system).
+AI catalog: GET /help?topic=resourceTypeCatalog on builder-api.
+`;
+
+const VALIDATE_HELP_AFTER = `
+
+Examples:
+  $ aifabrix integration-definition validate ./bid.json
+  $ aifabrix integration-definition validate ./bid.json --fix-hash
+
+Checks JSON Schema, definitionHash, product rules, and active resourceType catalog keys.
+`;
+
+const APPLY_HELP_AFTER = `
+
+Examples:
+  $ aifabrix integration-definition apply ./bid.json
+  $ aifabrix integration-definition apply ./bid.json --dry-run
+  $ aifabrix integration-definition apply ./bid.json --force
+  $ aifabrix integration-definition apply ./bid.json --output-dir /tmp/out
+`;
+
+/**
+ * @param {string} filePath
+ * @returns {Record<string, unknown>}
+ */
+function loadBidFile(filePath) {
+  const abs = path.resolve(filePath);
+  if (!fs.existsSync(abs)) {
+    throw new Error(`BID file not found: ${abs}`);
+  }
+  return JSON.parse(fs.readFileSync(abs, 'utf8'));
+}
+
+/**
+ * @param {string} file
+ * @param {{ fixHash?: boolean }} options
+ * @returns {Promise<void>}
+ */
+async function runValidateCommand(file, options) {
+  let bid = loadBidFile(file);
+  if (options.fixHash) {
+    bid = withDefinitionHash(bid);
+    fs.writeFileSync(path.resolve(file), `${JSON.stringify(bid, null, 2)}\n`, 'utf8');
+    console.log(formatSuccessLine(`Wrote definitionHash to ${file}`));
+  }
+  const result = validateIntegrationDefinition(bid);
+  if (!result.valid) {
+    console.error(formatBlockingError('BID invalid'));
+    for (const err of result.errors) {
+      console.error(chalk.red(`  ${failureGlyph()} ${err}`));
+    }
+    process.exit(1);
+  }
+  console.log(formatSuccessLine('BID valid'));
+  console.log(`  definitionId: ${result.bid.definitionId}`);
+  console.log(`  definitionHash: ${result.bid.definitionHash}`);
+}
+
+/**
+ * @param {string} file
+ * @param {{ outputDir?: string, dryRun?: boolean, force?: boolean }} options
+ * @returns {Promise<void>}
+ */
+async function runApplyCommand(file, options) {
+  const bid = loadBidFile(file);
+  const out = await applyIntegrationDefinition(bid, {
+    outputDir: options.outputDir,
+    dryRun: Boolean(options.dryRun),
+    force: Boolean(options.force)
+  });
+  console.log(formatSuccessLine(`BID apply ${out.status}`));
+  console.log(`  systemKey: ${out.systemKey}`);
+  console.log(`  outputDir: ${out.outputDir}`);
+  console.log(`  definitionHash: ${out.definitionHash}`);
+  if (out.files) {
+    console.log(`  files: ${out.files.join(', ')}`);
+  }
+}
+
+/**
+ * @param {import('commander').Command} program
+ */
+function setupIntegrationDefinitionCommands(program) {
+  const cmd = program
+    .command('integration-definition')
+    .description(
+      'Validate or apply a Builder Integration Definition (BID) — minimal business create language for integration packages'
+    )
+    .addHelpText('after', PARENT_HELP_AFTER);
+
+  cmd
+    .command('validate <file>')
+    .description(
+      'Validate BID JSON (schema, definitionHash, product rules, resourceType catalog)'
+    )
+    .option('--fix-hash', 'Rewrite file with computed definitionHash')
+    .addHelpText('after', VALIDATE_HELP_AFTER)
+    .action(async(file, options) => {
+      try {
+        await runValidateCommand(file, options);
+      } catch (error) {
+        handleCommandError(error, 'integration-definition validate');
+      }
+    });
+
+  cmd
+    .command('apply <file>')
+    .description(
+      'Idempotently apply BID to integration/<systemKey>/ (Builder-owned EDS/system writes)'
+    )
+    .option('--output-dir <dir>', 'Override output directory')
+    .option('--force', 'Rewrite package even when definitionHash matches stamp')
+    .option('--dry-run', 'Show planned files without writing')
+    .addHelpText('after', APPLY_HELP_AFTER)
+    .action(async(file, options) => {
+      try {
+        await runApplyCommand(file, options);
+      } catch (error) {
+        handleCommandError(error, 'integration-definition apply');
+      }
+    });
+}
+
+module.exports = {
+  setupIntegrationDefinitionCommands
+};

package/lib/commands/repair-auth-apply.js

@@ -28,6 +28,7 @@ const ALLOWED_REPAIR_AUTH = [
   'oidc',
   'hmac',
   'none',
+  'system',
   'bearerforward'
 ];
 
@@ -57,8 +58,12 @@ function isAllowedRepairAuth(authOption) {
  */
 function buildAuthenticationForRepair(systemKey, authOption) {
   const normalized = normalizeRepairAuthOption(authOption);
+  if (normalized === 'system') {
+    return buildSystemAuthentication();
+  }
   if (normalized === 'bearerforward') {
-    return buildBearerForwardAuthentication();
+    // Legacy alias: prefer authType system for platform facades.
+    return buildSystemAuthentication();
   }
   const schemaMethod =
     normalized === 'queryparam'
@@ -70,11 +75,19 @@ function buildAuthenticationForRepair(systemKey, authOption) {
 }
 
 /**
- * Facade APIs that forward the caller Bearer token — no workspace kv secret.
- * @returns {{ authType: 'none' }}
+ * Platform-managed downstream authentication (no workspace kv secret).
+ * @returns {{ authType: 'system' }}
+ */
+function buildSystemAuthentication() {
+  return { authType: 'system' };
+}
+
+/**
+ * @deprecated Use buildSystemAuthentication — bearerForward is not a public authType.
+ * @returns {{ authType: 'system' }}
  */
 function buildBearerForwardAuthentication() {
-  return { authType: 'none' };
+  return buildSystemAuthentication();
 }
 
 /**
@@ -99,7 +112,7 @@ function mergePreservedAuthVariables(mergedVariables, existingVars) {
 function repairAuthChangeLabel(authOption) {
   const normalized = normalizeRepairAuthOption(authOption);
   if (normalized === 'bearertoken' || normalized === 'bearerkey') return 'bearerToken';
-  if (normalized === 'bearerforward') return 'bearerForward';
+  if (normalized === 'bearerforward') return 'system';
   return normalized;
 }
 
@@ -157,6 +170,7 @@ module.exports = {
   normalizeRepairAuthOption,
   isAllowedRepairAuth,
   buildAuthenticationForRepair,
+  buildSystemAuthentication,
   buildBearerForwardAuthentication,
   mergePreservedAuthVariables,
   repairAuthChangeLabel,