gatekeep 0.3.0

Code-first authorization engine for Rust
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
147
148
149

use crate::{ClauseLabel, Condition, GatekeepResult, ObligationSpec, Policy, ReasonCode};

/// Builds an unconditional permit policy.
#[must_use]
pub const fn permit<O>(outcome: O) -> Policy<O> {
    Policy::Permit(outcome)
}

/// Builds an unconditional denial policy.
#[must_use]
pub const fn deny<O>() -> Policy<O> {
    Policy::Deny
}

/// Builds a conditional denial guard.
///
/// The returned policy permits when `condition` is false and denies with
/// `reason` when `condition` is true. Place these guards in `policy::all` before
/// positive grant clauses to get ordered fail-closed precedence.
#[must_use]
pub fn deny_when<O: crate::Lattice>(
    condition: Condition,
    reason: impl IntoReasonCode,
) -> Policy<O> {
    grant(O::top(), crate::condition::not(condition)).reason(reason)
}

/// Builds a conditional grant policy.
#[must_use]
pub const fn grant<O>(outcome: O, condition: Condition) -> Policy<O> {
    Policy::Grant {
        outcome,
        condition,
        label: None,
        deny_shape: crate::DenyShape::Forbidden,
        obligations: Vec::new(),
        reason: None,
    }
}

/// Builds a meet composition. Empty input fails closed.
#[must_use]
pub fn all<O>(policies: impl IntoIterator<Item = Policy<O>>) -> Policy<O> {
    let policies = policies.into_iter().collect::<Vec<_>>();
    if policies.is_empty() {
        Policy::Deny
    } else {
        Policy::All(policies)
    }
}

/// Builds a join composition. Empty input fails closed.
#[must_use]
pub fn any<O>(policies: impl IntoIterator<Item = Policy<O>>) -> Policy<O> {
    let policies = policies.into_iter().collect::<Vec<_>>();
    if policies.is_empty() {
        Policy::Deny
    } else {
        Policy::Any(policies)
    }
}

/// Builds a fallback policy.
#[must_use]
pub fn or_else<O>(primary: Policy<O>, fallback: Policy<O>) -> Policy<O> {
    Policy::OrElse {
        primary: Box::new(primary),
        fallback: Box::new(fallback),
    }
}

impl<O> Policy<O> {
    /// Adds a label to grant policies.
    #[must_use]
    pub fn labeled(mut self, label: impl IntoLabel) -> Self {
        if let Self::Grant {
            label: grant_label, ..
        } = &mut self
        {
            *grant_label = Some(label.into_label());
        }
        self
    }

    /// Tries to add a validated label to grant policies.
    pub fn try_labeled(self, label: impl Into<String>) -> GatekeepResult<Self> {
        Ok(self.labeled(ClauseLabel::new(label)?))
    }

    /// Marks grant denial as hidden.
    #[must_use]
    pub const fn hidden(mut self) -> Self {
        if let Self::Grant { deny_shape, .. } = &mut self {
            *deny_shape = crate::DenyShape::Hidden;
        }
        self
    }

    /// Adds a reason code to grant denials.
    #[must_use]
    pub fn reason(mut self, reason: impl IntoReasonCode) -> Self {
        if let Self::Grant {
            reason: grant_reason,
            ..
        } = &mut self
        {
            *grant_reason = Some(reason.into_reason_code());
        }
        self
    }

    /// Tries to add a validated reason code to grant denials.
    pub fn try_reason(self, reason: impl Into<String>) -> GatekeepResult<Self> {
        Ok(self.reason(ReasonCode::new(reason)?))
    }

    /// Adds a typed obligation to grant permits.
    #[must_use]
    pub fn with_obligation<S: ObligationSpec>(mut self) -> Self {
        if let Self::Grant { obligations, .. } = &mut self {
            obligations.push(crate::ObligationId::from_trusted(S::ID.as_str()));
        }
        self
    }
}

/// Conversion into a validated clause label.
pub trait IntoLabel {
    /// Converts the value into a label.
    fn into_label(self) -> ClauseLabel;
}

impl IntoLabel for ClauseLabel {
    fn into_label(self) -> ClauseLabel {
        self
    }
}

/// Conversion into a validated reason code.
pub trait IntoReasonCode {
    /// Converts the value into a reason code.
    fn into_reason_code(self) -> ReasonCode;
}

impl IntoReasonCode for ReasonCode {
    fn into_reason_code(self) -> ReasonCode {
        self
    }
}