castrum 0.9.6 → 0.9.8

package/rust/ffi/payload.rs

@@ -24,10 +24,18 @@ pub unsafe extern "C" fn castrum_ws_accept_key(
     if key.is_null() {
         return std::ptr::null();
     }
-    cstring_return(28, |out| {
-        crate::payload::websocket::ws_accept_key_into(std::ffi::CStr::from_ptr(key).to_bytes(), out)
-            .ok()
-    })
+    panic_guard(
+        || {
+            cstring_return(28, |out| {
+                crate::payload::websocket::ws_accept_key_into(
+                    std::ffi::CStr::from_ptr(key).to_bytes(),
+                    out,
+                )
+                .ok()
+            })
+        },
+        std::ptr::null(),
+    )
 }
 
 /// RFC 6455 Sec-WebSocket-Accept written directly into a caller buffer — the
@@ -76,14 +84,19 @@ pub unsafe extern "C" fn castrum_ws_frame_encode(
     if payload.is_null() || out.is_null() {
         return 0;
     }
-    crate::payload::ws_frames::encode_frame_into(
-        opcode,
-        slice::from_raw_parts(payload, plen),
-        mask != 0,
-        fin != 0,
-        slice::from_raw_parts_mut(out, out_cap),
+    panic_guard(
+        || {
+            crate::payload::ws_frames::encode_frame_into(
+                opcode,
+                slice::from_raw_parts(payload, plen),
+                mask != 0,
+                fin != 0,
+                slice::from_raw_parts_mut(out, out_cap),
+            )
+            .unwrap_or(0)
+        },
+        0,
     )
-    .unwrap_or(0)
 }
 
 /// Decode a WebSocket frame into a packed `[u8 flags][u8 opcode][u32 payload_len]
@@ -102,22 +115,29 @@ pub unsafe extern "C" fn castrum_ws_frame_decode_packed(
     if data.is_null() || out.is_null() {
         return 0;
     }
-    let Some(frame) = crate::payload::ws_frames::decode_frame(slice::from_raw_parts(data, len))
-    else {
-        return 0;
-    };
-    let Some(need) = 6usize.checked_add(frame.payload.len()) else {
-        return 0;
-    };
-    if need > out_cap {
-        return 0;
-    }
-    let o = slice::from_raw_parts_mut(out, need);
-    o[0] = u8::from(frame.fin);
-    o[1] = frame.opcode;
-    o[2..6].copy_from_slice(&(frame.payload.len() as u32).to_le_bytes());
-    o[6..].copy_from_slice(&frame.payload);
-    need
+    // Attacker-controlled frame bytes: a panic must become 0.
+    panic_guard(
+        || {
+            let Some(frame) =
+                crate::payload::ws_frames::decode_frame(slice::from_raw_parts(data, len))
+            else {
+                return 0;
+            };
+            let Some(need) = 6usize.checked_add(frame.payload.len()) else {
+                return 0;
+            };
+            if need > out_cap {
+                return 0;
+            }
+            let o = slice::from_raw_parts_mut(out, need);
+            o[0] = u8::from(frame.fin);
+            o[1] = frame.opcode;
+            o[2..6].copy_from_slice(&(frame.payload.len() as u32).to_le_bytes());
+            o[6..].copy_from_slice(&frame.payload);
+            need
+        },
+        0,
+    )
 }
 
 // ── Compression (gzip / brotli) ──────────────────────────────────

package/rust/ffi/task.rs

@@ -32,12 +32,17 @@ pub unsafe extern "C" fn castrum_task_submit(
     if args.is_null() && args_len != 0 {
         return 0;
     }
-    let owned: Vec<u8> = if args_len == 0 {
-        Vec::new()
-    } else {
-        slice::from_raw_parts(args, args_len).to_vec()
-    };
-    u32::from(task::submit_op(op, owned, task_id as u64))
+    panic_guard(
+        || {
+            let owned: Vec<u8> = if args_len == 0 {
+                Vec::new()
+            } else {
+                slice::from_raw_parts(args, args_len).to_vec()
+            };
+            u32::from(task::submit_op(op, owned, task_id as u64))
+        },
+        0,
+    )
 }
 
 /// Drain finished tasks into `out` (packed `[u32 count][entry…]`).
@@ -85,18 +90,23 @@ pub unsafe extern "C" fn castrum_task_submit_out(
     if (args.is_null() && args_len != 0) || out.is_null() || out_cap == 0 {
         return 0;
     }
-    let owned: Vec<u8> = if args_len == 0 {
-        Vec::new()
-    } else {
-        slice::from_raw_parts(args, args_len).to_vec()
-    };
-    u32::from(task::submit_op_into(
-        op,
-        owned,
-        task_id as u64,
-        out as usize,
-        out_cap,
-    ))
+    panic_guard(
+        || {
+            let owned: Vec<u8> = if args_len == 0 {
+                Vec::new()
+            } else {
+                slice::from_raw_parts(args, args_len).to_vec()
+            };
+            u32::from(task::submit_op_into(
+                op,
+                owned,
+                task_id as u64,
+                out as usize,
+                out_cap,
+            ))
+        },
+        0,
+    )
 }
 
 /// Mark `task_id` cancelled. Returns `1` when newly marked, `0` otherwise.
@@ -129,20 +139,25 @@ pub unsafe extern "C" fn castrum_task_submit_slice(
     if (hdr.is_null() && hdr_len != 0) || (data.is_null() && data_len != 0) {
         return 0;
     }
-    // The header is small, so copying it keeps the caller free to reuse a
-    // scratch buffer; the payload is never copied.
-    let owned = if hdr_len == 0 {
-        Vec::new()
-    } else {
-        slice::from_raw_parts(hdr, hdr_len).to_vec()
-    };
-    u32::from(task::submit_slice_op(
-        op,
-        owned,
-        data as usize,
-        data_len,
-        task_id as u64,
-    ))
+    panic_guard(
+        || {
+            // The header is small, so copying it keeps the caller free to reuse a
+            // scratch buffer; the payload is never copied.
+            let owned = if hdr_len == 0 {
+                Vec::new()
+            } else {
+                slice::from_raw_parts(hdr, hdr_len).to_vec()
+            };
+            u32::from(task::submit_slice_op(
+                op,
+                owned,
+                data as usize,
+                data_len,
+                task_id as u64,
+            ))
+        },
+        0,
+    )
 }
 
 /// Register the thread-safe doorbell trampoline address (`0` disables it).
@@ -158,8 +173,12 @@ pub extern "C" fn castrum_task_set_doorbell(cb: *const std::os::raw::c_void) ->
 }
 
 /// Stop the pool and drop pending completions. Returns `0`.
