DevOps11 min de leitura

Arquitetura Cloud: Upload Direto para S3 e Distribuição com CloudFront

Upload direto do browser para S3 com Presigned URLs (sem passar pela API), bucket privado com Origin Access Control, invalidação de cache no CloudFront, validação de tipo MIME e IAM least-privilege.

12 de agosto de 2026

Quando sua API Node.js recebe um upload de 10MB de imagem, ela bloqueia um worker para fazer I/O de rede enquanto recebe o arquivo, processa e envia para o storage. Com 100 uploads simultâneos, isso pode paralisar completamente a API. O padrão correto é Presigned URL: a API gera uma URL temporária assinada pelo IAM, e o browser faz o upload direto para o S3 — a API nunca vê o arquivo.

Além disso, servir arquivos estáticos diretamente do S3 em us-east-1 para usuários no Brasil adiciona ~200ms de latência por arquivo. O CloudFront resolve isso com edge caching em São Paulo — a segunda requisição do mesmo arquivo é servida em milissegundos da edge location local.

Arquitetura com Presigned URL

Frontend solicita à API: POST /uploads/presigned-url com o nome e tipo do arquivo
API valida o tipo MIME, gera uma Presigned URL com expiração curta (ex: 5 minutos) e retorna para o frontend
Frontend faz o upload diretamente para o S3 usando a URL assinada — a API não processa o arquivo
Após o upload, o frontend notifica a API com a chave do objeto no S3
A API armazena a referência do arquivo no banco de dados

bash

1npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner
npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner

Essa arquitetura elimina um gargalo de I/O da API: o processo Node.js nunca precisa ler o arquivo de uma requisição multipart, nem redirecionar os bytes para o S3. A Presigned URL tem uma assinatura criptográfica gerada pelo IAM que valida o tipo de conteúdo, o bucket de destino e a chave do objeto — qualquer tentativa de desviar para outro bucket ou caminho é rejeitada pelo S3.

S3StorageProvider.ts

1import { S3Client, PutObjectCommand, DeleteObjectCommand, GetObjectCommand } from '@aws-sdk/client-s3';
import { S3Client, PutObjectCommand, DeleteObjectCommand, GetObjectCommand } from '@aws-sdk/client-s3';
2import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
3import { randomBytes } from 'crypto';
import { randomBytes } from 'crypto';
4import path from 'path';
import path from 'path';
5

6const ALLOWED_MIME_TYPES = new Set([
const ALLOWED_MIME_TYPES = new Set([
7  'image/jpeg',
  'image/jpeg',
8  'image/png',
  'image/png',
9  'image/webp',
  'image/webp',
10  'image/avif',
  'image/avif',
11  'application/pdf',
  'application/pdf',
12]);
]);
13

14const MAX_FILE_SIZE = 10 * 1024 * 1024; // 10MB
const MAX_FILE_SIZE = 10 * 1024 * 1024; // 10MB
15

