ICriticalHeaderHandler Interface
Abblix.Jwt
Abblix.Jwt
ICriticalHeaderHandler Interface
Recipient-side handler for one JWS 'crit' header extension spec (RFC 7515 §4.1.11). Covers «understood AND processed»: the handler applies the extension's recipient-side semantics via HandleAsync(CriticalHeaderContext, CancellationToken). The JOSE header parameter name the handler implements is the DI key it is registered under — see AddCriticalHeaderHandler<THandler>(this IServiceCollection, string) — so name and behaviour are inseparable: a name cannot be registered without a handler behind it.
public interface ICriticalHeaderHandler
Remarks
One method, HandleAsync(CriticalHeaderContext, CancellationToken), intentionally collapses «validate» and «handle». Every realistic crit extension reads the header, optionally performs side effects (consume a replay nonce, emit an audit event), and returns success or a typed error. Splitting into validate+handle methods would tear related code apart — nonce extraction, freshness check, and consumption are one logical step.
Two realistic processing modes share this shape:
- Validate-only — read the header value, compare against local policy, accept or reject. Pure function over the JWT. Examples: RFC 8225 'ppt' (PASSporT Type), enterprise-policy headers.
- Stateful handler — read the header value, mutate external state (replay-cache, audit log, counters), accept or reject. Example: ACME-style 'nonce' (RFC 8555 §6.5.2) consumption with atomic single-use semantics.
Signature-affecting crit extensions (RFC 7797 'b64' — Unencoded Payload Option) need a pre-signature hook that transforms the JWS Signing Input bytes, which MUST run before signature verification. That hook is a separate sibling contract on the signing pipeline (out of scope for this interface). A b64 implementation of THIS interface is a thin shim registered under "b64" that short-circuits to success — successful signature verification already proves the directive was honoured.
Register with AddCriticalHeaderHandler<THandler>(this IServiceCollection, string), passing the JOSE header parameter name as the DI key. One handler owns one name; a handler covering a family of related names registers under each.
Methods
ICriticalHeaderHandler.HandleAsync(CriticalHeaderContext, CancellationToken) Method
Apply the extension's recipient-side semantics. May read the parsed token (header and payload), consult external state via DI-injected dependencies (inject System.TimeProvider if the extension needs the clock), perform side effects, and reject the JWS by returning a non-null JwtValidationError. Return null on success.
System.Threading.Tasks.Task<Abblix.Jwt.JwtValidationError?> HandleAsync(Abblix.Jwt.CriticalHeaderContext context, System.Threading.CancellationToken cancellationToken);
Parameters
context CriticalHeaderContext
Per-call inputs: the parsed token and the validation parameters in force.
cancellationToken System.Threading.CancellationToken
Propagates cancellation to I/O-bound handlers (replay-store lookups, audit emitters).