DEV Community: brkpt

Refactoring NestJS Auth Built with brkpt-auth: How Easy Is It, Really?

brkpt — Tue, 08 Sep 2026 10:53:13 +0000

The last post built a password + Google sign-in MVP with brkpt-auth. This one makes two changes to that same project, the kind that come up naturally as a product grows, and checks what moved.

Adding a unique username, without giving up email sign-in

Say the product now needs a public, unique handle, something people can share and search for, that isn't tied to an email address they might change later. username is that field: unique, and usable for sign-in alongside email, which stays unique too and stays valid for signing in as well.

Worth being upfront here: credentials is meant to be a plain username-and-password flow, it was only using email as the identifier earlier in this series for convenience. It still collects email in this signup form, for the same reason, keeping the focus on the identifier and OAuth changes below. That does leave a real gap: nothing here verifies a user actually owns the email they typed in. On its own, that's harmless. Combined with OAuth, it isn't: register with a stranger's email through credentials, and when the real owner later signs in with Google using that same address, OAuth attaches their identity to the account someone else created. brkpt-auth's verify-email feature closes this by restricting access until the address is confirmed; another option is collecting email through otp instead, verified before it's ever attached to an account. Neither is added here, to stay focused on the changes below.

Update the schema:

// prisma/schema.prisma
model User {
  id       Int    @id @default(autoincrement())
  username String @unique
  name     String
  email    String @unique
  password String
}

If your database already has users, adding a required, unique username column isn't a migration you can run as-is: existing rows have no value for it, and nothing generated one for them when they signed up with just an email and a password. A real migration needs a plan for backfilling those rows first. This post resets the database instead, to keep the focus on the adapter changes, not a migration script.

The DTOs change to match:

// src/brkpt-auth/features/credentials/dto/sign-up.dto.ts
import { IsEmail, IsString, MinLength } from 'class-validator';

export class SignUpDto {
  @IsString()
  @MinLength(3)
  username!: string;

  @IsString()
  name!: string;

  @IsEmail()
  email!: string;

  @IsString()
  @MinLength(6)
  password!: string;
}

// src/brkpt-auth/features/credentials/dto/sign-in.dto.ts
import { IsString } from 'class-validator';

export class SignInDto {
  @IsString()
  identifier!: string;

  @IsString()
  password!: string;
}

CredentialsAdapter.findUserByDto is the one method that actually encodes "how a user gets looked up." It now accepts either username or email as the sign-in identifier, and for sign-up, checks both fields for a conflict, since either one being taken should block the new account:

// src/brkpt-auth/adapters/credentials.adapter.ts
findUserByDto(dto: SignInDto | SignUpDto) {
  if ('identifier' in dto) {
    return this.prisma.user.findFirst({
      where: {
        OR: [{ username: dto.identifier }, { email: dto.identifier }],
      },
    });
  }
  return this.prisma.user.findFirst({
    where: {
      OR: [{ username: dto.username }, { email: dto.email }],
    },
  });
}

SignInDto calls the field identifier rather than username, because a real product usually lets people sign in with either: username and email are both unique, so either one reliably points at exactly one user.

createUser needs the same field added, since it's building the record findUserByDto will later look up:

// src/brkpt-auth/adapters/credentials.adapter.ts
async createUser(dto: SignUpDto) {
  const password = await bcrypt.hash(dto.password, 10);
  return this.prisma.user.create({
    data: {
      username: dto.username,
      name: dto.name,
      email: dto.email,
      password,
    },
  });
}

CredentialsService still calls both methods the same way it always did. It has no idea the lookup field changed, because it was never told what the field was in the first place, just that one method returns a user or null and the other returns a created one.

The JWT payload is worth a second look too, not because email stopped being valid, sub alone has always been enough to identify a user, but because it's a convenient place to carry the field the frontend is most likely to want to display without an extra request:

// src/brkpt-auth/adapters/types.ts
export type AuthJwtPayload = { sub: number; username: string };

// src/brkpt-auth/adapters/core.adapter.ts
mapUserToJwtPayload(user: User): AuthJwtPayload {
  return {
    sub: user.id,
    username: user.username,
  };
}

Two methods, in the two adapters that were always the place this kind of decision was supposed to live. CoreService, CredentialsService, the guards, the controllers: still untouched.

OAuth sign-in needs to match on something other than email too

Right now, an account's email is also its identifier for OAuth: if two providers ever returned the same address, they'd both resolve to the same user, and that's as far as the current mapping goes. What it can't do is record that relationship, so there's no clean way to see or manage which providers a given account has actually connected. It also breaks in a simple, concrete case: a user changes their email on this app, then signs in with the Google account tied to their original address. A lookup by email finds nothing, and a second account gets created for the same person.

Tracking the real relationship needs a record of which provider identity belongs to which user, independent of whatever email happens to be on file at the time. The standard way to model that is a separate table: one User can have many LinkedAccount rows, one per provider they've connected, and each LinkedAccount belongs to exactly one User.

