@payloadcms/figma 0.0.1-alpha.0

package/dist/auth/oauth-flow.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/auth/oauth-flow.ts"],"sourcesContent":["import * as p from '@clack/prompts'\nimport crypto from 'crypto'\n\nimport type { TokenStore } from './token-store.js'\nimport type { FigmaTokens } from './types.js'\n\nimport { OAUTH_CONFIG } from '../config/oauth.js'\nimport { isDebug } from '../utils/is-debug.js'\nimport * as log from '../utils/log.js'\nimport { buildAuthorizationUrl, openBrowser } from './browser.js'\nimport { CallbackServer } from './callback-server.js'\nimport { generatePKCEPair } from './pkce.js'\nimport { exchangeCodeForTokens, refreshAccessToken } from './refresh.js'\n\n/**\n * Error during OAuth flow\n */\nexport class OAuthFlowError extends Error {\n  constructor(\n    message: string,\n    public cause?: Error,\n  ) {\n    super(message)\n    this.name = 'OAuthFlowError'\n  }\n}\n\n/**\n * Options for OAuth flow\n */\nexport interface OAuthFlowOptions {\n  /** OAuth2 client ID (defaults to config) */\n  clientId?: string\n  /** Callback server port (defaults to 3000) */\n  port?: number\n  /** Redirect URI (defaults to config) */\n  redirectUri?: string\n  /** OAuth scopes (defaults to config) */\n  scopes?: string[]\n  /** Callback timeout in milliseconds (defaults to 120000) */\n  timeoutMs?: number\n}\n\n/**\n * Result of OAuth flow\n */\nexport interface OAuthFlowResult {\n  /** OAuth2 tokens */\n  tokens: FigmaTokens\n  /** Figma user ID */\n  userId?: string\n}\n\n/**\n * Execute complete OAuth2 authorization flow\n *\n * This orchestrates the full OAuth flow:\n * 1. Generate PKCE pair for security\n * 2. Start local callback server\n * 3. Open browser to authorization URL\n * 4. Wait for user to authorize\n * 5. Exchange authorization code for tokens\n * 6. Store tokens securely\n *\n * @param tokenStore - Token store for persisting tokens\n * @param options - Flow configuration options\n * @returns Promise resolving to OAuth flow result\n * @throws OAuthFlowError if any step fails\n */\nexport async function executeOAuthFlow(\n  tokenStore: TokenStore,\n  options: OAuthFlowOptions = {},\n): Promise<OAuthFlowResult> {\n  // Check if OAuth flow should be mocked\n  // Default to true for OAuth (allow testing without real authentication by default)\n  const shouldMock = process.env.FIGMA_MOCK_OAUTH !== 'false'\n\n  if (shouldMock) {\n    // MOCK IMPLEMENTATION: Return mock tokens for testing\n    if (isDebug()) {\n      log.debug('Using mock OAuth flow (FIGMA_MOCK_OAUTH != \"false\")')\n    }\n    const mockTokens: FigmaTokens = {\n      accessToken: 'figt_mock_access_token_' + crypto.randomBytes(16).toString('hex'),\n      expiresAt: Date.now() + 2 * 60 * 60 * 1000, // 2 hours\n      refreshToken: 'figt_mock_refresh_token_' + crypto.randomBytes(16).toString('hex'),\n      scopes: (options.scopes || OAUTH_CONFIG.scopes) as FigmaTokens['scopes'],\n      tokenType: 'Bearer',\n    }\n\n    // Store mock tokens\n    tokenStore.setTokens(mockTokens)\n\n    return {\n      tokens: mockTokens,\n      userId: 'mock_user_123',\n    }\n  }\n\n  // REAL OAUTH IMPLEMENTATION\n  const {\n    clientId = OAUTH_CONFIG.clientId,\n    port = 3000,\n    redirectUri = OAUTH_CONFIG.redirectUri,\n    scopes = OAUTH_CONFIG.scopes,\n    timeoutMs = 120000,\n  } = options\n\n  // Generate PKCE pair for enhanced security\n  const { codeChallenge, codeChallengeMethod, codeVerifier } = generatePKCEPair()\n\n  // Generate random state for CSRF protection\n  const state = crypto.randomBytes(32).toString('base64url')\n\n  // Create callback server\n  const callbackServer = new CallbackServer({ port, timeoutMs })\n\n  try {\n    // Start waiting for callback (this starts the server and captures actual port)\n    const callbackPromise = callbackServer.waitForCallback(state)\n\n    // Wait a bit for server to start and determine actual port\n    await new Promise((resolve) => setTimeout(resolve, 100))\n\n    // Get the actual port (may differ from preferred if that was in use)\n    const actualPort = callbackServer.getActualPort()\n\n    // Build redirect URI with actual port\n    const actualRedirectUri = redirectUri.replace(/:\\d+/, `:${actualPort}`)\n\n    // Build authorization URL\n    const authUrl = buildAuthorizationUrl({\n      authorizationUrl: OAUTH_CONFIG.authorizationUrl,\n      clientId,\n      codeChallenge,\n      codeChallengeMethod,\n      redirectUri: actualRedirectUri,\n      scopes,\n      state,\n    })\n\n    // Prompt user to open browser\n    const shouldOpenBrowser = await p.confirm({\n      initialValue: true,\n      message: 'Log in or create Figma account in your browser?',\n    })\n\n    if (p.isCancel(shouldOpenBrowser)) {\n      throw new OAuthFlowError('Authentication cancelled by user')\n    }\n\n    if (shouldOpenBrowser) {\n      // Try to open browser, but don't fail if it doesn't work\n      try {\n        await openBrowser(authUrl)\n      } catch (_error) {\n        // Browser opening failed, show URL for manual opening\n        log.warning('Could not open browser automatically.')\n        log.info(`Please open this URL in your browser:`)\n        log.info(`  ${authUrl}`)\n      }\n    } else {\n      // User declined automatic opening, show URL\n      log.info(`Please open this URL manually in your browser:`)\n      log.info(`  ${authUrl}`)\n    }\n\n    // Wait for callback\n    const { code } = await callbackPromise\n\n    // Exchange authorization code for tokens\n    let tokens: FigmaTokens\n    try {\n      tokens = await exchangeCodeForTokens(code, codeVerifier, actualRedirectUri, clientId)\n    } catch (error) {\n      throw new OAuthFlowError(\n        'Failed to exchange authorization code for tokens',\n        error instanceof Error ? error : undefined,\n      )\n    }\n\n    // Store tokens\n    try {\n      tokenStore.setTokens(tokens)\n    } catch (error) {\n      throw new OAuthFlowError('Failed to store tokens', error instanceof Error ? error : undefined)\n    }\n\n    return {\n      tokens,\n      userId: tokens.userId,\n    }\n  } catch (error) {\n    // Clean up server on error\n    callbackServer.stop()\n\n    if (error instanceof OAuthFlowError) {\n      throw error\n    }\n\n    throw new OAuthFlowError(\n      `OAuth flow failed: ${error instanceof Error ? error.message : 'Unknown error'}`,\n      error instanceof Error ? error : undefined,\n    )\n  } finally {\n    // Ensure server is always stopped\n    callbackServer.stop()\n  }\n}\n\n/**\n * Get valid access token, refreshing if necessary\n *\n * Checks if stored tokens exist and are valid. If expired, automatically\n * refreshes using the refresh token. If no tokens exist, returns null.\n *\n * @param tokenStore - Token store to use\n * @returns Promise resolving to access token or null if no valid tokens\n * @throws OAuthFlowError if refresh fails\n */\nexport async function getValidAccessToken(tokenStore: TokenStore): Promise<null | string> {\n  // Check if we have valid tokens\n  if (tokenStore.hasValidTokens()) {\n    return tokenStore.getAccessToken()\n  }\n\n  // Check if we have a refresh token\n  const refreshToken = tokenStore.getRefreshToken()\n  if (!refreshToken) {\n    return null\n  }\n\n  // Try to refresh\n  try {\n    const tokens = await refreshAccessToken(refreshToken)\n    tokenStore.setTokens(tokens)\n    return tokens.accessToken\n  } catch (error) {\n    // Refresh failed - clear invalid tokens\n    tokenStore.clearTokens()\n    throw new OAuthFlowError(\n      'Failed to refresh access token',\n      error instanceof Error ? error : undefined,\n    )\n  }\n}\n"],"names":["p","crypto","OAUTH_CONFIG","isDebug","log","buildAuthorizationUrl","openBrowser","CallbackServer","generatePKCEPair","exchangeCodeForTokens","refreshAccessToken","OAuthFlowError","Error","message","cause","name","executeOAuthFlow","tokenStore","options","shouldMock","process","env","FIGMA_MOCK_OAUTH","debug","mockTokens","accessToken","randomBytes","toString","expiresAt","Date","now","refreshToken","scopes","tokenType","setTokens","tokens","userId","clientId","port","redirectUri","timeoutMs","codeChallenge","codeChallengeMethod","codeVerifier","state","callbackServer","callbackPromise","waitForCallback","Promise","resolve","setTimeout","actualPort","getActualPort","actualRedirectUri","replace","authUrl","authorizationUrl","shouldOpenBrowser","confirm","initialValue","isCancel","_error","warning","info","code","error","undefined","stop","getValidAccessToken","hasValidTokens","getAccessToken","getRefreshToken","clearTokens"],"mappings":"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"}

package/dist/auth/oauth-flow.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=oauth-flow.spec.d.ts.map

package/dist/auth/oauth-flow.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-flow.spec.d.ts","sourceRoot":"","sources":["../../src/auth/oauth-flow.spec.ts"],"names":[],"mappings":""}

package/dist/auth/oauth-flow.spec.js

@@ -0,0 +1,134 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { CallbackServer } from './callback-server.js';
+import { executeOAuthFlow, getValidAccessToken, OAuthFlowError } from './oauth-flow.js';
+import { refreshAccessToken } from './refresh.js';
+import { TokenStore } from './token-store.js';
+// Mock the refresh module
+vi.mock('./refresh.js', ()=>({
+        exchangeCodeForTokens: vi.fn(),
+        refreshAccessToken: vi.fn()
+    }));
+// Mock browser and callback server
+vi.mock('./browser.js', ()=>({
+        buildAuthorizationUrl: vi.fn(()=>'https://www.figma.com/oauth?...'),
+        openBrowser: vi.fn()
+    }));
+// Mock @clack/prompts
+vi.mock('@clack/prompts', ()=>({
+        confirm: vi.fn().mockResolvedValue(true),
+        isCancel: vi.fn().mockReturnValue(false)
+    }));
+// Create mock factory for CallbackServer
+const createMockCallbackServer = ()=>{
+    const mock = {
+        getActualPort: vi.fn().mockReturnValue(3000),
+        stop: vi.fn(),
+        waitForCallback: vi.fn()
+    };
+    return mock;
+};
+vi.mock('./callback-server.js', ()=>({
+        CallbackServer: vi.fn()
+    }));
+describe('oauth-flow', ()=>{
+    describe('getValidAccessToken', ()=>{
+        let tokenStore;
+        beforeEach(()=>{
+            tokenStore = new TokenStore({
+                configName: 'test-payloadcms-figma-oauth-flow'
+            });
+            tokenStore.clearTokens();
+        });
+        it('should return access token if valid tokens exist', async ()=>{
+            const mockTokens = {
+                accessToken: 'valid-token',
+                expiresAt: Date.now() + 3600000,
+                refreshToken: 'refresh-token'
+            };
+            tokenStore.setTokens(mockTokens);
+            const token = await getValidAccessToken(tokenStore);
+            expect(token).toBe('valid-token');
+        });
+        it('should refresh expired tokens', async ()=>{
+            const expiredTokens = {
+                accessToken: 'expired-token',
+                expiresAt: Date.now() - 1000,
+                refreshToken: 'refresh-token'
+            };
+            tokenStore.setTokens(expiredTokens);
+            const newTokens = {
+                accessToken: 'new-token',
+                expiresAt: Date.now() + 3600000,
+                refreshToken: 'new-refresh-token'
+            };
+            // Mock the refresh function
+            vi.mocked(refreshAccessToken).mockResolvedValueOnce(newTokens);
+            const token = await getValidAccessToken(tokenStore);
+            expect(token).toBe('new-token');
+            // Verify tokens were stored
+            const storedTokens = tokenStore.getTokens();
+            expect(storedTokens?.accessToken).toBe('new-token');
+        });
+        it('should clear tokens and throw on refresh failure', async ()=>{
+            const expiredTokens = {
+                accessToken: 'expired-token',
+                expiresAt: Date.now() - 1000,
+                refreshToken: 'refresh-token'
+            };
+            tokenStore.setTokens(expiredTokens);
+            // Mock refresh to fail
+            vi.mocked(refreshAccessToken).mockRejectedValueOnce(new Error('Refresh failed'));
+            await expect(getValidAccessToken(tokenStore)).rejects.toThrow(OAuthFlowError);
+            // Verify tokens were cleared
+            expect(tokenStore.getTokens()).toBeNull();
+        });
+    });
+    describe('executeOAuthFlow', ()=>{
+        let tokenStore;
+        let mockServer;
+        beforeEach(()=>{
+            tokenStore = new TokenStore({
+                configName: 'test-payloadcms-figma-oauth-execute'
+            });
+            tokenStore.clearTokens();
+            vi.clearAllMocks();
+            // Setup mock server with default pending callback
+            mockServer = createMockCallbackServer();
+            mockServer.waitForCallback.mockReturnValue(new Promise(()=>{
+            /* pending forever by default */ }));
+            vi.mocked(CallbackServer).mockImplementation(()=>mockServer);
+        });
+        it('should execute mock OAuth flow successfully (default behavior)', async ()=>{
+            const result = await executeOAuthFlow(tokenStore);
+            // Verify mock tokens were generated and stored
+            const storedTokens = tokenStore.getTokens();
+            expect(storedTokens).toBeDefined();
+            expect(storedTokens?.accessToken).toMatch(/^figt_mock_access_token_/);
+            expect(storedTokens?.refreshToken).toMatch(/^figt_mock_refresh_token_/);
+            expect(storedTokens?.tokenType).toBe('Bearer');
+            expect(storedTokens?.expiresAt).toBeGreaterThan(Date.now());
+            // Verify result
+            expect(result.tokens).toEqual(storedTokens);
+            expect(result.userId).toBe('mock_user_123');
+            // Verify callback server was NOT started (mock flow skips it)
+            expect(mockServer.waitForCallback).not.toHaveBeenCalled();
+        });
+        it('should handle callback timeout (real OAuth flow)', async ()=>{
+            // Temporarily disable mocking to test real OAuth flow error handling
+            const originalEnv = process.env.FIGMA_MOCK_OAUTH;
+            process.env.FIGMA_MOCK_OAUTH = 'false';
+            mockServer.waitForCallback.mockRejectedValueOnce(new Error('Callback timed out'));
+            await expect(executeOAuthFlow(tokenStore)).rejects.toThrow(OAuthFlowError);
+            // Server should be stopped
+            expect(mockServer.stop).toHaveBeenCalled();
+            // Restore original environment
+            if (originalEnv === undefined) {
+                delete process.env.FIGMA_MOCK_OAUTH;
+            } else {
+                process.env.FIGMA_MOCK_OAUTH = originalEnv;
+            }
+        });
+    });
+});
+
+//# sourceMappingURL=oauth-flow.spec.js.map

package/dist/auth/oauth-flow.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/auth/oauth-flow.spec.ts"],"sourcesContent":["import { beforeEach, describe, expect, it, vi } from 'vitest'\n\nimport type { FigmaTokens } from './types.js'\n\nimport { CallbackServer } from './callback-server.js'\nimport { executeOAuthFlow, getValidAccessToken, OAuthFlowError } from './oauth-flow.js'\nimport { refreshAccessToken } from './refresh.js'\nimport { TokenStore } from './token-store.js'\n\n// Mock the refresh module\nvi.mock('./refresh.js', () => ({\n  exchangeCodeForTokens: vi.fn(),\n  refreshAccessToken: vi.fn(),\n}))\n\n// Mock browser and callback server\nvi.mock('./browser.js', () => ({\n  buildAuthorizationUrl: vi.fn(() => 'https://www.figma.com/oauth?...'),\n  openBrowser: vi.fn(),\n}))\n\n// Mock @clack/prompts\nvi.mock('@clack/prompts', () => ({\n  confirm: vi.fn().mockResolvedValue(true),\n  isCancel: vi.fn().mockReturnValue(false),\n}))\n\n// Create mock factory for CallbackServer\nconst createMockCallbackServer = () => {\n  const mock = {\n    getActualPort: vi.fn().mockReturnValue(3000),\n    stop: vi.fn(),\n    waitForCallback: vi.fn(),\n  }\n  return mock\n}\n\nvi.mock('./callback-server.js', () => ({\n  CallbackServer: vi.fn(),\n}))\n\ndescribe('oauth-flow', () => {\n  describe('getValidAccessToken', () => {\n    let tokenStore: TokenStore\n\n    beforeEach(() => {\n      tokenStore = new TokenStore({ configName: 'test-payloadcms-figma-oauth-flow' })\n      tokenStore.clearTokens()\n    })\n\n    it('should return access token if valid tokens exist', async () => {\n      const mockTokens: FigmaTokens = {\n        accessToken: 'valid-token',\n        expiresAt: Date.now() + 3600000, // 1 hour from now\n        refreshToken: 'refresh-token',\n      }\n\n      tokenStore.setTokens(mockTokens)\n\n      const token = await getValidAccessToken(tokenStore)\n      expect(token).toBe('valid-token')\n    })\n\n    it('should refresh expired tokens', async () => {\n      const expiredTokens: FigmaTokens = {\n        accessToken: 'expired-token',\n        expiresAt: Date.now() - 1000, // Expired\n        refreshToken: 'refresh-token',\n      }\n\n      tokenStore.setTokens(expiredTokens)\n\n      const newTokens: FigmaTokens = {\n        accessToken: 'new-token',\n        expiresAt: Date.now() + 3600000,\n        refreshToken: 'new-refresh-token',\n      }\n\n      // Mock the refresh function\n      vi.mocked(refreshAccessToken).mockResolvedValueOnce(newTokens)\n\n      const token = await getValidAccessToken(tokenStore)\n      expect(token).toBe('new-token')\n\n      // Verify tokens were stored\n      const storedTokens = tokenStore.getTokens()\n      expect(storedTokens?.accessToken).toBe('new-token')\n    })\n\n    it('should clear tokens and throw on refresh failure', async () => {\n      const expiredTokens: FigmaTokens = {\n        accessToken: 'expired-token',\n        expiresAt: Date.now() - 1000,\n        refreshToken: 'refresh-token',\n      }\n\n      tokenStore.setTokens(expiredTokens)\n\n      // Mock refresh to fail\n      vi.mocked(refreshAccessToken).mockRejectedValueOnce(new Error('Refresh failed'))\n\n      await expect(getValidAccessToken(tokenStore)).rejects.toThrow(OAuthFlowError)\n\n      // Verify tokens were cleared\n      expect(tokenStore.getTokens()).toBeNull()\n    })\n  })\n\n  describe('executeOAuthFlow', () => {\n    let tokenStore: TokenStore\n    let mockServer: ReturnType<typeof createMockCallbackServer>\n\n    beforeEach(() => {\n      tokenStore = new TokenStore({ configName: 'test-payloadcms-figma-oauth-execute' })\n      tokenStore.clearTokens()\n      vi.clearAllMocks()\n\n      // Setup mock server with default pending callback\n      mockServer = createMockCallbackServer()\n      mockServer.waitForCallback.mockReturnValue(\n        new Promise(() => {\n          /* pending forever by default */\n        }),\n      )\n      vi.mocked(CallbackServer).mockImplementation(() => mockServer as unknown as CallbackServer)\n    })\n\n    it('should execute mock OAuth flow successfully (default behavior)', async () => {\n      const result = await executeOAuthFlow(tokenStore)\n\n      // Verify mock tokens were generated and stored\n      const storedTokens = tokenStore.getTokens()\n      expect(storedTokens).toBeDefined()\n      expect(storedTokens?.accessToken).toMatch(/^figt_mock_access_token_/)\n      expect(storedTokens?.refreshToken).toMatch(/^figt_mock_refresh_token_/)\n      expect(storedTokens?.tokenType).toBe('Bearer')\n      expect(storedTokens?.expiresAt).toBeGreaterThan(Date.now())\n\n      // Verify result\n      expect(result.tokens).toEqual(storedTokens)\n      expect(result.userId).toBe('mock_user_123')\n\n      // Verify callback server was NOT started (mock flow skips it)\n      expect(mockServer.waitForCallback).not.toHaveBeenCalled()\n    })\n\n    it('should handle callback timeout (real OAuth flow)', async () => {\n      // Temporarily disable mocking to test real OAuth flow error handling\n      const originalEnv = process.env.FIGMA_MOCK_OAUTH\n      process.env.FIGMA_MOCK_OAUTH = 'false'\n\n      mockServer.waitForCallback.mockRejectedValueOnce(new Error('Callback timed out'))\n\n      await expect(executeOAuthFlow(tokenStore)).rejects.toThrow(OAuthFlowError)\n\n      // Server should be stopped\n      expect(mockServer.stop).toHaveBeenCalled()\n\n      // Restore original environment\n      if (originalEnv === undefined) {\n        delete process.env.FIGMA_MOCK_OAUTH\n      } else {\n        process.env.FIGMA_MOCK_OAUTH = originalEnv\n      }\n    })\n  })\n})\n"],"names":["beforeEach","describe","expect","it","vi","CallbackServer","executeOAuthFlow","getValidAccessToken","OAuthFlowError","refreshAccessToken","TokenStore","mock","exchangeCodeForTokens","fn","buildAuthorizationUrl","openBrowser","confirm","mockResolvedValue","isCancel","mockReturnValue","createMockCallbackServer","getActualPort","stop","waitForCallback","tokenStore","configName","clearTokens","mockTokens","accessToken","expiresAt","Date","now","refreshToken","setTokens","token","toBe","expiredTokens","newTokens","mocked","mockResolvedValueOnce","storedTokens","getTokens","mockRejectedValueOnce","Error","rejects","toThrow","toBeNull","mockServer","clearAllMocks","Promise","mockImplementation","result","toBeDefined","toMatch","tokenType","toBeGreaterThan","tokens","toEqual","userId","not","toHaveBeenCalled","originalEnv","process","env","FIGMA_MOCK_OAUTH","undefined"],"mappings":"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"}

package/dist/auth/pages/error.html

@@ -0,0 +1,85 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <title>Figma Authentication Failed</title>
+  <style>
+    body {
+      font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+      max-width: 600px;
+      margin: 40px auto;
+      padding: 40px 20px;
+      background: #ffffff;
+      color: #000000;
+    }
+    .container {
+      text-align: center;
+    }
+    .logo {
+      margin-bottom: 32px;
+    }
+    .logo svg {
+      width: 80px;
+      height: 100px;
+      display: block;
+      margin: 0 auto;
+    }
+    .error-icon {
+      width: 64px;
+      height: 64px;
+      margin: 0 auto 24px;
+      background: #FF3737;
+      border-radius: 50%;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      font-size: 32px;
+      color: #ffffff;
+    }
+    h1 {
+      font-size: 24px;
+      font-weight: 600;
+      margin: 0 0 16px 0;
+      color: #000000;
+    }
+    p {
+      font-size: 14px;
+      line-height: 1.5;
+      color: #697485;
+      margin: 0 0 16px 0;
+    }
+    .error-code {
+      font-family: 'Monaco', 'Courier New', monospace;
+      background: #000000;
+      color: #ffffff;
+      padding: 8px 12px;
+      border-radius: 4px;
+      display: inline-block;
+      margin: 8px 0;
+    }
+    .footer {
+      margin-top: 32px;
+      font-size: 13px;
+      color: #697485;
+    }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <div class="logo">
+      <svg width="80" height="100" viewBox="0 0 1024 1280" fill="none" xmlns="http://www.w3.org/2000/svg">
+        <path d="M312 840C312 784.772 356.772 740 412 740H512V840C512 895.228 467.228 940 412 940C356.772 940 312 895.228 312 840Z" fill="#24CB71"/>
+        <path d="M512 340V540H612C667.228 540 712 495.228 712 440C712 384.772 667.228 340 612 340H512Z" fill="#FF7237"/>
+        <circle cx="611.167" cy="640" r="100" fill="#00B6FF"/>
+        <path d="M312 440C312 495.228 356.772 540 412 540H512V340H412C356.772 340 312 384.772 312 440Z" fill="#FF3737"/>
+        <path d="M312 640C312 695.228 356.772 740 412 740H512V540H412C356.772 540 312 584.772 312 640Z" fill="#874FFF"/>
+      </svg>
+    </div>
+    <div class="error-icon">✕</div>
+    <h1>Authentication Failed</h1>
+    <p>{{description}}</p>
+    {{error}}
+    <p class="footer">Please close this window and try again from your terminal.</p>
+  </div>
+</body>
+</html>

package/dist/auth/pages/success.html

@@ -0,0 +1,74 @@
+<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <title>Figma Authentication Successful</title>
+    <style>
+      body {
+        font-family:
+          'Inter',
+          -apple-system,
+          BlinkMacSystemFont,
+          'Segoe UI',
+          sans-serif;
+        max-width: 600px;
+        margin: 40px auto;
+        padding: 40px 20px;
+        background: #ffffff;
+        color: #1e1e1e;
+      }
+      .container {
+        text-align: center;
+      }
+      .logo {
+        margin-bottom: 32px;
+      }
+      .logo svg {
+        width: 80px;
+        height: 100px;
+        display: block;
+        margin: 0 auto;
+      }
+      .success-icon {
+        width: 64px;
+        height: 64px;
+        margin: 0 auto 24px;
+        background: #24CB71;
+        border-radius: 50%;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        font-size: 32px;
+        color: #ffffff;
+      }
+      h1 {
+        font-size: 24px;
+        font-weight: 600;
+        margin: 0 0 16px 0;
+        color: #000000;
+      }
+      p {
+        font-size: 14px;
+        line-height: 1.5;
+        color: #697485;
+        margin: 0;
+      }
+    </style>
+  </head>
+  <body>
+    <div class="container">
+      <div class="logo">
+        <svg width="80" height="100" viewBox="0 0 1024 1280" fill="none" xmlns="http://www.w3.org/2000/svg">
+          <path d="M312 840C312 784.772 356.772 740 412 740H512V840C512 895.228 467.228 940 412 940C356.772 940 312 895.228 312 840Z" fill="#24CB71"/>
+          <path d="M512 340V540H612C667.228 540 712 495.228 712 440C712 384.772 667.228 340 612 340H512Z" fill="#FF7237"/>
+          <circle cx="611.167" cy="640" r="100" fill="#00B6FF"/>
+          <path d="M312 440C312 495.228 356.772 540 412 540H512V340H412C356.772 340 312 384.772 312 440Z" fill="#FF3737"/>
+          <path d="M312 640C312 695.228 356.772 740 412 740H512V540H412C356.772 540 312 584.772 312 640Z" fill="#874FFF"/>
+        </svg>
+      </div>
+      <div class="success-icon">✓</div>
+      <h1>Authentication Successful</h1>
+      <p>You can now close this window and return to your terminal.</p>
+    </div>
+  </body>
+</html>

package/dist/auth/pkce.d.ts

@@ -0,0 +1,51 @@
+/**
+ * PKCE code verifier and challenge pair
+ * @see https://datatracker.ietf.org/doc/html/rfc7636
+ */
+export interface PKCEPair {
+    /** SHA256 hash of verifier, base64url encoded (without padding) */
+    codeChallenge: string;
+    /** Challenge method (always S256 for SHA256) */
+    codeChallengeMethod: 'S256';
+    /** Random code verifier (43-128 characters from [A-Z, a-z, 0-9, -, ., _, ~]) */
+    codeVerifier: string;
+}
+/**
+ * Generate a cryptographically random PKCE code verifier
+ *
+ * Creates a high-entropy random string suitable for use as an OAuth 2.0 PKCE code verifier.
+ * The verifier must be 43-128 characters and use only [A-Z, a-z, 0-9, -, ., _, ~].
+ *
+ * @returns Random code verifier string (43 characters from 32 random bytes)
+ * @see https://datatracker.ietf.org/doc/html/rfc7636#section-4.1
+ */
+export declare function generateCodeVerifier(): string;
+/**
+ * Generate code challenge from verifier using S256 method
+ *
+ * Creates a SHA256 hash of the code verifier and encodes it in base64url format.
+ * Formula: challenge = BASE64URL(SHA256(ASCII(code_verifier)))
+ *
+ * @param verifier - The code verifier to hash
+ * @returns Code challenge string (43 characters)
+ * @see https://datatracker.ietf.org/doc/html/rfc7636#section-4.2
+ */
+export declare function generateCodeChallenge(verifier: string): string;
+/**
+ * Generate complete PKCE pair for OAuth flow
+ *
+ * Creates both a code verifier and its corresponding code challenge.
+ * Use this at the start of an OAuth flow:
+ * 1. Generate pair
+ * 2. Store verifier securely (needed for token exchange)
+ * 3. Send challenge in authorization request
+ * 4. Send verifier in token exchange request
+ *
+ * @returns Complete PKCE pair with verifier, challenge, and method
+ * @example
+ * const { codeVerifier, codeChallenge, codeChallengeMethod } = generatePKCEPair()
+ * // Store codeVerifier for later
+ * // Include codeChallenge and codeChallengeMethod in authorization URL
+ */
+export declare function generatePKCEPair(): PKCEPair;
+//# sourceMappingURL=pkce.d.ts.map

package/dist/auth/pkce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pkce.d.ts","sourceRoot":"","sources":["../../src/auth/pkce.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB,mEAAmE;IACnE,aAAa,EAAE,MAAM,CAAA;IACrB,gDAAgD;IAChD,mBAAmB,EAAE,MAAM,CAAA;IAC3B,gFAAgF;IAChF,YAAY,EAAE,MAAM,CAAA;CACrB;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAK7C;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAG9D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,IAAI,QAAQ,CAS3C"}

package/dist/auth/pkce.js

@@ -0,0 +1,71 @@
+import crypto from 'crypto';
+/**
+ * Generate a cryptographically random PKCE code verifier
+ *
+ * Creates a high-entropy random string suitable for use as an OAuth 2.0 PKCE code verifier.
+ * The verifier must be 43-128 characters and use only [A-Z, a-z, 0-9, -, ., _, ~].
+ *
+ * @returns Random code verifier string (43 characters from 32 random bytes)
+ * @see https://datatracker.ietf.org/doc/html/rfc7636#section-4.1
+ */ export function generateCodeVerifier() {
+    // Generate 32 random bytes (256 bits of entropy)
+    // This will produce a 43-character base64url string
+    const buffer = crypto.randomBytes(32);
+    return base64UrlEncode(buffer);
+}
+/**
+ * Generate code challenge from verifier using S256 method
+ *
+ * Creates a SHA256 hash of the code verifier and encodes it in base64url format.
+ * Formula: challenge = BASE64URL(SHA256(ASCII(code_verifier)))
+ *
+ * @param verifier - The code verifier to hash
+ * @returns Code challenge string (43 characters)
+ * @see https://datatracker.ietf.org/doc/html/rfc7636#section-4.2
+ */ export function generateCodeChallenge(verifier) {
+    const hash = crypto.createHash('sha256').update(verifier).digest();
+    return base64UrlEncode(hash);
+}
+/**
+ * Generate complete PKCE pair for OAuth flow
+ *
+ * Creates both a code verifier and its corresponding code challenge.
+ * Use this at the start of an OAuth flow:
+ * 1. Generate pair
+ * 2. Store verifier securely (needed for token exchange)
+ * 3. Send challenge in authorization request
+ * 4. Send verifier in token exchange request
+ *
+ * @returns Complete PKCE pair with verifier, challenge, and method
+ * @example
+ * const { codeVerifier, codeChallenge, codeChallengeMethod } = generatePKCEPair()
+ * // Store codeVerifier for later
+ * // Include codeChallenge and codeChallengeMethod in authorization URL
+ */ export function generatePKCEPair() {
+    const codeVerifier = generateCodeVerifier();
+    const codeChallenge = generateCodeChallenge(codeVerifier);
+    return {
+        codeChallenge,
+        codeChallengeMethod: 'S256',
+        codeVerifier
+    };
+}
+/**
+ * Base64URL encode without padding (RFC 7636 requirement)
+ *
+ * Converts a buffer to base64url format by:
+ * 1. Base64 encoding
+ * 2. Replacing + with -
+ * 3. Replacing / with _
+ * 4. Removing = padding
+ *
+ * This format is URL-safe and required by OAuth 2.0 PKCE spec.
+ *
+ * @param buffer - Buffer to encode
+ * @returns Base64url encoded string (no padding)
+ * @see https://datatracker.ietf.org/doc/html/rfc7636#appendix-A
+ */ function base64UrlEncode(buffer) {
+    return buffer.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
+}
+
+//# sourceMappingURL=pkce.js.map

package/dist/auth/pkce.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/auth/pkce.ts"],"sourcesContent":["import crypto from 'crypto'\n\n/**\n * PKCE code verifier and challenge pair\n * @see https://datatracker.ietf.org/doc/html/rfc7636\n */\nexport interface PKCEPair {\n  /** SHA256 hash of verifier, base64url encoded (without padding) */\n  codeChallenge: string\n  /** Challenge method (always S256 for SHA256) */\n  codeChallengeMethod: 'S256'\n  /** Random code verifier (43-128 characters from [A-Z, a-z, 0-9, -, ., _, ~]) */\n  codeVerifier: string\n}\n\n/**\n * Generate a cryptographically random PKCE code verifier\n *\n * Creates a high-entropy random string suitable for use as an OAuth 2.0 PKCE code verifier.\n * The verifier must be 43-128 characters and use only [A-Z, a-z, 0-9, -, ., _, ~].\n *\n * @returns Random code verifier string (43 characters from 32 random bytes)\n * @see https://datatracker.ietf.org/doc/html/rfc7636#section-4.1\n */\nexport function generateCodeVerifier(): string {\n  // Generate 32 random bytes (256 bits of entropy)\n  // This will produce a 43-character base64url string\n  const buffer = crypto.randomBytes(32)\n  return base64UrlEncode(buffer)\n}\n\n/**\n * Generate code challenge from verifier using S256 method\n *\n * Creates a SHA256 hash of the code verifier and encodes it in base64url format.\n * Formula: challenge = BASE64URL(SHA256(ASCII(code_verifier)))\n *\n * @param verifier - The code verifier to hash\n * @returns Code challenge string (43 characters)\n * @see https://datatracker.ietf.org/doc/html/rfc7636#section-4.2\n */\nexport function generateCodeChallenge(verifier: string): string {\n  const hash = crypto.createHash('sha256').update(verifier).digest()\n  return base64UrlEncode(hash)\n}\n\n/**\n * Generate complete PKCE pair for OAuth flow\n *\n * Creates both a code verifier and its corresponding code challenge.\n * Use this at the start of an OAuth flow:\n * 1. Generate pair\n * 2. Store verifier securely (needed for token exchange)\n * 3. Send challenge in authorization request\n * 4. Send verifier in token exchange request\n *\n * @returns Complete PKCE pair with verifier, challenge, and method\n * @example\n * const { codeVerifier, codeChallenge, codeChallengeMethod } = generatePKCEPair()\n * // Store codeVerifier for later\n * // Include codeChallenge and codeChallengeMethod in authorization URL\n */\nexport function generatePKCEPair(): PKCEPair {\n  const codeVerifier = generateCodeVerifier()\n  const codeChallenge = generateCodeChallenge(codeVerifier)\n\n  return {\n    codeChallenge,\n    codeChallengeMethod: 'S256',\n    codeVerifier,\n  }\n}\n\n/**\n * Base64URL encode without padding (RFC 7636 requirement)\n *\n * Converts a buffer to base64url format by:\n * 1. Base64 encoding\n * 2. Replacing + with -\n * 3. Replacing / with _\n * 4. Removing = padding\n *\n * This format is URL-safe and required by OAuth 2.0 PKCE spec.\n *\n * @param buffer - Buffer to encode\n * @returns Base64url encoded string (no padding)\n * @see https://datatracker.ietf.org/doc/html/rfc7636#appendix-A\n */\nfunction base64UrlEncode(buffer: Buffer): string {\n  return buffer.toString('base64').replace(/\\+/g, '-').replace(/\\//g, '_').replace(/=/g, '')\n}\n"],"names":["crypto","generateCodeVerifier","buffer","randomBytes","base64UrlEncode","generateCodeChallenge","verifier","hash","createHash","update","digest","generatePKCEPair","codeVerifier","codeChallenge","codeChallengeMethod","toString","replace"],"mappings":"AAAA,OAAOA,YAAY,SAAQ;AAe3B;;;;;;;;CAQC,GACD,OAAO,SAASC;IACd,iDAAiD;IACjD,oDAAoD;IACpD,MAAMC,SAASF,OAAOG,WAAW,CAAC;IAClC,OAAOC,gBAAgBF;AACzB;AAEA;;;;;;;;;CASC,GACD,OAAO,SAASG,sBAAsBC,QAAgB;IACpD,MAAMC,OAAOP,OAAOQ,UAAU,CAAC,UAAUC,MAAM,CAACH,UAAUI,MAAM;IAChE,OAAON,gBAAgBG;AACzB;AAEA;;;;;;;;;;;;;;;CAeC,GACD,OAAO,SAASI;IACd,MAAMC,eAAeX;IACrB,MAAMY,gBAAgBR,sBAAsBO;IAE5C,OAAO;QACLC;QACAC,qBAAqB;QACrBF;IACF;AACF;AAEA;;;;;;;;;;;;;;CAcC,GACD,SAASR,gBAAgBF,MAAc;IACrC,OAAOA,OAAOa,QAAQ,CAAC,UAAUC,OAAO,CAAC,OAAO,KAAKA,OAAO,CAAC,OAAO,KAAKA,OAAO,CAAC,MAAM;AACzF"}

package/dist/auth/pkce.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=pkce.spec.d.ts.map

package/dist/auth/pkce.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pkce.spec.d.ts","sourceRoot":"","sources":["../../src/auth/pkce.spec.ts"],"names":[],"mappings":""}

package/dist/auth/pkce.spec.js

@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest';
+import { generateCodeChallenge, generatePKCEPair } from './pkce.js';
+describe('generateCodeChallenge', ()=>{
+    it('should generate consistent challenge for same verifier', ()=>{
+        const verifier = 'test-verifier-123456789012345678901234567890';
+        const challenge1 = generateCodeChallenge(verifier);
+        const challenge2 = generateCodeChallenge(verifier);
+        expect(challenge1).toBe(challenge2);
+    });
+    it('should generate different challenges for different verifiers', ()=>{
+        const verifier1 = 'test-verifier-1';
+        const verifier2 = 'test-verifier-2';
+        const challenge1 = generateCodeChallenge(verifier1);
+        const challenge2 = generateCodeChallenge(verifier2);
+        expect(challenge1).not.toBe(challenge2);
+    });
+});
+describe('generatePKCEPair', ()=>{
+    it('should generate a complete PKCE pair', ()=>{
+        const pair = generatePKCEPair();
+        expect(pair).toHaveProperty('codeVerifier');
+        expect(pair).toHaveProperty('codeChallenge');
+        expect(pair).toHaveProperty('codeChallengeMethod');
+    });
+    it('should generate challenge derived from verifier', ()=>{
+        const pair = generatePKCEPair();
+        const derivedChallenge = generateCodeChallenge(pair.codeVerifier);
+        expect(pair.codeChallenge).toBe(derivedChallenge);
+    });
+});
+
+//# sourceMappingURL=pkce.spec.js.map

package/dist/auth/pkce.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/auth/pkce.spec.ts"],"sourcesContent":["import { describe, expect, it } from 'vitest'\n\nimport { generateCodeChallenge, generatePKCEPair } from './pkce.js'\n\ndescribe('generateCodeChallenge', () => {\n  it('should generate consistent challenge for same verifier', () => {\n    const verifier = 'test-verifier-123456789012345678901234567890'\n    const challenge1 = generateCodeChallenge(verifier)\n    const challenge2 = generateCodeChallenge(verifier)\n    expect(challenge1).toBe(challenge2)\n  })\n\n  it('should generate different challenges for different verifiers', () => {\n    const verifier1 = 'test-verifier-1'\n    const verifier2 = 'test-verifier-2'\n    const challenge1 = generateCodeChallenge(verifier1)\n    const challenge2 = generateCodeChallenge(verifier2)\n    expect(challenge1).not.toBe(challenge2)\n  })\n})\n\ndescribe('generatePKCEPair', () => {\n  it('should generate a complete PKCE pair', () => {\n    const pair = generatePKCEPair()\n\n    expect(pair).toHaveProperty('codeVerifier')\n    expect(pair).toHaveProperty('codeChallenge')\n    expect(pair).toHaveProperty('codeChallengeMethod')\n  })\n\n  it('should generate challenge derived from verifier', () => {\n    const pair = generatePKCEPair()\n    const derivedChallenge = generateCodeChallenge(pair.codeVerifier)\n    expect(pair.codeChallenge).toBe(derivedChallenge)\n  })\n})\n"],"names":["describe","expect","it","generateCodeChallenge","generatePKCEPair","verifier","challenge1","challenge2","toBe","verifier1","verifier2","not","pair","toHaveProperty","derivedChallenge","codeVerifier","codeChallenge"],"mappings":"AAAA,SAASA,QAAQ,EAAEC,MAAM,EAAEC,EAAE,QAAQ,SAAQ;AAE7C,SAASC,qBAAqB,EAAEC,gBAAgB,QAAQ,YAAW;AAEnEJ,SAAS,yBAAyB;IAChCE,GAAG,0DAA0D;QAC3D,MAAMG,WAAW;QACjB,MAAMC,aAAaH,sBAAsBE;QACzC,MAAME,aAAaJ,sBAAsBE;QACzCJ,OAAOK,YAAYE,IAAI,CAACD;IAC1B;IAEAL,GAAG,gEAAgE;QACjE,MAAMO,YAAY;QAClB,MAAMC,YAAY;QAClB,MAAMJ,aAAaH,sBAAsBM;QACzC,MAAMF,aAAaJ,sBAAsBO;QACzCT,OAAOK,YAAYK,GAAG,CAACH,IAAI,CAACD;IAC9B;AACF;AAEAP,SAAS,oBAAoB;IAC3BE,GAAG,wCAAwC;QACzC,MAAMU,OAAOR;QAEbH,OAAOW,MAAMC,cAAc,CAAC;QAC5BZ,OAAOW,MAAMC,cAAc,CAAC;QAC5BZ,OAAOW,MAAMC,cAAc,CAAC;IAC9B;IAEAX,GAAG,mDAAmD;QACpD,MAAMU,OAAOR;QACb,MAAMU,mBAAmBX,sBAAsBS,KAAKG,YAAY;QAChEd,OAAOW,KAAKI,aAAa,EAAER,IAAI,CAACM;IAClC;AACF"}

package/dist/auth/project-token.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Project Token Management
+ *
+ * Handles project token (JWT) generation and refresh for authenticating
+ * to the Content API. Project tokens are scoped to a specific tenant/CMS
+ * and have a shorter lifespan (15-30 minutes) than OAuth tokens.
+ */
+import type { TokenStore } from './token-store.js';
+/**
+ * Error during project token operations
+ */
+export declare class ProjectTokenError extends Error {
+    cause?: Error | undefined;
+    constructor(message: string, cause?: Error | undefined);
+}
+/**
+ * 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
+ *
+ * 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
+ * @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>;
+/**
+ * Refresh a project token for a tenant
+ *
+ * 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.
+ *
+ * @param tokenStore - Token store for persisting tokens
+ * @param tenantId - The tenant/CMS ID to refresh token for
+ * @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

package/dist/auth/project-token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-token.d.ts","sourceRoot":"","sources":["../../src/auth/project-token.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAUlD;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAGjC,KAAK,CAAC,EAAE,KAAK;gBADpB,OAAO,EAAE,MAAM,EACR,KAAK,CAAC,EAAE,KAAK,YAAA;CAKvB;AAkCD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,GAAG,MAAM,CAAC,CAmExB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CACvC,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,GAAG,MAAM,CAAC,CAMxB"}