@ackplus/nest-auth 0.1.51 → 1.1.0

package/src/lib/auth/guards/auth.guard.ts

@@ -0,0 +1,386 @@
+import { Injectable, CanActivate, ExecutionContext, UnauthorizedException, ForbiddenException } from '@nestjs/common';
+import { UNAUTHORIZED_EXCEPTION_CODE } from '../../auth.constants';
+import { Reflector } from '@nestjs/core';
+import { Request, Response } from 'express';
+import { JwtService } from '../../core/services/jwt.service';
+import { SessionManagerService } from '../../session/services/session-manager.service';
+import { AccessKeyService } from '../../user/services/access-key.service';
+import { JWTTokenPayload } from '../../core/interfaces/token-payload.interface';
+import { SKIP_MFA_KEY } from '../../core/decorators/skip-mfa.decorator';
+import { PERMISSIONS_KEY } from '../../core/decorators/permissions.decorator';
+import { ROLES_KEY } from '../../core/decorators/role.decorator';
+
+// Key for optional auth metadata
+export const OPTIONAL_AUTH_KEY = 'optional_auth';
+
+/**
+ * NestAuthAuthGuard
+ *
+ * Handles authentication and authorization for protected routes.
+ * Token refresh is handled by RefreshTokenInterceptor (applied globally).
+ *
+ * This guard verifies:
+ * - JWT tokens (Bearer)
+ * - API keys
+ * - MFA requirements
+ * - Roles and permissions
+ *
+ * Note: For automatic token refresh, enable RefreshTokenInterceptor globally.
+ */
+@Injectable()
+export class NestAuthAuthGuard implements CanActivate {
+    constructor(
+        private reflector: Reflector,
+        private jwtService: JwtService,
+        private sessionManager: SessionManagerService,
+        private accessKeyService: AccessKeyService,
+    ) { }
+
+    async canActivate(context: ExecutionContext): Promise<boolean> {
+        const request = context.switchToHttp().getRequest<Request>() as any;
+        const response = context.switchToHttp().getResponse<Response>();
+
+        // Check if authentication is optional
+        const isOptional = this.reflector.getAllAndOverride<boolean>(OPTIONAL_AUTH_KEY, [
+            context.getHandler(),
+            context.getClass(),
+        ]);
+
+        // Initialize request properties
+        request.user = null;
+        request.session = null;
+        request.accessKey = null;
+        request.authType = null;
+
+        const authHeader = request.headers.authorization;
+
+        // If no auth header
+        if (!authHeader) {
+            if (isOptional) {
+                // Optional auth: allow request to proceed without user data
+                return true;
+            } else {
+                // Required auth: throw error
+                throw new UnauthorizedException({
+                    message: 'No authentication provided',
+                    code: 'NO_AUTH'
+                });
+            }
+        }
+
+        const [type, token] = authHeader.split(' ');
+        if (!type || !token) {
+            if (isOptional) {
+                return true;
+            } else {
+                throw new UnauthorizedException({
+                    message: 'Invalid authentication format',
+                    code: 'INVALID_AUTH_FORMAT'
+                });
+            }
+        }
+
+        // Handle authentication
+        let isAuthenticated = false;
+        try {
+            switch (type.toLowerCase()) {
+                case 'bearer':
+                    isAuthenticated = await this.handleJwtAuth(context, request, response, token, isOptional);
+                    break;
+                case 'apikey':
+                    isAuthenticated = await this.handleApiKeyAuth(request, token, isOptional);
+                    break;
+                default:
+                    if (isOptional) {
+                        // Invalid auth type, but optional - proceed without user data
+                        return true;
+                    } else {
+                        throw new UnauthorizedException({
+                            message: 'Invalid authentication type',
+                            code: 'INVALID_AUTH_TYPE'
+                        });
+                    }
+            }
+        } catch (error) {
+            if (isOptional) {
+                // If optional auth fails, silently proceed without user data
+                return true;
+            } else {
+                // If required auth fails, re-throw the error
+                throw error;
+            }
+        }
+
+        // If authentication failed and it's required, stop here
+        if (!isAuthenticated && !isOptional) {
+            return false;
+        }
+
+        // After successful authentication, check authorization (roles, permissions)
+        // Only check authorization if user is authenticated
+        if (isAuthenticated && request.user) {
+            await this.checkAuthorization(context, request);
+        }
+
+        return true;
+    }
+
+    private async handleJwtAuth(context: ExecutionContext, request: any, response: Response, token: string, isOptional: boolean = false): Promise<boolean> {
+        try {
+            // Verify the JWT token
+            const payload = await this.jwtService.verifyToken(token);
+            request.user = payload;
+            request.authType = 'jwt';
+
+            // Verify session exists
+            const session = await this.sessionManager.getSession(payload.sessionId as string);
+            if (!session) {
+                if (isOptional) {
+                    // Session not found but auth is optional - reset user data and continue
+                    request.user = null;
+                    request.authType = null;
+                    return false;
+                } else {
+                    throw new UnauthorizedException({
+                        message: 'Session not found',
+                        code: UNAUTHORIZED_EXCEPTION_CODE
+                    });
+                }
+            }
+
+            request.session = session;
+
+            // Check MFA requirements
+            await this.checkMfa(context, payload, isOptional);
+            return true;
+        } catch (error) {
+            // Token verification failed
+            // Note: Token refresh is handled by RefreshTokenInterceptor
+            if (isOptional) {
+                // Auth is optional - continue without user data
+                return false;
+            } else {
+                throw new UnauthorizedException({
+                    message: 'Invalid or expired token',
+                    code: UNAUTHORIZED_EXCEPTION_CODE
+                });
+            }
+        }
+    }
+
+    private async handleApiKeyAuth(request: any, token: string, isOptional: boolean = false): Promise<boolean> {
+        // Split the token into public and private parts
+        const [publicKey, privateKey] = token.split('.');
+        if (!publicKey || !privateKey) {
+            if (isOptional) {
+                // Invalid format but auth is optional - continue without user data
+                return false;
+            } else {
+                throw new UnauthorizedException({
+                    message: 'Invalid API key format',
+                    code: 'INVALID_API_KEY_FORMAT'
+                });
+            }
+        }
+
+        try {
+            // Validate API key pair
+            const isValid = await this.accessKeyService.validateAccessKey(publicKey, privateKey);
+            if (!isValid) {
+                if (isOptional) {
+                    // Invalid API key but auth is optional - continue without user data
+                    return false;
+                } else {
+                    throw new UnauthorizedException({
+                        message: 'Invalid API key',
+                        code: 'INVALID_API_KEY'
+                    });
+                }
+            }
+
+            // Get access key details
+            const accessKey = await this.accessKeyService.getAccessKey(publicKey);
+
+            // Update last used timestamp
+            await this.accessKeyService.updateAccessKeyLastUsed(publicKey);
+
+            // Attach user and access key to request
+            request.user = accessKey.user;
+            request.accessKey = accessKey;
+            request.authType = 'api-key';
+
+            return true;
+        } catch (error) {
+            if (isOptional) {
+                // API key validation failed but auth is optional - continue without user data
+                return false;
+            } else {
+                throw error;
+            }
+        }
+    }
+
+
+    private async checkMfa(context: ExecutionContext, payload: JWTTokenPayload, isOptional: boolean = false): Promise<void> {
+        // Check if MFA should be skipped
+        const skipMfa = this.reflector.getAllAndOverride<boolean>(SKIP_MFA_KEY, [
+            context.getHandler(),
+            context.getClass(),
+        ]);
+
+        // Get MFA status from token
+        const isMfaEnabled = payload.isMfaEnabled;
+        const isMfaVerified = payload.isMfaVerified;
+
+        // If MFA is enabled and not verified, and route is not marked to skip MFA, require MFA verification
+        if (isMfaEnabled && !isMfaVerified && !skipMfa) {
+            if (isOptional) {
+                // MFA required but auth is optional - this creates a conflict
+                // In this case, we should not set user data since MFA is not verified
+                throw new Error('MFA verification required - cannot proceed with optional auth');
+            } else {
+                throw new UnauthorizedException({
+                    message: 'Multi-factor authentication is required',
+                    code: UNAUTHORIZED_EXCEPTION_CODE
+                });
+            }
+        }
+    }
+
+    /**
+     * Check authorization (roles, permissions) after successful authentication
+     */
+    private async checkAuthorization(context: ExecutionContext, request: Request): Promise<void> {
+        // Get required permissions and roles from decorators
+        const requiredPermissions = this.getRequiredPermissions(context);
+        const requiredRoles = this.getRequiredRoles(context);
+
+        // If no authorization requirements, allow access
+        if (!requiredPermissions.length && !requiredRoles.length) {
+            return;
+        }
+
+        const user = request.user;
+
+        // Check if user exists
+        if (!user) {
+            throw new ForbiddenException('Access denied: User not authenticated');
+        }
+
+        // Check roles if required
+        if (requiredRoles.length > 0) {
+            this.checkRoles(user, requiredRoles);
+        }
+
+        // Check permissions if required
+        if (requiredPermissions.length > 0) {
+            this.checkPermissions(user, requiredPermissions);
+        }
+    }
+
+    /**
+     * Get required permissions from decorator
+     */
+    private getRequiredPermissions(context: ExecutionContext): string[] {
+        let permissions = this.reflector.getAllAndOverride<string[] | string>(
+            PERMISSIONS_KEY,
+            [context.getHandler(), context.getClass()],
+        );
+
+        if (!permissions) {
+            return [];
+        }
+
+        // Normalize to array
+        return typeof permissions === 'string' ? [permissions] : permissions;
+    }
+
+    /**
+     * Get required roles from decorator
+     */
+    private getRequiredRoles(context: ExecutionContext): string[] {
+        let roles = this.reflector.getAllAndOverride<string[] | string>(
+            ROLES_KEY,
+            [context.getHandler(), context.getClass()],
+        );
+
+        if (!roles) {
+            return [];
+        }
+
+        // Normalize to array
+        return typeof roles === 'string' ? [roles] : roles;
+    }
+
+    /**
+     * Check if user has required roles
+     */
+    private checkRoles(user: any, requiredRoles: string[]): void {
+        if (!user.roles || !Array.isArray(user.roles)) {
+            throw new ForbiddenException('Access denied: No roles assigned');
+        }
+
+        // Get active role names
+        const userRoleNames = user.roles
+            .filter(role => role.isActive)
+            .map(role => role.name);
+
+        // Check if user has all required roles
+        const hasAllRoles = requiredRoles.every(role => userRoleNames.includes(role));
+
+        if (!hasAllRoles) {
+            const missingRoles = requiredRoles.filter(role => !userRoleNames.includes(role));
+            throw new ForbiddenException(
+                `Access denied: Missing required roles: ${missingRoles.join(', ')}`
+            );
+        }
+    }
+
+    /**
+     * Check if user has required permissions
+     */
+    private checkPermissions(user: any, requiredPermissions: string[]): void {
+        if (!user.roles || !Array.isArray(user.roles)) {
+            throw new ForbiddenException('Access denied: No roles assigned for permission check');
+        }
+
+        // Get all permissions from user's roles
+        const userPermissions = this.getUserPermissions(user.roles);
+
+        // Check if user has all required permissions
+        const hasAllPermissions = requiredPermissions.every(permission =>
+            userPermissions.includes(permission)
+        );
+
+        if (!hasAllPermissions) {
+            const missingPermissions = requiredPermissions.filter(permission =>
+                !userPermissions.includes(permission)
+            );
+
+            throw new ForbiddenException(
+                `Access denied: Missing required permissions: ${missingPermissions.join(', ')}`
+            );
+        }
+    }
+
+    /**
+     * Extract all permissions from user's roles
+     */
+    private getUserPermissions(roles: any[]): string[] {
+        const permissions = new Set<string>();
+
+        roles.forEach(role => {
+            // Skip inactive roles
+            if (!role.isActive) {
+                return;
+            }
+
+            // Add permissions from this role
+            if (role.permissions && Array.isArray(role.permissions)) {
+                role.permissions.forEach(permission => permissions.add(permission));
+            }
+        });
+
+        return Array.from(permissions);
+    }
+}

