Harden high-assurance CT guidance

Author: eldryoth

CHANGELOG.md

@@ -5,6 +5,11 @@
 - Synchronized all workspace crate package versions to `1.3.6`.
 - Added consistent companion-crate README headers with the shared project image,
   core documentation links, and crate-specific one-line summaries.
+- Moved the top constant-time guide example to
+  `decode_slice_staged_clear_tail` so shared-memory and HSM-adjacent users see
+  the safer staged pattern first.
+- Added the custom `base64_ng_require_high_assurance` cfg. When set, builds
+  that also enable `simd` fail at compile time.
 - No encode/decode logic, SIMD admission scope, or runtime dependency posture
   changes.
 

Cargo.toml

@@ -70,6 +70,7 @@ fuzzing = []
 [lints.rust]
 unexpected_cfgs = { level = "warn", check-cfg = [
     "cfg(base64_ng_aarch64_csdb_attested)",
+    "cfg(base64_ng_require_high_assurance)",
     "cfg(base64_ng_kani_advanced)",
     "cfg(kani)",
     "cfg(miri)",

README.md

@@ -225,6 +225,12 @@ license = "MIT OR Apache-2.0"
 | `kani` | no | Reserved for verifier harnesses; normal builds do not require Kani. |
 | `fuzzing` | no | Reserved for verifier and fuzz harness integration; published crate stays dependency-free. |
 
+High-assurance deployments that must fail closed when SIMD is enabled can build
+with `RUSTFLAGS="--cfg base64_ng_require_high_assurance"`. This custom cfg is
+not a Cargo feature, so normal `--all-features` release evidence and docs.rs
+builds remain usable. When the cfg is set, `base64-ng` refuses to compile if
+the `simd` feature is enabled.
+
 ## Companion Crates
 
 The core `base64-ng` crate keeps its zero-runtime-dependency policy. Optional

docs/API_AUDIT.md

@@ -45,7 +45,7 @@ audit favors removing or documenting ambiguous APIs over adding convenience.
 | `ct` module | documented boundary | Keep non-claim wording and opaque error behavior explicit unless verification evidence changes. |
 | `stream` module | documented boundary | Fail-closed decode, retry semantics, state helpers, recovery helpers, and framed-reader behavior are explicit. |
 | Runtime backend reporting | candidate stable | Scalar-only posture and stable log identifiers are documented and release-gated. |
-| Feature flags | documented boundary | `tokio`, `kani`, `fuzzing`, and `simd` remain inert or reserved unless admitted by their policy docs. `allow-wasm32-best-effort-wipe` is an explicit opt-in for wasm builds that accept compiler-fence-only cleanup; `allow-compiler-fence-only-wipe` is the equivalent opt-in for unsupported native architectures. AArch64 CSDB attestation uses the custom cfg `base64_ng_aarch64_csdb_attested`, not a Cargo feature, so `--all-features` cannot enable it accidentally. |
+| Feature flags | documented boundary | `tokio`, `kani`, `fuzzing`, and `simd` remain inert or reserved unless admitted by their policy docs. `allow-wasm32-best-effort-wipe` is an explicit opt-in for wasm builds that accept compiler-fence-only cleanup; `allow-compiler-fence-only-wipe` is the equivalent opt-in for unsupported native architectures. AArch64 CSDB attestation uses the custom cfg `base64_ng_aarch64_csdb_attested`, not a Cargo feature, so `--all-features` cannot enable it accidentally. High-assurance deployments may use custom cfg `base64_ng_require_high_assurance` to fail builds that enable `simd`. |
 | Error types | candidate stable | Encode, decode, and alphabet errors are recoverable and diagnostic without committing ct errors to localized detail. |
 | Macros and custom alphabets | documented boundary | Compile-time validation and conservative fixed-scan performance/security tradeoffs are explicit. |
 

docs/CONSTANT_TIME.md

@@ -17,8 +17,10 @@ payloads:
 ```rust
 use base64_ng::ct;
 
+let mut staging = [0u8; 32];
 let mut output = [0u8; 32];
-let written = ct::STANDARD.decode_slice_clear_tail(b"...", &mut output)?;
+let written = ct::STANDARD
+    .decode_slice_staged_clear_tail(b"...", &mut output, &mut staging)?;
 ```
 
 The API should be separate from the default strict decoder so users can choose
@@ -62,6 +64,19 @@ require_backend_policy(BackendPolicy::HighAssuranceScalarOnly)
     .expect("base64-ng posture check failed: CT gate not attested on this core");
 ```
 
+Deployments that want a compile-time fail-closed guard can also build with the
+custom cfg `base64_ng_require_high_assurance`. That cfg rejects builds where
+the `simd` feature is enabled:
+
+```sh
+RUSTFLAGS="--cfg base64_ng_require_high_assurance" cargo build --no-default-features
+```
+
+This is a custom cfg rather than a Cargo feature so normal `--all-features`
+release evidence and docs.rs builds can continue to exercise every public
+feature. Treat the cfg as a deployment policy assertion and keep the runtime
+`require_backend_policy(BackendPolicy::HighAssuranceScalarOnly)` startup gate.
+
 `HighAssuranceScalarOnly` is still a build and target posture assertion. On
 AArch64, the crate emits `isb sy` plus the CSDB hint for the CT result gate.
 By default this reports `CtGatePosture::HardwareSpeculationBarrierUnattested`

docs/CRATE_VERSION_MATRIX.md

@@ -10,8 +10,11 @@ sets.
 The `1.3.6` release keeps the workspace crate family synchronized. The main
 crate and all companion crates carry the companion README header refresh so
 crate pages share the project image, core documentation links, and a
-crate-specific one-line summary. No encode/decode logic, SIMD admission scope,
-or runtime dependency posture changes in this release.
+crate-specific one-line summary. The main crate also moves the top
+constant-time guide example to staged decode and adds the custom
+`base64_ng_require_high_assurance` cfg so deployments can fail builds that
+combine a high-assurance posture assertion with `simd`. No encode/decode logic,
+SIMD admission scope, or runtime dependency posture changes in this release.
 
 | Crate | Version | Publish In 1.3.6 | Cargo |
 | --- | --- | --- | --- |

docs/TRUST.md

@@ -11,7 +11,7 @@ stable release.
 | Active release toolchain | Rust `1.96.1`; MSRV remains Rust `1.90.0` | `rust-toolchain.toml`, `scripts/ci_install_rust.sh` |
 | Runtime dependencies | Zero external crates in the core package; optional companion crates are separate opt-in packages | `scripts/validate-dependencies.sh`, `scripts/check_companion_crates.sh` |
 | Default dev dependencies | Zero external crates | `Cargo.toml` |
-| Optional runtime features | `alloc`, `std`, `stream`; `allow-wasm32-best-effort-wipe` explicit wasm cleanup-limit acceptance; `allow-compiler-fence-only-wipe` explicit unsupported-native cleanup-limit acceptance; reserved `simd`, `tokio`, `kani`, `fuzzing`. AArch64 CSDB attestation uses custom cfg `base64_ng_aarch64_csdb_attested`, not a feature. | `Cargo.toml`, `scripts/check_reserved_features.sh`, `scripts/check_wasm_wipe_policy.sh` |
+| Optional runtime features | `alloc`, `std`, `stream`; `allow-wasm32-best-effort-wipe` explicit wasm cleanup-limit acceptance; `allow-compiler-fence-only-wipe` explicit unsupported-native cleanup-limit acceptance; reserved `simd`, `tokio`, `kani`, `fuzzing`. AArch64 CSDB attestation uses custom cfg `base64_ng_aarch64_csdb_attested`, not a feature. High-assurance deployments may set custom cfg `base64_ng_require_high_assurance` to make `simd` a compile-time error. | `Cargo.toml`, `scripts/check_reserved_features.sh`, `scripts/check_wasm_wipe_policy.sh` |
 | Unsafe policy | Scalar encode/decode remains safe Rust; audited unsafe is limited to volatile wiping, constant-time comparison, CT alphabet scan and result-gate barriers, and the reviewed SIMD boundary; runtime unsafe-boundary reports are conservative and mark SIMD-enabled builds as not high-assurance-boundary-enforced | `src/cleanup.rs`, `src/ct/`, `src/simd/`, `docs/UNSAFE.md` |
 | Active backend | Scalar by default; std x86/x86_64 AVX-512 VBMI encode preferred, then AVX2, then SSSE3/SSE4.1 encode, plus little-endian std aarch64 NEON encode, when `simd` is enabled and platform checks pass. Strict decode has a separate runtime report method and may use std x86/x86_64 AVX-512 VBMI, AVX2, SSSE3/SSE4.1, or little-endian std aarch64 NEON. wasm32 binaries compiled with `target-feature=+simd128`, `simd`, and `allow-wasm32-best-effort-wipe` may use the admitted narrow wasm `simd128` encode and strict-decode backend. | `runtime::backend_report()` tests |
 | SIMD status | AVX-512 VBMI, AVX2, SSSE3/SSE4.1, NEON, and narrow wasm `simd128` encode admitted for Standard and URL-safe alphabet families; AVX-512 VBMI, AVX2, SSSE3/SSE4.1, NEON, and narrow wasm `simd128` strict decode admitted for the documented runtime profiles. Wrapped and legacy decode may enter the admitted strict decode backend only after scalar line-profile validation, line-ending compaction, or legacy-whitespace compaction. Strict in-place encode and decode may enter admitted backends only after stack staging. Custom-alphabet, CT secret, big-endian AArch64, RISC-V RVV, broader wasm/browser, and `no_std` acceleration remain prototype-only or scalar. | `docs/SIMD.md` |

release-crates.toml

@@ -7,7 +7,7 @@ previous_version = "1.3.5"
 version = "1.3.6"
 change = "dependency"
 publish = true
-reason = "Publishes the 1.3.6 family patch with synchronized crate versions and refreshed companion crate README headers."
+reason = "Publishes the 1.3.6 family patch with synchronized crate versions, refreshed companion crate README headers, staged CT decode docs, and a high-assurance compile cfg guard."
 
 [crates."base64-ng-sanitization"]
 previous_version = "1.3.5"

release-notes/RELEASE_NOTES_1.3.6.md

@@ -10,8 +10,15 @@ the `base64-ng` crate family.
   image, core documentation links, and crate-specific one-line summaries.
 - Updated public examples and migration snippets to reference the `1.3.6`
   crate family.
+- Moved the top constant-time guide example to
+  `decode_slice_staged_clear_tail` so shared-memory and HSM-adjacent users see
+  the staged decode pattern first.
+- Added the custom `base64_ng_require_high_assurance` cfg. When set, builds
+  that also enable `simd` fail at compile time.
 
 ## Notes
 
 No encode/decode logic, SIMD admission scope, target evidence posture, unsafe
-boundary, or runtime dependency policy changes in this release.
+boundary, or runtime dependency policy changes in this release. The
+high-assurance guard is a custom cfg, not a Cargo feature, so normal
+`--all-features` release evidence and docs.rs builds remain usable.

scripts/checks.sh

@@ -33,6 +33,14 @@ scripts/check_companion_crates.sh
 echo "checks: reserved feature placeholders"
 scripts/check_reserved_features.sh
 
+echo "checks: high-assurance cfg"
+RUSTFLAGS="--cfg base64_ng_require_high_assurance" cargo check --no-default-features --lib
+if RUSTFLAGS="--cfg base64_ng_require_high_assurance" cargo check --no-default-features --features simd --lib; then
+    echo "high-assurance cfg: expected simd combination to fail" >&2
+    exit 1
+fi
+echo "high-assurance cfg: ok"
+
 echo "checks: unsafe boundary"
 scripts/validate-unsafe-boundary.sh