# .env (NEVER commit)
FIGMA_PAT="figd_your-personal-access-token"
FIGMA_OAUTH_CLIENT_SECRET="your-oauth-secret"

# .gitignore
.env
.env.local
.env.*.local
*.pem

// Validate token exists before any API call
function getToken(): string {
  const token = process.env.FIGMA_PAT;
  if (!token) throw new Error('FIGMA_PAT is not set');
  if (!token.startsWith('figd_')) {
    console.warn('Token does not have expected figd_ prefix');
  }
  return token;
}

# PATs have a maximum 90-day lifetime
# Schedule rotation before expiry

# 1. Generate new token in Figma Settings > Personal access tokens
# 2. Test new token
curl -s -H "X-Figma-Token: ${NEW_TOKEN}" \
  https://api.figma.com/v1/me | jq '.handle'

# 3. Update environment
# For CI: gh secret set FIGMA_PAT --body "${NEW_TOKEN}"
# For production: update your secret manager

# 4. Verify old token is revoked in Figma Settings

// When creating a webhook, you provide a passcode:
// POST /v2/webhooks
// { "event_type": "FILE_UPDATE", "team_id": "...", "endpoint": "...", "passcode": "my-secret" }

// Figma sends the passcode back in the webhook payload body
interface FigmaWebhookPayload {
  event_type: string;
  passcode: string;      // Your secret, echoed back
  timestamp: string;
  file_key?: string;
  file_name?: string;
  webhook_id: string;
}

function verifyFigmaWebhook(
  payload: FigmaWebhookPayload,
  expectedPasscode: string
): boolean {
  // Timing-safe comparison to prevent timing attacks
  if (payload.passcode.length !== expectedPasscode.length) return false;

  const a = Buffer.from(payload.passcode);
  const b = Buffer.from(expectedPasscode);
  return crypto.timingSafeEqual(a, b);
}

// Express handler
app.post('/webhooks/figma', express.json(), (req, res) => {
  const payload: FigmaWebhookPayload = req.body;

  if (!verifyFigmaWebhook(payload, process.env.FIGMA_WEBHOOK_PASSCODE!)) {
    console.warn('Invalid webhook passcode');
    return res.status(401).json({ error: 'Invalid passcode' });
  }

  // Process the event
  handleFigmaEvent(payload);
  res.status(200).json({ received: true });
});

- [ ] PAT stored in environment variable, not in code
- [ ] `.env` files listed in `.gitignore`
- [ ] Token uses minimum required scopes
- [ ] Token rotation scheduled before 90-day expiry
- [ ] Webhook passcode verified on every incoming request
- [ ] OAuth client secret stored in secret manager (not repo)
- [ ] No tokens in frontend/client-side code
- [ ] Git history scanned for leaked tokens (use `git log -p | grep figd_`)
- [ ] Different tokens for dev/staging/prod environments