File Storage

O File Storage guarda os arquivos dos seus clientes sem que eles passem pelo seu servidor. Você pede uma URL de upload, entrega essa URL ao navegador ou ao aplicativo, e o arquivo vai direto para o armazenamento. Sua aplicação fica com o registro: qual arquivo é, de qual empresa, a qual negócio ele pertence e se o envio foi mesmo concluído.

Na prática ele resolve o anexo. Uma financeira que pede RG, comprovante de residência e comprovante de renda em toda proposta não precisa construir infraestrutura de upload, nem dimensionar servidor para aguentar quinhentos PDFs simultâneos, nem escrever a política de acesso que impede o parceiro A de baixar o documento do parceiro B.

Está no catálogo desde novembro de 2025, roda como serviço próprio em staging e em produção sobre S3 ou MinIO, e é irmão declarado do data-store: aquele guarda documentos JSON estruturados, este guarda bytes.

flowchart LR
  Cliente["Navegador ou app<br/>do seu cliente"]
  App["Sua aplicação"]
  FS["File Storage<br/>registra e assina"]
  S3["S3 ou MinIO<br/>os bytes moram aqui"]

  App -->|"1. pede a URL de upload"| FS
  FS -->|"2. uploadUrl + expiresAt"| App
  App -->|"3. entrega a URL"| Cliente
  Cliente ==>|"4. PUT dos bytes, sem passar pelo seu servidor"| S3
  App -->|"5. confirm-upload"| FS
  FS -->|"6. HEAD no objeto"| S3

O cenário. Todo produto B2B acaba precisando receber arquivo. Documento de identidade, comprovante, contrato assinado, foto de garantia, planilha de importação. Parece o pedaço trivial do sistema e é o pedaço que mais dá problema.

O desenho intuitivo — o arquivo chega no seu servidor e ele reenvia — é o que cobra a conta depois:

flowchart LR
  U["Usuário"] -->|"1. envia o arquivo"| API["Seu servidor de API"]
  API -->|"2. reenvia os mesmos bytes"| S["Armazenamento"]
  API -->|"3. responde"| U
  API --> Mem["Memória e conexão ocupadas<br/>pelo tráfego de arquivo"]
  Mem --> Pico["Pico de upload derruba rota<br/>que nada tem a ver com arquivo"]
  API --> Banda["Banda paga duas vezes:<br/>entrada e saída"]

O que trava hoje.

• O arquivo passa pelo seu servidor sem precisar. O upload chega no seu processo, ocupa memória, ocupa conexão, e o servidor que deveria responder chamada de API vira roteador de bytes. Um pico de envio simultâneo derruba o que não tem nada a ver com upload.
• A conta de saída aparece depois. Armazenar é barato. Devolver o arquivo ao usuário é o que custa: no S3 Standard, US$ 0,09 por GB de saída para a internet (tabela oficial da AWS, consultada em 2026-08-16). Um produto que entrega documento de volta ao cliente paga mais por banda do que por disco, e quase ninguém modela isso antes.
• Bucket por cliente não escala. É a saída intuitiva para isolar empresas e a que mais custa: política de acesso por bucket, limite de bucket por conta, e um provisionamento novo a cada cliente que entra.
• O controle de acesso vira código repetido. "Este usuário pode baixar este arquivo?" é uma pergunta que cada serviço responde de um jeito, e o terceiro esquece de perguntar.
• Ninguém sabe se o upload terminou. Sem confirmação, o banco fica cheio de registro de arquivo que nunca chegou, e o suporte descobre isso quando o cliente reclama que o documento sumiu.

O custo de não resolver. A parte mensurável é a fatura de saída, que só aparece quando o produto já está em escala.

A parte cara é a outra: cada serviço que precisa de anexo reimplementa upload, confirmação e autorização.

Seu servidor não carrega byte. A aplicação só assina a URL. O upload e o download acontecem entre o cliente e o armazenamento, o que tira do seu dimensionamento o tráfego de arquivo inteiro.

O tenant está no caminho do objeto. A chave gravada é {organizationId}/{fileId}/{nome}. O identificador da empresa não é só uma coluna consultada — ele é o prefixo físico do objeto, o que torna auditoria, expurgo por cliente e política por prefixo operações diretas.

flowchart LR
  Org["organizationId<br/>vem do token do IAM"] --> K
  Fid["fileId<br/>gerado no registro"] --> K
  Nome["name<br/>informado na criação"] --> K
  K["s3Key = organizationId / fileId / nome"] --> Obj["Objeto no bucket único"]
  K --> Uso["Listar, expurgar e aplicar política<br/>por prefixo de um cliente inteiro"]

A confirmação é verificada, não declarada. confirm-upload faz HEAD no objeto antes de marcar uploaded: true. Se o arquivo não chegou, a chamada falha com 400. Também é daí que sai o tamanho real gravado, não o que o cliente declarou.

Metadado de negócio junto do arquivo. Cada arquivo carrega businessId e category, e a listagem filtra por eles. "Todos os comprovantes de renda da proposta 123" é uma chamada, não uma varredura.

Chamada entre serviços resolve sozinha o endereço certo. Um building block que faz o transporte dos bytes por conta própria recebe a URL assinada contra o endpoint interno do cluster; um cliente externo recebe a pública. A decisão é automática, baseada na identidade de quem chamou.

flowchart LR
  Dentro["Consumidor de dentro do cluster<br/>outro building block, pelo facade"] --> FS["File Storage"]
  Fora["Cliente externo<br/>navegador, app, integração"] --> FS
  FS -->|"URL assinada contra o endpoint interno"| Ei["Armazenamento, endereço do cluster"]
  FS -->|"URL assinada contra o endpoint público"| Ep["Armazenamento, endereço público"]

Panorama

O armazenamento de objetos virou commodity, e a disputa migrou para dois lugares. O primeiro é o preço de saída: a Cloudflare construiu o R2 em cima de "zero egresso" e a Backblaze oferece franquia generosa, enquanto o S3 e o Supabase Storage cobram na faixa de US$ 0,09 por GB. O segundo é a camada de aplicação: serviços como o Uploadthing não vendem disco, vendem a experiência de subir arquivo sem escrever infraestrutura.

