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

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.

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.

Terminal
node ace add @adonisplus/persona

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.

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.

app/models/user.ts
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.

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.

app/validators/user.ts
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.

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.

Persona requires the following peer dependencies.

@adonisjs/core^7.0.0required
The AdonisJS framework core.
@adonisjs/lucid^22.0.0required
The Lucid ORM for database operations and model mixins.
@adonisjs/ally^6.0.0
Required only if you use the social identity module. Provides OAuth driver integrations for providers like Google and GitHub.
@adonisjs/session^8.0.0
Used for flashing error messages to the session during content-negotiated error handling.
@adonisjs/i18n^3.0.0
Used for translating error messages using the errors.* keys.
@vinejs/vine^4.0.0
Required only if you use the validation rules.
otpauth^9.5.0
Required only if you use the TOTP management module. Generates and verifies time-based one-time passwords.
qrcode^1.5.4
Required only if you use the TOTP management module. Generates QR codes for authenticator app enrollment.
@simplewebauthn/server^14.0.2
Required only if you use the passkey management module. Generates and verifies WebAuthn registration and login responses.