Email Verification
Email verification proves that a person can read mail sent to the address on their account. Until they click the link you mailed them, the account is unverified. You’d want this before sending invoices to that address, before letting them join a team, or before trusting the address for a password reset.
In Strutvane it’s the emailVerification switch in config/auth.ts. The installer turns it on by default (question 6, “Extra sign-in security”).
The smallest example
Section titled “The smallest example”-
Turn it on:
config/auth.ts import { defineAuthConfig } from '@strutvane/auth'export default defineAuthConfig({appUrl: process.env.APP_URL ?? 'http://localhost:3000',features: { emailVerification: true },}) -
A new user signs up (with
registrationon) or is created by an admin. They receive a mail with a link like:http://localhost:3000/email/verify/0193a1c2-7e4b-7c1d-9f2e-5a6b7c8d9e0f/4f1c2e7a0b4d6f8e1a3c5b7d9e0f2a4c6b8d0e1f?expires=1763202121&signature=5d1c8a3e… -
They click it.
What you’ll see: the link answers 204 No Content (your page then shows “Thanks, your email is verified”), and GET /user now says:
{ "user": { "id": "0193a1c2-7e4b-7c1d-9f2e-5a6b7c8d9e0f", "email": "grace@example.com", "emailVerified": true } }The link, piece by piece
Section titled “The link, piece by piece”/email/verify/{id}/{hash}?expires={expires}&signature={signature}| Part | Example | What it is |
|---|---|---|
{id} |
0193a1c2-7e4b-… |
the user’s id (a UUID) |
{hash} |
4f1c2e7a… (40 hex characters) |
a keyed digest of the user’s current address |
expires |
1763202121 |
when the link stops working, in seconds since 1970 |
signature |
5d1c8a3e… |
an HMAC made by the framework’s one signer (the same one signed routes and file links use) over the path, the query, the expiry and the purpose, with a key derived from your APP_KEY |
What this gives you:
- It can’t be edited. Change any character (another user’s id, a later
expires) and the signature no longer matches. - It expires. 60 minutes by default (
links.verificationMinutes). - It’s tied to the address. If the user changes their email, links sent to the old address stop working, because the
{hash}no longer matches. - It needs no session. The signature is the proof, so the link works on a phone even if the user signed up on a laptop.
- Clicking it twice is harmless. The second click also answers
204. - Nothing is stored. The link carries everything; there is no table of verification tokens to clean up.
Resending the link
Section titled “Resending the link”A signed-in, unverified user asks for a fresh link (your “check your inbox” screen has a “Send it again” button):
curl -X POST http://localhost:3000/email/verification-notification \ -H "Origin: http://localhost:3000" \ -H "Cookie: strutvane_session=<your session>"What you’ll see: one of two answers:
{"status":"sent"}{"status":"already-verified"}Throttling, per account:
| Limit | Default | Setting |
|---|---|---|
| Wait between two mails | 60 seconds | limits.verificationResendCooldown |
| Mails per hour | 6 | limits.verificationResendPerAccount |
Only a mail that was actually sent starts the 60-second wait, so a refused click doesn’t push it further away. Too soon:
HTTP/1.1 429 Too Many Requestsretry-after: 42content-type: application/problem+json
{"type":"about:blank","title":"Too many attempts. Please try again later.","status":429,"code":"rate_limited"}Show the retry-after seconds as a countdown on the button.
Requiring a verified email on routes
Section titled “Requiring a verified email on routes”Use the verified middleware, Laravel’s name:
import { defineRoutes, Route } from '@strutvane/framework'import { InvoiceController } from '../app/http/controllers/invoice.controller.ts'import { PostController } from '../app/http/controllers/post.controller.ts'
export default defineRoutes([ // Anyone signed in may read; only verified users may write. Route.apiResource('posts', PostController) .middlewareFor(['index', 'show'], 'auth') .middlewareFor(['store', 'update', 'destroy'], 'auth', 'verified'),
// A whole group that needs a verified address. Route.group({ prefix: 'billing', middleware: ['auth', 'verified'] }, [ Route.get('/invoices', [InvoiceController, 'index']).name('billing.invoices'), ]),])What you’ll see for an unverified user:
HTTP/1.1 403 Forbiddencontent-type: application/problem+json
{"type":"about:blank","title":"Verify your email address first.","status":403,"code":"email_not_verified"}Your UI can recognise email_not_verified and send the user to the “check your inbox” screen.
When emailVerification is off, verified lets everyone through: there’s nothing to verify against.
Checking in your own code
Section titled “Checking in your own code”Inside a controller, the same check is one call on the auth engine. In the prototype it’s verification.assertVerified(user), which throws the email_not_verified error above:
// Planned wiring: how a controller reaches the auth engine isn't final.auth.verification.assertVerified(user)Registration and verification together
Section titled “Registration and verification together”With both registration and emailVerification on, signing up doesn’t sign you in:
curl -X POST http://localhost:3000/register \ -H "Content-Type: application/json" -H "Origin: http://localhost:3000" \ -d '{"name":"Grace","email":"grace@example.com","password":"a long sentence I can remember 42"}'What you’ll see: {"status":"verification-sent"} and no session. You get the same answer if the email is already taken; the owner of that address gets a “someone tried to register with your address” mail instead of a verification link. That way, the sign-up form can’t be used to find out who has an account.
Edge cases you’ll meet
Section titled “Edge cases you’ll meet”| Situation | What happens |
|---|---|
| The link is older than 60 minutes | 403 signature_expired; the user asks for a new one |
| The link was edited (id, hash, expires or signature) | 403 invalid_signature |
| The user changed their address after the mail was sent | 403 invalid_signature (the hash no longer matches) |
| The user already verified | 204, nothing changes |
| The user was deleted | 403 invalid_signature, the same answer as an edited link |
| The link is opened on another device | works: no session needed |
APP_KEY was rotated since the mail |
still works: links signed with a key in APP_PREVIOUS_KEYS are accepted (decided; the prototype doesn’t do this yet, see Encryption) |
| A mail scanner opens the link before the user | the address is verified by the scanner’s visit; harmless, since the scanner reads the same inbox |
Every bad link gets the same invalid_signature answer, so nobody learns which part was wrong. Only an expired link gets its own code, signature_expired, so your page can offer “send me a new link”.
When mail is down
Section titled “When mail is down”POST /email/verification-notification still answers {"status":"sent"} and starts the 60-second wait. The failure goes to your log (the mail kind and user id only; the link is never logged). If users report missing mail, check the log, then where mail goes (below). Once a queue is available (0.3), failed mails are retried.
Where the mail goes in development
Section titled “Where the mail goes in development”- With Docker, open the Mailpit inbox at
http://localhost:8025and click the link in the mail. - Without Docker, new apps use
MAIL_MAILER=log: the mail, with its link, is written to your log instorage/logs/. Copy the link into your browser.
Links are built from APP_URL, so they point at http://localhost:3000 in development. On a server, set APP_URL to your real address, or the links will point at localhost.
Settings
Section titled “Settings”Setting in config/auth.ts |
Default | Meaning |
|---|---|---|
features.emailVerification |
off (the installer turns it on) | the whole feature; off means no routes at all |
links.verificationMinutes |
60 | how long a link works |
limits.verificationResendCooldown |
1 per 60 s | wait between resends |
limits.verificationResendPerAccount |
6 per hour | resends per hour |
A switched-off feature doesn’t exist: /email/verify/… and /email/verification-notification answer the same 404 not_found as a path that was never there.
Common mistakes
Section titled “Common mistakes”Every link answers invalid_signature or signature_expired
Section titled “Every link answers invalid_signature or signature_expired”{"type":"about:blank","title":"Invalid signature","status":403,"code":"invalid_signature","detail":"This link is not valid. It may have been changed or copied incompletely."}{"type":"about:blank","title":"Link expired","status":403,"code":"signature_expired","detail":"This link has expired. Ask for a new one."}Why: most often the link is older than 60 minutes, the mail app wrapped the long link across two lines so it was cut, or APP_KEY differs between the server that sent the mail and the one that checked it.
Fix: ask for a new link. If you run several servers, make sure they all share the same APP_KEY.
The links in the mail point at localhost on my server
Section titled “The links in the mail point at localhost on my server”Why: links are built from APP_URL, and the server still has the development value.
Fix:
APP_URL=https://app.example.com“Send it again” answers 429
Section titled ““Send it again” answers 429”{"type":"about:blank","title":"Too many attempts. Please try again later.","status":429,"code":"rate_limited"}Why: the last mail went out less than 60 seconds ago, or 6 mails were sent this hour.
Fix: wait for the seconds in the retry-after header. Disable the button and show a countdown so people don’t keep clicking.
/email/verify/… answers 404
Section titled “/email/verify/… answers 404”{"type":"about:blank","title":"Not found.","status":404,"code":"not_found"}Why: emailVerification is off, so its routes don’t exist.
Fix:
features: { emailVerification: true },Verified users still get email_not_verified
Section titled “Verified users still get email_not_verified”Why: the request is made with an old session or token that was loaded before verification, or as a different user than you think.
Fix: check GET /user with the same cookie or token; emailVerified must be true. Sign out and in again if your UI cached the user.
My mail doesn’t arrive at all
Section titled “My mail doesn’t arrive at all”Why: in development without Docker, nothing is sent: MAIL_MAILER=log writes mail to the log.
Fix: look in storage/logs/, or start the Docker services and open Mailpit at http://localhost:8025. See Mail.
Next steps
Section titled “Next steps”- Authentication: registration, sign-in and the auth middleware.
- Password Reset: the other emailed link.
- Mail: sending real mail in production.
- Middleware: how
authandverifiedrun on routes.