castrum 0.9.3 → 0.9.6

package/rust/crypto/jwt/token.rs

@@ -0,0 +1,360 @@
+// rust/crypto/jwt/token.rs — HS256/EdDSA JWT token core (assembly + verification).
+//
+// Backend-framework feature: JWTs for auth. We implement HS256 by hand on top
+// of the existing aws-lc-rs HMAC + base64 crates (no `jsonwebtoken` dep) to
+// keep the dependency tree small and match this crate's byte-machinery style.
+// RS256 (RSA via aws-lc-rs) can be layered on later.
+//
+// This is the pure token machinery: header constants, base64url (shared via
+// `crate::crypto::base64`), HMAC-SHA256, split/build/verify, zero-DOM
+// time-claim checks, and `iat`/`exp` injection. It is reused by the napi entry
+// points (`napi.rs`), the C-ABI fast paths in `rust/ffi.rs`, and
+// `crate::crypto::ed25519` keypair serialization. Only the
+// `inject_and_payload_b64*` helpers touch napi types (`napi::Result`), because
+// `rust/ffi.rs` reuses them; everything else is napi-free and unit-testable.
+
+use memchr::memchr;
+use napi::{Error, Result};
+use sonic_rs::{JsonValueMutTrait, JsonValueTrait};
+use std::sync::OnceLock;
+
+use crate::crypto::base64::{base64url_decode_bytes, base64url_encode_bytes};
+
+/// Clock-skew tolerance (seconds) for the `iat` claim in `jwt_verify`.
+const CLOCK_SKEW_LEEWAY_SECS: i64 = 60;
+
+/// The canonical HS256 JWT header (`{"alg":"HS256","typ":"JWT"}`), serialized
+/// and base64url-encoded ONCE (lazily). `JwtSigner::sign`, the scalar
+/// `jwt_sign` and the batch sign all reuse it instead of rebuilding +
+/// re-serializing the constant header on every call.
+static JWT_HEADER_B64: OnceLock<Vec<u8>> = OnceLock::new();
+
+pub fn jwt_header_b64() -> &'static [u8] {
+    JWT_HEADER_B64.get_or_init(|| {
+        let header = serde_json::json!({ "alg": "HS256", "typ": "JWT" });
+        base64url_encode_bytes(
+            &serde_json::to_vec(&header).expect("constant JWT header serializes"),
+        )
+    })
+}
+
+/// The canonical EdDSA (Ed25519) JWT header (`{"alg":"EdDSA","typ":"JWT"}`),
+/// serialized + base64url-encoded ONCE (lazily) — twin of `jwt_header_b64`.
+static EDDSA_HEADER_B64: OnceLock<Vec<u8>> = OnceLock::new();
+
+pub fn eddsa_header_b64() -> &'static [u8] {
+    EDDSA_HEADER_B64.get_or_init(|| {
+        let header = serde_json::json!({ "alg": "EdDSA", "typ": "JWT" });
+        base64url_encode_bytes(
+            &serde_json::to_vec(&header).expect("constant JWT header serializes"),
+        )
+    })
+}
+
+// ── HMAC-SHA256 (aws-lc-rs) ────────────────────────────────────
+
+/// HMAC-SHA256 with a PRE-COMPILED key — avoids re-deriving the key on every
+/// call (the win the `JwtSigner`/`HmacSigner` instances exploit).
+pub fn hmac_sha256_with_key(key: &aws_lc_rs::hmac::Key, data: &[u8]) -> [u8; 32] {
+    let tag = aws_lc_rs::hmac::sign(key, data);
+    let mut out = [0u8; 32];
+    out.copy_from_slice(tag.as_ref());
+    out
+}
+
+// ── Token assembly / splitting ─────────────────────────────────
+
+pub struct TokenParts<'a> {
+    pub header_b64: &'a [u8],
+    pub payload_b64: &'a [u8],
+    pub sig_b64: &'a [u8],
+}
+
+/// Split a compact JWT into its three dot-separated segments.
+pub fn split_token(token: &[u8]) -> Option<TokenParts<'_>> {
+    let first = memchr(b'.', token)?;
+    let header_b64 = &token[..first];
+    let rest = &token[first + 1..];
+    let second = memchr(b'.', rest)?;
+    let payload_b64 = &rest[..second];
+    let sig_b64 = &rest[second + 1..];
+    if memchr(b'.', sig_b64).is_some() {
+        return None;
+    }
+    Some(TokenParts {
+        header_b64,
+        payload_b64,
+        sig_b64,
+    })
+}
+
+/// Build a full HS256 token from base64url-encoded header + payload segments.
+pub fn build_token(header_b64: &[u8], payload_b64: &[u8], secret: &[u8]) -> Vec<u8> {
+    let key = aws_lc_rs::hmac::Key::new(aws_lc_rs::hmac::HMAC_SHA256, secret);
+    build_token_with_key(header_b64, payload_b64, &key)
+}
+
+/// Build a token with a PRE-COMPILED key (per-call key derivation removed).
+pub fn build_token_with_key(
+    header_b64: &[u8],
+    payload_b64: &[u8],
+    key: &aws_lc_rs::hmac::Key,
+) -> Vec<u8> {
+    let mut signing_input = Vec::with_capacity(header_b64.len() + 1 + payload_b64.len());
+    signing_input.extend_from_slice(header_b64);
+    signing_input.push(b'.');
+    signing_input.extend_from_slice(payload_b64);
+
+    let sig = hmac_sha256_with_key(key, &signing_input);
+    let sig_b64 = base64url_encode_bytes(&sig);
+
+    signing_input.push(b'.');
+    signing_input.extend_from_slice(&sig_b64);
+    signing_input
+}
+
+/// Constant-time byte comparison (no early exit on length mismatch beyond the
+/// required guard — lengths differ → false).
+fn ct_eq(a: &[u8], b: &[u8]) -> bool {
+    if a.len() != b.len() {
+        return false;
+    }
+    let mut diff = 0u8;
+    for (x, y) in a.iter().zip(b.iter()) {
+        diff |= x ^ y;
+    }
+    diff == 0
+}
+
+/// Verify an HS256 signature (constant-time). Does NOT check claims/expiry.
+///
+/// Test-only convenience over the fresh-key derivation: production code uses
+/// `verify_signature_with_key` with a precompiled key.
+#[cfg(test)]
+pub fn verify_signature(token: &[u8], secret: &[u8]) -> bool {
+    let key = aws_lc_rs::hmac::Key::new(aws_lc_rs::hmac::HMAC_SHA256, secret);
+    verify_signature_with_key(token, &key)
+}
+
+/// Verify an HS256 signature (constant-time) with a PRE-COMPILED key.
+pub fn verify_signature_with_key(token: &[u8], key: &aws_lc_rs::hmac::Key) -> bool {
+    let Some(parts) = split_token(token) else {
+        return false;
+    };
+
+    let mut signing_input =
+        Vec::with_capacity(parts.header_b64.len() + 1 + parts.payload_b64.len());
+    signing_input.extend_from_slice(parts.header_b64);
+    signing_input.push(b'.');
+    signing_input.extend_from_slice(parts.payload_b64);
+
+    let sig = hmac_sha256_with_key(key, &signing_input);
+
+    match base64url_decode_bytes(parts.sig_b64) {
+        Some(provided) => ct_eq(&sig, &provided),
+        None => false,
+    }
+}
+
+// ── Claim injection (iat/exp) ──────────────────────────────────
+
+/// Inject `iat`/`exp` into object claims when `ttl_seconds` is set, then
+/// serialize + base64url-encode the payload. Shared by the scalar, instance,
+/// and byte-JSON sign paths so the injection semantics can't drift.
+pub fn inject_and_payload_b64(
+    claims: &mut serde_json::Value,
+    ttl_seconds: Option<i64>,
+    now_seconds: i64,
+) -> Result<Vec<u8>> {
+    if let Some(obj) = claims.as_object_mut() {
+        if let Some(ttl) = ttl_seconds {
+            if ttl > 0 {
+                obj.entry("iat")
+                    .or_insert_with(|| serde_json::json!(now_seconds));
+                obj.entry("exp")
+                    .or_insert_with(|| serde_json::json!(now_seconds + ttl));
+            }
+        }
+    }
+    Ok(base64url_encode_bytes(
+        &serde_json::to_vec(claims).map_err(napi_err)?,
+    ))
+}
+
+/// Inject `iat`/`exp` into a sonic object when `ttl_seconds` is set (unless
+/// already present) — shared by the sonic byte-sign paths.
+pub(crate) fn inject_ttl_claims(
+    claims: &mut sonic_rs::Value,
+    ttl_seconds: Option<i64>,
+    now_seconds: i64,
+) {
+    if let Some(ttl) = ttl_seconds {
+        if ttl > 0 {
+            if let Some(obj) = claims.as_object_mut() {
+                if obj.get(&"iat").is_none() {
+                    obj.insert("iat", now_seconds);
+                }
+                if obj.get(&"exp").is_none() {
+                    obj.insert("exp", now_seconds + ttl);
+                }
+            }
+        }
+    }
+}
+
+/// Sonic twin of [`inject_and_payload_b64`] for the pre-serialized-claim-byte
+/// sign paths (no `serde_json::Value` DOM): parse the claims once into a
+/// compact `sonic_rs::Value`, inject `iat`/`exp`, serialize + base64url.
+pub fn inject_and_payload_b64_sonic(
+    claims: &mut sonic_rs::Value,
+    ttl_seconds: Option<i64>,
+    now_seconds: i64,
+) -> Result<Vec<u8>> {
+    inject_ttl_claims(claims, ttl_seconds, now_seconds);
+    Ok(base64url_encode_bytes(
+        &sonic_rs::to_vec(claims).map_err(napi_err)?,
+    ))
+}
+
+fn napi_err(e: impl std::fmt::Display) -> Error {
+    Error::from_reason(e.to_string())
+}
+
+// ── Verification ───────────────────────────────────────────────
+
+/// Pure-core JWT verification: HS256 signature + `alg` allowlist + time claims
+/// (`exp`/`nbf`/`iat`). Returns the decoded payload BYTES (valid JSON claims),
+/// or `None` on any failure — no `serde_json::Value` DOM and no re-serialize.
+pub fn verify_token(token: &[u8], secret: &[u8], now_seconds: i64) -> Option<Vec<u8>> {
+    let key = aws_lc_rs::hmac::Key::new(aws_lc_rs::hmac::HMAC_SHA256, secret);
+    verify_token_with_key(token, &key, now_seconds)
+}
+
+/// Zero-DOM time-claim checks over a base64url payload segment: `exp`
+/// (reject when `now >= exp`), `nbf` (reject when not yet valid), `iat`
+/// (reject tokens issued beyond the clock-skew leeway). Returns the decoded
+/// payload bytes (valid JSON claims) or `None`. Shared by the HS256 and
+/// EdDSA verify paths so the claim semantics can't drift.
+pub(crate) fn verify_time_claims(payload_b64: &[u8], now_seconds: i64) -> Option<Vec<u8>> {
+    let payload = base64url_decode_bytes(payload_b64)?;
+    let value: sonic_rs::Value = sonic_rs::from_slice(&payload).ok()?;
+
+    // `exp`: reject when now >= exp.
+    if let Some(exp) = value.get("exp").and_then(|v| v.as_i64()) {
+        if now_seconds >= exp {
+            return None;
+        }
+    }
+
+    // `nbf` (not before): reject when the token is not yet valid.
+    if let Some(nbf) = value.get("nbf").and_then(|v| v.as_i64()) {
+        if now_seconds < nbf {
+            return None;
+        }
+    }
+
+    // `iat` (issued at): reject tokens issued in the future beyond a small
+    // clock-skew leeway.
+    if let Some(iat) = value.get("iat").and_then(|v| v.as_i64()) {
+        if now_seconds < iat.saturating_sub(CLOCK_SKEW_LEEWAY_SECS) {
+            return None;
+        }
+    }
+
+    Some(payload)
+}
+
+/// Verify with a PRE-COMPILED key (no per-call key derivation). Time-claim
+/// checks run over a compact `sonic_rs::Value` (zero per-key heap `String`);
+/// the decoded payload bytes are returned verbatim.
+pub fn verify_token_with_key(
+    token: &[u8],
+    key: &aws_lc_rs::hmac::Key,
+    now_seconds: i64,
+) -> Option<Vec<u8>> {
+    if !verify_signature_with_key(token, key) {
+        return None;
+    }
+
+    let parts = split_token(token)?;
+
+    // ── Header: enforce the alg allowlist (prevents alg-confusion) ──
+    // Fast path: the canonical HS256 header matches — accept without parsing
+    // the header into a DOM. Otherwise fall back to the full parse (which
+    // accepts alternative key order / extra header fields), so behavior is
+    // identical to the previous always-parse path.
+    if parts.header_b64 != jwt_header_b64() {
+        let header: sonic_rs::Value =
+            sonic_rs::from_slice(&base64url_decode_bytes(parts.header_b64)?).ok()?;
+        if header.get("alg").and_then(|v| v.as_str()) != Some("HS256") {
+            return None;
+        }
+    }
+
+    // ── Payload: decode once; zero-DOM time-claim checks (shared) ──
+    verify_time_claims(parts.payload_b64, now_seconds)
+}
+
+// ── EdDSA (Ed25519) ────────────────────────────────────────────
+
+/// Sign an EdDSA (Ed25519) JWT from pre-serialized claim JSON bytes. Claims
+/// parsing/`iat`/`exp` injection is shared with the HS256 byte path; only the
+/// signature primitive differs. Returns the compact token bytes, or `None` on
+/// invalid claims JSON / invalid private key.
+pub fn sign_eddsa(
+    claims_json: &[u8],
+    private_der: &[u8],
+    ttl_seconds: Option<i64>,
+    now_seconds: i64,
+) -> Option<Vec<u8>> {
+    let mut claims: sonic_rs::Value = sonic_rs::from_slice(claims_json).ok()?;
+    let payload_b64 = inject_and_payload_b64_sonic(&mut claims, ttl_seconds, now_seconds).ok()?;
+    build_eddsa_token(eddsa_header_b64(), &payload_b64, private_der)
+}
+
+/// Assemble an EdDSA token from base64url header + payload segments: sign
+/// `header.payload` with the Ed25519 private key, append the base64url sig.
+pub fn build_eddsa_token(
+    header_b64: &[u8],
+    payload_b64: &[u8],
+    private_der: &[u8],
+) -> Option<Vec<u8>> {
+    let mut signing_input = Vec::with_capacity(header_b64.len() + 1 + payload_b64.len());
+    signing_input.extend_from_slice(header_b64);
+    signing_input.push(b'.');
+    signing_input.extend_from_slice(payload_b64);
+    let sig = crate::crypto::ed25519::sign(private_der, &signing_input)?;
+    signing_input.push(b'.');
+    signing_input.extend_from_slice(&base64url_encode_bytes(&sig));
+    Some(signing_input)
+}
+
+/// Verify an EdDSA (Ed25519) JWT: signature + `alg` allowlist + time claims
+/// (shared with the HS256 path). Returns the decoded payload bytes (valid JSON
+/// claims), or `None` on any failure.
+pub fn verify_token_eddsa(token: &[u8], public_der: &[u8], now_seconds: i64) -> Option<Vec<u8>> {
+    let parts = split_token(token)?;
+
+    // ── Header: enforce the alg allowlist (prevents alg-confusion) ──
+    // Fast path: the canonical EdDSA header matches — accept without parsing.
+    if parts.header_b64 != eddsa_header_b64() {
+        let header: sonic_rs::Value =
+            sonic_rs::from_slice(&base64url_decode_bytes(parts.header_b64)?).ok()?;
+        if header.get("alg").and_then(|v| v.as_str()) != Some("EdDSA") {
+            return None;
+        }
+    }
+
+    // ── Signature: constant-time Ed25519 verify over `header.payload` ──
+    let sig = base64url_decode_bytes(parts.sig_b64)?;
+    let mut signing_input =
+        Vec::with_capacity(parts.header_b64.len() + 1 + parts.payload_b64.len());
+    signing_input.extend_from_slice(parts.header_b64);
+    signing_input.push(b'.');
+    signing_input.extend_from_slice(parts.payload_b64);
+    if !crate::crypto::ed25519::verify(public_der, &signing_input, &sig) {
+        return None;
+    }
+
+    verify_time_claims(parts.payload_b64, now_seconds)
+}

