@jacebenson/jsn 4.2.4 → 4.3.0

package/src/auth.js

@@ -112,14 +112,19 @@ const KEYRING_SERVICE = 'servicenow-cli';
 const KEYRING_ATTR_SERVICE = 'service';
 const KEYRING_ATTR_USERNAME = 'username';
 
-function credentialsPath(key) {
+function credentialsFilePath(key) {
   const dir = path.join(globalConfigDir(), 'credentials');
-  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
   // Match Go's filename encoding: replace :// and / and : with _
   const filename = key + '.json';
   return path.join(dir, filename);
 }
 
+function credentialsPath(key) {
+  const filePath = credentialsFilePath(key);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+  return filePath;
+}
+
 function getOAuthClientID() {
   return process.env.SERVICENOW_OAUTH_CLIENT_ID || DEFAULT_OAUTH_CLIENT_ID;
 }
@@ -167,6 +172,9 @@ function keyringLookup(key) {
       refresh_token: parsed.refresh_token || parsed.RefreshToken || '',
       expires_at: parsed.expires_at || parsed.ExpiresAt || 0,
       created_at: parsed.created_at || parsed.CreatedAt || 0,
+      auth_source: ['oauth', 'env_token', 'env_basic', undefined].includes(parsed.auth_source)
+        ? (parsed.auth_method === 'gck' ? 'gck' : 'keyring')
+        : parsed.auth_source,
     };
   } catch {
     return null;
@@ -206,16 +214,25 @@ function keyringDelete(key) {
  * When username is omitted (legacy configs without profile user), uses
  * bare instance key for lookup.
  */
-function loadCredentials(instance, username) {
+function loadCredentials(instance, username, injectedStore) {
+  if (injectedStore) return injectedStore.load(instance, username);
   const key = username ? credKey(instance, username) : credKey(instance);
   const keyringCreds = keyringLookup(key);
   if (keyringCreds) {
-    return { ...keyringCreds, auth_source: 'keyring' };
+    return {
+      ...keyringCreds,
+      auth_source: keyringCreds.auth_source || (keyringCreds.auth_method === 'gck' ? 'gck' : 'keyring'),
+    };
   }
   try {
-    const data = fs.readFileSync(credentialsPath(key), 'utf-8');
+    const data = fs.readFileSync(credentialsFilePath(key), 'utf-8');
     const creds = JSON.parse(data);
-    return { ...creds, auth_source: 'file' };
+    return {
+      ...creds,
+      auth_source: ['oauth', 'env_token', 'env_basic', undefined].includes(creds.auth_source)
+        ? (creds.auth_method === 'gck' ? 'gck' : 'file')
+        : creds.auth_source,
+    };
   } catch {
     return null;
   }
@@ -225,7 +242,11 @@ function loadCredentials(instance, username) {
  * Save credentials for an instance.
  * Uses <username>@<instance> key when username is available.
  */
-function saveCredentials(instance, creds, username) {
+function saveCredentials(instance, creds, username, injectedStore) {
+  if (injectedStore) {
+    creds.last_seen = creds.last_seen || Math.floor(Date.now() / 1000);
+    return injectedStore.save(instance, creds, username);
+  }
   const key = username ? credKey(instance, username) : credKey(instance);
   // Stamp last_seen on every credential save
   creds.last_seen = creds.last_seen || Math.floor(Date.now() / 1000);
@@ -235,29 +256,11 @@ function saveCredentials(instance, creds, username) {
   }
 }
 
-/**
- * Get the last_seen timestamp for an instance, if available.
- */
-function getLastSeen(instance, username) {
-  const creds = loadCredentials(instance, username);
-  if (!creds || !creds.last_seen) return null;
-  return creds.last_seen;
-}
-
-/**
- * Update the last_seen timestamp for an instance to now.
- */
-function touchLastSeen(instance, username) {
-  const creds = loadCredentials(instance, username);
-  if (!creds) return;
-  creds.last_seen = Math.floor(Date.now() / 1000);
-  saveCredentials(instance, creds, username);
-}
-
 /**
  * Delete credentials for an instance keyed by <username>@<instance>.
  */
-function deleteCredentials(instance, username) {
+function deleteCredentials(instance, username, injectedStore) {
+  if (injectedStore) return injectedStore.delete(instance, username);
   const key = username ? credKey(instance, username) : credKey(instance);
   keyringDelete(key);
   try {
@@ -267,6 +270,12 @@ function deleteCredentials(instance, username) {
   }
 }
 
+const defaultCredentialStore = {
+  load: loadCredentials,
+  save: saveCredentials,
+  delete: deleteCredentials,
+};
+
 function askHidden(promptText) {
   return passwordPrompt({ message: promptText });
 }
@@ -290,6 +299,130 @@ export function parseBrowserSessionInput(input) {
   return { auth_method: 'gck', access_token: token, cookies, auth_source: 'gck' };
 }
 
+const AUTH_METHODS = new Set(['oauth', 'basic', 'gck']);
+const AUTH_SOURCES = new Set(['env_token', 'env_basic', 'gck', 'keyring', 'file', 'unavailable']);
+
+function normalizeAuthMethod(value, fallback = 'unconfigured') {
+  return AUTH_METHODS.has(value) ? value : fallback;
+}
+
+function normalizeAuthSource(value, fallback = 'unavailable') {
+  return AUTH_SOURCES.has(value) ? value : fallback;
+}
+
+function sourceMethod(source) {
+  return { env_token: 'oauth', env_basic: 'basic', gck: 'gck' }[source] || null;
+}
+
+const PROBE_FAILURES = {
+  missing_credentials: {
+    message: 'Credentials are not available for this profile.',
+    hint: 'Run: jsn auth login',
+  },
+  credentials_expired: {
+    message: 'Credentials have expired and cannot be refreshed.',
+    hint: 'Run: jsn auth login',
+  },
+  refresh_required: {
+    message: 'Credentials require refresh before probing.',
+    hint: 'Run: jsn auth refresh',
+  },
+  refresh_failed: {
+    message: 'Credential refresh failed before the authenticated probe.',
+    hint: 'Run: jsn auth login',
+  },
+  invalid_browser_session: {
+    message: 'Browser session credentials are incomplete or invalid.',
+    hint: 'Capture a fresh ServiceNow browser request and run: jsn auth login --gck',
+  },
+  malformed_credentials: {
+    message: 'Credentials are malformed for the selected authentication method.',
+    hint: 'Run: jsn auth login',
+  },
+  permission_denied: {
+    message: 'The authenticated user lacks permission for the current-user probe.',
+    hint: 'Ask an administrator to grant access to the sys_user table/API.',
+  },
+  unauthorized: {
+    message: 'The instance rejected the selected credentials.',
+    hint: 'Run: jsn auth login',
+  },
+  network: {
+    message: 'The authenticated probe could not reach the instance.',
+    hint: 'Check your internet connection and instance URL.',
+  },
+  unknown: {
+    message: 'The authenticated probe failed for an unknown reason.',
+    hint: 'Retry the probe; if it persists, check the instance logs.',
+  },
+  missing_instance: {
+    message: 'No instance is configured for this profile.',
+    hint: 'Set an instance URL and run: jsn auth login',
+  },
+  sdk_construction_failed: {
+    message: 'The authenticated probe could not be initialized for this profile.',
+    hint: 'Check the profile configuration and run: jsn auth status again',
+  },
+};
+
+const PROBE_CLASSIFICATIONS = {
+  missing_credentials: 'unavailable', credentials_expired: 'expired', refresh_required: 'refresh_required',
+  refresh_failed: 'refresh_failed', invalid_browser_session: 'browser_session_invalid',
+  malformed_credentials: 'malformed', permission_denied: 'permission_denied', unauthorized: 'unauthorized',
+  network: 'network_error', unknown: 'unknown',
+  missing_instance: 'unavailable', sdk_construction_failed: 'configuration_error',
+};
+
+function probeFailure(code, status = 'failed') {
+  return { status, code, classification: PROBE_CLASSIFICATIONS[code] || 'unknown', ...PROBE_FAILURES[code] };
+}
+
+function classifyProbeError(error, method) {
+  if (error?.status === 401 || error?.status === 403) {
+    return error.status === 403 ? 'permission_denied' : 'unauthorized';
+  }
+  if (error?.code === 'network_error' || ['ECONNREFUSED', 'ENOTFOUND', 'ETIMEDOUT'].includes(error?.code)) {
+    return 'network';
+  }
+  const text = String(error?.message || '').toLowerCase();
+  if (error?.code === 'auth_error' && text.includes('refresh')) return 'refresh_failed';
+  if (method === 'gck' && error?.code === 'auth_error') return 'invalid_browser_session';
+  return 'unknown';
+}
+
+/**
+ * Classify credentials without returning or logging any credential material.
+ * This is deliberately pure so diagnostics cannot refresh, persist, or probe.
+ */
+export function classifyCredentialState(credentials, method, now = Date.now()) {
+  if (!credentials) return 'missing';
+  if (!AUTH_METHODS.has(method)) return 'malformed';
+
+  if (method === 'basic') {
+    const hasUser = typeof credentials.username === 'string' && credentials.username.length > 0;
+    const hasPassword = typeof credentials.password === 'string' && credentials.password.length > 0;
+    return hasUser && hasPassword ? 'available' : 'malformed';
+  }
+
+  if (method === 'gck') {
+    const hasToken = typeof credentials.access_token === 'string' && credentials.access_token.length > 0;
+    const hasCookies = typeof credentials.cookies === 'string' && credentials.cookies.length > 0;
+    return hasToken && hasCookies ? 'available' : 'malformed';
+  }
+
+  if (credentials.access_token !== undefined && typeof credentials.access_token !== 'string') return 'malformed';
+  if (credentials.refresh_token !== undefined && typeof credentials.refresh_token !== 'string') return 'malformed';
+
+  const hasToken = typeof credentials.access_token === 'string' && credentials.access_token.length > 0;
+  if (!hasToken) return credentials.refresh_token ? 'refreshable' : 'missing';
+  if (credentials.expires_at !== undefined && credentials.expires_at !== null && credentials.expires_at !== 0) {
+    const expiresAt = Number(credentials.expires_at);
+    if (!Number.isFinite(expiresAt)) return 'malformed';
+    if (now >= (expiresAt - 300) * 1000) return credentials.refresh_token ? 'refreshable' : 'expired';
+  }
+  return 'available';
+}
+
 export class AuthManager {
   /**
    * @param {object} identity — the resolved-identity provider. Production
@@ -300,8 +433,11 @@ export class AuthManager {
    *   Transitional back-compat: a legacy configProvider ({ config, ...
    *   getEffectiveInstance() }) is adapted to the identity surface, so the
    *   existing test fixtures (which predate the session) keep working.
+   * @param {object} options
+   * @param {object} options.credentialStore — optional load/save/delete adapter;
+   *   defaults to the OS keyring with file fallback.
    */
-  constructor(identity) {
+  constructor(identity, { credentialStore = defaultCredentialStore } = {}) {
     if (identity && identity.config && typeof identity.getUsername !== 'function') {
       const provider = identity;
       this.identity = {
@@ -311,10 +447,16 @@ export class AuthManager {
           return (name && cfg.profiles?.[name]?.username) || null;
         },
         getEffectiveInstance: () => provider.getEffectiveInstance(),
+        getAuthMethod: () => {
+          const cfg = provider.config;
+          const name = cfg.activeProfile || cfg.defaultProfile;
+          return cfg.profiles?.[name]?.auth_method || null;
+        },
       };
     } else {
       this.identity = identity;
     }
+    this.credentialStore = credentialStore;
     this.httpClient = { timeout: 30000 };
   }
 
@@ -324,15 +466,39 @@ export class AuthManager {
    * instance key for backward compatibility with legacy / no-profile usage.
    */
   _activeUsername() {
-    return this.identity.getUsername() || null;
+    return typeof this.identity.getUsername === 'function' ? this.identity.getUsername() || null : null;
+  }
+
+  // An options object with a username property is an explicit identity,
+  // including `username: undefined` which intentionally selects bare creds.
+  // Omitted options retain the legacy active-user fallback.
+  _usernameForOptions(options = {}) {
+    return Object.hasOwn(options, 'username') ? options.username : this._activeUsername();
   }
 
-  getLastSeen(instance) {
-    return getLastSeen(instance, this._activeUsername());
+  loadCredentials(instance, username) {
+    return this.credentialStore.load(instance, username);
   }
 
-  touchLastSeen(instance) {
-    return touchLastSeen(instance, this._activeUsername());
+  saveCredentials(instance, credentials, username) {
+    return this.credentialStore.save(instance, credentials, username);
+  }
+
+  deleteCredentials(instance, username) {
+    return this.credentialStore.delete(instance, username);
+  }
+
+  getLastSeen(instance, options = {}) {
+    const creds = this.loadCredentials(instance, this._usernameForOptions(options));
+    return creds?.last_seen || null;
+  }
+
+  touchLastSeen(instance, options = {}) {
+    const username = this._usernameForOptions(options);
+    const creds = this.credentialStore.load(instance, username);
+    if (!creds) return;
+    creds.last_seen = Math.floor(Date.now() / 1000);
+    this.credentialStore.save(instance, creds, username);
   }
 
   /**
@@ -340,15 +506,15 @@ export class AuthManager {
    * user@instance keying). Returns true when old-style creds are found
    * but wouldn't be picked up by the current username-scoped lookup.
    */
-  hasLegacyCredentials(instance) {
+  hasLegacyCredentials(instance, options = {}) {
     if (!instance) return false;
-    const bareCreds = loadCredentials(instance);
+    const bareCreds = this.credentialStore.load(instance);
     if (!bareCreds) return false;
     // If active profile has a username, the bare key won't be found
     // by loadCredentials(instance, username). That's the legacy case.
-    const username = this._activeUsername();
+    const username = this._usernameForOptions(options);
     if (!username) return false; // No username set — bare key IS the active path
-    const userCreds = loadCredentials(instance, username);
+    const userCreds = this.credentialStore.load(instance, username);
     return !!bareCreds && !userCreds;
   }
 
@@ -358,76 +524,187 @@ export class AuthManager {
    * For older stored credentials without auth_source, falls back
    * to the saved auth_method field.
    */
-  getAuthSource(instance) {
-    if (process.env.SERVICENOW_OAUTH_TOKEN) return 'env_token';
-    if (getBasicAuthFromEnv(instance)) return 'env_basic';
-    const creds = loadCredentials(instance, this._activeUsername());
+  getAuthSource(instance, options = {}) {
+    const method = this._selectedMethod(options);
+    if (method !== 'gck' && method !== 'basic' && process.env.SERVICENOW_OAUTH_TOKEN) return 'env_token';
+    if (method !== 'gck' && method !== 'oauth' && getBasicAuthFromEnv(instance)) return 'env_basic';
+    const creds = this.credentialStore.load(instance, this._usernameForOptions(options));
     if (!creds) return null;
+    // A configured method is authoritative at this public boundary. Stored
+    // metadata from another method must not be reported as usable source.
+    if (method !== 'unconfigured') {
+      const storedMethod = normalizeAuthMethod(creds.auth_method, '');
+      if (creds.auth_method != null && (!storedMethod || storedMethod !== method)) return 'unavailable';
+      const source = normalizeAuthSource(creds.auth_source, '');
+      if (!source) return 'unavailable';
+      const sourceMethod = { env_token: 'oauth', env_basic: 'basic', gck: 'gck' }[source];
+      if (sourceMethod && sourceMethod !== method) return 'unavailable';
+      return source;
+    }
     // New creds have auth_source; older ones only have auth_method
-    return creds.auth_source || creds.auth_method || 'stored';
+    const source = normalizeAuthSource(creds.auth_source, '');
+    if (source) return source;
+    return normalizeAuthMethod(creds.auth_method, '') || 'unavailable';
+  }
+
+  probeUnavailable(code) {
+    return probeFailure(code, 'not_attempted');
+  }
+
+  _selectedMethod(options = {}) {
+    const value = Object.hasOwn(options, 'authMethod') ? options.authMethod
+      : typeof this.identity.getAuthMethod === 'function' ? this.identity.getAuthMethod() : null;
+    return normalizeAuthMethod(value, 'unconfigured');
+  }
+
+  createProfileProvider(instance, options = {}) {
+    return {
+      getCredentials: () => this.getCredentialsFor(instance, options.username, options),
+      touchLastSeen: () => this.touchLastSeen(instance, options),
+    };
+  }
+
+  /**
+   * Return only safe metadata about the selected auth method and credentials.
+   * Unlike getCredentialsFor(), this never refreshes or mutates credentials.
+   */
+  getAuthState(instance = this.identity.getEffectiveInstance(), options = {}) {
+    const configuredValue = Object.hasOwn(options, 'authMethod')
+      ? options.authMethod
+      : typeof this.identity.getAuthMethod === 'function'
+      ? this.identity.getAuthMethod() : null;
+    const configuredMethod = normalizeAuthMethod(configuredValue);
+    const isConfigured = configuredMethod !== 'unconfigured';
+    let method = configuredMethod;
+    let classificationMethod = isConfigured ? configuredMethod : null;
+    let source = 'unavailable';
+    let credentials = null;
+    let malformedMetadata = configuredValue != null && !isConfigured;
+
+    if (process.env.SERVICENOW_OAUTH_TOKEN && (!isConfigured || configuredMethod === 'oauth')) {
+      source = 'env_token';
+      classificationMethod = 'oauth';
+      credentials = { access_token: process.env.SERVICENOW_OAUTH_TOKEN };
+    } else {
+      const basicCredentials = getBasicAuthFromEnv(instance);
+      if (basicCredentials && (!isConfigured || configuredMethod === 'basic')) {
+        source = 'env_basic';
+        classificationMethod = 'basic';
+        credentials = basicCredentials;
+      } else if (instance) {
+        credentials = this.credentialStore.load(instance, this._usernameForOptions(options));
+        if (credentials) {
+          if (credentials.auth_method != null) {
+            const storedMethod = normalizeAuthMethod(credentials.auth_method, '');
+            if (!storedMethod) malformedMetadata = true;
+            else if (isConfigured && storedMethod !== configuredMethod) malformedMetadata = true;
+            else if (!isConfigured) classificationMethod = storedMethod;
+          }
+          if (credentials.auth_source != null) {
+            const storedSource = normalizeAuthSource(credentials.auth_source, '');
+            if (storedSource) source = storedSource;
+            else {
+              source = 'unavailable';
+              malformedMetadata = true;
+            }
+            if (storedSource && isConfigured && sourceMethod(storedSource)
+              && sourceMethod(storedSource) !== configuredMethod) {
+              source = 'unavailable';
+              malformedMetadata = true;
+            }
+          }
+        }
+      }
+    }
+
+    const state = malformedMetadata
+      ? 'malformed'
+      : classificationMethod
+        ? classifyCredentialState(credentials, classificationMethod)
+        : credentials ? 'malformed' : 'missing';
+    return {
+      auth_method: method,
+      auth_source: normalizeAuthSource(source, 'unavailable'),
+      state,
+    };
+  }
+
+  /**
+   * Perform one read-only authenticated current-user request and classify only
+   * safe lifecycle outcomes. The SDK is injected to keep this seam independent
+   * of command wiring and to make the selected auth path explicit.
+   */
+  async probeCurrentUser(instance = this.identity.getEffectiveInstance(), sdk, options = {}) {
+    const authState = this.getAuthState(instance, options);
+    const method = authState.auth_method === 'unconfigured' ? null : authState.auth_method;
+    const stateFailures = {
+      missing: 'missing_credentials',
+      expired: 'credentials_expired',
+      refreshable: 'refresh_required',
+      malformed: method === 'gck' ? 'invalid_browser_session' : 'malformed_credentials',
+    };
+    if (stateFailures[authState.state]) return probeFailure(stateFailures[authState.state], 'not_attempted');
+    if (!sdk || typeof sdk.getCurrentUser !== 'function') return probeFailure('unknown', 'not_attempted');
+
+    try {
+      await sdk.getCurrentUser({ touchLastSeen: false });
+      return { status: 'succeeded', classification: 'authenticated' };
+    } catch (error) {
+      return probeFailure(classifyProbeError(error, method));
+    }
   }
 
   isAuthenticated() {
-    if (process.env.SERVICENOW_OAUTH_TOKEN) return true;
-    if (getBasicAuthFromEnv()) return true;
     const instance = this.identity.getEffectiveInstance();
     if (!instance) return false;
-    try {
-      this.getCredentialsFor(instance);
-      return true;
-    } catch {
-      return false;
-    }
+    return this.getAuthState(instance).state === 'available';
   }
 
-  isAuthenticatedFor(instance) {
+  isAuthenticatedFor(instance, options = {}) {
     if (!instance) return false;
-    if (getBasicAuthFromEnv(instance)) return true;
-    const creds = loadCredentials(instance, this._activeUsername());
-    if (!creds) return false;
-    if (creds.auth_method === 'basic') {
-      return Boolean(creds.username && creds.password);
-    }
-    if (creds.auth_method === 'gck') {
-      return Boolean(creds.access_token && creds.cookies);
-    }
-    if (creds.expires_at && Date.now() >= creds.expires_at * 1000) return false;
-    return !!creds.access_token;
+    return this.getAuthState(instance, options).state === 'available';
   }
 
   async getCredentials() {
-    if (process.env.SERVICENOW_OAUTH_TOKEN) {
-      return { auth_method: 'oauth', access_token: process.env.SERVICENOW_OAUTH_TOKEN, auth_source: 'env_token' };
-    }
     const instance = this.identity.getEffectiveInstance();
     if (!instance) {
       throw errAuth('No instance configured');
     }
-    // Check basic auth from env vars first
-    const basicCreds = getBasicAuthFromEnv(instance);
-    if (basicCreds) return basicCreds;
     return this.getCredentialsFor(instance);
   }
 
-  getCredentialsFor(instance, username = this._activeUsername()) {
-    // Check basic auth from env vars first
-    const basicCreds = getBasicAuthFromEnv(instance);
-    if (basicCreds) return basicCreds;
-    const creds = loadCredentials(instance, username);
+  getCredentialsFor(instance, username, options = {}) {
+    const method = this._selectedMethod(options);
+    // With no configured method, preserve the legacy environment precedence:
+    // OAuth token first, then Basic credentials, then stored credentials.
+    if ((method === 'unconfigured' || method === 'oauth') && process.env.SERVICENOW_OAUTH_TOKEN) {
+      return { auth_method: 'oauth', access_token: process.env.SERVICENOW_OAUTH_TOKEN, auth_source: 'env_token' };
+    }
+    if (method === 'unconfigured' || method === 'basic') {
+      const basicCreds = getBasicAuthFromEnv(instance);
+      if (basicCreds) return basicCreds;
+    }
+    const credentialUsername = Object.hasOwn(options, 'username') ? options.username : (username ?? this._activeUsername());
+    const creds = this.credentialStore.load(instance, credentialUsername);
     if (!creds) {
       throw errAuth(`Not authenticated for ${instance}`);
     }
+    if (method !== 'unconfigured' && creds.auth_method != null && creds.auth_method !== method) {
+      throw errAuth(`Stored credentials do not match configured ${method} authentication`);
+    }
+    const resolved = method !== 'unconfigured' && !creds.auth_method ? { ...creds, auth_method: method } : creds;
+    if (method === 'gck' && (!resolved.access_token || !resolved.cookies)) throw errAuth('Invalid browser session credentials');
+    if (method === 'basic' && (!resolved.username || !resolved.password)) throw errAuth('Invalid basic auth credentials');
+    if (method === 'oauth' && !resolved.access_token) throw errAuth('Invalid OAuth credentials');
     // Check expiry — refresh if less than 5 minutes remaining
-    if (creds.expires_at && Date.now() >= (creds.expires_at - 300) * 1000) {
-      if (creds.refresh_token) {
-        return this.refreshToken(instance, creds);
-      }
+    if (resolved.expires_at && Date.now() >= (resolved.expires_at - 300) * 1000) {
+      if (resolved.refresh_token) return this.refreshToken(instance, resolved, credentialUsername);
       throw errAuth('Token expired, please login again');
     }
-    return creds;
+    return resolved;
   }
 
-  async login(instanceURL) {
+  async login(instanceURL, username = this._activeUsername()) {
     instanceURL = normalizeInstanceURL(instanceURL);
     const clientID = getOAuthClientID();
     const pkce = generatePKCE();
@@ -453,8 +730,8 @@ export class AuthManager {
 
     console.log('\nExchanging authorization code for tokens...');
     const newCreds = await this.exchangeCode(instanceURL, clientID, code, pkce);
-    // Save with username for per-user credential keying
-    saveCredentials(instanceURL, newCreds, newCreds.username);
+    // Save with the selected profile username when one is already known.
+    this.saveCredentials(instanceURL, newCreds, username || newCreds.username);
     return newCreds;
   }
 
@@ -465,7 +742,7 @@ export class AuthManager {
    * If waitFile is provided, the method will read the code from that file
    * (waits for file to appear, polling every 2 seconds, up to 5 minutes).
    */
-  buildAuthURL(instanceURL, waitFile) {
+  buildAuthURL(instanceURL, waitFile, username = this._activeUsername()) {
     instanceURL = normalizeInstanceURL(instanceURL);
     const clientID = getOAuthClientID();
     const pkce = generatePKCE();
@@ -476,12 +753,12 @@ export class AuthManager {
       console.log();
       console.log(`Waiting for authorization code in file: ${waitFile}`);
       console.log('(polling every 2 seconds — write the code to the file to complete login)');
-      return this._waitForCodeFile(instanceURL, clientID, pkce, waitFile);
+      return this._waitForCodeFile(instanceURL, clientID, pkce, waitFile, 300000, username);
     }
     return url;
   }
 
-  async _waitForCodeFile(instanceURL, clientID, pkce, filePath, timeout = 300000) {
+  async _waitForCodeFile(instanceURL, clientID, pkce, filePath, timeout = 300000, username) {
     const start = Date.now();
     const pollInterval = 2000;
     while (Date.now() - start < timeout) {
@@ -491,7 +768,7 @@ export class AuthManager {
           console.log(`\nAuthorization code found in ${filePath}`);
           removePKCEState(instanceURL);
           const newCreds = await this.exchangeCode(instanceURL, clientID, code, pkce);
-          saveCredentials(instanceURL, newCreds, newCreds.username);
+          this.saveCredentials(instanceURL, newCreds, username || newCreds.username);
           console.log('Token exchange successful!\n');
           return newCreds;
         }
@@ -511,7 +788,7 @@ export class AuthManager {
   async loginWithPassword(instanceURL, username = this._activeUsername()) {
     instanceURL = normalizeInstanceURL(instanceURL);
     const envCreds = getBasicAuthFromEnv(instanceURL);
-    const storedCreds = loadCredentials(instanceURL, username);
+    const storedCreds = this.loadCredentials(instanceURL, username);
     const creds = envCreds || storedCreds;
     if (!creds || creds.auth_method !== 'basic' || !creds.username || !creds.password) {
       throw errAuth(
@@ -523,7 +800,7 @@ export class AuthManager {
         `  jsn auth login --basic ${instanceURL}`
       );
     }
-    saveCredentials(instanceURL, creds, creds.username);
+    this.saveCredentials(instanceURL, creds, creds.username);
     console.log(`✓ Basic auth credentials saved for ${instanceURL}`);
     return creds;
   }
@@ -535,11 +812,11 @@ export class AuthManager {
   async loginWithGck(instanceURL, input, username = this._activeUsername()) {
     instanceURL = normalizeInstanceURL(instanceURL);
     const creds = parseBrowserSessionInput(input);
-    saveCredentials(instanceURL, { ...creds, username: username || undefined }, username || undefined);
+    this.saveCredentials(instanceURL, { ...creds, username: username || undefined }, username || undefined);
     return { ...creds, username: username || undefined };
   }
 
-  async loginWithCode(instanceURL, code) {
+  async loginWithCode(instanceURL, code, username = this._activeUsername()) {
     instanceURL = normalizeInstanceURL(instanceURL);
     const clientID = getOAuthClientID();
     const pkce = loadPKCEState(instanceURL);
@@ -555,7 +832,7 @@ export class AuthManager {
     removePKCEState(instanceURL);
 
     const newCreds = await this.exchangeCode(instanceURL, clientID, code, pkce);
-    saveCredentials(instanceURL, newCreds, newCreds.username);
+    this.saveCredentials(instanceURL, newCreds, username || newCreds.username);
     return newCreds;
   }
 
@@ -576,7 +853,7 @@ export class AuthManager {
 
     const text = await resp.text();
     if (!resp.ok) {
-      throw errAuth(`Token exchange failed (status ${resp.status}): ${text}`);
+      throw errAuth(`Token exchange failed (status ${resp.status})`);
     }
 
     const tokenResp = JSON.parse(text);
@@ -592,7 +869,10 @@ export class AuthManager {
     };
   }
 
-  async refreshToken(instance, creds) {
+  async refreshToken(instance, creds, targetUsername = undefined) {
+    if (creds.auth_method !== 'oauth') {
+      throw errAuth(`Cannot refresh ${creds.auth_method || 'unconfigured'} credentials; only OAuth credentials support refresh`);
+    }
     const tokenURL = `${instance.replace(/\/$/, '')}/oauth_token.do`;
     const clientID = getOAuthClientID();
     const body = new URLSearchParams();
@@ -607,11 +887,17 @@ export class AuthManager {
     });
 
     if (!resp.ok) {
-      const text = await resp.text();
-      throw errAuth(`Token refresh failed: ${text}`);
+      await resp.text();
+      throw errAuth(`Token refresh failed (status ${resp.status})`);
     }
 
     const tokenResp = await resp.json();
+    // An explicitly supplied target (including null for a username-less
+    // non-active target) must not fall back to the active identity. Preserve
+    // the legacy fallback only for callers that omit the third argument.
+    const username = targetUsername !== undefined
+      ? (targetUsername || creds.username || null)
+      : (creds.username || this._activeUsername());
     const newCreds = {
       auth_method: 'oauth',
       access_token: tokenResp.access_token,
@@ -622,15 +908,15 @@ export class AuthManager {
     if (tokenResp.expires_in) {
       newCreds.expires_at = Math.floor(Date.now() / 1000) + tokenResp.expires_in;
     }
-    saveCredentials(instance, newCreds, creds.username);
+    this.credentialStore.save(instance, newCreds, username);
     return newCreds;
   }
 
-  logout(instance) {
+  logout(instance, username = this._activeUsername()) {
     if (!instance) {
       throw errAuth('No instance specified');
     }
-    deleteCredentials(instance, this._activeUsername());
+    this.credentialStore.delete(instance, username);
   }
 
   /**
@@ -643,11 +929,11 @@ export class AuthManager {
    */
   migrateLegacyCredential(instance, username) {
     if (!instance || !username) return false;
-    const stored = loadCredentials(instance);
+    const stored = this.credentialStore.load(instance);
     if (!stored || !stored.access_token) return false;
     stored.username = username;
-    saveCredentials(instance, stored, username);
-    deleteCredentials(instance); // remove bare-instance legacy key
+    this.credentialStore.save(instance, stored, username);
+    this.credentialStore.delete(instance); // remove bare-instance legacy key
     return true;
   }
 }