Реализация проверяющей стороны

Чтобы реализовать проверку адреса электронной почты на своем сайте, обновите разметку формы, чтобы запрашивать токен, и добавьте проверку входящих токенов на стороне сервера.

Зарегистрируйтесь для участия в эксперименте с источником

На сайтах, выполняющих проверку, должен быть настроен эксперимент с источником.

Начиная с Chrome 154 поддерживаются эксперименты со сторонними источниками, но с важной оговоркой: зарегистрированный источник для эксперимента должен быть тем же сайтом, что и эмитент. Пример:

  • Домен издателя: issuer.example
  • Регистрант OT: https://issuer.example
  • Источник JavaScript: https://issuer.example (или https://app.issuer.example с сопоставлением субдоменов).

Как настроить поля формы

Добавьте скрытое поле токена в форму отправки электронных писем:

<input
  type="email"
  name="email-address"
  autocomplete="email">
<input
  type="hidden"
  name="token"
  autocomplete="email-verification-token"
  nonce="rAnD0m-VaLuE">

Требования к полям

  • Поле адреса электронной почты. Задайте type="email" и autocomplete="email", чтобы Chrome мог распознавать адрес и автоматически заполнять поле.
  • Атрибуты поля токена:
    • Set autocomplete="email-verification-token": Chrome identifies this field to populate the token on submission.
    • Установите nonce="<VALUE>": сайт должен предоставлять уникальный одноразовый код, связанный с сеансом, чтобы подтвердить отправку формы.

Проверьте токен подтверждения адреса электронной почты (EVT)

Когда пользователь отправляет форму, ваш сервер получает адрес электронной почты и токен из скрытого поля. Пустое поле токена означает, что браузер или поставщик не поддерживает EVP или пользователь пропустил проверку. В этом случае вернитесь к существующему процессу подтверждения, например отправке одноразового кода или волшебной ссылки.

Если токен есть, проверьте его следующим образом:

  1. Проанализируйте токен с помощью библиотеки SD-JWT.
  2. Проверьте ожидаемые значения и утверждения сеанса.
  3. Проверьте делегирование DNS.
  4. Получение метаданных издателя и JWKS.
  5. Проверьте криптографические подписи и привязку ключей.

1. Как анализировать токен

Токен использует формат RFC 9901: Selective Disclosure JWT (SD-JWT+KB). Для синтаксического анализа и проверки токена используйте библиотеки, подходящие для вашей платформы. Например, для Node можно использовать @sd-jwt/core и jose. В необработанном виде это выглядит так: подписанный издателем токен JWT, за которым следует ноль или более раскрытий, а затем токен JWT для связывания ключей. Каждый компонент разделен тильдой:

<Issuer-signed EVT>~<Disclosure 1>~...~<Disclosure N>~<Key Binding JWT>

В текущей реализации токен не содержит раскрытия информации (<Issuer-signed EVT>~<Key Binding JWT>). Однако в будущем это может измениться.

Расшифруйте токен с помощью библиотеки:

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;

Если verifier.example подтверждает demo@provider.example, декодированный токен выглядит примерно так:

{
  "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. Как проверить ожидаемые значения и утверждения сеанса

Убедитесь, что основные значения в полезной нагрузке соответствуют предоставленным и ожидаемым значениям:

  • email_verified: должно быть true.
  • email: должен совпадать с адресом электронной почты, указанным в форме.
  • aud (аудитория) – должно совпадать с источником вашего сайта.
  • nonce: должно совпадать с одноразовым кодом, указанным в форме.
  • iat (время выпуска) и exp (срок действия). Убедитесь, что токен действителен и срок его действия не истек.

3. Проверьте делегирование DNS

Проверьте запись DNS _email-verification для домена адреса электронной почты. Например, для demo@gmail.com запросите запись TXT _email-verification.gmail.com. Для этого поставщика запрос возвращает местоположение поставщика аккаунта, то есть accounts.google.com.

$ dig +short TXT _email-verification.gmail.com
"iss=accounts.google.com"

Убедитесь, что схема издателя – https:// и что значение https://<domain> совпадает с утверждением iss в EVT.

4. Проверка подписи EVT

Получите метаданные обнаружения эмитента из 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"]
}

