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

package/dist/auth/token-store.js

@@ -1,18 +1,20 @@
 /* eslint-disable perfectionist/sort-classes */ import Conf from 'conf';
+import envPaths from 'env-paths';
 import fsSync from 'node:fs';
+import path from 'node:path';
 import { TOKEN_EXPIRY_BUFFER_SECONDS } from '../config/oauth.js';
 import { getInfraEnvironment } from '../constants.js';
+import { getEnvVarSync } from '../utils/env-management.js';
 import * as log from '../utils/log.js';
 import { deriveEncryptionKey } from './crypto-utils.js';
+import { migrateOAuth, migrateProjectData, needsMigration } from './token-store-migration.js';
 /**
- * Environment-keyed instances for singleton pattern
+ * Environment-keyed instances for singleton pattern.
  */ const instances = {};
+const OAUTH_STORE_SCHEMA_VERSION = 1;
+const PROJECT_STORE_SCHEMA_VERSION = 1;
 /**
- * Get the singleton TokenStore instance for an environment
- * Use this for all production code to ensure a single shared instance per environment
- *
- * @param environment - The environment to get the token store for
- * @returns The singleton TokenStore instance for that environment
+ * Get the singleton TokenStore instance for an environment.
  */ export function getTokenStore(environment = getInfraEnvironment()) {
     if (!instances[environment]) {
         instances[environment] = new TokenStore({
@@ -22,110 +24,180 @@ import { deriveEncryptionKey } from './crypto-utils.js';
     return instances[environment];
 }
 /**
- * Secure storage manager for Figma OAuth2 tokens
- *
- * Uses the `conf` library to store tokens in an OS-specific secure location:
- * - macOS: ~/Library/Preferences/payloadcms-figma
- * - Linux: ~/.config/payloadcms-figma or $XDG_CONFIG_HOME/payloadcms-figma
- * - Windows: %APPDATA%/payloadcms-figma/Config
- *
- * Tokens are encrypted at rest with a machine-specific key and file permissions
- * are set to 0600 (owner read/write only)
+ * Secure storage manager for OAuth tokens and project-scoped bootstrap/token data.
  *
  * For production code, use getTokenStore() to get the singleton instance.
  * The constructor is still exported for test isolation.
  */ export class TokenStore {
-    config;
+    baseConfigName;
+    encryptionKey;
     environment;
+    legacyRootDir;
+    oauthConfig;
+    projectName;
+    projectStoreConfigs = new Map();
     constructor(options){
         if (process.env.AWS_EXECUTION_ENV) {
             throw new Error('TokenStore cannot be used in AWS Lambda environments');
         }
         const environment = options?.environment ?? 'production';
-        const projectName = environment === 'production' ? 'payloadcms-figma' : `payloadcms-figma-${environment}`;
+        const projectName = 'payloadcms-figma';
+        const encryptionKey = options?.encryptionKey ?? deriveEncryptionKey();
+        const baseConfigName = options?.configName || projectName;
+        this.baseConfigName = baseConfigName;
+        this.encryptionKey = encryptionKey;
         this.environment = environment;
-        const confOptions = {
-            clearInvalidConfig: false,
-            configName: options?.configName || projectName,
-            encryptionKey: options?.encryptionKey || deriveEncryptionKey(),
-            projectName
-        };
-        try {
-            this.config = new Conf(confOptions);
-        } catch (error) {
-            // Deserialization failed (e.g. encryption key changed).
-            // Log diagnostics, clear the corrupted file, then create a fresh store.
-            if (environment === 'staging') {
-                log.warning(`Token store corrupted, resetting. ` + `Error: ${error instanceof Error ? error.message : 'Unknown'}`);
-            }
-            // Temporarily allow clearing so Conf can reinitialize
-            this.config = new Conf({
-                ...confOptions,
-                clearInvalidConfig: true
+        this.projectName = projectName;
+        // Resolve the legacy root dir (matching Conf's env-paths convention)
+        // without instantiating Conf, which would read/parse the encrypted file
+        // and could wipe it under clearInvalidConfig.
+        this.legacyRootDir = envPaths(projectName).config;
+        const legacyFilePath = path.join(this.legacyRootDir, `${baseConfigName}.json`);
+        const newOAuthCwd = this.buildOAuthStoreCwd();
+        const newOAuthFilePath = path.join(newOAuthCwd, `${this.buildOAuthConfigName()}.json`);
+        const resolveProjectStorePath = (scope)=>({
+                configName: this.buildProjectStoreConfigName(scope),
+                cwd: this.buildProjectStoreCwd(scope)
+            });
+        if (needsMigration({
+            legacyFilePath,
+            newOAuthFilePath
+        })) {
+            migrateOAuth({
+                encryptionKey,
+                legacyConfigName: baseConfigName,
+                newOAuthConfigName: this.buildOAuthConfigName(),
+                newOAuthCwd,
+                projectName
             });
-            // Force a write so the corrupt file is replaced with an empty store.
-            // Without this, clearInvalidConfig only ignores bad reads in memory
-            // and the corrupt file persists, triggering this fallback every time.
-            this.config.clear();
         }
-    }
-    safeGet(key) {
-        try {
-            return this.config.get(key);
-        } catch (error) {
-            if (this.environment === 'staging') {
-                const filePath = this.config.path;
-                const fileExists = fsSync.existsSync(filePath);
-                const fileSize = fileExists ? fsSync.statSync(filePath).size : 0;
-                log.warning(`Token store read failed (key: ${key}). ` + `File: ${filePath}, exists: ${fileExists}, size: ${fileSize}B. ` + `Error: ${error instanceof Error ? error.message : 'Unknown'}`);
+        if (fsSync.existsSync(legacyFilePath)) {
+            migrateProjectData({
+                encryptionKey,
+                legacyConfigName: baseConfigName,
+                projectName,
+                resolveProjectStorePath
+            });
+        }
+        // Also check for legacy files in old environment-specific directories
+        // (e.g., payloadcms-figma-staging-nodejs/ for staging environment).
+        if (environment !== 'production') {
+            const oldEnvProjectName = `payloadcms-figma-${environment}`;
+            const oldEnvConfigName = options?.configName || oldEnvProjectName;
+            const oldEnvLegacyDir = envPaths(oldEnvProjectName).config;
+            const oldEnvLegacyFilePath = path.join(oldEnvLegacyDir, `${oldEnvConfigName}.json`);
+            if (needsMigration({
+                legacyFilePath: oldEnvLegacyFilePath,
+                newOAuthFilePath
+            })) {
+                migrateOAuth({
+                    encryptionKey,
+                    legacyConfigName: oldEnvConfigName,
+                    legacyCwd: oldEnvLegacyDir,
+                    newOAuthConfigName: this.buildOAuthConfigName(),
+                    newOAuthCwd,
+                    projectName: oldEnvProjectName
+                });
+            }
+            if (fsSync.existsSync(oldEnvLegacyFilePath)) {
+                migrateProjectData({
+                    encryptionKey,
+                    legacyConfigName: oldEnvConfigName,
+                    legacyCwd: oldEnvLegacyDir,
+                    projectName: oldEnvProjectName,
+                    resolveProjectStorePath
+                });
             }
-            return undefined;
         }
+        this.oauthConfig = this.createConfig({
+            configName: this.buildOAuthConfigName(),
+            cwd: this.buildOAuthStoreCwd(),
+            encryptionKey: this.encryptionKey,
+            storeType: 'oauth'
+        });
     }
-    /**
-   * Retrieve stored tokens
-   * @returns FigmaTokens if stored, null otherwise
-   */ getTokens() {
-        const tokens = this.safeGet('tokens');
-        return tokens || null;
+    getOauthInfo() {
+        const accessToken = this.safeGet({
+            config: this.oauthConfig,
+            key: 'accessToken'
+        });
+        const expiresAt = this.safeGet({
+            config: this.oauthConfig,
+            key: 'expiresAt'
+        });
+        const refreshToken = this.safeGet({
+            config: this.oauthConfig,
+            key: 'refreshToken'
+        });
+        if (typeof accessToken !== 'string' || typeof expiresAt !== 'number' || typeof refreshToken !== 'string') {
+            return null;
+        }
+        return {
+            accessToken,
+            expiresAt,
+            refreshToken,
+            scopes: this.safeGet({
+                config: this.oauthConfig,
+                key: 'scopes'
+            }),
+            tokenType: this.safeGet({
+                config: this.oauthConfig,
+                key: 'tokenType'
+            }),
+            userId: this.safeGet({
+                config: this.oauthConfig,
+                key: 'userId'
+            })
+        };
     }
-    /**
-   * Store OAuth2 tokens securely
-   * @param tokens - Figma OAuth2 tokens to store
-   */ setTokens(tokens) {
-        this.config.set('tokens', tokens);
-        // Verify the round-trip: read back what we just wrote
-        const readBack = this.safeGet('tokens');
+    setTokens(tokens) {
+        this.oauthConfig.set('_schemaVersion', OAUTH_STORE_SCHEMA_VERSION);
+        this.oauthConfig.set('accessToken', tokens.accessToken);
+        this.oauthConfig.set('expiresAt', tokens.expiresAt);
+        this.oauthConfig.set('refreshToken', tokens.refreshToken);
+        if (tokens.scopes) {
+            this.oauthConfig.set('scopes', tokens.scopes);
+        } else {
+            this.oauthConfig.delete('scopes');
+        }
+        if (tokens.tokenType) {
+            this.oauthConfig.set('tokenType', tokens.tokenType);
+        } else {
+            this.oauthConfig.delete('tokenType');
+        }
+        if (tokens.userId) {
+            this.oauthConfig.set('userId', tokens.userId);
+        } else {
+            this.oauthConfig.delete('userId');
+        }
+        // Verify the round-trip: read back what we just wrote.
+        const readBack = this.getOauthInfo();
         if (!readBack || readBack.accessToken !== tokens.accessToken) {
             if (this.environment === 'staging') {
-                const filePath = this.config.path;
+                const filePath = this.oauthConfig.path;
                 const fileExists = fsSync.existsSync(filePath);
                 const fileSize = fileExists ? fsSync.statSync(filePath).size : 0;
                 log.warning(`Token verify-after-write FAILED. ` + `File: ${filePath}, exists: ${fileExists}, size: ${fileSize}B. ` + `Written accessToken starts: ${tokens.accessToken.substring(0, 10)}..., ` + `Read back: ${readBack ? readBack.accessToken.substring(0, 10) + '...' : 'null'}`);
             }
         }
     }
-    /**
-   * Clear all stored tokens (used for logout)
-   */ clearTokens() {
-        this.config.delete('tokens');
+    clearTokens() {
+        this.oauthConfig.delete('accessToken');
+        this.oauthConfig.delete('expiresAt');
+        this.oauthConfig.delete('refreshToken');
+        this.oauthConfig.delete('scopes');
+        this.oauthConfig.delete('tokenType');
+        this.oauthConfig.delete('userId');
     }
-    /**
-   * Check if valid (non-expired) tokens exist
-   * @returns true if tokens exist and are not expired
-   */ hasValidTokens() {
-        const tokens = this.getTokens();
+    hasValidOauthToken() {
+        const tokens = this.getOauthInfo();
         if (!tokens) {
             return false;
         }
-        return !this.isExpired();
+        return !this.isOauthExpired();
     }
-    /**
-   * Check if the current access token is expired
-   * Includes a buffer time to avoid using tokens that are about to expire
-   * @returns true if token is expired or will expire within buffer time
-   */ isExpired() {
-        const tokens = this.safeGet('tokens');
+    isOauthExpired() {
+        const tokens = this.getOauthInfo();
         if (!tokens) {
             return true;
         }
@@ -134,30 +206,19 @@ import { deriveEncryptionKey } from './crypto-utils.js';
         const expiryWithBuffer = tokens.expiresAt - bufferMs;
         return now >= expiryWithBuffer;
     }
-    /**
-   * Get the access token if it exists and is valid
-   * @returns Access token string or null if expired/missing
-   */ getAccessToken() {
-        if (!this.hasValidTokens()) {
+    getCurrentOauthToken() {
+        if (!this.hasValidOauthToken()) {
             return null;
         }
-        const tokens = this.getTokens();
+        const tokens = this.getOauthInfo();
         return tokens?.accessToken || null;
     }
-    /**
-   * Get the refresh token if it exists
-   * @returns Refresh token string or null if missing
-   */ getRefreshToken() {
-        const tokens = this.getTokens();
+    getCurrentRefreshToken() {
+        const tokens = this.getOauthInfo();
         return tokens?.refreshToken || null;
     }
-    /**
-   * Update just the access token after a refresh
-   * Preserves the existing refresh token and other metadata
-   * @param accessToken - New access token
-   * @param expiresIn - Expiration time in seconds
-   */ updateAccessToken(accessToken, expiresIn) {
-        const existingTokens = this.getTokens();
+    updateAccessToken(accessToken, expiresIn) {
+        const existingTokens = this.getOauthInfo();
         if (!existingTokens) {
             throw new Error('Cannot update access token: no existing tokens found');
         }
@@ -169,123 +230,201 @@ import { deriveEncryptionKey } from './crypto-utils.js';
         });
     }
     /**
-   * Get the path to the config file (useful for debugging)
-   * @returns Absolute path to the token storage file
+   * Returns the OAuth storage file path.
    */ getStoragePath() {
-        return this.config.path;
+        return this.oauthConfig.path;
     }
-    /**
-   * Retrieve a project token for a specific tenant
-   * Automatically removes expired tokens from storage
-   * @param tenantId - The tenant/CMS ID
-   * @returns ProjectToken if stored and valid, null otherwise
-   */ getProjectToken(tenantId) {
-        const projectTokens = this.safeGet('projectTokens') || {};
-        const projectToken = projectTokens[tenantId];
+    getProjectToken({ projectInfo } = {}) {
+        const resolvedProjectInfo = projectInfo ?? this.getProjectInfoFromEnv();
+        if (!resolvedProjectInfo) {
+            return null;
+        }
+        const config = this.getProjectStore(resolvedProjectInfo);
+        const projectToken = this.safeGet({
+            config,
+            key: 'projectToken'
+        });
         if (!projectToken) {
             return null;
         }
-        // Auto-cleanup expired project token
         if (this.isProjectTokenExpired(projectToken)) {
-            this.clearProjectToken(tenantId);
+            this.clearProjectToken({
+                projectInfo: resolvedProjectInfo
+            });
             return null;
         }
         return projectToken;
     }
-    /**
-   * Store a project token for a specific tenant
-   * @param tenantId - The tenant/CMS ID
-   * @param projectToken - The project token to store
-   */ setProjectToken(tenantId, projectToken) {
-        const projectTokens = this.safeGet('projectTokens') || {};
-        projectTokens[tenantId] = projectToken;
-        this.config.set('projectTokens', projectTokens);
-    }
-    /**
-   * Clear a project token for a specific tenant
-   * @param tenantId - The tenant/CMS ID
-   */ clearProjectToken(tenantId) {
-        const projectTokens = this.safeGet('projectTokens') || {};
-        delete projectTokens[tenantId];
-        this.config.set('projectTokens', projectTokens);
+    setProjectToken({ projectInfo, token }) {
+        const resolvedProjectInfo = projectInfo ?? this.getProjectInfoFromEnv();
+        if (!resolvedProjectInfo) {
+            throw new Error('Cannot set project token: FIGMA_PROJECT_ID and FIGMA_ENVIRONMENT_NAME must be set');
+        }
+        const config = this.getProjectStore(resolvedProjectInfo);
+        config.set('_schemaVersion', PROJECT_STORE_SCHEMA_VERSION);
+        config.set('projectToken', token);
     }
-    /**
-   * Clear all project tokens
-   */ clearAllProjectTokens() {
-        this.config.delete('projectTokens');
+    clearProjectToken({ projectInfo } = {}) {
+        const resolvedProjectInfo = projectInfo ?? this.getProjectInfoFromEnv();
+        if (!resolvedProjectInfo) {
+            return; // Nothing to clear if we can't determine the project
+        }
+        const config = this.getProjectStore(resolvedProjectInfo);
+        config.delete('projectToken');
     }
-    /**
-   * Check if a project token is expired
-   * Includes a buffer time to avoid using tokens that are about to expire
-   * @param projectToken - The project token to check
-   * @returns true if token is expired or will expire within buffer time
-   */ isProjectTokenExpired(projectToken) {
+    isProjectTokenExpired(token) {
         const now = Date.now();
         const bufferMs = TOKEN_EXPIRY_BUFFER_SECONDS * 1000;
-        const expiryWithBuffer = projectToken.expiresAt - bufferMs;
+        const expiryWithBuffer = token.expiresAt - bufferMs;
         return now >= expiryWithBuffer;
     }
-    /**
-   * Check if a valid (non-expired) project token exists for a tenant
-   * @param tenantId - The tenant/CMS ID
-   * @returns true if token exists and is not expired
-   */ hasValidProjectToken(tenantId) {
-        const projectToken = this.getProjectToken(tenantId);
+    hasValidProjectToken({ projectInfo } = {}) {
+        const projectToken = this.getProjectToken({
+            projectInfo
+        });
         if (!projectToken) {
             return false;
         }
         return !this.isProjectTokenExpired(projectToken);
     }
     /**
-   * Get validated JWT claims from a project token
-   * @param tenantId - The tenant/CMS ID
-   * @returns JWT payload claims or null if token not found or has no claims
-   */ getProjectTokenClaims(tenantId) {
-        const projectToken = this.getProjectToken(tenantId);
-        return projectToken?.claims || null;
+   * Get the tenantId (contentSystemId) for the project scope.
+   * Returns null if bootstrap data is not available.
+   */ getTenantId({ projectInfo } = {}) {
+        const resolvedProjectInfo = projectInfo ?? this.getProjectInfoFromEnv();
+        if (!resolvedProjectInfo) {
+            return null;
+        }
+        const bootstrapData = this.getBootstrapData(resolvedProjectInfo.projectId, resolvedProjectInfo.environmentName);
+        return bootstrapData?.contentSystemId ?? null;
     }
     /**
-   * Get all tenant IDs that have stored project tokens
-   * @returns Array of tenant IDs
-   */ getAllProjectTokenTenantIds() {
-        const projectTokens = this.safeGet('projectTokens') || {};
-        return Object.keys(projectTokens);
+   * Derive project info from environment variables.
+   * Returns null if either FIGMA_PROJECT_ID or FIGMA_ENVIRONMENT_NAME is not set.
+   */ getProjectInfoFromEnv() {
+        const projectId = process.env.FIGMA_PROJECT_ID || getEnvVarSync(process.cwd(), 'FIGMA_PROJECT_ID');
+        const environmentName = process.env.FIGMA_ENVIRONMENT_NAME || getEnvVarSync(process.cwd(), 'FIGMA_ENVIRONMENT_NAME');
+        if (!projectId || !environmentName) {
+            return null;
+        }
+        return {
+            environmentName,
+            projectId
+        };
     }
-    /**
-   * Build the composite key for bootstrap data storage
-   * @param projectId - The CMS resource/project ID
-   * @param environmentName - The environment name (e.g. 'production', 'staging')
-   * @returns Composite key string
-   */ bootstrapKey(projectId, environmentName) {
-        return `${projectId}:${environmentName}`;
+    getBootstrapData(projectId, environmentName) {
+        const config = this.getProjectStore({
+            environmentName,
+            projectId
+        });
+        const bootstrapData = this.safeGet({
+            config,
+            key: 'bootstrapData'
+        });
+        return bootstrapData || null;
     }
-    /**
-   * Retrieve bootstrap data for a project + environment
-   * @param projectId - The CMS resource/project ID
-   * @param environmentName - The environment name
-   * @returns BootstrapData if stored, null otherwise
-   */ getBootstrapData(projectId, environmentName) {
-        const allData = this.safeGet('bootstrapData') || {};
-        return allData[this.bootstrapKey(projectId, environmentName)] || null;
+    setBootstrapData(projectId, environmentName, data) {
+        const config = this.getProjectStore({
+            environmentName,
+            projectId
+        });
+        config.set('_schemaVersion', PROJECT_STORE_SCHEMA_VERSION);
+        config.set('bootstrapData', data);
     }
-    /**
-   * Store bootstrap data for a project + environment
-   * @param projectId - The CMS resource/project ID
-   * @param environmentName - The environment name
-   * @param data - The bootstrap data to store
-   */ setBootstrapData(projectId, environmentName, data) {
-        const allData = this.safeGet('bootstrapData') || {};
-        allData[this.bootstrapKey(projectId, environmentName)] = data;
-        this.config.set('bootstrapData', allData);
+    clearBootstrapData(projectId, environmentName) {
+        const config = this.getProjectStore({
+            environmentName,
+            projectId
+        });
+        config.delete('bootstrapData');
     }
-    /**
-   * Clear bootstrap data for a project + environment
-   * @param projectId - The CMS resource/project ID
-   * @param environmentName - The environment name
-   */ clearBootstrapData(projectId, environmentName) {
-        const allData = this.safeGet('bootstrapData') || {};
-        delete allData[this.bootstrapKey(projectId, environmentName)];
-        this.config.set('bootstrapData', allData);
+    buildOAuthConfigName() {
+        // For test isolation: if using a custom config name, use it as-is with -oauth suffix
+        // Otherwise use the standard naming that includes environment
+        if (this.baseConfigName !== this.projectName) {
+            return `${this.baseConfigName}-oauth`;
+        }
+        return `payloadcms-figma-${this.environment}-oauth`;
+    }
+    buildOAuthStoreCwd() {
+        return path.join(this.getLegacyRootDir(), 'oauth');
+    }
+    buildProjectStoreConfigName(projectInfo) {
+        const env = this.sanitizeConfigSegment(projectInfo.environmentName);
+        if (this.baseConfigName !== this.projectName) {
+            return `${this.baseConfigName}-${env}-contentAPI`;
+        }
+        return `payloadcms-figma-${env}-contentAPI`;
+    }
+    buildProjectStoreCwd(projectInfo) {
+        return path.join(this.getLegacyRootDir(), 'projects', this.sanitizeConfigSegment(projectInfo.projectId));
+    }
+    sanitizeConfigSegment(value) {
+        return value.replace(/[^\w-]/g, '-').replace(/-+/g, '-');
+    }
+    projectInfoKey(projectInfo) {
+        return `${projectInfo.projectId}:${projectInfo.environmentName}`;
+    }
+    getLegacyRootDir() {
+        return this.legacyRootDir;
+    }
+    getProjectStore(projectInfo) {
+        const projectInfoKey = this.projectInfoKey(projectInfo);
+        const existing = this.projectStoreConfigs.get(projectInfoKey);
+        if (existing) {
+            return existing;
+        }
+        const config = this.createConfig({
+            configName: this.buildProjectStoreConfigName(projectInfo),
+            cwd: this.buildProjectStoreCwd(projectInfo),
+            encryptionKey: this.encryptionKey,
+            storeType: 'project'
+        });
+        this.projectStoreConfigs.set(projectInfoKey, config);
+        return config;
+    }
+    createConfig(params) {
+        const confOptions = {
+            clearInvalidConfig: false,
+            configName: params.configName,
+            cwd: params.cwd,
+            ...params.encryptionKey ? {
+                encryptionKey: params.encryptionKey
+            } : {},
+            projectName: this.projectName
+        };
+        try {
+            return new Conf(confOptions);
+        } catch (error) {
+            // Deserialization failed (e.g. encryption key changed).
+            // Log diagnostics, then clear and replace with a fresh store.
+            if (this.environment === 'staging') {
+                log.warning(`${params.storeType} token store corrupted, resetting. ` + `Error: ${error instanceof Error ? error.message : 'Unknown'}`);
+            }
+            const config = new Conf({
+                ...confOptions,
+                clearInvalidConfig: true
+            });
+            // Force a write so the corrupt file is replaced with an empty store.
+            // Without this, clearInvalidConfig only ignores bad reads in memory
+            // and the corrupt file persists, triggering this fallback every time.
+            config.clear();
+            return config;
+        }
+    }
+    safeGet(params) {
+        const { config, key } = params;
+        try {
+            return config.get(key);
+        } catch (error) {
+            if (this.environment === 'staging') {
+                const filePath = config.path;
+                const fileExists = fsSync.existsSync(filePath);
+                const fileSize = fileExists ? fsSync.statSync(filePath).size : 0;
+                log.warning(`Token store read failed (key: ${String(key)}). ` + `File: ${filePath}, exists: ${fileExists}, size: ${fileSize}B. ` + `Error: ${error instanceof Error ? error.message : 'Unknown'}`);
+            }
+            return undefined;
+        }
     }
 }
 

package/dist/auth/types.d.ts

@@ -109,7 +109,7 @@ export interface OAuthTokenRefreshParams {
 export type TokenStoreConfig = {
     /** Config file name (for testing) */
     configName?: string;
-    /** Encryption key (for testing) */
+    /** Optional override for storage encryption key (primarily for tests). */
     encryptionKey?: string;
     /** Environment for config file naming */
     environment?: Environment;
@@ -171,6 +171,13 @@ export type BootstrapData = {
     oauthClientSecret: string;
     tenantInstanceId: string;
 };
+/**
+ * Scope information used for project/environment-specific token storage.
+ */
+export type ProjectStoreScope = {
+    environmentName: string;
+    projectId: string;
+};
 /**
  * JWT payload structure from Figma project tokens
  * Extends jose's standard JWTPayload with Figma-specific claims

package/dist/cli.js

@@ -4,6 +4,7 @@ import pc from 'picocolors';
 import { buildLambdaZipCommand } from './commands/build-lambda-zip.js';
 import { debugCommand } from './commands/debug.js';
 import { deployCommand } from './commands/deploy.js';
+import { dumpTokensCommand } from './commands/dump-tokens.js';
 import { envCommand } from './commands/env.js';
 import { initCommand } from './commands/init.js';
 import { listTokensCommand } from './commands/list-tokens.js';
@@ -101,6 +102,11 @@ class Main {
                 await debugCommand();
                 process.exit(0);
             }
+            // dump-tokens outputs plain text
+            if (subcommand === 'dump-tokens') {
+                await dumpTokensCommand();
+                process.exit(0);
+            }
             // eslint-disable-next-line no-console
             console.log('\n');
             p.intro(pc.bgCyan(pc.black(' @payloadcms/figma ')));