API Reference

Complete reference documentation for nauth-toolkit. All APIs documented with TypeScript signatures, validation rules, and framework-specific examples.

NestJS

Getting Started

import { AuthService, AuthModule, AuthGuard } from '@nauth-toolkit/nestjs';

Documentation Structure

Framework Integration

• NestJS Overview - Modules, configuration, setup
• Guards - Route protection with @UseGuards(AuthGuard)
• Decorators - Extract user data with @CurrentUser()

Core Services

• AuthService - Login, signup, password management, sessions
• MFAService - Multi-factor authentication setup and verification
• SocialAuthService - Google, Apple, Facebook, Microsoft OAuth
• All Services - Complete service list

Data Transfer Objects

• LoginDTO - User login request
• SignupDTO - User registration request
• AuthResponseDTO - Unified authentication response
• All DTOs - Complete DTO list

Identity Provider

• OIDC Provider - Be an OpenID Connect provider, so other apps can offer "Sign in with your app"

Error Handling

• NAuthException - Structured exception class
• Error Handling Guide - Best practices and patterns

Feature Packages

MFA Providers

npm

npm install @nauth-toolkit/mfa-totp

Yarn

yarn add @nauth-toolkit/mfa-totp

pnpm

pnpm add @nauth-toolkit/mfa-totp

Bun

bun add @nauth-toolkit/mfa-totp

import { TOTPMFAModule } from '@nauth-toolkit/mfa-totp/nestjs';
import { SMSMFAModule } from '@nauth-toolkit/mfa-sms/nestjs';

@Module({
  imports: [
    AuthModule.forRoot(config),
    TOTPMFAModule,
    SMSMFAModule,
  ],
})

Social Auth Providers

npm

npm install @nauth-toolkit/social-google

Yarn

yarn add @nauth-toolkit/social-google

pnpm

pnpm add @nauth-toolkit/social-google

Bun

bun add @nauth-toolkit/social-google

import { GoogleSocialAuthModule } from '@nauth-toolkit/social-google/nestjs';
import { AppleSocialAuthModule } from '@nauth-toolkit/social-apple/nestjs';

@Module({
  imports: [
    AuthModule.forRoot(config),
    GoogleSocialAuthModule,
    AppleSocialAuthModule,
  ],
})

Email & SMS Providers

npm

npm install @nauth-toolkit/email-nodemailer

Yarn

yarn add @nauth-toolkit/email-nodemailer

pnpm

pnpm add @nauth-toolkit/email-nodemailer

Bun

bun add @nauth-toolkit/email-nodemailer

Configure in AuthModule.forRoot():

AuthModule.forRoot({
  emailProvider: new NodemailerEmailProvider({ ... }),
  smsProvider: new TwilioSMSProvider({ ... }),
})

OpenID Connect Provider

npm

npm install @nauth-toolkit/oidc-provider oidc-provider

Yarn

yarn add @nauth-toolkit/oidc-provider oidc-provider

pnpm

pnpm add @nauth-toolkit/oidc-provider oidc-provider

Bun

bun add @nauth-toolkit/oidc-provider oidc-provider

import { OIDCProviderModule } from '@nauth-toolkit/oidc-provider/nestjs';

@Module({
  imports: [AuthModule.forRoot(config), OIDCProviderModule.forRoot(oidcConfig)],
})

See Set Up the OpenID Connect Provider.

Express

Getting Started

import { NAuth, ExpressAdapter, AuthService } from '@nauth-toolkit/core';

Documentation Structure

Framework Integration

• Bootstrap - NAuth.create() with ExpressAdapter
• Middleware - nauth.middleware.clientInfo, auth, csrf, tokenDelivery
• Helpers - nauth.helpers.requireAuth(), public(), getCurrentUser()

Core Services

• AuthService - Login, signup, password management, sessions
• MFAService - Multi-factor authentication setup and verification
• SocialAuthService - Google, Apple, Facebook, Microsoft OAuth
• All Services - Complete service list

Data Transfer Objects

• LoginDTO - User login request
• SignupDTO - User registration request
• AuthResponseDTO - Unified authentication response
• All DTOs - Complete DTO list

Error Handling

• NAuthException - Structured exception class
• Error Handling Guide - Best practices and patterns

Bootstrap Example

import { NAuth, ExpressAdapter } from '@nauth-toolkit/core';

const nauth = await NAuth.create({
  config: authConfig,
  dataSource: dataSource,
  adapter: new ExpressAdapter(),
});

// Mount middleware (order matters)
app.use(nauth.middleware.clientInfo); // FIRST
app.use(nauth.middleware.csrf);
app.use(nauth.middleware.auth);
app.use(nauth.middleware.tokenDelivery);

// Routes
app.post('/auth/signup', nauth.helpers.public(), async (req, res, next) => {
  try {
    const result = await nauth.authService.signup(req.body);
    res.status(201).json(result);
  } catch (error) {
    next(error);
  }
});

Feature Packages

MFA Providers

npm

npm install @nauth-toolkit/mfa-totp

Yarn

yarn add @nauth-toolkit/mfa-totp

pnpm

pnpm add @nauth-toolkit/mfa-totp

Bun

bun add @nauth-toolkit/mfa-totp

MFA providers auto-register when configured:

const nauth = await NAuth.create({
  config: {
    mfa: {
      enabled: true,
      allowedMethods: [MFAMethod.TOTP, MFAMethod.SMS],
    },
  },
  dataSource,
  adapter: new ExpressAdapter(),
});

Social Auth Providers

npm

npm install @nauth-toolkit/social-google

Yarn

yarn add @nauth-toolkit/social-google

pnpm

