@ambushsoftworks/nestjs-auth-graphql 0.6.5 → 0.7.2

package/README.md

@@ -1,1560 +1,859 @@
 # @ambushsoftworks/nestjs-auth-graphql
 
-Production-grade authentication package for NestJS with GraphQL, extracted from the Lift fitness app.
+Production-grade authentication module for NestJS GraphQL + REST APIs. JWT, cookie auth, multi-tenancy, realm-based identity isolation, OAuth, email verification, and more -- with zero database coupling.
+
+## Table of Contents
+
+- [Design Principles](#design-principles)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Why BaseAuthResolver?](#why-baseauthresolver)
+- [Features](#features)
+  - [Cookie Authentication](#cookie-authentication)
+  - [Multi-Tenancy](#multi-tenancy)
+  - [Realm-Based Identity Isolation](#realm-based-identity-isolation)
+  - [API Key Authentication](#api-key-authentication)
+  - [Email System](#email-system)
+  - [Verification Modes](#verification-modes)
+  - [OAuth](#oauth)
+  - [Brute Force Protection](#brute-force-protection)
+  - [Password Policy](#password-policy)
+  - [Lifecycle Hooks](#lifecycle-hooks)
+  - [JWT Validation Modes](#jwt-validation-modes)
+  - [JWT Payload Factory](#jwt-payload-factory)
+- [Configuration Reference](#configuration-reference)
+  - [Required Options](#required-options)
+  - [Common Options](#common-options)
+  - [Feature Flags](#feature-flags-features)
+  - [Security Secrets](#security-secrets)
+  - [Cookie Options](#cookie-options-cookie)
+  - [CSRF Options](#csrf-options-csrf)
+  - [Composable Email](#composable-email-email)
+  - [Verification Options](#verification-options-verification)
+  - [Optional Instance Options](#optional-instance-options)
+- [Decorators](#decorators)
+- [Guards](#guards)
+- [Utilities](#utilities)
+- [Security Features](#security-features)
+- [License](#license)
 
 ---
 
-## 🚨 BREAKING CHANGES in v0.2.0
+## Design Principles
 
-**Version 0.2.0 introduces a complete architectural refactor.** If upgrading from v0.1.x, you **MUST** follow the migration guide.
-
-**Key Changes**:
-- Package no longer exports concrete `AuthResolver` - you must create your own extending `BaseAuthResolver<T>`
-- All entities/DTOs are now interfaces (IAuthUser, IAuthSignupInput, etc.) - you define GraphQL types
-- Package owns canonical enums (AuthProvider, UserStatus) - consumers use these in code
-
-**Migration Time**: 2-4 hours | **Read**: [MIGRATION.md](./MIGRATION.md) | **Quick Start**: [QUICK-START.md](./QUICK-START.md)
-
-**Why?** v0.2.0 eliminates GraphQL schema conflicts, provides full control over types, and works with any database/ORM across diverse projects.
-
----
-
-## Features
-
-- **JWT Authentication**: Secure token-based authentication with automatic refresh
-- **OAuth 2.0**: Google and Facebook social login
-- **Email Verification**: 6-digit PIN codes via SendGrid with rate limiting
-- **SMS Verification**: Phone number verification via Twilio
-- **Password Reset**: 6-digit verification codes with email enumeration protection
-- **Biometric Authentication**: Face ID, Touch ID, fingerprint support
-- **Brute Force Protection**: Account lockout after failed login attempts
-- **Account Linking**: Link/unlink social accounts to existing accounts
-- **Security**: HMAC-SHA256 token hashing, AES-256-GCM encryption, constant-time comparison
-- **Type Safety**: Full TypeScript support with strict mode
-- **Testing**: 246+ tests from production codebase
+- **Interface-driven persistence** -- All storage is behind interfaces (`IUserRepository`, `IRefreshTokenRepository`, `ITenantRepository`, etc.). Bring your own database.
+- **Instance-based DI** -- Repositories and services are injected as instances via `useFactory`, not as classes.
+- **Consumer owns GraphQL types** -- The package provides `BaseAuthResolver<T>` with `protected perform*()` methods. You create your own resolver with `@Mutation()` decorators (see [Why BaseAuthResolver?](#why-baseauthresolver)).
+- **Guards are exported, not auto-registered** -- You register guards in your own `APP_GUARD` chain to control execution order.
+- **NoOp fallbacks** -- Every optional dependency has a no-op implementation, so the module works with minimal config.
 
 ## Installation
 
 ```bash
-npm install @yourorg/nestjs-auth-graphql
+npm install @ambushsoftworks/nestjs-auth-graphql
 ```
 
 ### Peer Dependencies
 
 ```bash
-npm install @nestjs/common @nestjs/core @nestjs/config @nestjs/graphql @nestjs/jwt @nestjs/passport @nestjs/throttler graphql passport passport-jwt reflect-metadata rxjs
+npm install @nestjs/common @nestjs/core @nestjs/graphql @nestjs/jwt @nestjs/passport @nestjs/throttler graphql passport passport-jwt reflect-metadata rxjs
 ```
 
+`resend` is an optional peer dependency -- install it only if using the Resend email sender.
+
 ## Quick Start
 
-### 1. Implement Required Repositories
+Minimal setup: JWT authentication with email/password login.
 
-The package uses interfaces for data persistence - you must implement these for your database (Prisma, TypeORM, etc.):
+### 1. Implement the required repositories
 
 ```typescript
-import { IUserRepository, IRefreshTokenRepository, IAuthUser } from '@yourorg/nestjs-auth-graphql';
+// users.repository.ts
 import { Injectable } from '@nestjs/common';
-import { PrismaService } from './prisma.service';
+import { IUserRepositoryCore, CreateUserData } from '@ambushsoftworks/nestjs-auth-graphql';
 
 @Injectable()
-export class PrismaUserRepository implements IUserRepository {
-  constructor(private prisma: PrismaService) {}
-
-  async findById(id: string): Promise<IAuthUser | null> {
-    return this.prisma.user.findUnique({ where: { id } });
-  }
-
-  async findByEmail(email: string): Promise<IAuthUser | null> {
-    return this.prisma.user.findUnique({ where: { email } });
-  }
-
-  async create(data: any): Promise<IAuthUser> {
-    return this.prisma.user.create({ data });
-  }
-
-  // Implement other required methods...
+export class UsersRepository implements IUserRepositoryCore<User> {
+  async findByEmail(email: string): Promise<User | null> { /* ... */ }
+  async findById(id: string): Promise<User | null> { /* ... */ }
+  async create(data: CreateUserData): Promise<User> { /* ... */ }
+  // ... implement remaining IUserRepositoryCore methods
 }
+```
 
-@Injectable()
-export class PrismaRefreshTokenRepository implements IRefreshTokenRepository {
-  constructor(private prisma: PrismaService) {}
-
-  async create(data: any): Promise<any> {
-    return this.prisma.refreshToken.create({ data });
-  }
+```typescript
+// refresh-token.repository.ts
+import { Injectable } from '@nestjs/common';
+import { IRefreshTokenRepository } from '@ambushsoftworks/nestjs-auth-graphql';
 
-  // Implement other required methods...
+@Injectable()
+export class RefreshTokenRepository implements IRefreshTokenRepository {
+  async create(data: {
+    userId: string;
+    token: string;
+    hashedToken: string;
+    expiresAt: Date;
+    deviceInfo?: string | null;
+  }): Promise<any> { /* ... */ }
+  async findByHashedToken(hashedToken: string): Promise<any | null> { /* ... */ }
+  async deleteByUserId(userId: string): Promise<number> { /* ... */ }
+  // ... implement remaining methods
 }
 ```
 
-### 2. Configure the Auth Module
-
-**IMPORTANT**: This package uses instance-based dependency injection. You must register your repository/service classes in the `providers` array and inject instances into the `useFactory` function.
+### 2. Register the module
 
 ```typescript
 import { Module } from '@nestjs/common';
-import { AuthModule } from '@yourorg/nestjs-auth-graphql';
-import { ConfigModule, ConfigService } from '@nestjs/config';
-import { PrismaModule } from './prisma/prisma.module';
-import { PrismaUserRepository } from './repositories/prisma-user.repository';
-import { PrismaRefreshTokenRepository } from './repositories/prisma-refresh-token.repository';
+import { ConfigService } from '@nestjs/config';
+import { AuthModule } from '@ambushsoftworks/nestjs-auth-graphql';
 
 @Module({
   imports: [
-    ConfigModule.forRoot(),
-    PrismaModule,  // Import module that provides repositories
     AuthModule.forRootAsync({
-      imports: [PrismaModule, ConfigModule],
-      inject: [
-        PrismaUserRepository,           // Inject repository instances
-        PrismaRefreshTokenRepository,
-        ConfigService,
-      ],
-      useFactory: (
-        usersRepo: PrismaUserRepository,
-        tokenRepo: PrismaRefreshTokenRepository,
-        config: ConfigService,
-      ) => ({
-        // Pass instances directly (not classes)
+      imports: [ConfigModule, DatabaseModule],
+      inject: [UsersRepository, RefreshTokenRepository, ConfigService],
+      useFactory: (usersRepo, tokenRepo, config) => ({
         userRepositoryInstance: usersRepo,
         refreshTokenRepositoryInstance: tokenRepo,
-
-        // JWT configuration (required)
         jwtSecret: config.get('JWT_SECRET'),
-        jwtExpiresIn: '15m',  // Default: '15m'
-        refreshTokenExpiresIn: '30d',  // Default: '30d'
-
-        // Feature flags
-        features: {
-          emailVerification: true,
-          smsVerification: true,
-          googleOAuth: true,
-          facebookOAuth: true,
-          biometricAuth: true,
-          bruteForceProtection: true,
-        },
-
-        // OAuth configuration
-        oauth: {
-          google: {
-            clientId: config.get('GOOGLE_CLIENT_ID'),
-            clientSecret: config.get('GOOGLE_CLIENT_SECRET'),
-            callbackUrl: config.get('GOOGLE_CALLBACK_URL'),
-          },
-          facebook: {
-            clientId: config.get('FACEBOOK_CLIENT_ID'),
-            clientSecret: config.get('FACEBOOK_CLIENT_SECRET'),
-            callbackUrl: config.get('FACEBOOK_CALLBACK_URL'),
-          },
-        },
       }),
     }),
   ],
-  providers: [
-    // Register repository classes so NestJS can inject them
-    PrismaUserRepository,
-    PrismaRefreshTokenRepository,
-  ],
+  providers: [UsersRepository, RefreshTokenRepository],
 })
 export class AppModule {}
 ```
 
-**Note**: You must register your repository classes in the `providers` array of the module where you call `forRootAsync()`. NestJS will inject instances of these repositories into the factory function.
-
-### 3. Create Your Auth Resolver
-
-**CRITICAL**: Due to TypeScript decorator metadata limitations, you MUST create your own resolver extending `BaseAuthResolver`. The package provides business logic, but YOU define GraphQL types.
-
-Create `src/auth/auth.resolver.ts`:
+### 3. Create your auth resolver
 
 ```typescript
-import { Resolver, Mutation, Args, Context, Query } from '@nestjs/graphql';
-import { UseGuards } from '@nestjs/common';
-import { Throttle } from '@nestjs/throttler';
+import { Resolver, Mutation, Args, Context } from '@nestjs/graphql';
+import { Inject } from '@nestjs/common';
 import {
   BaseAuthResolver,
-  JwtAuthGuard,
-  CurrentUser
-} from '@yourorg/nestjs-auth-graphql';
-import { User } from '../users/entities/user.entity';  // Your User @ObjectType
-import { AuthResponse } from './dto/auth-response.dto';  // Your AuthResponse @ObjectType
-import { LoginInput } from './dto/login.input';  // Your @InputType classes
-import { SignupInput } from './dto/signup.input';
-import { RefreshTokenInput } from './dto/refresh-token.input';
-import { LogoutInput } from './dto/logout.input';
-import { LogoutResponse, LogoutAllResponse } from './dto/logout-response.dto';
-// ... import other DTOs for email/SMS verification, etc.
-
-/**
- * Your app's auth resolver - extends BaseAuthResolver for business logic
- */
+  CurrentUser,
+  AuthService,
+  BruteForceProtectionService,
+  USER_REPOSITORY,
+  AUTH_LOGGER,
+} from '@ambushsoftworks/nestjs-auth-graphql';
+
 @Resolver()
 export class AuthResolver extends BaseAuthResolver<User> {
-  // Core auth mutations (required - override to provide GraphQL types)
+  constructor(
+    authService: AuthService,
+    bruteForceProtection: BruteForceProtectionService,
+    @Inject(USER_REPOSITORY) userRepository: any,
+    @Inject(AUTH_LOGGER) authLogger: any,
+  ) {
+    super(authService, bruteForceProtection, userRepository, authLogger);
+  }
 
   @Mutation(() => AuthResponse)
-  @Throttle({ default: { limit: 5, ttl: 60000 } })
-  async signup(@Args('input') input: SignupInput): Promise<AuthResponse> {
-    return this.performSignup(input) as Promise<AuthResponse>;
+  async signup(@Args('input') input: SignupInput, @Context() ctx: any) {
+    return this.performSignup(input, ctx);
   }
 
   @Mutation(() => AuthResponse)
-  @Throttle({ default: { limit: 5, ttl: 60000 } })
-  async login(
-    @Args('input') input: LoginInput,
-    @Context() context: any,
-  ): Promise<AuthResponse> {
-    return this.performLogin(input, context) as Promise<AuthResponse>;
+  async login(@Args('input') input: LoginInput, @Context() ctx: any) {
+    return this.performLogin(input, ctx);
   }
 
   @Mutation(() => AuthResponse)
-  @Throttle({ default: { limit: 10, ttl: 60000 } })
-  async refreshToken(@Args('input') input: RefreshTokenInput): Promise<AuthResponse> {
-    return this.performRefreshToken(input) as Promise<AuthResponse>;
+  async refreshToken(@Args('input') input: RefreshTokenInput, @Context() ctx: any) {
+    return this.performRefreshToken(input, ctx);
   }
 
   @Mutation(() => LogoutResponse)
-  @UseGuards(JwtAuthGuard)
-  @Throttle({ default: { limit: 10, ttl: 60000 } })
-  async logout(
-    @Args('input') input: LogoutInput,
-    @CurrentUser() user: User,
-  ): Promise<LogoutResponse> {
-    return this.performLogout(input, user) as Promise<LogoutResponse>;
-  }
-
-  @Mutation(() => LogoutAllResponse)
-  @UseGuards(JwtAuthGuard)
-  @Throttle({ default: { limit: 5, ttl: 60000 } })
-  async logoutAll(@CurrentUser() user: User): Promise<LogoutAllResponse> {
-    return this.performLogoutAll(user) as Promise<LogoutAllResponse>;
+  async logout(@Args('input') input: LogoutInput, @CurrentUser() user: User) {
+    return this.performLogout(input, user);
   }
-
-  // Add overrides for other mutations: verifyEmail, sendPhoneVerification, etc.
-  // See full example in Lift backend: src/auth/lift-auth.resolver.ts
 }
 ```
 
-**Why this pattern?**
-- TypeScript decorator metadata is NOT preserved when importing classes from compiled npm packages
-- This causes "Cannot determine GraphQL output type" errors at runtime
-- Solution: Package provides `protected perform*()` methods, you add GraphQL decorators
-
-**Register your resolver:**
+### 4. Set up the guard chain
 
 ```typescript
+import { APP_GUARD } from '@nestjs/core';
+import { createAuthGuard } from '@ambushsoftworks/nestjs-auth-graphql';
+
 @Module({
-  imports: [AuthModule.forRootAsync(...)],
   providers: [
-    AuthResolver,  // Add your resolver here
-    PrismaUserRepository,
-    PrismaRefreshTokenRepository,
+    {
+      provide: APP_GUARD,
+      useClass: createAuthGuard(['jwt'], { allowPublic: true }),
+    },
   ],
 })
 export class AppModule {}
 ```
 
-### 4. Configure Input Validation
-
-**IMPORTANT**: This package includes input validation using `class-validator` decorators on all input DTOs. You **must** enable NestJS's `ValidationPipe` globally for automatic validation.
-
-Add this to your `main.ts`:
+Mark public routes with `@Public()`:
 
 ```typescript
-import { NestFactory } from '@nestjs/core';
-import { ValidationPipe } from '@nestjs/common';
-import { AppModule } from './app.module';
-
-async function bootstrap() {
-  const app = await NestFactory.create(AppModule);
-
-  // Enable validation globally
-  app.useGlobalPipes(
-    new ValidationPipe({
-      whitelist: true,           // Strip properties not in DTO
-      forbidNonWhitelisted: true, // Throw error if extra properties
-      transform: true,            // Auto-transform payloads to DTO instances
-      transformOptions: {
-        enableImplicitConversion: true, // Auto-convert primitive types
-      },
-    }),
-  );
+import { Public } from '@ambushsoftworks/nestjs-auth-graphql';
 
-  await app.listen(3000);
-}
-bootstrap();
+@Public()
+@Mutation(() => AuthResponse)
+async login() { /* ... */ }
 ```
 
-**What gets validated:**
+## Why BaseAuthResolver?
 
-The package validates all input fields with appropriate decorators:
+TypeScript decorator metadata is not preserved when importing from compiled npm packages. If the package exported a resolver with `@Mutation(() => AuthResponse)`, NestJS would throw "Cannot determine GraphQL output type" at runtime.
 
-- **Email fields**: `@IsEmail()` - Validates proper email format
-- **Password fields** (signup): `@MinLength(8)`, `@MaxLength(100)`, `@Matches()` - Enforces strong passwords with uppercase, lowercase, number, and special character
-- **Password fields** (login): `@IsNotEmpty()` - Validates presence only (no strength check for existing passwords)
-- **Verification codes**: `@Matches(/^\d{6}$/)` - Validates 6-digit PIN codes
-- **Phone numbers**: `@Matches(/^\+[1-9]\d{1,14}$/)` - Validates E.164 international format (e.g., +14155552671)
-- **Tokens**: `@IsString()`, `@IsNotEmpty()` - Validates refresh tokens and OAuth tokens
-- **Device IDs**: `@IsUUID()` or `@IsString()` - Validates biometric device identifiers
-- **Provider names**: `@IsIn(['google', 'facebook', 'apple'])` - Validates OAuth provider names
+`BaseAuthResolver<T>` solves this by providing only business logic via `protected perform*()` methods. You add the GraphQL decorators in your own code, where metadata resolution works correctly.
 
-**Validation error responses:**
+When cookie auth is enabled, pass the GraphQL `context` so tokens are set as HttpOnly cookies. The response body will contain empty strings for `accessToken`/`refreshToken`.
 
-When validation fails, NestJS automatically returns a `400 Bad Request` with detailed error messages:
+### Available `perform*()` methods
 
-```json
-{
-  "statusCode": 400,
-  "message": [
-    "Please provide a valid email address",
-    "Password must be at least 8 characters",
-    "Password must contain uppercase, lowercase, number, and special character"
-  ],
-  "error": "Bad Request"
-}
-```
+**Authentication:**
 
-**Custom validation for your DTOs:**
+| Method | Purpose |
+|--------|---------|
+| `performSignup(input, context?)` | Create account |
+| `performLogin(input, context)` | Authenticate |
+| `performRefreshToken(input, context?)` | Rotate tokens |
+| `performLogout(input, user, context?)` | Invalidate token |
+| `performLogoutAll(user, context?)` | Invalidate all tokens |
+| `performGetCurrentUser(userId)` | Get current user |
 
-If you create your own input DTOs implementing the package interfaces (recommended for full type control), add `class-validator` decorators:
+**Verification:**
 
-```typescript
-import { InputType, Field } from '@nestjs/graphql';
-import { IsEmail, IsString, MinLength, Matches } from 'class-validator';
-import { IAuthSignupInput } from '@ambushsoftworks/nestjs-auth-graphql';
-
-@InputType()
-export class SignupInput implements IAuthSignupInput {
-  @Field()
-  @IsEmail({}, { message: 'Please provide a valid email address' })
-  email: string;
-
-  @Field()
-  @IsString()
-  @MinLength(12, { message: 'Password must be at least 12 characters' })
-  @Matches(/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[@$!%*?&])/, {
-    message: 'Password must contain uppercase, lowercase, number, and special character',
-  })
-  password: string;
-}
-```
+| Method | Purpose |
+|--------|---------|
+| `performVerifyEmail(input, context?)` | Email verification |
+| `performResendVerificationEmail(email)` | Resend verification email |
+| `performSendPhoneVerification(input, user)` | Send SMS verification code |
+| `performVerifyPhone(input, user)` | Verify phone with SMS code |
+| `performResendPhoneVerification(phoneNumber, user)` | Resend phone verification |
+| `performRemovePhoneNumber(user)` | Remove phone number from account |
+| `performPhoneVerificationStatus(user)` | Get phone verification status |
 
-**Note**: The package's default input classes (marked as `@deprecated`) already include validation decorators for backward compatibility. If using these, validation works automatically with `ValidationPipe` enabled.
+**Password:**
 
-## Configuration Options
+| Method | Purpose |
+|--------|---------|
+| `performRequestPasswordReset(input, context?)` | Send reset code/token |
+| `performResetPassword(input, context?)` | Reset password |
+| `performChangePassword(userId, current, new)` | Change password |
 
-### Required Options
+**Other:**
 
-- `userRepositoryInstance`: Instance of `IUserRepository` implementation
-- `refreshTokenRepositoryInstance`: Instance of `IRefreshTokenRepository` implementation
-- `jwtSecret`: Secret key for signing JWT tokens
+| Method | Purpose |
+|--------|---------|
+| `performCheckAccountLockStatus(email)` | Check brute force lock status |
+| `performCompleteFacebookSignUp(input)` | Facebook email fallback |
 
-### Optional Options
-
-- `emailServiceInstance`: Instance of `IEmailService` implementation (default: null)
-  - Use `SendGridEmailService` for production
-  - Use `NoOpEmailService` for development/testing
-- `smsServiceInstance`: Instance of `ISmsService` implementation (default: null)
-  - Use `TwilioSmsService` for production
-  - Use `NoOpSmsService` for development/testing
-- `lifecycleHooksInstance`: Instance of `IAuthLifecycleHooks` implementation (default: null)
-  - Add custom logic for signup, login, logout, etc.
-- `verificationRepositoryInstance`: Instance of `IVerificationRepository` implementation (default: NoOpVerificationRepository)
-- `bruteForceRepositoryInstance`: Instance of `IBruteForceRepository` implementation (default: NoOpBruteForceRepository)
-- `biometricRepositoryInstance`: Instance of `IBiometricRepository` implementation (default: NoOpBiometricRepository)
-- `jwtExpiresIn`: JWT access token expiration time (default: '15m')
-- `refreshTokenExpiresIn`: Refresh token expiration time (default: '30d')
-
-### Feature Flags
-
-Control which authentication features are enabled:
+---
 
-```typescript
-features: {
-  emailVerification: true,      // Email verification with PIN codes
-  smsVerification: true,         // SMS verification with Twilio
-  googleOAuth: true,             // Google Sign In
-  facebookOAuth: true,           // Facebook Login
-  biometricAuth: true,           // Face ID, Touch ID, fingerprint
-  bruteForceProtection: true,    // Account lockout after failed attempts
-}
-```
+## Features
 
-## Using Default Implementations
+### Cookie Authentication
 
-### SendGrid Email Service
+Enable `features.cookieAuth` to deliver tokens via HttpOnly cookies instead of response bodies.
 
 ```typescript
-import { SendGridEmailService } from '@yourorg/nestjs-auth-graphql';
-import { ConfigService } from '@nestjs/config';
-
-@Module({
-  imports: [
-    AuthModule.forRootAsync({
-      inject: [SendGridEmailService, ConfigService, /* ... */],
-      useFactory: (emailSvc, config, /* ... */) => ({
-        emailServiceInstance: emailSvc,
-        // ...
-      }),
-    }),
-  ],
-  providers: [
-    SendGridEmailService,  // Register in providers
-  ],
+AuthModule.forRootAsync({
+  useFactory: () => ({
+    // ...required options
+    features: { cookieAuth: true },
+    cookie: {
+      httpOnly: true,     // default
+      secure: true,       // default
+      sameSite: 'lax',    // default
+      domain: undefined,  // browser uses request domain
+      useHostPrefix: true, // prefix names with __Host- for enhanced security
+    },
+  }),
 })
-
-// Environment variables required:
-// SENDGRID_API_KEY=your_api_key
-// SENDGRID_FROM_EMAIL=noreply@yourapp.com
-// SENDGRID_FROM_NAME=Your App Name
 ```
 
-### Twilio SMS Service
+When `useHostPrefix: true`, cookie names become `__Host-access_token` and `__Host-refresh_token`. The module validates at startup that `secure` is true, `path` is `/`, and `domain` is unset (as required by the `__Host-` spec).
 
-```typescript
-import { TwilioSmsService } from '@yourorg/nestjs-auth-graphql';
+You can also customize cookie names and max ages -- see [Cookie Options](#cookie-options-cookie).
 
-@Module({
-  imports: [
-    AuthModule.forRootAsync({
-      inject: [TwilioSmsService, /* ... */],
-      useFactory: (smsSvc, /* ... */) => ({
-        smsServiceInstance: smsSvc,
-        // ...
-      }),
-    }),
-  ],
-  providers: [
-    TwilioSmsService,  // Register in providers
-  ],
-})
+The JWT strategy automatically reads from cookies first, then falls back to `Authorization: Bearer` headers.
 
-// Environment variables required:
-// TWILIO_ACCOUNT_SID=your_account_sid
-// TWILIO_AUTH_TOKEN=your_auth_token
-// TWILIO_PHONE_NUMBER=+1234567890
-```
+#### CSRF Protection
 
-### No-Op Services (Development/Testing)
+With cookie auth, register `CsrfGuard` to protect mutations. It validates that a configurable header (default: `X-Requested-With`) is present when the request is authenticated via cookies.
 
 ```typescript
-import { NoOpEmailService, NoOpSmsService } from '@yourorg/nestjs-auth-graphql';
+import { APP_GUARD } from '@nestjs/core';
+import { createAuthGuard, CsrfGuard } from '@ambushsoftworks/nestjs-auth-graphql';
 
 @Module({
-  imports: [
-    AuthModule.forRootAsync({
-      inject: [NoOpEmailService, NoOpSmsService, /* ... */],
-      useFactory: (emailSvc, smsSvc, /* ... */) => ({
-        emailServiceInstance: emailSvc,
-        smsServiceInstance: smsSvc,
-        // ...
-      }),
-    }),
-  ],
   providers: [
-    NoOpEmailService,  // These log operations instead of sending actual emails/SMS
-    NoOpSmsService,
+    { provide: APP_GUARD, useClass: createAuthGuard(['jwt'], { allowPublic: true }) },
+    { provide: APP_GUARD, useClass: CsrfGuard },
   ],
 })
 ```
 
-## Password Reset
-
-Secure password reset flow with 6-digit verification codes, rate limiting, and email enumeration protection.
-
-### Features
-
-- **6-Digit Verification Codes** - SMS/email verification pattern (not magic links)
-- **Email Enumeration Protection** - Generic success messages for all requests
-- **Rate Limiting** - 60-second cooldown between requests per user
-- **Password Strength Validation** - Configurable requirements (default: 8+ chars, uppercase, lowercase, number)
-- **Token Revocation** - All refresh tokens invalidated on password change
-- **Brute Force Protection** - Integration with account locking system
-- **OAuth User Protection** - Users authenticated via social login cannot reset passwords
-- **Security Logging** - Audit trail for all password reset activities
+Configure via `csrf` options:
 
-### Consumer Setup
-
-#### Step 1: Database Migration
-
-Add `passwordResetSentAt` field to your User model:
-
-**Prisma Example:**
-```prisma
-model User {
-  id                  String    @id @default(cuid())
-  email               String    @unique
-  passwordHash        String?
-
-  // Password reset rate limiting
-  passwordResetSentAt DateTime? // 60-second cooldown
-
-  // ... other fields
-}
-```
-
-**TypeORM Example:**
 ```typescript
-@Entity()
-export class User {
-  @PrimaryGeneratedColumn('uuid')
-  id: string;
-
-  @Column({ nullable: true })
-  passwordResetSentAt: Date;
-
-  // ... other fields
+csrf: {
+  headerName: 'X-Requested-With',  // default
+  requireInProduction: true,        // default
+  exemptOperations: ['refreshToken'], // skip CSRF for specific operations
 }
 ```
 
-#### Step 2: Configure Email Service
+The guard automatically skips when:
+- The request uses `Authorization` header (Bearer/API key)
+- The route has `@Public()`
+- Cookie auth is not enabled
+- `requireInProduction` is false and not in production
+- The GraphQL operation is in `exemptOperations`
 
-Ensure `SendGridEmailService` (or your custom email service) is configured:
+### Multi-Tenancy
+
+Enable tenant resolution and permission checking across requests.
 
 ```typescript
 AuthModule.forRootAsync({
-  imports: [ConfigModule],
-  inject: [ConfigService, UsersRepository, /* ... */],
-  useFactory: (config: ConfigService, usersRepo, /* ... */) => ({
-    // ... other options
-
-    emailServiceInstance: new SendGridEmailService(
-      config.get('SENDGRID_API_KEY'),
-    ),
-
-    // IMPORTANT: Set frontend URL for email templates
-    // (Not used in 6-digit code flow, but required by email service)
-    features: {
-      emailVerification: true,
-      // ... other features
-    },
+  useFactory: (tenantRepo, tenantExtractor) => ({
+    // ...required options
+    features: { multiTenancy: true },
+    tenantRepositoryInstance: tenantRepo,
+    tenantExtractorInstance: tenantExtractor,
   }),
-}),
-```
-
-**Environment Variable:**
-```bash
-FRONTEND_URL=https://yourapp.com  # Used in email branding
+})
 ```
 
-#### Step 3: Create GraphQL DTOs
+**Guard chain** (order matters):
 
-Create consumer-specific DTOs with GraphQL decorators:
-
-**`request-password-reset.input.ts`:**
 ```typescript
-import { InputType, Field } from '@nestjs/graphql';
-import { IAuthRequestPasswordResetInput } from '@ambushsoftworks/nestjs-auth-graphql';
-
-@InputType()
-export class RequestPasswordResetInput implements IAuthRequestPasswordResetInput {
-  @Field(() => String, {
-    description: 'User email address. Code sent if account exists.',
-  })
-  email: string;
-}
+providers: [
+  { provide: APP_GUARD, useClass: createAuthGuard(['jwt'], { allowPublic: true }) },
+  { provide: APP_GUARD, useClass: TenantGuard },
+  { provide: APP_GUARD, useClass: PermissionGuard },
+]
 ```
 
-**`reset-password.input.ts`:**
-```typescript
-import { InputType, Field } from '@nestjs/graphql';
-import { IAuthResetPasswordInput } from '@ambushsoftworks/nestjs-auth-graphql';
-
-@InputType()
-export class ResetPasswordInput implements IAuthResetPasswordInput {
-  @Field(() => String)
-  email: string;
-
-  @Field(() => String, { description: '6-digit verification code' })
-  code: string;
+**`ITenantRepository`** resolves whether a user has access to a tenant:
 
-  @Field(() => String, { description: 'New password (8+ chars, uppercase, lowercase, number)' })
-  newPassword: string;
-}
-```
-
-**`password-reset-response.dto.ts`:**
 ```typescript
-import { ObjectType, Field, Int } from '@nestjs/graphql';
-import { IAuthPasswordResetResponse } from '@ambushsoftworks/nestjs-auth-graphql';
-
-@ObjectType()
-export class PasswordResetResponse implements IAuthPasswordResetResponse {
-  @Field(() => Boolean)
-  success: boolean;
-
-  @Field(() => String)
-  message: string;
-
-  @Field(() => Int, { nullable: true })
-  retryAfterSeconds?: number;
-}
-```
-
-#### Step 4: Add Resolver Mutations
-
-Extend your custom resolver with password reset mutations:
-
-```typescript
-import { Resolver, Mutation, Args, Context } from '@nestjs/graphql';
-import { Throttle } from '@nestjs/throttler';
-import { BaseAuthResolver } from '@ambushsoftworks/nestjs-auth-graphql';
-import { RequestPasswordResetInput } from './dto/request-password-reset.input';
-import { ResetPasswordInput } from './dto/reset-password.input';
-import { PasswordResetResponse } from './dto/password-reset-response.dto';
-import { User } from './entities/user.entity';
-
-@Resolver()
-export class AppAuthResolver extends BaseAuthResolver<User> {
-  // ... other mutations (signup, login, etc.)
-
-  @Mutation(() => PasswordResetResponse, {
-    name: 'requestPasswordReset',
-    description: 'Request password reset code via email',
-  })
-  @Throttle({ default: { limit: 3, ttl: 60000 } }) // 3 requests per minute
-  async requestPasswordReset(
-    @Args('input') input: RequestPasswordResetInput,
-    @Context() context: any,
-  ): Promise<PasswordResetResponse> {
-    return this.performRequestPasswordReset(input, context) as Promise<PasswordResetResponse>;
-  }
-
-  @Mutation(() => PasswordResetResponse, {
-    name: 'resetPassword',
-    description: 'Reset password using verification code',
-  })
-  @Throttle({ default: { limit: 5, ttl: 900000 } }) // 5 attempts per 15 minutes
-  async resetPassword(
-    @Args('input') input: ResetPasswordInput,
-    @Context() context: any,
-  ): Promise<PasswordResetResponse> {
-    return this.performResetPassword(input, context) as Promise<PasswordResetResponse>;
+@Injectable()
+class TenantRepository implements ITenantRepository {
+  async resolveTenant(userId: string, tenantId: string): Promise<ITenantContext | null> {
+    const membership = await this.db.membership.find({ userId, tenantId });
+    if (!membership) return null;
+    return {
+      tenantId,
+      permissions: membership.role.permissions,
+      metadata: { accountId: membership.accountId },
+    };
   }
 }
 ```
 
-#### Step 5: Deploy & Test
+**`ITenantExtractor`** pulls the tenant ID from the request. Use the built-in `HeaderTenantExtractor` (reads `x-tenant-id` header) or implement your own:
 
-```bash
-# Run migration
-npx prisma migrate deploy
+```typescript
+import { HeaderTenantExtractor } from '@ambushsoftworks/nestjs-auth-graphql';
 
-# Start dev server
-npm run start:dev
+// Default: reads x-tenant-id header
+const extractor = new HeaderTenantExtractor();
 
-# Test GraphQL API
-curl -X POST http://localhost:3000/graphql \
-  -H "Content-Type: application/json" \
-  -d '{"query":"mutation { requestPasswordReset(input: {email: \"test@example.com\"}) { success message } }"}'
+// Custom header name
+const extractor = new HeaderTenantExtractor('x-org-id');
 ```
 
-### GraphQL Schema
-
-After setup, your schema will include:
+**Access tenant context** in resolvers:
 
-```graphql
-type Mutation {
-  requestPasswordReset(input: RequestPasswordResetInput!): PasswordResetResponse!
-  resetPassword(input: ResetPasswordInput!): PasswordResetResponse!
-}
-
-input RequestPasswordResetInput {
-  email: String!
-}
-
-input ResetPasswordInput {
-  email: String!
-  code: String!
-  newPassword: String!
-}
-
-type PasswordResetResponse {
-  success: Boolean!
-  message: String!
-  retryAfterSeconds: Int
+```typescript
+@Query(() => [Item])
+async items(@CurrentTenant() tenant: ITenantContext) {
+  return this.service.findByTenant(tenant.tenantId);
 }
 ```
 
-### Error Handling
-
-**Expected Exceptions:**
-
-| Exception | HTTP Status | When Thrown | Client Action |
-|-----------|-------------|-------------|---------------|
-| `PasswordResetRateLimitException` | 429 | < 60 seconds since last request | Display countdown: "Try again in X seconds" |
-| `WeakPasswordException` | 400 | Password doesn't meet requirements | Show validation errors to user |
-| `AccountLockedException` | 403 | Account locked due to brute force | Show "Account locked" message |
-| `UnauthorizedException` | 401 | Invalid/expired code | "Code is invalid or expired" |
-
-**Example Client-Side Error Handling (GraphQL):**
+**Skip tenant resolution** for routes that don't need it:
 
 ```typescript
-try {
-  const result = await client.mutate({
-    mutation: RESET_PASSWORD_MUTATION,
-    variables: { input: { email, code, newPassword } },
-  });
-
-  if (result.data?.resetPassword?.success) {
-    // Redirect to login
-    router.push('/login');
-  }
-} catch (error) {
-  if (error.extensions?.code === 'BAD_REQUEST') {
-    // WeakPasswordException
-    showErrors(error.extensions.errors); // ["Password must contain uppercase", ...]
-  } else if (error.extensions?.code === 'TOO_MANY_REQUESTS') {
-    // PasswordResetRateLimitException
-    const retryAfter = error.extensions.retryAfterSeconds;
-    showCountdown(retryAfter);
-  } else if (error.message.includes('invalid or expired')) {
-    // UnauthorizedException
-    showError('Code is invalid or expired');
-  }
-}
+@SkipTenant()
+@Query(() => User)
+async me(@CurrentUser() user: User) { /* ... */ }
 ```
 
-### Security Considerations
-
-1. **Never reveal whether email exists**
-   - Always return success message, even for non-existent emails
-   - Client cannot enumerate valid email addresses
-
-2. **Rate limiting is essential**
-   - Implement both per-user (60s) AND per-IP (via @Throttle) limits
-   - Prevents abuse and spam
-
-3. **Code security**
-   - Codes are HMAC-SHA256 hashed in database (never plain text)
-   - Constant-time comparison prevents timing attacks
-   - 15-minute expiry limits exposure window
-   - Single-use enforcement prevents replay attacks
-
-4. **Token revocation**
-   - All refresh tokens are invalidated on password change
-   - Forces re-authentication on all devices
-   - Prevents attacker from maintaining access
-
-5. **Email template security**
-   - Do NOT include personalized reset URLs with embedded tokens
-   - Use 6-digit codes displayed in email (user manually enters in app)
-   - Prevents phishing attacks via link manipulation
-
-### Lifecycle Hooks
-
-Optionally track password reset events:
+**Permission checking** with `@RequirePermissions()`:
 
 ```typescript
-export class AppAuthHooks implements IAuthLifecycleHooks<User> {
-  async onPasswordReset(user: User): Promise<void> {
-    // Send security alert to user's phone
-    await this.smsService.send(user.phoneNumber, 'Your password was just changed');
-
-    // Log to analytics
-    await this.analytics.track(user.id, 'password_reset_completed');
-
-    // Revoke API keys (if your app has them)
-    await this.apiKeyService.revokeAllKeys(user.id);
-  }
-}
+@RequirePermissions('clients:read')
+@Query(() => [Client])
+async clients(@CurrentTenant() tenant: ITenantContext) { /* ... */ }
 ```
 
-## GraphQL API
-
-The package provides a complete GraphQL API:
-
-### Mutations
-
-```graphql
-# Signup
-mutation Signup($input: SignupInput!) {
-  signup(signupInput: $input) {
-    accessToken
-    refreshToken
-    user { id email }
-  }
-}
+For resource-scoped permissions, combine with `@ResourceScope()` and provide an `IResourcePermissionRepository`:
 
-# Login
-mutation Login($input: LoginInput!) {
-  login(loginInput: $input) {
-    accessToken
-    refreshToken
-    user { id email }
-  }
-}
-
-# Refresh Token
-mutation RefreshToken($input: RefreshTokenInput!) {
-  refreshToken(refreshTokenInput: $input) {
-    accessToken
-    refreshToken
-  }
-}
-
-# Logout
-mutation Logout($input: LogoutInput!) {
-  logout(logoutInput: $input) {
-    success
-  }
-}
-
-# Email Verification
-mutation VerifyEmail($input: VerifyEmailInput!) {
-  verifyEmail(verifyEmailInput: $input) {
-    success
-    user { id email emailVerified }
-  }
-}
-
-# SMS Verification
-mutation VerifyPhone($input: VerifyPhoneInput!) {
-  verifyPhone(verifyPhoneInput: $input) {
-    success
-    user { id phoneNumber phoneVerified }
-  }
-}
-
-# Password Reset Request
-mutation RequestPasswordReset($input: RequestPasswordResetInput!) {
-  requestPasswordReset(input: $input) {
-    success
-    message
-    retryAfterSeconds
-  }
-}
-
-# Password Reset Confirmation
-mutation ResetPassword($input: ResetPasswordInput!) {
-  resetPassword(input: $input) {
-    success
-    message
-  }
-}
-
-# Google OAuth Account Linking
-mutation LinkGoogleAccount($input: LinkGoogleAccountInput!) {
-  linkGoogleAccount(linkGoogleAccountInput: $input) {
-    user { id googleId }
-  }
-}
-
-# Biometric Enrollment
-mutation EnrollBiometric($input: EnrollBiometricInput!) {
-  enrollBiometric(enrollBiometricInput: $input) {
-    credentialId
-    publicKey
-  }
-}
+```typescript
+@RequirePermissions('clients:write')
+@ResourceScope('client', 'clientId')
+@Mutation(() => Client)
+async updateClient(@Args('clientId') clientId: string) { /* ... */ }
 ```
 
-### Queries
-
-```graphql
-# Get current user
-query Me {
-  me {
-    id
-    email
-    emailVerified
-    phoneVerified
-    googleId
-    facebookId
-  }
-}
+### Realm-Based Identity Isolation
 
-# Check account lock status
-query CheckAccountLockStatus($email: String!) {
-  checkAccountLockStatus(email: $email) {
-    isLocked
-    remainingLockoutTime
-  }
-}
+Realms partition the user identity space so that users in one realm are completely invisible to another. The same email address can exist independently in different realms, each with its own password, tokens, and verification state. This is useful for white-label platforms, multi-brand businesses, and franchise systems.
 
-# Get biometric auth status
-query BiometricStatus {
-  biometricStatus {
-    isEnabled
-    registeredDevices { deviceId deviceName }
-  }
-}
-```
-
-## Implementing Custom Lifecycle Hooks
+Realms are opt-in: provide a `realmExtractorInstance` in `AuthModuleOptions`. No separate feature flag is needed. When not provided, everything works exactly as before.
 
-Add custom business logic to authentication events:
+**Implement `IRealmExtractor`:**
 
 ```typescript
 import { Injectable } from '@nestjs/common';
-import { IAuthLifecycleHooks, IAuthUser } from '@yourorg/nestjs-auth-graphql';
+import { IRealmExtractor } from '@ambushsoftworks/nestjs-auth-graphql';
 
 @Injectable()
-export class MyAuthHooks implements IAuthLifecycleHooks {
-  async onSignup(user: IAuthUser): Promise<void> {
-    // Send welcome email, create default settings, etc.
-    console.log(`New user signed up: ${user.email}`);
-  }
-
-  async onLogin(user: IAuthUser): Promise<void> {
-    // Update last login timestamp, log analytics, etc.
-    console.log(`User logged in: ${user.email}`);
+export class HostnameRealmExtractor implements IRealmExtractor {
+  extractRealm(request: Record<string, any>): string | null {
+    const host = request.headers?.host;
+    if (!host) return null;
+    // e.g., "acme.example.com" -> "acme"
+    const subdomain = host.split('.')[0];
+    return subdomain || null;
   }
+}
+```
 
-  async onLogout(user: IAuthUser): Promise<void> {
-    // Clean up sessions, log analytics, etc.
-    console.log(`User logged out: ${user.email}`);
-  }
+**Register the module with realm support:**
 
-  async onEmailVerified(user: IAuthUser): Promise<void> {
-    // Send confirmation email, unlock features, etc.
-    console.log(`Email verified: ${user.email}`);
-  }
+```typescript
+AuthModule.forRootAsync({
+  imports: [ConfigModule, DatabaseModule],
+  inject: [UsersRepository, RefreshTokenRepository, HostnameRealmExtractor, ConfigService],
+  useFactory: (usersRepo, tokenRepo, realmExtractor, config) => ({
+    userRepositoryInstance: usersRepo,
+    refreshTokenRepositoryInstance: tokenRepo,
+    jwtSecret: config.get('JWT_SECRET'),
+    realmExtractorInstance: realmExtractor,
+  }),
+})
+```
 
-  async onPasswordReset(user: IAuthUser): Promise<void> {
-    // Log security event, notify user, etc.
-    console.log(`Password reset: ${user.email}`);
-  }
+`RealmMiddleware` is automatically registered by `AuthModule` — no manual middleware registration needed. When a `realmExtractorInstance` is provided, the middleware calls `extractor.extractRealm(request)` on every request before any guards run. If the extractor returns `null`, the request is rejected with `400 Bad Request` (strict mode).
 
-  async onAccountLocked(user: IAuthUser, unlockTime: Date): Promise<void> {
-    // Send notification, log security event, etc.
-    console.log(`Account locked: ${user.email} until ${unlockTime}`);
-  }
+**Use `@CurrentRealm()` in resolvers:**
 
-  async onSocialAccountLinked(user: IAuthUser, provider: string): Promise<void> {
-    // Send confirmation email, log event, etc.
-    console.log(`${provider} account linked: ${user.email}`);
-  }
+```typescript
+import { CurrentRealm } from '@ambushsoftworks/nestjs-auth-graphql';
 
-  async onSocialAccountUnlinked(user: IAuthUser, provider: string): Promise<void> {
-    // Send confirmation email, log event, etc.
-    console.log(`${provider} account unlinked: ${user.email}`);
+@Resolver()
+export class AuthResolver extends BaseAuthResolver<User> {
+  @Mutation(() => AuthResponse)
+  async signup(
+    @Args('input') input: SignupInput,
+    @CurrentRealm() realm: string,
+    @Context() ctx: any,
+  ) {
+    return this.performSignup(input, ctx);
   }
 }
 ```
 
-## Security Features
-
-### Brute Force Protection
-
-- **5 failed login attempts** → 15-minute account lockout
-- IP-based rate limiting: 10 attempts per minute
-- Custom exception with `remainingLockoutTime` field
-
-### Token Security
-
-- **Access tokens**: Short-lived (15 minutes default)
-- **Refresh tokens**: Long-lived (30 days), HMAC-SHA256 hashed
-- **Token rotation**: New refresh token issued on each refresh
-- **Idempotent refresh**: 10-second grace period prevents race conditions
-
-### Verification Codes
-
-- **6-digit PIN codes**
-- **HMAC-SHA256 hashing**
-- **15-minute expiry**
-- **3 max attempts** per code
-- **60-second rate limit** on resend
-
-### OAuth Security
-
-- **Stateless CSRF protection**: JWT-based state tokens
-- **AES-256-GCM encryption**: OAuth access tokens encrypted at rest
-- **Account linking**: Secure flow with linking tokens
+`BaseAuthResolver` automatically extracts the realm from the GraphQL context via `getRealmFromContext()` and passes it to all service methods. Repository identity-resolution methods (`findByEmail`, `findByPhoneNumber`, `findByOAuthProvider`, `create`) receive the realm as a parameter so your implementation can scope queries accordingly.
 
-### Biometric Authentication
+**JWT realm validation:** The JWT payload includes a `realm` claim. On subsequent requests, `JwtStrategy` validates that the realm in the token matches the realm resolved from the current request. A mismatch results in `401 Unauthorized`.
 
-- **Public key cryptography**: WebAuthn-compatible
-- **Device enrollment**: Multiple device support
-- **Challenge-response**: Prevents replay attacks
+**Rate limiter scoping:** When realms are enabled, rate limiter keys are automatically prefixed with the realm to prevent cross-realm interference (e.g., a lockout in realm A does not affect realm B).
 
-## Security Best Practices
+**Realms vs. Multi-Tenancy:**
 
-### 🔐 Secret Management
+| Concern | Realms | Multi-Tenancy |
+|---------|--------|---------------|
+| Partitions | Identity (who the user _is_) | Authorization (what the user _can access_) |
+| Scope | User signup, login, tokens, verification | Permissions, resources, team membership |
+| Same email in multiple? | Yes -- fully independent users | Yes -- same user, different tenant contexts |
+| Guard layer | Middleware (before guards) | Guard (`TenantGuard`, after auth) |
 
-**CRITICAL**: Never commit secrets to version control. Use environment variables and secret management systems.
+Realms and multi-tenancy are orthogonal and can be used together. For example, a white-label SaaS platform might use realms to isolate brand identities and tenancy to manage organizations within each brand.
 
-**Required Secrets:**
+**Note:** Deprecated OAuth controller methods are not realm-aware. Use the current `BaseAuthResolver` OAuth methods for realm-scoped OAuth flows.
 
-1. **JWT_SECRET**:
-   - Generate: `openssl rand -base64 64`
-   - Minimum: 32 bytes (256 bits)
-   - Rotate: Every 90 days or on suspected compromise
-   - Store: Environment variables, AWS Secrets Manager, HashiCorp Vault, etc.
+### API Key Authentication
 
-2. **ENCRYPTION_KEY** (for OAuth):
-   - Generate: `openssl rand -hex 32` (produces 64-character hex string)
-   - Required length: Exactly 32 bytes (64 hex characters)
-   - Purpose: AES-256-GCM encryption for OAuth access tokens at rest
-   - Auto-generated if not provided, but **provide explicitly in production** for consistency across instances
-
-3. **OAuth Secrets**:
-   - Never expose in client-side code
-   - Use environment-specific secrets (dev/staging/prod)
-   - Rotate on suspected compromise
-
-**Example `.env` file** (never commit this file):
-```bash
-# Generate with: openssl rand -base64 64
-JWT_SECRET=your_random_64_byte_base64_secret
-
-# Generate with: openssl rand -hex 32
-ENCRYPTION_KEY=your_64_character_hex_string
-
-# OAuth secrets from provider dashboards
-GOOGLE_CLIENT_SECRET=...
-FACEBOOK_CLIENT_SECRET=...
-
-# Third-party API keys
-SENDGRID_API_KEY=...
-TWILIO_AUTH_TOKEN=...
-```
-
-**Production Secret Management:**
+For machine-to-machine auth, provide an `IApiKeyRepository`:
 
 ```typescript
-// ❌ BAD: Hard-coded secrets
-AuthModule.forRootAsync({
-  useFactory: () => ({
-    jwtSecret: 'my-secret-key',  // NEVER DO THIS
-  }),
-});
-
-// ✅ GOOD: Environment variables
 AuthModule.forRootAsync({
-  inject: [ConfigService],
-  useFactory: (config: ConfigService) => ({
-    jwtSecret: config.get<string>('JWT_SECRET'),  // Read from env
-    encryptionKey: config.get<string>('ENCRYPTION_KEY'),
+  useFactory: (apiKeyRepo) => ({
+    // ...required options
+    apiKeyRepositoryInstance: apiKeyRepo,
   }),
-});
-
-// ✅ BETTER: Validation with config module
-import { ConfigModule } from '@nestjs/config';
-import * as Joi from 'joi';
-
-ConfigModule.forRoot({
-  validationSchema: Joi.object({
-    JWT_SECRET: Joi.string().min(32).required(),
-    ENCRYPTION_KEY: Joi.string().length(64).pattern(/^[0-9a-f]{64}$/).required(),
-    GOOGLE_CLIENT_SECRET: Joi.string().when('GOOGLE_CLIENT_ID', {
-      is: Joi.exist(),
-      then: Joi.required(),
-    }),
-  }),
-});
+})
 ```
 
-### 🛡️ Token Configuration
-
-**Access Token Best Practices:**
+Then use a multi-strategy guard:
 
 ```typescript
-AuthModule.forRootAsync({
-  useFactory: (config) => ({
-    // Short-lived access tokens (minimize damage if compromised)
-    jwtExpiresIn: '15m',  // Default: 15 minutes
+{ provide: APP_GUARD, useClass: createAuthGuard(['api-key', 'jwt'], { allowPublic: true }) }
+```
 
-    // For mobile apps with poor connectivity, consider 1h max
-    // jwtExpiresIn: '1h',  // Longer for mobile, but less secure
+The `ApiKeyStrategy` hashes the bearer token with SHA-256 and calls `findByKeyHash()` on your repository. API keys and JWT tokens use the same `Authorization: Bearer` header -- strategies are tried in the order specified. When no bearer token is present (e.g. cookie auth), the API key strategy gracefully falls through to the next strategy.
 
-    // NEVER use long-lived access tokens
-    // jwtExpiresIn: '30d',  // ❌ INSECURE
-  }),
-});
-```
+### Email System
 
-**Refresh Token Best Practices:**
+The email system uses a composable architecture: a **sender** (transport) and a **template renderer** (HTML generation).
 
 ```typescript
+import { SendGridEmailSender } from '@ambushsoftworks/nestjs-auth-graphql';
+
 AuthModule.forRootAsync({
   useFactory: (config) => ({
-    // Balance between security and user experience
-    refreshTokenExpiresIn: '30d',  // Default: 30 days
-
-    // For high-security applications, use shorter expiration
-    // refreshTokenExpiresIn: '7d',  // Re-authenticate weekly
-
-    // For consumer apps, longer is acceptable
-    // refreshTokenExpiresIn: '90d',  // Re-authenticate quarterly
+    // ...required options
+    email: {
+      sender: new SendGridEmailSender(config.get('SENDGRID_API_KEY')),
+      from: { email: 'noreply@example.com', name: 'MyApp' },
+      branding: {
+        appName: 'MyApp',
+        primaryColor: '#1976D2',
+        logoUrl: 'https://example.com/logo.png',
+        companyName: 'My Company',
+        supportEmail: 'support@example.com',
+      },
+    },
   }),
-});
+})
 ```
 
-**Token Rotation**: This package automatically rotates refresh tokens on each use. Old tokens are invalidated to prevent replay attacks.
+`email.branding` is required when using the default template renderer. If you provide a custom `email.templateRenderer`, branding can be omitted.
 
-### 🔒 Password Policy
+**Built-in senders:** `SendGridEmailSender`, `ResendEmailSender`, `NoOpEmailSender`
 
-**Enforce Strong Passwords:**
+**Custom sender:** Implement `IEmailSender`:
 
-The package includes default password validation (8+ characters, uppercase, lowercase, number, special character). For stronger policies:
+```typescript
+class SmtpEmailSender implements IEmailSender {
+  async send(params: {
+    to: string;
+    from: { email: string; name?: string };
+    subject: string;
+    html: string;
+    text?: string;
+  }) {
+    // your SMTP logic
+  }
+}
+```
+
+**Custom template renderer:** Override `DefaultEmailTemplateRenderer` by providing `email.templateRenderer`:
 
 ```typescript
-import { InputType, Field } from '@nestjs/graphql';
-import { IsEmail, IsString, MinLength, MaxLength, Matches } from 'class-validator';
-
-@InputType()
-export class SignupInput {
-  @Field()
-  @IsEmail({}, { message: 'Please provide a valid email address' })
-  email: string;
-
-  @Field()
-  @IsString()
-  @MinLength(12, { message: 'Password must be at least 12 characters' })
-  @MaxLength(128, { message: 'Password must not exceed 128 characters' })
-  @Matches(
-    /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[@$!%*?&])[A-Za-z\d@$!%*?&]+$/,
-    { message: 'Password must contain uppercase, lowercase, number, and special character' }
-  )
-  password: string;
+email: {
+  sender: new SendGridEmailSender(apiKey),
+  from: { email: 'noreply@example.com' },
+  templateRenderer: new MyCustomRenderer(),
 }
 ```
 
-**Additional Recommendations:**
-- ✅ Check against common password lists (e.g., `have-i-been-pwned` API)
-- ✅ Implement password history (prevent reuse of last 5 passwords)
-- ✅ Require password change on first login (for admin-created accounts)
-- ✅ Implement password expiration (60-90 days for high-security apps)
+### Verification Modes
 
-### ⏱️ Rate Limiting
+Two modes for email verification and password reset:
 
-**Configure Throttling:**
+- **`'code'`** (default) -- 6-digit numeric codes
+- **`'token'`** -- URL-based tokens with configurable base URL
 
 ```typescript
-import { ThrottlerModule } from '@nestjs/throttler';
+features: { verificationMode: 'token' },
+verification: {
+  baseUrl: 'https://app.example.com',
+  tokenLength: 64,          // bytes, default: 64
+  tokenExpiresInMinutes: 60, // default: 60
+},
+```
 
-@Module({
-  imports: [
-    // Global rate limiting
-    ThrottlerModule.forRoot([{
-      ttl: 60000,  // 60 seconds
-      limit: 100,  // 100 requests per minute
-    }]),
+### OAuth
 
-    AuthModule.forRootAsync({
-      // Auth-specific throttling is handled per-mutation
-      // See AuthResolver for @Throttle() decorators
-    }),
-  ],
+Google and Facebook OAuth with encrypted token storage (AES-256-GCM).
+
+```typescript
+AuthModule.forRootAsync({
+  useFactory: (config) => ({
+    // ...required options
+    encryptionKey: config.get('ENCRYPTION_KEY'), // 32-byte hex string
+    oauth: {
+      google: {
+        clientId: config.get('GOOGLE_CLIENT_ID'),
+        clientSecret: config.get('GOOGLE_CLIENT_SECRET'),
+        callbackUrl: config.get('GOOGLE_CALLBACK_URL'),
+      },
+      facebook: {
+        clientId: config.get('FACEBOOK_CLIENT_ID'),
+        clientSecret: config.get('FACEBOOK_CLIENT_SECRET'),
+        callbackUrl: config.get('FACEBOOK_CALLBACK_URL'),
+      },
+    },
+  }),
 })
 ```
 
-**Per-Endpoint Throttling** (already implemented in BaseAuthResolver):
-- Login: 5 requests/minute (prevent brute force)
-- Signup: 5 requests/minute (prevent spam)
-- Refresh: 10 requests/minute (allow frequent refreshes)
-- Verification codes: 3 requests/minute (prevent SMS/email bombing)
+The `OAuthController` is automatically registered and handles OAuth callback routes. OAuth strategies gracefully degrade to no-ops when credentials are not configured.
 
-**Brute Force Protection**: Enabled by default - 5 failed login attempts = 15-minute account lockout.
+### Brute Force Protection
 
-### 🌐 HTTPS/TLS Requirements
+When `features.bruteForceProtection` is enabled and a `bruteForceRepositoryInstance` is provided, the module tracks failed login attempts and temporarily locks accounts. The lockout policy (attempt thresholds, lockout duration) is determined by your `IBruteForceRepository` implementation.
 
-**PRODUCTION REQUIREMENT**: All authentication endpoints MUST use HTTPS.
+### Password Policy
 
 ```typescript
-// Production enforcement example
-import { NestFactory } from '@nestjs/core';
-import { AppModule } from './app.module';
-
-async function bootstrap() {
-  const app = await NestFactory.create(AppModule);
-
-  // Enforce HTTPS in production
-  if (process.env.NODE_ENV === 'production') {
-    app.use((req, res, next) => {
-      if (!req.secure && req.headers['x-forwarded-proto'] !== 'https') {
-        return res.redirect(301, `https://${req.headers.host}${req.url}`);
-      }
-      next();
-    });
-  }
-
-  await app.listen(3000);
+passwordPolicy: {
+  minLength: 12,            // default: 8
+  maxLength: 72,            // bcrypt limit
+  requireUppercase: true,   // default: true
+  requireLowercase: true,   // default: true
+  requireNumber: true,      // default: true
+  requireSpecialChar: true, // default: false
+  customValidator: async (password) => {
+    // Optional: dictionary checks, leaked password detection, etc.
+    const isCommon = await checkLeakedPasswords(password);
+    return {
+      isValid: !isCommon,
+      errors: isCommon ? ['Password found in data breaches'] : [],
+    };
+  },
 }
-bootstrap();
 ```
 
-**OAuth Callback URLs**: Must be HTTPS in production (required by Google/Facebook).
-
-### 📊 Security Logging
+### Lifecycle Hooks
 
-**Implement Custom Security Logger** for production monitoring:
+React to auth events without modifying core logic:
 
 ```typescript
-import { Injectable } from '@nestjs/common';
-import { IAuthLogger, SecurityEvent } from '@ambushsoftworks/nestjs-auth-graphql';
-
-@Injectable()
-export class ProductionAuthLogger implements IAuthLogger {
-  constructor(
-    private readonly datadogClient: DatadogClient,
-    private readonly slackNotifier: SlackNotifier,
-  ) {}
-
-  log(event: SecurityEvent, metadata: Record<string, any>) {
-    // Log to centralized logging service
-    this.datadogClient.log({
-      level: 'info',
-      message: event,
-      tags: ['auth', 'security'],
-      ...metadata,
-    });
-
-    // Alert on suspicious events
-    if (event === SecurityEvent.TOKEN_REUSE_DETECTED) {
-      this.slackNotifier.send(`⚠️ Security Alert: Token reuse detected for user ${metadata.userId}`);
-    }
-  }
-
-  error(message: string, trace?: string, context?: string) {
-    this.datadogClient.error({ message, trace, context });
-  }
-
-  warn(message: string, context?: string) {
-    this.datadogClient.warn({ message, context });
-  }
-
-  debug(message: string, context?: string) {
-    // Only in development
-    if (process.env.NODE_ENV === 'development') {
-      this.datadogClient.debug({ message, context });
-    }
-  }
-
-  verbose(message: string, context?: string) {
-    // Only in development
-    if (process.env.NODE_ENV === 'development') {
-      this.datadogClient.log({ level: 'verbose', message, context });
-    }
-  }
+lifecycleHooksInstance: {
+  async onSignup(user) { /* create default settings, send analytics */ },
+  async onLogin(user) { /* update metrics */ },
+  async onLogout(user) { /* cleanup */ },
+  async onEmailVerified(user) { /* unlock features */ },
+  async onPhoneVerified(user) { /* enable 2FA */ },
+  async onOAuthAccountLinked(user, provider) { /* sync data */ },
+  async onPasswordReset(user) { /* send security alert */ },
+  async onPasswordChanged(user) { /* notify user */ },
+  async onAccountDelete(user) { /* cleanup user data */ },
+  onAuthFailure(email, ip, reason) { /* security monitoring */ },
 }
 ```
 
-**Critical Events to Monitor:**
-- `TOKEN_REUSE_DETECTED`: Possible security breach
-- `ACCOUNT_LOCKED`: High failed login attempts
-- `LOGIN_FAILURE`: Pattern analysis for attacks
-- `VERIFICATION_CODE_FAILED`: Potential brute force on codes
+All hooks are optional. Async hooks are awaited but failures are logged and do not block the auth operation. `onAuthFailure` is synchronous (fire-and-forget).
 
-### 🚀 Production Deployment
+### JWT Validation Modes
 
-**Environment Separation:**
+- **`'full'`** (default) -- Calls `userRepository.findById()` on every request to verify the user still exists.
+- **`'payload-only'`** -- Returns `{ id, email }` from the JWT payload without a DB lookup. Faster, but does not detect deleted/disabled users until token expiry.
 
-```bash
-# Development (.env.development)
-NODE_ENV=development
-JWT_SECRET=dev_secret_key
-ENCRYPTION_KEY=dev_encryption_key
-
-# Staging (.env.staging)
-NODE_ENV=staging
-JWT_SECRET=staging_secret_key_different_from_dev
-ENCRYPTION_KEY=staging_encryption_key_different_from_dev
-
-# Production (.env.production)
-NODE_ENV=production
-JWT_SECRET=production_secret_key_from_secrets_manager
-ENCRYPTION_KEY=production_encryption_key_from_secrets_manager
+```typescript
+jwtValidation: 'payload-only',
 ```
 
-**Multi-Instance Deployment** (Load Balanced):
-- See "Production Deployment" section in CLAUDE.md for cache limitations
-- Use Redis for shared refresh token cache across instances
-- OR configure sticky sessions on load balancer
-- OR accept 10-second grace period limitation for most apps
-
-**Security Checklist:**
-- ✅ HTTPS enforced (no HTTP in production)
-- ✅ Secrets managed via environment variables or secret manager
-- ✅ CORS configured to allow only trusted domains
-- ✅ Rate limiting enabled globally
-- ✅ Security logging to centralized service
-- ✅ Database connections use TLS
-- ✅ OAuth callback URLs whitelisted
-- ✅ ValidationPipe enabled globally
-- ✅ Helmet middleware for HTTP security headers
-- ✅ CSRF protection enabled (built-in for OAuth)
-
-**Security Headers Example:**
+### JWT Payload Factory
 
-```typescript
-import helmet from 'helmet';
-
-async function bootstrap() {
-  const app = await NestFactory.create(AppModule);
-
-  // Security headers
-  app.use(helmet({
-    contentSecurityPolicy: {
-      directives: {
-        defaultSrc: ["'self'"],
-        styleSrc: ["'self'", "'unsafe-inline'"],
-        scriptSrc: ["'self'"],
-      },
-    },
-    hsts: {
-      maxAge: 31536000,
-      includeSubDomains: true,
-      preload: true,
-    },
-  }));
+Customize JWT claims by providing an `IJwtPayloadFactory`:
 
-  await app.listen(3000);
+```typescript
+jwtPayloadFactoryInstance: {
+  createPayload(user) {
+    return { sub: user.id, email: user.email, role: user.role };
+  },
+  extractUserId(payload) {
+    return payload.sub;
+  },
 }
 ```
 
-### 🔍 Security Audits
-
-**Regular Security Practices:**
-1. **Dependency Scanning**: `npm audit` (weekly in CI/CD)
-2. **Secret Scanning**: Use tools like GitGuardian, TruffleHog
-3. **Penetration Testing**: Quarterly security assessments
-4. **Log Review**: Weekly review of security event logs
-5. **Incident Response**: Document and practice breach response procedures
-
-**Monitoring Alerts:**
-- Failed login spike (>100/hour)
-- Account lockout spike (>10/hour)
-- Token reuse detection (any occurrence)
-- Unusual geographic login patterns
-- Multiple verification code failures
-
-## Database Schema Requirements
-
-This package expects specific database tables to implement the repository interfaces. You have two options:
-
-### Option 1: Match the Package Schema (Recommended)
-
-Create tables that directly match the package interfaces for optimal performance:
-
-#### User Table
-
-Required fields:
-```sql
-CREATE TABLE users (
-  id VARCHAR(36) PRIMARY KEY,
-  email VARCHAR(255) UNIQUE NOT NULL,
-  passwordHash VARCHAR(255),  -- Nullable for OAuth-only accounts
-  emailVerified BOOLEAN DEFAULT false,
-  phoneNumber VARCHAR(20),    -- Nullable
-  phoneVerified BOOLEAN DEFAULT false,
-  googleId VARCHAR(255),      -- Nullable, unique
-  facebookId VARCHAR(255),    -- Nullable, unique
-  appleId VARCHAR(255),       -- Nullable, unique
-  authProvider VARCHAR(20) DEFAULT 'local',  -- 'local' | 'google' | 'facebook' | 'apple'
-  accountLockedUntil TIMESTAMP,  -- Nullable, for brute force protection
-  lastLoginAt TIMESTAMP,
-  createdAt TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-  updatedAt TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
-);
-```
+---
 
-#### RefreshToken Table
-
-```sql
-CREATE TABLE refresh_tokens (
-  id VARCHAR(36) PRIMARY KEY,
-  userId VARCHAR(36) NOT NULL REFERENCES users(id) ON DELETE CASCADE,
-  token VARCHAR(255) NOT NULL,  -- Plain token (sent to client)
-  hashedToken VARCHAR(255) NOT NULL UNIQUE,  -- HMAC-SHA256 hash for lookup
-  expiresAt TIMESTAMP NOT NULL,
-  deviceInfo TEXT,  -- Nullable, JSON with device/browser info
-  createdAt TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-  INDEX idx_userId (userId),
-  INDEX idx_hashedToken (hashedToken),
-  INDEX idx_expiresAt (expiresAt)
-);
-```
+## Configuration Reference
 
-#### EmailVerification Table
-
-```sql
-CREATE TABLE email_verifications (
-  id VARCHAR(36) PRIMARY KEY,
-  userId VARCHAR(36) NOT NULL REFERENCES users(id) ON DELETE CASCADE,
-  codeHash VARCHAR(255) NOT NULL,  -- HMAC-SHA256 hash of 6-digit code
-  expiresAt TIMESTAMP NOT NULL,
-  attempts INT DEFAULT 0,
-  used BOOLEAN DEFAULT false,
-  createdAt TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-  INDEX idx_userId (userId),
-  UNIQUE idx_userId_unused (userId, used)  -- Ensure only one active code per user
-);
-```
+### Required Options
 
-#### PhoneVerification Table
-
-```sql
-CREATE TABLE phone_verifications (
-  id VARCHAR(36) PRIMARY KEY,
-  userId VARCHAR(36) NOT NULL REFERENCES users(id) ON DELETE CASCADE,
-  codeHash VARCHAR(255) NOT NULL,  -- HMAC-SHA256 hash of 6-digit code
-  expiresAt TIMESTAMP NOT NULL,
-  attempts INT DEFAULT 0,
-  used BOOLEAN DEFAULT false,
-  createdAt TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-  INDEX idx_userId (userId),
-  UNIQUE idx_userId_unused (userId, used)
-);
-```
+| Option | Type | Description |
+|--------|------|-------------|
+| `userRepositoryInstance` | `IUserRepository` | User persistence |
+| `refreshTokenRepositoryInstance` | `IRefreshTokenRepository` | Token persistence |
+| `jwtSecret` | `string` | JWT signing secret |
+
+### Common Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `jwtExpiresIn` | `string` | `'15m'` | Access token TTL |
+| `refreshTokenExpiresIn` | `string` | `'30d'` | Refresh token TTL |
+| `jwtValidation` | `'full' \| 'payload-only'` | `'full'` | JWT validation strategy |
+| `bcryptRounds` | `number` | `12` | Password hashing cost |
+| `nodeEnv` | `string` | `'production'` | Environment identifier |
+| `passwordPolicy` | `PasswordPolicyConfig` | See [Password Policy](#password-policy) | Password strength rules |
+| `encryptionKey` | `string` | -- | 32-byte hex string for AES-256-GCM (OAuth token encryption) |
+
+### Feature Flags (`features`)
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `cookieAuth` | `false` | Token delivery via HttpOnly cookies |
+| `multiTenancy` | `false` | Enable TenantGuard + PermissionGuard |
+| `bruteForceProtection` | `false` | Account lockout on failed logins |
+| `preventEnumerationOnSignup` | `false` | Return synthetic success for duplicate emails |
+| `verificationMode` | `'code'` | `'code'` for 6-digit codes, `'token'` for URL tokens |
+| `emailVerification` | `false` | Enable email verification flow |
+| `smsVerification` | `false` | Enable SMS verification flow |
+| `googleOAuth` | `false` | Enable Google OAuth |
+| `facebookOAuth` | `false` | Enable Facebook OAuth |
+| `biometricAuth` | `false` | Enable biometric authentication |
+
+### Security Secrets
+
+Separate HMAC secrets for security isolation. All fall back to `jwtSecret` if not provided.
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `refreshTokenSecret` | `string` | HMAC secret for refresh token hashing |
+| `verificationCodeSecret` | `string` | HMAC secret for verification code hashing |
+| `oauthStateSecret` | `string` | JWT secret for OAuth CSRF state tokens |
+| `oauthRedirectWhitelist` | `string` | Comma-separated allowed OAuth redirect URLs |
+
+### Cookie Options (`cookie`)
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `httpOnly` | `boolean` | `true` | HttpOnly flag |
+| `secure` | `boolean` | `true` | Secure flag |
+| `sameSite` | `'lax' \| 'strict' \| 'none'` | `'lax'` | SameSite attribute |
+| `domain` | `string` | `undefined` | Cookie domain |
+| `path` | `string` | `'/'` | Cookie path |
+| `accessTokenName` | `string` | `'access_token'` | Access token cookie name |
+| `refreshTokenName` | `string` | `'refresh_token'` | Refresh token cookie name |
+| `accessTokenMaxAge` | `number` | derived from `jwtExpiresIn` | Access token cookie max age (ms) |
+| `refreshTokenMaxAge` | `number` | derived from `refreshTokenExpiresIn` | Refresh token cookie max age (ms) |
+| `useHostPrefix` | `boolean` | `false` | Prefix names with `__Host-` |
+
+### CSRF Options (`csrf`)
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `headerName` | `string` | `'X-Requested-With'` | Header to check |
+| `requireInProduction` | `boolean` | `true` | Require CSRF header in production |
+| `exemptOperations` | `string[]` | `[]` | GraphQL operations to skip |
+
+### Composable Email (`email`)
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `email.sender` | `IEmailSender` | Transport (SendGrid, Resend, etc.) -- required |
+| `email.from` | `{ email, name? }` | Sender address -- required |
+| `email.branding` | `EmailBrandingConfig` | App name, colors, logo, etc. -- required unless `templateRenderer` is provided |
+| `email.templateRenderer` | `IEmailTemplateRenderer` | Override default HTML renderer |
+
+When `email` is provided, it takes precedence over `emailServiceInstance`.
+
+### Verification Options (`verification`)
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `tokenLength` | `number` | `64` | Token length in bytes (token mode) |
+| `tokenExpiresInMinutes` | `number` | `60` | Token expiration (token mode) |
+| `baseUrl` | `string` | -- | Base URL for verification/reset URLs |
+
+### Optional Instance Options
+
+| Option | Interface | Fallback |
+|--------|-----------|----------|
+| `emailServiceInstance` | `IEmailService` | `NoOpEmailService` |
+| `smsServiceInstance` | `ISmsService` | `NoOpSmsService` |
+| `lifecycleHooksInstance` | `IAuthLifecycleHooks` | `{}` (no-op) |
+| `verificationRepositoryInstance` | `IVerificationRepository` | `NoOpVerificationRepository` |
+| `bruteForceRepositoryInstance` | `IBruteForceRepository` | `NoOpBruteForceRepository` |
+| `biometricRepositoryInstance` | `IBiometricRepository` | `NoOpBiometricRepository` |
+| `authLoggerInstance` | `IAuthLogger` | `ConsoleAuthLogger` |
+| `tenantRepositoryInstance` | `ITenantRepository` | `null` |
+| `tenantExtractorInstance` | `ITenantExtractor` | `null` |
+| `resourcePermissionRepositoryInstance` | `IResourcePermissionRepository` | `null` |
+| `jwtPayloadFactoryInstance` | `IJwtPayloadFactory` | `DefaultJwtPayloadFactory` |
+| `apiKeyRepositoryInstance` | `IApiKeyRepository` | `null` |
+| `rateLimiterInstance` | `IRateLimiter` | `InMemoryRateLimiterService` |
+| `realmExtractorInstance` | `IRealmExtractor` | `null` (realms disabled) |
 
-#### FailedLoginAttempt Table
-
-```sql
-CREATE TABLE failed_login_attempts (
-  id VARCHAR(36) PRIMARY KEY,
-  userId VARCHAR(36) NOT NULL REFERENCES users(id) ON DELETE CASCADE,
-  ipAddress VARCHAR(45),  -- IPv4 or IPv6
-  attemptedAt TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-  INDEX idx_userId (userId),
-  INDEX idx_attemptedAt (attemptedAt)
-);
-```
+---
 
-#### BiometricCredential Table
-
-```sql
-CREATE TABLE biometric_credentials (
-  id VARCHAR(36) PRIMARY KEY,
-  userId VARCHAR(36) NOT NULL REFERENCES users(id) ON DELETE CASCADE,
-  credentialId VARCHAR(255) NOT NULL UNIQUE,  -- WebAuthn credential ID
-  publicKey TEXT NOT NULL,  -- PEM-encoded ECDSA public key
-  deviceName VARCHAR(255) NOT NULL,
-  createdAt TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-  lastUsedAt TIMESTAMP,
-  INDEX idx_userId (userId),
-  INDEX idx_credentialId (credentialId)
-);
-```
+## Decorators
 
-#### BiometricChallenge Table
-
-```sql
-CREATE TABLE biometric_challenges (
-  id VARCHAR(36) PRIMARY KEY,
-  userId VARCHAR(36) NOT NULL REFERENCES users(id) ON DELETE CASCADE,
-  challenge VARCHAR(255) NOT NULL,  -- Base64-encoded random challenge
-  expiresAt TIMESTAMP NOT NULL,
-  used BOOLEAN DEFAULT false,
-  createdAt TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-  INDEX idx_userId (userId),
-  INDEX idx_expiresAt (expiresAt)
-);
-```
+| Decorator | Target | Description |
+|-----------|--------|-------------|
+| `@Public()` | Method/Class | Skip authentication |
+| `@PublicEndpoint()` | Method/Class | Skip authentication + tenant resolution (combines `@Public()` + `@SkipTenant()`) |
+| `@SkipTenant()` | Method/Class | Skip tenant resolution |
+| `@RequirePermissions('p1', 'p2')` | Method/Class | Require specific permissions |
+| `@CurrentUser()` | Parameter | Inject authenticated user |
+| `@CurrentTenant()` | Parameter | Inject resolved tenant context |
+| `@CurrentRealm()` | Parameter | Inject resolved realm from request context |
+| `@ResourceScope('resourceType', 'argName')` | Method | Resource-level permission scoping |
 
-### Option 2: Adapter Pattern (Flexible Schema)
+## Guards
 
-If your database schema differs from the package expectations, create **adapter repositories** that translate between your schema and the package interfaces.
+| Guard | Description |
+|-------|-------------|
+| `createAuthGuard(strategies, options)` | Factory for multi-strategy auth guards |
+| `CsrfGuard` | CSRF header validation for cookie auth |
+| `TenantGuard` | Multi-tenant context resolution |
+| `PermissionGuard` | Permission checking against tenant context |
+| `JwtAuthGuard` | Basic JWT guard (prefer `createAuthGuard`) |
 
-**Example**: Lift app uses a unified `VerificationCode` table for both email and SMS verification:
+### Recommended Guard Chains
 
-```typescript
-@Injectable()
-export class PrismaVerificationRepository implements IVerificationRepository {
-  constructor(private prisma: PrismaService) {}
-
-  async storeVerificationCode(
-    userId: string,
-    code: string,
-    expiresAt: Date,
-    type: 'email' | 'phone',
-  ): Promise<void> {
-    // 1. Look up user to get email or phone (extra query)
-    const user = await this.prisma.user.findUnique({
-      where: { id: userId },
-      select: { email: true, phoneNumber: true },
-    });
-
-    const identifier = type === 'email' ? user.email : user.phoneNumber;
-
-    // 2. Store in unified VerificationCode table
-    await this.prisma.verificationCode.create({
-      data: {
-        type: type === 'email' ? 'email' : 'sms',
-        identifier: identifier.toLowerCase(),
-        codeHash: code,
-        expiresAt,
-        attempts: 0,
-        used: false,
-      },
-    });
-  }
-
-  // Implement other methods with similar adapter logic...
-}
-```
+When realm support is enabled, `RealmMiddleware` runs before all guards (as NestJS middleware) and attaches the resolved realm to `request._realm`. It is registered automatically by `AuthModule` -- see [Realm-Based Identity Isolation](#realm-based-identity-isolation).
 
-**Trade-offs**:
-- ✅ **Pro**: No schema migration required, preserves existing logic
-- ❌ **Con**: Extra database queries (performance overhead)
-- ❌ **Con**: Adapter complexity increases maintenance burden
-
-**Recommendation**: Use Option 1 for new projects. Use Option 2 for migrating existing apps with established schemas.
+```typescript
+// JWT only
+{ provide: APP_GUARD, useClass: createAuthGuard(['jwt'], { allowPublic: true }) }
 
-## Environment Variables
+// JWT + API keys
+{ provide: APP_GUARD, useClass: createAuthGuard(['jwt', 'api-key'], { allowPublic: true }) }
 
-```bash
-# JWT
-JWT_SECRET=your_secret_key_here
-
-# SendGrid (if using SendGridEmailService)
-SENDGRID_API_KEY=your_sendgrid_api_key
-SENDGRID_FROM_EMAIL=noreply@yourapp.com
-SENDGRID_FROM_NAME=Your App Name
-
-# Twilio (if using TwilioSmsService)
-TWILIO_ACCOUNT_SID=your_twilio_account_sid
-TWILIO_AUTH_TOKEN=your_twilio_auth_token
-TWILIO_PHONE_NUMBER=+1234567890
-
-# Google OAuth (if using)
-GOOGLE_CLIENT_ID=your_google_client_id
-GOOGLE_CLIENT_SECRET=your_google_client_secret
-GOOGLE_CALLBACK_URL=https://yourapp.com/api/auth/google/callback
-
-# Facebook OAuth (if using)
-FACEBOOK_CLIENT_ID=your_facebook_app_id
-FACEBOOK_CLIENT_SECRET=your_facebook_app_secret
-FACEBOOK_CALLBACK_URL=https://yourapp.com/api/auth/facebook/callback
-
-# Encryption (auto-generated if not provided)
-ENCRYPTION_KEY=32_byte_hex_string
+// Full stack with cookie auth + multi-tenancy
+{ provide: APP_GUARD, useClass: CsrfGuard },
+{ provide: APP_GUARD, useClass: createAuthGuard(['jwt', 'api-key'], { allowPublic: true }) },
+{ provide: APP_GUARD, useClass: TenantGuard },
+{ provide: APP_GUARD, useClass: PermissionGuard },
 ```
 
-## Testing
-
-The package includes 246+ tests from the production Lift app:
-
-```bash
-npm test                # Run all tests
-npm run test:watch      # Watch mode
-npm run test:cov        # Coverage report
-```
+## Utilities
 
-## Architecture
+Helper functions exported for use in custom guards and middleware:
 
-This package follows **Layer 0 architecture** with complete interface abstraction:
+| Function | Description |
+|----------|-------------|
+| `getRequestFromContext(context)` | Extract request from `ExecutionContext` (handles GraphQL + HTTP) |
+| `extractIpAddress(request)` | Extract client IP (checks `clientIp`, `req.ip`, falls back to `'unknown'`) |
 
-- **No database coupling**: All services use interfaces (`IUserRepository`, etc.)
-- **No Prisma imports** in package code
-- **Dependency injection**: Proper NestJS DI patterns
-- **Type safety**: Strict TypeScript mode enabled
-- **Production tested**: Extracted from Lift app with 246+ passing tests
+```typescript
+import { getRequestFromContext, extractIpAddress } from '@ambushsoftworks/nestjs-auth-graphql';
 
-## Migration from Lift Codebase
+@Injectable()
+export class CustomGuard implements CanActivate {
+  canActivate(context: ExecutionContext): boolean {
+    const request = getRequestFromContext(context);
+    const ip = extractIpAddress(request);
+    // your logic
+    return true;
+  }
+}
+```
 
-If you're migrating from the Lift codebase:
+## Security Features
 
-1. Replace `import { AuthModule } from './auth/auth.module'` with `import { AuthModule } from '@yourorg/nestjs-auth-graphql'`
-2. Implement `IUserRepository` and `IRefreshTokenRepository` using your Prisma models
-3. Configure `AuthModule.forRootAsync()` with your repositories and services
-4. Remove old `src/auth/` directory (keep only repository implementations)
+- **Refresh token rotation** with HMAC-SHA256 hashing and idempotent 10-second grace period
+- **Bcrypt password hashing** with configurable rounds (default: 12)
+- **AES-256-GCM encryption** for OAuth tokens at rest
+- **Constant-time comparison** for verification codes
+- **Account enumeration prevention** on signup (optional)
+- **Stateless CSRF protection** for OAuth flows via `OAuthStateService`
+- **`__Host-` cookie prefix** support for enhanced cookie security
+- **Separate HMAC secrets** for refresh tokens, verification codes, and OAuth state
+- **Realm-based identity isolation** with JWT realm claim validation and realm-scoped rate limiting
 
 ## License
 
-MIT
-
-## Support
-
-For issues and questions, please open an issue on GitLab.
+MIT -- see [LICENSE](./LICENSE).