@nauth-toolkit/core 0.1.0 → 0.1.3

package/src/interfaces/oauth.interface.ts

@@ -1,148 +0,0 @@
-/**
- * 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

@@ -1,47 +0,0 @@
-/**
- * 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

@@ -1,131 +0,0 @@
-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

@@ -1,82 +0,0 @@
-/**
- * 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>;
-}