TrustPinValidationListener

Observer of certificate-pinning validation outcomes.

Install with TrustPin.setValidationListener to learn when pin validation reaches a definitive verdict — the signal apps use for field telemetry (recording suspected machine-in-the-middle events) and for monitoring a pinning rollout.

The listener observes; it never decides

This is a deliberate security boundary: the listener has no return value, cannot veto or approve a connection, and any exception it throws is swallowed. The pinning verdict is fully decided before the listener is invoked and cannot be influenced from it — so tampering with the listener (or registering a hostile one) can at most blind the app's telemetry, never weaken pinning itself.

What is reported

onValidationFailure fires only for definitive pin verdicts: TrustPinError.PinsMismatch, TrustPinError.AllPinsExpired, and TrustPinError.DomainNotRegistered (strict mode). Transient conditions — configuration fetch failures, timeouts, lifecycle errors — still fail verification per the documented error contract but are not reported here; they are operational noise, not pin verdicts. onValidationSuccess fires when a registered domain's certificate matches a pin. Permissive-mode connections to unregistered domains produce no callback (no pin verdict was made), and verdicts served from the trust manager's internal cache do not re-notify — one evaluation, at most one callback.

Threading

Callbacks are delivered synchronously from SDK internals, including threads performing TLS handshakes. Implementations must be thread-safe and fast: do not block, do not perform network or disk I/O inline (enqueue instead), and do not call back into TrustPin from a callback.