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

.changeset/stateful-auth.md

@@ -0,0 +1,35 @@
+---
+'@salesforce/b2c-cli': minor
+'@salesforce/b2c-tooling-sdk': minor
+---
+
+# Stateful authentication support
+
+Introduces stateful authentication commands and session management, enabling tokens to be persisted on disk and automatically reused across CLI commands — eliminating the need to pass credentials on every invocation.
+
+## New commands
+
+- **`auth login`** – Log in via browser (implicit OAuth) and persist the session for stateful user auth. Only the flags relevant to the implicit flow are exposed (`--client-id`, `--account-manager-host`, `--auth-scope`).
+- **`auth logout`** – Clear the stored session and return to stateless-only auth.
+- **`auth client`** – Authenticate an API client using `client_credentials` or `password` grant (non-interactive). Use `--renew` to store credentials for later token renewal.
+- **`auth client renew`** – Refresh the stored token using credentials saved with `--renew`. Supports `refresh_token` grant with automatic fallback to `client_credentials`.
+- **`auth client token`** – Return the current stored token: raw to stdout (pipe-friendly) or full metadata with `--json`.
+
+## Session storage
+
+Sessions are stored as a JSON file in the CLI's own data directory (e.g. `~/Library/Application Support/@salesforce/b2c-cli/auth-session.json` on macOS).
+
+> **Note:** Sessions stored by `sfcc-ci` are no longer shared with the CLI. Re-authenticate using `b2c auth login` or `b2c auth client` after upgrading.
+
+## Auth precedence
+
+When a valid stored session exists, all OAuth commands automatically use it — no flags required. The CLI falls back to stateless auth when:
+
+- The stored token is **expired or invalid** — a warning suggests the appropriate renewal command.
+- **Explicit stateless flags** are passed (`--client-secret`, `--user-auth`, or `--auth-methods`) — a warning lists the triggering flags.
+
+Passing `--client-id` alone does not force stateless auth; the stored session is used if the client ID matches.
+
+## No breaking change
+
+When no stateful session exists, behavior is identical to before (stateless auth). Existing environment variable and `dw.json` configuration continues to work without modification.

docs/cli/auth.md

@@ -6,6 +6,153 @@ description: Authentication commands for obtaining OAuth tokens and configuring
 
 Commands for authentication and token management.
 
