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}