@payloadcms/figma 0.0.1-alpha.62 → 0.0.1-alpha.64

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

@@ -36,4 +36,15 @@ export declare function deriveEncryptionKey(): string;
  * without exposing the actual key.
  */
 export declare function getEncryptionKeyHash(): string;
+/**
+ * Write decrypted versions of all encrypted store files for debugging.
+ *
+ * For each .json file in the store directory, creates a neighboring .decrypted.json
+ * file containing the decrypted contents. Useful for debugging token storage issues.
+ *
+ * @param rootDir - Root directory of the token store (e.g., ~/Library/Preferences/payloadcms-figma-nodejs)
+ * @param encryptionKey - The encryption key used by Conf
+ * @returns Array of paths to decrypted files created
+ */
+export declare function exportDecryptedStoreFiles(rootDir: string, encryptionKey: string): string[];
 //# sourceMappingURL=crypto-utils.d.ts.map

package/dist/auth/crypto-utils.js

@@ -1,6 +1,8 @@
 import Conf from 'conf';
 import crypto from 'crypto';
+import fsSync from 'node:fs';
 import os from 'os';
+import path from 'path';
 /**
  * Get or generate a random salt for key derivation
  *
@@ -94,5 +96,54 @@ import os from 'os';
     const key = deriveEncryptionKey();
     return crypto.createHash('sha256').update(key).digest('hex').substring(0, 8);
 }
+/**
+ * Write decrypted versions of all encrypted store files for debugging.
+ *
+ * For each .json file in the store directory, creates a neighboring .decrypted.json
+ * file containing the decrypted contents. Useful for debugging token storage issues.
+ *
+ * @param rootDir - Root directory of the token store (e.g., ~/Library/Preferences/payloadcms-figma-nodejs)
+ * @param encryptionKey - The encryption key used by Conf
+ * @returns Array of paths to decrypted files created
+ */ export function exportDecryptedStoreFiles(rootDir, encryptionKey) {
+    const decryptedFiles = [];
+    function processDirectory(dir) {
+        if (!fsSync.existsSync(dir)) {
+            return;
+        }
+        const entries = fsSync.readdirSync(dir, {
+            withFileTypes: true
+        });
+        for (const entry of entries){
+            const fullPath = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                processDirectory(fullPath);
+            } else if (entry.name.endsWith('.json') && !entry.name.endsWith('.decrypted.json') && !entry.name.includes('.corrupt-')) {
+                try {
+                    // Extract configName from filename (remove .json extension)
+                    const configName = entry.name.replace(/\.json$/, '');
+                    // Create a Conf instance to read/decrypt the file
+                    const config = new Conf({
+                        clearInvalidConfig: false,
+                        configName,
+                        cwd: dir,
+                        encryptionKey,
+                        projectName: 'payloadcms-figma'
+                    });
+                    // Read all data from the store (Conf decrypts it)
+                    const data = config.store;
+                    // Write decrypted content to neighboring file
+                    const decryptedPath = fullPath.replace(/\.json$/, '.decrypted.json');
+                    fsSync.writeFileSync(decryptedPath, JSON.stringify(data, null, 2));
+                    decryptedFiles.push(decryptedPath);
+                } catch  {
+                // Skip files that can't be decrypted (e.g., crypto config, already unencrypted)
+                }
+            }
+        }
+    }
+    processDirectory(rootDir);
+    return decryptedFiles;
+}
 
 //# sourceMappingURL=crypto-utils.js.map

package/dist/auth/oauth-flow.js

@@ -147,15 +147,15 @@ import { exchangeCodeForTokens, refreshAccessToken, TokenRefreshError } from './
  * @throws OAuthFlowError if refresh fails
  */ export async function getValidOAuthAccessToken(tokenStore) {
     // Check if we have valid tokens
-    if (tokenStore.hasValidTokens()) {
-        const token = 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;
     }
@@ -195,6 +195,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

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,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,94 +59,179 @@ 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.
  *
- * @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) {
+ */ 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;
     }
-    // Check for existing valid project token
-    if (tokenStore.hasValidProjectToken(tenantId)) {
-        const projectToken = tokenStore.getProjectToken(tenantId);
-        return projectToken?.token || null;
+    const resolvedTenantId = tenantId ?? tokenStore.getTenantId({
+        projectInfo
+    });
+    if (!resolvedTenantId) {
+        throw new ProjectTokenError('tenantId was not provided and could not be resolved from bootstrap data');
     }
-    // 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 projectToken = await fetchProjectToken(credential, tenantId);
-    // 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(projectToken.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(projectToken.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;
+        }
+        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/token-store-migration.d.ts

@@ -0,0 +1,58 @@
+import type { BootstrapData, FigmaTokens, ProjectToken } from './types.js';
+export type LegacyStoreSchema = {
+    bootstrapData?: Record<string, BootstrapData>;
+    projectTokens?: Record<string, ProjectToken>;
+    tokens?: FigmaTokens;
+};
+export type MigrationCheckParams = {
+    checkFileExists?: (filePath: string) => boolean;
+    legacyFilePath: string;
+    newOAuthFilePath: string;
+};
+export type MigrateOAuthParams = {
+    encryptionKey: string;
+    legacyConfigName: string;
+    legacyCwd?: string;
+    newOAuthConfigName: string;
+    newOAuthCwd: string;
+    projectName: string;
+};
+/**
+ * Check if migration is needed.
+ * Returns true only when legacy file exists AND new oauth file does not.
+ */
+export declare function needsMigration(params: MigrationCheckParams): boolean;
+/**
+ * Migrate OAuth tokens from legacy store to new oauth store.
+ * Reads from legacy location, writes to new location with root-level keys.
+ *
+ * `clearInvalidConfig` is deliberately OFF so a transient decrypt error does
+ * not wipe the legacy file — older CLI versions elsewhere on disk still read
+ * it. If we cannot open the file, we log and skip migration.
+ */
+export declare function migrateOAuth(params: MigrateOAuthParams): void;
+export type ResolveProjectStorePath = (scope: {
+    environmentName: string;
+    projectId: string;
+}) => {
+    configName: string;
+    cwd: string;
+};
+export type MigrateProjectDataParams = {
+    encryptionKey: string;
+    legacyConfigName: string;
+    legacyCwd?: string;
+    projectName: string;
+    resolveProjectStorePath: ResolveProjectStorePath;
+};
+/**
+ * Migrate per-project bootstrap data and project tokens from the legacy
+ * combined store into individual per-project stores.
+ *
+ * Walks legacy `bootstrapData` (keyed by `projectId:environmentName`), writes
+ * each entry into its own project store file, and stashes the matching
+ * `projectToken` (looked up by `bootstrapData.contentSystemId`) alongside it.
+ * Target files that already exist are left alone.
+ */
+export declare function migrateProjectData(params: MigrateProjectDataParams): void;
+//# sourceMappingURL=token-store-migration.d.ts.map