# @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](#quick-start)
* [Architecture](#architecture)
* [API Reference](#api-reference)
* [Guides](#guides)
* [Examples](#examples)
* [Integration](#integration)

***

## Quick Start

### Installation

```bash
npm install @hsuite/auth
```

### Basic Setup

```typescript
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

```typescript
@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.

```typescript
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

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

#### RedisAuthGuard

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

#### ConfirmedAuthGuard

```typescript
@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

```typescript
@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

```typescript
@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

```json
{
  "@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

```env
# 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
SMTP_USER=your-email@gmail.com
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

```json
{
  "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.

<p align="center">Built with ❤️ by the HSuite Team<br>Copyright © 2025 HSuite. All rights reserved.</p>