JSPM

  • Created
  • Published
  • Downloads 241
  • Score
    100M100P100Q90445F
  • License SEE LICENSE

Embedded authentication engine for Node.js — NestJS, Express, Fastify

Package Exports

  • @nauth-toolkit/core
  • @nauth-toolkit/core/internal
  • @nauth-toolkit/core/openapi

Readme

@nauth-toolkit/core

The authentication engine behind nauth-toolkit. All auth business logic lives here — signup, login, MFA, social OAuth, sessions, JWT lifecycle, and more. Runs inside your server process, stores all data in your own database, makes zero external API calls.

Documentation · Quick Start · API Reference · Live Demo · GitHub


What it includes

  • Auth flows — signup, login, email/phone verification, forgot password, change password, account lockout
  • Social OAuth — Google, Apple, Facebook with web redirect and native mobile token flows, automatic account linking
  • Multi-factor auth — TOTP, SMS OTP, email OTP, WebAuthn passkeys, recovery codes, adaptive MFA by login risk
  • JWT lifecycle — access + refresh tokens, rotation with reuse detection, cookie or JSON delivery
  • Sessions — concurrent session limits, device tracking, IP geolocation, trusted devices, session revocation
  • Security — Argon2id password hashing, CSRF protection, per-IP and per-user rate limiting, account lockout
  • Audit trail — structured event log for logins, MFA, password changes, and security incidents
  • Challenge-based flows — verification, MFA, and password steps return challenge states, not hard errors
  • Single config — one TypeScript object defines your entire auth policy; everything bootstraps from it

Install

Express or Fastify — adapters (ExpressAdapter, FastifyAdapter) are included in this package:

npm install @nauth-toolkit/core @nauth-toolkit/database-typeorm-postgres @nauth-toolkit/storage-database @nauth-toolkit/email-console @nauth-toolkit/sms-console
# Or for MySQL: replace database-typeorm-postgres with database-typeorm-mysql

NestJS — install both core and the NestJS module:

npm install @nauth-toolkit/core @nauth-toolkit/nestjs @nauth-toolkit/database-typeorm-postgres @nauth-toolkit/storage-database @nauth-toolkit/email-console @nauth-toolkit/sms-console
# Or for MySQL: replace database-typeorm-postgres with database-typeorm-mysql

Quick start

Express

import express from 'express';
import { DataSource } from 'typeorm';
import { NAuth, ExpressAdapter, NAuthConfig } from '@nauth-toolkit/core';
// PostgreSQL:
import { getNAuthEntities } from '@nauth-toolkit/database-typeorm-postgres';
// MySQL: import { getNAuthEntities } from '@nauth-toolkit/database-typeorm-mysql';

const app = express();
app.use(express.json());

// Database
const dataSource = new DataSource({
  type: 'postgres', // or 'mysql'
  url: process.env.DATABASE_URL,
  entities: getNAuthEntities(),
  synchronize: true, // dev only
});
await dataSource.initialize();

// Bootstrap
const nauth = await NAuth.create({
  config: {
    jwt: { secret: process.env.JWT_SECRET },
    signup: { requireEmailVerification: false },
    tokenDelivery: { mode: 'json' },
  },
  dataSource,
  adapter: new ExpressAdapter(),
});

// Middleware — order matters
app.use(nauth.middleware.clientInfo); // MUST be first — initializes context
app.use(nauth.middleware.csrf); // CSRF validation
app.use(nauth.middleware.auth); // JWT validation
app.use(nauth.middleware.tokenDelivery); // Cookie delivery interceptor

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

app.post('/auth/login', nauth.helpers.public(), async (req, res, next) => {
  try {
    res.json(await nauth.authService.login(req.body));
  } catch (err) {
    next(err);
  }
});

app.get('/auth/me', nauth.helpers.requireAuth(), (req, res, next) => {
  try {
    res.json(nauth.helpers.getCurrentUser());
  } catch (err) {
    next(err);
  }
});

app.listen(3000);

Full guide: nauth.dev/docs/quick-start/express

Fastify

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

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

// Hooks — order matters
fastify.addHook('preHandler', nauth.middleware.clientInfo); // MUST be first
fastify.addHook('preHandler', nauth.middleware.csrf);
fastify.addHook('preHandler', nauth.middleware.auth);
fastify.addHook('onSend', nauth.middleware.tokenDelivery);

