@salesforce/core 9.1.11 → 9.1.12-qa.0

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) {
@@ -608,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',
                         },
                     },
@@ -834,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) {
@@ -854,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);
         }
@@ -883,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);
@@ -901,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');
     }
@@ -1009,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/core",
-  "version": "9.1.11",
+  "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",