ic_backup/model/fence_acquisition/
mod.rs

1//! Exact application update bytes and original fence acquisition reservation binding.
2
3use crate::model::evidence_digest::EvidenceDigest;
4use crate::model::{
5    artifacts::ArtifactChecksumRecord,
6    attempt_journal::{AttemptAuthorityRecord, AttemptJournalRecord, MAX_OPERATION_ATTEMPTS},
7    fence_obligation::{FenceObligationError, FenceObligationRecord},
8    operation_plan::{OperationPlanError, OperationPlanRecord},
9};
10use std::fmt;
11use thiserror::Error;
12
13/// Maximum opaque application arguments for one acquisition update, checked before copying.
14pub const MAX_FENCE_ACQUISITION_ARGUMENT_BYTES: usize = 1024 * 1024;
15/// Maximum exact visible ASCII method bytes; method spelling is never normalized.
16pub const MAX_FENCE_ACQUISITION_METHOD_BYTES: usize = 128;
17
18/// Immutable bounded host update envelope; application codecs own argument semantics.
19///
20/// Receiver and routing target are the same exact application canister. No management,
21/// proxy, query, signing or default method is supplied. Retain these original bytes
22/// before publishing their plan and obligation; hashes cannot recover missing bytes.
23/// The nonrecursive payload digest excludes plan/requirement/obligation hashes,
24/// which bind the payload subsequently through the original operation authority.
25#[derive(Clone)]
26pub struct FenceAcquisitionPayload {
27    target: String,
28    target_bytes: Vec<u8>,
29    method: String,
30    arguments: Vec<u8>,
31}
32impl FenceAcquisitionPayload {
33    /// Admit exact application receiver, method and bounded opaque argument bytes.
34    /// # Errors
35    /// Rejects malformed/management receivers, empty/nonvisible/oversized methods and excessive bytes.
36    pub fn new(
37        target: &str,
38        method: &str,
39        arguments: &[u8],
40    ) -> Result<Self, FenceAcquisitionError> {
41        if arguments.len() > MAX_FENCE_ACQUISITION_ARGUMENT_BYTES {
42            return Err(FenceAcquisitionError::ArgumentsTooLarge);
43        }
44        if method.is_empty()
45            || method.len() > MAX_FENCE_ACQUISITION_METHOD_BYTES
46            || !method.bytes().all(|byte| byte.is_ascii_graphic())
47        {
48            return Err(FenceAcquisitionError::InvalidMethod);
49        }
50        let (target, principal) = crate::model::principal::canonical_parts(target)
51            .ok_or(FenceAcquisitionError::InvalidTarget)?;
52        if principal.as_slice().is_empty() {
53            return Err(FenceAcquisitionError::ManagementReceiver);
54        }
55        Ok(Self {
56            target,
57            target_bytes: principal.as_slice().to_vec(),
58            method: method.into(),
59            arguments: arguments.into(),
60        })
61    }
62    /// Read the exact canonical application receiver and routing target.
63    #[must_use]
64    pub fn target(&self) -> &str {
65        &self.target
66    }
67    /// Read exact original method spelling.
68    #[must_use]
69    pub fn method(&self) -> &str {
70        &self.method
71    }
72    /// Read exact opaque original bytes; the application must qualify whole-unit acquisition semantics.
73    #[must_use]
74    pub fn arguments(&self) -> &[u8] {
75        &self.arguments
76    }
77    /// Hash NUL-terminated domain, u8 principal length/raw bytes, fixed update byte 1,
78    /// big-endian u32 method length/exact bytes and u64 argument length/exact bytes.
79    #[must_use]
80    pub fn digest(&self) -> ArtifactChecksumRecord {
81        let mut bytes = EvidenceDigest::new(b"ic-backup/application-fence-acquisition/v1\0");
82        // Principal's canonical raw representation is at most 29 bytes.
83        bytes.byte(self.target_bytes.len().to_le_bytes()[0]);
84        bytes.append(&self.target_bytes);
85        bytes.byte(1); // Exactly one host replicated update, never a query.
86        // Visible ASCII methods are admitted at <=128 bytes, so their low byte is exact.
87        bytes.append(&u32::from(self.method.len().to_le_bytes()[0]).to_be_bytes());
88        bytes.append(self.method.as_bytes());
89        bytes.append(&(self.arguments.len() as u64).to_be_bytes());
90        bytes.append(&self.arguments);
91        bytes.finish()
92    }
93}
94impl fmt::Debug for FenceAcquisitionPayload {
95    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
96        formatter
97            .debug_struct("FenceAcquisitionPayload")
98            .field("target", &self.target)
99            .field("method", &self.method)
100            .field("argument_bytes", &self.arguments.len())
101            .finish_non_exhaustive()
102    }
103}
104
105/// Admit exact original acquisition authority and payload before reserving spending.
106///
107/// This checks declarations only: no pending reservation, fresh permission,
108/// never-dispatched custody or executable application contract is established.
109/// # Errors
110/// Rejects changed obligation/plan, journal authority, receiver or exact wire bytes.
111pub fn original_authority(
112    plan: &OperationPlanRecord,
113    obligation: &FenceObligationRecord,
114    journal: &AttemptJournalRecord,
115    payload: &FenceAcquisitionPayload,
116) -> Result<AttemptAuthorityRecord, FenceAcquisitionError> {
117    obligation.validate_plan(plan)?;
118    let authority = plan.attempt_authority(obligation.acquisition_operation())?;
119    if journal.authority() != &authority {
120        return Err(FenceAcquisitionError::AuthorityMismatch);
121    }
122    if payload.target() != authority.binding().target() {
123        return Err(FenceAcquisitionError::TargetMismatch);
124    }
125    if payload.digest().hash() != authority.binding().request() {
126        return Err(FenceAcquisitionError::PayloadMismatch);
127    }
128    Ok(authority)
129}
130
131/// Structural binding to an already reserved acquisition; never a fresh dispatch permit.
132///
133/// Integration admission additionally requires durable originals, exact request semantics,
134/// actual permissions/context/unit, dependency/custody qualification and proof that this
135/// reservation has never been dispatched. Reconstructing a pending request proves none
136/// of those conditions. After interruption without that proof, reconcile instead.
137#[derive(Debug)]
138pub struct FenceAcquisitionRequest<'a> {
139    plan: &'a OperationPlanRecord,
140    obligation: &'a FenceObligationRecord,
141    payload: &'a FenceAcquisitionPayload,
142    authority: AttemptAuthorityRecord,
143    mutation_attempt: u32,
144}
145impl<'a> FenceAcquisitionRequest<'a> {
146    /// Bind original exact application bytes only after the canonical journal reserves mutation.
147    /// # Errors
148    /// Rejects changed originals, target/bytes, missing mutation or an acquisition already in observation recovery.
149    pub fn new(
150        plan: &'a OperationPlanRecord,
151        obligation: &'a FenceObligationRecord,
152        journal: &AttemptJournalRecord,
153        payload: &'a FenceAcquisitionPayload,
154    ) -> Result<Self, FenceAcquisitionError> {
155        let authority = original_authority(plan, obligation, journal, payload)?;
156        let mutation_attempt = journal
157            .pending_mutation()
158            .ok_or(FenceAcquisitionError::NoPendingMutation)?;
159        let request = Self {
160            plan,
161            obligation,
162            payload,
163            authority,
164            mutation_attempt,
165        };
166        request.validate_journal(journal)?;
167        Ok(request)
168    }
169    /// Read original full context/inventory/selected unit; target routing does not narrow coverage.
170    #[must_use]
171    pub const fn plan(&self) -> &OperationPlanRecord {
172        self.plan
173    }
174    /// Read original purpose/fence/revisions under the retained requirement.
175    #[must_use]
176    pub const fn obligation(&self) -> &FenceObligationRecord {
177        self.obligation
178    }
179    /// Read exact immutable application update bytes.
180    #[must_use]
181    pub const fn payload(&self) -> &FenceAcquisitionPayload {
182        self.payload
183    }
184    /// Read full original operation identity and spending limits.
185    #[must_use]
186    pub const fn authority(&self) -> &AttemptAuthorityRecord {
187        &self.authority
188    }
189    /// Read the already consumed original mutation number.
190    #[must_use]
191    pub const fn mutation_attempt(&self) -> u32 {
192        self.mutation_attempt
193    }
194    /// Recheck current reservation before associating an acknowledgement; performs no IO or effects.
195    /// # Errors
196    /// Rejects changed authority, settled/replaced mutation or pending observation recovery.
197    pub fn validate_journal(
198        &self,
199        journal: &AttemptJournalRecord,
200    ) -> Result<(), FenceAcquisitionError> {
201        journal.validate_pending_mutation(
202            &self.authority,
203            self.mutation_attempt,
204            FenceAcquisitionError::AuthorityMismatch,
205            FenceAcquisitionError::MutationMismatch,
206            FenceAcquisitionError::ObservationPending,
207        )
208    }
209}
210
211/// Passive exact update reply association, without acquisition outcome or fence custody proof.
212#[derive(Clone, Debug)]
213pub struct FenceAcquisitionAcknowledgement {
214    /// Full original authority digest, including original plan/context/operation/limits.
215    pub authority: ArtifactChecksumRecord,
216    /// Original already reserved mutation attempt, not an independently numbered call.
217    pub mutation_attempt: u32,
218    /// Qualified provider's retained exact reply association evidence; not an authenticated signature.
219    pub evidence: ArtifactChecksumRecord,
220}
221impl FenceAcquisitionAcknowledgement {
222    /// Admit a passive acknowledgement with a finite original mutation identity.
223    /// # Errors
224    /// Rejects zero or attempt numbers above the existing combined attempt ceiling.
225    pub fn new(
226        authority: ArtifactChecksumRecord,
227        mutation_attempt: u32,
228        evidence: ArtifactChecksumRecord,
229    ) -> Result<Self, FenceAcquisitionError> {
230        if mutation_attempt == 0 || mutation_attempt > MAX_OPERATION_ATTEMPTS {
231            return Err(FenceAcquisitionError::InvalidAttempt);
232        }
233        Ok(Self {
234            authority,
235            mutation_attempt,
236            evidence,
237        })
238    }
239}
240
241/// Typed payload/original reservation rejection; no error refunds or releases anything.
242#[derive(Debug, Error)]
243pub enum FenceAcquisitionError {
244    /// Receiver is not a bounded canonical principal.
245    #[error("invalid fence acquisition receiver")]
246    InvalidTarget,
247    /// This port cannot call the management canister.
248    #[error("fence acquisition requires an application receiver")]
249    ManagementReceiver,
250    /// Method exceeds the exact visible ASCII envelope bound.
251    #[error("invalid fence acquisition method")]
252    InvalidMethod,
253    /// Raw arguments exceed the finite input bound.
254    #[error("fence acquisition arguments exceed the input bound")]
255    ArgumentsTooLarge,
256    /// Journal is not the exact original acquisition authority.
257    #[error("fence acquisition original journal authority mismatch")]
258    AuthorityMismatch,
259    /// Receiver differs from the original operation target.
260    #[error("fence acquisition original target mismatch")]
261    TargetMismatch,
262    /// Method/arguments differ from the original declared payload digest.
263    #[error("fence acquisition original payload mismatch")]
264    PayloadMismatch,
265    /// Original mutation was not already reserved.
266    #[error("fence acquisition requires a pending mutation reservation")]
267    NoPendingMutation,
268    /// Current journal no longer retains this exact unresolved mutation.
269    #[error("fence acquisition pending mutation mismatch")]
270    MutationMismatch,
271    /// An observation is pending; original mutation must not be dispatched again.
272    #[error("fence acquisition observation recovery is pending")]
273    ObservationPending,
274    /// Acknowledgement attempt is outside the finite original journal range.
275    #[error("invalid fence acquisition acknowledgement attempt")]
276    InvalidAttempt,
277    /// Original obligation admission failed.
278    #[error(transparent)]
279    Obligation(#[from] FenceObligationError),
280    /// Original plan authority cannot be derived.
281    #[error(transparent)]
282    Plan(#[from] OperationPlanError),
283}
284
285#[cfg(test)]
286mod tests;
ic_backup/model/fence_acquisition/mod.rs

ic_backup/model/fence_acquisition/
mod.rs
