Add secret and source property to Variable (#1422)

* feat: add secret property to `Variable`

* feat: Add ability to set secret variables in `VariableScope`

* fix: remove redundant check

* feat: Add ability to track secret variables in mutations

* Add `source` property to support referencing of secret type of variable. (#1421)

* Add ref prop within variable for secret support

* Renamed "ref" to "source" to better align with postman-runtime

* 5.2.1-beta.1

* Add changelog

* 5.3.0-beta.1

* Updated JSDoc type interfaces with exact structure of source field

* Added unit tests for variable.source property creation/updation

* remove separate definition of type secret as any to be used as fallback

* revert back the original package.json version

* chore: fix types

---------

Co-authored-by: Appurva Murawat <appurva21@proton.me>

---------

Co-authored-by: Vishal Shingala <vishalb.shingala@gmail.com>

Author: appurva21

CHANGELOG.yaml

@@ -1,3 +1,10 @@
+unreleased:
+  new features:
+    - Add `secret` property to `Variable`
+    - Add ability to set secret variables using `VariableScope.set()` method
+    - Add ability to track secret variables in mutations
+    - Add `source` property in variables to resolve secrets
+
 5.2.1:
   date: 2026-02-04
   chores:

lib/collection/mutation-tracker.js

@@ -21,7 +21,8 @@ var _ = require('../util').lodash,
      * @returns {Boolean}
      */
     isPrimitiveMutation = function (mutation) {
-        return mutation && mutation.length <= 2;
+        // Primitive mutations can have 1-3 elements: [key], [key, value], [key, value, metadata]
+        return mutation && mutation.length <= 3;
     },
 
     /**
@@ -53,10 +54,14 @@ var _ = require('../util').lodash,
  * This captures the instruction and the parameters of the instruction so that it can be replayed on a different object.
  * Mutations can be any change on an object. For example setting a key or unsetting a key.
  *
- * For example, the mutation to set `name` on an object to 'Bruce Wayne' would look like ['name', 'Bruce Wayne']. Where
- * the first item is the key path and second item is the value. To add a property `punchLine` to the object it would be
- * the same as updating the property i.e. ['punchLine', 'I\'m Batman']. To remove a property `age` the mutation would
- * look like ['age'].
+ * Mutation formats:
+ * - SET without metadata: ['key', 'value']
+ * - SET with metadata: ['key', 'value', { metadata }]
+ * - UNSET: ['key']
+ *
+ * For example, the mutation to set `name` on an object to 'Bruce Wayne' would look like ['name', 'Bruce Wayne'].
+ * To set a variable with secret flag: ['password', 'secret123', { secret: true }].
+ * To remove a property `age` the mutation would look like ['age'].
  *
  * This format of representing changes is derived from
  * {@link http://json-delta.readthedocs.io/en/latest/philosophy.html}.
@@ -65,6 +70,10 @@ var _ = require('../util').lodash,
  * instruction. For more complex mutation the instruction would have to be explicitly stated.
  *
  * @typedef {Array} MutationTracker.mutation
+ * @example
+ * ['password', 'secret123', { secret: true }]  // SET with metadata
+ * ['userId', '42']                             // SET without metadata
+ * ['tempKey']                                  // UNSET
  */
 
 /**

lib/collection/variable-scope.js

@@ -16,6 +16,16 @@ var _ = require('../util').lodash,
         UNSET: 'unset'
     },
 
+    /**
+     * Properties that should be tracked in mutations when set on variables.
+     * Add new properties here to have them automatically tracked and replayed.
+     *
+     * @private
+     * @constant
+     * @type {Array}
+     */
+    TRACKED_PROPERTIES = ['secret'],
+
     VariableScope;
 
 /**
@@ -226,16 +236,25 @@ _.assign(VariableScope.prototype, /** @lends VariableScope.prototype */ {
      *
      * @param {String} key - The name of the variable to set.
      * @param {*} value - The value of the variable to be set.
-     * @param {Variable.types} [type] - Optionally, the value of the variable can be set to a type
+     * @param {Variable.types|Object} [options] - Optional configuration for the variable.
+     * Can be a string (e.g., 'string', 'number') or an object with properties:
+     * - `type` {String} - The variable type
+     * - `secret` {Boolean} - Whether the variable contains secret/sensitive data
      */
-    set: function (key, value, type) {
+    set: function (key, value, options) {
         const _key = (this.prefix || '') + key;
         var variable = this.values.oneNormalizedVariable(_key),
 
             // create an object that will be used as setter
             update = { key: _key, value: value };
 
-        _.isString(type) && (update.type = type);
+        // handle third parameter - can be a string (type) or object ({ type, secret })
+        if (_.isString(options)) {
+            options = { type: options };
+        }
+
+        options && _.isString(options.type) && (update.type = options.type);
+        options && _.isBoolean(options.secret) && (update.secret = options.secret);
 
         // If a variable by the name key exists, update it's value and return.
         // @note adds new variable if existing is disabled. Disabled variables are not updated.
@@ -247,7 +266,10 @@ _.assign(VariableScope.prototype, /** @lends VariableScope.prototype */ {
         }
 
         // track the change if mutation tracking is enabled
-        this._postman_enableTracking && this.mutations.track(MUTATIONS.SET, key, value);
+        // include tracked properties in mutations so they are preserved during replay
+        if (this._postman_enableTracking) {
+            this.mutations.track(MUTATIONS.SET, key, value, _.pick(options, TRACKED_PROPERTIES));
+        }
     },
 
     /**
@@ -368,13 +390,14 @@ _.assign(VariableScope.prototype, /** @lends VariableScope.prototype */ {
      * @param {String} instruction Instruction identifying the type of the mutation, e.g. `set`, `unset`
      * @param {String} key -
      * @param {*} value -
+     * @param {Object} [metadata] - Optional metadata object (e.g., { secret: true })
      */
-    applyMutation: function (instruction, key, value) {
+    applyMutation: function (instruction, key, value, metadata) {
         // we know that `set` and `unset` are the only supported instructions
         // and we know the parameter signature of both is the same as the items in a mutation
         /* istanbul ignore else */
         if (this[instruction]) {
-            this[instruction](key, value);
+            this[instruction](key, value, metadata);
         }
     },
 

lib/collection/variable.js

@@ -9,22 +9,125 @@ var _ = require('../util').lodash,
     Variable;
 
 /**
- * The object representation of a Variable consists the variable value and type. It also optionally includes the `id`
+ * Postman integration - local vault.
+ *
+ * @typedef {Object} Variable.sourcePostmanLocal
+ * @property {"postman"} provider
+ * @property {Object} postman
+ * @property {"local"} postman.type
+ * @property {string} postman.secretId
+ * @property {string=} [postman.vaultId]
+ */
+
+/**
+ * Postman integration - cloud vault.
+ *
+ * @typedef {Object} Variable.sourcePostmanCloud
+ * @property {"postman"} provider
+ * @property {Object} postman
+ * @property {"cloud"} postman.type
+ * @property {string} postman.secretId
+ * @property {string} postman.vaultId
+ */
+
+/**
+ * @typedef {Variable.sourcePostmanLocal|Variable.sourcePostmanCloud} Variable.sourcePostman
+ */
+
+/**
+ * Azure Key Vault integration.
+ *
+ * @typedef {Object} Variable.sourceAzure
+ * @property {"azure"} provider
+ * @property {Object} azure
+ * @property {string} azure.secretId
+ */
+
+/**
+ * 1Password integration.
+ *
+ * @typedef {Object} Variable.sourceOnePassword
+ * @property {"1password"} provider
+ * @property {Object} 1password
+ * @property {string} 1password.secretReference
+ */
+
+/**
+ * AWS Secrets Manager integration.
+ *
+ * @typedef {Object} Variable.sourceAws
+ * @property {"aws"} provider
+ * @property {Object} aws
+ * @property {string} aws.secretArn
+ * @property {string=} [aws.roleArn]
+ * @property {string=} [aws.version]
+ * @property {"plaintext"|"json"=} [aws.format]
+ */
+
+/**
+ * HashiCorp Vault integration.
+ *
+ * @typedef {Object} Variable.sourceHashiCorp
+ * @property {"hashicorp"} provider
+ * @property {Object} hashicorp
+ * @property {string} hashicorp.engine
+ * @property {string} hashicorp.path
+ * @property {string} hashicorp.key
+ * @property {string=} [hashicorp.version]
+ */
+
+/**
+ * Source object for external secret resolution. The structure depends on the `provider` field.
+ * Resolver lookup is keyed by `provider`
+ * (for example: "postman", "azure", "1password", "aws", "hashicorp").
+ *
+ * @typedef {
+ *   Variable.sourcePostman |
+ *   Variable.sourceAzure |
+ *   Variable.sourceOnePassword |
+ *   Variable.sourceAws |
+ *   Variable.sourceHashiCorp
+ * } Variable.source
+ */
+
+/**
+ * The object representation of a Variable consists of the variable value and type. It may also include the `id`
  * and a friendly `name` of the variable. The `id` and the `name` of a variable is usually managed and used when a
  * variable is made part of a {@link VariableList} instance.
  *
  * @typedef {Object} Variable.definition
  * @property {*=} [value] - The value of the variable that will be stored and will be typecast to the `type`
  * set in the variable or passed along in this parameter.
  * @property {String=} [type] - The type of this variable from the list of types defined at {@link Variable.types}.
+ * @property {Boolean=} [system] - Indicates whether this is a system variable.
+ * @property {Boolean=} [secret] - Indicates whether this variable contains secret/sensitive data.
+ * @property {Boolean=} [disabled] - Indicates whether this variable is disabled.
+ * @property {Variable.source=} [source] - Optional source object for external secret resolution. Contains metadata
+ * on how to resolve the variable value from an external source. The structure depends on the source `provider` field.
  *
- * @example
+ * @example Default variable
  * {
  *     "id": "my-var-1",
  *     "name": "MyFirstVariable",
  *     "value": "Hello World",
  *     "type": "string"
  * }
+ *
+ * @example Secret variable - Postman local vault
+ * {
+ *     "id": "my-secret-var",
+ *     "key": "apiKey",
+ *     "value": "",
+ *     "type": "secret",
+ *     "source": {
+ *         "provider": "postman",
+ *         "postman": {
+ *             "type": "local",
+ *             "secretId": "ID_OF_THE_SECRET"
+ *             "vaultId": "ID_OF_THE_VAULT"
+ *         }
+ *     }
+ * }
  */
 _.inherit((
 
@@ -55,7 +158,14 @@ _.inherit((
             /**
              * @type {*}
              */
-            value: undefined
+            value: undefined,
+
+            /**
+             * Optional source object for external secret resolution.
+             *
+             * @type {Variable.source}
+             */
+            source: undefined
         });
 
         if (!_.isNil(definition)) {
@@ -206,8 +316,10 @@ _.assign(Variable.prototype, /** @lends Variable.prototype */ {
         _.has(options, 'type') && this.valueType(options.type, _.has(options, 'value'));
         _.has(options, 'value') && this.set(options.value);
         _.has(options, 'system') && (this.system = options.system);
+        _.has(options, 'secret') && (this.secret = options.secret);
         _.has(options, 'disabled') && (this.disabled = options.disabled);
         _.has(options, 'description') && (this.describe(options.description));
+        _.has(options, 'source') && (this.source = options.source);
     }
 });
 

test/unit/mutation-tracker.test.js

@@ -163,12 +163,20 @@ describe('MutationTracker', function () {
         it('should not track invalid mutation format', function () {
             var tracker = new MutationTracker();
 
-            // expected signature is two parameters
-            tracker.track('set', 'foo', 'bar', 'baz');
+            tracker.track('set', 'foo', 'bar', 'baz', 'qux');
 
             expect(tracker.count()).to.eql(0);
         });
 
+        it('should track mutations with metadata (3 parameters)', function () {
+            var tracker = new MutationTracker();
+
+            // new format supports three parameters: key, value, metadata
+            tracker.track('set', 'foo', 'bar', { secret: true });
+
+            expect(tracker.count()).to.eql(1);
+        });
+
         it('should not track mutation with no instruction', function () {
             var tracker = new MutationTracker();