Guia Completo de Configuração CORS com Claude Code

Implementando Configuração CORS Corretamente com Claude Code

CORS (Cross-Origin Resource Sharing) é um mecanismo que controla a comunicação segura entre origens diferentes. Erros de configuração podem levar a riscos de segurança ou mau funcionamento. Com o Claude Code, você pode implementar configurações CORS adequadas aos seus requisitos com precisão.

Conceitos Básicos de CORS

Fluxo de Preflight Request

> Explique o mecanismo de preflight request do CORS.
> Inclua um diagrama de sequência.

Para “requisições não simples”, o navegador envia um preflight request com o método OPTIONS para confirmar a permissão do servidor. Isso inclui headers personalizados e requisições POST em formato JSON.

Configuração no Express.js

Configuração CORS por Ambiente

> Crie a configuração CORS do Express.js.
> Requisitos:
> - Produção permite apenas origens específicas
> - Desenvolvimento permite localhost
> - Suporte a requisições com autenticação
> - Cache de preflight

// src/middleware/cors.ts
import cors from 'cors';

const allowedOrigins: Record<string, string[]> = {
  production: [
    'https://myapp.example.com',
    'https://admin.example.com',
  ],
  development: [
    'http://localhost:3000',
    'http://localhost:5173',
  ],
};

export const corsMiddleware = cors({
  origin: (origin, callback) => {
    const env = process.env.NODE_ENV || 'development';
    const origins = allowedOrigins[env] || allowedOrigins.development;

    // Comunicação entre servidores (sem origin) é permitida
    if (!origin) return callback(null, true);

    if (origins.includes(origin)) {
      callback(null, true);
    } else {
      callback(new Error(`CORS: ${origin} não é permitido`));
    }
  },
  credentials: true,
  methods: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'],
  allowedHeaders: ['Content-Type', 'Authorization', 'X-Request-ID'],
  exposedHeaders: ['X-Total-Count', 'X-Request-ID'],
  maxAge: 86400, // Cache de preflight: 24 horas
});

Configuração no Next.js

// next.config.js
const nextConfig = {
  async headers() {
    return [
      {
        source: '/api/:path*',
        headers: [
          { key: 'Access-Control-Allow-Origin', value: 'https://myapp.example.com' },
          { key: 'Access-Control-Allow-Methods', value: 'GET,POST,PUT,DELETE' },
          { key: 'Access-Control-Allow-Headers', value: 'Content-Type,Authorization' },
          { key: 'Access-Control-Allow-Credentials', value: 'true' },
          { key: 'Access-Control-Max-Age', value: '86400' },
        ],
      },
    ];
  },
};

Configuração CORS no Nginx/CDN

> Adicione configuração CORS no proxy reverso Nginx.

location /api/ {
    if ($request_method = 'OPTIONS') {
        add_header 'Access-Control-Allow-Origin' $http_origin;
        add_header 'Access-Control-Allow-Methods' 'GET, POST, PUT, DELETE';
        add_header 'Access-Control-Allow-Headers' 'Content-Type, Authorization';
        add_header 'Access-Control-Allow-Credentials' 'true';
        add_header 'Access-Control-Max-Age' 86400;
        return 204;
    }

    add_header 'Access-Control-Allow-Origin' $http_origin always;
    add_header 'Access-Control-Allow-Credentials' 'true' always;

    proxy_pass http://backend;
}

Troubleshooting

Erros Comuns e Soluções

Ao colar erros do console do navegador no Claude Code, ele indica imediatamente a causa e o método de correção.

Exemplo de erro:

Access to XMLHttpRequest at 'https://api.example.com/data' from origin
'https://myapp.com' has been blocked by CORS policy: No
'Access-Control-Allow-Origin' header is present on the requested resource.

Causas comuns:

• Headers CORS não configurados no lado do servidor
• Usar Access-Control-Allow-Origin: * com credentials: true (é necessário especificar uma origem específica)
• Não tratar o método OPTIONS do preflight request

Observações de Segurança

Access-Control-Allow-Origin: * deve ser usado apenas em APIs públicas que não requerem autenticação. Para requisições com autenticação, é necessário especificar origens específicas e combinar com credentials: true.

Resumo

Com o Claude Code, você pode implementar configurações CORS adequadas ao ambiente com precisão e eficientizar o troubleshooting. Consulte também Configuração de Headers de Segurança Web e o Guia de Desenvolvimento de API.

Para detalhes sobre CORS, consulte MDN Web Docs - CORS.