auth subcommand support

Author: clavery

packages/b2c-cli/package.json

@@ -63,6 +63,9 @@
     ],
     "topicSeparator": " ",
     "topics": {
+      "auth": {
+        "description": "Authentication and token management"
+      },
       "hello": {
         "description": "Say hello to the world and others"
       },

packages/b2c-cli/src/commands/auth/token.ts

@@ -0,0 +1,48 @@
+import {ux} from '@oclif/core';
+import {OAuthCommand} from '@salesforce/b2c-tooling/cli';
+import type {AccessTokenResponse} from '@salesforce/b2c-tooling/auth';
+import {t} from '../../i18n/index.js';
+
+/**
+ * JSON output structure for the token command
+ */
+interface TokenJsonOutput {
+  accessToken: string;
+  expires: string;
+  scopes: string[];
+}
+
+export default class AuthToken extends OAuthCommand<typeof AuthToken> {
+  static description = t('commands.auth.token.description', 'Get an OAuth access token');
+
+  static enableJsonFlag = true;
+
+  static examples = [
+    '<%= config.bin %> <%= command.id %>',
+    '<%= config.bin %> <%= command.id %> --scope sfcc.orders --scope sfcc.products',
+    '<%= config.bin %> <%= command.id %> --json',
+  ];
+
+  async run(): Promise<TokenJsonOutput> {
+    this.requireOAuthCredentials();
+
+    const strategy = this.getOAuthStrategy();
+    const tokenResponse: AccessTokenResponse = await strategy.getTokenResponse();
+
+    const output: TokenJsonOutput = {
+      accessToken: tokenResponse.accessToken,
+      expires: tokenResponse.expires.toISOString(),
+      scopes: tokenResponse.scopes,
+    };
+
+    // In JSON mode, return the full token response
+    if (this.jsonEnabled()) {
+      return output;
+    }
+
+    // In normal mode, output just the raw token to stdout
+    ux.stdout(tokenResponse.accessToken);
+
+    return output;
+  }
+}

packages/b2c-tooling/src/auth/oauth.ts

@@ -67,6 +67,31 @@ export class OAuthStrategy implements AuthStrategy {
     return decodeJWT(token);
   }
 
+  /**
+   * Gets the full token response including expiration and scopes.
+   * Useful for commands that need to display or return token metadata.
+   */
+  async getTokenResponse(): Promise<AccessTokenResponse> {
+    const logger = getLogger();
+    const cached = ACCESS_TOKEN_CACHE.get(this.config.clientId);
+
+    if (cached) {
+      const now = new Date();
+      const requiredScopes = this.config.scopes || [];
+      const hasAllScopes = requiredScopes.every((scope) => cached.scopes.includes(scope));
+
+      if (hasAllScopes && now.getTime() <= cached.expires.getTime()) {
+        logger.debug('Reusing cached access token');
+        return cached;
+      }
+    }
+
+    // Get new token via client credentials
+    const tokenResponse = await this.clientCredentialsGrant();
+    ACCESS_TOKEN_CACHE.set(this.config.clientId, tokenResponse);
+    return tokenResponse;
+  }
+
   /**
    * Invalidates the cached token, forcing re-authentication on next request
    */

packages/b2c-tooling/src/cli/oauth-command.ts

@@ -2,19 +2,18 @@ import {Command, Flags} from '@oclif/core';
 import {BaseCommand} from './base-command.js';
 import {loadConfig} from './config.js';
 import type {ResolvedConfig, LoadConfigOptions} from './config.js';
-import type {AuthStrategy} from '../auth/types.js';
 import {OAuthStrategy} from '../auth/oauth.js';
 import {t} from '../i18n/index.js';
 
 /**
  * Base command for operations requiring OAuth authentication.
- * Use this for platform-level operations like ODS/Sandbox API.
+ * Use this for platform-level operations like ODS, APIs.
  *
  * Environment variables:
  * - SFCC_CLIENT_ID: OAuth client ID
  * - SFCC_CLIENT_SECRET: OAuth client secret
  *
- * For B2C instance operations, use InstanceCommand instead.
+ * For B2C instance specific operations, use InstanceCommand instead.
  */
 export abstract class OAuthCommand<T extends typeof Command> extends BaseCommand<T> {
   static baseFlags = {
@@ -29,6 +28,12 @@ export abstract class OAuthCommand<T extends typeof Command> extends BaseCommand
       env: 'SFCC_CLIENT_SECRET',
       helpGroup: 'AUTH',
     }),
+    scope: Flags.string({
+      description: 'OAuth scopes to request (can be specified multiple times)',
+      env: 'SFCC_OAUTH_SCOPES',
+      multiple: true,
+      helpGroup: 'AUTH',
+    }),
   };
 
   protected override loadConfiguration(): ResolvedConfig {
@@ -42,13 +47,20 @@ export abstract class OAuthCommand<T extends typeof Command> extends BaseCommand
       clientSecret: this.flags['client-secret'],
     };
 
-    return loadConfig(flagConfig, options);
+    const config = loadConfig(flagConfig, options);
+
+    // Merge scopes from flags with config file scopes (flags take precedence if provided)
+    if (this.flags.scope && this.flags.scope.length > 0) {
+      config.scopes = this.flags.scope;
+    }
+
+    return config;
   }
 
   /**
    * Gets an OAuth auth strategy.
    */
-  protected getOAuthStrategy(): AuthStrategy {
+  protected getOAuthStrategy(): OAuthStrategy {
     const config = this.resolvedConfig;
 
     if (config.clientId && config.clientSecret) {