@ambushsoftworks/nestjs-auth-graphql 0.2.0 → 0.3.0

package/README.md

@@ -25,6 +25,7 @@ Production-grade authentication package for NestJS with GraphQL, extracted from
 - **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
@@ -253,6 +254,93 @@ export class AuthResolver extends BaseAuthResolver<User> {
 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`:
+
+```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
+      },
+    }),
+  );
+
+  await app.listen(3000);
+}
+bootstrap();
+```
+
+**What gets validated:**
+
+The package validates all input fields with appropriate decorators:
+
+- **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
+
+**Validation error responses:**
+
+When validation fails, NestJS automatically returns a `400 Bad Request` with detailed error messages:
+
+```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"
+}
+```
+
+**Custom validation for your DTOs:**
+
+If you create your own input DTOs implementing the package interfaces (recommended for full type control), add `class-validator` decorators:
+
+```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;
+}
+```
+
+**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.
+
 ## Configuration Options
 
 ### Required Options
@@ -370,6 +458,308 @@ import { NoOpEmailService, NoOpSmsService } from '@yourorg/nestjs-auth-graphql';
 })
 ```
 
+## 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
+
+#### 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
+}
+```
+
+#### Step 2: Configure Email Service
+
+Ensure `SendGridEmailService` (or your custom email service) is configured:
+
+```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
+    },
+  }),
+}),
+```
+
+**Environment Variable:**
+```bash
+FRONTEND_URL=https://yourapp.com  # Used in email branding
+```
+
+#### Step 3: Create GraphQL DTOs
+
+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;
+}
+```
+
+**`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;
+
+  @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>;
+  }
+}
+```
+
+#### Step 5: Deploy & Test
+
+```bash
+# Run migration
+npx prisma migrate deploy
+
+# Start dev server
+npm run start:dev
+
+# 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 } }"}'
+```
+
+### GraphQL Schema
+
+After setup, your schema will include:
+
+```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
+}
+```
+
+### 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):**
+
+```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');
+  }
+}
+```
+
+### 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:
+
+```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);
+  }
+}
+```
+
 ## GraphQL API
 
 The package provides a complete GraphQL API:
@@ -426,6 +816,23 @@ mutation VerifyPhone($input: VerifyPhoneInput!) {
   }
 }
 
+# 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) {
@@ -561,6 +968,358 @@ export class MyAuthHooks implements IAuthLifecycleHooks {
 - **Device enrollment**: Multiple device support
 - **Challenge-response**: Prevents replay attacks
 
+## Security Best Practices
+
+### 🔐 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:**
+
+```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(),
+    }),
+  }),
+});
+```
+
+### 🛡️ Token Configuration
+
+**Access Token Best Practices:**
+
+```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
+  }),
+});
+```
+
+**Token Rotation**: This package automatically rotates refresh tokens on each use. Old tokens are invalidated to prevent replay attacks.
+
+### 🔒 Password Policy
+
+**Enforce Strong Passwords:**
+
+The package includes default password validation (8+ characters, uppercase, lowercase, number, special character). For stronger policies:
+
+```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;
+}
+```
+
+**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
+
+**Configure Throttling:**
+
+```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
+    }),
+  ],
+})
+```
+
+**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.
+
+### 🌐 HTTPS/TLS Requirements
+
+**PRODUCTION REQUIREMENT**: All authentication endpoints MUST use HTTPS.
+
+```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();
+```
+
+**OAuth Callback URLs**: Must be HTTPS in production (required by Google/Facebook).
+
+### 📊 Security Logging
+
+**Implement Custom Security Logger** for production monitoring:
+
+```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 });
+    }
+  }
+}
+```
+
+**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:**
+
+```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
+```
+
+**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:**
+
+```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);
+}
+```
+
+### 🔍 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: