Getting Started with node-auth

node-auth is a production-ready, database-agnostic JWT authentication and communication bus for Node.js written in TypeScript. It establishes a 360-degree communication and access control layer compatible with any Node.js framework (NestJS, Next.js, Express, Fastify, etc.) and any database through a simple interface pattern.

Before you start

Make sure you have Node.js 18+ and a package manager (npm / yarn / pnpm) installed.

Pick a recipe

Choose the authentication strategy that fits your application. You can combine multiple recipes.

Recipe	Description
Email / Password	Classic login with bcrypt hashing
OAuth / Social	Google, GitHub, custom providers
Magic Link	Passwordless email login
SMS OTP	Phone number verification
TOTP 2FA	Google Authenticator-compatible
API Keys	Machine-to-machine service tokens
Multi-Tenancy	Isolated tenant support
Auth Tools & SSE	Event bus, SSE streams, webhooks, telemetry

---

Step 1: Install

npm install @nik2208/node-auth

---

Step 2: Implement IUserStore

node-auth is database-agnostic. You connect it to your database by implementing the IUserStore interface:

import { IUserStore, BaseUser } from '@nik2208/node-auth';

export class MyUserStore implements IUserStore {
  async findByEmail(email: string): Promise<BaseUser | null> {
    return db.users.findOne({ email });
  }
  async findById(id: string): Promise<BaseUser | null> {
    return db.users.findOne({ id });
  }
  async create(data: Partial<BaseUser>): Promise<BaseUser> {
    return db.users.insert(data);
  }
  async updateRefreshToken(userId: string, token: string | null, expiry: Date | null): Promise<void> {
    await db.users.update({ id: userId }, { refreshToken: token, refreshTokenExpiry: expiry });
  }
  // ... other methods as needed
}

tip

See Database Integration for ready-to-use implementations for SQLite, PostgreSQL, MySQL, and MongoDB.

---

Step 3: Configure AuthConfigurator

Express

import express from 'express';
import { AuthConfigurator } from '@nik2208/node-auth';
import { MyUserStore } from './my-user-store';

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

const auth = new AuthConfigurator(
  {
    accessTokenSecret: process.env.ACCESS_TOKEN_SECRET!,
    refreshTokenSecret: process.env.REFRESH_TOKEN_SECRET!,
    accessTokenExpiresIn: '15m',
    refreshTokenExpiresIn: '7d',
  },
  new MyUserStore()
);

NestJS

// auth.module.ts
import { Module } from '@nestjs/common';
import { AuthConfigurator } from '@nik2208/node-auth';
import { MyUserStore } from './my-user-store';

const auth = new AuthConfigurator(
  {
    accessTokenSecret: process.env.ACCESS_TOKEN_SECRET!,
    refreshTokenSecret: process.env.REFRESH_TOKEN_SECRET!,
    accessTokenExpiresIn: '15m',
    refreshTokenExpiresIn: '7d',
  },
  new MyUserStore()
);

@Module({
  providers: [{ provide: 'AUTH', useValue: auth }],
  exports: ['AUTH'],
})
export class AuthModule {}

Next.js

// lib/auth.ts
import { AuthConfigurator } from '@nik2208/node-auth';
import { MyUserStore } from './my-user-store';

export const auth = new AuthConfigurator(
  {
    accessTokenSecret: process.env.ACCESS_TOKEN_SECRET!,
    refreshTokenSecret: process.env.REFRESH_TOKEN_SECRET!,
    accessTokenExpiresIn: '15m',
    refreshTokenExpiresIn: '7d',
  },
  new MyUserStore()
);

---

Step 4: Mount the router

Express

// Mount all auth endpoints under /auth
app.use('/auth', auth.router());

// Protect routes
app.get('/protected', auth.middleware(), (req, res) => {
  res.json({ user: req.user });
});

app.listen(3000);

NestJS

// main.ts
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { auth } from './auth';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.use('/auth', auth.router());
  await app.listen(3000);
}
bootstrap();

Next.js App Router

// See the Next.js integration guide for the full catch-all route handler
// that bridges the App Router request/response to the Express-compatible router.
// https://your-wiki/docs/frameworks/nextjs
import { getAuth } from '@/lib/auth';

// Use auth.router() inside a catch-all API route handler.
// The auth singleton is created in lib/auth.ts:
//   export const auth = new AuthConfigurator(config, userStore);

---

Next Steps

• Installation & Configuration – Full config options, CSRF, 2FA
• Authentication Strategies – All available recipes
• Database Integration – IUserStore implementations
• API Reference – All endpoints