castrum 0.9.2 → 0.9.4

package/rust/crypto/hashing.rs

@@ -0,0 +1,140 @@
+// rust/crypto/hashing.rs — FNV-1a / XXH3 checksums.
+
+use napi::bindgen_prelude::*;
+use napi_derive::napi;
+
+use xxhash_rust::xxh3::xxh3_64;
+
+pub const FNV_OFFSET_BASIS: u64 = 0xcbf2_9ce4_8422_2325;
+pub const FNV_PRIME: u64 = 0x0000_0100_0000_01b3;
+
+// ── FNV-1a (byte-by-byte, correct per spec) ──────────────────────
+
+/// FNV-1a in the "continue" style. FNV-1a is inherently byte-serial,
+/// so we process each byte individually (this is the correct algorithm).
+#[inline]
+pub fn fnv1a64_continue(mut hash: u64, input: &[u8]) -> u64 {
+    for &b in input {
+        hash ^= u64::from(b);
+        hash = hash.wrapping_mul(FNV_PRIME);
+    }
+    hash
+}
+
+/// FNV-1a on a full byte slice, with fast path for small inputs.
+#[inline]
+pub fn fnv1a64_bytes(input: &[u8]) -> u64 {
+    fnv1a64_continue(FNV_OFFSET_BASIS, input)
+}
+
+// ── XXHash wrappers ────────────────────────────────────────────────
+
+#[inline]
+pub fn fast_hash_bytes(input: &[u8]) -> u64 {
+    xxh3_64(input)
+}
+
+// ── Napi exports ───────────────────────────────────────────────────
+
+/// CRC32 over a raw byte slice (pure core, shared by the napi boundary and
+/// the pure-core unit tests).
+#[inline]
+pub fn crc32_bytes(input: &[u8]) -> u32 {
+    crc32fast::hash(input)
+}
+
+#[napi]
+pub fn crc32(input: Uint8Array) -> u32 {
+    crc32_bytes(input.as_ref())
+}
+
+#[napi(js_name = "fnv1a64")]
+pub fn fnv1a64(input: Uint8Array) -> u64 {
+    fnv1a64_bytes(input.as_ref())
+}
+
+/// XXH3-64 over raw bytes. High-throughput non-cryptographic hash; the same
+/// core the ingress IP-trust hasher uses. Exposed publicly so callers can
+/// race it against `Bun.hash.xxHash3` — see docs/bun-builtins-decision-matrix.md.
+#[napi]
+pub fn xxh3(input: Uint8Array) -> u64 {
+    fast_hash_bytes(input.as_ref())
+}
+
+/// CRC32 batch — delegates to the shared packed-u32 writer (same wire format
+/// as the `_into` variant; validation + parallelism live in
+/// `util::packed::write_u32_batch_into`, single source of truth).
+#[napi]
+pub fn crc32_batch_packed(input: Uint8Array) -> Result<Buffer> {
+    let data = input.as_ref();
+    let count = crate::util::packed::PackedIter::new(data)?.len();
+    let mut out = vec![0u8; 4 + count.saturating_mul(4)];
+    let written = crate::util::write_u32_batch_into(data, &mut out, crc32_bytes)?;
+    out.truncate(written);
+    Ok(Buffer::from(out))
+}
+
+/// Reusable-output CRC32 batch: writes `[u32 count][u32…]` into `output` and
+/// returns bytes written. Wire format is byte-identical to
+/// [`crc32_batch_packed`]; the JS loader uses this with a pooled buffer.
+#[napi]
+pub fn crc32_batch_packed_into(input: Uint8Array, mut output: Uint8Array) -> Result<u32> {
+    crate::util::run_packed_into(&input, &mut output, |data, out| {
+        crate::util::write_u32_batch_into(data, out, crc32_bytes)
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn fnv1a_known_vectors() {
+        // Standard FNV-1a 64-bit test vectors.
+        assert_eq!(fnv1a64_bytes(b""), 0xcbf2_9ce4_8422_2325);
+        assert_eq!(fnv1a64_bytes(b"a"), 0xaf63_dc4c_8601_ec8c);
+        assert_eq!(fnv1a64_bytes(b"foobar"), 0x8594_4171_f739_67e8);
+        // Continue-style matches one-shot.
+        let h = fnv1a64_continue(fnv1a64_bytes(b"foo"), b"bar");
+        assert_eq!(h, fnv1a64_bytes(b"foobar"));
+    }
+
+    #[test]
+    fn crc32_known_vector() {
+        assert_eq!(crc32fast::hash(b""), 0);
+        // Standard CRC-32 check value.
+        assert_eq!(crc32fast::hash(b"123456789"), 0xcbf4_3926);
+        // The napi wrapper agrees.
+        assert_eq!(crc32(Uint8Array::new(b"123456789".to_vec())), 0xcbf4_3926);
+    }
+
+    #[test]
+    fn fnv1a_napi_agrees_with_core() {
+        assert_eq!(
+            fnv1a64(Uint8Array::new(b"foobar".to_vec())),
+            fnv1a64_bytes(b"foobar")
+        );
+    }
+
+    #[test]
+    fn xxh3_stable_and_distinct() {
+        let empty = fast_hash_bytes(b"");
+        assert_eq!(empty, fast_hash_bytes(b""));
+        assert_ne!(empty, fast_hash_bytes(b"a"));
+        assert_eq!(fast_hash_bytes(b"castrum"), fast_hash_bytes(b"castrum"));
+    }
+
+    #[test]
+    fn xxh3_napi_agrees_with_core() {
+        let input = b"castrum xxh3 known-vector check 0123456789";
+        assert_eq!(
+            xxh3(Uint8Array::new(input.to_vec())),
+            fast_hash_bytes(input)
+        );
+        // Deterministic across calls on the same bytes.
+        assert_eq!(
+            xxh3(Uint8Array::new(input.to_vec())),
+            xxh3(Uint8Array::new(input.to_vec()))
+        );
+    }
+}

package/rust/crypto/hmac_sha256.rs

@@ -0,0 +1,88 @@
+// rust/crypto/hmac_sha256.rs — HMAC-SHA256 sign/verify (scalar + HmacSigner instance).
+
+use crate::util::bytes::{hex_decode_32, hex_encode_32, trim_ascii_whitespace};
+use aws_lc_rs::hmac;
+use napi::bindgen_prelude::*;
+use napi_derive::napi;
+
+#[napi]
+pub fn hmac_sha256(key: Uint8Array, data: Buffer) -> Buffer {
+    let key = hmac::Key::new(hmac::HMAC_SHA256, key.as_ref());
+    let tag = hmac::sign(&key, data.as_ref());
+
+    let mut out = [0u8; 64];
+    hex_encode_32(tag.as_ref(), &mut out);
+
+    Buffer::from(out.to_vec())
+}
+
+#[napi]
+pub fn hmac_sha256_verify(key: Uint8Array, data: Buffer, sig: Buffer) -> bool {
+    let sig = trim_ascii_whitespace(sig.as_ref());
+
+    let Some(sig_bytes) = hex_decode_32(sig) else {
+        return false;
+    };
+
+    let key = hmac::Key::new(hmac::HMAC_SHA256, key.as_ref());
+    hmac::verify(&key, data.as_ref(), &sig_bytes).is_ok()
+}
+
+#[napi]
+pub struct HmacSigner {
+    key: hmac::Key,
+}
+
+#[napi]
+impl HmacSigner {
+    #[napi(constructor)]
+    pub fn new(key: Uint8Array) -> Self {
+        Self {
+            key: hmac::Key::new(hmac::HMAC_SHA256, key.as_ref()),
+        }
+    }
+
+    #[napi]
+    pub fn sign(&self, data: Buffer) -> Buffer {
+        let tag = hmac::sign(&self.key, data.as_ref());
+
+        let mut out = [0u8; 64];
+        hex_encode_32(tag.as_ref(), &mut out);
+
+        Buffer::from(out.to_vec())
+    }
+
+    #[napi]
+    pub fn verify(&self, data: Buffer, sig: Buffer) -> bool {
+        let sig = trim_ascii_whitespace(sig.as_ref());
+
+        let Some(sig_bytes) = hex_decode_32(sig) else {
+            return false;
+        };
+
+        hmac::verify(&self.key, data.as_ref(), &sig_bytes).is_ok()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    #[test]
+    fn hmac_sign_then_verify_roundtrip() {
+        let key = aws_lc_rs::hmac::Key::new(aws_lc_rs::hmac::HMAC_SHA256, b"secret-key");
+        let data = b"hello world";
+        let tag = aws_lc_rs::hmac::sign(&key, data);
+
+        let mut hex = [0u8; 64];
+        crate::util::bytes::hex_encode_32(tag.as_ref(), &mut hex);
+        let decoded = crate::util::bytes::hex_decode_32(&hex).expect("valid hex decodes");
+
+        assert!(aws_lc_rs::hmac::verify(&key, data, &decoded).is_ok());
+    }
+
+    #[test]
+    fn hex_decode_32_rejects_bad_length_and_digits() {
+        assert!(crate::util::bytes::hex_decode_32(b"abc").is_none());
+        assert!(crate::util::bytes::hex_decode_32(&[b'0'; 64]).is_some());
+        assert!(crate::util::bytes::hex_decode_32(&[b'g'; 64]).is_none());
+    }
+}

package/rust/crypto/jwt/api.rs

@@ -0,0 +1,286 @@
+// rust/crypto/jwt/api.rs — napi entry points for JWT signing/verification.
+//
+// Thin napi boundary over the pure token core in `token.rs`: scalar sign/
+// verify, the precompiled-key `JwtSigner` instance, the C-ABI `_core` helpers
+// consumed by `rust/ffi.rs`, and the packed sign/verify batches.
+
+use napi::bindgen_prelude::*;
+use napi_derive::napi;
+
+use crate::crypto::base64::base64url_encode_bytes;
+
+use super::{
+    build_token, build_token_with_key, inject_and_payload_b64, inject_and_payload_b64_sonic,
+    inject_ttl_claims, jwt_header_b64, sign_eddsa, verify_token, verify_token_eddsa,
+    verify_token_with_key,
+};
+
+/// Sign a JWT (HS256). `claims` is any JSON value; when it is an object and a
+/// positive `ttlSeconds` is given, `iat`/`exp` are injected (unless present).
+/// `nowSeconds` is the caller-supplied current epoch seconds (keeps the core
+/// time-free and testable). Returns the compact token bytes.
+#[napi]
+pub fn jwt_sign(
+    claims: serde_json::Value,
+    secret: Uint8Array,
+    ttl_seconds: Option<i64>,
+    now_seconds: i64,
+) -> Result<Buffer> {
+    let mut claims = claims;
+    let payload_b64 = inject_and_payload_b64(&mut claims, ttl_seconds, now_seconds)?;
+    Ok(Buffer::from(build_token(
+        jwt_header_b64(),
+        &payload_b64,
+        secret.as_ref(),
+    )))
+}
+
+/// Sign a JWT (HS256) from pre-serialized claim JSON bytes. Avoids the napi
+/// `serde_json::Value` DOM marshal of `jwt_sign` for callers that already hold
+/// the claim bytes (e.g. JSON.stringify'd on the JS side). The claims are
+/// parsed straight into a `sonic_rs::Value` (compact, no per-key heap
+/// `String`). Semantics are identical to `jwt_sign` (incl. `iat`/`exp`
+/// injection).
+#[napi]
+pub fn jwt_sign_bytes(
+    claims_json: Uint8Array,
+    secret: Uint8Array,
+    ttl_seconds: Option<i64>,
+    now_seconds: i64,
+) -> Result<Buffer> {
+    let mut claims: sonic_rs::Value =
+        sonic_rs::from_slice(claims_json.as_ref()).map_err(napi_err)?;
+    let payload_b64 = inject_and_payload_b64_sonic(&mut claims, ttl_seconds, now_seconds)?;
+    Ok(Buffer::from(build_token(
+        jwt_header_b64(),
+        &payload_b64,
+        secret.as_ref(),
+    )))
+}
+
+/// Verify a JWT (HS256 signature + time claims). Returns the decoded claims
+/// object (marshaled from the compact sonic Value), or `null` on any failure
+/// (malformed, bad signature, wrong `alg`, expired, not-yet-valid `nbf`/`iat`,
+/// non-JSON payload).
+#[napi]
+pub fn jwt_verify(
+    env: Env,
+    token: Uint8Array,
+    secret: Uint8Array,
+    now_seconds: i64,
+) -> Result<Unknown<'static>> {
+    let Some(payload) = verify_token(token.as_ref(), secret.as_ref(), now_seconds) else {
+        return crate::json::napi_marshal::sonic_value_to_js(&env, &sonic_rs::Value::new());
+    };
+    match sonic_rs::from_slice::<sonic_rs::Value>(&payload) {
+        Ok(v) => crate::json::napi_marshal::sonic_value_to_js(&env, &v),
+        // The payload already parsed for the time-claim check — unreachable.
+        Err(_) => crate::json::napi_marshal::sonic_value_to_js(&env, &sonic_rs::Value::new()),
+    }
+}
+
+/// Sign an EdDSA (Ed25519) JWT from pre-serialized claim JSON bytes. Semantics
+/// identical to `jwt_sign_bytes` (incl. `iat`/`exp` injection); the signature
+/// is Ed25519 (RFC 8032) under the `EdDSA` alg.
+#[napi]
+pub fn jwt_sign_eddsa(
+    claims_json: Uint8Array,
+    private_key: Uint8Array,
+    ttl_seconds: Option<i64>,
+    now_seconds: i64,
+) -> Result<Buffer> {
+    match sign_eddsa(
+        claims_json.as_ref(),
+        private_key.as_ref(),
+        ttl_seconds,
+        now_seconds,
+    ) {
+        Some(token) => Ok(Buffer::from(token)),
+        None => Err(Error::from_reason(
+            "EdDSA sign failed (invalid claims or private key)",
+        )),
+    }
+}
+
+/// Verify an EdDSA (Ed25519) JWT (signature + time claims). Returns the decoded
+/// claims object, or `null` on any failure.
+#[napi]
+pub fn jwt_verify_eddsa(
+    env: Env,
+    token: Uint8Array,
+    public_key: Uint8Array,
+    now_seconds: i64,
+) -> Result<Unknown<'static>> {
+    let Some(payload) = verify_token_eddsa(token.as_ref(), public_key.as_ref(), now_seconds) else {
+        return crate::json::napi_marshal::sonic_value_to_js(&env, &sonic_rs::Value::new());
+    };
+    match sonic_rs::from_slice::<sonic_rs::Value>(&payload) {
+        Ok(v) => crate::json::napi_marshal::sonic_value_to_js(&env, &v),
+        // The payload already parsed for the time-claim check — unreachable.
+        Err(_) => crate::json::napi_marshal::sonic_value_to_js(&env, &sonic_rs::Value::new()),
+    }
+}
+
+/// Higher-order instance: precompiles the HMAC-SHA256 key once from `secret`,
+/// so `sign`/`verify` never re-derive the key on the per-call path. `ttl` is
+/// fixed at construction (0/absent → no `iat`/`exp` injection).
+#[napi]
+pub struct JwtSigner {
+    pub(crate) key: aws_lc_rs::hmac::Key,
+    ttl_seconds: Option<i64>,
+}
+
+#[napi]
+impl JwtSigner {
+    #[napi(constructor)]
+    pub fn new(secret: Uint8Array, ttl_seconds: Option<i64>) -> Self {
+        Self {
+            key: aws_lc_rs::hmac::Key::new(aws_lc_rs::hmac::HMAC_SHA256, secret.as_ref()),
+            ttl_seconds,
+        }
+    }
+
+    /// Opaque handle to the precompiled key + ttl, for the `bun:ffi` C-ABI
+    /// fast path (`castrum_jwt_signer_*` in rust/ffi.rs). Only valid while THIS
+    /// instance is alive; the JS wrapper holds the instance.
+    #[napi]
+    pub fn inner_ptr(&self) -> u64 {
+        self as *const JwtSigner as u64
+    }
+
+    /// Sign a JWT with the precompiled key. When `ttl` was set at construction,
+    /// `iat`/`exp` are injected into object claims (unless already present).
+    #[napi]
+    pub fn sign(&self, claims: serde_json::Value, now_seconds: i64) -> Result<Buffer> {
+        let mut claims = claims;
+        let payload_b64 = inject_and_payload_b64(&mut claims, self.ttl_seconds, now_seconds)?;
+        Ok(Buffer::from(build_token_with_key(
+            jwt_header_b64(),
+            &payload_b64,
+            &self.key,
+        )))
+    }
+
+    /// Sign a JWT from pre-serialized claim JSON bytes with the precompiled
+    /// key — no napi `serde_json::Value` marshal, no per-call key derivation.
+    #[napi]
+    pub fn sign_bytes(&self, claims_json: Uint8Array, now_seconds: i64) -> Result<Buffer> {
+        let mut claims: sonic_rs::Value =
+            sonic_rs::from_slice(claims_json.as_ref()).map_err(napi_err)?;
+        let payload_b64 = inject_and_payload_b64_sonic(&mut claims, self.ttl_seconds, now_seconds)?;
+        Ok(Buffer::from(build_token_with_key(
+            jwt_header_b64(),
+            &payload_b64,
+            &self.key,
+        )))
+    }
+
+    /// Verify a JWT with the precompiled key (signature + `alg` + time claims).
+    /// Returns the decoded claims object, or `null` on any failure.
+    #[napi]
+    pub fn verify(
+        &self,
+        env: Env,
+        token: Uint8Array,
+        now_seconds: i64,
+    ) -> Result<Unknown<'static>> {
+        let Some(payload) = verify_token_with_key(token.as_ref(), &self.key, now_seconds) else {
+            return crate::json::napi_marshal::sonic_value_to_js(&env, &sonic_rs::Value::new());
+        };
+        match sonic_rs::from_slice::<sonic_rs::Value>(&payload) {
+            Ok(v) => crate::json::napi_marshal::sonic_value_to_js(&env, &v),
+            // The payload already parsed for the time-claim check — unreachable.
+            Err(_) => crate::json::napi_marshal::sonic_value_to_js(&env, &sonic_rs::Value::new()),
+        }
+    }
+}
+
+/// C-ABI support: sign pre-serialized claim JSON with the precompiled key.
+/// `Err(())` on invalid claims JSON (napi parity: throws).
+///
+/// # Safety
+/// `p` must be a valid `*const JwtSigner` from `inner_ptr`, alive for the call.
+pub(crate) unsafe fn jwt_signer_sign_bytes_core(
+    p: *const JwtSigner,
+    claims_json: &[u8],
+    now_seconds: i64,
+) -> std::result::Result<Vec<u8>, ()> {
+    let this = &*p;
+    let mut claims: sonic_rs::Value = sonic_rs::from_slice(claims_json).map_err(|_| ())?;
+    let payload_b64 =
+        inject_and_payload_b64_sonic(&mut claims, this.ttl_seconds, now_seconds).map_err(|_| ())?;
+    Ok(build_token_with_key(
+        jwt_header_b64(),
+        &payload_b64,
+        &this.key,
+    ))
+}
+
+/// C-ABI support: verify a JWT with the precompiled key → the decoded payload
+/// BYTES (valid JSON claims), or None on invalid signature / expired /
+/// malformed. No `serde_json::Value` DOM, no re-serialize.
+///
+/// # Safety
+/// `p` must be a valid `*const JwtSigner` from `inner_ptr`, alive for the call.
+pub(crate) unsafe fn jwt_signer_verify_core(
+    p: *const JwtSigner,
+    token: &[u8],
+    now_seconds: i64,
+) -> Option<Vec<u8>> {
+    let this = &*p;
+    verify_token_with_key(token, &this.key, now_seconds)
+}
+
+fn napi_err(e: impl std::fmt::Display) -> Error {
+    Error::from_reason(e.to_string())
+}
+
+/// Parallel sign batch: packed `[u32 count]{[u32 len][claims-json]}` in →
+/// packed `[u32 count]{[u32 len][token]}` out (same secret/ttl/now for all).
+#[napi]
+pub fn jwt_sign_batch_packed(
+    data: Uint8Array,
+    secret: Uint8Array,
+    ttl_seconds: Option<i64>,
+    now_seconds: i64,
+) -> Result<Buffer> {
+    // Derive the HMAC key ONCE for the whole batch (build_token derives a
+    // fresh key per call), then route through the shared packed batch helper
+    // (zero-alloc serial PackedIter path; rayon direct-write when justified).
+    let key = aws_lc_rs::hmac::Key::new(aws_lc_rs::hmac::HMAC_SHA256, secret.as_ref());
+
+    let sign_one = |claims_json: &[u8]| -> Vec<u8> {
+        let Ok(mut claims) = sonic_rs::from_slice::<sonic_rs::Value>(claims_json) else {
+            return Vec::new();
+        };
+        inject_ttl_claims(&mut claims, ttl_seconds, now_seconds);
+        let header_b64 = jwt_header_b64();
+        let Ok(payload_bytes) = sonic_rs::to_vec(&claims) else {
+            return Vec::new();
+        };
+        let payload_b64 = base64url_encode_bytes(&payload_bytes);
+        build_token_with_key(header_b64, &payload_b64, &key)
+    };
+
+    crate::util::run_packed_batch(data.as_ref(), sign_one).map(Buffer::from)
+}
+
+/// Parallel verify batch: packed `[u32 count]{[u32 len][token]}` in → bitset
+/// (`[u32 count][ceil(n/8) bytes]`) of valid tokens.
+#[napi]
+pub fn jwt_verify_batch_packed(
+    data: Uint8Array,
+    secret: Uint8Array,
+    now_seconds: i64,
+) -> Result<Buffer> {
+    // Derive the HMAC key ONCE for the whole batch (verify_token derives a
+    // fresh key per call), then route through the shared bitset batch helper
+    // (zero-alloc serial PackedIter path; rayon direct-write when justified).
+    let key = aws_lc_rs::hmac::Key::new(aws_lc_rs::hmac::HMAC_SHA256, secret.as_ref());
+    crate::util::run_bitset_batch(
+        data.as_ref(),
+        |token| verify_token_with_key(token, &key, now_seconds).is_some(),
+        4096,
+    )
+    .map(Buffer::from)
+}

package/rust/crypto/jwt/mod.rs

@@ -0,0 +1,22 @@
+//! HS256 / EdDSA JSON Web Tokens.
+//!
+//! Split into a small folder so the token machinery is navigable:
+//!   - `token.rs` — pure token core (headers, HMAC, split/build/verify, zero-DOM
+//!     time-claim checks, `iat`/`exp` injection). Reused by the napi boundary,
+//!     the C-ABI fast paths in `rust/ffi.rs`, and `crate::crypto::ed25519`.
+//!   - `api.rs` — napi entry points (scalar sign/verify, precompiled-key
+//!     `JwtSigner` instance, C-ABI `_core` helpers, packed sign/verify batches).
+//!   - `tests.rs` — unit tests.
+//!
+//! All items are re-exported at this module root (`pub use self::token::*` +
+//! `pub use self::api::*`) so existing `crate::crypto::jwt::*` call sites keep
+//! working unchanged.
+
+mod api;
+mod token;
+
+#[cfg(test)]
+mod tests;
+
+pub use self::api::*;
+pub use self::token::*;