Skip to main content

plexus_auth_core/
principal.rs

1//! `Principal` — sealed authenticated-actor identity.
2//!
3//! A `Principal` is an authenticated actor: a user, a service, or anonymous.
4//! Every cross-boundary invocation has exactly one immediate-caller principal
5//! that the framework auto-stamps. Activations receive a `&Principal`; they
6//! cannot construct one.
7//!
8//! Per AUTHZ-0 §"The sealed-type pattern" (and the same protections enumerated
9//! in `verified_user.rs`):
10//!
11//! - **No fabrication.** Constructors are crate-private.
12//! - **No backdoor `From` / `Into`.** Orphan rules forbid foreign-trait
13//!   impls for this foreign type from a third crate.
14//! - **No accidental `Default`.** Not derived; a default would be ambiguous
15//!   between anonymous and verified-anonymous.
16//! - **No leaky `Deserialize`.** Not derived; raw JSON cannot fabricate one.
17//! - **No mutation.** Fields are private; only accessors expose data.
18//!
19//! # Not to be confused with [`crate::identity::Principal`]
20//!
21//! This crate has two types named `Principal`, and they answer different
22//! questions:
23//!
24//! - **this one** (`plexus_auth_core::Principal`) is the *caller-stamp*:
25//!   what **kind** of actor made this call — anonymous, a user, a service.
26//! - [`crate::identity::Principal`] is the *subject-name*: **which**
27//!   identity, and who vouches for it (`idp:<uuid>`, `nostr:<pubkey>`).
28//!
29//! They compose rather than compete — [`Principal::subject`] projects one
30//! into the other. The full resolution of the collision (including the third
31//! same-named type in `plexus-core`) is recorded in the
32//! [`crate::identity`] module docs, which is the single place to read about
33//! it.
34
35use crate::verified_user::VerifiedUser;
36use serde::Serialize;
37
38/// Service-identity claim, paired with `Principal::Service` to identify a
39/// non-user authenticated actor (e.g., another Plexus deployment).
40#[derive(Debug, Clone, Serialize)]
41pub struct ServiceIdentity {
42    service_id: String,
43}
44
45impl ServiceIdentity {
46    /// Mint a `ServiceIdentity`. Crate-private — only the framework's
47    /// verifier code (inside `plexus-auth-core`) is able to produce one.
48    ///
49    /// `dead_code` is allowed for the same reason as
50    /// [`VerifiedUser::new_sealed`]: the verifier-side caller lands in a
51    /// follow-up ticket. The constructor must exist now for the trybuild
52    /// compile-fail asserts to be meaningful.
53    #[allow(dead_code)]
54    pub(crate) fn new_sealed(service_id: String) -> Self {
55        Self { service_id }
56    }
57
58    /// The service identifier (e.g., a SPIFFE ID or workload name).
59    pub fn service_id(&self) -> &str {
60        &self.service_id
61    }
62}
63
64/// An authenticated actor: a user, a service, or anonymous.
65///
66/// Every cross-boundary invocation carries exactly one immediate-caller
67/// `Principal`. The framework stamps it; activations read it; nobody outside
68/// `plexus-auth-core` can construct one.
69///
70/// # Sealing
71///
72/// The discriminants below carry sealed payloads (`VerifiedUser`,
73/// `ServiceIdentity`), and the `Anonymous` variant is constructable only via
74/// the `pub(crate)` `anonymous_sealed` constructor. This means external
75/// crates cannot match-then-rebuild a `Principal::Anonymous` and pass it
76/// off as authentic; the only way to obtain any `Principal` is through the
77/// framework's mint paths inside this crate.
78///
79/// `tests/compile_fail/seal_principal_construct.rs` asserts external
80/// construction is rejected.
81#[derive(Debug, Clone, Serialize)]
82pub enum Principal {
83    /// An end-user principal, carrying the verified token claims.
84    User(VerifiedUser),
85    /// A non-user authenticated principal (e.g., another Plexus service).
86    Service(ServiceIdentity),
87    /// An unauthenticated caller. Methods marked `#[plexus::method(public)]`
88    /// see this; everything else is denied at the perimeter.
89    Anonymous,
90}
91
92impl Principal {
93    /// Mint the anonymous principal. Crate-private — exists so no external
94    /// crate can construct *any* `Principal` variant directly.
95    ///
96    /// `dead_code` is allowed because the framework code that mints
97    /// principals lives in plexus-transport and lands in a follow-up
98    /// ticket. The constructor must exist now for the trybuild
99    /// compile-fail asserts to be meaningful.
100    #[allow(dead_code)]
101    pub(crate) fn anonymous_sealed() -> Self {
102        Self::Anonymous
103    }
104
105    /// Mint a `Principal::User` from a `VerifiedUser`. Crate-private.
106    #[allow(dead_code)]
107    pub(crate) fn user_sealed(verified: VerifiedUser) -> Self {
108        Self::User(verified)
109    }
110
111    /// Mint a `Principal::Service` from a `ServiceIdentity`. Crate-private.
112    #[allow(dead_code)]
113    pub(crate) fn service_sealed(service: ServiceIdentity) -> Self {
114        Self::Service(service)
115    }
116
117    /// Is this principal a verified user?
118    pub fn is_user(&self) -> bool {
119        matches!(self, Self::User(_))
120    }
121
122    /// Is this principal anonymous?
123    pub fn is_anonymous(&self) -> bool {
124        matches!(self, Self::Anonymous)
125    }
126
127    /// This caller-stamp's namespaced subject, when it names one.
128    ///
129    /// The bridge between the two `Principal`s in this crate — see the
130    /// [module docs](self) and [`crate::identity`]. The caller-stamp says
131    /// *what kind* of actor is calling; this projects that into *which*
132    /// identity, when the stamp carries enough to name one.
133    ///
134    /// - [`User`](Principal::User) — the verified user's id, interpreted as
135    ///   `idp:<uuid>`. `None` if that id is not a plexus-idp UUID (an
136    ///   externally-federated subject, say), because guessing a namespace
137    ///   for it would fabricate an identity.
138    /// - [`Service`](Principal::Service) — `None`. A service id is a
139    ///   workload name (a SPIFFE ID, say), not an issuer-namespaced subject;
140    ///   giving service identities a namespace is future work, not something
141    ///   to infer here.
142    /// - [`Anonymous`](Principal::Anonymous) — `None`, necessarily.
143    pub fn subject(&self) -> Option<crate::identity::Principal> {
144        match self {
145            Self::User(v) => crate::identity::Principal::from_legacy_user_id(v.user_id()),
146            Self::Service(_) | Self::Anonymous => None,
147        }
148    }
149}
150
151#[cfg(test)]
152mod tests {
153    use super::*;
154
155    #[test]
156    fn principal_anonymous_constructs() {
157        let p = Principal::anonymous_sealed();
158        assert!(p.is_anonymous());
159        assert!(!p.is_user());
160    }
161
162    #[test]
163    fn principal_user_carries_verified() {
164        let v = VerifiedUser::new_sealed(
165            "alice".to_string(),
166            "https://idp.example.com".to_string(),
167            1_700_000_000,
168            1_700_003_600,
169            None,
170        );
171        let p = Principal::user_sealed(v);
172        assert!(p.is_user());
173        match p {
174            Principal::User(v) => assert_eq!(v.user_id(), "alice"),
175            _ => unreachable!("expected User variant"),
176        }
177    }
178
179    #[test]
180    fn principal_service_carries_identity() {
181        let s = ServiceIdentity::new_sealed("plexus.example".to_string());
182        let p = Principal::service_sealed(s);
183        match p {
184            Principal::Service(s) => assert_eq!(s.service_id(), "plexus.example"),
185            _ => unreachable!("expected Service variant"),
186        }
187    }
188}