@salesforce/b2c-tooling-sdk 1.21.2 → 1.22.0

package/dist/esm/auth/oauth-pkce-fallback.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Transitional auth strategy that prefers Authorization Code + PKCE but
+ * automatically falls back to the deprecated implicit flow when the configured
+ * Account Manager client is not (yet) registered for the PKCE grant.
+ *
+ * ## Why this exists
+ *
+ * Switching the default browser-based flow from implicit to PKCE requires a
+ * PKCE-capable "public client" in Account Manager. An AM client's type cannot be
+ * changed after creation, so a legacy implicit-only client must be replaced by a
+ * newly-created public client. Until that migration is complete, a user whose
+ * client is still implicit-only would hit a hard failure on the first request.
+ * This wrapper catches that specific failure ({@link PkceGrantUnsupportedError}),
+ * logs a deprecation WARN, and transparently retries with the implicit flow so
+ * those users keep working.
+ *
+ * ## Scope of the fallback
+ *
+ * The implicit flow uses the SAME authorize endpoint and redirect URI as PKCE,
+ * so this only rescues clients that are implicit-enabled but not PKCE-enabled.
+ * A client missing the redirect URI entirely fails under both flows — those
+ * users must fix their Account Manager registration.
+ *
+ * ## Removal
+ *
+ * This is a temporary migration aid. Once all public clients are PKCE-capable,
+ * delete this file, stop constructing it from {@link resolveAuthStrategy} /
+ * `getOAuthStrategy()`, and drop {@link PkceGrantUnsupportedError}. The
+ * {@link SFCC_DISABLE_PKCE_FALLBACK} env var can disable it in the meantime.
+ *
+ * @module auth/oauth-pkce-fallback
+ */
+import type { UserAuthStrategy, AccessTokenResponse, DecodedJWT, FetchInit } from './types.js';
+import { type PkceOAuthConfig } from './oauth-pkce.js';
+/**
+ * Returns true when the automatic PKCE→implicit fallback is disabled via the
+ * `SFCC_DISABLE_PKCE_FALLBACK` environment variable (any non-empty value).
+ */
+export declare function isPkceFallbackDisabled(): boolean;
+/**
+ * Wraps a {@link PkceOAuthStrategy} and, on a {@link PkceGrantUnsupportedError},
+ * falls back to an {@link ImplicitOAuthStrategy} for the same client. The
+ * fallback is attempted at most once and then sticks for the lifetime of this
+ * instance, so subsequent calls go straight to implicit without re-attempting
+ * the failing PKCE flow.
+ */
+export declare class PkceWithImplicitFallbackStrategy implements UserAuthStrategy {
+    private readonly config;
+    private readonly pkce;
+    private implicit;
+    /** Once PKCE has failed with a grant error, route everything to implicit. */
+    private useImplicit;
+    constructor(config: PkceOAuthConfig);
+    fetch(url: string, init?: FetchInit): Promise<Response>;
+    getAuthorizationHeader(): Promise<string>;
+    getJWT(): Promise<DecodedJWT>;
+    getTokenResponse(): Promise<AccessTokenResponse>;
+    invalidateToken(): void;
+    private warnAndSwitch;
+    private getImplicit;
+}
+/**
+ * Builds the browser-based "user" auth strategy. Returns a plain
+ * {@link PkceOAuthStrategy} when the fallback is disabled
+ * (`SFCC_DISABLE_PKCE_FALLBACK`), otherwise a
+ * {@link PkceWithImplicitFallbackStrategy}.
+ */
+export declare function createUserAuthStrategy(config: PkceOAuthConfig): UserAuthStrategy;

package/dist/esm/auth/oauth-pkce-fallback.js

