castrum 0.9.2 → 0.9.4

package/rust/ingress/cors.rs

@@ -0,0 +1,403 @@
+// rust/ingress/cors.rs — CORS engine extracted from ingress.rs
+// Pre-computes method bitmask for O(1) method matching
+
+use crate::http::headers::HeaderRefs;
+use crate::http::method::MethodKind;
+use crate::util::bytes::ascii_eq_ignore_case;
+use crate::util::trim_ascii_whitespace;
+use napi::{Error, Result, Status};
+use napi_derive::napi;
+
+// ── CORS engine ───────────────────────────────────────────────────
+#[derive(Clone)]
+pub enum CorsMode {
+    Disabled,
+    Wildcard,
+    Allowlist(Vec<Box<[u8]>>),
+}
+
+#[derive(Clone)]
+pub struct CorsEngine {
+    mode: CorsMode,
+    credentials: bool,
+    methods_wildcard: bool,
+    // Bitmask of allowed methods for O(1) lookup
+    method_bits: u16,
+    headers_wildcard: bool,
+    headers: Vec<Box<[u8]>>,
+}
+
+pub struct CorsEvaluation {
+    pub allowed: bool,
+    pub preflight: bool,
+}
+
+impl CorsEngine {
+    pub fn disabled() -> Self {
+        Self {
+            mode: CorsMode::Disabled,
+            credentials: false,
+            methods_wildcard: false,
+            method_bits: 0,
+            headers_wildcard: false,
+            headers: Vec::new(),
+        }
+    }
+
+    pub fn from_options(opts: Option<CorsOptions>) -> Result<Self> {
+        let Some(opts) = opts else {
+            return Ok(Self::disabled());
+        };
+
+        let credentials = opts.allow_credentials.unwrap_or(false);
+
+        let mode = match opts.allow_origin {
+            Some(list) if !list.is_empty() => {
+                if list.iter().any(|o| o == "*") {
+                    if credentials {
+                        return Err(Error::new(
+                            Status::InvalidArg,
+                            "CORS allowCredentials cannot be used with allowOrigin ['*']",
+                        ));
+                    }
+                    CorsMode::Wildcard
+                } else {
+                    CorsMode::Allowlist(
+                        list.iter()
+                            .map(|s| s.as_bytes().to_vec().into_boxed_slice())
+                            .collect(),
+                    )
+                }
+            }
+            _ => {
+                if credentials {
+                    return Err(Error::new(
+                        Status::InvalidArg,
+                        "CORS allowCredentials requires an explicit allowOrigin list",
+                    ));
+                }
+                CorsMode::Wildcard
+            }
+        };
+
+        let (methods_wildcard, method_bits) = parse_allowed_methods_bitset(opts.allow_methods);
+        let (headers_wildcard, headers) = parse_allowed_headers(opts.allow_headers);
+
+        Ok(Self {
+            mode,
+            credentials,
+            methods_wildcard,
+            method_bits,
+            headers_wildcard,
+            headers,
+        })
+    }
+
+    #[inline]
+    pub fn evaluate(&self, method: MethodKind, headers: &HeaderRefs) -> CorsEvaluation {
+        let origin = match headers.origin() {
+            Some(o) => o,
+            None => {
+                return CorsEvaluation {
+                    allowed: false,
+                    preflight: false,
+                }
+            }
+        };
+
+        let preflight = method == MethodKind::Options && headers.has_acrm();
+
+        let mut allowed = match &self.mode {
+            CorsMode::Disabled => false,
+            CorsMode::Wildcard => !self.credentials,
+            CorsMode::Allowlist(list) => {
+                let origin_trim = trim_ascii_whitespace(origin);
+                list.iter().any(|allowed| &**allowed == origin_trim)
+            }
+        };
+
+        if allowed {
+            if preflight {
+                allowed = self.preflight_method_allowed(headers.acrm())
+                    && self.headers_allowed(headers.acrh());
+            } else {
+                allowed = self.method_allowed_kind(method);
+            }
+        }
+
+        CorsEvaluation { allowed, preflight }
+    }
+
+    #[inline(always)]
+    fn method_allowed_kind(&self, kind: MethodKind) -> bool {
+        if self.methods_wildcard {
+            return true;
+        }
+
+        if self.method_bits == 0 {
+            return matches!(kind, MethodKind::Get | MethodKind::Head | MethodKind::Post);
+        }
+
+        (self.method_bits & kind.bit()) != 0
+    }
+
+    #[inline]
+    fn preflight_method_allowed(&self, acrm: Option<&[u8]>) -> bool {
+        let Some(acrm) = acrm else {
+            return false;
+        };
+
+        let trimmed = trim_ascii_whitespace(acrm);
+        if trimmed.is_empty() {
+            return false;
+        }
+
+        let kind = MethodKind::from_bytes_ignore_case(trimmed);
+        self.method_allowed_kind(kind)
+    }
+
+    #[inline]
+    fn headers_allowed(&self, acrh: Option<&[u8]>) -> bool {
+        let Some(acrh) = acrh else {
+            return true;
+        };
+
+        if self.headers_wildcard {
+            return true;
+        }
+
+        for requested in acrh.split(|&b| b == b',') {
+            let name = trim_ascii_whitespace(requested);
+            if name.is_empty() {
+                continue;
+            }
+
+            if self.headers.is_empty() {
+                if !is_cors_safelisted_request_header(name) {
+                    return false;
+                }
+            } else if !self
+                .headers
+                .iter()
+                .any(|allowed| ascii_eq_ignore_case(name, allowed.as_ref()))
+            {
+                return false;
+            }
+        }
+
+        true
+    }
+}
+
+fn is_cors_safelisted_request_header(name: &[u8]) -> bool {
+    ascii_eq_ignore_case(name, b"accept")
+        || ascii_eq_ignore_case(name, b"accept-language")
+        || ascii_eq_ignore_case(name, b"content-language")
+        || ascii_eq_ignore_case(name, b"content-type")
+}
+
+fn parse_allowed_methods_bitset(list: Option<Vec<String>>) -> (bool, u16) {
+    let Some(list) = list else {
+        return (false, 0);
+    };
+
+    let mut bits = 0u16;
+
+    for raw in list {
+        let trimmed = raw.trim();
+
+        if trimmed == "*" {
+            return (true, 0);
+        }
+
+        if trimmed.is_empty() {
+            continue;
+        }
+
+        let upper = trimmed.to_ascii_uppercase();
+        let kind = MethodKind::from_str(&upper);
+
+        if kind != MethodKind::Other {
+            bits |= kind.bit();
+        }
+    }
+
+    (false, bits)
+}
+
+fn parse_allowed_headers(list: Option<Vec<String>>) -> (bool, Vec<Box<[u8]>>) {
+    let Some(list) = list else {
+        return (false, Vec::new());
+    };
+
+    let mut headers = Vec::new();
+
+    for raw in list {
+        let trimmed = raw.trim();
+
+        if trimmed == "*" {
+            return (true, Vec::new());
+        }
+
+        if trimmed.is_empty() {
+            continue;
+        }
+
+        headers.push(trimmed.to_ascii_lowercase().into_bytes().into_boxed_slice());
+    }
+
+    (false, headers)
+}
+
+// ── NAPI option struct ───────────────────────────────────────────
+#[napi(object)]
+#[derive(Clone)]
+pub struct CorsOptions {
+    pub allow_origin: Option<Vec<String>>,
+    pub allow_methods: Option<Vec<String>>,
+    pub allow_headers: Option<Vec<String>>,
+    pub allow_credentials: Option<bool>,
+    // NOTE: expose_headers / max_age are intentionally NOT here — the Rust
+    // engine only EVALUATES origin/method/header/credentials. The emitted
+    // `Access-Control-Expose-Headers` / `Access-Control-Max-Age` headers are
+    // produced by the TS header templates (both ingress paths), which read the
+    // same `cors` option object.
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{CorsEngine, CorsOptions};
+    use crate::http::headers::HeaderRefs;
+    use crate::http::method::MethodKind;
+    use crate::test_support::pack_headers;
+
+    fn cors_options(
+        origin: Vec<String>,
+        methods: Vec<String>,
+        headers: Vec<String>,
+        creds: bool,
+    ) -> CorsOptions {
+        CorsOptions {
+            allow_origin: Some(origin),
+            allow_methods: Some(methods),
+            allow_headers: Some(headers),
+            allow_credentials: Some(creds),
+        }
+    }
+
+    #[test]
+    fn cors_wildcard_with_credentials_rejected() {
+        let opts = cors_options(vec!["*".to_string()], vec![], vec![], true);
+        assert!(CorsEngine::from_options(Some(opts)).is_err());
+    }
+
+    #[test]
+    fn cors_wildcard_without_credentials_ok() {
+        let opts = cors_options(vec!["*".to_string()], vec![], vec![], false);
+        let engine = CorsEngine::from_options(Some(opts)).unwrap();
+        let packed = pack_headers([("origin", "https://anywhere.com")]);
+        let h = HeaderRefs::parse(&packed, false, 100).unwrap();
+        let ev = engine.evaluate(MethodKind::Get, &h);
+        assert!(ev.allowed);
+        assert!(!ev.preflight);
+    }
+
+    #[test]
+    fn cors_allowlist_matching_origin() {
+        let opts = cors_options(
+            vec!["https://app.example.com".to_string()],
+            vec!["GET".to_string(), "POST".to_string()],
+            vec![],
+            true,
+        );
+        let engine = CorsEngine::from_options(Some(opts)).unwrap();
+        let packed = pack_headers([("origin", "https://app.example.com")]);
+        let h = HeaderRefs::parse(&packed, false, 100).unwrap();
+        let ev = engine.evaluate(MethodKind::Get, &h);
+        assert!(ev.allowed);
+    }
+
+    #[test]
+    fn cors_allowlist_non_matching_origin() {
+        let opts = cors_options(
+            vec!["https://app.example.com".to_string()],
+            vec!["GET".to_string()],
+            vec![],
+            true,
+        );
+        let engine = CorsEngine::from_options(Some(opts)).unwrap();
+        let packed = pack_headers([("origin", "https://evil.example.net")]);
+        let h = HeaderRefs::parse(&packed, false, 100).unwrap();
+        let ev = engine.evaluate(MethodKind::Get, &h);
+        assert!(!ev.allowed);
+    }
+
+    #[test]
+    fn cors_no_origin_never_allowed() {
+        let opts = cors_options(vec!["*".to_string()], vec![], vec![], false);
+        let engine = CorsEngine::from_options(Some(opts)).unwrap();
+        let packed = pack_headers([]);
+        let h = HeaderRefs::parse(&packed, false, 100).unwrap();
+        let ev = engine.evaluate(MethodKind::Get, &h);
+        assert!(!ev.allowed);
+    }
+
+    #[test]
+    fn cors_preflight_allowed() {
+        let opts = cors_options(
+            vec!["https://app.example.com".to_string()],
+            vec!["POST".to_string()],
+            vec!["Content-Type".to_string()],
+            true,
+        );
+        let engine = CorsEngine::from_options(Some(opts)).unwrap();
+        let packed = pack_headers([
+            ("origin", "https://app.example.com"),
+            ("access-control-request-method", "POST"),
+            ("access-control-request-headers", "Content-Type"),
+        ]);
+        let h = HeaderRefs::parse(&packed, true, 100).unwrap();
+        let ev = engine.evaluate(MethodKind::Options, &h);
+        assert!(ev.preflight);
+        assert!(ev.allowed);
+    }
+
+    #[test]
+    fn cors_preflight_disallowed_method() {
+        let opts = cors_options(
+            vec!["https://app.example.com".to_string()],
+            vec!["GET".to_string()],
+            vec![],
+            true,
+        );
+        let engine = CorsEngine::from_options(Some(opts)).unwrap();
+        let packed = pack_headers([
+            ("origin", "https://app.example.com"),
+            ("access-control-request-method", "DELETE"),
+        ]);
+        let h = HeaderRefs::parse(&packed, true, 100).unwrap();
+        let ev = engine.evaluate(MethodKind::Options, &h);
+        assert!(ev.preflight);
+        assert!(!ev.allowed);
+    }
+
+    #[test]
+    fn cors_preflight_disallowed_header() {
+        let opts = cors_options(
+            vec!["https://app.example.com".to_string()],
+            vec!["POST".to_string()],
+            vec!["Content-Type".to_string()],
+            true,
+        );
+        let engine = CorsEngine::from_options(Some(opts)).unwrap();
+        let packed = pack_headers([
+            ("origin", "https://app.example.com"),
+            ("access-control-request-method", "POST"),
+            ("access-control-request-headers", "X-Secret-Token"),
+        ]);
+        let h = HeaderRefs::parse(&packed, true, 100).unwrap();
+        let ev = engine.evaluate(MethodKind::Options, &h);
+        assert!(ev.preflight);
+        assert!(!ev.allowed);
+    }
+}

