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

Transparent

Full source code installed directly into your project. No compiled packages, no hidden behavior, and a structure that is easy to inspect and modify.

Composable

Add only what you need. Independent features communicate through events with loose coupling.

Non-invasive

No assumptions about your database schema, user model, or JWT payload. Implement the required ports and integrate without restructuring your application.

Portable

Business logic stays independent from adapters. Move the authentication logic into another project and replace only the adapters.

NestJS Native

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

Hexagonal

A clear boundary that services contain business logic, ports define contracts, and adapters remain fully under your control.

How does it work

brkpt-auth separates stable authentication logic from project-specific implementation. Authentication capabilities are organized as independent features, while adapters connect those features to your own application.

Each feature is added to the project, connected through an adapter, and registered through BrkptAuthModule. Whether you enable credentials, OAuth, sessions, blacklist, or any other capability, the integration pattern remains the same.

Features communicate through events instead of direct dependencies, allowing new capabilities to be added without modifying existing ones. Features that are not added simply don’t participate in BrkptAuthModule.

Ports and adapters keep infrastructure outside of the authentication core. Your database schema, user model, password strategy, JWT payload, validation rules, and external services remain under your control. Migrating to another project usually means replacing adapters instead of rewriting authentication logic.

Session management is built on top of stateless JWT instead of replacing it. Stateful capabilities such as session management and token revocation can be added incrementally without changing the core authentication flow.

brkpt-cli helps assemble this structure by installing source code directly into your project and wiring new features into the same architecture.

Is it hard to integrate

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.