package/rust/crypto/mod.rs

@@ -0,0 +1,27 @@
+//! Auth & hashing (pure-Rust primitives + compiled-once napi instances).
+//
+// Pure-Rust crypto primitives + compiled-once napi instances (each instance
+// precompiles its key/engine/params once at construction):
+//   - hmac_sha256.rs   HMAC-SHA256 (+ HmacSigner instance)
+//   - cookie_sign.rs   signed cookies `value.signature` (CookieSigner)
+//   - csrf.rs          CSRF tokens, random hex + HMAC (CsrfProtector)
+//   - jwt/             hand-rolled HS256 + EdDSA JWT (token.rs / napi.rs)
+//   - aead.rs          AES-256-GCM / chacha20-poly1305 (AeadCipher) + batch
+//   - argon2.rs        argon2id password hashing (Argon2Hasher) + batch//!   - bcrypt.rs        bcrypt password hashing (PHC `$2b$`) + verify
+//!   - pbkdf2.rs        PBKDF2-HMAC-SHA256 key derivation//   - base64.rs        base64/base64url/hex codecs (Base64Codec)
+//   - hashing.rs       FNV-1a / XXH3 / crc32 checksums
+//   - random_token.rs  random hex tokens
+
+pub mod aead;
+pub mod argon2;
+pub mod base64;
+pub mod bcrypt;
+pub mod cookie_sign;
+pub mod csrf;
+pub mod ed25519;
+pub mod hashing;
+pub mod hmac_sha256;
+pub mod jwt;
+pub mod pbkdf2;
+pub mod random_token;
+pub mod session;

