maple-sdk 4.0.2

Maple Rust SDK for secure AI APIs, encrypted sessions, and Nitro attestation
Documentation
use std::{fmt, str::FromStr};

use base64::{engine::general_purpose::STANDARD, Engine as _};
use bytes::Bytes;
use http::{HeaderName, HeaderValue, Method, Uri};
use p256::elliptic_curve::rand_core::{OsRng, RngCore};
use serde::{Deserialize, Serialize, Serializer};
use zeroize::{Zeroize, ZeroizeOnDrop, Zeroizing};

use super::{Result, TransportV2Error, ROUTING_KEY_HEADER};

const VERSION: u8 = 2;
const REQUEST_ID_BYTES: usize = 16;
const METADATA_LENGTH_BYTES: usize = 4;
const MAX_METADATA_BYTES: usize = 128 * 1024;
const MAX_BODY_BYTES: usize = 50 * 1024 * 1024;
const MAX_CREDENTIAL_BYTES: usize = 16 * 1024;
const MAX_METHOD_BYTES: usize = 32;
const MAX_TARGET_BYTES: usize = 16 * 1024;
const MAX_HEADER_COUNT: usize = 64;

#[derive(Clone, Copy, Eq, Hash, Ord, PartialEq, PartialOrd)]
pub(super) struct RequestId([u8; REQUEST_ID_BYTES]);

impl RequestId {
    pub(super) fn random() -> Result<Self> {
        let mut bytes = [0; REQUEST_ID_BYTES];
        OsRng
            .try_fill_bytes(&mut bytes)
            .map_err(|_| TransportV2Error::RandomnessUnavailable)?;
        Ok(Self(bytes))
    }

    #[cfg(test)]
    pub(super) const fn from_bytes(bytes: [u8; REQUEST_ID_BYTES]) -> Self {
        Self(bytes)
    }

    pub(super) const fn as_bytes(&self) -> &[u8; REQUEST_ID_BYTES] {
        &self.0
    }
}

impl fmt::Debug for RequestId {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter.write_str("RequestId(")?;
        formatter.write_str(&hex::encode(self.0))?;
        formatter.write_str(")")
    }
}

impl fmt::Display for RequestId {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter.write_str(&hex::encode(self.0))
    }
}

#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
pub(crate) enum CredentialKind {
    Bearer,
    ApiKey,
    Resumption,
}

#[derive(Clone, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub(crate) struct Credential {
    kind: CredentialKind,
    value: String,
}

impl Credential {
    pub(crate) fn new(kind: CredentialKind, value: String) -> Result<Self> {
        if value.is_empty()
            || value.len() > MAX_CREDENTIAL_BYTES
            || !value.bytes().all(|byte| matches!(byte, 0x21..=0x7e))
        {
            return Err(TransportV2Error::InvalidRequest);
        }
        Ok(Self { kind, value })
    }
}

impl fmt::Debug for Credential {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("Credential")
            .field("kind", &self.kind)
            .field("value_bytes", &self.value.len())
            .finish()
    }
}

impl Drop for Credential {
    fn drop(&mut self) {
        self.value.zeroize();
    }
}

#[derive(Clone, Eq, PartialEq, Zeroize, ZeroizeOnDrop)]
pub(crate) struct CacheNamespaceRoot([u8; 32]);

impl CacheNamespaceRoot {
    pub(crate) const fn from_bytes(bytes: [u8; 32]) -> Self {
        Self(bytes)
    }
}

impl fmt::Debug for CacheNamespaceRoot {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter.write_str("CacheNamespaceRoot([REDACTED])")
    }
}

impl Serialize for CacheNamespaceRoot {
    fn serialize<S>(&self, serializer: S) -> std::result::Result<S::Ok, S::Error>
    where
        S: Serializer,
    {
        let encoded = Zeroizing::new(STANDARD.encode(self.0));
        serializer.serialize_str(encoded.as_str())
    }
}

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub(crate) struct LogicalHeader {
    name: String,
    value: String,
}

impl LogicalHeader {
    pub(crate) fn new(name: String, value: String) -> Result<Self> {
        let header = Self { name, value };
        validate_header(&header)?;
        Ok(header)
    }

