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}