Add panic policy validation

Author: eldryoth

CHANGELOG.md

@@ -22,6 +22,8 @@
   redacted owned sensitive output with dependency-free best-effort cleanup.
 - Added `docs/TRUST.md`, `docs/SECURITY_CONTROLS.md`, and a README trust
   dashboard for adoption-focused security evidence and CWE mapping.
+- Added `docs/PANIC_POLICY.md` and `scripts/validate-panic-policy.sh` to keep
+  runtime panic-like sites reviewed and release-gated.
 
 ## 0.5.0 - 2026-05-14
 

README.md

@@ -478,6 +478,8 @@ acceleration gate, see [docs/SIMD.md](docs/SIMD.md).
 For the trust dashboard and CWE/security-control mapping, see
 [docs/TRUST.md](docs/TRUST.md) and
 [docs/SECURITY_CONTROLS.md](docs/SECURITY_CONTROLS.md).
+For panic-free public API policy, see
+[docs/PANIC_POLICY.md](docs/PANIC_POLICY.md).
 For dependency admission rules, see [docs/DEPENDENCIES.md](docs/DEPENDENCIES.md).
 For adoption guidance from the established `base64` crate, see
 [docs/MIGRATION.md](docs/MIGRATION.md).

SECURITY.md

@@ -96,6 +96,8 @@ 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.
+`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`.
 
 Bounded-memory users should prefer `checked_encoded_len`, `decoded_capacity`,
 `decode_slice`, and `decode_in_place` so allocation limits are chosen by the

docs/PANIC_POLICY.md

@@ -0,0 +1,54 @@
+# Panic Policy
+
+`base64-ng` treats runtime panics in public scalar APIs as denial-of-service
+risk. Public encode, decode, validation, length, in-place, streaming, and
+profile APIs should report malformed input and size failures with `Result` or
+`Option` rather than unwinding.
+
+This policy is enforced by:
+
+```sh
+scripts/validate-panic-policy.sh
+```
+
+The validator scans non-test source before Kani/test-only modules and fails on
+new `panic!`, `unreachable!`, `.unwrap()`, or `.expect()` sites unless they
+match an allowlisted pattern documented here.
+
+## Allowed Non-Test Sites
+
+The current reviewed exceptions are:
+
+- `Engine::encode_array` may panic during const evaluation when the caller
+  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.
+- Internal remainder matches use `_ => unreachable!()` after matching
+  `len % 3` or equivalent remainder values. The preceding arithmetic bounds
+  make those arms unreachable.
+- `String::from_utf8` conversions after Base64 encoding use `unreachable!`
+  because crate encoders produce ASCII bytes by construction.
+- 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.
+
+Test code, doctest examples, and Kani proof harnesses may use `unwrap`,
+`expect`, or panic-like macros when they are asserting expected outcomes.
+
+## Caller Guidance
+
+For untrusted input and untrusted length metadata, prefer:
+
+- `checked_encoded_len`
+- `encoded_len`
+- `wrapped_encoded_len`
+- `decoded_capacity`
+- `decoded_len`
+- caller-owned `encode_slice` and `decode_slice`
+- in-place APIs that return `Result`
+
+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.

docs/PLAN.md

@@ -178,12 +178,13 @@ the zero-runtime-dependency stance.
 - Internal safe-Rust best-effort wipe helpers for initialized bytes and
   redacted `SecretBuffer` owned outputs when `alloc` is enabled.
 - README trust dashboard and CWE/security-control mapping documentation.
+- Panic policy documentation and release-gated panic-like-site validation for
+  non-test source.
 
 ### Missing Secure Core Features
 
-- Expand panic-free policy checks for non-test scalar code, replacing unchecked
-  indexing and unwrap-like operations where practical or proving their bounds
-  where replacement would harm clarity.
+- Continue replacing unchecked indexing where practical or documenting bounded
+  internal indexing with proof, tests, or local invariants.
 
 ### Missing Performance Features
 

docs/RELEASE_EVIDENCE.md

@@ -62,6 +62,8 @@ The release gate runs:
 - unsafe-boundary validation that requires inventory documentation for every
   SIMD-boundary unsafe function and a nearby `SAFETY:` explanation for every
   unsafe block
