Module self_tests 

Power-on + conditional self-tests for Phantom Protocol’s cryptographic primitives (FIPS 140-3 §7.7).

FIPS 140-3 requires that every approved algorithm pass a known-answer or pairwise-consistency test before it can be used for the first time after module power-up. This module exposes run_post — call it once at process start (typically from the embedder’s bootstrap before the first crate::api::PhantomSession::connect_with_transport or crate::api::PhantomListener::bind) to satisfy that requirement. Failure means a primitive returned a wrong answer or refused to initialize at all; in that case abort rather than serve traffic with a broken cryptographic module.

The library does not auto-invoke run_post — embedders pulling in phantom_protocol for non-FIPS deployments shouldn’t pay the (~ms) startup cost. The CAVP-style canonical vectors live in core/tests/cavp.rs (Phase 5.4); this module re-tests the same primitives via pairwise consistency + a fixed HKDF KAT, sufficient for a §7.7 POST without pulling the full CAVP corpus into the production binary.

Phase 5.5 (per docs/PROGRESS.md / docs/compliance/fips-readiness.md).

Enums

AeadStage

Stage at which a per-algorithm self-test failed. Lets the caller log “AES-GCM encrypt failed” vs “AES-GCM decrypt mismatch” instead of an opaque “self-test failed”.

KemStage

Stage at which the hybrid KEM round-trip failed.

SelfTestError

Top-level error surface. Each variant carries enough context for an operator to know which primitive misbehaved without pulling in long-form error types.

SignStage

Stage at which the hybrid signature round-trip failed.

Functions

ensure_post_passed

Process-global single-shot wrapper around run_post. The first call runs the POST and caches the verdict; subsequent calls return the cached verdict. Designed for the fips bootstrap path (PhantomListener::bind*, PhantomSession::connect*) which calls this before doing any cryptographic work — a failure short-circuits to CoreError::FipsSelfTestFailure instead of standing up a listener / session over broken primitives.

run_post

Run every per-algorithm self-test once and return Ok(()) only if all pass. Aborts at the first failure (do not continue with a broken cryptographic module). Designed to be called once at process start.