@payloadcms/figma 0.0.1-alpha.63 → 0.0.1-alpha.65

package/dist/auth/callback-server.d.ts

@@ -7,6 +7,14 @@ export interface CallbackResult {
     /** State parameter for CSRF verification */
     state: string;
 }
+export type CallbackServerOptions = {
+    /** Additional callback ports to try after port. */
+    fallbackPorts?: number[];
+    /** First callback port to try. Defaults to the configured callback port range. */
+    port?: number;
+    /** Callback timeout in milliseconds. */
+    timeoutMs?: number;
+};
 /**
  * Error from OAuth callback
  */
@@ -20,18 +28,18 @@ export declare class CallbackError extends Error {
  * Starts a temporary server on localhost to receive the OAuth authorization code.
  * The server automatically shuts down after receiving the callback or on timeout.
  *
- * Implements dynamic port allocation: tries preferred port first, falls back to
- * OS-assigned port if unavailable.
+ * Tries the registered localhost callback ports in order. It does not use an
+ * OS-assigned random port because OAuth redirect URIs must be registered.
  */
 export declare class CallbackServer {
     private actualPort?;
-    private preferredPort;
+    private callbackPorts;
+    private readyPromise;
+    private rejectReady?;
+    private resolveReady?;
     private server;
     private timeoutMs;
-    constructor(options?: {
-        port?: number;
-        timeoutMs?: number;
-    });
+    constructor(options?: CallbackServerOptions);
     /**
      * Render error page shown in browser when auth fails
      */
@@ -57,5 +65,9 @@ export declare class CallbackServer {
      * @throws CallbackError if callback fails or times out
      */
     waitForCallback(expectedState: string): Promise<CallbackResult>;
+    /**
+     * Wait until the callback server is listening.
+     */
+    waitUntilReady(): Promise<number>;
 }
 //# sourceMappingURL=callback-server.d.ts.map

package/dist/auth/callback-server.js

@@ -2,7 +2,7 @@ import { readFileSync } from 'fs';
 import { createServer } from 'http';
 import path from 'path';
 import { fileURLToPath } from 'url';
-import { DEFAULT_CALLBACK_PORT } from '../config/oauth.js';
+import { DEFAULT_CALLBACK_PORT, DEFAULT_CALLBACK_PORTS } from '../config/oauth.js';
 const filename = fileURLToPath(import.meta.url);
 const dirname = path.dirname(filename);
 /**
@@ -20,17 +20,19 @@ const dirname = path.dirname(filename);
  * Starts a temporary server on localhost to receive the OAuth authorization code.
  * The server automatically shuts down after receiving the callback or on timeout.
  *
- * Implements dynamic port allocation: tries preferred port first, falls back to
- * OS-assigned port if unavailable.
+ * Tries the registered localhost callback ports in order. It does not use an
+ * OS-assigned random port because OAuth redirect URIs must be registered.
  */ export class CallbackServer {
     actualPort;
-    preferredPort;
+    callbackPorts;
+    readyPromise = null;
+    rejectReady;
+    resolveReady;
     server = null;
     timeoutMs;
     constructor(options = {}){
-        this.preferredPort = options.port || DEFAULT_CALLBACK_PORT;
+        this.callbackPorts = resolveCallbackPorts(options);
         this.timeoutMs = options.timeoutMs || 120000; // 2 minutes default
-        this.server = createServer();
     }
     /**
    * Render error page shown in browser when auth fails
@@ -47,7 +49,7 @@ const dirname = path.dirname(filename);
    * Get the actual port the server is listening on
    * @returns Port number (may differ from preferred if that was in use)
    */ getActualPort() {
-        return this.actualPort || this.preferredPort;
+        return this.actualPort || this.callbackPorts[0];
     }
     /**
    * Stop the server if running
@@ -65,6 +67,17 @@ const dirname = path.dirname(filename);
    * @throws CallbackError if callback fails or times out
    */ async waitForCallback(expectedState) {
         return new Promise((resolve, reject)=>{
+            if (this.server) {
+                reject(new CallbackError('Callback server is already running', 'server_error'));
+                return;
+            }
+            this.readyPromise = new Promise((resolveReady, rejectReady)=>{
+                this.resolveReady = resolveReady;
+                this.rejectReady = rejectReady;
+            });
+            this.readyPromise.catch(()=>{
+            // The caller may only await waitForCallback(); avoid an unhandled rejection.
+            });
             const cleanup = (handle)=>{
                 clearTimeout(handle);
                 if (this.server) {
@@ -77,8 +90,7 @@ const dirname = path.dirname(filename);
                 cleanup(timeoutHandle);
                 reject(new CallbackError('OAuth authorization timed out. Please try again.', 'timeout'));
             }, this.timeoutMs);
-            // Create HTTP server
-            this.server = createServer((req, res)=>{
+            const handleRequest = (req, res)=>{
                 const url = new URL(req.url || '', `http://localhost:${this.getActualPort()}`);
                 // Only handle /callback path
                 if (url.pathname !== '/callback') {
@@ -134,36 +146,65 @@ const dirname = path.dirname(filename);
                     code,
                     state
                 });
-            });
-            // Try to start server with dynamic port allocation
-            const tryListen = (port, isRetry = false)=>{
-                if (!this.server) {
-                    reject(new CallbackError('Server instance is not available', 'server_error'));
-                    return;
-                }
-                this.server.listen(port, '127.0.0.1', ()=>{
+            };
+            // Try registered callback ports in order.
+            const tryListen = (portIndex)=>{
+                const port = this.callbackPorts[portIndex];
+                const server = createServer(handleRequest);
+                this.server = server;
+                server.once('error', (err)=>{
+                    if (this.server === server) {
+                        this.server = null;
+                    }
+                    if (err.code === 'EADDRINUSE' && portIndex < this.callbackPorts.length - 1) {
+                        tryListen(portIndex + 1);
+                        return;
+                    }
+                    cleanup(timeoutHandle);
+                    const callbackError = err.code === 'EADDRINUSE' ? new CallbackError(`OAuth callback ports are all in use: ${this.callbackPorts.join(', ')}. Close the process using one of these ports and run login again.`, 'ports_in_use') : new CallbackError(`Failed to start callback server: ${err.message}`, 'server_error');
+                    this.rejectReady?.(callbackError);
+                    reject(callbackError);
+                });
+                server.listen(port, '127.0.0.1', ()=>{
+                    if (this.server !== server) {
+                        return;
+                    }
                     // Capture the actual port that was assigned
-                    const addr = this.server.address();
+                    const addr = server.address();
                     if (addr && typeof addr === 'object') {
                         this.actualPort = addr.port;
-                    }
-                });
-                // Handle server errors (port in use, etc)
-                this.server.once('error', (err)=>{
-                    if (err.code === 'EADDRINUSE' && !isRetry) {
-                        // Port in use, try with OS-assigned port (0 = dynamic)
-                        this.server.removeAllListeners();
-                        tryListen(0, true);
-                    } else {
-                        cleanup(timeoutHandle);
-                        reject(new CallbackError(`Failed to start callback server: ${err.message}${!isRetry ? ' (tried fallback port)' : ''}`));
+                        this.resolveReady?.(addr.port);
                     }
                 });
             };
-            // Start with preferred port
-            tryListen(this.preferredPort);
+            // Start with first configured port
+            tryListen(0);
         });
     }
+    /**
+   * Wait until the callback server is listening.
+   */ waitUntilReady() {
+        if (!this.readyPromise) {
+            return Promise.reject(new CallbackError('Callback server has not started', 'server_error'));
+        }
+        return this.readyPromise;
+    }
+}
+function resolveCallbackPorts(options) {
+    if (!options.port && !options.fallbackPorts) {
+        return DEFAULT_CALLBACK_PORTS;
+    }
+    const primaryPort = options.port || DEFAULT_CALLBACK_PORT;
+    const ports = uniquePorts([
+        primaryPort,
+        ...options.fallbackPorts || []
+    ]).slice(0, DEFAULT_CALLBACK_PORTS.length);
+    return ports.length > 0 ? ports : DEFAULT_CALLBACK_PORTS;
+}
+function uniquePorts(ports) {
+    return [
+        ...new Set(ports)
+    ];
 }
 
 //# sourceMappingURL=callback-server.js.map

package/dist/auth/crypto-utils.d.ts

@@ -30,6 +30,17 @@
  * @throws Error if unable to derive key due to missing machine information
  */
 export declare function deriveEncryptionKey(): string;
+/**
+ * @deprecated Exists solely to read token stores written by older versions of
+ * this CLI that mixed `os.hostname()` into the encryption-key derivation. macOS
+ * rewrites the kernel hostname across DHCP/VPN/sleep events, which made those
+ * stores periodically un-decryptable. Used only by the transparent-migration
+ * path in `token-store.ts` and should be removed in a future release once
+ * upgraded clients are sufficiently common.
+ *
+ * @returns 64-character hex string (32-byte key) suitable for AES-256
+ */
+export declare function deriveLegacyEncryptionKey(): string;
 /**
  * Get a short hash of the encryption key for diagnostics.
  * Returns first 8 chars of SHA-256 hash — enough to compare across invocations

package/dist/auth/crypto-utils.js

@@ -36,7 +36,6 @@ import path from 'path';
  */ function gatherMachineEntropy() {
     try {
         const entropy = [
-            os.hostname(),
             os.homedir(),
             os.userInfo().username,
             os.platform(),
@@ -88,6 +87,28 @@ import path from 'path';
     const key = crypto.pbkdf2Sync(machineId, salt, 100000, 32, 'sha256');
     return key.toString('hex');
 }
+/**
+ * @deprecated Exists solely to read token stores written by older versions of
+ * this CLI that mixed `os.hostname()` into the encryption-key derivation. macOS
+ * rewrites the kernel hostname across DHCP/VPN/sleep events, which made those
+ * stores periodically un-decryptable. Used only by the transparent-migration
+ * path in `token-store.ts` and should be removed in a future release once
+ * upgraded clients are sufficiently common.
+ *
+ * @returns 64-character hex string (32-byte key) suitable for AES-256
+ */ export function deriveLegacyEncryptionKey() {
+    const entropy = [
+        os.hostname(),
+        os.homedir(),
+        os.userInfo().username,
+        os.platform(),
+        os.arch()
+    ];
+    const machineId = entropy.join('::');
+    const salt = getOrCreateSalt();
+    const key = crypto.pbkdf2Sync(machineId, salt, 100000, 32, 'sha256');
+    return key.toString('hex');
+}
 /**
  * Get a short hash of the encryption key for diagnostics.
  * Returns first 8 chars of SHA-256 hash — enough to compare across invocations

package/dist/auth/oauth-flow.d.ts

@@ -14,7 +14,9 @@ export declare class OAuthFlowError extends Error {
 export interface OAuthFlowOptions {
     /** OAuth2 client ID (defaults to config) */
     clientId?: string;
-    /** Callback server port (defaults to DEFAULT_CALLBACK_PORT) */
+    /** Callback server fallback ports to try after port */
+    fallbackPorts?: number[];
+    /** First callback server port to try */
     port?: number;
     /** Redirect URI (defaults to config) */
     redirectUri?: string;

package/dist/auth/oauth-flow.js

@@ -1,6 +1,6 @@
 import * as p from '@clack/prompts';
 import crypto from 'crypto';
-import { DEFAULT_CALLBACK_PORT, getOAuthConfig } from '../config/oauth.js';
+import { getOAuthConfig } from '../config/oauth.js';
 import * as log from '../utils/log.js';
 import { buildAuthorizationUrl, openBrowser } from './browser.js';
 import { CallbackServer } from './callback-server.js';
@@ -53,25 +53,27 @@ import { exchangeCodeForTokens, refreshAccessToken, TokenRefreshError } from './
         };
     }
     // REAL OAUTH IMPLEMENTATION
-    const { clientId = oauthConfig.clientId, port = DEFAULT_CALLBACK_PORT, redirectUri = oauthConfig.redirectUri, scopes = oauthConfig.scopes, timeoutMs = 120000 } = options;
+    const { clientId = oauthConfig.clientId, fallbackPorts, port, redirectUri = oauthConfig.redirectUri, scopes = oauthConfig.scopes, timeoutMs = 120000 } = options;
     // Generate PKCE pair for enhanced security
     const { codeChallenge, codeChallengeMethod, codeVerifier } = generatePKCEPair();
     // Generate random state for CSRF protection
     const state = crypto.randomBytes(32).toString('base64url');
     // Create callback server
     const callbackServer = new CallbackServer({
+        fallbackPorts,
         port,
         timeoutMs
     });
     try {
         // Start waiting for callback (this starts the server and captures actual port)
         const callbackPromise = callbackServer.waitForCallback(state);
-        // Wait a bit for server to start and determine actual port
-        await new Promise((resolve)=>setTimeout(resolve, 100));
+        callbackPromise.catch(()=>{
+        // The callback promise is awaited below; avoid an unhandled rejection if startup fails early.
+        });
         // Get the actual port (may differ from preferred if that was in use)
-        const actualPort = callbackServer.getActualPort();
+        const actualPort = await callbackServer.waitUntilReady();
         // Build redirect URI with actual port
-        const actualRedirectUri = redirectUri.replace(/:\d+/, `:${actualPort}`);
+        const actualRedirectUri = replaceRedirectUriPort(redirectUri, actualPort);
         // Build authorization URL
         const authUrl = buildAuthorizationUrl({
             authorizationUrl: oauthConfig.authorizationUrl,
@@ -195,6 +197,7 @@ import { exchangeCodeForTokens, refreshAccessToken, TokenRefreshError } from './
  */ export async function getValidCredential(tokenStore) {
     const envFigmaAccessToken = process.env.FIGMA_ACCESS_TOKEN;
     if (envFigmaAccessToken) {
+        log.debug('Using FIGMA_ACCESS_TOKEN env var override; skipping stored OAuth tokens');
         return {
             type: 'plan_access_token',
             token: envFigmaAccessToken
@@ -212,5 +215,10 @@ import { exchangeCodeForTokens, refreshAccessToken, TokenRefreshError } from './
         return null;
     }
 }
+function replaceRedirectUriPort(redirectUri, port) {
+    const url = new URL(redirectUri);
+    url.port = String(port);
+    return url.toString();
+}
 
 //# sourceMappingURL=oauth-flow.js.map

package/dist/auth/project-token.d.ts

@@ -14,15 +14,18 @@ export declare class ProjectTokenError extends Error {
     cause?: Error | undefined;
     constructor(message: string, cause?: Error | undefined);
 }
+/** Test-only: clears the in-memory token cache and any in-flight refresh promises. */
+export declare function __resetProjectTokenCacheForTests(): void;
 /**
- * Get a valid project token for a tenant, refreshing if necessary
+ * Get a valid project token for a tenant, refreshing if necessary.
  *
- * This function:
- * 1. Checks if a stored project token exists and is valid (not expired)
- * 2. If expired or missing, gets a valid user access token
- * 3. Calls the Figma API to generate a new project token
- * 4. Stores the new project token in encrypted storage
- * 5. Returns the JWT string
+ * Lookup order:
+ * 1. Module-level in-memory cache (no I/O on hits).
+ * 2. In-flight refresh map — concurrent callers with no cached entry share a single
+ *    refresh promise, so the project-token endpoint is only hit once per cache key.
+ * 3. Persisted (`conf`-backed) token store — picks up tokens minted by sibling processes.
+ * 4. Figma API — fetch + JWT validation, then write to both the persisted store and
+ *    the in-memory cache.
  *
  * The project token is used by local Payload instances to authenticate
  * requests to the Content API without requiring a round-trip to Sinatra.
@@ -39,10 +42,12 @@ export declare function getValidProjectToken({ projectInfo, tenantId, tokenStore
     tokenStore: TokenStore;
 }): Promise<null | string>;
 /**
- * Refresh a project token for a tenant
+ * Force-refresh a project token, bypassing all cache layers.
  *
- * Forces a refresh of the project token even if the current one is still valid.
- * Useful for testing or when you want to ensure you have the freshest token.
+ * Invalidates the in-memory cache entry, the in-flight refresh promise (so a
+ * concurrently-running refresh that may already be returning a soon-to-be-stale
+ * token is dropped from the dedup map), and the persisted token store. Then
+ * delegates to {@link getValidProjectToken} to mint a fresh token.
  *
  * @param params.tokenStore - Token store for persisting tokens
  * @param params.tenantId - Optional tenant/CMS ID; resolved from stored bootstrap data when omitted

package/dist/auth/project-token.js

@@ -5,6 +5,7 @@
  * to the Content API. Project tokens are scoped to a specific tenant/CMS
  * and have a shorter lifespan (15-30 minutes) than OAuth tokens.
  */ import { getProjectToken as fetchProjectToken } from '../api/figma-api.js';
+import { TOKEN_EXPIRY_BUFFER_SECONDS } from '../config/oauth.js';
 import { getInfraEnvironment } from '../constants.js';
 import * as log from '../utils/log.js';
 import { JWTValidationError, validateProjectToken } from './jwt-validator.js';
@@ -18,6 +19,21 @@ import { getValidCredential } from './oauth-flow.js';
         this.name = 'ProjectTokenError';
     }
 }
+const projectTokenCache = new Map();
+const inFlightRefreshes = new Map();
+function buildCacheKey(params) {
+    const projectId = params.projectInfo?.projectId ?? '';
+    const environmentName = params.projectInfo?.environmentName ?? '';
+    return `${params.tenantId}::${projectId}::${environmentName}`;
+}
+function isCachedTokenValid(entry) {
+    const bufferMs = TOKEN_EXPIRY_BUFFER_SECONDS * 1000;
+    return Date.now() < entry.expiresAt - bufferMs;
+}
+/** Test-only: clears the in-memory token cache and any in-flight refresh promises. */ export function __resetProjectTokenCacheForTests() {
+    projectTokenCache.clear();
+    inFlightRefreshes.clear();
+}
 /**
  * Parse JWT claims from token without validation
  * Used for mock tokens where signature validation is not needed
@@ -43,14 +59,15 @@ import { getValidCredential } from './oauth-flow.js';
     }
 }
 /**
- * Get a valid project token for a tenant, refreshing if necessary
+ * Get a valid project token for a tenant, refreshing if necessary.
  *
- * This function:
- * 1. Checks if a stored project token exists and is valid (not expired)
- * 2. If expired or missing, gets a valid user access token
- * 3. Calls the Figma API to generate a new project token
- * 4. Stores the new project token in encrypted storage
- * 5. Returns the JWT string
+ * Lookup order:
+ * 1. Module-level in-memory cache (no I/O on hits).
+ * 2. In-flight refresh map — concurrent callers with no cached entry share a single
+ *    refresh promise, so the project-token endpoint is only hit once per cache key.
+ * 3. Persisted (`conf`-backed) token store — picks up tokens minted by sibling processes.
+ * 4. Figma API — fetch + JWT validation, then write to both the persisted store and
+ *    the in-memory cache.
  *
  * The project token is used by local Payload instances to authenticate
  * requests to the Content API without requiring a round-trip to Sinatra.
@@ -71,70 +88,125 @@ import { getValidCredential } from './oauth-flow.js';
     if (!resolvedTenantId) {
         throw new ProjectTokenError('tenantId was not provided and could not be resolved from bootstrap data');
     }
-    // Check for existing valid project token
-    if (tokenStore.hasValidProjectToken({
-        projectInfo
-    })) {
-        const projectToken = tokenStore.getProjectToken({
-            projectInfo
-        });
-        return projectToken?.token || null;
-    }
-    // We need to refresh the project token
-    // An oauth access token is required for the call
-    let credential;
-    try {
-        credential = await getValidCredential(tokenStore);
-    } catch (error) {
-        throw new ProjectTokenError('Failed to get valid access token for project token refresh', error instanceof Error ? error : undefined);
+    const cacheKey = buildCacheKey({
+        projectInfo,
+        tenantId: resolvedTenantId
+    });
+    const cached = projectTokenCache.get(cacheKey);
+    if (cached && isCachedTokenValid(cached)) {
+        return cached.token;
     }
-    if (!credential) {
-        // No valid user tokens available - user needs to authenticate
-        return null;
+    const inFlight = inFlightRefreshes.get(cacheKey);
+    if (inFlight) {
+        return inFlight;
     }
-    // Fetch a new project token from the Figma API
-    const fetchedToken = await fetchProjectToken(credential, resolvedTenantId);
-    // Validate the JWT signature and claims (skip for mocks)
-    const hasEnvToken = !!process.env.FIGMA_MOCK_PROJECT_TOKEN_VALUE;
-    const shouldMock = process.env.FIGMA_MOCK_PROJECT_TOKEN !== 'false';
-    let validatedClaims;
-    if (hasEnvToken || shouldMock) {
-        // MOCK: Skip JWT validation and parse claims directly
-        log.debug('Skipping JWT validation for mock/env project token');
-        validatedClaims = parseJWTClaims(fetchedToken.token);
-    } else {
-        // REAL: Validate JWT signature against JWKS
+    // The IIFE references this holder so it can check whether it is still the
+    // active refresh before writing back to the caches. Without this guard a
+    // stale in-flight refresh could clobber a fresh token written by a later
+    // refresh (e.g. one triggered by `refreshProjectToken`).
+    const handle = {};
+    handle.promise = (async ()=>{
+        if (tokenStore.hasValidProjectToken({
+            projectInfo
+        })) {
+            const stored = tokenStore.getProjectToken({
+                projectInfo
+            });
+            if (stored?.token && inFlightRefreshes.get(cacheKey) === handle.promise) {
+                projectTokenCache.set(cacheKey, {
+                    expiresAt: stored.expiresAt,
+                    token: stored.token
+                });
+                return stored.token;
+            }
+            if (stored?.token) {
+                return stored.token;
+            }
+            // hasValidProjectToken said yes but getProjectToken returned no token —
+            // store was likely cleared by another process between calls. Fall through
+            // to fetch so the caller still gets a token.
+            log.warning(`Stored project token vanished between hasValidProjectToken and getProjectToken (cacheKey=${cacheKey}); re-fetching`);
+        }
+        let credential;
+        try {
+            credential = await getValidCredential(tokenStore);
+        } catch (error) {
+            throw new ProjectTokenError('Failed to get valid access token for project token refresh', error instanceof Error ? error : undefined);
+        }
+        if (!credential) {
+            return null;
+        }
+        let fetchedToken;
         try {
-            validatedClaims = await validateProjectToken(fetchedToken.token, getInfraEnvironment());
-        } catch (validationError) {
-            // Handle validation errors
-            if (validationError instanceof JWTValidationError) {
-                throw new ProjectTokenError(`Project token validation failed: ${validationError.message}`, validationError);
+            fetchedToken = await fetchProjectToken(credential, resolvedTenantId);
+        } catch (error) {
+            // Let API errors (e.g. FigmaApiError) propagate raw so callers can
+            // branch on status codes — but log context for debugging.
+            log.debug(`fetchProjectToken failed (cacheKey=${cacheKey}, tenantId=${resolvedTenantId}): ${error instanceof Error ? error.message : 'Unknown error'}`);
+            throw error;
+        }
+        const hasEnvToken = !!process.env.FIGMA_MOCK_PROJECT_TOKEN_VALUE;
+        const shouldMock = process.env.FIGMA_MOCK_PROJECT_TOKEN !== 'false';
+        let validatedClaims;
+        if (hasEnvToken || shouldMock) {
+            log.debug('Skipping JWT validation for mock/env project token');
+            validatedClaims = parseJWTClaims(fetchedToken.token);
+        } else {
+            try {
+                validatedClaims = await validateProjectToken(fetchedToken.token, getInfraEnvironment());
+            } catch (validationError) {
+                if (validationError instanceof JWTValidationError) {
+                    throw new ProjectTokenError(`Project token validation failed: ${validationError.message}`, validationError);
+                }
+                throw validationError;
             }
-            throw validationError;
         }
-    }
-    // Ensure exp claim is present
-    if (!validatedClaims.exp) {
-        throw new ProjectTokenError('Project token missing expiration (exp) claim');
-    }
-    // Store the project token with validated expiration and claims
-    tokenStore.setProjectToken({
-        projectInfo,
-        token: {
-            claims: validatedClaims,
-            expiresAt: validatedClaims.exp * 1000,
-            tenantId: resolvedTenantId,
+        if (typeof validatedClaims.exp !== 'number' || !Number.isFinite(validatedClaims.exp)) {
+            throw new ProjectTokenError('Project token missing or invalid expiration (exp) claim');
+        }
+        const expiresAt = validatedClaims.exp * 1000;
+        if (inFlightRefreshes.get(cacheKey) !== handle.promise) {
+            log.debug(`Project token refresh superseded; not persisting (cacheKey=${cacheKey})`);
+            return fetchedToken.token;
+        }
+        try {
+            tokenStore.setProjectToken({
+                projectInfo,
+                token: {
+                    claims: validatedClaims,
+                    expiresAt,
+                    tenantId: resolvedTenantId,
+                    token: fetchedToken.token
+                }
+            });
+        } catch (error) {
+            // Persistence is best-effort: a failure here (disk full, permissions,
+            // corrupt conf entry) shouldn't lose the freshly-minted token. Log and
+            // populate the in-memory cache so this process can still use it.
+            log.error(`Failed to persist project token to store (cacheKey=${cacheKey}): ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+        projectTokenCache.set(cacheKey, {
+            expiresAt,
             token: fetchedToken.token
+        });
+        return fetchedToken.token;
+    })();
+    inFlightRefreshes.set(cacheKey, handle.promise);
+    try {
+        return await handle.promise;
+    } finally{
+        if (inFlightRefreshes.get(cacheKey) === handle.promise) {
+            inFlightRefreshes.delete(cacheKey);
         }
-    });
-    return fetchedToken.token;
+    }
 }
 /**
- * Refresh a project token for a tenant
+ * Force-refresh a project token, bypassing all cache layers.
  *
- * Forces a refresh of the project token even if the current one is still valid.
- * Useful for testing or when you want to ensure you have the freshest token.
+ * Invalidates the in-memory cache entry, the in-flight refresh promise (so a
+ * concurrently-running refresh that may already be returning a soon-to-be-stale
+ * token is dropped from the dedup map), and the persisted token store. Then
+ * delegates to {@link getValidProjectToken} to mint a fresh token.
  *
  * @param params.tokenStore - Token store for persisting tokens
  * @param params.tenantId - Optional tenant/CMS ID; resolved from stored bootstrap data when omitted
@@ -142,12 +214,23 @@ import { getValidCredential } from './oauth-flow.js';
  * @returns Promise resolving to JWT token string or null if failed
  * @throws {ProjectTokenError} If token refresh fails
  */ export async function refreshProjectToken(params) {
-    const { projectInfo, tokenStore } = params;
-    // Clear the existing project token to force a refresh
+    const { projectInfo, tenantId, tokenStore } = params;
+    const resolvedTenantId = tenantId ?? tokenStore.getTenantId({
+        projectInfo
+    });
+    if (resolvedTenantId) {
+        const cacheKey = buildCacheKey({
+            projectInfo,
+            tenantId: resolvedTenantId
+        });
+        projectTokenCache.delete(cacheKey);
+        // Drop any in-flight refresh so getValidProjectToken below cannot return
+        // a soon-to-be-stale token via the dedup map.
+        inFlightRefreshes.delete(cacheKey);
+    }
     tokenStore.clearProjectToken({
         projectInfo
     });
-    // Get a new token (which will fetch from API since we just cleared it)
     return getValidProjectToken(params);
 }