// prisma/schema.prisma
model User {
  id            Int             @id @default(autoincrement())
  username      String          @unique
  name          String
  email         String          @unique
  password      String
  linkedAccounts LinkedAccount[]
}

model LinkedAccount {
  id         Int    @id @default(autoincrement())
  provider   String
  providerId String
  userId     Int
  user       User   @relation(fields: [userId], references: [id])

  @@unique([provider, providerId])
}

UserProfile also needs to carry provider and providerId now, alongside the name and email fields the last post already added to it:

// src/brkpt-auth/adapters/types.ts
export interface UserProfile {
  provider: string;
  providerId: string;
  name: string;
  email: string;
}

findOrCreateUserByProfile is where this logic has always lived, and it's the only place that changes. It still matches on email, not username, because that's the only identifier an OAuth profile actually carries; Google and GitHub have no idea what username a person picked on this app, so email is the only field there is to match against. It now checks three things in order: has this exact provider identity signed in before, does a user with this email already exist to attach it to, or is this a genuinely new user.

// src/brkpt-auth/adapters/oauth.adapter.ts
async findOrCreateUserByProfile(profile: UserProfile) {
  const linkedAccount = await this.prisma.linkedAccount.findUnique({
    where: {
      provider_providerId: {
        provider: profile.provider,
        providerId: profile.providerId,
      },
    },
    include: { user: true },
  });
  if (linkedAccount) {
    return { user: linkedAccount.user, created: false };
  }

  const existingUser = await this.prisma.user.findUnique({
    where: { email: profile.email },
  });
  if (existingUser) {
    await this.prisma.linkedAccount.create({
      data: {
        provider: profile.provider,
        providerId: profile.providerId,
        userId: existingUser.id,
      },
    });
    return { user: existingUser, created: false };
  }

  const user = await this.prisma.user.create({
    data: {
      username: await this.generateUniqueUsername(profile.email),
      name: profile.name,
      email: profile.email,
      password: '',
      linkedAccounts: {
        create: { provider: profile.provider, providerId: profile.providerId },
      },
    },
  });
  return { user, created: true };
}

Signing up with a password means choosing a username up front; signing up through Google doesn't go through that form at all, so this method still has to decide one for a genuinely new user. It's a placeholder, generated from the email prefix, with the same uniqueness rule as any other username: if it collides with one that already exists, it's not usable, and a suffix gets added until it is. Letting the user change it later is a separate feature, not something this method needs to solve.

// src/brkpt-auth/adapters/oauth.adapter.ts
private async generateUniqueUsername(email: string): Promise<string> {
  const base = email.split('@')[0];
  let candidate = base;
  let suffix = 0;
  while (await this.prisma.user.findUnique({ where: { username: candidate } })) {
    suffix += 1;
    candidate = `${base}${suffix}`;
  }
  return candidate;
}

mapRawToProfile is what fills in provider and providerId in the first place:

// src/brkpt-auth/adapters/oauth.adapter.ts
import { BadRequestException, Injectable } from '@nestjs/common';
import { TokenPayload } from 'google-auth-library';
import { User } from '../../../generated/prisma/client';
import { PrismaService } from '../../prisma/prisma.service';
import { OAuthPort } from '../features/oauth/oauth.port';
import { UserProfile } from './types';

interface GoogleUser extends TokenPayload {
  name: string;
  email: string;
}

@Injectable()
export class OAuthAdapter implements OAuthPort<User, UserProfile> {
  constructor(private readonly prisma: PrismaService) {}

  mapRawToProfile(provider: string, raw: unknown): UserProfile | undefined {
    switch (provider) {
      case 'google': {
        const r = raw as GoogleUser;
        if (!r.email || !r.sub) {
          throw new BadRequestException(
            'Google profile is missing required fields',
          );
        }
        return {
          provider,
          providerId: r.sub,
          name: r.name,
          email: r.email,
        };
      }
    }
  }

  // findOrCreateUserByProfile and generateUniqueUsername as above

  extractUserIdFromUser(user: User) {
    return user.id;
  }
}

OAuthPort itself hasn't changed: mapRawToProfile still returns a profile shape, findOrCreateUserByProfile still returns { user, created }. Every file brkpt-auth's CLI installed is untouched.

Adding GitHub sign-in on top of this

With the account-linking table already in place, adding a second provider is a smaller change than it looks. brkpt auth add oauth --driver github installs GithubOAuthDriver, which talks to a completely different protocol than Google's: it exchanges an authorization code for an access token, then calls GitHub's /user endpoint, returning whatever JSON GitHub sends back.

That's also a different request shape than Google's: the controller needs code, not idToken. OAuthDto has to accept either, since both providers share this DTO:

// src/brkpt-auth/features/oauth/dto/oauth.dto.ts
import { IsOptional, IsString } from 'class-validator';

export class OAuthDto {
  @IsOptional()
  @IsString()
  idToken?: string;

