Activity Logs

The Activity Log system is a centralized, compliance-ready auditing engine. It captures the "Who, What, Where, When, and Why" of every significant action.

Core Philosophy

1. Immutable History: Once written, logs are never altered.
2. Loose Coupling: Logs do not use Foreign Keys. If a User or Tenant is deleted, the audit trail remains intact (orphaned logs are a feature, not a bug).
3. Security First: Sensitive data is sanitized before it leaves application memory. Secrets are redacted; PII is either redacted or encrypted depending on sensitivity level.
4. Performance Tiers: Critical actions (money movement) are logged synchronously; non-critical actions (views) are fire-and-forget.

Architecture

The Service (modules/audit-logs/service.ts)

• AuditService: The central dispatcher. Determines whether to write synchronously, queue, or fire-and-forget based on tier.
• Sanitizer: A recursive engine that processes data based on a 3-level sensitivity system.
• Diff Engine: Uses microdiff to calculate deep JSON differences between changeBefore and changeAfter, stored in dot-notation format.
• Crypto: AES-256-GCM implementation for encrypting PII at HIGH sensitivity.

The Plugin (plugins/audit.ts)

• Fastify Decorator: Adds request.audit.log() to every request via the onRequest hook.
• Context Auto-fill: Automatically captures ipAddress, userAgent, requestId, traceId, sessionId, httpMethod, path, service, environment, and duration.
• Actor Auto-population: Calls populateUser(req) to extract user context. Defaults actorType to "HUMAN" if user is authenticated, "SYSTEM" otherwise. Defaults actorId to user.id or "ANONYMOUS".
• Runtime Validation: Drops the log with a warning if action, module, tier, or status are missing.
• Safety: If a SYNC log fails, the error is re-thrown to abort the transaction. If a QUEUE/ASYNC log fails, it logs the error but allows the request to proceed.

The Helper (utils/audit-helper.ts)

Provides logSuccess() and logFailure() convenience functions that extract actor fields from request.user and combine them with route-specific config. Routes still provide all domain context (tags, metadata, tier, sensitivity) — the helpers only eliminate repetitive actor extraction.

await logSuccess(request, {
  action: "license.create",
  module: "LICENSES",
  entityType: "license",
  entityId: license.id,
  changeAfter: license,
  tier: "SYNC",
  sensitivity: "HIGH",
  tags: ["provisioning", "billing", "contract"],
  metadata: { companyName: license.companyName, statusCode: 201 },
  tenantId: "SYSTEM", // Override for system-level operations
});

logFailure() uses getFriendlyErrorMessage() from modules/audit-logs/utils.ts to extract safe error messages (matching the global error handler's logic) and automatically captures the HTTP status code from AppError instances.

Tiered Logging Strategy

3-tier strategy balancing data integrity with system performance:

If no tier is provided, the service determines it from the action name using a built-in mapping (AUDIT_TIERS in service.ts). Routes should always set tier explicitly.

Sensitivity & Sanitization

The sensitivity field controls how the sanitizer handles data. It is applied to changeBefore, changeAfter, and metadata before anything is written to the database.

Sensitivity Levels

At HIGH sensitivity, PII is encrypted and recoverable by authorized admins. At MEDIUM and LOW, PII is irreversibly redacted with [PII_REDACTED].

The isSensitive boolean on the database row is set to true when sensitivity === "HIGH", flagging that the row contains encrypted (rather than redacted) PII.

Field Classification

Always Redacted ([REDACTED]) — secrets that must never appear in logs:

password, passwordConfirmation, oldPassword, newPassword, currentPassword, confirmPassword, token, accessToken, refreshToken, verificationToken, pin, clientSecret, apiKey, otp

Any key containing "password" is also redacted, unless it matches the Password Policy Whitelist (config fields like passwordMinLength, passwordExpiryDays, passwordHistory, etc.).

PII Fields — redacted at MEDIUM/LOW, encrypted at HIGH:

ssn, socialSecurityNumber, nationalId, pan, cardNumber, cvv, cvc, email, phone, phoneNumber, mobile, address, street, dob, dateOfBirth, iban, accountNumber

Truncated — large binary/file data capped at 20 characters to prevent storage bloat:

base64, image, file, buffer, pdf

Encryption

• Algorithm: AES-256-GCM (authenticated encryption — verifies integrity).
• Key Derivation: scrypt using ENCRYPTION_KEY + ENCRYPTION_SALT from environment variables.
• Output Format: ENC:v1:<IV hex>:<AuthTag hex>:<Ciphertext hex>
• Failure Handling: If encryption fails, the value is replaced with [ENCRYPTION_FAILED] rather than crashing the logging pipeline.

Data Model

Table: remoteEaze_activity_logs

Core Fields

Actor Context (Who)

Event Details (What)

Data Changes

Context (Where and How)

Additional Context

Status and Performance

Security and Compliance

Indexes

@@index([tenantId, timestamp])           // Tenant-scoped date range queries
@@index([tenantId, action, timestamp])   // Filter by action type
@@index([entityType, entityId])          // Entity audit history
@@index([actorId, timestamp])            // User activity timeline
@@index([traceId])                       // Distributed tracing
@@index([status])                        // Failure analysis
@@index([tags], type: Gin)               // Tag filtering (PostgreSQL GIN)
@@index([customFields], type: Gin)       // Custom field queries (PostgreSQL GIN)

Enums

ActorType: HUMAN | SYSTEM | SERVICE | CRON | IMPERSONATION

LogStatus: SUCCESS | FAILURE | PENDING

Usage Guide

Use request.audit.log() in route handlers. The RequestAuditEvent type requires action, module, tier, and status — the plugin will drop the log if any are missing.

Create (SYNC — Critical)

await request.audit.log({
  action: "transaction.create",
  module: "TRANSACTIONS",
  entityType: "transaction",
  entityId: transaction.id,
  changeAfter: transaction,
  tier: "SYNC",
  sensitivity: "HIGH",
  status: "SUCCESS",
  tags: ["financial", "high-value"],
});

Update (With Diff)

await request.audit.log({
  action: "user.update",
  module: "USERS",
  entityType: "user",
  entityId: userId,
  changeBefore: oldUser,
  changeAfter: newUser,
  tier: "QUEUE",
  sensitivity: "MEDIUM",
  status: "SUCCESS",
  tags: ["profile"],
});

View (ASYNC — Fire & Forget)

// No await — fire and forget
request.audit.log({
  action: "dashboard.view",
  module: "DASHBOARD",
  entityType: "dashboard",
  tier: "ASYNC",
  sensitivity: "LOW",
  status: "SUCCESS",
});

Using the Helper (Recommended for Routes)

import { logSuccess, logFailure } from "../../utils/audit-helper";

try {
  const result = await service.create(data);
  await logSuccess(request, {
    action: "role.create",
    module: "ACCESS_CONTROL",
    entityType: "role",
    entityId: result.id,
    changeAfter: result,
    tier: "SYNC",
    sensitivity: "MEDIUM",
    tags: ["access-control", "rbac"],
    metadata: { roleName: result.name, statusCode: 201 },
  });
} catch (error) {
  await logFailure(request, {
    action: "role.create",
    module: "ACCESS_CONTROL",
    entityType: "role",
    tier: "SYNC",
    sensitivity: "LOW",
    tags: ["access-control", "rbac"],
    error,
    additionalMetadata: { attemptedName: data.name },
  });
  throw error; // Let global error handler send the response
}