Enforce custom alphabet consistency

eldryoth · eldryoth · commit 731b8032fc06 · 2026-07-15T19:17:45.000+02:00
diff --git a/.github/workflows/security-audit.yml b/.github/workflows/security-audit.yml
@@ -0,0 +1,44 @@
+name: Scheduled Security Audit
+
+on:
+  schedule:
+    - cron: "17 3 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: scheduled-security-audit
+  cancel-in-progress: false
+
+jobs:
+  advisories:
+    name: RustSec and cargo-deny advisories
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Install Rust toolchain
+        shell: bash
+        run: scripts/ci_install_rust.sh
+
+      - name: Cache Cargo data
+        uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2.9.1
+        with:
+          cache-on-failure: true
+
+      - name: Install cargo-audit
+        uses: taiki-e/install-action@c7eb1735f09259a5035e8e5d44b1406b1cddc0fb # v2.83.0
+        with:
+          tool: cargo-audit@0.22.2
+          fallback: none
+
+      - name: Install cargo-deny
+        run: cargo install --locked cargo-deny --version 0.20.2
+
+      - name: Check workspace and isolated-tool advisories
+        run: scripts/check_scheduled_advisories.sh
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -11,6 +11,11 @@
   attribute created only after successful JavaScript and wasm execution.
 - Added a fail-closed assertion that the browser success attribute is absent
   from the static smoke-test document.
+- Added a runtime alphabet-contract check that rejects hand-written
+  `Alphabet::encode` overrides when they disagree with `Alphabet::ENCODE`,
+  preventing API-, input-length-, or backend-dependent output.
+- Added daily and manually dispatchable RustSec and cargo-deny advisory checks
+  for the workspace and isolated dudect, fuzz, and performance lockfiles.
 - Updated async cleanup and release-evidence documentation.
 - Moved the stronger RISC-V RVV proof and backend-admission review to `1.3.9`.
 - No core encode/decode logic, SIMD admission scope, unsafe boundary, or core
diff --git a/README.md b/README.md
@@ -59,6 +59,9 @@ versions aligned and closes two low-severity evidence and cleanup gaps. Tokio
 read-all helpers now wipe replaced vector allocations before deallocation, and
 the Chromium wasm smoke gate requires a success attribute created only by
 runtime execution rather than matching a token present in static HTML.
+Runtime encoding also rejects custom `Alphabet::encode` overrides that
+disagree with their authoritative `Alphabet::ENCODE` table, and a dedicated
+daily workflow checks all maintained lockfiles for newly published advisories.
 The stronger RISC-V RVV proof and admission review is scheduled for `1.3.9`;
 until then, RISC-V remains QEMU-tested scalar/fallback-only. The workspace
 crate family stays version-aligned at `1.3.8`.
diff --git a/SECURITY.md b/SECURITY.md
@@ -28,6 +28,7 @@ Required for release:
 - `cargo +nightly miri test --no-default-features` when nightly Miri is installed
 - `cargo deny check`
 - `cargo audit`
+- daily and manually dispatchable RustSec and cargo-deny advisory monitoring
 - `cargo license --json`
 - SBOM generation
 - Reproducible build check
diff --git a/docs/API_AUDIT.md b/docs/API_AUDIT.md
@@ -248,6 +248,11 @@ Decision rationale:
   for every emitted byte. This preserves the conservative no secret-indexed
   lookup posture, but it is slower than the arithmetic mappers used by built-in
   alphabets.
+- `Alphabet::ENCODE` is the authoritative output table. A hand-written
+  `Alphabet::encode` override must agree with all 64 entries; runtime encode
+  APIs check that contract before dispatch and return
+  `EncodeError::InvalidAlphabet` before writing output when it is violated.
+  Const array encoding reads `Alphabet::ENCODE` directly.
 - Manual `Alphabet` implementations can override `encode` or `decode`; those
   overrides affect the normal `Engine` path. The `ct` module scans
   `Alphabet::ENCODE` directly and does not depend on custom `decode`
