castrum 0.9.2 → 0.9.4

package/rust/crypto/argon2.rs

@@ -0,0 +1,265 @@
+// rust/crypto/argon2.rs — argon2id password hashing.
+//
+// Backend-framework feature: password storage hashing. argon2id is the OWASP
+// recommendation for new hashes; it is deliberately CPU/memory-heavy, which
+// makes it an ideal candidate to offload to Rust (and parallelize with rayon).
+// The `argon2` crate (RustCrypto) is pure Rust; `SaltString::encode_b64` lets us
+// feed a caller-supplied salt so outputs are deterministic (unit-testable).
+//
+// Pure-Rust core (no napi types) stays unit-testable; only the entry points
+// use napi types.
+
+use argon2::password_hash::{PasswordHash, PasswordHasher, PasswordVerifier, SaltString};
+use argon2::{Algorithm, Argon2, Params, Version};
+use napi::bindgen_prelude::*;
+use napi_derive::napi;
+
+// ── Options ────────────────────────────────────────────────────
+
+/// argon2id parameters (defaults follow OWASP: 19 MiB, 2 iterations, 1 lane,
+/// 32-byte output). Callers may lower the memory cost for fast benchmarks.
+#[napi(object)]
+pub struct PasswordHashOptions {
+    /// Memory cost in KiB (m). Default: 19_456 (19 MiB).
+    pub m_cost: Option<u32>,
+    /// Iterations (t). Default: 2.
+    pub t_cost: Option<u32>,
+    /// Parallelism (p). Default: 1.
+    pub p_cost: Option<u32>,
+    /// Output length in bytes. Default: 32.
+    pub out_len: Option<u32>,
+}
+
+fn resolve_opts(o: Option<&PasswordHashOptions>) -> (u32, u32, u32, u32) {
+    match o {
+        Some(o) => (
+            o.m_cost.unwrap_or(19_456),
+            o.t_cost.unwrap_or(2),
+            o.p_cost.unwrap_or(1),
+            o.out_len.unwrap_or(32),
+        ),
+        None => (19_456, 2, 1, 32),
+    }
+}
+
+// ── Pure-Rust core ─────────────────────────────────────────────
+
+/// Hash `password` with argon2id using the given raw salt bytes. Returns the
+/// PHC string (`$argon2id$v=19$m=...,t=...,p=...$<b64 salt>$<b64 hash>`).
+pub fn hash_password(
+    password: &[u8],
+    salt: &[u8],
+    m_cost: u32,
+    t_cost: u32,
+    p_cost: u32,
+    out_len: u32,
+) -> std::result::Result<String, argon2::password_hash::Error> {
+    let params = Params::new(m_cost, t_cost, p_cost, Some(out_len as usize))?;
+    let argon2 = Argon2::new(Algorithm::Argon2id, Version::V0x13, params);
+    let salt = SaltString::encode_b64(salt)?;
+    Ok(argon2.hash_password(password, &salt)?.to_string())
+}
+
+/// Verify a password against a PHC string (constant-time internally).
+pub fn verify_password(password: &[u8], phc: &[u8]) -> bool {
+    let Ok(phc_str) = std::str::from_utf8(phc) else {
+        return false;
+    };
+    let Ok(parsed) = PasswordHash::new(phc_str) else {
+        return false;
+    };
+    Argon2::default().verify_password(password, &parsed).is_ok()
+}
+
+// ── NAPI entry points ──────────────────────────────────────────
+
+/// Hash a password with argon2id. `salt` must be at least 8 bytes; output is a
+/// PHC string. Deterministic given the same inputs.
+#[napi]
+pub fn password_hash(
+    password: Uint8Array,
+    salt: Uint8Array,
+    options: Option<PasswordHashOptions>,
+) -> Result<Buffer> {
+    let (m, t, p, out_len) = resolve_opts(options.as_ref());
+    let phc = hash_password(password.as_ref(), salt.as_ref(), m, t, p, out_len)
+        .map_err(|e| Error::from_reason(format!("argon2 hash failed: {e}")))?;
+    Ok(Buffer::from(phc.into_bytes()))
+}
+
+/// Verify a password against a PHC string. Returns false on any parse failure.
+#[napi]
+pub fn password_verify(password: Uint8Array, phc: Buffer) -> bool {
+    verify_password(password.as_ref(), phc.as_ref())
+}
+
+/// Packed password-verify batch (two packed lists: passwords + PHC strings,
+/// zipped) → bitset of valid. Items with malformed PHC strings yield `false`.
+#[napi]
+pub fn password_verify_batch_packed(passwords: Uint8Array, phcs: Uint8Array) -> Result<Buffer> {
+    use crate::util::packed::PackedIter;
+    let pws = passwords.as_ref();
+    let ph = phcs.as_ref();
+    let count = PackedIter::new(pws)?.len().min(PackedIter::new(ph)?.len());
+    let mut out = Vec::with_capacity(4 + count.div_ceil(8));
+    out.extend_from_slice(&(count as u32).to_le_bytes());
+    out.resize(4 + count.div_ceil(8), 0);
+    for (i, (pw, phc)) in PackedIter::new(pws)?.zip(PackedIter::new(ph)?).enumerate() {
+        if verify_password(pw, phc) {
+            out[4 + (i >> 3)] |= 1 << (i & 7);
+        }
+    }
+    Ok(Buffer::from(out))
+}
+
+/// Higher-order instance: precompiles the argon2id `Params`/`Argon2` once at
+/// construction (fixed m/t/p/out_len), so every `hash` skips the per-call
+/// parameter construction — the CPU/memory cost of the hash itself is
+/// unchanged, only the setup is amortized.
+#[napi]
+pub struct Argon2Hasher {
+    argon2: Argon2<'static>,
+}
+
+#[napi]
+impl Argon2Hasher {
+    #[napi(constructor)]
+    pub fn new(options: Option<PasswordHashOptions>) -> Result<Self> {
+        let (m, t, p, out_len) = resolve_opts(options.as_ref());
+        let params = Params::new(m, t, p, Some(out_len as usize))
+            .map_err(|e| Error::from_reason(format!("invalid argon2 params: {e}")))?;
+        Ok(Self {
+            argon2: Argon2::new(Algorithm::Argon2id, Version::V0x13, params),
+        })
+    }
+
+    /// Hash a password with the precompiled params → PHC string bytes.
+    #[napi]
+    pub fn hash(&self, password: Uint8Array, salt: Uint8Array) -> Result<Buffer> {
+        let salt = SaltString::encode_b64(salt.as_ref())
+            .map_err(|e| Error::from_reason(format!("invalid salt: {e}")))?;
+        let phc = self
+            .argon2
+            .hash_password(password.as_ref(), &salt)
+            .map_err(|e| Error::from_reason(format!("argon2 hash failed: {e}")))?;
+        Ok(Buffer::from(phc.to_string().into_bytes()))
+    }
+
+    /// Verify a password against a PHC string. Returns false on any failure.
+    #[napi]
+    pub fn verify(&self, password: Uint8Array, phc: Buffer) -> bool {
+        verify_password(password.as_ref(), phc.as_ref())
+    }
+}
+
+/// Parallel argon2id batch: packed `[u32 count]{[u32 len][password]}` in →
+/// packed `[u32 count]{[u32 len][phc]}` out, all hashed with the SAME salt.
+#[napi]
+pub fn password_hash_batch_packed(
+    data: Uint8Array,
+    salt: Uint8Array,
+    options: Option<PasswordHashOptions>,
+) -> Result<Buffer> {
+    let (m, t, p, out_len) = resolve_opts(options.as_ref());
+
+    let phc_for = |password: &[u8]| -> Vec<u8> {
+        hash_password(password, salt.as_ref(), m, t, p, out_len)
+            .map(|s| s.into_bytes())
+            .unwrap_or_default()
+    };
+
+    crate::util::run_packed_batch(data.as_ref(), phc_for).map(Buffer::from)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const PASSWORD: &[u8] = b"correct horse battery staple";
+    const SALT: &[u8] = b"0123456789abcdef";
+
+    #[test]
+    fn hash_then_verify_roundtrip() {
+        let phc = hash_password(PASSWORD, SALT, 4096, 2, 1, 32).unwrap();
+        assert!(phc.starts_with("$argon2id$v=19$"));
+        assert!(verify_password(PASSWORD, phc.as_bytes()));
+    }
+
+    #[test]
+    fn argon2_hasher_instance_roundtrips() {
+        // Precompiled-params instance: hash/verify with no per-call Params
+        // construction. Output must match the scalar core for the same params.
+        let hasher = Argon2Hasher::new(Some(PasswordHashOptions {
+            m_cost: Some(4096),
+            t_cost: Some(2),
+            p_cost: Some(1),
+            out_len: Some(32),
+        }))
+        .unwrap();
+
+        let phc = hasher
+            .hash(
+                Uint8Array::new(PASSWORD.to_vec()),
+                Uint8Array::new(SALT.to_vec()),
+            )
+            .unwrap();
+        let phc_str = String::from_utf8(phc.to_vec()).unwrap();
+        assert!(phc_str.starts_with("$argon2id$v=19$"));
+
+        // The instance output matches the scalar core byte-for-byte.
+        let scalar = hash_password(PASSWORD, SALT, 4096, 2, 1, 32).unwrap();
+        assert_eq!(phc_str, scalar);
+
+        // Verify: correct password true, wrong password false.
+        assert!(hasher.verify(
+            Uint8Array::new(PASSWORD.to_vec()),
+            Buffer::from(phc_str.clone().into_bytes())
+        ));
+        assert!(!hasher.verify(
+            Uint8Array::new(b"wrong-password".to_vec()),
+            Buffer::from(phc_str.into_bytes())
+        ));
+
+        // Invalid options → construction error.
+        assert!(Argon2Hasher::new(Some(PasswordHashOptions {
+            m_cost: Some(0),
+            t_cost: Some(2),
+            p_cost: Some(1),
+            out_len: Some(32),
+        }))
+        .is_err());
+    }
+
+    #[test]
+    fn verify_rejects_wrong_password() {
+        let phc = hash_password(PASSWORD, SALT, 4096, 2, 1, 32).unwrap();
+        assert!(!verify_password(b"wrong password", phc.as_bytes()));
+    }
+
+    #[test]
+    fn verify_is_deterministic_given_salt() {
+        let a = hash_password(PASSWORD, SALT, 4096, 2, 1, 32).unwrap();
+        let b = hash_password(PASSWORD, SALT, 4096, 2, 1, 32).unwrap();
+        assert_eq!(a, b);
+    }
+
+    #[test]
+    fn different_salt_different_hash() {
+        let a = hash_password(PASSWORD, b"aaaaaaaaaaaaaaaa", 4096, 2, 1, 32).unwrap();
+        let b = hash_password(PASSWORD, b"bbbbbbbbbbbbbbbb", 4096, 2, 1, 32).unwrap();
+        assert_ne!(a, b);
+    }
+
+    #[test]
+    fn verify_rejects_garbage() {
+        assert!(!verify_password(PASSWORD, b"not-a-phc-string"));
+        assert!(!verify_password(PASSWORD, b""));
+    }
+
+    #[test]
+    fn params_validation() {
+        assert!(hash_password(PASSWORD, SALT, 0, 2, 1, 32).is_err());
+        // Salt too short (argon2 requires >= 8 bytes).
+        assert!(hash_password(PASSWORD, b"123", 4096, 2, 1, 32).is_err());
+    }
+}

