canic-core 0.65.4

Canic — a canister orchestration and management toolkit for the Internet Computer
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151

use crate::{
    cdk::types::Principal,
    dto::{
        capability::{CapabilityProof, CapabilityProofBlob, DelegatedGrantProof},
        error::Error,
        rpc::{CreateCanisterParent, Request},
    },
    ops::{
        ic::IcOps, storage::children::CanisterChildrenOps,
        storage::registry::subnet::SubnetRegistryOps,
    },
};
use candid::{decode_one, encode_one};
use std::convert::TryFrom;

/// verify_root_structural_proof
///
/// Verify structural proof constraints for capability families that allow it.
pub(super) fn verify_root_structural_proof(capability: &Request) -> Result<(), Error> {
    let caller = IcOps::msg_caller();

    if SubnetRegistryOps::get(caller).is_none() {
        return Err(Error::forbidden(
            "structural proof requires caller to be registered in subnet registry",
        ));
    }

    match capability {
        Request::Cycles(_) => Ok(()),
        Request::CreateCanister(request) => verify_root_structural_create(request),
        Request::UpgradeCanister(request) => {
            verify_root_structural_child_target(caller, request.canister_pid, "upgrade")
        }
        Request::RecycleCanister(request) => {
            verify_root_structural_child_target(caller, request.canister_pid, "recycle")
        }
        Request::IssueRoleAttestation(_) | Request::IssueInternalInvocationProof(_) => {
            Err(Error::forbidden(
                "structural proof is only supported for root cycles, child provision, child upgrade, and child recycle capabilities",
            ))
        }
    }
}

fn verify_root_structural_create(
    request: &crate::dto::rpc::CreateCanisterRequest,
) -> Result<(), Error> {
    if matches!(&request.parent, CreateCanisterParent::ThisCanister) {
        return Ok(());
    }

    Err(Error::forbidden(
        "structural provision proof requires parent=ThisCanister",
    ))
}

fn verify_root_structural_child_target(
    caller: Principal,
    target_pid: Principal,
    operation: &str,
) -> Result<(), Error> {
    let target = SubnetRegistryOps::get(target_pid).ok_or_else(|| {
        Error::forbidden(format!(
            "structural proof requires registered {operation} target"
        ))
    })?;
    if target.parent_pid != Some(caller) {
        return Err(Error::forbidden(format!(
            "structural proof requires {operation} target to be a direct child of caller"
        )));
    }
    Ok(())
}

/// verify_nonroot_structural_cycles_proof
///
/// Verify that a structural cycles request came from a cached direct child.
pub(super) fn verify_nonroot_structural_cycles_proof() -> Result<(), Error> {
    let caller = IcOps::msg_caller();

    if !CanisterChildrenOps::contains_pid(&caller) {
        return Err(Error::forbidden(
            "structural proof requires caller to be a direct child of receiver",
        ));
    }

    Ok(())
}

/// verify_capability_hash_binding
///
/// Ensure the proof hash matches canonical capability payload bytes.
pub(super) fn verify_capability_hash_binding(
    target_canister: Principal,
    capability_version: u16,
    capability: &Request,
    capability_hash: [u8; 32],
) -> Result<(), Error> {
    let expected = super::root_capability_hash(target_canister, capability_version, capability)?;
    if capability_hash != expected {
        return Err(Error::invalid(
            "capability_hash does not match capability payload",
        ));
    }

    Ok(())
}

// --- Wire Encoding ------------------------------------------------------

// Encode the full delegated-grant proof into the compact shared wire blob.
pub(super) fn encode_delegated_grant_blob(
    proof: &DelegatedGrantProof,
) -> Result<CapabilityProofBlob, Error> {
    Ok(CapabilityProofBlob {
        proof_version: proof.proof_version,
        capability_hash: proof.capability_hash,
        payload: encode_one(proof).map_err(|err| {
            Error::internal(format!("failed to encode delegated grant proof: {err}"))
        })?,
    })
}

// Decode a delegated-grant wire blob back into its concrete proof payload.
pub(super) fn decode_delegated_grant_blob(
    blob: &CapabilityProofBlob,
) -> Result<DelegatedGrantProof, Error> {
    let proof: DelegatedGrantProof = decode_one(&blob.payload)
        .map_err(|err| Error::invalid(format!("failed to decode delegated grant proof: {err}")))?;

    if proof.proof_version != blob.proof_version {
        return Err(Error::invalid(
            "delegated grant proof_version does not match wire header",
        ));
    }
    if proof.capability_hash != blob.capability_hash {
        return Err(Error::invalid(
            "delegated grant capability_hash does not match wire header",
        ));
    }

    Ok(proof)
}

impl TryFrom<DelegatedGrantProof> for CapabilityProof {
    type Error = Error;

    fn try_from(value: DelegatedGrantProof) -> Result<Self, Self::Error> {
        Ok(Self::DelegatedGrant(encode_delegated_grant_blob(&value)?))
    }
}