@aifabrix/builder 2.40.2 → 2.42.0

package/lib/utils/device-code-helpers.js

@@ -0,0 +1,224 @@
+/**
+ * Device code flow parsing, error handling, and polling helpers.
+ * Used by device-code.js; not part of the public API.
+ *
+ * @fileoverview Helpers for device code flow (RFC 8628)
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+/**
+ * Parses device code response from API
+ * @param {Object} response - API response object
+ * @returns {Object} Parsed device code response
+ */
+function parseDeviceCodeResponse(response) {
+  const apiResponse = response.data;
+  const responseData = apiResponse.data || apiResponse;
+  const deviceCode = responseData.deviceCode;
+  const userCode = responseData.userCode;
+  const verificationUri = responseData.verificationUri;
+  const expiresIn = responseData.expiresIn || 600;
+  const interval = responseData.interval || 5;
+
+  if (!deviceCode || !userCode || !verificationUri) {
+    throw new Error('Invalid device code response: missing required fields');
+  }
+
+  return {
+    device_code: deviceCode,
+    user_code: userCode,
+    verification_uri: verificationUri,
+    expires_in: expiresIn,
+    interval: interval
+  };
+}
+
+/**
+ * Parses token response from API
+ * @param {Object} response - API response object
+ * @returns {Object|null} Parsed token response or null if pending
+ */
+function parseTokenResponse(response) {
+  const apiResponse = response.data;
+  const responseData = apiResponse.data || apiResponse;
+  const error = responseData.error || apiResponse.error;
+  if (error === 'authorization_pending' || error === 'slow_down') {
+    return null;
+  }
+
+  const accessToken = responseData.accessToken;
+  const refreshToken = responseData.refreshToken;
+  const expiresIn = responseData.expiresIn || 3600;
+
+  if (!accessToken) {
+    throw new Error('Invalid token response: missing accessToken');
+  }
+
+  return {
+    access_token: accessToken,
+    refresh_token: refreshToken,
+    expires_in: expiresIn
+  };
+}
+
+/**
+ * Checks if token has expired based on elapsed time
+ * @param {number} startTime - Start time in milliseconds
+ * @param {number} expiresIn - Expiration time in seconds
+ */
+function checkTokenExpiration(startTime, expiresIn) {
+  const maxWaitTime = (expiresIn + 30) * 1000;
+  if (Date.now() - startTime > maxWaitTime) {
+    throw new Error('Device code expired: Maximum polling time exceeded');
+  }
+}
+
+function attachFormattedError(validationError, response) {
+  if (response && response.formattedError) {
+    validationError.formattedError = response.formattedError;
+    validationError.message = `Token polling failed:\n${response.formattedError}`;
+  }
+}
+
+function buildDetailedErrorMessage(errorData) {
+  const detail = errorData.detail || errorData.title || errorData.message || 'Validation error';
+  let errorMsg = `Token polling failed: ${detail}`;
+  if (errorData.errors && Array.isArray(errorData.errors) && errorData.errors.length > 0) {
+    errorMsg += '\n\nValidation errors:';
+    errorData.errors.forEach(err => {
+      const field = err.field || err.path || 'validation';
+      const message = err.message || 'Invalid value';
+      errorMsg += (field === 'validation' || field === 'unknown')
+        ? `\n  • ${message}` : `\n  • ${field}: ${message}`;
+    });
+  }
+  return errorMsg;
+}
+
+function attachErrorData(validationError, response) {
+  if (response && response.errorData) {
+    validationError.errorData = response.errorData;
+    validationError.errorType = response.errorType || 'validation';
+    if (!validationError.formattedError) {
+      validationError.message = buildDetailedErrorMessage(response.errorData);
+    }
+  }
+}
+
+function createValidationError(response) {
+  const validationError = new Error('Token polling failed: Validation error');
+  attachFormattedError(validationError, response);
+  attachErrorData(validationError, response);
+  return validationError;
+}
+
+/**
+ * Handles polling errors; throws for fatal errors, returns true to continue polling.
+ * @param {string} error - Error code
+ * @param {number} status - HTTP status code
+ * @param {Object} response - Full API response object
+ * @returns {boolean} True if should continue polling
+ */
+function handlePollingErrors(error, status, response) {
+  if (error === 'authorization_pending' || status === 202) {
+    return true;
+  }
+  if (error === 'authorization_declined') {
+    throw new Error('Authorization declined: User denied the request');
+  }
+  if (error === 'expired_token' || status === 410) {
+    throw new Error('Device code expired: Please restart the authentication process');
+  }
+  if (error === 'slow_down') {
+    return true;
+  }
+  if (error === 'validation_error' || status === 400 ||
+      error === 'INVALID_TOKEN' || error === 'INVALID_ACCESS_TOKEN') {
+    throw createValidationError(response);
+  }
+  throw new Error(`Token polling failed: ${error}`);
+}
+
+async function waitForNextPoll(interval, slowDown) {
+  const waitInterval = slowDown ? interval * 2 : interval;
+  await new Promise(resolve => setTimeout(resolve, waitInterval * 1000));
+}
+
+function isValidationErrorCode(errorCode) {
+  return errorCode === 'INVALID_TOKEN' || errorCode === 'INVALID_ACCESS_TOKEN';
+}
+
+function extractStructuredError(response) {
+  if (response.errorType === 'validation') {
+    return 'validation_error';
+  }
+  const errorData = response.errorData;
+  const errorCode = errorData.error || errorData.code || response.error;
+  if (isValidationErrorCode(errorCode)) {
+    return 'validation_error';
+  }
+  return errorData.detail || errorData.title || errorData.message || errorCode || response.error || 'Unknown error';
+}
+
+function extractFallbackError(response) {
+  const apiResponse = response.data || {};
+  const errorData = typeof apiResponse === 'object' ? apiResponse : {};
+  const errorCode = errorData.error || response.error || 'Unknown error';
+  if (isValidationErrorCode(errorCode)) {
+    return 'validation_error';
+  }
+  return errorCode;
+}
+
+function extractPollingError(response) {
+  if (response.errorData) {
+    return extractStructuredError(response);
+  }
+  return extractFallbackError(response);
+}
+
+function handleSuccessfulPoll(response) {
+  const tokenResponse = parseTokenResponse(response);
+  return tokenResponse || null;
+}
+
+/**
+ * Processes polling response and determines next action.
+ * @param {Object} response - API response object
+ * @param {number} interval - Polling interval in seconds
+ * @returns {Promise<Object|null>} Token response if complete, null if should continue
+ */
+async function processPollingResponse(response, interval) {
+  if (response.success) {
+    const apiResponse = response.data || {};
+    const responseData = apiResponse.data || apiResponse;
+    const errorCode = responseData.error || apiResponse.error || response.error;
+    if (errorCode && (errorCode === 'INVALID_TOKEN' || errorCode === 'INVALID_ACCESS_TOKEN')) {
+      throw createValidationError(response);
+    }
+    const tokenResponse = handleSuccessfulPoll(response);
+    if (tokenResponse) {
+      return tokenResponse;
+    }
+    const error = errorCode;
+    const slowDown = error === 'slow_down';
+    await waitForNextPoll(interval, slowDown);
+    return null;
+  }
+
+  const error = extractPollingError(response);
+  const shouldContinue = handlePollingErrors(error, response.status, response);
+  if (shouldContinue) {
+    await waitForNextPoll(interval, error === 'slow_down');
+    return null;
+  }
+  return null;
+}
+
+module.exports = {
+  parseDeviceCodeResponse,
+  parseTokenResponse,
+  checkTokenExpiration,
+  processPollingResponse
+};

