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

package/dist/oauth/utilities/figmaHostnames.js

@@ -0,0 +1,24 @@
+// Copied from share/figma-url/src/hostnames.ts.
+// This package is published to npm (@payloadcms/figma) and cannot import from
+// the monorepo's internal share/ tree, so the list is duplicated here.
+export const FIGMA_HOSTNAMES = new Set([
+    'embed.figma.com',
+    'embed.figma-gov.com',
+    'embed.local.figma.engineering',
+    'embed.staging.figma.com',
+    'figma.com',
+    'figma-gov.com',
+    'local.figma.engineering',
+    'localhost',
+    'staging.figma.com',
+    'www.figma.com',
+    'www.figma-gov.com'
+]);
+export const isFigmaOrigin = (origin)=>{
+    try {
+        const { hostname } = new URL(origin);
+        return FIGMA_HOSTNAMES.has(hostname) || hostname.endsWith('.figdev.systems');
+    } catch  {
+        return false;
+    }
+};

package/dist/oauth/utilities/getAdminCollectionSlug.d.ts

@@ -1,3 +1,2 @@
 import type { Config } from 'payload';
 export declare const getAdminCollectionSlug: (config: Config) => string;
-//# sourceMappingURL=getAdminCollectionSlug.d.ts.map

package/dist/oauth/utilities/getAdminCollectionSlug.js

@@ -14,5 +14,3 @@ export const getAdminCollectionSlug = (config)=>{
     // Otherwise, assume that it'll be the built-in auth
     return 'users';
 };
-
-//# sourceMappingURL=getAdminCollectionSlug.js.map

package/dist/oauth/utilities/getAuthorizeURL.d.ts

