beamr 0.3.15

A Rust runtime with the BEAM's execution model, targeting Gleam
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

//! Capability metadata and policies for native imports.
//!
//! Native functions are tagged with the authority they need. Import resolution
//! checks those tags once, then either binds the real native entry or a small
//! undef-returning denial stub.

use crate::atom::Atom;
use crate::native::ProcessContext;
use crate::term::Term;

/// Authority required by a native function.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum Capability {
    /// No side effects, no external I/O, and no nondeterminism.
    ///
    /// Arithmetic, comparisons, type checks, and pure collection operations are
    /// in this class.
    Pure,
    /// Reads wall-clock time or otherwise waits on timers.
    Clock,
    /// Consumes randomness or cryptographic entropy.
    Entropy,
    /// Talks to the outside world: shell commands, filesystem, network, or the
    /// process environment.
    ExternalIo,
}

/// Policy consulted by import resolution before binding a native function.
pub trait CapabilityPolicy: Send + Sync {
    /// Returns true when `capability` is granted by this policy.
    fn is_granted(&self, capability: Capability) -> bool;
}

/// Deny-by-default policy: only pure natives are granted.
#[derive(Debug, Clone, Copy, Default)]
pub struct LeastAuthorityPolicy;

impl CapabilityPolicy for LeastAuthorityPolicy {
    fn is_granted(&self, capability: Capability) -> bool {
        capability == Capability::Pure
    }
}

/// Backwards-compatible policy for trusted embedders: all natives are granted.
#[derive(Debug, Clone, Copy, Default)]
pub struct AllCapabilitiesPolicy;

impl CapabilityPolicy for AllCapabilitiesPolicy {
    fn is_granted(&self, _capability: Capability) -> bool {
        true
    }
}

/// Small custom capability policy built from an explicit allow-list.
#[derive(Debug, Clone, Default, Eq, PartialEq)]
pub struct CapabilitySet {
    grants: Vec<Capability>,
}

impl CapabilitySet {
    /// Builds a custom policy from a slice of granted capabilities.
    #[must_use]
    pub fn from_slice(capabilities: &[Capability]) -> Self {
        let mut grants = Vec::new();
        for capability in capabilities {
            if !grants.contains(capability) {
                grants.push(*capability);
            }
        }
        Self { grants }
    }

    /// Returns true when `capability` is in this set.
    #[must_use]
    pub fn grants(&self, capability: Capability) -> bool {
        self.grants.contains(&capability)
    }
}

impl CapabilityPolicy for CapabilitySet {
    fn is_granted(&self, capability: Capability) -> bool {
        self.grants(capability)
    }
}

/// Current denied-import binding behavior.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum DenialMode {
    /// Bind denied native imports to a native stub that raises `undef`.
    Undef,
}

/// Native stub used for denied imports.
///
/// The surrounding resolved import table preserves the import slot and arity;
/// this function has the same signature as every native and returns `undef`
/// when invoked.
pub fn denial_stub(_args: &[Term], _context: &mut ProcessContext) -> Result<Term, Term> {
    Err(Term::atom(Atom::UNDEF))
}

#[cfg(test)]
mod tests {
    use super::{
        AllCapabilitiesPolicy, Capability, CapabilityPolicy, CapabilitySet, LeastAuthorityPolicy,
        denial_stub,
    };
    use crate::native::ProcessContext;
    use crate::term::Term;

    #[test]
    fn least_authority_grants_only_pure() {
        let policy = LeastAuthorityPolicy;
        assert!(policy.is_granted(Capability::Pure));
        assert!(!policy.is_granted(Capability::Clock));
        assert!(!policy.is_granted(Capability::Entropy));
        assert!(!policy.is_granted(Capability::ExternalIo));
    }

    #[test]
    fn all_capabilities_grants_everything() {
        let policy = AllCapabilitiesPolicy;
        assert!(policy.is_granted(Capability::Pure));
        assert!(policy.is_granted(Capability::Clock));
        assert!(policy.is_granted(Capability::Entropy));
        assert!(policy.is_granted(Capability::ExternalIo));
    }

    #[test]
    fn capability_set_grants_exact_members() {
        let policy = CapabilitySet::from_slice(&[Capability::Pure, Capability::Clock]);
        assert!(policy.grants(Capability::Pure));
        assert!(policy.grants(Capability::Clock));
        assert!(!policy.grants(Capability::Entropy));
        assert!(!policy.grants(Capability::ExternalIo));
    }

    #[test]
    fn denial_stub_returns_undef() {
        let mut context = ProcessContext::new();
        assert_eq!(
            denial_stub(&[Term::small_int(1)], &mut context),
            Err(Term::atom(crate::atom::Atom::UNDEF))
        );
    }
}