  @IsOptional()
  @IsString()
  code?: string;
}

GitHub's response JSON doesn't look anything like a Google ID token's claims, and it has its own reliability quirk: GitHub's email field is null if the user hasn't made an email public on their account. Add the credentials, add a second case to the same switch, and nothing else in the file moves:

# .env, add:
GITHUB_CLIENT_ID="your-github-client-id"
GITHUB_CLIENT_SECRET="your-github-client-secret"

// src/app.module.ts, inside BrkptAuthModule.forRootAsync's useFactory, add:
oauth: {
  google: {
    clientId: config.getOrThrow('GOOGLE_CLIENT_ID'),
    clientSecret: config.getOrThrow('GOOGLE_CLIENT_SECRET'),
  },
  github: {
    clientId: config.getOrThrow('GITHUB_CLIENT_ID'),
    clientSecret: config.getOrThrow('GITHUB_CLIENT_SECRET'),
  },
},

// src/brkpt-auth/adapters/oauth.adapter.ts
interface GitHubUser {
  id: number;
  login: string;
  name: string | null;
  email: string | null;
}

// ...

mapRawToProfile(provider: string, raw: unknown): UserProfile | undefined {
  switch (provider) {
    case 'google': {
      const r = raw as GoogleUser;
      if (!r.email || !r.sub) {
        throw new BadRequestException('Google profile is missing required fields');
      }
      return {
        provider,
        providerId: r.sub,
        name: r.name,
        email: r.email,
      };
    }
    case 'github': {
      const r = raw as GitHubUser;
      if (!r.email) {
        throw new BadRequestException('GitHub profile does not include a public email address');
      }
      return {
        provider,
        providerId: String(r.id),
        name: r.name ?? r.login,
        email: r.email,
      };
    }
  }
}

Both branches end at the same UserProfile shape, provider, providerId, name, email, which is the only thing findOrCreateUserByProfile ever sees. It doesn't know or care whether that profile came from a Google ID token or a GitHub REST response.

// src/brkpt-auth/features.ts
oauthFeature(OAuthAdapter, GoogleOAuthDriver, GithubOAuthDriver),

What actually moved

Two real requirements, three adapters, two DTOs, and one new table touched, zero files owned by brkpt-auth edited. The username change reached into a JWT payload type and two CredentialsAdapter methods. The OAuth change added LinkedAccount, extended UserProfile, and rewrote findOrCreateUserByProfile's internals, including how it handles generating a username no signup form was there to provide. Adding a second provider on top of that touched the same switch statement again, plus the DTO. CredentialsService, CoreService, OAuthService, and everything wired into BrkptAuthModule stayed exactly as they were after the last post.

What rolling your own would look like

Rolling your own usually means reaching for Passport. Here's roughly what the same three changes touch: LocalStrategy for username/email sign-in, JwtStrategy and JwtRefreshStrategy for the two token types, GoogleStrategy and GithubStrategy for the two providers, a JwtAuthGuard and a JwtRefreshAuthGuard extending Passport's AuthGuard, and a shared AuthService all of it calls into.

// jwt.strategy.ts
@Injectable()
export class JwtStrategy extends PassportStrategy(Strategy) {
  constructor() {
    super({ jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(), secretOrKey: process.env.JWT_SECRET });
  }
  async validate(payload: any) {
    return payload;
  }
}

// jwt-refresh.strategy.ts
@Injectable()
export class JwtRefreshStrategy extends PassportStrategy(Strategy, 'jwt-refresh') {
  constructor() {
    super({ jwtFromRequest: ExtractJwt.fromExtractors([(req) => req?.cookies?.refresh_token]), secretOrKey: process.env.JWT_REFRESH_SECRET });
  }
  async validate(payload: any) {
    return payload;
  }
}

// jwt-auth.guard.ts
@Injectable()
export class JwtAuthGuard extends AuthGuard() {} // default strategy name, no argument needed

// jwt-refresh-auth.guard.ts
@Injectable()
export class JwtRefreshAuthGuard extends AuthGuard('jwt-refresh') {}

// local.strategy.ts
async validate(identifier: string, password: string) {
  const user = await this.authService.validateUser(identifier, password);
  if (!user) throw new UnauthorizedException();
  return user;
}

// google.strategy.ts
async validate(accessToken: string, refreshToken: string, profile: any, done: any) {
  const user = await this.authService.validateOAuthUser('google', profile);
  done(null, user);
}

// github.strategy.ts
async validate(accessToken: string, refreshToken: string, profile: any, done: any) {
  const user = await this.authService.validateOAuthUser('github', profile);
  done(null, user);
}

// auth.service.ts
async validateUser(identifier: string, password: string) {
  const user = await this.usersService.findByUsernameOrEmail(identifier);
  if (!user || !(await bcrypt.compare(password, user.password))) return null;
  return user;
}

