@aifabrix/builder 2.45.0 → 2.46.0

package/lib/governance/governance-download-display.js

@@ -0,0 +1,38 @@
+/**
+ * @fileoverview TTY summary when governance download finds no active packs.
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const { failureGlyph } = require('../utils/cli-test-layout-chalk');
+const logger = require('../utils/logger');
+
+/**
+ * @param {Array<{ datasourceKey: string, reason: string }>} missing
+ */
+function printGovernanceDownloadMisses(missing) {
+  if (!missing || missing.length === 0) {
+    return;
+  }
+  for (const row of missing) {
+    logger.log(
+      chalk.white(`${row.datasourceKey}: ${failureGlyph()} ${row.reason}`)
+    );
+  }
+  logger.log('');
+  logger.log(chalk.gray('Next steps:'));
+  logger.log(
+    chalk.gray(
+      '  • Run: aifabrix governance generate <systemKey> --subject-email <email>'
+    )
+  );
+  logger.log(
+    chalk.gray('  • Or use: aifabrix verify-governance <systemKey> --subject-email <email>')
+  );
+  logger.log(chalk.gray('  • Ensure protection is published and identity sync has run'));
+}
+
+module.exports = {
+  printGovernanceDownloadMisses
+};

package/lib/governance/governance-pack-loader.js

@@ -0,0 +1,70 @@
+/**
+ * @fileoverview Load governance scenario pack YAML from integration folder
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+const { getIntegrationPath } = require('../utils/paths');
+
+/**
+ * Resolve pack file path for test-governance.
+ * @param {string} systemKey
+ * @param {Object} options
+ * @param {string} [options.pack] - Explicit path (absolute or relative to integration root)
+ * @param {string} [options.app] - Integration folder override
+ * @returns {string}
+ */
+function resolveGovernancePackPath(systemKey, options = {}) {
+  const integrationPath = options.app
+    ? path.isAbsolute(options.app)
+      ? options.app
+      : path.resolve(process.cwd(), options.app)
+    : getIntegrationPath(systemKey);
+
+  if (options.pack) {
+    const packPath = path.isAbsolute(options.pack)
+      ? options.pack
+      : path.join(integrationPath, options.pack);
+    if (!fs.existsSync(packPath)) {
+      throw new Error(`Scenario pack not found: ${packPath}`);
+    }
+    return packPath;
+  }
+
+  const candidates = [
+    path.join(integrationPath, 'scenarios', 'default.yaml'),
+    path.join(integrationPath, 'scenarios', `${systemKey}-v1.yaml`)
+  ];
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  throw new Error(
+    `No scenario pack found under ${path.join(integrationPath, 'scenarios')}. ` +
+      'Use --pack <path> (e.g. scenarios/test-protection-v1.yaml).'
+  );
+}
+
+/**
+ * @param {string} packPath
+ * @returns {Object}
+ */
+function loadGovernancePackYaml(packPath) {
+  const raw = fs.readFileSync(packPath, 'utf8');
+  const doc = yaml.load(raw);
+  if (!doc || typeof doc !== 'object') {
+    throw new Error(`Invalid scenario pack YAML: ${packPath}`);
+  }
+  return doc;
+}
+
+module.exports = {
+  resolveGovernancePackPath,
+  loadGovernancePackYaml
+};

package/lib/governance/governance-run-display.js

