Document pentest boundary findings

Author: eldryoth

CHANGELOG.md

@@ -16,6 +16,9 @@
 - Classified stream adapters and error types for the `v1.0` audit, preserving
   fail-closed decode, checked recovery, framed-reader, localized diagnostic,
   and opaque constant-time-oriented error boundaries.
+- Tightened security documentation for public ct success/failure and length
+  boundaries, volatile best-effort cleanup limits, and const-array panic
+  policy.
 
 ## 0.9.0 - 2026-05-17
 

README.md

@@ -155,6 +155,8 @@ assert_eq!(&URL_BYTES, b"-_8");
 Stable Rust cannot yet express the encoded length as the return array length
 directly, so `encode_array` uses the destination array type supplied by the
 caller. A wrong output length fails during const evaluation.
+Use `encode_array` for fixed-size static values, not for runtime data whose
+size is controlled by an attacker.
 
 For untrusted length metadata, use checked length calculation:
 
@@ -656,6 +658,9 @@ Security commitments:
   standard ASCII assumptions. Its malformed-input errors are intentionally
   non-localized, clear-tail variants clear caller-owned buffers on error, and
   it is not documented as a formally verified cryptographic constant-time API.
+  Input length, padding length, decoded length, and final success/failure are
+  public; callers that need protocol-level success/failure timing resistance
+  should continue with fixed-shape dummy downstream work after decode failure.
 - Clear-tail encode/decode variants are available for callers that want
   best-effort cleanup of unused caller-owned buffers without adding a runtime
   dependency.

SECURITY.md

@@ -64,20 +64,30 @@ buffer. This reduces easy timing and retention pitfalls, but `base64-ng` does
 not currently claim a formally verified cryptographic constant-time encode or
 decode API.
 
+If a deployment treats final success/failure timing or exact ciphertext length
+as sensitive, the caller must continue protocol processing in a fixed-shape
+way after decode failure, for example by substituting dummy output and running
+the same downstream validation or comparison steps. The `ct` module narrows
+the Base64 symbol-mapping timing target; it does not hide the public `Result`,
+input length, padding length, or decoded length from the surrounding protocol.
+
 The clear-tail encode and decode APIs provide best-effort cleanup for
 caller-owned buffers by writing zero bytes over unused tail bytes on success and
-over the whole buffer on encode/decode error. Because the scalar crate forbids
-unsafe code and has no runtime dependencies, this cleanup uses ordinary Rust
-writes plus a compiler fence, not volatile writes or a formally verified
-zeroization primitive. Treat these APIs as buffer-retention reduction, not as a
-complete secret-erasure guarantee against compiler optimizations, core dumps,
-swap, hardware observation, or other process memory disclosure bugs.
+over the whole buffer on encode/decode error. The cleanup primitive uses
+volatile byte writes plus a `SeqCst` compiler fence so cleanup writes are not
+optimized away. Treat these APIs as buffer-retention reduction, not as a
+complete secret-erasure guarantee against historical stack-frame copies,
+compiler spills, CPU registers, allocator behavior, core dumps, swap, 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.
 
 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
-initialized bytes on drop with the same best-effort cleanup helper. It cannot
-clean historical copies outside the wrapper or allocator spare capacity.
+initialized bytes and vector spare capacity on drop with the same best-effort
+cleanup helper. It cannot clean historical copies outside the wrapper or make
+guarantees about allocator internals after ownership is exposed.
 
 Streaming wrappers apply best-effort cleanup to their small internal staging
 buffers. Encoders clear pending plaintext bytes when those bytes are consumed
@@ -95,7 +105,9 @@ helpers before allocating or accepting framed payloads.
 Runtime scalar APIs are expected to return `Result` or `Option` for malformed
 input and size errors instead of unwinding. Compile-time array encoding is the
 exception: it intentionally fails const evaluation when the caller supplies an
-incorrect output array length.
+incorrect output array length. Do not use `Engine::encode_array` as a runtime
+API for untrusted size decisions; use `checked_encoded_len`, `encoded_len`, or
+caller-owned slice APIs instead.
 `scripts/validate-panic-policy.sh` release-gates new non-test panic-like sites
 and requires reviewed exceptions to remain documented in `docs/PANIC_POLICY.md`.
 

docs/CONSTANT_TIME.md

@@ -47,6 +47,7 @@ The guarantee should explicitly exclude:
 - public input length
 - selected engine/alphabet
 - final success or failure result
+- total protocol work performed after the public `Result` is returned
 - invalid length and output-buffer capacity errors
 - output length
 - allocator behavior
