canic-core 0.104.2

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

//! Module: access::auth::predicates
//!
//! Responsibility: enforce caller and topology auth predicates.
//! Does not own: delegated token verification, app mode, or environment predicates.
//! Boundary: `access::auth` exposes these checks to access expressions.

use super::dependency_unavailable;
use crate::{
    access::AccessError,
    cdk::types::Principal,
    ops::{config::ConfigOps, runtime::env::EnvOps, storage::children::CanisterChildrenOps},
};
use ic_cdk::api::{canister_self, is_controller as caller_is_controller};

/// Require that the caller controls the current canister.
/// Allows controller-only maintenance calls.
#[expect(clippy::unused_async)]
pub(super) async fn is_controller(caller: Principal) -> Result<(), AccessError> {
    if caller_is_controller(&caller) {
        Ok(())
    } else {
        Err(AccessError::ControllerRequired)
    }
}

/// Require that the caller appears in the configured whitelist.
/// Missing whitelist configuration fails closed.
#[expect(clippy::unused_async)]
pub(super) async fn is_whitelisted(caller: Principal) -> Result<(), AccessError> {
    let whitelisted = ConfigOps::is_whitelisted(&caller).map_err(dependency_unavailable)?;
    if !whitelisted {
        return Err(AccessError::WhitelistRequired);
    }

    Ok(())
}

/// Require that the caller is a direct child of the current canister.
#[expect(clippy::unused_async)]
pub(super) async fn is_child(caller: Principal) -> Result<(), AccessError> {
    if CanisterChildrenOps::contains_pid(&caller) {
        Ok(())
    } else {
        Err(AccessError::DirectChildRequired)
    }
}

/// Require that the caller is the configured parent canister.
#[expect(clippy::unused_async)]
pub(super) async fn is_parent(caller: Principal) -> Result<(), AccessError> {
    let parent_pid = EnvOps::parent_pid().map_err(dependency_unavailable)?;

    if parent_pid == caller {
        Ok(())
    } else {
        Err(AccessError::ParentRequired)
    }
}

/// Require that the caller equals the configured root canister.
#[expect(clippy::unused_async)]
pub(super) async fn is_root(caller: Principal) -> Result<(), AccessError> {
    let root_pid = EnvOps::root_pid().map_err(dependency_unavailable)?;

    if caller == root_pid {
        Ok(())
    } else {
        Err(AccessError::RootRequired)
    }
}

/// Require that the caller is the currently executing canister.
#[expect(clippy::unused_async)]
pub(super) async fn is_same_canister(caller: Principal) -> Result<(), AccessError> {
    if caller == canister_self() {
        Ok(())
    } else {
        Err(AccessError::SelfRequired)
    }
}