@ambushsoftworks/nestjs-auth-graphql 0.4.0 → 0.6.7

package/README.md

@@ -1,1560 +1,775 @@
 # @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, 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)
+  - [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>;
+  async logout(@Args('input') input: LogoutInput, @CurrentUser() user: User) {
+    return this.performLogout(input, user);
   }
-
-  @Mutation(() => LogoutAllResponse)
-  @UseGuards(JwtAuthGuard)
-  @Throttle({ default: { limit: 5, ttl: 60000 } })
-  async logoutAll(@CurrentUser() user: User): Promise<LogoutAllResponse> {
-    return this.performLogoutAll(user) as Promise<LogoutAllResponse>;
-  }
-
-  // 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
-
-### Required Options
+| Method | Purpose |
+|--------|---------|
+| `performRequestPasswordReset(input, context?)` | Send reset code/token |
+| `performResetPassword(input, context?)` | Reset password |
+| `performChangePassword(userId, current, new)` | Change password |
 
-- `userRepositoryInstance`: Instance of `IUserRepository` implementation
-- `refreshTokenRepositoryInstance`: Instance of `IRefreshTokenRepository` implementation
-- `jwtSecret`: Secret key for signing JWT tokens
+**Other:**
 
-### Optional Options
+| Method | Purpose |
+|--------|---------|
+| `performCheckAccountLockStatus(email)` | Check brute force lock status |
+| `performCompleteFacebookSignUp(input)` | Facebook email fallback |
 
-- `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
-
-### Consumer Setup
+Configure via `csrf` options:
 
-#### 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
-
-Create consumer-specific DTOs with GraphQL decorators:
+**Guard chain** (order matters):
 
-**`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;
+```typescript
+@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 },
+    };
+  }
 }
 ```
 
-**`password-reset-response.dto.ts`:**
-```typescript
-import { ObjectType, Field, Int } from '@nestjs/graphql';
-import { IAuthPasswordResetResponse } from '@ambushsoftworks/nestjs-auth-graphql';
+**`ITenantExtractor`** pulls the tenant ID from the request. Use the built-in `HeaderTenantExtractor` (reads `x-tenant-id` header) or implement your own:
 
-@ObjectType()
-export class PasswordResetResponse implements IAuthPasswordResetResponse {
-  @Field(() => Boolean)
-  success: boolean;
+```typescript
+import { HeaderTenantExtractor } from '@ambushsoftworks/nestjs-auth-graphql';
 
-  @Field(() => String)
-  message: string;
+// Default: reads x-tenant-id header
+const extractor = new HeaderTenantExtractor();
 
-  @Field(() => Int, { nullable: true })
-  retryAfterSeconds?: number;
-}
+// Custom header name
+const extractor = new HeaderTenantExtractor('x-org-id');
 ```
 
-#### Step 4: Add Resolver Mutations
-
-Extend your custom resolver with password reset mutations:
+**Access tenant context** in resolvers:
 
 ```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>;
-  }
+@Query(() => [Item])
+async items(@CurrentTenant() tenant: ITenantContext) {
+  return this.service.findByTenant(tenant.tenantId);
 }
 ```
 
-#### Step 5: Deploy & Test
-
-```bash
-# Run migration
-npx prisma migrate deploy
-
-# Start dev server
-npm run start:dev
+**Skip tenant resolution** for routes that don't need it:
 
-# 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 } }"}'
+```typescript
+@SkipTenant()
+@Query(() => User)
+async me(@CurrentUser() user: User) { /* ... */ }
 ```
 
-### GraphQL Schema
-
-After setup, your schema will include:
+**Permission checking** with `@RequirePermissions()`:
 
-```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
+@RequirePermissions('clients:read')
+@Query(() => [Client])
+async clients(@CurrentTenant() tenant: ITenantContext) { /* ... */ }
 ```
 
-### 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):**
+For resource-scoped permissions, combine with `@ResourceScope()` and provide an `IResourcePermissionRepository`:
 
 ```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');
-  }
-}
+@RequirePermissions('clients:write')
+@ResourceScope('client', 'clientId')
+@Mutation(() => Client)
+async updateClient(@Args('clientId') clientId: string) { /* ... */ }
 ```
 