package/src/lib/auth/{index.d.ts → index.ts}

@@ -1,5 +1,11 @@
+// Guards
 export * from './guards/auth.guard';
 export { OPTIONAL_AUTH_KEY } from './guards/auth.guard';
+
+// Interceptors
+export * from './interceptors/refresh-token.interceptor';
+
+// Events
 export * from './events/logged-out-all.event';
 export * from './events/logged-out.event';
 export * from './events/password-reset-requested.event';
@@ -8,18 +14,39 @@ export * from './events/user-2fa-verified.event';
 export * from './events/user-logged-in.event';
 export * from './events/user-refresh-token.event';
 export * from './events/user-registered.event';
+
+// Services
 export * from './services/auth.service';
 export * from './services/cookie.service';
 export * from './services/mfa.service';
+export * from './services/client-config.service';
+
+// Controllers
 export * from './controllers/auth.controller';
 export * from './controllers/mfa.controller';
+
+// DTOs
 export * from './dto/requests/login.request.dto';
 export * from './dto/requests/signup.request.dto';
-export * from './dto/requests/social-login.request.dto';
+export * from './dto/credentials/social-credentials.dto';
+export * from './dto/credentials/email-credentials.dto';
+export * from './dto/credentials/phone-credentials.dto';
 export * from './dto/requests/forgot-password.request.dto';
 export * from './dto/requests/reset-password.request.dto';
