@nauth-toolkit/core 0.1.0

package/src/interfaces/oauth.interface.ts

@@ -0,0 +1,148 @@
+/**
+ * OAuth User Profile Interface
+ * Standardized user profile data from OAuth providers
+ *
+ * @example
+ * ```typescript
+ * const profile: OAuthUserProfile = {
+ *   id: 'google_123',
+ *   email: 'user@gmail.com',
+ *   firstName: 'John',
+ *   lastName: 'Doe',
+ *   picture: 'https://...',
+ *   verified: true
+ * };
+ * ```
+ */
+export interface OAuthUserProfile {
+  /**
+   * Provider's unique identifier for the user
+   * Examples: Google sub, Apple user ID, Facebook ID
+   */
+  id: string;
+
+  /**
+   * User's email address
+   * May be null if not provided by provider
+   */
+  email?: string | null;
+
+  /**
+   * User's first name
+   * May be null if not provided by provider
+   */
+  firstName?: string | null;
+
+  /**
+   * User's last name
+   * May be null if not provided by provider
+   */
+  lastName?: string | null;
+
+  /**
+   * User's profile picture URL
+   * May be null if not provided by provider
+   */
+  picture?: string | null;
+
+  /**
+   * Whether the email is verified by the provider
+   * @default false
+   */
+  verified?: boolean;
+
+  /**
+   * Additional provider-specific data
+   * Contains raw response from OAuth provider
+   */
+  raw?: Record<string, unknown>;
+}
+
+/**
+ * OAuth Client Interface
+ * Defines the contract for OAuth provider clients
+ *
+ * @example
+ * ```typescript
+ * class GoogleOAuthClient implements OAuthClient {
+ *   async getUserProfile(accessToken: string): Promise<OAuthUserProfile> {
+ *     // Implementation for Google
+ *   }
+ * }
+ * ```
+ */
+export interface OAuthClient {
+  /**
+   * Get user profile from OAuth provider using access token
+   *
+   * @param accessToken - OAuth access token
+   * @returns User profile data
+   * @throws {Error} When API call fails or token is invalid
+   *
+   * @example
+   * ```typescript
+   * const profile = await oauthClient.getUserProfile(accessToken);
+   * console.log(profile.email); // user@example.com
+   * ```
+   */
+  getUserProfile(accessToken: string): Promise<OAuthUserProfile>;
+
+  /**
+   * Exchange authorization code for access token
+   *
+   * @param code - Authorization code from OAuth callback
+   * @param redirectUri - Redirect URI used in OAuth flow
+   * @returns Access token and optional refresh token
+   * @throws {Error} When token exchange fails
+   *
+   * @example
+   * ```typescript
+   * const tokens = await oauthClient.exchangeCodeForToken(code, redirectUri);
+   * console.log(tokens.accessToken); // access_token_here
+   * ```
+   */
+  exchangeCodeForToken(
+    code: string,
+    redirectUri: string,
+  ): Promise<{
+    accessToken: string;
+    refreshToken?: string;
+    expiresIn?: number;
+  }>;
+}
+
+/**
+ * OAuth Configuration Interface
+ * Configuration for OAuth clients
+ *
+ * @example
+ * ```typescript
+ * const config: OAuthConfig = {
+ *   clientId: 'google_client_id',
+ *   clientSecret: 'google_client_secret',
+ *   redirectUri: 'https://myapp.com/auth/google/callback'
+ * };
+ * ```
+ */
+export interface OAuthConfig {
+  /**
+   * OAuth client ID
+   */
+  clientId: string;
+
+  /**
+   * OAuth client secret
+   */
+  clientSecret: string;
+
+  /**
+   * OAuth redirect URI
+   */
+  redirectUri: string;
+
+  /**
+   * OAuth scopes
+   * @default ['openid', 'email', 'profile']
+   */
+  scopes?: string[];
+}

package/src/interfaces/provider.interface.ts

