web

web / lib/services/audit-log-service

lib/services/audit-log-service

Service for creating immutable audit log entries.

Provides a single function to record sensitive account actions. PII (email, IP address) is hashed automatically. Errors are caught and logged — audit logging never blocks the primary action.

Interfaces

AuditLogEntry

Properties

action

action: AuditAction

The action being recorded.

userId

userId: number

The user ID the action pertains to.

userEmail

userEmail: string

The user’s email (will be hashed before storage).

performedBy?

optional performedBy: number

Admin user ID who initiated the action (null for self-initiated).

ipAddress?

optional ipAddress: string

Client IP address (stored raw for 30 days, then cleared; hash is permanent).

details?

optional details: Record<string, unknown>

Action-specific structured data.

FieldAuditConfig

Configuration for detecting field changes and creating audit entries.

Properties

action

action: AuditAction

The audit action to record for this field change.

fieldPath

fieldPath: string

Dot-separated path to the field on the document.

detailsFn()?

optional detailsFn: (oldValue, newValue) => Record<string, unknown>

Optional transform for the audit details. Receives (oldValue, newValue).

Parameters

oldValue

unknown

newValue

unknown

Returns

Record<string, unknown>

Type Aliases

AuditAction

AuditAction = typeof AUDIT_ACTIONS[keyof typeof AUDIT_ACTIONS]

Variables

AUDIT_ACTIONS

const AUDIT_ACTIONS: object

Action type constants for type safety (not credentials).

Type Declaration

EMAIL_CHANGED

readonly EMAIL_CHANGED: "account.email_changed" = "account.email_changed"

PASSWORD_CHANGED

readonly PASSWORD_CHANGED: "account.password_changed" = "account.password_changed"

DELETION_SCHEDULED

readonly DELETION_SCHEDULED: "account.deletion_scheduled" = "account.deletion_scheduled"

DELETION_CANCELLED

readonly DELETION_CANCELLED: "account.deletion_cancelled" = "account.deletion_cancelled"

DELETION_EXECUTED

readonly DELETION_EXECUTED: "account.deletion_executed" = "account.deletion_executed"

PASSWORD_VERIFY_FAILED

readonly PASSWORD_VERIFY_FAILED: "account.password_verify_failed" = "account.password_verify_failed"

TRUST_LEVEL_CHANGED

readonly TRUST_LEVEL_CHANGED: "admin.trust_level_changed" = "admin.trust_level_changed"

ROLE_CHANGED

readonly ROLE_CHANGED: "admin.role_changed" = "admin.role_changed"

USER_ACTIVATED

readonly USER_ACTIVATED: "admin.user_activated" = "admin.user_activated"

USER_DEACTIVATED

readonly USER_DEACTIVATED: "admin.user_deactivated" = "admin.user_deactivated"

CUSTOM_QUOTAS_CHANGED

readonly CUSTOM_QUOTAS_CHANGED: "admin.custom_quotas_changed" = "admin.custom_quotas_changed"

QUOTA_OVERRIDDEN

readonly QUOTA_OVERRIDDEN: "admin.quota_overridden" = "admin.quota_overridden"

CATALOG_VISIBILITY_CHANGED

readonly CATALOG_VISIBILITY_CHANGED: "data.catalog_visibility_changed" = "data.catalog_visibility_changed"

DATASET_VISIBILITY_CHANGED

readonly DATASET_VISIBILITY_CHANGED: "data.dataset_visibility_changed" = "data.dataset_visibility_changed"

CATALOG_OWNERSHIP_TRANSFERRED

readonly CATALOG_OWNERSHIP_TRANSFERRED: "data.catalog_ownership_transferred" = "data.catalog_ownership_transferred"

DATASET_OWNERSHIP_TRANSFERRED

readonly DATASET_OWNERSHIP_TRANSFERRED: "data.dataset_ownership_transferred" = "data.dataset_ownership_transferred"

FEATURE_FLAG_CHANGED

readonly FEATURE_FLAG_CHANGED: "system.feature_flag_changed" = "system.feature_flag_changed"

SETTINGS_CHANGED

readonly SETTINGS_CHANGED: "system.settings_changed" = "system.settings_changed"

IMPORT_JOB_STAGE_OVERRIDE

readonly IMPORT_JOB_STAGE_OVERRIDE: "import.job_stage_override" = "import.job_stage_override"

SCHEDULED_IMPORT_ADMIN_MODIFIED

readonly SCHEDULED_IMPORT_ADMIN_MODIFIED: "import.scheduled_import_admin_modified" = "import.scheduled_import_admin_modified"

Functions

auditLog()

auditLog(payload, entry): Promise<void>

Create an immutable audit log entry. Hashes PII internally.

This function catches all errors and logs them — it never throws. Audit logging must not prevent the primary operation from completing.

Parameters

payload

BasePayload

entry

AuditLogEntry

Returns

Promise<void>

auditFieldChanges()

auditFieldChanges(payload, args, fields): Promise<void>

Detect field-level changes between previousDoc and doc, and fire audit log entries for each changed field. Designed for Payload afterChange hooks.

Parameters

payload

BasePayload

args

previousDoc

Record<string, unknown> | undefined

doc

Record<string, unknown>

userId

number

userEmail

string

performedBy?

number

ipAddress?

string

fields

FieldAuditConfig[]

Returns

Promise<void>