+export * from './dto/requests/reset-password-with-token.request.dto';
+export * from './dto/requests/verify-forgot-password-otp-request-dto';
 export * from './dto/requests/send-mfa-code.request.dto';
+export * from './dto/requests/change-password.request.dto';
+export * from './dto/requests/toggle-mfa.request.dto';
 export * from './dto/requests/refresh-token.request.dto';
 export * from './dto/requests/verify-2fa.request.dto';
 export * from './dto/requests/verify-totp-setup.request.dto';
 export * from './dto/responses/auth.response.dto';
+export * from './dto/responses/auth-cookie.response.dto';
+export * from './dto/responses/verify-otp.response.dto';
+export * from './dto/responses/mfa-status.response.dto';
+export * from './dto/responses/client-config.response.dto';
+
+// Entities
+export * from './entities/otp.entity';
+export * from './entities/mfa-secret.entity';

package/src/lib/auth/interceptors/refresh-token.interceptor.ts

@@ -0,0 +1,117 @@
+import { Injectable, NestInterceptor, ExecutionContext, CallHandler } from '@nestjs/common';
+import { Observable, throwError } from 'rxjs';
+import { catchError } from 'rxjs/operators';
+import { Request, Response } from 'express';
+import { AuthService } from '../services/auth.service';
+import { CookieService } from '../services/cookie.service';
+import { JwtService } from '../../core/services/jwt.service';
+import { AuthConfigService } from '../../core/services/auth-config.service';
+import { REFRESH_TOKEN_COOKIE_NAME, UNAUTHORIZED_EXCEPTION_CODE } from '../../auth.constants';
+
+/**
+ * RefreshTokenInterceptor
+ *
+ * Automatically handles token refresh when access token is expired.
+ * This interceptor runs before guards and catches token expiration errors,
+ * attempting to refresh the token transparently.
+ *
+ * Token delivery method (header vs cookie) respects the `accessTokenType` configuration:
+ * - If `accessTokenType: 'header'` (default): Updates Authorization header only
+ * - If `accessTokenType: 'cookie'`: Sets tokens in cookies
+ *
+ * Apply this globally to handle token refresh across your entire application.
+ *
+ * @example
+ * ```typescript
+ * // In AppModule or NestAuthModule configuration
+ * providers: [
+ *   {
+ *     provide: APP_INTERCEPTOR,
+ *     useClass: RefreshTokenInterceptor,
+ *   },
+ * ]
+ * ```
+ */
+@Injectable()
+export class RefreshTokenInterceptor implements NestInterceptor {
+    constructor(
+        private readonly authService: AuthService,
+        private readonly cookieService: CookieService,
+        private readonly jwtService: JwtService,
+        private readonly authConfig: AuthConfigService,
+    ) { }
+
+    async intercept(context: ExecutionContext, next: CallHandler): Promise<Observable<any>> {
+        const request = context.switchToHttp().getRequest<Request>();
+        const response = context.switchToHttp().getResponse<Response>();
+
+        // Extract access token from Authorization header
+        const authHeader = request.headers.authorization;
+        if (!authHeader || !authHeader.startsWith('Bearer ')) {
+            // No bearer token, proceed normally
+            return next.handle();
+        }
+
+        const accessToken = authHeader.split(' ')[1];
+        if (!accessToken) {
+            return next.handle();
+        }
+
+        // Try to verify the access token
+        try {
+            await this.jwtService.verifyToken(accessToken);
+            // Token is valid, proceed normally
+            return next.handle();
+        } catch (error) {
+            // Token is invalid or expired, try to refresh
+            const refreshToken = this.extractRefreshToken(request);
+
+            if (!refreshToken) {
+                // No refresh token available, let the guard handle it
+                return next.handle();
+            }
+
+            try {
+                // Attempt to refresh the token
+                const newSession = await this.authService.refreshToken(refreshToken);
+
+                // Get auth configuration
+                const config = this.authConfig.getConfig();
+                const useCookies = config.accessTokenType === 'cookie';
+
+                if (useCookies) {
+                    // Cookie-based auth: Set tokens in cookies
+                    this.cookieService.setTokens(response, newSession.accessToken, newSession.refreshToken);
+                } else {
+                    // Header-based auth (default): Update Authorization header only
+                    request.headers.authorization = `Bearer ${newSession.accessToken}`;
+                }
+
+                // Proceed with the new token
+                return next.handle();
+            } catch (refreshError) {
+                // Refresh failed, let the guard handle the authentication failure
+                return next.handle();
+            }
+        }
+    }
+
+    /**
+     * Extract refresh token from cookies or headers
+     */
+    private extractRefreshToken(request: Request): string | null {
+        // Try to get refresh token from cookies
+        const tokenFromCookie = request.cookies?.[REFRESH_TOKEN_COOKIE_NAME];
+        if (tokenFromCookie) {
+            return tokenFromCookie;
+        }
+
+        // If not in cookies, try the custom header
+        const authHeader = request.headers['x-refresh-token'];
+        if (authHeader) {
+            return authHeader as string;
+        }
+
+        return null;
+    }
+}