Exportação Verificada

Exportação de relatórios com verificação de identidade via OTP

Exportação Verificada#

O sistema de exportação verificada permite baixar relatórios — incluindo pacotes .sulfite assinados — exigindo que o solicitante confirme sua identidade via código OTP enviado por email.

┌──────────┐  POST /export/verify   ┌──────────────┐   email   ┌──────────┐
│  Cliente  │──────────────────────▶│  Server       │──────────▶│  Email   │
│           │◀── { status: sent }   │  (gera OTP)   │           │  (OTP)   │
│           │                       └──────────────┘           └──────────┘
│           │  POST /export/confirm
│           │  { email, reportId, code, format }
│           │──────────────────────▶┌──────────────┐
│           │◀── .sulfite assinado  │  Server       │
└──────────┘                        │  (verifica +  │
                                    │   assina +    │
                                    │   gera output)│
                                    └──────────────┘

Princípios:

O OTP é gerado com Random.secure() — 15 caracteres alfanuméricos por default
O código é armazenado como hash SHA-256 — nunca em plaintext
A comparação é timing-safe
Após verificação, o relatório é assinado com role: "export" e a identidade do usuário é registrada (VerifiedIdentity)
O OTP é consumido na verificação — não pode ser reutilizado

Endpoints#

Política de exportação — `GET /api/v1/export/policy`#

Autenticação: canGenerate (opcional — retorna dados genéricos em modo dev)

Retorna a configuração de export policy do servidor. O cliente usa isso para decidir se deve exibir o fluxo OTP.

Response 200:

{
  "protectedFormats": ["sulfite", "pdf"],
  "requireVerificationForAll": false,
  "otpExpirationSeconds": 300,
  "identityHints": ["@acme.com", "user@example.com"]
}

Campo	Descrição
`protectedFormats`	Formatos que exigem verificação OTP
`requireVerificationForAll`	Se `true`, todos os formatos precisam de OTP
`otpExpirationSeconds`	Tempo de vida do código em segundos
`identityHints`	Domínios/emails permitidos (para UI de dicas)

Solicitar OTP — `POST /api/v1/export/verify`#

Autenticação: canGenerate (opcional em modo dev)

Gera e envia um código OTP para o email informado.

Body:

{
  "email": "user@acme.com",
  "reportId": "uuid-do-relatorio"
}

Response 200:

{
  "status": "sent",
  "expiresIn": 300
}

Erros:

Status	Erro	Quando
`400`	`invalid_email`	Email inválido
`400`	`validation_error`	`reportId` ausente
`403`	`identity_not_allowed`	Email/domínio não permitido por `EXPORT_ALLOWED_IDENTITIES`
`404`	`not_found`	Relatório não encontrado
`429`	`rate_limited`	Código já enviado há menos de 60s, ou limite por hora atingido (5/hora por email)
`503`	`otp_store_full`	Capacidade do OTP store atingida
`503`	`otp_delivery_failed`	Falha no envio do email
`503`	`not_configured`	OTP service não configurado (sem email provider)

Confirmar OTP e baixar — `POST /api/v1/export/confirm`#

Autenticação: canGenerate (opcional em modo dev)

Verifica o código OTP e retorna o relatório exportado, assinado.

Body:

{
  "email": "user@acme.com",
  "reportId": "uuid-do-relatorio",
  "code": "ABC123XYZ456DEF",
  "format": "sulfite"
}

Campo	Obrigatório	Default	Descrição
`email`	Sim	—	Email que recebeu o OTP
`reportId`	Sim	—	ID do relatório
`code`	Sim	—	Código OTP recebido
`format`	Não	`sulfite`	`sulfite`, `pdf`, `html`, `csv`, `excel`

Response 200: Bytes do relatório exportado.

Headers de resposta:

Content-Type: application/octet-stream  (sulfite) / application/pdf  (pdf) / ...
Content-Disposition: attachment; filename="nome-do-relatorio.sulfite"
X-Sulfite-Signed: true
X-Sulfite-Signed-By: user@acme.com
X-Sulfite-Signed-At: 2026-04-09T10:00:00.000Z

Erros:

