Email Verification API 规范 Accounts Validation 算法逐行讲解-平芜编程栈

Email Verification API 规范 Accounts Validation 算法逐行讲解

【免费下载链接】email-verificationverified autofill项目地址: https://gitcode.com/GitHub_Trending/em/email-verification

Email Verification API（邮件验证协议 EVP）是 W3C 正在孵化的一项浏览器新规范：它让浏览器无需发送验证码邮件，就能通过加密令牌证明"这个邮箱确实归用户所有"。而Accounts Validation 算法正是决定浏览器"敢不敢签发令牌"的核心守门环节。本文面向新手，逐行讲解规范 index.bs 中的完整算法与配套流程。

📮 为什么需要 Email Verification API：验证码邮件的三大痛点

每次注册你都经历过：填邮箱 → 等验证邮件 → 可能在垃圾箱里找一圈 → 复制验证码 → 切回网站粘贴。README.md 引用的数据：访问排名前 50 的网站中 95% 支持邮箱注册，其中 73% 会在邮箱验证完成前阻止创建账号。

这条流程的代价：

🐌慢：验证邮件有投递延迟，还常进垃圾箱；
😰易被钓鱼：验证码可能被钓鱼页面"截胡"；
📉流失：注册漏斗每多一步，用户就少一批，获客成本上升。

EVP 的思路很直白：用户本来就已登录邮箱服务商，浏览器直接向服务商索要一个签名过的Email Verification Token（EVT，邮件验证令牌），跳过"发邮件"这一整环。

🤝 先认识三方角色：验证者、浏览器、签发方

角色	是谁	职责
Verifier 验证者	你的网站（注册页）	接收并校验令牌
User Agent 浏览器	浏览器	全程协调、居中担保
Issuer 签发方	邮箱服务商	签发带签名的 EVT

整体流程六步：登录状态上报 → 网站声明请求 → DNS 发现签发方 →Accounts Validation 账号校验→ 获取令牌 → 绑定并提交。完整时序图见 README.md。

🔍 Accounts Validation 算法逐行讲解

这个算法在做什么？一句话：确认"用户刚选中的邮箱，确实是他当前在这家服务商上已登录的账号之一"——这是"不能被冒用、不能凭空签发"的根基。

形式化定义见 index.bs，共 10 步，我们逐行拆解：

第 1 步：查询签发方的登录状态

使用 Login Status API 检查 |issuer| 的登录状态。

浏览器先问一句："用户此刻登录着这家邮箱服务商吗？"这是最前置的"门卫检查"，没登录则后面全白搭。

第 2 步：未登录则返回 false

若状态为logged-out，返回 false。

直截了当：没登录 → 立即失败 → 浏览器静默放弃，网站照常走传统验证码流程。这正是"优雅降级"的关键：整个机制失败时对用户零感知。

第 3 步：拉取 well-known 元数据文件

获取 |issuer| 的 well-known 文件。

浏览器从签发方的标准路径.well-known/web-identity拉取一份元数据文件——相当于调取签发方的"营业执照"，上面写着它的账号列表接口地址。

第 4 步：元数据缺失则返回 false

若 |wellKnown| 为 null，返回 false。

服务商不支持本协议（文件不存在、请求失败）→ 立即放弃。这也保证浏览器不会反复打扰不支持的服务商。

第 5 步：读取 accounts_endpoint 字段

取 |wellKnown| 中accounts_endpoint成员的值。

从"营业执照"上摘出"账号列表 API"的地址。

第 6 步：校验端点地址合法性

若 |accountsEndpoint| 缺失或不是有效 URL，返回 false。

格式把关：字段缺失或不是合法 URL → 失败。防止畸形元数据让后续请求跑到野马路上。

第 7 步：拉取当前登录的账号列表

执行 FedCM 的 fetch accounts 算法，得到 |accounts|。

浏览器带着用户 Cookie 请求该端点，签发方返回用户当前已登录的账号列表，例如john_a@x.com、john_b@x.com。

第 8 步：列表为空则返回 false

若 |accounts| 为 null 或空，返回 false。

列表都拿不到（会话过期、网络抖动等）→ 失败，不做任何后续动作。

第 9 步：逐个比对，大小写不敏感 ⭐

对每个 |account|：若其email与 |email| 大小写不敏感地相等，返回 true。

算法的核心一步：遍历账号列表，把每个账号邮箱和用户页面上选中的邮箱逐一比对，且忽略大小写——选中John@Example.com能匹配到已登录的john@example.com。一旦命中，立即返回 true，流程继续向签发令牌推进。

第 10 步：遍历结束未命中，返回 false

返回 false。

循环走完都没匹配（比如用户选了另一台设备才登录的邮箱）→ 返回 false，浏览器根本不会向签发方发出令牌请求。隐私保护就藏在这里：网站与签发方之间不发生任何不必要的通信。

💡设计总结：10 步里只有第 9 步是成功出口，其余全是"快速失败"。这种风格让算法可审计、行为可预期——没有已登录会话，什么都不会发生。

🔑 配套速览：EVT Issuance 签发算法

Accounts Validation 通过后，浏览器进入 EVT Issuance 算法，简化版五步：

生成一对一次性密钥（默认 Ed25519 算法）；
构造携带邮箱、签发方标识与时间戳的签名 JWT 请求；
POST 到签发方的签发端点，附带用户登录 Cookie；
校验返回的 SD-JWT 令牌：签名有效、公钥匹配、邮箱一致，三关全过；
浏览器把令牌绑定到网站源（origin）+ nonce（Key-Bound JWT），提交表单时写入隐藏字段。

网站侧的 Verifier Processing Model 则要求核对：audience 是我的源、nonce 是我生成的、令牌未过期，三者缺一不可。

✍️ 网站如何接入：只需一个隐藏的 input

接入成本极低，在现有注册表单加一行即可（真实环境如何开 Chrome 开关实测，见 HOWTO.md）：

<form action="/signup" method="post"> <input type="email" name="email" autocomplete="email"> <!-- EVP 隐藏字段：nonce 需服务端生成、每次渲染唯一 --> <input type="hidden" name="evt" autocomplete="email-verification-token" nonce="xyz123456789"> </form>

用户提交表单时，浏览器自动把 EVT 填进evt字段；填不上时该字段就为空，网站退回传统邮件验证——用户行为零改变。email-verification-token与nonce两个新约定的定义见规范 HTML Extensions 一节。

🛡️ 安全与隐私：三个设计亮点

防重放：令牌被双重绑定到origin + nonce，偷到 A 站点用不了 B 站点，换个页面也用不了（index.bs）；
签发方致盲：签发请求禁止携带网站的 Origin/Referer 头，邮箱服务商看不到"用户在哪个网站注册"；
优雅降级：任何一步失败都退回现状的验证码邮件流程，不增加用户负担。

更完整的隐私自查清单（暴露了什么、为什么最小化）见 QUESTIONNAIRE.md。

📚 资料导航

资料	说明
README.md	提案全文：背景数据、时序图、开放问题与备选方案
index.bs	规范源码（本文逐行讲解的对象）
index.html	渲染后的规范 HTML 版本
HOWTO.md	Chrome 实测指南：开启 flag、逐步验证
QUESTIONNAIRE.md	W3C 安全与隐私自查问卷
CONTRIBUTING.md	W3C WICG 贡献流程说明