@payloadcms/figma 0.0.1-alpha.8 → 0.1.0-alpha.0

package/dist/auth/jwt-validator.d.ts

@@ -1,11 +1,12 @@
+import type { Environment } from '../constants.js';
 import type { JWTPayload } from './types.js';
 /**
  * JWT validation error with specific error codes
  */
 export declare class JWTValidationError extends Error {
-    code: 'EXPIRED' | 'JWKS_FETCH_FAILED' | 'MISSING_KID' | 'SIGNATURE_INVALID';
+    code: 'AUDIENCE_INVALID' | 'EXPIRED' | 'JWKS_FETCH_FAILED' | 'MISSING_KID' | 'SIGNATURE_INVALID' | 'TOKEN_CLAIMS_INVALID';
     cause?: Error | undefined;
-    constructor(message: string, code: 'EXPIRED' | 'JWKS_FETCH_FAILED' | 'MISSING_KID' | 'SIGNATURE_INVALID', cause?: Error | undefined);
+    constructor(message: string, code: 'AUDIENCE_INVALID' | 'EXPIRED' | 'JWKS_FETCH_FAILED' | 'MISSING_KID' | 'SIGNATURE_INVALID' | 'TOKEN_CLAIMS_INVALID', cause?: Error | undefined);
 }
 /**
  * Validate a project token JWT
@@ -22,12 +23,29 @@ export declare class JWTValidationError extends Error {
  * - Validates standard claims (exp, iat, nbf)
  * - Handles clock skew tolerance
  *
- * @param token - JWT token string
- * @param environment - Figma environment ('production' or 'staging')
+ * @param params.token - JWT token string
+ * @param params.environment - Figma environment ('production' or 'staging')
+ * @param params.audience - Expected `aud` claim (the tenant's contentSystemId);
+ *   when provided, jose rejects tokens whose `aud` does not match
  * @returns Promise resolving to validated JWT payload
  * @throws {JWTValidationError} If validation fails
  */
-export declare function validateProjectToken(token: string, environment: 'production' | 'staging'): Promise<JWTPayload>;
+export declare function validateProjectToken(params: {
+    /** Expected `aud` claim — the tenant's contentSystemId. Enforced when provided. */
+    audience?: string;
+    environment: Environment;
+    token: string;
+}): Promise<JWTPayload>;
+export declare function validatePayloadAdminToken(params: {
+    audience: string;
+    environment: Environment;
+    token: string;
+}): Promise<JWTPayload>;
+export declare function validateContentApiToken(params: {
+    audience: string;
+    environment: Environment;
+    token: string;
+}): Promise<JWTPayload>;
 /**
  * Clear JWKS cache (useful for testing or forcing refresh)
  *
@@ -38,4 +56,3 @@ export declare function validateProjectToken(token: string, environment: 'produc
  * - Clearing state between test runs
  */
 export declare function clearJWKSCache(): void;
-//# sourceMappingURL=jwt-validator.d.ts.map

package/dist/auth/jwt-validator.js

@@ -1,6 +1,6 @@
 import { createRemoteJWKSet, jwtVerify } from 'jose';