async validateOAuthUser(provider: string, profile: any) {
  const linkedAccount = await this.usersService.findLinkedAccount(provider, profile.id);
  if (linkedAccount) return linkedAccount.user;

  const email = provider === 'google' ? profile.emails[0].value : profile.email;
  const existingUser = await this.usersService.findByEmail(email);
  if (existingUser) {
    await this.usersService.attachLinkedAccount(existingUser.id, provider, profile.id);
    return existingUser;
  }

  if (provider === 'google') {
    return this.usersService.createFromGoogle(profile);
  } else if (provider === 'github') {
    return this.usersService.createFromGithub(profile);
  }
}

Seven files just to get sign-in and refresh authenticated: two strategies and two guards for the two token types, three more strategies for the three ways to sign in, all funneling into one AuthService with two entry points, validateOAuthUser alone branching by provider three times, once to read the email off a differently-shaped profile, once to decide who created it, once to decide how. Following a single Google sign-in means opening google.strategy.ts to see what gets passed in, auth.service.ts to see what happens to it, and github.strategy.ts to confirm the other provider calls the same method the same way. A fourth provider is a fourth strategy file and a fourth branch inside a method already doing three jobs at once.

Side-by-side: what actually had to change

Change	Rolling your own (Passport)	brkpt-auth
Add unique `username`, keep email sign-in	`LocalStrategy`, `AuthService.validateUser`, JWT payload construction, possibly `JwtStrategy`	`SignUpDto` / `SignInDto`, two methods in `CredentialsAdapter`, one method in `CoreAdapter`
Proper account linking (`LinkedAccount` table)	`AuthService.validateOAuthUser` rewritten, plus helpers in `UsersService`	One method in `OAuthAdapter` (`findOrCreateUserByProfile`)
Add GitHub provider	New `GithubStrategy` file + more branches inside `AuthService.validateOAuthUser`	One extra `case` in `mapRawToProfile` + register the driver
Services / Guards / Controllers	Frequently touched	Untouched

The difference is not that the business logic disappears. It is that the decisions stay inside the adapters you already own, while the generated services, guards, and controllers stay out of the way.

Build a Password + Google OAuth MVP with NestJS and brkpt-auth (in 15 Minutes)

brkpt — Tue, 08 Sep 2026 10:51:49 +0000

The last post in this series looked at why hand-rolled NestJS auth tends to accumulate glue code as real requirements pile up, and introduced brkpt-auth: full source code installed into your project, structured around interfaces (ports) you implement (adapters), so your database and token logic stay separate from the auth logic itself.

This post is the walkthrough: the same password + Google sign-in flow from the last post, built with brkpt-auth from scratch. Roughly, the shape of it is: install brkpt-auth's core feature, implement an adapter that connects it to Prisma, then add credentials and oauth the same way.

This post was written against NestJS v11 (a default CommonJS project from nest new) and Prisma 7.10.0. If your versions differ, some commands or config may not match, especially Prisma's CLI, which has changed flags across major versions. Check the Prisma releases page if something here doesn't work as shown.

Validation here uses class-validator, the same library NestJS's own docs default to, and what most NestJS tutorials still use. Worth noting up front: brkpt-auth doesn't require it. It doesn't ship with any validation library baked in, so class-validator, Zod, or nothing at all are all equally valid choices. class-validator is used here because it needs zero extra wiring with @Body(); Zod works too, but needs a small custom pipe to hook into NestJS's request pipeline, which would add a step this post doesn't need.

Setup

nest new my-app
cd my-app
npm install -g @brkpt/cli
npm install @nestjs/config @nestjs/event-emitter cookie-parser
npm install -D @types/cookie-parser
brkpt auth init

brkpt auth init installs the core feature and prints a checklist of anything else missing. Read it before moving on, it'll catch dependencies this post might not call out explicitly.

Prisma

npm install -D prisma@7.10.0 @types/pg
npm install @prisma/client@7.10.0 @prisma/adapter-pg pg
npx prisma@7.10.0 init --output ../generated/prisma

This needs a PostgreSQL database. Add the connection string to .env:

# .env
DATABASE_URL="postgresql://USER:PASSWORD@localhost:5432/DB_NAME?schema=public"

Define the user model:

// prisma/schema.prisma
generator client {
  provider     = "prisma-client"
  output       = "../generated/prisma"
  moduleFormat = "cjs"
}

datasource db {
  provider = "postgresql"
}

model User {
  id       Int    @id @default(autoincrement())
  name     String
  email    String @unique
  password String
}

moduleFormat = "cjs" keeps the generated client compatible with a default NestJS CommonJS setup.

npx prisma@7.10.0 migrate dev --name init
npx prisma@7.10.0 generate

// src/prisma/prisma.service.ts
import { Injectable } from '@nestjs/common';
import { PrismaPg } from '@prisma/adapter-pg';
import { PrismaClient } from '../../generated/prisma/client';

@Injectable()
export class PrismaService extends PrismaClient {
  constructor() {
    const adapter = new PrismaPg({
      connectionString: process.env.DATABASE_URL as string,
    });
    super({ adapter });
  }
}

