@lenan-soft/auth 1.0.1

package/dist/nestjs/index.d.ts

@@ -0,0 +1,510 @@
+import * as _nestjs_common from '@nestjs/common';
+import { Type, DynamicModule, ExecutionContext } from '@nestjs/common';
+import { JwtService } from '@nestjs/jwt';
+import * as rxjs from 'rxjs';
+import * as _nestjs_passport from '@nestjs/passport';
+import { Reflector } from '@nestjs/core';
+import * as passport_jwt from 'passport-jwt';
+import { Strategy } from 'passport-jwt';
+import { Request as Request$1 } from 'express';
+
+/**
+ * JWT payload structure
+ */
+interface JwtPayload {
+    /** User ID (subject) */
+    sub: string;
+    /** User email */
+    email: string;
+    /** Issued at timestamp */
+    iat?: number;
+    /** Expiration timestamp */
+    exp?: number;
+}
+/**
+ * Token response containing access and refresh tokens
+ */
+interface AuthTokens {
+    /** Short-lived access token */
+    accessToken: string;
+    /** Long-lived refresh token */
+    refreshToken: string;
+}
+/**
+ * Base user interface - minimal fields required by the auth system
+ * Consumers should extend this with their own user properties
+ */
+interface BaseUser {
+    /** Unique user identifier */
+    id: string;
+    /** User email address */
+    email: string;
+}
+/**
+ * Full auth user interface combining all auth-related fields
+ */
+interface AuthUser extends BaseUser {
+    passwordHash: string;
+    hashedRefreshToken: string | null;
+}
+/**
+ * Login credentials
+ */
+interface LoginCredentials {
+    email: string;
+    password: string;
+}
+/**
+ * Registration data
+ */
+interface RegisterData {
+    email: string;
+    password: string;
+}
+
+/**
+ * User service interface that consumers must implement
+ * This is the contract between the auth library and your application's user management
+ */
+interface UserServiceInterface<TUser extends AuthUser = AuthUser> {
+    /**
+     * Find a user by their email address
+     * Used during login to validate credentials
+     */
+    findByEmail(email: string): Promise<TUser | null>;
+    /**
+     * Find a user by their ID
+     * Used for token validation and user retrieval
+     */
+    findById(id: string): Promise<TUser | null>;
+    /**
+     * Create a new user with hashed password
+     * Called during registration
+     */
+    createUser(data: {
+        email: string;
+        passwordHash: string;
+    }): Promise<TUser>;
+    /**
+     * Update the user's hashed refresh token
+     * Called after login/refresh to store the new refresh token
+     * Pass null to clear the token (logout)
+     */
+    updateRefreshToken(userId: string, hashedToken: string | null): Promise<void>;
+    /**
+     * Validate that the provided refresh token matches the stored one
+     * Should compare hashed values
+     */
+    validateRefreshToken(userId: string, hashedToken: string): Promise<boolean>;
+}
+/**
+ * Injection token for the user service
+ */
+declare const LENAN_USER_SERVICE: unique symbol;
+/**
+ * Configuration options for the auth module
+ */
+interface AuthModuleOptions {
+    /** Secret key for signing JWT access tokens */
+    jwtSecret: string;
+    /** Access token expiration time (e.g., '15m', '1h') */
+    jwtAccessExpiry?: string;
+    /** Refresh token expiration time (e.g., '7d', '30d') */
+    jwtRefreshExpiry?: string;
+    /** Optional separate secret for refresh tokens (defaults to jwtSecret + '_refresh') */
+    jwtRefreshSecret?: string;
+    /** Whether to register the default AuthController (default: true) */
+    useController?: boolean;
+    /** Global route prefix for auth endpoints (default: 'auth') */
+    routePrefix?: string;
+}
+/**
+ * Async configuration options for the auth module
+ */
+interface AuthModuleAsyncOptions {
+    /**
+     * Imports required for the factory/useClass
+     */
+    imports?: any[];
+    /**
+     * Factory function to create the options
+     */
+    useFactory?: (...args: any[]) => Promise<AuthModuleOptions> | AuthModuleOptions;
+    /**
+     * Dependencies to inject into the factory
+     */
+    inject?: any[];
+    /**
+     * Class that implements AuthOptionsFactory
+     */
+    useClass?: new (...args: any[]) => AuthOptionsFactory;
+    /**
+     * Existing provider to use
+     */
+    useExisting?: new (...args: any[]) => AuthOptionsFactory;
+}
+/**
+ * Factory interface for creating auth options
+ */
+interface AuthOptionsFactory {
+    createAuthOptions(): Promise<AuthModuleOptions> | AuthModuleOptions;
+}
+/**
+ * Injection token for auth module options
+ */
+declare const LENAN_AUTH_OPTIONS: unique symbol;
+/**
+ * Request with user attached (after authentication)
+ */
+interface AuthenticatedRequest<TUser extends BaseUser = BaseUser> extends Request {
+    user: TUser;
+}
+/**
+ * JWT payload for access tokens
+ */
+interface AccessTokenPayload {
+    sub: string;
+    email: string;
+    type: "access";
+}
+/**
+ * JWT payload for refresh tokens
+ */
+interface RefreshTokenPayload {
+    sub: string;
+    email: string;
+    type: "refresh";
+}
+
+/**
+ * Lenan Auth Module for NestJS
+ *
+ * A flexible authentication module supporting JWT access/refresh tokens.
+ * Requires consumers to implement UserServiceInterface.
+ *
+ * @example
+ * ```typescript
+ * // Sync registration
+ * @Module({
+ *   imports: [
+ *     LenanAuthModule.register({
+ *       jwtSecret: 'your-secret',
+ *       jwtAccessExpiry: '15m',
+ *       jwtRefreshExpiry: '7d',
+ *     }, UserService),
+ *   ],
+ * })
+ * export class AppModule {}
+ *
+ * // Async registration with ConfigService
+ * @Module({
+ *   imports: [
+ *     LenanAuthModule.registerAsync({
+ *       imports: [ConfigModule],
+ *       useFactory: (config: ConfigService) => ({
+ *         jwtSecret: config.get('JWT_SECRET'),
+ *         jwtAccessExpiry: config.get('JWT_ACCESS_EXPIRY', '15m'),
+ *         jwtRefreshExpiry: config.get('JWT_REFRESH_EXPIRY', '7d'),
+ *       }),
+ *       inject: [ConfigService],
+ *     }, UserService),
+ *   ],
+ * })
+ * export class AppModule {}
+ * ```
+ */
+declare class LenanAuthModule {
+    /**
+     * Register the auth module with synchronous configuration
+     *
+     * @param options - Auth module configuration options
+     * @param userService - Your UserService class implementing UserServiceInterface
+     */
+    static register(options: AuthModuleOptions, userService: Type<UserServiceInterface>): DynamicModule;
+    /**
+     * Register the auth module with async configuration
+     *
+     * @param asyncOptions - Async configuration options
+     * @param userService - Your UserService class implementing UserServiceInterface
+     */
+    static registerAsync(asyncOptions: AuthModuleAsyncOptions, userService: Type<UserServiceInterface>): DynamicModule;
+    private static createProviders;
+    private static createAsyncProviders;
+    private static createAsyncOptionsProvider;
+}
+
+/**
+ * Login request DTO
+ */
+declare class LoginDto {
+    email: string;
+    password: string;
+}
+/**
+ * Registration request DTO
+ */
+declare class RegisterDto {
+    email: string;
+    password: string;
+    confirmPassword: string;
+}
+/**
+ * Refresh token request DTO
+ */
+declare class RefreshTokenDto {
+    refreshToken: string;
+}
+/**
+ * Token response DTO
+ */
+declare class TokensResponseDto {
+    accessToken: string;
+    refreshToken: string;
+    constructor(accessToken: string, refreshToken: string);
+}
+/**
+ * Message response DTO
+ */
+declare class MessageResponseDto {
+    message: string;
+    constructor(message: string);
+}
+
+/**
+ * Service for JWT token generation and verification
+ */
+declare class JwtTokenService {
+    private readonly jwtService;
+    private readonly accessExpiry;
+    private readonly refreshExpiry;
+    private readonly accessSecret;
+    private readonly refreshSecret;
+    constructor(jwtService: JwtService, options: AuthModuleOptions);
+    /**
+     * Generate access and refresh tokens for a user
+     */
+    generateTokens(userId: string, email: string): Promise<AuthTokens>;
+    /**
+     * Generate an access token
+     */
+    generateAccessToken(userId: string, email: string): Promise<string>;
+    /**
+     * Generate a refresh token
+     */
+    generateRefreshToken(userId: string, email: string): Promise<string>;
+    /**
+     * Verify an access token and return its payload
+     */
+    verifyAccessToken(token: string): Promise<AccessTokenPayload | null>;
+    /**
+     * Verify a refresh token and return its payload
+     */
+    verifyRefreshToken(token: string): Promise<RefreshTokenPayload | null>;
+    /**
+     * Decode a token without verification (useful for debugging)
+     */
+    decodeToken<T = any>(token: string): T | null;
+}
+
+/**
+ * Service for password hashing and comparison using bcrypt
+ */
+declare class PasswordService {
+    private readonly saltRounds;
+    /**
+     * Hash a plain text password
+     */
+    hash(password: string): Promise<string>;
+    /**
+     * Compare a plain text password with a hash
+     */
+    compare(password: string, hash: string): Promise<boolean>;
+    /**
+     * Hash a refresh token for storage
+     * Uses fewer rounds since refresh tokens are already random
+     */
+    hashToken(token: string): Promise<string>;
+    /**
+     * Compare a refresh token with its hash
+     */
+    compareToken(token: string, hash: string): Promise<boolean>;
+}
+
+/**
+ * Main authentication service
+ * Orchestrates user authentication, registration, and token management
+ */
+declare class AuthService {
+    private readonly userService;
+    private readonly passwordService;
+    private readonly jwtTokenService;
+    constructor(userService: UserServiceInterface, passwordService: PasswordService, jwtTokenService: JwtTokenService);
+    /**
+     * Register a new user
+     * @throws ConflictException if email already exists
+     */
+    register(dto: RegisterDto): Promise<AuthTokens>;
+    /**
+     * Authenticate a user with email and password
+     * @throws UnauthorizedException if credentials are invalid
+     */
+    login(dto: LoginDto): Promise<AuthTokens>;
+    /**
+     * Refresh tokens using a valid refresh token
+     * @throws UnauthorizedException if refresh token is invalid
+     */
+    refreshTokens(userId: string, refreshToken: string): Promise<AuthTokens>;
+    /**
+     * Log out a user by clearing their refresh token
+     */
+    logout(userId: string): Promise<void>;
+    /**
+     * Validate a user exists by ID
+     * Used by JWT strategy to validate token payloads
+     */
+    validateUser(userId: string): Promise<AuthUser | null>;
+    /**
+     * Get current user by ID (without sensitive fields)
+     */
+    getCurrentUser(userId: string): Promise<Omit<AuthUser, "passwordHash" | "hashedRefreshToken"> | null>;
+}
+
+declare const JwtAuthGuard_base: _nestjs_passport.Type<_nestjs_passport.IAuthGuard>;
+/**
+ * JWT Auth Guard for protecting routes
+ * Uses the 'lenan-jwt' strategy to validate access tokens
+ * Respects the @Public() decorator to skip authentication
+ */
+declare class JwtAuthGuard extends JwtAuthGuard_base {
+    private reflector;
+    constructor(reflector: Reflector);
+    canActivate(context: ExecutionContext): boolean | Promise<boolean> | rxjs.Observable<boolean>;
+}
+
+declare const RefreshTokenGuard_base: _nestjs_passport.Type<_nestjs_passport.IAuthGuard>;
+/**
+ * Refresh Token Guard for protecting the refresh endpoint
+ * Uses the 'lenan-jwt-refresh' strategy to validate refresh tokens
+ */
+declare class RefreshTokenGuard extends RefreshTokenGuard_base {
+}
+
+declare const JwtStrategy_base: new (...args: [opt: passport_jwt.StrategyOptionsWithRequest] | [opt: passport_jwt.StrategyOptionsWithoutRequest]) => Strategy & {
+    validate(...args: any[]): unknown;
+};
+/**
+ * JWT Strategy for validating access tokens
+ * Extracts token from Authorization header and validates against the user service
+ */
+declare class JwtStrategy extends JwtStrategy_base {
+    private readonly userService;
+    constructor(options: AuthModuleOptions, userService: UserServiceInterface);
+    /**
+     * Validate the JWT payload and return the user
+     * This is called by Passport after successfully verifying the token signature
+     */
+    validate(payload: AccessTokenPayload): Promise<{
+        id: string;
+        email: string;
+    }>;
+}
+
+declare const RefreshTokenStrategy_base: new (...args: [opt: passport_jwt.StrategyOptionsWithRequest] | [opt: passport_jwt.StrategyOptionsWithoutRequest]) => Strategy & {
+    validate(...args: any[]): unknown;
+};
+/**
+ * Refresh Token Strategy for validating refresh tokens
+ * Extracts token from request body and validates it
+ */
+declare class RefreshTokenStrategy extends RefreshTokenStrategy_base {
+    private readonly userService;
+    constructor(options: AuthModuleOptions, userService: UserServiceInterface);
+    /**
+     * Validate the refresh token payload
+     * Returns user with the refresh token attached for further validation
+     */
+    validate(req: Request$1, payload: RefreshTokenPayload): Promise<{
+        refreshToken: any;
+        passwordHash: string;
+        hashedRefreshToken: string | null;
+        id: string;
+        email: string;
+    }>;
+}
+
+/**
+ * Metadata key for public routes
+ */
+declare const IS_PUBLIC_KEY = "isPublic";
+/**
+ * Mark a route as public (no authentication required)
+ * Use this decorator on routes that should be accessible without a valid JWT
+ *
+ * @example
+ * ```typescript
+ * @Public()
+ * @Get('health')
+ * healthCheck() {
+ *   return { status: 'ok' };
+ * }
+ * ```
+ */
+declare const Public: () => _nestjs_common.CustomDecorator<string>;
+/**
+ * Extract the current authenticated user from the request
+ * Can optionally extract a specific property from the user object
+ *
+ * @example
+ * ```typescript
+ * // Get the entire user object
+ * @Get('profile')
+ * getProfile(@CurrentUser() user: User) {
+ *   return user;
+ * }
+ *
+ * // Get a specific property
+ * @Get('my-id')
+ * getMyId(@CurrentUser('id') userId: string) {
+ *   return { id: userId };
+ * }
+ * ```
+ */
+declare const CurrentUser: (...dataOrPipes: (string | _nestjs_common.PipeTransform<any, any> | _nestjs_common.Type<_nestjs_common.PipeTransform<any, any>> | undefined)[]) => ParameterDecorator;
+
+/**
+ * Authentication controller providing standard auth endpoints
+ * This controller is optional - consumers can disable it and implement their own
+ */
+declare class AuthController {
+    private readonly authService;
+    constructor(authService: AuthService);
+    /**
+     * Register a new user
+     * POST /auth/register
+     */
+    register(dto: RegisterDto): Promise<TokensResponseDto>;
+    /**
+     * Login with email and password
+     * POST /auth/login
+     */
+    login(dto: LoginDto): Promise<TokensResponseDto>;
+    /**
+     * Refresh access token using refresh token
+     * POST /auth/refresh
+     */
+    refresh(user: BaseUser & {
+        refreshToken: string;
+    }): Promise<TokensResponseDto>;
+    /**
+     * Logout (invalidate refresh token)
+     * POST /auth/logout
+     */
+    logout(userId: string): Promise<MessageResponseDto>;
+    /**
+     * Get current authenticated user
+     * GET /auth/me
+     */
+    me(user: BaseUser): Promise<BaseUser>;
+}
+
+export { type AccessTokenPayload, AuthController, type AuthModuleAsyncOptions, type AuthModuleOptions, type AuthOptionsFactory, AuthService, type AuthTokens, type AuthUser, type AuthenticatedRequest, type BaseUser, CurrentUser, IS_PUBLIC_KEY, JwtAuthGuard, type JwtPayload, JwtStrategy, JwtTokenService, LENAN_AUTH_OPTIONS, LENAN_USER_SERVICE, LenanAuthModule, type LoginCredentials, LoginDto, MessageResponseDto, PasswordService, Public, RefreshTokenDto, RefreshTokenGuard, type RefreshTokenPayload, RefreshTokenStrategy, type RegisterData, RegisterDto, TokensResponseDto, type UserServiceInterface };