castrum 0.9.4 → 0.9.7

package/rust/util/bytes.rs

@@ -145,33 +145,55 @@ pub fn decode_percent_at(src: &[u8], i: usize) -> Option<(u8, usize)> {
 
 // ── Form-component decoding ────────────────────────────────────────
 
-/// Decode failure modes for [`decode_form_component_into`].
+/// Decode failure modes for the form-component decoders.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum FormDecodeError {
-    /// Malformed `%XX` sequence (truncated or a non-hex digit).
+    /// Malformed `%XX` (truncated / non-hex digit) or a decoded byte sequence
+    /// that is not valid UTF-8 — exactly what JS's `decodeURIComponent` throws
+    /// `URIError` on. Reported by [`decode_form_component_strict_into`]; the
+    /// lenient [`decode_form_component_into`] answers with the RAW component
+    /// instead (JS's `catch` arm).
     Malformed,
     /// `out` cannot hold the decoded result.
     BufferTooSmall,
 }
 
-/// URL-decode a form component (`+` → space, `%XX` → byte) into `out`,
-/// returning the number of bytes written.
+/// SIMD-accelerated UTF-8 validation (the crate `http::url_codec` already uses,
+/// so the whole HTTP surface validates with the same implementation).
+#[inline]
+fn is_valid_utf8(bytes: &[u8]) -> bool {
+    simdutf8::basic::from_utf8(bytes).is_ok()
+}
+
+/// THE form-component decoder: `+` → space, `%XX` → byte, bulk-copying plain
+/// runs between them, and validating the result's UTF-8 shape.
+///
+/// This is the single place URL-form decoding happens. Its callers differ only
+/// in their FAILURE ARM:
 ///
-/// The decoded length never exceeds `src.len()` (each input byte maps to at
-/// most one output byte). Callers that pre-size `out` to `src.len()` can never
-/// observe [`FormDecodeError::BufferTooSmall`]; callers that pass the remaining
-/// tail of a larger buffer get a precise capacity check against the ACTUAL
-/// decoded length (a `%XX` sequence shrinks 3 input bytes to 1, so a buffer
-/// sized to the decoded form succeeds).
+/// * [`decode_form_component_into`] — lenient, JS `decodeURIComponent`
+///   semantics: `try { decodeURIComponent(s.replace(/\+/g, " ")) } catch { return s }`.
+///   Used by the packed pair parsers (query/form) and the native route stack,
+///   which must answer exactly like the pure-TS fallback.
+/// * [`decode_form_component_strict_into`] — `Malformed` is a real error, for
+///   callers that map a bad component to a 400 (query → JSON).
 ///
-/// Single shared implementation for `query_parser::write_decoded_form_component`
-/// (length-prefixed slice writer) and `json_ser::decode_query_component`
-/// (Vec appender) — the wire decode loop lives in exactly one place.
+/// Keeping one core means the two can never drift apart again — which is how
+/// the packed parser ended up erroring on input the JS fallback happily
+/// returned raw.
+///
+/// `Malformed` is exactly the set JS rejects: a truncated/non-hex `%XX`, and a
+/// decoded sequence that is not valid UTF-8 (overlong encodings, surrogate
+/// halves and > U+10FFFF fail `simdutf8` and `decodeURIComponent` alike).
+///
+/// The decoded length never exceeds `src.len()`, so a caller that sizes `out`
+/// to the input can only observe [`FormDecodeError::BufferTooSmall`] when it
+/// passed a smaller tail of a larger buffer.
 #[inline]
