@W-20893800: Adding support for stateful auth [sfcc-ci compatibility]

Author: amit-kumar8-sf

docs/cli/auth.md

@@ -10,7 +10,7 @@ Commands for authentication and token management.
 
 The CLI supports **stateful auth** (session stored on disk) in addition to **stateless auth** (client credentials or one-off implicit flow):
 
-- **Stateful (browser)**: After you run `b2c auth login`, your token is stored in the same location as [sfcc-ci](https://github.com/SalesforceCommerceCloud/sfcc-ci). Subsequent commands (e.g. `b2c auth token`, `b2c am orgs list`) use this token when it is present and valid. If the token is missing or expired, the CLI falls back to stateless auth.
+- **Stateful (browser)**: After you run `b2c auth login`, your token is stored on disk in the CLI data directory. Subsequent commands (e.g. `b2c auth token`, `b2c am orgs list`) use this token when it is present and valid. If the token is missing or expired, the CLI falls back to stateless auth.
 - **Stateful (client credentials)**: Use `b2c auth client` to authenticate with client ID and secret (or user/password) for non-interactive/automation use. Supports auto-renewal with `--renew`.
 - **Stateless**: You provide `--client-id` (and optionally `--client-secret`) per run or via environment/config; no session is persisted.
 
@@ -20,7 +20,7 @@ Use **auth:logout** to clear the stored session and return to stateless-only beh
 
 ## b2c auth login
 
-Log in via browser (implicit OAuth) and save the session for stateful auth. Uses the same storage as sfcc-ci.
+Log in via browser (implicit OAuth) and save the session for stateful auth.
 
 ### Usage
 
@@ -41,7 +41,7 @@ b2c auth logout
 
 ## b2c auth client
 
-Authenticate an API client using client credentials or resource owner password credentials and save the session for stateful auth. Mirrors the [sfcc-ci `client:auth`](https://github.com/SalesforceCommerceCloud/sfcc-ci) command.
+Authenticate an API client using client credentials or resource owner password credentials and save the session for stateful auth. Compatible with the [sfcc-ci `client:auth`](https://github.com/SalesforceCommerceCloud/sfcc-ci) workflow.
 
 This is the non-interactive alternative to `auth login` — ideal for CI/CD pipelines and automation.
 
@@ -120,7 +120,7 @@ b2c auth client renew
 
 ## b2c auth client token
 
-Return the current stored authentication token. Mirrors [sfcc-ci `client:auth:token`](https://github.com/SalesforceCommerceCloud/sfcc-ci).
+Return the current stored authentication token. Compatible with the [sfcc-ci `client:auth:token`](https://github.com/SalesforceCommerceCloud/sfcc-ci) workflow.
 
 ### Usage
 

docs/guide/authentication.md

@@ -49,9 +49,9 @@ The CLI supports four authentication methods:
 
 **Client Credentials** uses the API client's secret for non-interactive authentication. This is ideal for CI/CD pipelines and automation.
 
-**Stateful User Auth** uses `b2c auth login` to open a browser for interactive login once, then stores the session on disk. Subsequent commands automatically use the stored token when it is present and valid, without re-opening the browser. Uses the same storage as [sfcc-ci](https://github.com/SalesforceCommerceCloud/sfcc-ci). Clear the session with `b2c auth logout`. See [Auth Commands](/cli/auth#b2c-auth-login) for details.
+**Stateful User Auth** uses `b2c auth login` to open a browser for interactive login once, then stores the session on disk. Subsequent commands automatically use the stored token when it is present and valid, without re-opening the browser. Clear the session with `b2c auth logout`. See [Auth Commands](/cli/auth#b2c-auth-login) for details.
 
-**Stateful Client Auth** uses `b2c auth client` to authenticate once with client credentials (or user/password), store the session, and reuse it across subsequent commands without passing credentials each time. Use `--renew` to enable automatic token renewal via `b2c auth client renew`. See [Auth Commands](/cli/auth#b2c-auth-client) for details.
+**Stateful Client Auth** uses `b2c auth client` to authenticate once with client credentials (or user/password), store the session, and reuse it across subsequent commands without passing credentials each time. Mirrors the [sfcc-ci](https://github.com/SalesforceCommerceCloud/sfcc-ci) `client:auth` workflow. Use `--renew` to enable automatic token renewal via `b2c auth client renew`. See [Auth Commands](/cli/auth#b2c-auth-client) for details.
 
 ::: warning Stateful vs Stateless Precedence
 The stored session is used only when the token is valid **and** no explicit auth flags are provided. The CLI falls back to stateless auth when:

packages/b2c-tooling-sdk/package.json

@@ -359,7 +359,6 @@
     "node": ">=22.16.0"
   },
   "dependencies": {
-    "conf": "^13.0.0",
     "@salesforce/telemetry": "6.4.6",
     "archiver": "7.0.1",
     "chokidar": "5.0.0",

packages/b2c-tooling-sdk/src/auth/index.ts

@@ -84,8 +84,9 @@ export {ApiKeyStrategy} from './api-key.js';
 export {StatefulOAuthStrategy} from './stateful-oauth-strategy.js';
 export type {StatefulOAuthStrategyOptions} from './stateful-oauth-strategy.js';
 
-// Stateful auth store (sfcc-ci compatible)
+// Stateful auth store
 export {
+  initializeStatefulStore,
   getStoredSession,
   setStoredSession,
   clearStoredSession,

packages/b2c-tooling-sdk/src/auth/stateful-store.ts

@@ -4,110 +4,131 @@
  * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
  */
 /**
- * Stateful auth store using the same storage mechanism and keys as sfcc-ci.
- * Uses the `conf` package with projectName 'sfcc-ci' so tokens persist across
- * sfcc-ci and b2c-cli when present and valid.
+ * Stateful auth store backed by a JSON file in the oclif data directory
+ * (e.g. ~/Library/Application Support/@salesforce/b2c-cli/auth-session.json on macOS).
+ *
+ * Initialize via initializeStatefulStore(dataDir) from BaseCommand.init() so the
+ * session file is co-located with other CLI data. Falls back to an OS-appropriate
+ * default path when used standalone (outside a CLI command).
+ *
+ * The stateful auth workflow (b2c auth client / b2c auth login / b2c auth logout)
+ * is compatible with sfcc-ci command patterns. Session data is stored internally
+ * in the CLI data directory, not in the sfcc-ci config store.
  *
  * @module auth/stateful-store
  */
-import Conf from 'conf';
+import {existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync} from 'node:fs';
+import {join} from 'node:path';
+import {homedir, platform} from 'node:os';
 import {decodeJWT} from './oauth.js';
 import {getLogger} from '../logging/logger.js';
 
-/** Config keys matching sfcc-ci lib/config usage */
-const SFCC_CLIENT_ID = 'SFCC_CLIENT_ID';
-const SFCC_CLIENT_TOKEN = 'SFCC_CLIENT_TOKEN';
-const SFCC_REFRESH_TOKEN = 'SFCC_REFRESH_TOKEN';
-const SFCC_CLIENT_RENEW_BASE = 'SFCC_CLIENT_RENEW_BASE';
-const SFCC_USER = 'SFCC_USER';
+const STATEFUL_AUTH_SESSION_STORE = 'auth-session.json';
 
 /** Default buffer (seconds) before token exp to consider it expired */
 const EXPIRY_BUFFER_SEC = 60;
 
-let storeInstance: Conf | null = null;
+let storePath: string | null = null;
 
 /**
- * Returns the conf store instance (projectName 'sfcc-ci' for compatibility with sfcc-ci).
- * Uses 'sfcc-ci-test' when NODE_ENV === 'test' so tests do not touch user config.
+ * Computes the oclif-compatible data directory for @salesforce/b2c-cli.
+ * Used as a fallback when initializeStatefulStore() has not been called.
  */
-function getStore(): Conf {
-  if (!storeInstance) {
-    const projectName = process.env.NODE_ENV === 'test' ? 'sfcc-ci-test' : 'sfcc-ci';
-    storeInstance = new Conf({projectName});
+function getDefaultDataDir(): string {
+  const home = homedir();
+  const name = '@salesforce/b2c-cli';
+  switch (platform()) {
+    case 'darwin':
+      return join(home, 'Library', 'Application Support', name);
+    case 'win32':
+      return join(process.env.LOCALAPPDATA ?? join(home, 'AppData', 'Local'), name);
+    default:
+      return join(process.env.XDG_DATA_HOME ?? join(home, '.local', 'share'), name);
   }
-  return storeInstance;
+}
+
+function getSessionFilePath(): string {
+  return join(storePath ?? getDefaultDataDir(), STATEFUL_AUTH_SESSION_STORE);
+}
+
+/**
+ * Initialize the stateful store with the oclif data directory.
+ * Call this from BaseCommand.init() with this.config.dataDir so the session
+ * file is stored alongside other CLI data (e.g. ~/Library/Application Support/@salesforce/b2c-cli).
+ */
+export function initializeStatefulStore(dataDir: string): void {
+  storePath = dataDir;
 }
 
 /**
- * Stored session read from stateful store.
- * Matches sfcc-ci persisted keys.
+ * Stored session persisted by stateful auth commands.
  */
 export interface StatefulSession {
   clientId: string;
   accessToken: string;
   refreshToken?: string | null;
-  /** Base64-encoded "clientId:clientSecret" for token renewal (client_credentials or refresh_token). */
+  /** Base64-encoded "clientId:clientSecret" for token renewal. */
   renewBase?: string | null;
   user?: string | null;
 }
 
 /**
- * Reads the current stateful session from store if present.
- * Returns null if no access token is stored.
+ * Reads the current stateful session from the JSON file.
+ * Returns null if no session file exists or the file is invalid.
  */
 export function getStoredSession(): StatefulSession | null {
-  const store = getStore();
-  const accessToken = store.get(SFCC_CLIENT_TOKEN) as string | undefined;
-  if (!accessToken) {
+  const filePath = getSessionFilePath();
+  if (!existsSync(filePath)) {
     return null;
   }
-  const clientId = store.get(SFCC_CLIENT_ID) as string | undefined;
-  if (!clientId) {
+  try {
+    const data = JSON.parse(readFileSync(filePath, 'utf8')) as Partial<StatefulSession>;
+    if (!data.clientId || !data.accessToken) {
+      return null;
+    }
+    return {
+      clientId: data.clientId,
+      accessToken: data.accessToken,
+      refreshToken: data.refreshToken ?? null,
+      renewBase: data.renewBase ?? null,
+      user: data.user ?? null,
+    };
+  } catch {
     return null;
   }
-  return {
-    clientId,
-    accessToken,
-    refreshToken: (store.get(SFCC_REFRESH_TOKEN) as string | undefined) ?? null,
-    renewBase: (store.get(SFCC_CLIENT_RENEW_BASE) as string | undefined) ?? null,
-    user: (store.get(SFCC_USER) as string | undefined) ?? null,
-  };
 }
 
 /**
- * Writes a session to the stateful store (same keys as sfcc-ci).
+ * Writes a session to the JSON file, creating the directory if needed.
  */
 export function setStoredSession(session: StatefulSession): void {
-  const store = getStore();
-  store.set(SFCC_CLIENT_ID, session.clientId);
-  store.set(SFCC_CLIENT_TOKEN, session.accessToken);
-  if (session.refreshToken != null) {
-    store.set(SFCC_REFRESH_TOKEN, session.refreshToken);
-  } else {
-    store.delete(SFCC_REFRESH_TOKEN);
-  }
-  if (session.renewBase != null) {
-    store.set(SFCC_CLIENT_RENEW_BASE, session.renewBase);
-  } else {
-    store.delete(SFCC_CLIENT_RENEW_BASE);
-  }
-  if (session.user != null) {
-    store.set(SFCC_USER, session.user);
-  } else {
-    store.delete(SFCC_USER);
+  const filePath = getSessionFilePath();
+  const dir = join(filePath, '..');
+  if (!existsSync(dir)) {
+    mkdirSync(dir, {recursive: true});
   }
+  const data: StatefulSession = {
+    clientId: session.clientId,
+    accessToken: session.accessToken,
+    refreshToken: session.refreshToken ?? null,
+    renewBase: session.renewBase ?? null,
+    user: session.user ?? null,
+  };
+  writeFileSync(filePath, JSON.stringify(data, null, 2), 'utf8');
 }
 
 /**
- * Clears all stateful auth data (same keys as sfcc-ci clear()).
+ * Clears the stored session by removing the session file.
  */
 export function clearStoredSession(): void {
-  const store = getStore();
-  store.delete(SFCC_CLIENT_ID);
-  store.delete(SFCC_CLIENT_TOKEN);
-  store.delete(SFCC_REFRESH_TOKEN);
-  store.delete(SFCC_CLIENT_RENEW_BASE);
-  store.delete(SFCC_USER);
+  const filePath = getSessionFilePath();
+  if (existsSync(filePath)) {
+    try {
+      unlinkSync(filePath);
+    } catch {
+      // ignore — file may have already been removed
+    }
+  }
 }
 
 /**
@@ -142,7 +163,7 @@ export function isStatefulTokenValid(
     }
     const nowSec = Math.floor(Date.now() / 1000);
     if (nowSec >= exp - expiryBufferSec) {
-      logger.debug('[StatefulAuth] Token expired or within buffer');
+      logger.debug('[StatefulAuth] Token missing or expired');
       return false;
     }
     if (requiredScopes.length > 0) {
@@ -162,9 +183,10 @@ export function isStatefulTokenValid(
 }
 
 /**
- * Resets the store instance (for tests).
+ * Resets the store path (for tests). After calling this, the next operation
+ * will use the default data directory unless initializeStatefulStore() is called again.
  * @internal
  */
 export function resetStatefulStoreForTesting(): void {
-  storeInstance = null;
+  storePath = null;
 }

packages/b2c-tooling-sdk/src/cli/base-command.ts

@@ -22,6 +22,7 @@ import {createExtraParamsMiddleware, type ExtraParamsConfig} from '../clients/mi
 import type {ConfigSource} from '../config/types.js';
 import {globalMiddlewareRegistry} from '../clients/middleware-registry.js';
 import {globalAuthMiddlewareRegistry} from '../auth/middleware.js';
+import {initializeStatefulStore} from '../auth/stateful-store.js';
 import {setUserAgent} from '../clients/user-agent.js';
 import {createTelemetry, Telemetry, type TelemetryAttributes} from '../telemetry/index.js';
 
@@ -155,6 +156,10 @@ export abstract class BaseCommand<T extends typeof Command> extends Command {
 
     this.configureLogging();
 
+    // Initialize stateful auth store with oclif's data directory so session
+    // files are stored alongside other CLI data (e.g. ~/Library/Application Support/@salesforce/b2c-cli)
+    initializeStatefulStore(this.config.dataDir);
+
     // Set CLI User-Agent (CLI name/version only, without @salesforce/ prefix)
     // This must happen before any API clients are created
     setUserAgent(`${this.config.name.replace(/^@salesforce\//, '')}/${this.config.version}`);

packages/b2c-tooling-sdk/test/auth/stateful-store.test.ts

@@ -3,8 +3,12 @@
  * SPDX-License-Identifier: Apache-2
  * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
  */
+import {mkdtempSync, rmSync} from 'node:fs';
+import {join} from 'node:path';
+import {tmpdir} from 'node:os';
 import {expect} from 'chai';
 import {
+  initializeStatefulStore,
   getStoredSession,
   setStoredSession,
   clearStoredSession,
@@ -21,20 +25,20 @@ function makeJWT(payload: {exp?: number; scope?: string | string[]}): string {
 }
 
 describe('auth/stateful-store', () => {
-  const originalEnv = process.env.NODE_ENV;
+  let testDir: string;
 
   before(() => {
-    process.env.NODE_ENV = 'test';
-    resetStatefulStoreForTesting();
+    testDir = mkdtempSync(join(tmpdir(), 'b2c-stateful-test-'));
+    initializeStatefulStore(testDir);
   });
 
   after(() => {
-    process.env.NODE_ENV = originalEnv;
+    resetStatefulStoreForTesting();
+    rmSync(testDir, {recursive: true, force: true});
   });
 
   afterEach(() => {
     clearStoredSession();
-    resetStatefulStoreForTesting();
   });
 
   describe('getStoredSession', () => {

packages/b2c-tooling-sdk/test/cli/oauth-command.test.ts

@@ -3,13 +3,17 @@
  * SPDX-License-Identifier: Apache-2
  * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
  */
+import {mkdtempSync, rmSync} from 'node:fs';
+import {join} from 'node:path';
+import {tmpdir} from 'node:os';
 import {expect} from 'chai';
 import sinon from 'sinon';
 import {Config} from '@oclif/core';
 import {OAuthCommand} from '@salesforce/b2c-tooling-sdk/cli';
 import {
   ImplicitOAuthStrategy,
   StatefulOAuthStrategy,
+  initializeStatefulStore,
   setStoredSession,
   clearStoredSession,
   resetStatefulStoreForTesting,
@@ -88,18 +92,20 @@ class TestOAuthCommandWithDefault extends OAuthCommand<typeof TestOAuthCommandWi
 describe('cli/oauth-command', () => {
   let config: Config;
   let command: TestOAuthCommand;
-  const originalEnv = process.env.NODE_ENV;
+  let testDir: string;
 
   before(() => {
-    process.env.NODE_ENV = 'test';
+    testDir = mkdtempSync(join(tmpdir(), 'b2c-oauth-cmd-test-'));
+    initializeStatefulStore(testDir);
   });
+
   after(() => {
-    process.env.NODE_ENV = originalEnv;
+    resetStatefulStoreForTesting();
+    rmSync(testDir, {recursive: true, force: true});
   });
 
   beforeEach(async () => {
     clearStoredSession();
-    resetStatefulStoreForTesting();
     isolateConfig();
     config = await Config.load();
     command = new TestOAuthCommand([], config);
@@ -109,7 +115,6 @@ describe('cli/oauth-command', () => {
     sinon.restore();
     restoreConfig();
     clearStoredSession();
-    resetStatefulStoreForTesting();
   });
 
   describe('requireOAuthCredentials', () => {