diff --git a/docs/CRATE_VERSION_MATRIX.md b/docs/CRATE_VERSION_MATRIX.md
@@ -12,7 +12,9 @@ shipping two low-severity hardening fixes. The Tokio companion now performs
 guarded read-all vector growth and wipes every replaced allocation before
 deallocation. The Chromium-family wasm evidence gate now requires a
 runtime-created DOM success attribute that is proven absent from the static
-HTML source. Core encode/decode behavior, SIMD admission scope, unsafe
+HTML source. Runtime encoding now rejects custom `Alphabet::encode` overrides
+that disagree with their `Alphabet::ENCODE` table, and scheduled advisory
+monitoring covers all maintained lockfiles. SIMD admission scope, unsafe
 boundaries, and the zero-dependency core posture remain unchanged. The
 stronger RISC-V RVV proof and backend-admission review moves to `1.3.9`.
 
diff --git a/docs/DEPENDENCIES.md b/docs/DEPENDENCIES.md
@@ -126,6 +126,8 @@ At minimum, evidence must include:
 - `cargo tree` for the affected feature set.
 - `cargo deny check`.
 - `cargo audit`.
+- `scripts/check_scheduled_advisories.sh` through the daily and manually
+  dispatchable security-audit workflow.
 - `cargo license --json`.
 - Updated release notes and migration/security documentation when the public
   API or threat model changes.
diff --git a/docs/PLAN.md b/docs/PLAN.md
@@ -1177,6 +1177,10 @@ inside the `1.3.x` line if they remain evidence-gated and do not weaken the
   wiped before it is returned to the allocator.
 - Require Chromium-family wasm smoke evidence to contain a runtime-created DOM
   success attribute that is absent from the static test document.
+- Reject custom runtime alphabet encoders that disagree with their
+  authoritative `Alphabet::ENCODE` table before writing caller output.
+- Add daily and manually dispatchable advisory monitoring for workspace and
+  isolated tool lockfiles.
 - Preserve core encode/decode behavior, SIMD admission scope, unsafe
   boundaries, and the zero-dependency core posture.
 - Move the stronger RISC-V RVV proof and backend-admission review to `1.3.9`
diff --git a/docs/RELEASE_EVIDENCE.md b/docs/RELEASE_EVIDENCE.md
@@ -142,6 +142,8 @@ The release gate runs:
 - all-features and no-default-features doctests plus documentation builds
 - `cargo deny check`
 - `cargo audit`
+- daily and manually dispatchable RustSec plus cargo-deny advisory monitoring
+  for the workspace and isolated fuzz, dudect, and performance lockfiles
 - `cargo license --json`
 - async admission documentation packaged while the `tokio` feature remains
   inert and dependency-free
diff --git a/docs/TRUST.md b/docs/TRUST.md
@@ -24,7 +24,7 @@ stable release.
 | Miri | Release gate runs Miri when nightly Miri is installed and writes evidence artifacts | `scripts/check_miri.sh`, `target/release-evidence/miri/` |
 | Kani | 18 bounded no-default-features harnesses verify cleanly with the Rust `1.90.0` Kani toolchain and `cargo-kani 0.67.0`; incompatible future verifier/toolchain pairs must skip explicitly rather than pretending to prove. | `scripts/check_kani.sh`, `docs/KANI.md` |
 | Bounds invariants | Remaining internal indexing is grouped by documented local invariants | `docs/INVARIANTS.md` |
-| Audit | RustSec check required | `cargo audit`, `scripts/checks.sh` |
+| Audit | RustSec and cargo-deny advisory checks required on every change and daily while the repository is dormant | `cargo audit`, `scripts/checks.sh`, `scripts/check_scheduled_advisories.sh`, scheduled security-audit workflow |
 | License policy | `cargo deny` and `cargo license --json` required | `deny.toml`, `scripts/checks.sh` |
 | SBOM | SPDX and CycloneDX SBOM generation in release evidence | `scripts/generate-sbom.sh` |
 | Reproducibility | Package/build reproducibility check in release gate | `scripts/stable_release_gate.sh` |
