Document downstream zeroize layering

Author: eldryoth

CHANGELOG.md

@@ -19,6 +19,8 @@
 - Tightened security documentation for public ct success/failure and length
   boundaries, volatile best-effort cleanup limits, and const-array panic
   policy.
+- Added optional downstream guidance for applications that combine
+  caller-owned `base64-ng` buffers with their own admitted `zeroize` policy.
 
 ## 0.9.0 - 2026-05-17
 

SECURITY.md

@@ -82,6 +82,36 @@ observation, or other process memory disclosure bugs. Callers that require a
 platform-specific formal zeroization policy should apply that policy to their
 own buffers in addition to using crate cleanup APIs.
 
+For projects that already admit the `zeroize` crate in their own dependency
+policy, the recommended pattern is to keep `base64-ng` dependency-free and
+zeroize the caller-owned buffers at the application boundary:
+
+```rust
+use base64_ng::{STANDARD, decoded_capacity};
+use zeroize::Zeroize;
+
+let input = b"aGVsbG8=";
+let mut output = vec![0u8; decoded_capacity(input.len())];
+
+let result = STANDARD.decode_slice_clear_tail(input, &mut output);
+match result {
+    Ok(written) => {
+        // Use output[..written] here.
+        output.zeroize();
+    }
+    Err(err) => {
+        // decode_slice_clear_tail already cleared output; this is an
+        // application-policy extra cleanup step.
+        output.zeroize();
+        return Err(err);
+    }
+}
+# Ok::<(), base64_ng::DecodeError>(())
+```
+
+This pattern lets high-assurance applications use their approved cleanup
+wrapper while the `base64-ng` crate itself remains zero-runtime-dependency.
+
 The `SecretBuffer` owned wrapper is available with the `alloc` feature for
 sensitive encoded or decoded bytes that should not be accidentally logged. It
 redacts `Debug` and `Display`, requires explicit reveal methods, and clears

docs/DEPENDENCIES.md

@@ -81,6 +81,13 @@ These are product decisions as much as technical ones. The crate is allowed to
 remain smaller than the broader ecosystem when dependency-free APIs preserve
 explicit security semantics.
 
+Downstream applications may still combine `base64-ng` with their own approved
+dependencies. For example, a service with an existing `zeroize` policy can
+decode into a caller-owned buffer with `decode_slice_clear_tail` and then call
+`Zeroize::zeroize()` on that buffer after the protocol step is complete. That
+keeps the published `base64-ng` crate dependency-free while allowing the
+application to apply its local memory-cleanup policy at the ownership boundary.
+
 ## Isolated Tooling
 
 Fuzzing, benchmark, and timing-evidence dependencies may live in isolated

docs/SECURITY_CONTROLS.md

@@ -70,6 +70,9 @@ clear-tail APIs promptly and pair them with operating system and deployment
 controls that reduce crash dumps, swap, and broad memory disclosure exposure.
 If a platform requires a formal zeroization policy, apply that policy to
 caller-owned buffers in addition to the crate's dependency-free cleanup APIs.
+For applications that already admit `zeroize`, decode into caller-owned buffers
+and apply `Zeroize::zeroize()` after the Base64 step; `base64-ng` intentionally
+does not add that dependency for every user.
 
 ### Side-Channel Posture