Add stack encoded buffer helper

Author: eldryoth

CHANGELOG.md

@@ -16,6 +16,8 @@
 - Added named dependency-free profiles for MIME, PEM, bcrypt-style, and
   `crypt(3)`-style Base64 through `Profile`, `MIME`, `PEM`, `PEM_CRLF`,
   `BCRYPT`, and `CRYPT`.
+- Added `EncodedBuffer` and `encode_buffer` helpers for stack-backed short
+  encoded output without requiring `alloc`.
 
 ## 0.5.0 - 2026-05-14
 

README.md

@@ -31,6 +31,7 @@ Implemented now:
 - Custom alphabet validation helpers for user-defined 64-byte alphabets.
 - Named dependency-free profiles for MIME, PEM, bcrypt-style, and
   `crypt(3)`-style Base64.
+- Stack-backed encoded output buffers for short values without `alloc`.
 - Separate `ct` scalar decode module for sensitive payloads that avoids
   secret-indexed lookup tables during Base64 symbol mapping.
 - `std::io` streaming encoders and decoders behind the `stream` feature.
@@ -309,6 +310,23 @@ returning the error. The legacy whitespace profile also provides
 The `ct` module provides the same clear-tail decode variants for callers using
 the constant-time-oriented scalar decoder.
 
+For short values, `encode_buffer` returns a stack-backed `EncodedBuffer`
+without requiring the `alloc` feature:
+
+```rust
+use base64_ng::{BCRYPT, STANDARD};
+
+let encoded = STANDARD.encode_buffer::<8>(b"hello").unwrap();
+assert_eq!(encoded.as_str(), "aGVsbG8=");
+
+let bcrypt = BCRYPT.encode_buffer::<4>(&[0xff, 0xff, 0xff]).unwrap();
+assert_eq!(bcrypt.as_bytes(), b"9999");
+```
+
+`EncodedBuffer` exposes bytes only through `as_bytes` and `as_str`, redacts the
+payload from `Debug`, and clears its backing array when dropped as best-effort
+data-retention reduction.
+
 With the default `alloc` feature, vector and string helpers are available:
 
 ```rust

docs/PLAN.md

@@ -174,12 +174,10 @@ the zero-runtime-dependency stance.
 - Named MIME, PEM, bcrypt-style, and `crypt(3)`-style profiles.
 - Custom alphabet validation helpers with duplicate-character, padding-byte,
   and visible-ASCII checks.
+- Stack-backed encoded output helpers for short values without `alloc`.
 
 ### Missing Secure Core Features
 
-- Add zero-dependency small-output helpers for common short values, such as a
-  stack-backed encoded buffer type that avoids heap allocation without forcing
-  callers to hand-roll arrays.
 - Add internal best-effort wipe primitives for crate-owned temporary buffers,
   using volatile writes and compiler fences where appropriate. This must be
   documented as retention reduction, not a hard zeroization guarantee.
@@ -325,7 +323,8 @@ the zero-runtime-dependency stance.
   policies, including CRLF and LF output.
 - Add validate-only APIs for strict, legacy, profile-aware, and
   constant-time-oriented validation use cases.
-- Add zero-dependency stack-backed output helpers for short encoded values.
+- Completed zero-dependency stack-backed output helpers for short encoded
+  values.
 - Add internal best-effort wiping helpers and secret wrapper types with redacted
   formatting for sensitive owned buffers.
 - Add the README trust dashboard and CWE/security-control mapping

src/lib.rs

@@ -1503,6 +1503,126 @@ impl LineWrap {
     }
 }
 
+/// Stack-backed encoded Base64 output.
+///
+/// This type is intended for short values where heap allocation would be
+/// unnecessary but manually sizing and passing a separate output slice is
+/// noisy. Its visible bytes are produced by crate encoders, so [`Self::as_str`]
+/// can return `&str` without exposing a fallible UTF-8 conversion to callers.
+///
+/// The backing array is cleared when the value is dropped. This is best-effort
+/// data-retention reduction and is not a formal zeroization guarantee.
+pub struct EncodedBuffer<const CAP: usize> {
+    bytes: [u8; CAP],
+    len: usize,
+}
+
+impl<const CAP: usize> EncodedBuffer<CAP> {
+    /// Creates an empty encoded buffer.
+    #[must_use]
+    pub const fn new() -> Self {
+        Self {
+            bytes: [0u8; CAP],
+            len: 0,
+        }
+    }
+
+    /// Returns the number of visible encoded bytes.
+    #[must_use]
+    pub const fn len(&self) -> usize {
+        self.len
+    }
+
+    /// Returns whether the buffer has no visible encoded bytes.
+    #[must_use]
+    pub const fn is_empty(&self) -> bool {
+        self.len == 0
+    }
+
+    /// Returns the stack capacity in bytes.
+    #[must_use]
+    pub const fn capacity(&self) -> usize {
+        CAP
+    }
+
+    /// Returns the visible encoded bytes.
+    #[must_use]
+    pub fn as_bytes(&self) -> &[u8] {
+        &self.bytes[..self.len]
+    }
+
+    /// Returns the visible encoded bytes as UTF-8.
+    ///
+    /// # Panics
+    ///
+    /// Panics only if the crate's internal invariant is broken and the buffer
+    /// contains non-UTF-8 bytes.
+    #[must_use]
+    pub fn as_str(&self) -> &str {
+        match core::str::from_utf8(self.as_bytes()) {
+            Ok(output) => output,
+            Err(_) => unreachable!("base64 encoder produced non-UTF-8 output"),
+        }
+    }
+
+    /// Clears the visible bytes and the full backing array.
+    pub fn clear(&mut self) {
+        self.bytes.fill(0);
+        self.len = 0;
+    }
+
+    /// Clears bytes after the visible prefix.
+    pub fn clear_tail(&mut self) {
+        self.bytes[self.len..].fill(0);
+    }
+}
+
+impl<const CAP: usize> AsRef<[u8]> for EncodedBuffer<CAP> {
+    fn as_ref(&self) -> &[u8] {
+        self.as_bytes()
+    }
+}
+
+impl<const CAP: usize> Clone for EncodedBuffer<CAP> {
+    fn clone(&self) -> Self {
+        let mut output = Self::new();
+        output.bytes[..self.len].copy_from_slice(self.as_bytes());
+        output.len = self.len;
+        output
+    }
+}
+
+impl<const CAP: usize> core::fmt::Debug for EncodedBuffer<CAP> {
+    fn fmt(&self, formatter: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+        formatter
+            .debug_struct("EncodedBuffer")
+            .field("bytes", &"<redacted>")
+            .field("len", &self.len)
+            .field("capacity", &CAP)
+            .finish()
+    }
+}
+
+impl<const CAP: usize> Default for EncodedBuffer<CAP> {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl<const CAP: usize> Drop for EncodedBuffer<CAP> {
+    fn drop(&mut self) {
+        self.clear();
+    }
+}
+
+impl<const CAP: usize> Eq for EncodedBuffer<CAP> {}
+
+impl<const CAP: usize> PartialEq for EncodedBuffer<CAP> {
+    fn eq(&self, other: &Self) -> bool {
+        self.as_bytes() == other.as_bytes()
+    }
+}
+
 /// A named Base64 profile with an engine and optional strict line wrapping.
 ///
 /// Profiles are convenience values for protocol-shaped Base64. They keep the
@@ -1589,6 +1709,27 @@ where
         }
     }
 
+    /// Encodes `input` into a stack-backed buffer.
+    ///
+    /// This is useful for short values where heap allocation is unnecessary.
+    /// If encoding fails, the internal backing array is cleared before the
+    /// error is returned.
+    pub fn encode_buffer<const CAP: usize>(
+        &self,
+        input: &[u8],
+    ) -> Result<EncodedBuffer<CAP>, EncodeError> {
+        let mut output = EncodedBuffer::new();
+        let written = match self.encode_slice_clear_tail(input, &mut output.bytes) {
+            Ok(written) => written,
+            Err(err) => {
+                output.clear();
+                return Err(err);
+            }
+        };
+        output.len = written;
+        Ok(output)
+    }
+
     /// Decodes `input` into `output` according to this profile.
     pub fn decode_slice(&self, input: &[u8], output: &mut [u8]) -> Result<usize, DecodeError> {
         match self.wrap {
@@ -2657,6 +2798,36 @@ where
         Ok(written)
     }
 
+    /// Encodes `input` into a stack-backed buffer.
+    ///
+    /// This helper is useful for short values where callers want the
+    /// convenience of an owned result without enabling `alloc`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use base64_ng::STANDARD;
+    ///
+    /// let encoded = STANDARD.encode_buffer::<8>(b"hello").unwrap();
+    ///
+    /// assert_eq!(encoded.as_str(), "aGVsbG8=");
+    /// ```
+    pub fn encode_buffer<const CAP: usize>(
+        &self,
+        input: &[u8],
+    ) -> Result<EncodedBuffer<CAP>, EncodeError> {
+        let mut output = EncodedBuffer::new();
+        let written = match self.encode_slice_clear_tail(input, &mut output.bytes) {
+            Ok(written) => written,
+            Err(err) => {
+                output.clear();
+                return Err(err);
+            }
+        };
+        output.len = written;
+        Ok(output)
+    }
+
     /// Encodes `input` into a newly allocated byte vector.
     #[cfg(feature = "alloc")]
     pub fn encode_vec(&self, input: &[u8]) -> Result<alloc::vec::Vec<u8>, EncodeError> {

tests/rfc4648.rs

@@ -1,9 +1,9 @@
 use base64_ng::{
     Alphabet, AlphabetError, BCRYPT, BCRYPT_NO_PAD, Bcrypt, CRYPT, CRYPT_NO_PAD, Crypt,
-    DecodeError, EncodeError, Engine, LineEnding, LineWrap, MIME, PEM, PEM_CRLF, STANDARD,
-    STANDARD_NO_PAD, Standard, URL_SAFE, URL_SAFE_NO_PAD, UrlSafe, checked_encoded_len, ct,
-    decode_alphabet_byte, decoded_capacity, decoded_len, encoded_len, runtime, validate_alphabet,
-    wrapped_encoded_len,
+    DecodeError, EncodeError, EncodedBuffer, Engine, LineEnding, LineWrap, MIME, PEM, PEM_CRLF,
+    STANDARD, STANDARD_NO_PAD, Standard, URL_SAFE, URL_SAFE_NO_PAD, UrlSafe, checked_encoded_len,
+    ct, decode_alphabet_byte, decoded_capacity, decoded_len, encoded_len, runtime,
+    validate_alphabet, wrapped_encoded_len,
 };
 
 #[cfg(feature = "stream")]
@@ -1695,6 +1695,49 @@ fn rejects_non_canonical_trailing_bits() {
     );
 }
 
