@payloadcms/figma 0.0.1-alpha.7 → 0.0.1-alpha.70

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

@@ -1,3 +1,4 @@
+import type { AuthCredential } from './credentials.js';
 import type { TokenStore } from './token-store.js';
 import type { FigmaTokens } from './types.js';
 /**
@@ -13,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 3000) */
+    /** 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;
@@ -55,8 +58,21 @@ export declare function executeOAuthFlow(tokenStore: TokenStore, options?: OAuth
  * refreshes using the refresh token. If no tokens exist, returns null.
  *
  * @param tokenStore - Token store to use
- * @returns Promise resolving to access token or null if no valid tokens
+ * @returns Promise resolving to AuthCredential (wrapped access token) or null if no valid tokens
  * @throws OAuthFlowError if refresh fails
  */
-export declare function getValidAccessToken(tokenStore: TokenStore): Promise<null | string>;
+export declare function getValidOAuthAccessToken(tokenStore: TokenStore): Promise<AuthCredential | null>;
+/**
+ * Get a valid auth credential, checking process.env for plan access token
+ * first before checking tokenStore for OAuth tokens.
+ * *
+ * @param tokenStore - Token store to use for OAuth tokens
+ * @returns Promise resolving to AuthCredential or null
+ */
+export declare function getValidCredential(tokenStore: TokenStore): Promise<AuthCredential | null>;
+/**
+ * Like getValidCredential but returns null instead of throwing on refresh failure.
+ * Use in commands that want to fall through to a login prompt on failure.
+ */
+export declare function tryGetCredential(tokenStore: TokenStore): Promise<AuthCredential | null>;
 //# sourceMappingURL=oauth-flow.d.ts.map

package/dist/auth/oauth-flow.js

@@ -1,11 +1,11 @@
 import * as p from '@clack/prompts';
 import crypto from 'crypto';
-import { OAUTH_CONFIG } 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';
 import { generatePKCEPair } from './pkce.js';
