Para implementar a verificação de e-mail no seu site, atualize a marcação do formulário para solicitar o token e adicione a validação do lado do servidor para os tokens recebidos.
Inscrever-se no teste de origem
Os sites de verificação precisam ter o teste de origem configurado.
A partir do Chrome 154, os testes de origem de terceiros são aceitos com uma ressalva importante: a origem registrada para o teste precisa ser do mesmo site do emissor. Exemplo:
- Domínio do emissor:
issuer.example - Registrante do teste de origem:
https://issuer.example - Origem do JavaScript:
https://issuer.example(ouhttps://app.issuer.examplecom correspondência de subdomínio)
Configurar campos de formulário
Adicione um campo de token oculto ao formulário de envio de e-mail:
<input
type="email"
name="email-address"
autocomplete="email">
<input
type="hidden"
name="token"
autocomplete="email-verification-token"
nonce="rAnD0m-VaLuE">
Requisitos de campo:
- Campo de e-mail: defina
type="email"eautocomplete="email"para que o Chrome possa preencher automaticamente e reconhecer o endereço. - Atributos do campo de token:
- Defina
autocomplete="email-verification-token": o Chrome identifica esse campo para preencher o token no envio. - Defina
nonce="<VALUE>": o site precisa fornecer um nonce exclusivo vinculado à sessão para verificar o envio do formulário.
- Defina
Validar o token de verificação de e-mail (EVT, na sigla em inglês)
Quando o usuário envia o formulário, o servidor recebe o endereço de e-mail e o token do campo oculto. Um campo de token vazio indica que o navegador ou provedor não oferece suporte ao EVP ou que o usuário ignorou a verificação. Se isso ocorrer, volte ao processo de verificação atual, como enviar um OTP ou um link mágico.
Se um token estiver presente, valide-o da seguinte maneira:
- Analise o token usando uma biblioteca SD-JWT.
- Valide os valores esperados e as declarações de sessão.
- Verifique a delegação de DNS.
- Descubra os metadados do emissor e busque o JWKS.
- Verifique as assinaturas criptográficas e a vinculação de chaves.
1. Analisar o token
O token usa o formato RFC 9901: Selective Disclosure JWT
(SD-JWT+KB). Use as bibliotecas adequadas para sua plataforma para analisar e validar o token.
Por exemplo, para o Node, você pode usar
@sd-jwt/core e
jose. Na forma bruta, ele se parece com um JWT assinado pelo emissor, seguido por zero ou mais divulgações e terminando com um JWT de vinculação de chaves, com cada componente separado por um til:
<Issuer-signed EVT>~<Disclosure 1>~...~<Disclosure N>~<Key Binding JWT>
Na implementação atual, o token contém zero divulgações
(<Issuer-signed EVT>~<Key Binding JWT>). No entanto, isso pode mudar no
futuro.
Decodifique o token com a biblioteca:
import { decodeSdJwtSync } from "@sd-jwt/core";
import { createHash } from "node:crypto";
const hasher = (data, alg) =>
createHash(alg === "sha-256" ? "sha256" : alg)
.update(data)
.digest();
const decoded = decodeSdJwtSync(rawToken, hasher);
const evtPayload = decoded.jwt.payload;
const kbPayload = decoded.kbJwt?.payload;
Se verifier.example verificar demo@provider.example, o token decodificado será semelhante ao seguinte:
{
"evtJwtDecodedHeader": {
"typ": "evt+jwt",
"alg": "EdDSA",
"kid": "issuer-key-id"
},
"evtJwtDecodedPayload": {
"iss": "https://provider.example",
"iat": 12345678901,
"exp": 12345679901,
"cnf": {
"jwk": {
"kty": "OKP",
"crv": "Ed25519",
"x": "pUbLiCkEy123pUbLiCkEy123pUbLiCkEy123"
}
},
"email": "demo@provider.example",
"email_verified": true
},
"kbJwtDecodedHeader": {
"alg": "EdDSA",
"typ": "kb+jwt"
},
"kbJwtDecodedPayload": {
"aud": "https://verifier.example",
"iat": 12345678901,
"nonce": "rAnDoM123rAnDoM123rAnDoM123rAnDoM123",
"sd_hash": "hAsH456hAsH456hAsH456hAsH456hAsH456"
},
"disclosures": []
}
2. Validar os valores esperados e as declarações de sessão
Verifique se os valores básicos no payload correspondem aos valores fornecidos e esperados:
email_verified: precisa sertrue.email: precisa corresponder ao endereço de e-mail enviado no formulário.aud(público-alvo): precisa corresponder à origem do seu site.nonce: precisa corresponder ao nonce fornecido no formulário.iat(emitido em) eexp(expiração): confirme se o token está dentro da janela de tempo válida e não expirou.
3. Verificar a delegação de DNS
Verifique o registro DNS _email-verification do domínio do endereço de e-mail. Por exemplo, para demo@gmail.com, consulte o registro TXT _email-verification.gmail.com. Para esse provedor, a consulta retorna o local do provedor da conta, ou seja, accounts.google.com.
$ dig +short TXT _email-verification.gmail.com
"iss=accounts.google.com"
Verifique se o esquema do emissor é https:// e se https://<domain> corresponde
à iss declaração no EVT.
4. Verificar a assinatura do EVT
Busque os metadados de descoberta do emissor em
https://<issuer>/.well-known/email-verification:
{
"issuer": "https://accounts.google.com",
"issuance_endpoint": "https://accounts.google.com/gsi/email-verification/issue",
"jwks_uri": "https://verifiablecredentials-pa.googleapis.com/.well-known/vc-public-jwks",
"signing_alg_values_supported": ["Ed25519", "EdDSA"]
}
Se os metadados incluírem um campo issuer, verifique se ele corresponde à iss
declaração no EVT byte a byte. Busque o conjunto de chaves da Web JSON em jwks_uri.
Use sua biblioteca SD-JWT para verificar o pacote de tokens. A biblioteca coordena a validação:
- Validar a assinatura do emissor no EVT em relação ao JWKS buscado.
- Validar a assinatura do navegador no KB-JWT usando a chave pública efêmera em
cnf.jwk. - Verificar a vinculação de chaves (
aud,noncee o hash de resumosd_hash).
Exemplo de lógica de verificação no Node.js:
import { SDJwtInstance } from "@sd-jwt/core";
import { importJWK, compactVerify } from "jose";
import { createHash } from "node:crypto";
const allowedAlgs = ["Ed25519", "EdDSA", "ES256"];
const evtAlg = decoded.jwt.header.alg;
const kbAlg = decoded.kbJwt?.header.alg;
if (!allowedAlgs.includes(evtAlg) || !allowedAlgs.includes(kbAlg)) {
throw new Error("Unsupported signing algorithm");
}
const hasher = (data, alg) =>
createHash(alg === "sha-256" ? "sha256" : alg)
.update(data)
.digest();
const sdJwt = new SDJwtInstance({ hasher });
sdJwt.config({
hasher,
// Verifier for the Issuer-signed EVT
verifier: async (data, sig) => {
const token = `${data}.${sig}`;
const header = decoded.jwt.header;
// Match by kid if present, or iterate across matching algorithm keys
const keysToTry = header.kid
? jwksData.keys.filter(k => k.kid === header.kid)
: jwksData.keys;
for (const jwk of keysToTry) {
try {
const pubKey = await importJWK(jwk, jwk.alg || evtAlg);
await compactVerify(token, pubKey);
return true;
} catch {
// Try next candidate key
}
}
return false;
},
// Verifier for the Key Binding JWT (KB-JWT)
kbVerifier: async (data, sig) => {
try {
const browserJwkKey = evtPayload.cnf?.jwk;
if (!browserJwkKey) return false;
const pubKey = await importJWK(browserJwkKey, kbAlg);
await compactVerify(`${data}.${sig}`, pubKey);
return true;
} catch {
return false;
}
},
});
// The library automatically verifies EVT signature, KB-JWT signature, audience, nonce, and sd_hash
const result = await sdJwt.verify(rawToken, {
kb: {
expectedNonce: sessionNonce,
expectedAudience: "https://example.com",
required: true,
},
});
const verifiedPayload = result.payload;
if (
verifiedPayload.email_verified !== true ||
verifiedPayload.email?.toLowerCase() !== submittedEmail.toLowerCase()
) {
throw new Error("Token email does not match submitted email");
}
Se todas as etapas forem bem-sucedidas, você terá verificado o endereço de e-mail com o provedor. Se a verificação falhar, volte a enviar um e-mail de confirmação ao usuário usando o fluxo normal.
Solução de problemas
Se a verificação falhar ou o navegador não fornecer um token, confira os seguintes problemas comuns:
O campo de token está vazio no envio
- Registro do teste de origem: confirme se o cabeçalho
Origin-Trialou a<meta>tag é veiculada na página e se o token não passou da data de validade (os tokens gerados antes da extensão do Chrome 160 expiram em 17 de novembro de 2026). Para testes de origem de terceiros (Chrome 154 e versões mais recentes), a origem do teste registrada precisa ser do mesmo site do emissor (https://<issuer-domain>). Você pode inspecionar o status do teste de origem e a expiração do token em um site nas Ferramentas para desenvolvedores em Application > Frames > (selecione o frame relevante) > Origin trials. - Marcação de formulário:
<input type="email" autocomplete="email">e<input type="hidden" autocomplete="email-verification-token" nonce="...">precisam estar no mesmo elemento<form>(não isolado em limites do Shadow DOM ) enoncenão pode estar vazio. - Envio antecipado ou página reutilizada: o navegador busca o token em segundo plano depois que o e-mail é inserido ou preenchido automaticamente. O envio antes da conclusão da solicitação deixa o token vazio. Isso pode acontecer se o usuário pressionar "Retornar" para enviar o formulário depois de inserir o e-mail.
- Pré-requisitos do navegador e do provedor: o usuário precisa fazer login em um
provedor participante no mesmo perfil do navegador e ter o e-mail
verificado ativado nas configurações do Chrome (
chrome://settings/contactInfo).
A verificação da assinatura do emissor falha
- Cabeçalho
kidausente: a declaraçãokid(ID da chave) no cabeçalho EVT e no JWKS é opcional (por exemplo, o Gmail omitekid). Sekidestiver ausente, itere por todas as chaves candidatas nojwks_urido emissor em vez de falhar em uma pesquisa de ID de chave. - Identificadores de algoritmo (
Ed25519eEdDSA): a partir do Chrome 156, o Chrome usa o identificador de algoritmoEd25519totalmente especificado (RFC 9864) para cabeçalhoscnf.jwkeKB-JWT, enquanto emissores e bibliotecas podem especificarEd25519ouEdDSA(junto comES256). Verifique se a lógica de importação e verificação do JWK aceita os dois identificadores. - Formato de origem do emissor (
iss): o registro TXT do DNS (_email-verification.<domain>) contém um nome de host simples (iss=accounts.issuer.example), enquanto a declaraçãoissdo EVT é uma origem HTTPS completa (https://accounts.issuer.example, sem barra à direita). Adicione o prefixohttps://ao valor do registro DNS antes de comparar.
A validação da vinculação de chaves (KB-JWT) falha
- Nonce incompatível ou expirado: verifique se o
noncerenderizado no<input>corresponde ao nonce da sessão ativa no servidor e não foi substituído por outra guia ou consumido por uma solicitação anterior. - Incompatibilidade de público-alvo (
aud): a declaraçãoaudé a origem HTTPS do verificador (https://verifier.example, sem caminho ou barra à direita).
A comparação da declaração de e-mail (email) falha
- Maiúsculas e minúsculas e canonicalização: o Chrome 156 e versões mais recentes retornam a declaração
emailbyte a byte conforme inserida no formulário, mas versões anteriores do navegador ou provedores podem retornar um endereço canonicalizado (por exemplo,First.Last@example.comparafirst.last@example.com). Use uma comparação que não diferencia maiúsculas de minúsculas ao comparar a declaraçãoemaildo token com o valor do formulário enviado.