zerotal v1.7

Documentation

Documentation / zerotal / auth / TwoFactorMiddleware

Class: TwoFactorMiddleware

Defined in: packages/auth/src/TwoFactorMiddleware.ts:59

TwoFactorMiddleware — enforce 2FA completion for the current session.

Place this after AuthMiddleware in your route stack.

Behavior:

Session awaiting its second factor (TWO_FACTOR_PENDING_KEY) → redirect to the challenge page.
Otherwise unauthenticated → UnauthorizedError (401).
User has no 2FA configured (twoFactorSecret is null/empty) → pass through.
2FA is configured but NOT confirmed this session → redirect to the challenge page.
2FA is configured AND confirmed this session → pass through.

This middleware is a convenience, not the enforcement point. Auth.login marks a session with a confirmed second factor as pending and PersistUserMiddleware withholds ctx.user until the challenge is met, so a route that forgets this middleware still sees a guest. Attach it where you want the redirect-to-challenge behaviour instead of a bare 401.

The challenge page verifies the submitted code via TwoFactorService.verifyCode() and then calls Auth.completeTwoFactor(), which clears the pending marker, records the challenge as met, and rotates the session id.

Example

// In bootstrap/app.ts (authenticated group):
Router.group({ middleware: [AuthMiddleware, TwoFactorMiddleware] }, () => {
  Router.get('/dashboard', DashboardController, 'index');
});

Throws

When the request is unauthenticated (http.user is unset).

Extends

BaseMiddleware

Constructors

Constructor

new TwoFactorMiddleware(): TwoFactorMiddleware

Defined in: packages/core/src/middleware/BaseMiddleware.ts:36

Returns

TwoFactorMiddleware

Inherited from

BaseMiddleware.constructor

Properties

options

protected options: object = {}

Defined in: packages/auth/src/TwoFactorMiddleware.ts:60

Subclasses must declare this with their default option values. TypeScript enforces this at compile time — forgetting it is a type error.

Overrides

BaseMiddleware.options

challengeRoute

static challengeRoute: string = "/two-factor/challenge"

Defined in: packages/auth/src/TwoFactorMiddleware.ts:66

The route users are redirected to when 2FA is required. Override by subclassing or set TwoFactorMiddleware.challengeRoute.

Methods

handle()

handle(http, next): Promise<void | Response>

Defined in: packages/auth/src/TwoFactorMiddleware.ts:68

Parameters

http

next

Returns

Promise<void | Response>

Overrides

BaseMiddleware.handle

with()

static with<T, Opts>(this, options): () => InstanceType<T>

Defined in: packages/core/src/middleware/BaseMiddleware.ts:48

Returns a zero-arg subclass with the given options deep-merged on top of the subclass defaults, usable directly in app.use([...]).

Type Parameters

T

T extends (...args) => BaseMiddleware<any>

Opts

Opts = T extends (...args) => BaseMiddleware<U> ? U : object

Parameters

this

T

options

Partial<Opts>

Returns

() => InstanceType<T>

Inherited from

BaseMiddleware.with

afterResponse()?

optional afterResponse(ctx): Promise<void>

Defined in: packages/core/src/middleware/BaseMiddleware.ts:70

Parameters

ctx

Returns

Promise<void>

Inherited from

BaseMiddleware.afterResponse

onError()?

optional onError(ctx, error): Promise<void>

Defined in: packages/core/src/middleware/BaseMiddleware.ts:71

Parameters

ctx

error

Error

Returns

Promise<void>

Inherited from

BaseMiddleware.onError