@@ -5,6 +5,16 @@ interface Args {
     collection: CollectionConfig;
     collectionOptions: CollectionOptions;
     endpointSlug: string;
+    /**
+     * If the request already has an `__Host-payload-oauth-state_csrf` cookie,
+     * pass its value here — `getAuthorizeURL` will reuse it as `state.csrf`
+     * instead of minting a fresh nonce. This is what makes `/meta`
+     * idempotent across multiple calls in a single browser session (React
+     * Strict Mode re-mounts, retry-after-failure, multiple tabs) and
+     * prevents the cookie/state mismatch race where one call overwrites
+     * another call's cookie.
+     */
+    existingCsrfNonce?: null | string;
     failedRedirect?: unknown;
     payload: Payload;
     pluginOptions: PluginOptions;
@@ -12,6 +22,59 @@ interface Args {
     serverURLOverride?: unknown;
     strategy: Strategy;
 }
-export declare const getAuthorizeURL: ({ collection, collectionOptions, endpointSlug, failedRedirect, payload, pluginOptions, redirect, serverURLOverride, strategy, }: Args) => Promise<string>;
+export interface AuthorizeURLParams {
+    [key: string]: string;
+    client_id: string;
+    code_challenge: string;
+    code_challenge_method: string;
+    nonce: string;
+    redirect_uri: string;
+    response_mode: string;
+    response_type: string;
+    scope: string;
+    state: string;
+}
+export interface AuthorizeURLResult {
+    authorizeURL: string;
+    /**
+     * The plaintext CSRF nonce that the caller MUST set as an HttpOnly
+     * cookie on the response (see `OAUTH_STATE_CSRF_COOKIE_NAME`). `/sso/login`
+     * compares this value to the cookie on callback — this is the
+     * browser-binding required by RFC 6749 §10.12.
+     */
+    csrfNonce: string;
+    params: AuthorizeURLParams;
+}
+export declare const getAuthorizeURL: ({ collection, collectionOptions, endpointSlug, existingCsrfNonce, failedRedirect, payload, pluginOptions, redirect, serverURLOverride, strategy, }: Args) => Promise<AuthorizeURLResult>;
+/**
+ * Name of the HttpOnly cookie that carries the browser-bound CSRF nonce
+ * for the OAuth flow. The `__Host-` prefix instructs browsers to enforce:
+ * Secure, no Domain attribute (host-only), and Path=/ — which together
+ * prevent sibling subdomains from setting or overwriting it.
+ */
+export declare const OAUTH_STATE_CSRF_COOKIE_NAME = "__Host-payload-oauth-state_csrf";
+/**
+ * Build the `Set-Cookie` header value for the CSRF cookie. SameSite=None
+ * + Secure so the cookie survives the IdP cross-site redirect back into
+ * /sso/login, AND so the iframe auto-login path works (the iframe is a
+ * third-party context from the top-level Figma page). Path=/ is required
+ * by the `__Host-` prefix.
+ *
+ * `Partitioned` (CHIPS) is required because the Make preview embeds the
+ * admin panel in a cross-site iframe. Under Chrome's third-party-cookie
+ * restrictions a `SameSite=None` cookie set in a third-party context is
+ * NOT sent back unless it is partitioned by the top-level site. Without it
+ * the `__Host-payload-oauth-state_csrf` cookie is dropped on the way back
+ * to /sso/login, the cookie↔state.csrf binding check fails, and login dies
+ * with "CSRF cookie mismatch" (intermittent sign-in loop). `__Host-` and
+ * `Partitioned` are mutually compatible.
+ */
+export declare const buildCsrfCookieHeader: (nonce: string) => string;
+/**
+ * `Set-Cookie` header to clear the CSRF cookie after a successful (or
+ * failed) callback. Same attributes as the set version, plus Max-Age=0.
+ * Must include `Partitioned` so the clear targets the same partitioned
+ * cookie jar the set wrote to (an unpartitioned clear would not match).
+ */
+export declare const buildCsrfCookieClearHeader: () => string;
 export {};
-//# sourceMappingURL=getAuthorizeURL.d.ts.map

package/dist/oauth/utilities/getAuthorizeURL.js

@@ -2,14 +2,21 @@ import crypto from 'crypto';
 import * as QueryString from 'qs-esm';
 import { v4 as uuid } from 'uuid';
 import { defaultScope } from '../defaults.js';
-export const getAuthorizeURL = async ({ collection, collectionOptions, endpointSlug, failedRedirect, payload, pluginOptions, redirect, serverURLOverride, strategy })=>{
+export const getAuthorizeURL = async ({ collection, collectionOptions, endpointSlug, existingCsrfNonce, failedRedirect, payload, pluginOptions, redirect, serverURLOverride, strategy })=>{
     const { redirectServerURL } = pluginOptions;
     await strategy.ensureMeta();
     // Generate a random code verifier
     const codeVerifier = crypto.randomBytes(32).toString('base64url');
     // Create a code challenge by hashing the code verifier
     const code_challenge = crypto.createHash('sha256').update(codeVerifier).digest('base64url');
+    // Nonce that goes in both `state.csrf` and the `__Host-payload-oauth-state_csrf`
+    // HttpOnly cookie. /sso/login compares the two on callback to defeat
+    // login-CSRF (RFC 6749 §10.12). Reused from the request's existing cookie
+    // when present so `/meta` is idempotent across multiple calls; otherwise
+    // freshly minted.
+    const csrfNonce = existingCsrfNonce || crypto.randomBytes(32).toString('base64url');
     const state = {
+        csrf: csrfNonce,
         sig: payload.encrypt(strategy.name),
         verifier: payload.encrypt(codeVerifier)
     };
@@ -39,7 +46,53 @@ export const getAuthorizeURL = async ({ collection, collectionOptions, endpointS
     const authorizeURL = `${strategy.meta?.authorization_endpoint}?${QueryString.stringify(params, {
         encode: false
     })}`;
-    return authorizeURL;
+    return {
+        authorizeURL,
+        csrfNonce,
+        params
+    };
 };
-
-//# sourceMappingURL=getAuthorizeURL.js.map
+/**
+ * Name of the HttpOnly cookie that carries the browser-bound CSRF nonce
+ * for the OAuth flow. The `__Host-` prefix instructs browsers to enforce:
+ * Secure, no Domain attribute (host-only), and Path=/ — which together
+ * prevent sibling subdomains from setting or overwriting it.
+ */ export const OAUTH_STATE_CSRF_COOKIE_NAME = '__Host-payload-oauth-state_csrf';
+/**
+ * Build the `Set-Cookie` header value for the CSRF cookie. SameSite=None
+ * + Secure so the cookie survives the IdP cross-site redirect back into
+ * /sso/login, AND so the iframe auto-login path works (the iframe is a
+ * third-party context from the top-level Figma page). Path=/ is required
+ * by the `__Host-` prefix.
+ *
+ * `Partitioned` (CHIPS) is required because the Make preview embeds the
+ * admin panel in a cross-site iframe. Under Chrome's third-party-cookie
+ * restrictions a `SameSite=None` cookie set in a third-party context is
+ * NOT sent back unless it is partitioned by the top-level site. Without it
+ * the `__Host-payload-oauth-state_csrf` cookie is dropped on the way back
+ * to /sso/login, the cookie↔state.csrf binding check fails, and login dies
+ * with "CSRF cookie mismatch" (intermittent sign-in loop). `__Host-` and
+ * `Partitioned` are mutually compatible.
+ */ export const buildCsrfCookieHeader = (nonce)=>[
+        `${OAUTH_STATE_CSRF_COOKIE_NAME}=${nonce}`,
+        'HttpOnly',
+        'Secure',
+        'SameSite=None',
+        'Partitioned',
+        'Path=/',
+        'Max-Age=600'
+    ].join('; ');
+/**
+ * `Set-Cookie` header to clear the CSRF cookie after a successful (or
+ * failed) callback. Same attributes as the set version, plus Max-Age=0.
+ * Must include `Partitioned` so the clear targets the same partitioned
+ * cookie jar the set wrote to (an unpartitioned clear would not match).
+ */ export const buildCsrfCookieClearHeader = ()=>[
+        `${OAUTH_STATE_CSRF_COOKIE_NAME}=`,
+        'HttpOnly',
+        'Secure',
+        'SameSite=None',
+        'Partitioned',
+        'Path=/',
+        'Max-Age=0'
+    ].join('; ');

package/dist/oauth/utilities/getCookieExpiration.d.ts

@@ -1,4 +1,3 @@
 type CookieExpires = Date | number | string | undefined;
 export declare const getCookieExpiration: (expires?: CookieExpires) => Date;
 export {};
-//# sourceMappingURL=getCookieExpiration.d.ts.map

package/dist/oauth/utilities/getCookieExpiration.js

@@ -7,5 +7,3 @@ export const getCookieExpiration = (expires)=>{
     currentTime.setSeconds(currentTime.getSeconds() + seconds);
     return currentTime;
 };
-
-//# sourceMappingURL=getCookieExpiration.js.map

package/dist/oauth/utilities/getSecondsFromTokenExp.d.ts

@@ -1,2 +1 @@
 export declare function getSecondsFromTokenExp(futureUnixTimestamp: number): number;
-//# sourceMappingURL=getSecondsFromTokenExp.d.ts.map

package/dist/oauth/utilities/getSecondsFromTokenExp.js

@@ -3,5 +3,3 @@ export function getSecondsFromTokenExp(futureUnixTimestamp) {
     ;
     return futureUnixTimestamp - now;
 }
-
-//# sourceMappingURL=getSecondsFromTokenExp.js.map

package/dist/oauth/utilities/getTokenExp.d.ts

@@ -3,4 +3,3 @@ export declare const getTokenExp: ({ debugLogger, token, }: {
     debugLogger: DebugLogger;
     token: string;
 }) => number | undefined;
-//# sourceMappingURL=getTokenExp.d.ts.map

package/dist/oauth/utilities/getTokenExp.js

@@ -16,5 +16,3 @@ export const getTokenExp = ({ debugLogger, token })=>{
     }
     return undefined;
 };
-
-//# sourceMappingURL=getTokenExp.js.map

package/dist/oauth/utilities/getUsernameField.d.ts

@@ -6,4 +6,3 @@ interface Args {
 }
 export declare const getUsernameField: ({ collection, collectionOptions, }: Args) => EmailField | TextField;
 export {};
-//# sourceMappingURL=getUsernameField.d.ts.map

package/dist/oauth/utilities/getUsernameField.js

@@ -16,5 +16,3 @@ export const getUsernameField = ({ collection, collectionOptions })=>{
     }
     return collectionOptions.usernameField;
 };
-
-//# sourceMappingURL=getUsernameField.js.map

package/dist/oauth/utilities/hasUserTokenPropsChanged.d.ts

@@ -5,4 +5,3 @@ type User = Record<string, unknown>;
  */
 export declare const hasUserTokenPropsChanged: (user: User, token: Record<string, unknown>) => boolean;
 export {};
-//# sourceMappingURL=hasUserTokenPropsChanged.d.ts.map

package/dist/oauth/utilities/hasUserTokenPropsChanged.js

@@ -21,5 +21,3 @@ function compareValues(userVal, tokenVal) {
     }
     return userVal !== tokenVal;
 }
-
-//# sourceMappingURL=hasUserTokenPropsChanged.js.map

package/dist/oauth/utilities/isAbsoluteURL.d.ts

@@ -0,0 +1 @@
+export declare const isAbsoluteURL: (url: string) => boolean;

package/dist/oauth/utilities/isAbsoluteURL.js

@@ -0,0 +1 @@
+export const isAbsoluteURL = (url)=>/^[a-z][a-z\d+.-]*:/.test(url);

package/dist/oauth/utilities/isDuplicateKeyError.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Check if an error is a duplicate key/unique constraint violation from Content API.
+ *
+ * Content API returns HTTP 409 with "conflict" or "already exists" in the message.
+ */
+export declare function isDuplicateKeyError(error: unknown): boolean;

package/dist/oauth/utilities/isDuplicateKeyError.js

@@ -0,0 +1,12 @@
+/**
+ * Check if an error is a duplicate key/unique constraint violation from Content API.
+ *
+ * Content API returns HTTP 409 with "conflict" or "already exists" in the message.
+ */ export function isDuplicateKeyError(error) {
+    if (!error || typeof error !== 'object') {
+        return false;
+    }
+    const err = error;
+    const message = typeof err.message === 'string' ? err.message : '';
+    return message.includes('409') || message.toLowerCase().includes('conflict') || message.toLowerCase().includes('already exists');
+}

package/dist/oauth/utilities/mergeHeaders.d.ts

@@ -1,2 +1 @@
 export declare function mergeHeaders(sourceHeaders: Headers, destinationHeaders: Headers): void;
-//# sourceMappingURL=mergeHeaders.d.ts.map

package/dist/oauth/utilities/mergeHeaders.js

@@ -33,5 +33,3 @@ export function mergeHeaders(sourceHeaders, destinationHeaders) {
         destinationHeaders.append(key, value);
     });
 }