@@ -0,0 +1,309 @@
+/**
+ * @fileoverview TTY display for governance scenario acceptance runs
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const logger = require('../utils/logger');
+const {
+  sectionTitle,
+  headerKeyValue,
+  metadata: metaGray,
+  formatSuccessParagraph,
+  formatBlockingError
+} = require('../utils/cli-test-layout-chalk');
+
+const SEP = '────────────────────────';
+const MAX_SAMPLE_KEYS = 5;
+
+/**
+ * @param {Object|null|undefined} packDocument
+ * @returns {Map<string, { mustIncludeKeys: string[], mustExcludeKeys: string[] }>}
+ */
+function buildScenarioExpectMap(packDocument) {
+  const map = new Map();
+  const scenarios = packDocument?.spec?.scenarios;
+  if (!Array.isArray(scenarios)) {
+    return map;
+  }
+  for (const scenario of scenarios) {
+    if (!scenario || typeof scenario.id !== 'string') {
+      continue;
+    }
+    const expect = scenario.expect || {};
+    map.set(scenario.id, {
+      mustIncludeKeys: Array.isArray(expect.mustIncludeKeys) ? expect.mustIncludeKeys : [],
+      mustExcludeKeys: Array.isArray(expect.mustExcludeKeys) ? expect.mustExcludeKeys : []
+    });
+  }
+  return map;
+}
+
+/**
+ * @param {string[]} keys
+ * @param {number} [maxKeys]
+ * @returns {string}
+ */
+function formatKeySample(keys, maxKeys = MAX_SAMPLE_KEYS) {
+  if (!Array.isArray(keys) || keys.length === 0) {
+    return '—';
+  }
+  const slice = keys.slice(0, maxKeys);
+  const suffix = keys.length > maxKeys ? ` (+${keys.length - maxKeys} more)` : '';
+  return `${slice.join(', ')}${suffix}`;
+}
+
+/**
+ * @param {'pass'|'fail'} status
+ * @returns {string}
+ */
+function scenarioGlyph(status) {
+  return status === 'pass' ? chalk.green('✔') : chalk.red('✖');
+}
+
+/**
+ * @param {import('../api/types/governance-scenarios.types').GovernanceScenarioResult} scenario
+ */
+function logGovernanceScenarioSubjectLines(scenario) {
+  logger.log(`  ${scenarioGlyph(scenario.status)} ${scenario.id}`);
+  logger.log(metaGray(`      Subject email:  ${scenario.subjectEmail || '—'}`));
+  if (scenario.subjectDisplayName) {
+    logger.log(
+      metaGray(
+        `      Subject:        ${scenario.subjectDisplayName} (${scenario.subjectUserId || '—'})`
+      )
+    );
+  }
+  logger.log(metaGray(`      Verdict:        ${scenario.verdict || '—'}`));
+}
+
+/**
+ * @param {import('../api/types/governance-scenarios.types').GovernanceScenarioResult} scenario
+ */
+function logGovernanceScenarioCounts(scenario) {
+  const visible = typeof scenario.visibleKeyCount === 'number' ? scenario.visibleKeyCount : 0;
+  const abac = typeof scenario.excludedAbac === 'number' ? scenario.excludedAbac : 0;
+  const filter = typeof scenario.excludedFilter === 'number' ? scenario.excludedFilter : 0;
+  logger.log(metaGray(`      Visible keys:   ${visible} allowed`));
+  logger.log(metaGray(`      Declined:       ${abac} by ABAC · ${filter} by filter`));
+}
+
+/**
+ * @param {import('../api/types/governance-scenarios.types').GovernanceScenarioResult} scenario
+ * @param {{ mustIncludeKeys: string[], mustExcludeKeys: string[] }} expect
+ */
+function logGovernanceScenarioPassSamples(expect) {
+  const allowed =
+    expect.mustIncludeKeys.length > 0 ? formatKeySample(expect.mustIncludeKeys) : '—';
+  const blocked =
+    expect.mustExcludeKeys.length > 0 ? formatKeySample(expect.mustExcludeKeys) : '—';
+  logger.log(metaGray(`      Sample allowed: ${allowed}`));
+  logger.log(metaGray(`      Sample blocked: ${blocked}`));
+}
+
+/**
+ * @param {import('../api/types/governance-scenarios.types').GovernanceScenarioResult} scenario
+ */
+function logGovernanceScenarioFailSamples(scenario) {
+  if (scenario.missingRequiredKeys?.length) {
+    logger.log(
+      metaGray(`      Missing keys:   ${formatKeySample(scenario.missingRequiredKeys)}`)
+    );
+  }
+  if (scenario.unexpectedVisibleKeys?.length) {
+    logger.log(
+      metaGray(`      Unexpected:     ${formatKeySample(scenario.unexpectedVisibleKeys)}`)
+    );
+  }
+  if (scenario.fixHint) {
+    logger.log(metaGray(`      Fix:            ${scenario.fixHint}`));
+  }
+}
+
+/**
+ * @param {import('../api/types/governance-scenarios.types').GovernanceScenarioResult} scenario
+ * @param {Map<string, { mustIncludeKeys: string[], mustExcludeKeys: string[] }>} expectMap
+ */
+function logGovernanceScenarioDetail(scenario, expectMap) {
+  const expect = expectMap.get(scenario.id) || {
+    mustIncludeKeys: [],
+    mustExcludeKeys: []
+  };
+  logGovernanceScenarioSubjectLines(scenario);
+  logGovernanceScenarioCounts(scenario);
+  if (scenario.status === 'pass') {
+    logGovernanceScenarioPassSamples(expect);
+  } else {
+    logGovernanceScenarioFailSamples(scenario);
+  }
+  if (scenario.subjectGroups?.length) {
+    logger.log(metaGray(`      Groups:         ${scenario.subjectGroups.join(', ')}`));
+  }
+  if (scenario.auditRef) {
+    logger.log(metaGray(`      Audit:          ${scenario.auditRef}`));
+  }
+}
+
+/**
+ * One datasource block for verify-governance -v.
+ * @param {Object} row
+ * @param {string} row.datasourceKey
+ * @param {Object} [row.result]
+ * @param {Object} [row.packDocument]
+ * @param {string} [row.packPath]
+ * @param {string} [row.error]
+ */
+function displayGovernanceDatasourceVerbose(row) {
+  logger.log('');
+  logger.log(chalk.white(`Datasource: ${row.datasourceKey}`));
+  if (row.error) {
+    logger.log(formatBlockingError(row.error));
+    return;
+  }
+  const run = row.result;
+  if (!run || !run.summary) {
+    logger.log(metaGray('  No scenario run result (pack missing or run skipped).'));
+    return;
+  }
+  logger.log(headerKeyValue('Pack:', run.packKey || '—'));
+  if (row.packPath) {
+    logger.log(metaGray(`  File: ${row.packPath}`));
+  }
+  const summary = run.summary;
+  logger.log(
+    headerKeyValue('Scenarios:', `${summary.passed || 0}/${summary.total || 0} passed`)
+  );
+  const expectMap = buildScenarioExpectMap(row.packDocument);
+  for (const scenario of run.scenarios || []) {
+    logGovernanceScenarioDetail(scenario, expectMap);
+  }
+}
+
+/**
+ * Verbose (-v) scenario breakdown for verify-governance / governance verify.
+ * @param {Object} result
+ */
+function displayGovernanceVerboseDetails(result) {
+  if (!result) {
+    return;
+  }
+  logger.log('');
+  logger.log(chalk.white('Scenario results'));
+  logger.log(metaGray(SEP));
+  logger.log(metaGray('Key sets only — no record payloads.'));
+
+  if (result.legacyResult && result.legacyResult.summary) {
+    const dsKey =
+      result.packDatasourceKey ||
+      primaryDatasourceFromPack(result.packDocument) ||
+      'scenario pack';
+    displayGovernanceDatasourceVerbose({
+      datasourceKey: dsKey,
+      result: result.legacyResult,
+      packDocument: result.packDocument,
+      packPath: result.packPath
+    });
+    logger.log('');
+    return;
+  }
+
+  const rows = result.datasourceRows || [];
+  if (rows.length === 0) {
+    logger.log(metaGray('  No datasource scenario packs were run.'));
+    logger.log('');
+    return;
+  }
+  for (const row of rows) {
+    displayGovernanceDatasourceVerbose(row);
+  }
+  logger.log('');
+}
+
+/**
+ * @param {string} systemKey
+ * @param {import('../api/types/governance-scenarios.types').GovernanceScenariosRunResponse} result
+ * @param {{ verbose?: boolean, packPath?: string }} opts
+ */
+function displayGovernanceRunTTY(systemKey, result, opts = {}) {
+  const agg = result.summary.failed > 0 ? 'fail' : 'ok';
+  logger.log(SEP);
+  logger.log(sectionTitle('Governed search acceptance (key sets only — no record payload)'));
+  logger.log(headerKeyValue('System:', systemKey));
+  logger.log(headerKeyValue('Pack:', result.packKey));
+  if (opts.packPath) {
+    logger.log(metaGray(`  File: ${opts.packPath}`));
+  }
+  logger.log(
+    headerKeyValue(
+      'Summary:',
+      `${result.summary.passed}/${result.summary.total} passed`
+    )
+  );
+  logger.log(metaGray('  Does not call vendor APIs (use test-e2e for connectivity).'));
+  logger.log('');
+  const expectMap = buildScenarioExpectMap(opts.packDocument);
+  for (const scenario of result.scenarios || []) {
+    if (opts.verbose === true) {
+      logGovernanceScenarioDetail(scenario, expectMap);
+    } else {
+      logger.log(`  ${scenarioGlyph(scenario.status)} ${scenario.verdict}`);
+    }
+  }
+  logger.log('');
+  if (agg === 'ok') {
+    logger.log(formatSuccessParagraph('All governance scenarios passed'));
+  } else {
+    logger.log(formatBlockingError(`${result.summary.failed} scenario(s) failed`));
+  }
+  logger.log(SEP);
+}
+
+/**
+ * @param {import('../api/types/governance-scenarios.types').GovernanceScenariosRunResponse} result
+ */
+function printGovernanceRunJson(result) {
+  logger.log(JSON.stringify(result, null, 2));
+}
+
+/**
+ * @param {{ total: number, passed: number, failed: number }} summary
+ * @returns {number}
+ */
+function exitCodeFromGovernanceSummary(summary) {
+  if (!summary || summary.failed > 0) {
+    return 1;
+  }
+  return 0;
+}
+
+/**
+ * @param {Object|null|undefined} packDocument
+ * @returns {string|null}
+ */
+function primaryDatasourceFromPack(packDocument) {
+  const scenarios = packDocument?.spec?.scenarios;
+  if (!Array.isArray(scenarios)) {
+    return null;
+  }
+  for (const scenario of scenarios) {
+    const keys = scenario?.search?.datasourceKeys;
+    if (Array.isArray(keys) && keys.length > 0 && typeof keys[0] === 'string') {
+      return keys[0];
+    }
+  }
+  return null;
+}
+
+module.exports = {
+  buildScenarioExpectMap,
+  formatKeySample,
+  displayGovernanceDatasourceVerbose,
+  displayGovernanceVerboseDetails,
+  displayGovernanceRunTTY,
+  printGovernanceRunJson,
+  exitCodeFromGovernanceSummary,
+  primaryDatasourceFromPack
+};

