plexus-auth-core 0.2.2

Sealed-type primitives for the Plexus auth framework: AuthContext, VerifiedUser, Principal.
Documentation
//! `Principal` — sealed authenticated-actor identity.
//!
//! A `Principal` is an authenticated actor: a user, a service, or anonymous.
//! Every cross-boundary invocation has exactly one immediate-caller principal
//! that the framework auto-stamps. Activations receive a `&Principal`; they
//! cannot construct one.
//!
//! Per AUTHZ-0 §"The sealed-type pattern" (and the same protections enumerated
//! in `verified_user.rs`):
//!
//! - **No fabrication.** Constructors are crate-private.
//! - **No backdoor `From` / `Into`.** Orphan rules forbid foreign-trait
//!   impls for this foreign type from a third crate.
//! - **No accidental `Default`.** Not derived; a default would be ambiguous
//!   between anonymous and verified-anonymous.
//! - **No leaky `Deserialize`.** Not derived; raw JSON cannot fabricate one.
//! - **No mutation.** Fields are private; only accessors expose data.
//!
//! # Not to be confused with [`crate::identity::Principal`]
//!
//! This crate has two types named `Principal`, and they answer different
//! questions:
//!
//! - **this one** (`plexus_auth_core::Principal`) is the *caller-stamp*:
//!   what **kind** of actor made this call — anonymous, a user, a service.
//! - [`crate::identity::Principal`] is the *subject-name*: **which**
//!   identity, and who vouches for it (`idp:<uuid>`, `nostr:<pubkey>`).
//!
//! They compose rather than compete — [`Principal::subject`] projects one
//! into the other. The full resolution of the collision (including the third
//! same-named type in `plexus-core`) is recorded in the
//! [`crate::identity`] module docs, which is the single place to read about
//! it.

use crate::verified_user::VerifiedUser;
use serde::Serialize;

/// Service-identity claim, paired with `Principal::Service` to identify a
/// non-user authenticated actor (e.g., another Plexus deployment).
#[derive(Debug, Clone, Serialize)]
pub struct ServiceIdentity {
    service_id: String,
}

impl ServiceIdentity {
    /// Mint a `ServiceIdentity`. Crate-private — only the framework's
    /// verifier code (inside `plexus-auth-core`) is able to produce one.
    ///
    /// `dead_code` is allowed for the same reason as
    /// [`VerifiedUser::new_sealed`]: the verifier-side caller lands in a
    /// follow-up ticket. The constructor must exist now for the trybuild
    /// compile-fail asserts to be meaningful.
    #[allow(dead_code)]
    pub(crate) fn new_sealed(service_id: String) -> Self {
        Self { service_id }
    }

    /// The service identifier (e.g., a SPIFFE ID or workload name).
    pub fn service_id(&self) -> &str {
        &self.service_id
    }
}

/// An authenticated actor: a user, a service, or anonymous.
///
/// Every cross-boundary invocation carries exactly one immediate-caller
/// `Principal`. The framework stamps it; activations read it; nobody outside
/// `plexus-auth-core` can construct one.
///
/// # Sealing
///
/// The discriminants below carry sealed payloads (`VerifiedUser`,
/// `ServiceIdentity`), and the `Anonymous` variant is constructable only via
/// the `pub(crate)` `anonymous_sealed` constructor. This means external
/// crates cannot match-then-rebuild a `Principal::Anonymous` and pass it
/// off as authentic; the only way to obtain any `Principal` is through the
/// framework's mint paths inside this crate.
///
/// `tests/compile_fail/seal_principal_construct.rs` asserts external
/// construction is rejected.
#[derive(Debug, Clone, Serialize)]
pub enum Principal {
    /// An end-user principal, carrying the verified token claims.
    User(VerifiedUser),
    /// A non-user authenticated principal (e.g., another Plexus service).
    Service(ServiceIdentity),
    /// An unauthenticated caller. Methods marked `#[plexus::method(public)]`
    /// see this; everything else is denied at the perimeter.
    Anonymous,
}

impl Principal {
    /// Mint the anonymous principal. Crate-private — exists so no external
    /// crate can construct *any* `Principal` variant directly.
    ///
    /// `dead_code` is allowed because the framework code that mints
    /// principals lives in plexus-transport and lands in a follow-up
    /// ticket. The constructor must exist now for the trybuild
    /// compile-fail asserts to be meaningful.
    #[allow(dead_code)]
    pub(crate) fn anonymous_sealed() -> Self {
        Self::Anonymous
    }

    /// Mint a `Principal::User` from a `VerifiedUser`. Crate-private.
    #[allow(dead_code)]
    pub(crate) fn user_sealed(verified: VerifiedUser) -> Self {
        Self::User(verified)
    }

    /// Mint a `Principal::Service` from a `ServiceIdentity`. Crate-private.
    #[allow(dead_code)]
    pub(crate) fn service_sealed(service: ServiceIdentity) -> Self {
        Self::Service(service)
    }

    /// Is this principal a verified user?
    pub fn is_user(&self) -> bool {
        matches!(self, Self::User(_))
    }

    /// Is this principal anonymous?
    pub fn is_anonymous(&self) -> bool {
        matches!(self, Self::Anonymous)
    }

    /// This caller-stamp's namespaced subject, when it names one.
    ///
    /// The bridge between the two `Principal`s in this crate — see the
    /// [module docs](self) and [`crate::identity`]. The caller-stamp says
    /// *what kind* of actor is calling; this projects that into *which*
    /// identity, when the stamp carries enough to name one.
    ///
    /// - [`User`](Principal::User) — the verified user's id, interpreted as
    ///   `idp:<uuid>`. `None` if that id is not a plexus-idp UUID (an
    ///   externally-federated subject, say), because guessing a namespace
    ///   for it would fabricate an identity.
    /// - [`Service`](Principal::Service) — `None`. A service id is a
    ///   workload name (a SPIFFE ID, say), not an issuer-namespaced subject;
    ///   giving service identities a namespace is future work, not something
    ///   to infer here.
    /// - [`Anonymous`](Principal::Anonymous) — `None`, necessarily.
    pub fn subject(&self) -> Option<crate::identity::Principal> {
        match self {
            Self::User(v) => crate::identity::Principal::from_legacy_user_id(v.user_id()),
            Self::Service(_) | Self::Anonymous => None,
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn principal_anonymous_constructs() {
        let p = Principal::anonymous_sealed();
        assert!(p.is_anonymous());
        assert!(!p.is_user());
    }

    #[test]
    fn principal_user_carries_verified() {
        let v = VerifiedUser::new_sealed(
            "alice".to_string(),
            "https://idp.example.com".to_string(),
            1_700_000_000,
            1_700_003_600,
            None,
        );
        let p = Principal::user_sealed(v);
        assert!(p.is_user());
        match p {
            Principal::User(v) => assert_eq!(v.user_id(), "alice"),
            _ => unreachable!("expected User variant"),
        }
    }

    #[test]
    fn principal_service_carries_identity() {
        let s = ServiceIdentity::new_sealed("plexus.example".to_string());
        let p = Principal::service_sealed(s);
        match p {
            Principal::Service(s) => assert_eq!(s.service_id(), "plexus.example"),
            _ => unreachable!("expected Service variant"),
        }
    }
}