ic_backup/model/ic_request/
mod.rs

1//! Closed host-ingress IC request codec; no transport, authority or effect admission.
2
3use crate::model::evidence_digest::EvidenceDigest;
4mod method;
5pub use method::{IcManagementMethodRecord, IcRequestEffect};
6
7use crate::model::{
8    artifacts::ArtifactChecksumRecord, attempt_journal::OperationBindingRecord, bounded_sequence,
9};
10use ic_management_canister_types::{
11    CanisterIdRecord, LoadCanisterSnapshotArgs, TakeCanisterSnapshotArgs,
12};
13use serde::{Deserialize, Deserializer, Serialize};
14use thiserror::Error;
15
16/// Maximum raw snapshot identifier bytes, distinct from any backend's rendered token.
17pub const MAX_IC_SNAPSHOT_ID_BYTES: usize = 256;
18/// Maximum derived Candid argument bytes; checked before a request is admitted.
19pub const MAX_IC_ARGUMENT_BYTES: usize = 4096;
20/// Bound callers must use for encoded JSON input/output when retaining this record.
21pub const MAX_IC_REQUEST_RECORD_BYTES: u64 = 8192;
22
23/// Passive method/target/snapshot input; network, caller and permissions stay with their owners.
24#[derive(Clone, Debug)]
25pub struct IcManagementRequest {
26    /// One of the closed supported management methods.
27    pub method: IcManagementMethodRecord,
28    /// Exact effective canister principal; normalized on admission.
29    pub target: String,
30    /// Raw nonempty snapshot bytes required only for load; otherwise exactly None.
31    pub snapshot_id: Option<Vec<u8>>,
32}
33
34/// Immutable v1 request declaration with model-derived exact Candid bytes.
35///
36/// All supported methods use replicated update ingress, including observations.
37/// Network/caller selection, signing, freshness, budgets, custody and lifecycle
38/// safety are not granted by this record or its digest.
39#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
40#[serde(try_from = "RequestFields")]
41pub struct IcManagementRequestRecord {
42    version: u16,
43    method: IcManagementMethodRecord,
44    target: String,
45    snapshot_id: Option<Vec<u8>>,
46    #[serde(skip)]
47    target_bytes: Vec<u8>,
48    #[serde(skip)]
49    arguments: Vec<u8>,
50}
51#[derive(Deserialize)]
52#[serde(deny_unknown_fields)]
53struct RequestFields {
54    version: u16,
55    method: IcManagementMethodRecord,
56    target: String,
57    #[serde(deserialize_with = "required_snapshot")]
58    snapshot_id: Option<Vec<u8>>,
59}
60impl TryFrom<RequestFields> for IcManagementRequestRecord {
61    type Error = IcRequestError;
62    fn try_from(fields: RequestFields) -> Result<Self, Self::Error> {
63        if fields.version != 1 {
64            return Err(IcRequestError::UnsupportedVersion(fields.version));
65        }
66        Self::new(IcManagementRequest {
67            method: fields.method,
68            target: fields.target,
69            snapshot_id: fields.snapshot_id,
70        })
71    }
72}
73impl IcManagementRequestRecord {
74    /// Validate the closed request and encode exact host-ingress arguments.
75    ///
76    /// Capture retains code and creates a new snapshot; sender canister version
77    /// stays absent for host ingress. Load names exact raw bytes, with no identity remap.
78    ///
79    /// # Errors
80    /// Rejects malformed principals, missing/unexpected/oversized snapshot IDs,
81    /// Candid encoding failure and excessive derived argument bytes.
82    pub fn new(request: IcManagementRequest) -> Result<Self, IcRequestError> {
83        let (target, principal) = crate::model::principal::canonical_parts(&request.target)
84            .ok_or(IcRequestError::InvalidTarget)?;
85        match (request.method, request.snapshot_id.as_deref()) {
86            (IcManagementMethodRecord::LoadCanisterSnapshot, None) => {
87                return Err(IcRequestError::SnapshotRequired);
88            }
89            (IcManagementMethodRecord::LoadCanisterSnapshot, Some(bytes)) => {
90                if bytes.is_empty() || bytes.len() > MAX_IC_SNAPSHOT_ID_BYTES {
91                    return Err(IcRequestError::InvalidSnapshotId);
92                }
93            }
94            (_, Some(_)) => return Err(IcRequestError::UnexpectedSnapshot),
95            (_, None) => {}
96        }
97        let arguments = match request.method {
98            IcManagementMethodRecord::TakeCanisterSnapshot => {
99                candid::encode_one(TakeCanisterSnapshotArgs {
100                    canister_id: principal,
101                    replace_snapshot: None,
102                    uninstall_code: Some(false),
103                    sender_canister_version: None,
104                })
105            }
106            IcManagementMethodRecord::LoadCanisterSnapshot => {
107                candid::encode_one(LoadCanisterSnapshotArgs {
108                    canister_id: principal,
109                    snapshot_id: request
110                        .snapshot_id
111                        .clone()
112                        .ok_or(IcRequestError::SnapshotRequired)?,
113                    sender_canister_version: None,
114                })
115            }
116            IcManagementMethodRecord::CanisterStatus
117            | IcManagementMethodRecord::ListCanisterSnapshots
118            | IcManagementMethodRecord::StartCanister
119            | IcManagementMethodRecord::StopCanister => candid::encode_one(CanisterIdRecord {
120                canister_id: principal,
121            }),
122        }
123        .map_err(|error| IcRequestError::Encoding(error.to_string()))?;
124        if arguments.len() > MAX_IC_ARGUMENT_BYTES {
125            return Err(IcRequestError::ArgumentsTooLarge);
126        }
127        Ok(Self {
128            version: 1,
129            method: request.method,
130            target,
131            snapshot_id: request.snapshot_id,
132            target_bytes: principal.as_slice().to_vec(),
133            arguments,
134        })
135    }
136    /// Read the exact closed method; its effect class does not grant spending authority.
137    #[must_use]
138    pub const fn method(&self) -> IcManagementMethodRecord {
139        self.method
140    }
141    /// Read the canonical effective routing target, also encoded inside the arguments.
142    #[must_use]
143    pub fn target(&self) -> &str {
144        &self.target
145    }
146    /// Read exact raw load snapshot bytes, without backend token interpretation.
147    #[must_use]
148    pub fn snapshot_id(&self) -> Option<&[u8]> {
149        self.snapshot_id.as_deref()
150    }
151    /// Read derived exact Candid bytes for a future qualified update-ingress transport.
152    #[must_use]
153    pub fn arguments(&self) -> &[u8] {
154        &self.arguments
155    }
156    /// Read the fixed management receiver; the effective routing target is separate.
157    #[must_use]
158    pub const fn receiver(&self) -> &'static str {
159        "aaaaa-aa"
160    }
161    /// Hash fixed receiver, effective target, update mode, exact method and Candid bytes.
162    ///
163    /// Network/caller/intent/release/budgets stay outside this nonrecursive payload
164    /// digest and are bound by the existing operation plan/attempt authority.
165    #[must_use]
166    pub fn digest(&self) -> ArtifactChecksumRecord {
167        management_request_digest(&self.target_bytes, self.method.name(), &self.arguments)
168    }
169    /// Check exact payload target/digest and mutation class against original declared binding.
170    ///
171    /// This verifies bytes only; it does not authenticate the binding or admit dispatch.
172    /// # Errors
173    /// Rejects observation methods and changed target or request digest.
174    pub fn validate_mutation_binding(
175        &self,
176        binding: &OperationBindingRecord,
177    ) -> Result<(), IcRequestError> {
178        self.require_effect(IcRequestEffect::Mutation)?;
179        self.validate_identity(binding, binding.request())
180    }
181    /// Check an observation payload against its exact target and reserved observation digest.
182    ///
183    /// The original binding still names the mutation. The observation digest is
184    /// separately retained by the existing journal's observation reservation.
185    /// # Errors
186    /// Rejects mutation methods, changed target or a different observation digest.
187    pub fn validate_observation_binding(
188        &self,
189        binding: &OperationBindingRecord,
190        request: &ArtifactChecksumRecord,
191    ) -> Result<(), IcRequestError> {
192        self.require_effect(IcRequestEffect::Observation)?;
193        self.validate_identity(binding, request.hash())
194    }
195    fn require_effect(&self, expected: IcRequestEffect) -> Result<(), IcRequestError> {
196        if self.method.effect() != expected {
197            return Err(IcRequestError::EffectMismatch { expected });
198        }
199        Ok(())
200    }
201    fn validate_identity(
202        &self,
203        binding: &OperationBindingRecord,
204        expected: &str,
205    ) -> Result<(), IcRequestError> {
206        if self.target != binding.target() {
207            return Err(IcRequestError::TargetMismatch);
208        }
209        if self.digest().hash() != expected {
210            return Err(IcRequestError::DigestMismatch);
211        }
212        Ok(())
213    }
214}
215
216// Callers own canonical principal bytes, a fixed ASCII method and bounded arguments.
217pub(super) fn management_request_digest(
218    target_bytes: &[u8],
219    method: &str,
220    arguments: &[u8],
221) -> ArtifactChecksumRecord {
222    let mut bytes = EvidenceDigest::new(b"ic-backup/ic-management-request/v1\0");
223    bytes.byte(0); // Management receiver principal has zero raw bytes.
224    bytes.byte(target_bytes.len().to_le_bytes()[0]); // Principal <=29 raw bytes.
225    bytes.append(target_bytes);
226    bytes.byte(1); // Replicated update ingress.
227    bytes.byte(method.len().to_le_bytes()[0]); // Fixed names fit one byte.
228    bytes.append(method.as_bytes());
229    append_argument_length(&mut bytes, arguments.len());
230    bytes.append(arguments);
231    bytes.finish()
232}
233
234#[expect(
235    clippy::cast_possible_truncation,
236    reason = "admitted argument byte length is at most 4096"
237)]
238fn append_argument_length(bytes: &mut EvidenceDigest, length: usize) {
239    bytes.append(&(length as u32).to_be_bytes());
240}
241
242fn required_snapshot<'de, D: Deserializer<'de>>(
243    deserializer: D,
244) -> Result<Option<Vec<u8>>, D::Error> {
245    Ok(Option::<SnapshotBytes>::deserialize(deserializer)?.map(|bytes| bytes.0))
246}
247struct SnapshotBytes(Vec<u8>);
248impl<'de> Deserialize<'de> for SnapshotBytes {
249    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
250        bounded_sequence::deserialize::<_, u8, MAX_IC_SNAPSHOT_ID_BYTES>(
251            deserializer,
252            "at most 256 exact snapshot bytes",
253            IcRequestError::InvalidSnapshotId,
254        )
255        .map(Self)
256    }
257}
258
259/// Typed closed IC request, exact byte binding or codec admission failure.
260#[derive(Debug, Error, Eq, PartialEq)]
261pub enum IcRequestError {
262    /// Other product generations are not maintained.
263    #[error("unsupported IC request version {0}")]
264    UnsupportedVersion(u16),
265    /// Target text is not a bounded canonicalizable principal.
266    #[error("invalid IC request target principal")]
267    InvalidTarget,
268    /// Load requires exact raw snapshot bytes.
269    #[error("load snapshot request requires snapshot_id")]
270    SnapshotRequired,
271    /// A method that has no snapshot argument received one.
272    #[error("snapshot_id is not admitted for this IC request method")]
273    UnexpectedSnapshot,
274    /// Snapshot bytes are empty or exceed their finite bound.
275    #[error("snapshot_id must contain 1..={MAX_IC_SNAPSHOT_ID_BYTES} raw bytes")]
276    InvalidSnapshotId,
277    /// The pinned upstream Candid encoder rejected the typed arguments.
278    #[error("IC request Candid encoding failed: {0}")]
279    Encoding(String),
280    /// Derived argument size exceeds the codec bound.
281    #[error("IC request arguments exceed {MAX_IC_ARGUMENT_BYTES} bytes")]
282    ArgumentsTooLarge,
283    /// A mutation and observation request cannot substitute for each other.
284    #[error("IC request must have effect class {expected:?}")]
285    EffectMismatch {
286        /// Required semantic class, independent of replicated call mode.
287        expected: IcRequestEffect,
288    },
289    /// The payload/routing target differs from the original operation target.
290    #[error("IC request target differs from original binding")]
291    TargetMismatch,
292    /// Exact method/argument digest differs from its original reservation.
293    #[error("IC request digest differs from original binding")]
294    DigestMismatch,
295}
296
297#[cfg(test)]
298mod tests;
ic_backup/model/ic_request/mod.rs

ic_backup/model/ic_request/
mod.rs
