Harden backend boundary follow-up

Author: eldryoth

CHANGELOG.md

@@ -65,6 +65,11 @@
   clear-tail, wrapped, alloc, and in-place encode paths through it, giving
   future SIMD encode admission one audited integration point while preserving
   scalar-only runtime behavior.
+- Added the matching scalar-forced decode backend boundary for future decode
+  admission symmetry, changed the scalar in-place encode invariant to return an
+  error instead of panicking in release builds, tightened panic-policy scanning
+  for production equality assertions, and clarified that in-place clear-tail
+  errors intentionally clear original caller input.
 
 ## 1.1.0 - 2026-06-20
 

SECURITY.md

@@ -90,6 +90,10 @@ write buffers, allocator behavior, core dumps, swap, hibernation images,
 cold-boot remanence, hardware 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 in-place clear-tail methods, "whole buffer on error" includes any original
+plaintext or encoded input already present in the caller's buffer. Preserve a
+separate audit/retry copy before calling an in-place clear-tail API if recovery
+of the original input is required after a validation or sizing failure.
 
 High-assurance deployments handling classified or long-lived key material
 should pair `base64-ng` with OS and platform memory controls: locked memory

docs/PLAN.md

@@ -671,6 +671,9 @@ Current `1.1.x` checkpoint state:
   `encode_slice_clear_tail`, alloc encode helpers, wrapped encode helpers, and
   in-place encode now route through one audited encode backend boundary, with
   scalar-equivalence tests covering slice and in-place encode behavior.
+  Follow-up review also added the matching scalar-forced decode backend
+  boundary so future decode acceleration has a symmetric admission point, and
+  tightened panic-policy checks for production `assert_eq!`/`assert_ne!` sites.
 
 Planned checkpoints to reach `1.2.0` fully working encode acceleration:
 

docs/SECURITY_CONTROLS.md

@@ -98,6 +98,10 @@ certification claim.
   `ct::CtEngine::decode_slice_staged_clear_tail` when the caller-owned output
   buffer could be observed during the decode call, such as shared memory,
   sandbox boundaries, enclave-adjacent code, or multi-principal processes.
+- Treat in-place clear-tail APIs as destructive cleanup boundaries. On error,
+  they clear the full caller-provided buffer, including original plaintext or
+  encoded input. Preserve a separate audit/retry copy before calling them if
+  recovering the original input is part of the protocol.
 - Prefer fixed-size secret types generated by the `base64-ng-derive`
   `#[derive(Base64Secret)]` companion crate when protocol key sizes are known.
   The generated decode path uses staged CT decode, redacted `Debug`, and

docs/SIMD.md

@@ -29,7 +29,9 @@ The SIMD roadmap separates implementation evidence from active acceleration:
 - `1.1.5` adds the public encode backend boundary while still forcing scalar
   execution. This gives future accelerated encode admission one reviewed
   integration point for `encode_slice`, clear-tail helpers, alloc helpers,
-  wrapped helpers, and in-place encode.
+  wrapped helpers, and in-place encode. The same checkpoint also adds a
+  scalar-forced decode backend boundary for symmetry; decode acceleration
+  remains out of scope until the later decode line.
 - `1.2.0` is the release where encode acceleration must be fully working for
   the admitted encode scope. Public encode APIs must dispatch to admitted
   encode backends when runtime policy and CPU features allow it, and must fall

scripts/validate-panic-policy.sh

@@ -27,14 +27,14 @@ check_file() {
             }
             failed = 1
         }
