ic-platform 0.33.7

Controlled Candid and IC runtime dependency boundary
Documentation
//! Native IC HTTP protocol codecs, using upstream transport identities.
//!
//! Every input/output takes a caller-selected byte limit. Decoding does not
//! authenticate signatures, delegations, freshness or request bindings and
//! grants no submission, polling or replay authority. Original bytes remain
//! caller-owned. No generic CBOR value or serializer is exposed.

use crate::certification::cbor::{CborError, decode, encode_framed};
use crate::principal::Principal;

pub use ic_transport_types::{
    Envelope, EnvelopeContent, ReadStateResponse, SubnetMetrics, TransportCallResponse,
};

#[cfg(feature = "ic-protocol-fixtures")]
pub mod fixtures;

/// Decode an IC authentication envelope without verifying or re-encoding it.
pub fn decode_envelope(bytes: &[u8], max_bytes: usize) -> Result<Envelope<'static>, CborError> {
    decode(bytes, max_bytes)
}

/// Inspect a call's known fields with strict unknown-field admission. Outer
/// authentication metadata is not checked. Consumers retain sender-info policy,
/// expected content/request-ID binding and custody of the original signed bytes.
pub fn decode_call_content_strict(
    bytes: &[u8],
    max_bytes: usize,
) -> Result<EnvelopeContent, CborError> {
    use serde::Deserialize;
    use serde::de::Error as _;
    #[derive(Deserialize)]
    struct EnvelopeWire {
        content: CallWire,
    }
    #[derive(Deserialize)]
    #[serde(deny_unknown_fields)]
    struct CallWire {
        request_type: String,
        nonce: Option<serde_bytes::ByteBuf>,
        ingress_expiry: u64,
        sender: serde_bytes::ByteBuf,
        canister_id: serde_bytes::ByteBuf,
        method_name: String,
        arg: serde_bytes::ByteBuf,
        sender_info: Option<ic_transport_types::SenderInfo>,
    }
    let value: EnvelopeWire = decode(bytes, max_bytes)?;
    let call = value.content;
    let invalid = || CborError::Decode(serde_cbor::Error::custom("invalid IC call content"));
    if call.request_type != "call" {
        return Err(invalid());
    }
    Ok(EnvelopeContent::Call {
        nonce: call.nonce.map(serde_bytes::ByteBuf::into_vec),
        ingress_expiry: call.ingress_expiry,
        sender: call.sender.as_ref().try_into().map_err(|_| invalid())?,
        canister_id: call
            .canister_id
            .as_ref()
            .try_into()
            .map_err(|_| invalid())?,
        method_name: call.method_name,
        arg: call.arg.into_vec(),
        sender_info: call.sender_info,
    })
}

/// Inspect only the known content fields of a signed read-state envelope.
///
/// Requires `read_state`, unsigned expiry, a valid sender and arrays of byte-string
/// path labels. Unknown, duplicate, missing or mistyped content fields and trailing
/// input refuse. Outer authentication metadata is not checked. Returns the same
/// transport identity used by Agent, so its request-ID computation is unchanged.
///
/// `max_bytes` bounds the complete input before parsing, not total decoder work or
/// allocations. CBOR nesting admission follows the existing decoder. Consumers
/// retain the original signed bytes, signature validation, sender/path/request-ID
/// binding, deadlines, trust roots, freshness and dispatch policy.
pub fn decode_read_state_content_strict(
    bytes: &[u8],
    max_bytes: usize,
) -> Result<EnvelopeContent, CborError> {
    use crate::certification::cbor::strict::ByteString;
    use serde::Deserialize;
    use serde::de::{Error as _, IgnoredAny, MapAccess, Visitor};

    struct EnvelopeWire {
        content: ReadStateWire,
    }
    impl<'de> Deserialize<'de> for EnvelopeWire {
        fn deserialize<D: serde::Deserializer<'de>>(decoder: D) -> Result<Self, D::Error> {
            struct EnvelopeVisitor;
            impl<'de> Visitor<'de> for EnvelopeVisitor {
                type Value = EnvelopeWire;
                fn expecting(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
                    f.write_str("IC envelope map")
                }
                fn visit_map<A: MapAccess<'de>>(
                    self,
                    mut map: A,
                ) -> Result<EnvelopeWire, A::Error> {
                    let mut content = None;
                    while let Some(key) = map.next_key::<String>()? {
                        if key == "content" {
                            if content.is_some() {
                                return Err(A::Error::duplicate_field("content"));
                            }
                            content = Some(map.next_value()?);
                        } else {
                            map.next_value::<IgnoredAny>()?;
                        }
                    }
                    Ok(EnvelopeWire {
                        content: content.ok_or_else(|| A::Error::missing_field("content"))?,
                    })
                }
            }
            decoder.deserialize_map(EnvelopeVisitor)
        }
    }
    #[derive(Deserialize)]
    #[serde(tag = "request_type", deny_unknown_fields)]
    enum ReadStateWire {
        #[serde(rename = "read_state")]
        ReadState {
            ingress_expiry: u64,
            sender: ByteString,
            paths: Vec<Vec<ByteString>>,
        },
    }

    let value: EnvelopeWire = decode(bytes, max_bytes)?;
    let ReadStateWire::ReadState {
        ingress_expiry,
        sender,
        paths,
    } = value.content;
    Ok(EnvelopeContent::ReadState {
        ingress_expiry,
        sender: sender.0.as_slice().try_into().map_err(|_| {
            CborError::Decode(serde_cbor::Error::custom("invalid IC read-state sender"))
        })?,
        paths: paths
            .into_iter()
            .map(|path| path.into_iter().map(|label| label.0.into()).collect())
            .collect(),
    })
}

/// Encode an IC envelope with the same self-described framing as the SDK.
pub fn encode_envelope(envelope: &Envelope<'_>, max_bytes: usize) -> Result<Vec<u8>, CborError> {
    encode_framed(envelope, max_bytes, true)
}

/// Decode an HTTP call response; acceptance is not permission to poll or retry.
pub fn decode_call_response(
    bytes: &[u8],
    max_bytes: usize,
) -> Result<TransportCallResponse, CborError> {
    decode(bytes, max_bytes)
}

/// Decode a read-state response, retaining its original certificate bytes.
pub fn decode_read_state_response(
    bytes: &[u8],
    max_bytes: usize,
) -> Result<ReadStateResponse, CborError> {
    decode(bytes, max_bytes)
}

/// Decode the optional IC subnet-metrics leaf, preserving the upstream u128
/// cycle count. A CBOR null leaf is `None`; malformed or trailing bytes refuse.
/// Missing certificate paths remain the caller's responsibility.
pub fn decode_subnet_metrics(
    bytes: &[u8],
    max_bytes: usize,
) -> Result<Option<SubnetMetrics>, CborError> {
    decode(bytes, max_bytes)
}

/// Decode an IC certified controllers leaf; authentication and controller
/// counts, ordering, uniqueness and authority remain consumer-owned.
pub fn decode_controllers(bytes: &[u8], max_bytes: usize) -> Result<Vec<Principal>, CborError> {
    decode(bytes, max_bytes)
}

#[cfg(test)]
mod tests;