Module crypto 

Crypto-erasure coordinator — Tier-1+ AEAD envelope encryption.

Provides:

• Dek — 32-byte key material with zeroise-on-drop semantics. The runtime never handles wrapped key material; that lives in the HSM/KMS backend.
• EncryptedPii — generic wrapper over an opaque ciphertext + tag + nonce + DekId + AeadKind. The wire tag binds the PII marker (T::PII_CODE) via AAD, defeating the type-confused-deputy path.
• CryptoCoordinator — stateful entry-point that dispatches encrypt / decrypt by the shell manifest’s declared AeadKind and compliance tier. Under the default (Tier-0) feature set the coordinator refuses encryption with PiiError::TierTooLow.
• rotate_dek — slice-level DEK rotation helper. Callers must hold a single-writer lock; the helper is atomic per-element and rolls the whole slice back on the first failure.

Feature matrix:

Feature	XChaCha20-Poly1305	AES-256-GCM	AES-256-GCM-SIV
(default — Tier-0)	rejected	rejected	rejected
tier-1-kms	✓	rejected	rejected
tier-2-multi-kms	✓	✓	✓

The coordinator’s public surface is stable. HSM / KMS wrap-unwrap integration and the Sigstore transparency anchor route through hf2_kms.

Structs

CryptoCoordinator

Tier-1+ AEAD coordinator.

Dek

Per-user 32-byte DEK material. The byte buffer is wiped on Drop via the zeroize crate; callers obtain a Dek from an HSM unwrap — the runtime never derives key material directly (envelope encryption).

DekConfig

Construction-time configuration for a Dek. Single-writer deployments use the default (all fields zero); federation builds populate replica_id from the per-instance manifest anchor so two regions sharing the same DEK material cannot collide their deterministic nonces (the F6 invocation-field reservation).

EncryptedPii

Per-PII-marker ciphertext envelope.

OsNonceSource

OS-backed nonce source. On tier-1-kms / tier-2-multi-kms this pulls from the underlying AEAD crate’s default RNG hook (itself getrandom-backed). On the default feature set it is still constructible — encryption paths reject before the nonce source is consulted.

Enums

NonceBytes

Per-AEAD-kind nonce carrier — XChaCha20-Poly1305 uses 24 bytes, the AES-256-GCM family uses 12. A single variant enum keeps the on-wire layout round-trip stable under postcard. Variants use postcard’s default untagged discriminant (enum index byte).

Traits

NonceSource

Per-kind nonce generator. Production uses OsNonceSource (the getrandom syscall wrapper baked into the AEAD crates). Tests plug in a fixed value for bit-identical fixtures.

Functions

rotate_dek

Re-wrap every element of ciphertexts under new_dek using a fresh new_dek_id. Decrypts under old_dek first, re-encrypts under the new key material, and rolls the slice back if any element fails (atomic-per-call semantics).

rotation_advice

Helper — extract the rotation trigger for a post-rotation counter.