-        /debug_assert!\(/ {
+        /debug_assert!\(|debug_assert_eq!\(|debug_assert_ne!\(/ {
             next
         }
         FILENAME == "src/engine/encode.rs" && $0 ~ /^[[:space:]]*assert!\($/ {
             pending_encode_array_assert = 1
             next
         }
-        /panic!\(|unreachable!\(|\.unwrap\(|\.expect\(|assert!\(/ {
+        /panic!\(|unreachable!\(|\.unwrap\(|\.expect\(|assert!\(|assert_eq!\(|assert_ne!\(/ {
             allowed = 0
             if ($0 ~ /assert!\(line_len != 0, "base64 line wrap length must be non-zero"\)/) {
                 allowed = 1
@@ -69,7 +69,7 @@ test -s docs/PANIC_POLICY.md
 
 find src -name '*.rs' | sort | while IFS= read -r source_file; do
     case "$source_file" in
-        src/kani_proofs.rs|src/tests.rs|src/simd/tests.rs)
+        src/kani_proofs.rs|src/tests.rs|src/simd/tests.rs|src/simd/wasm.rs)
             continue
             ;;
     esac

src/buffers/secret.rs

@@ -183,6 +183,10 @@ impl ExposedSecretString {
         let text = match string_from_validated_secret_bytes(bytes) {
             Ok(text) => text,
             Err(mut bytes) => {
+                // This branch is unreachable for bytes produced from a valid
+                // `String`. If unsafe upstream code violates that invariant,
+                // wipe the bytes and fail closed without introducing a
+                // release-mode panic in secret cleanup code.
                 wipe_vec_all(&mut bytes);
                 alloc::string::String::new()
             }

src/decode_backend.rs

@@ -0,0 +1,39 @@
+//! Decode backend dispatch boundary.
+//!
+//! This module mirrors the encode backend boundary. Decode acceleration remains
+//! inactive; future SIMD decode admission must update this boundary together
+//! with canonicality, error-shape, fallback, retention, timing, and release
+//! evidence.
+
+use crate::{Alphabet, DecodeError, scalar};
+
+/// Decode backend currently allowed to execute.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub(crate) enum DecodeBackend {
+    /// The audited scalar implementation.
+    Scalar,
+}
+
+/// Returns the decode backend selected for this build and target.
+#[must_use]
+pub(crate) fn active_decode_backend() -> DecodeBackend {
+    #[cfg(feature = "simd")]
+    match crate::simd::active_backend() {
+        crate::simd::ActiveBackend::Scalar => {}
+    }
+
+    DecodeBackend::Scalar
+}
+
+/// Decodes `input` into `output` through the admitted decode backend.
+pub(crate) fn decode_slice<A, const PAD: bool>(
+    input: &[u8],
+    output: &mut [u8],
+) -> Result<usize, DecodeError>
+where
+    A: Alphabet,
+{
+    match active_decode_backend() {
+        DecodeBackend::Scalar => scalar::decode_slice::<A, PAD>(input, output),
+    }
+}

src/engine/decode.rs

@@ -3,8 +3,8 @@ use crate::SecretBuffer;
 #[cfg(feature = "alloc")]
 use crate::validate_decode;
 use crate::{
-    Alphabet, DecodeError, DecodedBuffer, Engine, LineWrap, decode_legacy_to_slice,
-    decode_wrapped_to_slice, scalar, validate_legacy_decode, validate_wrapped_decode, wipe_bytes,
+    Alphabet, DecodeError, DecodedBuffer, Engine, LineWrap, decode_backend, decode_legacy_to_slice,
+    decode_wrapped_to_slice, validate_legacy_decode, validate_wrapped_decode, wipe_bytes,
     wipe_tail,
 };
 
@@ -33,7 +33,7 @@ where
     /// constant-time-oriented secret decoding.
     #[must_use = "handle decode errors; use crate::ct for secret-bearing payloads"]
     pub fn decode_slice(&self, input: &[u8], output: &mut [u8]) -> Result<usize, DecodeError> {
-        scalar::decode_slice::<A, PAD>(input, output)
+        decode_backend::decode_slice::<A, PAD>(input, output)
     }
 
     /// Decodes `input` into `output` and clears all bytes after the decoded

src/engine/encode_in_place.rs

@@ -40,7 +40,10 @@ where
     ///
     /// If encoding fails because `input_len` is too large, the output buffer is
     /// too small, or the encoded length overflows `usize`, the entire buffer is
-    /// cleared before the error is returned.
+    /// cleared before the error is returned. This includes the original
+    /// plaintext in `buffer[..input_len]`; keep another copy before calling
+    /// this method if recovery of the original input is required after an
+    /// error.
     ///
     /// # Examples
     ///