Persona

Persona is a collection of Lucid model mixins for common user account operations. In this guide, you will learn:

• What modules Persona provides
• How the mixin composition pattern works
• What peer dependencies are required

Overview

User accounts share a set of predictable behaviors, like verifying email addresses, resetting passwords, enrolling in two-factor authentication, and linking social provider identities. 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.

Modules

Persona provides four modules, each available as a separate import.

• Email management (@adonisplus/persona/email) handles email verification flows using a two-column pattern, cryptographic tokens, and atomic email switching.
• Password management (@adonisplus/persona/password) handles password reset flows with secure tokens and atomic password updates.
• TOTP management (@adonisplus/persona/totp) handles two-factor authentication with authenticator app enrollment, QR codes, and recovery codes.
• Social identity (@adonisplus/persona/social) handles OAuth provider identity linking with secure identity resolution, snapshot tracking, and account management. Works directly with @adonisjs/ally user objects.

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 { 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(),
  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.

Peer dependencies

Persona requires the following peer dependencies.