Address final pentest hardening findings

Author: eldryoth

README.md

@@ -466,14 +466,16 @@ messages.
 `remaining_capacity()` for no-alloc sizing checks, redact the payload from
 `Debug`, clear their backing arrays when dropped as best-effort data-retention
 reduction, and provide explicit `constant_time_eq` helpers for equal-length
-values. They intentionally do not implement `PartialEq`/`==`: the helper is a
-dependency-free best-effort comparison, not a formal cryptographic token/MAC
-comparison primitive. Length mismatch returns immediately and must be treated
-as public protocol information. Applications that require a formally audited
-comparison should admit that dependency at the application boundary, for
-example by comparing exposed bytes with `subtle`. Do not use these helpers as
-the sole MAC, bearer-token, password-hash, or authentication-secret comparison
-primitive in high-assurance systems.
+reduction, and provide explicit equal-length comparison through
+`constant_time_eq_public_len`. They intentionally do not
+implement `PartialEq`/`==`: the helper is a dependency-free best-effort
+comparison, not a formal cryptographic token/MAC comparison primitive. Length
+mismatch returns immediately and must be treated as public protocol
+information. Applications that require a formally audited comparison should
+admit that dependency at the application boundary, for example by comparing
+exposed bytes with `subtle`. Do not use these helpers as the sole MAC,
+bearer-token, password-hash, or authentication-secret comparison primitive in
+high-assurance systems.
 
 `into_exposed_array` is the explicit no-alloc ownership escape hatch for both
 stack-backed buffers. It returns the backing array and visible length, so
