@wikiccu/nest-auth

A comprehensive authentication package for NestJS applications with Prisma and PostgreSQL. This package provides a complete authentication system with JWT tokens, role-based access control, email verification, password reset, and more.

Features

• 🔐 JWT Authentication - Secure token-based authentication
• 👥 User Management - Complete user registration, login, and profile management
• 🔄 Refresh Token Rotation - Secure token refresh mechanism
• 📧 Email Verification - Email verification with customizable templates
• 🔑 Password Reset - Secure password reset via email
• 🛡️ Role-Based Access Control - Fine-grained permissions system
• 📊 Session Management - Track and manage user sessions
• 🚀 Rate Limiting - Built-in rate limiting for security
• 📝 Comprehensive API Documentation - Full Swagger/OpenAPI documentation
• 🧪 TypeScript Support - Full TypeScript support with type definitions

Installation

npm install @wikiccu/nest-auth

Prerequisites

This package requires the following dependencies in your NestJS application:

npm install @nestjs/common @nestjs/core @nestjs/jwt @nestjs/passport @nestjs/config @nestjs/swagger @prisma/client prisma passport passport-jwt passport-local bcryptjs class-validator class-transformer nodemailer rxjs

Note: This package is compatible with NestJS v11+ and uses the latest versions of all dependencies. It will automatically work with fresh NestJS installations without version conflicts.

Quick Start

1. Database Setup

First, set up your PostgreSQL database and run the Prisma migrations:

# Copy the Prisma schema to your project
cp node_modules/@wikiccu/nest-auth/dist/prisma/schema.prisma ./prisma/

# Generate Prisma client
npx prisma generate

# Run migrations
npx prisma migrate dev --name init-auth

2. Environment Variables

Add the following environment variables to your .env file:

# Database
DATABASE_URL="postgresql://username:password@localhost:5432/your_database"

# JWT Configuration
JWT_SECRET="your-super-secret-jwt-key"
JWT_EXPIRES_IN="15m"
REFRESH_TOKEN_EXPIRES_IN="7d"
REFRESH_TOKEN_EXPIRES_IN_REMEMBER="30d"

# Email Configuration
SMTP_HOST="smtp.gmail.com"
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER="your-email@gmail.com"
SMTP_PASS="your-app-password"
EMAIL_FROM="noreply@yourdomain.com"
EMAIL_FROM_NAME="Your App Name"

# Frontend URL (for email links)
FRONTEND_URL="http://localhost:3000"

# Token Expiration
PASSWORD_RESET_TOKEN_EXPIRES_IN="1h"
EMAIL_VERIFICATION_TOKEN_EXPIRES_IN="24h"
SESSION_EXPIRES_IN="24h"

# Security
BCRYPT_ROUNDS=12
MAX_LOGIN_ATTEMPTS=5
LOCKOUT_DURATION="15m"

3. Import the Module

Import the AuthModule in your main application module:

import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { AuthModule } from '@wikiccu/nest-auth';

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
    }),
    AuthModule,
  ],
})
export class AppModule {}

4. Set up Global Guards (Optional)

To protect all routes by default, set up global guards:

import { Module } from '@nestjs/common';
import { APP_GUARD } from '@nestjs/core';
import { AuthModule, JwtAuthGuard } from '@wikiccu/nest-auth';

@Module({
  imports: [AuthModule],
  providers: [
    {
      provide: APP_GUARD,
      useClass: JwtAuthGuard,
    },
  ],
})
export class AppModule {}

API Endpoints

Public Endpoints

Protected Endpoints

Usage Examples

Basic Authentication

import { Controller, Get, UseGuards } from '@nestjs/common';
import { JwtAuthGuard, CurrentUser, AuthUser } from '@wikiccu/nest-auth';

@Controller('protected')
@UseGuards(JwtAuthGuard)
export class ProtectedController {
  @Get('profile')
  getProfile(@CurrentUser() user: AuthUser) {
    return user;
  }
}