// src/prisma/prisma.module.ts
import { Module } from '@nestjs/common';
import { PrismaService } from './prisma.service';

@Module({
  providers: [PrismaService],
  exports: [PrismaService],
})
export class PrismaModule {}

`core`: the only place your database and brkpt-auth meet

core depends on CorePort, an interface. You implement it once, and it never needs to change unless your schema does:

// src/brkpt-auth/adapters/types.ts
export type AuthJwtPayload = { sub: number; email: string };

// src/brkpt-auth/adapters/core.adapter.ts
import { Injectable } from '@nestjs/common';
import { User } from '../../../generated/prisma/client';
import { PrismaService } from '../../prisma/prisma.service';
import { CorePort } from '../features/core/core.port';
import { AuthJwtPayload } from './types';

@Injectable()
export class CoreAdapter implements CorePort<User> {
  constructor(private readonly prisma: PrismaService) {}

  mapUserToJwtPayload(user: User): AuthJwtPayload {
    return { sub: user.id, email: user.email };
  }

  shrinkJwtPayload(payload: AuthJwtPayload) {
    return { sub: payload.sub };
  }

  findUserByJwtPayload(payload: AuthJwtPayload) {
    return this.prisma.user.findUnique({ where: { id: payload.sub } });
  }

  toSafeUser(user: User) {
    const { password: _password, ...safe } = user;
    return safe;
  }

  extractUserIdFromJwtPayload(payload: AuthJwtPayload) {
    return payload.sub;
  }
}

Every method is a one-line mapping or a direct Prisma call. Register it, then wire PrismaModule, EventEmitterModule, and BrkptAuthModule into AppModule:

// src/brkpt-auth/features.ts
import { CoreAdapter } from './adapters/core.adapter';
import { FeatureConfig } from './common/interfaces';
import { coreFeature } from './features/core/core.feature';

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

// src/brkpt-auth/brkpt-auth.module.ts
import { Module } from '@nestjs/common';
import { PrismaModule } from '../prisma/prisma.module';
import { features } from './features';

@Module({
  imports: [PrismaModule],
  controllers: [...features.flatMap((f) => f.controllers)],
  providers: [...features.flatMap((f) => f.providers)],
})
export class BrkptAuthModule {
  // forRoot / forRootAsync are generated by the CLI and configure JwtModule; see below for the options this post needs.
}

// src/app.module.ts
import { Module } from '@nestjs/common';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { EventEmitterModule } from '@nestjs/event-emitter';
import { BrkptAuthModule } from './brkpt-auth/brkpt-auth.module';

@Module({
  imports: [
    ConfigModule.forRoot({ isGlobal: true }),
    EventEmitterModule.forRoot({ global: true, wildcard: true }),
    BrkptAuthModule.forRootAsync({
      imports: [ConfigModule],
      inject: [ConfigService],
      useFactory: (config: ConfigService) => ({
        jwt: {
          access: {
            secret: config.getOrThrow('JWT_ACCESS_SECRET'),
            expiresIn: '5m',
          },
          refresh: {
            secret: config.getOrThrow('JWT_REFRESH_SECRET'),
            expiresIn: '1h',
            transport: 'cookie',
          },
        },
      }),
    }),
  ],
})
export class AppModule {}

# .env
JWT_ACCESS_SECRET="dev-secret-change-me"
JWT_REFRESH_SECRET="dev-secret-change-me-too"

transport: 'cookie' means refresh tokens are read from a cookie, which is why cookie-parser needs to be enabled in main.ts:

// src/main.ts
import cookieParser from 'cookie-parser';
// ...
app.use(cookieParser());

npm run start:dev

GET /auth/me should return 401 here, expected: there's no sign-up or sign-in yet.

Password sign-in

brkpt auth add credentials
npm install class-validator class-transformer
npm install bcrypt && npm install -D @types/bcrypt

credentials ships with empty DTOs, brkpt-auth doesn't assume which fields a sign-up form uses:

// src/brkpt-auth/features/credentials/dto/sign-up.dto.ts
import { IsEmail, IsString, MinLength } from 'class-validator';

export class SignUpDto {
  @IsString()
  name!: string;

  @IsEmail()
  email!: string;

  @IsString()
  @MinLength(6)
  password!: string;
}

// src/brkpt-auth/features/credentials/dto/sign-in.dto.ts
import { IsEmail, IsString } from 'class-validator';

export class SignInDto {
  @IsEmail()
  email!: string;

  @IsString()
  password!: string;
}

Enable the global pipe once, in main.ts:

// src/main.ts
app.useGlobalPipes(
  new ValidationPipe({
    whitelist: true,
    transform: true,
  }),
);

Implement CredentialsAdapter:

