Skip to main content

engine/security/
authorization.rs

1//! Generic authorization.
2//!
3//! The Engine provides the *mechanism*: operations, actor references, and an
4//! injectable policy. It does not bake in Unix mode bits, UID/GID numbers, or
5//! any OS-specific security model. The OS installs a policy that
6//! gives its permission representation meaning.
7
8use std::collections::BTreeMap;
9
10use crate::core::metadata::Metadata;
11use crate::core::object_id::ObjectId;
12pub use crate::security::actor::ActorId;
13
14/// An operation an actor may attempt on an object.
15///
16/// The Engine checks exactly one operation per API call, against the primary
17/// target object of that call. Creating an object checks [`Operation::Create`]
18/// against the destination directory; all other operations check the object
19/// itself.
20#[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
21pub enum Operation {
22    /// Creating a new object in a directory.
23    Create,
24    /// Reading an object's state (content, metadata, listing).
25    Read,
26    /// Writing or replacing an object's content.
27    Write,
28    /// Moving, renaming, attaching, or detaching an object.
29    Move,
30    /// Copying an object.
31    Copy,
32    /// Deleting an object.
33    Delete,
34    /// Changing metadata (authorization, extensions, timestamps).
35    ChangeMetadata,
36    /// Changing the object's owning principal.
37    ///
38    /// Kept distinct from [`Operation::ChangeMetadata`] so that policies can
39    /// enforce stricter rules on ownership changes (for example, allowing only
40    /// the root user to change an owner, as real operating systems do).
41    ChangeOwner,
42    /// Executing a file. The OS assigns meaning; the Engine checks it.
43    Execute,
44}
45
46/// The result of an authorization decision.
47#[derive(Clone, Debug, PartialEq, Eq)]
48pub enum AuthorizationResult {
49    /// The operation is allowed.
50    Allowed,
51    /// The operation is denied, with an optional explanation.
52    Denied {
53        /// Why the operation was denied, if known.
54        reason: Option<String>,
55    },
56}
57
58impl AuthorizationResult {
59    /// Returns `true` when the operation is allowed.
60    pub fn is_allowed(&self) -> bool {
61        matches!(self, Self::Allowed)
62    }
63}
64
65/// The context of an object's parent, for policies that decide operations
66/// against the parent directory (for example Unix move/delete rules).
67#[derive(Clone, Debug)]
68pub struct ParentReference<'a> {
69    /// The parent object.
70    pub object: ObjectId,
71    /// The parent's metadata.
72    pub metadata: &'a Metadata,
73}
74
75/// A request to authorize an operation.
76#[derive(Clone, Debug)]
77pub struct AuthorizationRequest<'a> {
78    /// The actor attempting the operation, if any.
79    pub actor: Option<ActorId>,
80    /// The operation being attempted.
81    pub operation: Operation,
82    /// The primary target object.
83    pub object: ObjectId,
84    /// The target object's metadata, for the policy to inspect.
85    pub metadata: &'a Metadata,
86    /// The target object's parent, when it has one.
87    ///
88    /// Policies may inspect it to implement parent-directory semantics (for
89    /// example write access on the containing directory for moves and
90    /// deletions).
91    pub parent: Option<ParentReference<'a>>,
92}
93
94/// A policy that decides whether operations are allowed.
95///
96/// Implementations must be shareable across threads ([`Send`] + [`Sync`]).
97/// The OS layer provides the real policy; the Engine only consults it.
98pub trait AuthorizationPolicy: Send + Sync {
99    /// Decides whether the request is allowed.
100    fn authorize(&self, request: &AuthorizationRequest<'_>) -> AuthorizationResult;
101}
102
103/// A policy that allows everything.
104///
105/// This is the default until the OS installs a real policy.
106#[derive(Clone, Copy, Debug, Default)]
107pub struct PermissivePolicy;
108
109impl AuthorizationPolicy for PermissivePolicy {
110    fn authorize(&self, _request: &AuthorizationRequest<'_>) -> AuthorizationResult {
111        AuthorizationResult::Allowed
112    }
113}
114
115/// Opaque authorization data attached to an object.
116///
117/// The Engine stores and returns this data without understanding it. The OS
118/// encodes its permission representation (mode bits, ACLs, SIDs, ...) into it.
119#[derive(Clone, Debug, Default, PartialEq, Eq)]
120pub struct AuthorizationData {
121    fields: BTreeMap<String, String>,
122}
123
124impl AuthorizationData {
125    /// Creates empty authorization data.
126    pub fn new() -> Self {
127        Self::default()
128    }
129
130    /// Inserts a key/value pair, returning the previous value if any.
131    pub fn insert(&mut self, key: impl Into<String>, value: impl Into<String>) -> Option<String> {
132        self.fields.insert(key.into(), value.into())
133    }
134
135    /// Removes a key, returning its value if present.
136    pub fn remove(&mut self, key: &str) -> Option<String> {
137        self.fields.remove(key)
138    }
139
140    /// Returns the value for a key, if present.
141    pub fn get(&self, key: &str) -> Option<&str> {
142        self.fields.get(key).map(String::as_str)
143    }
144
145    /// Returns all fields.
146    pub fn fields(&self) -> &BTreeMap<String, String> {
147        &self.fields
148    }
149
150    /// Returns `true` when there are no fields.
151    pub fn is_empty(&self) -> bool {
152        self.fields.is_empty()
153    }
154}