@@ -222,6 +223,12 @@ those values are visible through the returned `Result` and decoded length. Any
 future cryptographic profile must document memory cleanup separately from timing
 behavior.
 
+Applications that must hide success/failure timing at the protocol level should
+continue with fixed-shape downstream work after decode failure. A common pattern
+is to decode into caller-owned storage, substitute a same-length dummy buffer on
+failure, and perform the same comparison, authentication, accounting, and
+cleanup steps before returning a protocol decision.
+
 ## Buffer Comparisons
 
 `SecretBuffer::constant_time_eq`, `EncodedBuffer::constant_time_eq`, and

docs/PANIC_POLICY.md

@@ -23,7 +23,9 @@ The current reviewed exceptions are:
   supplies an output array length that does not match the compile-time encoded
   length, or when that const length calculation overflows. This is documented
   as a const-array API contract and is not used for runtime untrusted length
-  metadata.
+  metadata. Calling it at runtime with a mismatched const output length can
+  also unwind; do not route attacker-controlled sizing decisions through this
+  API.
 - Internal remainder matches use `_ => unreachable!()` after matching
   `len % 3` or equivalent remainder values. The preceding arithmetic bounds
   make those arms unreachable.
@@ -53,3 +55,8 @@ For untrusted input and untrusted length metadata, prefer:
 Compile-time array encoding is intentionally stricter: an incorrect destination
 array length fails const evaluation so the mistake cannot silently produce a
 truncated or oversized static value.
+
+Use `Engine::encode_array` for fixed-size static data and compile-time checked
+arrays. For runtime data, especially data sized from packet headers, file
+metadata, network frames, or other untrusted sources, use checked length helpers
+and caller-owned slice APIs instead.

docs/SECURITY_CONTROLS.md

@@ -61,13 +61,15 @@ profiles are strict about the configured line ending and non-final line width.
 ### Memory Retention Reduction
 
 Cleanup APIs are best-effort initialized-byte cleanup. They are implemented
-without runtime dependencies and without unsafe code in scalar paths. They do
-not claim formal zeroization against compiler behavior, historical stack-frame
-copies, allocator internals, copies made outside the wrapper, core dumps, swap,
-or arbitrary process memory disclosure vulnerabilities. For high-assurance
-secret handling, use the clear-tail APIs promptly and pair them with operating
-system and deployment controls that reduce crash dumps, swap, and broad memory
-disclosure exposure.
+without runtime dependencies using the audited volatile wipe helpers inventoried
+in [UNSAFE.md](UNSAFE.md). They do not claim formal zeroization against
+compiler behavior, historical stack-frame copies, allocator internals, copies
+made outside the wrapper, core dumps, swap, or arbitrary process memory
+disclosure vulnerabilities. For high-assurance secret handling, use the
+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.
 
 ### Side-Channel Posture
 
@@ -76,6 +78,9 @@ built-in alphabets, and the decoder uses branch-minimized ASCII arithmetic.
 The `ct` module narrows the timing target further for scalar decode and uses a
 fixed scan over the selected alphabet for generic symbol mapping. It still does
 not carry a formal cryptographic constant-time guarantee.
+Input length, padding length, decoded length, and final success/failure remain
+public protocol facts; callers that must hide those facts need fixed-shape
+protocol-level processing after decode failure.
 
 ### Supply Chain
 

docs/UNSAFE.md

@@ -54,8 +54,12 @@ Safety argument:
 Limitations:
 
 - This is best-effort data-retention reduction, not a formal zeroization
-  guarantee. It cannot clear historical copies, allocator spare capacity, swap,
-  core dumps, CPU registers, or buffers outside the slice provided to the API.
+  guarantee. It cannot clear historical copies, compiler spill slots,
+  allocator spare capacity, swap, core dumps, CPU registers, or buffers outside
+  the slice provided to the API.
+- Callers with platform-specific formal zeroization requirements should apply
+  their own zeroization policy to caller-owned buffers in addition to using the
+  crate cleanup APIs.
 
 ### `wipe_vec_spare_capacity`
 
@@ -95,8 +99,9 @@ Safety argument:
 Limitations:
 
 - This is best-effort data-retention reduction, not a formal zeroization
-  guarantee. It cannot make claims about allocator internals, historical copies,
-  swap, core dumps, CPU registers, or buffers outside the vector allocation.
+  guarantee. It cannot make claims about allocator internals, historical
+  copies, compiler spill slots, swap, core dumps, CPU registers, or buffers
+  outside the vector allocation.
 
 ### `encode_48_bytes_avx512`