@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.

[clavery]

Can we make client ID a positional argument rather than using the flag (flag is fine too but positional aligns with existing sfcc-ci conventions so folks will be more comfortable)

[amit-kumar8-sf]

Thanks @clavery 😄
I can update it to a positional argument, but existing b2c auth token and b2c scapi custom status commands make use of the attributes --client-id and --client-secret. Should I make the change in those commands as well?

My only motivation here is to have it same across the board to avoid any confusion for the developers.

[clavery]

No the flags should remain the same. Only this one command should also support a positional and it should take precedence over existing client-id configuration AND should not set a client secret. auth:login in sfcc-ci forces an implicit auth and we need to do that here using the explicit positional

[amit-kumar8-sf]

Updated to take it as a positional argument.

[salesforce-cla]

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