brkpt-auth

Every approach has a cost

Managed services

A black box in the cloud. Limited customization and vendor lock-in.

Self-hosted libraries

A black box on your own machine. Heavy abstractions make customization difficult.

Auth boilerplates

Full source code with strong architectural opinions that often require significant rework.

Rolling your own

Complete control, but every project starts from the same foundation again.

Why brkpt-auth

brkpt-auth is not a boilerplate and not a library. It’s structured around interfaces you implement yourself, not an opinionated default that just runs.

Transparent

Full source code installed directly into your project. No compiled packages, no hidden behavior.

Composable

Independent features. Add only what you need.

Non-invasive

No assumptions about your database schema, user model, or JWT payload.

Portable

Business logic stays independent from adapters. Move to another project by swapping only the adapters.

NestJS Native

Built around NestJS modules, dependency injection, guards, decorators, and providers from the beginning.

Hexagonal

Services hold business logic, ports define contracts, adapters stay fully under your control. No nested domain/infrastructure layers to dig through.

How it works

The service depends on an abstract interface, a port, which you implement as an adapter. That’s the only place your infrastructure touches the auth logic. Features don’t depend on each other besides core, so you add only what you need without touching the rest. BrkptAuthModule, registered once in your AppModule, wires everything together automatically instead of you registering and wiring providers by hand.

This keeps it from becoming bloated like a boilerplate. You get clear points to customize, and it stays easy to get started with.

brkpt-cli installs the source code into your project. You implement the adapters and list them in features.ts; most adapter methods are simple field mappings or direct calls into your existing code.

How to use it

Each feature follows the same integration flow: add the feature, implement its adapter, and register it.

1. Add a feature

   Use brkpt-cli to add the feature source code to your project.

   Add credentials

   brkpt auth add credentials

2. Implement the adapter

   Connect the feature port to your existing application code. Most adapter methods are simple field mappings or direct service calls.

   credentials.adapter.ts

   @Injectable()
   export class CredentialsAdapter implements CredentialsPort<User> {
     constructor(private readonly prisma: PrismaService) {}
   
     findUserByDto(dto: SignInDto | SignUpDto): Promise<User | null> {
       return this.prisma.user.findUnique({ where: { email: dto.email } });
     }
   
     validatePassword(user: User, dto: SignInDto): Promise<boolean> {
       return bcrypt.compare(dto.password, user.password);
     }
   
     async createUser(dto: SignUpDto): Promise<User> {
       const password = await bcrypt.hash(dto.password, 10);
       return this.prisma.user.create({
         data: { email: dto.email, password },
       });
     }
   
     extractUserIdFromUser(user: User): number {
       return user.id;
     }
   }

3. Register the feature

   brkpt-cli updates features.ts for you. After implementing the adapter, pass it to the corresponding feature in the generated feature list.

   src/brkpt-auth/features.ts

   export const features: FeatureConfig[] = [
     coreFeature(CoreAdapter),
     credentialsFeature(CredentialsAdapter),
   ];

That’s it. Once BrkptAuthModule is registered in your AppModule, added features become part of the same NestJS authentication flow.

Depending on the feature, you may still need normal project setup such as dependencies, environment variables, DTOs, or infrastructure modules.

Available features

brkpt-auth organizes common authentication capabilities as independent features. Start with core, then add only the features your application needs.

Foundation

• core

Sign-in methods

• credentials
• oauth
• otp
• magic-link

Session management

• session
• blacklist

Account security

• verify-email
• change-password
• reset-password

Event handling

• audit

Who is brkpt-auth for

brkpt-auth is built for NestJS applications that need authentication code they can own, adapt, and grow over time.

MVP builders

Start with a working authentication foundation quickly, then add sessions, OAuth, OTP, audit, or other features as the product evolves.

Existing NestJS applications

Projects that already have their own user model, database, services, and infrastructure.

Long-term products

Teams that want authentication code they can inspect, maintain, and adapt over time.

Composable auth systems

Applications that need to start simple and add authentication capabilities gradually without rewriting existing features.

Multi-project builders

Developers who want to reuse authentication logic across NestJS projects while keeping each project free to use its own database, user model, and infrastructure.

Architecture-conscious teams

Teams that want clear boundaries between authentication logic, application infrastructure, and project-specific implementation.