@@ -513,7 +515,7 @@ assert_eq!(format!("{encoded:?}"), r#"SecretBuffer { bytes: "<redacted>", len: 8
 
 let decoded = STANDARD.decode_secret(encoded.expose_secret()).unwrap();
 assert_eq!(decoded.expose_secret(), b"hello");
-assert!(decoded.constant_time_eq(b"hello"));
+assert!(decoded.constant_time_eq_public_len(b"hello"));
 assert_eq!(format!("{decoded}"), "<redacted>");
 
 let wrapped = STANDARD
@@ -537,12 +539,12 @@ assert_eq!(decoded.expose_secret(), b"hello");
 initialized bytes plus spare capacity when dropped. It does not claim formal
 zeroization and cannot clean historical copies outside the wrapper or make
 guarantees about allocator behavior. `SecretBuffer` intentionally does not
-implement `PartialEq`/`==`; use the explicit `constant_time_eq` helper only
-when its best-effort, public-length security contract is sufficient. Length
-mismatch returns immediately and must be treated as public protocol
-information. Applications that require a formally audited comparison should
-admit that dependency at the application boundary, for example by comparing
-exposed bytes with `subtle`.
+implement `PartialEq`/`==`; use the explicit
+`constant_time_eq_public_len` helper only when its best-effort, public-length
+security contract is sufficient. Length mismatch returns immediately and must
+be treated as public protocol information. Applications that require a
+formally audited comparison should admit that dependency at the application
+boundary, for example by comparing exposed bytes with `subtle`.
 On `wasm32`, the same compiler-fence-only wipe-barrier caveat applies to owned
 secret buffers. `wasm32` builds fail closed by default; enable
 `allow-wasm32-best-effort-wipe` only when the deployment explicitly accepts the

docs/API_AUDIT.md

@@ -136,8 +136,8 @@ Decision rationale:
 - `into_exposed_array` is intentionally named as an ownership escape hatch
   where redaction and drop-time cleanup stop applying to the returned array.
 - Equality is intentionally not exposed through `PartialEq`/`==`. Callers must
-  opt into the explicit `constant_time_eq` helper, whose equal-length scan is
-  best-effort and whose length mismatch remains public.
+  opt into the explicit `constant_time_eq_public_len` helper, whose equal-length
+  scan is best-effort and whose length mismatch remains public.
 
 Stable boundary:
 
@@ -161,8 +161,8 @@ Decision rationale:
 - Drop-time cleanup uses the crate's volatile best-effort wipe helper for
   initialized bytes and vector spare capacity.
 - Equality is intentionally not exposed through `PartialEq`/`==`. Callers must
-  opt into the explicit `constant_time_eq` helper, whose equal-length scan is
-  best-effort and whose length mismatch remains public.
+  opt into the explicit `constant_time_eq_public_len` helper, whose equal-length
+  scan is best-effort and whose length mismatch remains public.
 - Strict standard padded `TryFrom` and `FromStr` implementations are kept only
   for native Rust ergonomics; non-standard profiles remain on explicit
   engine/profile methods.

docs/CONSTANT_TIME.md

@@ -262,10 +262,18 @@ partial plaintext before the final wipe.
 
 Before reporting the opaque malformed-input result, the ct decoder passes the
 accumulated error mask through a non-inlined `ct_error_gate_barrier` that uses
-`core::hint::black_box` and a compiler fence. This is defense in depth against
-compiler reordering around the final public success/failure gate; it is not a
-hardware speculation barrier and does not change the transient-output window
-described above.
+`core::hint::black_box`, a compiler fence, and architecture-specific hardware
+speculation barriers where available (`lfence` on x86/x86_64, `isb sy` on ARM,
+and `isb sy; hint #20` on AArch64). This is defense in depth around the final
+public success/failure gate; it does not make the ct decoder a formally
+verified hardware side-channel resistant primitive and does not change the
+transient-output window described above.
+
+For shared-memory or in-process sandbox threat models where even that transient
+output window is unacceptable, use
+`CtEngine::decode_slice_staged_clear_tail` with a private staging buffer. That
+API writes speculative decoded bytes into staging and copies into the caller's
+output only after validation succeeds.
 
 The clear-tail APIs do not try to hide success, failure, or output length:
 those values are visible through the returned `Result` and decoded length. Any
@@ -280,13 +288,19 @@ cleanup steps before returning a protocol decision.
 
 ## Buffer Comparisons
 
-`SecretBuffer::constant_time_eq`, `EncodedBuffer::constant_time_eq`, and
-`DecodedBuffer::constant_time_eq` provide dependency-free,
+`SecretBuffer::constant_time_eq_public_len`,
+`EncodedBuffer::constant_time_eq_public_len`, and
+`DecodedBuffer::constant_time_eq_public_len` provide dependency-free,
 constant-time-oriented comparison for equal-length buffers. These redacted
 buffer types intentionally do not implement `PartialEq`/`==`: the explicit
 method name is part of the security contract because this helper is best-effort
 and not a formal cryptographic comparison primitive.
 
+The old `constant_time_eq` method name remains only as a deprecated migration
+alias during the `1.0.0-alpha` window. New code should use the
+`constant_time_eq_public_len` name so the public-length contract is visible at
+the call site.
+
 Length mismatch returns immediately. Treat buffer length, the selected buffer
 type, and the final equality result as public. The helper scans every byte for
 equal-length inputs before returning. The per-byte difference is passed through

docs/SECURITY_CONTROLS.md

@@ -16,17 +16,18 @@ The mapping is practical adoption guidance, not a certification claim.
 | CWE-226 Sensitive Information in Resource Not Removed Before Reuse | Caller-owned output buffers or crate-owned staging buffers retain partial sensitive data | Clear-tail APIs, stream cleanup, `EncodedBuffer`, `DecodedBuffer`, and `SecretBuffer` provide best-effort initialized-byte and spare-capacity cleanup. |
 | CWE-327 Use of Broken Or Risky Cryptographic Algorithm | Treating Base64 as encryption | Documentation describes Base64 as encoding, not encryption; secret wrappers are retention/logging helpers only. |
 | CWE-532 Insertion of Sensitive Information Into Log File | Accidentally logging sensitive encoded or decoded material | `SecretBuffer` redacts `Debug` and `Display` output and requires explicit reveal calls. |
-| CWE-208 Observable Timing Discrepancy | Sensitive comparison exits early on the first different byte | `SecretBuffer`, `EncodedBuffer`, and `DecodedBuffer` intentionally avoid `PartialEq`/`==` so best-effort comparison cannot be mistaken for a formal cryptographic primitive. Use explicit `constant_time_eq` for dependency-free equal-length scans; length mismatch returns immediately and is public. |
+| CWE-208 Observable Timing Discrepancy | Sensitive comparison exits early on the first different byte | `SecretBuffer`, `EncodedBuffer`, and `DecodedBuffer` intentionally avoid `PartialEq`/`==` so best-effort comparison cannot be mistaken for a formal cryptographic primitive. Use explicit `constant_time_eq_public_len` for dependency-free equal-length scans; length mismatch returns immediately and is public. |
 | CWE-829 Inclusion of Functionality From Untrusted Control Sphere | Runtime dependency compromise | Published crate has zero external runtime and default dev dependencies; dependency admission is documented and checked. |
 
-The `constant_time_eq` helpers are dependency-free hardening aids, not audited
-MAC, bearer-token, password-hash, or authentication-secret comparison
-primitives. Their implementation is release-evidence-gated through generated
-assembly review, including LTO symbol-presence checks for
-`constant_time_eq_public_len`, but no formal cryptographic constant-time
-comparison guarantee is claimed. High-assurance applications that can admit a
-comparison dependency should use a reviewed primitive such as `subtle` at the
-protocol boundary.
+The `constant_time_eq_public_len` helpers are dependency-free hardening aids,
+not audited MAC, bearer-token, password-hash, or authentication-secret
+comparison primitives. Their implementation is release-evidence-gated through
+generated assembly review, including LTO symbol-presence checks for the helper,
+but no formal cryptographic constant-time comparison guarantee is claimed.
+High-assurance applications that can admit a comparison dependency should use a
+reviewed primitive such as `subtle` at the protocol boundary. The shorter
+`constant_time_eq` name remains only as a deprecated migration alias during the
+`1.0.0-alpha` window.
 
 ## Caller Responsibilities
 
@@ -109,9 +110,10 @@ reduces post-return retention, but it is not an isolation boundary: code running
 in the same process with concurrent or unsafe access to the output buffer during
 the decode call could observe transient partial plaintext before the final wipe.
 Before the opaque malformed-input result is reported, the accumulated ct error
-mask passes through a non-inlined compiler barrier. This is defense in depth
-against compiler reordering around the public success/failure gate, not a
-hardware speculation barrier.
+mask passes through a non-inlined compiler barrier plus architecture-specific
+hardware speculation barriers where available. Shared-memory deployments that
+cannot tolerate transient writes to the caller output should use
+`CtEngine::decode_slice_staged_clear_tail` with a private staging buffer.
 For constant-time-oriented in-place decode, use
 `ct::CtEngine::decode_in_place_clear_tail`. The non-clear-tail CT in-place API
 was removed before the `1.0` stable boundary because it could partially destroy

docs/UNSAFE.md

@@ -2,18 +2,20 @@
 
 `base64-ng` keeps scalar encode/decode in safe Rust. The crate root uses
 `#![deny(unsafe_code)]`, and reviewed `allow(unsafe_code)` exceptions are
-limited to volatile wipe helpers in `src/lib.rs` and the SIMD boundary in
-`src/simd.rs`.
+limited to volatile wipe helpers, the constant-time error gate barrier in
+`src/lib.rs`, and the SIMD boundary in `src/simd.rs`.
 
 This inventory is intentionally small and release-gate enforced. Any new unsafe
 block must be added here before an accelerated backend can be admitted.
 
 ## Policy
 
-- Default builds compile audited unsafe volatile wipe helpers.
+- Default builds compile audited unsafe volatile wipe helpers and the
+  constant-time error gate barrier.
 - Optional SIMD prototypes live only in `src/simd.rs`.
 - `scripts/validate-unsafe-boundary.sh` fails if `allow(unsafe_code)` appears
-  outside the volatile wipe helpers or `src/simd.rs`.
+  outside the volatile wipe helpers, the constant-time error gate barrier, or
+  `src/simd.rs`.
 - `scripts/validate-unsafe-boundary.sh` fails if architecture intrinsics, CPU
   feature detection, or `target_feature` gates appear outside `src/simd.rs`.
 - Every unsafe function and unsafe block must have a local safety explanation.
@@ -110,9 +112,9 @@ Preconditions:
 Unsafe operation:
 
 - `core::arch::asm!` emits `mfence` on non-Miri `x86`/`x86_64`,
-  `dsb sy; isb sy` on non-Miri `arm`/`aarch64`, and `fence rw, rw` on non-Miri
-  `riscv32`/`riscv64`. The pointer and length are also passed as opaque
-  operands.
+  `dsb sy; isb sy` on non-Miri `arm`, `dsb sy; isb sy; hint #20` on non-Miri
+  `aarch64`, and `fence rw, rw` on non-Miri `riscv32`/`riscv64`. The pointer
+  and length are also passed as opaque operands.
 
 Safety argument:
 
@@ -139,6 +141,43 @@ Limitations:
   enabled after reviewing this weaker cleanup posture and applying platform
   memory controls.
 
+### `ct_error_gate_barrier`
+
+Location: `src/lib.rs`
+
+Status: active constant-time error-gate hardening primitive.
+
+Purpose:
+
+- Keep the accumulated constant-time decoder malformed-input mask visible
+  across a non-inlined boundary before the public success/failure branch.
+- Emit an architecture-specific speculation barrier where stable Rust supports
+  one locally.
+
+Preconditions:
+
+- Caller passes accumulated public error-mask bytes.
+
+Unsafe operation:
+
+- `core::arch::asm!` emits `lfence` on non-Miri `x86`/`x86_64`, `isb sy` on
+  non-Miri `arm`, and `isb sy; hint #20` on non-Miri `aarch64`.
+
+Safety argument:
+
+- The assembly blocks do not access memory.
+- `options(nostack, preserves_flags)` states that the blocks do not use the
+  stack or modify flags. The x86/x86_64 block also uses `nomem`.
+- The helper does not read or write through any pointer and cannot violate
+  Rust aliasing or bounds rules.
+
+Limitations:
+
+- This is defense in depth against speculation around the final public
+  malformed-input result. It does not make the ct decoder a formally verified
+  hardware side-channel resistant primitive.
+- Unsupported architectures fall back to the compiler fence only.
+
 ### `wipe_vec_spare_capacity`
 
 Location: `src/lib.rs`

scripts/validate-unsafe-boundary.sh

@@ -20,24 +20,24 @@ if [ "$matches" != "$allowed" ]; then
 fi
 
 root_allow_count="$(grep -c '^#\[allow(unsafe_code)\]$' "$root_allowed" || true)"
-if [ "$root_allow_count" -ne 3 ]; then
-    echo "unsafe boundary: src/lib.rs must have exactly three reviewed allow(unsafe_code) cleanup helpers"
+if [ "$root_allow_count" -ne 4 ]; then
+    echo "unsafe boundary: src/lib.rs must have exactly four reviewed allow(unsafe_code) helpers"
     exit 1
 fi
 
 if ! awk '
     /^#\[allow\(unsafe_code\)\]$/ {
         allow_line = NR
     }
