# Persona

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

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

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](/docs/get-started/installation)), run the following command. It installs the package and registers the Persona provider inside `adonisrc.ts`.

```sh
node ace add @adonisplus/persona
```

## 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

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.

```ts [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),
  // [!code ++:3]
  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

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.

```ts [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](./validation-rules) for setup instructions and the available options.

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

```ts
import { errors } from '@adonisplus/persona'
```

`E_UNKNOWN_PASSKEY` also sends a passkey signal; see [Passkey management](/docs/packages/persona/passkey-management#keeping-password-managers-in-sync).

## Peer dependencies

Persona requires the following peer dependencies.

::::field-group

:::field{name="@adonisjs/core" type="^7.0.0" required}
The AdonisJS framework core.
:::

:::field{name="@adonisjs/lucid" type="^22.0.0" required}
The Lucid ORM for database operations and model mixins.
:::

:::field{name="@adonisjs/ally" type="^6.0.0"}
Required only if you use the social identity module. Provides OAuth driver integrations for providers like Google and GitHub.
:::

:::field{name="@adonisjs/session" type="^8.0.0"}
Used for flashing error messages to the session during content-negotiated error handling.
:::

:::field{name="@adonisjs/i18n" type="^3.0.0"}
Used for translating error messages using the `errors.*` keys.
:::

:::field{name="@vinejs/vine" type="^4.0.0"}
Required only if you use the validation rules.
:::

:::field{name="otpauth" type="^9.5.0"}
Required only if you use the TOTP management module. Generates and verifies time-based one-time passwords.
:::

:::field{name="qrcode" type="^1.5.4"}
Required only if you use the TOTP management module. Generates QR codes for authenticator app enrollment.
:::

:::field{name="@simplewebauthn/server" type="^14.0.2"}
Required only if you use the passkey management module. Generates and verifies WebAuthn registration and login responses.
:::

::::
