[AmanKrSahu]

Overview

This Pull Request implements the enterprise audit logging and outbound event webhook infrastructure identified in the system roadmap (Tasks 2.23 [FR-2] and 3.1 [FR-3] in docs/audit/2026-07-20/task.md). It equips AuthKit with immutable security audit logging across all critical authentication/authorization lifecycles and provides an outbound webhook delivery engine with cryptographic signature verification, SSRF protection, automated retries with exponential backoff, and secret rotation grace windows.

---

Key Changes by Feature Area

1. Security Audit Logging System (Task 2.23 / FR-2)

• Immutable AuditLog Persistence Model: Added the AuditLog Prisma model with comprehensive indexes (userId, action, createdAt, ipAddress) to support high-throughput, structured querying.
• Unified AuditService: Introduced a centralized, non-blocking AuditService that captures structured actor data (userId, role, ipAddress, userAgent), event action types, status (SUCCESS, FAILURE), and contextual metadata with automatic sensitive field sanitization.
• Comprehensive Mutation Auditing: Integrated automatic audit logging across 100% of mutation flows including User Auth (Register, Login, Password Reset, Magic Link), MFA (Enable, Disable, Verify, Backup Codes), OIDC (Client Registration, Token Exchange, Consent), OAuth, and Admin operations (User Promotion, Session Revocation).
• Admin Audit Query API: Implemented GET /api/v1/admin/audit-logs featuring cursor-based pagination and flexible filtering by userId, action, status, and date ranges (startDate, endDate).

2. Webhooks & Outbound Event System (Task 3.1 / FR-3)

• Webhook Subscriptions & Delivery History: Added WebhookSubscription and WebhookDelivery models tracking subscription states (ACTIVE, DISABLED), event filters, failure counts, delivery attempts (PENDING, SUCCESS, FAILURE, RETRIES_EXCEEDED), and execution durations.
• Shared Event Catalog: Standardized application-wide domain events across 24 distinct catalog event types (covering auth, user, session, MFA, OIDC, and admin mutations) packaged in versioned event envelopes (evt_<id>, type, version, timestamp, data) with wildcard * subscription support.
• Cryptographic HMAC-SHA256 Signatures & Dual-Secret Rotation: Implemented deterministic X-Webhook-Signature headers (t=<timestamp>,v1=<signature>). Secret rotation provides a 24-hour dual-signature grace window emitting both v1 (current secret) and v1_old (previous secret) to eliminate client downtime.
• SSRF Defense & URL Validation: Built an SSRF guard that resolves target URLs, validates protocol/domain structures, and blocks all private/internal IPv4/IPv6 ranges (RFC 1918, RFC 3927, Loopback, Link-Local) and cloud metadata services.
• Reliable Delivery, Exponential Backoff & Queue Worker: Engineered a delivery pipeline with configurable timeouts (5s), exponential backoff retry schedules (10s, 1m, 5m, 15m), Retry-After header adherence, automatic subscription disabling after 10 consecutive failures, and a background queue worker for pending/retry processing.
• Payload Redaction & Safety: Enforced automatic key masking on sensitive HTTP response data (token, password, secret, authorization, jwt) and response body truncation (10 KB max) to protect upstream endpoints and database storage.

3. API & Controller Refactoring

• Admin Webhooks API (/api/v1/admin/webhooks): Implemented complete REST endpoints for subscription creation, cursor-paginated retrieval, ID lookups, updates, deletions, secret rotations, live delivery testing, and delivery attempt inspection.
• Single-Object Typed Service Interfaces: Refactored service methods across webhook.service.ts to accept strictly typed single-parameter objects, maintaining consistency with core architectural patterns.
• Separation of Utilities: Extracted signing, payload redaction, HTTP dispatching, and backoff calculations into src/core/common/utils/webhook.util.ts.

---

Documentation & API Specification Updates

• README.md: Updated feature capabilities and architecture descriptions to reflect audit logging and outbound webhook integrations.
• docs/api_endpoints.md: Restructured Section 7 (Admin) into clean subsections:
  • 7.1 User Management (/admin/users)
  • 7.2 Session Management (/admin/sessions)
  • 7.3 OIDC Client Management (/admin/oidc)
  • 7.4 Security Audit Logs (/admin/audit-logs)
  • 7.5 Webhooks (/admin/webhooks)
• Postman Collection (AuthKit.postman_collection.json): Added a dedicated Webhooks & Outbound Events subfolder inside 08. Admin Controls & Role Management containing all 7 parameterized webhook endpoints and automated post-response test assertions.
• OpenAPI / Swagger (docs/api-specs/openapi.json): Added detailed schemas, request bodies, and responses categorized under the Admin - Webhooks tag.
• Roadmap (docs/audit/2026-07-20/task.md): Marked Tasks 2.23 and 3.1 as Done.

---

Verification & Test Results

• End-to-End Live Receiver Verification: Executed live receiver tests simulating real HTTP delivery, payload validation, HMAC-SHA256 signature verification, 24h rotation grace periods, simulated 503 outage retries, and automated queue worker processing.
• Test Suite: 20/20 test suites passed (93/93 tests passing) covering unit, integration, SSRF security, and E2E journeys.
• Type Safety & Quality: Passed pnpm build, pnpm type-check (tsc --noEmit), pnpm lint (eslint), and pnpm format:check (prettier) with zero errors or warnings.