Role-Based Access Control

import { Controller, Get, UseGuards } from '@nestjs/common';
import { JwtAuthGuard, RolesGuard, Roles, CurrentUser, AuthUser } from '@wikiccu/nest-auth';

@Controller('admin')
@UseGuards(JwtAuthGuard, RolesGuard)
export class AdminController {
  @Get('dashboard')
  @Roles('admin')
  getDashboard(@CurrentUser() user: AuthUser) {
    return { message: 'Admin dashboard', user };
  }
}

Permission-Based Access Control

import { Controller, Post, UseGuards } from '@nestjs/common';
import { JwtAuthGuard, PermissionsGuard, Permissions } from '@wikiccu/nest-auth';

@Controller('users')
@UseGuards(JwtAuthGuard, PermissionsGuard)
export class UserController {
  @Post('create')
  @Permissions('user:create')
  createUser() {
    return { message: 'User created' };
  }
}

Public Routes

import { Controller, Get } from '@nestjs/common';
import { Public } from '@wikiccu/nest-auth';

@Controller('public')
export class PublicController {
  @Get('health')
  @Public()
  healthCheck() {
    return { status: 'ok' };
  }
}

Database Schema

The package includes a comprehensive Prisma schema with the following models:

• User - User accounts with authentication data
• Role - User roles for access control
• Permission - Fine-grained permissions
• UserRole - Many-to-many relationship between users and roles
• Session - User session tracking
• RefreshToken - JWT refresh tokens
• PasswordResetToken - Password reset tokens
• EmailVerificationToken - Email verification tokens

Email Templates

The package includes customizable email templates for:

• Email verification
• Password reset
• Welcome emails
• Account locked notifications
• Password change notifications

Configuration Options

JWT Configuration

// JWT settings
JWT_SECRET="your-secret-key"
JWT_EXPIRES_IN="15m"
REFRESH_TOKEN_EXPIRES_IN="7d"
REFRESH_TOKEN_EXPIRES_IN_REMEMBER="30d"

Email Configuration

// SMTP settings
SMTP_HOST="smtp.gmail.com"
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER="your-email@gmail.com"
SMTP_PASS="your-app-password"
EMAIL_FROM="noreply@yourdomain.com"
EMAIL_FROM_NAME="Your App Name"

Security Configuration

// Security settings
BCRYPT_ROUNDS=12
MAX_LOGIN_ATTEMPTS=5
LOCKOUT_DURATION="15m"

Customization

Custom Email Templates

You can extend the EmailService to customize email templates:

import { EmailService } from '@wikiccu/nest-auth';

@Injectable()
export class CustomEmailService extends EmailService {
  protected getEmailVerificationTemplate(verificationUrl: string): EmailTemplate {
    return {
      subject: 'Verify Your Email - Custom App',
      html: `<div>Your custom template here</div>`,
      text: 'Your custom template here',
    };
  }
}

Custom Guards

You can create custom guards by extending the provided ones:

import { Injectable } from '@nestjs/common';
import { JwtAuthGuard } from '@wikiccu/nest-auth';

@Injectable()
export class CustomAuthGuard extends JwtAuthGuard {
  // Add your custom logic here
}

Error Handling

The package provides comprehensive error handling with appropriate HTTP status codes:

• 400 Bad Request - Invalid input data
• 401 Unauthorized - Authentication required or invalid credentials
• 403 Forbidden - Insufficient permissions
• 409 Conflict - Resource already exists
• 500 Internal Server Error - Server errors

Security Features

• Password Hashing - Bcrypt with configurable rounds
• JWT Token Security - Secure token generation and validation
• Refresh Token Rotation - Automatic token rotation for security
• Rate Limiting - Built-in rate limiting for authentication endpoints
• Session Management - Track and manage user sessions
• Account Lockout - Automatic account lockout after failed attempts
• Email Verification - Secure email verification process
• Password Reset - Secure password reset via email tokens

Testing

