feat(api): implement centralized audit logging

[David-patrick-chuks]

Overview

This PR adds a centralized audit logging system to apps/api to capture a tamper-evident trail of sensitive administrative and financial actions. It supports audit events for authentication, API key changes, payment initiation, redemptions, and webhook configuration changes, while recording the required fields for each entry.

Related Issue

Closes #22

Changes

⚙️ Audit Logging System

• [ADD] apps/api/src/audit-log/audit-log.service.ts

  • Added the core audit logging service for sensitive backend events.
  • Implemented support for auth.login, auth.register, api_key.changed, payment.initiated, redemption.created, and webhook.config_changed.
  • Captures the required audit fields: id, merchant_id, event_type, metadata, ip, and timestamp.
  • Added tamper-evident hash chaining with previous_hash and entry_hash.
  • Added verification logic to detect audit trail tampering.

• [ADD] apps/api/src/audit-log/interfaces/audit-event.interface.ts

  • Defined the supported audit event types.
  • Added the request contract for recording audit events.

• [ADD] apps/api/src/audit-log/interfaces/audit-log.interface.ts

  • Added shared interfaces for audit log entries and verification responses.

🧩 Audit Logging API

• [ADD] apps/api/src/audit-log/audit-log.controller.ts

  • Added endpoints to record audit events.
  • Added endpoints to list audit log entries globally or per merchant.
  • Added endpoints to verify the integrity of the audit trail.
  • Captures client IP addresses from request headers.

• [ADD] apps/api/src/audit-log/audit-log.module.ts

  • Added a dedicated NestJS module for centralized audit logging.
  • Exported the audit log service for reuse in future backend flows.

🏗️ Application Wiring

• [MODIFY] apps/api/src/app.module.ts
  • Registered the AuditLogModule in the API application.

🔐 Configuration

• [MODIFY] apps/api/.env.example
  • Added AUDIT_LOG_CHAIN_SECRET for keyed tamper-evident hashing.

🧪 Tests

• [ADD] apps/api/src/audit-log/audit-log.service.spec.ts
  • Added coverage for required field capture.
  • Added coverage for tamper-evident hash chaining.
  • Added coverage for merchant filtering.
  • Added validation coverage for unsupported event types.

Verification Results

Acceptance Criteria	Status
Auth events are logged	✅
API key changes are logged	✅
Payment initiation events are logged	✅
Redemption events are logged	✅
Webhook config change events are logged	✅
Audit entries capture id, merchant_id, event_type, metadata, ip, and timestamp	✅
Audit trail is tamper-evident	✅
API builds successfully with audit logging enabled	✅
Audit log tests pass successfully	✅

How to Test

# 1. Confirm you're on the branch
git branch --show-current

# 2. Run the audit logging unit tests
pnpm --filter api test -- --runInBand audit-log.service.spec.ts

# 3. Verify the API builds successfully
pnpm --filter api build

# 4. Optional: run the API locally
pnpm --filter api start:dev

# 5. Optional: create an audit log entry
curl -X POST http://localhost:3000/audit-logs \
  -H "Content-Type: application/json" \
  -H "x-real-ip: 127.0.0.1" \
  -d '{
    "merchant_id": "merchant_123",
    "event_type": "payment.initiated",
    "metadata": {
      "paymentId": "pay_123",
      "amount": "100.00",
      "currency": "USD"
    }
  }'

# 6. Optional: verify the audit trail
curl http://localhost:3000/audit-logs/verify

# 7. Optional: inspect the changed files
git diff -- apps/api/src/app.module.ts apps/api/src/audit-log apps/api/.env.example

Screenshots

✅ Audit log tests pass

A screenshot of:

pnpm --filter api test -- --runInBand audit-log.service.spec.ts

✅ API build passes

A screenshot of:

pnpm --filter api build

✅ Audit log entry can be recorded

A screenshot of:

curl -X POST http://localhost:3000/audit-logs \
  -H "Content-Type: application/json" \
  -H "x-real-ip: 127.0.0.1" \
  -d '{
    "merchant_id": "merchant_123",
    "event_type": "payment.initiated",
    "metadata": {
      "paymentId": "pay_123",
      "amount": "100.00",
      "currency": "USD"
    }
  }'

✅ Audit trail verification works

A screenshot of:

curl http://localhost:3000/audit-logs/verify

[vercel]

@David-patrick-chuks is attempting to deploy a commit to the missblue00's projects Team on Vercel.

A member of the Team first needs to authorize it.

[drips-wave]

@David-patrick-chuks Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[MissBlue00]

@David-patrick-chuks the ci/cd check failed, please resolve