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

[amit-kumar8-sf]

Summary

Adds stateful authentication to the B2C CLI, compatible with sfcc-ci's stored session mechanism. Tokens are persisted on disk and reused across CLI commands without re-authentication.

New commands:

• b2c auth client — Non-interactive auth via client_credentials or password grant, with optional --renew for auto-renewal
• b2c auth client renew — Refresh a stored token using refresh_token or client_credentials fallback
• b2c auth client token — Return the stored token (raw to stdout, or full metadata with --json)
• b2c auth login / b2c auth logout — Browser-based login/logout with session persistence

Stateful auth integration in existing commands:

• getOAuthStrategy() in OAuthCommand prefers a valid stored session over stateless auth
• Falls back to stateless when token is expired/invalid, client ID mismatches, required scopes are missing, or explicit stateless flags (--client-secret, --user-auth, --auth-methods) are passed
• Contextual warnings inform the user why stateful auth was skipped

Storage:

• Uses conf package with project name sfcc-ci, sharing the same keys (SFCC_CLIENT_ID, SFCC_CLIENT_TOKEN, SFCC_REFRESH_TOKEN, SFCC_CLIENT_RENEW_BASE, SFCC_USER) for cross-tool compatibility
• Token validation includes expiry check (with 60s buffer), scope matching, and client ID matching

No breaking changes: When no stateful session exists or it is expired, behavior is unchanged.

Testing

• Unit tests for stateful-store.ts: session CRUD, isStatefulTokenValid (expiry, scopes, client ID matching, invalid JWT)
• Unit tests for oauth-command.ts: stateful session preference, expired token warnings, explicit flag override, client ID matching passthrough
• Unit tests for CLI commands (auth client, auth client renew, auth client token): credential validation, grant type auto-detection, token storage, renewal flows, JSON/raw output, error handling
• Test helper updated with trace() on stubbed logger
• All tests use isolated conf store (sfcc-ci-test via NODE_ENV=test) to avoid interference with real user config

Dependencies

• No net-new third-party dependencies were added
• If net-new third-party dependencies were added, rationale/discussion is included and 3pl-approved is set by a maintainer

---

• Tests pass (pnpm test)
• Code is formatted (pnpm run format)

[clavery]

Hi @amit-kumar8-sf .

We definitely don't need the conf 3pl here. We should be implementing things the "oclif" way, using node filesystem APIs and plain JSON and storing the state in OCLIFs dataDir

Compatibility with sfcc-ci here doesn't mean it needs to be compatible with sfcc-cis storage (there's no reason folks would be using both tools at once). It just needs to be compatible with the pattern of storing the auth state on disk for future commands.

[amit-kumar8-sf]

SON and storing the state in OCLIFs dataDir

@clavery Sure, if it doesn't needs to align with the sfcc-ci storage, then I will get rid of the conf package completely and move everything under oclif's control. Will share the updated PR by EOD today.

[salesforce-cla]

Thanks for the contribution! Before we can merge this, we need @amit-kumar8-sf to sign the Salesforce Inc. Contributor License Agreement.

[clavery]

Looks good. Few nits:

• remove "sfcc-ci compatible store" from logging debug; just say "Using stateful session"
• if we can we should still dump the JWT payload like we do in the current trace log "JWT payload..." after we load from the store. if this is difficult don't bother. I see it's on the auth:login

[clavery]

Actually we should ensure that auth token command works for both auth login the client stateful auth.

We can have an alias for auth client token.

if this is the case already that's fine.

[amit-kumar8-sf]

Actually we should ensure that auth token command works for both auth login the client stateful auth.

We can have an alias for auth client token.

if this is the case already that's fine.

Yes, it is already there. 👍 I tested with both the commands auth token and auth client token during the development to ensure user has just one route to fetch out token without any confusion.

[amit-kumar8-sf]

Looks good. Few nits:

• remove "sfcc-ci compatible store" from logging debug; just say "Using stateful session"
• if we can we should still dump the JWT payload like we do in the current trace log "JWT payload..." after we load from the store. if this is difficult don't bother. I see it's on the auth:login

Updated the code as per comments above.