LevelUp.Health.Audit 0.1.0

LevelUp.Health.Audit

PHI-access audit skeleton for the LevelUp.Health backend packages (the asclepius P2 plane). Lifted faithfully from ares-elite/aegis-api's Compliance code: the IEndpointFilter that records every PHI touch, the audit event + sink service, the bounded-channel batching flusher and its BackgroundService, the PII-stripped DCR ingestion entry, and the managed-identity Data-Collection-Rule (DCR) ingestion client.

This package is Result-free — it does not depend on LevelUp.Health.Abstractions. It references the ASP.NET shared framework (Microsoft.AspNetCore.App) for IEndpointFilter / HttpContext / BackgroundService and Azure.Identity for the DCR managed-identity bearer token.

What's here

Seams (what the consumer fills)

The package ships no routes and no clinical audit verbs — those are Ares domain. Two seams:

• IPhiEndpointRegistry — the port that maps (routePattern, httpMethod) → PhiEndpointMapping?. Ares' 33 hardcoded /Patient, /api/v1/drill-sessions, /api/v1/evaluations, /api/v1/admin/* routes do not ship. PhiAccessAuditFilter depends only on this port. The consuming app implements it (e.g. a small in-memory table) to declare which of its endpoints touch PHI.
• Audit action is a string — carried by PhiEndpointMapping.Action and PhiAuditEvent.Action. There is no fixed enum of clinical verbs to fork; any vocabulary works. The only behavioural escalation that keys off an action is emergency break-glass (logged at Critical), keyed off the shared PhiAuditActions.BreakGlassAccess label.

Consuming it

// 1. Register your route→PHI map and the audit pipeline.
builder.Services.AddSingleton<IPhiEndpointRegistry, MyPhiEndpointRegistry>();
builder.Services.AddPhiAccessAudit();

// 2. (Optional) stream a PII-stripped copy to an Azure Monitor DCR custom table.
//    Opt-in: disabled / unconfigured ⇒ the hosted flush service never starts.
builder.Services.AddPhiAuditDcrIngestion(builder.Configuration);

// 3. Attach the filter to the PHI endpoints.
app.MapGet("/Patient/{patientId}", GetPatient)
   .AddEndpointFilter<PhiAccessAuditFilter>();

The filter calls next() first, then records — so the audit event carries the real response status. It never throws into the request path: a missing mapping, a missing sink, or a failed DCR flush all leave the request served (fail-open for the request; logging is the primary record).

Configuration

PhiAuditIngestionSettings (section Monitor) — DceEndpoint, DcrImmutableId, Enabled, plus StreamName (default Custom-PHIAudit_CL) and ApiVersion (default 2023-01-01). Ingestion is opt-in: IsConfigured() must be true (enabled + endpoint + rule id) for the hosted service to run.

AuditApiKeyOptions (section PhiAudit:ApiKey) — HeaderName (default X-API-Key), the header the filter reads for the audited-user fallback when there is no authenticated JWT identity.

HIPAA controls preserved

PhiAuditIngestionEntry intentionally omits IpAddress and UserAgent (HIPAA minimum-necessary); PhiAuditService.ToIngestionEntry strips them before transmission. The DCR client carries no Azure.Monitor.Ingestion dependency — a plain HttpClient + System.Net.Http.Json POST with a https://monitor.azure.com/.default managed-identity bearer token.