@vynelix/nestjs-multi-auth 0.3.2 → 1.0.1

package/prompts/otp_provider.md

@@ -0,0 +1,292 @@
+# Refactor OTP Architecture — nestjs-multi-auth
+
+## Context
+
+You are working on **nestjs-multi-auth**, a production-grade authentication library for NestJS.
+
+## Objective
+
+Refactor the OTP architecture to separate OTP lifecycle management from notification delivery, while maintaining full backward compatibility.
+
+## Problem
+
+The current implementation assumes the library always:
+
+1. Generates the OTP
+2. Stores it in the database
+3. Passes the generated code to `AuthNotificationProvider.sendVerificationCode()`
+
+This assumption prevents integration with providers like **Twilio Verify**, **Firebase Phone Authentication**, **Vonage Verify**, and **MessageBird Verify**, because these services generate, store, expire, and validate OTPs themselves — the raw code is never exposed to the library.
+
+The authentication library must support both:
+
+- **Internal database-managed OTPs** (current behavior)
+- **External OTP providers** (Twilio Verify, Firebase Phone, etc.)
+
+...without changing the public authentication API.
+
+---
+
+## Design Principles
+
+### The authentication library IS responsible for
+
+- Authentication
+- Authorization
+- Identity verification workflow
+- Session management
+- Password reset
+- Email verification
+- Phone verification
+- MFA orchestration
+
+### The authentication library is NOT responsible for
+
+- SMS delivery
+- Email delivery
+- Push notifications
+- WhatsApp
+- OTP transport
+
+Notification delivery remains the responsibility of the consuming application.
+
+---
+
+## New Architecture
+
+Split the current OTP implementation into two abstractions.
+
+### 1. `AuthOtpProvider` (NEW)
+
+Responsible for the **lifecycle** of an OTP: generate, store, validate, resend, expire.
+
+**Example implementations:**
+
+- `DatabaseOtpProvider`
+- `TwilioVerifyOtpProvider`
+- `FirebasePhoneOtpProvider`
+- `CustomOtpProvider`
+
+**Interface:**
+
+```typescript
+export interface AuthOtpProvider {
+  issue(request: IssueOtpRequest): Promise<IssueOtpResult>;
+  verify(request: VerifyOtpRequest): Promise<VerifyOtpResult>;
+  resend?(request: ResendOtpRequest): Promise<ResendOtpResult>;
+}
+```
+
+**`IssueOtpRequest`** — should contain enough information for any provider:
+
+```typescript
+{
+  uid,
+  authId,
+  identifier,
+  identifierType,
+  purpose,
+  expiresIn
+}
+```
+
+**`IssueOtpResult`** — must support both internal and external providers.
+
+For database providers:
+
+```typescript
+{
+  handledDelivery: false,
+  code: "483921",
+  expiresAt: Date
+}
+```
+
+For Twilio Verify:
+
+```typescript
+{
+  handledDelivery: true,
+  verificationId: "...",
+  expiresAt: Date | undefined
+}
+```
+
+> **Note:** External providers will not return the OTP.
+
+**`VerifyOtpResult`** — should be provider-independent:
+
+```typescript
+{
+  success: true,
+  metadata?: {}
+}
+```
+
+### 2. `AuthNotificationProvider` (existing — to be improved)
+
+Keep the notification provider, but enrich its signature.
+
+**Current:**
+
+```typescript
+sendVerificationCode(to, code, type)
+```
+
+**Replace with:**
+
+```typescript
+sendVerificationCode({
+  to,
+  code,
+  type,
+  purpose,
+  expiresAt
+})
+```
+
+This lets applications customize messages based on purpose (email verification, phone verification, password reset, login verification, etc.)
+
+> The notification provider should **never** know where the OTP came from.
+
+---
+
+## Default OTP Provider
+
+Create a built-in provider named `DatabaseOtpProvider`.
+
+Move all current logic from:
+
+- `sendVerification()`
+- `forgotPassword()`
+- `resetPassword()`
+- `verifyCode()`
+- `resendVerification()`
+
+...into this provider. It must preserve current behavior exactly:
+
+- Generate OTP
+- Hash OTP
+- Store hash
+- Handle expiration
+- Resend logic
+- Verification logic
+
+**Nothing should change functionally.**
+
+---
+
+## Twilio Verify Support
+
+Design the architecture so that implementing `TwilioVerifyOtpProvider` requires **no changes to `AuthService`**.
+
+**`issue()` flow:**
+
+```
+issue()
+  → Call Twilio Verify
+  → Twilio generates OTP
+  → Twilio stores OTP
+  → Twilio sends SMS
+  → Return { handledDelivery: true, verificationId }
+```
+
+**`verify()` flow:**
+
+```
+verify()
+  → Call Twilio Verify Check
+  → Return success
+```
+
+> Twilio Verify never exposes the OTP — the library must support this.
+
+---
+
+## `AuthService` Changes
+
+Replace all direct OTP generation with `otpProvider.issue(...)`.
+
+**Before:**
+
+```
+generate OTP → hash → save → notificationProvider.send(...)
+```
+
+**After:**
+
+```typescript
+const result = await otpProvider.issue(...);
+
+if (!result.handledDelivery) {
+  await notificationProvider.sendVerificationCode(...);
+}
+```
+
+The authentication flow should **not** know whether the OTP came from the database, Twilio, Firebase, or a custom provider.
+
+Replace every direct OTP verification with:
+
+```typescript
+await otpProvider.verify(...);
+```
+
+`AuthService` should **never** call `bcrypt.compare()` directly anymore — that logic belongs inside `DatabaseOtpProvider`.
+
+---
+
+## Existing Features (must keep working, no breaking changes)
+
+- Signup verification
+- Login verification
+- Resend verification
+- Forgot password
+- Password reset
+- Secure account
+- Magic link
+- MFA
+- Passwordless authentication
+
+---
+
+## OTP Purposes
+
+Continue using the existing enum:
+
+- `VERIFY_EMAIL`
+- `VERIFY_PHONE`
+- `PASSWORD_RESET`
+- `MAGIC_LINK`
+- `SECURE_ACCOUNT`
+
+Providers should receive the purpose.
+
+---
+
+## Dependency Injection
+
+Introduce `AUTH_OTP_PROVIDER`, similar to `AUTH_NOTIFICATION_PROVIDER`.
+
+If no provider is registered, automatically register `DatabaseOtpProvider` so existing users do not need to change anything.
+
+---
+
+## Backward Compatibility
+
+This refactor must **not** break existing applications.
+
+- Applications that already implement `AuthNotificationProvider` should continue working exactly as before.
+- Only developers who wish to use Twilio Verify or another external OTP provider need to implement `AuthOtpProvider`.
+
+---
+
+## Code Quality Requirements
+
+- Follow SOLID principles.
+- Separate orchestration from provider implementations.
+- Avoid duplicating OTP logic between `AuthService` and providers.
+- Keep `AuthService` focused on authentication workflows, not OTP implementation details.
+- Use dependency injection throughout.
+- Ensure each provider is independently unit testable.
+- Preserve all current tests and behavior where possible.
+- Keep public authentication endpoints unchanged — only the internal OTP architecture should be refactored.