16export class S3StorageProvider {
export class S3StorageProvider {
17  private client: S3Client;
  private client: S3Client;
18  private bucket: string;
  private bucket: string;
19  private cdnUrl: string;
  private cdnUrl: string;
20

21  constructor() {
  constructor() {
22    this.client = new S3Client({
    this.client = new S3Client({
23      region: process.env.AWS_REGION as string,
      region: process.env.AWS_REGION as string,
24      credentials: {
      credentials: {
25        accessKeyId: process.env.AWS_ACCESS_KEY_ID as string,
        accessKeyId: process.env.AWS_ACCESS_KEY_ID as string,
26        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY as string,
        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY as string,
27      },
      },
28    });
    });
29    this.bucket = process.env.AWS_S3_BUCKET as string;
    this.bucket = process.env.AWS_S3_BUCKET as string;
30    this.cdnUrl = process.env.CLOUDFRONT_URL as string; // Ex: https://d111.cloudfront.net
    this.cdnUrl = process.env.CLOUDFRONT_URL as string; // Ex: https://d111.cloudfront.net
31  }
  }
32

33  /**
  /**
34   * Gera uma Presigned URL para upload direto do browser para o S3.
   * Gera uma Presigned URL para upload direto do browser para o S3.
35   * A API nunca processa o arquivo — zero I/O na API.
   * A API nunca processa o arquivo — zero I/O na API.
36   */
   */
37  async generatePresignedUploadUrl({
  async generatePresignedUploadUrl({
38    filename,
    filename,
39    mimeType,
    mimeType,
40    folder = 'uploads',
    folder = 'uploads',
41  }: {
  }: {
42    filename: string;
    filename: string;
43    mimeType: string;
    mimeType: string;
44    folder?: string;
    folder?: string;
45  }): Promise<{ uploadUrl: string; key: string; publicUrl: string }> {
  }): Promise<{ uploadUrl: string; key: string; publicUrl: string }> {
46    // Valida o tipo MIME antes de gerar a URL
    // Valida o tipo MIME antes de gerar a URL
47    if (!ALLOWED_MIME_TYPES.has(mimeType)) {
    if (!ALLOWED_MIME_TYPES.has(mimeType)) {
48      throw new Error(`Tipo de arquivo não permitido: ${mimeType}`);
      throw new Error(`Tipo de arquivo não permitido: ${mimeType}`);
49    }
    }
50

51    // Gera uma chave aleatória para evitar colisões e enumeration
    // Gera uma chave aleatória para evitar colisões e enumeration
52    const uniqueId = randomBytes(16).toString('hex');
    const uniqueId = randomBytes(16).toString('hex');
53    const extension = path.extname(filename).toLowerCase();
    const extension = path.extname(filename).toLowerCase();
54    const key = `${folder}/${uniqueId}${extension}`;
    const key = `${folder}/${uniqueId}${extension}`;
55

56    const command = new PutObjectCommand({
    const command = new PutObjectCommand({
57      Bucket: this.bucket,
      Bucket: this.bucket,
58      Key: key,
      Key: key,
59      ContentType: mimeType,
      ContentType: mimeType,
60      // Metadados opcionais para rastreabilidade
      // Metadados opcionais para rastreabilidade
61      Metadata: {
      Metadata: {
62        originalFilename: encodeURIComponent(filename),
        originalFilename: encodeURIComponent(filename),
63      },
      },
64      // Restringe o tipo de conteúdo que pode ser enviado
      // Restringe o tipo de conteúdo que pode ser enviado
65      // (o browser deve enviar o header Content-Type correto)
      // (o browser deve enviar o header Content-Type correto)
66    });
    });
67

68    // URL expira em 5 minutos — tempo suficiente para o upload
    // URL expira em 5 minutos — tempo suficiente para o upload
69    const uploadUrl = await getSignedUrl(this.client, command, { expiresIn: 300 });
    const uploadUrl = await getSignedUrl(this.client, command, { expiresIn: 300 });
70

71    // URL pública via CloudFront (nunca exponha a URL do S3 diretamente)
    // URL pública via CloudFront (nunca exponha a URL do S3 diretamente)
72    const publicUrl = `${this.cdnUrl}/${key}`;
    const publicUrl = `${this.cdnUrl}/${key}`;
73

74    return { uploadUrl, key, publicUrl };
    return { uploadUrl, key, publicUrl };
75  }
  }
76

77  /**
  /**
78   * Gera uma Presigned URL para download privado (arquivos não-públicos).
   * Gera uma Presigned URL para download privado (arquivos não-públicos).
79   */
   */
80  async generatePresignedDownloadUrl(key: string, expiresIn = 3600): Promise<string> {
  async generatePresignedDownloadUrl(key: string, expiresIn = 3600): Promise<string> {
81    const command = new GetObjectCommand({ Bucket: this.bucket, Key: key });
    const command = new GetObjectCommand({ Bucket: this.bucket, Key: key });
82    return getSignedUrl(this.client, command, { expiresIn });
    return getSignedUrl(this.client, command, { expiresIn });
83  }
  }
84

85  async delete(key: string): Promise<void> {
  async delete(key: string): Promise<void> {
86    await this.client.send(
    await this.client.send(
87      new DeleteObjectCommand({ Bucket: this.bucket, Key: key })
      new DeleteObjectCommand({ Bucket: this.bucket, Key: key })
88    );
    );
89  }
  }
90}
}