flowchart TD
  M["Mercado de armazenamento de objetos"] --> P1["Disputa 1 — preço de saída"]
  M --> P2["Disputa 2 — camada de aplicação"]
  P1 --> R2["Cloudflare R2 — zero egresso"]
  P1 --> BB["Backblaze B2 — franquia generosa"]
  P1 --> S3P["Amazon S3 e Supabase — cerca de US$ 0,09 por GB"]
  P2 --> UT["Uploadthing — upload pronto para um app"]
  P2 --> FS["Catalisa File Storage — upload de uma plataforma multi-tenant"]

O File Storage está no segundo grupo, com um recorte diferente: ele não é a camada de upload de um app, é a camada de upload de uma plataforma multi-tenant. A pergunta que ele responde não é "como faço upload rápido", é "como faço upload de trinta empresas clientes no mesmo armazenamento sem misturar nada".

Tabela comparativa

Preços consultados nas páginas oficiais em 2026-08-16. Confira a tabela do fornecedor na data da sua análise.

Nossos diferenciais

1. O tenant está no caminho do objeto, não só na consulta. A chave é {organizationId}/{fileId}/{nome}. Isso muda o que é possível operacionalmente: listar tudo de um cliente, expurgar um cliente inteiro ou aplicar política por prefixo passam a ser operações de armazenamento, não varreduras de banco.
2. A escolha do fornecedor continua com o cliente. Falamos a API do S3 e não presumimos AWS. Quem tem tráfego de saída pesado pode apontar para o R2 e zerar essa linha da fatura sem trocar uma linha de código — a economia do produto muda, a integração não.
3. A URL certa para quem chama, sem configuração. Consumidor de dentro do cluster recebe URL assinada contra o endpoint interno; cliente externo recebe a pública. A decisão vem da identidade de quem chamou, é determinística e não depende de variável por ambiente. Quem já depurou "funciona local, falha no cluster" sabe o tamanho disso.
4. Vem com o resto da plataforma. O mesmo token, as mesmas permissões, os mesmos eventos. Um arquivo enviado aqui dispara file-storage.file.uploaded, que o Webhooks Engine entrega ao sistema do cliente e o Audit Trail registra.

Quando escolher o concorrente

Há quatro situações em que a resposta honesta é "não use o File Storage":

O File Storage ganha quando o problema é anexo de negócio dentro de uma plataforma multi-tenant, integrado ao resto do catálogo.

Unidade de cobrança

GB armazenado por mês. É a unidade que o cliente entende e que aparece na fatura de qualquer provedor de armazenamento, o que torna a comparação honesta.

O que dispara custo

Três drivers: volume armazenado, número de uploads (operações de escrita são cobradas por milhão em todos os provedores) e transferência de saída. O terceiro é o que costuma surpreender.

flowchart LR
  V["Volume armazenado<br/>GB por mês"] --> C["Fatura"]
  U["Número de uploads<br/>operações de escrita"] --> C
  S["Transferência de saída<br/>GB devolvidos ao usuário"] --> C
  S --> Surpresa["O driver que costuma surpreender"]

Custo de referência dos provedores

Cenário nomeado: 500 GB armazenados, 50 mil uploads por mês e 1 TB de saída por mês, uma operação que recebe documento e o devolve para consulta.

Valores em dólares, consultados nas páginas oficiais em 2026-08-16, sem impostos e sem descontos negociados. As somas são aritmética simples sobre esses preços, para ordem de grandeza em conversa comercial — não são proposta e não substituem a calculadora do fornecedor.

ROI

A conta tem três partes, e a segunda costuma ser a maior.

• A escolha de fornecedor que o building block permite. No cenário acima, a diferença entre apontar para o S3 e apontar para o R2 é da ordem de US$ 87 por mês em uma operação pequena, quase toda em saída. Como a troca é configuração, essa decisão pode ser revisada quando o volume mudar, em vez de virar dívida de arquitetura.
• A engenharia que não é gasta. Construir upload direto ao armazenamento com URL pré-assinada, confirmação verificada, isolamento por cliente e trilha de eventos é da ordem de duas a quatro semanas de trabalho — estimativa interna — por serviço que precisa de anexo. Numa plataforma com vários building blocks que anexam arquivo, esse trabalho acontece uma vez.
• O servidor que não é dimensionado. Retirar o tráfego de arquivo do processo de aplicação evita réplicas que existem só para aguentar pico de upload. No Caso 1, são cerca de 24 GB por dia que deixam de passar pelo backend.

Camadas e caminho da requisição

Quatro camadas, e o corte que importa: o Postgres guarda só metadados, os bytes moram no armazenamento de objetos.

flowchart TD
  HTTP["Requisição HTTP"] --> App

  subgraph App["Hono app — basePath /file-storage"]
    R1["/api/v1/files — filesRouter"]
    R2["/health — sonda de saúde"]
    MW["authMiddleware → requirePermission(FILES_*)<br/>→ requireOrganization → parse Zod → handleResult"]
    PID["partnerId = user.organizationId — NUNCA vem do corpo"]
  end

  App -->|"ResultAsync&lt;T, AppError&gt;"| Svc

  subgraph Svc["services/FileService"]
    S1["monta a chave organizationId / fileId / nome"]
    S2["pede a URL assinada · confirma com HEAD · publica eventos"]
  end

  Svc --> Repo["repositories/FileRepository<br/>(Prisma)"]
  Svc --> S3S["shared/lib/S3Service<br/>assina URL de upload e de download (SigV4)"]

  Repo --> PG["Postgres<br/>schema storage · tabela files<br/>(só metadados)"]
  S3S --> OBJ["S3 · MinIO · qualquer armazenamento<br/>compatível com a API do S3<br/>(os bytes moram aqui)"]

O byte nunca atravessa a aplicação

Este é o fluxo completo da URL pré-assinada, do registro à confirmação. Repare que só as setas 1, 2, 5 e 6 falam com o building block — as setas 3 e 4 são o cliente conversando direto com o armazenamento.

sequenceDiagram
    autonumber
    participant C as Cliente (navegador, app ou serviço)
    participant FS as File Storage
    participant DB as Postgres (schema storage)
    participant S3 as S3 / MinIO

    C->>FS: POST /file-storage/api/v1/files
    FS->>S3: assina a URL de upload para a chave organizationId/fileId/nome
    FS->>DB: cria a linha com uploaded = false
    FS-->>C: 201 com data, uploadUrl e expiresAt
    C->>S3: PUT na uploadUrl com os bytes e o Content-Type declarado
    S3-->>C: 200
    C->>FS: POST /file-storage/api/v1/files/{fileId}/confirm-upload
    FS->>S3: HEAD no objeto
    S3-->>FS: existe, com o contentLength real
    FS->>DB: uploaded = true e sizeBytes medido
    FS-->>C: 200 com o arquivo confirmado
    C->>FS: GET /file-storage/api/v1/files/{fileId}/download-url
    FS-->>C: downloadUrl e expiresAt
    C->>S3: GET na downloadUrl
    S3-->>C: os bytes

