پیاده‌سازی طرف اعتماد

برای پیاده‌سازی درستی‌سنجی ایمیل در سایتتان، نشان‌گذاری فرمتان را به‌روز کنید تا نمودافزار را درخواست کند و اعتبارسنجی سمت سرور را برای نمودافزارهای ورودی اضافه کنید.

ثبت‌نام برای آزمایش معرفی ویژگی جدید

سایت‌های درستی‌سنجی باید آزمایش معرفی ویژگی جدید را در سایتشان پیکربندی کرده باشند.

از Chrome 154، آزمایش‌های معرفی ویژگی جدید طرف سوم با یک هشدار مهم پشتیبانی می‌شوند: مبدأ ثبت‌شده برای آزمایش باید با صادرکننده در یک سایت باشد. برای مثال:

  • دامنه صادرکننده: issuer.example
  • ثبت‌کننده OT: https://issuer.example
  • مبدأ جاوا اسکریپت: 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 بتواند نشانی را تشخیص دهد و به‌طور خودکار تکمیل کند.
  • مشخصه‌های فیلد توکن:
    • تنظیم autocomplete="email-verification-token": Chrome این فیلد را شناسایی می‌کند تا نشان را هنگام ارسال تکمیل کند.
    • تنظیم nonce="<VALUE>": سایت باید یک مقدار یک‌باره منحصربه‌فرد و محدود به جلسه برای درستی‌سنجی ارسال فرم ارائه دهد.

اعتبارسنجی کردن کد درستی‌سنجی ایمیل (EVT)

وقتی کاربر فرم را ارسال می‌کند، سرور شما نشانی ایمیل و نشان را از فیلد پنهان دریافت می‌کند. فیلد کد خالی نشان می‌دهد که مرورگر یا ارائه‌دهنده از EVP پشتیبانی نمی‌کند یا کاربر از درستی‌سنجی رد شده است. اگر این اتفاق افتاد، به فرایند درستی‌سنجی موجودتان، مثل ارسال رمز یک‌بارمصرف یا پیوند جادویی، برگردید.

اگر کد وجود دارد، آن را به‌صورت زیر اعتبارسنجی کنید:

  1. بااستفاده از کتابخانه SD-JWT، کد را تجزیه کنید.
  2. مقادیر موردانتظار و ادعاهای جلسه را اعتبارسنجی کنید.
  3. واگذاری ساناد را درستی‌سنجی کنید.
  4. فراداده صادرکننده را کاوش کنید و JWKS را واکشی کنید.
  5. درستی‌سنجی امضاهای رمزنگاری و اتصال کلید.

۱. تجزیه کد

این توکن از قالب 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": []
}

۲. اعتبارسنجی مقادیر موردانتظار و ادعاهای جلسه

بررسی کنید که مقادیر پایه در پیام‌واره با مقادیر ارائه‌شده و موردانتظار شما مطابقت داشته باشد:

  • email_verified: باید true باشد.
  • email: باید با نشانی ایمیل ارسال‌شده در فرم مطابقت داشته باشد.
  • ‫aud (مخاطب): باید با مبدأ سایت شما مطابقت داشته باشد.
  • nonce: باید با مقدار یک‌بارمصرف ارائه‌شده در فرمتان مطابقت داشته باشد.
  • iat (صادرشده در) و exp (انقضا): تأیید کنید که توکن در پنجره زمانی معتبر خود قرار دارد و منقضی نشده است.

۳. درستی‌سنجی واگذاری ساناد

سابقه ساناد _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 مطابقت دارد.

۴. درستی‌سنجی امضای 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 در ۱۷ نوامبر ۲۰۲۶ منقضی می‌شوند). برای آزمایش‌های معرفی ویژگی جدید شخص ثالث (Chrome نسخه ۱۵۴ و بالاتر)، مبدأ آزمایش ثبت‌شده باید با صادرکننده (https://<issuer-domain>) در یک سایت باشد. می‌توانید وضعیت آزمایش معرفی ویژگی جدید و انقضای توکن را در سایت در DevTools در بخش برنامه > قاب‌ها > (انتخاب قاب مربوطه) > آزمایش‌های معرفی ویژگی جدید بررسی کنید.
  • نشانه‌گذاری فرم: هم <input type="email" autocomplete="email"> و هم <input type="hidden" autocomplete="email-verification-token" nonce="..."> باید در عنصر <form> یکسانی باشند (در مرزهای «سایه DOM» جدا نباشند)، و nonce نباید خالی باشد.
  • ارسال زودرس یا صفحه بازاستفاده‌شده: مرورگر پس‌از وارد شدن یا تکمیل خودکار ایمیل، نشانه را در پس‌زمینه واکشی می‌کند. ارسال کردن پیش‌از تکمیل درخواست، باعث می‌شود که توکن خالی بماند. این اتفاق زمانی می‌افتد که کاربر پس‌از وارد کردن ایمیلش، کلید Return را برای ارسال فرم فشار دهد.
  • پیش‌نیازهای مرورگر و ارائه‌دهنده: کاربر باید در همان نمایه مرورگر به سیستم ارائه‌دهنده مشارکت‌کننده وارد شده باشد و ایمیل تأییدشده را در تنظیمات 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 شما هردو شناسه را می‌پذیرد.
  • قالب مبدأ صادرکننده (iss): رکورد DNS TXT (_email-verification.<domain>) حاوی نام میزبان خالی (iss=accounts.issuer.example) است، درحالی‌که ادعای EVT iss یک مبدأ کامل HTTPS (https://accounts.issuer.example، بدون خط مورب پایانی) است. پیشوند https:// به مقدار رکورد ساناد قبل‌از مقایسه.

اعتبارسنجی اتصال کلید (KB-JWT) ناموفق است

  • مقدار یک‌بارمصرف نامنطبق یا منقضی‌شده: مطمئن شوید nonce ارائه‌شده در <input> با مقدار یک‌بارمصرف جلسه فعال در سرورتان مطابقت داشته باشد و توسط برگه دیگری بازنویسی نشده باشد یا توسط درخواست قبلی مصرف نشده باشد.
  • عدم تطابق مخاطب (aud): ادعای aud مبدأ HTTPS تأییدکننده است (https://verifier.example، بدون مسیر یا خط مورب پایانی).

مقایسه ادعای ایمیل (email) ناموفق بود

  • حروف بزرگ و کوچک و متعارف‌سازی: Chrome 156+ ادعای email را به‌صورت بایت‌به‌بایت همان‌طور که در فرم وارد شده است برمی‌گرداند، اما نسخه‌های قدیمی‌تر مرورگر یا ارائه‌دهندگان ممکن است نشانی متعارف‌شده‌ای را برگردانند (برای مثال، First.Last@example.com برای first.last@example.com). هنگام مطابقت دادن ادعای email کد با مقدار فرم ارسال‌شده، از مقایسه غیرحساس به حروف بزرگ و کوچک استفاده کنید.