package/lib/identity/identity-apply-core.js

@@ -0,0 +1,108 @@
+/**
+ * @fileoverview Shared helpers for identity apply
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { getUser, listUsers } = require('../api/users.api');
+
+/**
+ * @param {Object} response
+ * @returns {any}
+ */
+function unwrapControllerData(response) {
+  if (!response || response.success === false) {
+    return null;
+  }
+  return response?.data?.data ?? response?.data ?? response;
+}
+
+/**
+ * @param {Object} response
+ * @returns {string}
+ */
+function apiErrorMessage(response) {
+  if (!response) {
+    return 'Request failed';
+  }
+  const err = response.error;
+  if (typeof err === 'string') {
+    return err;
+  }
+  if (err && typeof err === 'object') {
+    return err.formattedError || err.message || err.error || 'Request failed';
+  }
+  return response.formattedError || response.message || 'Request failed';
+}
+
+/**
+ * @param {Object} response
+ * @throws {Error}
+ */
+function throwIfApiFailed(response) {
+  if (!response || response.success === false) {
+    throw new Error(apiErrorMessage(response));
+  }
+}
+
+/**
+ * @param {Object|null|undefined} stats
+ * @param {{ allowEmptySync?: boolean }} [opts]
+ * @throws {Error}
+ */
+function assertSyncStatsOk(stats, opts = {}) {
+  const syncErrors = Number(stats?.errors ?? 0);
+  if (syncErrors > 0) {
+    throw new Error(
+      `Dataplane full sync reported ${syncErrors} error(s). ` +
+        `usersProcessed=${stats?.usersProcessed ?? 0} groupsProcessed=${stats?.groupsProcessed ?? 0}. ` +
+        'Check miso-controller logs for the sync request.'
+    );
+  }
+  const processed = Number(stats?.usersProcessed ?? 0);
+  if (processed === 0 && !opts.allowEmptySync) {
+    throw new Error(
+      'Dataplane full sync completed with usersProcessed=0. Use --allow-empty-sync to accept, or fix identity on the controller.'
+    );
+  }
+}
+
+/**
+ * @async
+ * @param {string} controllerUrl
+ * @param {Object} authConfig
+ * @param {{ csvId?: string, email: string }} userSpec
+ * @returns {Promise<Object|null>}
+ */
+async function findExistingUser(controllerUrl, authConfig, userSpec) {
+  const csvId = String(userSpec.csvId || '').trim();
+  if (csvId) {
+    const byId = await getUser(controllerUrl, authConfig, csvId);
+    const row = unwrapControllerData(byId);
+    if (row && row.id) {
+      return row;
+    }
+  }
+  const email = String(userSpec.email || '').trim();
+  const listed = await listUsers(controllerUrl, authConfig, {
+    search: email,
+    pageSize: 10,
+    page: 1
+  });
+  const items = unwrapControllerData(listed);
+  const list = Array.isArray(items) ? items : items?.data;
+  if (!Array.isArray(list)) {
+    return null;
+  }
+  return list.find((u) => String(u.email || '').toLowerCase() === email.toLowerCase()) || null;
+}
+
+module.exports = {
+  unwrapControllerData,
+  apiErrorMessage,
+  throwIfApiFailed,
+  assertSyncStatsOk,
+  findExistingUser
+};