// src/brkpt-auth/adapters/credentials.adapter.ts
import { Injectable } from '@nestjs/common';
import * as bcrypt from 'bcrypt';
import { User } from '../../../generated/prisma/client';
import { PrismaService } from '../../prisma/prisma.service';
import { CredentialsPort } from '../features/credentials/credentials.port';
import { SignInDto } from '../features/credentials/dto/sign-in.dto';
import { SignUpDto } from '../features/credentials/dto/sign-up.dto';

@Injectable()
export class CredentialsAdapter implements CredentialsPort<User> {
  constructor(private readonly prisma: PrismaService) {}

  findUserByDto(dto: SignInDto | SignUpDto) {
    return this.prisma.user.findUnique({ where: { email: dto.email } });
  }

  validatePassword(user: User, dto: SignInDto) {
    return bcrypt.compare(dto.password, user.password);
  }

  async createUser(dto: SignUpDto) {
    const password = await bcrypt.hash(dto.password, 10);
    return this.prisma.user.create({
      data: { name: dto.name, email: dto.email, password },
    });
  }

  extractUserIdFromUser(user: User) {
    return user.id;
  }
}

// src/brkpt-auth/features.ts
import { CoreAdapter } from './adapters/core.adapter';
import { CredentialsAdapter } from './adapters/credentials.adapter';
import { FeatureConfig } from './common/interfaces';
import { coreFeature } from './features/core/core.feature';
import { credentialsFeature } from './features/credentials/credentials.feature';

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

curl -X POST localhost:3000/auth/sign-up \
  -H "Content-Type: application/json" \
  -d '{"name":"Kevin","email":"kevin@example.com","password":"password123"}'

This returns an accessToken and sets the refresh token as an HttpOnly cookie, httpOnly, secure, and sameSite configured by default.

Google sign-in

brkpt auth add oauth --driver google

# .env, add:
GOOGLE_CLIENT_ID="your-google-client-id"
GOOGLE_CLIENT_SECRET="your-google-client-secret"

// src/app.module.ts, inside BrkptAuthModule.forRootAsync's useFactory, add:
oauth: {
  google: {
    clientId: config.getOrThrow('GOOGLE_CLIENT_ID'),
    clientSecret: config.getOrThrow('GOOGLE_CLIENT_SECRET'),
  },
},

The oauth feature's DTO just needs the field its controller reads:

// src/brkpt-auth/features/oauth/dto/oauth.dto.ts
import { IsString } from 'class-validator';

export class OAuthDto {
  @IsString()
  idToken!: string;
}

The adapter is the one place a Google profile turns into a row in your User table:

// src/brkpt-auth/adapters/types.ts, add:
export interface UserProfile {
  name: string;
  email: string;
}

// src/brkpt-auth/adapters/oauth.adapter.ts
import { BadRequestException, Injectable } from '@nestjs/common';
import { TokenPayload } from 'google-auth-library';
import { User } from '../../../generated/prisma/client';
import { PrismaService } from '../../prisma/prisma.service';
import { OAuthPort } from '../features/oauth/oauth.port';
import { UserProfile } from './types';

interface GoogleUser extends TokenPayload {
  name: string;
  email: string;
}

@Injectable()
export class OAuthAdapter implements OAuthPort<User, UserProfile> {
  constructor(private readonly prisma: PrismaService) {}

  mapRawToProfile(provider: string, raw: unknown): UserProfile | undefined {
    switch (provider) {
      case 'google': {
        const r = raw as GoogleUser;
        if (!r.email) {
          throw new BadRequestException(
            'Google profile does not include an email address',
          );
        }
        return { name: r.name, email: r.email };
      }
    }
  }

  async findOrCreateUserByProfile(profile: UserProfile) {
    const existing = await this.prisma.user.findUnique({
      where: { email: profile.email },
    });
    if (existing) return { user: existing, created: false };
    const user = await this.prisma.user.create({
      data: { name: profile.name, email: profile.email, password: '' },
    });
    return { user, created: true };
  }

  extractUserIdFromUser(user: User) {
    return user.id;
  }
}

// src/brkpt-auth/features.ts
import { CoreAdapter } from './adapters/core.adapter';
import { CredentialsAdapter } from './adapters/credentials.adapter';
import { OAuthAdapter } from './adapters/oauth.adapter';
import { FeatureConfig } from './common/interfaces';
import { coreFeature } from './features/core/core.feature';
import { credentialsFeature } from './features/credentials/credentials.feature';
import { GoogleOAuthDriver } from './features/oauth/drivers/google.driver';
import { oauthFeature } from './features/oauth/oauth.feature';

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

Run it

npm run start:dev

Method	Path	Description
POST	`/auth/sign-up`	Create a user
POST	`/auth/sign-in`	Sign in
POST	`/auth/oauth/google`	Sign in with Google
GET	`/auth/me`	Return the current user
POST	`/auth/refresh`	Issue a new access token
POST	`/auth/sign-out`	Sign out

curl -X POST localhost:3000/auth/oauth/google \
  -H "Content-Type: application/json" \
  -d '{"idToken":"<google-id-token>"}'

