MFA for Payload (two-step sign-in): an authenticator code after the password, with emailed and recovery codes as backups, each used once, limited per account, and required by a rule you set.
Status: early, 0.1.0, not on npm yet. 46 tests pass against a real Payload 3.92 with an in-memory MongoDB, covering every factor, replays, the limits (including 40 tries at once), remembered browsers, per-session expiry, the required rule, the login endpoint, and races with Payload's own sign-in (a sign-in begun earlier can't undo two-step or reuse a code). It's extracted from the version a live site runs, but this package itself isn't in use on any site yet, and it has no screens of its own: your site builds the sign-in and settings pages.
- After the password, a code. From an authenticator app (6 digits, one 30-second step of clock drift allowed), or as backups an emailed code (8 digits, 10 minutes) or one of 10 recovery codes. No text messages.
- Each code works once. An app code can't be replayed, even within its drift window. An emailed or recovery code is used up. Two requests racing with the same code can't both win.
- Limited per account, never by address. 5 code tries and 3 emailed codes per 15 minutes per account, so changing address gives no fresh tries. An optional per-address limit sits on top. Bring your own limiter with
limit; the plugin builds the key itself. - Required by your rule.
requiredFordecides who must have it. It's checked at sign-in, on every refresh, and on every request for open sessions, and if it throws the account counts as required. A required account that hasn't enrolled can't sign in, so a stolen password can't enrol its own phone. Staff can open a short window withallowEnrollment. - Remembered browsers. After a code, the site can set a cookie so the password alone works for 24 hours. A new password or a new app ends it. A session can't outlive the code it came from, counted per session, so one device's code never extends another.
- After a password reset, emailed codes are off for 24 hours, since the mailbox has just proved itself. The plugin does this by itself after Payload's
resetPassword. - Nothing readable. The secret is sealed with AES-256-GCM, using a key derived from your app secret. Codes are stored hashed. The state lives in its own
mfa-statecollection (one document per account), hidden from every API read and never written by Payload's sign-in.
On its own: it adds its own mfa-state and tries collections beside your users collection. Your server code calls signIn, start, confirm and verify, and your site builds the pages. API keys can't be on the same collection.
Works with:
- Hats: use
isOnForandverifyas Hats'stepUp(the two lines are under "Using it"), so switching into a sensitive hat asks for the same authenticator code. - Audit Trail: pass
onEventthrough Audit Trail'sfromPluginEvent. MFA's own state writes skip collection hooks, so these events are the only record the trail gets.
Family: It's part of the Identity family (a working draft): plugins designed to sit together for accounts and access.
npm install @extantape/payload-plugin-mfaimport { mfa } from '@extantape/payload-plugin-mfa'
export default buildConfig({
plugins: [
mfa({
requiredFor: ({ user }) => user.roles?.includes('admin') ?? false,
issuer: 'My site',
onEvent: (event) => auditLog(event), // event.user is the account; event.req has no code, headers or body, and its payload isn't enumerable
}),
],
})HTTP can't carry the code: it travels in req.context, which only your server code can set. So:
- Sign in from a server action with
signIn(payload, { email, password, code }), or withremember(the cookie's value) instead ofcode. Errors are Payload's usual ones; anMfaErrorhasmfa: 'needed' | 'wrong' | 'enroll'. After a good code, set theREMEMBER_COOKIEcookie (HttpOnly) toawait rememberValue(payload, { userId }). Sites without server actions can turn onendpoint: trueforPOST /api/users/mfa/login { email, password, code }, which sets both cookies. - Set up with
start(payload, { userId }), which returns{ uri, key }for a QR code, and thenconfirm(payload, { userId, code }), which returns the recovery codes once. Check the person's password beforestart. If two-step is already on,startneeds a current app or recovery code. - Turn off or renew codes with
turnOffandnewRecoveryCodesFor. Check the password first; both need an app or recovery code (an emailed code only proves the mailbox). - Emailed codes:
sendEmailCode(payload, { email }). It answers the same whatever the address, so say "if that account uses two-step, we've sent a code". - Step-up before a sensitive action:
verify(payload, { user, code, req }). For Hats:stepUp: { available: (u) => isOnFor(payload, u.id), verify: ({ user, code, req }) => verify(payload, { user, code, req }) }. - Your own vouching: pass
context: { [MFA_TRUSTED]: true }topayload.loginonly from server code that has checked the person another way, or that throws the token away (for example, checking a password). - Invitations: after a password set through an emailed link, call
afterPasswordSet(payload, { userId }). - Status for the person's own security page:
statusFor(payload, userId)gives{ on, since, recoveryLeft }, and nothing about the secret or the codes. Pass the signed-in person's own id; it trusts the id it's given. - A maintainer's reset, for someone who lost their app and their recovery codes:
resetFor(payload, userId, { enrollHours, actor }).- It needs no code, so check the maintainer, and confirm who you're resetting another way, in your own code first.
- It clears the app, the recovery codes, any emailed code and the per-session records. Remembered browsers stop working.
- It signs the account out everywhere, because a stolen phone may have a session open. Pass
endSessions: falseto keep them. It also records when the reset happened, and any session made before then is refused at every request and refresh. That holds even if a sign-in racing the reset wrote the old sessions back, so each signed-in request reads the account's two-step state once (one small query). This needs Payload's sessions (auth.useSessions, on by default). With sessions off there's nothing to end, and old tokens keep working until they expire. - It opens an enrollment window: default 24 hours, at most 14 days. During it, anyone who knows the password can set up a phone. Keep it short, and reset the password too if it may be known.
- It clears the account's built-in limiter tries. A limiter of your own isn't cleared.
- It sends a
resetevent withby: pass the maintainer's id asactor, never an email address. If youronEventthrows, the reset has still happened. - A block on emailed codes after a password reset stays.
- Neither function has an endpoint.
If your site kept two-step state in a group on the account (the first site did, as twoStep):
- Back up the database. Get the site owner's yes before it runs on production.
- Remove that field from the auth collection and pass
legacyUserField: 'twoStep', plus thekeyDerivationvalues you used. The plugin refuses to start while the field is still declared. - Run
await moveLegacyState(payload)once, as a script. It copies each account's old state where the account has no record yet and removes the old field. If the account already has a record with no secret and no sign that two-step was cleared on purpose (a started setup, or an email-code block after a password reset), the old secret, enabled date and last step are merged into that record, which keeps what it already had. Recovery codes are never copied into an existing record. The old field is removed only after the merge is written. If the record was left byturnOffor by a maintainer'sresetFor(it hasturnedOffAt,resetAtorenrollUntil, or an enabled date, recovery codes or a last step), nothing is merged: the old field stays, the account stays at the two-step step, and its id is listed inneedsReviewfor the site to decide. If the record already has a secret, that secret stays. When the old secret is different, the id is listed indifferentSecretand the old secret is gone from the account, so keep the backup. A setup that was never confirmed is dropped and counted. It returns{ moved, merged, alreadyMoved, unfinished, cleared, differentSecret, needsReview }and is safe to run again. MongoDB only.
Until an account's old state is moved, that account can't sign in, so nothing runs half-moved with weaker sign-in.
- API keys aren't supported on the same collection: they sign in without a password or code, so the plugin refuses to start with
useAPIKeyon. Keep API keys on another collection. A custom auth strategy is your code's job: checkisOnForand your rule there. - Payload's own reset page can't collect a code. For an enrolled account, reset the password through your own form, with a code (or
MFA_TRUSTEDonce you've checked one). - The per-request check for open sessions looks the account up once per authenticated request, and only when you set
requiredFor. - Changing the app secret (or the
keyDerivationvalues) makes stored authenticator secrets unreadable. People then sign in with a recovery code and set up again. - The plugin's own state writes go straight to the database, so collection hooks (an audit trail's included) don't see them;
onEventis the record. - The try limit orders tries by each server's clock. If your servers' clocks disagree, a burst could get a few extra tries through. Keep clocks in sync (they are on any managed host).
- Old tries are deleted as new ones arrive, so the try table stays small.
- The emailed code's default wording is English. Pass
sendEmailCodefor your own.
npm test # Vitest, in-memory MongoDB
npm run typecheck
npm run buildMIT