Adds support for secret resolution via support of secretResolver.

CHANGELOG.yaml

@@ -1,3 +1,7 @@
+unreleased:
+  new features:
+    - Add support for secret variable resolution
+
 7.51.1:
   date: 2026-01-27
   chores:

README.md

@@ -54,6 +54,17 @@ runner.run(collection, {
     // Local variables (a "VariableScope" from the SDK)
     localVariables: new sdk.VariableScope(),
 
+    // Function to resolve secret variables (variables with secret: true) before request execution.
+    // Receives { secrets, url }; url is request URL without query params. Callback(err, result).
+    // On fatal error: callback(err) — execution stops. On success: callback(null, result) where result
+    // is Array<{ resolvedValue?, error?, allowedInScript? }>; result[i] maps to secrets[i].
+    // allowedInScript: true exposes value to scripts; false/undefined masks it from pm.environment/pm.variables.
+    secretResolver: function ({ secrets, url }, callback) {
+        callback(null, secrets.map(function (s) {
+            return { resolvedValue: 'resolved-string', error: undefined, allowedInScript: true };
+        }));
+    },
+
     // Execute a folder/request using id/name or path
     entrypoint: {
         // execute a folder/request using id or name

lib/runner/extensions/event.command.js

@@ -38,7 +38,46 @@ var _ = require('lodash'),
 
     getCookieDomain, // fn
     postProcessContext, // fn
-    sanitizeFiles; // fn
+    sanitizeFiles, // fn
+    maskForbiddenSecrets; // fn
+
+/**
+ * Clones variable scopes and masks variables in forbiddenSecretKeys (Set of "scopeName:variableKey").
+ * Used to hide secrets not allowed in scripts while keeping them available for request substitution.
+ *
+ * @param {Object} context - Context with environment, globals, collectionVariables
+ * @param {Set} forbiddenSecretKeys - Set of "scopeName:variableKey" for secrets with allowedInScript=false
+ * @returns {Object} - Context with cloned, masked scopes
+ */
+maskForbiddenSecrets = function (context, forbiddenSecretKeys) {
+    if (!forbiddenSecretKeys || forbiddenSecretKeys.size === 0) {
+        return context;
+    }
+
+    var scopeNames = ['environment', 'globals', 'collectionVariables'],
+        maskedContext = _.assign({}, context);
+
+    scopeNames.forEach(function (scopeName) {
+        var scope = context[scopeName],
+            maskedScope;
+
+        if (!scope || !sdk.VariableScope.isVariableScope(scope)) {
+            return;
+        }
+
+        maskedScope = new sdk.VariableScope(scope.toJSON ? scope.toJSON() : scope);
+
+        maskedScope.values.each(function (variable) {
+            if (variable && forbiddenSecretKeys.has(scopeName + ':' + variable.key)) {
+                variable.set(undefined);
+            }
+        });
+
+        maskedContext[scopeName] = maskedScope;
+    });
+
+    return maskedContext;
+};
 
 postProcessContext = function (execution, failures) { // function determines whether the event needs to abort
     var error;
@@ -514,6 +553,12 @@ module.exports = {
                 const currentEventItem = event.parent && event.parent(),
 
                     executeScript = ({ resolvedPackages }, done) => {
+                        var contextToUse = _.pick(payload.context, SAFE_CONTEXT_VARIABLES);
+
+                        if (payload.context._forbiddenSecretKeys) {
+                            contextToUse = maskForbiddenSecrets(contextToUse, payload.context._forbiddenSecretKeys);
+                        }
+
                         // finally execute the script
                         this.host.execute(event, {
                             id: executionId,
@@ -522,7 +567,7 @@ module.exports = {
                             // @todo: Expose this as a property in Collection SDK's Script
                             timeout: payload.scriptTimeout,
                             cursor: scriptCursor,
-                            context: _.pick(payload.context, SAFE_CONTEXT_VARIABLES),
+                            context: contextToUse,
                             resolvedPackages: resolvedPackages,
 
                             disabledAPIs: !_.get(this, 'options.script.requestResolver') ?

lib/runner/index.js

@@ -97,6 +97,17 @@ _.assign(Runner.prototype, {
      * @param {String} [options.entrypoint.lookupStrategy=idOrName] strategy to lookup the entrypoint [idOrName, path]
      * @param {Array<String>} [options.entrypoint.path] path to lookup
      * @param {Object} [options.run] Run-specific options, such as options related to the host
+     * @param {Function} [options.secretResolver] - Function({ secrets, url }, callback) that resolves secrets.
+     * Receives: secrets (array of { scopeName, scope, variable, context }), url (request URL without query).
+     * Callback is (err, result).
+     * On fatal error: callback(err) — request execution stops.
+     * On success: callback(null, result) where result is Array<{ resolvedValue?: string,
+     *  error?: Error, allowedInScript?: boolean }>;
+     * result[i] corresponds to secrets[i].
+     * resolvedValue: resolved string (undefined if failed/skipped).
+     * error: Error when resolution failed for particular secret.
+     * allowedInScript: if true, value is exposed to scripts via pm.environment/pm.variables;
+     *       if false/undefined, masked from scripts. Runtime applies values.
      *
      * @param {Function} callback -
      */
@@ -147,7 +158,8 @@ _.assign(Runner.prototype, {
                 collectionVariables: collection.variables,
                 localVariables: options.localVariables,
                 certificates: options.certificates,
-                proxies: options.proxies
+                proxies: options.proxies,
+                secretResolver: options.secretResolver
             }, runOptions)));
         });
     }

lib/runner/resolve-secrets.js

@@ -0,0 +1,130 @@
+var _ = require('lodash'),
+    { resolveUrlString } = require('./util');
+
+/**
+ * Extract all variables with secret === true from a variable scope.
+ *
+ * @param {VariableScope|Object} scope - scope
+ * @returns {Array} - variables
+ */
+function extractSecretVariables (scope) {
+    if (!scope) {
+        return [];
+    }
+
+    var values = _.get(scope, 'values'),
+        secretVariables = [];
+
+    if (!values || typeof values.each !== 'function') {
+        return [];
+    }
+
+    values.each(function (variable) {
+        if (variable && variable.secret === true) {
+            secretVariables.push(variable);
+        }
+    });
+
+    return secretVariables;
+}
+
+/**
+ * Build context object for resolver function
+ *
+ * @param {Object} payload - Request payload
+ * @param {String} variableKey - The key of the variable being resolved
+ * @returns {Object} - Context object
+ */
+function buildResolverContext (payload, variableKey) {
+    return {
+        item: payload.item,
+        variableKey: variableKey
+    };
+}
+
+/**
+ * Scans variable scopes for secrets and invokes the secretResolver with them.
+ * Consumer returns array of { resolvedValue, error, allowedInScript }; runtime applies values.
+ *
+ * @param {Object} payload - Request payload
+ * @param {Object} payload.item - The request item
+ * @param {Object} payload.environment - Environment scope
+ * @param {Object} payload.globals - Globals scope
+ * @param {Object} payload.collectionVariables - Collection variables scope
+ * @param {Object} payload.vaultSecrets - Vault secrets scope
+ * @param {Object} payload._variables - Local variables scope
+ * @param {Object} payload.data - Iteration data
+ * @param {Function} secretResolver - Function({ secrets, urlString }, callback) that resolves secrets.
+ *   Callback is (err, result) where result is Array<{ resolvedValue?: string, error?: Error,
+ *   allowedInScript?: boolean }>.
+ * @param {Function} callback - callback(err, secretResolutionErrors, forbiddenSecretKeys)
+ */
+function resolveSecrets (payload, secretResolver, callback) {
+    if (!secretResolver || typeof secretResolver !== 'function') {
+        return callback();
+    }
+
+    var scopesToScan = [
+            { name: 'environment', scope: payload.environment },
+            { name: 'globals', scope: payload.globals },
+            { name: 'collectionVariables', scope: payload.collectionVariables }
+        ],
+        secrets = [],
+        url = resolveUrlString(payload.item, payload),
+        urlString = typeof url.toString === 'function' ? url.toString() : String(url);
+
+    scopesToScan.forEach(function (scopeInfo) {
+        var secretVars = extractSecretVariables(scopeInfo.scope);
+
+        secretVars.forEach(function (variable) {
+            secrets.push({
+                scopeName: scopeInfo.name,
+                scope: scopeInfo.scope,
+                variable: variable,
+                context: buildResolverContext(payload, variable.key)
+            });
+        });
+    });
+
+    if (secrets.length === 0) {
+        return callback();
+    }
+
+    secretResolver({ secrets, urlString }, function (err, result) {
+        if (err) {
+            return callback(err);
+        }
+
+        if (result && Array.isArray(result)) {
+            result.forEach(function (entry, i) {
+                var hasResolvedValue = entry && entry.resolvedValue !== undefined &&
+                    typeof entry.resolvedValue === 'string';
+
+                if (i < secrets.length && hasResolvedValue) {
+                    secrets[i].variable.set(entry.resolvedValue);
+                }
+            });
+        }
+
+        var secretResolutionErrors = (result && Array.isArray(result)) ?
+                result.filter(function (entry) { return entry && entry.error; })
+                    .map(function (entry) { return entry.error; }) :
+                [],
+            forbiddenSecretKeys = new Set();
+
+        if (result && Array.isArray(result)) {
+            result.forEach(function (entry, i) {
+                if (i < secrets.length && entry && entry.allowedInScript === false) {
+                    forbiddenSecretKeys.add(secrets[i].scopeName + ':' + secrets[i].variable.key);
+                }
+            });
+        }
+
+        callback(null, secretResolutionErrors, forbiddenSecretKeys);
+    });
+}
+
+module.exports = {
+    resolveSecrets,
+    extractSecretVariables
+};