-### Security Considerations
-
-1. **Never reveal whether email exists**
-   - Always return success message, even for non-existent emails
-   - Client cannot enumerate valid email addresses
+### API Key Authentication
 
-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:
+For machine-to-machine auth, provide an `IApiKeyRepository`:
 
 ```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);
-  }
-}
+AuthModule.forRootAsync({
+  useFactory: (apiKeyRepo) => ({
+    // ...required options
+    apiKeyRepositoryInstance: apiKeyRepo,
+  }),
+})
 ```
 
-## GraphQL API
-
-The package provides a complete GraphQL API:
-
-### Mutations
-
-```graphql
-# Signup
-mutation Signup($input: SignupInput!) {
-  signup(signupInput: $input) {
-    accessToken
-    refreshToken
-    user { id email }
-  }
-}
-
-# Login
-mutation Login($input: LoginInput!) {
-  login(loginInput: $input) {
-    accessToken
-    refreshToken
-    user { id email }
-  }
-}
+Then use a multi-strategy guard:
 
-# 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 }
-  }
-}
+```typescript
+{ provide: APP_GUARD, useClass: createAuthGuard(['api-key', 'jwt'], { allowPublic: true }) }
+```
 
-# SMS Verification
-mutation VerifyPhone($input: VerifyPhoneInput!) {
-  verifyPhone(verifyPhoneInput: $input) {
-    success
-    user { id phoneNumber phoneVerified }
-  }
-}
+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.
 
-# Password Reset Request
-mutation RequestPasswordReset($input: RequestPasswordResetInput!) {
-  requestPasswordReset(input: $input) {
-    success
-    message
-    retryAfterSeconds
-  }
-}
+### Email System
 
-# Password Reset Confirmation
-mutation ResetPassword($input: ResetPasswordInput!) {
-  resetPassword(input: $input) {
-    success
-    message
-  }
-}
+The email system uses a composable architecture: a **sender** (transport) and a **template renderer** (HTML generation).
 
-# Google OAuth Account Linking
-mutation LinkGoogleAccount($input: LinkGoogleAccountInput!) {
-  linkGoogleAccount(linkGoogleAccountInput: $input) {
-    user { id googleId }
-  }
-}
+```typescript
+import { SendGridEmailSender } from '@ambushsoftworks/nestjs-auth-graphql';
 
-# Biometric Enrollment
-mutation EnrollBiometric($input: EnrollBiometricInput!) {
-  enrollBiometric(enrollBiometricInput: $input) {
-    credentialId
-    publicKey
-  }
-}
+AuthModule.forRootAsync({
+  useFactory: (config) => ({
+    // ...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',
+      },
+    },
+  }),
+})
 ```
 
-### Queries
-
-```graphql
-# Get current user
-query Me {
-  me {
-    id
-    email
-    emailVerified
-    phoneVerified
-    googleId
-    facebookId
-  }
-}
+`email.branding` is required when using the default template renderer. If you provide a custom `email.templateRenderer`, branding can be omitted.
 
-# Check account lock status
-query CheckAccountLockStatus($email: String!) {
-  checkAccountLockStatus(email: $email) {
-    isLocked
-    remainingLockoutTime
-  }
-}
+**Built-in senders:** `SendGridEmailSender`, `ResendEmailSender`, `NoOpEmailSender`
 
