Introduction

@nestbolt/authentication is a complete, database-agnostic authentication backend for NestJS. It provides a full suite of authentication features out of the box -- registration, login, password reset, email verification, profile management, password confirmation, and two-factor authentication (TOTP) -- without tying you to any specific database, ORM, or frontend framework.

Inspired by Laravel Fortify, the package follows the same philosophy of providing a backend-only authentication layer that you wire up to your own user storage and frontend.

Key Features

• Database-agnostic -- implement a simple UserRepository interface for any database or ORM (TypeORM, Prisma, Mongoose, MikroORM, DynamoDB, or plain SQL).
• Feature toggles -- enable only the features you need via a features array. Unused routes and services are never registered.
• JWT-based sessions -- issues short-lived access tokens and long-lived refresh tokens. No server-side session storage required.
• Two-factor authentication -- full TOTP-based 2FA with QR code generation, secret key management, confirmation flow, and recovery codes.
• Rate limiting -- built-in throttle guards for login, two-factor challenge, and email verification endpoints.
• Password confirmation -- time-limited password confirmation for sensitive operations, modeled after Laravel's password confirmation middleware.
• Event-driven -- emits authentication lifecycle events via @nestjs/event-emitter (optional) so you can react to logins, registrations, password changes, and more.
• Encryption -- AES-256-GCM encryption for two-factor secrets and recovery codes at rest.
• Validation -- request DTOs validated with class-validator and class-transformer out of the box.
• Global module -- register once in your root module and all guards, decorators, and services are available throughout your application.

Architecture Overview

The package is composed of several layers:

1. AuthenticationModule -- a dynamic NestJS module that accepts configuration via forRoot() or forRootAsync(). It registers controllers, services, guards, strategies, and interceptors based on which features you enable.

2. Controllers -- each feature area has its own controller (auth, registration, password reset, email verification, profile, password, two-factor, two-factor challenge, confirm password). Controllers are only registered when their corresponding feature is enabled.

3. Services -- business logic is encapsulated in injectable services. Core services like AuthService, EncryptionService, and ConfirmPasswordService are always available. Feature-specific services (e.g., RegistrationService, TwoFactorService) are registered conditionally.

4. Guards -- Passport-based guards (JwtAuthGuard, LocalAuthGuard) handle authentication. Custom guards handle rate limiting (LoginThrottleGuard, TwoFactorThrottleGuard, VerificationThrottleGuard), feature gating (FeatureEnabledGuard), guest-only access (GuestGuard), and password confirmation (PasswordConfirmedGuard).

5. Strategies -- three Passport strategies are registered: local for username/password validation, jwt for access token validation, and jwt-refresh for refresh token validation.

6. Decorators -- @CurrentUser() extracts the authenticated user from the request, @Public() skips JWT authentication on specific routes, and @RequiresFeature() marks routes as requiring a specific feature to be enabled.

7. Events -- when @nestjs/event-emitter is installed, the package emits events for login, logout, registration, lockout, password changes, email verification, and all two-factor operations.

How It Works

When you import AuthenticationModule.forRoot() with your configuration, the module:

1. Registers Passport with jwt as the default strategy.
2. Configures the JWT module with your signing secret and token expiry.
3. Creates an instance of your UserRepository class and makes it available for injection.
4. Registers only the controllers and services for the features you enabled.
5. Sets up rate limiting guards with your configured thresholds.
6. Optionally integrates with @nestjs/event-emitter for lifecycle events.

All 19 authentication routes become available immediately, gated by their feature flags. Your frontend (React, Vue, Angular, mobile, or anything else) communicates with these routes using standard HTTP requests with JSON payloads and JWT Bearer tokens.

Next Steps

• Installation -- install the package and its peer dependencies.
• Quick Start -- go from zero to a working authentication system in minutes.
• Configuration -- explore all available configuration options in detail.
• Features -- understand each feature toggle and what it enables.
• API Routes -- complete reference for all 19 authentication endpoints.
• Decorators and Guards -- learn about the decorators and guards you can use in your own controllers.
• Events -- subscribe to authentication lifecycle events.