Introduction
On this page
Persona is a premium package of Lucid model mixins for user accounts. In this guide, you will learn:
- What modules Persona provides
- How the mixin composition pattern works
- What validation rules Persona registers
- What peer dependencies are required
Overview
Section titled "Overview"User accounts share a set of predictable behaviors, like verifying email addresses, resetting passwords, enrolling in two-factor authentication, and linking social provider accounts. Persona packages these behaviors as Lucid model mixins that you compose onto your User model.
Each module is independent. You can use email management without password management, or add TOTP later without touching your existing setup.
Installation
Section titled "Installation"Persona needs an AdonisJS 7 app on Node.js 24 or later. It installs from the AdonisJS Plus registry. Once your project points at the registry (see Installation and setup), run the following command. It installs the package and registers the Persona provider inside adonisrc.ts.
node ace add @adonisplus/personaModules
Section titled "Modules"Persona has five modules with a mixin each, and a password policy module. Each one is a separate import.
- Email management (
@adonisplus/persona/email) verifies email addresses with tokens, and keeps the verified address until a new one is verified. - Password management (
@adonisplus/persona/password) creates password reset tokens, and resets the password with one. - TOTP management (
@adonisplus/persona/totp) enrolls users in two-factor authentication with an authenticator app, a QR code and recovery codes. - Passkey management (
@adonisplus/persona/passkeys) registers WebAuthn passkeys and signs users in with them. - Social identity (
@adonisplus/persona/social) links OAuth provider accounts to users by the provider's user id, keeps a copy of the provider profile, and lists and removes linked accounts. It takes the user objects of@adonisjs/ally. - Password policy (
@adonisplus/persona/password_policy) defines a password policy and checks passwords against it, on the server and in the browser.
Mixin composition
Section titled "Mixin composition"Persona uses the compose helper from AdonisJS to apply mixins to your model. Each mixin adds instance methods and static methods to the model class.
import { UserSchema } from '#database/schema'
import hash from '@adonisjs/core/services/hash'
import { compose } from '@adonisjs/core/helpers'
import { withAuthFinder } from '@adonisjs/auth/mixins/lucid'
import { withManagedEmail } from '@adonisplus/persona/email'
import { withSocialIdentity } from '@adonisplus/persona/social'
import { withManagedPassword } from '@adonisplus/persona/password'
export default class User extends compose(
UserSchema,
withAuthFinder(hash),
withManagedEmail(),
withManagedPassword(),
withSocialIdentity()
) {}
You do not need to declare columns on the model. Lucid auto-generates a Schema class by introspecting the database, and the model picks up its columns from there.
Validation rules
Section titled "Validation rules"Alongside the mixins, Persona registers three VineJS validation rules. The passwordPolicy rule enforces a password policy you can also share with your frontend to build a strength meter, the uncompromised rule rejects passwords that have appeared in data leaks, and the nonDisposable rule rejects email addresses from disposable email providers.
import vine from '@vinejs/vine'
import { definePasswordPolicy } from '@adonisplus/persona/password_policy'
export const passwordPolicy = definePasswordPolicy({ minLength: 12 })
export const signupValidator = vine.create({
email: vine.string().email().nonDisposable(),
password: vine.string().passwordPolicy(passwordPolicy).uncompromised(),
})The rules are registered by the Persona provider. See the validation rules guide for setup instructions and the available options.
Errors
Section titled "Errors"Every E_* error in errors converts itself to an HTTP response. For an HTML request, it flashes its message under error and redirects back, or to the URL set with setRedirectUrl. Without a session, it responds with the message and the status of the error. A JSON request receives { errors: [{ message }] }, and a JSON:API request receives { errors: [{ code, title }] }.
With @adonisjs/i18n configured, the message is translated from the errors.<CODE> key, for example errors.E_INVALID_EMAIL_TOKEN.
Import the error classes from @adonisplus/persona to check for them.
import { errors } from '@adonisplus/persona'E_UNKNOWN_PASSKEY also sends a passkey signal; see Passkey management.
Peer dependencies
Section titled "Peer dependencies"Persona requires the following peer dependencies.
@adonisjs/core^7.0.0required@adonisjs/lucid^22.0.0required@adonisjs/ally^6.0.0@adonisjs/session^8.0.0@adonisjs/i18n^3.0.0errors.* keys.@vinejs/vine^4.0.0otpauth^9.5.0qrcode^1.5.4@simplewebauthn/server^14.0.2