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}