@hsuite/auth - Authentication Module

🔐 Comprehensive NestJS authentication module providing unified Web2 & Web3 authentication solutions

A robust, enterprise-grade authentication module that seamlessly integrates traditional username/password authentication with cutting-edge Web3 wallet-based authentication, designed specifically for the HSuite ecosystem.

Quick Start

Installation

npm install @hsuite/auth

Basic Setup

import { AuthModule } from '@hsuite/auth';

@Module({
  imports: [
    AuthModule.forRootAsync({
      useFactory: () => ({
        commonOptions: {
          jwt: { secret: 'your-secret', signOptions: { expiresIn: '24h' } },
          passport: IAuth.IConfiguration.IPassportStrategy.JWT
        },
        web2Options: { confirmation_required: true },
        web3Options: { tokenGateOptions: {} }
      })
    })
  ]
})
export class AppModule {}

Protect Your Routes

@UseGuards(JwtAuthGuard)
@Get('protected')
getProtected(@Request() req) {
  return { user: req.user };
}

Architecture

Core Components

🛡️ Guards

JwtAuthGuard - JWT-based route protection
RedisAuthGuard - Redis session authentication
ConfirmedAuthGuard - Email confirmation requirement

🌐 Strategies

JwtStrategy - Passport JWT strategy implementation
RedisStrategy - Redis-based session strategy
Web3Strategy - Blockchain wallet authentication

🔧 Services

AuthService - Core authentication logic
AuthController - REST API endpoints

Module Structure

src/
├── guards/           # Route protection guards
├── strategies/       # Passport authentication strategies  
├── interfaces/       # TypeScript interfaces
├── serializers/      # Session serialization
├── web2/            # Traditional auth (username/password)
├── web3/            # Blockchain auth (wallet-based)
├── redis/           # Redis session management
├── auth.module.ts   # Main module configuration
├── auth.service.ts  # Core service implementation
└── auth.controller.ts # HTTP endpoints

API Reference

AuthModule

Static Methods

forRootAsync(options: AuthModuleAsyncOptions): DynamicModule

Configures the authentication module with async dependency injection.

interface AuthModuleAsyncOptions {
  imports?: any[];
  useFactory?: (...args: any[]) => Promise<IAuth.IConfiguration.IAuthentication>;
  inject?: any[];
  config?: {
    passport: IAuth.IConfiguration.IPassportStrategy;
    module: 'web2' | 'web3';
    options: IAuth.IConfiguration.IOptions;
  };
}

AuthService

Core Methods

validateUser(username: string, password: string): Promise<any>

Validates user credentials for Web2 authentication

login(user: any): Promise<{ access_token: string }>

Generates JWT token for authenticated user

register(userData: CreateUserDto): Promise<User>

Registers new user with email confirmation

Guards Reference

JwtAuthGuard

@UseGuards(JwtAuthGuard)
@Get('jwt-protected')
jwtProtected(@Request() req) {
  return { user: req.user };
}

RedisAuthGuard

@UseGuards(RedisAuthGuard)
@Get('session-protected')
sessionProtected(@Request() req) {
  return { session: req.session };
}

ConfirmedAuthGuard

@UseGuards(JwtAuthGuard, ConfirmedAuthGuard)
@Post('confirmed-only')
confirmedOnly(@Request() req) {
  return { message: 'Email confirmed user only' };
}

Guides

Web2 Authentication Guide

Learn how to implement traditional username/password authentication with email confirmation and 2FA. Configure user registration, login flows, password reset, and session management.

Web3 Authentication Guide

Implement blockchain wallet-based authentication with signature verification and token gating. Set up wallet connection, signature validation, and decentralized identity management.

Session Management Guide

Configure Redis-based session management for distributed applications. Implement session storage, expiration policies, and cross-service session sharing.

Guards & Strategies Guide

Deep dive into authentication guards and Passport strategies. Create custom guards, implement authorization logic, and manage authentication flows.

Examples

Complete Module Configuration

@Module({
  imports: [
    AuthModule.forRootAsync({
      imports: [ConfigModule],
      useFactory: async (configService: ConfigService) => ({
        commonOptions: {
          jwt: {
            secret: configService.get('JWT_SECRET'),
            signOptions: { expiresIn: '24h' }
          },
          passport: IAuth.IConfiguration.IPassportStrategy.JWT,
          operator: {
            accountId: configService.get('HEDERA_ACCOUNT_ID'),
            privateKey: configService.get('HEDERA_PRIVATE_KEY')
          },
          appName: configService.get('APP_NAME', 'HSuite')
        },
        web2Options: {
          confirmation_required: true,
          admin_only: false,
          sendMailOptions: {
            confirm: {
              subject: 'Confirm your account',
              template: 'confirmation'
            }
          },
          mailerOptions: {
            transport: {
              host: configService.get('SMTP_HOST'),
              port: configService.get('SMTP_PORT'),
              auth: {
                user: configService.get('SMTP_USER'),
                pass: configService.get('SMTP_PASS')
              }
            }
          },
          twilioOptions: {
            accountSid: configService.get('TWILIO_ACCOUNT_SID'),
            authToken: configService.get('TWILIO_AUTH_TOKEN'),
            serviceSid: configService.get('TWILIO_SERVICE_SID')
          }
        },
        web3Options: {
          tokenGateOptions: {
            requiredTokens: [
              {
                contractAddress: '0x...',
                minimumBalance: 1
              }
            ]
          }
        }
      }),
      inject: [ConfigService]
    })
  ]
})
export class AppModule {}

Multi-Guard Protection

@Controller('api')
export class SecureController {
  @UseGuards(JwtAuthGuard, ConfirmedAuthGuard)
  @Get('secure-data')
  getSecureData(@Request() req) {
    return {
      message: 'Access granted to confirmed user',
      user: req.user
    };
  }

  @UseGuards(RedisAuthGuard)
  @Post('session-action')
  sessionAction(@Request() req) {
    return {
      message: 'Session-based action completed',
      sessionId: req.session.id
    };
  }
}

Integration

Required Dependencies

{
  "@hsuite/auth-types": "^2.1.2",
  "@hsuite/users": "^2.1.0",
  "@hsuite/client": "^2.1.2",
  "@hsuite/smart-config": "^2.1.1"
}

Environment Variables

# JWT Configuration
JWT_SECRET=your-secret-key

# Database
DB_HOST=localhost
DB_PORT=5432
DB_USERNAME=postgres
DB_PASSWORD=password
DB_DATABASE=hsuite

# Email Configuration (Web2)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
[email protected]
SMTP_PASS=your-app-password

# Twilio Configuration (2FA)
TWILIO_ACCOUNT_SID=ACxxxxx
TWILIO_AUTH_TOKEN=xxxxx
TWILIO_SERVICE_SID=VAxxxxx

# Hedera Configuration (Web3)
HEDERA_ACCOUNT_ID=0.0.123456
HEDERA_PRIVATE_KEY=302e020100300506032b657004220420...

TypeScript Configuration

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "strict": true
  }
}

📝 Note: This module requires proper configuration of external services (Redis, PostgreSQL, SMTP, Twilio) for full functionality. See individual guides for detailed setup instructions.

Previous@hsuite/auth-types Next@hsuite/client-types

Last updated 23 days ago

Table of Contents