@@ -0,0 +1,47 @@
+/**
+ * Email provider interface for sending emails
+ */
+export interface EmailProvider {
+  /**
+   * Send email verification code/link
+   * @param to - Recipient email address
+   * @param code - Verification code (e.g., "123456")
+   * @param link - Optional verification link (only sent if provided by consumer app)
+   */
+  sendVerificationEmail(to: string, code: string, link?: string): Promise<void>;
+
+  /**
+   * Send password reset email
+   */
+  sendPasswordResetEmail(to: string, token: string, link: string): Promise<void>;
+
+  /**
+   * Send welcome email
+   */
+  sendWelcomeEmail(to: string, name: string): Promise<void>;
+
+  /**
+   * Send account lockout notification
+   */
+  sendLockoutEmail?(to: string, reason: string, duration: number): Promise<void>;
+
+  /**
+   * Send new device login notification
+   */
+  sendNewDeviceEmail?(to: string, deviceInfo: any, location?: any): Promise<void>;
+}
+
+/**
+ * SMS provider interface for sending text messages
+ */
+export interface SMSProvider {
+  /**
+   * Send OTP code via SMS
+   */
+  sendOTP(phone: string, code: string): Promise<void>;
+
+  /**
+   * Send verification code
+   */
+  sendVerificationCode?(phone: string, code: string): Promise<void>;
+}

package/src/interfaces/social-auth-provider.interface.ts

@@ -0,0 +1,131 @@
+import { AuthResponseDTO } from '../dto';
+import { OAuthUserProfile } from '../interfaces/oauth.interface';
+
+/**
+ * Social Auth Provider Service Interface
+ *
+ * Defines the contract for social authentication provider services.
+ * Each provider (Google, Apple, Facebook, etc.) must implement this interface
+ * to be registered with the core SocialAuthService.
+ *
+ * This allows for:
+ * - Modular provider imports (only install what you need)
+ * - Consistent API across all providers
+ * - Proper NestJS dependency injection
+ * - Easy addition of new providers without modifying core code
+ *
+ * @example
+ * ```typescript
+ * @Injectable()
+ * export class GoogleSocialAuthService implements ISocialAuthProviderService {
+ *   readonly providerName = 'google';
+ *
+ *   async getAuthUrl(state?: string): Promise<string> {
+ *     // Generate Google OAuth URL
+ *   }
+ *
+ *   async handleCallback(code: string, state: string): Promise<AuthResponseDTO> {
+ *     // Handle Google OAuth callback
+ *   }
+ *
+ *   async verifyToken(idToken: string, accessToken?: string, profileData?: any): Promise<AuthResponseDTO> {
+ *     // Verify Google ID token
+ *   }
+ * }
+ * ```
+ */
+export interface ISocialAuthProviderService {
+  /**
+   * Provider name (e.g., 'google', 'apple', 'facebook')
+   * Used as the key in the provider registry
+   */
+  readonly providerName: string;
+
+  /**
+   * Generate OAuth authorization URL for this provider
+   *
+   * @param state - Optional state parameter for CSRF protection
+   * @returns Authorization URL to redirect user to
+   * @throws {BadRequestException} When provider is not properly configured
+   *
+   * @example
+   * ```typescript
+   * const authUrl = await provider.getAuthUrl('random-state-123');
+   * // Redirect user to authUrl
+   * ```
+   */
+  getAuthUrl(state?: string): Promise<string>;
+
+  /**
+   * Handle OAuth callback and authenticate user
+   *
+   * Exchanges authorization code for access token, fetches user profile,
+   * and returns unified authentication response with JWT tokens.
+   *
+   * @param code - Authorization code from OAuth callback
+   * @param state - State parameter from OAuth callback (for CSRF protection)
+   * @returns Unified authentication response with tokens and user info
+   * @throws {BadRequestException} When callback is invalid
+   *
+   * @example
+   * ```typescript
+   * const result = await provider.handleCallback(code, state);
+   * console.log(result.accessToken); // JWT access token
+   * console.log(result.user.email); // User email
+   * ```
+   */
+  handleCallback(code: string, state: string): Promise<AuthResponseDTO>;
+
+  /**
+   * Verify social authentication token from native mobile apps
+   *
+   * Handles authentication tokens from native mobile apps (iOS/Android)
+   * that use native SDKs (Google Sign-In SDK, Apple Sign In, etc.)
+   *
+   * @param idToken - ID token from native SDK
+   * @param accessToken - Optional access token from native SDK
+   * @param profileData - Optional profile data from native SDK (for name extraction)
+   * @returns Unified authentication response with tokens and user info
+   * @throws {BadRequestException} When token is invalid
+   *
+   * @example
+   * ```typescript
+   * const result = await provider.verifyToken(idToken, accessToken, profileData);
+   * return result; // Same format as login/signup
+   * ```
+   */
+  verifyToken(idToken: string, accessToken?: string, profileData?: any): Promise<AuthResponseDTO>;
+
+  /**
+   * Link social account to existing user
+   *
+   * Used when an authenticated user wants to link a social account
+   * to their existing account.
+   *
+   * @param userId - User ID (sub)
+   * @param code - Authorization code from OAuth callback
+   * @param state - State parameter from OAuth callback
+   * @returns Success message
+   * @throws {NotFoundException} When user is not found
+   * @throws {ConflictException} When account is already linked
+   *
+   * @example
+   * ```typescript
+   * await provider.linkAccount(userId, code, state);
+   * ```
+   */
+  linkAccount(userId: string, code: string, state: string): Promise<{ message: string }>;
+
+  /**
+   * Get OAuth user profile from callback
+   *
+   * Internal method used by handleCallback to extract user profile.
+   * Exposed for advanced use cases.
+   *
+   * @param code - Authorization code from OAuth callback
+   * @param state - State parameter from OAuth callback
+   * @returns OAuth user profile
+   * @private
+   */
+  getUserProfileFromCallback(code: string, state: string): Promise<OAuthUserProfile>;
+}

