@aifabrix/builder 2.54.1 → 2.55.2

package/lib/utils/api.js

@@ -98,7 +98,12 @@ function parseErrorText(errorText, status, statusText) {
 async function handleErrorResponse(response, url, options, duration) {
   const errorText = await response.text();
   const errorData = parseErrorText(errorText, response.status, response.statusText);
-  const parsedError = parseErrorResponse(errorData, response.status, false);
+  const { enrichForbiddenErrorData } = require('./api-required-permissions');
+  const parsedError = parseErrorResponse(enrichForbiddenErrorData(errorData, {
+    status: response.status,
+    method: options && options.method,
+    url
+  }), response.status, false);
 
   await logApiPerformance({
     url,
@@ -406,21 +411,14 @@ function setAuthHeader(headers, token, authType) {
  * @param {string} [tokenOrAuthConfig.controller] - Controller URL for token refresh (if object)
  * @returns {Promise<Object>} Response object
  */
-/**
- * Retry once after device-token refresh on 401 (Bearer only; never for client-token/preserveBearer).
- * @param {Object} response
- * @param {string} url
- * @param {Object} options
- * @param {Object} headers
- * @param {string|null} authControllerUrl
- * @returns {Promise<Object>}
- */
+/** Retry once after device-token refresh on 401 (Bearer only). */
 async function retryApiCallAfterDeviceTokenRefresh(
   response,
   url,
   options,
   headers,
-  authControllerUrl
+  authControllerUrl,
+  authConfig
 ) {
   try {
     const { forceRefreshDeviceToken } = require('./token-manager');
@@ -429,6 +427,11 @@ async function retryApiCallAfterDeviceTokenRefresh(
     );
     if (refreshedToken?.token) {
       headers.Authorization = `Bearer ${refreshedToken.token}`;
+      // Keep long-running commands current instead of reusing the expired bearer.
+      if (authConfig && typeof authConfig === 'object') {
+        authConfig.token = refreshedToken.token;
+        authConfig.controller = refreshedToken.controller || authControllerUrl;
+      }
       return await makeApiCall(url, { ...options, headers });
     }
     const authError =
@@ -471,7 +474,8 @@ async function authenticatedApiCall(url, options = {}, tokenOrAuthConfig) {
       url,
       options,
       headers,
-      authControllerUrl
+      authControllerUrl,
+      isStringToken ? null : tokenOrAuthConfig
     );
   }
 
@@ -492,4 +496,3 @@ module.exports = {
   displayDeviceCodeInfo,
   refreshDeviceToken
 };
-

package/lib/utils/authentication-slot-show.js

@@ -0,0 +1,153 @@
+/**
+ * Connected System credential line for `aifabrix show` (usage slots + online/offline).
+ *
+ * @fileoverview TTY formatter for authentications[] / legacy authentication
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const { getAuthMethodFromAuthentication } = require('./authentication-shape');
+
+/** Same labels as the dataplane Connected System authentication tab. */
+const AUTHENTICATION_USAGE_LABELS = Object.freeze({
+  api: 'API calls',
+  webhookInbound: 'Webhook inbound',
+  syncExecution: 'Sync execution',
+  messageInbound: 'Message inbound',
+  messageOutbound: 'Message outbound',
+  callback: 'Callback',
+  provisioning: 'Provisioning'
+});
+
+/**
+ * @param {string} method
+ * @param {string} glyph
+ * @returns {string}
+ */
+function chalkGlyph(method, glyph) {
+  const fn = chalk[method];
+  return typeof fn === 'function' ? fn(glyph) : glyph;
+}
+
+/**
+ * @param {string|null|undefined} status
+ * @returns {string}
+ */
+function formatOnlineOfflineIcon(status) {
+  const raw = String(status || 'offline').trim().toLowerCase();
+  if (raw === 'online') return chalkGlyph('green', '✔');
+  if (raw === 'partially') return chalkGlyph('yellow', '⚠');
+  return chalkGlyph('red', '✖');
+}
+
+/**
+ * @param {unknown} value
+ * @returns {Object|null}
+ */
+function asObject(value) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+}
+
+/**
+ * @param {Object} slot
+ * @returns {string}
+ */
+function formatSlotType(slot) {
+  const authType = String(slot.authType || '').trim().toLowerCase();
+  if (authType === 'system' || authType === 'none') return authType;
+  if (authType === 'apiprovider') return 'apiProvider';
+  const method = getAuthMethodFromAuthentication(slot);
+  if (method) return method;
+  const nested = asObject(slot.credential);
+  const nestedMethod = nested && typeof nested.method === 'string' ? nested.method.trim() : '';
+  return nestedMethod || authType || '—';
+}
+
+/**
+ * @param {Object} slot
+ * @param {string|null|undefined} systemStatus
+ * @returns {string}
+ */
+function slotStatus(slot, systemStatus) {
+  const authType = String(slot.authType || '').trim().toLowerCase();
+  if (authType === 'system' || authType === 'none') return 'online';
+  return systemStatus || 'offline';
+}
+
+/**
+ * @param {Object} slot
+ * @param {string|null|undefined} systemStatus
+ * @param {boolean} includeUsage
+ * @returns {string}
+ */
+function formatOneSlot(slot, systemStatus, includeUsage) {
+  const type = formatSlotType(slot);
+  const icon = formatOnlineOfflineIcon(slotStatus(slot, systemStatus));
+  if (!includeUsage) return `${type}  ${icon}`;
+  const usage = String(slot.usage || 'api').trim() || 'api';
+  const label = AUTHENTICATION_USAGE_LABELS[usage] || usage;
+  return `${label}: ${type} ${icon}`;
+}
+
+/**
+ * @param {unknown} entry
+ * @returns {Object|null}
+ */
+function normalizeSlot(entry) {
+  const obj = asObject(entry);
+  if (!obj) return null;
+  const key = typeof obj.key === 'string' && obj.key.trim() ? obj.key.trim() : 'default';
+  const usage = typeof obj.usage === 'string' && obj.usage.trim() ? obj.usage.trim() : 'api';
+  return { ...obj, key, usage };
+}
+
+/**
+ * @param {Object|null|undefined} config
+ * @param {Object|null|undefined} system
+ * @returns {Object[]}
+ */
+function resolveAuthenticationSlots(config, system) {
+  const cfg = asObject(config) || {};
+  const sys = asObject(system) || {};
+  const fromCfg = Array.isArray(cfg.authentications) && cfg.authentications.length > 0
+    ? cfg.authentications
+    : null;
+  const fromSys = Array.isArray(sys.authentications) && sys.authentications.length > 0
+    ? sys.authentications
+    : null;
+  const rawSlots = fromCfg || fromSys;
+  if (rawSlots) return rawSlots.map(normalizeSlot).filter(Boolean);
+  const legacy = asObject(cfg.authentication) || asObject(sys.authentication);
+  if (!legacy) return [];
+  return [normalizeSlot({ ...legacy, key: 'default', usage: 'api' })];
+}
+
+/**
+ * One slot: `oauth2  ✔`. Several: `API calls: oauth2 ✔, Webhook inbound: hmac ✔`.
+ * @param {Object} ext
+ * @returns {string}
+ */
+function formatCredentialShowLine(ext) {
+  if (!ext || typeof ext !== 'object') return '—';
+  const slots = Array.isArray(ext.authenticationSlots) ? ext.authenticationSlots : [];
+  const status = ext.authenticationStatus;
+  if (slots.length === 1) return formatOneSlot(slots[0], status, false);
+  if (slots.length > 1) {
+    return slots.map((slot) => formatOneSlot(slot, status, true)).join(', ');
+  }
+  const method = typeof ext.credentialMethod === 'string' ? ext.credentialMethod.trim() : '';
+  if (method && method.toLowerCase() !== 'unknown') {
+    return `${method}  ${formatOnlineOfflineIcon(status)}`;
+  }
+  return '—';
+}
+
+module.exports = {
+  AUTHENTICATION_USAGE_LABELS,
+  resolveAuthenticationSlots,
+  formatCredentialShowLine,
+  formatOnlineOfflineIcon
+};

package/lib/utils/cli-json-exit.js

@@ -0,0 +1,41 @@
+/**
+ * Truncation-safe JSON stdout write + exit for CLI commands.
+ *
+ * @fileoverview Shared helper for `--json` command output followed by a
+ *   non-zero process exit.
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const logger = require('./logger');
+const { writeStreamAndWait } = require('./write-stream-and-wait');
+
+/**
+ * Write a JSON envelope to stdout and exit with the given code, without
+ * truncating the output.
+ *
+ * Writes to a piped (non-TTY) stdout are asynchronous on Linux; calling
+ * `process.exit()` immediately after `logger.log()`/`console.log()` can
+ * kill the process before the OS finishes flushing a large write, silently
+ * truncating the JSON. Waiting for the `stdout.write` callback before
+ * exiting avoids that. Applies `logger.sanitizeValue` first, when available,
+ * so token/secret masking still happens (bypassing `logger.log()` skips it
+ * otherwise) — falls back to an identity function for test doubles that
+ * mock `logger` without it.
+ *
+ * @param {unknown} payload - Value to serialize as the JSON envelope.
+ * @param {number} exitCode - Exit code; 0 resolves without exiting.
+ * @returns {Promise<void>}
+ */
+async function writeJsonEnvelopeAndExit(payload, exitCode) {
+  const sanitize = typeof logger.sanitizeValue === 'function' ? logger.sanitizeValue : v => v;
+  const json = `${JSON.stringify(sanitize(payload), null, 2)}\n`;
+  await writeStreamAndWait(process.stdout, json);
+  if (exitCode !== 0) {
+    process.exit(exitCode);
+  }
+}
+
+module.exports = { writeJsonEnvelopeAndExit };

package/lib/utils/cli-utils.js

@@ -83,9 +83,11 @@ function isPortConflictError(errorMsg) {
  * @returns {boolean} True if permission denied error
  */
 function isPermissionDeniedError(errorMsg) {
-  return (errorMsg.includes('permission denied') || errorMsg.includes('EACCES') || errorMsg.includes('Permission denied')) &&
-    !errorMsg.includes('permissions/') &&
-    !errorMsg.includes('Field "permissions');
+  const text = String(errorMsg || '');
+  const lower = text.toLowerCase();
+  return (lower.includes('permission denied') || lower.includes('eacces')) &&
+    !text.includes('permissions/') &&
+    !text.includes('Field "permissions');
 }
 
 /**
@@ -287,7 +289,7 @@ function formatApiPermissionError(errorMsg) {
   if (isLocalFilesystemPermissionDeniedError(errorMsg)) return null;
   return [
     `   ${errorMsg}`,
-    '   Ensure your token has the required permission (e.g. external-system:delete for delete).'
+    '   Assign the required permission on the Controller or Dataplane for this environment (roles and groups).'
   ];
 }
 
@@ -418,11 +420,27 @@ function isAuthenticationError(error) {
  * @param {Error} error - The error that occurred
  * @param {string} command - Command that failed
  */
+function appendCommandPermissionHint(errorMessages, command) {
+  const blob = Array.isArray(errorMessages) ? errorMessages.join('\n') : '';
+  if (!isPermissionDeniedError(blob)) return errorMessages;
+  if (/Required permissions:|Missing permissions:|Required permission \(/.test(blob)) {
+    return errorMessages;
+  }
+  const { lookupCommandRequiredPermission } = require('./api-required-permissions');
+  const hit = lookupCommandRequiredPermission(command);
+  if (!hit) return errorMessages;
+  return [
+    ...errorMessages,
+    `   Required permission (${hit.service}): ${hit.permissions.join(', ')}`,
+    `   Assign it on the ${hit.service} for this environment (roles and groups).`
+  ];
+}
+
 function handleCommandError(error, command) {
   if (error && error.compactGateAbortLogged === true) {
     return;
   }
-  const errorMessages = formatError(error);
+  const errorMessages = appendCommandPermissionHint(formatError(error), command);
   const skipDoctor = isMissingSecretsErrorMessage(error && error.message);
   logError(command, errorMessages, { skipDoctor });
   if (error.wizardResumeMessage) {

package/lib/utils/controller-url.js

@@ -14,6 +14,10 @@ const devConfig = require('./dev-config');
 const config = require('../core/config');
 const { getDeviceToken, isTokenExpired } = require('./token-manager');
 
+/** Default Front Door / Traefik mount for Miso Controller on public hosts. */
+const DEFAULT_CONTROLLER_VDIR = '/miso';
+const CONTROLLER_HEALTH_TIMEOUT_MS = 2500;
+
 /**
  * Calculate default controller URL based on developer ID
  * Uses getDevPorts to get the app port which is adjusted by developer ID
@@ -132,14 +136,58 @@ async function isPlatformAuthValidForController(controllerUrl) {
 }
 
 /**
- * Best-effort GET /health on the controller (no auth). Used to avoid token refresh HTTP
- * during setup before Miso Controller is running.
+ * True for local controller ports (no Front Door /miso vdir).
+ * @param {string} hostname
+ * @returns {boolean}
+ */
+function isLoopbackControllerHost(hostname) {
+  const host = String(hostname || '').toLowerCase();
+  return host === 'localhost' || host === '127.0.0.1' || host === '::1';
+}
+
+/**
+ * @param {string} pathname
+ * @returns {boolean}
+ */
+function isMisoVdirPath(pathname) {
+  return pathname === DEFAULT_CONTROLLER_VDIR
+    || pathname.startsWith(`${DEFAULT_CONTROLLER_VDIR}/`);
+}
+
+/**
+ * Strip extra path segments. Public hosts always use origin + /miso.
+ * Loopback keeps origin unless the path is already /miso.
  *
+ * @param {string} url
+ * @returns {string}
+ */
+function canonicalizeControllerLoginUrl(url) {
+  const base = normalizeUrl(url);
+  if (!base) {
+    return url;
+  }
+  let parsed;
+  try {
+    parsed = new URL(base);
+  } catch {
+    return base;
+  }
+  const origin = `${parsed.protocol}//${parsed.host}`;
+  const pathname = (parsed.pathname || '/').replace(/\/+$/, '') || '/';
+  if (isLoopbackControllerHost(parsed.hostname)) {
+    return isMisoVdirPath(pathname) ? `${origin}${DEFAULT_CONTROLLER_VDIR}` : origin;
+  }
+  return `${origin}${DEFAULT_CONTROLLER_VDIR}`;
+}
+
+/**
+ * Best-effort GET /health on the controller (no auth).
  * @async
  * @param {string} controllerUrl
+ * @param {number} timeoutMs
  * @returns {Promise<boolean>}
  */
-async function isControllerHealthReachable(controllerUrl) {
+async function probeControllerHealth(controllerUrl, timeoutMs) {
   const base = normalizeUrl(controllerUrl);
   if (!base) {
     return false;
@@ -147,7 +195,7 @@ async function isControllerHealthReachable(controllerUrl) {
   try {
     const { fetchWithOptionalDevPlatformTls } = require('./dev-platform-tls');
     const res = await fetchWithOptionalDevPlatformTls(`${base}/health`, {
-      signal: AbortSignal.timeout(2500)
+      signal: AbortSignal.timeout(timeoutMs)
     });
     return res.ok;
   } catch {
@@ -155,6 +203,29 @@ async function isControllerHealthReachable(controllerUrl) {
   }
 }
 
+/**
+ * Best-effort GET /health on the controller (no auth). Used to avoid token refresh HTTP
+ * during setup before Miso Controller is running.
+ *
+ * @async
+ * @param {string} controllerUrl
+ * @returns {Promise<boolean>}
+ */
+async function isControllerHealthReachable(controllerUrl) {
+  return probeControllerHealth(controllerUrl, CONTROLLER_HEALTH_TIMEOUT_MS);
+}
+
+/**
+ * Resolve a controller base URL for login: public hosts always origin + /miso.
+ *
+ * @async
+ * @param {string} controllerUrl
+ * @returns {Promise<string>} Canonical controller URL
+ */
+async function discoverControllerBaseUrl(controllerUrl) {
+  return canonicalizeControllerLoginUrl(controllerUrl);
+}
+
 /**
  * Get controller URL from logged-in user's device tokens.
  * Prefers the entry under {@link config.controller} when it matches a `device` key; otherwise a
@@ -237,11 +308,14 @@ async function resolveControllerUrl() {
 }
 
 module.exports = {
+  DEFAULT_CONTROLLER_VDIR,
   getDefaultControllerUrl,
   hasStoredDeviceTokenForController,
   isDeviceTokenUsableForController,
   isPlatformAuthValidForController,
   isControllerHealthReachable,
+  canonicalizeControllerLoginUrl,
+  discoverControllerBaseUrl,
   getControllerUrlFromLoggedInUser,
   getControllerFromConfig,
   resolveControllerUrl

package/lib/utils/credential-display.js

@@ -8,6 +8,7 @@
  */
 
 const chalk = require('chalk');
+const { formatCredentialShowLine } = require('./authentication-slot-show');
 
 /** @type {{ verified: string, pending: string, failed: string, expired: string }} */
 const STATUS_ICONS = {
@@ -74,10 +75,51 @@ function formatCredentialWithStatus(credential) {
   return { key, name, statusFormatted, statusLabel };
 }
 
+/**
+ * @param {unknown[]} values
+ * @returns {string|null}
+ */
+function firstNonEmptyScalar(values) {
+  for (const value of values) {
+    if (typeof value === 'number') return String(value);
+    if (typeof value === 'string' && value.trim()) return value.trim();
+  }
+  return null;
+}
+
+/**
+ * Identity from a dataplane credential id or ForeignKeyReference. Never `[object Object]`.
+ * @param {unknown} value
+ * @returns {string|null}
+ */
+function formatCredentialIdentity(value) {
+  if (value === null || value === undefined || value === '') return null;
+  if (typeof value !== 'object') return String(value);
+  return firstNonEmptyScalar([
+    value.name,
+    value.displayName,
+    value.key,
+    value.id,
+    value.credentialKey,
+    value.credentialId
+  ]);
+}
+
+/**
+ * Scalar credential id/key for show output. Objects must not print as [object Object].
+ * @param {unknown} value
+ * @returns {string}
+ */
+function formatCredentialIdValue(value) {
+  return formatCredentialIdentity(value) || '—';
+}
+
 module.exports = {
   STATUS_ICONS,
   STATUS_LABELS,
   STATUS_CHALK,
   formatCredentialStatus,
-  formatCredentialWithStatus
+  formatCredentialWithStatus,
+  formatCredentialIdValue,
+  formatCredentialShowLine
 };

package/lib/utils/deployment-errors.js

@@ -193,6 +193,17 @@ function createFormattedError(parsedError, safeError, originalError) {
   return formattedError;
 }
 
+function createPreservedFormattedError(error, safeError) {
+  if (!error || typeof error.formatted !== 'string' || !error.formatted.trim()) {
+    return null;
+  }
+  return createFormattedError({
+    message: error.message || error.formatted,
+    formatted: error.formatted,
+    data: error.data
+  }, safeError, error);
+}
+
 /**
  * Unified error handler for deployment errors
  * Handles audit logging, error formatting, and user-friendly messages
@@ -227,6 +238,10 @@ async function handleDeploymentErrors(error, appName, url, alreadyLogged = false
   }
 
   const safeError = handleDeploymentError(error);
+  const preserved = createPreservedFormattedError(error, safeError);
+  if (preserved) {
+    throw preserved;
+  }
   const errorResponse = extractErrorResponse(safeError, error);
   const parsedError = parseErrorResponseSafely(errorResponse, safeError);
 

package/lib/utils/deployment-validation-helpers.js

@@ -49,7 +49,10 @@ function processValidationFailure(responseData) {
 function processValidationError(response) {
   const error = new Error(`Validation request failed: ${response.formattedError || response.error || 'Unknown error'}`);
   error.status = response.status || 400;
-  error.data = response.data;
+  error.data = response.errorData || response.data;
+  if (response.formattedError) {
+    error.formatted = response.formattedError;
+  }
   throw error;
 }
 

package/lib/utils/device-code.js

@@ -128,25 +128,45 @@ function buildVerificationUrlWithUserCode(verificationUri, userCode) {
 }
 
 /**
- * Displays device code information to the user
- * Formats user code and verification URL for easy reading. Uses a URL with user_code in the query
- * so the device page can pre-fill the code and the user does not need to type it.
+ * Full visit URL for device login (complete URI when the controller sends one).
+ *
+ * @param {Object} deviceCodeResponse
+ * @param {string} [deviceCodeResponse.verification_uri_complete]
+ * @param {string} [deviceCodeResponse.verification_uri]
+ * @param {string} [deviceCodeResponse.user_code]
+ * @returns {string}
+ */
+function resolveDeviceVisitUrl(deviceCodeResponse) {
+  const complete = deviceCodeResponse && deviceCodeResponse.verification_uri_complete;
+  if (complete) {
+    return complete;
+  }
+  return buildVerificationUrlWithUserCode(
+    deviceCodeResponse && deviceCodeResponse.verification_uri,
+    deviceCodeResponse && deviceCodeResponse.user_code
+  );
+}
+
+/**
+ * Displays device code information to the user.
+ * Prints a visit URL with user_code so the device page can pre-fill the code.
  *
  * @function displayDeviceCodeInfo
  * @param {string} userCode - User code to display
  * @param {string} verificationUri - Verification URL (base, without user_code)
  * @param {Object} logger - Logger instance with log method
  * @param {Object} chalk - Chalk instance for colored output
+ * @param {string} [verificationUriComplete] - Full verification URL when provided by the controller
  */
-function displayDeviceCodeInfo(userCode, verificationUri, logger, chalk) {
-  const visitUrl = buildVerificationUrlWithUserCode(verificationUri, userCode);
+function displayDeviceCodeInfo(userCode, verificationUri, logger, chalk, verificationUriComplete) {
+  const visitUrl = verificationUriComplete
+    || buildVerificationUrlWithUserCode(verificationUri, userCode);
   logger.log(chalk.cyan('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
   logger.log(chalk.cyan('  Device Code Flow Authentication'));
   logger.log(chalk.cyan('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n'));
-  logger.log(chalk.yellow('To complete authentication:'));
-  logger.log(chalk.gray('  1. Visit (code is in the URL): ') + chalk.blue.underline(visitUrl));
-  logger.log(chalk.gray('  2. Approve the request\n'));
-  logger.log(chalk.gray('Waiting for approval...'));
+  logger.log(chalk.yellow('Open this URL to authenticate:'));
+  logger.log(chalk.blue.underline(visitUrl));
+  logger.log(chalk.gray('\nApprove the request in the browser. Waiting for approval...'));
 }
 
 /** Timeout for token refresh request (ms). Longer than default to allow for slow controller/Keycloak. */
@@ -197,5 +217,6 @@ module.exports = {
   displayDeviceCodeInfo,
   refreshDeviceToken,
   parseTokenResponse,
-  buildVerificationUrlWithUserCode
+  buildVerificationUrlWithUserCode,
+  resolveDeviceVisitUrl
 };

package/lib/utils/error-formatters/error-parser.js

@@ -177,6 +177,21 @@ function handleGenericError(errorData, statusCode) {
   return createErrorResult('generic', errorData.message || errorData.error || 'Unknown error', formatGenericError(errorData, statusCode), errorData);
 }
 
+function unwrapNestedErrorData(errorData) {
+  if (!errorData || !errorData.data || typeof errorData.data !== 'object') {
+    return errorData;
+  }
+  const nested = errorData.data;
+  return {
+    ...nested,
+    cliPermissionService: errorData.cliPermissionService || nested.cliPermissionService,
+    requiredPermissions: errorData.requiredPermissions || nested.requiredPermissions,
+    method: errorData.method || nested.method,
+    url: nested.instance || nested.url || errorData.url,
+    instance: nested.instance || errorData.instance
+  };
+}
+
 /**
  * Parses error response and determines error type
  * @param {string|Object} errorResponse - Error response (string or parsed JSON)
@@ -200,7 +215,7 @@ function parseErrorResponse(errorResponse, statusCode, isNetworkError) {
 
   // Handle nested response structure (some APIs wrap errors in data field)
   if (errorData.data && typeof errorData.data === 'object') {
-    errorData = errorData.data;
+    errorData = unwrapNestedErrorData(errorData);
   }
 
   // Handle network errors

package/lib/utils/error-formatters/permission-errors.js

@@ -42,6 +42,9 @@ function extractRequiredPermissions(errorData) {
   if (errorData.requiredPermissions && Array.isArray(errorData.requiredPermissions)) {
     return errorData.requiredPermissions;
   }
+  if (typeof errorData.requiredPermission === 'string' && errorData.requiredPermission.trim()) {
+    return [errorData.requiredPermission.trim()];
+  }
   if (errorData.required && errorData.required.permissions && Array.isArray(errorData.required.permissions)) {
     return errorData.required.permissions;
   }
@@ -97,6 +100,19 @@ function getPermissionDetailLines(errorData) {
   return lines;
 }
 
+function appendPermissionAssignHint(lines, errorData) {
+  const service = errorData.cliPermissionService;
+  if (service) {
+    lines.push(chalk.gray(`Required on: ${service}`));
+  }
+  lines.push(chalk.gray(
+    service
+      ? `Assign this permission on the ${service} for this environment (roles and groups).`
+      : 'Assign the required permission on the Controller or Dataplane for this environment (roles and groups).'
+  ));
+  lines.push('');
+}
+
 /**
  * Formats permission error with missing and required permissions
  * @param {Object} errorData - Error response data
@@ -111,11 +127,9 @@ function formatPermissionError(errorData) {
     lines.push('');
   }
 
-  const missingPerms = extractMissingPermissions(errorData);
-  addPermissionList(lines, missingPerms, 'Missing permissions');
-
-  const requiredPerms = extractRequiredPermissions(errorData);
-  addPermissionList(lines, requiredPerms, 'Required permissions');
+  addPermissionList(lines, extractMissingPermissions(errorData), 'Missing permissions');
+  addPermissionList(lines, extractRequiredPermissions(errorData), 'Required permissions');
+  appendPermissionAssignHint(lines, errorData);
 
   const requestUrl = errorData.instance || errorData.url;
   const method = errorData.method || 'POST';