O Controller valida o payload com Zod (incluindo o fileSize para rejeitar requisições de URLs para arquivos maiores que o permitido antes mesmo de gerar a URL) e organiza os uploads em pastas por usuário. A pasta users/${req.user.id} garante isolamento entre usuários e facilita auditoria de quem fez upload de quais arquivos.

UploadsController.ts

1import type { Request, Response } from 'express';
import type { Request, Response } from 'express';
2import { z } from 'zod';
import { z } from 'zod';
3import { S3StorageProvider } from '../infra/providers/storage/S3StorageProvider';
import { S3StorageProvider } from '../infra/providers/storage/S3StorageProvider';
4

5const presignedUrlSchema = z.object({
const presignedUrlSchema = z.object({
6  filename: z.string().min(1).max(255),
  filename: z.string().min(1).max(255),
7  mimeType: z.string(),
  mimeType: z.string(),
8  fileSize: z.number().int().positive().max(10 * 1024 * 1024), // Máximo 10MB
  fileSize: z.number().int().positive().max(10 * 1024 * 1024), // Máximo 10MB
9});
});
10

11export class UploadsController {
export class UploadsController {
12  private storage = new S3StorageProvider();
  private storage = new S3StorageProvider();
13

14  async requestPresignedUrl(req: Request, res: Response): Promise<void> {
  async requestPresignedUrl(req: Request, res: Response): Promise<void> {
15    const body = presignedUrlSchema.parse(req.body);
    const body = presignedUrlSchema.parse(req.body);
16

17    const result = await this.storage.generatePresignedUploadUrl({
    const result = await this.storage.generatePresignedUploadUrl({
18      filename: body.filename,
      filename: body.filename,
19      mimeType: body.mimeType,
      mimeType: body.mimeType,
20      folder: `users/${req.user.id}`,
      folder: `users/${req.user.id}`,
21    });
    });
22

23    res.json({
    res.json({
24      // URL para o frontend fazer PUT diretamente no S3
      // URL para o frontend fazer PUT diretamente no S3
25      uploadUrl: result.uploadUrl,
      uploadUrl: result.uploadUrl,
26      // Chave para referenciar no banco após o upload
      // Chave para referenciar no banco após o upload
27      key: result.key,
      key: result.key,
28      // URL pública via CloudFront para exibir após o upload
      // URL pública via CloudFront para exibir após o upload
29      publicUrl: result.publicUrl,
      publicUrl: result.publicUrl,
30    });
    });
31  }
  }
32}
}

Upload no Frontend

Frontend: upload com Presigned URL

1async function uploadFile(file: File): Promise<string> {
async function uploadFile(file: File): Promise<string> {
2  // 1. Solicita a Presigned URL à API
  // 1. Solicita a Presigned URL à API
3  const { uploadUrl, key, publicUrl } = await fetch('/api/uploads/presigned-url', {
  const { uploadUrl, key, publicUrl } = await fetch('/api/uploads/presigned-url', {
4    method: 'POST',
    method: 'POST',
5    headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
    headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
6    body: JSON.stringify({
    body: JSON.stringify({
7      filename: file.name,
      filename: file.name,
8      mimeType: file.type,
      mimeType: file.type,
9      fileSize: file.size,
      fileSize: file.size,
10    }),
    }),
11  }).then((r) => r.json());
  }).then((r) => r.json());
12

13  // 2. Faz o upload diretamente para o S3 — a API não vê este request
  // 2. Faz o upload diretamente para o S3 — a API não vê este request
14  const uploadResponse = await fetch(uploadUrl, {
  const uploadResponse = await fetch(uploadUrl, {
15    method: 'PUT',
    method: 'PUT',
16    body: file,
    body: file,
17    headers: { 'Content-Type': file.type },
    headers: { 'Content-Type': file.type },
18  });
  });
19

20  if (!uploadResponse.ok) {
  if (!uploadResponse.ok) {
21    throw new Error('Falha no upload para o S3');
    throw new Error('Falha no upload para o S3');
22  }
  }
23

24  // 3. Notifica a API da chave do arquivo
  // 3. Notifica a API da chave do arquivo
25  await fetch('/api/users/avatar', {
  await fetch('/api/users/avatar', {
26    method: 'PATCH',
    method: 'PATCH',
27    headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
    headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
28    body: JSON.stringify({ avatarKey: key }),
    body: JSON.stringify({ avatarKey: key }),
29  });
  });
30

31  return publicUrl; // URL do CloudFront para exibir imediatamente
  return publicUrl; // URL do CloudFront para exibir imediatamente
32}
}

