castrum 0.9.7 → 0.9.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "castrum",
-  "version": "0.9.7",
+  "version": "0.9.9",
   "private": false,
   "description": "Enterprise-grade Bun + Rust runtime: Rust-accelerated FFI primitives, a production-grade HTTP ingress pipeline, validation, hashing, and JSON processing with benchmark-grade performance.",
   "type": "module",
@@ -66,7 +66,7 @@
     "build:all": "bun run build && bun run build:v3",
     "build:js": "bun run build:js:bundle && bun run build:js:types",
     "build:js:bundle": "bun build ./index.ts --target=node --format=esm --outdir=dist",
-    "build:js:types": "dts-bundle-generator -o dist/index.d.ts index.ts",
+    "build:js:types": "node scripts/ensure-dts-typescript.mjs && dts-bundle-generator -o dist/index.d.ts index.ts",
     "bench": "bun run build && bun bench.ts",
     "check": "bun bench.ts",
     "test": "bun test test/unit test/property test/compat",
@@ -74,6 +74,7 @@
     "test:coverage": "node scripts/check-coverage.mjs",
     "setup": "bun install && bun run build",
     "test:node": "node --test test/integration/node-smoke.test.mjs test/integration/node-enterprise.test.mjs",
+    "test:differential": "bun test test/differential",
     "verify:install": "node scripts/verify-install.mjs",
     "build:debug": "napi build --platform",
     "lint": "bunx biome check .",
@@ -146,6 +147,7 @@
     "fast-json-patch": "^3.1.1",
     "mime-types": "^3.0.2",
     "typescript": "7.0.2",