-import { exchangeCodeForTokens, refreshAccessToken } from './refresh.js';
+import { exchangeCodeForTokens, refreshAccessToken, TokenRefreshError } from './refresh.js';
 /**
  * Error during OAuth flow
  */ export class OAuthFlowError extends Error {
@@ -32,16 +32,17 @@ import { exchangeCodeForTokens, refreshAccessToken } from './refresh.js';
  * @throws OAuthFlowError if any step fails
  */ export async function executeOAuthFlow(tokenStore, options = {}) {
     // Check if OAuth flow should be mocked
-    // Default to true for OAuth (allow testing without real authentication by default)
-    const shouldMock = process.env.FIGMA_MOCK_OAUTH !== 'false';
+    // Default to false for OAuth
+    const shouldMock = process.env.FIGMA_MOCK_OAUTH === 'true';
+    const oauthConfig = getOAuthConfig();
     if (shouldMock) {
         // MOCK IMPLEMENTATION: Return mock tokens for testing
-        log.debug('Using mock OAuth flow (FIGMA_MOCK_OAUTH != "false")');
+        log.debug('Using mock OAuth flow (FIGMA_MOCK_OAUTH = true)');
         const mockTokens = {
             accessToken: 'figt_mock_access_token_' + crypto.randomBytes(16).toString('hex'),
             expiresAt: Date.now() + 2 * 60 * 60 * 1000,
             refreshToken: 'figt_mock_refresh_token_' + crypto.randomBytes(16).toString('hex'),
-            scopes: options.scopes || OAUTH_CONFIG.scopes,
+            scopes: options.scopes || oauthConfig.scopes,
             tokenType: 'Bearer'
         };
         // Store mock tokens
@@ -52,28 +53,30 @@ import { exchangeCodeForTokens, refreshAccessToken } from './refresh.js';
         };
     }
     // REAL OAUTH IMPLEMENTATION
-    const { clientId = OAUTH_CONFIG.clientId, port = 3000, redirectUri = OAUTH_CONFIG.redirectUri, scopes = OAUTH_CONFIG.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: OAUTH_CONFIG.authorizationUrl,
+            authorizationUrl: oauthConfig.authorizationUrl,
             clientId,
             codeChallenge,
             codeChallengeMethod,
@@ -84,7 +87,7 @@ import { exchangeCodeForTokens, refreshAccessToken } from './refresh.js';
         // Prompt user to open browser
         const shouldOpenBrowser = await p.confirm({
             initialValue: true,
-            message: 'Log in or create Figma account in your browser?'
+            message: 'Authenticate with Figma in your browser?'
         });
         if (p.isCancel(shouldOpenBrowser)) {
             throw new OAuthFlowError('Authentication cancelled by user');
@@ -142,28 +145,80 @@ import { exchangeCodeForTokens, refreshAccessToken } from './refresh.js';
  * refreshes using the refresh token. If no tokens exist, returns null.
  *
  * @param tokenStore - Token store to use
- * @returns Promise resolving to access token or null if no valid tokens
+ * @returns Promise resolving to AuthCredential (wrapped access token) or null if no valid tokens
  * @throws OAuthFlowError if refresh fails
- */ export async function getValidAccessToken(tokenStore) {
+ */ export async function getValidOAuthAccessToken(tokenStore) {
     // Check if we have valid tokens
-    if (tokenStore.hasValidTokens()) {
-        return tokenStore.getAccessToken();
+    if (tokenStore.hasValidOauthToken()) {
+        const token = tokenStore.getCurrentOauthToken();
+        return token ? {
+            type: 'oauth',
+            token
+        } : null;
     }
     // Check if we have a refresh token
-    const refreshToken = tokenStore.getRefreshToken();
+    const refreshToken = tokenStore.getCurrentRefreshToken();
     if (!refreshToken) {
         return null;
     }
-    // Try to refresh
+    // Try to refresh (with one retry for transient auth errors)
     try {
         const tokens = await refreshAccessToken(refreshToken);
         tokenStore.setTokens(tokens);
-        return tokens.accessToken;
+        return {
+            type: 'oauth',
+            token: tokens.accessToken
+        };
     } catch (error) {
-        // Refresh failed - clear invalid tokens
-        tokenStore.clearTokens();
+        const isAuthFailure = error instanceof TokenRefreshError && (error.statusCode === 401 || error.statusCode === 403 || error.statusCode === 400 && error.errorCode === 'invalid_grant');
+        if (isAuthFailure) {
+            // Retry once — a transient 401 (e.g. misconfigured proxy) shouldn't wipe tokens
+            try {
+                const tokens = await refreshAccessToken(refreshToken);
+                tokenStore.setTokens(tokens);
+                return {
+                    type: 'oauth',
+                    token: tokens.accessToken
+                };
+            } catch  {
+                // Retry also failed — token is genuinely revoked
+                tokenStore.clearTokens();
+            }
+        }
         throw new OAuthFlowError('Failed to refresh access token', error instanceof Error ? error : undefined);
     }
 }
+/**
+ * Get a valid auth credential, checking process.env for plan access token
+ * first before checking tokenStore for OAuth tokens.
+ * *
+ * @param tokenStore - Token store to use for OAuth tokens
+ * @returns Promise resolving to AuthCredential or null
+ */ 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
+        };
+    }
+    return getValidOAuthAccessToken(tokenStore);
+}
+/**
+ * Like getValidCredential but returns null instead of throwing on refresh failure.
+ * Use in commands that want to fall through to a login prompt on failure.
+ */ export async function tryGetCredential(tokenStore) {
+    try {
+        return await getValidCredential(tokenStore);
+    } catch  {
+        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

@@ -6,6 +6,7 @@
  * and have a shorter lifespan (15-30 minutes) than OAuth tokens.
  */
 import type { TokenStore } from './token-store.js';
+import type { ProjectStoreScope } from './types.js';
 /**
  * Error during project token operations
  */
@@ -13,35 +14,50 @@ 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.
  *
- * @param tokenStore - Token store for persisting tokens
- * @param tenantId - The tenant/CMS ID to get a token for
+ * @param params.tokenStore - Token store for persisting tokens
+ * @param params.tenantId - Optional tenant/CMS ID; resolved from stored bootstrap data when omitted
+ * @param params.projectInfo - Optional project scope (defaults to env vars)
  * @returns Promise resolving to JWT token string or null if failed
  * @throws {ProjectTokenError} If token generation fails
  */
-export declare function getValidProjectToken(tokenStore: TokenStore, tenantId: string): Promise<null | string>;
+export declare function getValidProjectToken({ projectInfo, tenantId, tokenStore, }: {
+    projectInfo?: ProjectStoreScope;
+    tenantId?: string;
+    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 tokenStore - Token store for persisting tokens
- * @param tenantId - The tenant/CMS ID to refresh token for
+ * @param params.tokenStore - Token store for persisting tokens
+ * @param params.tenantId - Optional tenant/CMS ID; resolved from stored bootstrap data when omitted
+ * @param params.projectInfo - Optional project scope (defaults to env vars)
  * @returns Promise resolving to JWT token string or null if failed
  * @throws {ProjectTokenError} If token refresh fails
  */
-export declare function refreshProjectToken(tokenStore: TokenStore, tenantId: string): Promise<null | string>;
+export declare function refreshProjectToken(params: {
+    projectInfo?: ProjectStoreScope;
+    tenantId?: string;
+    tokenStore: TokenStore;
+}): Promise<null | string>;
 //# sourceMappingURL=project-token.d.ts.map

package/dist/auth/project-token.js

@@ -5,10 +5,11 @@
  * 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 { getEnvironment } from '../constants.js';
+import { PROJECT_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';
-import { getValidAccessToken } from './oauth-flow.js';
+import { getValidCredential } from './oauth-flow.js';
 /**
  * Error during project token operations
  */ export class ProjectTokenError extends Error {
@@ -18,6 +19,21 @@ import { getValidAccessToken } 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 = PROJECT_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,89 +59,179 @@ import { getValidAccessToken } 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.
  *
- * @param tokenStore - Token store for persisting tokens
- * @param tenantId - The tenant/CMS ID to get a token for
+ * @param params.tokenStore - Token store for persisting tokens
+ * @param params.tenantId - Optional tenant/CMS ID; resolved from stored bootstrap data when omitted
+ * @param params.projectInfo - Optional project scope (defaults to env vars)
  * @returns Promise resolving to JWT token string or null if failed
  * @throws {ProjectTokenError} If token generation fails
- */ export async function getValidProjectToken(tokenStore, tenantId) {
-    // Check if we have a valid project token already
-    if (tokenStore.hasValidProjectToken(tenantId)) {
-        const projectToken = tokenStore.getProjectToken(tenantId);
-        return projectToken?.token || null;
+ */ export async function getValidProjectToken({ projectInfo, tenantId, tokenStore }) {
+    if (process.env.FIGMA_CONTENT_API_ACCESS_KEY) {
+        log.debug('FIGMA_CONTENT_API_ACCESS_KEY is set; skipping project token retrieval from API');
+        return null;
     }
-    // We need to refresh the project token
-    // First, get a valid user access token (will auto-refresh if needed)
-    let accessToken;
-    try {
-        accessToken = await getValidAccessToken(tokenStore);
-    } catch (error) {
-        throw new ProjectTokenError('Failed to get valid access token for project token refresh', error instanceof Error ? error : undefined);
+    const resolvedTenantId = tenantId ?? tokenStore.getTenantId({
+        projectInfo
+    });
+    if (!resolvedTenantId) {
+        throw new ProjectTokenError('tenantId was not provided and could not be resolved from bootstrap data');
     }
-    if (!accessToken) {
-        // No valid user tokens available - user needs to authenticate
-        return null;
+    const cacheKey = buildCacheKey({
+        projectInfo,
+        tenantId: resolvedTenantId
+    });
+    const cached = projectTokenCache.get(cacheKey);
+    if (cached && isCachedTokenValid(cached)) {
+        return cached.token;
     }
-    // Fetch a new project token from the Figma API
-    const projectToken = await fetchProjectToken(accessToken, tenantId);
-    // Validate the JWT signature and claims (skip for mocks)
-    const shouldMock = process.env.FIGMA_MOCK_PROJECT_TOKEN !== 'false';
-    let validatedClaims;
-    if (shouldMock) {
-        // MOCK: Skip JWT validation and parse claims directly
-        log.debug('Skipping JWT validation for mock project token');
-        validatedClaims = parseJWTClaims(projectToken.token);
-    } else {
-        // REAL: Validate JWT signature against JWKS
+    const inFlight = inFlightRefreshes.get(cacheKey);
+    if (inFlight) {
+        return inFlight;
+    }
+    // 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(projectToken.token, getEnvironment());
-        } 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;
+        }
+        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);
         }
     }
-    // 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(tenantId, {
-        claims: validatedClaims,
-        expiresAt: validatedClaims.exp * 1000,
-        tenantId,
-        token: projectToken.token
-    });
-    return projectToken.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 tokenStore - Token store for persisting tokens
- * @param tenantId - The tenant/CMS ID to refresh token for
+ * @param params.tokenStore - Token store for persisting tokens
+ * @param params.tenantId - Optional tenant/CMS ID; resolved from stored bootstrap data when omitted
+ * @param params.projectInfo - Optional project scope (defaults to env vars)
  * @returns Promise resolving to JWT token string or null if failed
  * @throws {ProjectTokenError} If token refresh fails
- */ export async function refreshProjectToken(tokenStore, tenantId) {
-    // Clear the existing project token to force a refresh
-    tokenStore.clearProjectToken(tenantId);
-    // Get a new token (which will fetch from API since we just cleared it)
-    return getValidProjectToken(tokenStore, tenantId);
+ */ export async function refreshProjectToken(params) {
+    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
+    });
+    return getValidProjectToken(params);
 }
 
 //# sourceMappingURL=project-token.js.map

package/dist/auth/refresh.d.ts

@@ -4,7 +4,8 @@ import type { FigmaTokens } from './types.js';
  */
 export declare class TokenRefreshError extends Error {
     statusCode?: number | undefined;
-    constructor(message: string, statusCode?: number | undefined);
+    errorCode?: string | undefined;
+    constructor(message: string, statusCode?: number | undefined, errorCode?: string | undefined);
 }
 /**
  * Refresh an expired OAuth2 access token using a refresh token