Add subtle companion crate

Author: eldryoth

CHANGELOG.md

@@ -31,6 +31,9 @@
 - Wiped the small unpadded in-place decode tail buffer before return, expanded
   test-only AArch64 NEON prototype cleanup to all vector registers, and
   documented the wrapped slice encoder's temporary in-buffer staging behavior.
+- Added `base64-ng-subtle` as an optional companion crate for projects that
+  already admit `subtle` and want reviewed `ConstantTimeEq` comparisons for
+  `base64-ng` buffers.
 - Added a real non-dispatchable AVX2 fixed-block encode prototype for Standard
   and URL-safe alphabets. The prototype remains test-only and active runtime
   backend selection remains scalar-only.

Cargo.lock

@@ -38,6 +38,7 @@ members = [
     "crates/base64-ng-derive",
     "crates/base64-ng-sanitization",
     "crates/base64-ng-serde",
+    "crates/base64-ng-subtle",
     "crates/base64-ng-tokio",
 ]
 default-members = ["."]

Cargo.toml

@@ -74,9 +74,9 @@ Implemented now:
   clear-on-drop secret containers.
 - Optional `base64-ng-derive` companion crate for fixed-size byte newtypes that
   need narrow Base64 parsing and encoding helpers.
-- Optional `base64-ng-serde`, `base64-ng-bytes`, and `base64-ng-tokio`
-  companion crates for projects that explicitly admit those ecosystem
-  dependencies.
+- Optional `base64-ng-serde`, `base64-ng-bytes`, `base64-ng-subtle`, and
+  `base64-ng-tokio` companion crates for projects that explicitly admit those
+  ecosystem dependencies.
 - Local check scripts, release gate, dependency policy, audit config, CI, SBOM script, reproducible build check, and a 500-line production-source budget guard.
 
 Planned behind admission evidence:
@@ -162,9 +162,10 @@ The core `base64-ng` crate keeps its zero-runtime-dependency policy. Optional
 ecosystem integrations live as separate crates so applications can opt into
 their own approved dependency set without changing the base package.
 
-The `1.1.0` release changes only the core crate. Optional companion crates
-remain on their previous published versions, and Cargo's normal compatible
-dependency ranges allow those companions to resolve with `base64-ng` `1.1.0`.
+The `1.1.0` release changes the core crate and adds the optional
+`base64-ng-subtle` companion crate. Other optional companion crates remain on
+their previous published versions, and Cargo's normal compatible dependency
+ranges allow those companions to resolve with `base64-ng` `1.1.0`.
 
 | Crate | Purpose |
 | --- | --- |
@@ -173,6 +174,7 @@ dependency ranges allow those companions to resolve with `base64-ng` `1.1.0`.
 | `base64-ng-derive` | Dependency-free `Base64Secret` derive for fixed-size secret newtypes. |
 | `base64-ng-serde` | Optional `serde` wrappers for projects that already admit `serde`. |
 | `base64-ng-bytes` | Optional `bytes` helpers for `Bytes`, `Buf`, and `BufMut` users. |
+| `base64-ng-subtle` | Optional `subtle::ConstantTimeEq` helpers for token/MAC comparison boundaries. |
 | `base64-ng-tokio` | Optional bounded Tokio async helpers for services that already admit Tokio. |
 
 Subcrates are documented so crate pages are readable, but they belong to the
