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}