    pub(crate) fn name(&self) -> &str {
        &self.name
    }

    pub(crate) fn value(&self) -> &str {
        &self.value
    }
}

pub(crate) struct LogicalRequest {
    credential: Option<Credential>,
    cache_namespace_root: Option<CacheNamespaceRoot>,
    method: Method,
    target: String,
    headers: Vec<LogicalHeader>,
    body: Option<Bytes>,
}

impl LogicalRequest {
    pub(crate) fn new(
        credential: Option<Credential>,
        cache_namespace_root: Option<CacheNamespaceRoot>,
        method: Method,
        target: String,
        headers: Vec<LogicalHeader>,
        body: Option<Bytes>,
    ) -> Result<Self> {
        let request = Self {
            credential,
            cache_namespace_root,
            method,
            target,
            headers,
            body,
        };
        request.validate()?;
        Ok(request)
    }

    fn validate(&self) -> Result<()> {
        if self.method.as_str().len() > MAX_METHOD_BYTES {
            return Err(TransportV2Error::InvalidRequest);
        }
        validate_target(&self.target)?;
        validate_headers(&self.headers)?;
        if self.body.as_ref().map_or(0, Bytes::len) > MAX_BODY_BYTES {
            return Err(TransportV2Error::InvalidRequest);
        }
        Ok(())
    }

    pub(crate) fn encode(&self) -> Result<Zeroizing<Vec<u8>>> {
        self.validate()?;
        let metadata = RequestMetadata {
            version: VERSION,
            credential: self.credential.clone(),
            cache_namespace_root: self.cache_namespace_root.clone(),
            method: self.method.as_str().to_string(),
            target: self.target.clone(),
            headers: self.headers.clone(),
            body_present: self.body.is_some(),
        };
        let encoded_metadata = Zeroizing::new(
            serde_json::to_vec(&metadata).map_err(|_| TransportV2Error::InvalidRequest)?,
        );
        if encoded_metadata.len() > MAX_METADATA_BYTES {
            return Err(TransportV2Error::InvalidRequest);
        }

        let body = self.body.as_deref().unwrap_or_default();
        let mut encoded = Zeroizing::new(Vec::with_capacity(
            METADATA_LENGTH_BYTES + encoded_metadata.len() + body.len(),
        ));
        encoded.extend_from_slice(&(encoded_metadata.len() as u32).to_be_bytes());
        encoded.extend_from_slice(&encoded_metadata);
        encoded.extend_from_slice(body);
        Ok(encoded)
    }
}

#[derive(Serialize)]
struct RequestMetadata {
    version: u8,
    credential: Option<Credential>,
    cache_namespace_root: Option<CacheNamespaceRoot>,
    method: String,
    target: String,
    headers: Vec<LogicalHeader>,
    body_present: bool,
}

fn validate_target(target: &str) -> Result<()> {
    if target.is_empty()
        || target.len() > MAX_TARGET_BYTES
        || !target.starts_with('/')
        || target.starts_with("//")
        || target.contains(['#', '\\'])
    {
        return Err(TransportV2Error::InvalidRequest);
    }
    let uri = Uri::from_str(target).map_err(|_| TransportV2Error::InvalidRequest)?;
    if uri.scheme().is_some()
        || uri.authority().is_some()
        || uri
            .path_and_query()
            .is_none_or(|path_and_query| path_and_query.as_str() != target)
    {
        return Err(TransportV2Error::InvalidRequest);
    }
    Ok(())
}

fn validate_headers(headers: &[LogicalHeader]) -> Result<()> {
    if headers.len() > MAX_HEADER_COUNT {
        return Err(TransportV2Error::InvalidRequest);
    }
    for header in headers {
        validate_header(header)?;
    }
    Ok(())
}

fn validate_header(header: &LogicalHeader) -> Result<()> {
    let parsed_name = HeaderName::from_bytes(header.name.as_bytes())
        .map_err(|_| TransportV2Error::InvalidRequest)?;
    if parsed_name.as_str() != header.name || is_gateway_controlled_header(parsed_name.as_str()) {
        return Err(TransportV2Error::InvalidRequest);
    }
    HeaderValue::from_str(&header.value).map_err(|_| TransportV2Error::InvalidRequest)?;
    Ok(())
}

