@salesforce/b2c-tooling-sdk 1.21.3 → 1.23.0

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;
+}

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

@@ -0,0 +1,579 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * SPDX-License-Identifier: Apache-2
+ * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import { createServer } from 'node:http';
+import { URL } from 'node:url';
+import { dispatchFetch } from './dispatch-fetch.js';
+import { getLogger } from '../logging/logger.js';
+import { decodeJWT } from './oauth.js';
+import { DEFAULT_ACCOUNT_MANAGER_HOST } from '../defaults.js';
+import { findAuthSession, saveAuthSession } from './session-store.js';
+const DEFAULT_LOCAL_PORT = 8080;
+const ACCESS_TOKEN_CACHE = new Map();
+const PENDING_AUTH = new Map();
+/**
+ * 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 class PkceGrantUnsupportedError extends Error {
+    /** The OAuth 2.0 `error` code from the authorize redirect or token response, when available. */
+    oauthError;
+    /** The OAuth stage at which the failure occurred. */
+    stage;
+    constructor(message, stage, oauthError) {
+        super(message);
+        this.name = 'PkceGrantUnsupportedError';
+        this.stage = stage;
+        this.oauthError = oauthError;
+    }
+}
+/**
+ * OAuth 2.0 `error` codes that genuinely indicate the client is not registered
+ * as a PKCE-capable public client — the only failures the implicit fallback can
+ * legitimately rescue. Implicit shares the same authorize endpoint and redirect
+ * URI but returns the token on the redirect with NO token-endpoint call and NO
+ * client authentication, so it rescues clients that support implicit but not
+ * the Authorization Code grant:
+ *
+ * - `invalid_client` — at the token exchange, Account Manager demands client
+ *   authentication (e.g. "Parameter client_assertion_type is missing"), i.e. the
+ *   client is confidential/implicit-only, NOT a public/PKCE client. This is the
+ *   primary real-world migration case for legacy implicit clients.
+ * - `unauthorized_client` — client is not permitted to use this grant type.
+ * - `unsupported_response_type` — authorize endpoint rejects `response_type=code`.
+ * - `unsupported_grant_type` — token endpoint rejects `authorization_code`.
+ *
+ * Every other error is a real failure that would fail identically under
+ * implicit and MUST NOT trigger the fallback, e.g. `invalid_scope` (bad
+ * scopes), `access_denied` (user cancelled consent), `invalid_grant`
+ * (expired/replayed code or PKCE verifier mismatch), `invalid_request`.
+ */
+const PKCE_GRANT_UNSUPPORTED_OAUTH_ERRORS = new Set([
+    'invalid_client',
+    'unauthorized_client',
+    'unsupported_response_type',
+    'unsupported_grant_type',
+]);
+/**
+ * Returns true only when an OAuth `error` code indicates the client cannot use
+ * the Authorization Code (PKCE) grant — the narrow set of failures the implicit
+ * fallback should rescue. Unknown/absent codes return false so ambiguous
+ * failures surface directly instead of silently downgrading to implicit.
+ */
+function isPkceGrantUnsupportedError(oauthError) {
+    return oauthError !== undefined && PKCE_GRANT_UNSUPPORTED_OAUTH_ERRORS.has(oauthError);
+}
+function base64url(buf) {
+    return buf.toString('base64').replace(/=+$/, '').replaceAll('+', '-').replaceAll('/', '_');
+}
+function generatePkcePair() {
+    const verifier = base64url(randomBytes(32));
+    const challenge = base64url(createHash('sha256').update(verifier).digest());
+    return { verifier, challenge };
+}
+function parseOAuthErrorBody(text) {
+    try {
+        const parsed = JSON.parse(text);
+        return {
+            error: typeof parsed.error === 'string' ? parsed.error : undefined,
+            errorDescription: typeof parsed.error_description === 'string' ? parsed.error_description : undefined,
+        };
+    }
+    catch {
+        return {};
+    }
+}
+async function openBrowserDefault(url) {
+    try {
+        const open = await import('open');
+        await open.default(url);
+    }
+    catch {
+        getLogger().debug('Could not automatically open browser');
+    }
+}
+/**
+ * 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 class PkceOAuthStrategy {
+    config;
+    accountManagerHost;
+    localPort;
+    redirectUri;
+    persistSession;
+    _hasHadSuccess = false;
+    _refreshToken = null;
+    _sub = '';
+    _hydrated = false;
+    constructor(config) {
+        this.config = config;
+        this.accountManagerHost = config.accountManagerHost || DEFAULT_ACCOUNT_MANAGER_HOST;
+        this.localPort = config.localPort || parseInt(process.env.SFCC_OAUTH_LOCAL_PORT || '', 10) || DEFAULT_LOCAL_PORT;
+        this.redirectUri = config.redirectUri || process.env.SFCC_REDIRECT_URI || `http://localhost:${this.localPort}`;
+        this.persistSession = config.persistSession !== false;
+        getLogger().debug({
+            clientId: this.config.clientId,
+            accountManagerHost: this.accountManagerHost,
+            port: this.localPort,
+            redirectUri: this.redirectUri,
+            persistSession: this.persistSession,
+        }, '[Auth] PkceOAuthStrategy initialized');
+    }
+    /**
+     * Load any persisted session for this clientId. Idempotent.
+     */
+    hydrate() {
+        if (!this.persistSession || this._hydrated)
+            return;
+        this._hydrated = true;
+        try {
+            const stored = findAuthSession(this.config.clientId);
+            if (!stored || stored.flow !== 'pkce')
+                return;
+            this._sub = stored.sub ?? '';
+            this._refreshToken = stored.refreshToken ?? null;
+            if (!ACCESS_TOKEN_CACHE.has(this.config.clientId) && stored.accessToken) {
+                const expires = stored.expiresAt ? new Date(stored.expiresAt) : new Date(0);
+                ACCESS_TOKEN_CACHE.set(this.config.clientId, {
+                    accessToken: stored.accessToken,
+                    expires,
+                    scopes: stored.scopes ?? [],
+                });
+            }
+            getLogger().debug({ clientId: this.config.clientId, sub: this._sub, hasRefresh: this._refreshToken !== null }, '[Auth] Hydrated PKCE session from store');
+        }
+        catch (error) {
+            getLogger().debug({ err: error }, '[Auth] PKCE store hydration failed');
+        }
+    }
+    async fetch(url, init = {}) {
+        const logger = getLogger();
+        const method = init.method || 'GET';
+        const token = await this.getAccessToken();
+        const headers = new Headers(init.headers);
+        headers.set('Authorization', `Bearer ${token}`);
+        headers.set('x-dw-client-id', this.config.clientId);
+        let res = await dispatchFetch(url, { ...init, headers });
+        logger.debug({ method, url, status: res.status }, '[Auth] Response');
+        if (res.status !== 401) {
+            this._hasHadSuccess = true;
+        }
+        if (res.status === 401 && this._hasHadSuccess) {
+            logger.debug('[Auth] Received 401, invalidating PKCE token and retrying');
+            this.invalidateToken();
+            const newToken = await this.getAccessToken();
+            headers.set('Authorization', `Bearer ${newToken}`);
+            res = await dispatchFetch(url, { ...init, headers });
+            logger.debug({ method, url, status: res.status }, '[Auth] Retry response');
+        }
+        return res;
+    }
+    async getAuthorizationHeader() {
+        const token = await this.getAccessToken();
+        return `Bearer ${token}`;
+    }
+    async getJWT() {
+        const token = await this.getAccessToken();
+        return decodeJWT(token);
+    }
+    async getTokenResponse() {
+        this.hydrate();
+        const cached = ACCESS_TOKEN_CACHE.get(this.config.clientId);
+        if (cached && this.isCachedTokenUsable(cached)) {
+            return cached;
+        }
+        if (this._refreshToken) {
+            const refreshed = await this.tryRefresh();
+            if (refreshed)
+                return refreshed;
+        }
+        const tokenResponse = await this.runFlow();
+        ACCESS_TOKEN_CACHE.set(this.config.clientId, tokenResponse);
+        return tokenResponse;
+    }
+    invalidateToken() {
+        // Only drop the cached access token. The refresh token is preserved so the
+        // next getAccessToken() can silently mint a new access token via
+        // tryRefresh() instead of re-opening the browser. tryRefresh() forgets the
+        // refresh token on its own when the exchange genuinely fails (revoked /
+        // expired), which is the only case where we fall back to the browser flow.
+        ACCESS_TOKEN_CACHE.delete(this.config.clientId);
+    }
+    isCachedTokenUsable(cached) {
+        const requiredScopes = this.config.scopes || [];
+        const hasAllScopes = requiredScopes.every((scope) => cached.scopes.includes(scope));
+        return hasAllScopes && Date.now() <= cached.expires.getTime();
+    }
+    async getAccessToken() {
+        this.hydrate();
+        const clientId = this.config.clientId;
+        const cached = ACCESS_TOKEN_CACHE.get(clientId);
+        if (cached && this.isCachedTokenUsable(cached)) {
+            return cached.accessToken;
+        }
+        if (cached) {
+            ACCESS_TOKEN_CACHE.delete(clientId);
+        }
+        const pending = PENDING_AUTH.get(clientId);
+        if (pending) {
+            const tokenResponse = await pending;
+            return tokenResponse.accessToken;
+        }
+        const authPromise = (async () => {
+            if (this._refreshToken) {
+                const refreshed = await this.tryRefresh();
+                if (refreshed)
+                    return refreshed;
+            }
+            return this.runFlow();
+        })();
+        PENDING_AUTH.set(clientId, authPromise);
+        try {
+            const tokenResponse = await authPromise;
+            ACCESS_TOKEN_CACHE.set(clientId, tokenResponse);
+            return tokenResponse.accessToken;
+        }
+        finally {
+            PENDING_AUTH.delete(clientId);
+        }
+    }
+    /**
+     * 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.
+     */
+    async tryRefresh() {
+        const logger = getLogger();
+        if (!this._refreshToken)
+            return null;
+        const tokenUrl = `https://${this.accountManagerHost}/dwsso/oauth2/access_token`;
+        const body = new URLSearchParams({
+            grant_type: 'refresh_token',
+            refresh_token: this._refreshToken,
+            client_id: this.config.clientId,
+        });
+        if (this.config.scopes && this.config.scopes.length > 0) {
+            body.set('scope', this.config.scopes.join(' '));
+        }
+        logger.debug({ method: 'POST', url: tokenUrl }, '[Auth REQ] POST /dwsso/oauth2/access_token (refresh_token)');
+        // refresh_token is a secret; trace only the non-sensitive parameters.
+        logger.trace({
+            method: 'POST',
+            url: tokenUrl,
+            body: { grant_type: 'refresh_token', client_id: this.config.clientId, scope: this.config.scopes?.join(' ') },
+        }, '[Auth REQ BODY] POST /dwsso/oauth2/access_token (refresh_token)');
+        let response;
+        try {
+            response = await dispatchFetch(tokenUrl, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+                body: body.toString(),
+            });
+        }
+        catch (error) {
+            logger.debug({ err: error }, '[Auth] PKCE refresh request failed');
+            this._refreshToken = null;
+            return null;
+        }
+        logger.debug({ url: tokenUrl, status: response.status }, `[Auth RESP] POST /dwsso/oauth2/access_token ${response.status}`);
+        if (!response.ok) {
+            const text = await response.text();
+            const oauthError = parseOAuthErrorBody(text);
+            logger.trace({ url: tokenUrl, status: response.status, body: oauthError }, '[Auth RESP BODY] POST /dwsso/oauth2/access_token (refresh_token)');
+            logger.debug({ status: response.status, oauthError: oauthError.error }, '[Auth] PKCE refresh failed; falling back to browser flow');
+            this._refreshToken = null;
+            return null;
+        }
+        let parsed;
+        try {
+            parsed = (await response.json());
+        }
+        catch (error) {
+            logger.debug({ err: error }, '[Auth] PKCE refresh returned non-JSON response');
+            this._refreshToken = null;
+            return null;
+        }
+        if (typeof parsed.access_token !== 'string' || parsed.access_token.length === 0) {
+            logger.debug('[Auth] PKCE refresh response did not contain an access token');
+            this._refreshToken = null;
+            return null;
+        }
+        const expiresIn = typeof parsed.expires_in === 'number' ? parsed.expires_in : 0;
+        const expires = new Date(Date.now() + expiresIn * 1000);
+        const scopes = typeof parsed.scope === 'string' ? parsed.scope.split(' ') : (this.config.scopes ?? []);
+        const tokenResponse = {
+            accessToken: parsed.access_token,
+            expires,
+            scopes,
+        };
+        if (typeof parsed.refresh_token === 'string' && parsed.refresh_token.length > 0) {
+            this._refreshToken = parsed.refresh_token;
+        }
+        try {
+            logger.trace({ jwt: decodeJWT(parsed.access_token).payload }, '[Auth] Refreshed PKCE access token JWT payload');
+        }
+        catch {
+            // access token is not a JWT; nothing to trace
+        }
+        this.persistTokens(tokenResponse);
+        logger.debug({ clientId: this.config.clientId }, '[Auth] PKCE token refreshed silently');
+        return tokenResponse;
+    }
+    /**
+     * 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.
+     */
+    persistTokens(tokenResponse) {
+        if (!this.persistSession)
+            return;
+        let sub = this._sub;
+        try {
+            const decoded = decodeJWT(tokenResponse.accessToken);
+            if (typeof decoded.payload.sub === 'string' && decoded.payload.sub.length > 0) {
+                sub = decoded.payload.sub;
+            }
+        }
+        catch {
+            // ignore — token may not be a JWT, fall back to existing _sub
+        }
+        this._sub = sub;
+        const record = {
+            clientId: this.config.clientId,
+            flow: 'pkce',
+            accessToken: tokenResponse.accessToken,
+            refreshToken: this._refreshToken,
+            sub,
+            expiresAt: tokenResponse.expires.toISOString(),
+            scopes: tokenResponse.scopes,
+            accountManagerHost: this.accountManagerHost,
+        };
+        try {
+            saveAuthSession(record);
+        }
+        catch (error) {
+            getLogger().debug({ err: error }, '[Auth] Failed to persist PKCE session');
+        }
+    }
+    async runFlow() {
+        const logger = getLogger();
+        logger.trace({ clientId: this.config.clientId, scopes: this.config.scopes, redirectUri: this.redirectUri }, '[Auth] Starting Authorization Code + PKCE flow');
+        const { verifier, challenge } = generatePkcePair();
+        const state = base64url(randomBytes(16));
+        // Verifier is a secret; trace only the derived challenge and state.
+        logger.trace({ codeChallenge: challenge, codeChallengeMethod: 'S256', state }, '[Auth] Generated PKCE challenge');
+        const params = new URLSearchParams({
+            client_id: this.config.clientId,
+            redirect_uri: this.redirectUri,
+            response_type: 'code',
+            code_challenge: challenge,
+            code_challenge_method: 'S256',
+            state,
+        });
+        if (this.config.scopes && this.config.scopes.length > 0) {
+            params.set('scope', this.config.scopes.join(' '));
+        }
+        const authorizeUrl = `https://${this.accountManagerHost}/dwsso/oauth2/authorize?${params.toString()}`;
+        logger.info({ url: authorizeUrl }, `Login URL: ${authorizeUrl}`);
+        logger.info('If the URL does not open automatically, copy/paste it into a browser on this machine.');
+        const code = await this.waitForAuthCode(state, async () => {
+            if (this.config.openBrowser) {
+                await this.config.openBrowser(authorizeUrl);
+            }
+            else {
+                await openBrowserDefault(authorizeUrl);
+            }
+        });
+        logger.debug({ codePrefix: code.slice(0, 8) }, '[Auth] Got authorization code, exchanging for token');
+        const tokenUrl = `https://${this.accountManagerHost}/dwsso/oauth2/access_token`;
+        const tokenBody = new URLSearchParams({
+            grant_type: 'authorization_code',
+            code,
+            redirect_uri: this.redirectUri,
+            client_id: this.config.clientId,
+            code_verifier: verifier,
+        });
+        logger.debug({ method: 'POST', url: tokenUrl }, '[Auth REQ] POST /dwsso/oauth2/access_token (authorization_code)');
+        // Redact the single-use code and PKCE verifier from the traced body.
+        logger.trace({
+            method: 'POST',
+            url: tokenUrl,
+            body: { grant_type: 'authorization_code', redirect_uri: this.redirectUri, client_id: this.config.clientId },
+        }, '[Auth REQ BODY] POST /dwsso/oauth2/access_token');
+        const tokenRes = await dispatchFetch(tokenUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: tokenBody.toString(),
+        });
+        const rawText = await tokenRes.text();
+        logger.debug({ url: tokenUrl, status: tokenRes.status }, `[Auth RESP] POST /dwsso/oauth2/access_token ${tokenRes.status}`);
+        if (!tokenRes.ok) {
+            // Distinguish "this client can't do the code grant" (which the implicit
+            // fallback can rescue) from real errors that would fail identically under
+            // implicit — e.g. invalid_scope, invalid_grant. Only the former is typed
+            // as PkceGrantUnsupportedError; everything else is a plain Error so the
+            // fallback wrapper propagates it instead of silently downgrading.
+            const errorBody = parseOAuthErrorBody(rawText);
+            const oauthError = errorBody.error;
+            logger.trace({ url: tokenUrl, status: tokenRes.status, body: errorBody }, '[Auth RESP BODY] POST /dwsso/oauth2/access_token');
+            const detail = errorBody.errorDescription ?? errorBody.error;
+            const message = `PKCE token exchange failed (${tokenRes.status})${detail ? `: ${detail}` : ''}`;
+            if (isPkceGrantUnsupportedError(oauthError)) {
+                throw new PkceGrantUnsupportedError(message, 'token', oauthError);
+            }
+            throw new Error(message);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(rawText);
+        }
+        catch {
+            // Do not echo an untrusted response body: a malformed success response
+            // can still contain live token material.
+            throw new Error('PKCE token exchange returned a non-JSON response');
+        }
+        if (typeof parsed.access_token !== 'string' || parsed.access_token.length === 0) {
+            throw new Error('PKCE token exchange response did not contain an access token');
+        }
+        // Never log the raw token response: it contains both the access token and
+        // the long-lived refresh token, and an opaque string bypasses pino's
+        // field-based redaction. JWT claims are traced below after decoding.
+        logger.trace({
+            url: tokenUrl,
+            status: tokenRes.status,
+            body: {
+                expires_in: parsed.expires_in,
+                scope: parsed.scope,
+                hasAccessToken: typeof parsed.access_token === 'string' && parsed.access_token.length > 0,
+                hasRefreshToken: typeof parsed.refresh_token === 'string' && parsed.refresh_token.length > 0,
+            },
+        }, '[Auth RESP BODY] POST /dwsso/oauth2/access_token');
+        const expiresIn = typeof parsed.expires_in === 'number' ? parsed.expires_in : 0;
+        const expires = new Date(Date.now() + expiresIn * 1000);
+        const scopes = typeof parsed.scope === 'string' ? parsed.scope.split(' ') : (this.config.scopes ?? []);
+        const tokenResponse = {
+            accessToken: parsed.access_token,
+            expires,
+            scopes,
+        };
+        if (typeof parsed.refresh_token === 'string' && parsed.refresh_token.length > 0) {
+            this._refreshToken = parsed.refresh_token;
+        }
+        logger.trace({ scopes, expires, hasRefreshToken: !!parsed.refresh_token }, '[Auth] PKCE token exchange succeeded');
+        try {
+            logger.trace({ jwt: decodeJWT(parsed.access_token).payload }, '[Auth] PKCE access token JWT payload');
+        }
+        catch {
+            // access token is not a JWT; nothing to trace
+        }
+        this.persistTokens(tokenResponse);
+        return tokenResponse;
+    }
+    waitForAuthCode(expectedState, openBrowser) {
+        const logger = getLogger();
+        return new Promise((resolve, reject) => {
+            const sockets = new Set();
+            let settled = false;
+            const settleAfterClose = (settle) => {
+                if (settled)
+                    return;
+                settled = true;
+                const forceCloseTimer = setTimeout(() => {
+                    for (const socket of sockets)
+                        socket.destroy();
+                }, 100);
+                server.close(() => {
+                    clearTimeout(forceCloseTimer);
+                    for (const socket of sockets)
+                        socket.destroy();
+                    settle();
+                });
+            };
+            const server = createServer((req, res) => {
+                const requestUrl = new URL(req.url || '/', `http://localhost:${this.localPort}`);
+                const code = requestUrl.searchParams.get('code');
+                const state = requestUrl.searchParams.get('state') ?? '';
+                const error = requestUrl.searchParams.get('error');
+                const errorDescription = requestUrl.searchParams.get('error_description');
+                if (error) {
+                    res.writeHead(500, { 'Content-Type': 'text/plain' });
+                    res.end(`Authentication failed: ${errorDescription ?? error}`);
+                    // Only a grant/registration error (e.g. unsupported_response_type,
+                    // unauthorized_client) means the client can't do the code grant — the
+                    // implicit fallback can rescue that. A user-driven error like
+                    // access_denied (cancelled consent) MUST NOT fall back, so type it
+                    // only for the grant-unsupported set; otherwise reject plainly.
+                    const message = `OAuth error: ${errorDescription ?? error}`;
+                    const authError = isPkceGrantUnsupportedError(error)
+                        ? new PkceGrantUnsupportedError(message, 'authorize', error)
+                        : new Error(message);
+                    settleAfterClose(() => reject(authError));
+                    return;
+                }
+                if (!code) {
+                    res.writeHead(404, { 'Content-Type': 'text/plain' });
+                    res.end('Waiting for authorization code...');
+                    return;
+                }
+                if (state !== expectedState) {
+                    res.writeHead(400, { 'Content-Type': 'text/plain' });
+                    res.end('State mismatch.');
+                    settleAfterClose(() => reject(new Error('OAuth state mismatch — aborting')));
+                    return;
+                }
+                res.writeHead(200, { 'Content-Type': 'text/plain' });
+                res.end('Authentication successful! You may close this browser window and return to your terminal.');
+                settleAfterClose(() => resolve(code));
+            });
+            server.on('connection', (socket) => {
+                sockets.add(socket);
+                socket.on('close', () => sockets.delete(socket));
+            });
+            server.listen(this.localPort, async () => {
+                logger.debug({ port: this.localPort }, `[Auth] PKCE redirect server listening on port ${this.localPort}`);
+                logger.info('Waiting for user to authenticate...');
+                try {
+                    await openBrowser();
+                }
+                catch (error) {
+                    const browserError = error instanceof Error ? error : new Error(String(error));
+                    settleAfterClose(() => reject(browserError));
+                }
+            });
+            server.on('error', (err) => {
+                const hint = 'code' in err && err.code === 'EADDRINUSE'
+                    ? ` Port ${this.localPort} is in use; set SFCC_OAUTH_LOCAL_PORT or pass localPort to use a different port.`
+                    : '';
+                if (!settled) {
+                    settled = true;
+                    reject(new Error(`Failed to start OAuth redirect server: ${err.message}.${hint}`));
+                }
+            });
+        });
+    }
+}
+//# sourceMappingURL=oauth-pkce.js.map