+- panic-policy validation that fails on unreviewed non-test `panic!`,
+  `unreachable!`, `.unwrap()`, or `.expect()` sites
 - runtime backend report tests proving the public active backend remains scalar
   until an accelerated backend is explicitly admitted
 - runtime backend policy tests for scalar execution and no-SIMD deployment

scripts/checks.sh

@@ -16,6 +16,9 @@ scripts/check_reserved_features.sh
 echo "checks: unsafe boundary"
 scripts/validate-unsafe-boundary.sh
 
+echo "checks: panic policy"
+scripts/validate-panic-policy.sh
+
 echo "checks: clippy default"
 cargo clippy --all-targets -- -D warnings
 

scripts/validate-panic-policy.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env sh
+set -eu
+
+check_file() {
+    file="$1"
+    awk '
+        BEGIN {
+            failed = 0
+        }
+        /^#\[cfg\((test|kani)\)\]/ {
+            exit failed
+        }
+        /^[[:space:]]*\/\/[!\/]/ {
+            next
+        }
+        /panic!\(|unreachable!\(|\.unwrap\(|\.expect\(/ {
+            allowed = 0
+            if ($0 ~ /unreachable!\("stream .* was already taken"\)/) {
+                allowed = 1
+            }
+            if ($0 ~ /unreachable!\("base64 encoder produced non-UTF-8 output"\)/) {
+                allowed = 1
+            }
+            if ($0 ~ /_ => unreachable!\(\),/) {
+                allowed = 1
+            }
+            if ($0 ~ /panic!\("encoded base64 length overflows usize"\)/) {
+                allowed = 1
+            }
+            if (!allowed) {
+                printf "panic policy: unreviewed panic-like site in %s:%d: %s\n", FILENAME, FNR, $0 > "/dev/stderr"
+                failed = 1
+            }
+        }
+        END {
+            exit failed
+        }
+    ' "$file"
+}
+
+test -s docs/PANIC_POLICY.md
+
+check_file src/lib.rs
+check_file src/simd.rs
+
+echo "panic policy: ok"

scripts/validate-release-metadata.sh

@@ -61,10 +61,13 @@ test -s docs/BENCHMARKS.md
 test -s docs/CONSTANT_TIME.md
 test -s docs/DEPENDENCIES.md
 test -s docs/MIGRATION.md
+test -s docs/PANIC_POLICY.md
 test -s docs/PLAN.md
 test -s docs/RELEASE.md
 test -s docs/RELEASE_EVIDENCE.md
+test -s docs/SECURITY_CONTROLS.md
 test -s docs/SIMD.md
+test -s docs/TRUST.md
 test -s docs/UNSAFE.md
 
 for required_script in \
@@ -81,6 +84,7 @@ for required_script in \
     "scripts/reproducible_build_check.sh" \
     "scripts/stable_release_gate.sh" \
     "scripts/validate-dependencies.sh" \
+    "scripts/validate-panic-policy.sh" \
     "scripts/validate-release-metadata.sh" \
     "scripts/validate-unsafe-boundary.sh"
 do
@@ -128,10 +132,13 @@ for required_package_file in \
     "docs/CONSTANT_TIME.md" \
     "docs/DEPENDENCIES.md" \
     "docs/MIGRATION.md" \
+    "docs/PANIC_POLICY.md" \
     "docs/PLAN.md" \
     "docs/RELEASE.md" \
     "docs/RELEASE_EVIDENCE.md" \
+    "docs/SECURITY_CONTROLS.md" \
     "docs/SIMD.md" \
+    "docs/TRUST.md" \
     "docs/UNSAFE.md" \
     "scripts/check_backend_evidence.sh" \
     "scripts/check_fuzz.sh" \
@@ -146,6 +153,7 @@ for required_package_file in \
     "scripts/reproducible_build_check.sh" \
     "scripts/stable_release_gate.sh" \
     "scripts/validate-dependencies.sh" \
+    "scripts/validate-panic-policy.sh" \
     "scripts/validate-release-metadata.sh" \
     "scripts/validate-unsafe-boundary.sh" \
     "src/lib.rs" \