No frontend yet? Google's OAuth Playground issues a real idToken you can paste straight in; brkpt-auth's recipe for this walks through getting one in about five minutes.

What just happened

Two sign-in methods, one user model, one token flow, zero hand-written glue between them. CoreAdapter and CredentialsAdapter are Prisma calls and one-line mappings. OAuthAdapter is the only place Google's response shape ever touches the database. None of this required learning what hexagonal architecture is first, the interfaces just happened to only ask for what a working sign-up and sign-in flow needs.

For adding more sign-in methods or features the same way, the docs cover that ground. This series won't repeat it. The next post takes this exact project and puts a real claim to the test: how easy it actually is to change something that usually isn't, and what that costs in practice.

Why Your NestJS Auth Keeps Getting Rebuilt And How To Avoid It

brkpt — Tue, 08 Sep 2026 10:51:06 +0000

Every NestJS project has this moment. Sign-up and sign-in work. Password hashing works. A JWT gets issued, a guard checks it, and everyone moves on to the parts of the product that actually matter. Then, a few months in, someone asks for Google sign-in, or that users need to be able to change or reset their password, or sign in with a one-time code instead, or that a stateless JWT isn't enough anymore, sessions need to be revocable. And the auth code, the part everyone assumed was finished, turns out to be the part nobody wants to touch.

This post is about why that happens, using the code that actually causes it, and what changes when the auth layer is built to expect it.

Three ways to avoid writing it, each with a real cost

Before getting to the code: not everyone writes auth by hand, and it's worth being honest about why.

Managed services like Auth0 or Clerk get a working sign-in flow running in an afternoon. The cost shows up later: your user data lives on someone else's infrastructure, and the day a requirement doesn't fit their model, you're waiting on their roadmap, not shipping your own fix.

Compiled libraries like Better Auth ship a lot of functionality out of the box, but they may not be built NestJS-native, the integration sits alongside NestJS's module and DI system rather than inside it, and extending them past what their plugin system anticipated gets hard fast, because the internals aren't yours to change.

Boilerplates hand you a full NestJS project with auth already wired up, source code included. The catch is the schema comes pre-decided:

@Entity()
export class User {
  @PrimaryGeneratedColumn()
  id: number;

  @Column({ unique: true })
  email: string;

  @Column()
  password: string;
}

If your product signs in by phone number instead of email, or already has a members table shaped differently, you're not configuring this, you're editing it, in a file structure someone else designed and you're now responsible for maintaining. Full source doesn't mean full ownership if the shape underneath it doesn't fit.

That leaves writing it yourself, which is what most NestJS projects that don't reach for the above three actually do. This is where the rest of this post lives.

Writing it by hand: the version everyone starts with

Passport is the standard way NestJS projects handle this, and it starts reasonably. A local strategy for email and password:

// local.strategy.ts
@Injectable()
export class LocalStrategy extends PassportStrategy(Strategy) {
  constructor(private authService: AuthService) {
    super({ usernameField: 'email' });
  }

  async validate(email: string, password: string): Promise<any> {
    const user = await this.authService.validateUser(email, password);
    if (!user) {
      throw new UnauthorizedException();
    }
    return user;
  }
}

// auth.service.ts
async validateUser(email: string, pass: string): Promise<any> {
  const user = await this.usersService.findByEmail(email);
  if (user && (await bcrypt.compare(pass, user.password))) {
    const { password, ...result } = user;
    return result;
  }
  return null;
}

async login(user: any) {
  const payload = { email: user.email, sub: user.id };
  return { access_token: this.jwtService.sign(payload) };
}

A JwtStrategy and a JwtGuard to protect routes, a sign-up endpoint that hashes a password and saves a user, and it works. (Trilon, the company founded by NestJS's creator, has a good walkthrough of the same idea done without Passport, if you'd rather skip it for local auth specifically. Either way, the shape of what comes next is the same.)

Product asks for Google sign-in. Passport handles this with another strategy:

// google.strategy.ts
@Injectable()
export class GoogleStrategy extends PassportStrategy(Strategy, 'google') {
  constructor() {
    super({
      clientID: process.env.GOOGLE_CLIENT_ID,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET,
      callbackURL: '/auth/google/callback',
      scope: ['email', 'profile'],
    });
  }

  async validate(
    accessToken: string,
    refreshToken: string,
    profile: any,
    done: any,
  ) {
    const { emails, displayName } = profile;
    const user = await this.authService.validateOAuthUser({
      email: emails[0].value,
      name: displayName,
    });
    done(null, user);
  }
}

// auth.service.ts
async validateOAuthUser(googleUser: { email: string; name: string }) {
  let user = await this.usersService.findByEmail(googleUser.email);
  if (!user) {
    user = await this.usersService.create({
      email: googleUser.email,
      name: googleUser.name,
      password: null,
    });
  }
  return user;
}

