canic-core 0.100.83

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

//! Module: workflow::rpc::capability::proof
//!
//! Responsibility: verify structural capability proof constraints.
//! Does not own: envelope validation, metrics, request dispatch, or replay metadata.
//! Boundary: checks caller topology against protected root capability authority.

use crate::{
    cdk::types::Principal,
    dto::{error::Error, rpc::CreateCanisterParent},
    ops::{ic::IcOps, storage::children::CanisterChildrenOps},
    workflow::rpc::{RootCapabilityAuthority, request::handler::capability::RootCapability},
};

/// verify_root_structural_proof
///
/// Verify structural proof constraints for capability families that allow it.
pub(super) fn verify_root_structural_proof(
    capability: &RootCapability,
    authority: &RootCapabilityAuthority,
) -> Result<(), Error> {
    let caller = IcOps::msg_caller();
    if authority.caller_canister_id() != caller {
        return Err(Error::forbidden(
            "structural proof caller differs from protected root capability authority",
        ));
    }

    match capability {
        RootCapability::AcknowledgePlacementReceipt(_) | RootCapability::RequestCycles(_) => {
            require_no_scoped_authority(authority)
        }
        RootCapability::AllocatePlacementChild(request)
        | RootCapability::ProvisionCanister(request) => {
            verify_root_structural_create(request, authority)
        }
        RootCapability::UpgradeCanister(request) => {
            verify_root_structural_child_target(caller, request.canister_pid, "upgrade", authority)
        }
        RootCapability::RecycleCanister(request) => {
            verify_replayable_recycle_target(caller, request.canister_pid, authority)
        }
    }
}

fn verify_replayable_recycle_target(
    caller: Principal,
    target_pid: Principal,
    authority: &RootCapabilityAuthority,
) -> Result<(), Error> {
    require_no_provision_parent_authority(authority)?;
    if !authority.has_target() {
        return Ok(());
    }
    verify_root_structural_child_target(caller, target_pid, "recycle", authority)
}

fn verify_root_structural_create(
    request: &crate::dto::rpc::CreateCanisterRequest,
    authority: &RootCapabilityAuthority,
) -> Result<(), Error> {
    if !matches!(&request.parent, CreateCanisterParent::ThisCanister) {
        return Err(Error::forbidden(
            "structural provision proof requires parent=ThisCanister",
        ));
    }
    require_no_target_authority(authority)?;
    if authority.provision_parent_canister_id() != Some(authority.caller_canister_id()) {
        return Err(Error::forbidden(
            "structural provision parent differs from the protected caller authority",
        ));
    }
    Ok(())
}

fn verify_root_structural_child_target(
    caller: Principal,
    target_pid: Principal,
    operation: &str,
    authority: &RootCapabilityAuthority,
) -> Result<(), Error> {
    require_no_provision_parent_authority(authority)?;
    if authority.target_canister_id() != Some(target_pid) {
        return Err(Error::forbidden(format!(
            "structural proof requires an exact active {operation} target"
        )));
    }
    if authority.target_parent_canister_id() != Some(caller) {
        return Err(Error::forbidden(format!(
            "structural proof requires {operation} target to be a direct child of caller"
        )));
    }
    Ok(())
}

fn require_no_scoped_authority(authority: &RootCapabilityAuthority) -> Result<(), Error> {
    require_no_target_authority(authority)?;
    require_no_provision_parent_authority(authority)
}

fn require_no_target_authority(authority: &RootCapabilityAuthority) -> Result<(), Error> {
    if authority.has_target() {
        return Err(Error::forbidden(
            "root capability carries unexpected target authority",
        ));
    }
    Ok(())
}

fn require_no_provision_parent_authority(authority: &RootCapabilityAuthority) -> Result<(), Error> {
    if authority.has_provision_parent() {
        return Err(Error::forbidden(
            "root capability carries unexpected provision-parent authority",
        ));
    }
    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(())
}