Decisões não óbvias

• Duas rotas para a URL de upload, de propósito. POST /files cria o registro e devolve a URL na mesma resposta, o que resolve o caso comum em uma chamada. GET /files/:id/upload-url gera outra URL para um registro que já existe — é o caminho para reenviar depois que a primeira expirou, sem criar registro duplicado.
• A confirmação faz HEAD no objeto em vez de confiar no cliente. Marcar uploaded: true porque o cliente disse que enviou produz registro fantasma. O HEAD também é a fonte do tamanho real: sizeBytes enviado na criação é declaração, o gravado na confirmação é medição.
• Dois clientes S3 no processo, um interno e um público. As URLs pré-assinadas normalmente são assinadas contra o endpoint público (S3_PUBLIC_ENDPOINT), porque quem as usa é um navegador. Mas consumidor de dentro do cluster costuma não alcançar o domínio público do próprio armazenamento, e a chamada morre em conexão recusada. Por isso o serviço mantém um cliente por endpoint e escolhe qual assina.
• A escolha do endpoint é determinística e vem da identidade. Chamada que chega autenticada como o usuário sentinela 00000000-0000-0000-0000-000000000000 — o identificador que o facade usa entre building blocks — recebe a URL interna para upload. Qualquer outro chamador recebe a pública. Não é bandeira por chamada nem variável por ambiente: mesma entrada, mesmo endpoint, sempre. O download é sempre assinado contra o endpoint público, porque quem consome download é externo.

flowchart TD
  Req["Pedido de URL de upload<br/>POST /files ou GET /files/{id}/upload-url"] --> Q{"user.sub é o sentinela<br/>00000000-0000-0000-0000-000000000000?"}
  Q -->|"sim — chamada entre building blocks pelo facade"| I["Assina com o cliente interno<br/>S3_ENDPOINT"]
  Q -->|"não — qualquer outro chamador"| P["Assina com o cliente público<br/>S3_PUBLIC_ENDPOINT"]
  D["Pedido de URL de download<br/>GET /files/{id}/download-url"] --> P2["Sempre o cliente público<br/>S3_PUBLIC_ENDPOINT"]

• Exclusão lógica no banco, exclusão real no armazenamento. O DELETE marca deletedAt na linha e só então apaga o objeto, e apenas se ele tiver sido enviado. A ordem preserva o registro para auditoria mesmo que a remoção no armazenamento falhe — o preço dessa escolha está em §15.
• Lista de tipos MIME fechada. O mimeType é validado contra um conjunto explícito de 23 valores. Bloquear na criação é mais barato que descobrir depois que alguém guardou um executável.
• O bucket é garantido no boot. No modo standalone, o serviço verifica se o bucket existe e o cria se não existir. Falha vira aviso, não impede o boot — a operação é tentada de novo no primeiro uso.

Monolito vs. standalone

Em monolito, o app é montado sob /file-storage e outros building blocks o alcançam pelo facade local, que já chama com a marcação de servidor. Em standalone — o modo de produção — sobe como serviço próprio e o facade remoto chama por HTTP, autenticado como o sentinela.

O comportamento de negócio é idêntico; o que muda é qual endpoint assina a URL de upload.

Glossário

Modelo de dados

Schema storage no PostgreSQL. Uma única tabela.

