Harden exposed arrays and CT posture reporting

Author: eldryoth

README.md

@@ -432,6 +432,9 @@ or `ct::CtEngine::decode_buffer`. The non-clear-tail CT slice API was removed
 before the `1.0` stable boundary because it can leave real decoded plaintext
 from valid leading quanta in `output` when later malformed input is rejected
 after the fixed-shape decode pass.
+For shared-memory, HSM-adjacent, sandboxed, or other multi-principal threat
+models where even transient writes to caller-owned output are unacceptable, use
+`ct::CtEngine::decode_slice_staged_clear_tail` with a private staging buffer.
 
 For short values, `encode_buffer` returns a stack-backed `EncodedBuffer`
 and `decode_buffer` returns a stack-backed `DecodedBuffer` without requiring
@@ -478,9 +481,11 @@ 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
-redacted formatting and drop-time cleanup no longer apply to the returned
-array.
+stack-backed buffers. It returns `ExposedEncodedArray` or
+`ExposedDecodedArray`, keeping redacted formatting and best-effort drop-time
+cleanup after ownership transfer. If a bare array is unavoidable, call
+`into_exposed_unprotected_array_caller_must_zeroize`; cleanup then becomes the
+caller responsibility.
 
 Stack-backed buffers clear their backing arrays when dropped, but they cannot
 clear historical stack-frame copies made by the compiler, caller code, panic

docs/API_AUDIT.md

@@ -133,8 +133,11 @@ Decision rationale:
   Base64 text through explicit display/text APIs.
 - Drop-time cleanup is best-effort and scoped to the buffer's current backing
   array, not historical stack-frame copies.
-- `into_exposed_array` is intentionally named as an ownership escape hatch
-  where redaction and drop-time cleanup stop applying to the returned array.
+- `into_exposed_array` is intentionally named as an ownership escape hatch and
+  returns `ExposedEncodedArray` or `ExposedDecodedArray`, preserving redaction
+  and drop-time cleanup after ownership transfer. The raw-array escape hatch is
+  deliberately loud:
+  `into_exposed_unprotected_array_caller_must_zeroize`.
 - Equality is intentionally not exposed through `PartialEq`/`==`. Callers must
   opt into the explicit `constant_time_eq_public_len` helper, whose equal-length
   scan is best-effort and whose length mismatch remains public.

docs/CONSTANT_TIME.md

@@ -263,14 +263,14 @@ 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`, 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). On RISCV the gate uses `fence rw, rw`,
-which is an ordering fence rather than a canonical speculation barrier in the
-base ISA. The runtime backend report exposes this separately through
-`ct_gate_posture`. 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.
+speculation barriers where available (`lfence` on x86/x86_64 and
+`isb sy; hint #20` on AArch64). On 32-bit ARM the gate uses `isb sy`, and on
+RISCV it uses `fence rw, rw`; both are reported as `ordering-fence` because the
+base ISA path is not a canonical Spectre-v1 data-flow speculation barrier. The
+runtime backend report exposes this separately through `ct_gate_posture`. 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
@@ -316,6 +316,10 @@ CT gate barrier used by malformed-input reporting. The helper is marked
 `constant_time_eq_public_len` remains visible as a separate text symbol in the
 LTO artifact.
 
+When the value length itself should not be modeled as a runtime branch, use
+`constant_time_eq_fixed_width` with fixed-size arrays. Its length is a
+compile-time type fact and it scans exactly that width before returning.
+
 This remains a best-effort API and does not upgrade `base64-ng` to a formally
 verified cryptographic constant-time comparison crate. Do not use this helper
 as the sole MAC, bearer-token, password-hash, or authentication-secret

docs/SECURITY_CONTROLS.md

@@ -38,8 +38,10 @@ The caller still owns:
 - choosing strict, legacy, wrapped, MIME, PEM, bcrypt-style, or custom profiles
   intentionally
 - avoiding accidental copies of secrets before wrapping them in `SecretBuffer`
-- treating stack-buffer `into_exposed_array` calls as boundaries where redacted
-  formatting and drop-time cleanup intentionally stop for the returned arrays
+- treating
+  `into_exposed_unprotected_array_caller_must_zeroize` calls as boundaries
+  where redacted formatting and crate-owned drop-time cleanup intentionally
+  stop for returned bare arrays
 - understanding that stack-backed buffers can clear their own backing arrays
   but cannot clear historical stack-frame copies made by compiler spills,
   caller code, panic machinery, crash handlers, or operating system capture
@@ -104,9 +106,12 @@ for secret regions, and the deployment's approved zeroization primitive at the
 ownership boundary.
 For constant-time-oriented decode, use `ct::CtEngine::decode_slice_clear_tail`
 or `ct::CtEngine::decode_buffer` when a caller-owned output buffer may be
-reused after a rejected input. The non-clear-tail CT slice API was removed
-before the `1.0` stable boundary because it could leave decoded plaintext from
-valid leading quanta in the buffer on error.
+reused after a rejected input. For shared-memory, HSM-adjacent, sandboxed, or
+multi-principal environments where even transient writes to caller output are
+unacceptable, use `ct::CtEngine::decode_slice_staged_clear_tail` with a private
+staging buffer. The non-clear-tail CT slice API was removed before the `1.0`
+stable boundary because it could leave decoded plaintext from valid leading
+quanta in the buffer on error.
 The internal constant-time-oriented decode loop writes decoded bytes to the
 caller-owned output buffer before final malformed-input reporting, then
 `decode_slice_clear_tail` wipes the buffer before returning an error. This

docs/UNSAFE.md

@@ -151,8 +151,8 @@ 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.
+- Emit an architecture-specific speculation or ordering barrier where stable
+  Rust supports one locally.
 
 Preconditions:
 
@@ -161,7 +161,7 @@ Preconditions:
 Unsafe operation:
 
 - `core::arch::asm!` emits `lfence` on non-Miri `x86`/`x86_64`, `isb sy` on
-  non-Miri `arm`, `isb sy; hint #20` on non-Miri `aarch64`, and
+  non-Miri 32-bit `arm`, `isb sy; hint #20` on non-Miri `aarch64`, and
   `fence rw, rw` on non-Miri `riscv32`/`riscv64`.
 
 Safety argument:
@@ -177,9 +177,12 @@ 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.
-- RISC-V base ISA has no canonical speculation barrier. The crate reports its
-  CT gate posture as `ordering-fence` on RISCV rather than
-  `hardware-speculation-barrier`.
+- 32-bit ARM uses `isb sy` without CSDB, and RISC-V base ISA has no canonical
+  speculation barrier. The crate reports both CT gate postures as
+  `ordering-fence` rather than `hardware-speculation-barrier`.
+- On AArch64, the CSDB hint may be treated as a no-op on older cores. The
+  runtime posture reports the emitted barrier sequence, not a formal
+  microarchitecture certification.
 - Unsupported architectures fall back to the compiler fence only.
 
 ### `wipe_vec_spare_capacity`