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-mysqlNestJS — 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-mysqlQuick 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.