@payloadcms/figma 0.0.1-alpha.9 → 0.1.0-alpha.1

package/dist/api/figma-api.js

@@ -3,7 +3,10 @@
  *
  * Client for Figma REST API (Pixie) endpoints
  * Handles project token generation and other CMS-related API calls
- */ import * as log from '../utils/log.js';
+ */ import { getAuthHeaders } from '../auth/credentials.js';
+import { getEnvConfig } from '../constants.js';
+import * as log from '../utils/log.js';
+import { parseControlPlaneApiError } from './error-response.js';
 /**
  * Error thrown when Figma API calls fail
  */ export class FigmaApiError extends Error {
@@ -14,19 +17,6 @@
         this.name = 'FigmaApiError';
     }
 }
-/**
- * Base URLs for Figma API
- */ const API_BASE_URLS = {
-    prod: 'https://api.figma.com',
-    staging: 'https://api.staging.figma.com'
-};
-/**
- * Get the Figma API base URL based on environment
- * TODO: Use this once real API endpoints are available
- */ function _getApiBaseUrl() {
-    // For now, default to staging to match OAuth config
-    return process.env.FIGMA_API_BASE_URL || API_BASE_URLS.staging;
-}
 /**
  * Get a project token (JWT) for a specific tenant/CMS
  *
@@ -34,21 +24,49 @@
  * requests to the Content API. The token contains the CMS ID and
  * user identifying information in its claims.
  *
- * Endpoint: GET https://api.figma.com/v1/cms/:id/token/
+ * Endpoint: POST https://api.figma.com/v1/cms/content-systems/:id/token/
  *
  * @param accessToken - OAuth access token for authentication
  * @param tenantId - The tenant/CMS ID
  * @returns ProjectToken with JWT and expiry information
  * @throws {FigmaApiError} If the API call fails
- */ export async function getProjectToken(accessToken, tenantId) {
-    // Check if project token API should be mocked
+ */ export async function getProjectToken(credential, tenantId) {
+    // Priority 1: Check for direct token value from environment
+    const envTokenValue = process.env.FIGMA_MOCK_PROJECT_TOKEN_VALUE;
+    if (envTokenValue) {
+        log.debug('Using direct project token from FIGMA_MOCK_PROJECT_TOKEN_VALUE');
+        try {
+            // Parse JWT payload to extract claims
+            const parts = envTokenValue.split('.');
+            if (parts.length !== 3) {
+                throw new Error('Invalid JWT format: must have 3 parts (header.payload.signature)');
+            }
+            const payload = parts[1];
+            const base64 = payload.replace(/-/g, '+').replace(/_/g, '/');
+            const paddedBase64 = base64.padEnd(base64.length + (4 - base64.length % 4) % 4, '=');
+            const decodedPayload = JSON.parse(Buffer.from(paddedBase64, 'base64').toString('utf-8'));
+            if (!decodedPayload.exp || typeof decodedPayload.exp !== 'number') {
+                throw new Error('JWT payload missing exp claim');
+            }
+            // Extract tenant ID from aud claim (use parameter as fallback)
+            const extractedTenantId = decodedPayload.aud || tenantId;
+            return {
+                expiresAt: decodedPayload.exp * 1000,
+                tenantId: extractedTenantId,
+                token: envTokenValue
+            };
+        } catch (error) {
+            throw new FigmaApiError(`Invalid JWT token in FIGMA_MOCK_PROJECT_TOKEN_VALUE: ${error instanceof Error ? error.message : 'Unknown error'}`, undefined, error instanceof Error ? error : undefined);
+        }
+    }
+    // Priority 2: Check if project token API should be mocked
     // Default to false (use real API)
     const shouldMock = process.env.FIGMA_MOCK_PROJECT_TOKEN === 'true';
     try {
         if (shouldMock) {
             // MOCK IMPLEMENTATION: Generate a mock JWT token for testing
             log.debug('Using mock project token API for getProjectToken (FIGMA_MOCK_PROJECT_TOKEN = "true")');
-            const mockToken = createMockJWT(tenantId, 25) // 25 minutes expiry
+            const mockToken = createMockJWT(`csid_${tenantId}`, 25) // 25 minutes expiry
             ;
             // Mock response data
             const data = {
@@ -68,24 +86,20 @@
             };
         }
         // REAL API IMPLEMENTATION
-        const baseUrl = _getApiBaseUrl();
-        const url = `${baseUrl}/v1/cms/${tenantId}/token/`;
+        const baseUrl = getEnvConfig().apiBaseUrl;
+        const url = `${baseUrl}/v1/cms/content-systems/${tenantId}/token/`;
         const response = await fetch(url, {
-            headers: {
-                Authorization: `Bearer ${accessToken}`
-            },
+            headers: getAuthHeaders(credential),
             method: 'POST'
         });
         if (!response.ok) {
-            // Handle error responses
-            let errorMessage = `Failed to get project token: ${response.status} ${response.statusText}`;
-            try {
-                const errorBody = await response.json();
-                if (errorBody.error || errorBody.message) {
-                    errorMessage = errorBody.error || errorBody.message;
-                }
-            } catch  {
-            // Ignore JSON parse errors for error body
+            let errorMessage = await parseControlPlaneApiError({
+                context: 'get project token',
+                response
+            });
+            // Provide an actionable error for the common misconfiguration case.
+            if (response.status === 404) {
+                errorMessage = `Content System ID "${tenantId}" not found. Ensure FIGMA_CONTENT_API_CONTENT_SYSTEM_ID is set to a valid content system ID in your .env file.`;
             }
             throw new FigmaApiError(errorMessage, response.status);
         }
@@ -108,6 +122,36 @@
         throw new FigmaApiError(`Failed to get project token: ${error instanceof Error ? error.message : 'Unknown error'}`, undefined, error instanceof Error ? error : undefined);
     }
 }
+export async function getPayloadAdminToken(credential, environmentId) {
+    if (process.env.FIGMA_MOCK_PROJECT_TOKEN === 'true') {
+        const token = createMockJWT(`eid_${environmentId}`, 25);
+        return {
+            expiresAt: parseJwtExpiry(token),
+            tenantId: environmentId,
+            token
+        };
+    }
+    const baseUrl = getEnvConfig().apiBaseUrl;
+    const response = await fetch(`${baseUrl}/v1/cms/environments/${environmentId}/admin-token`, {
+        headers: getAuthHeaders(credential),
+        method: 'POST'
+    });
+    if (!response.ok) {
+        throw new FigmaApiError(await parseControlPlaneApiError({
+            context: 'get Payload Admin token',
+            response
+        }), response.status);
+    }
+    const data = await response.json();
+    if (!data.meta?.token) {
+        throw new FigmaApiError('Invalid response: missing token in meta');
+    }
+    return {
+        expiresAt: parseJwtExpiry(data.meta.token),
+        tenantId: environmentId,
+        token: data.meta.token
+    };
+}
 /**
  * Create a mock JWT token for testing
  * TODO: Remove this when real API is available
@@ -165,5 +209,37 @@
         throw new FigmaApiError(`Failed to parse JWT expiry: ${error instanceof Error ? error.message : 'Unknown error'}`, undefined, error instanceof Error ? error : undefined);
     }
 }
-
-//# sourceMappingURL=figma-api.js.map
+/**
+ * Get user info from Figma API
+ *
+ * Endpoint: GET https://api.figma.com/v1/me
+ * Requires OAuth access_token (not project token)
+ *
+ * @param accessToken - OAuth access token for authentication
+ * @returns FigmaUserInfo with user profile data
+ * @throws {FigmaApiError} If the API call fails
+ */ export async function getUserInfo(credential) {
+    const baseUrl = getEnvConfig().apiBaseUrl;
+    const url = `${baseUrl}/v1/me`;
+    try {
+        const response = await fetch(url, {
+            headers: getAuthHeaders(credential)
+        });
+        if (!response.ok) {
+            throw new FigmaApiError(await parseControlPlaneApiError({
+                context: 'get user info',
+                response
+            }), response.status);
+        }
+        const data = await response.json();
+        if (!data.id || !data.email || typeof data.handle !== 'string') {
+            throw new FigmaApiError('Invalid user info response: missing required fields');
+        }
+        return data;
+    } catch (error) {
+        if (error instanceof FigmaApiError) {
+            throw error;
+        }
+        throw new FigmaApiError(`Failed to get user info: ${error instanceof Error ? error.message : 'Unknown error'}`, undefined, error instanceof Error ? error : undefined);
+    }
+}

package/dist/auth/browser.d.ts

@@ -28,4 +28,3 @@ export declare function buildAuthorizationUrl(params: {
     scopes: string[];
     state: string;
 }): string;
-//# sourceMappingURL=browser.d.ts.map

package/dist/auth/browser.js

@@ -37,5 +37,3 @@ import open from 'open';
     url.searchParams.set('code_challenge_method', params.codeChallengeMethod);
     return url.toString();
 }
-
-//# sourceMappingURL=browser.js.map

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,8 @@ 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,6 +2,7 @@ import { readFileSync } from 'fs';
 import { createServer } from 'http';
 import path from 'path';
 import { fileURLToPath } from 'url';
+import { DEFAULT_CALLBACK_PORT, DEFAULT_CALLBACK_PORTS } from '../config/oauth.js';
 const filename = fileURLToPath(import.meta.url);
 const dirname = path.dirname(filename);
 /**
@@ -19,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 || 3000;
+        this.callbackPorts = resolveCallbackPorts(options);
         this.timeoutMs = options.timeoutMs || 120000; // 2 minutes default
-        this.server = createServer();
     }
     /**
    * Render error page shown in browser when auth fails
@@ -46,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
@@ -64,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) {
@@ -76,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') {
@@ -133,36 +146,63 @@ 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/credentials.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Auth Access Tokens types for CLI authentication
+ *
+ * Distinguishes between OAuth tokens (Authorization: Bearer) and
+ * Plan Access Tokens (X-Figma-Token header).
+ */
+/**
+ * Represents an authenticated credential — either OAuth or PAT
+ */
+export type AuthCredential = {
+    token: string;
+    type: 'oauth';
+} | {
+    token: string;
+    type: 'plan_access_token';
+};
+/**
+ * Build the correct auth headers for a credential
+ */
+export declare function getAuthHeaders(credential: AuthCredential): Record<string, string>;

package/dist/auth/credentials.js

@@ -0,0 +1,19 @@
+/**
+ * Auth Access Tokens types for CLI authentication
+ *
+ * Distinguishes between OAuth tokens (Authorization: Bearer) and
+ * Plan Access Tokens (X-Figma-Token header).
+ */ /**
+ * Represents an authenticated credential — either OAuth or PAT
+ */ /**
+ * Build the correct auth headers for a credential
+ */ export function getAuthHeaders(credential) {
+    if (credential.type === 'plan_access_token') {
+        return {
+            'X-Figma-Token': credential.token
+        };
+    }
+    return {
+        Authorization: `Bearer ${credential.token}`
+    };
+}

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

@@ -30,4 +30,31 @@
  * @throws Error if unable to derive key due to missing machine information
  */
 export declare function deriveEncryptionKey(): string;
-//# sourceMappingURL=crypto-utils.d.ts.map
+/**
+ * @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
+ * 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[];

package/dist/auth/crypto-utils.js

@@ -1,11 +1,9 @@
 import Conf from 'conf';
 import crypto from 'crypto';
+import envPaths from 'env-paths';
+import fsSync from 'node:fs';
 import os from 'os';
-// Configuration store for cryptographic salt
-const cryptoConf = new Conf({
-    configName: 'payloadcms-figma-crypto',
-    projectName: 'payloadcms-figma'
-});
+import path from 'path';
 /**
  * Get or generate a random salt for key derivation
  *
@@ -13,15 +11,56 @@ const cryptoConf = new Conf({
  * for future use. This ensures the encryption key is unique per machine and not
  * reproducible even if machine identifiers are known.
  *
+ * Uses an atomic create-or-read pattern (O_EXCL via `flag: 'wx'`) so concurrent
+ * callers — e.g. parallel vitest workers on a fresh CI container — converge on
+ * the same salt instead of clobbering each other's writes. Once the file
+ * exists, no caller ever overwrites it.
+ *
  * @returns 32-byte hex string (64 characters)
  */ function getOrCreateSalt() {
-    let salt = cryptoConf.get('salt');
-    if (!salt) {
-        // Generate cryptographically secure random salt (32 bytes = 256 bits)
-        salt = crypto.randomBytes(32).toString('hex');
-        cryptoConf.set('salt', salt);
+    // Path mirrors what `Conf({ projectName: 'payloadcms-figma', configName:
+    // 'payloadcms-figma-crypto' })` would produce, so files written by older
+    // versions remain readable.
+    const configDir = envPaths('payloadcms-figma', {
+        suffix: 'nodejs'
+    }).config;
+    const configPath = path.join(configDir, 'payloadcms-figma-crypto.json');
+    const readSalt = ()=>{
+        try {
+            const parsed = JSON.parse(fsSync.readFileSync(configPath, 'utf8'));
+            return typeof parsed.salt === 'string' && parsed.salt.length > 0 ? parsed.salt : undefined;
+        } catch (err) {
+            if (err.code === 'ENOENT') {
+                return undefined;
+            }
+            throw err;
+        }
+    };
+    const existing = readSalt();
+    if (existing) {
+        return existing;
+    }
+    fsSync.mkdirSync(configDir, {
+        recursive: true
+    });
+    const candidate = crypto.randomBytes(32).toString('hex');
+    try {
+        fsSync.writeFileSync(configPath, JSON.stringify({
+            salt: candidate
+        }, null, '\t'), {
+            flag: 'wx'
+        });
+        return candidate;
+    } catch (err) {
+        if (err.code !== 'EEXIST') {
+            throw err;
+        }
+        const winner = readSalt();
+        if (!winner) {
+            throw new Error('Failed to read salt after losing create-race');
+        }
+        return winner;
     }
-    return salt;
 }
 /**
  * Gather machine-specific entropy sources
@@ -33,19 +72,12 @@ const cryptoConf = new Conf({
  * @throws Error if unable to gather sufficient entropy
  */ function gatherMachineEntropy() {
     try {
-        const userInfo = os.userInfo();
-        const networkInterfaces = os.networkInterfaces();
-        // Get MAC address from first available network interface (if available)
-        const macAddress = Object.values(networkInterfaces).flat().find((iface)=>iface && !iface.internal && iface.mac !== '00:00:00:00:00:00')?.mac;
         const entropy = [
-            os.hostname(),
             os.homedir(),
-            userInfo.username,
+            os.userInfo().username,
             os.platform(),
-            os.arch(),
-            macAddress
-        ].filter(Boolean) // Remove any undefined values
-        ;
+            os.arch()
+        ];
         if (entropy.length < 4) {
             throw new Error('Insufficient machine entropy available');
         }
@@ -92,5 +124,82 @@ const cryptoConf = new Conf({
     const key = crypto.pbkdf2Sync(machineId, salt, 100000, 32, 'sha256');
     return key.toString('hex');
 }
-
-//# sourceMappingURL=crypto-utils.js.map
+/**
+ * @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
+ * without exposing the actual key.
+ */ export function getEncryptionKeyHash() {
+    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;
+}