canic-core 0.111.0

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

//! Module: role_contract::profile
//!
//! Responsibility: derive and parse the immutable compiled protocol-profile identity.
//! Does not own: Candid extraction, artifact persistence, binding selection, or endpoint dispatch.
//! Boundary: hashes exact build-owned release, role, capability, and generated-Candid evidence.

use super::RoleCapabilityKey;
use canic_contracts::ids::CanisterRole;
use sha2::{Digest, Sha256};
use std::collections::BTreeSet;

pub use canic_contracts::protocol::profile::{
    ProtocolProfileDigest, ProtocolProfileDigestParseError,
};

/// Build environment carrying one canonical lowercase protocol-profile digest.

pub const PROTOCOL_PROFILE_DIGEST_ENV: &str = "CANIC_PROTOCOL_PROFILE_DIGEST";

const PROTOCOL_PROFILE_DOMAIN: &[u8] = b"canic.protocol-profile.v1";

/// Pair of generated-Candid and complete protocol-profile hashes from one authority.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct ProtocolProfileHashes {
    pub candid_sha256: [u8; 32],
    pub protocol_profile_digest: ProtocolProfileDigest,
}

/// Derive the accepted `canic.protocol-profile.v1` identity encoding.
#[must_use]
pub fn derive_protocol_profile_hashes(
    release_identity: &str,
    role: &CanisterRole,
    capabilities: &BTreeSet<RoleCapabilityKey>,
    canonical_candid: &[u8],
) -> ProtocolProfileHashes {
    let candid_sha256 = sha256_array(canonical_candid);
    let mut hasher = Sha256::new();
    hasher.update(PROTOCOL_PROFILE_DOMAIN);
    update_length_prefixed(&mut hasher, release_identity.as_bytes());
    update_length_prefixed(&mut hasher, role.as_str().as_bytes());
    hasher.update(
        u32::try_from(capabilities.len())
            .expect("compiled capability count must fit u32")
            .to_be_bytes(),
    );
    for capability in capabilities {
        update_length_prefixed(&mut hasher, capability.manifest_name().as_bytes());
    }
    hasher.update(candid_sha256);

    ProtocolProfileHashes {
        candid_sha256,
        protocol_profile_digest: ProtocolProfileDigest::from_bytes(hasher.finalize().into()),
    }
}

fn update_length_prefixed(hasher: &mut Sha256, bytes: &[u8]) {
    hasher.update(
        u32::try_from(bytes.len())
            .expect("protocol-profile field length must fit u32")
            .to_be_bytes(),
    );
    hasher.update(bytes);
}

fn sha256_array(bytes: &[u8]) -> [u8; 32] {
    Sha256::digest(bytes).into()
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn profile_encoding_is_ordered_stable_and_binds_every_input() {
        let capabilities = BTreeSet::from([
            RoleCapabilityKey::Runtime,
            RoleCapabilityKey::AutomaticTopup,
        ]);
        let first = derive_protocol_profile_hashes(
            "0.103.0",
            &CanisterRole::new("app"),
            &capabilities,
            b"service : {}\n",
        );
        let reordered = BTreeSet::from([
            RoleCapabilityKey::AutomaticTopup,
            RoleCapabilityKey::Runtime,
        ]);
        assert_eq!(
            first,
            derive_protocol_profile_hashes(
                "0.103.0",
                &CanisterRole::new("app"),
                &reordered,
                b"service : {}\n",
            )
        );
        assert_ne!(
            first,
            derive_protocol_profile_hashes(
                "0.103.1",
                &CanisterRole::new("app"),
                &capabilities,
                b"service : {}\n",
            )
        );
        assert_eq!(
            ProtocolProfileDigest::from_hex(&first.protocol_profile_digest.to_string())
                .expect("parse rendered digest"),
            first.protocol_profile_digest
        );
    }

    #[test]
    fn capability_manifest_names_are_lexicographically_ordered() {
        let names = [
            RoleCapabilityKey::AutomaticTopup,
            RoleCapabilityKey::ChildProvisioning,
            RoleCapabilityKey::DelegatedTokenIssuer,
            RoleCapabilityKey::DelegatedTokenVerifier,
            RoleCapabilityKey::FleetAdmissionProjection,
            RoleCapabilityKey::FleetCoordinator,
            RoleCapabilityKey::Icrc21,
            RoleCapabilityKey::Index,
            RoleCapabilityKey::LocalApplicationAuthorization,
            RoleCapabilityKey::ObservabilityDiagnostics,
            RoleCapabilityKey::ObservabilityHistory,
            RoleCapabilityKey::ObservabilityLogs,
            RoleCapabilityKey::ObservabilityMetrics,
            RoleCapabilityKey::RoleAttestationSigner,
            RoleCapabilityKey::RoleAttestationVerifier,
            RoleCapabilityKey::Root,
            RoleCapabilityKey::RootControlPlane,
            RoleCapabilityKey::RootDelegation,
            RoleCapabilityKey::Runtime,
            RoleCapabilityKey::Scaling,
            RoleCapabilityKey::Sharding,
            RoleCapabilityKey::WasmStore,
        ]
        .map(RoleCapabilityKey::manifest_name);
        assert!(names.windows(2).all(|pair| pair[0] < pair[1]));
    }
}