Merge branch 'development' into fix/DX-3749-improve-error-msgs

Author: reeshika-h

.talismanrc

@@ -9,7 +9,7 @@ fileignoreconfig:
     ignore_detectors:
       - filecontent
   - filename: package-lock.json
-    checksum: 424e5c45fa8043c95e0da5b215279c41cbe85230f75262ec7ac9ba01520e8821
+    checksum: 17b5bbabcc58beaa180a7fa931fc3fb407ee0e3447d47da224f60118c0a4c294
   - filename: .husky/pre-commit
     checksum: 52a664f536cf5d1be0bea19cb6031ca6e8107b45b6314fe7d47b7fad7d800632
   - filename: test/sanity-check/api/user-test.js

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## [v1.27.1](https://github.com/contentstack/contentstack-management-javascript/tree/v1.27.1) (2026-01-5)
+ - Fix
+   - Resolve qs dependency version
+
 ## [v1.27.0](https://github.com/contentstack/contentstack-management-javascript/tree/v1.27.0) (2025-12-15)
  - Enhancement
    - Refactored region endpoint resolution to use centralized `@contentstack/utils` package

lib/contentstack.js

@@ -168,6 +168,29 @@ import { getContentstackEndpoint } from '@contentstack/utils'
  * const client = contentstack.client({ region: 'eu' })
  *
  * @prop {string=} params.feature - Feature identifier for user agent header
+ * @prop {Array<Object>=} params.plugins - Optional array of plugin objects. Each plugin must have `onRequest` and `onResponse` methods.
+ * @example //Set plugins to intercept and modify requests/responses
+ * import * as contentstack from '@contentstack/management'
+ * const client = contentstack.client({
+ *   plugins: [
+ *     {
+ *       onRequest: (request) => {
+ *         // Return modified request
+ *         return {
+ *           ...request,
+ *           headers: {
+ *             ...request.headers,
+ *             'X-Custom-Header': 'value'
+ *           }
+ *         }
+ *       },
+ *       onResponse: (response) => {
+ *         // Return modified response
+ *         return response
+ *       }
+ *     }
+ *   ]
+ * })
  * @returns {ContentstackClient} Instance of ContentstackClient
  */
 export function client (params = {}) {

lib/core/Util.js

@@ -237,3 +237,26 @@ export const validateAndSanitizeConfig = (config) => {
     url: config.url.trim() // Sanitize URL by removing whitespace
   }
 }
+
+/**
+ * Normalizes and validates plugin array
+ * @param {Array|undefined} plugins - Array of plugin objects
+ * @returns {Array} Normalized array of plugins
+ */
+export function normalizePlugins (plugins) {
+  if (!plugins) {
+    return []
+  }
+
+  if (!Array.isArray(plugins)) {
+    return []
+  }
+
+  return plugins.filter(plugin => {
+    if (!plugin || typeof plugin !== 'object') {
+      return false
+    }
+    // Plugin must have both onRequest and onResponse methods
+    return typeof plugin.onRequest === 'function' && typeof plugin.onResponse === 'function'
+  })
+}

lib/core/concurrency-queue.js