+    "typescript-dts": "npm:typescript@5.9.3",
     "validator": "^13.15.35"
   },
   "overrides": {

package/rust/crypto/aead.rs

@@ -36,6 +36,18 @@ fn batch_nonce(base: &[u8], index: usize) -> [u8; NONCE_LEN] {
     nonce
 }
 
+/// Reject a nonce that is not exactly [`NONCE_LEN`] bytes. Guards the batch
+/// entry points, whose `copy_from_slice` would otherwise panic.
+fn validate_nonce(nonce: &[u8]) -> Result<()> {
+    if nonce.len() != NONCE_LEN {
+        return Err(Error::from_reason(format!(
+            "aead nonce must be {NONCE_LEN} bytes, got {}",
+            nonce.len()
+        )));
+    }
+    Ok(())
+}
+
 fn resolve_algorithm(name: Option<&str>) -> Result<&'static aead::Algorithm> {
     match name {
         None | Some("aes-256-gcm") => Ok(&aead::AES_256_GCM),
@@ -197,6 +209,7 @@ pub fn aead_encrypt_batch_packed(
     algorithm: Option<String>,
 ) -> Result<Buffer> {
     let alg = resolve_algorithm(algorithm.as_deref())?;
+    validate_nonce(nonce.as_ref())?;
 
     let enc_for = |plaintext: &[u8], index: usize| -> Vec<u8> {
         let n = batch_nonce(nonce.as_ref(), index);
@@ -220,6 +233,7 @@ pub fn aead_decrypt_batch_packed(
     algorithm: Option<String>,
 ) -> Result<Buffer> {
     let alg = resolve_algorithm(algorithm.as_deref())?;
+    validate_nonce(nonce.as_ref())?;
 
     let dec_for = |ciphertext: &[u8], index: usize| -> Vec<u8> {
         let n = batch_nonce(nonce.as_ref(), index);
@@ -317,6 +331,36 @@ mod tests {
         }
     }
 
+    fn packed_one(bytes: &[u8]) -> Uint8Array {
+        let mut data = Vec::new();
+        data.extend_from_slice(&1u32.to_le_bytes());
+        data.extend_from_slice(&(bytes.len() as u32).to_le_bytes());
+        data.extend_from_slice(bytes);
+        Uint8Array::new(data)
+    }
+
+    #[test]
+    fn batch_rejects_a_non_12_byte_nonce() {
+        // A wrong-length nonce used to panic inside `copy_from_slice` (and the
+        // napi sync trampoline unwinds through extern "C" → abort). It must be
+        // a normal JS error instead.
+        let key = key_bytes();
+        assert!(aead_encrypt_batch_packed(
+            packed_one(b"abc"),
+            Uint8Array::new(key.to_vec()),
+            Uint8Array::new(vec![0u8; 16]),
+            None,
+        )
+        .is_err());
+        assert!(aead_decrypt_batch_packed(
+            packed_one(b"abc"),
+            Uint8Array::new(key.to_vec()),
+            Uint8Array::new(vec![0u8; 8]),
+            None,
+        )
+        .is_err());
+    }
+
     #[test]
     fn batch_nonce_derived_encrypt_roundtrip() {
         // Each item encrypted with its derived nonce decrypts correctly, and a

package/rust/crypto/argon2.rs

@@ -30,8 +30,16 @@ pub struct PasswordHashOptions {
     pub out_len: Option<u32>,
 }
 
+/// Sanity caps for caller-supplied argon2 params: a hostile or mis-set config
+/// must not force a multi-GiB allocation or a multi-minute CPU burn. Generous
+/// enough for any real deployment (defaults are 19 MiB / 2 / 1 / 32).
+pub const ARGON2_MAX_M_COST: u32 = 1_048_576; // 1 GiB, in KiB
+pub const ARGON2_MAX_T_COST: u32 = 64;
+pub const ARGON2_MAX_P_COST: u32 = 64;
+pub const ARGON2_MAX_OUT_LEN: u32 = 1024;
+
 fn resolve_opts(o: Option<&PasswordHashOptions>) -> (u32, u32, u32, u32) {
-    match o {
+    let (m, t, p, out) = match o {
         Some(o) => (
             o.m_cost.unwrap_or(19_456),
             o.t_cost.unwrap_or(2),
@@ -39,7 +47,13 @@ fn resolve_opts(o: Option<&PasswordHashOptions>) -> (u32, u32, u32, u32) {
             o.out_len.unwrap_or(32),
         ),
         None => (19_456, 2, 1, 32),
-    }
+    };
+    (
+        m.min(ARGON2_MAX_M_COST),
+        t.min(ARGON2_MAX_T_COST),
+        p.min(ARGON2_MAX_P_COST),
+        out.min(ARGON2_MAX_OUT_LEN),
+    )
 }
 
 // ── Pure-Rust core ─────────────────────────────────────────────
@@ -230,6 +244,22 @@ mod tests {
         .is_err());
     }
 
+    #[test]
+    fn argon2_params_are_capped() {
+        let (m, t, p, out) = resolve_opts(Some(&PasswordHashOptions {
+            m_cost: Some(u32::MAX),
+            t_cost: Some(u32::MAX),
+            p_cost: Some(u32::MAX),
+            out_len: Some(u32::MAX),
+        }));
+        assert_eq!(m, ARGON2_MAX_M_COST);
+        assert_eq!(t, ARGON2_MAX_T_COST);
+        assert_eq!(p, ARGON2_MAX_P_COST);
+        assert_eq!(out, ARGON2_MAX_OUT_LEN);
+        // Sane defaults pass through untouched.
+        assert_eq!(resolve_opts(None), (19_456, 2, 1, 32));
+    }
+
     #[test]
     fn verify_rejects_wrong_password() {
         let phc = hash_password(PASSWORD, SALT, 4096, 2, 1, 32).unwrap();

package/rust/crypto/jwt/tests.rs

@@ -76,6 +76,25 @@ fn verify_token_enforces_iat_leeway() {
     assert!(verify_token(&near, SECRET, now).is_some());
 }
 
+#[test]
+fn verify_token_rejects_non_integer_or_non_numeric_exp() {
+    let now = 1_000_000i64;
+    // A fractional exp in the PAST must reject. Pre-fix `as_i64()` returned
+    // None for a float, so the expiry check was skipped and the token verified
+    // as never-expiring.
+    let frac_past = token(&serde_json::json!({ "sub": "1", "exp": 999_999.5 }), SECRET);
+    assert!(verify_token(&frac_past, SECRET, now).is_none());
+    // Present-but-non-numeric exp is malformed → reject.
+    let string_exp = token(&serde_json::json!({ "sub": "1", "exp": "999999" }), SECRET);
+    assert!(verify_token(&string_exp, SECRET, now).is_none());
+    // A fractional exp in the FUTURE is a valid RFC 7519 NumericDate → accept.
+    let frac_future = token(
+        &serde_json::json!({ "sub": "1", "exp": 1_000_000.5 }),
+        SECRET,
+    );
+    assert!(verify_token(&frac_future, SECRET, now).is_some());
+}
+
 #[test]
 fn verify_token_accepts_valid_claims() {
     let claims = serde_json::json!({ "sub": "123", "role": "admin" });

package/rust/crypto/jwt/token.rs

@@ -113,19 +113,6 @@ pub fn build_token_with_key(
     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
@@ -148,10 +135,11 @@ pub fn verify_signature_with_key(token: &[u8], key: &aws_lc_rs::hmac::Key) -> bo
     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),
+        // Audited constant-time comparison (aws-lc-rs), matching every other
+        // MAC path in the crate (cookie sign / CSRF / hmac_sha256) instead of a
+        // hand-rolled loop the compiler could optimize into an early exit.
+        Some(provided) => aws_lc_rs::hmac::verify(key, &signing_input, &provided).is_ok(),
         None => false,
     }
 }
@@ -239,31 +227,58 @@ pub(crate) fn verify_time_claims(payload_b64: &[u8], now_seconds: i64) -> Option
     let payload = base64url_decode_bytes(payload_b64)?;
     let value: sonic_rs::Value = sonic_rs::from_slice(&payload).ok()?;
 
+    // RFC 7519 NumericDate may be non-integer, so parse as f64 — `as_i64()`
+    // returns None for a float, which previously SKIPPED the check entirely and
+    // made a token with a fractional `exp` verify as never-expiring. A claim
+    // that is present but not a finite number is malformed → reject.
+    let now = now_seconds as f64;
+
     // `exp`: reject when now >= exp.
-    if let Some(exp) = value.get("exp").and_then(|v| v.as_i64()) {
-        if now_seconds >= exp {
-            return None;
-        }
+    match time_claim(&value, "exp") {
+        TimeClaim::Absent => {}
+        TimeClaim::Invalid => return None,
+        TimeClaim::Value(exp) if now >= exp => return None,
+        TimeClaim::Value(_) => {}
     }
 
     // `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;
-        }
+    match time_claim(&value, "nbf") {
+        TimeClaim::Absent => {}
+        TimeClaim::Invalid => return None,
+        TimeClaim::Value(nbf) if now < nbf => return None,
+        TimeClaim::Value(_) => {}
     }
 
     // `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;
-        }
+    match time_claim(&value, "iat") {
+        TimeClaim::Absent => {}
+        TimeClaim::Invalid => return None,
+        TimeClaim::Value(iat) if now < iat - CLOCK_SKEW_LEEWAY_SECS as f64 => return None,
+        TimeClaim::Value(_) => {}
     }
 
     Some(payload)
 }
 
+/// Parsed state of a JWT time claim: absent, a finite numeric value, or present
+/// but malformed (string / null / non-finite).
+enum TimeClaim {
+    Absent,
+    Value(f64),
+    Invalid,
+}
+
+fn time_claim(value: &sonic_rs::Value, key: &str) -> TimeClaim {
+    match value.get(key) {
+        None => TimeClaim::Absent,
+        Some(v) => match v.as_f64() {
+            Some(n) if n.is_finite() => TimeClaim::Value(n),
+            _ => TimeClaim::Invalid,
+        },
+    }
+}
+
 /// 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.

package/rust/crypto/session.rs

@@ -41,6 +41,12 @@ pub fn seal_core(id: &[u8], data_json: &[u8], exp_secs: i64, secret: &[u8]) -> O
 /// 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.
+///
+/// The returned `exp` is **advisory**: this function does NOT compare it to the
+/// current time, so a correctly signed but expired envelope still opens. The
+/// caller MUST reject it (`exp != 0 && now >= exp`). (Enforcing it here was
+/// considered and rejected: the wire contract is signature + extraction, and
+/// the bind-time self-test seals with fixed historical timestamps.)
 pub fn open_core(token: &[u8], secret: &[u8]) -> Option<(i64, Vec<u8>, Vec<u8>)> {
     if secret.is_empty() {
         return None;

package/rust/ffi/crypto.rs

@@ -9,7 +9,7 @@ use pbkdf2::pbkdf2_hmac;
 use sha2::Sha256;
 use std::slice;
 
-use super::util::{aead_alg, cstring_return, hmac_key_cached, panic_guard};
+use super::util::{aead_alg, cstring_return, panic_guard, with_hmac_key_cached};
 
 /// HMAC-SHA256 verify → 1/0 (constant-time, hex sig compared after
 /// whitespace-trim — mirrors the napi scalar path).
@@ -32,8 +32,9 @@ pub unsafe extern "C" fn castrum_hmac_sha256_verify(
     let Some(sig_bytes) = crate::util::bytes::hex_decode_32(sig_t) else {
         return 0;
     };
-    let k = hmac_key_cached(slice::from_raw_parts(key, klen));
-    u8::from(hmac::verify(&k, slice::from_raw_parts(data, dlen), &sig_bytes).is_ok())
+    with_hmac_key_cached(slice::from_raw_parts(key, klen), |k| {
+        u8::from(hmac::verify(k, slice::from_raw_parts(data, dlen), &sig_bytes).is_ok())
+    })
 }
 
 /// CSRF constant-time verify → 1/0 (token format `<64-hex>.<64-hex>`).
@@ -50,11 +51,12 @@ pub unsafe extern "C" fn castrum_csrf_verify(
     if token.is_null() || secret.is_null() {
         return 0;
     }
-    let k = hmac_key_cached(slice::from_raw_parts(secret, slen));
-    u8::from(crate::crypto::csrf::csrf_verify_with_key(
-        slice::from_raw_parts(token, tlen),
-        &k,
-    ))
+    with_hmac_key_cached(slice::from_raw_parts(secret, slen), |k| {
+        u8::from(crate::crypto::csrf::csrf_verify_with_key(
+            slice::from_raw_parts(token, tlen),
+            k,
+        ))
+    })
 }
 
 /// Argon2id password verify → 1/0 (constant-time internally).
@@ -71,10 +73,17 @@ pub unsafe extern "C" fn castrum_password_verify(
     if password.is_null() || phc.is_null() {
         return 0;
     }
-    u8::from(crate::crypto::argon2::verify_password(
-        slice::from_raw_parts(password, plen),
-        slice::from_raw_parts(phc, phclen),
-    ))
+    // The argon2 core allocates/derives — a panic must become 0, not unwind
+    // through `extern "C"`.
+    panic_guard(
+        || {
+            u8::from(crate::crypto::argon2::verify_password(
+                slice::from_raw_parts(password, plen),
+                slice::from_raw_parts(phc, phclen),
+            ))
+        },
+        0,
+    )
 }
 
 /// bcrypt password verify → 1/0 (PHC `$2b$` string).
@@ -95,10 +104,15 @@ pub unsafe extern "C" fn castrum_password_verify_bcrypt(
     if password.is_null() || hash.is_null() {
         return 0;
     }
-    let Ok(h) = std::ffi::CStr::from_ptr(hash).to_str() else {
-        return 0;
-    };
-    u8::from(bcrypt::verify(slice::from_raw_parts(password, plen), h).unwrap_or(false))
+    panic_guard(
+        || {
+            let Ok(h) = std::ffi::CStr::from_ptr(hash).to_str() else {
+                return 0;
+            };
+            u8::from(bcrypt::verify(slice::from_raw_parts(password, plen), h).unwrap_or(false))
+        },
+        0,
+    )
 }
 
 /// HMAC-SHA256 hex (64 chars) into `out`.
@@ -117,8 +131,9 @@ pub unsafe extern "C" fn castrum_hmac_sha256(
     if key.is_null() || data.is_null() || out.is_null() || out_cap < 64 {
         return 0;
     }
-    let k = hmac_key_cached(slice::from_raw_parts(key, klen));
-    let tag = hmac::sign(&k, slice::from_raw_parts(data, dlen));
+    let tag = with_hmac_key_cached(slice::from_raw_parts(key, klen), |k| {
+        hmac::sign(k, slice::from_raw_parts(data, dlen))
+    });
     let mut hex = [0u8; 64];
     crate::util::bytes::hex_encode_32(tag.as_ref(), &mut hex);
     slice::from_raw_parts_mut(out, 64).copy_from_slice(&hex);
@@ -141,9 +156,10 @@ pub unsafe extern "C" fn castrum_sign_cookie(
         return std::ptr::null();
     }
     let v = slice::from_raw_parts(value, vlen);
-    let key = hmac_key_cached(slice::from_raw_parts(secret, slen));
     cstring_return(vlen + 65, |out| {
-        crate::crypto::cookie_sign::sign_cookie_into(v, &key, out)
+        with_hmac_key_cached(slice::from_raw_parts(secret, slen), |key| {
+            crate::crypto::cookie_sign::sign_cookie_into(v, key, out)
+        })
     })
 }
 
@@ -173,9 +189,14 @@ pub unsafe extern "C" fn castrum_sign_cookie_into(
         return needed;
     }
     let v = slice::from_raw_parts(value, vlen);
-    let key = hmac_key_cached(slice::from_raw_parts(secret, slen));
-    crate::crypto::cookie_sign::sign_cookie_into(v, &key, slice::from_raw_parts_mut(out, out_cap))
-        .unwrap_or_default()
+    with_hmac_key_cached(slice::from_raw_parts(secret, slen), |key| {
+        crate::crypto::cookie_sign::sign_cookie_into(
+            v,
+            key,
+            slice::from_raw_parts_mut(out, out_cap),
+        )
+    })
+    .unwrap_or_default()
 }
 
 /// Verify a signed cookie → the value without its signature, returned as a
@@ -195,9 +216,10 @@ pub unsafe extern "C" fn castrum_verify_cookie(
         return std::ptr::null();
     }
     let s = slice::from_raw_parts(signed, slen);
-    let key = hmac_key_cached(slice::from_raw_parts(secret, klen));
     cstring_return(slen, |out| {
-        crate::crypto::cookie_sign::verify_cookie_into(s, &key, out)
+        with_hmac_key_cached(slice::from_raw_parts(secret, klen), |key| {
+            crate::crypto::cookie_sign::verify_cookie_into(s, key, out)
+        })
     })
 }
 
@@ -224,7 +246,6 @@ pub unsafe extern "C" fn castrum_verify_cookie_into(
         return 0;
     }
     let s = slice::from_raw_parts(signed, slen);
-    let key = hmac_key_cached(slice::from_raw_parts(secret, klen));
     // The value is a prefix of `signed` (everything before the last `.`), so
     // `slen` is always a sufficient bound — needed-size only differs when the
     // caller passed less.
@@ -237,8 +258,14 @@ pub unsafe extern "C" fn castrum_verify_cookie_into(
         }
         return slen;
     }
-    crate::crypto::cookie_sign::verify_cookie_into(s, &key, slice::from_raw_parts_mut(out, out_cap))
-        .unwrap_or_default()
+    with_hmac_key_cached(slice::from_raw_parts(secret, klen), |key| {
+        crate::crypto::cookie_sign::verify_cookie_into(
+            s,
+            key,
+            slice::from_raw_parts_mut(out, out_cap),
+        )
+    })
+    .unwrap_or_default()
 }
 
 /// CSRF token (`<64-hex(rnd)>.<64-hex(sig)>`, 129 bytes) returned as a
@@ -254,7 +281,6 @@ pub unsafe extern "C" fn castrum_csrf_token(
     if secret.is_null() {
         return std::ptr::null();
     }
-    let k = hmac_key_cached(slice::from_raw_parts(secret, slen));
     let mut rnd = [0u8; 32];
     if getrandom::fill(&mut rnd).is_err() {
         return std::ptr::null();
@@ -262,7 +288,10 @@ pub unsafe extern "C" fn castrum_csrf_token(
     let mut rnd_hex = [0u8; 64];
     crate::util::bytes::hex_encode(&rnd, &mut rnd_hex);
     let mut sig_hex = [0u8; 64];
-    crate::util::bytes::hex_encode(hmac::sign(&k, &rnd_hex).as_ref(), &mut sig_hex);
+    let signed = with_hmac_key_cached(slice::from_raw_parts(secret, slen), |k| {
+        hmac::sign(k, &rnd_hex)
+    });
+    crate::util::bytes::hex_encode(signed.as_ref(), &mut sig_hex);
     cstring_return(129, |out| {
         out[..64].copy_from_slice(&rnd_hex);
         out[64] = b'.';
@@ -291,7 +320,6 @@ pub unsafe extern "C" fn castrum_csrf_token_into(
     if out_cap < 129 {
         return 129;
     }
-    let k = hmac_key_cached(slice::from_raw_parts(secret, slen));
     let mut rnd = [0u8; 32];
     if getrandom::fill(&mut rnd).is_err() {
         return 0;
@@ -299,7 +327,10 @@ pub unsafe extern "C" fn castrum_csrf_token_into(
     let mut rnd_hex = [0u8; 64];
     crate::util::bytes::hex_encode(&rnd, &mut rnd_hex);
     let mut sig_hex = [0u8; 64];
-    crate::util::bytes::hex_encode(hmac::sign(&k, &rnd_hex).as_ref(), &mut sig_hex);
+    let signed = with_hmac_key_cached(slice::from_raw_parts(secret, slen), |k| {
+        hmac::sign(k, &rnd_hex)
+    });
+    crate::util::bytes::hex_encode(signed.as_ref(), &mut sig_hex);
     let o = slice::from_raw_parts_mut(out, 129);
     o[..64].copy_from_slice(&rnd_hex);
     o[64] = b'.';

package/rust/ffi/hashing.rs

@@ -7,6 +7,8 @@
 use std::ptr;
 use std::slice;
 
+use super::util::panic_guard;
+
 /// CRC32 over `data[0..len]`. Returns the CRC-32 checksum.
 ///
 /// # Safety
@@ -179,19 +181,22 @@ pub unsafe extern "C" fn castrum_json_sum_ids(
     if data.is_null() || out.is_null() {
         return 0;
     }
-    match crate::json::json_ops::json_sum_ids_bytes(slice::from_raw_parts(data, len)) {
-        Ok(sum) if out_len >= 9 => {
-            *out = 1;
-            ptr::copy_nonoverlapping(sum.to_le_bytes().as_ptr(), out.add(1), 8);
-            9
-        }
-        Ok(_) => 9, // too-small buffer → exact required size (growExact)
-        Err(_) if out_len >= 1 => {
-            *out = 0;
-            1
-        }
-        Err(_) => 1, // too-small buffer → exact required size
-    }
+    panic_guard(
+        || match crate::json::json_ops::json_sum_ids_bytes(slice::from_raw_parts(data, len)) {
+            Ok(sum) if out_len >= 9 => {
+                *out = 1;
+                ptr::copy_nonoverlapping(sum.to_le_bytes().as_ptr(), out.add(1), 8);
+                9
+            }
+            Ok(_) => 9, // too-small buffer → exact required size (growExact)
+            Err(_) if out_len >= 1 => {
+                *out = 0;
+                1
+            }
+            Err(_) => 1, // too-small buffer → exact required size
+        },
+        0,
+    )
 }
 
 /// Escape JS-RegExp metacharacters (`\ . * + ? ^ $ { } | ( ) [ ]`) in
@@ -212,13 +217,18 @@ pub unsafe extern "C" fn castrum_regex_escape(
     if data.is_null() || out.is_null() {
         return 0;
     }
-    let input = slice::from_raw_parts(data, len);
-    let needed = crate::util::text::regex_escape_len(input);
-    if needed > out_cap {
-        return needed;
-    }
-    crate::util::text::regex_escape_write(input, slice::from_raw_parts_mut(out, out_cap));
-    needed
+    panic_guard(
+        || {
+            let input = slice::from_raw_parts(data, len);
+            let needed = crate::util::text::regex_escape_len(input);
+            if needed > out_cap {
+                return needed;
+            }
+            crate::util::text::regex_escape_write(input, slice::from_raw_parts_mut(out, out_cap));
+            needed
+        },
+        0,
+    )
 }
 
 /// String-input / string-return sibling of [`castrum_regex_escape`]: the
@@ -269,17 +279,22 @@ pub unsafe extern "C" fn castrum_hex_validate_batch_str(
     if ids.is_null() || out.is_null() {
         return 0;
     }
-    let input = std::ffi::CStr::from_ptr(ids).to_bytes();
-    let needed = crate::util::validation::hex_batch_count(input);
-    if needed > out_cap {
-        return needed;
-    }
-    let mut buf = Vec::with_capacity(needed);
-    match crate::util::validation::hex_batch_valid_into(input, width as usize, &mut buf) {
-        Ok(()) if buf.len() <= out_cap => {
-            slice::from_raw_parts_mut(out, buf.len()).copy_from_slice(&buf);
-            buf.len()
-        }
-        _ => 0,
-    }
+    panic_guard(
+        || {
+            let input = std::ffi::CStr::from_ptr(ids).to_bytes();
+            let needed = crate::util::validation::hex_batch_count(input);
+            if needed > out_cap {
+                return needed;
+            }
+            let mut buf = Vec::with_capacity(needed);
+            match crate::util::validation::hex_batch_valid_into(input, width as usize, &mut buf) {
+                Ok(()) if buf.len() <= out_cap => {
+                    slice::from_raw_parts_mut(out, buf.len()).copy_from_slice(&buf);
+                    buf.len()
+                }
+                _ => 0,
+            }
+        },
+        0,
+    )
 }