Status	Erro	Quando
`400`	`invalid_email`	Email inválido
`400`	`validation_error`	`reportId` ou `code` ausente
`400`	`invalid_code`	Código incorreto
`400`	`otp_not_found`	Nenhum código pendente para este email/relatório
`403`	`identity_not_allowed`	Email/domínio não permitido
`404`	`not_found`	Relatório não encontrado
`410`	`expired`	Código expirado
`422`	`invalid_report`	Relatório sem definição válida
`422`	`package_rebuild_failed`	Falha ao preservar conteúdo do pacote `.sulfite` ao assinar
`423`	`max_attempts`	Tentativas esgotadas — solicitar novo código
`503`	`not_configured`	OTP service ou signer não configurados

Configuração#

Variáveis de ambiente#

Variável	Default	Descrição
`EXPORT_ALLOWED_IDENTITIES`	— (todos)	Emails ou domínios permitidos, separados por vírgula. Ex: `user@example.com,acme.com`
`EXPORT_PROTECTED_FORMATS`	`sulfite,pdf`	Formatos que exigem OTP
`EXPORT_REQUIRE_ALL`	`false`	Se `true`, todos os formatos exigem OTP
`EXPORT_OTP_EXPIRATION`	`300`	Expiração do OTP em segundos
`EXPORT_OTP_MAX_ATTEMPTS`	`3`	Tentativas antes de invalidar
`EXPORT_OTP_LENGTH`	`15`	Comprimento do código

Também é necessário configurar um email provider (Resend ou MailerSend). Veja Configuração → Email.

Requisitos#

ENCRYPTION_KEY configurado (necessário para assinar o relatório após verificação)
Um email provider configurado (RESEND_API_TOKEN ou MAILERSEND_API_TOKEN)

Exemplo de configuração#

export ENCRYPTION_KEY="base64-encoded-32-byte-key"
export EXPORT_ALLOWED_IDENTITIES="acme.com,partner@example.com"
export EXPORT_PROTECTED_FORMATS="sulfite,pdf"
export EXPORT_OTP_EXPIRATION=300
export RESEND_API_TOKEN="re_..."
export RESEND_FROM_EMAIL="noreply@acme.com"

Fluxo completo#

1. Cliente detecta a política#

GET /api/v1/export/policy
# → { "protectedFormats": ["sulfite", "pdf"], ... }

Se o formato desejado está em protectedFormats, exibir o fluxo OTP.

2. Solicitar OTP#

curl -X POST https://server.com/api/v1/export/verify \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "email": "user@acme.com", "reportId": "abc123" }'

# Response: { "status": "sent", "expiresIn": 300 }
# → Usuário recebe email com o código

3. Confirmar e baixar#

curl -X POST https://server.com/api/v1/export/confirm \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@acme.com",
    "reportId": "abc123",
    "code": "ABC123XYZ456DEF",
    "format": "sulfite"
  }' \
  -o relatorio.sulfite

O arquivo baixado é um pacote .sulfite assinado digitalmente com a identidade verificada do usuário.

Assinatura resultante#

Após exportação verificada, o relatório carrega uma assinatura com role: "export":

{
  "_signatures": {
    "export": {
      "alg": "hmac-sha256",
      "key_id": "current",
      "value": "base64url...",
      "signed_at": "2026-04-09T10:00:00.000Z",
      "origin": "verified-export",
      "identity": {
        "email": "user@acme.com",
        "verified_at": "2026-04-09T10:00:00.000Z",
        "domain": "acme.com"
      }
    }
  }
}

Essa assinatura pode ser verificada via GET /api/v1/reports/:id/signatures. Veja Assinatura.

Segurança#

Proteção	Detalhe
OTP hashing	SHA-256 — código nunca armazenado em plaintext
Comparação	Timing-safe (evita timing attacks)
Rate limit por IP	Herdado do rate limiter global
Rate limit por email	5 OTPs/hora por email
Rate limit de reenvio	60s entre pedidos para o mesmo relatório
Tentativas máximas	3 (configurável) — após esgotar, OTP invalidado
Identidades permitidas	`EXPORT_ALLOWED_IDENTITIES` — bloqueia emails/domínios não autorizados
Auditoria	Todos os eventos logados (ver Segurança → Auditoria)