Skip to main content

substrate_kit/
principal.rs

1//! `principal` — service-principal embodiment.
2//!
3//! Binds a running container/process on the box (plain OS-level facts —
4//! container id, uid, optional cgroup/mount-namespace handles) to an
5//! already-defined [`identity_kit::ServicePrincipal`].
6//!
7//! **Hard constraint:** identity-kit *owns* the grant data model; substrate-kit
8//! only *embodies* it. This module must never construct a `Capabilities`
9//! bundle or a principal definition of its own — `embody` only takes an
10//! already-built `ServicePrincipal` and pairs it with the OS facts of a
11//! running container. See `identity_kit::authz::ServicePrincipal` for the
12//! type this resolves to, verbatim.
13//!
14//! This slice is the descriptor + binding only — no live dockerd call.
15//! Resolving a real `ContainerRef` from a running container is
16//! `lifecycle`'s job, in a later slice.
17
18use identity_kit::{Scope, ServicePrincipal};
19
20/// The OS-level facts of a running container/process on the box.
21///
22/// Plain descriptor. `cgroup`/`mount_ns` are opaque path handles filled in
23/// once `cgroup`/`mount` modules do real resolution; unset here.
24#[derive(Debug, Clone, PartialEq, Eq)]
25pub struct ContainerRef {
26    /// dockerd container id (or a PID-derived id for a bare process).
27    pub container_id: String,
28    /// The uid the container/process runs as on the host.
29    pub uid: u32,
30    /// Resolved cgroup path, if known.
31    pub cgroup: Option<String>,
32    /// Resolved mount-namespace handle (e.g. `/proc/<pid>/ns/mnt`), if
33    /// known.
34    pub mount_ns: Option<String>,
35}
36
37impl ContainerRef {
38    /// A bare container reference: just the id and the uid it runs as.
39    pub fn new(container_id: impl Into<String>, uid: u32) -> Self {
40        Self {
41            container_id: container_id.into(),
42            uid,
43            cgroup: None,
44            mount_ns: None,
45        }
46    }
47
48    /// Attach a resolved cgroup path.
49    pub fn with_cgroup(mut self, cgroup: impl Into<String>) -> Self {
50        self.cgroup = Some(cgroup.into());
51        self
52    }
53
54    /// Attach a resolved mount-namespace handle.
55    pub fn with_mount_ns(mut self, mount_ns: impl Into<String>) -> Self {
56        self.mount_ns = Some(mount_ns.into());
57        self
58    }
59}
60
61/// A running container/process bound to the [`ServicePrincipal`]
62/// identity-kit defined for it.
63///
64/// `Embodiment` never constructs or mutates the principal it wraps — it
65/// only pairs an already-built `identity_kit::ServicePrincipal` with the
66/// [`ContainerRef`] facts of the container/process embodying it.
67#[derive(Debug, Clone)]
68pub struct Embodiment {
69    container: ContainerRef,
70    principal: ServicePrincipal,
71}
72
73/// Bind a running container/process to an already-defined
74/// `ServicePrincipal`.
75///
76/// Maps the OS-level embodiment facts (uid/container) onto the principal
77/// identity-kit owns. Does not construct capabilities or a principal
78/// definition — `principal` must already exist; this only binds it.
79pub fn embody(container: &ContainerRef, principal: ServicePrincipal) -> Embodiment {
80    Embodiment {
81        container: container.clone(),
82        principal,
83    }
84}
85
86impl Embodiment {
87    /// The `ServicePrincipal` this container/process embodies, verbatim as
88    /// identity-kit defined it.
89    pub fn principal(&self) -> &ServicePrincipal {
90        &self.principal
91    }
92
93    /// The OS-level facts of the running container/process.
94    pub fn container(&self) -> &ContainerRef {
95        &self.container
96    }
97
98    /// Whether the embodied principal holds the given scope. Delegates
99    /// through to `identity_kit::ServicePrincipal::has`, which in turn
100    /// delegates to `Capabilities::includes` — substrate-kit performs no
101    /// capability logic of its own.
102    pub fn has(&self, scope: &Scope) -> bool {
103        self.principal.has(scope)
104    }
105}
106
107#[cfg(test)]
108mod tests {
109    use super::*;
110    use identity_kit::Capabilities;
111
112    fn scope(s: &str) -> Scope {
113        Scope(s.to_string())
114    }
115
116    #[test]
117    fn embody_binds_container_to_the_given_principal() {
118        let caps = Capabilities::new(vec![scope("run:container")]);
119        let principal = ServicePrincipal::new(None, caps);
120        let principal_id = principal.id();
121
122        let container = ContainerRef::new("c-1234", 1000)
123            .with_cgroup("/sys/fs/cgroup/substrate/c-1234")
124            .with_mount_ns("/proc/4242/ns/mnt");
125
126        let embodiment = embody(&container, principal);
127
128        assert_eq!(embodiment.principal().id(), principal_id);
129        assert_eq!(embodiment.container(), &container);
130    }
131
132    #[test]
133    fn embodiment_has_delegates_through_to_service_principal() {
134        let caps = Capabilities::new(vec![scope("pair:device")]);
135        let principal = ServicePrincipal::new(None, caps);
136        let container = ContainerRef::new("c-5678", 1001);
137
138        let embodiment = embody(&container, principal);
139
140        assert!(embodiment.has(&scope("pair:device")));
141        assert!(!embodiment.has(&scope("admin:everything")));
142    }
143
144    #[test]
145    fn embody_never_constructs_capabilities_of_its_own() {
146        // `embody`'s signature takes an already-built ServicePrincipal —
147        // it has no path to construct Capabilities itself. This round-
148        // trips a principal built entirely through identity-kit's own
149        // constructors and confirms the capability set survives embodiment
150        // unmodified.
151        let caps = Capabilities::new(vec![scope("read:account"), scope("write:family")]);
152        let principal = ServicePrincipal::new(None, caps.clone());
153        let container = ContainerRef::new("c-9", 1002);
154
155        let embodiment = embody(&container, principal);
156
157        assert_eq!(embodiment.principal().capabilities().scopes, caps.scopes);
158    }
159
160    /// Hard-constraint guard test (not merely behavioural): substrate-kit
161    /// never defines its own principal shape — `Embodiment::principal`
162    /// must resolve to `identity_kit::ServicePrincipal` verbatim. If a
163    /// future edit swapped in a substrate-kit-local principal type, this
164    /// helper's parameter type stops compiling and the PR has to face the
165    /// hard constraint explicitly rather than slip past review.
166    #[test]
167    fn embodiment_principal_is_identity_kit_service_principal_verbatim() {
168        fn assert_is_identity_kit_principal(_: &identity_kit::ServicePrincipal) {}
169
170        let principal = ServicePrincipal::new(None, Capabilities::default());
171        let container = ContainerRef::new("c-guard", 0);
172        let embodiment = embody(&container, principal);
173
174        assert_is_identity_kit_principal(embodiment.principal());
175    }
176}