docs [AI]

core/src/crypto/aead.rs

@@ -1,6 +1,24 @@
+//! Абстракция AEAD-шифрования над конкретным алгоритмом.
+//!
+//! Кодек ([`nrxp`](crate::nrxp)) работает не с ChaCha20-Poly1305 напрямую, а через
+//! трейт [`AeadPacker`]. Это развязывает горячий путь от выбора шифра: сегодня за
+//! трейтом стоит [`ChaChaStream`](super::chacha::ChaChaStream), завтра можно
+//! подставить другой AEAD без правок кодека, а в тестах — фейковую реализацию.
+
 use bytes::BytesMut;
 
+/// Шифрование «на месте» (in-place) для одного направления потока.
+///
+/// Обе операции мутируют переданный [`BytesMut`] прямо в его буфере — никаких
+/// промежуточных аллокаций и копий (zero-copy на горячем пути):
+/// - [`encrypt`](AeadPacker::encrypt) дописывает 16-байтовый тег аутентификации в
+///   конец буфера (вызывающий код заранее резервирует под него место);
+/// - [`decrypt`](AeadPacker::decrypt) проверяет тег и усекает буфер до открытого
+///   текста; при провале проверки возвращает ошибку и данные считаются
+///   скомпрометированными (tampering).
 pub(crate) trait AeadPacker {
+    /// Шифрует `data` на месте и дописывает тег аутентификации.
     fn encrypt(&mut self, data: &mut BytesMut) -> Result<(), chacha20poly1305::aead::Error>;
+    /// Расшифровывает `data` на месте и проверяет тег; `Err` ⇒ tampering.
     fn decrypt(&mut self, data: &mut BytesMut) -> Result<(), chacha20poly1305::aead::Error>;
 }