fix(sphragis): return typed entropy failures instead of panicking

[forkwright]

Summary

OsRng.fill_bytes panics on OS-RNG failure (rand_core 0.6 os.rs), and this crate called it directly at three sites: HybridKem::generate, EncapsulationKey::encapsulate, and the AEAD nonce draw inside seal_for. A recoverable host entropy failure (an early-boot RNG-not-seeded window, a sandboxed/misconfigured environment getrandom cannot service) crashed the process instead of returning a SealError.

Every entropy draw now goes through try_fill_bytes and propagates as a new SealError::Entropy { source: rand_core::Error, location }. HybridKem::generate becomes fallible. The RNG is caller-injectable at each site (generate_with_rng, encapsulate_with_rng, seal_for_with_rng, each &mut R: RngCore + CryptoRng) — the trait bound x25519-dalek's own random_from_rng requires — because the OS RNG cannot be made to fail on demand and this is the only way to prove the typed-error path under test. rand_core's std feature is now enabled (alongside getrandom) so rand_core::Error implements std::error::Error and chains behind SealError::Entropy's source field rather than being flattened to a string.

Closes #16

Breaking change

HybridKem::generate() -> (DecapsulationKey, EncapsulationKey) is now HybridKem::generate() -> Result<(DecapsulationKey, EncapsulationKey), SealError>. Taken deliberately, per the issue, before the preview-pq API stabilizes. akroasis consumes sphragis via an unpinned bare git = reference and will take this break on its next build.

EncapsulationKey::encapsulate and seal_for keep their existing Result<_, SealError> signatures — adding SealError::Entropy to what they can return is non-breaking against #[non_exhaustive].

What I verified, not just assumed

• rand_core::Error does not implement std::error::Error under this crate's prior feature set (getrandom only, no std) — confirmed by reading rand_core-0.6.4/src/error.rs, where the impl std::error::Error for Error block is #[cfg(feature = "std")]-gated off. Enabling std (additive, no new transitive dependencies — Cargo.lock is unchanged) was necessary before SealError::Entropy's source field could compile against .context().
• The injected-RNG bound is &mut R rather than x25519-dalek's by-value T, deliberately: seal_for_with_rng draws twice per recipient across N recipients from the same RNG, and a mid-batch injected-failure test needs that RNG's state to survive across draws, which a take-and-drop-per-call parameter would not allow.

Test evidence (the failing-test-before)

The OS RNG cannot be made to fail on demand, so there is no way to git-bisect a literal "same test, red before / green after" against main — the injectable seam this PR adds is what makes the defect observable at all. tests/entropy_failure.rs's injected CountdownRng (succeeds N calls, then fails every call after) drives generate_with_rng, encapsulate_with_rng, and seal_for_with_rng — including mid-batch across two recipients, and specifically isolating the nonce draw from the encapsulation draw inside seal_for_with_rng — asserting every case returns Err(SealError::Entropy { .. }) with a call-site-accurate location, never panics.

The mock's own fill_bytes (the trait's infallible method, distinct from the try_fill_bytes production code calls) is written to .expect()-panic if anything ever calls it — mirroring exactly what real OsRng::fill_bytes does on failure — so it doubles as a live check that production code has not regressed onto the panicking path: if any _with_rng call site were reverted to .fill_bytes(), generate_with_rng_returns_entropy_error_not_panic (which injects a zero-succeeds CountdownRng) would abort with CountdownRng: production code must use try_fill_bytes, not fill_bytes instead of returning Err.

