Skip to content
GitHub

Strutvane 0.2 is still being built. These pages describe how it will work; anything marked "Coming in 0.2" doesn't exist yet. Release notes and support policy.

Email Verification

View as Markdownllms.txt

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”).

  1. 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 },
    })
  2. A new user signs up (with registration on) 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…
  3. 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 } }
/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.

A signed-in, unverified user asks for a fresh link (your “check your inbox” screen has a “Send it again” button):

Terminal window
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 Requests
retry-after: 42
content-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.

Use the verified middleware, Laravel’s name:

routes/api.ts
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 Forbidden
content-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.

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:

app/http/controllers/invoice.controller.ts
// Planned wiring: how a controller reaches the auth engine isn't final.
auth.verification.assertVerified(user)

With both registration and emailVerification on, signing up doesn’t sign you in:

Terminal window
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.

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”.

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.

  • With Docker, open the Mailpit inbox at http://localhost:8025 and click the link in the mail.
  • Without Docker, new apps use MAIL_MAILER=log: the mail, with its link, is written to your log in storage/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.

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.

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.

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:

.env.production
APP_URL=https://app.example.com
{"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.

{"type":"about:blank","title":"Not found.","status":404,"code":"not_found"}

Why: emailVerification is off, so its routes don’t exist. Fix:

config/auth.ts
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.

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.