@@ -21,6 +21,14 @@ const defaultConfig = {
 
 /**
  * Creates a concurrency queue manager for Axios requests with retry logic and rate limiting.
+ * SECURITY NOTICE - SSRF Prevention (CWE-918):
+ * This module implements comprehensive Server-Side Request Forgery (SSRF) protection.
+ * All axios requests are validated using validateAndSanitizeConfig() which:
+ * - Restricts requests to approved Contentstack domains only
+ * - Blocks private IP addresses and internal network access
+ * - Enforces HTTP/HTTPS protocols only (blocks file://, ftp://, etc.)
+ * - Validates both URL and baseURL configurations
+ * - Prevents URL injection attacks through proper sanitization
  * @param {Object} options - Configuration options.
  * @param {Object} options.axios - Axios instance to manage.
  * @param {Object=} options.config - Queue configuration options.
@@ -71,6 +79,30 @@ export function ConcurrencyQueue ({ axios, config }) {
   this.running = []
   this.paused = false
 
+  // SECURITY: Safe axios wrapper that always validates configs to prevent SSRF (CWE-918)
+  // This ensures ALL axios requests are validated before execution
+  const safeAxiosRequest = (requestConfig) => {
+    // Validate and sanitize to prevent SSRF attacks (CWE-918)
+    // This function throws an error if the URL is not allowed
+    const sanitized = validateAndSanitizeConfig(requestConfig)
+
+    // Additional runtime check: Ensure URL has been validated
+    if (!sanitized || !sanitized.url) {
+      throw new Error('Invalid request: URL validation failed')
+    }
+
+    // SECURITY: The axios call below is safe because validateAndSanitizeConfig ensures:
+    // 1. Only approved Contentstack domains are allowed
+    // 2. Private IP addresses are blocked
+    // 3. Only HTTP/HTTPS protocols are permitted
+    // 4. URL injection attacks are prevented
+    //
+    // This axios call is protected by validateAndSanitizeConfig above which validates
+    // all URLs against SSRF attacks. The function throws an error for any disallowed URLs.
+    // deepcode ignore Ssrf: URL is validated and sanitized by validateAndSanitizeConfig before use
+    return axios(sanitized)
+  }
+
   // Helper function to determine if an error is a transient network failure
   const isTransientNetworkError = (error) => {
     // DNS resolution failures
@@ -159,12 +191,13 @@ export function ConcurrencyQueue ({ axios, config }) {
       setTimeout(() => {
         // Keep the request in running queue to maintain maxRequests constraint
         // Set retry flags to ensure proper queue handling
-        const sanitizedConfig = validateAndSanitizeConfig(updateRequestConfig(error, `Network retry ${attempt}`, delay))
-        sanitizedConfig.retryCount = sanitizedConfig.retryCount || 0
+        const requestConfig = updateRequestConfig(error, `Network retry ${attempt}`, delay)
+        requestConfig.retryCount = requestConfig.retryCount || 0
 
         // Use axios directly but ensure the running queue is properly managed
         // The request interceptor will handle this retry appropriately
-        axios(sanitizedConfig)
+        // SECURITY: Using safeAxiosRequest wrapper that validates against SSRF attacks
+        safeAxiosRequest(requestConfig)
           .then((response) => {
             // On successful retry, call the original onComplete to properly clean up
             if (error.config.onComplete) {
@@ -316,9 +349,8 @@ export function ConcurrencyQueue ({ axios, config }) {
 
       // Retry the requests that were pending due to token expiration
       this.running.forEach(({ request, resolve, reject }) => {
-      // Retry the request with sanitized configuration to prevent SSRF
-        const sanitizedConfig = validateAndSanitizeConfig(request)
-        axios(sanitizedConfig).then(resolve).catch(reject)
+        // SECURITY: Using safeAxiosRequest wrapper that validates against SSRF attacks
+        safeAxiosRequest(request).then(resolve).catch(reject)
       })
       this.running = [] // Clear the running queue after retrying requests
     } catch (error) {
@@ -446,9 +478,8 @@ export function ConcurrencyQueue ({ axios, config }) {
       // Cool down the running requests
       delay(wait, response.status === 401)
       error.config.retryCount = networkError
-      // SSRF Prevention: Validate URL before making request
-      const sanitizedConfig = validateAndSanitizeConfig(updateRequestConfig(error, retryErrorType, wait))
-      return axios(sanitizedConfig)
+      // SECURITY: Using safeAxiosRequest wrapper that validates against SSRF attacks
+      return safeAxiosRequest(updateRequestConfig(error, retryErrorType, wait))
     }
     if (this.config.retryCondition && this.config.retryCondition(error)) {
       retryErrorType = error.response ? `Error with status: ${response.status}` : `Error Code:${error.code}`
@@ -478,9 +509,8 @@ export function ConcurrencyQueue ({ axios, config }) {
     error.config.retryCount = retryCount
     return new Promise(function (resolve) {
       return setTimeout(function () {
-        // SSRF Prevention: Validate URL before making request
-        const sanitizedConfig = validateAndSanitizeConfig(updateRequestConfig(error, retryErrorType, delaytime))
-        return resolve(axios(sanitizedConfig))
+        // SECURITY: Using safeAxiosRequest wrapper that validates against SSRF attacks
+        return resolve(safeAxiosRequest(updateRequestConfig(error, retryErrorType, delaytime)))
       }, delaytime)
     })
   }

lib/core/contentstackHTTPClient.js

@@ -2,7 +2,7 @@ import axios from 'axios'
 import clonedeep from 'lodash/cloneDeep'
 import Qs from 'qs'
 import { ConcurrencyQueue } from './concurrency-queue'
-import { isHost } from './Util'
+import { isHost, normalizePlugins } from './Util'
 import { ERROR_MESSAGES } from './errorMessages'
 
 export default function contentstackHttpClient (options) {
@@ -110,6 +110,11 @@ export default function contentstackHttpClient (options) {
   const instance = axios.create(axiosOptions)
   instance.httpClientParams = options
   instance.concurrencyQueue = new ConcurrencyQueue({ axios: instance, config })
+
+  // Normalize and store plugins
+  const plugins = normalizePlugins(config.plugins)
+
+  // Request interceptor for versioning strategy (must run first)
   instance.interceptors.request.use((request) => {
     if (request.versioningStrategy && request.versioningStrategy === 'path') {
       request.baseURL = request.baseURL.replace('{api-version}', version)
@@ -118,5 +123,117 @@ export default function contentstackHttpClient (options) {
     }
     return request
   })
+
+  // Request interceptor for plugins (runs after versioning)
+  if (plugins.length > 0) {
+    instance.interceptors.request.use(
+      (request) => {
+        // Run all onRequest hooks sequentially, using return values
+        let currentRequest = request
+        for (const plugin of plugins) {
+          try {
+            if (typeof plugin.onRequest === 'function') {
+              const result = plugin.onRequest(currentRequest)
+              // Use returned value if provided, otherwise use current request
+              if (result !== undefined) {
+                currentRequest = result
+              }
+            }
+          } catch (error) {
+            // Log error and continue with next plugin
+            if (config.logHandler) {
+              config.logHandler('error', {
+                name: 'PluginError',
+                message: `Error in plugin onRequest: ${error.message}`,
+                error: error
+              })
+            }
+          }
+        }
+        return currentRequest
+      },
+      (error) => {
+        // Handle request errors - run plugins even on error
+        let currentConfig = error.config
+        for (const plugin of plugins) {
+          try {
+            if (typeof plugin.onRequest === 'function' && currentConfig) {
+              const result = plugin.onRequest(currentConfig)
+              // Use returned value if provided, otherwise use current config
+              if (result !== undefined) {
+                currentConfig = result
+                error.config = currentConfig
+              }
+            }
+          } catch (pluginError) {
+            if (config.logHandler) {
+              config.logHandler('error', {
+                name: 'PluginError',
+                message: `Error in plugin onRequest (error handler): ${pluginError.message}`,
+                error: pluginError
+              })
+            }
+          }
+        }
+        return Promise.reject(error)
+      }
+    )
+
+    // Response interceptor for plugins
+    instance.interceptors.response.use(
+      (response) => {
+        // Run all onResponse hooks sequentially for successful responses
+        // Use return values from plugins
+        let currentResponse = response
+        for (const plugin of plugins) {
+          try {
+            if (typeof plugin.onResponse === 'function') {
+              const result = plugin.onResponse(currentResponse)
+              // Use returned value if provided, otherwise use current response
+              if (result !== undefined) {
+                currentResponse = result
+              }
+            }
+          } catch (error) {
+            // Log error and continue with next plugin
+            if (config.logHandler) {
+              config.logHandler('error', {
+                name: 'PluginError',
+                message: `Error in plugin onResponse: ${error.message}`,
+                error: error
+              })
+            }
+          }
+        }
+        return currentResponse
+      },
+      (error) => {
+        // Handle response errors - run plugins even on error
+        // Pass the error object (which may contain error.response if server responded)
+        let currentError = error
+        for (const plugin of plugins) {
+          try {
+            if (typeof plugin.onResponse === 'function') {
+              const result = plugin.onResponse(currentError)
+              // Use returned value if provided, otherwise use current error
+              if (result !== undefined) {
+                currentError = result
+              }
+            }
+          } catch (pluginError) {
+            if (config.logHandler) {
+              config.logHandler('error', {
+                name: 'PluginError',
+                message: `Error in plugin onResponse (error handler): ${pluginError.message}`,
+                error: pluginError
+              })
+            }
+          }
+        }
+        return Promise.reject(currentError)
+      }
+    )
+  }
+
   return instance
 }