diff --git a/release-crates.toml b/release-crates.toml
@@ -7,7 +7,7 @@ previous_version = "1.3.7"
 version = "1.3.8"
 change = "code"
 publish = true
-reason = "Publishes the 1.3.8 security-hardening patch with guarded Tokio read-all growth and a runtime-only browser wasm success marker; the stronger RISC-V RVV proof and admission review moves to 1.3.9."
+reason = "Publishes the 1.3.8 security-hardening patch with guarded Tokio read-all growth, runtime-only browser wasm evidence, consistent custom alphabet encoding, and scheduled advisory monitoring; the stronger RISC-V RVV review moves to 1.3.9."
 
 [crates."base64-ng-sanitization"]
 previous_version = "1.3.7"
diff --git a/release-notes/RELEASE_NOTES_1.3.8.md b/release-notes/RELEASE_NOTES_1.3.8.md
@@ -12,6 +12,10 @@ the `base64-ng` workspace.
   coverage above the 8 KiB eager capacity.
 - Hardened Chromium-family wasm runtime evidence so success requires a
   runtime-created DOM attribute that is absent from the static HTML source.
+- Added a runtime alphabet-contract check that rejects hand-written
+  `Alphabet::encode` overrides when they disagree with `Alphabet::ENCODE`.
+- Added daily and manually dispatchable RustSec and cargo-deny monitoring for
+  the workspace and isolated tool lockfiles.
 - Updated async cleanup, release evidence, migration, and dependency examples.
 - Moved the stronger RISC-V RVV proof and backend-admission review to `1.3.9`.
 
diff --git a/scripts/check_scheduled_advisories.sh b/scripts/check_scheduled_advisories.sh
@@ -0,0 +1,29 @@
+#!/usr/bin/env sh
+set -eu
+
+deny_advisories() {
+    manifest="$1"
+    config="$2"
+
+    if cargo deny --help 2>/dev/null | grep -q -- '--config'; then
+        cargo deny --manifest-path "$manifest" --config "$config" check advisories
+    else
+        cargo deny --manifest-path "$manifest" check advisories --config "$config"
+    fi
+}
+
+echo "scheduled advisories: workspace RustSec audit"
+cargo audit --file Cargo.lock
+
+echo "scheduled advisories: workspace cargo-deny advisory policy"
+deny_advisories Cargo.toml deny.toml
+
+for package in dudect fuzz perf; do
+    echo "scheduled advisories: $package RustSec audit"
+    cargo audit --file "$package/Cargo.lock"
+
+    echo "scheduled advisories: $package cargo-deny advisory policy"
+    deny_advisories "$package/Cargo.toml" "$package/deny.toml"
+done
+
+echo "scheduled advisories: ok"
diff --git a/scripts/validate-release-metadata.sh b/scripts/validate-release-metadata.sh
@@ -88,6 +88,7 @@ test -s docs/SIMD_ADMISSION.md
 test -s docs/SIMD_ENCODE_ADMISSION_DRAFT.md
 test -s docs/TRUST.md
 test -s docs/UNSAFE.md
+test -s .github/workflows/security-audit.yml
 test -x scripts/release_crates.py
 test -x scripts/generate_release_history.py
 test -x scripts/validate-release-readiness.sh
@@ -116,6 +117,7 @@ for required_script in \
     "scripts/cargo-deny-check.sh" \
     "scripts/check_riscv_qemu.sh" \
     "scripts/check_riscv_intrinsics_status.sh" \
+    "scripts/check_scheduled_advisories.sh" \
     "scripts/validate-api-audit.sh" \
     "scripts/validate-big-endian-posture.sh" \
     "scripts/validate-riscv-posture.sh" \
@@ -161,6 +163,17 @@ do
     fi
 done
 
