castrum 0.9.3 → 0.9.6

package/rust/crypto/base64.rs

@@ -0,0 +1,420 @@
+// rust/crypto/base64.rs — base64 (standard/url-safe) + hex encode/decode.
+//
+// Uses the `base64` crate engines (Cargo dep already present). The
+// `Base64Codec` higher-order instance precompiles the alphabet/decoding
+// configuration once in its constructor and reuses it across calls.
+
+use napi::bindgen_prelude::*;
+use napi_derive::napi;
+
+use crate::util::bytes::{hex_val, HEX_LOWER};
+use base64::Engine as _;
+
+fn engine(url_safe: bool, padding: bool) -> base64::engine::general_purpose::GeneralPurpose {
+    use base64::engine::general_purpose::*;
+    match (url_safe, padding) {
+        (false, true) => STANDARD,
+        (false, false) => STANDARD_NO_PAD,
+        (true, true) => URL_SAFE,
+        (true, false) => URL_SAFE_NO_PAD,
+    }
+}
+
+#[napi]
+pub fn base64_encode(input: Uint8Array, url_safe: Option<bool>, padding: Option<bool>) -> Buffer {
+    let out = engine(url_safe.unwrap_or(false), padding.unwrap_or(true)).encode(input.as_ref());
+    Buffer::from(out.into_bytes())
+}
+
+#[napi]
+pub fn base64_decode(
+    input: Uint8Array,
+    url_safe: Option<bool>,
+    padding: Option<bool>,
+) -> Result<Buffer> {
+    engine(url_safe.unwrap_or(false), padding.unwrap_or(true))
+        .decode(input.as_ref())
+        .map(Buffer::from)
+        .map_err(|e| Error::from_reason(e.to_string()))
+}
+
+#[napi]
+pub fn base64url_encode(input: Uint8Array) -> Buffer {
+    Buffer::from(
+        base64::engine::general_purpose::URL_SAFE_NO_PAD
+            .encode(input.as_ref())
+            .into_bytes(),
+    )
+}
+
+#[napi]
+pub fn base64url_decode(input: Uint8Array) -> Result<Buffer> {
+    base64::engine::general_purpose::URL_SAFE_NO_PAD
+        .decode(input.as_ref())
+        .map(Buffer::from)
+        .map_err(|e| Error::from_reason(e.to_string()))
+}
+
+/// Base64-encode to raw bytes (no Buffer wrapping). Shared by the scalar and
+/// packed-batch paths.
+pub fn base64_encode_bytes(input: &[u8], url_safe: bool, padding: bool) -> Vec<u8> {
+    engine(url_safe, padding).encode(input).into_bytes()
+}
+
+/// Base64-decode from raw bytes. Errors on invalid input. Shared by the scalar
+/// and packed-batch paths.
+pub fn base64_decode_bytes(input: &[u8], url_safe: bool, padding: bool) -> Result<Vec<u8>> {
+    engine(url_safe, padding)
+        .decode(input)
+        .map_err(|e| Error::from_reason(e.to_string()))
+}
+
+/// Base64url (RFC 7515 §2 — URL-safe alphabet, NO padding) encode to raw
+/// bytes. The single shared source of truth for JWT segment encoding
+/// (`crate::crypto::jwt`) and Ed25519 keypair serialization
+/// (`crate::crypto::ed25519`) — keeps the url-safe alphabet defined in exactly
+/// one place.
+#[inline]
+pub fn base64url_encode_bytes(data: &[u8]) -> Vec<u8> {
+    base64::engine::general_purpose::URL_SAFE_NO_PAD
+        .encode(data)
+        .into_bytes()
+}
+
+/// Base64url (RFC 7515 §2 — URL-safe alphabet, NO padding) decode from raw
+/// bytes. Returns `None` on invalid UTF-8 or non-base64url input.
+#[inline]
+pub fn base64url_decode_bytes(data: &[u8]) -> Option<Vec<u8>> {
+    let text = std::str::from_utf8(data).ok()?;
+    base64::engine::general_purpose::URL_SAFE_NO_PAD
+        .decode(text)
+        .ok()
+}
+
+// ── hex ──────────────────────────────────────────────────────────
+
+/// Encode bytes as lowercase hex (uses the shared `HEX_LOWER` table — direct
+/// byte writes, no per-nibble `char` push).
+///
+/// # Safety
+///
+/// Hex output is always ASCII (`HEX_LOWER` is a byte string of `0-9a-f`), so
+/// the built `Vec<u8>` is valid UTF-8 by construction; `from_utf8_unchecked`
+/// skips a redundant validation pass on the allocating hot path.
+pub fn hex_encode_bytes(input: &[u8]) -> String {
+    let mut out = Vec::with_capacity(input.len() * 2);
+    for &b in input {
+        out.push(HEX_LOWER[(b >> 4) as usize]);
+        out.push(HEX_LOWER[(b & 0x0f) as usize]);
+    }
+    // SAFETY: every byte pushed is an ASCII hex digit from `HEX_LOWER`.
+    unsafe { String::from_utf8_unchecked(out) }
+}
+
+/// Decode lowercase/uppercase hex to bytes.
+pub fn hex_decode_bytes(input: &[u8]) -> std::result::Result<Vec<u8>, &'static str> {
+    if !input.len().is_multiple_of(2) {
+        return Err("odd hex length");
+    }
+    let mut out = Vec::with_capacity(input.len() / 2);
+    for i in (0..input.len()).step_by(2) {
+        let hi = hex_val(input[i]).ok_or("invalid hex digit")?;
+        let lo = hex_val(input[i + 1]).ok_or("invalid hex digit")?;
+        out.push((hi << 4) | lo);
+    }
+    Ok(out)
+}
+
+#[napi]
+pub fn hex_encode(input: Uint8Array) -> Buffer {
+    Buffer::from(hex_encode_bytes(input.as_ref()).into_bytes())
+}
+
+#[napi]
+pub fn hex_decode(input: Uint8Array) -> Result<Buffer> {
+    hex_decode_bytes(input.as_ref())
+        .map(Buffer::from)
+        .map_err(|e| Error::from_reason(e.to_string()))
+}
+
+// ── Reusable-output (_into) variants ────────────────────────────
+//
+// These write into a caller-provided output buffer and return the number of
+// bytes written (u32), so hot loops can pool the buffer instead of allocating
+// a fresh Vec + napi Buffer per call. They error on a buffer that is too small;
+// input/output overlap is handled by `crate::util::run_packed_into`.
+
+/// Lowercase-hex encode directly into `out`. Returns bytes written
+/// (`input.len() * 2`). Errors if `out` is too small.
+#[inline]
+pub fn hex_encode_into_slice(input: &[u8], out: &mut [u8]) -> Result<usize> {
+    let needed = input
+        .len()
+        .checked_mul(2)
+        .ok_or_else(|| Error::from_reason("hex encode: input too large (length overflow)"))?;
+    if out.len() < needed {
+        return Err(Error::from_reason("hex encode: output buffer too small"));
+    }
+    let mut pos = 0usize;
+    for &b in input {
+        out[pos] = HEX_LOWER[(b >> 4) as usize];
+        out[pos + 1] = HEX_LOWER[(b & 0x0f) as usize];
+        pos += 2;
+    }
+    Ok(pos)
+}
+
+#[napi]
+pub fn hex_encode_into(input: Uint8Array, mut output: Uint8Array) -> Result<u32> {
+    crate::util::run_packed_into(&input, &mut output, hex_encode_into_slice)
+}
+
+/// Hex-decode directly into `out`. Returns bytes written (`input.len() / 2`).
+/// Errors on odd length, invalid digits, or an output buffer that is too small.
+#[inline]
+pub fn hex_decode_into_slice(input: &[u8], out: &mut [u8]) -> Result<usize> {
+    if !input.len().is_multiple_of(2) {
+        return Err(Error::from_reason("odd hex length"));
+    }
+    let needed = input.len() / 2;
+    if out.len() < needed {
+        return Err(Error::from_reason("hex decode: output buffer too small"));
+    }
+    let mut pos = 0usize;
+    for i in (0..input.len()).step_by(2) {
+        let hi = hex_val(input[i]).ok_or_else(|| Error::from_reason("invalid hex digit"))?;
+        let lo = hex_val(input[i + 1]).ok_or_else(|| Error::from_reason("invalid hex digit"))?;
+        out[pos] = (hi << 4) | lo;
+        pos += 1;
+    }
+    Ok(pos)
+}
+
+#[napi]
+pub fn hex_decode_into(input: Uint8Array, mut output: Uint8Array) -> Result<u32> {
+    crate::util::run_packed_into(&input, &mut output, hex_decode_into_slice)
+}
+
+/// Pure core: base64-encode `input` into `out` (zero-alloc `encode_slice`).
+/// Returns bytes written; errors if `out` is too small. Shared by the `_into`
+/// napi path and the pure-core unit tests.
+pub fn base64_encode_into_slice(
+    input: &[u8],
+    out: &mut [u8],
+    url_safe: bool,
+    padding: bool,
+) -> Result<usize> {
+    engine(url_safe, padding)
+        .encode_slice(input, out)
+        .map_err(|e| Error::from_reason(format!("base64 encode: {e}")))
+}
+
+/// Base64-encode into a caller-provided output buffer (zero-alloc via
+/// `Engine::encode_slice`). Returns bytes written; errors if `output` is too
+/// small.
+#[napi]
+pub fn base64_encode_into(
+    input: Uint8Array,
+    mut output: Uint8Array,
+    url_safe: Option<bool>,
+    padding: Option<bool>,
+) -> Result<u32> {
+    crate::util::run_packed_into(&input, &mut output, move |inp, out| {
+        base64_encode_into_slice(inp, out, url_safe.unwrap_or(false), padding.unwrap_or(true))
+    })
+}
+
+/// Pure core: base64-decode `input` into `out` (zero-alloc `decode_slice`).
+/// Returns bytes written; errors on invalid input or a too-small output
+/// buffer. Shared by the `_into` napi path and the pure-core unit tests.
+pub fn base64_decode_into_slice(
+    input: &[u8],
+    out: &mut [u8],
+    url_safe: bool,
+    padding: bool,
+) -> Result<usize> {
+    engine(url_safe, padding)
+        .decode_slice(input, out)
+        .map_err(|e| Error::from_reason(format!("base64 decode: {e}")))
+}
+
+/// Base64-decode into a caller-provided output buffer (zero-alloc via
+/// `Engine::decode_slice`). Returns bytes written; errors on invalid input or
+/// an output buffer that is too small.
+#[napi]
+pub fn base64_decode_into(
+    input: Uint8Array,
+    mut output: Uint8Array,
+    url_safe: Option<bool>,
+    padding: Option<bool>,
+) -> Result<u32> {
+    crate::util::run_packed_into(&input, &mut output, move |inp, out| {
+        base64_decode_into_slice(inp, out, url_safe.unwrap_or(false), padding.unwrap_or(true))
+    })
+}
+
+/// Higher-order instance: the alphabet/padding engine is selected ONCE at
+/// construction and stored concretely, so `encode`/`decode` never re-run the
+/// 4-way engine match on the per-call path.
+#[napi]
+pub struct Base64Codec {
+    engine: base64::engine::general_purpose::GeneralPurpose,
+}
+
+#[napi]
+impl Base64Codec {
+    #[napi(constructor)]
+    pub fn new(url_safe: Option<bool>, padding: Option<bool>) -> Self {
+        Self {
+            engine: engine(url_safe.unwrap_or(false), padding.unwrap_or(true)),
+        }
+    }
+
+    #[napi]
+    pub fn encode(&self, input: Uint8Array) -> Buffer {
+        Buffer::from(self.engine.encode(input.as_ref()).into_bytes())
+    }
+
+    #[napi]
+    pub fn decode(&self, input: Uint8Array) -> Result<Buffer> {
+        self.engine
+            .decode(input.as_ref())
+            .map(Buffer::from)
+            .map_err(|e| Error::from_reason(e.to_string()))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn base64_roundtrip_standard() {
+        let data = b"hello world!";
+        let enc = base64::engine::general_purpose::STANDARD.encode(data);
+        assert_eq!(
+            base64_decode(Uint8Array::new(enc.into_bytes()), None, None)
+                .unwrap()
+                .as_ref(),
+            data
+        );
+    }
+
+    #[test]
+    fn base64url_no_padding() {
+        // 0xfb → 111110 11 → "-w" (url-safe, no padding)
+        let enc = base64::engine::general_purpose::URL_SAFE_NO_PAD.encode([0xfb]);
+        assert_eq!(enc, "-w");
+        let dec = base64url_decode(Uint8Array::new(enc.into_bytes())).unwrap();
+        assert_eq!(dec.as_ref(), [0xfb]);
+    }
+
+    #[test]
+    fn base64_decode_rejects_invalid() {
+        assert!(base64_decode(Uint8Array::new(b"!!!".to_vec()), None, None).is_err());
+    }
+
+    #[test]
+    fn hex_roundtrip() {
+        let data = b"\x00\x01\xfe\xffAB";
+        let enc = hex_encode_bytes(data);
+        assert_eq!(enc, "0001feff4142");
+        assert_eq!(hex_decode_bytes(enc.as_bytes()).unwrap(), data);
+    }
+
+    #[test]
+    fn hex_rejects_odd_and_bad() {
+        assert!(hex_decode_bytes(b"abc").is_err());
+        assert!(hex_decode_bytes(b"zz").is_err());
+    }
+
+    #[test]
+    fn codec_instance_encodes_urlsafe() {
+        let c = Base64Codec::new(Some(true), Some(false));
+        let enc = c.encode(Uint8Array::new(b"\xfb".to_vec()));
+        assert_eq!(enc.as_ref(), b"-w");
+    }
+
+    // ── reusable-output (_into) variants ──
+
+    #[test]
+    fn hex_encode_into_slice_matches_allocating() {
+        let data = b"\x00\x01\xfe\xffAB";
+        let expected = hex_encode_bytes(data);
+        let mut out = [0u8; 32];
+        let n = hex_encode_into_slice(data, &mut out).unwrap();
+        assert_eq!(n, expected.len());
+        assert_eq!(&out[..n], expected.as_bytes());
+    }
+
+    #[test]
+    fn hex_encode_into_reports_length() {
+        let data = b"hello";
+        let out = Uint8Array::new(vec![0u8; 16]);
+        let n = hex_encode_into(Uint8Array::new(data.to_vec()), out).unwrap();
+        assert_eq!(n as usize, data.len() * 2);
+    }
+
+    #[test]
+    fn hex_encode_into_small_buffer_errors() {
+        let mut out = [0u8; 2];
+        assert!(hex_encode_into_slice(b"abc", &mut out).is_err());
+        let out2 = Uint8Array::new(vec![0u8; 4]);
+        assert!(hex_encode_into(Uint8Array::new(b"abcdef".to_vec()), out2).is_err());
+    }
+
+    #[test]
+    fn hex_decode_into_roundtrips() {
+        let enc = hex_encode_bytes(b"\x00\x01\xfe\xffAB");
+        let mut out = [0u8; 16];
+        let n = hex_decode_into_slice(enc.as_bytes(), &mut out).unwrap();
+        assert_eq!(&out[..n], b"\x00\x01\xfe\xffAB");
+    }
+
+    #[test]
+    fn hex_decode_into_rejects_bad_input() {
+        let mut out = [0u8; 4];
+        assert!(hex_decode_into_slice(b"abc", &mut out).is_err());
+        assert!(hex_decode_into_slice(b"zz", &mut out).is_err());
+    }
+
+    #[test]
+    fn hex_decode_into_small_buffer_errors() {
+        let mut out = [0u8; 2];
+        assert!(hex_decode_into_slice(b"0001020304", &mut out).is_err());
+    }
+
+    #[test]
+    fn base64_encode_into_reports_length() {
+        let data = b"hello world!";
+        let out = Uint8Array::new(vec![0u8; 64]);
+        let n = base64_encode_into(Uint8Array::new(data.to_vec()), out, None, None).unwrap();
+        assert_eq!(
+            n as usize,
+            base64::engine::general_purpose::STANDARD.encode(data).len()
+        );
+    }
+
+    #[test]
+    fn base64_encode_into_small_buffer_errors() {
+        let out = Uint8Array::new(vec![0u8; 4]);
+        assert!(
+            base64_encode_into(Uint8Array::new(b"hello world!".to_vec()), out, None, None).is_err()
+        );
+    }
+
+    #[test]
+    fn base64_decode_into_roundtrips() {
+        let data = b"hello world!";
+        let enc = base64::engine::general_purpose::STANDARD.encode(data);
+        let out = Uint8Array::new(vec![0u8; 32]);
+        let n = base64_decode_into(Uint8Array::new(enc.into_bytes()), out, None, None).unwrap();
+        assert_eq!(n as usize, data.len());
+    }
+
+    #[test]
+    fn base64_decode_into_rejects_invalid() {
+        let out = Uint8Array::new(vec![0u8; 32]);
+        assert!(base64_decode_into(Uint8Array::new(b"!!!".to_vec()), out, None, None).is_err());
+    }
+}

package/rust/crypto/bcrypt.rs

@@ -0,0 +1,89 @@
+// rust/crypto/bcrypt.rs — bcrypt password hashing.
+//
+// Pure-Rust (bcrypt crate, Blowfish-based). Unlike argon2id (memory-hard), a
+// bcrypt cost of `2^cost` is CPU-bound. We expose the standard `$2b$` PHC
+// string format so the output is interchangeable with Bun.password / bcryptjs.
+//
+// Pure-Rust core stays unit-testable; only the entry points use napi types.
+
+use napi::bindgen_prelude::*;
+use napi_derive::napi;
+
+/// bcrypt cost lower bound (bcrypt crate enforces 4..=31).
+pub const BCRYPT_MIN_COST: u32 = 4;
+/// bcrypt cost upper bound.
+pub const BCRYPT_MAX_COST: u32 = 31;
+
+/// Clamp a caller cost into the bcrypt-legal range (4..=31).
+#[inline]
+pub fn clamp_cost(cost: u32) -> u32 {
+    cost.clamp(BCRYPT_MIN_COST, BCRYPT_MAX_COST)
+}
+
+/// Hash a password with bcrypt at `cost`, returning a `$2b$` PHC string.
+#[napi]
+pub fn password_hash_bcrypt(password: Uint8Array, cost: u32) -> Result<String> {
+    let cost = clamp_cost(cost);
+    bcrypt::hash(password.as_ref(), cost).map_err(|e| Error::from_reason(e.to_string()))
+}
+
+/// Verify a password against a bcrypt `$2b$` PHC string.
+/// Returns false on ANY malformed hash (parity with argon2 `password_verify`).
+#[napi]
+pub fn password_verify_bcrypt(password: Uint8Array, hash: String) -> bool {
+    bcrypt::verify(password.as_ref(), &hash).unwrap_or(false)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn clamp_cost_bounds() {
+        assert_eq!(clamp_cost(0), BCRYPT_MIN_COST);
+        assert_eq!(clamp_cost(3), BCRYPT_MIN_COST);
+        assert_eq!(clamp_cost(4), 4);
+        assert_eq!(clamp_cost(10), 10);
+        assert_eq!(clamp_cost(31), 31);
+        assert_eq!(clamp_cost(99), BCRYPT_MAX_COST);
+    }
+
+    #[test]
+    fn bcrypt_roundtrip_and_wrong_password() {
+        let h = bcrypt::hash(b"password".as_slice(), 4).unwrap();
+        assert!(h.starts_with("$2b$04$"));
+        assert_eq!(h.len(), 60); // PHC bcrypt strings are exactly 60 chars
+        assert!(bcrypt::verify(b"password".as_slice(), &h).unwrap());
+        assert!(!bcrypt::verify(b"wrong".as_slice(), &h).unwrap());
+    }
+
+    #[test]
+    fn bcrypt_is_cost_sensitive_and_self_contained() {
+        // Same password, two hashes differ (random salt) but both verify.
+        let a = bcrypt::hash(b"pw".as_slice(), 4).unwrap();
+        let b = bcrypt::hash(b"pw".as_slice(), 4).unwrap();
+        assert_ne!(a, b);
+        assert!(bcrypt::verify(b"pw".as_slice(), &a).unwrap());
+        assert!(bcrypt::verify(b"pw".as_slice(), &b).unwrap());
+    }
+
+    #[test]
+    fn napi_wrapper_clamps_and_roundtrips() {
+        // cost 3 is clamped up to 4 (cheap) — exercises the napi boundary.
+        let h = password_hash_bcrypt(Uint8Array::new(b"pw".to_vec()), 3).unwrap();
+        assert!(h.starts_with("$2b$04$"));
+        assert!(password_verify_bcrypt(
+            Uint8Array::new(b"pw".to_vec()),
+            h.clone()
+        ));
+        assert!(!password_verify_bcrypt(
+            Uint8Array::new(b"nope".to_vec()),
+            h
+        ));
+        // Malformed hash -> false (not a throw), matching argon2 semantics.
+        assert!(!password_verify_bcrypt(
+            Uint8Array::new(b"pw".to_vec()),
+            "garbage".to_string()
+        ));
+    }
+}

package/rust/crypto/cookie_sign.rs

@@ -0,0 +1,169 @@
+// rust/crypto/cookie_sign.rs — signed cookies (`value.signature`, HMAC-SHA256).
+//
+// Composes the existing HMAC core + hex tables. The `CookieSigner`
+// higher-order instance precomputes the HMAC key once in its constructor and
+// reuses it across sign/verify calls.
+
+use aws_lc_rs::hmac;
+use napi::bindgen_prelude::*;
+use napi_derive::napi;
+
+use crate::util::bytes::{hex_decode_32, hex_encode_32};
+
+/// Zero-alloc core: `value` ++ "." ++ 64-hex into `out`. Returns the bytes
+/// written, or `None` on a too-small buffer. Used by the C-ABI (`bun:ffi`)
+/// path to avoid the signed-cookie Vec + copy.
+pub fn sign_cookie_into(value: &[u8], key: &hmac::Key, out: &mut [u8]) -> Option<usize> {
+    let need = value.len() + 1 + 64;
+    if out.len() < need {
+        return None;
+    }
+    let tag = hmac::sign(key, value);
+    let mut sig = [0u8; 64];
+    hex_encode_32(tag.as_ref(), &mut sig);
+    out[..value.len()].copy_from_slice(value);
+    out[value.len()] = b'.';
+    out[value.len() + 1..need].copy_from_slice(&sig);
+    Some(need)
+}
+
+/// `value` ++ "." ++ lowercase-hex(HMAC-SHA256(secret, value)).
+pub fn sign_cookie_bytes(value: &[u8], key: &hmac::Key) -> Vec<u8> {
+    let tag = hmac::sign(key, value);
+    let mut sig = [0u8; 64];
+    hex_encode_32(tag.as_ref(), &mut sig);
+    let mut out = Vec::with_capacity(value.len() + 1 + 64);
+    out.extend_from_slice(value);
+    out.push(b'.');
+    out.extend_from_slice(&sig);
+    out
+}
+
+/// Zero-alloc core: constant-time verify into `out` (the value without its
+/// signature). Returns the value length, or `None` on invalid signature /
+/// too-small buffer. Used by the C-ABI (`bun:ffi`) path to avoid the Vec.
+pub fn verify_cookie_into(signed: &[u8], key: &hmac::Key, out: &mut [u8]) -> Option<usize> {
+    let dot = signed.iter().rposition(|&b| b == b'.')?;
+    let (value, sig) = signed.split_at(dot);
+    let sig = &sig[1..];
+    if sig.len() != 64 {
+        return None;
+    }
+    let sig_bytes = hex_decode_32(sig)?;
+    if hmac::verify(key, value, &sig_bytes).is_err() {
+        return None;
+    }
+    if out.len() < value.len() {
+        return None;
+    }
+    out[..value.len()].copy_from_slice(value);
+    Some(value.len())
+}
+
+/// Constant-time verify; returns the signed value without its signature.
+pub fn verify_cookie_bytes(signed: &[u8], key: &hmac::Key) -> Option<Vec<u8>> {
+    let dot = signed.iter().rposition(|&b| b == b'.')?;
+    let (value, sig) = signed.split_at(dot);
+    let sig = &sig[1..];
+    if sig.len() != 64 {
+        return None;
+    }
+    let sig_bytes = hex_decode_32(sig)?;
+    hmac::verify(key, value, &sig_bytes)
+        .ok()
+        .map(|()| value.to_vec())
+}
+
+/// Constant-time verify; returns whether the signature matches, WITHOUT
+/// materializing the signed value. Same checks as [`verify_cookie_bytes`] but
+/// skips the `value.to_vec()` — used by the packed batch to avoid a discarded
+/// allocation per item.
+pub fn verify_cookie_bytes_bool(signed: &[u8], key: &hmac::Key) -> bool {
+    let Some(dot) = signed.iter().rposition(|&b| b == b'.') else {
+        return false;
+    };
+    let (value, sig) = signed.split_at(dot);
+    let sig = &sig[1..];
+    if sig.len() != 64 {
+        return false;
+    }
+    let Some(sig_bytes) = hex_decode_32(sig) else {
+        return false;
+    };
+    hmac::verify(key, value, &sig_bytes).is_ok()
+}
+
+#[napi]
+pub fn sign_cookie(value: Uint8Array, secret: Uint8Array) -> Buffer {
+    let key = hmac::Key::new(hmac::HMAC_SHA256, secret.as_ref());
+    Buffer::from(sign_cookie_bytes(value.as_ref(), &key))
+}
+
+#[napi]
+pub fn verify_cookie(signed: Uint8Array, secret: Uint8Array) -> Option<Buffer> {
+    let key = hmac::Key::new(hmac::HMAC_SHA256, secret.as_ref());
+    verify_cookie_bytes(signed.as_ref(), &key).map(Buffer::from)
+}
+
+/// Higher-order instance: HMAC key compiled once, reused across calls.
+#[napi]
+pub struct CookieSigner {
+    key: hmac::Key,
+}
+
+#[napi]
+impl CookieSigner {
+    #[napi(constructor)]
+    pub fn new(secret: Uint8Array) -> Self {
+        Self {
+            key: hmac::Key::new(hmac::HMAC_SHA256, secret.as_ref()),
+        }
+    }
+
+    #[napi]
+    pub fn sign(&self, value: Uint8Array) -> Buffer {
+        Buffer::from(sign_cookie_bytes(value.as_ref(), &self.key))
+    }
+
+    #[napi]
+    pub fn verify(&self, signed: Uint8Array) -> Option<Buffer> {
+        verify_cookie_bytes(signed.as_ref(), &self.key).map(Buffer::from)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn key(secret: &[u8]) -> hmac::Key {
+        hmac::Key::new(hmac::HMAC_SHA256, secret)
+    }
+
+    #[test]
+    fn sign_then_verify_roundtrip() {
+        let k = key(b"super-secret");
+        let value = b"session=abc123";
+        let signed = sign_cookie_bytes(value, &k);
+        assert!(signed.starts_with(value));
+        assert_eq!(signed[value.len()], b'.');
+        assert_eq!(verify_cookie_bytes(&signed, &k).unwrap(), value);
+    }
+
+    #[test]
+    fn verify_rejects_tampered() {
+        let k = key(b"super-secret");
+        let value = b"session=abc123";
+        let mut signed = sign_cookie_bytes(value, &k);
+        let last = signed.len() - 1;
+        signed[last] = if signed[last] == b'0' { b'1' } else { b'0' };
+        assert!(verify_cookie_bytes(&signed, &k).is_none());
+    }
+
+    #[test]
+    fn verify_rejects_wrong_secret_and_malformed() {
+        let signed = sign_cookie_bytes(b"x", &key(b"secret-a"));
+        assert!(verify_cookie_bytes(&signed, &key(b"secret-b")).is_none());
+        assert!(verify_cookie_bytes(b"no-dot", &key(b"s")).is_none());
+        assert!(verify_cookie_bytes(b"x.bad", &key(b"s")).is_none());
+    }
+}