-import { JWKSMultipleMatchingKeys, JWKSNoMatchingKey, JWSInvalid, JWSSignatureVerificationFailed, JWTExpired } from 'jose/errors';
-import { getJWKSUri } from '../constants.js';
+import { JWKSMultipleMatchingKeys, JWKSNoMatchingKey, JWSInvalid, JWSSignatureVerificationFailed, JWTClaimValidationFailed, JWTExpired } from 'jose/errors';
+import { getEnvConfig } from '../constants.js';
 /**
  * JWT validation error with specific error codes
  */ export class JWTValidationError extends Error {
@@ -28,7 +28,7 @@ import { getJWKSUri } from '../constants.js';
  * @param environment - Figma environment ('production' or 'staging')
  * @returns JWKS resolver function
  */ function getJWKSResolver(environment) {
-    const jwksUri = getJWKSUri(environment);
+    const jwksUri = getEnvConfig(environment).jwksUri;
     if (!jwksResolvers.has(jwksUri)) {
         jwksResolvers.set(jwksUri, createRemoteJWKSet(new URL(jwksUri), {
             cacheMaxAge: 24 * 60 * 60 * 1000,
@@ -52,15 +52,21 @@ import { getJWKSUri } from '../constants.js';
  * - Validates standard claims (exp, iat, nbf)
  * - Handles clock skew tolerance
  *
- * @param token - JWT token string
- * @param environment - Figma environment ('production' or 'staging')
+ * @param params.token - JWT token string
+ * @param params.environment - Figma environment ('production' or 'staging')
+ * @param params.audience - Expected `aud` claim (the tenant's contentSystemId);
+ *   when provided, jose rejects tokens whose `aud` does not match
  * @returns Promise resolving to validated JWT payload
  * @throws {JWTValidationError} If validation fails
- */ export async function validateProjectToken(token, environment) {
+ */ export async function validateProjectToken(params) {
+    const { audience, environment, token } = params;
     try {
         const JWKS = getJWKSResolver(environment);
         const { payload } = await jwtVerify(token, JWKS, {
-            clockTolerance: 300
+            clockTolerance: 30,
+            ...audience ? {
+                audience
+            } : {}
         });
         return payload;
     } catch (error) {
@@ -86,6 +92,10 @@ import { getJWKSUri } from '../constants.js';
         if (error instanceof JWSInvalid) {
             throw new JWTValidationError('Invalid JWT structure - missing required header fields (kid or alg)', 'MISSING_KID', error);
         }
+        // Audience mismatch (or missing `aud` when an audience is required)
+        if (error instanceof JWTClaimValidationFailed && error.claim === 'aud') {
+            throw new JWTValidationError('Token audience does not match this tenant', 'AUDIENCE_INVALID', error);
+        }
         // Network or fetch errors (not jose errors, generic Error instances)
         if (error instanceof Error) {
             const message = error.message;
@@ -98,6 +108,24 @@ import { getJWKSUri } from '../constants.js';
         throw new JWTValidationError(`JWT validation failed: ${message}`, 'SIGNATURE_INVALID', error instanceof Error ? error : undefined);
     }
 }
+export async function validatePayloadAdminToken(params) {
+    const payload = await validateProjectToken({
+        ...params,
+        audience: `eid_${params.audience}`
+    });
+    if (typeof payload.sub !== 'string' || typeof payload.email !== 'string') {
+        throw new JWTValidationError('Payload Admin token claims are invalid', 'TOKEN_CLAIMS_INVALID');
+    }
+    return payload;
+}
+export async function validateContentApiToken(params) {
+    // Content API tokens are issued by the content-system-scoped endpoint, which
+    // prefixes the `aud` with `csid_` (mirrors the `eid_` admin-token scoping).
+    return validateProjectToken({
+        ...params,
+        audience: `csid_${params.audience}`
+    });
+}
 /**
  * Clear JWKS cache (useful for testing or forcing refresh)
  *
@@ -109,5 +137,3 @@ import { getJWKSUri } from '../constants.js';
  */ export function clearJWKSCache() {
     jwksResolvers.clear();
 }
-
-//# sourceMappingURL=jwt-validator.js.map

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,20 @@ 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>;
-//# sourceMappingURL=oauth-flow.d.ts.map
+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>;

package/dist/auth/oauth-flow.js

@@ -1,11 +1,12 @@
 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 { CallbackError, CallbackServer } from './callback-server.js';
+import { parsePastedCode, validatePastedCode } from './paste-code.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 +33,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 +54,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,28 +88,36 @@ 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: 'Open browser to authenticate with Figma?'
         });
         if (p.isCancel(shouldOpenBrowser)) {
             throw new OAuthFlowError('Authentication cancelled by user');
         }
+        let browserOpened = false;
         if (shouldOpenBrowser) {
-            // Try to open browser, but don't fail if it doesn't work
             try {
                 await openBrowser(authUrl);
+                browserOpened = true;
             } catch (_error) {
-                // Browser opening failed, show URL for manual opening
                 log.warning('Could not open browser automatically.');
-                log.info(`Please open this URL in your browser:`);
-                log.info(`  ${authUrl}`);
             }
+        }
+        let code;
+        if (browserOpened) {
+            // Browser launched locally; the localhost listener receives the callback.
+            code = (await callbackPromise).code;
         } else {
-            // User declined automatic opening, show URL
-            log.info(`Please open this URL manually in your browser:`);
-            log.info(`  ${authUrl}`);
+            // No local browser (user declined, or open() failed — e.g. a remote devbox).
+            // Show the URL to open manually and accept the redirected code pasted back,
+            // while the localhost listener keeps running in case it can still receive it.
+            // p.log.step directly (not log.info) to avoid bolding the URL.
+            p.log.step(`Open this URL to authenticate:\n\n  ${authUrl}`);
+            code = await waitForCallbackOrPastedCode({
+                callbackPromise,
+                callbackServer,
+                expectedState: state
+            });
         }
-        // Wait for callback
-        const { code } = await callbackPromise;
         // Exchange authorization code for tokens
         let tokens;
         try {
@@ -142,28 +154,133 @@ 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);
     }
 }
-
-//# sourceMappingURL=oauth-flow.js.map
+/**
+ * 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;
+    }
+}
+/**
+ * Race the localhost callback listener against a pasted-code prompt.
+ *
+ * Used when no local browser was opened (remote/headless environments). Whichever
+ * settles first wins: if the listener receives the callback, the paste prompt is
+ * aborted; if the user pastes first, the listener is stopped. The listener's own
+ * timeout is non-fatal here — the user may take a while approving in the browser.
+ *
+ * @returns The authorization code from whichever source won
+ * @throws OAuthFlowError if the user cancels the paste prompt or the pasted value is invalid
+ */ async function waitForCallbackOrPastedCode({ callbackPromise, callbackServer, expectedState }) {
+    const abortController = new AbortController();
+    const listenerBranch = callbackPromise.then((result)=>{
+        // Listener won — tear down the paste prompt.
+        abortController.abort();
+        return result.code;
+    }, (error)=>{
+        // A timeout (or an unreachable listener on a remote box, which surfaces as a
+        // timeout) is non-fatal here — the user can still paste. Any other callback
+        // error means the browser actually reached the listener (denied consent, bad
+        // request, state mismatch), so surface it instead of hanging silently on the
+        // paste prompt.
+        if (error instanceof CallbackError && error.code === 'timeout') {
+            return new Promise(()=>{});
+        }
+        abortController.abort();
+        throw error;
+    });
+    const pasteBranch = (async ()=>{
+        // @clack/prompts TextOptions doesn't expose `signal` in its public type, but the
+        // underlying @clack/core PromptOptions does. Cast to reach the runtime capability.
+        const textOpts = {
+            message: 'Paste the redirect URL or code (optional):',
+            signal: abortController.signal,
+            validate: (value)=>validatePastedCode(value ?? '')
+        };
+        const pasted = await p.text(textOpts);
+        if (p.isCancel(pasted)) {
+            throw new OAuthFlowError('Authentication cancelled by user');
+        }
+        // Paste won — stop the listener before exchanging.
+        callbackServer.stop();
+        try {
+            return parsePastedCode(pasted, expectedState);
+        } catch (error) {
+            throw new OAuthFlowError(error instanceof Error ? error.message : 'Invalid pasted authorization code', error instanceof Error ? error : undefined);
+        }
+    })();
+    // Avoid an unhandled rejection when the paste prompt is aborted after the listener wins.
+    pasteBranch.catch(()=>{});
+    return Promise.race([
+        listenerBranch,
+        pasteBranch
+    ]);
+}
+function replaceRedirectUriPort(redirectUri, port) {
+    const url = new URL(redirectUri);
+    url.port = String(port);
+    return url.toString();
+}

package/dist/auth/paste-code.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Error parsing a pasted authorization code or redirect URL.
+ */
+export declare class PastedCodeError extends Error {
+    constructor(message: string);
+}
+/**
+ * Parse a value the user pasted back after completing OAuth in their browser.
+ *
+ * Accepts either the full redirect URL (e.g.
+ * `http://localhost:34462/callback?code=...&state=...`) or a bare authorization
+ * code. When a URL is pasted, the `state` is validated against the value the CLI
+ * generated (CSRF protection); when a bare code is pasted, no state check is
+ * possible and PKCE alone gates the subsequent token exchange.
+ *
+ * @param input - Raw pasted text
+ * @param expectedState - The state value the CLI generated for this flow
+ * @returns The authorization code
+ * @throws PastedCodeError if the input is empty, is a URL without a code, or has a mismatched state
+ */
+export declare function parsePastedCode(input: string, expectedState: string): string;
+/**
+ * Structural validation for use as a `@clack/prompts` `text` validator.
+ *
+ * Returns `undefined` when the input could yield a code (so the prompt accepts it),
+ * or a human-readable message to re-prompt. Intentionally does NOT validate `state`
+ * — a state mismatch is a hard failure handled after the prompt resolves, not a
+ * re-prompt condition.
+ *
+ * @param input - Current prompt value
+ * @returns Error message string, or undefined if structurally valid
+ */
+export declare function validatePastedCode(input: string): string | undefined;

package/dist/auth/paste-code.js

@@ -0,0 +1,87 @@
+/**
+ * Error parsing a pasted authorization code or redirect URL.
+ */ export class PastedCodeError extends Error {
+    constructor(message){
+        super(message);
+        this.name = 'PastedCodeError';
+    }
+}
+const NO_CODE_MESSAGE = 'That URL has no "code" parameter. Paste the full redirect URL or just the code.';
+function parsePasteInput(input) {
+    const trimmed = input.trim();
+    if (!trimmed) {
+        return {
+            kind: 'empty'
+        };
+    }
+    let url;
+    try {
+        url = new URL(trimmed);
+    } catch  {
+        return {
+            code: trimmed,
+            kind: 'bare-code'
+        };
+    }
+    const code = url.searchParams.get('code');
+    if (!code) {
+        return {
+            kind: 'url-missing-code'
+        };
+    }
+    return {
+        code,
+        kind: 'url',
+        state: url.searchParams.get('state')
+    };
+}
+/**
+ * Parse a value the user pasted back after completing OAuth in their browser.
+ *
+ * Accepts either the full redirect URL (e.g.
+ * `http://localhost:34462/callback?code=...&state=...`) or a bare authorization
+ * code. When a URL is pasted, the `state` is validated against the value the CLI
+ * generated (CSRF protection); when a bare code is pasted, no state check is
+ * possible and PKCE alone gates the subsequent token exchange.
+ *
+ * @param input - Raw pasted text
+ * @param expectedState - The state value the CLI generated for this flow
+ * @returns The authorization code
+ * @throws PastedCodeError if the input is empty, is a URL without a code, or has a mismatched state
+ */ export function parsePastedCode(input, expectedState) {
+    const parsed = parsePasteInput(input);
+    switch(parsed.kind){
+        case 'empty':
+            throw new PastedCodeError('No value provided.');
+        case 'bare-code':
+            return parsed.code;
+        case 'url-missing-code':
+            throw new PastedCodeError(NO_CODE_MESSAGE);
+        case 'url':
+            if (parsed.state !== null && parsed.state !== expectedState) {
+                throw new PastedCodeError('State mismatch — possible CSRF. Run login again.');
+            }
+            return parsed.code;
+    }
+}
+/**
+ * Structural validation for use as a `@clack/prompts` `text` validator.
+ *
+ * Returns `undefined` when the input could yield a code (so the prompt accepts it),
+ * or a human-readable message to re-prompt. Intentionally does NOT validate `state`
+ * — a state mismatch is a hard failure handled after the prompt resolves, not a
+ * re-prompt condition.
+ *
+ * @param input - Current prompt value
+ * @returns Error message string, or undefined if structurally valid
+ */ export function validatePastedCode(input) {
+    const parsed = parsePasteInput(input);
+    switch(parsed.kind){
+        case 'empty':
+            return 'Paste the redirect URL or the code.';
+        case 'url-missing-code':
+            return NO_CODE_MESSAGE;
+        default:
+            return undefined;
+    }
+}

package/dist/auth/pkce.d.ts

@@ -48,4 +48,3 @@ export declare function generateCodeChallenge(verifier: string): string;
  * // Include codeChallenge and codeChallengeMethod in authorization URL
  */
 export declare function generatePKCEPair(): PKCEPair;
-//# sourceMappingURL=pkce.d.ts.map

package/dist/auth/pkce.js

@@ -67,5 +67,3 @@ import crypto from 'crypto';
  */ function base64UrlEncode(buffer) {
     return buffer.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
 }
-
-//# sourceMappingURL=pkce.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,49 @@ 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>;
-//# sourceMappingURL=project-token.d.ts.map
+export declare function refreshProjectToken(params: {
+    projectInfo?: ProjectStoreScope;
+    tenantId?: string;
+    tokenStore: TokenStore;
+}): Promise<null | string>;