Como validar solicitações de provedores da Chrome Email Verification API em 2026?

O marco de versão muda o formato, não a evidência necessária

A partir do Chrome 153, a solicitação do emissor passou a usar corpo JSON e HTTP Message Signatures, conforme a atualização oficial de agosto de 2026. Para quem mantém um provedor, a ação imediata é validar a assinatura criptográfica, o resumo do corpo, a sessão e a correspondência do endereço antes de emitir qualquer token. A presença dos cabeçalhos não basta.

Este artigo trata apenas de solicitações recebidas por um provedor de e-mail ou identidade próprio, ou por um ambiente de teste autorizado. A emissão do token pelo provedor, a aceitação desse token pelo navegador e a conclusão da verificação pelo site são etapas distintas. Se a emissão falhar ou o recurso não estiver disponível, o fluxo existente de confirmação por e-mail deve continuar funcionando.

Este guia é para:
- Desenvolvedores que implementam ou mantêm um endpoint emissor.
- Profissionais de segurança que revisam assinatura, sessão e limites de confiança.
- QA que valida formatos e resultados em diferentes versões do navegador.

Última atualização: 30 de outubro de 2026. As alterações de versão e de tratamento citadas abaixo foram conferidas no guia oficial do emissor, nas atualizações de agosto e de outubro de 2026. O recurso continua descrito como Origin Trial; a implementação deve acompanhar a documentação oficial vigente.

Para o responsável pelo emissor, aceite apenas o que foi comprovado

A solicitação recebida inicia uma verificação; não a conclui. Um endpoint pode receber uma requisição bem formada e ainda assim não ter evidência de que ela foi assinada por uma chave confiável, de que o corpo corresponde ao resumo declarado ou de que o usuário da sessão controla o endereço solicitado.

Essa distinção deve aparecer tanto na implementação quanto nos registros. O servidor pode registrar separadamente: requisição recebida, assinatura verificada, sessão confirmada, endereço correspondente e token emitido. Esses eventos descrevem resultados diferentes. Um log que registra apenas “solicitação processada” dificulta descobrir em que fronteira uma rejeição ocorreu.

O papel do emissor também não deve ser confundido com o do site que consome o token. O emissor recebe a solicitação do navegador e decide se há base para assinar e emitir um resultado. O site, por sua vez, valida o token recebido e conclui a verificação da conta. A descrição oficial do fluxo da Chrome Email Verification API ajuda a manter essa separação: uma emissão correta não prova, por si só, que um site aceitou o token ou marcou o endereço como verificado.

Para o Chrome Email Verification API issuer, isso significa manter a decisão de emissão condicionada a verificações explícitas, em vez de tratar a requisição como uma autorização automática. A implementação deve seguir o contrato atual do guia do emissor. Não se deve ampliar o que é aceito com base apenas em comportamento observado em uma versão específica do navegador.

Para quem mantém compatibilidade, registre o formato recebido

A partir do Chrome 153, o guia descreve solicitações de emissão com corpo JSON e HTTP Message Signatures. Essa mudança afeta a análise do corpo e a validação dos componentes assinados; um endpoint que só reconhece o formato anterior pode rejeitar solicitações válidas ou, pior, aplicar uma interpretação permissiva que não corresponde à assinatura.

Há também uma alteração em Sec-Fetch-Dest: a partir do Chrome 154, o valor indicado é email-verification. Versões anteriores podem apresentar a forma sem hífen. A atualização oficial de outubro de 2026 documenta a mudança. O endpoint deve reconhecer a diferença durante a transição sem concluir que todos os clientes enviam o mesmo valor.

Na prática, convém armazenar o valor recebido, a versão do navegador disponível para o teste e a decisão tomada pelo servidor. Essa trilha permite separar uma incompatibilidade de cabeçalho de uma falha criptográfica. Não use Sec-Fetch-Dest como substituto da autenticação da solicitação: ele é uma informação de contexto, não uma prova de que o corpo veio de uma fonte confiável.

