LevelUp.Health.Auth 0.1.0

LevelUp.Health.Auth

Role / API-key / JWT auth-hardening for the LevelUp.Health backend packages (the asclepius P2 plane). Lifted faithfully from ares-elite/aegis-api's Aegis.API authorization, middleware, and JWT-hardening skeleton, with every Ares-specific string promoted to a configurable option and the patient-ownership rule generalized to a pluggable port.

This package is Result-free — it does not depend on LevelUp.Health.Abstractions. It composes onto LevelUp.ServiceDefaults* at the host (it ships no ServiceDefaults, AppHost, or god-method).

What's here

Consuming

builder.Services.AddHealthAuth(builder.Configuration);   // ApiKeySettings + AuthHardeningOptions + validator + CallerContext + default resolver + filters
builder.Services.AddJwtHardening();                       // 2-min clock skew, audience/issuer/lifetime validation

// Role-gated group (consumer supplies its own role strings — no fixed vocabulary ships):
var admin = app.MapGroup("/api/v1/admin").RequireRole("admin");

// Resource-ownership group: unscoped roles read anything; everyone else reads only what they own.
var history = app.MapGroup("/api/v1/history").RequireResourceOwnership("admin", "doctor", "trainer");

Seams (Ares coupling → option/port)

• AuthHardeningOptions (section AuthHardening) parameterizes the request shape, each value defaulting to the original Ares string:
  • headers — RoleHeaderName (X-User-Role), OwnedResourceIdHeaderName (X-User-Patient-Fhir-Id), ApiKeyHeaderName (X-API-Key), AdminApiKeyHeaderName (X-Admin-API-Key);
  • claims — RoleClaimType (role), OwnedResourceIdClaimType (patient_fhir_id);
  • ErrorTypeBaseUri (https://api.aegis.areselite.com/errors/) — the RFC 7807 problem type link base.
• ApiKeySettings (section ApiKeys) — the valid-key set the validator loads. Keys are hashed (HMAC-SHA256, keyed by a shared pepper in ApiKeyHashingOptions) rather than compared as plaintext, and the digest set is rebuilt live via IOptionsMonitor on config reload.
• Admin privilege is no longer an AuthHardeningOptions field. It is gated by a wholly separate, fail-secure store — AdminApiKeySettings (section AdminApiKeys) validated by IAdminApiKeyValidator / AdminApiKeyValidator — so a key present only in ApiKeySettings can never satisfy an admin check, and an unconfigured admin store rejects every admin request.
• IResourceOwnershipResolver is the ownership port behind ResourceOwnershipFilter (replacing Ares' PatientSelfReadFilter). The shipped default, SelfReadResourceOwnershipResolver, allows a read when the requested resource id equals the caller's own id (URL-decoded, ordinal, fail-closed). Ares' patient/Person.link-graph specifics are not shipped — a consumer needing graph-based ownership registers its own IResourceOwnershipResolver.
• No Roles constants. RoleRequirementFilter / ResourceOwnershipFilter take consumer-supplied role strings; the Ares clinical role vocabulary (doctor/athlete/client_admin/…) does not ship (spec R5.3).

Security guarantees (kill-probe-validated)

• JWT hardening is verbatim — ClockSkew = 2 min, ValidateAudience/ValidateIssuer/ValidateLifetime = true (spec R5.2).
• RoleRequirementFilter is fail-closed and gives JWT claim precedence over the trusted header — an authenticated JWT with no/insufficient role is denied even when a spoofed role header is present.
• ApiKeyValidator rejects unknown and blank keys, comparing HMAC-hashed digests rather than plaintext.
• AdminApiKeyValidator is fail-secure — with no admin keys configured, every admin request is rejected (no special-case bypass).
• ResourceOwnershipFilter is fail-closed — a missing role, requested id, or caller id denies access.