-    /^fn wipe_bytes\(/ || /^fn wipe_barrier\(/ || /^fn wipe_vec_spare_capacity\(/ {
+    /^fn wipe_bytes\(/ || /^fn wipe_barrier\(/ || /^fn wipe_vec_spare_capacity\(/ || /^fn ct_error_gate_barrier\(/ {
         if (allow_line != NR - 1) {
             failed = 1
         }
         seen += 1
     }
-    END { exit failed || seen != 3 }
+    END { exit failed || seen != 4 }
 ' "$root_allowed"; then
-    echo "unsafe boundary: src/lib.rs allow(unsafe_code) must apply only to reviewed cleanup helpers"
+    echo "unsafe boundary: src/lib.rs allow(unsafe_code) must apply only to reviewed cleanup and CT gate helpers"
     exit 1
 fi
 
@@ -62,7 +62,7 @@ if [ ! -s docs/UNSAFE.md ]; then
     exit 1
 fi
 
-unsafe_functions="$(sed -n 's/^[[:space:]]*pub(super)[[:space:]]*unsafe[[:space:]]*fn[[:space:]]*\([A-Za-z0-9_][A-Za-z0-9_]*\).*/\1/p' "$simd_allowed")"
+unsafe_functions="$(sed -n 's/^[[:space:]]*unsafe[[:space:]]*fn[[:space:]]*\([A-Za-z0-9_][A-Za-z0-9_]*\).*/\1/p' "$simd_allowed")"
 
 if [ -z "$unsafe_functions" ]; then
     echo "unsafe boundary: expected documented prototype unsafe functions in $allowed"