castrum 0.9.6 → 0.9.7

package/Cargo.lock

@@ -233,7 +233,7 @@ checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04"
 
 [[package]]
 name = "castrum"
-version = "0.9.6"
+version = "0.9.7"
 dependencies = [
  "argon2",
  "aws-lc-rs",
@@ -1075,13 +1075,14 @@ dependencies = [
 
 [[package]]
 name = "napi"
-version = "3.11.0"
+version = "3.12.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "de33522036981030a75c231829566bc63414e08101a6f5ff4ac6cef19c8e0941"
+checksum = "58c5f4d5375213fdb7be2655e152386e82f026f9a5ba36a75556e11359aafe09"
 dependencies = [
  "bitflags",
  "ctor",
  "futures",
+ "libc",
  "napi-build",
  "napi-sys",
  "nohash-hasher",

package/Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "castrum"
 # Keep in sync with package.json "version" (single source of truth: the npm package).
-version = "0.9.6"
+version = "0.9.7"
 edition = "2021"
 # Keep in sync with package.json "license" (cargo-deny rejects a crate with no
 # license expression).

package/dist/index.js

@@ -1085,6 +1085,8 @@ function buildInstances(sym, ctx) {
   const cookieValidateSym = sym.castrum_cookie_validate;
   const sessionSealSym = sym.castrum_session_seal;
   const sessionOpenSym = sym.castrum_session_open;
+  const sessionSealBytesSym = sym.castrum_session_seal_bytes;
+  const sessionOpenBytesSym = sym.castrum_session_open_bytes;
   const rateLimiterCheckRaw = sym.castrum_rate_limiter_check;
   const rateLimiterCheckKeyRaw = sym.castrum_rate_limiter_check_key;
   const jwtSignBytes = sym.castrum_jwt_sign_bytes;
@@ -1151,6 +1153,12 @@ function buildInstances(sym, ctx) {
       const w = Number(sessionOpenSym(token, secret, output, lenOrView(output)));
       return w;
     },
+    sessionSealBytes(id, dataJson, expSecs, secret) {
+      return sessionSealBytesSym(id, lenOrView(id), dataJson, lenOrView(dataJson), BigInt(expSecs), secret, lenOrView(secret));
+    },
+    sessionOpenBytes(token, secret, output) {
+      return Number(sessionOpenBytesSym(token, lenOrView(token), secret, lenOrView(secret), output, lenOrView(output)));
+    },
     rateLimiterCheck(inner, key, nowMs) {
       const out = rateScratch;
       const w = Number(rateLimiterCheckRaw(inner, key, BigInt(Math.trunc(nowMs)), out, lenOrView(out)));
@@ -1404,6 +1412,18 @@ function selfTestInstances(b) {
       return false;
     if (b.sessionOpen(tok, "wrong", out) !== 0)
       return false;
+    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;
+    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;
   }
   let rlKeyThrew = false;
   try {
@@ -1528,7 +1548,6 @@ function selfTestMetrics(b) {
       console.error("FAIL: recordStr");
       return false;
     }
-    console.error("CK: counter");
     const gauge = b.metricsGauge(handle, "ct_selftest_depth", "q");
     if (gauge === METRICS_DECLARE_ERR)
       return false;
@@ -1536,7 +1555,6 @@ function selfTestMetrics(b) {
       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;
@@ -1544,10 +1562,8 @@ function selfTestMetrics(b) {
       return false;
     if (b.metricsRecord(handle, hist, EMPTY, -1))
       return false;
-    console.error("CK: hist");
     if (b.metricsRecord(handle, counter, encodeUtf8("/a"), 1))
       return false;
-    console.error("CK: arity");
     const probe = new Uint8Array(16);
     const needed = b.metricsRender(handle, probe);
     if (needed <= probe.length)
@@ -1566,7 +1582,6 @@ function selfTestMetrics(b) {
 `)) {
       return false;
     }
-    console.error("CK: render");
     {
       const probe2 = new Uint8Array(16);
       const need = b.metricsSnapshot(handle, probe2);
@@ -1581,7 +1596,6 @@ function selfTestMetrics(b) {
       if (sv.getUint32(4, true) < 3)
         return false;
     }
-    console.error("CK: snapshot");
     {
       const c2 = b.metricsCounter(handle, "ct_selftest_batch", "k");
       const buf = new Uint8Array(64);
@@ -1601,7 +1615,6 @@ function selfTestMetrics(b) {
         return false;
       }
     }
-    console.error("CK: batch");
     try {
       b.metricsCounter(0, "ct_selftest_x", "");
       return false;
@@ -2712,6 +2725,14 @@ function bind(forcedPath, tried = []) {
         args: abi(["cstring", "cstring", "ptr", "usize"]),
         returns: U64_FAST
       },
+      castrum_session_seal_bytes: {
+        args: abi(["ptr", "usize", "ptr", "usize", "i64", "ptr", "usize"]),
+        returns: "cstring"
+      },
+      castrum_session_open_bytes: {
+        args: abi(["ptr", "usize", "ptr", "usize", "ptr", "usize"]),
+        returns: U64_FAST
+      },
       castrum_task_init: { args: ["u32"], returns: "u32" },
       castrum_task_submit: { args: abi(["u32", "ptr", "usize", "usize"]), returns: "u32" },
       castrum_task_submit_slice: {

package/docs/ARCHITECTURE.md

@@ -31,7 +31,7 @@ The bridge between TypeScript and Rust has **two transports**, both loading the
 cdylib (built with napi-rs):
 
 - **`bun:ffi` (PRIMARY on Bun)** — `src/native/ffi.ts` `dlopen`s the addon's
-  `extern "C"` exports (`rust/ffi/`, 119 `castrum_*` symbols — 107 direct + 4
+  `extern "C"` exports (`rust/ffi/`, 121 `castrum_*` symbols — 109 direct + 4
   `validator_c_abi!` + 4 `validator_bytes_c_abi!` + 4 `compress_to_out!`,
   parity guarded by
   `test/unit/native/ffi-symbol-parity.test.ts`) and Bun JIT-calls them

package/docs/CASE_STUDY.md

@@ -44,7 +44,7 @@ as a pre-baked pipeline, and still be usable from both runtimes.
 ### 2.1 One cdylib, two transports
 
 The addon is built with napi-rs (so Node can load it), but it *also* exports
-`extern "C"` symbols (`rust/ffi/`, **119 `castrum_*` symbols** — 107 direct + 4
+`extern "C"` symbols (`rust/ffi/`, **121 `castrum_*` symbols** — 109 direct + 4
 `validator_c_abi!` + 4 `validator_bytes_c_abi!` + 4 `compress_to_out!`) so Bun can
 `dlopen` it directly:
 

package/docs/FFI_BUN_GUIDE.md

@@ -240,6 +240,18 @@ measuring the bare binding suggested the opposite. **Measure through the functio
 users call, not the binding** — the guard itself costs ~4 ns, so guarding is
 cheap and routing everything through bytes is not always a win.
 
+**A second measured instance: the session seal/open siblings (0.9.7).** They
+land in the same place, and the hinge is the caller's own encode. Through the
+real call path, 200k calls, ns/call: one short-string `TextEncoder.encode`
+costs 45.4; `session_seal` is 613.5 via `cstring` versus 557.8 via
+`castrum_session_seal_bytes` when every argument is ALREADY bytes (−9.1%), but
+620.6 when the caller re-encodes its JS strings per call (**+1.2%, slower**).
+`session_open` mirrors it: 568.5 / 501.1 (−11.9%) / 579.5 (+1.9%). So ~45 ns of
+encode against ~45–67 ns of transcode: the byte form pays only for a caller that
+already holds bytes. Byte-identical tokens between the two forms was asserted at
+runtime (`parity: true`), so the siblings are a correctness escape hatch — the
+NUL case, or a caller that already owns buffers — never a blanket migration.
+
 **Rule**: a `cstring` ARG is only correct when truncation cannot change the
 answer — i.e. the string is developer-supplied config or NUL-free by
 construction (a MIME extension, a base64 key, a header name). Anything

package/docs/HOW_TO_ADD_AN_OP.md

@@ -13,6 +13,30 @@ guards fail.
 
 ---
 
+### ⚠️ Rebuild BOTH binaries before binding anything
+
+`bun run build` writes the **baseline** addon only. The loader CPU-detects and
+PREFERS the x86-64-v3 SIMD variant (`castrum.linux-x64-v3-gnu.node`, built by
+`bun run build:v3`) on any AVX2 host — i.e. essentially every modern x86-64
+machine, including CI runners.
+
+A stale v3 binary therefore ships the OLD symbol table, and the failure mode is
+**not** a clean "missing symbol" error: `bun:ffi` binds against it, the first call
+jumps through a missing symbol, and the process **SIGSEGVs** — often at teardown,
+with every test passing. Observed while adding
+`castrum_session_{seal,open}_bytes`: `test/compat` printed `9 pass / 0 fail` and
+then died, `gdb` showing the fault inside `castrum.linux-x64-v3-gnu.node`.
+
+So: after adding or changing ANY `castrum_*` export, rebuild with
+`bun run build:all` (baseline + v3). If you hit a segfault with no failing test,
+check this FIRST — it is much cheaper than bisecting the ABI:
+
+```bash
+nm -D --defined-only castrum.linux-x64-v3-gnu.node | grep <your_symbol>
+```
+
+---
+
 ## 0. The six wiring points at a glance
 
 | # | File | What you add |

package/docs/REPO_MAP.md

@@ -178,7 +178,7 @@ rust/                     ONE cdylib crate (Cargo [lib] → lib.rs).
                           CASTRUM_TASK_THREADS, batch dequeue + spin-then-park + optional
                           CASTRUM_TASK_PIN_CORES), result ring + batched thread-safe doorbell,
                           op dispatch + cancel + catch_unwind containment + `_into` ops.
-  ffi/                    #[no_mangle] extern "C" exports (119 castrum_* symbols — 107 direct + 4
+  ffi/                    #[no_mangle] extern "C" exports (121 castrum_* symbols — 109 direct + 4
                           validator_c_abi! + 4 validator_bytes_c_abi! + 4 compress_to_out!; parity guarded by
                           test/unit/native/ffi-symbol-parity.test.ts) for Bun's bun:ffi
                           primary transport, incl. castrum_ingress_layout (the layout blob).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "castrum",
-  "version": "0.9.6",
+  "version": "0.9.7",
   "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",

package/rust/crypto/session.rs

@@ -83,13 +83,10 @@ pub fn open_core(token: &[u8], secret: &[u8]) -> Option<(i64, Vec<u8>, Vec<u8>)>
                         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;
+                        let body = pos + 1;
+                        let end = scan_json_string_end(bytes, body)?;
+                        id = Some(unescape_json_id(&bytes[body..end]));
+                        pos = end + 1;
                     }
                     b"exp" => {
                         let vs = pos;
@@ -174,6 +171,108 @@ fn skip_json_value(bytes: &[u8], pos: usize) -> Option<usize> {
     }
 }
 
+/// Index of the `"` that TERMINATES a JSON string whose body starts at `start`
+/// (just past the opening quote).
+///
+/// Escape-aware: the id used to be captured by scanning for the next `"`, which
+/// stops at the quote inside an escaped `\"` — truncating the id AND leaving
+/// `pos` in the middle of the string, so the rest of the envelope was then read
+/// as structure (a quote-carrying id could make `open` fail outright).
+fn scan_json_string_end(bytes: &[u8], start: usize) -> Option<usize> {
+    let mut i = start;
+    while i < bytes.len() {
+        match bytes[i] {
+            b'\\' => i += 2,
+            b'"' => return Some(i),
+            _ => i += 1,
+        }
+    }
+    None
+}
+
+/// Decode 4 hex digits at `at` (the `\uXXXX` payload).
+fn hex4(bytes: &[u8], at: usize) -> Option<u32> {
+    let mut v = 0u32;
+    for k in 0..4 {
+        v = (v << 4) | (*bytes.get(at + k)? as char).to_digit(16)?;
+    }
+    Some(v)
+}
+
+/// Inverse of `json_ser::write_json_escaped` for the id: decodes `\"`, `\\`,
+/// `\/`, `\b`, `\f`, `\n`, `\r`, `\t` and `\uXXXX`.
+///
+/// `\u00XX` maps back to the single BYTE `XX`. That is deliberate and load
+/// bearing: the escaper emits that form for control characters AND — in its
+/// invalid-UTF-8 mode — for every byte of binary input, so routing it through a
+/// code point and re-encoding as UTF-8 would expand bytes >= 0x80 into two
+/// bytes and destroy the byte-exact round trip the id is supposed to have.
+/// (A valid-UTF-8 id is written RAW by the escaper, so `\u00XX` cannot be its
+/// origin.)
+///
+/// `\uXXXX` above 0xFF can only come from a different producer (e.g. JS
+/// `JSON.stringify` of a non-ASCII id), so it is decoded as a code point with
+/// surrogate-pair combining. Unknown escapes and a trailing backslash are kept
+/// verbatim — never silently dropped.
+fn unescape_json_id(escaped: &[u8]) -> Vec<u8> {
+    let mut out = Vec::with_capacity(escaped.len());
+    let mut i = 0usize;
+    while i < escaped.len() {
+        if escaped[i] != b'\\' {
+            out.push(escaped[i]);
+            i += 1;
+            continue;
+        }
+        let Some(&e) = escaped.get(i + 1) else {
+            out.push(b'\\');
+            break;
+        };
+        i += 2;
+        match e {
+            b'"' => out.push(b'"'),
+            b'\\' => out.push(b'\\'),
+            b'/' => out.push(b'/'),
+            b'b' => out.push(0x08),
+            b'f' => out.push(0x0c),
+            b'n' => out.push(b'\n'),
+            b'r' => out.push(b'\r'),
+            b't' => out.push(b'\t'),
+            b'u' => {
+                let Some(cp) = hex4(escaped, i) else {
+                    out.push(b'\\');
+                    out.push(b'u');
+                    continue;
+                };
+                i += 4;
+                if cp <= 0xFF {
+                    out.push(cp as u8);
+                    continue;
+                }
+                let mut code = cp;
+                if (0xD800..=0xDBFF).contains(&cp)
+                    && escaped.get(i) == Some(&b'\\')
+                    && escaped.get(i + 1) == Some(&b'u')
+                {
+                    if let Some(lo) = hex4(escaped, i + 2) {
+                        if (0xDC00..=0xDFFF).contains(&lo) {
+                            code = 0x10000 + ((cp - 0xD800) << 10) + (lo - 0xDC00);
+                            i += 6;
+                        }
+                    }
+                }
+                let mut buf = [0u8; 4];
+                let ch = char::from_u32(code).unwrap_or('\u{FFFD}');
+                out.extend_from_slice(ch.encode_utf8(&mut buf).as_bytes());
+            }
+            other => {
+                out.push(b'\\');
+                out.push(other);
+            }
+        }
+    }
+    out
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -209,6 +308,64 @@ mod tests {
         assert!(seal_core(b"", b"{}", 0, SECRET).is_none());
     }
 
+    #[test]
+    fn id_round_trips_byte_exactly_through_escapes() {
+        // A `"` used to terminate the id scan early, and the id came back
+        // escaped. Both are the same root cause: an escape-unaware scan with no
+        // decode. Every id here must survive the envelope byte-for-byte.
+        for id in [
+            &b"plain-id"[..],
+            &b"sess\"quote"[..],
+            &b"back\\slash"[..],
+            &b"new\nline"[..],
+            &b"tab\there"[..],
+            &b"cr\rhere"[..],
+            &b"nul\0byte"[..],
+            &b"binary\xff\xfe"[..],
+            &b"trailing\\"[..],
+        ] {
+            let token = seal_core(id, br#"{"a":1}"#, 42, SECRET).expect("seal");
+            let (exp, got, data) = open_core(&token, SECRET).expect("open");
+            assert_eq!(got, id, "id must round-trip byte-exactly");
+            assert_eq!(exp, 42);
+            assert_eq!(data, br#"{"a":1}"#);
+        }
+    }
+
+    #[test]
+    fn unescape_json_id_matches_the_escaper() {
+        assert_eq!(unescape_json_id(br#"a\"b"#), b"a\"b");
+        assert_eq!(unescape_json_id(br#"a\\b"#), b"a\\b");
+        assert_eq!(unescape_json_id(br#"a\/b"#), b"a/b");
+        assert_eq!(unescape_json_id(br#"a\nb"#), b"a\nb");
+        assert_eq!(unescape_json_id(br#"a\rb"#), b"a\rb");
+        assert_eq!(unescape_json_id(br#"a\tb"#), b"a\tb");
+        assert_eq!(unescape_json_id(br#"a\bb"#), b"a\x08b");
+        assert_eq!(unescape_json_id(br#"a\fb"#), b"a\x0cb");
+        // `\u00XX` is a BYTE (the escaper's binary mode), not a code point.
+        assert_eq!(unescape_json_id(br#"a\u00e9b"#), b"a\xe9b");
+        // Above 0xFF is a real code point → UTF-8.
+        assert_eq!(unescape_json_id(br#"a\u20acb"#), "a\u{20ac}b".as_bytes());
+        // A surrogate pair combines into one code point.
+        assert_eq!(unescape_json_id(br#"\ud83d\ude00"#), "\u{1f600}".as_bytes());
+        // Unknown escapes and a trailing backslash stay verbatim.
+        assert_eq!(unescape_json_id(br#"a\qb"#), br#"a\qb"#);
+        assert_eq!(unescape_json_id(b"a\\"), b"a\\");
+    }
+
+    #[test]
+    fn scan_json_string_end_skips_escaped_quotes() {
+        // `a\"b"` (a, \, ", b, ") — the escaped quote does NOT terminate; the
+        // plain quote at index 4 does.
+        assert_eq!(scan_json_string_end(b"a\\\"b\"", 0), Some(4));
+        // No escape at all: the first quote terminates.
+        assert_eq!(scan_json_string_end(b"ab\"cd", 0), Some(2));
+        // Unterminated: the trailing backslash swallows the rest.
+        assert_eq!(scan_json_string_end(b"ab\\\"", 0), None);
+        // Escaped BACKSLASH then a terminator: `a\\"` = a, \, \, " → Some(3).
+        assert_eq!(scan_json_string_end(b"a\\\\\"", 0), Some(3));
+    }
+
     #[test]
     fn wire_format_matches_sign_cookie() {
         // The sealed token must be verifiable by the EXISTING cookie verify

package/rust/ffi/crypto.rs

@@ -625,6 +625,58 @@ pub unsafe extern "C" fn castrum_random_token_into(
 
 // ── Session envelope (fused JSON + HMAC) ────────────────────────────
 
+/// Shared tail of both seal entry points: `None` (empty id/secret, or a panic)
+/// → null pointer, otherwise clone the sealed token into the engine's
+/// per-thread cstring buffer. Extracted so the cstring and byte forms cannot
+/// diverge — the byte form exists only to change how the INPUTS cross.
+fn sealed_to_cstr(sealed: Option<Vec<u8>>) -> *const std::os::raw::c_char {
+    let Some(tok) = sealed else {
+        return std::ptr::null();
+    };
+    super::util::cstring_return(tok.len(), move |buf| {
+        if buf.len() < tok.len() {
+            return None;
+        }
+        buf[..tok.len()].copy_from_slice(&tok);
+        Some(tok.len())
+    })
+}
+
+/// Shared tail of both open entry points: pack the extracted envelope into the
+/// caller's buffer as `[u8 ok=1][i64 exp][u32 idLen][id][u32 dataLen][dataJson]`,
+/// or report the EXACT size required when `out_cap` is too small. `None` (bad
+/// signature / malformed envelope) → `0`. Never returns `0` on a valid call.
+///
+/// # Safety
+/// `out` must be valid for writes up to `out_cap`; the caller null-checks it.
+unsafe fn pack_open_result(
+    opened: Option<(i64, Vec<u8>, Vec<u8>)>,
+    out: *mut u8,
+    out_cap: usize,
+) -> usize {
+    let Some((exp, id, data)) = opened else {
+        return 0;
+    };
+    // Layout size: 1 + 8 + 4+id + 4+data
+    let need = 1 + 8 + 4 + id.len() + 4 + data.len();
+    if need > out_cap {
+        return need;
+    }
+    let o = slice::from_raw_parts_mut(out, need);
+    o[0] = 1;
+    o[1..9].copy_from_slice(&exp.to_le_bytes());
+    let id_len = id.len() as u32;
+    o[9..13].copy_from_slice(&id_len.to_le_bytes());
+    let mut p = 13usize;
+    o[p..p + id.len()].copy_from_slice(&id);
+    p += id.len();
+    let d_len = data.len() as u32;
+    o[p..p + 4].copy_from_slice(&d_len.to_le_bytes());
+    p += 4;
+    o[p..p + data.len()].copy_from_slice(&data);
+    need
+}
+
 /// Seal a session envelope NATIVELY: build
 /// `{"id":"…","data":<data_json>,"exp":exp}` and HMAC-sign it into the
 /// `payload.<64-hex>` cookie token — ONE crossing replaces the JS
@@ -650,16 +702,7 @@ pub unsafe extern "C" fn castrum_session_seal(
         || crate::crypto::session::seal_core(id_b, data_b, exp_secs, sec_b),
         None,
     );
-    let Some(tok) = sealed else {
-        return std::ptr::null();
-    };
-    super::util::cstring_return(tok.len(), move |buf| {
-        if buf.len() < tok.len() {
-            return None;
-        }
-        buf[..tok.len()].copy_from_slice(&tok);
-        Some(tok.len())
-    })
+    sealed_to_cstr(sealed)
 }
 
 /// Open a sealed session token: verify the HMAC and extract the envelope in
@@ -684,25 +727,72 @@ pub unsafe extern "C" fn castrum_session_open(
     let tok = std::ffi::CStr::from_ptr(token).to_bytes();
     let sec = std::ffi::CStr::from_ptr(secret).to_bytes();
     let opened = panic_guard(|| crate::crypto::session::open_core(tok, sec), None);
-    let Some((exp, id, data)) = opened else {
+    pack_open_result(opened, out, out_cap)
+}
+
+/// Byte-arg sibling of `castrum_session_seal`: same core, same wire format, but
+/// every input crosses as `(ptr, len)` instead of a `cstring` ARG.
+///
+/// Per `docs/FFI_BUN_GUIDE.md` §6.1 there are two reasons, and only the second
+/// cannot be worked around:
+/// 1. a `cstring` ARG costs the engine a transcode into a call-scoped
+///    NUL-terminated buffer (~80ns per arg through the public surface vs ~37ns
+///    for the byte path);
+/// 2. an embedded `U+0000` SILENTLY TRUNCATES the value before Rust sees it.
+///    `id` and `data_json` are user-derived (the id is escaped by
+///    `seal_core`, which only makes sense if it may contain arbitrary bytes),
+///    so a session id carrying a NUL would be sealed under its truncated form.
+///    This form carries the exact length and cannot be truncated.
+///
+/// # Safety
+/// `id`/`data_json`/`secret` must be valid for reads of their stated lengths;
+/// null pointers are rejected (→ null).
+#[no_mangle]
+pub unsafe extern "C" fn castrum_session_seal_bytes(
+    id: *const u8,
+    id_len: usize,
+    data_json: *const u8,
+    data_len: usize,
+    exp_secs: i64,
+    secret: *const u8,
+    secret_len: usize,
+) -> *const std::os::raw::c_char {
+    if id.is_null() || data_json.is_null() || secret.is_null() {
+        return std::ptr::null();
+    }
+    let id_b = slice::from_raw_parts(id, id_len);
+    let data_b = slice::from_raw_parts(data_json, data_len);
+    let sec_b = slice::from_raw_parts(secret, secret_len);
+    let sealed = super::util::panic_guard(
+        || crate::crypto::session::seal_core(id_b, data_b, exp_secs, sec_b),
+        None,
+    );
+    sealed_to_cstr(sealed)
+}
+
+/// Byte-arg sibling of `castrum_session_open`: `token`/`secret` cross as
+/// `(ptr, len)`; the output layout and the needed-size convention are identical
+/// to `castrum_session_open` (`0` = bad signature / malformed). Saves the
+/// per-arg transcode and, unlike the `cstring` form, cannot be truncated by an
+/// embedded `U+0000` in the token.
+///
+/// # Safety
+/// `token`/`secret` must be valid for reads of their stated lengths; `out` must
+/// be valid for writes up to `out_cap`. Null pointers → 0.
+#[no_mangle]
+pub unsafe extern "C" fn castrum_session_open_bytes(
+    token: *const u8,
+    token_len: usize,
+    secret: *const u8,
+    secret_len: usize,
+    out: *mut u8,
+    out_cap: usize,
+) -> usize {
+    if token.is_null() || secret.is_null() || out.is_null() {
         return 0;
-    };
-    // Layout size: 1 + 8 + 4+id + 4+data
-    let need = 1 + 8 + 4 + id.len() + 4 + data.len();
-    if need > out_cap {
-        return need;
     }
-    let o = slice::from_raw_parts_mut(out, need);
-    o[0] = 1;
-    o[1..9].copy_from_slice(&exp.to_le_bytes());
-    let id_len = id.len() as u32;
-    o[9..13].copy_from_slice(&id_len.to_le_bytes());
-    let mut p = 13usize;
-    o[p..p + id.len()].copy_from_slice(&id);
-    p += id.len();
-    let d_len = data.len() as u32;
-    o[p..p + 4].copy_from_slice(&d_len.to_le_bytes());
-    p += 4;
-    o[p..p + data.len()].copy_from_slice(&data);
-    need
+    let tok = slice::from_raw_parts(token, token_len);
+    let sec = slice::from_raw_parts(secret, secret_len);
+    let opened = panic_guard(|| crate::crypto::session::open_core(tok, sec), None);
+    pack_open_result(opened, out, out_cap)
 }

package/rust/ffi/tests.rs

@@ -2308,6 +2308,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/src/native/ffi/build/instances.ts

@@ -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
@@ -164,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
@@ -623,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

@@ -159,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)
@@ -195,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)
@@ -208,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')
@@ -229,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', '')

package/src/native/ffi/types.ts

@@ -471,6 +471,23 @@ export interface BunFFI {
    * exact required size).
    */
   sessionOpen(token: string, secret: string, output: Uint8Array): number
+  /**
+   * Byte-arg `{@link sessionSeal}`: same envelope + wire format, inputs as
+   * bytes. Preferred for user-derived `id`/`dataJson`, because a `cstring` ARG
+   * is engine-transcoded (a per-arg cost) and SILENTLY TRUNCATES at an
+   * embedded `U+0000` before Rust sees it. `null` = failure.
+   */
+  sessionSealBytes(
+    id: Uint8Array,
+    dataJson: Uint8Array,
+    expSecs: number,
+    secret: Uint8Array,
+  ): string | null
+  /**
+   * Byte-arg `{@link sessionOpen}`: same output layout and needed-size
+   * convention, `token`/`secret` as bytes (exact length, no transcode).
+   */
+  sessionOpenBytes(token: Uint8Array, secret: Uint8Array, output: Uint8Array): number
 
   // ── Batch fixed-width hex validation / RegExp escaping ─────────────
   /**

package/src/native/ffi.ts

@@ -576,6 +576,18 @@ function bind(forcedPath?: string, tried: string[] = []): BunFFI | null {
         args: abi(['cstring', 'cstring', 'ptr', 'usize']),
         returns: U64_FAST,
       },
+      // Byte-arg siblings of the pair above: identical core and wire format,
+      // but every INPUT crosses as `(ptr,len)`. A `cstring` ARG costs the
+      // engine a transcode per arg AND silently truncates at an embedded
+      // U+0000 — reachable here because `id`/`data_json` are user-derived.
+      castrum_session_seal_bytes: {
+        args: abi(['ptr', 'usize', 'ptr', 'usize', 'i64', 'ptr', 'usize']),
+        returns: 'cstring',
+      },
+      castrum_session_open_bytes: {
+        args: abi(['ptr', 'usize', 'ptr', 'usize', 'ptr', 'usize']),
+        returns: U64_FAST,
+      },
       // Off-thread task runtime: `submit` takes a packed `(ptr,len)` arg blob
       // plus a JS-assigned id; `drain` writes the packed completion batch into
       // a caller buffer (needed-size convention). `set_doorbell` takes the raw