fn is_gateway_controlled_header(name: &str) -> bool {
    matches!(
        name,
        "authorization"
            | "proxy-authorization"
            | "cookie"
            | "set-cookie"
            | "host"
            | "content-length"
            | "transfer-encoding"
            | "connection"
            | "keep-alive"
            | "te"
            | "trailer"
            | "upgrade"
            | "forwarded"
            | "via"
            | "x-forwarded-for"
            | "x-forwarded-host"
            | "x-forwarded-proto"
            | "x-session-id"
            | ROUTING_KEY_HEADER
    )
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn envelope_uses_bounded_metadata_and_a_raw_body_tail() {
        let body = Bytes::from_static(&[0, 1, 2, 0xfe, 0xff]);
        let request = LogicalRequest::new(
            Some(Credential::new(CredentialKind::Bearer, "signed.token".into()).unwrap()),
            Some(CacheNamespaceRoot::from_bytes([0x22; 32])),
            Method::POST,
            "/v1/chat/completions?trace=1".into(),
            vec![LogicalHeader::new("content-type".into(), "application/json".into()).unwrap()],
            Some(body.clone()),
        )
        .unwrap();
        let encoded = request.encode().unwrap();
        assert!(encoded.ends_with(&body));
        let metadata_length = u32::from_be_bytes(encoded[..4].try_into().unwrap()) as usize;
        let metadata: serde_json::Value =
            serde_json::from_slice(&encoded[4..4 + metadata_length]).unwrap();
        assert_eq!(metadata["version"], 2);
        assert_eq!(metadata["credential"]["kind"], "bearer");
        assert_eq!(metadata["credential"]["value"], "signed.token");
        assert_eq!(
            metadata["cache_namespace_root"],
            STANDARD.encode([0x22; 32])
        );
        assert_eq!(metadata["body_present"], true);
    }

    #[test]
    fn absent_and_present_empty_bodies_are_distinct() {
        let make = |body| {
            LogicalRequest::new(None, None, Method::POST, "/v1/test".into(), vec![], body)
                .unwrap()
                .encode()
                .unwrap()
        };
        let absent = make(None);
        let empty = make(Some(Bytes::new()));
        assert_ne!(absent, empty);
        for (encoded, expected) in [(&absent, false), (&empty, true)] {
            let length = u32::from_be_bytes(encoded[..4].try_into().unwrap()) as usize;
            let metadata: serde_json::Value =
                serde_json::from_slice(&encoded[4..4 + length]).unwrap();
            assert_eq!(metadata["body_present"], expected);
        }
    }

    #[test]
    fn outer_authority_fields_cannot_enter_logical_headers_or_targets() {
        for name in [
            "authorization",
            "cookie",
            "host",
            "x-session-id",
            ROUTING_KEY_HEADER,
        ] {
            assert!(LogicalHeader::new(name.into(), "value".into()).is_err());
        }
        for target in ["https://example.com", "//example.com", "/ok#fragment"] {
            assert!(
                LogicalRequest::new(None, None, Method::GET, target.into(), vec![], None,).is_err()
            );
        }
    }

    #[test]
    fn repeated_end_to_end_headers_remain_ordered() {
        let encoded = LogicalRequest::new(
            None,
            None,
            Method::GET,
            "/v1/models".into(),
            vec![
                LogicalHeader::new("x-provider-option".into(), "first".into()).unwrap(),
                LogicalHeader::new("x-provider-option".into(), "second".into()).unwrap(),
            ],
            None,
        )
        .unwrap()
        .encode()
        .unwrap();
        let length = u32::from_be_bytes(encoded[..4].try_into().unwrap()) as usize;
        let metadata: serde_json::Value = serde_json::from_slice(&encoded[4..4 + length]).unwrap();
        assert_eq!(metadata["headers"][0]["value"], "first");
        assert_eq!(metadata["headers"][1]["value"], "second");
    }

    #[test]
    fn request_ids_are_random_full_width_values_without_a_registry() {
        let first = RequestId::random().unwrap();
        let second = RequestId::random().unwrap();
        assert_eq!(first.as_bytes().len(), 16);
        assert_ne!(first, second);
    }
}