-pub fn decode_form_component_into(
-    src: &[u8],
-    out: &mut [u8],
-) -> std::result::Result<usize, FormDecodeError> {
+fn decode_form_core(src: &[u8], out: &mut [u8]) -> std::result::Result<usize, FormDecodeError> {
+    // Nothing to decode at all (the overwhelming majority of components): a
+    // verbatim copy. No UTF-8 check — an undecoded component is passed through
+    // byte-for-byte, exactly like the JS fallback's `indexOf` early return.
     if memchr::memchr2(b'+', b'%', src).is_none() {
         if out.len() < src.len() {
             return Err(FormDecodeError::BufferTooSmall);
@@ -187,6 +209,9 @@ pub fn decode_form_component_into(
     // input bytes to 1), preserving the existing semantics.
     let mut i = 0usize;
     let mut written = 0usize;
+    // ASCII output is trivially valid UTF-8, so the validator is only paid when
+    // a high byte actually reaches the result (same discipline as `url_codec`).
+    let mut saw_high = false;
     while i < src.len() {
         match memchr::memchr2(b'+', b'%', &src[i..]) {
             Some(rel) => {
@@ -196,6 +221,7 @@ pub fn decode_form_component_into(
                     return Err(FormDecodeError::BufferTooSmall);
                 }
                 out[written..written + run.len()].copy_from_slice(run);
+                saw_high |= !run.is_ascii();
                 written += run.len();
                 i = run_end;
 
@@ -212,6 +238,7 @@ pub fn decode_form_component_into(
                     return Err(FormDecodeError::BufferTooSmall);
                 }
                 out[written] = b;
+                saw_high |= b >= 0x80;
                 written += 1;
                 i = next;
             }
@@ -221,51 +248,136 @@ pub fn decode_form_component_into(
                     return Err(FormDecodeError::BufferTooSmall);
                 }
                 out[written..written + run.len()].copy_from_slice(run);
+                saw_high |= !run.is_ascii();
                 written += run.len();
                 i = src.len();
             }
         }
     }
+    if saw_high && !is_valid_utf8(&out[..written]) {
+        return Err(FormDecodeError::Malformed);
+    }
     Ok(written)
 }
 
-/// Compute the decoded length of `src` WITHOUT writing (mirror of
-/// [`decode_form_component_into`], minus the output). Used by the C-ABI
-/// "needed-size" convention: when a packed/JSON writer hits a too-small output
-/// buffer, the caller runs this exact-size pass ONCE (only on the rare miss)
-/// and reports the required size so the JS wrapper can `growExact` and retry —
-/// no doubling re-run loop, no 9×/8× pre-size.
+/// Copy `src` verbatim into `out` — the raw fallback of the lenient contract.
+#[inline]
+fn write_raw_component(src: &[u8], out: &mut [u8]) -> std::result::Result<usize, FormDecodeError> {
+    if out.len() < src.len() {
+        return Err(FormDecodeError::BufferTooSmall);
+    }
+    out[..src.len()].copy_from_slice(src);
+    Ok(src.len())
+}
+
+/// URL-decode a form component (`+` → space, `%XX` → byte) into `out` with
+/// **JS `decodeURIComponent` fallback semantics**, returning bytes written.
 ///
-/// Same `Malformed` signal on a bad `%XX`, so a caller can disambiguate a
-/// too-small buffer from a real parse error.
+/// Per COMPONENT (name and value decode independently):
+///
+/// 1. no `%` and no `+` → copied verbatim;
+/// 2. otherwise `+` → space and `%XX` → byte;
+/// 3. a malformed escape (truncated or non-hex) → the WHOLE component is
+///    returned RAW — note `+` stays `+`, because JS's `catch` returns the
+///    string it was given, before the `+` replacement;
+/// 4. a decoded sequence that is not valid UTF-8 → the whole component RAW.
+///
+/// That is `try { decodeURIComponent(s.replace(/\+/g, " ")) } catch { return s }`
+/// — the pure-TS fallback swallows the `URIError` and the native path must too,
+/// or a single bad escape turns a public request into a 500 (and a divergent
+/// parse) instead of a raw field.
 #[inline]
-pub fn decode_form_component_len(src: &[u8]) -> std::result::Result<usize, FormDecodeError> {
+pub fn decode_form_component_into(
+    src: &[u8],
+    out: &mut [u8],
+) -> std::result::Result<usize, FormDecodeError> {
+    match decode_form_core(src, out) {
+        Ok(written) => Ok(written),
+        Err(FormDecodeError::Malformed) => write_raw_component(src, out),
+        Err(e) => Err(e),
+    }
+}
+
+/// Compute the decoded length of `src` WITHOUT writing — the exact-size pass for
+/// the C-ABI "needed size" convention (run ONCE on a buffer miss, so the caller
+/// can `growExact` and retry instead of a doubling loop).
+///
+/// Reports [`FormDecodeError::Malformed`] exactly when the writer would (the
+/// raw fallback reports `src.len()`), so the reported size and the written size
+/// can never disagree — a mismatch would make the caller's grow-and-retry loop
+/// spin forever.
+///
+/// One conservative case is deliberate: when the decoded output contains a
+/// non-ASCII byte, the result MAY be invalid UTF-8 and the writer would then
+/// emit the raw component (longer than the decoded form), so `src.len()` is
+/// reported. Over-reporting only costs the caller a few buffer bytes (the C fn
+/// still returns the true written length); under-reporting would hang.
+#[inline]
+pub fn decode_form_component_len(src: &[u8]) -> usize {
     if memchr::memchr2(b'+', b'%', src).is_none() {
-        return Ok(src.len());
+        return src.len();
     }
     let mut i = 0usize;
     let mut written = 0usize;
+    let mut saw_high = false;
     while i < src.len() {
         match memchr::memchr2(b'+', b'%', &src[i..]) {
             Some(rel) => {
+                let run_end = i + rel;
                 written += rel;
-                i += rel;
-                let next = match src[i] {
-                    b'+' => i + 1,
-                    _ => decode_percent_at(src, i)
-                        .map(|(_, next)| next)
-                        .ok_or(FormDecodeError::Malformed)?,
-                };
-                written += 1;
-                i = next;
+                saw_high |= !src[i..run_end].is_ascii();
+                i = run_end;
+                match src[i] {
+                    b'+' => {
+                        written += 1;
+                        i += 1;
+                    }
+                    _ => match decode_percent_at(src, i) {
+                        Some((byte, next)) => {
+                            written += 1;
+                            saw_high |= byte >= 0x80;
+                            i = next;
+                        }
+                        // Malformed → the writer emits the raw component, so
+                        // the raw length is the exact answer here.
+                        None => return src.len(),
+                    },
+                }
             }
             None => {
                 written += src.len() - i;
+                saw_high |= !src[i..].is_ascii();
                 i = src.len();
             }
         }
     }
-    Ok(written)
+    if saw_high {
+        src.len()
+    } else {
+        written
+    }
+}
+
+/// Decode a form component into a reusable scratch buffer, returning the
+/// decoded bytes — or `src` itself when nothing needed decoding. The shared
+/// entry point for Vec-based callers (the native route stack); the returned
+/// slice borrows either `src` or `scratch`, so it is valid only until the next
+/// call with the same scratch.
+#[inline]
+pub fn decode_form_component_scratch<'a>(src: &'a [u8], scratch: &'a mut Vec<u8>) -> &'a [u8] {
+    // Fast path: nothing to decode (the overwhelming majority of segments).
+    if memchr::memchr2(b'+', b'%', src).is_none() {
+        return src;
+    }
+    if scratch.len() < src.len() {
+        scratch.resize(src.len(), 0);
+    }
+    match decode_form_component_into(src, scratch.as_mut_slice()) {
+        Ok(n) => &scratch[..n],
+        // Unreachable: the buffer is input-sized, and the decoded length never
+        // exceeds the input.
+        Err(_) => src,
+    }
 }
 
 // ── Whitespace + cookie splitting ──────────────────────────────────
@@ -350,23 +462,98 @@ mod tests {
         assert_eq!(decode(b"%41%42"), b"AB");
         assert_eq!(decode(b"q=%E2%9C%93"), b"q=\xE2\x9C\x93");
         assert_eq!(decode(b"%2B"), b"+");
+        // A NUL is a legal decode target (U+0000), not an error.
+        assert_eq!(decode(b"%00"), b"\x00");
+        assert_eq!(decode(b"%2f"), b"/");
     }
 
     #[test]
-    fn decode_form_malformed_percent() {
-        let mut out = [0u8; 8];
-        assert_eq!(
-            decode_form_component_into(b"%ZZ", &mut out),
-            Err(FormDecodeError::Malformed)
-        );
-        assert_eq!(
-            decode_form_component_into(b"%4", &mut out),
-            Err(FormDecodeError::Malformed)
-        );
-        assert_eq!(
-            decode_form_component_into(b"x%", &mut out),
-            Err(FormDecodeError::Malformed)
-        );
+    fn decode_form_decodeuri_semantics_table() {
+        // The contract is `try { decodeURIComponent(s.replace(/\+/g," ")) }
+        // catch { return s }` — verified against Bun's `decodeURIComponent`.
+        let cases: &[(&[u8], &[u8])] = &[
+            // (input, JS result)
+            (b"a=%C3", b"a=%C3"), // truncated multibyte → URIError → raw
+            (b"a=%2", b"a=%2"),   // truncated escape → raw
+            (b"a=%", b"a=%"),     // dangling % → raw
+            (b"a=%2G", b"a=%2G"), // non-hex digit → raw
+            (b"a=%FF", b"a=%FF"), // invalid UTF-8 byte → raw
+            (b"a=%ED%A0%80", b"a=%ED%A0%80"), // surrogate half → raw
+            (b"a=%C0%80", b"a=%C0%80"), // overlong encoding → raw
+            (b"a=%F4%90%80%80", b"a=%F4%90%80%80"), // > U+10FFFF → raw
+            (b"bad=%ZZ", b"bad=%ZZ"), // non-hex → raw
+            (b"100%", b"100%"),   // trailing % → raw
+            // The whole component goes raw — including a '+' that the decode
+            // would otherwise have turned into a space (the JS catch returns
+            // the string it was given, before the replace).
+            (b"a+b=%ZZ", b"a+b=%ZZ"),
+            (b"a+b=%20", b"a b= "),   // valid → decoded
+            (b"%C3%A9", b"\xC3\xA9"), // valid multibyte → decoded
+        ];
+        for (input, expected) in cases {
+            assert_eq!(
+                decode(input).as_slice(),
+                *expected,
+                "lenient decode of {:?}",
+                core::str::from_utf8(input).unwrap_or("<non-utf8>")
+            );
+        }
+    }
+
+    #[test]
+    fn decode_form_needed_size_matches_written_size() {
+        // The C-ABI "needed size" pass must equal what the writer produces for
+        // EVERY input — a mismatch would spin the caller's grow-and-retry loop.
+        // It may only over-report (never under-report) when the decoded form
+        // could be invalid UTF-8.
+        let cases: &[&[u8]] = &[
+            b"",
+            b"a",
+            b"a=1&b=2",
+            b"%ZZ",
+            b"a=%C3",
+            b"a=%FF",
+            b"a=%ED%A0%80",
+            b"q=hello+world",
+            b"u=%E2%9C%93",
+            b"\xFF\xFE", // non-UTF-8 passthrough
+            b"a=%E2%9C%93&b%ZZ=1",
+            b"x%",
+        ];
+        for src in cases {
+            let mut out = vec![0u8; src.len() + 16];
+            let written = decode_form_component_into(src, &mut out).unwrap();
+            let reported = decode_form_component_len(src);
+            assert!(
+                reported >= written,
+                "reported {reported} < written {written} for {:?}",
+                core::str::from_utf8(src).unwrap_or("<non-utf8>")
+            );
+            // An exact-size buffer must succeed and agree with the report.
+            let mut exact = vec![0u8; reported];
+            assert_eq!(
+                decode_form_component_into(src, &mut exact).unwrap(),
+                written,
+                "exact-size decode disagreed for {:?}",
+                core::str::from_utf8(src).unwrap_or("<non-utf8>")
+            );
+        }
+    }
+
+    #[test]
+    fn decode_form_scratch_matches_slice_decoder() {
+        let mut scratch: Vec<u8> = Vec::new();
+        for input in [
+            &b"plain"[..],
+            b"a+b",
+            b"a=%20b",
+            b"%ZZ",
+            b"%C3",
+            b"a=%E2%9C%93",
+        ] {
+            let via_scratch = decode_form_component_scratch(input, &mut scratch).to_vec();
+            assert_eq!(via_scratch.as_slice(), decode(input).as_slice());
+        }
     }
 
     #[test]

package/src/ingress/health.ts

@@ -49,10 +49,9 @@ export function readinessHandler(check?: () => boolean | Promise<boolean>) {
       return ok
         ? jsonResponse(200, { status: 'ready' })
         : jsonResponse(503, { status: 'not_ready' })
-    } catch (err) {
+    } catch (_err) {
       return jsonResponse(503, {
         status: 'not_ready',
-        error: err instanceof Error ? err.message : String(err),
       })
     }
   }

package/src/native/ffi/build/codecs.ts

@@ -9,7 +9,7 @@ import { decodeUtf8, encodeUtf8 } from '../../../shared/codec'
 import { SELFTEST_HEX, SELFTEST_JSON } from '../constants'
 import type { BunFFI, Raw3, Raw4, Raw5, Raw6, Raw8, Raw9, Raw10, RawCStr } from '../types'
 import type { BuildCtx } from './util'
-import { allocOut, argon2PhcLength, cstr, flag, growExact, writeOrThrow } from './util'
+import { allocOut, argon2PhcLength, cstr, flag, growExact, hasNul, writeOrThrow } from './util'
 
 /**
  * Build the codec/crypto/auth methods of the BunFFI surface. `ctx` is
@@ -182,10 +182,14 @@ export function buildCodecs(
     },
     urlEncodeInto,
 
-    validateEmail: (input) => Number(validateEmail(input)) === 1,
-    validateUuid: (input) => Number(validateUuid(input)) === 1,
-    validateIpv4: (input) => Number(validateIpv4(input)) === 1,
-    validateIpv6: (input) => Number(validateIpv6(input)) === 1,
+    // Verdict guards: the `cstring` form would truncate at an embedded NUL, so
+    // `"a@b.com\0<script>"` would be reported VALID — a verdict callers act on.
+    // No address / UUID / IP contains U+0000, so short-circuit without an FFI
+    // call (one `indexOf` scan, far cheaper than the encode fallback).
+    validateEmail: (input) => !hasNul(input) && Number(validateEmail(input)) === 1,
+    validateUuid: (input) => !hasNul(input) && Number(validateUuid(input)) === 1,
+    validateIpv4: (input) => !hasNul(input) && Number(validateIpv4(input)) === 1,
+    validateIpv6: (input) => !hasNul(input) && Number(validateIpv6(input)) === 1,
     // Byte-input validators: `(ptr,len)` — zero transcode (no CString decode
     // + engine re-encode like the cstring-ARG string forms above).
     validateEmailBytes: (input) => Number(oneArg(validateEmailBytes, input)) === 1,
@@ -212,12 +216,30 @@ export function buildCodecs(
       return w
     },
     // Zero-copy text path: cstring ARG in (engine-transcoded), cstring return
-    // out (engine-cloned) — the JS side does zero encode AND zero decode.
-    regexEscapeStr: (input) => regexEscapeStrRaw(input),
+    // out (engine-cloned) — the JS side does zero encode AND zero decode. A NUL
+    // would truncate the INPUT, so that case routes to the `(ptr,len)` sibling
+    // (exact length) instead of returning a silently shortened string.
+    regexEscapeStr: (input) => {
+      if (!hasNul(input)) return regexEscapeStrRaw(input)
+      const bytes = encodeUtf8(input)
+      const escaped = growExact(
+        (out) => Number(regexEscapeRaw(bytes, lenOrView(bytes), out, lenOrView(out))),
+        16,
+        1 << 20,
+        'regex escape: output buffer too small',
+      )
+      return decodeUtf8(escaped)
+    },
     hexValidateBatchStr(ids, width, output) {
       if (width === 0 || width > 4096) {
         throw new Error('hex validate batch: width must be 1..=4096')
       }
+      // A NUL in the joined ids would truncate the line list, so a bad id could
+      // pass as its own prefix. Fall back to the byte form (exact length).
+      if (hasNul(ids)) {
+        const bytes = encodeUtf8(ids)
+        return Number(hexBatchRaw(bytes, lenOrView(bytes), width >>> 0, output, lenOrView(output)))
+      }
       const w = Number(hexBatchStrRaw(ids, width >>> 0, output, lenOrView(output)))
       return w
     },

package/src/native/ffi/build/compress.ts

@@ -117,6 +117,14 @@ export function buildCompress(
       }
       return w
     },
+    /**
+     * gzip ISIZE probe → uncompressed size for a single-member stream, or `0`
+     * when unknown. Used to PRE-SIZE a destination buffer for the zero-copy
+     * task path (one pass, no intermediate buffer, no retry in the common case).
+     */
+    gzipIsize(data) {
+      return Number(gzipIsize(data, lenOrView(data)))
+    },
     brotliCompress(data, quality = 5) {
       // Same cap rationale as gzipCompress (streaming core); growExact for
       // incompressible data.

package/src/native/ffi/build/instances.ts

@@ -10,7 +10,7 @@ import { decodeUtf8, encodeUtf8 } from '../../../shared/codec'
 import { EMPTY_VIEW } from '../constants'
 import type { BunFFI, Raw2, Raw3, Raw4, Raw5, Raw6, Raw7, Raw8, Raw12, RawCStr } from '../types'
 import type { BuildCtx } from './util'
-import { cstr, growExact, unpackRateCheck } from './util'
+import { cstr, growExact, hasNul, unpackRateCheck } from './util'
 
 /**
  * Build the opaque-handle methods of the BunFFI surface. `ctx` is destructured
@@ -41,6 +41,8 @@ export function buildInstances(
   const cookieValidateSym = sym.castrum_cookie_validate as (...a: unknown[]) => number | bigint
   const sessionSealSym = sym.castrum_session_seal as (...a: unknown[]) => string | null
   const sessionOpenSym = sym.castrum_session_open as Raw4
+  const sessionSealBytesSym = sym.castrum_session_seal_bytes as RawCStr
+  const sessionOpenBytesSym = sym.castrum_session_open_bytes as Raw6
   const rateLimiterCheckRaw = sym.castrum_rate_limiter_check as Raw5
   const rateLimiterCheckKeyRaw = sym.castrum_rate_limiter_check_key as Raw5
   const jwtSignBytes = sym.castrum_jwt_sign_bytes as RawCStr
@@ -144,10 +146,15 @@ export function buildInstances(
       return Number(schemaValidatorValidateRaw(inner, doc, lenOrView(doc))) === 1
     },
     queryValidate(inner, qs) {
-      // `qs` is a cstring ARG — engine-transcoded (zero JS encode).
+      // `qs` is a cstring ARG — engine-transcoded (zero JS encode). A raw NUL is
+      // not a valid query byte, and it would TRUNCATE the arg so only a prefix
+      // got validated: a gate that says "this query passed" must not be foolable.
+      if (hasNul(qs)) return false
       return Number(queryValidateSym(inner, qs)) === 1
     },
     cookieValidate(inner, header) {
+      // Same contract as `queryValidate`: a NUL would validate only a prefix.
+      if (hasNul(header)) return false
       return Number(cookieValidateSym(inner, header)) === 1
     },
     sessionSeal(id, dataJson, expSecs, secret) {
@@ -159,6 +166,33 @@ export function buildInstances(
       const w = Number(sessionOpenSym(token, secret, output, lenOrView(output)))
       return w
     },
+    sessionSealBytes(id, dataJson, expSecs, secret) {
+      // Byte-arg form: exact lengths, no engine transcode, no NUL truncation.
+      // The parity with `sessionSeal` is asserted in the bind-time self-test
+      // below (same core ⇒ byte-identical token for identical inputs).
+      return sessionSealBytesSym(
+        id,
+        lenOrView(id),
+        dataJson,
+        lenOrView(dataJson),
+        BigInt(expSecs),
+        secret,
+        lenOrView(secret),
+      )
+    },
+    sessionOpenBytes(token, secret, output) {
+      // Needed-size convention; 0 = bad signature / malformed.
+      return Number(
+        sessionOpenBytesSym(
+          token,
+          lenOrView(token),
+          secret,
+          lenOrView(secret),
+          output,
+          lenOrView(output),
+        ),
+      )
+    },
     rateLimiterCheck(inner, key, nowMs) {
       // Packed [u8 allowed][u32 remaining LE][i64 reset_ms LE] (13 bytes).
       // Reused scratch + cached DataView (no per-call allocs). `key` is a
@@ -618,6 +652,24 @@ export function selfTestInstances(b: BunFFI): boolean {
     if (w <= 13 || out[0] !== 1) return false
     // bad signature → 0
     if (b.sessionOpen(tok, 'wrong', out) !== 0) return false
+
+    // Byte-arg siblings. Both forms share ONE core, so the sealed token must be
+    // byte-identical — the strongest available parity check between the two.
+    const enc = new TextEncoder()
+    const tokB = b.sessionSealBytes(
+      enc.encode('sess-9'),
+      enc.encode('{"n":1}'),
+      1234567,
+      enc.encode('sekrit'),
+    )
+    if (tokB === null || tokB !== tok) return false
+    const outB = new Uint8Array(256)
+    const wB = b.sessionOpenBytes(enc.encode(tokB), enc.encode('sekrit'), outB)
+    if (wB !== w || outB[0] !== 1) return false
+    // Bad signature → 0; a too-small buffer reports the EXACT size, not 0.
+    if (b.sessionOpenBytes(enc.encode(tokB), enc.encode('wrong'), outB) !== 0) return false
+    if (b.sessionOpenBytes(enc.encode(tokB), enc.encode('sekrit'), outB.subarray(0, 4)) !== wB)
+      return false
   }
 
   // rateLimiterCheckKey: null (0) handle → throw (ABI exercise).

package/src/native/ffi/build/metrics.ts

@@ -9,6 +9,18 @@
 import { decodeUtf8, encodeUtf8 } from '../../../shared/codec'
 import type { BunFFI, Raw0, Raw3, Raw4, Raw5 } from '../types'
 import type { BuildCtx } from './util'
+import { hasNul } from './util'
+
+/**
+ * Declare-time NUL guard: a metric NAME or label-key set containing `U+0000`
+ * would be truncated by the `cstring` arg, silently colliding two series. This
+ * runs once at declaration, so failing fast costs nothing on the hot path.
+ */
+function throwIfNul(value: string, what: string): void {
+  if (hasNul(value)) {
+    throw new Error(`metrics: ${what} must not contain a NUL character (U+0000)`)
+  }
+}
 
 /**
  * Sentinel returned by the declare fns (`u32::MAX`) on invalid input — fits
@@ -59,12 +71,18 @@ export function buildMetrics(
       return h
     },
     metricsCounter(handle, name, labelKeys) {
+      throwIfNul(name, 'counter name')
+      throwIfNul(labelKeys, 'counter label keys')
       return declareOrThrow(metricsCounterRaw(handle, name, labelKeys), `counter "${name}"`)
     },
     metricsGauge(handle, name, labelKeys) {
+      throwIfNul(name, 'gauge name')
+      throwIfNul(labelKeys, 'gauge label keys')
       return declareOrThrow(metricsGaugeRaw(handle, name, labelKeys), `gauge "${name}"`)
     },
     metricsHistogram(handle, name, labelKeys, bucketsCsv) {
+      throwIfNul(name, 'histogram name')
+      throwIfNul(labelKeys, 'histogram label keys')
       return declareOrThrow(
         metricsHistogramRaw(handle, name, labelKeys, bucketsCsv),
         `histogram "${name}"`,
@@ -79,9 +97,14 @@ export function buildMetrics(
     },
     metricsRecordStr(handle, series, values, amount) {
       // `values` is the JOINED `\x1f` string — engine-transcoded (zero encode).
+      // Label values come from user data, so a NUL would truncate the join and
+      // silently record the WRONG series (the native side rejects a NUL value,
+      // but only if it ever sees it). Fail loudly and say why.
+      throwIfNul(values, 'label values')
       return Number(metricsRecordStrRaw(handle, series, values, amount)) === 1
     },
     metricsGaugeSetStr(handle, series, values, value) {
+      throwIfNul(values, 'label values')
       return Number(metricsGaugeSetStrRaw(handle, series, values, value)) === 1
     },
     metricsRender(handle, output) {
@@ -136,23 +159,19 @@ export function selfTestMetrics(b: BunFFI): boolean {
       return false
     }
 
-    console.error('CK: counter')
     const gauge = b.metricsGauge(handle, 'ct_selftest_depth', 'q')
     if (gauge === METRICS_DECLARE_ERR) return false
     if (!b.metricsGaugeSet(handle, gauge, encodeUtf8('jobs'), 4)) return false
     if (!b.metricsGaugeSetStr(handle, gauge, 'io', 6)) return false
 
-    console.error('CK: gauge')
     const hist = b.metricsHistogram(handle, 'ct_selftest_latency', '', '0.1,0.5')
     if (hist === METRICS_DECLARE_ERR) return false
     if (!b.metricsRecord(handle, hist, EMPTY, 0.25)) return false
     if (b.metricsRecord(handle, hist, EMPTY, -1)) return false // negatives rejected
 
-    console.error('CK: hist')
     // Arity mismatch must fail safely.
     if (b.metricsRecord(handle, counter, encodeUtf8('/a'), 1)) return false
 
-    console.error('CK: arity')
     // Render: probe with a small buffer → exact required size; then render.
     const probe = new Uint8Array(16)
     const needed = b.metricsRender(handle, probe)
@@ -172,7 +191,6 @@ export function selfTestMetrics(b: BunFFI): boolean {
       return false
     }
 
-    console.error('CK: render')
     // Snapshot: packed dump starts with version=1 + familyCount>=3.
     {
       const probe2 = new Uint8Array(16)
@@ -185,7 +203,6 @@ export function selfTestMetrics(b: BunFFI): boolean {
       if (sv.getUint32(4, true) < 3) return false
     }
 
-    console.error('CK: snapshot')
     // Batch: two entries in ONE crossing.
     {
       const c2 = b.metricsCounter(handle, 'ct_selftest_batch', 'k')
@@ -206,7 +223,6 @@ export function selfTestMetrics(b: BunFFI): boolean {
       }
     }
 
-    console.error('CK: batch')
     // A null handle must throw on declare (never dereference freed state).
     try {
       b.metricsCounter(0, 'ct_selftest_x', '')