The package includes comprehensive test coverage. To run tests:

npm test

Postman Collection

A complete Postman collection is included with the package to help you test all authentication endpoints. The collection includes:

Features

• All API Endpoints - Complete coverage of all authentication endpoints
• Request Examples - Pre-filled request bodies with example data
• Response Examples - Sample responses for each endpoint
• Environment Variables - Automatic token management
• Authentication Flow - Login/logout flow with automatic token handling
• Organized Structure - Endpoints grouped by functionality (Public, Authenticated, Admin)

Import Instructions

1. Export the Collection: Run the export script to copy the collection to your project:

   npm run export-postman

   Or manually copy the postman-collection.json file from the package to your project directory.

2. Import to Postman:

   • Open Postman
   • Click "Import" button
   • Select the postman-collection.json file
   • The collection will be imported with all endpoints and examples

Environment Setup

1. Set Base URL: Update the baseUrl variable in the collection to match your API server
2. Authentication Flow:
   • Run the "Login User" request first
   • The collection will automatically store your access and refresh tokens
   • All subsequent authenticated requests will use the stored tokens
   • Use "Refresh Token" to get new tokens when needed

Endpoint Groups

• Public Endpoints: Registration, login, password reset, email verification
• Authenticated Endpoints: Profile management, password change, logout
• Admin Endpoints: User management (requires admin role)

Usage Tips

• Start with "Register User" to create a test account
• Use "Login User" to get authentication tokens
• Test authenticated endpoints with the stored tokens
• Use "Refresh Token" when tokens expire
• Admin endpoints require a user with admin role

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

License

MIT License - see LICENSE file for details

Support

For support and questions:

• Create an issue on GitHub
• Check the documentation
• Review the examples

Changelog

v2.0.2

• NEW: Added comprehensive Postman collection with all API endpoints
• NEW: Included request/response examples for all authentication endpoints
• NEW: Added automatic token management and authentication flow
• NEW: Created export script (npm run export-postman) for easy collection setup
• NEW: Enhanced API documentation with detailed endpoint specifications
• NEW: Added organized endpoint groups (Public, Authenticated, Admin)
• IMPROVED: Better developer experience with ready-to-use API testing tools

v2.0.1

• FIX: Corrected Prisma schema path in README.md from prisma/schema.prisma to dist/prisma/schema.prisma
• Fixed documentation to match actual package structure

v2.0.0

• BREAKING CHANGE: Updated peer dependencies to use >= version ranges for maximum compatibility
• BREAKING CHANGE: Removed specific version pinning to allow latest versions
• Fixed dependency conflicts with fresh NestJS installations
• Updated to be compatible with latest NestJS v11+ and all dependencies
• Package now works seamlessly with npm install without version conflicts
• Enhanced compatibility with the latest NestJS ecosystem

v1.0.4

• BREAKING CHANGE: Upgraded @nestjs/swagger to v8.0.0 for NestJS v11 compatibility
• Fixed dependency conflict with @nestjs/swagger v7.x (only supports NestJS v9/v10)
• Updated all dependencies to latest stable versions
• Enhanced compatibility with latest NestJS ecosystem

v1.0.3

• BREAKING CHANGE: Upgraded @nestjs/config to v4.0.0 compatibility
• Fixed dependency conflict with @nestjs/config v4.x
• Updated all dependencies to latest stable versions
• Enhanced compatibility with latest NestJS ecosystem

v1.0.2

• BREAKING CHANGE: Upgraded to NestJS v11 compatibility
• Updated all dependencies to latest stable versions
• Fixed dependency conflicts with newer NestJS versions
• Improved TypeScript configuration for better compatibility
• Updated Jest configuration for latest versions
• Enhanced error handling and type safety

v1.0.1

• Bug fixes and improvements
• Enhanced error handling

v1.0.0

• Initial release
• Complete authentication system
• JWT token management
• Role-based access control
• Email verification and password reset
• Comprehensive API documentation