@@ -0,0 +1,128 @@
+import { getLogger } from '../logging/logger.js';
+import { PkceOAuthStrategy, PkceGrantUnsupportedError } from './oauth-pkce.js';
+import { ImplicitOAuthStrategy } from './oauth-implicit.js';
+/**
+ * Returns true when the automatic PKCE→implicit fallback is disabled via the
+ * `SFCC_DISABLE_PKCE_FALLBACK` environment variable (any non-empty value).
+ */
+export function isPkceFallbackDisabled() {
+    const value = process.env.SFCC_DISABLE_PKCE_FALLBACK;
+    return value !== undefined && value !== '' && value !== '0' && value.toLowerCase() !== 'false';
+}
+/**
+ * Wraps a {@link PkceOAuthStrategy} and, on a {@link PkceGrantUnsupportedError},
+ * falls back to an {@link ImplicitOAuthStrategy} for the same client. The
+ * fallback is attempted at most once and then sticks for the lifetime of this
+ * instance, so subsequent calls go straight to implicit without re-attempting
+ * the failing PKCE flow.
+ */
+export class PkceWithImplicitFallbackStrategy {
+    config;
+    pkce;
+    implicit = null;
+    /** Once PKCE has failed with a grant error, route everything to implicit. */
+    useImplicit = false;
+    constructor(config) {
+        this.config = config;
+        this.pkce = new PkceOAuthStrategy(config);
+    }
+    async fetch(url, init = {}) {
+        if (this.useImplicit) {
+            return this.getImplicit().fetch(url, init);
+        }
+        try {
+            return await this.pkce.fetch(url, init);
+        }
+        catch (error) {
+            if (error instanceof PkceGrantUnsupportedError) {
+                this.warnAndSwitch(error);
+                return this.getImplicit().fetch(url, init);
+            }
+            throw error;
+        }
+    }
+    async getAuthorizationHeader() {
+        if (this.useImplicit) {
+            return this.getImplicit().getAuthorizationHeader();
+        }
+        try {
+            return await this.pkce.getAuthorizationHeader();
+        }
+        catch (error) {
+            if (error instanceof PkceGrantUnsupportedError) {
+                this.warnAndSwitch(error);
+                return this.getImplicit().getAuthorizationHeader();
+            }
+            throw error;
+        }
+    }
+    async getJWT() {
+        if (this.useImplicit) {
+            return this.getImplicit().getJWT();
+        }
+        try {
+            return await this.pkce.getJWT();
+        }
+        catch (error) {
+            if (error instanceof PkceGrantUnsupportedError) {
+                this.warnAndSwitch(error);
+                return this.getImplicit().getJWT();
+            }
+            throw error;
+        }
+    }
+    async getTokenResponse() {
+        if (this.useImplicit) {
+            return this.getImplicit().getTokenResponse();
+        }
+        try {
+            return await this.pkce.getTokenResponse();
+        }
+        catch (error) {
+            if (error instanceof PkceGrantUnsupportedError) {
+                this.warnAndSwitch(error);
+                return this.getImplicit().getTokenResponse();
+            }
+            throw error;
+        }
+    }
+    invalidateToken() {
+        this.pkce.invalidateToken();
+        this.implicit?.invalidateToken();
+    }
+    warnAndSwitch(error) {
+        this.useImplicit = true;
+        getLogger().warn({ clientId: this.config.clientId, stage: error.stage, oauthError: error.oauthError }, `[Auth] Authorization Code + PKCE failed for client ${this.config.clientId} ` +
+            `(${error.oauthError ?? error.message}). Falling back to the deprecated implicit flow. ` +
+            'Recommend creating a new public (PKCE) client in Account Manager and using it to remove this warning. ' +
+            'See https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/authentication.html#implicit-flow-deprecation');
+    }
+    getImplicit() {
+        if (!this.implicit) {
+            const implicitConfig = {
+                clientId: this.config.clientId,
+                scopes: this.config.scopes,
+                accountManagerHost: this.config.accountManagerHost,
+                localPort: this.config.localPort,
+                redirectUri: this.config.redirectUri,
+                openBrowser: this.config.openBrowser,
+                persistSession: this.config.persistSession,
+            };
+            this.implicit = new ImplicitOAuthStrategy(implicitConfig);
+        }
+        return this.implicit;
+    }
+}
+/**
+ * Builds the browser-based "user" auth strategy. Returns a plain
+ * {@link PkceOAuthStrategy} when the fallback is disabled
+ * (`SFCC_DISABLE_PKCE_FALLBACK`), otherwise a
+ * {@link PkceWithImplicitFallbackStrategy}.
+ */
+export function createUserAuthStrategy(config) {
+    if (isPkceFallbackDisabled()) {
+        return new PkceOAuthStrategy(config);
+    }
+    return new PkceWithImplicitFallbackStrategy(config);
+}
+//# sourceMappingURL=oauth-pkce-fallback.js.map

package/dist/esm/auth/oauth-pkce-fallback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-pkce-fallback.js","sourceRoot":"","sources":["../../../src/auth/oauth-pkce-fallback.ts"],"names":[],"mappings":"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"}

