@ackplus/nest-auth

Full-featured authentication module for NestJS. Sessions, MFA, OAuth, passwordless, multi-tenancy, RBAC, audit logging, and an embedded admin console — all type-safe end to end.

📚 Full documentation: ack-solutions.github.io/nest-auth

Why

Modern auth has a long checklist: email + password, OAuth, MFA, refresh-token rotation, RBAC, multi-tenancy, audit logs, an admin console. Most teams glue together five libraries (and own the integration risk) or buy a hosted vendor (and lose data ownership). @ackplus/nest-auth picks a third path: a single, modular library you install in your own NestJS app, backed by your own database.

Install

pnpm add @ackplus/nest-auth @ackplus/nest-auth-contracts

Required peer dependencies:

pnpm add @nestjs/common @nestjs/core @nestjs/typeorm @nestjs/swagger \
  @nestjs/event-emitter @nestjs/platform-express \
  typeorm class-validator class-transformer reflect-metadata rxjs

Optional, only if you enable the matching feature:

| Feature | Add | | --- | --- | | Cookie-mode sessions | cookie-parser | | Redis sessions | ioredis | | Google OAuth | google-auth-library | | Facebook OAuth | fb | | Apple OAuth | apple-auth | | Rate limiting | @nestjs/throttler |

Full install guide →

What's included

| Capability | Notes | | --- | --- | | 9 sign-in methods | Email + password · phone + password · passwordless OTP · magic link · Google · Facebook · Apple · GitHub · API keys + custom OAuth providers | | MFA | TOTP · email OTP · SMS OTP · recovery codes · trusted-device tokens | | Sessions | Database (default), Redis, or in-memory · auto-refresh · refresh-token rotation · password-hash-prefix invalidation | | Multi-tenancy | disabled / shared / isolated modes · tenant-aware decorators · per-request context | | RBAC | Roles + permissions per guard namespace (web, api, mobile) · external IDP friendly | | Embedded admin console | Built-in React UI for users, roles, permissions, tenants, API keys | | Hooks & events | Every lifecycle moment is overridable; full EventEmitter2 integration | | Audit logging | Structured event hook for compliance | | OpenAPI | Auto-generated @nestjs/swagger spec for every endpoint |

Minimal example

import { Module } from '@nestjs/common';
import { TypeOrmModule } from '@nestjs/typeorm';
import { EventEmitterModule } from '@nestjs/event-emitter';
import { NestAuthModule, NestAuthEntities } from '@ackplus/nest-auth';

@Module({
  imports: [
    EventEmitterModule.forRoot(),
    TypeOrmModule.forRoot({
      type: 'postgres',
      url: process.env.DATABASE_URL,
      entities: [...NestAuthEntities],
      synchronize: process.env.NODE_ENV === 'development',
    }),
    TypeOrmModule.forFeature([...NestAuthEntities]),

    NestAuthModule.forRoot({
      appName: 'My App',
      session: { jwt: { secret: process.env.JWT_SECRET! } },
      // emailAuth: { enabled: true },        // default
      // google: { clientId, clientSecret },  // opt-in OAuth
      // mfa: { enabled: true, required: true },
      // tenant: { enabled: true, mode: TenantModeEnum.SHARED },
    }),
  ],
})
export class AppModule {}

That's it — you immediately get POST /auth/signup, POST /auth/login, /auth/refresh-token, password-reset, MFA, OAuth callbacks, and the rest of the API. Wire EventEmitterModule.forRoot(), cookie-parser, and the AuthExceptionFilter from the setup checklist and ship.

Documentation

| Section | What's there | | --- | --- | | Getting Started | Install, database setup (3 paths), env vars, quickstart for backend / React / Next.js / vanilla | | Core Concepts | Sessions, user model, multi-tenancy, RBAC, MFA, events, audit | | Authentication | One page per sign-in method | | Backend Reference | Module config, entities, decorators, guards, services, hooks, events, error codes, admin console | | Production | Email/SMS wiring, JWT customization, scaling, CORS & security, testing | | Recipes | 20 copy-paste solutions — referral codes, custom OAuth, tenant switcher, etc. | | API Reference | Auto-generated REST + TypeScript types | | FAQ & Troubleshooting | Error codes → likely cause → fix |

Companion packages

| Package | Use when | | --- | --- | | @ackplus/nest-auth-client | Vanilla JS / Vue / Angular / Svelte / React Native client | | @ackplus/nest-auth-react | React provider, hooks, guards, and Next.js App Router helpers | | @ackplus/nest-auth-contracts | Shared TS types — consumed by all three |

All four packages release together with the same version number. Pin them all to the same version.

Links

• 📚 Documentation
• 💬 Issue Tracker
• 📦 GitHub Repository

License

MIT