pnpm add @nauth-toolkit/social-google

Bun

bun add @nauth-toolkit/social-google

Social providers auto-register when configured:

const nauth = await NAuth.create({
  config: {
    social: {
      google: {
        enabled: true,
        clientId: process.env.GOOGLE_CLIENT_ID,
        clientSecret: process.env.GOOGLE_CLIENT_SECRET,
      },
    },
  },
  dataSource,
  adapter: new ExpressAdapter(),
});

Email & SMS Providers

npm

npm install @nauth-toolkit/email-nodemailer

Yarn

yarn add @nauth-toolkit/email-nodemailer

pnpm

pnpm add @nauth-toolkit/email-nodemailer

Bun

bun add @nauth-toolkit/email-nodemailer

Configure in NAuth.create():

const nauth = await NAuth.create({
  config: {
    emailProvider: new NodemailerEmailProvider({ ... }),
    smsProvider: new TwilioSMSProvider({ ... }),
  },
  dataSource,
  adapter: new ExpressAdapter(),
});

Fastify

Getting Started

import { NAuth, FastifyAdapter, AuthService } from '@nauth-toolkit/core';

Documentation Structure

Framework Integration

• Bootstrap - NAuth.create() with FastifyAdapter
• Hooks - nauth.middleware.clientInfo, auth, csrf, tokenDelivery
• Helpers - nauth.helpers.requireAuth(), public(), getCurrentUser()
• Context - nauth.adapter.wrapRouteHandler() for route handlers

Core Services

• AuthService - Login, signup, password management, sessions
• MFAService - Multi-factor authentication setup and verification
• SocialAuthService - Google, Apple, Facebook, Microsoft OAuth
• All Services - Complete service list

Data Transfer Objects

• LoginDTO - User login request
• SignupDTO - User registration request
• AuthResponseDTO - Unified authentication response
• All DTOs - Complete DTO list

Error Handling

• NAuthException - Structured exception class
• Error Handling Guide - Best practices and patterns

Bootstrap Example

import { NAuth, FastifyAdapter } from '@nauth-toolkit/core';

const nauth = await NAuth.create({
  config: authConfig,
  dataSource: dataSource,
  adapter: new FastifyAdapter(),
});

// Register hooks (order matters)
fastify.addHook('onRequest', nauth.middleware.clientInfo as any); // FIRST
fastify.addHook('onRequest', nauth.middleware.csrf as any);
fastify.addHook('onRequest', nauth.middleware.auth as any);
fastify.addHook('onSend', nauth.middleware.tokenDelivery as any);

// Routes - wrap handlers with nauth.adapter.wrapRouteHandler
fastify.post(
  '/auth/signup',
  { preHandler: nauth.helpers.public() as any },
  nauth.adapter.wrapRouteHandler(async (req) => {
    return nauth.authService.signup(req.body as any);
  }),
);

Fastify Context

Fastify hooks run independently, so AsyncLocalStorage context must be restored in route handlers. Use nauth.adapter.wrapRouteHandler() to access nauth.helpers.getCurrentUser() and context-dependent services.

Feature Packages

MFA Providers

npm

npm install @nauth-toolkit/mfa-totp

Yarn

yarn add @nauth-toolkit/mfa-totp

pnpm

pnpm add @nauth-toolkit/mfa-totp

Bun

bun add @nauth-toolkit/mfa-totp

MFA providers auto-register when configured:

const nauth = await NAuth.create({
  config: {
    mfa: {
      enabled: true,
      allowedMethods: [MFAMethod.TOTP, MFAMethod.SMS],
    },
  },
  dataSource,
  adapter: new FastifyAdapter(),
});

Social Auth Providers

npm

npm install @nauth-toolkit/social-google

Yarn

yarn add @nauth-toolkit/social-google

pnpm

pnpm add @nauth-toolkit/social-google

Bun

bun add @nauth-toolkit/social-google

Social providers auto-register when configured:

const nauth = await NAuth.create({
  config: {
    social: {
      google: {
        enabled: true,
        clientId: process.env.GOOGLE_CLIENT_ID,
        clientSecret: process.env.GOOGLE_CLIENT_SECRET,
      },
    },
  },
  dataSource,
  adapter: new FastifyAdapter(),
});

Email & SMS Providers

npm

npm install @nauth-toolkit/email-nodemailer

Yarn

yarn add @nauth-toolkit/email-nodemailer

pnpm

pnpm add @nauth-toolkit/email-nodemailer

Bun

bun add @nauth-toolkit/email-nodemailer

Configure in NAuth.create():

const nauth = await NAuth.create({
  config: {
    emailProvider: new NodemailerEmailProvider({ ... }),
    smsProvider: new TwilioSMSProvider({ ... }),
  },
  dataSource,
  adapter: new FastifyAdapter(),
});

Reading API Documentation

Services

Service pages document methods with:

• TypeScript signatures (parameters and return types)
• Error codes with NAuthException details
• Framework-specific examples in tabs
• Links to related DTOs

DTOs

DTO pages document request/response objects with:

• Properties table with validation rules
• JSON examples
• Links to services that use them

Configuration

Configuration pages document settings with:

• Interface definitions
• Default values
• Validation rules

See Configuration for config options.

API Stability

Public APIs (documented here) are stable and follow semantic versioning:

• Major versions for breaking changes
• Minor versions for new features
• Patch versions for bug fixes

Internal APIs (not documented) may change without notice.

Quick Links

Getting Started:

• Quick Start Guide
• Configuration Reference
• How It Works

Need Help?

• npm package: https://www.npmjs.com/package/@nauth-toolkit/core
• Source: https://github.com/noorixorg/nauth-toolkit