+///
+/// The doorbell trampoline is cleared FIRST: a worker completing after this
+/// point must not call a JS callback the owner is about to close.
 #[no_mangle]
 pub extern "C" fn castrum_task_shutdown() -> u32 {
+    task::completion::clear_doorbell();
     task::shutdown();
     task::completion::clear();
     0

package/rust/ffi/tests.rs

@@ -189,6 +189,30 @@ fn utf8_valid_c_abi() {
     assert_eq!(unsafe { castrum_utf8_valid(b"".as_ptr(), 0) }, 1);
 }
 
+#[test]
+fn borrowed_hmac_key_preserves_signatures_after_eviction() {
+    HMAC_KEY_CACHE.with(|c| c.borrow_mut().clear());
+    for i in 0..(HMAC_KEY_CACHE_CAP * 3) {
+        let secret = format!("borrowed-key-{}", i % (HMAC_KEY_CACHE_CAP + 1));
+        let expected = hmac::sign(&hmac_key(secret.as_bytes()), b"payload");
+        for _ in 0..2 {
+            let actual = with_hmac_key_cached(secret.as_bytes(), |key| hmac::sign(key, b"payload"));
+            assert_eq!(actual.as_ref(), expected.as_ref());
+        }
+    }
+}
+
+#[test]
+fn borrowed_hmac_key_releases_cache_on_unwind() {
+    let caught = std::panic::catch_unwind(|| {
+        with_hmac_key_cached(b"borrow-panic", |_| panic!("test callback panic"));
+    });
+    assert!(caught.is_err());
+    let actual = with_hmac_key_cached(b"borrow-panic", |key| hmac::sign(key, b"payload"));
+    let expected = hmac::sign(&hmac_key(b"borrow-panic"), b"payload");
+    assert_eq!(actual.as_ref(), expected.as_ref());
+}
+
 #[test]
 fn hmac_key_cache_reuses_compiled_key() {
     // Same-secret calls must hit the cache (the whole point of the LRU):
@@ -2308,6 +2332,179 @@ fn wire_validate_and_session_c_abi() {
         unsafe { castrum_session_open(token, c"wrong".as_ptr(), buf.as_mut_ptr(), buf.len()) },
         0
     );
+
+    // ── Byte-arg siblings ──────────────────────────────────────────
+    // Copy the first token OUT of the shared per-thread CSTR_BUF before the
+    // next `cstring` return reuses it (that buffer is one-per-thread by design).
+    let token_str = unsafe { std::ffi::CStr::from_ptr(token) }
+        .to_string_lossy()
+        .into_owned();
+    let id = b"sess-9";
+    let data = b"{\"n\":1}";
+    let secret = b"sekrit";
+    let token_b = unsafe {
+        castrum_session_seal_bytes(
+            id.as_ptr(),
+            id.len(),
+            data.as_ptr(),
+            data.len(),
+            1_234_567,
+            secret.as_ptr(),
+            secret.len(),
+        )
+    };
+    assert!(!token_b.is_null());
+    // One shared core ⇒ byte-identical token. This is the parity guarantee that
+    // makes the byte form a drop-in for the cstring form.
+    let token_b_str = unsafe { std::ffi::CStr::from_ptr(token_b) }
+        .to_string_lossy()
+        .into_owned();
+    assert_eq!(token_b_str, token_str);
+
+    let tok_bytes = token_b_str.as_bytes();
+    let mut buf2 = [0u8; 256];
+    let w2 = unsafe {
+        castrum_session_open_bytes(
+            tok_bytes.as_ptr(),
+            tok_bytes.len(),
+            secret.as_ptr(),
+            secret.len(),
+            buf2.as_mut_ptr(),
+            buf2.len(),
+        )
+    };
+    assert_eq!(w2, w);
+    assert_eq!(buf2[..w2], buf[..w]);
+    // bad signature → 0
+    assert_eq!(
+        unsafe {
+            castrum_session_open_bytes(
+                tok_bytes.as_ptr(),
+                tok_bytes.len(),
+                b"wrong".as_ptr(),
+                5,
+                buf2.as_mut_ptr(),
+                buf2.len(),
+            )
+        },
+        0
+    );
+    // Too-small buffer → the EXACT required size, not 0 (needed-size rule).
+    assert_eq!(
+        unsafe {
+            castrum_session_open_bytes(
+                tok_bytes.as_ptr(),
+                tok_bytes.len(),
+                secret.as_ptr(),
+                secret.len(),
+                buf2.as_mut_ptr(),
+                4,
+            )
+        },
+        w2
+    );
+
+    // The reason this sibling exists: the cstring form TRUNCATES at an embedded
+    // NUL (the engine's transcode is NUL-terminated), so an id carrying one is
+    // sealed under its truncated form. The byte form carries the exact length.
+    //
+    // Each token is copied to a String IMMEDIATELY after its own call: both
+    // `cstring` returns write into ONE per-thread CSTR_BUF, so the earlier
+    // pointer is dead the moment the next call reuses it — the aliasing hazard
+    // `docs/FFI_BUN_GUIDE.md` documents. The assertions below also read the
+    // recovered `id` BYTES rather than the token's text, so they hold
+    // regardless of how the payload is wire-encoded.
+    let nul_id = b"sess-9\0extra";
+    let tp = unsafe {
+        castrum_session_seal(
+            nul_id.as_ptr() as *const std::os::raw::c_char,
+            c"{\"n\":1}".as_ptr(),
+            1_234_567,
+            c"sekrit".as_ptr(),
+        )
+    };
+    assert!(!tp.is_null());
+    let truncated_str = unsafe { std::ffi::CStr::from_ptr(tp) }
+        .to_string_lossy()
+        .into_owned();
+
+    let ep = unsafe {
+        castrum_session_seal_bytes(
+            nul_id.as_ptr(),
+            nul_id.len(),
+            data.as_ptr(),
+            data.len(),
+            1_234_567,
+            secret.as_ptr(),
+            secret.len(),
+        )
+    };
+    assert!(!ep.is_null());
+    let exact_str = unsafe { std::ffi::CStr::from_ptr(ep) }
+        .to_string_lossy()
+        .into_owned();
+
+    assert_ne!(
+        exact_str, truncated_str,
+        "byte form must not truncate at NUL"
+    );
+
+    // Open each token and read back the `id` from the packed layout
+    // (`[u8 ok][i64 exp][u32 idLen][id]…`) — the ground truth this change is
+    // about. NOTE: `seal_core` JSON-escapes the id but `open_core` returns the
+    // raw captured span, so an id needing escapes comes back escaped. That
+    // asymmetry is pre-existing; these assertions are written not to depend on
+    // it, only on the truncation itself.
+    let id_of = |tok: &str, out: &mut [u8; 256]| -> Vec<u8> {
+        let w = unsafe {
+            castrum_session_open_bytes(
+                tok.as_ptr(),
+                tok.len(),
+                secret.as_ptr(),
+                secret.len(),
+                out.as_mut_ptr(),
+                out.len(),
+            )
+        };
+        assert!(w > 13, "open of {tok:?} failed");
+        let id_len = u32::from_le_bytes([out[9], out[10], out[11], out[12]]) as usize;
+        out[13..13 + id_len].to_vec()
+    };
+    let mut scratch = [0u8; 256];
+    let truncated_id = id_of(&truncated_str, &mut scratch);
+    let exact_id = id_of(&exact_str, &mut scratch);
+    assert_eq!(truncated_id, b"sess-9");
+    // The byte form carries the exact length, so the id comes back WHOLE — and
+    // byte-exact, because `open_core` now decodes the id rather than returning
+    // the escaped span.
+    assert_eq!(exact_id, &nul_id[..]);
+
+    // Null pointers are rejected, never dereferenced.
+    assert!(unsafe {
+        castrum_session_seal_bytes(
+            std::ptr::null(),
+            0,
+            std::ptr::null(),
+            0,
+            0,
+            std::ptr::null(),
+            0,
+        )
+    }
+    .is_null());
+    assert_eq!(
+        unsafe {
+            castrum_session_open_bytes(
+                std::ptr::null(),
+                0,
+                secret.as_ptr(),
+                secret.len(),
+                buf2.as_mut_ptr(),
+                buf2.len(),
+            )
+        },
+        0
+    );
 }
 
 #[test]

package/rust/ffi/util.rs

@@ -39,6 +39,7 @@ thread_local! {
 
 /// Return a compiled HMAC-SHA256 key for `secret`, reusing a cached copy when
 /// the same secret was used recently (per-thread LRU, cap 16).
+#[cfg(test)]
 #[inline]
 pub(crate) fn hmac_key_cached(secret: &[u8]) -> hmac::Key {
     HMAC_KEY_CACHE.with(|cache| {
@@ -49,11 +50,50 @@ pub(crate) fn hmac_key_cached(secret: &[u8]) -> hmac::Key {
             return key.clone();
         }
         let key = hmac::Key::new(hmac::HMAC_SHA256, secret);
+        // Zeroize the secret bytes of the entry we are about to evict: the raw
+        // key otherwise lingers in the per-thread LRU until eviction.
+        if cache.len() >= HMAC_KEY_CACHE_CAP {
+            if let Some((mut evicted, _)) = cache.pop_lru() {
+                evicted.iter_mut().for_each(|b| *b = 0);
+            }
+        }
         cache.put(secret.to_vec(), key.clone());
         key
     })
 }
 
+/// Run `f` with a reference to the cached compiled key for `secret` WITHOUT
+/// cloning it out of the per-thread LRU (the clone deep-copies the aws-lc
+/// `HMAC_CTX` on every hit). The borrow lives only inside `f`; the cache entry
+/// stays owned by the cache. The callback must not re-enter this cache:
+/// its mutable RefCell borrow is held until `f` returns. If `f` panics,
+/// the borrow is released by unwinding (no poisoning).
+///
+/// On a MISS the key is compiled, inserted, and passed by reference — same
+/// one-time cost as before.
+#[inline]
+pub(crate) fn with_hmac_key_cached<T>(secret: &[u8], f: impl FnOnce(&hmac::Key) -> T) -> T {
+    HMAC_KEY_CACHE.with(|cache| {
+        let mut cache = cache.borrow_mut();
+        if let Some(key) = cache.get(secret) {
+            #[cfg(test)]
+            HMAC_CACHE_HITS.with(|h| h.set(h.get() + 1));
+            return f(key);
+        }
+        let key = hmac::Key::new(hmac::HMAC_SHA256, secret);
+        // Zeroize the raw secret bytes of the evicted entry (the compiled key's
+        // ctx is already wiped on drop by aws-lc-rs; the cache KEY is the raw
+        // secret Vec, which would otherwise linger).
+        if cache.len() >= HMAC_KEY_CACHE_CAP {
+            if let Some((mut evicted, _)) = cache.pop_lru() {
+                evicted.iter_mut().for_each(|b| *b = 0);
+            }
+        }
+        cache.put(secret.to_vec(), key.clone());
+        f(&key)
+    })
+}
+
 /// Map an algorithm selector byte to the AEAD `Algorithm` (0 = AES-256-GCM,
 /// 1 = ChaCha20-Poly1305) — mirrors `crate::crypto::aead::resolve_algorithm`.
 #[inline]

package/rust/http/headers.rs

@@ -216,6 +216,19 @@ mod tests {
         assert_eq!(h.xff(), Some(&b"1.2.3.4"[..]));
     }
 
+    #[test]
+    fn headers_parse_keeps_the_last_duplicate_xff() {
+        // Documented behavior (docs/INGRESS.md trustProxy row): the parser
+        // overwrites on each occurrence, so only the LAST X-Forwarded-For line
+        // is read. A trusted-edge deployment must append only to that line.
+        let packed = pack_headers([
+            ("X-Forwarded-For", "10.0.0.1"),
+            ("X-Forwarded-For", "203.0.113.9"),
+        ]);
+        let h = HeaderRefs::parse(&packed, false, 100).unwrap();
+        assert_eq!(h.xff(), Some(&b"203.0.113.9"[..]));
+    }
+
     #[test]
     fn headers_parse_case_insensitive_names() {
         let packed = pack_headers([("ORIGIN", "https://x.io")]);

package/rust/http/multipart.rs

@@ -356,6 +356,90 @@ pub fn parts_to_packed(parts: &[Part<'_>], out: &mut Vec<u8>) {
     }
 }
 
+/// Packed size of `parts` per `parts_to_packed`'s layout (fixed header +
+/// per-part fields), saturating — used by the C-ABI direct-write path to
+/// size-check the caller's buffer BEFORE any write (no partial output).
+#[inline]
+pub fn parts_packed_len(parts: &[Part<'_>]) -> usize {
+    // [u32 count] + per part: [u32 name_len][name] + [u8 has_filename]
+    // ([u32 filename_len][filename] | [u32 0]) + [u8 has_ct]
+    // ([u32 ct_len][ct] | [u32 0]) + [u32 data_len][data].
+    // The has_* flags are ONE byte each (the Vec path `push`es them) — this
+    // must stay in lockstep with `parts_to_packed_into`'s writer below.
+    let mut len = 4usize;
+    for p in parts {
+        len += 4 + p.name.len();
+        len += 1 + match p.filename {
+            Some(f) => 4 + f.len(),
+            None => 4,
+        };
+        len += 1 + match p.content_type {
+            Some(c) => 4 + c.len(),
+            None => 4,
+        };
+        len += 4 + p.data.len();
+    }
+    len
+}
+
+/// Write `parts` into `out` exactly as [`parts_to_packed`] would, directly
+/// into a caller-provided slice (no intermediate `Vec`, no final memcpy).
+/// Returns bytes written, or `None` when `out` is smaller than needed (the
+/// caller then sizes via [`parts_packed_len`] and retries — needed-size
+/// convention; no partial bytes are written).
+pub fn parts_to_packed_into(parts: &[Part<'_>], out: &mut [u8]) -> Option<usize> {
+    let needed = parts_packed_len(parts);
+    if needed > out.len() {
+        return None;
+    }
+    let mut w = 0usize;
+    macro_rules! put32 {
+        ($v:expr) => {{
+            out[w..w + 4].copy_from_slice(&($v as u32).to_le_bytes());
+            w += 4;
+        }};
+    }
+    put32!(parts.len());
+    for p in parts {
+        put32!(p.name.len());
+        out[w..w + p.name.len()].copy_from_slice(p.name);
+        w += p.name.len();
+        match p.filename {
+            Some(f) => {
+                out[w] = 1;
+                w += 1;
+                put32!(f.len());
+                out[w..w + f.len()].copy_from_slice(f);
+                w += f.len();
+            }
+            None => {
+                out[w] = 0;
+                w += 1;
+                put32!(0);
+            }
+        }
+        match p.content_type {
+            Some(c) => {
+                out[w] = 1;
+                w += 1;
+                put32!(c.len());
+                out[w..w + c.len()].copy_from_slice(c);
+                w += c.len();
+            }
+            None => {
+                out[w] = 0;
+                w += 1;
+                put32!(0);
+            }
+        }
+        put32!(p.data.len());
+        out[w..w + p.data.len()].copy_from_slice(p.data);
+        w += p.data.len();
+    }
+    debug_assert_eq!(w, needed);
+    Some(needed)
+}
+
 /// Parallel multipart parse batch: packed `[u32 count]{[u32 len][body]}` in →
 /// packed `[u32 count]{[u32 len][parts_packed]}` out (same boundary for all).
 #[napi]
@@ -453,6 +537,61 @@ mod tests {
         assert_eq!(packed[8 + name_len], 1); // has filename
     }
 
+    #[test]
+    fn parts_to_packed_into_matches_vec_path() {
+        // The direct-write core must be byte-identical to the Vec-based
+        // serializer for every corpus shape (field-only, file, multi-part).
+        type Shape<'a> = (&'a [u8], Option<&'a [u8]>, Option<&'a [u8]>, &'a [u8]);
+        let shapes: Vec<Vec<Shape<'_>>> = vec![
+            vec![(b"a", None, None, b"1")],
+            vec![(
+                b"file",
+                Some(b"report.pdf"),
+                Some(b"application/pdf"),
+                b"BBBB",
+            )],
+            vec![(b"x", None, None, b""), (b"y", Some(b"y.bin"), None, b"zz")],
+            // Static multi-part corpus with varying field widths (no
+            // generated/borrowed temporaries — every slice is a literal).
+            vec![
+                (b"name_a" as &[u8], None, None, b"AAAAA" as &[u8]),
+                (b"n2", Some(b"n2.bin"), Some(b"text/plain"), b"BBBBBBBBBB"),
+                (b"n3", None, Some(b"application/json"), b"C"),
+            ],
+        ];
+        for parts in &shapes {
+            let owned: Vec<Part<'_>> = parts
+                .iter()
+                .map(|(n, f, c, d)| Part {
+                    name: n,
+                    filename: *f,
+                    content_type: *c,
+                    data: d,
+                })
+                .collect();
+            let mut expected = Vec::new();
+            parts_to_packed(&owned, &mut expected);
+            let mut direct = vec![0u8; expected.len() + 7];
+            let written = parts_to_packed_into(&owned, &mut direct).expect("fits");
+            assert_eq!(written, expected.len());
+            assert_eq!(&direct[..written], &expected[..]);
+            // Too-small buffer → None, no partial writes.
+            let mut small = vec![0u8; expected.len() - 1];
+            assert_eq!(parts_to_packed_into(&owned, &mut small), None);
+            assert!(small.iter().all(|&b| b == 0));
+        }
+    }
+
+    #[test]
+    fn parts_packed_len_matches_parts_to_packed() {
+        let mut b = body("f", Some("a.bin"), Some("text/plain"), b"data123");
+        b.extend_from_slice(b"--\r\n");
+        let parts = parse_multipart(&b, BOUNDARY);
+        let mut expected = Vec::new();
+        parts_to_packed(&parts, &mut expected);
+        assert_eq!(parts_packed_len(&parts), expected.len());
+    }
+
     #[test]
     fn parses_file_with_filename_and_type() {
         let mut b = body(