@salesforce/core 6.5.6 → 6.7.0

package/lib/config/sandboxProcessCache.d.ts

@@ -2,8 +2,9 @@ import { SandboxProcessObject, SandboxRequest } from '../org/org';
 import { TTLConfig } from './ttlConfig';
 export type SandboxRequestCacheEntry = {
     alias?: string;
-    setDefault: boolean;
+    setDefault?: boolean;
     prodOrgUsername: string;
+    action: 'Create' | 'Refresh';
     sandboxProcessObject: Partial<SandboxProcessObject>;
     sandboxRequest: Partial<SandboxRequest>;
     tracksSource?: boolean;

package/lib/crypto/crypto.d.ts

@@ -21,6 +21,7 @@ export declare class Crypto extends AsyncOptionalCreatable<CryptoOptions> {
      * @ignore
      */
     constructor(options?: CryptoOptions);
+    private static unsetCryptoVersion;
     /**
      * Encrypts text. Returns the encrypted string or undefined if no string was passed.
      *
@@ -45,10 +46,15 @@ export declare class Crypto extends AsyncOptionalCreatable<CryptoOptions> {
      * Clears the crypto state. This should be called in a finally block.
      */
     close(): void;
+    isV2Crypto(): boolean;
     /**
      * Initialize async components.
      */
     protected init(): Promise<void>;
+    private encryptV1;
+    private encryptV2;
+    private decryptV1;
+    private decryptV2;
     private getKeyChain;
 }
 export {};

package/lib/crypto/crypto.js

@@ -37,23 +37,96 @@ const node_path_1 = require("node:path");
 const ts_types_1 = require("@salesforce/ts-types");
 const kit_1 = require("@salesforce/kit");
 const logger_1 = require("../logger/logger");
+const lifecycleEvents_1 = require("../lifecycleEvents");
 const messages_1 = require("../messages");
 const cache_1 = require("../util/cache");
 const global_1 = require("../global");
+const sfError_1 = require("../sfError");
 const keyChain_1 = require("./keyChain");
 const secureBuffer_1 = require("./secureBuffer");
 const TAG_DELIMITER = ':';
-const BYTE_COUNT_FOR_IV = 6;
+const IV_BYTES = {
+    v1: 6,
+    v2: 12,
+};
+const ENCODING = {
+    v1: 'utf8',
+    v2: 'hex',
+};
+const KEY_SIZE = {
+    v1: 16,
+    v2: 32,
+};
 const ALGO = 'aes-256-gcm';
 const AUTH_TAG_LENGTH = 32;
 const ENCRYPTED_CHARS = /[a-f0-9]/;
 const KEY_NAME = 'sfdx';
 const ACCOUNT = 'local';
+let cryptoLogger;
+const getCryptoLogger = () => {
+    cryptoLogger ??= logger_1.Logger.childFromRoot('crypto');
+    return cryptoLogger;
+};
+const getCryptoV2EnvVar = () => {
+    let sfCryptoV2 = process.env.SF_CRYPTO_V2?.toLowerCase();
+    if (sfCryptoV2 !== undefined) {
+        getCryptoLogger().debug(`SF_CRYPTO_V2=${sfCryptoV2}`);
+        // normalize all values that aren't "true" to be "false"
+        if (sfCryptoV2 !== 'true') {
+            sfCryptoV2 = 'false';
+        }
+    }
+    return sfCryptoV2;
+};
+let cryptoVersion;
+const getCryptoVersion = () => {
+    if (!cryptoVersion) {
+        // This only happens when generating a new key, so use the env var
+        // and (for now) default to 'v1'.
+        cryptoVersion = getCryptoV2EnvVar() === 'true' ? 'v2' : 'v1';
+    }
+    return cryptoVersion;
+};
+// Detect the crypto version based on the password (key) length.
+// This happens once per process.
+const detectCryptoVersion = (pwd) => {
+    if (!cryptoVersion) {
+        // check the env var to see if it's set
+        const sfCryptoV2 = getCryptoV2EnvVar();
+        // Password length of 64 is v2 crypto and uses hex encoding.
+        // Password length of 32 is v1 crypto and uses utf8 encoding.
+        if (pwd?.length === KEY_SIZE.v2 * 2) {
+            cryptoVersion = 'v2';
+            getCryptoLogger().debug('Using v2 crypto');
+            if (sfCryptoV2 === 'false') {
+                getCryptoLogger().warn(messages.getMessage('v1CryptoWithV2KeyWarning'));
+            }
+        }
+        else if (pwd?.length === KEY_SIZE.v1 * 2) {
+            cryptoVersion = 'v1';
+            getCryptoLogger().debug('Using v1 crypto');
+            if (sfCryptoV2 === 'true') {
+                getCryptoLogger().warn(messages.getMessage('v2CryptoWithV1KeyWarning'));
+            }
+        }
+        else {
+            getCryptoLogger().debug("crypto key doesn't match v1 or v2. using SF_CRYPTO_V2.");
+            getCryptoVersion();
+        }
+        void lifecycleEvents_1.Lifecycle.getInstance().emitTelemetry({
+            eventName: 'crypto_version',
+            library: 'sfdx-core',
+            function: 'detectCryptoVersion',
+            cryptoVersion, // 'v1' or 'v2'
+            cryptoEnvVar: sfCryptoV2, // 'true' or 'false' or 'undefined'
+        });
+    }
+};
 ;
-const messages = new messages_1.Messages('@salesforce/core', 'encryption', new Map([["invalidEncryptedFormatError", "The encrypted data is not properly formatted."], ["invalidEncryptedFormatError.actions", ["If attempting to create a scratch org then re-authorize. Otherwise create a new scratch org."]], ["authDecryptError", "Failed to decipher auth data. reason: %s."], ["unsupportedOperatingSystemError", "Unsupported Operating System: %s"], ["missingCredentialProgramError", "Unable to find required security software: %s"], ["credentialProgramAccessError", "Unable to execute security software: %s"], ["passwordRetryError", "Failed to get the password after %i retries."], ["passwordRequiredError", "A password is required."], ["keyChainServiceRequiredError", "Unable to get or set a keychain value without a service name."], ["keyChainAccountRequiredError", "Unable to get or set a keychain value without an account name."], ["keyChainUserCanceledError", "User canceled authentication."], ["keychainPasswordCreationError", "Failed to create a password in the keychain."], ["genericKeychainServiceError", "The service and account specified in %s do not match the version of the toolbelt."], ["genericKeychainServiceError.actions", ["Check your toolbelt version and re-auth."]], ["genericKeychainInvalidPermsError", "Invalid file permissions for secret file"], ["genericKeychainInvalidPermsError.actions", ["Ensure the file %s has the file permission octal value of %s."]], ["passwordNotFoundError", "Could not find password.\n%s"], ["passwordNotFoundError.actions", ["Ensure a valid password is returned with the following command: [%s]"]], ["setCredentialError", "Command failed with response:\n%s"], ["setCredentialError.actions", ["Determine why this command failed to set an encryption key for user %s: [%s]."]], ["macKeychainOutOfSync", "We\u2019ve encountered an error with the Mac keychain being out of sync with your `sfdx` credentials. To fix the problem, sync your credentials by authenticating into your org again using the auth commands."]]));
-const makeSecureBuffer = (password) => {
+const messages = new messages_1.Messages('@salesforce/core', 'encryption', new Map([["invalidEncryptedFormatError", "The encrypted data is not properly formatted."], ["invalidEncryptedFormatError.actions", ["If attempting to create a scratch org then re-authorize. Otherwise create a new scratch org."]], ["authDecryptError", "Failed to decipher auth data. reason: %s."], ["unsupportedOperatingSystemError", "Unsupported Operating System: %s"], ["missingCredentialProgramError", "Unable to find required security software: %s"], ["credentialProgramAccessError", "Unable to execute security software: %s"], ["passwordRetryError", "Failed to get the password after %i retries."], ["passwordRequiredError", "A password is required."], ["keyChainServiceRequiredError", "Unable to get or set a keychain value without a service name."], ["keyChainAccountRequiredError", "Unable to get or set a keychain value without an account name."], ["keyChainUserCanceledError", "User canceled authentication."], ["keychainPasswordCreationError", "Failed to create a password in the keychain."], ["genericKeychainServiceError", "The service and account specified in %s do not match the version of the toolbelt."], ["genericKeychainServiceError.actions", ["Check your toolbelt version and re-auth."]], ["genericKeychainInvalidPermsError", "Invalid file permissions for secret file"], ["genericKeychainInvalidPermsError.actions", ["Ensure the file %s has the file permission octal value of %s."]], ["passwordNotFoundError", "Could not find password.\n%s"], ["passwordNotFoundError.actions", ["Ensure a valid password is returned with the following command: [%s]"]], ["setCredentialError", "Command failed with response:\n%s"], ["setCredentialError.actions", ["Determine why this command failed to set an encryption key for user %s: [%s]."]], ["macKeychainOutOfSync", "We\u2019ve encountered an error with the Mac keychain being out of sync with your `sfdx` credentials. To fix the problem, sync your credentials by authenticating into your org again using the auth commands."], ["v1CryptoWithV2KeyWarning", "The SF_CRYPTO_V2 environment variable was set to \"false\" but a v2 crypto key was detected. v1 crypto can only be used with a v1 key. Unset the SF_CRYPTO_V2 environment variable."], ["v2CryptoWithV1KeyWarning", "SF_CRYPTO_V2 was set to \"true\" but a v1 crypto key was detected. v2 crypto can only be used with a v2 key. To generate a v2 key:\n\n1. Logout of all orgs: `sf org logout --all`\n2. Delete the sfdx keychain entry (account: local, service: sfdx). If `SF_USE_GENERIC_UNIX_KEYCHAIN=true` env var is set, you can delete the `key.json` file.\n3. Set `SF_CRYPTO_V2=true` env var.\n4. Re-Authenticate with your orgs using the CLI org login commands."]]));
+const makeSecureBuffer = (password, encoding) => {
     const newSb = new secureBuffer_1.SecureBuffer();
-    newSb.consume(Buffer.from((0, ts_types_1.ensure)(password), 'utf8'));
+    newSb.consume(Buffer.from(password, encoding));
     return newSb;
 };
 /**
@@ -74,14 +147,19 @@ const keychainPromises = {
             return new Promise((resolve, reject) => _keychain.getPassword({ service, account }, (err, password) => {
                 if (err)
                     return reject(err);
-                cache_1.Cache.set(cacheKey, makeSecureBuffer(password));
-                return resolve({ username: account, password: (0, ts_types_1.ensure)(password) });
+                const pwd = (0, ts_types_1.ensure)(password, 'Expected the keychain password to be set');
+                detectCryptoVersion(pwd);
+                cache_1.Cache.set(cacheKey, makeSecureBuffer(pwd, ENCODING[getCryptoVersion()]));
+                return resolve({ username: account, password: pwd });
             }));
         }
         else {
-            const pw = sb.value((buffer) => buffer.toString('utf8'));
-            cache_1.Cache.set(cacheKey, makeSecureBuffer(pw));
-            return new Promise((resolve) => resolve({ username: account, password: (0, ts_types_1.ensure)(pw) }));
+            // If the password is cached, we know the crypto version and encoding because it was
+            // detected by the non-cache code path just above this.
+            const encoding = ENCODING[getCryptoVersion()];
+            const pwd = (0, ts_types_1.ensure)(sb.value((buffer) => buffer.toString(encoding)), 'Expected the keychain password to be set');
+            cache_1.Cache.set(cacheKey, makeSecureBuffer(pwd, encoding));
+            return new Promise((resolve) => resolve({ username: account, password: pwd }));
         }
     },
     /**
@@ -116,6 +194,11 @@ class Crypto extends kit_1.AsyncOptionalCreatable {
         this.key = new secureBuffer_1.SecureBuffer();
         this.options = options ?? {};
     }
+    // @ts-expect-error only for test access
+    // eslint-disable-next-line class-methods-use-this
+    static unsetCryptoVersion() {
+        cryptoVersion = undefined;
+    }
     encrypt(text) {
         if (text == null) {
             return;
@@ -123,14 +206,13 @@ class Crypto extends kit_1.AsyncOptionalCreatable {
         if (this.key == null) {
             throw messages.createError('keychainPasswordCreationError');
         }
-        const iv = crypto.randomBytes(BYTE_COUNT_FOR_IV).toString('hex');
-        return this.key.value((buffer) => {
-            const cipher = crypto.createCipheriv(ALGO, buffer.toString('utf8'), iv);
-            let encrypted = cipher.update(text, 'utf8', 'hex');
-            encrypted += cipher.final('hex');
-            const tag = cipher.getAuthTag().toString('hex');
-            return `${iv}${encrypted}${TAG_DELIMITER}${tag}`;
-        });
+        // When everything is v2, we can remove the else
+        if (this.isV2Crypto()) {
+            return this.encryptV2(text);
+        }
+        else {
+            return this.encryptV1(text);
+        }
     }
     decrypt(text) {
         if (text == null) {
@@ -140,27 +222,13 @@ class Crypto extends kit_1.AsyncOptionalCreatable {
         if (tokens.length !== 2) {
             throw messages.createError('invalidEncryptedFormatError');
         }
-        const tag = tokens[1];
-        const iv = tokens[0].substring(0, BYTE_COUNT_FOR_IV * 2);
-        const secret = tokens[0].substring(BYTE_COUNT_FOR_IV * 2, tokens[0].length);
-        return this.key.value((buffer) => {
-            const decipher = crypto.createDecipheriv(ALGO, buffer.toString('utf8'), iv);
-            let dec;
-            try {
-                decipher.setAuthTag(Buffer.from(tag, 'hex'));
-                dec = decipher.update(secret, 'hex', 'utf8');
-                dec += decipher.final('utf8');
-            }
-            catch (err) {
-                const error = messages.createError('authDecryptError', [err.message], [], err);
-                const useGenericUnixKeychain = kit_1.env.getBoolean('SF_USE_GENERIC_UNIX_KEYCHAIN') || kit_1.env.getBoolean('USE_GENERIC_UNIX_KEYCHAIN');
-                if (os.platform() === 'darwin' && !useGenericUnixKeychain) {
-                    error.actions = [messages.getMessage('macKeychainOutOfSync')];
-                }
-                throw error;
-            }
-            return dec;
-        });
+        // When everything is v2, we can remove the else
+        if (this.isV2Crypto()) {
+            return this.decryptV2(tokens);
+        }
+        else {
+            return this.decryptV1(tokens);
+        }
     }
     /**
      * Takes a best guess if the value provided was encrypted by {@link Crypto.encrypt} by
@@ -181,7 +249,7 @@ class Crypto extends kit_1.AsyncOptionalCreatable {
         const tag = tokens[1];
         const value = tokens[0];
         return (tag.length === AUTH_TAG_LENGTH &&
-            value.length >= BYTE_COUNT_FOR_IV &&
+            value.length >= IV_BYTES[getCryptoVersion()] &&
             ENCRYPTED_CHARS.test(tag) &&
             ENCRYPTED_CHARS.test(tokens[0]));
     }
@@ -193,33 +261,39 @@ class Crypto extends kit_1.AsyncOptionalCreatable {
             this.key.clear();
         }
     }
+    // eslint-disable-next-line class-methods-use-this
+    isV2Crypto() {
+        return getCryptoVersion() === 'v2';
+    }
     /**
      * Initialize async components.
      */
     async init() {
-        const logger = await logger_1.Logger.child('crypto');
         if (!this.options.platform) {
             this.options.platform = os.platform();
         }
-        logger.debug(`retryStatus: ${this.options.retryStatus}`);
         this.noResetOnClose = !!this.options.noResetOnClose;
         try {
-            this.key.consume(Buffer.from((await keychainPromises.getPassword(await this.getKeyChain(this.options.platform), KEY_NAME, ACCOUNT))
-                .password, 'utf8'));
+            const keyChain = await this.getKeyChain(this.options.platform);
+            const pwd = (await keychainPromises.getPassword(keyChain, KEY_NAME, ACCOUNT)).password;
+            // The above line ensures the crypto version is detected and set so we can rely on it now.
+            this.key.consume(Buffer.from(pwd, ENCODING[getCryptoVersion()]));
         }
         catch (err) {
             // No password found
             if (err.name === 'PasswordNotFoundError') {
                 // If we already tried to create a new key then bail.
                 if (this.options.retryStatus === 'KEY_SET') {
-                    logger.debug('a key was set but the retry to get the password failed.');
+                    getCryptoLogger().debug('a key was set but the retry to get the password failed.');
                     throw err;
                 }
                 else {
-                    logger.debug('password not found in keychain attempting to created one and re-init.');
+                    getCryptoLogger().debug(`password not found in keychain. Creating new one (Crypto ${getCryptoVersion()}) and re-init.`);
                 }
-                const key = crypto.randomBytes(Math.ceil(16)).toString('hex');
-                // Create a new password in the KeyChain.
+                // 2/6/2024: This generates a new key using the crypto version based on the SF_CRYPTO_V2 env var.
+                // Sometime in the future we could hardcode this to be `KEY_SIZE.v2` so that it becomes the default.
+                const key = crypto.randomBytes(KEY_SIZE[getCryptoVersion()]).toString('hex');
+                // Set the new password in the KeyChain.
                 await keychainPromises.setPassword((0, ts_types_1.ensure)(this.options.keychain), KEY_NAME, ACCOUNT, key);
                 return this.init();
             }
@@ -228,6 +302,68 @@ class Crypto extends kit_1.AsyncOptionalCreatable {
             }
         }
     }
+    encryptV1(text) {
+        const iv = crypto.randomBytes(IV_BYTES.v1).toString('hex');
+        return this.key.value((buffer) => {
+            const cipher = crypto.createCipheriv(ALGO, buffer.toString('utf8'), iv);
+            let encrypted = cipher.update(text, 'utf8', 'hex');
+            encrypted += cipher.final('hex');
+            const tag = cipher.getAuthTag().toString('hex');
+            return `${iv}${encrypted}${TAG_DELIMITER}${tag}`;
+        });
+    }
+    encryptV2(text) {
+        const iv = crypto.randomBytes(IV_BYTES.v2);
+        return this.key.value((buffer) => {
+            const cipher = crypto.createCipheriv(ALGO, buffer, iv);
+            const ivHex = iv.toString('hex');
+            let encrypted = cipher.update(text, 'utf8', 'hex');
+            encrypted += cipher.final('hex');
+            const tag = cipher.getAuthTag().toString('hex');
+            return `${ivHex}${encrypted}${TAG_DELIMITER}${tag}`;
+        });
+    }
+    decryptV1(tokens) {
+        const tag = tokens[1];
+        const iv = tokens[0].substring(0, IV_BYTES.v1 * 2);
+        const secret = tokens[0].substring(IV_BYTES.v1 * 2, tokens[0].length);
+        return this.key.value((buffer) => {
+            const decipher = crypto.createDecipheriv(ALGO, buffer.toString('utf8'), iv);
+            try {
+                decipher.setAuthTag(Buffer.from(tag, 'hex'));
+                return `${decipher.update(secret, 'hex', 'utf8')}${decipher.final('utf8')}`;
+            }
+            catch (err) {
+                const error = messages.createError('authDecryptError', [err.message], [], err);
+                const useGenericUnixKeychain = kit_1.env.getBoolean('SF_USE_GENERIC_UNIX_KEYCHAIN') || kit_1.env.getBoolean('USE_GENERIC_UNIX_KEYCHAIN');
+                if (os.platform() === 'darwin' && !useGenericUnixKeychain) {
+                    error.actions = [messages.getMessage('macKeychainOutOfSync')];
+                }
+                throw error;
+            }
+        });
+    }
+    decryptV2(tokens) {
+        const tag = tokens[1];
+        const iv = tokens[0].substring(0, IV_BYTES.v2 * 2);
+        const secret = tokens[0].substring(IV_BYTES.v2 * 2, tokens[0].length);
+        return this.key.value((buffer) => {
+            const decipher = crypto.createDecipheriv(ALGO, buffer, Buffer.from(iv, 'hex'));
+            try {
+                decipher.setAuthTag(Buffer.from(tag, 'hex'));
+                return `${decipher.update(secret, 'hex', 'utf8')}${decipher.final('utf8')}`;
+            }
+            catch (_err) {
+                const err = ((0, ts_types_1.isString)(_err) ? sfError_1.SfError.wrap(_err) : _err);
+                const error = messages.createError('authDecryptError', [err.message], [], err);
+                const useGenericUnixKeychain = kit_1.env.getBoolean('SF_USE_GENERIC_UNIX_KEYCHAIN') || kit_1.env.getBoolean('USE_GENERIC_UNIX_KEYCHAIN');
+                if (os.platform() === 'darwin' && !useGenericUnixKeychain) {
+                    error.actions = [messages.getMessage('macKeychainOutOfSync')];
+                }
+                throw error;
+            }
+        });
+    }
     async getKeyChain(platform) {
         if (!this.options.keychain) {
             this.options.keychain = await (0, keyChain_1.retrieveKeychain)(platform);

package/lib/crypto/keyChain.js

@@ -12,7 +12,7 @@ const logger_1 = require("../logger/logger");
 const messages_1 = require("../messages");
 const keyChainImpl_1 = require("./keyChainImpl");
 ;
-const messages = new messages_1.Messages('@salesforce/core', 'encryption', new Map([["invalidEncryptedFormatError", "The encrypted data is not properly formatted."], ["invalidEncryptedFormatError.actions", ["If attempting to create a scratch org then re-authorize. Otherwise create a new scratch org."]], ["authDecryptError", "Failed to decipher auth data. reason: %s."], ["unsupportedOperatingSystemError", "Unsupported Operating System: %s"], ["missingCredentialProgramError", "Unable to find required security software: %s"], ["credentialProgramAccessError", "Unable to execute security software: %s"], ["passwordRetryError", "Failed to get the password after %i retries."], ["passwordRequiredError", "A password is required."], ["keyChainServiceRequiredError", "Unable to get or set a keychain value without a service name."], ["keyChainAccountRequiredError", "Unable to get or set a keychain value without an account name."], ["keyChainUserCanceledError", "User canceled authentication."], ["keychainPasswordCreationError", "Failed to create a password in the keychain."], ["genericKeychainServiceError", "The service and account specified in %s do not match the version of the toolbelt."], ["genericKeychainServiceError.actions", ["Check your toolbelt version and re-auth."]], ["genericKeychainInvalidPermsError", "Invalid file permissions for secret file"], ["genericKeychainInvalidPermsError.actions", ["Ensure the file %s has the file permission octal value of %s."]], ["passwordNotFoundError", "Could not find password.\n%s"], ["passwordNotFoundError.actions", ["Ensure a valid password is returned with the following command: [%s]"]], ["setCredentialError", "Command failed with response:\n%s"], ["setCredentialError.actions", ["Determine why this command failed to set an encryption key for user %s: [%s]."]], ["macKeychainOutOfSync", "We\u2019ve encountered an error with the Mac keychain being out of sync with your `sfdx` credentials. To fix the problem, sync your credentials by authenticating into your org again using the auth commands."]]));
+const messages = new messages_1.Messages('@salesforce/core', 'encryption', new Map([["invalidEncryptedFormatError", "The encrypted data is not properly formatted."], ["invalidEncryptedFormatError.actions", ["If attempting to create a scratch org then re-authorize. Otherwise create a new scratch org."]], ["authDecryptError", "Failed to decipher auth data. reason: %s."], ["unsupportedOperatingSystemError", "Unsupported Operating System: %s"], ["missingCredentialProgramError", "Unable to find required security software: %s"], ["credentialProgramAccessError", "Unable to execute security software: %s"], ["passwordRetryError", "Failed to get the password after %i retries."], ["passwordRequiredError", "A password is required."], ["keyChainServiceRequiredError", "Unable to get or set a keychain value without a service name."], ["keyChainAccountRequiredError", "Unable to get or set a keychain value without an account name."], ["keyChainUserCanceledError", "User canceled authentication."], ["keychainPasswordCreationError", "Failed to create a password in the keychain."], ["genericKeychainServiceError", "The service and account specified in %s do not match the version of the toolbelt."], ["genericKeychainServiceError.actions", ["Check your toolbelt version and re-auth."]], ["genericKeychainInvalidPermsError", "Invalid file permissions for secret file"], ["genericKeychainInvalidPermsError.actions", ["Ensure the file %s has the file permission octal value of %s."]], ["passwordNotFoundError", "Could not find password.\n%s"], ["passwordNotFoundError.actions", ["Ensure a valid password is returned with the following command: [%s]"]], ["setCredentialError", "Command failed with response:\n%s"], ["setCredentialError.actions", ["Determine why this command failed to set an encryption key for user %s: [%s]."]], ["macKeychainOutOfSync", "We\u2019ve encountered an error with the Mac keychain being out of sync with your `sfdx` credentials. To fix the problem, sync your credentials by authenticating into your org again using the auth commands."], ["v1CryptoWithV2KeyWarning", "The SF_CRYPTO_V2 environment variable was set to \"false\" but a v2 crypto key was detected. v1 crypto can only be used with a v1 key. Unset the SF_CRYPTO_V2 environment variable."], ["v2CryptoWithV1KeyWarning", "SF_CRYPTO_V2 was set to \"true\" but a v1 crypto key was detected. v2 crypto can only be used with a v2 key. To generate a v2 key:\n\n1. Logout of all orgs: `sf org logout --all`\n2. Delete the sfdx keychain entry (account: local, service: sfdx). If `SF_USE_GENERIC_UNIX_KEYCHAIN=true` env var is set, you can delete the `key.json` file.\n3. Set `SF_CRYPTO_V2=true` env var.\n4. Re-Authenticate with your orgs using the CLI org login commands."]]));
 /**
  * Gets the os level keychain impl.
  *

package/lib/crypto/keyChainImpl.js

@@ -41,7 +41,7 @@ const kit_1 = require("@salesforce/kit");
 const global_1 = require("../global");
 const messages_1 = require("../messages");
 ;
-const messages = new messages_1.Messages('@salesforce/core', 'encryption', new Map([["invalidEncryptedFormatError", "The encrypted data is not properly formatted."], ["invalidEncryptedFormatError.actions", ["If attempting to create a scratch org then re-authorize. Otherwise create a new scratch org."]], ["authDecryptError", "Failed to decipher auth data. reason: %s."], ["unsupportedOperatingSystemError", "Unsupported Operating System: %s"], ["missingCredentialProgramError", "Unable to find required security software: %s"], ["credentialProgramAccessError", "Unable to execute security software: %s"], ["passwordRetryError", "Failed to get the password after %i retries."], ["passwordRequiredError", "A password is required."], ["keyChainServiceRequiredError", "Unable to get or set a keychain value without a service name."], ["keyChainAccountRequiredError", "Unable to get or set a keychain value without an account name."], ["keyChainUserCanceledError", "User canceled authentication."], ["keychainPasswordCreationError", "Failed to create a password in the keychain."], ["genericKeychainServiceError", "The service and account specified in %s do not match the version of the toolbelt."], ["genericKeychainServiceError.actions", ["Check your toolbelt version and re-auth."]], ["genericKeychainInvalidPermsError", "Invalid file permissions for secret file"], ["genericKeychainInvalidPermsError.actions", ["Ensure the file %s has the file permission octal value of %s."]], ["passwordNotFoundError", "Could not find password.\n%s"], ["passwordNotFoundError.actions", ["Ensure a valid password is returned with the following command: [%s]"]], ["setCredentialError", "Command failed with response:\n%s"], ["setCredentialError.actions", ["Determine why this command failed to set an encryption key for user %s: [%s]."]], ["macKeychainOutOfSync", "We\u2019ve encountered an error with the Mac keychain being out of sync with your `sfdx` credentials. To fix the problem, sync your credentials by authenticating into your org again using the auth commands."]]));
+const messages = new messages_1.Messages('@salesforce/core', 'encryption', new Map([["invalidEncryptedFormatError", "The encrypted data is not properly formatted."], ["invalidEncryptedFormatError.actions", ["If attempting to create a scratch org then re-authorize. Otherwise create a new scratch org."]], ["authDecryptError", "Failed to decipher auth data. reason: %s."], ["unsupportedOperatingSystemError", "Unsupported Operating System: %s"], ["missingCredentialProgramError", "Unable to find required security software: %s"], ["credentialProgramAccessError", "Unable to execute security software: %s"], ["passwordRetryError", "Failed to get the password after %i retries."], ["passwordRequiredError", "A password is required."], ["keyChainServiceRequiredError", "Unable to get or set a keychain value without a service name."], ["keyChainAccountRequiredError", "Unable to get or set a keychain value without an account name."], ["keyChainUserCanceledError", "User canceled authentication."], ["keychainPasswordCreationError", "Failed to create a password in the keychain."], ["genericKeychainServiceError", "The service and account specified in %s do not match the version of the toolbelt."], ["genericKeychainServiceError.actions", ["Check your toolbelt version and re-auth."]], ["genericKeychainInvalidPermsError", "Invalid file permissions for secret file"], ["genericKeychainInvalidPermsError.actions", ["Ensure the file %s has the file permission octal value of %s."]], ["passwordNotFoundError", "Could not find password.\n%s"], ["passwordNotFoundError.actions", ["Ensure a valid password is returned with the following command: [%s]"]], ["setCredentialError", "Command failed with response:\n%s"], ["setCredentialError.actions", ["Determine why this command failed to set an encryption key for user %s: [%s]."]], ["macKeychainOutOfSync", "We\u2019ve encountered an error with the Mac keychain being out of sync with your `sfdx` credentials. To fix the problem, sync your credentials by authenticating into your org again using the auth commands."], ["v1CryptoWithV2KeyWarning", "The SF_CRYPTO_V2 environment variable was set to \"false\" but a v2 crypto key was detected. v1 crypto can only be used with a v1 key. Unset the SF_CRYPTO_V2 environment variable."], ["v2CryptoWithV1KeyWarning", "SF_CRYPTO_V2 was set to \"true\" but a v1 crypto key was detected. v2 crypto can only be used with a v2 key. To generate a v2 key:\n\n1. Logout of all orgs: `sf org logout --all`\n2. Delete the sfdx keychain entry (account: local, service: sfdx). If `SF_USE_GENERIC_UNIX_KEYCHAIN=true` env var is set, you can delete the `key.json` file.\n3. Set `SF_CRYPTO_V2=true` env var.\n4. Re-Authenticate with your orgs using the CLI org login commands."]]));
 const GET_PASSWORD_RETRY_COUNT = 3;
 /**
  * Helper to reduce an array of cli args down to a presentable string for logging.

package/lib/exported.d.ts

@@ -20,7 +20,7 @@ export { SfdcUrl } from './util/sfdcUrl';
 export { getJwtAudienceUrl } from './util/getJwtAudienceUrl';
 export { Fields, FieldValue, LoggerLevel, LoggerLevelValue, LogLine, LoggerOptions, Logger } from './logger/logger';
 export { Messages, StructuredMessage } from './messages';
-export { Org, SandboxProcessObject, StatusEvent, SandboxEvents, SandboxUserAuthResponse, SandboxUserAuthRequest, SandboxRequest, ResumeSandboxRequest, OrgTypes, ResultEvent, ScratchOrgRequest, } from './org/org';
+export { Org, SandboxProcessObject, StatusEvent, SandboxInfo, SandboxEvents, SandboxUserAuthResponse, SandboxUserAuthRequest, SandboxRequest, ResumeSandboxRequest, OrgTypes, ResultEvent, ScratchOrgRequest, } from './org/org';
 export { OrgConfigProperties, ORG_CONFIG_ALLOWED_PROPERTIES } from './org/orgConfigProperties';
 export { PackageDir, NamedPackageDir, PackageDirDependency, SfProject, SfProjectJson } from './sfProject';
 export { SchemaValidator } from './schema/validator';

package/lib/org/org.d.ts

@@ -71,6 +71,24 @@ export type ResumeSandboxRequest = {
     SandboxName?: string;
     SandboxProcessObjId?: string;
 };
+export type SandboxInfo = {
+    Id: string;
+    IsDeleted: boolean;
+    CreatedDate: string;
+    CreatedById: string;
+    LastModifiedDate: string;
+    LastModifiedById: string;
+    SandboxName: string;
+    LicenseType: 'DEVELOPER' | 'DEVELOPER PRO' | 'PARTIAL' | 'FULL';
+    TemplateId?: string;
+    HistoryDays: -1 | 0 | 10 | 20 | 30 | 60 | 90 | 120 | 150 | 180;
+    CopyChatter: boolean;
+    AutoActivate: boolean;
+    ApexClassId?: string;
+    Description?: string;
+    SourceId?: string;
+    CopyArchivedActivities?: boolean;
+};
 export type ScratchOrgRequest = Omit<ScratchOrgCreateOptions, 'hubOrg'>;
 export type SandboxFields = {
     sandboxOrgId: string;
@@ -130,6 +148,18 @@ export declare class Org extends AsyncOptionalCreatable<Org.Options> {
         interval?: Duration;
         async?: boolean;
     }): Promise<SandboxProcessObject>;
+    /**
+     * Refresh (update) a sandbox from a production org.
+     * 'this' needs to be a production org with sandbox licenses available
+     *
+     * @param sandboxInfo SandboxInfo to update the sandbox with
+     * @param options Wait: The amount of time to wait before timing out, Interval: The time interval between polling
+     */
+    refreshSandbox(sandboxInfo: SandboxInfo, options?: {
+        wait?: Duration;
+        interval?: Duration;
+        async?: boolean;
+    }): Promise<SandboxProcessObject>;
     /**
      *
      * @param sandboxReq SandboxRequest options to create the sandbox with
@@ -142,10 +172,10 @@ export declare class Org extends AsyncOptionalCreatable<Org.Options> {
         interval?: Duration;
     }): Promise<SandboxProcessObject>;
     /**
-     * Resume a sandbox creation from a production org.
+     * Resume a sandbox create or refresh from a production org.
      * `this` needs to be a production org with sandbox licenses available.
      *
-     * @param resumeSandboxRequest SandboxRequest options to create the sandbox with
+     * @param resumeSandboxRequest SandboxRequest options to create/refresh the sandbox with
      * @param options Wait: The amount of time to wait (default: 0 minutes) before timing out,
      * Interval: The time interval (default: 30 seconds) between polling
      */

package/lib/org/org.js

@@ -52,7 +52,7 @@ const authInfo_1 = require("./authInfo");
 const scratchOrgCreate_1 = require("./scratchOrgCreate");
 const orgConfigProperties_1 = require("./orgConfigProperties");
 ;
-const messages = new messages_1.Messages('@salesforce/core', 'org', new Map([["notADevHub", "The provided dev hub username %s is not a valid dev hub."], ["noUsernameFound", "No username found."], ["noDevHubFound", "Unable to associate this scratch org with a DevHub."], ["deleteOrgHubError", "The Dev Hub org cannot be deleted."], ["insufficientAccessToDelete", "You do not have the appropriate permissions to delete a scratch org. Please contact your Salesforce admin."], ["scratchOrgNotFound", "Attempting to delete an expired or deleted org"], ["sandboxDeleteFailed", "The sandbox org deletion failed with a result of %s."], ["sandboxNotFound", "We can't find a SandboxProcess for the sandbox %s."], ["sandboxInfoCreateFailed", "The sandbox org creation failed with a result of %s."], ["missingAuthUsername", "The sandbox %s does not have an authorized username."], ["orgPollingTimeout", "Sandbox status is %s; timed out waiting for completion."], ["NotFoundOnDevHub", "The scratch org does not belong to the dev hub username %s."], ["AuthInfoOrgIdUndefined", "AuthInfo orgId is undefined."], ["sandboxCreateNotComplete", "The sandbox creation has not completed."], ["SandboxProcessNotFoundBySandboxName", "We can't find a SandboxProcess with the SandboxName %s."], ["MultiSandboxProcessNotFoundBySandboxName", "We found more than one SandboxProcess with the SandboxName %s."], ["sandboxNotResumable", "The sandbox %s cannot resume with status of %s."]]));
+const messages = new messages_1.Messages('@salesforce/core', 'org', new Map([["notADevHub", "The provided dev hub username %s is not a valid dev hub."], ["noUsernameFound", "No username found."], ["noDevHubFound", "Unable to associate this scratch org with a DevHub."], ["deleteOrgHubError", "The Dev Hub org cannot be deleted."], ["insufficientAccessToDelete", "You do not have the appropriate permissions to delete a scratch org. Please contact your Salesforce admin."], ["scratchOrgNotFound", "Attempting to delete an expired or deleted org"], ["sandboxDeleteFailed", "The sandbox org deletion failed with a result of %s."], ["sandboxNotFound", "We can't find a SandboxProcess for the sandbox %s."], ["sandboxInfoCreateFailed", "The sandbox org creation failed with a result of %s."], ["sandboxInfoRefreshFailed", "The sandbox org refresh failed with a result of %s."], ["missingAuthUsername", "The sandbox %s does not have an authorized username."], ["orgPollingTimeout", "Sandbox status is %s; timed out waiting for completion."], ["NotFoundOnDevHub", "The scratch org does not belong to the dev hub username %s."], ["AuthInfoOrgIdUndefined", "AuthInfo orgId is undefined."], ["sandboxCreateNotComplete", "The sandbox creation has not completed."], ["SandboxProcessNotFoundBySandboxName", "We can't find a SandboxProcess with the SandboxName %s."], ["MultiSandboxProcessNotFoundBySandboxName", "We found more than one SandboxProcess with the SandboxName %s."], ["sandboxNotResumable", "The sandbox %s cannot resume with status of %s."]]));
 var OrgTypes;
 (function (OrgTypes) {
     OrgTypes["Scratch"] = "scratch";
@@ -72,6 +72,19 @@ function sandboxIsResumable(value) {
     return resumableSandboxStatus.includes(value);
 }
 exports.sandboxIsResumable = sandboxIsResumable;
+const sandboxProcessFields = [
+    'Id',
+    'Status',
+    'SandboxName',
+    'SandboxInfoId',
+    'LicenseType',
+    'CreatedDate',
+    'CopyProgress',
+    'SandboxOrganization',
+    'SourceId',
+    'Description',
+    'EndDate',
+];
 /**
  * Provides a way to manage a locally authenticated Org.
  *
@@ -141,6 +154,46 @@ class Org extends kit_1.AsyncOptionalCreatable {
             pollInterval,
         });
     }
+    /**
+     * Refresh (update) a sandbox from a production org.
+     * 'this' needs to be a production org with sandbox licenses available
+     *
+     * @param sandboxInfo SandboxInfo to update the sandbox with
+     * @param options Wait: The amount of time to wait before timing out, Interval: The time interval between polling
+     */
+    async refreshSandbox(sandboxInfo, options = {
+        wait: kit_1.Duration.minutes(6),
+        async: false,
+        interval: kit_1.Duration.seconds(30),
+    }) {
+        this.logger.debug(sandboxInfo, 'RefreshSandbox called with SandboxInfo');
+        const refreshResult = await this.connection.tooling.update('SandboxInfo', sandboxInfo);
+        this.logger.debug(refreshResult, 'Return from calling tooling.update');
+        if (!refreshResult.success) {
+            throw messages.createError('sandboxInfoRefreshFailed', [JSON.stringify(refreshResult)]);
+        }
+        const soql = `SELECT ${sandboxProcessFields.join(',')} FROM SandboxProcess WHERE SandboxName='${sandboxInfo.SandboxName}' ORDER BY CreatedDate DESC`;
+        const sbxProcessObjects = (await this.connection.tooling.query(soql)).records.filter((item) => !item.Status.startsWith('Del'));
+        this.logger.debug(sbxProcessObjects, `SandboxProcesses for ${sandboxInfo.SandboxName}`);
+        // throw if none found
+        if (sbxProcessObjects?.length === 0) {
+            throw new Error(`No SandboxProcesses found for: ${sandboxInfo.SandboxName}`);
+        }
+        const sandboxRefreshProgress = sbxProcessObjects[0];
+        const isAsync = !!options.async;
+        if (isAsync) {
+            // The user didn't want us to poll, so simply return the status
+            await lifecycleEvents_1.Lifecycle.getInstance().emit(SandboxEvents.EVENT_ASYNC_RESULT, sandboxRefreshProgress);
+            return sandboxRefreshProgress;
+        }
+        const [wait, pollInterval] = this.validateWaitOptions(options);
+        this.logger.debug(sandboxRefreshProgress, `refresh - pollStatusAndAuth sandboxProcessObj, max wait time of ${wait.minutes} minutes`);
+        return this.pollStatusAndAuth({
+            sandboxProcessObj: sandboxRefreshProgress,
+            wait,
+            pollInterval,
+        });
+    }
     /**
      *
      * @param sandboxReq SandboxRequest options to create the sandbox with
@@ -154,10 +207,10 @@ class Org extends kit_1.AsyncOptionalCreatable {
         return this.createSandbox(sandboxReq, options);
     }
     /**
-     * Resume a sandbox creation from a production org.
+     * Resume a sandbox create or refresh from a production org.
      * `this` needs to be a production org with sandbox licenses available.
      *
-     * @param resumeSandboxRequest SandboxRequest options to create the sandbox with
+     * @param resumeSandboxRequest SandboxRequest options to create/refresh the sandbox with
      * @param options Wait: The amount of time to wait (default: 0 minutes) before timing out,
      * Interval: The time interval (default: 30 seconds) between polling
      */
@@ -861,7 +914,7 @@ class Org extends kit_1.AsyncOptionalCreatable {
     async queryLatestSandboxProcessBySandboxName(sandboxNameIn) {
         const { tooling } = this.getConnection();
         this.logger.debug(`QueryLatestSandboxProcessBySandboxName called with SandboxName: ${sandboxNameIn}`);
-        const queryStr = `SELECT Id, Status, SandboxName, SandboxInfoId, LicenseType, CreatedDate, CopyProgress, SandboxOrganization, SourceId, Description, EndDate FROM SandboxProcess WHERE SandboxName='${sandboxNameIn}' AND Status != 'D' ORDER BY CreatedDate DESC LIMIT 1`;
+        const queryStr = `SELECT ${sandboxProcessFields.join(',')} FROM SandboxProcess WHERE SandboxName='${sandboxNameIn}' AND Status != 'D' ORDER BY CreatedDate DESC LIMIT 1`;
         const queryResult = await tooling.query(queryStr);
         this.logger.debug(queryResult, 'Return from calling queryToolingApi');
         if (queryResult?.records?.length === 1) {
@@ -1071,6 +1124,17 @@ class Org extends kit_1.AsyncOptionalCreatable {
                 oauth2Options.privateKey = productionAuthFields.privateKey;
                 oauth2Options.clientId = productionAuthFields.clientId;
             }
+            // Before creating the AuthInfo, delete any existing auth files for the sandbox.
+            // This is common when refreshing sandboxes, and will cause AuthInfo to throw
+            // because it doesn't want to overwrite existing auth files.
+            const stateAggregator = await stateAggregator_1.StateAggregator.getInstance();
+            try {
+                await stateAggregator.orgs.read(sandboxRes.authUserName);
+                await stateAggregator.orgs.remove(sandboxRes.authUserName);
+            }
+            catch (e) {
+                // ignore since this is only for deleting existing auth files.
+            }
             const authInfo = await authInfo_1.AuthInfo.create({
                 username: sandboxRes.authUserName,
                 oauth2Options,
@@ -1081,8 +1145,11 @@ class Org extends kit_1.AsyncOptionalCreatable {
                 productionAuthFieldsUsername: productionAuthFields.username,
                 ...oauth2Options,
             }, 'Creating AuthInfo for sandbox');
-            // save auth info for new sandbox
-            await authInfo.save();
+            // save auth info for sandbox
+            await authInfo.save({
+                isScratch: false,
+                isSandbox: true,
+            });
             const sandboxOrgId = authInfo.getFields().orgId;
             if (!sandboxOrgId) {
                 throw messages.createError('AuthInfoOrgIdUndefined');
@@ -1157,7 +1224,7 @@ class Org extends kit_1.AsyncOptionalCreatable {
      * @private
      */
     async querySandboxProcess(where) {
-        const soql = `SELECT Id, Status, SandboxName, SandboxInfoId, LicenseType, CreatedDate, CopyProgress, SandboxOrganization, SourceId, Description, EndDate FROM SandboxProcess WHERE ${where} ORDER BY CreatedDate DESC`;
+        const soql = `SELECT ${sandboxProcessFields.join(',')} FROM SandboxProcess WHERE ${where} ORDER BY CreatedDate DESC`;
         const result = (await this.connection.tooling.query(soql)).records.filter((item) => !item.Status.startsWith('Del'));
         if (result.length === 0) {
             throw new sfError_1.SfError(`No record found for ${soql}`, connection_1.SingleRecordQueryErrors.NoRecords);
@@ -1204,15 +1271,15 @@ class Org extends kit_1.AsyncOptionalCreatable {
             return result;
         }
         catch (err) {
-            const error = err;
+            const error = err instanceof Error ? err : sfError_1.SfError.wrap((0, ts_types_1.isString)(err) ? err : 'unknown');
             // There are cases where the endDate is set before the sandbox has actually completed.
             // In that case, the sandboxAuth call will throw a specific exception.
             if (error?.name === 'INVALID_STATUS') {
-                this.logger.debug('Error while authenticating the user', error?.toString());
+                this.logger.debug('Error while authenticating the user:', error.message);
             }
             else {
-                // If it fails for any unexpected reason, just pass that through
-                throw sfError_1.SfError.wrap(error);
+                // If it fails for any unexpected reason, rethrow
+                throw error;
             }
         }
     }

package/messages/encryption.md

@@ -83,3 +83,16 @@ Command failed with response:
 # macKeychainOutOfSync
 
 We’ve encountered an error with the Mac keychain being out of sync with your `sfdx` credentials. To fix the problem, sync your credentials by authenticating into your org again using the auth commands.
+
+# v1CryptoWithV2KeyWarning
+
+The SF_CRYPTO_V2 environment variable was set to "false" but a v2 crypto key was detected. v1 crypto can only be used with a v1 key. Unset the SF_CRYPTO_V2 environment variable.
+
+# v2CryptoWithV1KeyWarning
+
+SF_CRYPTO_V2 was set to "true" but a v1 crypto key was detected. v2 crypto can only be used with a v2 key. To generate a v2 key:
+
+1. Logout of all orgs: `sf org logout --all`
+2. Delete the sfdx keychain entry (account: local, service: sfdx). If `SF_USE_GENERIC_UNIX_KEYCHAIN=true` env var is set, you can delete the `key.json` file.
+3. Set `SF_CRYPTO_V2=true` env var.
+4. Re-Authenticate with your orgs using the CLI org login commands.

package/messages/org.md

@@ -34,6 +34,10 @@ We can't find a SandboxProcess for the sandbox %s.
 
 The sandbox org creation failed with a result of %s.
 
+# sandboxInfoRefreshFailed
+
+The sandbox org refresh failed with a result of %s.
+
 # missingAuthUsername
 
 The sandbox %s does not have an authorized username.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/core",
-  "version": "6.5.6",
+  "version": "6.7.0",
   "description": "Core libraries to interact with SFDX projects, orgs, and APIs.",
   "main": "lib/exported",
   "types": "lib/exported.d.ts",