castrum 0.9.3 → 0.9.4

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,96 @@
+// 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;
+
+/// 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());
+    }
+}

package/rust/crypto/session.rs

@@ -0,0 +1,222 @@
+// rust/crypto/session.rs — fused session-envelope seal/open.
+//
+// The framework's session plugin per-request path was:
+//   seal:  JSON.stringify(envelope)          → signCookie(json, secret)
+//   open:  verifyCookie(token, secret)       → JSON.parse(unsigned)
+// i.e. two FFI crossings + a full envelope stringify/parse. Both steps here
+// build/extract the envelope NATIVELY (id/data/exp), so the caller crosses
+// ONCE and only `data` (the arbitrary user object) is stringified/parsed in
+// JS — the id and exp never round-trip through JSC.
+
+use crate::crypto::cookie_sign::{sign_cookie_bytes, verify_cookie_bytes};
+use aws_lc_rs::hmac;
+
+/// Build the envelope JSON for `id` / `dataJson` / `exp` and sign it with
+/// HMAC-SHA256 (same wire format as signCookie: `payload.<64-hex>`).
+/// `data_json` must be a valid JSON object/value — embedded verbatim.
+pub fn seal_core(id: &[u8], data_json: &[u8], exp_secs: i64, secret: &[u8]) -> Option<Vec<u8>> {
+    if id.is_empty() || secret.is_empty() {
+        return None;
+    }
+    // Envelope size: {"id":"","data":<data>,"exp":0} + escapes on id only
+    // (data is already valid JSON; exp is an integer literal).
+    let id_esc_len = crate::json::json_ser::json_escaped_len(id);
+    let mut json = Vec::with_capacity(id_esc_len + data_json.len() + 32);
+    json.push(b'{');
+    json.extend_from_slice(b"\"id\":\"");
+    let mut wpos = json.len();
+    json.resize(json.len() + id_esc_len, 0);
+    crate::json::json_ser::write_json_escaped(&mut json, &mut wpos, id);
+    json.truncate(wpos);
+    json.extend_from_slice(b"\",\"data\":");
+    json.extend_from_slice(data_json);
+    json.extend_from_slice(b",\"exp\":");
+    json.extend_from_slice(exp_secs.to_string().as_bytes());
+    json.push(b'}');
+
+    let key = hmac::Key::new(hmac::HMAC_SHA256, secret);
+    Some(sign_cookie_bytes(&json, &key))
+}
+
+/// Verify a sealed token and extract the envelope fields into the packed
+/// layout: `[u8 ok=1][i64 exp][u32 idLen][id][u32 dataLen][dataJson]`.
+/// Returns `None` on bad signature / malformed envelope.
+pub fn open_core(token: &[u8], secret: &[u8]) -> Option<(i64, Vec<u8>, Vec<u8>)> {
+    if secret.is_empty() {
+        return None;
+    }
+    let key = hmac::Key::new(hmac::HMAC_SHA256, secret);
+    let json = verify_cookie_bytes(token, &key)?;
+    // Minimal extraction over the known shape {"id":"…","data":…,"exp":N}.
+    // The id/data values were written by `seal` (or an equivalent signer), so
+    // a targeted scan of the top-level keys is sufficient — no DOM needed.
+    let mut id: Option<Vec<u8>> = None;
+    let mut data: Option<Vec<u8>> = None;
+    let mut exp: Option<i64> = None;
+
+    let mut pos = 1usize; // skip '{'
+    let bytes = &json[..];
+    while pos < bytes.len() {
+        match bytes[pos] {
+            b',' | b'{' | b'}' => pos += 1,
+            b'"' => {
+                // key string
+                let kstart = pos + 1;
+                let mut kend = kstart;
+                while kend < bytes.len() && bytes[kend] != b'"' {
+                    kend += 1;
+                }
+                if kend >= bytes.len() {
+                    return None;
+                }
+                let key = &bytes[kstart..kend];
+                pos = kend + 1;
+                if bytes.get(pos) != Some(&b':') {
+                    return None;
+                }
+                pos += 1;
+                while matches!(bytes.get(pos), Some(b' ')) {
+                    pos += 1;
+                }
+                match key {
+                    b"id" => {
+                        if bytes.get(pos) != Some(&b'"') {
+                            return None;
+                        }
+                        let vs = pos + 1;
+                        let mut ve = vs;
+                        while ve < bytes.len() && bytes[ve] != b'"' {
+                            ve += 1;
+                        }
+                        id = Some(bytes[vs..ve].to_vec());
+                        pos = ve + 1;
+                    }
+                    b"exp" => {
+                        let vs = pos;
+                        while matches!(bytes.get(pos), Some(c) if c.is_ascii_digit() || *c == b'-')
+                        {
+                            pos += 1;
+                        }
+                        exp = std::str::from_utf8(&bytes[vs..pos])
+                            .ok()
+                            .and_then(|s| s.parse::<i64>().ok());
+                    }
+                    b"data" => {
+                        // Capture the raw JSON value: object/array/string/num.
+                        let vs = pos;
+                        let ve = skip_json_value(bytes, vs)?;
+                        data = Some(bytes[vs..ve].to_vec());
+                        pos = ve;
+                    }
+                    _ => {
+                        // Unknown key: skip its value generically.
+                        pos = skip_json_value(bytes, pos)?;
+                    }
+                }
+            }
+            _ => pos += 1,
+        }
+    }
+
+    let id = id?;
+    if id.is_empty() {
+        return None;
+    }
+    Some((exp.unwrap_or(0), id, data.unwrap_or_else(|| b"{}".to_vec())))
+}
+
+/// Skip one JSON value starting at `pos`; returns the end offset.
+fn skip_json_value(bytes: &[u8], pos: usize) -> Option<usize> {
+    match bytes.get(pos)? {
+        b'"' => {
+            let mut e = pos + 1;
+            while e < bytes.len() {
+                if bytes[e] == b'\\' {
+                    e += 2;
+                    continue;
+                }
+                if bytes[e] == b'"' {
+                    return Some(e + 1);
+                }
+                e += 1;
+            }
+            None
+        }
+        b'{' | b'[' => {
+            let open = bytes[pos];
+            let close = if open == b'{' { b'}' } else { b']' };
+            let mut depth = 0usize;
+            let mut e = pos;
+            while e < bytes.len() {
+                match bytes[e] {
+                    b'"' => e = skip_json_value(bytes, e)? - 1, // string inside
+                    c if c == open => depth += 1,
+                    c if c == close => {
+                        depth -= 1;
+                        if depth == 0 {
+                            return Some(e + 1);
+                        }
+                    }
+                    _ => {}
+                }
+                e += 1;
+            }
+            None
+        }
+        _ => {
+            // number / true / false / null → until delimiter
+            let mut e = pos;
+            while e < bytes.len() && !matches!(bytes[e], b',' | b'}' | b']') {
+                e += 1;
+            }
+            Some(e)
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const SECRET: &[u8] = b"test-secret";
+
+    #[test]
+    fn seal_open_round_trip() {
+        let token =
+            seal_core(b"sess-123", br#"{"cart":["a","b"]}"#, 1_700_000_000, SECRET).expect("seal");
+        let (exp, id, data) = open_core(&token, SECRET).expect("open");
+        assert_eq!(id, b"sess-123");
+        assert_eq!(exp, 1_700_000_000);
+        assert_eq!(data, br#"{"cart":["a","b"]}"#);
+    }
+
+    #[test]
+    fn tampered_token_rejected() {
+        let mut token = seal_core(b"id1", b"{}", 0, SECRET).expect("seal");
+        let last = token.len() - 1;
+        token[last] ^= 0xff;
+        assert!(open_core(&token, SECRET).is_none());
+    }
+
+    #[test]
+    fn wrong_secret_rejected() {
+        let token = seal_core(b"id1", b"{}", 0, SECRET).expect("seal");
+        assert!(open_core(&token, b"other").is_none());
+    }
+
+    #[test]
+    fn empty_id_rejected() {
+        assert!(seal_core(b"", b"{}", 0, SECRET).is_none());
+    }
+
+    #[test]
+    fn wire_format_matches_sign_cookie() {
+        // The sealed token must be verifiable by the EXISTING cookie verify
+        // core (same "payload.<hex>" wire format) so old readers stay valid.
+        let token = seal_core(b"sid", br#"{"n":1}"#, 5, SECRET).expect("seal");
+        let key = hmac::Key::new(hmac::HMAC_SHA256, SECRET);
+        let unsigned = verify_cookie_bytes(&token, &key).expect("verify via cookie core");
+        let s = String::from_utf8(unsigned).expect("utf8");
+        assert!(s.starts_with("{\"id\":\"sid\",\"data\":{\"n\":1},\"exp\":5}"));
+    }
+}