-
-//# sourceMappingURL=mergeHeaders.js.map

package/dist/oauth/utilities/refreshTokens.d.ts

@@ -13,4 +13,3 @@ type Result = {
 } | false;
 export declare const refreshTokens: ({ payload, refreshToken, strategy }: Args) => Promise<Result>;
 export {};
-//# sourceMappingURL=refreshTokens.d.ts.map

package/dist/oauth/utilities/refreshTokens.js

@@ -1,10 +1,11 @@
 import { generateCookie } from 'payload';
-import { getProjectToken } from '../../api/figma-api.js';
-import { validateProjectToken } from '../../auth/jwt-validator.js';
-import { getEnvironment } from '../../constants.js';
+import { getPayloadAdminToken } from '../../api/figma-api.js';
+import { validatePayloadAdminToken } from '../../auth/jwt-validator.js';
+import { getInfraEnvironment } from '../../constants.js';
 import { createCookieOptions } from './createCookieOptions.js';
 import { createDebugLogger } from './createDebugLogger.js';
 import { getCookieExpiration } from './getCookieExpiration.js';
+import { withPartitionedCookie } from './withPartitionedCookie.js';
 export const refreshTokens = async ({ payload, refreshToken, strategy })=>{
     const debugLogger = createDebugLogger(payload, strategy.debug);
     debugLogger.info({
@@ -15,12 +16,18 @@ export const refreshTokens = async ({ payload, refreshToken, strategy })=>{
     // but refresh token is still valid
     // so we will refresh both tokens
     try {
-        // Get another project token
-        const { expiresAt, token } = await getProjectToken(refreshToken, 'someproject');
+        // Get another Payload Admin token.
+        const environmentId = payload.config.custom.figma.environmentId;
+        if (!environmentId) {
+            throw new Error('Cannot refresh Payload Admin token: environmentId is not configured');
+        }
+        const { expiresAt, token } = await getPayloadAdminToken({
+            type: 'oauth',
+            token: refreshToken
+        }, environmentId);
         debugLogger.info({
             expiresAt,
-            msg: 'Received new tokens from Figma API',
-            token
+            msg: 'Received new Payload Admin token from Figma API'
         });
         // On error, no user
         if (!token) {
@@ -31,8 +38,7 @@ export const refreshTokens = async ({ payload, refreshToken, strategy })=>{
         }
         if (token) {
             debugLogger.info({
-                msg: 'Successfully refreshed project token',
-                token
+                msg: 'Successfully refreshed Payload Admin token'
             });
             const expires_in = new Date(expiresAt);
             const cookieOptions = createCookieOptions({
@@ -47,8 +53,12 @@ export const refreshTokens = async ({ payload, refreshToken, strategy })=>{
                 returnCookieAsObject: false,
                 value: token
             });
-            headers.append('Set-Cookie', tokenCookie);
-            const decodedOauthToken = await validateProjectToken(token, getEnvironment());
+            headers.append('Set-Cookie', withPartitionedCookie(tokenCookie));
+            const decodedOauthToken = await validatePayloadAdminToken({
+                audience: environmentId,
+                environment: getInfraEnvironment(),
+                token
+            });
             return {
                 decodedOauthToken,
                 headers,
@@ -63,5 +73,3 @@ export const refreshTokens = async ({ payload, refreshToken, strategy })=>{
     }
     return false;
 };
-
-//# sourceMappingURL=refreshTokens.js.map

package/dist/oauth/utilities/withPartitionedCookie.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Append the `Partitioned` (CHIPS) attribute to a `Set-Cookie` header string.
+ *
+ * Payload's `generateCookie` cannot emit `Partitioned`, but Chrome requires it
+ * for a `SameSite=None` cookie set inside the cross-site Make-preview iframe
+ * (top-level `figma.com`, app on a different site) to be stored and sent back.
+ * Without it the session cookies are dropped, `/api/users/me` sees no token,
+ * and the admin login loops forever. The CSRF cookie avoids this by
+ * hand-building its header (`buildCsrfCookieHeader`); the session cookies go
+ * through `generateCookie`, so we add the attribute here to match.
+ *
+ * Only applied to `Secure` cookies: `Partitioned` requires `Secure`, and a
+ * partitioned non-secure cookie is rejected outright. Idempotent. The presence
+ * check matches a bare `Secure` or `generateCookie`'s `Secure=true` form, but
+ * deliberately NOT `Secure=false` — `generateCookie` never emits that today
+ * (it only writes `Secure` when truthy), but the check stays defensive so a
+ * future/hand-built `Secure=false` can't get `Partitioned` (which requires Secure).
+ */
+export declare const withPartitionedCookie: (cookie: string) => string;

package/dist/oauth/utilities/withPartitionedCookie.js

@@ -0,0 +1,26 @@
+/**
+ * Append the `Partitioned` (CHIPS) attribute to a `Set-Cookie` header string.
+ *
+ * Payload's `generateCookie` cannot emit `Partitioned`, but Chrome requires it
+ * for a `SameSite=None` cookie set inside the cross-site Make-preview iframe
+ * (top-level `figma.com`, app on a different site) to be stored and sent back.
+ * Without it the session cookies are dropped, `/api/users/me` sees no token,
+ * and the admin login loops forever. The CSRF cookie avoids this by
+ * hand-building its header (`buildCsrfCookieHeader`); the session cookies go
+ * through `generateCookie`, so we add the attribute here to match.
+ *
+ * Only applied to `Secure` cookies: `Partitioned` requires `Secure`, and a
+ * partitioned non-secure cookie is rejected outright. Idempotent. The presence
+ * check matches a bare `Secure` or `generateCookie`'s `Secure=true` form, but
+ * deliberately NOT `Secure=false` — `generateCookie` never emits that today
+ * (it only writes `Secure` when truthy), but the check stays defensive so a
+ * future/hand-built `Secure=false` can't get `Partitioned` (which requires Secure).
+ */ export const withPartitionedCookie = (cookie)=>{
+    if (!/;\s*Secure(?:=true)?(?:;|$)/i.test(cookie)) {
+        return cookie;
+    }
+    if (/;\s*Partitioned(?:=|;|$)/i.test(cookie)) {
+        return cookie;
+    }
+    return `${cookie}; Partitioned`;
+};

package/dist/oauth/utils/getSearchParam.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Retrieves a single search-parameter value from the return type of
+ * `@payloadcms/ui`'s `useSearchParams` hook.
+ *
+ * In Payload v4 the hook returns a `URLSearchParams`-like object; params are
+ * read via `.get(key)`:
+ * ```ts
+ * import { useSearchParams } from '@payloadcms/ui'
+ * const searchParams = useSearchParams()
+ * const value = searchParams.get('redirect') // string | null
+ * ```
+ *
+ * @param searchParamsHookResult - Raw return value of `useSearchParams()` from `@payloadcms/ui`.
+ * @param key - The query-string parameter name to read.
+ * @returns The first string value for `key`, or `undefined` if absent.
+ */
+export declare const getSearchParam: (searchParamsHookResult: unknown, key: string) => string | undefined;

package/dist/oauth/utils/getSearchParam.js

@@ -0,0 +1,22 @@
+/**
+ * Retrieves a single search-parameter value from the return type of
+ * `@payloadcms/ui`'s `useSearchParams` hook.
+ *
+ * In Payload v4 the hook returns a `URLSearchParams`-like object; params are
+ * read via `.get(key)`:
+ * ```ts
+ * import { useSearchParams } from '@payloadcms/ui'
+ * const searchParams = useSearchParams()
+ * const value = searchParams.get('redirect') // string | null
+ * ```
+ *
+ * @param searchParamsHookResult - Raw return value of `useSearchParams()` from `@payloadcms/ui`.
+ * @param key - The query-string parameter name to read.
+ * @returns The first string value for `key`, or `undefined` if absent.
+ */ export const getSearchParam = (searchParamsHookResult, key)=>{
+    if (searchParamsHookResult && typeof searchParamsHookResult === 'object' && 'get' in searchParamsHookResult && typeof searchParamsHookResult.get === 'function') {
+        const value = searchParamsHookResult.get(key);
+        return typeof value === 'string' ? value : undefined;
+    }
+    return undefined;
+};

package/dist/plugin/adapter.d.ts

@@ -2,4 +2,3 @@ import type { DatabaseAdapterObj } from 'payload';
 export interface FigmaContentSystemOptions {
 }
 export declare function figmaContentSystem(options?: FigmaContentSystemOptions): DatabaseAdapterObj;
-//# sourceMappingURL=adapter.d.ts.map

package/dist/plugin/adapter.js

@@ -135,5 +135,3 @@ export function figmaContentSystem(options = {}) {
         init: adapter
     };
 }
-
-//# sourceMappingURL=adapter.js.map

package/dist/plugin/auth-preflight.d.ts

@@ -0,0 +1,7 @@
+import type { TokenStore } from '../auth/token-store.js';
+/**
+ * Print a one-shot banner when the plugin is about to use `tokenStore`
+ * auth but no valid OAuth credential is present. Keeps the dev loop
+ * actionable instead of relying on per-request middleware errors.
+ */
+export declare function logMissingCliAuth(tokenStore: TokenStore): void;

package/dist/plugin/auth-preflight.js

@@ -0,0 +1,18 @@
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+/**
+ * Print a one-shot banner when the plugin is about to use `tokenStore`
+ * auth but no valid OAuth credential is present. Keeps the dev loop
+ * actionable instead of relying on per-request middleware errors.
+ */ export function logMissingCliAuth(tokenStore) {
+    if (tokenStore.hasValidOauthToken()) {
+        return;
+    }
+    const lines = [
+        'Not logged in to the Figma CLI.',
+        'Content API requests will fail until you authenticate.',
+        '',
+        `Run ${pc.cyan('npx @payloadcms/figma login')} to log in, then restart the dev server.`
+    ];
+    p.note(lines.join('\n'), pc.yellow('Figma authentication required'));
+}

package/dist/plugin/bootstrap-preflight.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Reason the Content System ID could not be resolved. Drives the
+ * banner's copy so the dev sees the specific remediation step.
+ */
+export type MissingContentSystemIdReason = {
+    environmentName: string;
+    kind: 'environment-not-found';
+    projectId: string;
+} | {
+    kind: 'network';
+    message: string;
+} | {
+    kind: 'no-config';
+} | {
+    kind: 'unauthenticated';
+};
+/**
+ * Print a banner explaining why Content System ID resolution failed and
+ * what to run next. Called just before `buildFigmaConfig` throws, so the
+ * actionable step is visible above the stack trace.
+ */
+export declare function logMissingContentSystemId(reason: MissingContentSystemIdReason): void;

package/dist/plugin/bootstrap-preflight.js

@@ -0,0 +1,43 @@
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+/**
+ * Print a banner explaining why Content System ID resolution failed and
+ * what to run next. Called just before `buildFigmaConfig` throws, so the
+ * actionable step is visible above the stack trace.
+ */ export function logMissingContentSystemId(reason) {
+    const lines = buildBody(reason);
+    p.note(lines.join('\n'), pc.yellow('Figma project not configured'));
+}
+function buildBody(reason) {
+    const loginCmd = pc.cyan('npx @payloadcms/figma login');
+    const initCmd = pc.cyan('npx @payloadcms/figma init');
+    const initForceCmd = pc.cyan('npx @payloadcms/figma init --force');
+    if (reason.kind === 'no-config') {
+        return [
+            'No Figma project configuration found.',
+            '',
+            `Run ${initCmd} to set up this project.`
+        ];
+    }
+    if (reason.kind === 'unauthenticated') {
+        return [
+            'Project config found, but you are not logged in.',
+            'Cannot fetch bootstrap data without a valid session.',
+            '',
+            `Run ${loginCmd}, then restart the dev server.`
+        ];
+    }
+    if (reason.kind === 'network') {
+        return [
+            'Could not reach the Figma API to fetch bootstrap data.',
+            `Error: ${reason.message}`,
+            '',
+            'Check your network, then restart the dev server.'
+        ];
+    }
+    return [
+        `Environment ${pc.bold(reason.environmentName)} not found for project ${pc.bold(reason.projectId)}.`,
+        '',
+        `Run ${initForceCmd} to reconfigure, or set FIGMA_ENVIRONMENT_NAME to a valid environment.`
+    ];
+}

package/dist/plugin/build-config.d.ts

@@ -1,4 +1,13 @@
 import type { Config, SanitizedConfig } from 'payload';
+/**
+ * Worker-trusted marker injected by Figma's sites-worker after it validates the
+ * X-Figma-Job-Queues-Auth-Bypass secret on a Payload jobs endpoint. The default
+ * `jobs.access.run` below honors this marker so Sinatra (async-job-workflow)
+ * can drive job runs without the bypass secret ever reaching tenant code.
+ *
+ * KEEP_IN_SYNC(cloudflare/wrangler/sites-worker/src/auth.ts): FIGMA_INTERNAL_FORWARDED_HAS_AUTH_BYPASS_HEADER
+ */
+export declare const FIGMA_INTERNAL_FORWARDED_HAS_AUTH_BYPASS_HEADER = "figma-internal-forwarded-has-auth-bypass";
 /**
  * Configuration type for Payload projects on the Figma platform.
  *
@@ -6,38 +15,41 @@ import type { Config, SanitizedConfig } from 'payload';
  * - `db`: Omitted (auto-injected by Figma platform)
  * - `secret`: Omitted (auto-injected by Figma platform)
  * - `editor`: Optional (defaults to lexicalEditor() if not provided)
+ * - `contentSystemId`: Optional (resolved automatically from env vars or bootstrap cache)
  *
  * @example
- * // Minimal config
+ * // Minimal config (contentSystemId resolved automatically)
  * const config: FigmaConfig = {
+ *   figma: {},
  *   collections: [...]
  * }
  *
  * @example
  * // With custom editor
  * const config: FigmaConfig = {
+ *   figma: {},
  *   collections: [...],
  *   editor: lexicalEditor({ features: [...] })
  * }
+ *
+ * @example
+ * // Disable Content System (use custom db)
+ * const config: FigmaConfig = {
+ *   figma: {
+ *     useContentSystem: false
+ *   },
+ *   db: mongooseAdapter({ url: process.env.DATABASE_URI }),
+ *   collections: [...]
+ * }
  */
 export type FigmaConfig = {
     editor?: Config['editor'];
 } & {
     figma: {
-        region: string;
-        tenantId: string;
+        contentSystemId?: string;
+        environmentId?: string;
+        storage?: boolean;
         useContentSystem?: boolean;
     };
 } & Omit<Config, 'db' | 'editor' | 'secret'> & Partial<Pick<Config, 'db'>>;
-/**
- * Figma platform wrapper for Payload's buildConfig.
- * Automatically injects:
- * - Figma database adapter
- * - Secret (platform-provided)
- * - Default lexicalEditor (if no custom editor specified)
- *
- * @param config - Payload configuration (db and secret omitted, editor optional)
- * @returns Promise<SanitizedConfig> - Built Payload configuration
- */
-export declare function buildConfig(config: FigmaConfig): Promise<SanitizedConfig>;
-//# sourceMappingURL=build-config.d.ts.map
+export declare function buildFigmaConfig(config: FigmaConfig): Promise<SanitizedConfig>;