Segurança

Versão: 1.0
Owner: Engenharia & Compliance SOFIA
Última revisão: 2026
Aplicável a: Dev Backend, Dev Frontend, Arquitetura

Esta página define os requisitos obrigatórios de segurança para qualquer integração com a SOFIA.

Integrações que não seguem estas diretrizes podem ser bloqueadas.

1. Assinatura HMAC

A SOFIA utiliza HMAC SHA-256 para:

• Garantir autenticidade
• Garantir integridade
• Mitigar replay e manipulação de payload

Formato padrão:

sha256=<hex>

Regras obrigatórias:

• Assinar exatamente o conteúdo esperado (raw body ou signing string)
• Validar com comparação constante (timingSafeEqual)
• Nunca gerar assinatura no frontend público quando o segredo não puder ser exposto

1.1 Webhook (Raw Body)

Headers esperados:

• x-sofia-signature (obrigatório)
• x-sofia-timestamp (obrigatório)
• x-sofia-version (opcional; se presente, deve ser 1)

A assinatura é calculada sobre o raw body (bytes exatos).

Exemplo de verificação:

import crypto from 'crypto'
 
export function verifySofiaWebhookSignature(rawBody: Buffer, secret: string, headerValue: string) {
  const provided = String(headerValue || '').startsWith('sha256=')
    ? String(headerValue).slice('sha256='.length)
    : String(headerValue || '');
 
  const expected = crypto.createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
 
  if (!/^[0-9a-f]+$/i.test(provided)) return false;
  if (provided.length !== expected.length) return false;
 
  return crypto.timingSafeEqual(
    Buffer.from(provided, 'hex'),
    Buffer.from(expected, 'hex')
  );
}

Nunca:

• Re-serializar JSON antes de validar
• Logar segredo ou assinatura

1.2 postMessage (Signing String)

A assinatura deve ser calculada sobre:

<ts>.<table_id>.<balance_cents>.<user_external_id>.<session_id>.<nonce>

Regras:

• ts em ms (UTC)
• Drift máximo: 30.000ms
• nonce obrigatório quando assinatura ativa
• Anti-replay com cache mínimo de 5 minutos

Detalhes: postMessage

2. Verificação de Origem

2.1 postMessage

Obrigatório validar:

if (event.source !== iframe.contentWindow) return;
if (event.origin !== expectedOrigin) return;

Regras:

• Comparar apenas origin (ex.: https://casino.com)
• Nunca usar '*'
• Nunca confiar apenas no type

Falha de validação deve resultar em descarte silencioso do evento.

2.2 APIs HTTP

Endpoints que exigem autenticação:

• Devem ser chamados pelo backend
• Nunca expor token no browser
• Nunca aceitar segredo via querystring

3. Allowlist de IP

Pode ser configurada para endpoints sensíveis.

Regras:

• Se allowlist ativa, IP fora da lista retorna 403
• Funciona apenas se IP do emissor for determinístico
• Se estiver atrás de proxy/CDN, configure corretamente trust proxy

4. Rate Limit

A SOFIA aplica rate limit para:

• Proteger contra abuso
• Reduzir brute force
• Evitar sobrecarga

Regras de integração:

• Tratar 429 com backoff
• Respeitar Retry-After
• Não fazer retry agressivo

5. Circuit Breaker

Recomendação para parceiros:

• Se receber 401/403 repetidos → interromper envio e corrigir configuração
• Se receber 5xx → retry com limite
• Não entrar em loop infinito de falha

6. Política de Retry

Retry permitido apenas para:

• 429
• 502
• 503
• 504
• erro de rede

Não fazer retry automático para:

• 400
• 401
• 403
• 409

Webhook:

• Responder 2xx rapidamente
• Processar em background
• Implementar idempotência

API Pull:

• Dedupe por id
• Persistir cursor
• Evitar polling agressivo

7. Checklist Obrigatório (Produção)

Antes de ir para produção:

• Assinatura HMAC validada
• Idempotência implementada
• Validação de origin implementada
• Tokens armazenados em secret manager
• Logs sem segredos ou PII
• Clock sincronizado (NTP)
• HTTPS obrigatório
• Rate limit tratado corretamente

8. Princípio Geral

Se você:

• Não valida assinatura
• Não valida origem
• Não implementa idempotência
• Loga segredos

Você está operando fora do padrão mínimo de segurança.