package/scratch/create-prisma-repos-final.js

@@ -0,0 +1,139 @@
+const fs = require('fs');
+const path = require('path');
+
+const repoDir = path.join(__dirname, '../src/database/prisma/repositories');
+
+const files = {
+  'auth.repository.ts': `
+import { Injectable, Inject } from '@nestjs/common';
+import { AuthRepository } from '../../../auth/interfaces/repositories.interface';
+import { Auth as CoreAuth } from '../../../auth/interfaces/models.interface';
+import { AuthStrategy } from '../../../auth/enums/auth-type.enum';
+
+@Injectable()
+export class PrismaAuthRepository implements AuthRepository {
+  constructor(@Inject('PRISMA_SERVICE_TOKEN') private readonly prisma: any) {}
+
+  async create(data: Partial<CoreAuth>): Promise<CoreAuth> {
+    const { identifiers, ...rest } = data;
+    return this.prisma.auth.create({
+      data: {
+        ...rest,
+        identifiers: identifiers ? { create: identifiers } : undefined,
+      } as any,
+      include: { identifiers: true }
+    });
+  }
+
+  async findById(id: string): Promise<CoreAuth | null> { return this.prisma.auth.findUnique({ where: { id }, include: { identifiers: true } }); }
+  async findByUid(uid: string): Promise<CoreAuth | null> { return this.prisma.auth.findUnique({ where: { uid }, include: { identifiers: true } }); }
+  async findAllByUid(uid: string): Promise<CoreAuth[]> { return this.prisma.auth.findMany({ where: { uid } }); }
+  async findAll(): Promise<CoreAuth[]> { return this.prisma.auth.findMany(); }
+  async findByUidAndStrategy(uid: string, strategy: AuthStrategy): Promise<CoreAuth | null> { return this.prisma.auth.findFirst({ where: { uid, strategy } }); }
+  async findByUidAndStrategies(uid: string, strategies: AuthStrategy[]): Promise<CoreAuth | null> { return this.prisma.auth.findFirst({ where: { uid, strategy: { in: strategies } } }); }
+  async save(auth: CoreAuth): Promise<CoreAuth> { return this.prisma.auth.update({ where: { id: auth.id }, data: auth as any }); }
+  async update(id: string, data: Partial<CoreAuth>): Promise<void> { await this.prisma.auth.update({ where: { id }, data: data as any }); }
+  async delete(id: string): Promise<void> { await this.prisma.auth.delete({ where: { id } }); }
+  async deleteByUid(uid: string): Promise<void> { await this.prisma.auth.deleteMany({ where: { uid } }); }
+  async findWithIdentifiers(id: string): Promise<CoreAuth | null> { return this.prisma.auth.findUnique({ where: { id }, include: { identifiers: true } }); }
+}
+`,
+
+  'auth-identifier.repository.ts': `
+import { Injectable, Inject } from '@nestjs/common';
+import { AuthIdentifierRepository } from '../../../auth/interfaces/repositories.interface';
+import { AuthIdentifier as CoreAuthIdentifier, Auth as CoreAuth } from '../../../auth/interfaces/models.interface';
+
+@Injectable()
+export class PrismaAuthIdentifierRepository implements AuthIdentifierRepository {
+  constructor(@Inject('PRISMA_SERVICE_TOKEN') private readonly prisma: any) {}
+
+  async create(data: Partial<CoreAuthIdentifier>): Promise<CoreAuthIdentifier> { return this.prisma.authIdentifier.create({ data: data as any }); }
+  async findByValue(value: string): Promise<CoreAuthIdentifier | null> { return this.prisma.authIdentifier.findUnique({ where: { value } }); }
+  async findByAuthId(authId: string): Promise<CoreAuthIdentifier[]> { return this.prisma.authIdentifier.findMany({ where: { authId } }); }
+  async findByUidAndTypes(uid: string, types: string[]): Promise<CoreAuthIdentifier | null> { return this.prisma.authIdentifier.findFirst({ where: { auth: { uid }, type: { in: types } }}); }
+  
+  async findWithAuthByValue(value: string): Promise<{ identifier: CoreAuthIdentifier; auth: CoreAuth } | null> {
+    const res = await this.prisma.authIdentifier.findUnique({ where: { value }, include: { auth: true } });
+    if (!res) return null;
+    const { auth, ...identifier } = res;
+    return { identifier: identifier as any, auth: auth as any };
+  }
+  
+  async save(identifier: CoreAuthIdentifier): Promise<CoreAuthIdentifier> { return this.prisma.authIdentifier.update({ where: { id: identifier.id }, data: identifier as any }); }
+  async markVerifiedByAuthId(authId: string): Promise<void> { await this.prisma.authIdentifier.updateMany({ where: { authId }, data: { isVerified: true } }); }
+}
+`,
+
+  'mfa-method.repository.ts': `
+import { Injectable, Inject } from '@nestjs/common';
+import { MfaMethodRepository } from '../../../auth/interfaces/repositories.interface';
+import { MfaMethod as CoreMfaMethod } from '../../../auth/interfaces/models.interface';
+
+@Injectable()
+export class PrismaMfaMethodRepository implements MfaMethodRepository {
+  constructor(@Inject('PRISMA_SERVICE_TOKEN') private readonly prisma: any) {}
+
+  async create(data: Partial<CoreMfaMethod>): Promise<CoreMfaMethod> { return this.prisma.mfaMethod.create({ data: data as any }); }
+  async findByUidAndType(uid: string, type: string): Promise<CoreMfaMethod | null> { return this.prisma.mfaMethod.findFirst({ where: { auth: { uid }, type } }); }
+  async findByUidAndEnabled(uid: string): Promise<CoreMfaMethod | null> { return this.prisma.mfaMethod.findFirst({ where: { auth: { uid }, isEnabled: true } }); }
+  async save(method: CoreMfaMethod): Promise<CoreMfaMethod> { return this.prisma.mfaMethod.update({ where: { id: method.id }, data: method as any }); }
+  async deleteByUid(uid: string): Promise<void> { await this.prisma.mfaMethod.deleteMany({ where: { auth: { uid } } }); }
+}
+`,
+
+  'oauth-provider.repository.ts': `
+import { Injectable, Inject } from '@nestjs/common';
+import { OAuthProviderRepository } from '../../../auth/interfaces/repositories.interface';
+import { OAuthProvider as CoreOAuthProvider, Auth as CoreAuth } from '../../../auth/interfaces/models.interface';
+
+@Injectable()
+export class PrismaOAuthProviderRepository implements OAuthProviderRepository {
+  constructor(@Inject('PRISMA_SERVICE_TOKEN') private readonly prisma: any) {}
+
+  async create(data: Partial<CoreOAuthProvider>): Promise<CoreOAuthProvider> { return this.prisma.oAuthProvider.create({ data: data as any }); }
+  async findByProviderUserId(provider: string, providerUserId: string): Promise<CoreOAuthProvider | null> { return this.prisma.oAuthProvider.findUnique({ where: { providerUserId } }); }
+  
+  async findWithAuthByProviderUserId(provider: string, providerUserId: string): Promise<{ provider: CoreOAuthProvider; auth: CoreAuth } | null> {
+    const res = await this.prisma.oAuthProvider.findUnique({ where: { providerUserId }, include: { auth: true } });
+    if (!res) return null;
+    const { auth, ...prov } = res;
+    return { provider: prov as any, auth: auth as any };
+  }
+
+  async save(provider: CoreOAuthProvider): Promise<CoreOAuthProvider> { return this.prisma.oAuthProvider.update({ where: { id: provider.id }, data: provider as any }); }
+  async update(id: string, data: Partial<CoreOAuthProvider>): Promise<void> { await this.prisma.oAuthProvider.update({ where: { id }, data: data as any }); }
+}
+`,
+
+  'session.repository.ts': `
+import { Injectable, Inject } from '@nestjs/common';
+import { SessionRepository } from '../../../auth/interfaces/repositories.interface';
+import { Session as CoreSession } from '../../../auth/interfaces/models.interface';
+
+@Injectable()
+export class PrismaSessionRepository implements SessionRepository {
+  constructor(@Inject('PRISMA_SERVICE_TOKEN') private readonly prisma: any) {}
+
+  async create(data: Partial<CoreSession>): Promise<CoreSession> { return this.prisma.session.create({ data: data as any }); }
+  async findById(id: string): Promise<CoreSession | null> { return this.prisma.session.findUnique({ where: { id } }); }
+  async findDeviceSession(uid: string, namespace: string | undefined, deviceFingerprint: string): Promise<CoreSession | null> {
+    // simplified lookup since Prisma cannot easily query inside Json without raw queries across different DBs.
+    return this.prisma.session.findFirst({ where: { uid } }); 
+  }
+  async findByUid(uid: string): Promise<CoreSession[]> { return this.prisma.session.findMany({ where: { uid } }); }
+  async findByIdWithDetails(id: string, namespace?: string): Promise<CoreSession | null> { return this.prisma.session.findUnique({ where: { id } }); }
+  async save(session: CoreSession): Promise<CoreSession> { return this.prisma.session.update({ where: { id: session.id }, data: session as any }); }
+  async update(id: string, data: Partial<CoreSession>): Promise<void> { await this.prisma.session.update({ where: { id }, data: data as any }); }
+  async delete(id: string): Promise<void> { await this.prisma.session.delete({ where: { id } }); }
+  async deleteByUid(uid: string): Promise<void> { await this.prisma.session.deleteMany({ where: { uid } }); }
+  async transaction(runInTransaction: (repo: SessionRepository) => Promise<void>): Promise<void> { await runInTransaction(this); }
+}
+`
+};
+
+for (const [filename, content] of Object.entries(files)) {
+  fs.writeFileSync(path.join(repoDir, filename), content.trim(), 'utf8');
+}
+
+console.log('Fixed Prisma repositories completely');