-# Get biometric auth status
-query BiometricStatus {
-  biometricStatus {
-    isEnabled
-    registeredDevices { deviceId deviceName }
+**Custom sender:** Implement `IEmailSender`:
+
+```typescript
+class SmtpEmailSender implements IEmailSender {
+  async send(params: {
+    to: string;
+    from: { email: string; name?: string };
+    subject: string;
+    html: string;
+    text?: string;
+  }) {
+    // your SMTP logic
   }
 }
 ```
 
-## Implementing Custom Lifecycle Hooks
-
-Add custom business logic to authentication events:
+**Custom template renderer:** Override `DefaultEmailTemplateRenderer` by providing `email.templateRenderer`:
 
 ```typescript
-import { Injectable } from '@nestjs/common';
-import { IAuthLifecycleHooks, IAuthUser } from '@yourorg/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}`);
-  }
-
-  async onLogout(user: IAuthUser): Promise<void> {
-    // Clean up sessions, log analytics, etc.
-    console.log(`User logged out: ${user.email}`);
-  }
-
-  async onEmailVerified(user: IAuthUser): Promise<void> {
-    // Send confirmation email, unlock features, etc.
-    console.log(`Email verified: ${user.email}`);
-  }
-
-  async onPasswordReset(user: IAuthUser): Promise<void> {
-    // Log security event, notify user, etc.
-    console.log(`Password reset: ${user.email}`);
-  }
-
-  async onAccountLocked(user: IAuthUser, unlockTime: Date): Promise<void> {
-    // Send notification, log security event, etc.
-    console.log(`Account locked: ${user.email} until ${unlockTime}`);
-  }
-
-  async onSocialAccountLinked(user: IAuthUser, provider: string): Promise<void> {
-    // Send confirmation email, log event, etc.
-    console.log(`${provider} account linked: ${user.email}`);
-  }
-
-  async onSocialAccountUnlinked(user: IAuthUser, provider: string): Promise<void> {
-    // Send confirmation email, log event, etc.
-    console.log(`${provider} account unlinked: ${user.email}`);
-  }
+email: {
+  sender: new SendGridEmailSender(apiKey),
+  from: { email: 'noreply@example.com' },
+  templateRenderer: new MyCustomRenderer(),
 }
 ```
 
-## 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
-
-### Biometric Authentication
-
-- **Public key cryptography**: WebAuthn-compatible
-- **Device enrollment**: Multiple device support
-- **Challenge-response**: Prevents replay attacks
+### Verification Modes
 
-## Security Best Practices
+Two modes for email verification and password reset:
 
-### 🔐 Secret Management
-
-**CRITICAL**: Never commit secrets to version control. Use environment variables and secret management systems.
-
-**Required Secrets:**
-
-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.
-
-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:**
+- **`'code'`** (default) -- 6-digit numeric codes
+- **`'token'`** -- URL-based tokens with configurable base URL
 
 ```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'),
-  }),
-});
-
-// ✅ 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(),
-    }),
-  }),
-});
+features: { verificationMode: 'token' },
+verification: {
+  baseUrl: 'https://app.example.com',
+  tokenLength: 64,          // bytes, default: 64
+  tokenExpiresInMinutes: 60, // default: 60
+},
 ```
 
-### 🛡️ Token Configuration
+### OAuth
 
-**Access Token Best Practices:**
+Google and Facebook OAuth with encrypted token storage (AES-256-GCM).
 
 ```typescript
 AuthModule.forRootAsync({
   useFactory: (config) => ({
-    // Short-lived access tokens (minimize damage if compromised)
-    jwtExpiresIn: '15m',  // Default: 15 minutes
-
-    // For mobile apps with poor connectivity, consider 1h max
-    // jwtExpiresIn: '1h',  // Longer for mobile, but less secure
-
-    // NEVER use long-lived access tokens
-    // jwtExpiresIn: '30d',  // ❌ INSECURE
-  }),
-});
-```
-
-**Refresh Token Best Practices:**
-
-```typescript
-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
+    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'),
+      },
+    },
   }),
-});
+})
 ```
 
-**Token Rotation**: This package automatically rotates refresh tokens on each use. Old tokens are invalidated to prevent replay attacks.
+The `OAuthController` is automatically registered and handles OAuth callback routes. OAuth strategies gracefully degrade to no-ops when credentials are not configured.
 
-### 🔒 Password Policy
+### Brute Force Protection
 
-**Enforce Strong Passwords:**
+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.
 
-The package includes default password validation (8+ characters, uppercase, lowercase, number, special character). For stronger policies:
+### Password Policy
 
 ```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;
+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'] : [],
+    };
+  },
 }
 ```
 
-**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)
-
-### ⏱️ Rate Limiting
+### Lifecycle Hooks
 
-**Configure Throttling:**
+React to auth events without modifying core logic:
 
 ```typescript