cargo build --features preview-pq and cargo fmt --all -- --check were confirmed clean locally before the first push. metis was under sustained heavy load from a concurrent fleet-wide push at the time (uptime load average in the 20s-30s against an 8-core box, vgate admits nothing above ~7.2), so the full local cargo clippy --all-targets --features preview-pq -- -D warnings / cargo test --features preview-pq run never got admitted before I pushed — CI (ci.yml + the gate/full-gate-build reusable workflow, both GitHub-hosted ubuntu-latest, uncontended) is what actually ran both, and caught three real findings the local cargo build-only check couldn't have: clippy::similar_names (the new rng parameter next to a pre-existing local named rnd) and two more clippy::expect_used/clippy::panic misses in the new test file itself (this crate's [lints.clippy] denies those crate-wide, including tests/*.rs, and I'd only carried over unwrap_used's file-level #![expect] from the existing test files' convention, not the other two). All fixed in follow-up commits on this branch; CI is green as of the current HEAD.

Also fixed inline (adjacent, not scope creep)

CHANGELOG.md had a stale ## [Unreleased] heading sitting below the already-released 0.1.2/0.1.1 sections — its rich prose documented commits already shipped in 0.1.1 (issues #1/#3/#4/#6), mislabeled as unreleased. Removed the stale heading (the prose now reads as 0.1.1 detail, where it belongs) and opened a fresh ## [Unreleased] at the top for this change.

Filed, not bundled

Found two adjacent issues while in this code and filed them separately rather than growing this diff:

• SharedSecret's derived Debug prints the raw X-Wing shared secret #25 — SharedSecret's derived Debug prints the raw shared secret (the same class of leak DecapsulationKey already got a manual redacting Debug for).
• Retrofit #[snafu(implicit)] location onto SealError's remaining variants #26 — SealError's seven pre-existing variants lack #[snafu(implicit)] location per the fleet Rust standard; retrofitting it touches every fallible construction site in three files and is a poor fit for this PR's diff.

[forkwright]

Rebased onto current main (now carrying #24 bounded-CBOR, #27 KAT provenance lock, #32 public-API narrowing). Conflicts in Cargo.toml, DECISION.md, README.md, src/hybrid.rs, src/lib.rs resolved by hand; src/seal.rs/tests/known_answer_vectors.rs auto-merged.

Two coherence decisions this rebase had to make, since #32 landed after this branch was written:

• HybridKem::generate_with_rng / EncapsulationKey::encapsulate_with_rng now follow feat(sphragis): narrow the public API to the envelope profile, define the adapter seam #32's own pub(crate)-without-hazmat / pub-with-hazmat split, matching generate/encapsulate/decapsulate. tests/entropy_failure.rs names HybridKem directly, so it now requires hazmat too (new [[test]] block in Cargo.toml, mirroring known_answer_vectors) — the runtime logic under test doesn't change with the feature flag, only what's pub vs pub(crate).
• EncapsulationKey::encapsulate (the fixed-OsRng convenience wrapper) turned out to have no internal caller at all once combined with feat(sphragis): narrow the public API to the envelope profile, define the adapter seam #32: seal_for now goes through seal_for_with_rng, which is generic over the RNG and calls encapsulate_with_rng directly, never encapsulate. Without hazmat that's dead_code under -D warnings (caught by CI, not by me first) — fixed by making encapsulate hazmat-only outright, no pub(crate) variant.
• generate_recipient_keypair becomes fallible along with HybridKem::generate (it's a thin wrapper); tests/profile_api.rs (added by feat(sphragis): narrow the public API to the envelope profile, define the adapter seam #32, exercises the narrowed API without hazmat) updated to match.

DECISION.md §9/§10 and README.md's example updated to describe the merged state accurately, not the pre-#32 one. CI green on the current head (cargo test/check/clippy × default/preview-pq/preview-pq,hazmat, gate/full-gate-build, security scans).

[forkwright]

Rebased onto current main (now carrying merged #31). No textual conflicts — #31's changes (the SharedSecret pub(crate)/pub split, privatizing encapsulate_deterministic, relocating the KAT test) and this branch's changes (the generate/generate_with_rng/encapsulate_with_rng split, encapsulate's hazmat-only gating) sit in non-overlapping regions of src/hybrid.rs.

Checked the two specific things flagged for this rebase, by reading the merged file:

1. No duplicate/contradictory hazmat split. generate_with_rng/encapsulate_with_rng's split is not redundant with fix(sphragis)!: make deterministic encapsulation private #31's SharedSecret split — it's a different axis (method reachability vs. type reachability) and the two are now mutually dependent: encapsulate_with_rng returns a SharedSecret, and since fix(sphragis)!: make deterministic encapsulation private #31 made that type pub(crate) without hazmat, an unconditionally-pub encapsulate_with_rng would now be a private_interfaces violation (a public fn leaking a pub(crate) type). The split I added is load-bearing for that reason, not just convention-following. generate_with_rng doesn't touch SharedSecret at all — its split exists solely to match HybridKem's own reachability (a method on a pub(crate)-without-hazmat type). One coherent story: every seam's visibility tracks the visibility of the types it touches.
2. EncapsulationKey::encapsulate stays hazmat-only, and the premise still holds. fix(sphragis)!: make deterministic encapsulation private #31 didn't touch src/seal.rs at all — seal_for_with_rng still calls ek.encapsulate_with_rng(rng) directly, never ek.encapsulate(), so the fixed-OsRng wrapper still has zero internal callers without hazmat. fix(sphragis)!: make deterministic encapsulation private #31's relocated KAT test (in src/hybrid.rs's own mod tests) calls encapsulate_deterministic and decapsulate directly, not encapsulate() either. tests/known_answer_vectors.rs (still hazmat-required) is still encapsulate's only caller, at 4 call sites, unchanged. Nothing reopened the reachability gap.

Also fixed a small positional error in the SharedSecret doc comment from my own #31 rebase work — it said "matching HybridKem's gating above," but HybridKem's split is declared after SharedSecret's in the file, not before.

CI green on the current head. Not merging — leaving that to you.