+for required_scheduled_audit_text in \
+    'cron: "17 3 * * *"' \
+    "workflow_dispatch:" \
+    "scripts/check_scheduled_advisories.sh"
+do
+    if ! grep -F -q "$required_scheduled_audit_text" .github/workflows/security-audit.yml; then
+        echo "release metadata: scheduled security audit is missing $required_scheduled_audit_text" >&2
+        exit 1
+    fi
+done
+
 if [ "$(sed -n '1p' scripts/validate-release-readiness.sh)" != "#!/usr/bin/env sh" ]; then
     echo "release metadata: scripts/validate-release-readiness.sh must use #!/usr/bin/env sh" >&2
     exit 1
diff --git a/src/alphabet.rs b/src/alphabet.rs
@@ -221,7 +221,12 @@ pub const fn decode_alphabet_byte(byte: u8, encode: &[u8; 64]) -> Option<u8> {
 /// it scans all 64 alphabet entries instead of using `ENCODE[value as usize]`.
 /// If an implementation overrides `encode` with a direct table lookup, normal
 /// [`Engine`](crate::Engine) encoding becomes timing-sensitive with respect to
-/// the emitted 6-bit value.
+/// the emitted 6-bit value. An override must return exactly the byte stored at
+/// the corresponding [`Alphabet::ENCODE`] index for every value from 0 through
+/// 63. Runtime encode APIs verify this fixed contract before dispatch and
+/// return [`EncodeError::InvalidAlphabet`](crate::EncodeError::InvalidAlphabet)
+/// without writing output when it is violated. Const array encoding uses
+/// [`Alphabet::ENCODE`] directly.
 ///
 /// The normal strict decode path calls [`Alphabet::decode`] and is not a
 /// constant-time decoder. The [`ct`](crate::ct) module does not call
@@ -358,6 +363,17 @@ pub(crate) fn encode_base64_value_runtime<A: Alphabet>(value: u8) -> u8 {
     A::encode(value)
 }
 
+pub(crate) fn encode_contract_holds<A: Alphabet>() -> bool {
+    let mut value = 0u8;
+    while value < 64 {
+        if A::encode(value) != A::ENCODE[value as usize] {
+            return false;
+        }
+        value += 1;
+    }
+    true
+}
+
 #[inline]
 const fn encode_alphabet_value(value: u8, encode: &[u8; 64]) -> u8 {
     let mut output = 0;
diff --git a/src/encode_backend.rs b/src/encode_backend.rs
@@ -8,7 +8,7 @@
 //! stack staging before entering admitted encode backends so output writes do
 //! not overwrite unread input bytes.
 
-use crate::{Alphabet, EncodeError, scalar, scalar_encode_in_place};
+use crate::{Alphabet, EncodeError, encode_contract_holds, scalar, scalar_encode_in_place};
 #[cfg(any(
     all(
         feature = "simd",
@@ -125,6 +125,10 @@ pub(crate) fn encode_slice<A, const PAD: bool>(
 where
     A: Alphabet,
 {
+    if !encode_contract_holds::<A>() {
+        return Err(EncodeError::InvalidAlphabet);
+    }
+
     if input.len() < MIN_SIMD_ENCODE_BLOCK {
         return scalar::encode_slice::<A, PAD>(input, output);
     }
@@ -199,6 +203,10 @@ pub(crate) fn encode_in_place<A, const PAD: bool>(
 where
     A: Alphabet,
 {
+    if !encode_contract_holds::<A>() {
+        return Err(EncodeError::InvalidAlphabet);
+    }
+
     match active_encode_backend() {
         EncodeBackend::Scalar => {
             scalar_encode_in_place::encode_in_place::<A, PAD>(buffer, input_len)
diff --git a/src/encode_surface_tests.rs b/src/encode_surface_tests.rs
@@ -10,6 +10,20 @@ impl Alphabet for DispatchFallbackAlphabet {
     }
 }
 
+struct InconsistentEncodeAlphabet;
+
+impl Alphabet for InconsistentEncodeAlphabet {
+    const ENCODE: [u8; 64] = Standard::ENCODE;
+
+    fn encode(_value: u8) -> u8 {
+        b'!'
+    }
+
+    fn decode(byte: u8) -> Option<u8> {
+        Standard::decode(byte)
+    }
+}
+
 fn fill_pattern(output: &mut [u8], seed: usize) {
     for (index, byte) in output.iter_mut().enumerate() {
         let value = (index * 73 + seed * 19) % 256;
@@ -111,6 +125,65 @@ fn encode_in_place_backend_matches_scalar_reference() {
     }
 }
 
+#[test]
+fn inconsistent_encode_override_fails_before_runtime_output_writes() {
+    const TABLE_OUTPUT: [u8; 4] =
+        Engine::<InconsistentEncodeAlphabet, true>::new().encode_array(&[0, 0, 0]);
+    assert_eq!(TABLE_OUTPUT, *b"AAAA");
+
+    let engine = Engine::<InconsistentEncodeAlphabet, true>::new();
+    let input = [0u8; 49];
+
+    for input_len in [1, 12, 49] {
+        let input = &input[..input_len];
+        let mut output = [0x55; 128];
+        assert_eq!(
+            engine.encode_slice(input, &mut output),
+            Err(EncodeError::InvalidAlphabet)
+        );
+        assert!(output.iter().all(|byte| *byte == 0x55));
+
+        let mut wrapped = [0x66; 160];
+        assert_eq!(
+            engine.encode_slice_wrapped(input, &mut wrapped, LineWrap::new(16, LineEnding::CrLf),),
+            Err(EncodeError::InvalidAlphabet)
+        );
+        assert!(wrapped.iter().all(|byte| *byte == 0x66));
+
+        let mut clear_tail = [0x77; 128];
+        assert_eq!(
+            engine.encode_slice_clear_tail(input, &mut clear_tail),
+            Err(EncodeError::InvalidAlphabet)
+        );
+        assert!(clear_tail.iter().all(|byte| *byte == 0));
+
+        let mut in_place = [0x88; 128];
+        in_place[..input_len].copy_from_slice(input);
+        let original = in_place;
+        assert_eq!(
+            engine
+                .encode_in_place(&mut in_place, input_len)
+                .unwrap_err(),
+            EncodeError::InvalidAlphabet
+        );
+        assert_eq!(in_place, original);
+
+        assert_eq!(
+            engine.encode_buffer::<128>(input).unwrap_err(),
+            EncodeError::InvalidAlphabet
+        );
+
+        #[cfg(feature = "alloc")]
+        {
+            assert_eq!(engine.encode_vec(input), Err(EncodeError::InvalidAlphabet));
+            assert_eq!(
+                engine.encode_string(input),
+                Err(EncodeError::InvalidAlphabet)
+            );
+        }
+    }
+}
+
 #[test]
 fn encode_simd_admission_rejects_non_standard_alphabet_families() {
     #[cfg(all(
diff --git a/src/engine/encode_in_place.rs b/src/engine/encode_in_place.rs
@@ -38,12 +38,12 @@ where
     /// Encodes the first `input_len` bytes of `buffer` in place and clears all
     /// bytes after the encoded prefix.
     ///
-    /// If encoding fails because `input_len` is too large, the output buffer is
-    /// too small, or the encoded length overflows `usize`, the entire buffer is
-    /// cleared before the error is returned. This includes the original
-    /// plaintext in `buffer[..input_len]`; keep another copy before calling
-    /// this method if recovery of the original input is required after an
-    /// error.
+    /// If encoding fails because the alphabet contract is invalid,
+    /// `input_len` is too large, the output buffer is too small, or the encoded
+    /// length overflows `usize`, the entire buffer is cleared before the error
+    /// is returned. This includes the original plaintext in
+    /// `buffer[..input_len]`; keep another copy before calling this method if
+    /// recovery of the original input is required after an error.
     ///
     /// # Examples
     ///
diff --git a/src/errors.rs b/src/errors.rs
diff --git a/src/lib.rs b/src/lib.rs