+#[test]
+fn stack_encoded_buffer_helpers_avoid_alloc_and_clear_tail() {
+    let encoded = STANDARD.encode_buffer::<8>(b"hello").unwrap();
+    assert_eq!(encoded.len(), 8);
+    assert_eq!(encoded.capacity(), 8);
+    assert!(!encoded.is_empty());
+    assert_eq!(encoded.as_bytes(), b"aGVsbG8=");
+    assert_eq!(encoded.as_str(), "aGVsbG8=");
+    assert_eq!(encoded.as_ref(), b"aGVsbG8=");
+    assert_eq!(
+        format!("{encoded:?}"),
+        "EncodedBuffer { bytes: \"<redacted>\", len: 8, capacity: 8 }"
+    );
+
+    let cloned = encoded.clone();
+    assert_eq!(encoded, cloned);
+
+    let too_small: Result<EncodedBuffer<7>, EncodeError> = STANDARD.encode_buffer(b"hello");
+    assert_eq!(
+        too_small,
+        Err(EncodeError::OutputTooSmall {
+            required: 8,
+            available: 7,
+        })
+    );
+
+    let mut empty = EncodedBuffer::<8>::new();
+    assert!(empty.is_empty());
+    empty.clear_tail();
+    empty.clear();
+    assert_eq!(empty.as_bytes(), b"");
+}
+
+#[test]
+fn profile_stack_encoded_buffer_respects_wrapping_policy() {
+    let encoded = MIME.encode_buffer::<82>(&[0x5a; 58]).unwrap();
+    assert_eq!(&encoded.as_bytes()[76..78], b"\r\n");
+    assert!(MIME.validate(encoded.as_bytes()));
+
+    let bcrypt = BCRYPT.encode_buffer::<4>(&[0xff, 0xff, 0xff]).unwrap();
+    assert_eq!(bcrypt.as_bytes(), b"9999");
+}
+
 #[cfg(feature = "alloc")]
 #[test]
 fn alloc_helpers_round_trip() {