AuthAuditService

Package: @nauth-toolkit/core Type: Service

Query authentication and security audit events for monitoring and investigation.

NestJS

import { AuthAuditService } from '@nauth-toolkit/nestjs';

Express

import { AuthAuditService } from '@nauth-toolkit/core';

Fastify

import { AuthAuditService } from '@nauth-toolkit/core';

Overview

Use this service to query the authentication audit trail (login attempts, MFA events, suspicious activity, and risk-assessment markers). Audit event recording is internal.

Methods

getEventsByType()

Get events by type with pagination.

async getEventsByType(dto: GetEventsByTypeDTO): Promise<GetEventsByTypeResponseDTO>

Parameters

• dto - GetEventsByTypeDTO

Errors

None.

Returns

• GetEventsByTypeResponseDTO - Paginated audit events

Example

NestJS

const result = await this.auditService.getEventsByType({
  eventType: AuthAuditEventType.SUSPICIOUS_ACTIVITY,
  page: 1,
  limit: 100,
  startDate: new Date('2026-01-01'),
});

Express

const result = await nauth.authAuditService.getEventsByType({
  eventType: AuthAuditEventType.SUSPICIOUS_ACTIVITY,
  page: 1,
  limit: 100,
  startDate: new Date('2026-01-01'),
});

Fastify

const result = await nauth.authAuditService.getEventsByType({
  eventType: AuthAuditEventType.SUSPICIOUS_ACTIVITY,
  page: 1,
  limit: 100,
  startDate: new Date('2026-01-01'),
});

---

getRiskAssessmentHistory()

Get risk assessment history for adaptive MFA analysis.

async getRiskAssessmentHistory(dto: GetRiskAssessmentHistoryDTO): Promise<GetRiskAssessmentHistoryResponseDTO>

Parameters

• dto - GetRiskAssessmentHistoryDTO

Errors

Throws NAuthException with code:

Code	When	Details
NOT_FOUND	User not found	undefined

Returns

• GetRiskAssessmentHistoryResponseDTO - Array of risk assessment audit events

Example

NestJS

const result = await this.auditService.getRiskAssessmentHistory({
  sub: 'user-uuid',
  limit: 50,
});

Express

const result = await nauth.authAuditService.getRiskAssessmentHistory({
  sub: 'user-uuid',
  limit: 50,
});

Fastify

const result = await nauth.authAuditService.getRiskAssessmentHistory({
  sub: 'user-uuid',
  limit: 50,
});

---

getSuspiciousActivity()

Get suspicious activity events.

async getSuspiciousActivity(dto: GetSuspiciousActivityDTO): Promise<GetSuspiciousActivityResponseDTO>

Parameters

• dto - GetSuspiciousActivityDTO

Errors

Throws NAuthException with code:

Code	When	Details
NOT_FOUND	User not found	undefined

Returns

• GetSuspiciousActivityResponseDTO - Array of suspicious audit events

Example

NestJS

const result = await this.auditService.getSuspiciousActivity({
  sub: 'user-uuid',
  limit: 50,
});

Express

const result = await nauth.authAuditService.getSuspiciousActivity({
  sub: 'user-uuid',
  limit: 50,
});

Fastify

const result = await nauth.authAuditService.getSuspiciousActivity({
  sub: 'user-uuid',
  limit: 50,
});

---

getUserAuthHistory()

Get paginated authentication history for a user (admin operation).

async getUserAuthHistory(dto: AdminGetUserAuthHistoryDTO): Promise<GetUserAuthHistoryResponseDTO>

Parameters

• dto - AdminGetUserAuthHistoryDTO - Admin DTO with required sub field

Errors

Throws NAuthException with code:

Code	When	Details
NOT_FOUND	User not found	undefined

Returns

• GetUserAuthHistoryResponseDTO - Paginated audit events

Example

NestJS

@Injectable()
export class MyService {
  constructor(private auditService: AuthAuditService) {}

  async example() {
    const result = await this.auditService.getUserAuthHistory({
      sub: 'user-uuid', // Required: target user's sub
      page: 1,
      limit: 50,
      eventTypes: [AuthAuditEventType.LOGIN_SUCCESS],
    });
    // result.data - IAuthAudit[]
    // result.total - number
    // result.page - number
    // result.limit - number
    // result.totalPages - number
  }
}

Express

app.get('/user/history', async (req, res) => {
  const result = await nauth.authAuditService.getUserAuthHistory({
    sub: req.user.sub,
    page: 1,
    limit: 50,
  });
  res.json(result);
});

Fastify

fastify.get(
  '/user/history',
  { preHandler: nauth.helpers.requireAuth() },
  nauth.adapter.wrapRouteHandler(async () => {
    const user = nauth.helpers.getCurrentUser();
    return nauth.authAuditService.getUserAuthHistory({
      sub: user.sub,
      page: 1,
      limit: 50,
    });
  }),
);

---

Related APIs

• AdminGetUserAuthHistoryDTO - Admin DTO for getUserAuthHistory
• GetUserAuthHistoryDTO - User self-service DTO (used by AuthService)
• GetEventsByTypeDTO
• GetSuspiciousActivityDTO
• GetRiskAssessmentHistoryDTO
• AuthAuditEventType - Complete list of event types
• AuthAuditEventStatus - Event status values
• NAuthException - Error type thrown by services