Implementação do provedor de e-mail (emissor)

Para mais detalhes, consulte o código de demonstração do provedor de e-mail simulado e as etapas do emissor nas propostas da API de verificação de e-mail e do protocolo de verificação de e-mail.

Como emissor, você não precisa se inscrever no teste de origem nem fornecer um token, porque o site da parte confiável aciona o comportamento do navegador. Verifique se os endpoints estão configurados para responder a essas solicitações.

Configurar a descoberta do emissor

Para permitir que os navegadores descubram automaticamente seus endpoints de verificação quando um endereço de e-mail pertencente ao seu domínio for selecionado, exponha sua configuração usando o DNS e um endpoint HTTP .well-known.

Configurar o registro de delegado de DNS

Configure um registro TXT de DNS no seu domínio de e-mail que delega a autoridade de verificação ao identificador do emissor. Esses identificadores podem usar o mesmo domínio, dependendo da sua infraestrutura.

Formato do registro: _email-verification.<email-domain>

Exemplo de arquivo de zona:

_email-verification.example.com IN TXT "iss=accounts.issuer.example"

O valor iss= precisa ser um nome do host canônico e simples em letras minúsculas (por exemplo, iss=accounts.issuer.example) sem esquema (https://), porta, caminho ou caracteres maiúsculos. O Chrome rejeita registros que incluem componentes que não são nomes de host.

Hospedar um endpoint .well-known/email-verification

Hospede um arquivo JSON de metadados no domínio do emissor no caminho /.well-known/. Esse arquivo descreve suas capacidades de emissão e os algoritmos de assinatura criptográfica que sua infraestrutura oferece suporte.

Endpoint: https://<issuer-domain>/.well-known/email-verification

Exemplo de resposta:

{
  "issuer": "https://accounts.issuer.example",
  "issuance_endpoint": "https://accounts.issuer.example/email-verification/issuance",
  "jwks_uri": "https://accounts.issuer.example/.well-known/vc-public-jwks",
  "signing_alg_values_supported": ["Ed25519", "EdDSA", "ES256"]
}

Propriedades de metadados:

  • issuer: a origem do emissor (https://<issuer-domain>, sem barra à direita). Precisa corresponder à origem em que o arquivo de metadados é veiculado byte a byte.
  • issuance_endpoint: o URL HTTPS que recebe solicitações POST de emissão de token.
  • jwks_uri: o URL HTTPS que veicula seu conjunto de chaves da Web JSON (JWKS).
  • signing_alg_values_supported: matriz de algoritmos de assinatura JWS compatíveis.

Hospedar um endpoint .well-known/web-identity

Talvez você já tenha implementado um recurso JSON .well-known adicional como parte da API Federated Credentials (FedCM). Esse recurso fornece links para o endpoint de contas e o URL de login.

Endpoint: https://<domain>/.well-known/web-identity

Exemplo de resposta:

{
  "accounts_endpoint": "https://accounts.issuer.example/accounts",
  "login_url": "https://accounts.issuer.example/login"
}

Usar um endpoint de contas

O endpoint de contas da API FedCM fornece uma lista de contas conectadas no momento. O exemplo a seguir mostra uma resposta mínima. Para mais detalhes, consulte o guia de implementação do provedor de identidade.

Endpoint: conforme especificado em .well-known/web-identity

Veja a seguir um exemplo de resposta:

{
  "accounts": [
    {
      "id": "demo-example",
      "name": "Demo User",
      "email": "demo@example.com",
      "given_name": "Demo"
    }
  ]
}

Integrar com a API Login Status

O usuário precisa ter uma sessão ativa com o provedor, e você precisa sinalizar isso para o navegador usando a API Login Status.

Quando um usuário faz login ou logout, veicule o cabeçalho de resposta HTTP correspondente:

Set-Login: logged-in
Set-Login: logged-out

Como alternativa, atualize o status usando JavaScript no contexto do aplicativo da Web:

navigator.login.setStatus("logged-in");
navigator.login.setStatus("logged-out");

Processar solicitações de emissão

O issuance_endpoint recebe uma solicitação application/json POST que contém a chave email e os cabeçalhos de assinaturas de mensagens HTTP para Signature, Signature-Input e Signature-Key.

Use uma biblioteca que ofereça suporte a cabeçalhos estruturados e assinaturas de mensagens HTTP para seu ambiente. No Node.js, você pode usar structured-headers e http-message-sig.

Formato completo da solicitação:

POST /email-verification/issuance HTTP/1.1
Host: provider.example
Accept: application/json
Content-Digest: sha-256=:aBc123aBc123aBc123aBc123aBc123=:
Content-Type: application/json
Sec-Fetch-Dest: email-verification
Signature: sig=:+dEf567dEf567/dEf567dEf567dEf567/dEf567==:
Signature-Input: sig=("@method" "@authority" "@path" "content-digest" "signature-key");created=1786455840
Signature-Key: sig=hwk;alg="Ed25519";crv="Ed25519";kty="OKP";x="gHi890_gHi890_gHi890"

{email: "demo@example.com"}

Analise e valide a solicitação:

  • Autenticação de sessão: valide os cookies de sessão primários enviados com a solicitação. O usuário precisa ser autenticado.
  • Cabeçalho Sec-Fetch-Dest: definido como email-verification.
  • Assinaturas de mensagens HTTP: verifique a assinatura da solicitação usando a chave pública efêmera em Signature-Key e valide o Content-Digest. A partir do Chrome 156, o Signature-Key cabeçalho inclui alg="Ed25519" nos seus hwk parâmetros. Aceite "Ed25519" e "EdDSA" e permita que alg seja omitido por versões anteriores do Chrome.
  • Payload: o corpo JSON contém a string email solicitada para verificação.

Resposta de emissão

Após a validação da sessão e do token de solicitação, gere um JWT de divulgação seletiva (SD-JWT) assinado retornado como JSON usando bibliotecas adequadas para sua plataforma. Por exemplo, para o Node, você pode usar @sd-jwt/core e jose.

O formato do payload bruto precisa ser semelhante a:

{
  "iss": "https://accounts.issuer.example",
  "iat": 1780272000,
  "exp": 1780272300,
  "cnf": {
    "jwk": {
      "kty": "EC",
      "crv": "P-256",
      "x": "pUbLiCKeY123pUbLiCKeY123pUbLiCKeY123",
      "y": "pUbLiCKeY456pUbLiCKeY456pUbLiCKeY456"
    }
  },
  "email": "demo@example.com",
  "email_verified": true
}

Crie, assine e retorne o token:

import { importJWK, CompactSign } from "jose";
import { SDJwtInstance } from "@sd-jwt/core";
import crypto from "node:crypto";
// Issuer private key from secure storage
const privateKey = await importJWK(PRIVATE_KEY_JWK, "EdDSA");
const origin = url.origin;
const currentTime = Math.floor(Date.now() / 1000);
const evtPayload = {
  iss: origin,
  iat: currentTime,
  exp: currentTime + 300, // 5 minutes
  cnf: {
    jwk: browserJwk,
  },
  email: payload.email, // exactly as received in payload
  email_verified: true,
};
const sdJwt = new SDJwtInstance({
  signer: async (data) => {
    const [headerB64, payloadB64] = data.split(".");
    const header = JSON.parse(Buffer.from(headerB64, "base64url").toString());
    const payload = Buffer.from(payloadB64, "base64url");
    const signed = await new CompactSign(payload).setProtectedHeader(header).sign(privateKey);
    return signed.split(".").pop()!;
  },
  signAlg: "EdDSA",
  hasher: async (data, alg) => {
    const nodeAlg = alg.replace("-", "");
    return new Uint8Array(crypto.createHash(nodeAlg).update(data).digest());
  },
  hashAlg: "sha-256",
  saltGenerator: async () => crypto.randomBytes(16).toString("base64url"),
});
const issuanceToken = await sdJwt.issue(evtPayload, undefined, {
  header: {
    alg: "EdDSA",
    kid: PRIVATE_KEY_JWK.kid,
    typ: "evt+jwt",
  },
});
return sendResponse({ issuance_token: issuanceToken, }, 200);

O corpo da resposta resultante é semelhante a:

{
  "issuance_token": "tOkEn123tOkEn123tOkEn123...~"
}

Depois de criar e assinar o token de verificação de e-mail, o navegador o transmite ao site do verificador para validação.

Solução de problemas

Se o navegador não entrar em contato com seus endpoints ou rejeitar tokens emitidos, verifique os seguintes problemas comuns:

O navegador nunca chama accounts_endpoint ou issuance_endpoint

  • Status de login não definido: o Chrome só consulta seus endpoints se souber que o usuário está conectado. Verifique se o fluxo de login define o Set-Login: logged-in cabeçalho HTTP ou chama navigator.login.setStatus("logged-in").
  • Cookies de sessão bloqueados (SameSite=None): o navegador busca seu accounts_endpoint e issuance_endpoint de uma parte confiável em um site diferente. Como essas são solicitações entre sites, o cookie de sessão precisa incluir SameSite=None; Secure. Um cookie SameSite=Lax funciona ao testar em um verificador do mesmo site, mas é omitido em solicitações entre sites.
  • Incompatibilidade de descoberta ou conta: verifique se _email-verification.<email-domain> retorna um único registro TXT com um nome do host canônico em letras minúsculas (iss=<issuer-domain>, sem https://, uma porta, um caminho ou caracteres maiúsculos), se os dois endpoints .well-known retornam Content-Type: application/json, se .well-known/email-verification tem um issuer correspondente a https://<issuer-domain> byte a byte e se a accounts_endpoint resposta inclui uma conta cujo email corresponde ao endereço inserido.
  • Algoritmo de assinatura não compatível em .well-known/email-verification: o Chrome 154 e 155 exigem "EdDSA" em signing_alg_values_supported, enquanto o Chrome 156 e versões mais recentes e a especificação IETF oferecem suporte a "Ed25519". Anuncie ["Ed25519", "EdDSA"] durante a transição para que o Chrome Stable não rejeite seus metadados de descoberta.

A validação da solicitação de emissão falha

  • Sec-Fetch-Dest ortografia do cabeçalho: o Chrome 154 e versões mais recentes enviam Sec-Fetch-Dest: email-verification (com um hífen), enquanto o Chrome 153 enviou emailverification (sem um hífen). Aceite os dois valores durante o lançamento.
  • Incompatibilidade de assinatura de mensagem HTTP (@authority) por trás de um proxy: ao verificar a assinatura RFC 9421, o componente @authority reflete o host público. Se o servidor estiver por trás de um proxy reverso ou balanceador de carga, reconstrua o URL de verificação usando X-Forwarded-Host (ou sua origem pública) em vez do nome do host interno e calcule Content-Digest nos bytes do corpo da solicitação bruta antes da análise JSON.

O navegador rejeita o issuance_token retornado

  • Declaração email modificada ou canônica: a partir do Chrome 156, o navegador verifica se a declaração email do EVT corresponde ao email byte a byte. Se o back-end normalizar o endereço para um formato de conta canônico (como retornar First.Last@example.com quando first.LAST@example.com foi solicitado), o Chrome vai descartar o token. Faça a correspondência da solicitação com a conta do usuário, mas retorne a string email exata recebida no corpo da solicitação.
  • Til (~) ausente: mesmo com zero divulgações, o issuance_token precisa ser um SD-JWT válido que termina com um til (<Issuer-signed-JWT>~) para que o navegador possa anexar o <KB-JWT>.
  • iss ou cnf.jwk incompatíveis: verifique se a declaração iss do EVT é a origem HTTPS exata (https://<issuer-domain>, sem barra à direita) que corresponde aos metadados .well-known/email-verification e se cnf.jwk incorpora a chave pública efêmera do navegador do cabeçalho Signature-Key.