🔑@hsuite/auth - Authentication & User Management Module

🔐 Comprehensive NestJS authentication module providing unified Web2 & Web3 authentication, user management, and API key authentication

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

---

Table of Contents

• Quick Start

• Architecture

• API Reference

• Guides

• Examples

• Integration

---

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

• ApiKeyAuthGuard - API key authentication guard

🌐 Strategies

• JwtStrategy - Passport JWT strategy implementation

• RedisStrategy - Redis-based session strategy

• Web3Strategy - Blockchain wallet authentication

• ApiKeyStrategy - Header-based API key validation

🔧 Services

• AuthService - Core authentication logic

• UsersService - User management operations

• ApiKeyService - API key validation

• AuthController - REST API endpoints

👥 User Management

• UsersModule - Complete user management module

• UsersService - User CRUD operations and business logic

• UserModelService - Database operations with Mongoose

• User Entity - Mongoose schema and TypeScript types

🔑 API Key Authentication

• ApiKeyModule - API key authentication module

• ApiKeyService - API key validation and management

• ApiKeyAuthGuard - Route protection with API keys

• ApiKeyStrategy - Passport strategy for API keys

Module Structure

src/
├── users/           # User management module
│   ├── entities/    # Mongoose schemas
│   ├── models/      # Database operations
│   ├── users.service.ts
│   └── users.module.ts
├── api-key/         # API key authentication module
│   ├── guards/      # API key guard
│   ├── strategies/  # API key strategy
│   ├── api-key.service.ts
│   └── api-key.module.ts
├── 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/client": "^2.1.2",
  "@hsuite/smart-config": "^2.1.1",
  "@hsuite/helpers": "^2.0.8",
  "@hsuite/ipfs": "^2.0.5",
  "@hsuite/mirrors": "^2.0.3",
  "@hsuite/hashgraph-types": "^2.0.3",
  "@hsuite/smart-network-types": "^2.0.0",
  "@hsuite/subscriptions-types": "^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.

Built with ❤️ by the HSuite Team Copyright © 2025 HSuite. All rights reserved.