package/rust/ingress/ingress_constants.rs

@@ -0,0 +1,209 @@
+// rust/ingress/ingress_constants.rs — NAPI exports for the ingress binary layout
+//
+// The NUMERIC values live in `output.rs` (the single source of truth). This
+// module re-exports them to JavaScript via NAPI so TypeScript (via
+// `src/ingress/constants.ts`) always reads the same numbers the Rust hot path
+// uses — the two copies can never drift.
+
+// The `as u32` on each const is an intentional explicit-width projection of the
+// layout values (which are already u32) so the JS surface reads as a u32 layout
+// contract. Newer clippy (>= 1.97) flags these as redundant casts.
+#![allow(clippy::unnecessary_cast)]
+
+use crate::ingress::output;
+use napi_derive::napi;
+
+// ── Output buffer layout ───────────────────────────────────
+#[napi]
+pub const INGRESS_OUT_VERDICT: u32 = output::OUT_VERDICT as u32;
+#[napi]
+pub const INGRESS_OUT_ERROR_CODE: u32 = output::OUT_ERROR_CODE as u32;
+#[napi]
+pub const INGRESS_OUT_STATUS: u32 = output::OUT_STATUS as u32;
+#[napi]
+pub const INGRESS_OUT_FLAGS: u32 = output::OUT_FLAGS as u32;
+#[napi]
+pub const INGRESS_OUT_RATE_LIMIT: u32 = output::OUT_RATE_LIMIT as u32;
+#[napi]
+pub const INGRESS_OUT_RATE_REMAINING: u32 = output::OUT_RATE_REMAINING as u32;
+#[napi]
+pub const INGRESS_OUT_RATE_RESET: u32 = output::OUT_RATE_RESET as u32;
+#[napi]
+pub const INGRESS_OUT_RETRY_AFTER: u32 = output::OUT_RETRY_AFTER as u32;
+#[napi]
+pub const INGRESS_OUT_COOKIES_JSON_LEN: u32 = output::OUT_COOKIES_JSON_LEN as u32;
+#[napi]
+pub const INGRESS_OUT_QUERY_JSON_LEN: u32 = output::OUT_QUERY_JSON_LEN as u32;
+#[napi]
+pub const INGRESS_OUT_HEADER_VARIANT: u32 = output::OUT_HEADER_VARIANT as u32;
+#[napi]
+pub const INGRESS_OUT_BODY_JSON_LEN: u32 = output::OUT_BODY_JSON_LEN as u32;
+#[napi]
+pub const INGRESS_OUT_DATA_START: u32 = output::OUT_DATA_START as u32;
+
+// ── Flags ──────────────────────────────────────────────────
+#[napi]
+pub const INGRESS_FLAG_HAS_COOKIES: u32 = output::FLAG_HAS_COOKIES;
+#[napi]
+pub const INGRESS_FLAG_HAS_QUERY: u32 = output::FLAG_HAS_QUERY;
+#[napi]
+pub const INGRESS_FLAG_BODY_VALID_JSON: u32 = output::FLAG_BODY_VALID_JSON;
+#[napi]
+pub const INGRESS_FLAG_SCHEMA_VALID: u32 = output::FLAG_SCHEMA_VALID;
+#[napi]
+pub const INGRESS_FLAG_CORS_ALLOWED: u32 = output::FLAG_CORS_ALLOWED;
+#[napi]
+pub const INGRESS_FLAG_IS_PREFLIGHT: u32 = output::FLAG_IS_PREFLIGHT;
+#[napi]
+pub const INGRESS_FLAG_RATE_LIMITED: u32 = output::FLAG_RATE_LIMITED;
+#[napi]
+pub const INGRESS_FLAG_HTTPS: u32 = output::FLAG_HTTPS;
+#[napi]
+pub const INGRESS_FLAG_TRUSTED_PROXY: u32 = output::FLAG_TRUSTED_PROXY;
+#[napi]
+pub const INGRESS_FLAG_BODY_TRUNCATED: u32 = output::FLAG_BODY_TRUNCATED;
+
+// ── Header variant bits ────────────────────────────────────
+#[napi]
+pub const INGRESS_HV_JSON: u32 = output::HV_JSON as u32;
+#[napi]
+pub const INGRESS_HV_CORS_SIMPLE: u32 = output::HV_CORS_SIMPLE as u32;
+#[napi]
+pub const INGRESS_HV_CORS_PREFLIGHT: u32 = output::HV_CORS_PREFLIGHT as u32;
+#[napi]
+pub const INGRESS_HV_RATE_ACTIVE: u32 = output::HV_RATE_ACTIVE as u32;
+#[napi]
+pub const INGRESS_HV_RATE_LIMITED: u32 = output::HV_RATE_LIMITED as u32;
+#[napi]
+pub const INGRESS_HV_COUNT: u32 = output::HV_COUNT as u32;
+
+// ── Error codes ────────────────────────────────────────────
+#[napi]
+pub const INGRESS_ERR_NONE: u32 = output::ERR_CODE_NONE as u32;
+#[napi]
+pub const INGRESS_ERR_CORS_PREFLIGHT: u32 = output::ERR_CODE_CORS_PREFLIGHT as u32;
+#[napi]
+pub const INGRESS_ERR_RATE_LIMITED: u32 = output::ERR_CODE_RATE_LIMITED as u32;
+#[napi]
+pub const INGRESS_ERR_BODY_TOO_LARGE: u32 = output::ERR_CODE_BODY_TOO_LARGE as u32;
+#[napi]
+pub const INGRESS_ERR_INVALID_JSON: u32 = output::ERR_CODE_INVALID_JSON as u32;
+#[napi]
+pub const INGRESS_ERR_SCHEMA_VALIDATION: u32 = output::ERR_CODE_SCHEMA_VALIDATION as u32;
+#[napi]
+pub const INGRESS_ERR_BAD_REQUEST: u32 = output::ERR_CODE_BAD_REQUEST as u32;
+#[napi]
+pub const INGRESS_ERR_REQUEST_TOO_LARGE: u32 = output::ERR_CODE_REQUEST_TOO_LARGE as u32;
+#[napi]
+pub const INGRESS_ERR_INTERNAL: u32 = output::ERR_CODE_INTERNAL as u32;
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::ingress::output;
+
+    /// The napi projections must never drift from the single numeric source
+    /// (`output.rs`). If a layout constant is changed in `output.rs` and the
+    /// projection here is not updated, this test fails.
+    #[test]
+    fn out_constants_match_output_source() {
+        assert_eq!(INGRESS_OUT_VERDICT as u32, output::OUT_VERDICT as u32);
+        assert_eq!(INGRESS_OUT_ERROR_CODE as u32, output::OUT_ERROR_CODE as u32);
+        assert_eq!(INGRESS_OUT_STATUS as u32, output::OUT_STATUS as u32);
+        assert_eq!(INGRESS_OUT_FLAGS as u32, output::OUT_FLAGS as u32);
+        assert_eq!(INGRESS_OUT_RATE_LIMIT as u32, output::OUT_RATE_LIMIT as u32);
+        assert_eq!(
+            INGRESS_OUT_RATE_REMAINING as u32,
+            output::OUT_RATE_REMAINING as u32
+        );
+        assert_eq!(INGRESS_OUT_RATE_RESET as u32, output::OUT_RATE_RESET as u32);
+        assert_eq!(
+            INGRESS_OUT_RETRY_AFTER as u32,
+            output::OUT_RETRY_AFTER as u32
+        );
+        assert_eq!(
+            INGRESS_OUT_COOKIES_JSON_LEN as u32,
+            output::OUT_COOKIES_JSON_LEN as u32
+        );
+        assert_eq!(
+            INGRESS_OUT_QUERY_JSON_LEN as u32,
+            output::OUT_QUERY_JSON_LEN as u32
+        );
+        assert_eq!(
+            INGRESS_OUT_HEADER_VARIANT as u32,
+            output::OUT_HEADER_VARIANT as u32
+        );
+        assert_eq!(
+            INGRESS_OUT_BODY_JSON_LEN as u32,
+            output::OUT_BODY_JSON_LEN as u32
+        );
+        assert_eq!(INGRESS_OUT_DATA_START as u32, output::OUT_DATA_START as u32);
+    }
+
+    #[test]
+    fn flag_constants_match_output_source() {
+        assert_eq!(INGRESS_FLAG_HAS_COOKIES, output::FLAG_HAS_COOKIES);
+        assert_eq!(INGRESS_FLAG_HAS_QUERY, output::FLAG_HAS_QUERY);
+        assert_eq!(INGRESS_FLAG_BODY_VALID_JSON, output::FLAG_BODY_VALID_JSON);
+        assert_eq!(INGRESS_FLAG_SCHEMA_VALID, output::FLAG_SCHEMA_VALID);
+        assert_eq!(INGRESS_FLAG_CORS_ALLOWED, output::FLAG_CORS_ALLOWED);
+        assert_eq!(INGRESS_FLAG_IS_PREFLIGHT, output::FLAG_IS_PREFLIGHT);
+        assert_eq!(INGRESS_FLAG_RATE_LIMITED, output::FLAG_RATE_LIMITED);
+        assert_eq!(INGRESS_FLAG_HTTPS, output::FLAG_HTTPS);
+        assert_eq!(INGRESS_FLAG_TRUSTED_PROXY, output::FLAG_TRUSTED_PROXY);
+        assert_eq!(INGRESS_FLAG_BODY_TRUNCATED, output::FLAG_BODY_TRUNCATED);
+    }
+
+    #[test]
+    fn hv_constants_match_output_source() {
+        assert_eq!(INGRESS_HV_JSON as u32, output::HV_JSON as u32);
+        assert_eq!(INGRESS_HV_CORS_SIMPLE as u32, output::HV_CORS_SIMPLE as u32);
+        assert_eq!(
+            INGRESS_HV_CORS_PREFLIGHT as u32,
+            output::HV_CORS_PREFLIGHT as u32
+        );
+        assert_eq!(INGRESS_HV_RATE_ACTIVE as u32, output::HV_RATE_ACTIVE as u32);
+        assert_eq!(
+            INGRESS_HV_RATE_LIMITED as u32,
+            output::HV_RATE_LIMITED as u32
+        );
+        assert_eq!(INGRESS_HV_COUNT as u32, output::HV_COUNT as u32);
+    }
+
+    #[test]
+    fn err_constants_match_output_source() {
+        assert_eq!(INGRESS_ERR_NONE as u32, output::ERR_CODE_NONE as u32);
+        assert_eq!(
+            INGRESS_ERR_CORS_PREFLIGHT as u32,
+            output::ERR_CODE_CORS_PREFLIGHT as u32
+        );
+        assert_eq!(
+            INGRESS_ERR_RATE_LIMITED as u32,
+            output::ERR_CODE_RATE_LIMITED as u32
+        );
+        assert_eq!(
+            INGRESS_ERR_BODY_TOO_LARGE as u32,
+            output::ERR_CODE_BODY_TOO_LARGE as u32
+        );
+        assert_eq!(
+            INGRESS_ERR_INVALID_JSON as u32,
+            output::ERR_CODE_INVALID_JSON as u32
+        );
+        assert_eq!(
+            INGRESS_ERR_SCHEMA_VALIDATION as u32,
+            output::ERR_CODE_SCHEMA_VALIDATION as u32
+        );
+        assert_eq!(
+            INGRESS_ERR_BAD_REQUEST as u32,
+            output::ERR_CODE_BAD_REQUEST as u32
+        );
+        assert_eq!(
+            INGRESS_ERR_REQUEST_TOO_LARGE as u32,
+            output::ERR_CODE_REQUEST_TOO_LARGE as u32
+        );
+        assert_eq!(
+            INGRESS_ERR_INTERNAL as u32,
+            output::ERR_CODE_INTERNAL as u32
+        );
+    }
+}