Skip to main content

plexus_auth_core/
verified_user.rs

1//! `VerifiedUser` — sealed proof that an IdP-signed token was verified.
2//!
3//! Possessing a `VerifiedUser` value is *proof* the framework verified an
4//! IdP-signed token. The constructor is `pub(crate)` to plexus-auth-core,
5//! so no other crate can fabricate one — the only path to producing a
6//! `VerifiedUser` runs through the (forthcoming) verifier inside this crate.
7//!
8//! Per AUTHZ-0 §"The sealed-type pattern":
9//!
10//! - **No fabrication.** Constructor is crate-private.
11//! - **No backdoor `From` / `Into`.** Orphan rules forbid foreign-trait
12//!   impls for this foreign type from a third crate.
13//! - **No accidental `Default`.** Not derived; a default would be
14//!   anonymous-with-no-claims, easy to confuse with verified-anonymous.
15//! - **No leaky `Deserialize`.** Not derived; raw JSON cannot fabricate a
16//!   sealed value.
17//! - **No mutation.** Fields are private; no setters.
18
19use crate::tenant::types::TenantId;
20use serde::Serialize;
21
22/// Sealed proof that an IdP-signed token was verified.
23///
24/// Carries the verified claims that the framework extracted from the signed
25/// token (`user_id`, `issuer`, `issued_at`, `expires_at`, and — per UT-1 —
26/// the optional `tenant` sourced from the `org_id` claim). The presence of
27/// a `VerifiedUser` value is itself the proof — there is no way to
28/// construct one from outside `plexus-auth-core`.
29///
30/// # Sealing
31///
32/// The constructor is `pub(crate)`. Only the verifier inside this crate
33/// (which validates the IdP signature) is able to mint a `VerifiedUser`.
34/// `tests/compile_fail/seal_verified_user_construct.rs` asserts that no
35/// external crate can construct one.
36#[derive(Debug, Clone, Serialize)]
37pub struct VerifiedUser {
38    user_id: String,
39    issuer: String,
40    issued_at: i64,
41    expires_at: i64,
42    /// The verified tenant identity, sourced from the token's `org_id`
43    /// claim (UT-S01 D3: `org_id` is the tenancy claim, Auth0
44    /// Organizations convention). `None` ⇔ the token carried no `org_id`
45    /// — a valid-but-tenantless user.
46    tenant: Option<TenantId>,
47}
48
49impl VerifiedUser {
50    /// Mint a new `VerifiedUser`.
51    ///
52    /// This is `pub(crate)` — only the verifier inside `plexus-auth-core`
53    /// can call it. The OIDC validator (`crate::oidc`, UT-1 / UT-S01 D1)
54    /// is the verifier this constructor was built to wait for: it mints a
55    /// `VerifiedUser` only after RS256 signature + `iss`/`aud`/`exp`/`iat`
56    /// validation succeeds. External crates that need a `VerifiedUser`
57    /// route through that validator; they cannot construct one directly.
58    pub(crate) fn new_sealed(
59        user_id: String,
60        issuer: String,
61        issued_at: i64,
62        expires_at: i64,
63        tenant: Option<TenantId>,
64    ) -> Self {
65        Self {
66            user_id,
67            issuer,
68            issued_at,
69            expires_at,
70            tenant,
71        }
72    }
73
74    /// The verified user identifier (e.g., the `sub` claim of the JWT).
75    pub fn user_id(&self) -> &str {
76        &self.user_id
77    }
78
79    /// The token issuer (e.g., the `iss` claim).
80    pub fn issuer(&self) -> &str {
81        &self.issuer
82    }
83
84    /// Token-issued-at unix timestamp.
85    pub fn issued_at(&self) -> i64 {
86        self.issued_at
87    }
88
89    /// Token expiry unix timestamp.
90    pub fn expires_at(&self) -> i64 {
91        self.expires_at
92    }
93
94    /// The verified tenant identity (the token's `org_id` claim), if any.
95    ///
96    /// `None` means the token was valid but carried no `org_id` — a
97    /// tenantless user (UT-S01 D3). Tenancy *authorization* still routes
98    /// through the sealed [`Tenant`](crate::Tenant) via a
99    /// [`TenantResolver`](crate::TenantResolver); this accessor exposes the
100    /// verified claim itself.
101    pub fn tenant_id(&self) -> Option<&TenantId> {
102        self.tenant.as_ref()
103    }
104}
105
106#[cfg(test)]
107mod tests {
108    use super::*;
109
110    #[test]
111    fn verified_user_carries_claims() {
112        // Crate-private constructor is reachable from inside the crate.
113        let v = VerifiedUser::new_sealed(
114            "alice".to_string(),
115            "https://idp.example.com".to_string(),
116            1_700_000_000,
117            1_700_003_600,
118            None,
119        );
120        assert_eq!(v.user_id(), "alice");
121        assert_eq!(v.issuer(), "https://idp.example.com");
122        assert_eq!(v.issued_at(), 1_700_000_000);
123        assert_eq!(v.expires_at(), 1_700_003_600);
124        assert!(v.tenant_id().is_none());
125    }
126
127    #[test]
128    fn verified_user_carries_org_id_tenant() {
129        // UT-1: a token whose `org_id` claim validated carries the typed
130        // tenant identity on the sealed proof.
131        let v = VerifiedUser::new_sealed(
132            "alice".to_string(),
133            "https://idp.example.com".to_string(),
134            1_700_000_000,
135            1_700_003_600,
136            Some(TenantId::try_new("org_hypermemetic").unwrap()),
137        );
138        assert_eq!(
139            v.tenant_id().map(TenantId::as_str),
140            Some("org_hypermemetic")
141        );
142    }
143}