package/dist/esm/auth/oauth-pkce.d.ts

@@ -0,0 +1,94 @@
+import type { AuthStrategy, AccessTokenResponse, DecodedJWT, FetchInit } from './types.js';
+/**
+ * Thrown when the Authorization Code + PKCE flow fails in a way that indicates
+ * the Account Manager client is not registered for this grant (e.g. an old
+ * implicit-only public client, or a missing/mismatched redirect URI) rather
+ * than a transient or user-driven failure.
+ *
+ * {@link PkceWithImplicitFallbackStrategy} keys its automatic fallback off this
+ * type so it retries with the legacy implicit flow ONLY for grant/registration
+ * failures — never for user-cancel, state mismatch, or a port-in-use error.
+ *
+ * @remarks Part of the implicit→PKCE migration safety net. Remove together with
+ * the fallback strategy once all public clients are PKCE-capable.
+ */
+export declare class PkceGrantUnsupportedError extends Error {
+    /** The OAuth 2.0 `error` code from the authorize redirect or token response, when available. */
+    readonly oauthError?: string;
+    /** The OAuth stage at which the failure occurred. */
+    readonly stage: 'authorize' | 'token';
+    constructor(message: string, stage: 'authorize' | 'token', oauthError?: string);
+}
+/**
+ * Configuration for the OAuth Authorization Code + PKCE flow.
+ */
+export interface PkceOAuthConfig {
+    clientId: string;
+    scopes?: string[];
+    accountManagerHost?: string;
+    /** Local port for the redirect server (default 8080 or SFCC_OAUTH_LOCAL_PORT). */
+    localPort?: number;
+    /** Override redirect URI (default `http://localhost:${localPort}` or SFCC_REDIRECT_URI). */
+    redirectUri?: string;
+    /** Custom browser opener. Receives the authorization URL. */
+    openBrowser?: (url: string) => Promise<void>;
+    /**
+     * Persist tokens (access + refresh) to disk between CLI invocations,
+     * keyed by clientId. When a refresh token is available it is used to
+     * silently obtain a new access token instead of opening the browser.
+     * Defaults to `true`.
+     */
+    persistSession?: boolean;
+}
+/**
+ * OAuth 2.0 Authorization Code Flow with PKCE.
+ *
+ * Used for public clients (no client secret). Replaces the legacy implicit flow,
+ * which is deprecated for public clients per OAuth 2.1.
+ *
+ * Flow:
+ * 1. Generate PKCE verifier + S256 challenge.
+ * 2. Open browser to `/dwsso/oauth2/authorize?response_type=code&code_challenge=...`.
+ * 3. Capture redirect with `?code=...` on a localhost listener.
+ * 4. POST `grant_type=authorization_code` + `code_verifier` to `/dwsso/oauth2/access_token`.
+ *
+ * Tokens may include a refresh_token (depends on client registration in Account Manager).
+ */
+export declare class PkceOAuthStrategy implements AuthStrategy {
+    private config;
+    private accountManagerHost;
+    private localPort;
+    private redirectUri;
+    private persistSession;
+    private _hasHadSuccess;
+    private _refreshToken;
+    private _sub;
+    private _hydrated;
+    constructor(config: PkceOAuthConfig);
+    /**
+     * Load any persisted session for this clientId. Idempotent.
+     */
+    private hydrate;
+    fetch(url: string, init?: FetchInit): Promise<Response>;
+    getAuthorizationHeader(): Promise<string>;
+    getJWT(): Promise<DecodedJWT>;
+    getTokenResponse(): Promise<AccessTokenResponse>;
+    invalidateToken(): void;
+    private isCachedTokenUsable;
+    private getAccessToken;
+    /**
+     * Exchange a stored refresh_token for a new access token. Returns null if no
+     * refresh token is available or the exchange fails (e.g. revoked / expired).
+     * On failure, the refresh token is forgotten so the next request triggers
+     * the browser flow.
+     */
+    private tryRefresh;
+    /**
+     * Persist the current token + refresh token. No-op when `persistSession`
+     * is disabled. Updates `_sub` from the JWT when available so the persisted
+     * record carries the authenticated user identity for diagnostics.
+     */
+    private persistTokens;
+    private runFlow;
+    private waitForAuthCode;
+}