postMessage (Tempo real via Iframe)

Versão: 1.0
Owner: Engenharia SOFIA
Última revisão: 2026
Aplicável a: Dev Frontend Integradores

O modelo postMessage permite comunicação em tempo real entre o conteúdo embutido em um iframe e a aplicação host (SOFIA).

Este canal é exclusivamente browser-to-browser.

Não substitui Webhook.

1. Quando Utilizar

Use postMessage quando:

• O provedor roda dentro de iframe.
• É necessário sincronizar dados em tempo real (ex.: saldo).
• A origem do iframe é controlável.
• A comunicação ocorre no contexto do navegador.

Não utilize quando:

• Precisa de confiabilidade server-to-server.
• Precisa de retries garantidos.
• Precisa de persistência independente do browser.

Para esses cenários, use Webhook ou API Pull.

2. Requisitos Técnicos

O provedor deve:

• Executar JavaScript dentro do iframe.
• Ter permissão de embed.
• Conseguir executar:

window.parent.postMessage(envelope, targetOrigin);

3. Contrato Oficial (Casino postMessage v1)

Somente o seguinte contrato é suportado oficialmente:

Outros eventos não fazem parte do contrato público.

4. Estrutura do Evento

Envelope

{
  "source": "sofia-casino",
  "version": "1.0",
  "ts": 1760713212123,
  "type": "BALANCE_UPDATE",
  "payload": {
    "table_id": "evolution-roulette",
    "balance_cents": 105000,
    "currency": "BRL",
    "user_external_id": "user-123",
    "session_id": "sess-abc",
    "nonce": "nonce-hex",
    "signature": "sha256=<HEX>"
  }
}

5. Campos Obrigatórios

Regras:

• balance_cents deve ser inteiro.
• Não usar float.
• currency recomendada: BRL.

6. Segurança

postMessage é vulnerável se mal implementado.

A validação obrigatória no host é:

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

Nunca:

• Aceitar qualquer origem
• Usar '*' como targetOrigin em produção
• Processar evento sem validar source e version

7. Assinatura HMAC (Opcional, Recomendado)

Se habilitado no Admin:

O evento deve incluir:

• nonce
• signature
• ts

Drift permitido

• Máximo: 30.000ms

Cache anti-replay

• 5 minutos por nonce

String de assinatura

{ts}.{table_id}.{balance_cents}.{external_user_id}.{session_id}.{nonce}

Formato:

signature = sha256=<hex>

8. Exemplo de Envio (Iframe)

window.parent.postMessage(envelope, targetOrigin);

Nunca usar:

window.parent.postMessage(envelope, '*');

9. Exemplo de Consumo Seguro

window.addEventListener('message', (event) => {
  if (event.source !== iframe.contentWindow) return;
  if (event.origin !== expectedOrigin) return;
  if (!event.data || typeof event.data !== 'object') return;
 
  const { source, version, type, payload } = event.data;
 
  if (source !== 'sofia-casino') return;
  if (version !== '1.0') return;
  if (type !== 'BALANCE_UPDATE') return;
 
  if (!Number.isSafeInteger(payload.balance_cents)) return;
 
  console.log('Saldo atualizado:', payload.balance_cents);
});

10. Responsabilidade do Parceiro

Ao usar postMessage, o parceiro é responsável por:

• Garantir que o provedor envia apenas dados necessários.
• Implementar validação forte de origem.
• Não expor segredo HMAC no frontend público.
• Implementar rotação periódica do segredo (se habilitado).
• Não logar signature ou segredo.

11. Limitações do Modelo

postMessage:

• Não possui retry.
• Depende de browser ativo.
• Não garante entrega.
• Não é idempotente por padrão.
• Pode falhar silenciosamente se iframe for recarregado.

Para persistência confiável, combine:

Iframe + postMessage + Webhook.