package/rust/crypto/base64.rs

@@ -0,0 +1,420 @@
+// rust/crypto/base64.rs — base64 (standard/url-safe) + hex encode/decode.
+//
+// Uses the `base64` crate engines (Cargo dep already present). The
+// `Base64Codec` higher-order instance precompiles the alphabet/decoding
+// configuration once in its constructor and reuses it across calls.
+
+use napi::bindgen_prelude::*;
+use napi_derive::napi;
+
+use crate::util::bytes::{hex_val, HEX_LOWER};
+use base64::Engine as _;
+
+fn engine(url_safe: bool, padding: bool) -> base64::engine::general_purpose::GeneralPurpose {
+    use base64::engine::general_purpose::*;
+    match (url_safe, padding) {
+        (false, true) => STANDARD,
+        (false, false) => STANDARD_NO_PAD,
+        (true, true) => URL_SAFE,
+        (true, false) => URL_SAFE_NO_PAD,
+    }
+}
+
+#[napi]
+pub fn base64_encode(input: Uint8Array, url_safe: Option<bool>, padding: Option<bool>) -> Buffer {
+    let out = engine(url_safe.unwrap_or(false), padding.unwrap_or(true)).encode(input.as_ref());
+    Buffer::from(out.into_bytes())
+}
+
+#[napi]
+pub fn base64_decode(
+    input: Uint8Array,
+    url_safe: Option<bool>,
+    padding: Option<bool>,
+) -> Result<Buffer> {
+    engine(url_safe.unwrap_or(false), padding.unwrap_or(true))
+        .decode(input.as_ref())
+        .map(Buffer::from)
+        .map_err(|e| Error::from_reason(e.to_string()))
+}
+
+#[napi]
+pub fn base64url_encode(input: Uint8Array) -> Buffer {
+    Buffer::from(
+        base64::engine::general_purpose::URL_SAFE_NO_PAD
+            .encode(input.as_ref())
+            .into_bytes(),
+    )
+}
+
+#[napi]
+pub fn base64url_decode(input: Uint8Array) -> Result<Buffer> {
+    base64::engine::general_purpose::URL_SAFE_NO_PAD
+        .decode(input.as_ref())
+        .map(Buffer::from)
+        .map_err(|e| Error::from_reason(e.to_string()))
+}
+
+/// Base64-encode to raw bytes (no Buffer wrapping). Shared by the scalar and
+/// packed-batch paths.
+pub fn base64_encode_bytes(input: &[u8], url_safe: bool, padding: bool) -> Vec<u8> {
+    engine(url_safe, padding).encode(input).into_bytes()
+}
+
+/// Base64-decode from raw bytes. Errors on invalid input. Shared by the scalar
+/// and packed-batch paths.
+pub fn base64_decode_bytes(input: &[u8], url_safe: bool, padding: bool) -> Result<Vec<u8>> {
+    engine(url_safe, padding)
+        .decode(input)
+        .map_err(|e| Error::from_reason(e.to_string()))
+}
+
+/// Base64url (RFC 7515 §2 — URL-safe alphabet, NO padding) encode to raw
+/// bytes. The single shared source of truth for JWT segment encoding
+/// (`crate::crypto::jwt`) and Ed25519 keypair serialization
+/// (`crate::crypto::ed25519`) — keeps the url-safe alphabet defined in exactly
+/// one place.
+#[inline]
+pub fn base64url_encode_bytes(data: &[u8]) -> Vec<u8> {
+    base64::engine::general_purpose::URL_SAFE_NO_PAD
+        .encode(data)
+        .into_bytes()
+}
+
+/// Base64url (RFC 7515 §2 — URL-safe alphabet, NO padding) decode from raw
+/// bytes. Returns `None` on invalid UTF-8 or non-base64url input.
+#[inline]
+pub fn base64url_decode_bytes(data: &[u8]) -> Option<Vec<u8>> {
+    let text = std::str::from_utf8(data).ok()?;
+    base64::engine::general_purpose::URL_SAFE_NO_PAD
+        .decode(text)
+        .ok()
+}
+
+// ── hex ──────────────────────────────────────────────────────────
+
+/// Encode bytes as lowercase hex (uses the shared `HEX_LOWER` table — direct
+/// byte writes, no per-nibble `char` push).
+///
+/// # Safety
+///
+/// Hex output is always ASCII (`HEX_LOWER` is a byte string of `0-9a-f`), so
+/// the built `Vec<u8>` is valid UTF-8 by construction; `from_utf8_unchecked`
+/// skips a redundant validation pass on the allocating hot path.
+pub fn hex_encode_bytes(input: &[u8]) -> String {
+    let mut out = Vec::with_capacity(input.len() * 2);
+    for &b in input {
+        out.push(HEX_LOWER[(b >> 4) as usize]);
+        out.push(HEX_LOWER[(b & 0x0f) as usize]);
+    }
+    // SAFETY: every byte pushed is an ASCII hex digit from `HEX_LOWER`.
+    unsafe { String::from_utf8_unchecked(out) }
+}
+
+/// Decode lowercase/uppercase hex to bytes.
+pub fn hex_decode_bytes(input: &[u8]) -> std::result::Result<Vec<u8>, &'static str> {
+    if !input.len().is_multiple_of(2) {
+        return Err("odd hex length");
+    }
+    let mut out = Vec::with_capacity(input.len() / 2);
+    for i in (0..input.len()).step_by(2) {
+        let hi = hex_val(input[i]).ok_or("invalid hex digit")?;
+        let lo = hex_val(input[i + 1]).ok_or("invalid hex digit")?;
+        out.push((hi << 4) | lo);
+    }
+    Ok(out)
+}
+
+#[napi]
+pub fn hex_encode(input: Uint8Array) -> Buffer {
+    Buffer::from(hex_encode_bytes(input.as_ref()).into_bytes())
+}
+
+#[napi]
+pub fn hex_decode(input: Uint8Array) -> Result<Buffer> {
+    hex_decode_bytes(input.as_ref())
+        .map(Buffer::from)
+        .map_err(|e| Error::from_reason(e.to_string()))
+}
+
+// ── Reusable-output (_into) variants ────────────────────────────
+//
+// These write into a caller-provided output buffer and return the number of
+// bytes written (u32), so hot loops can pool the buffer instead of allocating
+// a fresh Vec + napi Buffer per call. They error on a buffer that is too small;
+// input/output overlap is handled by `crate::util::run_packed_into`.
+
+/// Lowercase-hex encode directly into `out`. Returns bytes written
+/// (`input.len() * 2`). Errors if `out` is too small.
+#[inline]
+pub fn hex_encode_into_slice(input: &[u8], out: &mut [u8]) -> Result<usize> {
+    let needed = input
+        .len()
+        .checked_mul(2)
+        .ok_or_else(|| Error::from_reason("hex encode: input too large (length overflow)"))?;
+    if out.len() < needed {
+        return Err(Error::from_reason("hex encode: output buffer too small"));
+    }
+    let mut pos = 0usize;
+    for &b in input {
+        out[pos] = HEX_LOWER[(b >> 4) as usize];
+        out[pos + 1] = HEX_LOWER[(b & 0x0f) as usize];
+        pos += 2;
+    }
+    Ok(pos)
+}
+
+#[napi]
+pub fn hex_encode_into(input: Uint8Array, mut output: Uint8Array) -> Result<u32> {
+    crate::util::run_packed_into(&input, &mut output, hex_encode_into_slice)
+}
+
+/// Hex-decode directly into `out`. Returns bytes written (`input.len() / 2`).
+/// Errors on odd length, invalid digits, or an output buffer that is too small.
+#[inline]
+pub fn hex_decode_into_slice(input: &[u8], out: &mut [u8]) -> Result<usize> {
+    if !input.len().is_multiple_of(2) {
+        return Err(Error::from_reason("odd hex length"));
+    }
+    let needed = input.len() / 2;
+    if out.len() < needed {
+        return Err(Error::from_reason("hex decode: output buffer too small"));
+    }
+    let mut pos = 0usize;
+    for i in (0..input.len()).step_by(2) {
+        let hi = hex_val(input[i]).ok_or_else(|| Error::from_reason("invalid hex digit"))?;
+        let lo = hex_val(input[i + 1]).ok_or_else(|| Error::from_reason("invalid hex digit"))?;
+        out[pos] = (hi << 4) | lo;
+        pos += 1;
+    }
+    Ok(pos)
+}
+
+#[napi]
+pub fn hex_decode_into(input: Uint8Array, mut output: Uint8Array) -> Result<u32> {
+    crate::util::run_packed_into(&input, &mut output, hex_decode_into_slice)
+}
+
+/// Pure core: base64-encode `input` into `out` (zero-alloc `encode_slice`).
+/// Returns bytes written; errors if `out` is too small. Shared by the `_into`
+/// napi path and the pure-core unit tests.
+pub fn base64_encode_into_slice(
+    input: &[u8],
+    out: &mut [u8],
+    url_safe: bool,
+    padding: bool,
+) -> Result<usize> {
+    engine(url_safe, padding)
+        .encode_slice(input, out)
+        .map_err(|e| Error::from_reason(format!("base64 encode: {e}")))
+}
+
+/// Base64-encode into a caller-provided output buffer (zero-alloc via
+/// `Engine::encode_slice`). Returns bytes written; errors if `output` is too
+/// small.
+#[napi]
+pub fn base64_encode_into(
+    input: Uint8Array,
+    mut output: Uint8Array,
+    url_safe: Option<bool>,
+    padding: Option<bool>,
+) -> Result<u32> {
+    crate::util::run_packed_into(&input, &mut output, move |inp, out| {
+        base64_encode_into_slice(inp, out, url_safe.unwrap_or(false), padding.unwrap_or(true))
+    })
+}
+
+/// Pure core: base64-decode `input` into `out` (zero-alloc `decode_slice`).
+/// Returns bytes written; errors on invalid input or a too-small output
+/// buffer. Shared by the `_into` napi path and the pure-core unit tests.
+pub fn base64_decode_into_slice(
+    input: &[u8],
+    out: &mut [u8],
+    url_safe: bool,
+    padding: bool,
+) -> Result<usize> {
+    engine(url_safe, padding)
+        .decode_slice(input, out)
+        .map_err(|e| Error::from_reason(format!("base64 decode: {e}")))
+}
+
+/// Base64-decode into a caller-provided output buffer (zero-alloc via
+/// `Engine::decode_slice`). Returns bytes written; errors on invalid input or
+/// an output buffer that is too small.
+#[napi]
+pub fn base64_decode_into(
+    input: Uint8Array,
+    mut output: Uint8Array,
+    url_safe: Option<bool>,
+    padding: Option<bool>,
+) -> Result<u32> {
+    crate::util::run_packed_into(&input, &mut output, move |inp, out| {
+        base64_decode_into_slice(inp, out, url_safe.unwrap_or(false), padding.unwrap_or(true))
+    })
+}
+
+/// Higher-order instance: the alphabet/padding engine is selected ONCE at
+/// construction and stored concretely, so `encode`/`decode` never re-run the
+/// 4-way engine match on the per-call path.
+#[napi]
+pub struct Base64Codec {
+    engine: base64::engine::general_purpose::GeneralPurpose,
+}
+
+#[napi]
+impl Base64Codec {
+    #[napi(constructor)]
+    pub fn new(url_safe: Option<bool>, padding: Option<bool>) -> Self {
+        Self {
+            engine: engine(url_safe.unwrap_or(false), padding.unwrap_or(true)),
+        }
+    }
+
+    #[napi]
+    pub fn encode(&self, input: Uint8Array) -> Buffer {
+        Buffer::from(self.engine.encode(input.as_ref()).into_bytes())
+    }
+
+    #[napi]
+    pub fn decode(&self, input: Uint8Array) -> Result<Buffer> {
+        self.engine
+            .decode(input.as_ref())
+            .map(Buffer::from)
+            .map_err(|e| Error::from_reason(e.to_string()))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn base64_roundtrip_standard() {
+        let data = b"hello world!";
+        let enc = base64::engine::general_purpose::STANDARD.encode(data);
+        assert_eq!(
+            base64_decode(Uint8Array::new(enc.into_bytes()), None, None)
+                .unwrap()
+                .as_ref(),
+            data
+        );
+    }
+
+    #[test]
+    fn base64url_no_padding() {
+        // 0xfb → 111110 11 → "-w" (url-safe, no padding)
+        let enc = base64::engine::general_purpose::URL_SAFE_NO_PAD.encode([0xfb]);
+        assert_eq!(enc, "-w");
+        let dec = base64url_decode(Uint8Array::new(enc.into_bytes())).unwrap();
+        assert_eq!(dec.as_ref(), [0xfb]);
+    }
+
+    #[test]
+    fn base64_decode_rejects_invalid() {
+        assert!(base64_decode(Uint8Array::new(b"!!!".to_vec()), None, None).is_err());
+    }
+
+    #[test]
+    fn hex_roundtrip() {
+        let data = b"\x00\x01\xfe\xffAB";
+        let enc = hex_encode_bytes(data);
+        assert_eq!(enc, "0001feff4142");
+        assert_eq!(hex_decode_bytes(enc.as_bytes()).unwrap(), data);
+    }
+
+    #[test]
+    fn hex_rejects_odd_and_bad() {
+        assert!(hex_decode_bytes(b"abc").is_err());
+        assert!(hex_decode_bytes(b"zz").is_err());
+    }
+
+    #[test]
+    fn codec_instance_encodes_urlsafe() {
+        let c = Base64Codec::new(Some(true), Some(false));
+        let enc = c.encode(Uint8Array::new(b"\xfb".to_vec()));
+        assert_eq!(enc.as_ref(), b"-w");
+    }
+
+    // ── reusable-output (_into) variants ──
+
+    #[test]
+    fn hex_encode_into_slice_matches_allocating() {
+        let data = b"\x00\x01\xfe\xffAB";
+        let expected = hex_encode_bytes(data);
+        let mut out = [0u8; 32];
+        let n = hex_encode_into_slice(data, &mut out).unwrap();
+        assert_eq!(n, expected.len());
+        assert_eq!(&out[..n], expected.as_bytes());
+    }
+
+    #[test]
+    fn hex_encode_into_reports_length() {
+        let data = b"hello";
+        let out = Uint8Array::new(vec![0u8; 16]);
+        let n = hex_encode_into(Uint8Array::new(data.to_vec()), out).unwrap();
+        assert_eq!(n as usize, data.len() * 2);
+    }
+
+    #[test]
+    fn hex_encode_into_small_buffer_errors() {
+        let mut out = [0u8; 2];
+        assert!(hex_encode_into_slice(b"abc", &mut out).is_err());
+        let out2 = Uint8Array::new(vec![0u8; 4]);
+        assert!(hex_encode_into(Uint8Array::new(b"abcdef".to_vec()), out2).is_err());
+    }
+
+    #[test]
+    fn hex_decode_into_roundtrips() {
+        let enc = hex_encode_bytes(b"\x00\x01\xfe\xffAB");
+        let mut out = [0u8; 16];
+        let n = hex_decode_into_slice(enc.as_bytes(), &mut out).unwrap();
+        assert_eq!(&out[..n], b"\x00\x01\xfe\xffAB");
+    }
+
+    #[test]
+    fn hex_decode_into_rejects_bad_input() {
+        let mut out = [0u8; 4];
+        assert!(hex_decode_into_slice(b"abc", &mut out).is_err());
+        assert!(hex_decode_into_slice(b"zz", &mut out).is_err());
+    }
+
+    #[test]
+    fn hex_decode_into_small_buffer_errors() {
+        let mut out = [0u8; 2];
+        assert!(hex_decode_into_slice(b"0001020304", &mut out).is_err());
+    }
+
+    #[test]
+    fn base64_encode_into_reports_length() {
+        let data = b"hello world!";
+        let out = Uint8Array::new(vec![0u8; 64]);
+        let n = base64_encode_into(Uint8Array::new(data.to_vec()), out, None, None).unwrap();
+        assert_eq!(
+            n as usize,
+            base64::engine::general_purpose::STANDARD.encode(data).len()
+        );
+    }
+
+    #[test]
+    fn base64_encode_into_small_buffer_errors() {
+        let out = Uint8Array::new(vec![0u8; 4]);
+        assert!(
+            base64_encode_into(Uint8Array::new(b"hello world!".to_vec()), out, None, None).is_err()
+        );
+    }
+
+    #[test]
+    fn base64_decode_into_roundtrips() {
+        let data = b"hello world!";
+        let enc = base64::engine::general_purpose::STANDARD.encode(data);
+        let out = Uint8Array::new(vec![0u8; 32]);
+        let n = base64_decode_into(Uint8Array::new(enc.into_bytes()), out, None, None).unwrap();
+        assert_eq!(n as usize, data.len());
+    }
+
+    #[test]
+    fn base64_decode_into_rejects_invalid() {
+        let out = Uint8Array::new(vec![0u8; 32]);
+        assert!(base64_decode_into(Uint8Array::new(b"!!!".to_vec()), out, None, None).is_err());
+    }
+}