@@ -257,6 +259,23 @@ let encoded = STANDARD.encode_bytes(b"hello").unwrap();
 assert_eq!(&encoded[..], b"aGVsbG8=");
 ```
 
+`base64-ng-subtle` provides explicit `subtle::ConstantTimeEq` integration for
+projects that already admit `subtle`:
+
+```toml
+[dependencies]
+base64-ng = "1.1.0"
+base64-ng-subtle = "1.1.0"
+```
+
+```rust
+use base64_ng::ct;
+use base64_ng_subtle::SubtleEqExt;
+
+let decoded = ct::STANDARD.decode_secret(b"aGVsbG8=").unwrap();
+assert!(decoded.subtle_verify(b"hello"));
+```
+
 `base64-ng-tokio` provides bounded async helpers for applications that already
 use Tokio:
 

README.md

@@ -0,0 +1,39 @@
+[package]
+name = "base64-ng-subtle"
+version = "1.1.0"
+edition = "2024"
+rust-version = "1.90"
+license = "MIT OR Apache-2.0"
+description = "Optional subtle::ConstantTimeEq helpers for base64-ng buffers"
+repository = "https://github.com/valkyoth/base64-ng"
+homepage = "https://github.com/valkyoth/base64-ng"
+documentation = "https://docs.rs/base64-ng-subtle"
+readme = "README.md"
+keywords = ["base64", "constant-time", "crypto", "encoding"]
+categories = ["cryptography", "encoding", "no-std"]
+include = [
+    "src/**",
+    "tests/**",
+    "Cargo.toml",
+    "README.md",
+]
+
+[features]
+default = ["alloc"]
+alloc = ["base64-ng/alloc"]
+std = ["alloc", "base64-ng/std", "subtle/std"]
+
+[dependencies]
+base64-ng = { version = "1.1.0", path = "../..", default-features = false }
+subtle = { version = "2.6.1", default-features = false }
+
+[lints.rust]
+unsafe_code = "deny"
+missing_docs = "deny"
+
+[lints.clippy]
+all = "deny"
+pedantic = "deny"
+
+[package.metadata.docs.rs]
+all-features = true

crates/base64-ng-subtle/Cargo.toml

@@ -0,0 +1,24 @@
+# base64-ng-subtle
+
+Optional `subtle::ConstantTimeEq` integration for `base64-ng`.
+
+The core `base64-ng` crate stays zero-runtime-dependency. This companion crate
+is for applications that already admit the `subtle` crate and want explicit
+comparison helpers for decoded or encoded Base64 material.
+
+```toml
+[dependencies]
+base64-ng = "1.1.0"
+base64-ng-subtle = "1.1.0"
+```
+
+```rust
+use base64_ng::ct;
+use base64_ng_subtle::SubtleEqExt;
+
+let decoded = ct::STANDARD.decode_secret(b"aGVsbG8=").unwrap();
+assert!(decoded.subtle_verify(b"hello"));
+```
+
+Length is public: mismatched lengths return `Choice::from(0)` immediately.
+Use fixed-size protocol tokens when length must not vary.

crates/base64-ng-subtle/README.md

@@ -0,0 +1,122 @@
+#![cfg_attr(not(feature = "std"), no_std)]
+#![deny(unsafe_code)]
+#![deny(missing_docs)]
+#![deny(clippy::all)]
+#![deny(clippy::pedantic)]
+
+//! Optional `subtle::ConstantTimeEq` integration for `base64-ng`.
+//!
+//! The core `base64-ng` package stays zero-runtime-dependency. This companion
+//! crate exists for applications that already admit `subtle` and want a
+//! reviewed comparison primitive at the protocol boundary.
+//!
+//! Length is treated as public. Mismatched lengths return
+//! [`subtle::Choice::from(0)`] immediately. Use fixed-size protocol tokens when
+//! length must not vary.
+
+use base64_ng::{DecodedBuffer, EncodedBuffer};
+use subtle::{Choice, ConstantTimeEq};
+
+#[cfg(feature = "alloc")]
+use base64_ng::SecretBuffer;
+
+/// Extension trait for comparing `base64-ng` buffers with `subtle`.
+///
+/// The comparison delegates equal-length byte comparisons to
+/// [`subtle::ConstantTimeEq`]. Length mismatch remains public and returns
+/// `Choice::from(0)`.
+pub trait SubtleEqExt {
+    /// Compares `self` with `expected` using `subtle` for equal-length inputs.
+    ///
+    /// Length is public. If lengths differ, this returns `Choice::from(0)`.
+    #[must_use = "use Choice or convert it deliberately with bool::from(choice)"]
+    fn subtle_ct_eq(&self, expected: &[u8]) -> Choice;
+
+    /// Convenience boolean wrapper around [`Self::subtle_ct_eq`].
+    ///
+    /// Prefer [`Self::subtle_ct_eq`] when composing with other `subtle`
+    /// decisions.
+    #[must_use]
+    fn subtle_verify(&self, expected: &[u8]) -> bool {
+        bool::from(self.subtle_ct_eq(expected))
+    }
+}
+
+impl SubtleEqExt for [u8] {
+    fn subtle_ct_eq(&self, expected: &[u8]) -> Choice {
+        subtle_ct_eq_public_len(self, expected)
+    }
+}
+
+impl SubtleEqExt for &[u8] {
+    fn subtle_ct_eq(&self, expected: &[u8]) -> Choice {
+        subtle_ct_eq_public_len(self, expected)
+    }
+}
+
+impl<const CAP: usize> SubtleEqExt for DecodedBuffer<CAP> {
+    fn subtle_ct_eq(&self, expected: &[u8]) -> Choice {
+        subtle_ct_eq_public_len(self.as_bytes(), expected)
+    }
+}
+
+impl<const CAP: usize> SubtleEqExt for EncodedBuffer<CAP> {
+    fn subtle_ct_eq(&self, expected: &[u8]) -> Choice {
+        subtle_ct_eq_public_len(self.as_bytes(), expected)
+    }
+}
+
+#[cfg(feature = "alloc")]
+impl SubtleEqExt for SecretBuffer {
+    fn subtle_ct_eq(&self, expected: &[u8]) -> Choice {
+        subtle_ct_eq_public_len(self.expose_secret(), expected)
+    }
+}
+
+/// Compares two byte slices with public length.
+///
+/// Equal-length comparisons are delegated to [`subtle::ConstantTimeEq`].
+/// Mismatched lengths return `Choice::from(0)` immediately.
+#[must_use = "use Choice or convert it deliberately with bool::from(choice)"]
+pub fn subtle_ct_eq_public_len(left: &[u8], right: &[u8]) -> Choice {
+    if left.len() == right.len() {
+        left.ct_eq(right)
+    } else {
+        Choice::from(0)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{SubtleEqExt, subtle_ct_eq_public_len};
+    use base64_ng::STANDARD;
+
+    #[cfg(feature = "alloc")]
+    use base64_ng::ct;
+
+    #[test]
+    fn compares_raw_slices_with_public_length() {
+        assert!(bool::from(subtle_ct_eq_public_len(b"hello", b"hello")));
+        assert!(!bool::from(subtle_ct_eq_public_len(b"hello", b"world")));
+        assert!(!bool::from(subtle_ct_eq_public_len(b"hello", b"hello!")));
+    }
+
+    #[test]
+    fn compares_stack_backed_buffers() {
+        let decoded = STANDARD.decode_buffer::<5>(b"aGVsbG8=").unwrap();
+        assert!(decoded.subtle_verify(b"hello"));
+        assert!(!decoded.subtle_verify(b"world"));
+
+        let encoded = STANDARD.encode_buffer::<8>(b"hello").unwrap();
+        assert!(encoded.subtle_verify(b"aGVsbG8="));
+        assert!(!encoded.subtle_verify(b"aGVsbG8h"));
+    }
+
+    #[cfg(feature = "alloc")]
+    #[test]
+    fn compares_secret_buffer() {
+        let decoded = ct::STANDARD.decode_secret(b"aGVsbG8=").unwrap();
+        assert!(decoded.subtle_verify(b"hello"));
+        assert!(!decoded.subtle_verify(b"world"));
+    }
+}

crates/base64-ng-subtle/src/lib.rs

@@ -14,6 +14,7 @@ sets.
 | `base64-ng-derive` | `1.0.9` | no | <https://crates.io/crates/base64-ng-derive> |
 | `base64-ng-serde` | `1.0.10` | no | <https://crates.io/crates/base64-ng-serde> |
 | `base64-ng-bytes` | `1.0.9` | no | <https://crates.io/crates/base64-ng-bytes> |
+| `base64-ng-subtle` | `1.1.0` | yes | <https://crates.io/crates/base64-ng-subtle> |
 | `base64-ng-tokio` | `1.0.9` | no | <https://crates.io/crates/base64-ng-tokio> |
 
 ## Release Policy

docs/CRATE_VERSION_MATRIX.md

@@ -32,9 +32,10 @@ new dependency expands the audit, license, advisory, and supply-chain surface.
 - `base64-ng-derive` is an optional companion package for fixed-size byte
   newtypes. It is dependency-free and does not add proc-macro machinery to the
   core `base64-ng` package.
-- `base64-ng-serde`, `base64-ng-bytes`, and `base64-ng-tokio` are optional
-  companion packages for applications that already admit `serde`, `bytes`, or
-  `tokio`; they are not dependencies of the core `base64-ng` package.
+- `base64-ng-serde`, `base64-ng-bytes`, `base64-ng-subtle`, and
+  `base64-ng-tokio` are optional companion packages for applications that
+  already admit `serde`, `bytes`, `subtle`, or `tokio`; they are not
+  dependencies of the core `base64-ng` package.
 - Fuzz, performance, and dudect-style timing harness dependencies are isolated
   under `fuzz/`, `perf/`, and `dudect/`; the standard local gate checks them
   separately from the published crate dependency graph.
@@ -64,15 +65,21 @@ Current decisions:
 - `base64-ng-bytes` is admitted as a companion crate because services that
   already use `bytes` can opt into `Bytes`, `Buf`, and `BufMut` helpers without
   adding `bytes` to the core package.
+- `base64-ng-subtle` is admitted as a companion crate because authentication,
+  MAC, password-hash, and token verification boundaries can opt into a reviewed
+  `subtle::ConstantTimeEq` primitive without adding `subtle` to the core
+  package.
 - `base64-ng-tokio` is admitted as a companion crate for bounded async
   read-all/write-all helpers. Full streaming state machines remain deferred
   until cancellation-safety and drop-cleanup evidence is complete.
 - The core `tokio` feature remains reserved and inert until async
   cancellation, drop cleanup, chunk-boundary, dependency, and release-evidence
   requirements are satisfied.
-- `zeroize` and `subtle` remain deferred; applications can combine their own
-  approved dependencies with caller-owned buffers while `base64-ng` keeps its
-  audited local best-effort helpers dependency-free.
+- `zeroize` remains deferred for the core crate; applications can combine their
+  own approved dependencies with caller-owned buffers while `base64-ng` keeps
+  its audited local best-effort helpers dependency-free.
+- `subtle` is admitted only through `base64-ng-subtle`, not through the core
+  crate.
 - Property-testing and benchmark frameworks remain isolated or deferred; fuzz,
   dudect-style timing, and performance harnesses stay outside the published
   crate package.
@@ -131,9 +138,11 @@ core crate today:
   needed. The core crate does not admit `serde`.
 - `bytes`: use `base64-ng-bytes` when `Bytes`, `Buf`, or `BufMut` integration
   is needed. The core crate does not admit `bytes`.
-- `zeroize` or `subtle`: deferred unless a review proves that the dependency
-  materially improves the documented best-effort cleanup or
-  constant-time-oriented posture beyond the current audited local helpers.
+- `zeroize`: deferred unless a review proves that the dependency materially
+  improves the documented best-effort cleanup posture beyond the current
+  audited local helpers.
+- `subtle`: use `base64-ng-subtle` when protocol code needs a reviewed
+  constant-time equality primitive for decoded or encoded buffers.
 - Criterion or other benchmark frameworks: keep benchmark evidence isolated
   unless the added dependency graph clearly improves release evidence quality.
 
@@ -160,10 +169,10 @@ workspaces only when they are not packaged with the published crate:
 - `perf/` dependencies are reviewed by `scripts/check_perf.sh`.
 - `dudect/` dependencies are reviewed by `scripts/check_dudect.sh`.
 - `crates/base64-ng-sanitization/`, `crates/base64-ng-derive/`,
-  `crates/base64-ng-serde/`, `crates/base64-ng-bytes/`, and
-  `crates/base64-ng-tokio/` are optional companion crates, not dependencies of
-  the core `base64-ng` package. They are reviewed separately by
-  `scripts/check_companion_crates.sh` so the root package keeps its
+  `crates/base64-ng-serde/`, `crates/base64-ng-bytes/`,
+  `crates/base64-ng-subtle/`, and `crates/base64-ng-tokio/` are optional
+  companion crates, not dependencies of the core `base64-ng` package. They are
+  reviewed separately by `scripts/check_companion_crates.sh` so the root package keeps its
   zero-runtime-dependency guarantee.
 
 `scripts/checks.sh` runs those isolated harness checks so ordinary local

docs/DEPENDENCIES.md

@@ -624,6 +624,10 @@ Recommended `1.0.x` source-layout sequence:
   wipe path without emitting unsafe code into downstream crates. Add
   `base64-ng-serde`, `base64-ng-bytes`, and `base64-ng-tokio` as explicit
   opt-in ecosystem companion crates. Keep the core crate dependency-free.
+- `1.1.x`: add `base64-ng-subtle` as an explicit companion crate for
+  applications that already admit `subtle` and want reviewed
+  `ConstantTimeEq` comparison helpers without adding `subtle` to the core
+  crate.
 - `1.0.10`: source-layout maintenance release. Split oversized production
   modules into focused internal files, move Kani proofs and unit tests out of
   the root module, and add a 500-line production-source budget guard to the