This works too. It also means User now needs a nullable password, validateOAuthUser has its own logic for finding-or-creating a user that doesn't share anything with validateUser, and there are two separate code paths that both end up calling login(), each responsible for making sure the payload it builds is the same shape. At this point, the relationship between the strategies, the service, and the guard is already hard to hold in your head at once, following what happens on a single sign-in request means jumping between three or four files that were each written at a different time, for a different reason.

The requirements that come next

None of the above is unusual. It's what a competent NestJS auth setup looks like after one sign-in method becomes two. The trouble starts with what comes after.

"Sessions need to be revocable." A stateless JWT can't be revoked before it expires, by definition. Making it revocable means introducing a session store, a session id in the token payload, and a lookup added to whatever verifies the refresh token, a check that used to be pure signature verification:

// Before: refreshing a token is pure signature verification
async refresh(refreshToken: string) {
  const payload = await this.jwtService.verifyAsync(refreshToken, {
    secret: this.refreshSecret,
  });
  return this.login(await this.usersService.findById(payload.sub));
}

// After: needs a session lookup before issuing a new token
async refresh(refreshToken: string) {
  const payload = await this.jwtService.verifyAsync(refreshToken, {
    secret: this.refreshSecret,
  });
  const session = await this.sessionStore.get(payload.sid); // new dependency
  if (!session) {
    throw new UnauthorizedException('Session revoked');
  }
  return this.login(await this.usersService.findById(payload.sub));
}

refresh() now depends on a sessionStore that didn't exist before, which means anywhere this method is constructed, tested, or mocked needs to know about it too. A change that was, conceptually, "check one more thing before issuing a token" turns into a dependency that ripples out to every test and every place AuthService gets instantiated.

"Users need to be able to reset a forgotten password." Nothing written so far helps with this. validateUser proves someone knows a password they already have; it has nothing to say about someone who doesn't. Handling "forgot password" means building a separate mechanism from scratch: generate a token, store it somewhere with an expiry, email it, verify it when it comes back, and only then allow a new password to be set. None of this shares code with anything above it, and if sign-in with a one-time code gets added later, that's a third implementation of roughly the same idea: prove you have access to something, get a short-lived credential for it.

"A Google account should stay linked to one user, even if they signed up with a password first." Right now, validateOAuthUser matches purely on email, a simple, common baseline that works fine until two identities need to be tracked as one. Actually recording that relationship, this specific Google account belongs to this specific user, means introducing a linkedAccounts table or similar, and changing the matching logic inside the one validate callback that Passport also uses to decide whether a request is even authenticated at all. The two concerns, is this a valid OAuth response, and which user does it belong to, live in the same function, so changing one risks the other.

And the list keeps going, in the direction most NestJS projects eventually go: the user table moves from TypeORM to Prisma, or from Postgres to something else, and every one of the services above that calls usersService.findByEmail needs to be checked, because "the thing that changed" and "the thing that has to change alongside it" were never separated to begin with. The JWT payload's shape changes to include a tenant id, and now every place that reads payload.sub needs to be audited to see if it also needs payload.tenantId. None of these are hypothetical. They're the normal lifecycle of a real product, and each one, on its own, is small. It's the fact that they all touch the same tangle of files that makes them expensive.

Each of these is a reasonable, common request. None of them is exotic. And each one lands in whatever file has the closest related code, because that's the path of least resistance when the auth layer wasn't built expecting it. This is also, increasingly, not a problem an LLM can't solve for you, generating the glue code above is easy in 2026. The problem was never writing it. It's that none of it was designed to expect the next request, so structure, readability, and how confidently you can change any one piece without touching the rest, keep eroding regardless of who or what wrote the code.

What if none of that had to happen the way it just did

Imagine adding a capability like session revocation meant adding a feature, not writing a pile of glue code and hoping every caller still works. Imagine changing your database, or the shape of your JWT payload, meant touching your adapters and nothing else, because nothing outside them was ever supposed to know those details in the first place.

That's the premise brkpt-auth is built on. Its CLI writes source code directly into your project, the shadcn/ui model applied to authentication: full source installed directly into your project, no compiled package, no hidden behavior. Not a boilerplate or a library, since you get the source code, and it's structured around interfaces you implement yourself, not an opinionated default that just runs.

Every feature, credentials, oauth, session, and more, is independent, so you add only what you need, and depends on a port, an interface that makes no assumptions about your DB schema, user model, or JWT payload. Your database and token logic live in your own implementation of that interface, called an adapter, which is also what makes the business logic portable: move to another project by swapping only the adapters. Features besides core don't depend on each other either, so session revocation is a feature you add, not a guard you edit.

Stateless dual-token JWT is the default, refresh token cookies are configured correctly out of the box, and everything above it, sessions, additional sign-in methods, password reset, is something you add when you need it.

It's early, v0.1.0, and it won't fit every project. But if any of the above sounded like a rewrite waiting to happen, the next post shows how fast this actually gets you to a working MVP, a password and Google sign-in flow, built from scratch with brkpt-auth, and the post after that makes changes like these to see what actually moves.