A tabela é um instrumento de triagem, não uma especificação substituta. A aplicação deve seguir as regras do guia oficial para cada formato. Também é importante testar o endpoint atrás da mesma arquitetura de proxy ou balanceador usada no ambiente real: o authority público pode diferir do nome interno do serviço.

Para quem implementa HTTP Message Signatures, valide os componentes cobertos

A presença de Signature, Signature-Input, Signature-Key e Content-Digest não comprova que a requisição passou pela validação. O servidor precisa conferir o resumo do corpo recebido e verificar a assinatura com a chave e os parâmetros esperados. O guia oficial de implementação do emissor define as responsabilidades específicas desse fluxo; o RFC 9421 descreve o mecanismo padronizado de HTTP Message Signatures.

A revisão técnica deve responder a perguntas concretas:

• O corpo recebido é exatamente o corpo usado no cálculo de Content-Digest?
• A assinatura foi verificada contra o conteúdo identificado pelo Signature-Input, e não contra uma seleção improvisada de cabeçalhos?
• A chave associada a Signature-Key é aceita pelo procedimento documentado?
• A aplicação rejeita alterações em componentes cobertos pela assinatura?
• A interpretação do alvo e do authority corresponde à requisição pública que foi assinada?

Essa última questão merece atenção em ambientes com proxy reverso. O serviço pode receber internamente um nome de host diferente daquele usado na solicitação externa. Se a aplicação reconstruir os dados assinados usando valores internos sem uma regra confiável de encaminhamento, pode verificar a mensagem errada ou aceitar uma composição inconsistente. A configuração de proxy deve preservar uma representação confiável dos elementos externos, com cabeçalhos de encaminhamento aceitos somente de infraestrutura autorizada.

O RFC é a referência para o mecanismo geral; não substitui os requisitos específicos do Chrome. Em particular, TLS protege o transporte entre pontos da conexão, mas não equivale à validação da assinatura da mensagem. Da mesma forma, a existência de um campo de assinatura ou de um digest não é prova de que sua verificação foi executada e aprovada.

Para quem mantém contas e sessões, valide a identidade antes de emitir

Uma assinatura válida não demonstra que o endereço solicitado pertence à conta autenticada. O emissor também precisa confirmar que a sessão está válida e que o endereço presente na solicitação corresponde a um endereço que aquela sessão pode verificar. São controles diferentes: um protege a integridade e a origem da mensagem; o outro vincula o pedido a uma conta e a um endereço.

A comparação exige cuidado com a normalização. O sistema pode precisar de uma forma interna normalizada para localizar a conta, mas isso não autoriza reescrever silenciosamente o valor que será incluído no token. A orientação oficial estabelece que, a partir do Chrome 156, a declaração de e-mail no token deve corresponder ao valor do endereço da solicitação. A atualização de outubro de 2026 também descreve mudanças na identificação do algoritmo de assinatura e no tratamento da declaração de e-mail; confira os detalhes no aviso oficial já citado antes de ajustar o emissor.

Uma revisão útil acompanha os valores em etapas separadas:

1. Valor de e-mail recebido no corpo.
2. Valor usado para localizar ou comparar a conta, conforme a política interna.
3. Valor que o emissor pretende declarar no token.
4. Resultado da comparação entre esses valores e o endereço autorizado pela sessão.

Se a política do produto considerar equivalentes certas variações de endereços, essa equivalência deve servir apenas à regra de correspondência interna. Não deve alterar, sem respaldo na documentação, o valor solicitado que precisa ser refletido no token. Também não se deve inferir posse do endereço a partir do fato de o usuário estar autenticado em outra conta ou sessão.

Para ambientes de teste, use contas, sessões e endereços controlados e separados dos dados de produção. A orientação de privacidade para uso de endereços de teste pode ajudar a organizar esse limite: os dados usados para validar o fluxo não precisam identificar clientes reais.