package/src/interfaces/storage-adapter.interface.ts

@@ -0,0 +1,82 @@
+/**
+ * Storage adapter interface for shared state management
+ * Critical for multi-server deployments
+ */
+export interface StorageAdapter {
+  /**
+   * Initialize the storage adapter
+   */
+  initialize(): Promise<void>;
+
+  /**
+   * Check if adapter is healthy
+   */
+  isHealthy(): Promise<boolean>;
+
+  /**
+   * Basic key-value operations
+   */
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string, ttlSeconds?: number, options?: { nx?: boolean }): Promise<string | null | void>;
+  del(key: string): Promise<void>;
+  exists(key: string): Promise<boolean>;
+
+  /**
+   * Atomic operations
+   */
+  incr(key: string, ttlSeconds?: number): Promise<number>;
+  decr(key: string): Promise<number>;
+  expire(key: string, ttl: number): Promise<void>;
+  ttl(key: string): Promise<number>;
+
+  /**
+   * Hash operations (for complex data structures)
+   */
+  hget(key: string, field: string): Promise<string | null>;
+  hset(key: string, field: string, value: string): Promise<void>;
+  hgetall(key: string): Promise<Record<string, string>>;
+  hdel(key: string, ...fields: string[]): Promise<number>;
+
+  /**
+   * List operations (for token families)
+   */
+  lpush(key: string, value: string): Promise<void>;
+  lrange(key: string, start: number, stop: number): Promise<string[]>;
+  llen(key: string): Promise<number>;
+
+  /**
+   * Pattern operations
+   */
+  keys(pattern: string): Promise<string[]>;
+  scan(cursor: number, pattern: string, count: number): Promise<[number, string[]]>;
+
+  /**
+   * Cleanup and disconnect
+   */
+  cleanup(): Promise<void>;
+  disconnect(): Promise<void>;
+}
+
+/**
+ * Rate limiting specific operations
+ */
+export interface RateLimitStorage {
+  incrementRateLimit(identifier: string, endpoint: string, windowMs: number): Promise<number>;
+  getRateLimit(identifier: string, endpoint: string): Promise<number>;
+  resetRateLimit(identifier: string, endpoint: string): Promise<void>;
+}
+
+/**
+ * Account lockout specific operations
+ *
+ * SECURITY: Uses IP addresses instead of user identifiers to prevent
+ * attackers from locking out legitimate users by guessing their email/username.
+ */
+export interface AccountLockoutStorage {
+  recordFailedAttempt(ipAddress: string): Promise<number>;
+  getFailedAttempts(ipAddress: string): Promise<number>;
+  isAccountLocked(ipAddress: string): Promise<boolean>;
+  blockIpAdresss(ipAddress: string, duration: number, reason: string): Promise<void>;
+  unblockIPAdress(ipAddress: string): Promise<void>;
+  resetFailedAttempts(ipAddress: string): Promise<void>;
+}