Address Tokio writer pentest follow-up

Author: eldryoth

crates/base64-ng-tokio/src/decoder_writer.rs

@@ -21,6 +21,9 @@ const DECODE_OUTPUT_CAP: usize = 1024;
 /// already have been written before a later malformed quantum is observed. For
 /// atomic or secret-bearing frames, collect a bounded frame and use a
 /// non-streaming strict or `ct` decode path.
+///
+/// I/O errors from the wrapped writer during drain do not set [`Self::is_failed`];
+/// only internal protocol or capacity violations latch a permanent failure.
 pub struct DecoderWriter<W, A, const PAD: bool>
 where
     A: Alphabet,

crates/base64-ng-tokio/src/encoder_writer.rs

@@ -23,6 +23,9 @@ const ENCODE_OUTPUT_CAP: usize = 1024;
 /// Internal cleanup is best-effort and limited to this adapter's fixed pending
 /// and output buffers. It cannot clear copies held by the wrapped writer, the
 /// caller's buffers, registers, caches, swap, or crash dumps.
+///
+/// I/O errors from the wrapped writer during drain do not set [`Self::is_failed`];
+/// only internal protocol or capacity violations latch a permanent failure.
 pub struct EncoderWriter<W, A, const PAD: bool>
 where
     A: Alphabet,

crates/base64-ng-tokio/tests/tokio_writer.rs

@@ -222,3 +222,71 @@ async fn streaming_encoder_writer_propagates_inner_write_error() {
     assert_eq!(error.kind(), std::io::ErrorKind::BrokenPipe);
     assert!(!writer.is_failed());
 }
+
+#[tokio::test]
+async fn streaming_encoder_writer_round_trips_large_input_with_one_byte_backpressure() {
+    let input: Vec<u8> = (0u8..=250).cycle().take(5000).collect();
+    let expected = STANDARD.encode_vec(&input).unwrap();
+    let inner = ScriptedWriter::new((0..expected.len()).map(|_| WriteAction::Accept(1)));
+    let mut writer = EncoderWriter::new(inner, STANDARD);
+
+    writer.write_all(&input).await.unwrap();
+    writer.shutdown().await.unwrap();
+
+    assert_eq!(writer.into_inner().output(), expected);
+}
+
+#[tokio::test]
+async fn streaming_decoder_writer_round_trips_large_input_with_one_byte_backpressure() {
+    let input: Vec<u8> = (0u8..=250).cycle().take(5000).collect();
+    let encoded = STANDARD.encode_vec(&input).unwrap();
+    let inner = ScriptedWriter::new((0..input.len()).map(|_| WriteAction::Accept(1)));
+    let mut writer = DecoderWriter::new(inner, STANDARD);
+
+    writer.write_all(&encoded).await.unwrap();
+    writer.shutdown().await.unwrap();
+
+    assert_eq!(writer.into_inner().output(), input);
+}
+
+#[tokio::test]
+async fn streaming_encoder_writer_clamps_single_large_poll_write_to_queue_capacity() {
+    let input: Vec<u8> = (0u8..=250).cycle().take(2000).collect();
+    let expected = STANDARD.encode_vec(&input).unwrap();
+    let mut writer = EncoderWriter::new(Vec::new(), STANDARD);
+    let waker = noop_waker();
+    let mut context = Context::from_waker(&waker);
+
+    let accepted = Pin::new(&mut writer)
+        .poll_write(&mut context, &input)
+        .map(|result| result.unwrap());
+
+    assert_eq!(accepted, Poll::Ready(768));
+    assert_eq!(writer.buffered_output_len(), 1024);
+
+    writer.write_all(&input[768..]).await.unwrap();
+    writer.shutdown().await.unwrap();
+
+    assert_eq!(writer.into_inner(), expected);
+}
+
+#[tokio::test]
+async fn streaming_decoder_writer_clamps_single_large_poll_write_to_queue_capacity() {
+    let input: Vec<u8> = (0u8..=250).cycle().take(2000).collect();
+    let encoded = STANDARD.encode_vec(&input).unwrap();
+    let mut writer = DecoderWriter::new(Vec::new(), STANDARD);
+    let waker = noop_waker();
+    let mut context = Context::from_waker(&waker);
+
+    let accepted = Pin::new(&mut writer)
+        .poll_write(&mut context, &encoded)
+        .map(|result| result.unwrap());
+
+    assert_eq!(accepted, Poll::Ready(1364));
+    assert_eq!(writer.buffered_output_len(), 1023);
+
+    writer.write_all(&encoded[1364..]).await.unwrap();
+    writer.shutdown().await.unwrap();
+
+    assert_eq!(writer.into_inner(), input);
+}

docs/PANIC_POLICY.md