// Routes — wrap handlers with nauth.adapter.wrapRouteHandler for context access
fastify.post(
  '/auth/signup',
  { preHandler: nauth.helpers.public() },
  nauth.adapter.wrapRouteHandler(async (req) => nauth.authService.signup(req.body)),
);

Full guide: nauth.dev/docs/quick-start/fastify

NestJS

// auth.module.ts
import { Module } from '@nestjs/common';
import { AuthModule as NAuthModule } from '@nauth-toolkit/nestjs';

@Module({
  imports: [NAuthModule.forRoot(authConfig)],
  controllers: [AuthController],
})
export class AuthModule {}
// auth.controller.ts
import { AuthService, SignupDTO, LoginDTO, AuthGuard, Public, CurrentUser, IUser } from '@nauth-toolkit/nestjs';

@UseGuards(AuthGuard)
@Controller('auth')
export class AuthController {
  constructor(private authService: AuthService) {}

  @Public()
  @Post('signup')
  @HttpCode(201)
  signup(@Body() dto: SignupDTO) {
    return this.authService.signup(dto);
  }

  @Public()
  @Post('login')
  login(@Body() dto: LoginDTO) {
    return this.authService.login(dto);
  }

  @Get('me')
  profile(@CurrentUser() user: IUser) {
    return user;
  }
}

Full guide: nauth.dev/docs/quick-start/nestjs


Example apps

Full working examples with Docker, database setup, and frontend integration:

Example Description
Express Express + TypeORM + PostgreSQL
Fastify Fastify + TypeORM + PostgreSQL
NestJS NestJS + TypeORM + PostgreSQL
React React frontend with @nauth-toolkit/client

Repository: github.com/noorixorg/nauth


Package ecosystem

nauth-toolkit is modular. Start with this package plus a database adapter, then add providers for MFA, social, email, and SMS as needed.

Framework adapter

Package Purpose
@nauth-toolkit/nestjs NestJS DynamicModule with AuthModule.forRoot(), guards, decorators, and interceptors

Frontend SDKs

Package Purpose
@nauth-toolkit/client Framework-agnostic client SDK — React, Vue, Svelte, vanilla JS
@nauth-toolkit/client-angular Angular SDK with NAuthModule, AuthService, HTTP interceptor, and route guards

Database

Pick one. Provides TypeORM entity definitions for your database.

Package Purpose
@nauth-toolkit/database-typeorm-postgres PostgreSQL entities
@nauth-toolkit/database-typeorm-mysql MySQL entities

Storage

Used for rate limiting, token blacklisting, account lockout, and distributed locks.

Package Purpose
@nauth-toolkit/storage-database Database-backed storage — no Redis required
@nauth-toolkit/storage-redis Redis — recommended for production and multi-instance deployments

MFA providers

Each method is a separate package. Install only what you need.

Package Method
@nauth-toolkit/mfa-totp TOTP — Google Authenticator, Authy
@nauth-toolkit/mfa-sms SMS OTP
@nauth-toolkit/mfa-email Email OTP
@nauth-toolkit/mfa-passkey WebAuthn / passkeys — Face ID, Touch ID, YubiKey

Social OAuth

Each provider is a separate package with web redirect and native mobile token support.

Package Provider
@nauth-toolkit/social-google Google OAuth 2.0
@nauth-toolkit/social-apple Sign in with Apple
@nauth-toolkit/social-facebook Facebook Login

Email providers

Required if you enable email verification, email OTP, or password reset emails.

Package Purpose
@nauth-toolkit/email-nodemailer Nodemailer — SMTP, AWS SES, SendGrid, and any transport
@nauth-toolkit/email-console Log emails to console — development use

SMS providers

Required if you enable phone verification or SMS MFA.

Package Purpose
@nauth-toolkit/sms-aws-sns AWS SNS
@nauth-toolkit/sms-console Log SMS to console — development use

Other

Package Purpose
@nauth-toolkit/recaptcha reCAPTCHA v2, v3, and Enterprise

Documentation

Resource Link
Full documentation nauth.dev
Quick Start — NestJS nauth.dev/docs/quick-start/nestjs
Quick Start — Express nauth.dev/docs/quick-start/express
Quick Start — Fastify nauth.dev/docs/quick-start/fastify
Configuration reference nauth.dev/docs/concepts/configuration
Auth flows guide nauth.dev/docs/guides/basic-auth
API reference nauth.dev/docs/api/overview
Frontend SDK nauth.dev/docs/frontend-sdk/overview
Example apps github.com/noorixorg/nauth
Live demo demo.nauth.dev

Free to use. See license.