erDiagram
    ORGANIZATION ||--o{ FILE : "possui os arquivos de"
    FILE {
        uuid id PK
        uuid partner_id FK "o organizationId do token — o tenant, indexado"
        string name "vira o último segmento da chave"
        string mime_type "um dos 23 valores aceitos"
        bigint size_bytes "declarado na criação, medido na confirmação"
        boolean uploaded "false até o HEAD confirmar o objeto, indexado"
        string business_id "identificador livre de negócio, indexado"
        string category "classificação, indexada"
        string s3_key "único — partnerId/fileId/nome"
        string s3_bucket "bucket onde o objeto foi gravado"
        timestamp created_at
        timestamp updated_at
        timestamp deleted_at "exclusão lógica, indexado"
        uuid created_by "userId do token"
        uuid updated_by "userId do token"
    }

Há índice em partnerId, businessId, category, uploaded e deletedAt, e uma relação de chave estrangeira com Organization do IAM.

Tipos MIME aceitos

São 23 valores.

Ciclo de vida de um arquivo

O modelo não tem um campo status: o estado é a combinação de uploaded e deletedAt. São três estados e quatro transições.

stateDiagram-v2
    direction TB

    registrado: uploaded = false — registrado
    disponivel: uploaded = true — disponível
    excluido: deletedAt preenchido — linha preservada

    [*] --> registrado: POST /files cria a linha e assina a URL de upload
    registrado --> registrado: GET /files/{id}/upload-url gera nova URL se a primeira expirou, sem criar outra linha
    registrado --> disponivel: PUT na uploadUrl e POST /files/{id}/confirm-upload, com HEAD confirmando o objeto
    disponivel --> disponivel: GET /files/{id}/download-url devolve URL temporária
    registrado --> excluido: DELETE /files/{id} — não há objeto a apagar
    disponivel --> excluido: DELETE /files/{id} marca deletedAt e apaga o objeto do armazenamento
    excluido --> [*]

    note right of registrado
      Enquanto uploaded for falso,
      GET /files/{id}/download-url devolve 400.
    end note

Prefixo: /file-storage. Em staging, a base é https://storage.bb.stg.catalisa.app — o domínio é storage, o prefixo de rota é /file-storage.

Todas as rotas exigem, nesta ordem: authMiddleware (JWT válido), requirePermission(...) e requireOrganization (token com organizationId; devolve 403 sem ele). O corpo aceita o formato direto ou o envelope JSON:API ({"data":{"attributes":{...}}}).

flowchart LR
  R["Requisição HTTP"] --> A["authMiddleware<br/>JWT válido, senão 401"]
  A --> P["requirePermission(FILES_*)<br/>senão 403"]
  P --> O["requireOrganization<br/>sem organizationId, 403"]
  O --> Z["parse Zod<br/>corpo direto ou envelope JSON API"]
  Z --> S["FileService<br/>ResultAsync"]
  S --> H["handleResult<br/>JSON de resposta"]

São 7 endpoints, todos em routes/files.router.ts, mais GET /health, declarado em app.ts.

Arquivos — /file-storage/api/v1/files

Saúde

Quem tem as permissões. O papel ADMIN tem as três (FILES_CREATE, FILES_READ, FILES_DELETE). O papel FILE_MANAGER tem as três. O papel VIEWER tem apenas FILES_READ. Como em todo building block, a organização é o teto.

Atenção ao ler documentação antiga: não existem as rotas /files/:id/download nem /files/:id/confirm. Os nomes reais são download-url e confirm-upload, e nenhuma rota devolve os bytes — todas devolvem URL.

POST /file-storage/api/v1/files

Cria o registro e devolve a URL de upload na mesma resposta. Exige FILES_CREATE.

Request

{
  "name": "comprovante-renda.pdf",
  "mimeType": "application/pdf",
  "sizeBytes": 1048576,
  "businessId": "PROP-2026-000123",
  "category": "income"
}

{
  "name": "comprovante-renda.pdf",
  "mimeType": "application/pdf",
  "sizeBytes": 1048576,
  "businessId": "PROP-2026-000123",
  "category": "income"
}

Resposta 201

{
  "data": {
    "type": "files",
    "id": "7c1e2a44-9b3d-4f10-8a55-2e6b1c0d9f33",
    "links": { "self": "/api/v1/files/7c1e2a44-9b3d-4f10-8a55-2e6b1c0d9f33" },
    "attributes": {
      "name": "comprovante-renda.pdf",
      "mimeType": "application/pdf",
      "sizeBytes": 1048576,
      "uploaded": false,
      "businessId": "PROP-2026-000123",
      "category": "income",
      "createdAt": "2026-08-16T12:00:00.000Z",
      "createdBy": "b1000000-0000-0000-0000-000000000001"
    }
  },
  "uploadUrl": "https://s3.bb.stg.catalisa.app/building-blocks/b0000000-…/7c1e2a44-…/comprovante-renda.pdf?X-Amz-Algorithm=…",
  "expiresAt": "2026-08-16T13:00:00.000Z",
  "links": { "self": "/api/v1/files/7c1e2a44-9b3d-4f10-8a55-2e6b1c0d9f33" }
}

{
  "data": {
    "type": "files",
    "id": "7c1e2a44-9b3d-4f10-8a55-2e6b1c0d9f33",
    "links": { "self": "/api/v1/files/7c1e2a44-9b3d-4f10-8a55-2e6b1c0d9f33" },
    "attributes": {
      "name": "comprovante-renda.pdf",
      "mimeType": "application/pdf",
      "sizeBytes": 1048576,
      "uploaded": false,
      "businessId": "PROP-2026-000123",
      "category": "income",
      "createdAt": "2026-08-16T12:00:00.000Z",
      "createdBy": "b1000000-0000-0000-0000-000000000001"
    }
  },
  "uploadUrl": "https://s3.bb.stg.catalisa.app/building-blocks/b0000000-…/7c1e2a44-…/comprovante-renda.pdf?X-Amz-Algorithm=…",
  "expiresAt": "2026-08-16T13:00:00.000Z",
  "links": { "self": "/api/v1/files/7c1e2a44-9b3d-4f10-8a55-2e6b1c0d9f33" }
}

O uploadUrl está fora de data, no topo da resposta. expiresAt marca o fim da validade — por padrão, uma hora depois da emissão. O links do topo repete o links de data.

Erros

Enviar os bytes

Não é uma rota do building block. Você faz PUT direto na uploadUrl, com o mesmo Content-Type que declarou:

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  --data-binary @comprovante-renda.pdf

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  --data-binary @comprovante-renda.pdf

O Content-Type faz parte da assinatura. Enviar um diferente do declarado na criação faz o armazenamento recusar com erro de assinatura.

POST /file-storage/api/v1/files/:fileId/confirm-upload

Verifica o objeto no armazenamento e marca o registro como enviado. Exige FILES_CREATE.

Não recebe corpo. O serviço faz HEAD no objeto: se ele não existe, a chamada falha e o registro continua com uploaded: false. Se existe, grava uploaded: true e substitui sizeBytes pelo tamanho medido, publicando file-storage.file.uploaded.

flowchart TD
  C["POST /files/{fileId}/confirm-upload"] --> F{"o arquivo existe nesta organização?"}
  F -->|"não"| E404["404 — inexistente, excluído ou de outra organização"]
  F -->|"sim"| H["HEAD no objeto no armazenamento"]
  H -->|"objeto ausente"| E400["400 — File has not been uploaded to storage<br/>o registro continua com uploaded false"]
  H -->|"objeto presente"| U["uploaded = true e sizeBytes medido"]
  U --> EV["publica file-storage.file.uploaded"]
  EV --> OK["200 com o arquivo confirmado"]

Resposta 200 — o arquivo com uploaded: true e o sizeBytes real.

Erros

GET /file-storage/api/v1/files/:fileId/download-url

Gera uma URL temporária de download. Exige FILES_READ.

Resposta 200

{
  "downloadUrl": "https://s3.bb.stg.catalisa.app/building-blocks/b0000000-…/7c1e2a44-…/comprovante-renda.pdf?X-Amz-Algorithm=…",
  "expiresAt": "2026-08-16T13:00:00.000Z"
}

{
  "downloadUrl": "https://s3.bb.stg.catalisa.app/building-blocks/b0000000-…/7c1e2a44-…/comprovante-renda.pdf?X-Amz-Algorithm=…",
  "expiresAt": "2026-08-16T13:00:00.000Z"
}

Erros

A URL vale até expiresAt e quem a possui consegue baixar o arquivo, sem apresentar token. Trate-a como credencial de curta duração — §14 detalha.

GET /file-storage/api/v1/files

Lista os arquivos da organização, paginado. Exige FILES_READ.

Ordena por createdAt decrescente. Devolve data, meta de paginação e links. Arquivos excluídos logicamente não aparecem.

DELETE /file-storage/api/v1/files/:fileId

Marca deletedAt no registro e, se o arquivo tiver sido enviado, apaga o objeto do armazenamento. Publica file-storage.file.deleted. Exige FILES_DELETE. Responde 204 sem corpo.

Do zero a um arquivo enviado e baixável. Os comandos usam staging; substitua pelo seu ambiente. Não executados nesta revisão da documentação — confira a resposta no seu ambiente.

São seis passos, e o quarto é o único que não existe em nenhuma outra API de upload:

flowchart LR
  P1["1. Autenticar<br/>no IAM"] --> P2["2. Registrar o arquivo<br/>e pegar a uploadUrl"]
  P2 --> P3["3. PUT dos bytes<br/>direto no armazenamento"]
  P3 --> P4["4. confirm-upload<br/>HEAD verifica e mede"]
  P4 --> P5["5. download-url<br/>e baixar"]
  P5 --> P6["6. Conferir o isolamento<br/>com token de outra organização"]

1. Autenticar no IAM

TOKEN=$(curl -s -X POST https://iam.bb.stg.catalisa.app/iam/api/v1/users/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@catalisa.app",
    "password": "root123456",
    "organizationId": "b0000000-0000-0000-0000-000000000001"
  }' | jq -r .accessToken)

BASE=https://storage.bb.stg.catalisa.app

TOKEN=$(curl -s -X POST https://iam.bb.stg.catalisa.app/iam/api/v1/users/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@catalisa.app",
    "password": "root123456",
    "organizationId": "b0000000-0000-0000-0000-000000000001"
  }' | jq -r .accessToken)

BASE=https://storage.bb.stg.catalisa.app

2. Registrar o arquivo e pegar a URL de upload

RESP=$(curl -s -X POST "$BASE/file-storage/api/v1/files" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"comprovante-renda.pdf","mimeType":"application/pdf",
       "businessId":"PROP-2026-000123","category":"income"}')

FILE_ID=$(echo "$RESP" | jq -r '.data.id')
UPLOAD_URL=$(echo "$RESP" | jq -r '.uploadUrl')
echo "$RESP" | jq '{id: .data.id, uploaded: .data.attributes.uploaded, expiresAt}'

RESP=$(curl -s -X POST "$BASE/file-storage/api/v1/files" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"comprovante-renda.pdf","mimeType":"application/pdf",
       "businessId":"PROP-2026-000123","category":"income"}')

FILE_ID=$(echo "$RESP" | jq -r '.data.id')
UPLOAD_URL=$(echo "$RESP" | jq -r '.uploadUrl')
echo "$RESP" | jq '{id: .data.id, uploaded: .data.attributes.uploaded, expiresAt}'

{ "id": "7c1e2a44-…", "uploaded": false, "expiresAt": "2026-08-16T13:00:00.000Z" }

{ "id": "7c1e2a44-…", "uploaded": false, "expiresAt": "2026-08-16T13:00:00.000Z" }

3. Enviar os bytes direto ao armazenamento

curl -s -o /dev/null -w "%{http_code}\n" -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  --data-binary @comprovante-renda.pdf

curl -s -o /dev/null -w "%{http_code}\n" -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  --data-binary @comprovante-renda.pdf

Devolve 200. Repare que esta chamada não passa pelo building block — os bytes vão do seu terminal ao armazenamento.

4. Confirmar o upload

curl -s -X POST "$BASE/file-storage/api/v1/files/$FILE_ID/confirm-upload" \
  -H "Authorization: Bearer $TOKEN" | jq '.data.attributes | {uploaded, sizeBytes}'

curl -s -X POST "$BASE/file-storage/api/v1/files/$FILE_ID/confirm-upload" \
  -H "Authorization: Bearer $TOKEN" | jq '.data.attributes | {uploaded, sizeBytes}'

{ "uploaded": true, "sizeBytes": 1048576 }

{ "uploaded": true, "sizeBytes": 1048576 }

O sizeBytes agora é o tamanho medido no armazenamento, não o que você declarou.

5. Gerar a URL de download e baixar

DOWNLOAD_URL=$(curl -s "$BASE/file-storage/api/v1/files/$FILE_ID/download-url" \
  -H "Authorization: Bearer $TOKEN" | jq -r '.downloadUrl')

curl -s "$DOWNLOAD_URL" -o baixado.pdf && ls -l baixado.pdf

DOWNLOAD_URL=$(curl -s "$BASE/file-storage/api/v1/files/$FILE_ID/download-url" \
  -H "Authorization: Bearer $TOKEN" | jq -r '.downloadUrl')

curl -s "$DOWNLOAD_URL" -o baixado.pdf && ls -l baixado.pdf

O arquivo aparece no disco com o mesmo tamanho que a confirmação mediu. A downloadUrl não pede token — ela já carrega a autorização dentro dela (§14).

6. Confirmar que o isolamento é real

curl -s -o /dev/null -w "%{http_code}\n" \
  "$BASE/file-storage/api/v1/files/$FILE_ID" \
  -H "Authorization: Bearer $TOKEN_DE_OUTRA_ORGANIZACAO"

curl -s -o /dev/null -w "%{http_code}\n" \
  "$BASE/file-storage/api/v1/files/$FILE_ID" \
  -H "Authorization: Bearer $TOKEN_DE_OUTRA_ORGANIZACAO"

Devolve 404, não 403 — de propósito. Arquivo de outra organização é indistinguível de arquivo inexistente, o que impede descobrir a existência de um identificador por tentativa.

Credenciais de staging, publicadas em AMBIENTES.md. Nunca use credencial de produção em documentação ou script de exemplo.

Upload a partir do navegador, sem passar pelo seu backend

Objetivo. Que o arquivo vá do computador do usuário para o armazenamento sem tocar no seu servidor.

sequenceDiagram
    autonumber
    participant N as Navegador
    participant B as Seu backend
    participant FS as File Storage
    participant S3 as Armazenamento
    N->>B: POST /api/anexos
    B->>FS: POST /files com o token do IAM
    FS-->>B: uploadUrl e expiresAt
    B-->>N: só a uploadUrl — o token nunca sai do backend
    N->>S3: PUT com o arquivo e o Content-Type declarado
    N->>B: POST /api/anexos/{id}/confirmar
    B->>FS: POST /files/{fileId}/confirm-upload
    FS->>S3: HEAD no objeto
    FS-->>B: uploaded true

1. Seu backend pede a URL. O token do IAM fica no servidor; o navegador recebe só a URL assinada.

const { data, uploadUrl } = await fetch('/api/anexos', { method: 'POST' }).then(r => r.json())

const { data, uploadUrl } = await fetch('/api/anexos', { method: 'POST' }).then(r => r.json())

2. O navegador envia direto ao armazenamento. Esta chamada não passa pelo seu backend nem pelo building block.

await fetch(uploadUrl, {
  method: 'PUT',
  headers: { 'Content-Type': file.type },
  body: file,
})

await fetch(uploadUrl, {
  method: 'PUT',
  headers: { 'Content-Type': file.type },
  body: file,
})

O armazenamento responde 200 quando aceita os bytes.

3. Seu backend confirma. É a chamada que faz o HEAD e marca o registro como enviado.

await fetch(`/api/anexos/${data.id}/confirmar`, { method: 'POST' })

await fetch(`/api/anexos/${data.id}/confirmar`, { method: 'POST' })

Armadilhas.

• O Content-Type do PUT precisa ser exatamente o mimeType declarado na criação. Ele entra na assinatura; qualquer diferença vira erro de assinatura, e a mensagem do armazenamento não é óbvia.
• Não use fetch com FormData aqui. A URL pré-assinada espera o corpo cru, não multipart/form-data.
• Nunca envie o token do IAM ao navegador para ele chamar o building block direto. O desenho correto é o do exemplo: o backend assina, o navegador só transporta bytes.
• A URL expira em uma hora por padrão. Se o usuário abandonar a tela e voltar depois, peça outra em GET /files/:id/upload-url em vez de criar um registro novo.

Anexar arquivos a um registro de negócio e recuperá-los depois

Objetivo. Guardar os três documentos de uma proposta e listar só os dela.

flowchart LR
  P["Proposta PROP-2026-000123"] --> D1["identity.pdf<br/>category = identity"]
  P --> D2["address.pdf<br/>category = address"]
  P --> D3["income.pdf<br/>category = income"]
  D1 --> B["businessId = PROP-2026-000123"]
  D2 --> B
  D3 --> B
  B --> L["GET /files com filter de businessId<br/>e filter de uploaded"]

1. Criar os três registros com o mesmo businessId e categorias diferentes.

for CAT in identity address income; do
  curl -s -X POST "$BASE/file-storage/api/v1/files" \
    -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
    -d "{\"name\":\"$CAT.pdf\",\"mimeType\":\"application/pdf\",
         \"businessId\":\"PROP-2026-000123\",\"category\":\"$CAT\"}"
done

for CAT in identity address income; do
  curl -s -X POST "$BASE/file-storage/api/v1/files" \
    -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
    -d "{\"name\":\"$CAT.pdf\",\"mimeType\":\"application/pdf\",
         \"businessId\":\"PROP-2026-000123\",\"category\":\"$CAT\"}"
done

Cada iteração devolve um 201 com o seu próprio uploadUrl. Envie os bytes de cada um e confirme, como no §10.

2. Recuperar todos os da proposta que já chegaram.

curl -s -G "$BASE/file-storage/api/v1/files" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode 'filter[businessId]=PROP-2026-000123' \
  --data-urlencode 'filter[uploaded]=true' | jq '.data[].attributes | {name, category}'

curl -s -G "$BASE/file-storage/api/v1/files" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode 'filter[businessId]=PROP-2026-000123' \
  --data-urlencode 'filter[uploaded]=true' | jq '.data[].attributes | {name, category}'

{ "name": "identity.pdf", "category": "identity" }
{ "name": "address.pdf", "category": "address" }
{ "name": "income.pdf", "category": "income" }

{ "name": "identity.pdf", "category": "identity" }
{ "name": "address.pdf", "category": "address" }
{ "name": "income.pdf", "category": "income" }

Armadilhas.

• businessId é texto livre e não é validado contra nada. Um erro de digitação cria um grupo órfão que ninguém vai encontrar — gere esse valor no código, nunca à mão.
• category também é texto livre no schema da rota. Os seis valores de §8 são convenção da plataforma, não restrição do código.
• Filtre por filter[uploaded]=true ao montar tela para o usuário. Sem isso, entram registros de upload que nunca terminou.

Encontrar e limpar uploads abandonados

Objetivo. Achar registros criados que nunca receberam bytes.

1. Listar os registros que ficaram sem bytes.

curl -s -G "$BASE/file-storage/api/v1/files" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode 'filter[uploaded]=false' \
  --data-urlencode 'page[size]=100' | jq '.data[] | {id, name, createdAt: .attributes.createdAt}'

curl -s -G "$BASE/file-storage/api/v1/files" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode 'filter[uploaded]=false' \
  --data-urlencode 'page[size]=100' | jq '.data[] | {id, name, createdAt: .attributes.createdAt}'

{ "id": "7c1e2a44-…", "name": "comprovante-renda.pdf", "createdAt": "2026-08-14T09:12:00.000Z" }

{ "id": "7c1e2a44-…", "name": "comprovante-renda.pdf", "createdAt": "2026-08-14T09:12:00.000Z" }

2. Excluir os que já passaram do prazo aceitável.

curl -s -X DELETE "$BASE/file-storage/api/v1/files/$FILE_ID" \
  -H "Authorization: Bearer $TOKEN" -o /dev/null -w "%{http_code}\n"

curl -s -X DELETE "$BASE/file-storage/api/v1/files/$FILE_ID" \
  -H "Authorization: Bearer $TOKEN" -o /dev/null -w "%{http_code}\n"

Devolve 204, sem corpo.

Armadilhas.

• Não existe limpeza automática. Registro com uploaded: false fica lá para sempre até alguém apagar — vale uma rotina periódica.
• Excluir um registro não enviado não tenta apagar objeto no armazenamento, porque não há objeto. É seguro.
• A exclusão é lógica: a linha continua no banco com deletedAt. Se o seu requisito é eliminação definitiva, é preciso expurgo à parte.

Consumir o File Storage de outro building block

Objetivo. Um serviço seu que já tem os bytes em mãos quer guardá-los, de dentro do cluster.

Use o facade (FileStorageFacadeToken) em vez de chamar a API direto. Ele autentica como o usuário sentinela, e o roteador detecta essa identidade e devolve a URL de upload assinada contra o endpoint interno — o único alcançável de dentro do cluster.

flowchart TD
  BB["Seu building block, dentro do cluster"] --> Esc{"Como você chama?"}
  Esc -->|"pelo facade — usuário sentinela"| OK["uploadUrl contra S3_ENDPOINT<br/>PUT funciona de dentro do cluster"]
  Esc -->|"pela API, com token de usuário comum"| ERR["uploadUrl contra S3_PUBLIC_ENDPOINT<br/>PUT falha com conexão recusada ou timeout"]

Armadilhas.

• Se você chamar a API com um token de usuário comum a partir de um processo de dentro do cluster, vai receber a URL pública e o PUT pode falhar com conexão recusada ou timeout. Esse é o modo de falha exato descrito em file-storage-internal-presigned-urls.md.
• A URL de download é sempre assinada contra o endpoint público, mesmo para chamador interno. Se um dia um consumidor de dentro do cluster precisar baixar, isso exige mudança no serviço.
• O endpoint interno precisa ser alcançável pelos workers (S3_ENDPOINT, por exemplo http://minio:9000), e o público precisa ser o domínio externo. Errar essa dupla é a causa mais comum de "funciona local, falha no cluster".

Eventos publicados. file-storage.file.created, file-storage.file.uploaded, file-storage.file.deleted. Todos carregam organizationId e userId nos metadados.

Documentação antiga cita os eventos como storage.file.*. Os nomes reais começam com file-storage.. Assinatura de webhook feita com o prefixo antigo não recebe nada.

flowchart TD
  U["Usuário"] -->|"pede a URL"| IAM["IAM — token"]
  IAM -->|"organizationId do token"| FS["File Storage"]
  FS -->|"assina a URL"| S3["S3 / MinIO"]
  U ==>|"PUT dos bytes"| S3

  FS -->|"guarda o fileId junto do dado de negócio"| DS["Data Store — documento"]
  FS --> ES["E-Signature · WPP"]
  FS -->|"eventos file-storage.*"| WH["Webhooks Engine · Audit Trail"]

O par com o Data Store é o desenho recomendado: o binário fica no armazenamento pelo file-storage e o documento JSON guarda o fileId junto dos campos de negócio. Assim a consulta por conteúdo acontece sobre metadado estruturado, e o blob não passa pelo banco. Esse é o argumento da plataforma inteira em uma imagem — as peças se encaixam sem cola escrita pelo cliente.

Variáveis de ambiente

Divergência de porta conhecida. O registro de módulos (src/shared/registry/types.ts) declara file-storage: 3005, e é o valor autoritativo. O docker-compose.yaml de desenvolvimento publica 3004:3000, e READMEs antigos citam 3004. Dentro do cluster o serviço escuta sempre em 3000, então a divergência só afeta desenvolvimento local. Confira a porta publicada antes de apontar um cliente local.

Dependências de infraestrutura

flowchart LR
  FS["File Storage"] --> PG["PostgreSQL<br/>schema storage, tabela files"]
  FS --> OBJ["Armazenamento compatível com S3<br/>MinIO local, S3 ou equivalente em produção"]
  FS --> RD["Redis<br/>contadores do rate limit — falha aberta"]
  FS --> IAM["IAM<br/>verificação do token e permissões"]

Limites e quotas

Não há quota de armazenamento por tenant. Um cliente pode enviar até onde o bucket aguentar.

Catálogo de erros

Observabilidade

• GET /file-storage/health devolve a versão do build e o nome do módulo. É a sonda usada pelo healthcheck do container.
• No boot em standalone, o serviço registra em log se o bucket já existia ou foi criado. Falha vira aviso e não impede o boot.
• Os eventos file-storage.* carregam userId e organizationId, o que permite reconstruir o histórico de quem enviou e apagou o quê pelo Audit Trail.
• Métrica operacional útil sem custo: a contagem de registros com uploaded: false mais velhos que algumas horas. É o indicador direto de upload que está falhando no caminho entre cliente e armazenamento.

Isolamento entre tenants

O partnerId é sempre user.organizationId, extraído do token assinado pelo IAM. Nenhuma rota lê o identificador da organização do corpo ou da query da requisição. Sobre isso:

1. Autenticação — authMiddleware verifica a assinatura do token.
2. Autorização — requirePermission(FILES_CREATE | FILES_READ | FILES_DELETE).
3. Contexto obrigatório — requireOrganization devolve 403 para token sem organizationId.
4. Escopo na consulta — toda busca de arquivo é findFirst({ id, partnerId, deletedAt: null }). Não existe busca por id sem o tenant junto, o que faz arquivo de outra organização responder 404, indistinguível de inexistente.
5. Escopo no caminho do objeto — a chave é {organizationId}/{fileId}/{nome}. O tenant é o prefixo físico, o que permite política por prefixo no armazenamento como camada extra, se o provedor oferecer.

flowchart TD
  T["Token assinado pelo IAM"] --> C1["1. authMiddleware verifica a assinatura"]
  C1 -->|"token inválido"| E401["401"]
  C1 --> C2["2. requirePermission — FILES_CREATE, FILES_READ ou FILES_DELETE"]
  C2 -->|"sem a permissão"| E403["403"]
  C2 --> C3["3. requireOrganization exige organizationId no token"]
  C3 -->|"token sem organização"| E403
  C3 --> C4["4. findFirst com id + partnerId + deletedAt null"]
  C4 -->|"não pertence a esta organização"| E404["404 — indistinguível de inexistente"]
  C4 --> C5["5. chave organizationId / fileId / nome no armazenamento"]

URLs pré-assinadas — o que elas são e o risco que carregam

Uma URL pré-assinada carrega a autorização dentro dela. A AWS é direta sobre o que isso significa: "presigned URLs are bearer tokens that grant access to those who possess them. As such, we recommend that you protect them appropriately" (AWS — Download and upload objects with presigned URLs). Quem tem a URL baixa o arquivo, sem apresentar token, até ela expirar.

O risco de vazamento, dito de frente

Se a URL de download vazar — colada em um chamado de suporte, registrada em log de proxy, enviada em mensagem — qualquer pessoa baixa aquele arquivo até o prazo acabar.

flowchart LR
  G["URL de download emitida"] --> V{"Vazou?"}
  V -->|"não"| OK["Expira em PRESIGNED_URL_EXPIRY e some"]
  V -->|"chamado de suporte, log de proxy, mensagem"| L["Quem tem a URL baixa o arquivo,<br/>sem apresentar token"]
  L --> R["Não há revogação individual<br/>só rotacionar a credencial S3 ou apagar o objeto"]

Recomendações práticas:

• Não registre a URL completa em log de aplicação. Registre o fileId.
• Gere a URL no momento do uso e entregue-a ao usuário final, em vez de guardá-la em banco ou em cache.
• Encurte PRESIGNED_URL_EXPIRY se o seu uso não precisa de uma hora. Para clique imediato, minutos bastam.
• Trate a URL como credencial em qualquer análise de risco: ela é um portador, não uma referência.
• Não é possível revogar uma URL já emitida sem rotacionar a credencial S3 do serviço ou apagar o objeto.

Dados sensíveis

O building block guarda metadados, não conteúdo: nome, tipo, tamanho, categoria, identificador de negócio e autoria. O conteúdo do arquivo fica no armazenamento e nunca passa pelo banco.

flowchart LR
  Arq["Arquivo enviado"] --> Meta["Postgres — metadados<br/>nome, tipo, tamanho, categoria,<br/>businessId, createdBy, updatedBy"]
  Arq --> Bytes["Armazenamento — conteúdo<br/>criptografia em repouso é do provedor"]
  Meta -.->|"DELETE marca deletedAt"| Sobrevive["Metadado sobrevive para auditoria"]
  Bytes -.->|"DELETE apaga o objeto"| Some["Conteúdo não sobrevive"]

Consequências:

• Criptografia em repouso é responsabilidade do armazenamento configurado (por exemplo, SSE do S3). O building block não cifra o conteúdo por conta própria.
• O nome do arquivo aparece na chave do objeto e na URL. Nome que contenha dado pessoal — cpf-12345678900.pdf — expõe esse dado a quem vir a URL. Gere nomes neutros.
• Exclusão lógica no banco, exclusão real no armazenamento. O DELETE marca deletedAt e apaga o objeto. Metadado sobrevive para auditoria; o conteúdo não. Se o seu requisito for eliminar o metadado também, é preciso expurgo à parte.
• Rastro de autoria. Todo arquivo guarda createdBy e updatedBy com o userId do token.

LGPD

Documento de identidade e comprovante são dado pessoal, às vezes sensível. A postura recomendada:

Autenticação e permissões

Toda rota exige token válido, a permissão correspondente e organização no token. Chamadas entre building blocks passam pelo facade e chegam autenticadas como o usuário sentinela 00000000-0000-0000-0000-000000000000, o que as torna distinguíveis de tráfego de cliente e é o que faz a URL de upload interna ser escolhida.

As treze limitações abaixo caem em quatro famílias. Nenhuma delas impede o uso em produção, mas todas mudam o que você precisa construir por fora.

flowchart TD
  L["Limitações conhecidas"] --> A["Volume e quota<br/>tamanho não imposto · sem quota por tenant"]
  L --> B["Ciclo de vida<br/>sem limpeza de abandonado · objeto órfão · sem expurgo LGPD"]
  L --> C["Conteúdo e integridade<br/>sem checksum · sem antivírus · sem criptografia pela aplicação · sem versionamento · sem multipart"]
  L --> D["Alcance e operação<br/>download interno · divergência de porta · URL não revogável · category e businessId sem validação"]

Por que a API não devolve o arquivo, só uma URL?

Porque o objetivo é que o byte não passe pelo seu servidor. Devolver o arquivo transformaria o building block em intermediário de tráfego, com custo de banda e de dimensionamento. A URL pré-assinada faz o cliente falar direto com o armazenamento, e a autorização acontece antes, na hora de gerar a URL.

Quanto tempo a URL de upload ou download vale?

Uma hora por padrão, configurável em PRESIGNED_URL_EXPIRY. O campo expiresAt vem em toda resposta que devolve URL. Se ela expirar antes do uso, peça outra: GET /files/:id/upload-url para upload e GET /files/:id/download-url para download. Não crie registro novo por causa disso.

Se alguém copiar a URL de download, essa pessoa consegue baixar o arquivo?

Consegue, até a URL expirar. É a natureza do mecanismo — a AWS descreve a URL pré-assinada como um token portador. Por isso o prazo é curto, a URL não deve ir para log e ela deve ser gerada no momento do uso, não guardada. §14 traz as recomendações completas.

Qual a diferença entre o File Storage e o Data Store?

O File Storage guarda bytes: PDF, imagem, áudio, planilha. O Data Store guarda documentos JSON estruturados e consultáveis pelo conteúdo. O desenho recomendado usa os dois: o binário vai para o armazenamento aqui, e lá fica o documento com os campos de negócio e o fileId que aponta para o arquivo.

Posso usar com Cloudflare R2, MinIO ou outro provedor em vez do S3 da AWS?

Pode. O serviço fala a API do S3 e o destino é configuração: S3_ENDPOINT, S3_BUCKET, credenciais e S3_FORCE_PATH_STYLE. O desenvolvimento local já roda sobre MinIO. Essa é a alavanca de custo mais relevante do building block, porque a taxa de saída varia muito entre provedores (§6).

O que acontece se eu não chamar confirm-upload?

O registro fica com uploaded: false para sempre, o sizeBytes continua sendo a sua declaração em vez da medição, e GET /files/:id/download-url responde 400. O arquivo pode até estar no armazenamento, mas o building block não o considera disponível. A confirmação é o que fecha o fluxo.

Existe limite de tamanho por arquivo?

O registro valida até 100 MB no campo sizeBytes, mas esse valor é uma declaração: a URL pré-assinada não carrega restrição de tamanho, então o cliente pode enviar mais (§15). Limite real precisa vir de política do bucket. Também não há upload em partes, então arquivo muito grande depende de uma única conexão estável.

Como impeço que a empresa A baixe o arquivo da empresa B?

Você não precisa fazer nada: o identificador da organização vem do token assinado, toda busca filtra por ele, e arquivo de outra organização responde 404. A URL de download só é gerada depois dessa verificação. Além disso, o identificador da organização é o prefixo da chave no armazenamento, o que permite uma camada extra de política por prefixo se o provedor oferecer.

O arquivo é cifrado?

Não pelo building block. O conteúdo é gravado como veio, e criptografia em repouso é responsabilidade do armazenamento configurado — no S3, por exemplo, habilitando SSE no bucket. Se o requisito for criptografia ponta a ponta com chave sua, ela precisa acontecer no cliente, antes do PUT.

Dá para guardar dado estruturado junto do arquivo?

Em parte: businessId e category cobrem a classificação básica e são filtráveis na listagem. Para além disso — campos de negócio, formulário, contexto —, o lugar certo é o Data Store, guardando o fileId junto do documento.

_{Padrão: PADRAO-DOCUMENTACAO.md · Índice: INDEX.md · Nota técnica: file-storage-internal-presigned-urls.md}