package/rust/crypto/pbkdf2.rs

@@ -0,0 +1,105 @@
+// rust/crypto/pbkdf2.rs — PBKDF2-HMAC-SHA256 key derivation.
+//
+// Pure-Rust (RustCrypto pbkdf2 + sha2). Standard NIST 800-132 KDF, exposed as
+// a NAPI scalar. Bun has no synchronous PBKDF2 built-in (crypto.subtle.deriveBits
+// is async), so this fills a real gap — the honest baseline is node:crypto's
+// pbkdf2Sync, and @flux/native can prefer Bun's async path where a caller wants
+// it. Output length is caller-chosen (default 32 bytes).
+
+use napi::bindgen_prelude::*;
+use napi_derive::napi;
+
+use pbkdf2::pbkdf2_hmac;
+use sha2::Sha256;
+
+/// Minimum output length (1 byte) / maximum sanity cap (1 MiB).
+pub const PBKDF2_MIN_LEN: u32 = 1;
+/// Cap derived-key length so a hostile caller can't request a huge allocation.
+pub const PBKDF2_MAX_LEN: u32 = 1024 * 1024;
+
+/// Pure core (no napi types) for [`pbkdf2_sha256`] and the off-thread task
+/// runtime: derive `dk_len` bytes, clamping the length to the documented range.
+pub fn pbkdf2_sha256_into(password: &[u8], salt: &[u8], rounds: u32, dk_len: u32) -> Vec<u8> {
+    let dk_len = dk_len.clamp(PBKDF2_MIN_LEN, PBKDF2_MAX_LEN) as usize;
+    let mut out = vec![0u8; dk_len];
+    pbkdf2_hmac::<Sha256>(password, salt, rounds.max(1), &mut out);
+    out
+}
+
+/// Derive a PBKDF2-HMAC-SHA256 key: `out = PBKDF2(password, salt, rounds, dkLen)`.
+#[napi]
+pub fn pbkdf2_sha256(
+    password: Uint8Array,
+    salt: Uint8Array,
+    rounds: u32,
+    dk_len: u32,
+) -> Result<Buffer> {
+    let dk_len = dk_len.clamp(PBKDF2_MIN_LEN, PBKDF2_MAX_LEN);
+    let mut out = vec![0u8; dk_len as usize];
+    // PBKDF2 rounds must be >= 1 (a 0-round call would be meaningless).
+    let rounds = rounds.max(1);
+    pbkdf2_hmac::<Sha256>(password.as_ref(), salt.as_ref(), rounds, &mut out);
+    Ok(out.into())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn pbkdf2_sha256_known_vector() {
+        // RFC 7914 / NIST-style known answer: password "password", salt "salt",
+        // 1 iteration, 32 bytes — cross-checked with node:crypto pbkdf2Sync.
+        let out = pbkdf2_sha256(
+            Uint8Array::new(b"password".to_vec()),
+            Uint8Array::new(b"salt".to_vec()),
+            1,
+            32,
+        )
+        .unwrap();
+        let expected: [u8; 32] = [
+            0x12, 0x0f, 0xb6, 0xcf, 0xfc, 0xf8, 0xb3, 0x2c, 0x43, 0xe7, 0x22, 0x52, 0x56, 0xc4,
+            0xf8, 0x37, 0xa8, 0x65, 0x48, 0xc9, 0x2c, 0xcc, 0x35, 0x48, 0x08, 0x05, 0x98, 0x7c,
+            0xb7, 0x0b, 0xe1, 0x7b,
+        ];
+        assert_eq!(out.as_ref(), &expected);
+    }
+
+    #[test]
+    fn pbkdf2_is_iteration_sensitive() {
+        let a = pbkdf2_sha256(
+            Uint8Array::new(b"pw".to_vec()),
+            Uint8Array::new(b"salt".to_vec()),
+            1,
+            16,
+        )
+        .unwrap();
+        let b = pbkdf2_sha256(
+            Uint8Array::new(b"pw".to_vec()),
+            Uint8Array::new(b"salt".to_vec()),
+            2,
+            16,
+        )
+        .unwrap();
+        assert_ne!(a.as_ref(), b.as_ref());
+    }
+
+    #[test]
+    fn pbkdf2_zero_rounds_treated_as_one() {
+        let one = pbkdf2_sha256(
+            Uint8Array::new(b"pw".to_vec()),
+            Uint8Array::new(b"salt".to_vec()),
+            1,
+            16,
+        )
+        .unwrap();
+        let zero = pbkdf2_sha256(
+            Uint8Array::new(b"pw".to_vec()),
+            Uint8Array::new(b"salt".to_vec()),
+            0,
+            16,
+        )
+        .unwrap();
+        assert_eq!(one.as_ref(), zero.as_ref());
+    }
+}