Para segurança e QA, cubra falhas antes de liberar a emissão

Uma suíte que testa somente a solicitação válida comprova pouco. Ela mostra que existe um caminho de sucesso, mas não demonstra que o endpoint bloqueia pedidos manipulados ou sem vínculo com uma conta. A revisão deve exercitar casos positivos e negativos, verificando tanto o código de resposta quanto o efeito final: emissão ou ausência de token.

Um plano de teste pode incluir:

• Assinatura válida: mensagem e corpo correspondem à assinatura; a sessão e o endereço também são válidos.
• Assinatura ausente ou inválida: o endpoint rejeita a solicitação e não emite token.
• Resumo divergente: o corpo é alterado sem atualizar Content-Digest; a validação falha.
• Sessão ausente, expirada ou sem vínculo: a assinatura não deve autorizar a emissão por conta própria.
• Endereço diferente do associado à sessão: o servidor recusa o pedido, mesmo que a assinatura seja válida.
• Formato de cabeçalho em transição: cada forma documentada é testada com a versão de navegador correspondente, sem presumir uma única combinação universal.

Para evitar falsos positivos, verifique a ausência de emissão nos casos rejeitados. Uma resposta de erro não basta se um token ainda tiver sido criado por um caminho lateral, por uma tarefa assíncrona ou por uma rotina de recuperação. Em ambientes controlados, os registros de teste devem ligar a decisão final às verificações que foram executadas, sem expor chaves privadas, tokens ou dados pessoais desnecessários.

Também separe testes de assinatura de testes de fluxo completo. Um teste unitário da biblioteca criptográfica não prova que o endpoint montou a base de assinatura corretamente. Um teste de integração do endpoint não prova que o navegador aceitou o token. A validação de ponta a ponta deve deixar claro qual componente foi observado em cada etapa.

Para quem prepara a publicação, prove o fallback de e-mail separadamente

A aprovação do emissor não encerra a verificação de ponta a ponta. Há pelo menos três resultados diferentes a registrar: o provedor emitiu um token, o navegador aceitou esse resultado e o site concluiu a verificação. A equipe deve evitar apresentar um desses eventos como prova dos outros. Isso é especialmente importante quando um teste de recebimento de mensagem é usado para confirmar o caminho alternativo.

Antes da publicação, faça uma execução controlada:

1. Registre a versão do navegador e o formato de solicitação observado.
2. Envie uma solicitação válida e confirme que o endpoint executou todas as verificações previstas.
3. Confirme a emissão do resultado conforme o formato oficial vigente.
4. Teste a ausência de suporte, a falha de emissão e a rejeição no fluxo de verificação.
5. Em cada cenário aplicável, confirme que a confirmação por e-mail já existente continua disponível.
6. Registre evidências distintas para o comportamento do emissor, a aceitação no navegador e a conclusão no site.

O resultado do teste de e-mail também tem limites. Receber uma mensagem em uma caixa de teste mostra que aquele envio chegou àquela caixa naquele contexto. Não garante a entrega em produção, nem confirma o funcionamento da assinatura ou da emissão de tokens. Para escolher um endereço de teste e verificar o recebimento da mensagem, consulte o guia de opções de endereço para testes de e-mail e as orientações de verificação do recebimento de mensagens de teste.

Na publicação, documente a versão, o formato, o resultado de cada verificação e a evidência do fallback. Se a equipe usar ZOSend para observar o recebimento de uma mensagem de teste, trate isso somente como verificação do caminho de e-mail sob teste. Não substitui a validação do Chrome Email Verification API issuer nem comprova entrega futura em produção. Para um fluxo de cadastro que precisa preservar uma alternativa por e-mail, essa separação permite testar o recebimento sem confundir a mensagem com a prova de assinatura, sessão ou conclusão da verificação.