Download the PHP package svss-labs/email-verification-api without Composer

📧 ✅ Email Verification API for PHP

A PHP library to verify Email Verification Tokens (EVT) issued through the Email Verification Protocol — the proposed web standard that lets browsers verify a user's email address with their email provider directly, without one-time passwords (OTPs) or magic links.

The user picks their email address in a form, the browser obtains a cryptographically signed token from their email provider (e.g. Gmail), and your server verifies it with this package. No email is ever sent.

Requirements

• PHP 8.3+
• Composer
• PHP extensions: curl, gmp, openssl, sodium (standard on most hosts; sodium and gmp are required for Ed25519 signature verification and safe IP arithmetic)

Installation

How the protocol works

1. Your site renders a form with a hidden field carrying a per-render nonce.
2. The user enters (or autocomplete-selects) their email address.
3. The browser discovers the issuer via a DNS TXT record (_email-verification.<email-domain>), confirms the user's session with the provider, and obtains a signed token.
4. On form submit, the browser attaches the token (an SD-JWT with a Key Binding JWT) to the hidden field.
5. Your server verifies the full package: parsing → expected values (email/nonce/audience/age) → DNS delegation → issuer signature (metadata + JWKS) → key binding.

Full protocol details: Chrome developer article.

Usage

Form markup

The browser only attaches a token when the form follows this exact contract:

Laravel example

The token is bound to the nonce that was present when the user's email field changed, which can happen on a page load different from the submit. Store a small pool of recent nonces server-side (here in the session) so the submit handler can match the one the token was bound to.

routes/web.php

app/Http/Controllers/EmailVerificationController.php

resources/views/signup.blade.php

Nonce matching: pull('evp_nonce') works when the submit happens on the same page load. For the field-change-on-early-load case, keep the pool from show() (e.g. in the session) and match the nonce claim embedded in the token's KB-JWT, exactly like example/live-demo.php does.

VerifyEmailTokenInput

Result

verifyEmailToken() returns a Result object:

• Success: $result->ok === true, $result->value is a VerifiedEmail with email, issuer, audience, issuedAt (['evt' => ..., 'keyBinding' => ...]) and the full decoded claims.
• Failure: $result->ok === false, $result->error is a VerificationError with stage (input, parse, expected-values, dns, issuer, key-binding), code, message and optional cause.

Common error codes:

Security notes

• Fail-closed: any internal error results in a verification failure, never a false positive.
• SSRF-safe network calls: issuer endpoints must be HTTPS, on publicly-routable hosts; resolved IPs are validated against global ranges and pinned via cURL CURLOPT_RESOLVE; redirects are disabled.
• Constant-time comparisons (hash_equals) for signature-relevant hash checks; strict algorithm/key-type compatibility mapping prevents algorithm-confusion attacks.
• Nonces should be single-use, random (e.g. bin2hex(random_bytes(32))) and bound to the user's session.

Testing your integration

1. Offline demo (no browser needed)

Uses test fixtures and mocked network callbacks to walk through a successful verification.

2. Live browser demo (real Google/Gmail verification)

Open http://localhost:8080, enter your Gmail address, and submit — the page verifies a real token against Google's production issuer (real DNS, real JWKS).

⚠️ Browser requirements — enable the Chrome flag

The browser side of this protocol is experimental and disabled by default. If no token is attached to your form:

1. Open chrome://flags/#email-verification-protocol and set Email Verification Protocol to Enabled

Also required:

• Desktop Chrome 150+ (desktop-only up to Chrome 152)
• Signed in to your email provider in the same browser profile (for Gmail: signed into your Google Account)
• The origin trial token active on your origin for production use — sign up at the Chrome origin trials dashboard and either serve it as a <meta http-equiv="origin-trial" content="..."> tag (the live demo auto-injects one from the EVP_OT_TOKEN env var or example/origin-trial-token.txt) or as a response header
• Since Chrome 152, typing or pasting the email triggers verification on field change; earlier versions require selecting from the autocomplete dropdown
• Since Chrome 152, while verification runs Chrome shows a progress indicator (spinner → checkmark) inside the email input field; the form may submit before it finishes, so don't rely on it completing before submit

You can sanity-check your browser setup independently with Google's verifier demo and mock email provider.

Troubleshooting

Development

Compatibility

• Gmail participates in the origin trial; any @gmail.com address works when signed in.
• Breaking changes are expected while the protocol is experimental. The most notable one — Chrome 153 switching issuer requests to HTTP Message Signatures — only affects email providers that issue tokens. This library only verifies tokens, so no code changes are required on our side; you can keep this package updated to pick up any refinements to SD-JWT parsing, key binding, or expected-value checks that the protocol evolves.
• Watch the WICG repo and the evp-announce mailing list for ongoing protocol changes.

License

The MIT License (MIT). Please see License File for more information.