@nestbolt/authentication

Frontend-agnostic authentication backend for NestJS

---

A complete, database-agnostic authentication backend for NestJS with support for registration, login, password reset, email verification, profile management, password confirmation, and two-factor authentication (TOTP).

Inspired by Laravel Fortify.

Table of Contents

• Installation
• Quick Start
• Module Configuration
• Features
• Database Adapters
• API Routes
• Events
• Configuration Options
• Testing
• Changelog
• Contributing
• License

Installation

# pnpm
pnpm add @nestbolt/authentication

# npm
npm install @nestbolt/authentication

# yarn
yarn add @nestbolt/authentication

Peer Dependencies

pnpm add @nestjs/passport @nestjs/jwt passport passport-jwt passport-local class-validator class-transformer reflect-metadata

Optional:

pnpm add @nestjs/event-emitter

Quick Start

1. Implement the UserRepository interface for your database:

import { Injectable } from "@nestjs/common";
import { UserRepository, AuthUser } from "@nestbolt/authentication";

@Injectable()
export class MyUserRepository implements UserRepository {
  async findById(id: string): Promise<AuthUser | null> {
    /* ... */
  }
  async findByField(field: string, value: string): Promise<AuthUser | null> {
    /* ... */
  }
  async save(user: Partial<AuthUser> & { id: string }): Promise<AuthUser> {
    /* ... */
  }
  async create(data: Omit<AuthUser, "id">): Promise<AuthUser> {
    /* ... */
  }
}

2. Import AuthenticationModule in your app module:

import { AuthenticationModule, Feature } from "@nestbolt/authentication";
import { MyUserRepository } from "./my-user.repository";

@Module({
  imports: [
    AuthenticationModule.forRoot({
      features: [
        Feature.REGISTRATION,
        Feature.RESET_PASSWORDS,
        Feature.EMAIL_VERIFICATION,
        Feature.UPDATE_PROFILE_INFORMATION,
        Feature.UPDATE_PASSWORDS,
        Feature.TWO_FACTOR_AUTHENTICATION,
      ],
      userRepository: MyUserRepository,
      jwtSecret: process.env.JWT_SECRET!,
      refreshSecret: process.env.REFRESH_SECRET!,
      encryptionKey: process.env.ENCRYPTION_KEY!, // 32-byte base64
      appName: "MyApp",
    }),
  ],
})
export class AppModule {}

3. That's it! All 19 auth routes are now available.

Module Configuration

Synchronous

AuthenticationModule.forRoot({
  features: [Feature.REGISTRATION, Feature.TWO_FACTOR_AUTHENTICATION],
  userRepository: TypeOrmUserRepository,
  passwordResetRepository: TypeOrmPasswordResetRepository,
  jwtSecret: "your-jwt-secret",
  refreshSecret: "your-refresh-secret",
  encryptionKey: "base64-encoded-32-byte-key",
  appName: "MyApp",
});

Asynchronous

AuthenticationModule.forRootAsync({
  imports: [ConfigModule],
  inject: [ConfigService],
  useFactory: (config: ConfigService) => ({
    features: [Feature.REGISTRATION, Feature.TWO_FACTOR_AUTHENTICATION],
    userRepository: TypeOrmUserRepository,
    jwtSecret: config.get("JWT_SECRET"),
    refreshSecret: config.get("REFRESH_SECRET"),
    encryptionKey: config.get("ENCRYPTION_KEY"),
  }),
});

Features

Enable or disable features via the features array:

Feature	Description
Feature.REGISTRATION	User registration (POST /register)
Feature.RESET_PASSWORDS	Password reset flow (POST /forgot-password, POST /reset-password)
Feature.EMAIL_VERIFICATION	Email verification (GET /email/verify/:id/:hash)
Feature.UPDATE_PROFILE_INFORMATION	Profile updates (PUT /user/profile-information)
Feature.UPDATE_PASSWORDS	Password updates (PUT /user/password)
Feature.TWO_FACTOR_AUTHENTICATION	Full 2FA with TOTP, QR codes, and recovery codes

Database Adapters

The package is database-agnostic. Implement UserRepository and optionally PasswordResetRepository for any database:

TypeORM (SQL)

@Injectable()
export class TypeOrmUserRepository implements UserRepository {
  constructor(@InjectRepository(User) private repo: Repository<User>) {}
  findById(id: string) {
    return this.repo.findOneBy({ id });
  }
  findByField(field: string, value: string) {
    return this.repo.findOneBy({ [field]: value });
  }
  save(user) {
    return this.repo.save(user);
  }
  create(data) {
    return this.repo.save(this.repo.create(data));
  }
}

