docs(stack-encrypt): state the Kms and Aead outcomes of a wrong blob context

ZeroKMS refuses a wrong context's descriptor before the AEAD runs, so it
surfaces as Error::Kms; only a key source that ignores descriptors reaches
Error::Aead. Say so in the blob module docs and the changelog, as the crate
docs do, and limit the authentic-ciphertext claim to OpenedType and Blob.

Author: coderdan

packages/stack-encrypt/CHANGELOG.md

@@ -52,9 +52,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   any key is requested), and after the leaf authenticated, `blob_not_a_blob`,
   `blob_unsupported_version` (a later storage version: upgrade the reader),
   `blob_malformed` and `blob_mismatch` (a well-formed blob of another shape or
-  type). Every decrypt-side `Blob` error means the ciphertext was authentic;
-  tampering and a wrong context are still `Aead`, and a blob opened as a
-  scalar or a scalar as a blob is `OpenedType`. No message or payload names a
+  type). Every decrypt-side `Blob` error means the ciphertext was authentic.
+  Tampering is still `Aead`; a wrong context is refused by ZeroKMS before
+  the AEAD runs and surfaces as `Kms` (only a key source that ignores
+  descriptors, such as `FakeDataKeySource`, lets it reach the AEAD as
+  `Aead`); and a blob opened as a scalar or a scalar as a blob is
+  `OpenedType`. No message or payload names a
   value; a mismatch's payload names the declared field.
 - **`Zeroizing<T>` as the opt-in drop-guarded result** of the scalar API:
   `OpaqueDecode` is implemented for `Zeroizing<P>` of any decodable `P`, so

packages/stack-encrypt/src/blob.rs

@@ -148,10 +148,15 @@
 //!
 //! Decryption **authenticates before it decodes**. The leaf opens first,
 //! under its key and context; only then does the profile's reader see the
-//! bytes. So the errors tell three things apart:
-//!
-//! - [`Error::Aead`]: the leaf did not open. Wrong key, wrong context, or
-//!   altered bytes; the blob was never looked at.
+//! bytes. A context other than the one the blob was sealed under is
+//! normally refused before that: ZeroKMS binds each data key to its
+//! context's descriptor and denies the retrieve, so it surfaces as
+//! [`Error::Kms`] and nothing is decrypted. Past key retrieval, the errors
+//! tell three things apart:
+//!
+//! - [`Error::Aead`]: the leaf did not open. Altered bytes, the wrong key,
+//!   or a wrong context under a key source that ignores descriptors
+//!   (`FakeDataKeySource`, in tests); the blob was never looked at.
 //! - [`Error::OpenedType`]: the leaf opened but is not a bytes leaf: it was
 //!   sealed as a `String` or an integer, say, not as a blob.
 //! - [`Error::Blob`]: the leaf opened as bytes and they are not a blob this
@@ -160,9 +165,10 @@
 //!   of version 1 ([`BlobError::Malformed`]), or a well-formed blob that is
 //!   not a `T` ([`BlobError::Mismatch`]).
 //!
-//! All three are refusals of an authentic ciphertext, so an `Error::Blob`
-//! never says the data was tampered with; it says the data was written as
-//! something else. The whole blob is validated before `T`'s `Deserialize`
+//! [`Error::OpenedType`] and [`Error::Blob`] are refusals of an authentic
+//! ciphertext, so neither says the data was tampered with; each says the
+//! data was written as something else. Only [`Error::Aead`] (or
+//! [`Error::Kms`]) leaves the ciphertext's authenticity unestablished. The whole blob is validated before `T`'s `Deserialize`
 //! sees any of it: every length is checked against the end of the blob, so
 //! a forged length allocates nothing, and a `Deserialize` impl never builds
 //! part of a value from a malformed blob. No refusal names a value or a map
@@ -238,6 +244,7 @@
 //! with its marker; both readers read either form).
 //!
 //! [`Error::Aead`]: crate::Error::Aead
+//! [`Error::Kms`]: crate::Error::Kms
 //! [`Error::OpenedType`]: crate::Error::OpenedType
 //! [`Error::Blob`]: crate::Error::Blob
 //! [`KeysetCipher::encrypt`]: crate::KeysetCipher::encrypt