canic-core 0.35.7

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

use crate::{cdk::types::Principal, dto::error::Error, dto::rpc::Request};
use async_trait::async_trait;

use super::RootCapabilityProof;

/// VerifiedCapability
///
/// Marker output for successful proof verification.
pub(super) struct VerifiedCapability;

/// VerificationInput
///
/// Immutable verification context shared by all proof verifiers.
pub(super) struct VerificationInput<'a> {
    pub(super) capability: &'a Request,
    pub(super) capability_version: u16,
    pub(super) caller: Principal,
    pub(super) target_canister: Principal,
    pub(super) now_secs: u64,
}

/// CapabilityProofVerifier
///
/// Pluggable proof verifier contract for capability envelopes.
#[async_trait]
pub(super) trait CapabilityProofVerifier {
    /// Verify one proof mode against shared capability context.
    async fn verify(&self, input: &VerificationInput<'_>) -> Result<VerifiedCapability, Error>;
}

/// StructuralVerifier
///
/// Verifies topology-only structural proofs.
struct StructuralVerifier;

#[async_trait]
impl CapabilityProofVerifier for StructuralVerifier {
    /// Validate structural preconditions for supported capability families.
    async fn verify(&self, input: &VerificationInput<'_>) -> Result<VerifiedCapability, Error> {
        super::proof::verify_root_structural_proof(input.capability)?;
        Ok(VerifiedCapability)
    }
}

/// RoleAttestationVerifier
///
/// Verifies attestation proof with capability hash binding.
struct RoleAttestationVerifier<'a> {
    blob: &'a crate::dto::capability::CapabilityProofBlob,
}

#[async_trait]
impl CapabilityProofVerifier for RoleAttestationVerifier<'_> {
    /// Verify hash binding first, then run delegated attestation verification.
    async fn verify(&self, input: &VerificationInput<'_>) -> Result<VerifiedCapability, Error> {
        let proof = super::proof::decode_role_attestation_blob(self.blob)?;

        super::proof::verify_capability_hash_binding(
            input.target_canister,
            input.capability_version,
            input.capability,
            proof.capability_hash,
        )?;

        crate::api::auth::AuthApi::verify_role_attestation(&proof.attestation, 0).await?;
        Ok(VerifiedCapability)
    }
}

/// DelegatedGrantVerifier
///
/// Verifies grant hash binding, claims, and signature for delegated grants.
struct DelegatedGrantVerifier<'a> {
    blob: &'a crate::dto::capability::CapabilityProofBlob,
}

#[async_trait]
impl CapabilityProofVerifier for DelegatedGrantVerifier<'_> {
    /// Keep existing delegated-grant verification ordering unchanged.
    async fn verify(&self, input: &VerificationInput<'_>) -> Result<VerifiedCapability, Error> {
        let proof = super::proof::decode_delegated_grant_blob(self.blob)?;

        super::proof::verify_capability_hash_binding(
            input.target_canister,
            input.capability_version,
            input.capability,
            proof.capability_hash,
        )?;
        super::verify_delegated_grant_hash_binding(&proof)?;
        super::verify_root_delegated_grant_proof(
            input.capability,
            &proof,
            input.caller,
            input.target_canister,
            input.now_secs,
        )?;

        Ok(VerifiedCapability)
    }
}

/// verify_root_capability_proof
///
/// Route proof verification through the mode-specific verifier implementation.
pub(super) async fn verify_root_capability_proof(
    capability: &Request,
    capability_version: u16,
    proof: RootCapabilityProof<'_>,
) -> Result<VerifiedCapability, Error> {
    let input = VerificationInput {
        capability,
        capability_version,
        caller: crate::ops::ic::IcOps::msg_caller(),
        target_canister: crate::ops::ic::IcOps::canister_self(),
        now_secs: crate::ops::ic::IcOps::now_secs(),
    };

    match proof {
        RootCapabilityProof::Structural => StructuralVerifier.verify(&input).await,
        RootCapabilityProof::RoleAttestation(blob) => {
            RoleAttestationVerifier { blob }.verify(&input).await
        }
        RootCapabilityProof::DelegatedGrant(blob) => {
            DelegatedGrantVerifier { blob }.verify(&input).await
        }
    }
}