Configuração do Bucket e CloudFront

A configuração IAM Least Privilege é um detalhe crítico frequentemente ignorado: a role do servidor que gera as Presigned URLs precisa apenas de s3:PutObject e s3:DeleteObject. Não precisa de s3:GetObject — quem lê os arquivos é o CloudFront via Origin Access Control. O bucket completamente privado garante que nenhum arquivo seja acessível diretamente pelo URL do S3, forçando todo o tráfego a passar pelo CloudFront onde você pode configurar caching, segurança e distribuição geográfica.

Bucket privado: desative 'Block all public access' para ON — nenhum acesso público direto ao S3
Origin Access Control (OAC): crie um OAC e configure o bucket policy para permitir apenas o CloudFront acessar os objetos
CloudFront: crie uma distribuição com o S3 como origin, configure o OAC, habilite HTTP/2 e HTTP/3, e configure Cache-Control headers
IAM Least Privilege: o usuário IAM da API precisa apenas de s3:PutObject e s3:DeleteObject — não de s3:GetObject ou acesso global

Bucket Policy para CloudFront OAC

1{
{
2  "Version": "2012-10-17",
  "Version": "2012-10-17",
3  "Statement": [
  "Statement": [
4    {
    {
5      "Sid": "AllowCloudFrontServicePrincipal",
      "Sid": "AllowCloudFrontServicePrincipal",
6      "Effect": "Allow",
      "Effect": "Allow",
7      "Principal": {
      "Principal": {
8        "Service": "cloudfront.amazonaws.com"
        "Service": "cloudfront.amazonaws.com"
9      },
      },
10      "Action": "s3:GetObject",
      "Action": "s3:GetObject",
11      "Resource": "arn:aws:s3:::seu-bucket/*",
      "Resource": "arn:aws:s3:::seu-bucket/*",
12      "Condition": {
      "Condition": {
13        "StringEquals": {
        "StringEquals": {
14          "AWS:SourceArn": "arn:aws:cloudfront::ACCOUNT_ID:distribution/DISTRIBUTION_ID"
          "AWS:SourceArn": "arn:aws:cloudfront::ACCOUNT_ID:distribution/DISTRIBUTION_ID"
15        }
        }
16      }
      }
17    }
    }
18  ]
  ]
19}
}

Quando você deleta ou substitui um arquivo no S3, o CloudFront ainda serve a versão antiga do cache por horas ou dias. Para forçar a atualização, crie uma invalidação no CloudFront: aws cloudfront create-invalidation --distribution-id E1234 --paths '/uploads/usuario123/*'. Isso tem custo adicional — use nomes de arquivos com hash aleatório para evitar a necessidade de invalidações.

Conclusão

Presigned URLs + S3 + CloudFront é a tríade que resolve os três problemas de upload/storage em produção: desempenho da API (uploads não passam pela API), escalabilidade (S3 suporta qualquer volume), e velocidade de entrega (CloudFront serve da edge location mais próxima do usuário). O bucket privado + OAC garante que nenhum arquivo seja acessado diretamente sem passar pelo CloudFront.