Если в метаданных есть поле issuer, убедитесь, что оно полностью совпадает с утверждением iss в EVT. Получите набор веб-ключей JSON из jwks_uri.

Используйте библиотеку SD-JWT, чтобы проверить пакет токенов. Библиотека координирует проверку:

  1. Проверка подписи издателя в EVT на соответствие полученному JWKS.
  2. Проверка подписи браузера в KB-JWT с помощью временного открытого ключа в cnf.jwk.
  3. Проверка привязки ключа (aud, nonce и хеш дайджеста sd_hash).

Пример логики проверки в 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");
}

Если все шаги выполнены успешно, вы подтвердили адрес электронной почты у поставщика. Если подтверждение не удалось, отправьте пользователю письмо с подтверждением, как обычно.

Устранение неполадок

Если подтверждение не удалось или браузер не предоставил токен, проверьте, нет ли у вас следующих распространенных проблем:

Поле токена не заполнено.

  • Регистрация пробной версии источника. Убедитесь, что на странице есть заголовок Origin-Trial или тег <meta> и что срок действия токена не истек (токены, созданные до выхода расширения Chrome 160, перестанут действовать 17 ноября 2026 г.). Для сторонних экспериментов с источником (Chrome 154 и более поздних версий) зарегистрированный источник эксперимента должен быть того же сайта, что и издатель (https://<issuer-domain>). Вы можете проверить статус эксперимента с источником и срок действия токена на сайте в инструментах разработчика в разделе Приложение > Фреймы > (выберите нужный фрейм) > Эксперименты с источником.
  • Разметка формы. Теги <input type="email" autocomplete="email"> и <input type="hidden" autocomplete="email-verification-token" nonce="..."> должны находиться в одном элементе <form> (не изолированном границами Shadow DOM), а тег nonce не должен быть пустым.
  • Ранняя отправка или повторное использование страницы. Браузер получает токен в фоновом режиме после того, как адрес электронной почты введен или подставлен автоматически. Если отправить форму до завершения запроса, токен останется пустым. Это может произойти, если пользователь нажмет клавишу возврата, чтобы отправить форму после ввода адреса электронной почты.
  • Требования к браузеру и поставщику. Пользователь должен войти в аккаунт у участвующего поставщика в том же профиле браузера, а в настройках Chrome (chrome://settings/contactInfo) должен быть включен параметр Подтвержденный адрес электронной почты.

Не удается проверить подпись эмитента.

  • Отсутствует заголовок kid. Утверждение kid (идентификатор ключа) в заголовке EVT и JWKS необязательно (например, Gmail опускает kid). Если kid отсутствует, переберите все ключи-кандидаты в jwks_uri издателя, а не останавливайтесь на поиске идентификатора ключа.
  • Идентификаторы алгоритмов (Ed25519 и EdDSA). Начиная с Chrome 156, Chrome использует полностью указанный идентификатор алгоритма Ed25519 (RFC 9864) для заголовков cnf.jwk и KB-JWT, а издатели и библиотеки могут указывать Ed25519 или EdDSA (наряду с ES256). Убедитесь, что логика импорта и проверки JWK принимает оба идентификатора.
  • Формат источника Issuer (iss). Запись DNS TXT (_email-verification.<domain>) содержит только имя хоста (iss=accounts.issuer.example), а утверждение EVT iss – полный источник HTTPS (https://accounts.issuer.example, без косой черты в конце). Перед сравнением добавьте к значению записи DNS префикс https://.

Не удалось выполнить проверку привязки ключа (KB-JWT)

  • Несоответствие или истечение срока действия одноразового кода. Убедитесь, что код nonce, отрисованный в теге <input>, соответствует одноразовому коду активного сеанса на вашем сервере и не был перезаписан другой вкладкой или использован в предыдущем запросе.
  • Несоответствие аудитории (aud). Утверждение aud – это источник HTTPS верификатора (https://verifier.example без пути или косой черты в конце).

Не удалось сравнить утверждение адреса электронной почты (email)

  • Регистр и канонизация. Chrome 156 и более поздние версии возвращают утверждение email в том виде, в котором оно было введено в форму, но более ранние версии браузера или поставщики могут возвращать канонизированный адрес (например, First.Last@example.com вместо first.last@example.com). При сопоставлении утверждения email токена со значением, указанным в форме, используйте сравнение без учета регистра.