-import { ThrottlerModule } from '@nestjs/throttler';
-
-@Module({
-  imports: [
-    // Global rate limiting
-    ThrottlerModule.forRoot([{
-      ttl: 60000,  // 60 seconds
-      limit: 100,  // 100 requests per minute
-    }]),
-
-    AuthModule.forRootAsync({
-      // Auth-specific throttling is handled per-mutation
-      // See AuthResolver for @Throttle() decorators
-    }),
-  ],
-})
+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 */ },
+}
 ```
 
-**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)
-
-**Brute Force Protection**: Enabled by default - 5 failed login attempts = 15-minute account lockout.
+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).
 
-### 🌐 HTTPS/TLS Requirements
+### JWT Validation Modes
 
-**PRODUCTION REQUIREMENT**: All authentication endpoints MUST use HTTPS.
+- **`'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.
 
 ```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);
-}
-bootstrap();
+jwtValidation: 'payload-only',
 ```
 
-**OAuth Callback URLs**: Must be HTTPS in production (required by Google/Facebook).
+### JWT Payload Factory
 
-### 📊 Security Logging
-
-**Implement Custom Security Logger** for production monitoring:
+Customize JWT claims by providing an `IJwtPayloadFactory`:
 
 ```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 });
-    }
-  }
+jwtPayloadFactoryInstance: {
+  createPayload(user) {
+    return { sub: user.id, email: user.email, role: user.role };
+  },
+  extractUserId(payload) {
+    return payload.sub;
+  },
 }
 ```
 
-**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
-
-### 🚀 Production Deployment
+---
 
-**Environment Separation:**
+## Configuration Reference
 
-```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
-```
+### Required Options
 
-**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:**
+| 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` |
 
-```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,
-    },
-  }));
+---
 
-  await app.listen(3000);
-}
-```
+## Decorators
 
-### 🔍 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
-);
-```
+| 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 |
+| `@ResourceScope('resourceType', 'argName')` | Method | Resource-level permission scoping |
 
-#### 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)
-);
-```
+## Guards
 
-#### 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
-);
-```
+| 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`) |
 
-#### 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)
-);
-```
+### Recommended Guard Chains
 
-#### 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)
-);
-```
+```typescript
+// JWT only
+{ provide: APP_GUARD, useClass: createAuthGuard(['jwt'], { allowPublic: true }) }
 
-#### 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)
-);
-```
+// JWT + API keys
+{ provide: APP_GUARD, useClass: createAuthGuard(['jwt', 'api-key'], { allowPublic: true }) }
 
-#### 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)
-);
+// 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 },
 ```
 
-### Option 2: Adapter Pattern (Flexible Schema)
+## Utilities
 
-If your database schema differs from the package expectations, create **adapter repositories** that translate between your schema and the package interfaces.
+Helper functions exported for use in custom guards and middleware:
 
-**Example**: Lift app uses a unified `VerificationCode` table for both email and SMS verification:
+| Function | Description |
+|----------|-------------|
+| `getRequestFromContext(context)` | Extract request from `ExecutionContext` (handles GraphQL + HTTP) |
+| `extractIpAddress(request)` | Extract client IP (checks `clientIp`, `req.ip`, falls back to `'unknown'`) |
 
 ```typescript
+import { getRequestFromContext, extractIpAddress } from '@ambushsoftworks/nestjs-auth-graphql';
+
 @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,
-      },
-    });
+export class CustomGuard implements CanActivate {
+  canActivate(context: ExecutionContext): boolean {
+    const request = getRequestFromContext(context);
+    const ip = extractIpAddress(request);
+    // your logic
+    return true;
   }
-
-  // Implement other methods with similar adapter logic...
 }
 ```
 
-**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.
-
-## Environment Variables
-
-```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
-```
-
-## 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
-```
-
-## Architecture
-
-This package follows **Layer 0 architecture** with complete interface abstraction:
-
-- **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
-
-## Migration from Lift Codebase
-
-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
 
 ## License
 
-MIT
-
-## Support
-
-For issues and questions, please open an issue on GitLab.
+MIT -- see [LICENSE](./LICENSE).