# @ackplus/nest-auth

A comprehensive authentication and authorization module for NestJS applications, featuring:

- **Multi-tenant support** out of the box
- **Role-Based Access Control (RBAC)**
- **Session Management** with secure cookie or header-based tokens
- **Two-Factor Authentication (2FA)** (TOTP, SMS, Email)
- **Social Login** (Google, Facebook, Apple, GitHub)
- **Admin Console** UI for managing users and roles
- **Mobile-ready** API design

## Installation

```bash
npm install @ackplus/nest-auth
```

## Configuration

Import `NestAuthModule` in your `AppModule`. You can use `forRoot` or `forRootAsync`.

```typescript
import { NestAuthModule } from '@ackplus/nest-auth';

@Module({
  imports: [
    NestAuthModule.forRootAsync({
      useFactory: (configService: ConfigService) => ({
        appName: 'My App',
        jwt: {
          secret: configService.get('JWT_SECRET'),
          accessTokenExpiresIn: '15m',
          refreshTokenExpiresIn: '7d',
        },
        mfa: {
          enabled: true,
          methods: ['totp', 'email'],
          // Trusted device configuration
          trustedDeviceDuration: '30d', // Duration to trust a device
          trustDeviceStorageName: 'nest_auth_device_trust', // Cookie/Header name
        },
        // ... other options
      }),
      inject: [ConfigService],
    }),
  ],
})
export class AppModule {}
```

## Features

### Two-Factor Authentication (2FA)

The library supports TOTP (Authenticator apps), SMS, and Email-based 2FA.

#### Trusted Devices ("Remember Me")

Users can choose to trust their device during 2FA verification to skip 2FA on subsequent logins for a configured duration.

**Web Flow (Cookies):**
1.  Login triggers 2FA (`isRequiresMfa: true`).
2.  Call `/auth/verify-2fa` with `rememberDevice: true`.
3.  Server sets a `nest_auth_device_trust` (or configured name) HTTP-only cookie.
4.  Subsequent logins from the same browser will automatically skip 2FA.

**Mobile Flow (Headers):**
1.  Login triggers 2FA (`isRequiresMfa: true`).
2.  Call `/auth/verify-2fa` with `rememberDevice: true`.
3.  Response body includes `trustToken`.
4.  Store `trustToken` securely (e.g., Keychain/Keystore).
5.  For subsequent logins, send the token in the request header:
    ```
    x-nest-auth-trust-token: <your-trust-token>
    ```
    *Note: The header name defaults to `nest_auth_device_trust` or whatever you configured in `trustDeviceStorageName`.*

### Admin Console

The library includes an embedded Admin Console UI for managing users, roles, and settings.
Access it at `/auth/admin`.

## API Documentation

The API documentation is available via Swagger UI at `/api` (if configured in your main application).
You can also download the OpenAPI specification JSON from the Admin Console or the Swagger UI.