+## Stateful vs stateless auth
+
+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 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.
+
+The stored session is used only when the token is valid and no explicit stateless auth flags are provided. The CLI falls back to stateless auth when the stored token is expired/invalid, or when `--client-secret`, `--user-auth`, or `--auth-methods` are passed on the command line. In both cases a warning is shown explaining why stateful auth was skipped. Note that `--client-id` alone does not force stateless; the stored session is used if the client ID matches. To opt out of stateful auth entirely, run `b2c auth logout` to clear the stored session.
+
+Use **auth:logout** to clear the stored session and return to stateless-only behavior.
+
+## b2c auth login
+
+Log in via browser (implicit OAuth) and save the session for stateful auth.
+
+### Usage
+
+```bash
+b2c auth login
+b2c auth login --client-id your-client-id
+```
+
+After a successful login, subsequent commands use the stored token until it expires or you run `b2c auth logout`.
+
+## b2c auth logout
+
+Clear the stored OAuth session (stateful auth). After logout, commands use stateless auth when configured.
+
+```bash
+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. 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.
+
+### Usage
+
+```bash
+# Client credentials grant (client ID + secret)
+b2c auth client --client-id <id> --client-secret <secret>
+
+# With auto-renewal enabled
+b2c auth client --client-id <id> --client-secret <secret> --renew
+
+# Resource owner password credentials grant (+ user credentials)
+b2c auth client --client-id <id> --client-secret <secret> --user <email> --user-password <pwd>
+
+# Force a specific grant type
+b2c auth client --client-id <id> --client-secret <secret> --grant-type client_credentials
+```
+
+### Flags
+
+| Flag | Environment Variable | Description |
+|------|---------------------|-------------|
+| `--client-id` | `SFCC_CLIENT_ID` | Client ID (required) |
+| `--client-secret` | `SFCC_CLIENT_SECRET` | Client secret (required) |
+| `--renew` / `-r` | | Enable auto-renewal (stores credentials for `auth client renew`) |
+| `--grant-type` / `-t` | | Force grant type: `client_credentials` or `password` |
+| `--user` | `SFCC_OAUTH_USER_NAME` | Username for password grant |
+| `--user-password` | `SFCC_OAUTH_USER_PASSWORD` | Password for password grant |
+| `--auth-scope` | `SFCC_OAUTH_SCOPES` | OAuth scopes to request |
+| `--account-manager-host` | `SFCC_ACCOUNT_MANAGER_HOST` | Account Manager hostname |
+
+### Grant type auto-detection
+
+If `--grant-type` is not specified:
+- **client_credentials** is used when only `--client-id` and `--client-secret` are provided
+- **password** is used when `--user` and `--user-password` are also provided
+
+### Examples
+
+```bash
+# Authenticate for automation (CI/CD)
+export SFCC_CLIENT_ID=my-client
+export SFCC_CLIENT_SECRET=my-secret
+b2c auth client
+
+# Authenticate with auto-renewal for long-running scripts
+b2c auth client --client-id <id> --client-secret <secret> --renew
+
+# Authenticate with user credentials
+b2c auth client --client-id <id> --client-secret <secret> \
+  --user admin@example.com --user-password secret123
+```
+
+## b2c auth client renew
+
+Renew the authentication token using stored credentials. Requires initial authentication with `--renew` flag.
+
+Uses `refresh_token` grant when a refresh token is stored, otherwise falls back to `client_credentials` grant.
+
+### Usage
+
+```bash
+b2c auth client renew
+```
+
+### Example
+
+```bash
+# Initial auth with --renew
+b2c auth client --client-id <id> --client-secret <secret> --renew
+
+# Later, renew the token without re-entering credentials
+b2c auth client renew
+```
+
+## b2c auth client token
+
+Return the current stored authentication token. Compatible with the [sfcc-ci `client:auth:token`](https://github.com/SalesforceCommerceCloud/sfcc-ci) workflow.
+
+### Usage
+
+```bash
+# Raw token to stdout (pipe-friendly)
+b2c auth client token
+
+# Full metadata as JSON
+b2c auth client token --json
+```
+
+### Output
+
+Raw token output (default):
+
+```
+eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
+```
+
+JSON output (`--json`):
+
+```json
+{
+  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "clientId": "my-client-id",
+  "expires": "2025-01-27T12:00:00.000Z",
+  "scopes": ["mail", "roles"],
+  "user": "admin@example.com",
+  "renewable": true
+}
+```
+
 ## b2c auth token
 
 Get an OAuth access token for use in scripts or other tools.

docs/guide/authentication.md

@@ -36,17 +36,31 @@ Most CLI operations require an Account Manager API Client. This is configured in
 
 ### Authentication Methods
 
-The CLI supports two authentication methods:
+The CLI supports four authentication methods:
 
-| Method                  | When Used                                                                        | Role Configuration                        |
-| ----------------------- | -------------------------------------------------------------------------------- | ----------------------------------------- |
-| **User Authentication** | When `--user-auth` is passed, or when only `--client-id` is provided (no secret) | Roles configured on your **user account** |
-| **Client Credentials**  | When both `--client-id` and `--client-secret` are provided                       | Roles configured on the **API client**    |
+| Method                             | When Used                                                                                      | Role Configuration                        |
+| ---------------------------------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------- |
+| **User Authentication**            | When `--user-auth` is passed, or when only `--client-id` is provided (no secret)               | Roles configured on your **user account** |
+| **Client Credentials**             | When both `--client-id` and `--client-secret` are provided                                     | Roles configured on the **API client**    |
+| **Stateful User Authentication**   | After running `b2c auth login` — browser-based login, token stored and reused                  | Roles configured on your **user account** |
+| **Stateful Client Authentication** | After running `b2c auth client` — client credentials login, token stored and reused            | Roles configured on the **API client**    |
 
 **User Authentication** opens a browser for interactive login and uses roles assigned to your user account. This is ideal for development and manual operations. Use `--user-auth` as a shorthand for `--auth-methods implicit` on any OAuth command.
 
 **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. 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. 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:
+- The stored token is **expired or invalid** — a warning suggests `b2c auth client renew` (if renewable) or `b2c auth client` / `b2c auth login` to re-authenticate.
+- **Explicit stateless auth flags** are passed (`--client-secret`, `--user-auth`, or `--auth-methods`) — a warning lists the flags that triggered the override. Remove them to use the stored session. Note that `--client-id` alone does not force stateless; the stored session is used if the client ID matches.
+
+To opt out of stateful auth entirely, run `b2c auth logout` to clear the stored session. The CLI will then use stateless auth exclusively.
+:::
+
 ::: tip
 For Account Manager operations that require user-level roles (organization and API client management), use `--user-auth` to authenticate with your user account. See [Account Manager Authentication](/cli/account-manager#authentication) for per-subtopic role requirements.
 :::