Campaign_Tracker/_bmad-output/implementation-artifacts/1-5-shared-audit-logging-infrastructure.md

Story 1.5: Shared Audit Logging Infrastructure

Status: done

Story

As a a system, I want all security-relevant and operational events captured by a shared logging service, so that audit history is uniformly available across all application features from day one without per-feature implementation.

Acceptance Criteria

1. Given any security-relevant action occurs (auth event, permission check, privileged update) When the action completes Then the event is written to the audit log within 5 seconds including actor identity, timestamp (UTC), action type, resource identifier, and outcome (NFR7)
2. Given audit records are persisted When the retention policy is evaluated Then records are retained for at least 365 days and are not purgeable by standard application operations (NFR7)
3. Given any application feature calls the audit logging service When the call is made Then it succeeds using the shared service contract — the calling feature does not implement its own audit persistence
4. Given an audit record is written When retrieved for review Then it is append-only — no update or delete operations are available on audit records
5. Given the audit service is unavailable When an auditable action occurs Then the action is blocked or queued — auditable operations must not silently proceed without capture

Tasks / Subtasks

• Implement story behavior in aligned backend/frontend modules (AC: #1)
  • Add or update API/service/UI components required by the story scope
  • Keep legacy Access entities read-only and route writes to extension-layer structures
• Cover acceptance criteria #2 in implementation and tests (AC: #2)
  • Add validation/error handling and UX state updates as needed
• Cover acceptance criteria #3 in implementation and tests (AC: #3)
  • Add validation/error handling and UX state updates as needed
• Cover acceptance criteria #4 in implementation and tests (AC: #4)
  • Add validation/error handling and UX state updates as needed
• Validate and document completion evidence
  • Verify build/tests for touched modules
  • Capture changed files and any migration/config implications

Review Findings

• [Review][Patch] Audit timestamps are serialized with caller-provided offsets instead of normalized UTC [Campaign_Tracker.Server/Audit/AppendOnlyFileAuditService.cs:40]
• [Review][Patch] AuditEvent required fields are not validated at runtime before durable write [Campaign_Tracker.Server/Audit/IAuditService.cs:19]
• [Review][Patch] Token exchange and refresh authentication events bypass shared audit logging [Campaign_Tracker.Server/Controllers/AuthTokenController.cs:15]
• [Review][Patch] Authorization success and anonymous challenge outcomes are not uniformly audited [Campaign_Tracker.Server/Authorization/AuthorizationAuditResultHandler.cs:18]
• [Review][Patch] Integration test audit service ignores GetRecent maxCount contract [Campaign_Tracker.Server.Tests/AuthEndpointTests.cs:75]
• [Review][Patch] AppendOnlyFileAuditService.GetRecent accepts negative maxCount and can throw an incidental range exception [Campaign_Tracker.Server/Audit/AppendOnlyFileAuditService.cs:71]

Dev Notes

• Follow Epic 1 architecture constraints: ASP.NET Core + React separation, RBAC-aware patterns, and immutable legacy tables.
• Reuse shared component and workflow patterns defined in UX and architecture docs; avoid parallel custom implementations.
• Keep changes scoped to this story; do not pull forward Epic 2+ features.

Project Structure Notes

• Backend: Campaign_Tracker.Server/
• Frontend: campaign-tracker-client/
• Story artifacts: _bmad-output/implementation-artifacts/

References

• Story source: _bmad-output/planning-artifacts/epics.md (Epic 1 / Story 1.5)
• Architecture constraints: _bmad-output/planning-artifacts/architecture.md
• UX patterns: _bmad-output/planning-artifacts/ux-design-specification.md

Dev Agent Record

Agent Model Used

claude-sonnet-4-6

Debug Log References

• Story generated from epic source and architecture/UX planning artifacts.
• 2026-05-05: Created IAuditService, AuditEvent, AppendOnlyFileAuditService in Audit/ folder.
• 2026-05-05: Updated InMemoryAuthenticationAuditStore to delegate to IAuditService.
• 2026-05-05: Registered IAuditService in Program.cs (configurable via Audit:LogDirectory).
• 2026-05-05: Wrote AuditServiceTests (8 tests covering ACs #1–#5).
• 2026-05-05: Added AC #5 integration test; refactored AuthEndpointTests to use AuthIntegrationTestFactory.
• 2026-05-05: dotnet test passed — 23/23 tests.

Completion Notes List

• Story context created and marked ready-for-dev.
• Created IAuditService + AuditEvent general-purpose contract. AuditEventType constants centralise event names (SESSION_LOGIN, SESSION_LOGOUT, etc.). Interface is intentionally append-only: only Record() and GetRecent() — no delete or update methods (AC #4).
• Created AppendOnlyFileAuditService: writes JSON Lines to daily-rotating .jsonl files in a configurable directory. Files are never deleted by the service (AC #2). Record() wraps IO failures in AuditServiceUnavailableException and propagates, blocking the caller (AC #5).
• Updated InMemoryAuthenticationAuditStore to accept IAuditService via constructor injection. Each Record*() method enqueues to the in-memory queue (for fast test assertions) AND calls IAuditService.Record() for durable persistence. Exceptions from IAuditService.Record() propagate to the caller per AC #5.
• Registered IAuditService → AppendOnlyFileAuditService in Program.cs. Log directory is configurable via Audit:LogDirectory configuration key (defaults to <ContentRoot>/audit-logs).
• InMemoryAuthenticationAuditStore now uses constructor DI for IAuditService — satisfies AC #3 (calling features use shared contract, not own persistence).
• Refactored AuthEndpointTests to use AuthIntegrationTestFactory (custom WebApplicationFactory subclass) that injects an in-memory IAuditService passthrough. This keeps integration tests file-system-independent while the real file service is validated by AuditServiceTests. AC #5 integration test confirms that a failing IAuditService blocks the authenticated session endpoint.
• All 23 backend tests pass.
• Applied review fixes: audit timestamps are normalized to UTC, audit required fields are validated before durable writes, GetRecent has bounded argument handling, token exchange/refresh paths write shared audit events, and authorization allowed/challenged/denied outcomes are centrally audited.
• 2026-05-06: dotnet test .\Campaign_Tracker.Server.Tests\Campaign_Tracker.Server.Tests.csproj /p:UseAppHost=false passed (86 tests).
• 2026-05-06: dotnet build .\campaign-tracker.sln /p:UseAppHost=false passed with 0 warnings and 0 errors.

File List

• Campaign_Tracker.Server/Audit/IAuditService.cs
• Campaign_Tracker.Server/Audit/AppendOnlyFileAuditService.cs
• Campaign_Tracker.Server/Controllers/AuthTokenController.cs
• Campaign_Tracker.Server/Authorization/AuthorizationAuditResultHandler.cs
• Campaign_Tracker.Server/Authentication/InMemoryAuthenticationAuditStore.cs
• Campaign_Tracker.Server/Program.cs
• Campaign_Tracker.Server.Tests/AuditServiceTests.cs
• Campaign_Tracker.Server.Tests/AuthEndpointTests.cs
• _bmad-output/implementation-artifacts/1-5-shared-audit-logging-infrastructure.md
• _bmad-output/implementation-artifacts/sprint-status.yaml

Change Log

Date	Version	Description	Author
2026-05-05	1.0	Implemented shared audit logging infrastructure: IAuditService, AppendOnlyFileAuditService, InMemoryAuthenticationAuditStore refactor, Program.cs registration, AuditServiceTests, AuthEndpointTests refactor. 23/23 tests passing.	Amelia (Dev)
2026-05-06	1.1	Applied code-review fixes for UTC normalization, required-field validation, token/authorization audit coverage, and bounded recent-event retrieval. 86/86 backend tests passing.	GPT-5 Codex