Mongoose (MongoDB)

@Injectable()
export class MongooseUserRepository implements UserRepository {
  constructor(@InjectModel(User.name) private model: Model<UserDocument>) {}
  findById(id: string) {
    return this.model.findById(id).lean().exec();
  }
  findByField(field: string, value: string) {
    return this.model
      .findOne({ [field]: value })
      .lean()
      .exec();
  }
  save(user) {
    return this.model.findByIdAndUpdate(user.id, user, { new: true }).lean().exec();
  }
  create(data) {
    return this.model.create(data);
  }
}

Prisma, MikroORM, DynamoDB, etc.

Same pattern - implement the interface for your ORM/driver.

API Routes

Method	Route	Description	Auth
POST	/login	Authenticate user	No
POST	/refresh	Refresh access token	Refresh Token
POST	/logout	Log out	JWT
POST	/register	Create new user	No
POST	/forgot-password	Send reset link	No
POST	/reset-password	Reset password	No
GET	/email/verify/:id/:hash	Verify email	JWT
POST	/email/verification-notification	Resend verification	JWT
PUT	/user/profile-information	Update profile	JWT
PUT	/user/password	Change password	JWT
POST	/user/confirm-password	Confirm password	JWT
GET	/user/confirmed-password-status	Check confirmation	JWT
POST	/user/two-factor-authentication	Enable 2FA	JWT
DELETE	/user/two-factor-authentication	Disable 2FA	JWT
POST	/user/confirmed-two-factor-authentication	Confirm 2FA setup	JWT
GET	/user/two-factor-qr-code	Get QR code SVG	JWT
GET	/user/two-factor-secret-key	Get TOTP secret	JWT
GET/POST	/user/two-factor-recovery-codes	Get/regenerate codes	JWT
POST	/two-factor-challenge	Complete 2FA login	No

Events

Subscribe to authentication events using @nestjs/event-emitter:

import { OnEvent } from "@nestjs/event-emitter";
import { AUTH_EVENTS, UserEvent } from "@nestbolt/authentication";

@Injectable()
export class AuthListener {
  @OnEvent(AUTH_EVENTS.LOGIN)
  handleLogin(payload: UserEvent) {
    console.log(`User ${payload.user.email} logged in`);
  }
}

Available events: auth.login, auth.logout, auth.registered, auth.lockout, auth.password-reset, auth.password-updated, auth.email-verified, auth.two-factor-enabled, auth.two-factor-disabled, auth.two-factor-confirmed, auth.two-factor-challenged, auth.two-factor-failed, auth.valid-two-factor-code, auth.recovery-code-replaced, auth.recovery-codes-generated

Configuration Options

Option	Type	Default	Description
features	Feature[]	required	Enabled features
userRepository	Type<UserRepository>	required	User repository class
passwordResetRepository	Type<PasswordResetRepository>	-	Password reset token storage
jwtSecret	string	required	JWT signing secret
refreshSecret	string	required	Refresh token secret
encryptionKey	string	required	32-byte base64 key for 2FA encryption
jwtExpiresIn	string	"15m"	Access token TTL
refreshExpiresIn	string	"7d"	Refresh token TTL
usernameField	string	"email"	Login username field
lowercaseUsernames	boolean	true	Lowercase usernames on login
loginRateLimit	{ ttl, limit }	{ 60000, 5 }	Login rate limiting
twoFactorRateLimit	{ ttl, limit }	{ 60000, 5 }	Two-factor challenge rate limiting
verificationRateLimit	{ ttl, limit }	{ 60000, 6 }	Email verification rate limiting
passwordTimeout	number	900	Password confirmation timeout (seconds)
appName	string	"NestBolt"	App name for TOTP QR codes
twoFactorOptions.confirm	boolean	false	Require 2FA confirmation step
twoFactorOptions.confirmPassword	boolean	false	Require password before 2FA changes
twoFactorOptions.window	number	1	TOTP time window
twoFactorOptions.secretLength	number	20	TOTP secret key length

Testing

pnpm test          # Run tests
pnpm test:watch    # Watch mode
pnpm test:cov      # Coverage report

Changelog

See CHANGELOG.md.

Contributing

See CONTRIBUTING.md.

Security

For security-related issues, please use the security label on GitHub Issues.

Credits

• Inspired by Laravel Fortify by Taylor Otwell

License

MIT License