Email Verification

When your install has an email adapter, every new member has to click a confirmation link before they can sign in. Without one, there is nobody to send the link, so accounts are confirmed the moment they are created and nothing changes.

That stops the oldest trick in the book: signing up with somebody else's address and using the account straight away.

What a member seesCopy Anchor Link

1. They register at /register. Instead of being signed in, they get a "Check your email" card.
2. The email holds a link to /login/verify-email?token=..., valid for 24 hours.
3. That page asks them to click Confirm email address. The page never confirms on load, because mail scanners and link previews open every URL in an email.
4. Once confirmed, they sign in with their password as usual.

If they try to sign in first, the sign-in form says Confirm your email first and offers Send a new confirmation link, which opens the resend form with their address already filled in.

The rulesCopy Anchor Link

• Password sign-in answers 403 { "error": "email_not_verified" } for an unconfirmed account. No session is created.
• Passkey sign-in follows the same rule, with the same error code.
• AdminCP sign-in at /admin is not blocked. Only staff get in, and staff are picked by an administrator, so an install that just added an email adapter can't lock its admins out.
• SSO sign-ups are confirmed already, since the provider vouches for the address.
• Completing a password reset also confirms the address - the reset link went to the same mailbox.
• Staff can confirm anyone by hand from the AdminCP user page.

API routesCopy Anchor Link

All routes live under /api/@vitnode/core/users.

/verify-email/resend answers the same 201 for an unknown address, a confirmed one and one waiting for confirmation, so it can't be used to check who has an account. It only sends when the account still needs confirming, and only once every five minutes. A new link replaces the old one.

Call them through the fetcher like any other core route:

import { fetcher } from '@vitnode/core/tanstack/fetcher'

const response = await fetcher({
  plugin: '@vitnode/core',
  method: 'post',
  module: 'users',
  path: '/verify-email',
  args: { body: { token } },
})

Confirming a link does not sign anybody in. Whoever clicks it owns the mailbox, but not necessarily the account - if a stranger registered with your address, your click must not drop you into their session.

How links are storedCopy Anchor Link

Links live in core_users_confirm_emails, one row per account:

• The token is 32 random bytes, base64url-encoded. Only its SHA-256 digest is stored, so a leaked database dump can't confirm anything.
• A link works once. Spending it deletes the row in the same statement that reads it, so two clicks racing each other can't both win.
• The hourly clean cron job deletes expired rows.

EventsCopy Anchor Link

Confirming an address emits user.email.verified with { userId, email } - from the link, from a completed password reset, or from staff in the AdminCP. See built-in events.