![\"@bymax-one/nest-auth\"](\"https://img.shields.io/badge/%40bymax--one-nest--auth-000000?style=for-the-badge&logo=nestjs&logoColor=E0234E\"){kind=icon}
\n\n
\n Full-stack authentication for NestJS, React & Next.js
\n JWT · MFA · OAuth · Sessions · Multi-Tenant · Zero External Crypto Dependencies\n
\n ![\"npm](\"https://img.shields.io/npm/v/@bymax-one/nest-auth?style=flat-square&colorA=000000&colorB=000000\")
![\"npm](\"https://img.shields.io/npm/dm/@bymax-one/nest-auth?style=flat-square&colorA=000000&colorB=000000\")
![\"CI](\"https://img.shields.io/github/actions/workflow/status/bymaxone/nest-auth/ci.yml?branch=main&style=flat-square&colorA=000000&label=CI\")
![\"coverage\"](\"https://img.shields.io/badge/coverage-100%25-brightgreen?style=flat-square&colorA=000000\"){kind=icon}
![\"mutation](\"https://img.shields.io/badge/mutation-100%25-brightgreen?style=flat-square&colorA=000000\"){kind=icon}
\n
![\"license\"](\"https://img.shields.io/github/license/bymaxone/nest-auth?style=flat-square&colorA=000000&colorB=000000\")
![\"TypeScript\"](\"https://img.shields.io/badge/TypeScript-strict-3178C6?style=flat-square&logo=typescript&logoColor=white\"){kind=icon}
![\"Node.js\"](\"https://img.shields.io/badge/Node.js-24%2B-339933?style=flat-square&logo=node.js&logoColor=white\"){kind=icon}
\n GitHub ·\n Issues ·\n Quick Start ·\n API Reference ·\n Example App\n
\n\n---\n\n## ✨ Overview\n\n`@bymax-one/nest-auth` is a **complete authentication and authorization solution** shipped as a single npm package with **5 subpath exports** — covering everything from NestJS backend guards to React hooks and Next.js route handlers.\n\nInstead of wiring together dozens of packages for JWT, MFA, OAuth, sessions, password reset, and brute-force protection, you install one library and get a production-ready auth system that works across your entire stack.\n\n### Why nest-auth?\n\n- **🎯 One package, full stack** — Backend module, shared types, fetch client, React hooks, and Next.js integration all in a single `pnpm add`. Types and constants are shared automatically between server and client — no manual synchronization.\n- **🔌 Your database, your rules** — The library defines TypeScript interfaces (`IUserRepository`, `IEmailProvider`). You implement them with your ORM of choice (Prisma, TypeORM, Drizzle). No vendor lock-in, no hidden database dependencies.\n- **🔒 Native crypto only** — All security-critical code (password hashing, MFA encryption, TOTP, token generation) runs on `node:crypto` — zero third-party crypto packages, so the most sensitive code paths carry no third-party supply-chain risk.\n- **⚡ Pay for what you use** — Features like MFA, sessions, OAuth, and platform admin are opt-in. When not configured, their controllers and services are never registered — zero overhead in your NestJS container.\n- **🏢 Multi-tenant ready** — Every operation is scoped by `tenantId`. Built for SaaS from day one, not bolted on as an afterthought.\n\n```\npnpm add @bymax-one/nest-auth\n```\n\n---\n\n## 🔥 Features\n\n### 🔐 Core Authentication\n\n- ✅ **Registration & Login** — Email/password with configurable validation\n- ✅ **JWT Access + Refresh Tokens** — Automatic rotation with grace window for concurrent requests\n- ✅ **Multi-Factor Authentication** — TOTP with QR code URI, recovery codes, and challenge flow\n- ✅ **OAuth 2.0** — Google out of the box, extensible via plugin interface\n- ✅ **Password Reset** — Token-based or OTP, configurable per deployment\n- ✅ **Email Verification** — OTP-based with configurable TTL\n\n### 🛡️ Security\n\n- ✅ **Zero External Crypto** — All cryptography via native `node:crypto` (scrypt, AES-256-GCM, HMAC-SHA1, TOTP)\n- ✅ **Brute-Force Protection** — Configurable rate limiting per email + tenant\n- ✅ **Session Management** — Track active sessions with FIFO eviction, and an `onNewSession` hook fired on every session created (alerting on it is yours to decide — see `sendNewSessionAlert`)\n- ✅ **HttpOnly Cookies** — Secure, SameSite, path-scoped refresh tokens by default\n- ✅ **Timing-Safe Comparisons** — All secret comparisons use `crypto.timingSafeEqual`\n- ✅ **JWT Revocation** — Instant access token revocation via Redis JTI blacklist\n- ✅ **Refresh-Token Reuse Detection** — Replaying a consumed token revokes that login's whole lineage, and only that lineage\n- ✅ **Bulk Access-Token Revocation** — A password reset advances a per-user token epoch, invalidating every outstanding access token in one write\n- ✅ **Absolute Session Lifetime** — Optional hard cap on how long one login can be extended by rotation\n- ✅ **Cross-Site Request Refusal** — Cookie-authenticated writes from an untrusted origin are rejected (matters under `SameSite=None`)\n- ✅ **Breached-Password Refusal** — Optional Have I Been Pwned check by k-anonymity range; the password never leaves the process\n- ✅ **Per-IP Rate Limiting** — Enforced by the library over Redis, so the limit holds across instances with no host wiring\n\n### 🏢 Multi-Tenant & Platform\n\n- ✅ **Tenant Isolation** — All operations scoped by `tenantId` with configurable resolver\n- ✅ **Platform Admin Auth** — Separate token context and role hierarchy for super-admins\n- ✅ **User Invitations** — Invite users with role assignment and configurable expiration\n- ✅ **Role-Based Access Control** — Hierarchical roles with `@Roles()` decorator\n\n### 🧩 Developer Experience\n\n- ✅ **Full-Stack TypeScript** — Strict types shared across server and client\n- ✅ **5 Subpath Exports** — Import only what you need, tree-shakeable\n- ✅ **Dynamic Module** — Configure everything via `registerAsync()`, sensible defaults included\n- ✅ **Interface-Driven** — Bring your own database and email provider\n- ✅ **No Passport Required** — Guards validate JWT natively via `@nestjs/jwt`\n\n---\n\n## 📦 Subpath Exports\n\nOne package, five entry points — import only what your app needs:\n\n| Subpath | Import | Purpose | Dependencies |\n| ----------- | ----------------------------- | ------------------------------------------- | :----------------: |\n| **Server** | `@bymax-one/nest-auth` | NestJS module, guards, decorators, services | NestJS 11, ioredis |\n| **Shared** | `@bymax-one/nest-auth/shared` | Types, constants, error codes | None |\n| **Client** | `@bymax-one/nest-auth/client` | Fetch-based auth client | None |\n| **React** | `@bymax-one/nest-auth/react` | Hooks & AuthProvider | React 19 |\n| **Next.js** | `@bymax-one/nest-auth/nextjs` | Proxy, route handlers, JWT helpers | Next.js 16 |\n\n```\nshared (zero deps)\n ↗ ↖\nserver client\n ↑\n react\n ↑\n nextjs\n```\n\n---\n\n> [!TIP]\n> Prefer to learn from a working app? See the [nest-auth-example](https://github.com/bymaxone/nest-auth-example) — a full NestJS + Next.js project wired with this library.\n\n## 🚀 Quick Start\n\n### 1. Install\n\n```bash\n# Using pnpm (recommended)\npnpm add @bymax-one/nest-auth\n\n# Using npm\nnpm install @bymax-one/nest-auth\n\n# Using yarn\nyarn add @bymax-one/nest-auth\n```\n\n> [!IMPORTANT]\n> You must also install the required **peer dependencies** for the subpaths you use:\n\n```bash\n# Server subpath (required)\npnpm add @nestjs/common @nestjs/core @nestjs/jwt @nestjs/throttler @nestjs/websockets ioredis class-validator class-transformer reflect-metadata\n\n# React subpath (optional)\npnpm add react\n\n# Next.js subpath (optional)\npnpm add next react server-only\n```\n\n> [!NOTE]\n> `server-only` is what makes importing the Next.js JWT helper from a Client Component a\n> **build error**. That module receives the HS256 secret, and a secret in a client chunk is a\n> secret published to every visitor — with nothing downstream to notice. It is a marker package\n> with no runtime behaviour, and Next.js's own documentation prescribes it for exactly this.\n\n> [!IMPORTANT]\n> Requires `@nestjs/throttler >= 6.0.0` for `AUTH_THROTTLE_CONFIGS` decorators to be honored.\n\n### 2. Implement the Repository Interface\n\nThe package defines **what** it needs — your app provides **how**. The consumer maps the abstract `AuthUser` fields onto its own database schema (column names, indexes, soft-delete columns are entirely up to you). The only invariant is that `passwordHash` MUST be persisted exactly as supplied by the library — it is the output of `node:crypto` scrypt and re-hashing or transforming it will break login.\n\n```typescript\n// user.repository.ts\nimport { Injectable } from '@nestjs/common'\nimport type {\n AuthUser,\n CreateUserData,\n CreateWithOAuthData,\n FindUserByEmailParams,\n FindUserByOAuthIdParams,\n IUserRepository,\n LinkOAuthParams,\n TenantScopedUserRef,\n UpdateEmailParams,\n UpdateEmailVerifiedParams,\n UpdateMfaParams,\n UpdatePasswordParams,\n UpdateStatusParams\n} from '@bymax-one/nest-auth'\nimport { PrismaService } from './prisma.service'\n\n@Injectable()\nexport class PrismaUserRepository implements IUserRepository {\n constructor(private readonly prisma: PrismaService) {}\n\n async findById({ id, tenantId }: TenantScopedUserRef): PromiseClick here to reset your password.
`\n })\n }\n\n async sendPasswordResetOtp(\n _tenantId: string,\n email: string,\n otp: string,\n _locale?: string\n ): PromiseYour code is ${otp}. It expires in 10 minutes.
`\n })\n }\n\n async sendEmailVerificationOtp(\n _tenantId: string,\n email: string,\n otp: string,\n _locale?: string\n ): PromiseYour verification code is ${otp}.
`\n })\n }\n\n // The library does NOT await the three MFA notices — by the time one is sent the factor is\n // already enabled or removed, so a bounced notice must not answer the caller with an error for\n // an operation that succeeded. The consequence is here: an inline send like this one can be\n // lost to a process shutdown or a serverless freeze arriving between the response and the send\n // completing. Where these alerts matter — the administrative reset most of all, since it is what\n // makes a support-desk takeover detectable — enqueue durably and resolve instead of sending\n // inline. Awaiting would not fix it either: a freeze mid-await loses the notice AND the response.\n async sendMfaEnabledNotification(\n _tenantId: string,\n email: string,\n _locale?: string\n ): PromiseTwo-factor authentication has been enabled. If this was not you, contact support immediately.
'\n })\n }\n\n async sendMfaDisabledNotification(\n _tenantId: string,\n email: string,\n _locale?: string\n ): PromiseTwo-factor authentication has been disabled. If this was not you, contact support immediately.
'\n })\n }\n\n async sendNewSessionAlert(\n _tenantId: string,\n email: string,\n sessionInfo: SessionAlertInfo,\n _locale?: string\n ): PromiseNew session detected:
\n${escapeHtml(inviteData.inviterName)} invited you to join\n ${escapeHtml(inviteData.tenantName)}.
\n \nThis link expires on ${inviteData.expiresAt.toUTCString()}.
\n `\n })\n }\n}\n```\n\nWire it via `extraProviders` alongside the user repository:\n\n```typescript\nimport { BYMAX_AUTH_EMAIL_PROVIDER } from '@bymax-one/nest-auth'\n\nextraProviders: [{ provide: BYMAX_AUTH_EMAIL_PROVIDER, useClass: ResendEmailProvider }]\n```\n\n### 4. Register the Module\n\nThe user repository and Redis client are provided via NestJS dependency injection tokens — not as direct config fields. This follows the [NestJS custom providers pattern](https://docs.nestjs.com/fundamentals/custom-providers) and ensures the DI container manages all dependencies correctly.\n\n```typescript\n// app.module.ts\nimport { Module } from '@nestjs/common'\nimport {\n BymaxAuthModule,\n BYMAX_AUTH_USER_REPOSITORY,\n BYMAX_AUTH_REDIS_CLIENT\n} from '@bymax-one/nest-auth'\n\n@Module({\n imports: [\n BymaxAuthModule.registerAsync({\n imports: [ConfigModule, DatabaseModule, RedisModule],\n useFactory: (config: ConfigService) => ({\n jwt: {\n secret: config.get('JWT_SECRET'), // min 32 chars, high entropy\n accessExpiresIn: '15m',\n refreshExpiresInDays: 7\n },\n tokenDelivery: 'cookie', // 'cookie' | 'bearer' | 'both'\n // Required while the limiter is on, and neither value can be a default:\n // 'peer' behind a proxy reads the proxy's address for every request, and\n // 'trusted-proxy' without one trusts a header the client can forge.\n rateLimit: { clientIpSource: 'trusted-proxy' }, // 'peer' | 'trusted-proxy'\n roles: {\n hierarchy: {\n admin: ['manager', 'user'],\n manager: ['user'],\n user: []\n }\n }\n }),\n inject: [ConfigService],\n extraProviders: [\n {\n provide: BYMAX_AUTH_USER_REPOSITORY,\n useClass: PrismaUserRepository\n },\n {\n provide: BYMAX_AUTH_REDIS_CLIENT,\n useFactory: (redis: RedisService) => redis.client,\n inject: [RedisService]\n }\n ]\n })\n ]\n})\nexport class AppModule {}\n```\n\n### 5. Protect Routes\n\n```typescript\n// users.controller.ts\nimport { Controller, Get, UseGuards } from '@nestjs/common'\nimport { JwtAuthGuard, RolesGuard, Roles, CurrentUser } from '@bymax-one/nest-auth'\n// `import type` is required for a type used in a decorated signature: with\n// `emitDecoratorMetadata` and `isolatedModules`, a value import would be emitted\n// into the metadata and fail to erase (TS1272).\nimport type { DashboardJwtPayload } from '@bymax-one/nest-auth'\n\n@Controller('users')\n@UseGuards(JwtAuthGuard, RolesGuard)\nexport class UsersController {\n @Get('me')\n getProfile(@CurrentUser() user: DashboardJwtPayload) {\n return { id: user.sub, role: user.role, tenantId: user.tenantId }\n }\n\n @Get()\n @Roles('admin')\n listUsers() {\n // Only accessible by admins (and above in hierarchy)\n }\n}\n```\n\n### 6. Frontend Integration (React)\n\nBuild an `AuthClient` once with `createAuthClient`, then hand it to\n`AuthProvider`. Hooks (`useSession`, `useAuth`, `useAuthStatus`) read\nthe context populated by the provider.\n\n```tsx\n// app/providers.tsx\n'use client'\nimport { AuthProvider } from '@bymax-one/nest-auth/react'\nimport { createAuthClient } from '@bymax-one/nest-auth/client'\n\nconst authClient = createAuthClient({\n // Same-origin: a relative base sends every call through the Next.js\n // proxy routes — `'/api'` plus the default `routePrefix` composes\n // `/api/auth/*`. Use an absolute origin for a cross-origin API.\n baseUrl: '/api'\n})\n\nexport function Providers({ children }: { children: React.ReactNode }) {\n return (\nWelcome, {user.name}!
\n \n\n ![\"NestJS\"](\"https://img.shields.io/badge/NestJS-11-E0234E?style=flat-square&logo=nestjs&logoColor=white\"){kind=icon}
![\"React\"](\"https://img.shields.io/badge/React-19-61DAFB?style=flat-square&logo=react&logoColor=black\"){kind=icon}
![\"Next.js\"](\"https://img.shields.io/badge/Next.js-16-000000?style=flat-square&logo=next.js&logoColor=white\"){kind=icon}
![\"Redis\"](\"https://img.shields.io/badge/Redis-7%2B-DC382D?style=flat-square&logo=redis&logoColor=white\"){kind=icon}
![\"Jest\"](\"https://img.shields.io/badge/Jest-29-C21325?style=flat-square&logo=jest&logoColor=white\"){kind=icon}