Philosophy

Five principles drive every API decision in this library.

1. Modular, hook-driven

Every important moment in the auth lifecycle is either a config-time hook or an emitted event. You never have to monkey-patch the library to add a referral-code field, send a custom welcome email, or sync roles from an external IDP — there's already a hook or event for it.

See Events & Hooks for the full extension surface.

2. Multi-tenant first

Multi-tenancy is built into the core, not bolted on. The tenant config has three modes — disabled, shared, isolated — and the same APIs work in all three. If you start single-tenant and grow into multi-tenant, you flip a flag rather than re-architect.

See Multi-tenancy.

3. Type-safe end to end

The shared @ackplus/nest-auth-contracts package defines every request, response, enum, and entity interface. Backend, JS client, and React layer all import from the same source — so when you change a DTO on the server, the client breaks at compile time, not at runtime.

4. The library does auth — your app does users

NestAuthUser only stores auth fields: email, phone, password hash, MFA state. Your app's user (call it AppUser) holds business data — name, avatar, billing tier, referral relations — and links to NestAuthUser via an authUserId foreign key. This separation keeps library upgrades safe and your domain model yours.

See User Model for the canonical pattern.

5. Production-ready defaults

Argon2id password hashing, refresh-token rotation, password-hash-prefix in JWT for instant invalidation on password change, sensible cookie flags, secret-rotation-friendly token signing, and a production checklist that covers HTTPS, CORS, CSRF, and rate limits. Defaults are safe — escape hatches are documented.