package/lib/utils/device-code.js

@@ -9,6 +9,13 @@
  * @version 2.0.0
  */
 
+const {
+  parseDeviceCodeResponse,
+  parseTokenResponse,
+  checkTokenExpiration,
+  processPollingResponse
+} = require('./device-code-helpers');
+
 // Lazy require to avoid circular dependency
 let makeApiCall;
 function getMakeApiCall() {
@@ -19,40 +26,6 @@ function getMakeApiCall() {
   return makeApiCall;
 }
 
-/**
- * Parses device code response from API
- * Matches OpenAPI DeviceCodeResponse schema (camelCase)
- * @function parseDeviceCodeResponse
- * @param {Object} response - API response object
- * @returns {Object} Parsed device code response
- * @throws {Error} If response is invalid
- */
-function parseDeviceCodeResponse(response) {
-  // OpenAPI spec: { success: boolean, data: DeviceCodeResponse, timestamp: string }
-  const apiResponse = response.data;
-  const responseData = apiResponse.data || apiResponse;
-
-  // OpenAPI spec uses camelCase: deviceCode, userCode, verificationUri, expiresIn, interval
-  const deviceCode = responseData.deviceCode;
-  const userCode = responseData.userCode;
-  const verificationUri = responseData.verificationUri;
-  const expiresIn = responseData.expiresIn || 600;
-  const interval = responseData.interval || 5;
-
-  if (!deviceCode || !userCode || !verificationUri) {
-    throw new Error('Invalid device code response: missing required fields');
-  }
-
-  // Return in snake_case for internal consistency (used by existing code)
-  return {
-    device_code: deviceCode,
-    user_code: userCode,
-    verification_uri: verificationUri,
-    expires_in: expiresIn,
-    interval: interval
-  };
-}
-
 /**
  * Initiates OAuth2 Device Code Flow
  * Calls the device code endpoint to get device_code and user_code
@@ -70,7 +43,6 @@ async function initiateDeviceCodeFlow(controllerUrl, environment, scope) {
     throw new Error('Environment key is required');
   }
 
-  // Default scope for backward compatibility
   const defaultScope = 'openid profile email';
   const requestScope = scope || defaultScope;
 
@@ -92,298 +64,6 @@ async function initiateDeviceCodeFlow(controllerUrl, environment, scope) {
   return parseDeviceCodeResponse(response);
 }
 
-/**
- * Checks if token has expired based on elapsed time
- * @function checkTokenExpiration
- * @param {number} startTime - Start time in milliseconds
- * @param {number} expiresIn - Expiration time in seconds
- * @throws {Error} If token has expired
- */
-function checkTokenExpiration(startTime, expiresIn) {
-  const maxWaitTime = (expiresIn + 30) * 1000;
-  if (Date.now() - startTime > maxWaitTime) {
-    throw new Error('Device code expired: Maximum polling time exceeded');
-  }
-}
-
-/**
- * Parses token response from API
- * Matches OpenAPI DeviceCodeTokenResponse schema (camelCase)
- * @function parseTokenResponse
- * @param {Object} response - API response object
- * @returns {Object|null} Parsed token response or null if pending
- */
-function parseTokenResponse(response) {
-  // OpenAPI spec: { success: boolean, data: DeviceCodeTokenResponse, timestamp: string }
-  const apiResponse = response.data;
-  const responseData = apiResponse.data || apiResponse;
-
-  const error = responseData.error || apiResponse.error;
-  if (error === 'authorization_pending' || error === 'slow_down') {
-    return null;
-  }
-
-  // OpenAPI spec uses camelCase: accessToken, refreshToken, expiresIn
-  const accessToken = responseData.accessToken;
-  const refreshToken = responseData.refreshToken;
-  const expiresIn = responseData.expiresIn || 3600;
-
-  if (!accessToken) {
-    throw new Error('Invalid token response: missing accessToken');
-  }
-
-  // Return in snake_case for internal consistency (used by existing code)
-  return {
-    access_token: accessToken,
-    refresh_token: refreshToken,
-    expires_in: expiresIn
-  };
-}
-
-/**
- * Creates a validation error with detailed information
- * @function createValidationError
- * @param {Object} response - Full API response object
- * @returns {Error} Validation error with formattedError and errorData attached
- */
-/**
- * Attaches formatted error to validation error
- * @function attachFormattedError
- * @param {Error} validationError - Validation error object
- * @param {Object} response - API response
- */
-function attachFormattedError(validationError, response) {
-  if (response && response.formattedError) {
-    validationError.formattedError = response.formattedError;
-    validationError.message = `Token polling failed:\n${response.formattedError}`;
-  }
-}
-
-/**
- * Builds detailed error message from error data
- * @function buildDetailedErrorMessage
- * @param {Object} errorData - Error data object
- * @returns {string} Detailed error message
- */
-function buildDetailedErrorMessage(errorData) {
-  const detail = errorData.detail || errorData.title || errorData.message || 'Validation error';
-  let errorMsg = `Token polling failed: ${detail}`;
-
-  if (errorData.errors && Array.isArray(errorData.errors) && errorData.errors.length > 0) {
-    errorMsg += '\n\nValidation errors:';
-    errorData.errors.forEach(err => {
-      const field = err.field || err.path || 'validation';
-      const message = err.message || 'Invalid value';
-      if (field === 'validation' || field === 'unknown') {
-        errorMsg += `\n  • ${message}`;
-      } else {
-        errorMsg += `\n  • ${field}: ${message}`;
-      }
-    });
-  }
-
-  return errorMsg;
-}
-
-/**
- * Attaches error data to validation error
- * @function attachErrorData
- * @param {Error} validationError - Validation error object
- * @param {Object} response - API response
- */
-function attachErrorData(validationError, response) {
-  if (response && response.errorData) {
-    validationError.errorData = response.errorData;
-    validationError.errorType = response.errorType || 'validation';
-
-    if (!validationError.formattedError) {
-      validationError.message = buildDetailedErrorMessage(response.errorData);
-    }
-  }
-}
-
-function createValidationError(response) {
-  const validationError = new Error('Token polling failed: Validation error');
-
-  attachFormattedError(validationError, response);
-  attachErrorData(validationError, response);
-
-  return validationError;
-}
-
-/**
- * Handles polling errors
- * @function handlePollingErrors
- * @param {string} error - Error code
- * @param {number} status - HTTP status code
- * @param {Object} response - Full API response object (for accessing formattedError and errorData)
- * @throws {Error} For fatal errors
- * @returns {boolean} True if should continue polling
- */
-function handlePollingErrors(error, status, response) {
-  if (error === 'authorization_pending' || status === 202) {
-    return true;
-  }
-
-  // Check error field first, then status code
-  if (error === 'authorization_declined') {
-    throw new Error('Authorization declined: User denied the request');
-  }
-
-  if (error === 'expired_token' || status === 410) {
-    throw new Error('Device code expired: Please restart the authentication process');
-  }
-
-  if (error === 'slow_down') {
-    return true;
-  }
-
-  // Handle validation errors with detailed message
-  // Check for validation_error, status 400, or specific validation error codes
-  if (error === 'validation_error' || status === 400 ||
-      error === 'INVALID_TOKEN' || error === 'INVALID_ACCESS_TOKEN') {
-    throw createValidationError(response);
-  }
-
-  throw new Error(`Token polling failed: ${error}`);
-}
-
-/**
- * Waits for next polling interval
- * @async
- * @function waitForNextPoll
- * @param {number} interval - Polling interval in seconds
- * @param {boolean} slowDown - Whether to slow down
- */
-async function waitForNextPoll(interval, slowDown) {
-  const waitInterval = slowDown ? interval * 2 : interval;
-  await new Promise(resolve => setTimeout(resolve, waitInterval * 1000));
-}
-
-/**
- * Extracts error from API response
- * @param {Object} response - API response object
- * @returns {string} Error code or 'Unknown error'
- */
-/**
- * Checks if error code indicates validation error
- * @function isValidationErrorCode
- * @param {string} errorCode - Error code to check
- * @returns {boolean} True if validation error
- */
-function isValidationErrorCode(errorCode) {
-  return errorCode === 'INVALID_TOKEN' || errorCode === 'INVALID_ACCESS_TOKEN';
-}
-
-/**
- * Extracts error from structured error data
- * @function extractStructuredError
- * @param {Object} response - API response with errorData
- * @returns {string} Error message or code
- */
-function extractStructuredError(response) {
-  const errorData = response.errorData;
-
-  // For validation errors, return the error type so we can handle it specially
-  if (response.errorType === 'validation') {
-    return 'validation_error';
-  }
-
-  // Check if error code indicates validation error (e.g., INVALID_TOKEN)
-  const errorCode = errorData.error || errorData.code || response.error;
-  if (isValidationErrorCode(errorCode)) {
-    return 'validation_error';
-  }
-
-  // Return the error message from structured error
-  return errorData.detail || errorData.title || errorData.message || errorCode || response.error || 'Unknown error';
-}
-
-/**
- * Extracts error from fallback response structure
- * @function extractFallbackError
- * @param {Object} response - API response
- * @returns {string} Error code
- */
-function extractFallbackError(response) {
-  const apiResponse = response.data || {};
-  const errorData = typeof apiResponse === 'object' ? apiResponse : {};
-  const errorCode = errorData.error || response.error || 'Unknown error';
-
-  // Check if error code indicates validation error (e.g., INVALID_TOKEN)
-  if (isValidationErrorCode(errorCode)) {
-    return 'validation_error';
-  }
-
-  return errorCode;
-}
-
-function extractPollingError(response) {
-  // Check for structured error data first (from api-error-handler)
-  if (response.errorData) {
-    return extractStructuredError(response);
-  }
-
-  // Fallback to original extraction logic
-  return extractFallbackError(response);
-}
-
-/**
- * Handles successful polling response
- * @param {Object} response - API response object
- * @returns {Object|null} Token response or null if pending
- */
-function handleSuccessfulPoll(response) {
-  const tokenResponse = parseTokenResponse(response);
-  if (tokenResponse) {
-    return tokenResponse;
-  }
-  return null;
-}
-
-/**
- * Processes polling response and determines next action
- * @async
- * @function processPollingResponse
- * @param {Object} response - API response object
- * @param {number} interval - Polling interval in seconds
- * @returns {Promise<Object|null>} Token response if complete, null if should continue
- */
-async function processPollingResponse(response, interval) {
-  if (response.success) {
-    // Check if response contains an error code even though success is true
-    const apiResponse = response.data || {};
-    const responseData = apiResponse.data || apiResponse;
-    const errorCode = responseData.error || apiResponse.error || response.error;
-
-    // If there's an error code like INVALID_TOKEN, treat it as a validation error
-    if (errorCode && (errorCode === 'INVALID_TOKEN' || errorCode === 'INVALID_ACCESS_TOKEN')) {
-      throw createValidationError(response);
-    }
-
-    const tokenResponse = handleSuccessfulPoll(response);
-    if (tokenResponse) {
-      return tokenResponse;
-    }
-
-    const error = errorCode;
-    const slowDown = error === 'slow_down';
-    await waitForNextPoll(interval, slowDown);
-    return null;
-  }
-
-  const error = extractPollingError(response);
-  const shouldContinue = handlePollingErrors(error, response.status, response);
-
-  if (shouldContinue) {
-    const slowDown = error === 'slow_down';
-    await waitForNextPoll(interval, slowDown);
-    return null;
-  }
-
-  return null;
-}
-
 /**
  * Polls for token during Device Code Flow
  * Continuously polls the token endpoint until user approves or flow expires
@@ -431,27 +111,47 @@ async function pollDeviceCodeToken(controllerUrl, deviceCode, interval, expiresI
   }
 }
 
+/**
+ * Builds verification URL with user_code query parameter so the device page can pre-fill the code.
+ *
+ * @function buildVerificationUrlWithUserCode
+ * @param {string} verificationUri - Base verification URL (e.g. http://localhost:8182/realms/aifabrix/device)
+ * @param {string} userCode - User code to append as user_code query param
+ * @returns {string} Full URL with ?user_code=<code> or &user_code=<code>
+ */
+function buildVerificationUrlWithUserCode(verificationUri, userCode) {
+  if (!verificationUri || !userCode) {
+    return verificationUri || '';
+  }
+  const separator = verificationUri.includes('?') ? '&' : '?';
+  return `${verificationUri}${separator}user_code=${encodeURIComponent(userCode)}`;
+}
+
 /**
  * Displays device code information to the user
- * Formats user code and verification URL for easy reading
+ * 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.
  *
  * @function displayDeviceCodeInfo
  * @param {string} userCode - User code to display
- * @param {string} verificationUri - Verification URL
+ * @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
  */
 function displayDeviceCodeInfo(userCode, verificationUri, logger, chalk) {
+  const visitUrl = 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: ') + chalk.blue.underline(verificationUri));
-  logger.log(chalk.gray('  2. Enter code: ') + chalk.bold.cyan(userCode));
-  logger.log(chalk.gray('  3. Approve the request\n'));
+  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...'));
 }
 
+/** Timeout for token refresh request (ms). Longer than default to allow for slow controller/Keycloak. */
+const REFRESH_TOKEN_TIMEOUT_MS = 60000;
+
 /**
  * Refresh device code access token using refresh token
  * Uses OpenAPI /api/v1/auth/login/device/refresh endpoint
@@ -469,13 +169,13 @@ async function refreshDeviceToken(controllerUrl, refreshToken) {
   }
 
   const url = `${controllerUrl}/api/v1/auth/login/device/refresh`;
-  // Send both refresh_token (OAuth2 RFC 6749 / Keycloak) and refreshToken (camelCase) so controller accepts either
   const response = await getMakeApiCall()(url, {
     method: 'POST',
     headers: {
       'Content-Type': 'application/json'
     },
-    body: JSON.stringify({ refresh_token: refreshToken, refreshToken })
+    body: JSON.stringify({ refresh_token: refreshToken, refreshToken }),
+    signal: AbortSignal.timeout(REFRESH_TOKEN_TIMEOUT_MS)
   });
 
   if (!response.success) {
@@ -483,7 +183,6 @@ async function refreshDeviceToken(controllerUrl, refreshToken) {
     throw new Error(`Failed to refresh token: ${errorMsg}`);
   }
 
-  // Parse response using existing parseTokenResponse function
   const tokenResponse = parseTokenResponse(response);
   if (!tokenResponse) {
     throw new Error('Invalid refresh token response');
@@ -491,10 +190,12 @@ async function refreshDeviceToken(controllerUrl, refreshToken) {
 
   return tokenResponse;
 }
+
 module.exports = {
   initiateDeviceCodeFlow,
   pollDeviceCodeToken,
   displayDeviceCodeInfo,
   refreshDeviceToken,
-  parseTokenResponse
+  parseTokenResponse,
+  buildVerificationUrlWithUserCode
 };