@salesforce/core 9.1.10 → 9.1.12-qa.0

package/lib/config/envVars.d.ts

@@ -77,7 +77,8 @@ export declare enum EnvironmentVariable {
     'SF_UPDATE_INSTRUCTIONS' = "SF_UPDATE_INSTRUCTIONS",
     'SF_INSTALLER' = "SF_INSTALLER",
     'SF_ENV' = "SF_ENV",
-    'SF_CAPITALIZE_RECORD_TYPES' = "SF_CAPITALIZE_RECORD_TYPES"
+    'SF_CAPITALIZE_RECORD_TYPES' = "SF_CAPITALIZE_RECORD_TYPES",
+    'SF_SKIP_SCRATCH_ORG_CHECK' = "SF_SKIP_SCRATCH_ORG_CHECK"
 }
 type EnvMetaData = {
     description: string;

package/lib/config/envVars.js

@@ -22,7 +22,7 @@ const kit_1 = require("@salesforce/kit");
 const messages_1 = require("../messages");
 const lifecycleEvents_1 = require("../lifecycleEvents");
 ;
-const messages = new messages_1.Messages('@salesforce/core', 'envVars', new Map([["forceOpenUrl", "Web page that opens in your browser when you connect to an org. For example, to open Lightning Experience, set to \"lightning\"."], ["forceShowSpinner", "Set to true to show a spinner animation on the command line when running asynchronous CLI commands. Default is false."], ["forceSpinnerDelay", "Speed of the spinner in milliseconds. Default is 60."], ["httpProxy", "HTTP URL and port of the proxy server when using Salesforce CLI behind a corporate firewall or web proxy."], ["httpsProxy", "HTTPS URL and port of the proxy server when using Salesforce CLI behind a corporate firewall or web proxy."], ["nodeExtraCaCerts", "Fully qualified path to your self-signed certificate. Will be installed after you run \"sfdx update\"."], ["nodeTlsRejectUnauthorized", "Set to 0 to allow Node.js to use the self-signed certificate in the certificate chain."], ["sfdxAccessToken", "Specifies an access token when using the auth:accesstoken:store command."], ["sfdxApiVersion", "The API version for a specific project or all projects. Default value is the API version of your Dev Hub. Overrides the apiVersion config value."], ["sfdxAudienceUrl", "URL that overrides the aud (audience) field used for JWT authentication so that it matches the expected value of the authorization server URL for the org you\u2019re logging into."], ["sfdxCodeCoverageRequirement", "Code coverage percentages that are displayed in green when you run force:apex:test:\\* with the --codecoverage parameter."], ["sfdxContentType", "Set to JSON so that all CLI commands output results in JSON format."], ["sfdxDefaultdevhubusername", "Username or alias of your default Dev Hub org. Overrides the defaultdevhubusername configuration value."], ["sfdxDefaultusername", "Username or alias of your default org. Overrides the defaultusername configuration value."], ["sfdxDisableAutoupdate", "Set to true to disable the auto-update feature of Salesforce CLI. Default value is false."], ["sfdxAutoupdateDisable", "Set to true to disable the auto-update feature of Salesforce CLI. Default value is false."], ["sfdxDisableSourceMemberPolling", "Set to true to disable polling of your org\u2019s SourceMember object when you run the force:source:push|pull commands. Default value is false."], ["sfdxSourceTrackingBatchSize", "Number of source-tracked file updates to batch after a deploy or retrieve. The default value is 8,000 (Windows) or 15,000 (Linux/macOS)."], ["sfdxDisableTelemetry", "Set to true to disable Salesforce CLI from collecting usage information, user environment information, and crash reports. Default value is false. Overrides the disableTelemetry configration variable."], ["sfdxDnsTimeout", "Number of seconds that the force:org:\\* commands wait for a response when checking whether an org is connected. Default value is 3."], ["sfdxDomainRetry", "Time, in seconds, that Salesforce CLI waits for the Lightning Experience custom domain to resolve and become available in a scratch org. Default value is 240."], ["sfdxImprovedCodeCoverage", "Set to true to scope Apex test results to the classes entered during a test run when running force:apex:test:\\*."], ["sfdxInstanceUrl", "URL of the Salesforce instance that is hosting your org. Default value is https://login.salesforce.com. Overrides the instanceUrl configuration value."], ["sfdxJsonToStdout", "Set to true to send messages resulting from failed Salesforce CLI commands to stdout instead of stderr."], ["sfdxDisableLogFile", "Set to true to disable log file writing"], ["sfdxLogLevel", "Level of messages that the CLI writes to the log file. Valid values are trace, debug, info, warn, error, fatal. Default value is warn."], ["sfdxLogRotationCount", "The default rotation period for logs. Example '1d' will rotate logs daily (at midnight)."], ["sfdxLogRotationPeriod", "The number of backup rotated log files to keep. Example: '3' will have the base sf.log file, and the past 3 (period) log files."], ["sfdxMaxQueryLimit", "Maximum number of Salesforce records returned by a CLI command. Default value is 10,000. Overrides the maxQueryLimit configuration value."], ["sfdxMdapiTempDir", "Directory that contains files (in metadata format) when running certain Salesforce CLI commands, such as force:source:\\*."], ["sfdxNpmRegistry", "URL to a private npm server, where all packages that you publish are private."], ["sfdxPrecompileEnable", "Set to true to enable Apex pre-compile before the tests are run with the force:apex:test:run command. Default is false."], ["sfdxProjectAutoupdateDisableForPackageCreate", "Set to true to disable automatic updates to sfdx-project.json when running force:package:create."], ["sfdxProjectAutoupdateDisableForPackageVersionCreate", "Set to true to disable automatic updates to sfdx-project.json when running force:package:version:create."], ["sfdxRestDeploy", "Set to true to make Salesforce CLI use the Metadata REST API for deployments. By default, the CLI uses SOAP."], ["sfdxSourceMemberPollingTimeout", "Number of seconds you want the force:source:push command to keep polling the SourceMember object before the command times out."], ["sfdxUseGenericUnixKeychain", "(Linux and macOS only) Set to true if you want to use the generic UNIX keychain instead of the Linux libsecret library or macOS keychain."], ["sfdxUseProgressBar", "Set to false to disable the progress bar when running force:mdapi:deploy, force:source:deploy, or force:source:push."], ["sfdxLazyLoadModules", "Set to true to enable lazy loading of sfdx modules"], ["sfdxS3Host", "URL to S3 host"], ["sfdxUpdateInstructions", "Text that describes how to update sfdx"], ["sfdxInstaller", "Boolean indicating that the installer is running"], ["sfdxEnv", "Describes if sfdx is in \"demo\" mode"], ["sfTargetOrg", "Username or alias of your default org. Overrides the target-org configuration variable."], ["sfTargetDevHub", "Username or alias of your default Dev Hub org. Overrides the target-dev-hub configuration variable."], ["sfAccessToken", "Specifies an access token when using a login command that uses access tokens."], ["sfOrgApiVersion", "API version for a specific project or all projects. Default value is the API version of your Dev Hub. Overrides the apiVersion configuration variable."], ["sfAudienceUrl", "URL that overrides the aud (audience) field used for JWT authentication so that it matches the expected value of the authorization server URL for the org you\u2019re logging into."], ["sfCodeCoverageRequirement", "Code coverage percentages that are displayed in green when you run the Apex test CLIcommands with the --code-coverage flag."], ["sfContentType", "Set to JSON so that all CLI commands output results in JSON format."], ["sfDisableAutoupdate", "Set to true to disable the auto-update feature of Salesforce CLI. Default value is false."], ["sfAutoupdateDisable", "Set to true to disable the auto-update feature of Salesforce CLI. Default value is false."], ["sfDisableSourceMemberPolling", "Set to true to disable polling of your org\u2019s SourceMember object when you run the commands to push and pull source. Default value is false."], ["sfDisableTelemetry", "Set to true to disable Salesforce CLI from collecting usage information, user environment information, and crash reports. Default value is false. Overrides the disableTelemetry configration variable."], ["sfDnsTimeout", "Number of seconds that the env commands wait for a response when checking whether an org is connected. Default value is 3."], ["sfDomainRetry", "Time, in seconds, that Salesforce CLI waits for the Lightning Experience custom domain to resolve and become available in a scratch org. Default value is 240."], ["sfImprovedCodeCoverage", "Set to true to scope Apex test results to the classes entered during a test run when running the Apex test commands."], ["sfOrgInstanceUrl", "URL of the Salesforce instance that is hosting your org. Default value is https://login.salesforce.com. Overrides the instanceUrl configuration variable."], ["sfJsonToStdout", "Set to true to send messages resulting from failed Salesforce CLI commands to stdout instead of stderr."], ["sfDisableLogFile", "Set to true to disable log file writing"], ["sfLogLevel", "Level of messages that the CLI writes to the log file. Valid values are trace, debug, info, warn, error, fatal. Default value is warn."], ["sfLogRotationCount", "The default rotation period for logs. Example '1d' will rotate logs daily (at midnight)."], ["sfLogRotationPeriod", "The number of backup rotated log files to keep. Example: '3' will have the base sf.log file, and the past 3 (period) log files."], ["sfOrgMaxQueryLimit", "Maximum number of Salesforce records returned by a CLI command. Default value is 10,000. Overrides the maxQueryLimit configuration variable."], ["sfMdapiTempDir", "Directory that contains files (in metadata format) when running certain Salesforce CLI commands."], ["sfNpmRegistry", "URL to a private npm server, where all packages that you publish are private."], ["sfPrecompileEnable", "Set to true to enable Apex pre-compile before the tests are run with the Apex test run command. Default is false."], ["sfProjectAutoupdateDisableForPackageCreate", "Set to true to disable automatic updates to sfdx-project.json when running the package create command."], ["sfProjectAutoupdateDisableForPackageVersionCreate", "Set to true to disable automatic updates to sfdx-project.json when running the package version create command."], ["sfSourceMemberPollingTimeout", "Number of seconds you want the source push command to keep polling the SourceMember object before the command times out."], ["sfUseGenericUnixKeychain", "(Linux and macOS only) Set to true if you want to use the generic UNIX keychain instead of the Linux libsecret library or macOS keychain."], ["sfUseProgressBar", "Set to false to disable the progress bar when running the metadata deploy command."], ["sfLazyLoadModules", "Set to true to enable lazy loading of sf modules"], ["sfS3Host", "URL to S3 host"], ["sfUpdateInstructions", "Text that describes how to update sf"], ["sfInstaller", "Boolean indicating that the installer is running"], ["sfEnv", "Describes if sf is in \"demo\" mode"], ["deprecatedEnv", "Deprecated environment variable: %s. Please use %s instead."], ["deprecatedEnvDisagreement", "Deprecated environment variable: %s. Please use %s instead.\n\nYour environment has both variables populated, and with different values. The value from %s will be used."], ["sfCapitalizeRecordTypes", "Whether record types are capitalized on scratch org creation."]]));
+const messages = new messages_1.Messages('@salesforce/core', 'envVars', new Map([["forceOpenUrl", "Web page that opens in your browser when you connect to an org. For example, to open Lightning Experience, set to \"lightning\"."], ["forceShowSpinner", "Set to true to show a spinner animation on the command line when running asynchronous CLI commands. Default is false."], ["forceSpinnerDelay", "Speed of the spinner in milliseconds. Default is 60."], ["httpProxy", "HTTP URL and port of the proxy server when using Salesforce CLI behind a corporate firewall or web proxy."], ["httpsProxy", "HTTPS URL and port of the proxy server when using Salesforce CLI behind a corporate firewall or web proxy."], ["nodeExtraCaCerts", "Fully qualified path to your self-signed certificate. Will be installed after you run \"sfdx update\"."], ["nodeTlsRejectUnauthorized", "Set to 0 to allow Node.js to use the self-signed certificate in the certificate chain."], ["sfdxAccessToken", "Specifies an access token when using the auth:accesstoken:store command."], ["sfdxApiVersion", "The API version for a specific project or all projects. Default value is the API version of your Dev Hub. Overrides the apiVersion config value."], ["sfdxAudienceUrl", "URL that overrides the aud (audience) field used for JWT authentication so that it matches the expected value of the authorization server URL for the org you\u2019re logging into."], ["sfdxCodeCoverageRequirement", "Code coverage percentages that are displayed in green when you run force:apex:test:\\* with the --codecoverage parameter."], ["sfdxContentType", "Set to JSON so that all CLI commands output results in JSON format."], ["sfdxDefaultdevhubusername", "Username or alias of your default Dev Hub org. Overrides the defaultdevhubusername configuration value."], ["sfdxDefaultusername", "Username or alias of your default org. Overrides the defaultusername configuration value."], ["sfdxDisableAutoupdate", "Set to true to disable the auto-update feature of Salesforce CLI. Default value is false."], ["sfdxAutoupdateDisable", "Set to true to disable the auto-update feature of Salesforce CLI. Default value is false."], ["sfdxDisableSourceMemberPolling", "Set to true to disable polling of your org\u2019s SourceMember object when you run the force:source:push|pull commands. Default value is false."], ["sfdxSourceTrackingBatchSize", "Number of source-tracked file updates to batch after a deploy or retrieve. The default value is 8,000 (Windows) or 15,000 (Linux/macOS)."], ["sfdxDisableTelemetry", "Set to true to disable Salesforce CLI from collecting usage information, user environment information, and crash reports. Default value is false. Overrides the disableTelemetry configration variable."], ["sfdxDnsTimeout", "Number of seconds that the force:org:\\* commands wait for a response when checking whether an org is connected. Default value is 3."], ["sfdxDomainRetry", "Time, in seconds, that Salesforce CLI waits for the Lightning Experience custom domain to resolve and become available in a scratch org. Default value is 240."], ["sfdxImprovedCodeCoverage", "Set to true to scope Apex test results to the classes entered during a test run when running force:apex:test:\\*."], ["sfdxInstanceUrl", "URL of the Salesforce instance that is hosting your org. Default value is https://login.salesforce.com. Overrides the instanceUrl configuration value."], ["sfdxJsonToStdout", "Set to true to send messages resulting from failed Salesforce CLI commands to stdout instead of stderr."], ["sfdxDisableLogFile", "Set to true to disable log file writing"], ["sfdxLogLevel", "Level of messages that the CLI writes to the log file. Valid values are trace, debug, info, warn, error, fatal. Default value is warn."], ["sfdxLogRotationCount", "The default rotation period for logs. Example '1d' will rotate logs daily (at midnight)."], ["sfdxLogRotationPeriod", "The number of backup rotated log files to keep. Example: '3' will have the base sf.log file, and the past 3 (period) log files."], ["sfdxMaxQueryLimit", "Maximum number of Salesforce records returned by a CLI command. Default value is 10,000. Overrides the maxQueryLimit configuration value."], ["sfdxMdapiTempDir", "Directory that contains files (in metadata format) when running certain Salesforce CLI commands, such as force:source:\\*."], ["sfdxNpmRegistry", "URL to a private npm server, where all packages that you publish are private."], ["sfdxPrecompileEnable", "Set to true to enable Apex pre-compile before the tests are run with the force:apex:test:run command. Default is false."], ["sfdxProjectAutoupdateDisableForPackageCreate", "Set to true to disable automatic updates to sfdx-project.json when running force:package:create."], ["sfdxProjectAutoupdateDisableForPackageVersionCreate", "Set to true to disable automatic updates to sfdx-project.json when running force:package:version:create."], ["sfdxRestDeploy", "Set to true to make Salesforce CLI use the Metadata REST API for deployments. By default, the CLI uses SOAP."], ["sfdxSourceMemberPollingTimeout", "Number of seconds you want the force:source:push command to keep polling the SourceMember object before the command times out."], ["sfdxUseGenericUnixKeychain", "(Linux and macOS only) Set to true if you want to use the generic UNIX keychain instead of the Linux libsecret library or macOS keychain."], ["sfdxUseProgressBar", "Set to false to disable the progress bar when running force:mdapi:deploy, force:source:deploy, or force:source:push."], ["sfdxLazyLoadModules", "Set to true to enable lazy loading of sfdx modules"], ["sfdxS3Host", "URL to S3 host"], ["sfdxUpdateInstructions", "Text that describes how to update sfdx"], ["sfdxInstaller", "Boolean indicating that the installer is running"], ["sfdxEnv", "Describes if sfdx is in \"demo\" mode"], ["sfTargetOrg", "Username or alias of your default org. Overrides the target-org configuration variable."], ["sfTargetDevHub", "Username or alias of your default Dev Hub org. Overrides the target-dev-hub configuration variable."], ["sfAccessToken", "Specifies an access token when using a login command that uses access tokens."], ["sfOrgApiVersion", "API version for a specific project or all projects. Default value is the API version of your Dev Hub. Overrides the apiVersion configuration variable."], ["sfAudienceUrl", "URL that overrides the aud (audience) field used for JWT authentication so that it matches the expected value of the authorization server URL for the org you\u2019re logging into."], ["sfCodeCoverageRequirement", "Code coverage percentages that are displayed in green when you run the Apex test CLIcommands with the --code-coverage flag."], ["sfContentType", "Set to JSON so that all CLI commands output results in JSON format."], ["sfDisableAutoupdate", "Set to true to disable the auto-update feature of Salesforce CLI. Default value is false."], ["sfAutoupdateDisable", "Set to true to disable the auto-update feature of Salesforce CLI. Default value is false."], ["sfDisableSourceMemberPolling", "Set to true to disable polling of your org\u2019s SourceMember object when you run the commands to push and pull source. Default value is false."], ["sfDisableTelemetry", "Set to true to disable Salesforce CLI from collecting usage information, user environment information, and crash reports. Default value is false. Overrides the disableTelemetry configration variable."], ["sfDnsTimeout", "Number of seconds that the env commands wait for a response when checking whether an org is connected. Default value is 3."], ["sfDomainRetry", "Time, in seconds, that Salesforce CLI waits for the Lightning Experience custom domain to resolve and become available in a scratch org. Default value is 240."], ["sfImprovedCodeCoverage", "Set to true to scope Apex test results to the classes entered during a test run when running the Apex test commands."], ["sfOrgInstanceUrl", "URL of the Salesforce instance that is hosting your org. Default value is https://login.salesforce.com. Overrides the instanceUrl configuration variable."], ["sfJsonToStdout", "Set to true to send messages resulting from failed Salesforce CLI commands to stdout instead of stderr."], ["sfDisableLogFile", "Set to true to disable log file writing"], ["sfLogLevel", "Level of messages that the CLI writes to the log file. Valid values are trace, debug, info, warn, error, fatal. Default value is warn."], ["sfLogRotationCount", "The default rotation period for logs. Example '1d' will rotate logs daily (at midnight)."], ["sfLogRotationPeriod", "The number of backup rotated log files to keep. Example: '3' will have the base sf.log file, and the past 3 (period) log files."], ["sfOrgMaxQueryLimit", "Maximum number of Salesforce records returned by a CLI command. Default value is 10,000. Overrides the maxQueryLimit configuration variable."], ["sfMdapiTempDir", "Directory that contains files (in metadata format) when running certain Salesforce CLI commands."], ["sfNpmRegistry", "URL to a private npm server, where all packages that you publish are private."], ["sfPrecompileEnable", "Set to true to enable Apex pre-compile before the tests are run with the Apex test run command. Default is false."], ["sfProjectAutoupdateDisableForPackageCreate", "Set to true to disable automatic updates to sfdx-project.json when running the package create command."], ["sfProjectAutoupdateDisableForPackageVersionCreate", "Set to true to disable automatic updates to sfdx-project.json when running the package version create command."], ["sfSourceMemberPollingTimeout", "Number of seconds you want the source push command to keep polling the SourceMember object before the command times out."], ["sfUseGenericUnixKeychain", "(Linux and macOS only) Set to true if you want to use the generic UNIX keychain instead of the Linux libsecret library or macOS keychain."], ["sfUseProgressBar", "Set to false to disable the progress bar when running the metadata deploy command."], ["sfLazyLoadModules", "Set to true to enable lazy loading of sf modules"], ["sfS3Host", "URL to S3 host"], ["sfUpdateInstructions", "Text that describes how to update sf"], ["sfInstaller", "Boolean indicating that the installer is running"], ["sfEnv", "Describes if sf is in \"demo\" mode"], ["deprecatedEnv", "Deprecated environment variable: %s. Please use %s instead."], ["deprecatedEnvDisagreement", "Deprecated environment variable: %s. Please use %s instead.\n\nYour environment has both variables populated, and with different values. The value from %s will be used."], ["sfCapitalizeRecordTypes", "Whether record types are capitalized on scratch org creation."], ["sfSkipScratchOrgCheck", "Set to \"true\" to skip the scratch org and sandbox identification check that runs after authenticating an org. When enabled, `sf org login jwt` (and other login commands) will not query existing cached orgs to determine whether the newly authenticated org is a scratch org or sandbox. This can significantly speed up authentication in CI/CD environments with many cached org authorizations."]]));
 var EnvironmentVariable;
 (function (EnvironmentVariable) {
     EnvironmentVariable["FORCE_OPEN_URL"] = "FORCE_OPEN_URL";
@@ -102,6 +102,7 @@ var EnvironmentVariable;
     EnvironmentVariable["SF_INSTALLER"] = "SF_INSTALLER";
     EnvironmentVariable["SF_ENV"] = "SF_ENV";
     EnvironmentVariable["SF_CAPITALIZE_RECORD_TYPES"] = "SF_CAPITALIZE_RECORD_TYPES";
+    EnvironmentVariable["SF_SKIP_SCRATCH_ORG_CHECK"] = "SF_SKIP_SCRATCH_ORG_CHECK";
 })(EnvironmentVariable || (exports.EnvironmentVariable = EnvironmentVariable = {}));
 const getMessage = (environmentVariable) => messages.getMessage((0, change_case_1.camelCase)(environmentVariable));
 exports.SUPPORTED_ENV_VARS = {
@@ -416,6 +417,10 @@ exports.SUPPORTED_ENV_VARS = {
         description: getMessage(EnvironmentVariable.SF_CAPITALIZE_RECORD_TYPES),
         synonymOf: null,
     },
+    [EnvironmentVariable.SF_SKIP_SCRATCH_ORG_CHECK]: {
+        description: getMessage(EnvironmentVariable.SF_SKIP_SCRATCH_ORG_CHECK),
+        synonymOf: null,
+    },
 };
 class EnvVars extends kit_1.Env {
     constructor(env = process.env) {

package/lib/org/authInfo.d.ts

@@ -321,6 +321,72 @@ export declare class AuthInfo extends AsyncOptionalCreatable<AuthInfo.Options> {
     private loadDecryptedAuthFromConfig;
     private isTokenOptions;
     private refreshFn;
+    /**
+     * Single-flight a refresh-token refresh so two connections/processes can't rotate the same token at once.
+     *
+     * With Refresh Token Rotation (RTR) enabled, each refresh returns a new refresh token and invalidates the
+     * previous one; a second refresh sent with the now-stale refresh token fails and invalidates the current token too.
+     * We take a cross-process lock (which also serializes same-process contenders), then re-read the latest
+     * tokens from disk: if another actor already rotated while we waited, we adopt their fresh credentials
+     * instead of refreshing again with our now-invalid token.
+     *
+     * Each pass is one call to `tryRotateOrAdopt`, which (1) adopts if disk already holds a rotated token, else
+     * (2) tries to acquire the lock and, once held, re-checks-then-refreshes. If we can't acquire (a live holder
+     * is mid-rotation, ELOCKED), we do NOT fall back to an unlocked refresh, which would race the holder and double-rotate
+     * under RTR; we simply loop back to (1) and re-run the pass (re-read disk, then try to acquire the lock again).
+     * `proper-lockfile` only grants the lock on genuine release or genuine staleness (a live
+     * holder refreshes its lock mtime ~every 5s and so is never stolen from), so looping converges: a slow holder is waited out,
+     * a dead holder's lock crosses the ~10s stale line and is stolen on a later attempt.
+     * Only a holder that keeps the lock alive for the whole budget below yields the timeout error.
+     *
+     * The lock uses a dedicated `<authfile>.token-rotation.lock`, kept separate from ConfigFile's
+     * own `<authfile>.lock` write lock, because proper-lockfile is not re-entrant: holding the auth-file lock
+     * here and then letting save() re-acquire the same path would self-block.
+     *
+     * KNOWN LIMITATIONS (all inherent, not bugs):
+     *
+     * (1) Only actors that take THIS lock are serialized. Within a single CLI release this is a non-issue: the
+     * CLI deduplicates @salesforce/core to one version, so every in-process refresher runs this same locking
+     * code (and the lock path is derived deterministically, so differing versions that BOTH lock still
+     * interoperate). The realistic gap is a 2nd/3rd-party plugin: those install under the CLI's plugin data dir
+     * with their OWN non-deduped node_modules and may bundle a core version predating this lock. Such a plugin
+     * (or any external tool that refreshes the token directly) won't honor `<authfile>.token-rotation.lock` and
+     * can still double-rotate the same auth while we hold it. There is no server-side coordination to prevent this.
+     *
+     * (2) On the web runtime (Global.isWeb), lockInit is a no-op that takes no lock (matching existing
+     * ConfigFile behavior), so nothing is serialized there.
+     *
+     * (3) A genuinely-stuck holder makes this block for up to the budget below plus one in-flight lock cycle
+     * (~40s) before throwing. Because that happens inside a live jsforce session-refresh, an upstream client
+     * with a shorter timeout may give up first with a less specific error. Only the pathological stuck case
+     * pays this; the common paths return in one lock cycle or via the lock-free adopt.
+     *
+     * @param heldRefreshToken the refresh token this connection currently holds (read from the auth file); the
+     * baseline we compare against disk to detect a rotation, and the token we would send if we do rotate.
+     */
+    private refreshWithTokenRotationLock;
+    /**
+     * One rotation attempt: adopt an already-rotated token if disk has one, else take the lock and
+     * double-check-then-rotate under it.
+     *
+     * @returns `true` if we adopted or refreshed (caller is done); `false` if the lock was contended
+     * (`ELOCKED`) and the caller should re-attempt. Throws on any non-`ELOCKED` failure.
+     */
+    private tryRotateOrAdopt;
+    /**
+     * Re-read the on-disk auth (without disturbing this instance's in-memory fields) and, if another
+     * connection/process has already rotated the refresh token, adopt those fresh credentials. Disk is
+     * already current in that case, so no save is needed.
+     *
+     * NOTE: this gates on the refresh token only, not access-token freshness (we don't persist access-token
+     * expiry). If the adopted access token has since expired, jsforce gets a 401 and re-enters refreshFn,
+     * which then rotates under the lock (our refresh token now matches disk, so the double-check falls through
+     * to a real refresh). That is one extra round trip in a narrow case, and still strictly better than the
+     * pre-adopt behavior, where refreshing with our rotated-out token would have failed outright.
+     *
+     * @returns true if a rotated token was adopted; false if the on-disk token still matches ours.
+     */
+    private adoptIfAlreadyRotated;
     private readJwtKey;
     private authJwt;
     private tryJwtAuth;

package/lib/org/authInfo.js

@@ -72,12 +72,13 @@ const filters_1 = require("../logger/filters");
 const messages_1 = require("../messages");
 const sfdcUrl_1 = require("../util/sfdcUrl");
 const findSuggestion_1 = require("../util/findSuggestion");
+const fileLocking_1 = require("../util/fileLocking");
 const connection_1 = require("./connection");
 const determineOrg_1 = require("./determineOrg");
 const org_1 = require("./org");
 const orgConfigProperties_1 = require("./orgConfigProperties");
 ;
-const messages = new messages_1.Messages('@salesforce/core', 'core', new Map([["authInfoCreationError", "Must pass a username and/or OAuth options when creating an AuthInfo instance."], ["authInfoOverwriteError", "Cannot create an AuthInfo instance that will overwrite existing auth data."], ["authInfoOverwriteError.actions", ["Create the AuthInfo instance using existing auth data by just passing the username. E.g., `AuthInfo.create({ username: 'my@user.org' });`."]], ["authCodeExchangeError", "Error authenticating with auth code due to: %s"], ["authCodeUsernameRetrievalError", "Could not retrieve the username after successful auth code exchange.\n\nDue to: %s"], ["jwtAuthError", "Error authenticating with JWT config due to: %s"], ["jwtAuthErrors", "Error authenticating with JWT.\nErrors encountered:\n%s"], ["refreshTokenAuthError", "Error authenticating with the refresh token due to: %s"], ["invalidSfdxAuthUrlError", "Invalid SFDX authorization URL. Must be in the format \"force://<clientId>:<clientSecret>:<refreshToken>@<instanceUrl>\". Note that the \"instanceUrl\" inside the SFDX authorization URL doesn\\'t include the protocol (\"https://\"). Run \"org display --target-org\" on an org to see an example of an SFDX authorization URL."], ["orgDataNotAvailableError", "An attempt to refresh the authentication token failed with a 'Data Not Found Error'. The org identified by username %s does not appear to exist. Likely cause is that the org was deleted by another user or has expired."], ["orgDataNotAvailableError.actions", ["Run `sfdx force:org:list --clean` to remove stale org authentications.", "Use `sfdx force:config:set` to update the defaultusername.", "Use `sfdx force:org:create` to create a new org.", "Use `sfdx auth` to authenticate an existing org."]], ["namedOrgNotFound", "No authorization information found for %s."], ["noAliasesFound", "Nothing to set."], ["invalidFormat", "Setting aliases must be in the format <key>=<value> but found: [%s]."], ["invalidJsonCasing", "All JSON input must have heads down camelcase keys. E.g., `{ sfdcLoginUrl: \"https://login.salesforce.com\" }`\nFound \"%s\" at %s"], ["missingClientId", "Client ID is required for JWT authentication."]]));
+const messages = new messages_1.Messages('@salesforce/core', 'core', new Map([["authInfoCreationError", "Must pass a username and/or OAuth options when creating an AuthInfo instance."], ["authInfoOverwriteError", "Cannot create an AuthInfo instance that will overwrite existing auth data."], ["authInfoOverwriteError.actions", ["Create the AuthInfo instance using existing auth data by just passing the username. E.g., `AuthInfo.create({ username: 'my@user.org' });`."]], ["authCodeExchangeError", "Error authenticating with auth code due to: %s"], ["authCodeUsernameRetrievalError", "Could not retrieve the username after successful auth code exchange.\n\nDue to: %s"], ["jwtAuthError", "Error authenticating with JWT config due to: %s"], ["jwtAuthErrors", "Error authenticating with JWT.\nErrors encountered:\n%s"], ["refreshTokenAuthError", "Error authenticating with the refresh token due to: %s"], ["refreshTokenAuthError.actions", ["The stored refresh token is no longer valid (it may have expired, been revoked, or been rotated). Re-authenticate to the org, then retry. For example, run \"sf org login web --alias <your-alias>\""]], ["refreshTokenRotationTimeoutError", "Timed out waiting for another process to finish rotating the refresh token for %s. Another process held the rotation lock for the entire wait without completing. Retry the command. If it persists, another \"sf\" process is likely stuck mid-refresh: stop any other running \"sf\" processes, then retry."], ["invalidSfdxAuthUrlError", "Invalid SFDX authorization URL. Must be in the format \"force://<clientId>:<clientSecret>:<refreshToken>@<instanceUrl>\". Note that the \"instanceUrl\" inside the SFDX authorization URL doesn\\'t include the protocol (\"https://\"). Run \"org display --target-org\" on an org to see an example of an SFDX authorization URL."], ["orgDataNotAvailableError", "An attempt to refresh the authentication token failed with a 'Data Not Found Error'. The org identified by username %s does not appear to exist. Likely cause is that the org was deleted by another user or has expired."], ["orgDataNotAvailableError.actions", ["Run `sfdx force:org:list --clean` to remove stale org authentications.", "Use `sfdx force:config:set` to update the defaultusername.", "Use `sfdx force:org:create` to create a new org.", "Use `sfdx auth` to authenticate an existing org."]], ["namedOrgNotFound", "No authorization information found for %s."], ["noAliasesFound", "Nothing to set."], ["invalidFormat", "Setting aliases must be in the format <key>=<value> but found: [%s]."], ["invalidJsonCasing", "All JSON input must have heads down camelcase keys. E.g., `{ sfdcLoginUrl: \"https://login.salesforce.com\" }`\nFound \"%s\" at %s"], ["missingClientId", "Client ID is required for JWT authentication."]]));
 // parses the id field returned from jsForce oauth2 methods to get
 // user ID and org ID.
 function parseIdUrl(idUrl) {
@@ -185,22 +186,25 @@ class AuthInfo extends kit_1.AsyncOptionalCreatable {
                 // prevent ConfigFile collision bug
                 // eslint-disable-next-line no-await-in-loop
                 const authInfo = await AuthInfo.create({ username });
-                const { orgId, instanceUrl, devHubUsername, expirationDate, isDevHub } = authInfo.getFields();
+                const authFields = authInfo.getFields();
+                const { orgId, instanceUrl, devHubUsername, expirationDate, isDevHub } = authFields;
+                const isScratchOrg = Boolean(devHubUsername) || Boolean(authFields[org_1.Org.Fields.IS_SCRATCH]);
+                const expDate = expirationDate ?? authFields[org_1.Org.Fields.TRIAL_EXPIRATION_DATE];
+                // eslint-disable-next-line no-await-in-loop
+                const hasSandboxFile = await stateAggregator.sandboxes.hasFile(orgId);
+                const isSandbox = Boolean(authFields[org_1.Org.Fields.IS_SANDBOX]) || hasSandboxFile;
                 final.push({
                     aliases,
                     configs,
                     username,
                     instanceUrl,
-                    isScratchOrg: Boolean(devHubUsername),
+                    isScratchOrg,
                     isDevHub: isDevHub ?? false,
-                    // eslint-disable-next-line no-await-in-loop
-                    isSandbox: await stateAggregator.sandboxes.hasFile(orgId),
+                    isSandbox,
                     orgId: orgId,
                     accessToken: authInfo.getConnectionOptions().accessToken,
                     oauthMethod: authInfo.isJwt() ? 'jwt' : authInfo.isOauth() ? 'web' : 'token',
-                    isExpired: Boolean(devHubUsername) && expirationDate
-                        ? new Date((0, ts_types_1.ensureString)(expirationDate)).getTime() < new Date().getTime()
-                        : 'unknown',
+                    isExpired: isScratchOrg && expDate ? new Date((0, ts_types_1.ensureString)(expDate)).getTime() < new Date().getTime() : 'unknown',
                 });
             }
             catch (err) {
@@ -283,31 +287,83 @@ class AuthInfo extends kit_1.AsyncOptionalCreatable {
      * @param orgAuthInfo
      */
     static async identifyPossibleScratchOrgs(fields, orgAuthInfo) {
+        if (kit_1.env.getBoolean('SF_SKIP_SCRATCH_ORG_CHECK')) {
+            (await logger_1.Logger.child('Common', { tag: 'identifyPossibleScratchOrgs' })).debug('Skipping scratch org identification due to SF_SKIP_SCRATCH_ORG_CHECK');
+            return;
+        }
         // fields property is passed in because the consumers of this method have performed the decrypt.
         // This is so we don't have to call authInfo.getFields(true) and decrypt again OR accidentally save an
         // authInfo before it is necessary.
         const logger = await logger_1.Logger.child('Common', { tag: 'identifyPossibleScratchOrgs' });
         await (0, determineOrg_1.determineOrg)(orgAuthInfo);
+        // re-read fields after determineOrg may have updated them
+        const updatedFields = orgAuthInfo.getFields();
         // return if we already know the hub org, we know it is a devhub or prod-like, or no orgId present
-        if (Boolean(fields.isDevHub) || Boolean(fields.devHubUsername) || !fields.orgId)
+        if (Boolean(updatedFields.isDevHub) || Boolean(updatedFields.devHubUsername) || !updatedFields.orgId)
+            return;
+        if (updatedFields.isSandbox) {
+            logger.debug('determineOrg already identified org as sandbox, skipping expensive org scan');
             return;
+        }
+        // for scratch orgs, skip the full listAllAuthorizations + sandbox identification and
+        // instead do a lightweight DevHub lookup using raw configs (no AuthInfo creation/decryption)
+        if (updatedFields.isScratch) {
+            logger.debug('determineOrg identified org as scratch, doing lightweight DevHub lookup');
+            const stateAggregator = await stateAggregator_1.StateAggregator.getInstance();
+            const allConfigs = await stateAggregator.orgs.readAll();
+            const devHubUsernames = allConfigs.filter((c) => c.isDevHub).map((c) => (0, ts_types_1.ensureString)(c.username));
+            for (const hubUsername of devHubUsernames) {
+                try {
+                    // eslint-disable-next-line no-await-in-loop
+                    const soi = await AuthInfo.queryScratchOrg(hubUsername, updatedFields.orgId);
+                    // eslint-disable-next-line no-await-in-loop
+                    await orgAuthInfo.save({
+                        ...fields,
+                        devHubUsername: hubUsername,
+                        expirationDate: soi.ExpirationDate,
+                        isScratch: true,
+                    });
+                    logger.debug(`set ${hubUsername} as devhub for scratch org ${orgAuthInfo.getUsername()}`);
+                    return;
+                }
+                catch (error) {
+                    if (error instanceof Error && error.name === 'NoActiveScratchOrgFound') {
+                        logger.debug(`devhub ${hubUsername} does not own this scratch org`);
+                    }
+                    else {
+                        logger.debug(`Error connecting to devhub ${hubUsername}`, error);
+                    }
+                }
+            }
+            return;
+        }
         logger.debug('getting devHubs and prod orgs to identify scratch orgs and sandboxes');
-        // TODO: return if url is not sandbox-like to avoid constantly asking about production orgs
         // TODO: someday we make this easier by asking the org if it is a scratch org
-        const hubAuthInfos = await AuthInfo.getDevHubAuthInfos();
-        // Get a list of org auths that are known not to be scratch orgs or sandboxes.
-        const possibleProdOrgs = await AuthInfo.listAllAuthorizations((orgAuth) => orgAuth && !orgAuth.isScratchOrg && !orgAuth.isSandbox);
+        const allOrgs = await AuthInfo.listAllAuthorizations();
+        const hubAuthInfos = allOrgs.filter((org) => org.isDevHub);
+        // skip sandbox identification if the instance URL is not sandbox-like
+        // enhanced domains: *.sandbox.my.salesforce.com; pre-enhanced My Domain: company--sbxname.my.salesforce.com
+        const isSandboxLikeUrl = fields.instanceUrl != null && (fields.instanceUrl.includes('.sandbox.') || fields.instanceUrl.includes('--'));
+        const possibleProdOrgs = isSandboxLikeUrl ? allOrgs.filter((org) => !org.isScratchOrg && !org.isSandbox) : [];
+        if (!isSandboxLikeUrl) {
+            logger.debug('instance URL is not sandbox-like, skipping sandbox identification');
+        }
         logger.debug(`found ${hubAuthInfos.length} DevHubs`);
         logger.debug(`found ${possibleProdOrgs.length} possible prod orgs`);
         if (hubAuthInfos.length === 0 && possibleProdOrgs.length === 0) {
             return;
         }
-        // ask all those orgs if they know this orgId
+        let identified = false;
+        // ask all those orgs if they know this orgId, but stop once one claims it
         await Promise.all([
             ...hubAuthInfos.map(async (hubAuthInfo) => {
+                if (identified)
+                    return;
                 try {
                     const soi = await AuthInfo.queryScratchOrg(hubAuthInfo.username, fields.orgId);
-                    // if any return a result
+                    if (identified)
+                        return;
+                    identified = true;
                     logger.debug(`found orgId ${fields.orgId ?? '<undefined>'} in devhub ${hubAuthInfo.username}`);
                     try {
                         await orgAuthInfo.save({
@@ -332,7 +388,11 @@ class AuthInfo extends kit_1.AsyncOptionalCreatable {
                 }
             }),
             ...possibleProdOrgs.map(async (pOrgAuthInfo) => {
-                await AuthInfo.identifyPossibleSandbox(pOrgAuthInfo, fields, orgAuthInfo, logger);
+                if (identified)
+                    return;
+                const found = await AuthInfo.identifyPossibleSandbox(pOrgAuthInfo, fields, orgAuthInfo, logger);
+                if (found)
+                    identified = true;
             }),
         ]);
     }
@@ -344,13 +404,13 @@ class AuthInfo extends kit_1.AsyncOptionalCreatable {
     }
     static async identifyPossibleSandbox(possibleProdOrg, fields, orgAuthInfo, logger) {
         if (!fields.orgId) {
-            return;
+            return false;
         }
         try {
             const prodOrg = await org_1.Org.create({ aliasOrUsername: possibleProdOrg.username });
             const sbxProcess = await prodOrg.querySandboxProcessByOrgId(fields.orgId);
             if (!sbxProcess?.SandboxInfoId) {
-                return;
+                return false;
             }
             logger.debug(`${fields.orgId} is a sandbox of ${possibleProdOrg.username}`);
             try {
@@ -383,9 +443,11 @@ class AuthInfo extends kit_1.AsyncOptionalCreatable {
             catch (e) {
                 logger.debug(`error writing sandbox auth file for: ${orgAuthInfo.getUsername()}`, e);
             }
+            return true;
         }
         catch (err) {
             logger.debug(`${fields.orgId} is not a sandbox of ${possibleProdOrg.username}`);
+            return false;
         }
     }
     /**
@@ -547,7 +609,10 @@ class AuthInfo extends kit_1.AsyncOptionalCreatable {
                             accessToken: (0, ts_types_1.ensureString)(authFields.accessToken),
                             clientId: decryptedApp.clientId,
                             clientSecret: decryptedApp.clientSecret,
-                            refreshToken: decryptedApp.refreshToken,
+                            // Persist the server-returned refresh token (rotated under RTR), falling back to the one we
+                            // sent when the response omits it (RTR off). Persisting the old token here would send an
+                            // invalidated credential on the next refresh once RTR is enabled on this connected app.
+                            refreshToken: (0, ts_types_1.ensureString)(authFields.refreshToken ?? decryptedApp.refreshToken),
                             oauthFlow: 'web',
                         },
                     },
@@ -773,11 +838,23 @@ class AuthInfo extends kit_1.AsyncOptionalCreatable {
                 if (!options.privateKey && options.privateKeyFile) {
                     options.privateKey = (0, node_path_1.resolve)(options.privateKeyFile);
                 }
-                if (options.privateKey) {
+                // Route to JWT only when there's a privateKey AND no refreshToken. A legitimate JWT auth never
+                // carries a refreshToken (authJwt writes none, and `login jwt` deletes-then-recreates the auth file).
+                // The edge case that contains BOTH a privateKey AND a refreshToken is when auth was originally JWT
+                // and later switched to Web auth. Web auth does not delete the existing auth file, so `AuthInfo.update`
+                // merges over the old file. In that case the refreshToken is the intended credential, so fall
+                // through to the refresh-token flow instead of misrouting into JWT, which also matches isJwt().
+                if (options.privateKey && !options.refreshToken) {
                     authConfig = await this.authJwt(options);
                 }
                 else if (!options.authCode && options.refreshToken) {
-                    // refresh token flow (from sfdxUrl or OAuth refreshFn)
+                    // refresh token flow (from sfdxUrl or OAuth refreshFn).
+                    // RTR CAUTION: this POST rotates the token server-side and invalidates the old one immediately.
+                    // Everything from here until the caller's save() (determineIfDevHub, orgs.read, update/encrypt,
+                    // determineOrg) runs on borrowed time -- a throw in that window strands the rotated token on the
+                    // wire while the old one is already dead server-side, permanently breaking the auth until re-login.
+                    // determineIfDevHub and determineOrg swallow their own errors, so the practical window is small,
+                    // but it is non-zero. A save-early seam for this branch would close it (tracked as a follow-up).
                     authConfig = await this.buildRefreshTokenConfig(options);
                 }
                 else if (this.options.oauth2 instanceof jsforce_node_1.OAuth2) {
@@ -793,6 +870,15 @@ class AuthInfo extends kit_1.AsyncOptionalCreatable {
                 await this.stateAggregator.orgs.read(authConfig.username, false, false);
             // Update the auth fields WITH encryption
             this.update(authConfig);
+            // A web/auth-code or refresh-token authorization is never a JWT one, so it must not carry a
+            // privateKey. When this flow overwrites an existing auth file (e.g. the user was JWT-authed for
+            // this org, then re-authed via web), the save path merges (Object.assign) over the existing
+            // file and would otherwise retain the stale privateKey, which later misroutes refreshFn into
+            // the JWT flow. Only clear it when a stale value actually lingers so we don't add an empty key
+            // to a fresh authorization.
+            if (!authConfig.privateKey && this.getFields().privateKey) {
+                this.stateAggregator.orgs.update(this.username, { privateKey: undefined });
+            }
             // Populate Organization metadata (orgEdition, isScratch, isSandbox, etc.) in a single query.
             await (0, determineOrg_1.determineOrg)(this);
         }
@@ -822,10 +908,27 @@ class AuthInfo extends kit_1.AsyncOptionalCreatable {
         this.logger.info('Access token has expired. Updating...');
         try {
             const fields = this.getFields(true);
-            // This method will request the new access token and save to the current AuthInfo instance (but don't persist them!).
-            await this.initAuthOptions(fields);
-            // Persist fields with refreshed access token to auth file.
-            await this.save();
+            // JWT auth mints a fresh access token from a locally-signed assertion and consumes no stored credential,
+            // so concurrent JWT refreshes are independent and safe. The refresh-token flow is different: every caller
+            // refreshes by re-sending the *same persisted refresh token* read from the auth file, and with Refresh
+            // Token Rotation enabled the server returns a new refresh token and invalidates the old one *immediately*.
+            // So two connections/processes refreshing at once would both send that on-disk token and double-rotate the
+            // auth. Serialize just that flow.
+            //
+            // Gate on `refreshToken` alone (not `refreshToken && !privateKey`): a legitimate JWT auth never carries
+            // a refresh token, so this still excludes JWT, and it also covers the fixed edge case where both-fields
+            // exist from an original JWT login and switching to web (stale privateKey + real refreshToken), which
+            // initAuthOptions routes through the refresh-token flow and which therefore must take the lock too.
+            //  See the router in initAuthOptions and isJwt().
+            if (fields.refreshToken) {
+                await this.refreshWithTokenRotationLock(fields.refreshToken);
+            }
+            else {
+                // This method will request the new access token and save to the current AuthInfo instance (but don't persist them!).
+                await this.initAuthOptions(fields);
+                // Persist fields with refreshed access token to auth file.
+                await this.save();
+            }
             // Pass new access token to the jsforce's session-refresh callback for proper propagation:
             // https://jsforce.github.io/jsforce/types/session_refresh_delegate.SessionRefreshFunc.html
             const { accessToken } = this.getFields(true);
@@ -840,6 +943,140 @@ class AuthInfo extends kit_1.AsyncOptionalCreatable {
             return callback(error);
         }
     }
+    /**
+     * Single-flight a refresh-token refresh so two connections/processes can't rotate the same token at once.
+     *
+     * With Refresh Token Rotation (RTR) enabled, each refresh returns a new refresh token and invalidates the
+     * previous one; a second refresh sent with the now-stale refresh token fails and invalidates the current token too.
+     * We take a cross-process lock (which also serializes same-process contenders), then re-read the latest
+     * tokens from disk: if another actor already rotated while we waited, we adopt their fresh credentials
+     * instead of refreshing again with our now-invalid token.
+     *
+     * Each pass is one call to `tryRotateOrAdopt`, which (1) adopts if disk already holds a rotated token, else
+     * (2) tries to acquire the lock and, once held, re-checks-then-refreshes. If we can't acquire (a live holder
+     * is mid-rotation, ELOCKED), we do NOT fall back to an unlocked refresh, which would race the holder and double-rotate
+     * under RTR; we simply loop back to (1) and re-run the pass (re-read disk, then try to acquire the lock again).
+     * `proper-lockfile` only grants the lock on genuine release or genuine staleness (a live
+     * holder refreshes its lock mtime ~every 5s and so is never stolen from), so looping converges: a slow holder is waited out,
+     * a dead holder's lock crosses the ~10s stale line and is stolen on a later attempt.
+     * Only a holder that keeps the lock alive for the whole budget below yields the timeout error.
+     *
+     * The lock uses a dedicated `<authfile>.token-rotation.lock`, kept separate from ConfigFile's
+     * own `<authfile>.lock` write lock, because proper-lockfile is not re-entrant: holding the auth-file lock
+     * here and then letting save() re-acquire the same path would self-block.
+     *
+     * KNOWN LIMITATIONS (all inherent, not bugs):
+     *
+     * (1) Only actors that take THIS lock are serialized. Within a single CLI release this is a non-issue: the
+     * CLI deduplicates @salesforce/core to one version, so every in-process refresher runs this same locking
+     * code (and the lock path is derived deterministically, so differing versions that BOTH lock still
+     * interoperate). The realistic gap is a 2nd/3rd-party plugin: those install under the CLI's plugin data dir
+     * with their OWN non-deduped node_modules and may bundle a core version predating this lock. Such a plugin
+     * (or any external tool that refreshes the token directly) won't honor `<authfile>.token-rotation.lock` and
+     * can still double-rotate the same auth while we hold it. There is no server-side coordination to prevent this.
+     *
+     * (2) On the web runtime (Global.isWeb), lockInit is a no-op that takes no lock (matching existing
+     * ConfigFile behavior), so nothing is serialized there.
+     *
+     * (3) A genuinely-stuck holder makes this block for up to the budget below plus one in-flight lock cycle
+     * (~40s) before throwing. Because that happens inside a live jsforce session-refresh, an upstream client
+     * with a shorter timeout may give up first with a less specific error. Only the pathological stuck case
+     * pays this; the common paths return in one lock cycle or via the lock-free adopt.
+     *
+     * @param heldRefreshToken the refresh token this connection currently holds (read from the auth file); the
+     * baseline we compare against disk to detect a rotation, and the token we would send if we do rotate.
+     */
+    async refreshWithTokenRotationLock(heldRefreshToken) {
+        const username = (0, ts_types_1.ensure)(this.getUsername());
+        // Cutoff for STARTING another attempt -- not a wall-clock cap on the whole method. Each attempt either
+        // finishes (adopt or refresh) or reports contention (ELOCKED); we re-attempt ONLY while contended. One
+        // lockInit acquisition cycle is ~10s (its lockRetryOptions retry budget before it throws ELOCKED) and the
+        // cutoff is consulted only between attempts, so a genuinely stuck holder pushes the actual time-to-throw
+        // to roughly this cutoff plus one in-flight cycle. Sizing it to ~35s (~3.5x a cycle) starts a 3rd attempt
+        // at ~20s with room to spare and leaves headroom for a 4th: enough for a dead holder's lock to cross the
+        // 10s stale line and be stolen on a later attempt, and for a slow-but-live holder to release.
+        const attemptDeadline = Date.now() + kit_1.Duration.seconds(35).milliseconds;
+        while (Date.now() < attemptDeadline) {
+            // eslint-disable-next-line no-await-in-loop
+            if (await this.tryRotateOrAdopt(username, heldRefreshToken)) {
+                return;
+            }
+            // Otherwise the lock was contended (a live holder is mid-rotation): loop and re-attempt. We never
+            // refresh unlocked, that would race the holder and double-rotate under RTR. No sleep needed: lockInit
+            // already backed off ~10s, and the next attempt re-reads disk before doing anything.
+        }
+        // Past the cutoff with every attempt still contended: a process kept the rotation lock's mtime fresh for
+        // the entire budget without completing. Genuinely stuck, not merely slow or crashed (a crash lets the
+        // lock go stale and be stolen by an attempt above).
+        throw messages.createError('refreshTokenRotationTimeoutError', [username]);
+    }
+    /**
+     * One rotation attempt: adopt an already-rotated token if disk has one, else take the lock and
+     * double-check-then-rotate under it.
+     *
+     * @returns `true` if we adopted or refreshed (caller is done); `false` if the lock was contended
+     * (`ELOCKED`) and the caller should re-attempt. Throws on any non-`ELOCKED` failure.
+     */
+    async tryRotateOrAdopt(username, heldRefreshToken) {
+        // Fast path / adopt: if another connection or process already rotated the token, adopt those fresh
+        // credentials without taking the lock. On the first pass this thins the herd (late arrivals never
+        // contend); on later passes it catches a holder that rotated and released while we were waiting.
+        if (await this.adoptIfAlreadyRotated(username, heldRefreshToken)) {
+            return true;
+        }
+        // proper-lockfile appends `.lock`, so this locks `<authfile>.token-rotation.lock`.
+        const lockPath = `${this.stateAggregator.orgs.getPath(username)}.token-rotation`;
+        let unlock;
+        try {
+            ({ unlock } = await (0, fileLocking_1.lockInit)(lockPath));
+        }
+        catch (err) {
+            // Contended: a live holder is mid-rotation. Report it so the caller re-attempts (never refreshing
+            // unlocked, which would double-rotate under RTR). Any non-ELOCKED error is a real failure.
+            if (err?.code === 'ELOCKED') {
+                return false;
+            }
+            throw err;
+        }
+        // We hold the lock. Run to completion regardless of the caller's cutoff -- we never abandon a rotation we
+        // hold the lock for; the cutoff only gates whether a NEW attempt starts.
+        try {
+            // Double-check under the lock: the holder we queued behind may have rotated while we waited.
+            if (await this.adoptIfAlreadyRotated(username, heldRefreshToken)) {
+                return true;
+            }
+            // No one rotated: perform the refresh (updates this instance in memory) and persist the new token
+            // before we release the lock, so everyone waiting behind us adopts it instead of re-rotating.
+            await this.initAuthOptions(this.getFields(true));
+            await this.save();
+            return true;
+        }
+        finally {
+            await unlock();
+        }
+    }
+    /**
+     * Re-read the on-disk auth (without disturbing this instance's in-memory fields) and, if another
+     * connection/process has already rotated the refresh token, adopt those fresh credentials. Disk is
+     * already current in that case, so no save is needed.
+     *
+     * NOTE: this gates on the refresh token only, not access-token freshness (we don't persist access-token
+     * expiry). If the adopted access token has since expired, jsforce gets a 401 and re-enters refreshFn,
+     * which then rotates under the lock (our refresh token now matches disk, so the double-check falls through
+     * to a real refresh). That is one extra round trip in a narrow case, and still strictly better than the
+     * pre-adopt behavior, where refreshing with our rotated-out token would have failed outright.
+     *
+     * @returns true if a rotated token was adopted; false if the on-disk token still matches ours.
+     */
+    async adoptIfAlreadyRotated(username, heldRefreshToken) {
+        const onDisk = await this.stateAggregator.orgs.peek(username, true);
+        if (onDisk?.refreshToken && onDisk.refreshToken !== heldRefreshToken) {
+            this.logger.info('Refresh token was already rotated by another process; adopting refreshed credentials.');
+            this.update(onDisk);
+            return true;
+        }
+        return false;
+    }
     async readJwtKey(keyFile) {
         return fs_1.fs.promises.readFile(keyFile, 'utf8');
     }
@@ -948,7 +1185,11 @@ class AuthInfo extends kit_1.AsyncOptionalCreatable {
             accessToken: authFieldsBuilder.access_token,
             instanceUrl: authFieldsBuilder.instance_url,
             loginUrl: fullOptions.loginUrl ?? authFieldsBuilder.instance_url,
-            refreshToken: fullOptions.refreshToken,
+            // Refresh Token Rotation (RTR): when the app has RTR enabled, the token endpoint returns a
+            // NEW refresh_token that we must persist, replacing the one we sent. When RTR is off, the
+            // response omits refresh_token, so we keep the existing one.
+            // https://help.salesforce.com/s/articleView?id=sf.remoteaccess_oauth_refresh_token_flow.htm&type=5
+            refreshToken: authFieldsBuilder.refresh_token ?? fullOptions.refreshToken,
             clientId: fullOptions.clientId,
             clientSecret: fullOptions.clientSecret,
         };

package/lib/stateAggregator/accessors/orgAccessor.d.ts

@@ -18,6 +18,15 @@ export declare abstract class BaseOrgAccessor<T extends ConfigFile, P extends Co
      * @param throwOnNotFound throw if file is not found for username
      */
     read(username: string, decrypt?: boolean, throwOnNotFound?: boolean): Promise<Nullable<P>>;
+    /**
+     * Read the current on-disk contents of a username's auth file WITHOUT mutating the cache (unlike `read`,
+     * which replaces the cached config/contents). Use this to inspect what another process has persisted
+     * without disturbing this instance's in-memory state. Returns null if the file can't be read.
+     *
+     * @param username username to read
+     * @param decrypt if true, decrypt encrypted values
+     */
+    peek(username: string, decrypt?: boolean): Promise<Nullable<P>>;
     /**
      * Read all the auth files under the global state directory
      *
@@ -50,6 +59,13 @@ export declare abstract class BaseOrgAccessor<T extends ConfigFile, P extends Co
      * @param username
      */
     stat(username: string): Promise<Nullable<Awaited<ReturnType<typeof fs.promises.stat>>>>;
+    /**
+     * Return the absolute path to the auth file for a given username. Does not require the file to have been
+     * read (resolves purely from the username and the global state directory).
+     *
+     * @param username
+     */
+    getPath(username: string): string;
     /**
      * Returns true if there is an auth file for the given username
      *

package/lib/stateAggregator/accessors/orgAccessor.js

@@ -92,6 +92,25 @@ class BaseOrgAccessor extends kit_1.AsyncOptionalCreatable {
             return null;
         }
     }
+    /**
+     * Read the current on-disk contents of a username's auth file WITHOUT mutating the cache (unlike `read`,
+     * which replaces the cached config/contents). Use this to inspect what another process has persisted
+     * without disturbing this instance's in-memory state. Returns null if the file can't be read.
+     *
+     * @param username username to read
+     * @param decrypt if true, decrypt encrypted values
+     */
+    async peek(username, decrypt = false) {
+        try {
+            const config = await this.initAuthFile(username, false);
+            return config.getContents(decrypt);
+        }
+        catch (err) {
+            const error = sfError_1.SfError.wrap(err);
+            this.logger.debug(`Error when peeking auth file for user: ${username} due to: ${error.name}:${error.message}`);
+            return null;
+        }
+    }
     /**
      * Read all the auth files under the global state directory
      *
@@ -134,7 +153,7 @@ class BaseOrgAccessor extends kit_1.AsyncOptionalCreatable {
         const config = this.configs.get(username);
         if (throwOnNotFound && config?.keys().length === 0) {
             ;
-            const messages = new messages_1.Messages('@salesforce/core', 'core', new Map([["authInfoCreationError", "Must pass a username and/or OAuth options when creating an AuthInfo instance."], ["authInfoOverwriteError", "Cannot create an AuthInfo instance that will overwrite existing auth data."], ["authInfoOverwriteError.actions", ["Create the AuthInfo instance using existing auth data by just passing the username. E.g., `AuthInfo.create({ username: 'my@user.org' });`."]], ["authCodeExchangeError", "Error authenticating with auth code due to: %s"], ["authCodeUsernameRetrievalError", "Could not retrieve the username after successful auth code exchange.\n\nDue to: %s"], ["jwtAuthError", "Error authenticating with JWT config due to: %s"], ["jwtAuthErrors", "Error authenticating with JWT.\nErrors encountered:\n%s"], ["refreshTokenAuthError", "Error authenticating with the refresh token due to: %s"], ["invalidSfdxAuthUrlError", "Invalid SFDX authorization URL. Must be in the format \"force://<clientId>:<clientSecret>:<refreshToken>@<instanceUrl>\". Note that the \"instanceUrl\" inside the SFDX authorization URL doesn\\'t include the protocol (\"https://\"). Run \"org display --target-org\" on an org to see an example of an SFDX authorization URL."], ["orgDataNotAvailableError", "An attempt to refresh the authentication token failed with a 'Data Not Found Error'. The org identified by username %s does not appear to exist. Likely cause is that the org was deleted by another user or has expired."], ["orgDataNotAvailableError.actions", ["Run `sfdx force:org:list --clean` to remove stale org authentications.", "Use `sfdx force:config:set` to update the defaultusername.", "Use `sfdx force:org:create` to create a new org.", "Use `sfdx auth` to authenticate an existing org."]], ["namedOrgNotFound", "No authorization information found for %s."], ["noAliasesFound", "Nothing to set."], ["invalidFormat", "Setting aliases must be in the format <key>=<value> but found: [%s]."], ["invalidJsonCasing", "All JSON input must have heads down camelcase keys. E.g., `{ sfdcLoginUrl: \"https://login.salesforce.com\" }`\nFound \"%s\" at %s"], ["missingClientId", "Client ID is required for JWT authentication."]]));
+            const messages = new messages_1.Messages('@salesforce/core', 'core', new Map([["authInfoCreationError", "Must pass a username and/or OAuth options when creating an AuthInfo instance."], ["authInfoOverwriteError", "Cannot create an AuthInfo instance that will overwrite existing auth data."], ["authInfoOverwriteError.actions", ["Create the AuthInfo instance using existing auth data by just passing the username. E.g., `AuthInfo.create({ username: 'my@user.org' });`."]], ["authCodeExchangeError", "Error authenticating with auth code due to: %s"], ["authCodeUsernameRetrievalError", "Could not retrieve the username after successful auth code exchange.\n\nDue to: %s"], ["jwtAuthError", "Error authenticating with JWT config due to: %s"], ["jwtAuthErrors", "Error authenticating with JWT.\nErrors encountered:\n%s"], ["refreshTokenAuthError", "Error authenticating with the refresh token due to: %s"], ["refreshTokenAuthError.actions", ["The stored refresh token is no longer valid (it may have expired, been revoked, or been rotated). Re-authenticate to the org, then retry. For example, run \"sf org login web --alias <your-alias>\""]], ["refreshTokenRotationTimeoutError", "Timed out waiting for another process to finish rotating the refresh token for %s. Another process held the rotation lock for the entire wait without completing. Retry the command. If it persists, another \"sf\" process is likely stuck mid-refresh: stop any other running \"sf\" processes, then retry."], ["invalidSfdxAuthUrlError", "Invalid SFDX authorization URL. Must be in the format \"force://<clientId>:<clientSecret>:<refreshToken>@<instanceUrl>\". Note that the \"instanceUrl\" inside the SFDX authorization URL doesn\\'t include the protocol (\"https://\"). Run \"org display --target-org\" on an org to see an example of an SFDX authorization URL."], ["orgDataNotAvailableError", "An attempt to refresh the authentication token failed with a 'Data Not Found Error'. The org identified by username %s does not appear to exist. Likely cause is that the org was deleted by another user or has expired."], ["orgDataNotAvailableError.actions", ["Run `sfdx force:org:list --clean` to remove stale org authentications.", "Use `sfdx force:config:set` to update the defaultusername.", "Use `sfdx force:org:create` to create a new org.", "Use `sfdx auth` to authenticate an existing org."]], ["namedOrgNotFound", "No authorization information found for %s."], ["noAliasesFound", "Nothing to set."], ["invalidFormat", "Setting aliases must be in the format <key>=<value> but found: [%s]."], ["invalidJsonCasing", "All JSON input must have heads down camelcase keys. E.g., `{ sfdcLoginUrl: \"https://login.salesforce.com\" }`\nFound \"%s\" at %s"], ["missingClientId", "Client ID is required for JWT authentication."]]));
             throw messages.createError('namedOrgNotFound', [username]);
         }
         if (config) {
@@ -177,6 +196,15 @@ class BaseOrgAccessor extends kit_1.AsyncOptionalCreatable {
         const config = this.configs.get(username);
         return config ? config.stat() : null;
     }
+    /**
+     * Return the absolute path to the auth file for a given username. Does not require the file to have been
+     * read (resolves purely from the username and the global state directory).
+     *
+     * @param username
+     */
+    getPath(username) {
+        return this.parseFilename(username);
+    }
     /**
      * Returns true if there is an auth file for the given username
      *

package/lib/util/findUppercaseKeys.js

@@ -20,7 +20,7 @@ const node_assert_1 = require("node:assert");
 const ts_types_1 = require("@salesforce/ts-types");
 const messages_1 = require("../messages");
 ;
-const coreMessages = new messages_1.Messages('@salesforce/core', 'core', new Map([["authInfoCreationError", "Must pass a username and/or OAuth options when creating an AuthInfo instance."], ["authInfoOverwriteError", "Cannot create an AuthInfo instance that will overwrite existing auth data."], ["authInfoOverwriteError.actions", ["Create the AuthInfo instance using existing auth data by just passing the username. E.g., `AuthInfo.create({ username: 'my@user.org' });`."]], ["authCodeExchangeError", "Error authenticating with auth code due to: %s"], ["authCodeUsernameRetrievalError", "Could not retrieve the username after successful auth code exchange.\n\nDue to: %s"], ["jwtAuthError", "Error authenticating with JWT config due to: %s"], ["jwtAuthErrors", "Error authenticating with JWT.\nErrors encountered:\n%s"], ["refreshTokenAuthError", "Error authenticating with the refresh token due to: %s"], ["invalidSfdxAuthUrlError", "Invalid SFDX authorization URL. Must be in the format \"force://<clientId>:<clientSecret>:<refreshToken>@<instanceUrl>\". Note that the \"instanceUrl\" inside the SFDX authorization URL doesn\\'t include the protocol (\"https://\"). Run \"org display --target-org\" on an org to see an example of an SFDX authorization URL."], ["orgDataNotAvailableError", "An attempt to refresh the authentication token failed with a 'Data Not Found Error'. The org identified by username %s does not appear to exist. Likely cause is that the org was deleted by another user or has expired."], ["orgDataNotAvailableError.actions", ["Run `sfdx force:org:list --clean` to remove stale org authentications.", "Use `sfdx force:config:set` to update the defaultusername.", "Use `sfdx force:org:create` to create a new org.", "Use `sfdx auth` to authenticate an existing org."]], ["namedOrgNotFound", "No authorization information found for %s."], ["noAliasesFound", "Nothing to set."], ["invalidFormat", "Setting aliases must be in the format <key>=<value> but found: [%s]."], ["invalidJsonCasing", "All JSON input must have heads down camelcase keys. E.g., `{ sfdcLoginUrl: \"https://login.salesforce.com\" }`\nFound \"%s\" at %s"], ["missingClientId", "Client ID is required for JWT authentication."]]));
+const coreMessages = new messages_1.Messages('@salesforce/core', 'core', new Map([["authInfoCreationError", "Must pass a username and/or OAuth options when creating an AuthInfo instance."], ["authInfoOverwriteError", "Cannot create an AuthInfo instance that will overwrite existing auth data."], ["authInfoOverwriteError.actions", ["Create the AuthInfo instance using existing auth data by just passing the username. E.g., `AuthInfo.create({ username: 'my@user.org' });`."]], ["authCodeExchangeError", "Error authenticating with auth code due to: %s"], ["authCodeUsernameRetrievalError", "Could not retrieve the username after successful auth code exchange.\n\nDue to: %s"], ["jwtAuthError", "Error authenticating with JWT config due to: %s"], ["jwtAuthErrors", "Error authenticating with JWT.\nErrors encountered:\n%s"], ["refreshTokenAuthError", "Error authenticating with the refresh token due to: %s"], ["refreshTokenAuthError.actions", ["The stored refresh token is no longer valid (it may have expired, been revoked, or been rotated). Re-authenticate to the org, then retry. For example, run \"sf org login web --alias <your-alias>\""]], ["refreshTokenRotationTimeoutError", "Timed out waiting for another process to finish rotating the refresh token for %s. Another process held the rotation lock for the entire wait without completing. Retry the command. If it persists, another \"sf\" process is likely stuck mid-refresh: stop any other running \"sf\" processes, then retry."], ["invalidSfdxAuthUrlError", "Invalid SFDX authorization URL. Must be in the format \"force://<clientId>:<clientSecret>:<refreshToken>@<instanceUrl>\". Note that the \"instanceUrl\" inside the SFDX authorization URL doesn\\'t include the protocol (\"https://\"). Run \"org display --target-org\" on an org to see an example of an SFDX authorization URL."], ["orgDataNotAvailableError", "An attempt to refresh the authentication token failed with a 'Data Not Found Error'. The org identified by username %s does not appear to exist. Likely cause is that the org was deleted by another user or has expired."], ["orgDataNotAvailableError.actions", ["Run `sfdx force:org:list --clean` to remove stale org authentications.", "Use `sfdx force:config:set` to update the defaultusername.", "Use `sfdx force:org:create` to create a new org.", "Use `sfdx auth` to authenticate an existing org."]], ["namedOrgNotFound", "No authorization information found for %s."], ["noAliasesFound", "Nothing to set."], ["invalidFormat", "Setting aliases must be in the format <key>=<value> but found: [%s]."], ["invalidJsonCasing", "All JSON input must have heads down camelcase keys. E.g., `{ sfdcLoginUrl: \"https://login.salesforce.com\" }`\nFound \"%s\" at %s"], ["missingClientId", "Client ID is required for JWT authentication."]]));
 /** will throw on any upperCase unless they are present in the allowList.  Recursively searches the object, returning valid keys */
 const ensureNoUppercaseKeys = (path) => (allowList = []) => (data) => {
     const keys = getKeys(data, allowList);

package/messages/core.md

@@ -34,6 +34,14 @@ Errors encountered:
 
 Error authenticating with the refresh token due to: %s
 
+# refreshTokenAuthError.actions
+
+- The stored refresh token is no longer valid (it may have expired, been revoked, or been rotated). Re-authenticate to the org, then retry. For example, run "sf org login web --alias <your-alias>"
+
+# refreshTokenRotationTimeoutError
+
+Timed out waiting for another process to finish rotating the refresh token for %s. Another process held the rotation lock for the entire wait without completing. Retry the command. If it persists, another "sf" process is likely stuck mid-refresh: stop any other running "sf" processes, then retry.
+
 # invalidSfdxAuthUrlError
 
 Invalid SFDX authorization URL. Must be in the format "force://<clientId>:<clientSecret>:<refreshToken>@<instanceUrl>". Note that the "instanceUrl" inside the SFDX authorization URL doesn\'t include the protocol ("https://"). Run "org display --target-org" on an org to see an example of an SFDX authorization URL.

package/messages/envVars.md

@@ -319,3 +319,7 @@ Your environment has both variables populated, and with different values. The va
 # sfCapitalizeRecordTypes
 
 Whether record types are capitalized on scratch org creation.
+
+# sfSkipScratchOrgCheck
+
+Set to "true" to skip the scratch org and sandbox identification check that runs after authenticating an org. When enabled, `sf org login jwt` (and other login commands) will not query existing cached orgs to determine whether the newly authenticated org is a scratch org or sandbox. This can significantly speed up authentication in CI/CD environments with many cached org authorizations.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/core",
-  "version": "9.1.10",
+  "version": "9.1.12-qa.0",
   "description": "Core libraries to interact with SFDX projects, orgs, and APIs.",
   "main": "lib/index",
   "types": "lib/index.d.ts",