@@ -57,10 +57,10 @@ The current reviewed exceptions are:
   length/allocation invariant break. Do not use them for untrusted length
   metadata, constrained allocation environments, or code paths that require
   recoverable errors; use the fallible encode helpers instead.
-- Stream `get_ref`, `get_mut`, and `into_inner` internal helpers use
-  `unreachable!` if a wrapper has already consumed its inner value. The public
-  API consumes `self` for `into_inner`/`finish`, so this state is not reachable
-  through safe public calls.
+- Core stream and Tokio writer `get_ref`, `get_mut`, and `into_inner` internal
+  helpers use `unreachable!` if a wrapper has already consumed its inner value.
+  The public API consumes `self` for `into_inner`/`finish`, so this state is not
+  reachable through safe public calls.
 
 Test code, doctest examples, and Kani proof harnesses may use `unwrap`,
 `expect`, or panic-like macros when they are asserting expected outcomes.

scripts/validate-panic-policy.sh

@@ -45,6 +45,9 @@ check_file() {
             if ($0 ~ /unreachable!\("stream .* was already taken"\)/) {
                 allowed = 1
             }
+            if ($0 ~ /unreachable!\("tokio .* writer inner writer was already taken"\)/) {
+                allowed = 1
+            }
             if ($0 ~ /unreachable!\("base64 encoder produced non-UTF-8 output"\)/) {
                 allowed = 1
             }
@@ -79,9 +82,9 @@ check_file() {
 
 test -s docs/PANIC_POLICY.md
 
-find src -name '*.rs' | sort | while IFS= read -r source_file; do
+find src crates/*/src -name '*.rs' | sort | while IFS= read -r source_file; do
     case "$source_file" in
-        src/encode_surface_tests.rs|src/kani_proofs.rs|src/tests.rs|src/simd/tests.rs|src/simd/wasm.rs|src/simd/neon_decode_tests.rs|src/simd/x86_decode_tests.rs)
+        src/encode_surface_tests.rs|src/kani_proofs.rs|src/tests.rs|src/simd/tests.rs|src/simd/wasm.rs|src/simd/neon_decode_tests.rs|src/simd/x86_decode_tests.rs|crates/*/src/tests.rs|crates/*/src/*_tests.rs)
             continue
             ;;
     esac

security/pentest/v1.3.1.md

@@ -0,0 +1,61 @@
+# base64-ng v1.3.1 Pentest Report
+
+Status: PASS WITH FOLLOW-UP FIXES
+
+Reviewed-Commit: d85a1fd Add Tokio async writer adapters
+Tester: Maintainer-supplied external pentest and CI review
+Scope: v1.3.0 through the Tokio async writer adapter checkpoint
+Date: 2026-07-03
+Report-Source: supplied `PENTEST.md` review for the `v1.3.0..HEAD`
+async writer adapter diff.
+
+## Scope
+
+Reviewed the new `base64-ng-tokio` writer adapter surface:
+
+- `crates/base64-ng-tokio/src/encoder_writer.rs`
+- `crates/base64-ng-tokio/src/decoder_writer.rs`
+- `crates/base64-ng-tokio/src/queue.rs`
+- public re-export and async documentation updates
+
+The review found no Critical, High, or exploitable memory-safety bugs. The
+reviewer noted that the Tokio companion crate denies unsafe code and that the
+new state machines use fixed internal buffers with explicit cleanup.
+
+## Findings
+
+The supplied report identified four follow-up items:
+
+1. Add a permanent `security/pentest/v1.3.1.md` artifact before tagging, so the
+   async writer admission has the same on-disk review trail as previous
+   releases.
+2. Extend panic-policy validation to companion crates. The old script scanned
+   only `src/`, so reviewed panic-like sites in `crates/*/src` were not covered
+   by the control.
+3. Add committed tests for large-input capacity-clamp and one-byte-backpressure
+   behavior in `EncoderWriter` and `DecoderWriter`.
+4. Document that wrapped-writer I/O errors during drain do not latch
+   `is_failed`; only internal protocol or capacity violations permanently fail
+   the adapter.
+
+## Remediation
+
+The follow-up commit after the review:
+
+- added this permanent pentest artifact,
+- updated `scripts/validate-panic-policy.sh` to scan `src` and `crates/*/src`,
+- documented the reviewed Tokio writer `unreachable!` pattern in
+  `docs/PANIC_POLICY.md`,
+- added large/backpressure Tokio writer regression tests, and
+- documented the retryable wrapped-writer I/O error behavior in both writer
+  adapter doc comments.
+
+## Verification
+
+Required verification for the remediation commit:
+
+- `cargo test -p base64-ng-tokio --all-features`
+- `cargo clippy -p base64-ng-tokio --all-targets --all-features -- -D warnings`
+- `scripts/checks.sh`
+
+The temporary `PENTEST.md` input is not retained in the repository.