pub struct Principal { /* private fields */ }Expand description
An issuer-namespaced subject: idp:<uuid>, nostr:<64-hex>, apikey:<id>.
§Invariants
The fields are private and both constructors (Principal::new and
FromStr) validate, so every Principal value in existence satisfies
its issuer’s rules. Deserialize goes through FromStr, so a JSON document
cannot smuggle in an invalid one either.
Display and FromStr round-trip exactly — no
normalization is performed anywhere, because normalizing would let one
subject have two renderings and therefore two unequal Principals.
§Wire form
A plain JSON string ("idp:6ba7b810-9dad-11d1-80b4-00c04fd430c8"), not an
object — implemented by hand rather than with #[serde(transparent)] so
that deserialization can enforce validation.
§This is a name, not a proof
Holding a Principal proves nothing about authentication: it is data,
parsed from a string. The proof is Authenticated,
which only an Authenticator produces, and whose
principal field was populated from verified material.
Implementations§
Source§impl Principal
impl Principal
Sourcepub fn new(
issuer: Issuer,
subject: impl Into<String>,
) -> Result<Self, PrincipalParseError>
pub fn new( issuer: Issuer, subject: impl Into<String>, ) -> Result<Self, PrincipalParseError>
Build a principal, validating the subject against the issuer’s rules.
§Errors
See PrincipalParseError.
Sourcepub fn oidc(provider: &str, sub: &str) -> Result<Self, PrincipalParseError>
pub fn oidc(provider: &str, sub: &str) -> Result<Self, PrincipalParseError>
The principal an OIDC provider adapter mints: oidc:<provider>/<sub>.
provider is the adapter’s configured name (auth0). sub is the
provider’s subject exactly as its token carries it; any :, %,
quote, backslash or non-printable byte is percent-encoded, so
auth0|64f1 stays auth0|64f1 and a colon-bearing subject still
has one rendering that round-trips through Display and FromStr.
Sourcepub fn from_legacy_user_id(user_id: &str) -> Option<Self>
pub fn from_legacy_user_id(user_id: &str) -> Option<Self>
Interpret a legacy bare user_id as an idp principal.
This is the bridge that makes AuthContext::principal and
AuthContext::user_id agree by construction: today’s user_id is
a plexus-idp-minted UUID v4 reused verbatim as the JWT sub, so
idp:<user_id> is the same identity under a namespaced name.
Returns None for anything that is not a canonical hyphenated UUID —
notably "anonymous", and any user_id minted by a system that is
not plexus-idp. A None here means “this context has no principal we
can name”, never “this context is authenticated as something else”.
Sourcepub fn as_legacy_user_id(&self) -> String
pub fn as_legacy_user_id(&self) -> String
The value this principal contributes to the legacy
AuthContext::user_id
field.
For idp: principals this is the bare subject — byte-identical to
what plexus-idp writes today, so nothing that reads user_id
observes any change. For every other issuer it is the full
namespaced string (nostr:abc…), because a nostr pubkey and an idp
UUID share no namespace and must never collide in a column that
callers treat as a unique user key.