package/rust/crypto/random_token.rs

@@ -0,0 +1,85 @@
+// rust/crypto/random_token.rs — random hex tokens (16/32/64 bytes use stack buffers)
+use crate::util::bytes::hex_encode;
+use napi::bindgen_prelude::*;
+use napi_derive::napi;
+
+#[napi]
+pub fn random_token(byte_len: u32) -> Result<Buffer> {
+    // Enterprise guard: never allocate more than this from a single call, even
+    // on API misuse — a u32 byte_len would otherwise permit a ~4 GiB alloc.
+    const MAX_BYTE_LEN: usize = 16 * 1024 * 1024;
+    if byte_len as usize > MAX_BYTE_LEN {
+        return Err(Error::from_reason(format!(
+            "random_token: byte_len {byte_len} exceeds max {MAX_BYTE_LEN}"
+        )));
+    }
+
+    let len = byte_len as usize;
+
+    // ⭐ Common sizes (16, 32, 64) use stack buffers — no heap alloc.
+    match len {
+        16 => {
+            let mut bytes = [0u8; 16];
+            getrandom::fill(&mut bytes).map_err(|e| Error::from_reason(e.to_string()))?;
+            let mut out = [0u8; 32];
+            hex_encode(&bytes, &mut out);
+            Ok(Buffer::from(out.to_vec()))
+        }
+        32 => {
+            let mut bytes = [0u8; 32];
+            getrandom::fill(&mut bytes).map_err(|e| Error::from_reason(e.to_string()))?;
+            let mut out = [0u8; 64];
+            hex_encode(&bytes, &mut out);
+            Ok(Buffer::from(out.to_vec()))
+        }
+        64 => {
+            let mut bytes = [0u8; 64];
+            getrandom::fill(&mut bytes).map_err(|e| Error::from_reason(e.to_string()))?;
+            let mut out = [0u8; 128];
+            hex_encode(&bytes, &mut out);
+            Ok(Buffer::from(out.to_vec()))
+        }
+        _ => {
+            let out_len = len
+                .checked_mul(2)
+                .ok_or_else(|| Error::from_reason("byte_len too large"))?;
+            let mut bytes = vec![0u8; len];
+            getrandom::fill(&mut bytes).map_err(|e| Error::from_reason(e.to_string()))?;
+            let mut out = vec![0u8; out_len];
+            hex_encode(&bytes, &mut out);
+            Ok(Buffer::from(out))
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn common_sizes_return_hex_of_requested_length() {
+        // The token is hex-encoded, so the output is exactly `len * 2` bytes
+        // of lowercase hex characters.
+        for len in [16u32, 32, 64, 7, 128] {
+            let out = random_token(len).expect("valid len must succeed");
+            assert_eq!(out.len(), len as usize * 2);
+            for b in out.iter() {
+                assert!(b.is_ascii_hexdigit(), "byte 0x{b:02x} is not hex");
+            }
+        }
+    }
+
+    #[test]
+    fn tokens_are_random() {
+        let a = random_token(32).unwrap();
+        let b = random_token(32).unwrap();
+        assert_ne!(a.to_vec(), b.to_vec(), "two tokens must not collide");
+    }
+
+    #[test]
+    fn huge_length_is_rejected() {
+        // The 16 MiB guard prevents a ~4 GiB single allocation from a u32 arg.
+        assert!(random_token(16 * 1024 * 1024 + 1).is_err());
+        assert!(random_token(u32::MAX).is_err());
+    }
+}