validationEvents property

A broadcast stream of definitive pin-validation verdicts, for field telemetry (recording suspected machine-in-the-middle incidents) and for monitoring a pinning rollout.

The underlying native listener is global: this one stream reports verdicts from every TrustPin instance, each event tagged with the TrustPinValidationEvent.instanceId that produced it ('default' for shared). The listener observes; it never decides — by the time an event arrives the connection has already been allowed or rejected, and nothing done with the event can change that verdict.

Failure events fire only for definitive pin verdicts (PINS_MISMATCH, ALL_PINS_EXPIRED, DOMAIN_NOT_REGISTERED in strict mode) and carry the presented leaf certificate as PEM — attacker-supplied data, so sanitize it before rendering or forwarding. Transient conditions (configuration fetch failures, timeouts) still fail verification through the documented error contract but produce no event. Success events fire when a registered domain's certificate matches a pin.

final subscription = TrustPin.validationEvents.listen((event) {
  if (event.isFailure) {
    analytics.recordPinningIncident(
      domain: event.domain,
      code: event.error!.code,
    );
  }
});

The native listener is installed when the first subscription starts and removed when the last one cancels.