Clarify high-assurance audit caveats

Author: eldryoth

CHANGELOG.md

@@ -51,6 +51,10 @@
 - Hardened the workspace publish helper so real crates.io publishing requires
   `HEAD` to match a verified signed `v<version>` tag, and documented the
   `git tag -v` release check.
+- Tightened high-assurance documentation after follow-up audit review: clarified
+  conservative tail wiping, `DecodedBuffer` clone duplication, public-length
+  `subtle` comparisons, strict decode error logging, AArch64/RISC-V deployment
+  policy checks, and wrapped in-place decode retention behavior.
 
 ## 1.1.0 - 2026-06-20
 

crates/base64-ng-subtle/src/lib.rs

@@ -12,7 +12,9 @@
 //!
 //! Length is treated as public. Mismatched lengths return
 //! [`subtle::Choice::from(0)`] immediately. Use fixed-size protocol tokens when
-//! length must not vary.
+//! length must not vary. When the length itself is secret, compare fixed-size
+//! arrays or fixed-width protocol buffers directly with
+//! [`subtle::ConstantTimeEq`] instead of this public-length helper.
 
 use base64_ng::{DecodedBuffer, EncodedBuffer};
 use subtle::{Choice, ConstantTimeEq};
@@ -77,6 +79,9 @@ impl SubtleEqExt for SecretBuffer {
 ///
 /// Equal-length comparisons are delegated to [`subtle::ConstantTimeEq`].
 /// Mismatched lengths return `Choice::from(0)` immediately.
+///
+/// Use [`subtle::ConstantTimeEq`] directly on fixed-size arrays or fixed-width
+/// protocol buffers when token length must not be observable.
 #[must_use = "use Choice or convert it deliberately with bool::from(choice)"]
 pub fn subtle_ct_eq_public_len(left: &[u8], right: &[u8]) -> Choice {
     if left.len() == right.len() {

docs/SECURITY_CONTROLS.md

@@ -87,6 +87,12 @@ certification claim.
   On AArch64, failure is expected unless the operator has attested CSDB
   effectiveness with `--cfg base64_ng_aarch64_csdb_attested`; do not use that
   cfg without processor, BSP, or certification evidence.
+  Deployment CI for a certified AArch64 target should run the application or
+  integration test suite with the same `RUSTFLAGS` and assert that this startup
+  policy passes. Generic project CI must not set that cfg because it would turn
+  an operator attestation into an unreviewed build default. RISC-V and 32-bit
+  ARM targets should expect this policy to fail unless the platform provides
+  external Spectre-v1 mitigation evidence.
 - Decode tokens, wrapped keys, MAC-adjacent payloads, and equivalent
   secret-bearing Base64 through `base64_ng::ct`. Use
   `ct::CtEngine::decode_slice_staged_clear_tail` when the caller-owned output
@@ -130,6 +136,13 @@ secret-adjacent tokens, or attacker-probed fragments of those values. Use
 `DecodeError::kind()` for redacted logging, or use the `ct` module for opaque
 malformed-content errors.
 
+```rust
+let err = base64_ng::STANDARD
+    .decode_buffer::<32>(input)
+    .unwrap_err();
+tracing::warn!(error_kind = %err.kind(), "base64 decode failed");
+```
+
 Legacy whitespace handling is opt-in through explicitly named APIs. Wrapped
 profiles are strict about the configured line ending and non-final line width.
 

src/buffers/decoded.rs

@@ -10,6 +10,14 @@ use crate::{DecodeError, STANDARD, constant_time_eq_public_len, wipe_bytes, wipe
 /// The backing array is cleared when the value is dropped. This is best-effort
 /// data-retention reduction and is not a formal zeroization guarantee.
 ///
+/// # Security: cloning
+///
+/// This type implements [`Clone`] for no-alloc ergonomics, but cloning
+/// duplicates decoded bytes. The compiler may also create temporary
+/// intermediates during the copy that are outside this crate's cleanup
+/// boundary. For heap-owned key material, prefer the alloc-gated
+/// `SecretBuffer`, which does not implement `Clone`.
+///
 /// On `wasm32` targets, the wipe barrier uses only a compiler fence. The wasm
 /// runtime JIT may still optimize or retain cleared bytes in ways this crate
 /// cannot control. `wasm32` builds fail closed by default; enable

src/cleanup.rs

@@ -95,6 +95,9 @@ fn wipe_barrier(ptr: *mut u8, len: usize) {
 pub(crate) fn wipe_tail(bytes: &mut [u8], start: usize) {
     debug_assert!(start <= bytes.len(), "wipe_tail start exceeds slice length");
     if start > bytes.len() {
+        // A caller that asks to wipe past the end has violated the helper's
+        // invariant. In release builds, fail closed by wiping everything
+        // instead of silently retaining bytes because of a bad offset.
         wipe_bytes(bytes);
         return;
     }

src/engine/decode_in_place.rs

@@ -26,7 +26,10 @@ where
     /// Use
     /// [`Self::decode_in_place_wrapped_clear_tail`] when the buffer may be
     /// reused or freed without a caller-managed wipe; treat that clear-tail
-    /// variant as the default for secret-bearing wrapped payloads.
+    /// variant as the default for secret-bearing wrapped payloads. If the
+    /// original encoded input must be preserved for audit logging or retry,
+    /// copy it before calling any in-place decode method or use a slice-output
+    /// decode API instead.
     ///
     /// # Examples
     ///

src/errors.rs

@@ -63,6 +63,14 @@ impl std::error::Error for EncodeError {}
 /// intentionally prints those diagnostics for developer-facing debugging. Do
 /// not log or return full [`DecodeError`] values for secret-bearing input; log
 /// [`Self::kind`] instead.
+///
+/// ```
+/// use base64_ng::STANDARD;
+///
+/// let err = STANDARD.decode_buffer::<8>(b"!!!!").unwrap_err();
+/// // Production logs should use the redacted class, not `{err}`.
+/// assert_eq!(err.kind().as_str(), "invalid-byte");
+/// ```
 #[derive(Clone, Copy, Eq, PartialEq)]
 pub enum DecodeError {
     /// The encoded input is malformed, but the decoder intentionally does not