@derek46518/nest-auth-kit

Reusable NestJS authentication module that bundles:

• Local username/email + password login
• JWT issuance with HttpOnly cookie support
• Google OAuth 2.0 strategy (passport-google-oauth20)
• CSRF double-submit middleware
• Password reset flow with pluggable token persistence
• Optional transactional email notifications

This package extracts the auth stack used in the WebBackend project and exposes extensible interfaces so you can bring your own user store, reset-token repository, and mailer implementation.

Status: experimental & work-in-progress. The API may change before 1.0.

Features

• Dynamic AuthModule with configurable providers and cookie behaviour
• Injectable AuthService exposing high-level login/registration helpers
• Passport strategies (local, jwt, google) and guards ready to plug into controllers
• CSRF middleware that validates origin + double-submit token
• DTOs for register/forgot/reset flows using class-validator

Installation

npm install @derek46518/nest-auth-kit passport passport-local passport-jwt passport-google-oauth20

The package declares peer dependencies on core NestJS packages (e.g. @nestjs/common, @nestjs/jwt, @nestjs/passport). Make sure they already exist in your host application.

Usage overview

1. Implement adapters that satisfy the exported interfaces.
2. Provide those adapters (and optionally a mailer) in a module the kit can import.
3. Register the auth kit using AuthModule.registerAsync(...) (or register(...)) and supply configuration (JWT, cookies, Google OAuth, frontend metadata).
4. Expose auth endpoints using the supplied guards/controller or by building your own controllers that delegate to AuthService.

The following sections walk through each step.

1. Implement adapters

Implement the interfaces exported by the kit (see src/interfaces):

• AuthUsersService – look up users, validate credentials, create accounts, and update passwords. Must return objects { id, username, email | null, role }.
• PasswordResetTokenStore – persist password reset tokens (saveToken, findByHash, markUsed).
• AuthMailer (optional) – send transactional email. Provide isEnabled(): boolean to indicate SMTP availability.

Example Drizzle/Nest adapter:

@Injectable()
export class UsersAuthServiceAdapter implements AuthUsersService {
  constructor(private readonly users: UsersService) {}

  private toAuthUser(user: UsersServiceSafeUser): AuthUser {
    return {
      id: user.id,
      username: user.username,
      email: user.email,
      role: user.role
    };
  }

  async validateCredentials(identifier: string, password: string) {
    const user = await this.users.validatePassword(identifier, password);
    return user ? this.toAuthUser(user) : null;
  }

  async registerUser(username: string, password: string, email: string) {
    return this.toAuthUser(await this.users.create(username, password, email));
  }

  async findByEmail(email: string) {
    const user = await this.users.findByEmail(email);
    return user ? this.toAuthUser(user as any) : null;
  }

  async createOAuthUser(email: string, usernameBase: string) {
    return this.toAuthUser(await this.users.createOAuthUser(email, usernameBase));
  }

  async updatePassword(userId: number, newPassword: string) {
    await this.users.updatePassword(userId, newPassword);
  }
}

Password reset token store example:

@Injectable()
export class PasswordResetTokenStoreAdapter implements PasswordResetTokenStore {
  constructor(@Inject(DRIZZLE) private readonly db: NodePgDatabase) {}

  async saveToken(userId: number, tokenHash: string, expiresAt: Date) {
    await this.db.insert(passwordResetTokens).values({ userId, tokenHash, expiresAt });
  }

  async findByHash(tokenHash: string) {
    const [row] = await this.db
      .select({
        id: passwordResetTokens.id,
        userId: passwordResetTokens.userId,
        tokenHash: passwordResetTokens.tokenHash,
        expiresAt: passwordResetTokens.expiresAt,
        usedAt: passwordResetTokens.usedAt
      })
      .from(passwordResetTokens)
      .where(eq(passwordResetTokens.tokenHash, tokenHash))
      .limit(1);

    if (!row) return null;
    return {
      id: row.id,
      userId: row.userId,
      tokenHash: row.tokenHash,
      expiresAt: row.expiresAt instanceof Date ? row.expiresAt : new Date(row.expiresAt),
      usedAt: row.usedAt ?? null
    };
  }

  async markUsed(id: number, usedAt: Date) {
    await this.db.update(passwordResetTokens).set({ usedAt }).where(eq(passwordResetTokens.id, id));
  }
}

If you want transactional email support, implement AuthMailer (or reuse an existing service) exposing:

isEnabled(): boolean;
send(to: string, subject: string, html: string, text?: string): Promise<void | boolean>;

2. Provide adapters & mailer in modules

Create modules that bind your adapters/mailer to the tokens exported by the kit:

@Module({
  imports: [UsersModule],
  providers: [
    UsersAuthServiceAdapter,
    PasswordResetTokenStoreAdapter,
    { provide: AUTH_USERS_SERVICE, useExisting: UsersAuthServiceAdapter },
    { provide: AUTH_RESET_TOKEN_STORE, useExisting: PasswordResetTokenStoreAdapter }
  ],
  exports: [UsersAuthServiceAdapter, PasswordResetTokenStoreAdapter, AUTH_USERS_SERVICE, AUTH_RESET_TOKEN_STORE]
})
export class AuthAdaptersModule {}

@Module({
  providers: [MailService, { provide: AUTH_MAILER, useExisting: MailService }],
  exports: [MailService, AUTH_MAILER]
})
export class AuthMailerModule {}

3. Register the auth kit

In your root auth module, configure and import the kit:

const authKitModule = AuthKitModule.registerAsync({
  imports: [AuthAdaptersModule, AuthMailerModule, ConfigModule],
  useFactory: (cfg: ConfigService): AuthModuleOptions => ({
    imports: [AuthAdaptersModule, AuthMailerModule, ConfigModule],
    userServiceToken: UsersAuthServiceAdapter,
    resetTokenStoreToken: PasswordResetTokenStoreAdapter,
    mailerToken: MailService,
    jwt: {
      secret: cfg.get<string>('JWT_SECRET')!,
      expiresIn: cfg.get<string>('JWT_EXPIRES_IN') ?? '15m'
    },
    cookies: {
      useCookies: cfg.get<string>('AUTH_USE_COOKIE') !== 'false',
      cookieDomain: cfg.get<string>('COOKIE_DOMAIN') || undefined,
      crossSite: cfg.get<string>('COOKIE_CROSS_SITE') === 'true'
    },
    google: cfg.get<string>('GOOGLE_CLIENT_ID') && cfg.get<string>('GOOGLE_CLIENT_SECRET')
      ? {
          clientID: cfg.get<string>('GOOGLE_CLIENT_ID')!,
          clientSecret: cfg.get<string>('GOOGLE_CLIENT_SECRET')!,
          callbackURL: cfg.get<string>('GOOGLE_CALLBACK_URL')!
        }
      : undefined,
    frontend: {
      origins: (cfg.get<string>('FRONTEND_ORIGINS') ?? '')
        .split(',')
        .map((s) => s.trim())
        .filter(Boolean),
      defaultRedirectUrl: cfg.get<string>('FRONTEND_ORIGIN') ?? 'http://localhost:3000',
      resetUrlBase: cfg.get<string>('FRONTEND_RESET_URL') ?? ''
    }
  }),
  inject: [ConfigService]
});

@Module({
  imports: [AuthAdaptersModule, AuthMailerModule, ConfigModule, authKitModule],
  exports: [authKitModule, AuthAdaptersModule, AuthMailerModule]
})
export class AuthModule {}

The kit exports AuthService, strategies, guards, middleware, and DTOs. Inject AuthService wherever you need to issue tokens manually.

4. Controllers & guards

Use the supplied guards in your own controllers or expose the built-in controller from the kit. Example custom controller:

@Controller('auth')
export class AuthController {
  constructor(private readonly auth: AuthService) {}

  @UseGuards(LocalAuthGuard)
  @Post('login')
  async login(@Req() req: Request, @Res({ passthrough: true }) res: Response) {
    const user = req.user as { id: number; username: string; role?: string | null };
    const token = await this.auth.issueAccessToken(user);
    res.cookie('accessToken', token, { httpOnly: true, sameSite: 'lax' });
    return { user, accessToken: token };
  }
}

Required environment variables

| Variable | Description | | --- | --- | | DATABASE_URL | Connection string for your user/password-reset persistence | | JWT_SECRET | Secret used to sign access tokens (min 16 chars recommended) | | JWT_EXPIRES_IN | Token lifetime (15m, 1h, etc.) | | AUTH_USE_COOKIE | true to set JWT in an HttpOnly cookie | | COOKIE_CROSS_SITE | true when API and frontend are on different domains (sets SameSite=None) | | COOKIE_DOMAIN | Optional domain for cookies (e.g. .example.com) | | FRONTEND_ORIGIN / FRONTEND_ORIGINS | Allowed origins for CORS/CSRF (comma separated) | | FRONTEND_RESET_URL | Base URL for password reset link (e.g. https://app/reset?token=) | | GOOGLE_CLIENT_ID | Google OAuth client ID (optional if Google login disabled) | | GOOGLE_CLIENT_SECRET | Google OAuth client secret | | GOOGLE_CALLBACK_URL | OAuth callback URL pointing back to your API | | SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS, EMAIL_FROM | SMTP configuration for password reset email (optional) |

Google OAuth set-up

1. In Google Cloud Console, create an OAuth client ID (Web application).
2. Add your API callback URL (e.g. https://api.example.com/auth/google/callback).
3. Add your frontend origins (https://app.example.com).
4. Populate GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, and GOOGLE_CALLBACK_URL in your environment.
5. Expose the /auth/google and /auth/google/callback routes using the guards provided by the kit or the default controller.

Frontend integration

Default endpoints (assuming the packaged controller is used):

| Method | Route | Description | | --- | --- | --- | | POST | /auth/login | Local login; returns { user, accessToken, csrfToken } (cookie set when enabled) | | POST | /auth/register | Register a user and issue access token | | POST | /auth/logout | Clear cookies (if cookie mode on) | | GET | /auth/csrf | Obtain CSRF token for double-submit scheme | | GET | /auth/google | Redirect to Google OAuth | | GET | /auth/google/callback | Callback; redirects with state or sets cookies | | POST | /auth/password/forgot | Trigger password reset flow | | POST | /auth/password/reset | Complete password reset |

Frontend tips:

• When using cookies, issue requests with credentials: 'include'.
• In SPA flows, parse the redirected URL for accessToken/csrfToken when cookie mode is off.
• Retrieve /auth/csrf before protected POST requests to include the double-submit token in headers.

Testing

• Unit-test your adapters to ensure they meet the contract.
• Add e2e tests that exercise local login, Google OAuth (or stub strategy), and password-reset flows.
• Mock SMTP or the mailer when running tests to avoid external calls.

License

MIT © Derek