plexus_auth_core/oidc/mod.rs
1//! OIDC token validation — "the forthcoming verifier" (UT-1, UT-S01 D1).
2//!
3//! This module is the verifier that `verified_user.rs` was built to wait
4//! for. It implements the UT-S01 resolution model: every plexus backend
5//! validates tokens **locally, with zero shared secrets** —
6//!
7//! 1. Backend config names its trusted issuer URL and audience
8//! ([`OidcConfig`]).
9//! 2. The validator fetches `{issuer}/.well-known/openid-configuration`
10//! (OIDC Discovery) and reads `jwks_uri`.
11//! 3. It fetches the JWKS (RFC 7517), selects the key by the JWT header
12//! `kid`, and caches per the AUTH-8 policy (see "Caching policy").
13//! 4. It validates the **RS256** signature plus the standard claims:
14//! `iss` (== configured issuer), `aud` (== configured audience),
15//! `exp`/`nbf`/`iat` (zero leeway — no grace), `sub` present.
16//! 5. On success it mints the sealed
17//! [`VerifiedUser`](crate::VerifiedUser) — the only production call
18//! site of `VerifiedUser::new_sealed` — carrying the
19//! [`TenantId`](crate::TenantId) from the `org_id` claim (UT-S01 D3).
20//!
21//! # The Auth0-interchangeability bar (UT-S01 D2)
22//!
23//! The validator's only coupling to the IdP is (issuer URL, audience, the
24//! five standard claims, `org_id`). Pointing [`OidcConfig`] at a real
25//! Auth0 tenant (`https://<tenant>.auth0.com/`) with the backend
26//! registered as an Auth0 API is a zero-code-change swap. The plexus
27//! extensions `roles` / `username` are read if present and **optional for
28//! validation**, per the bar's negative-space rule.
29//!
30//! # Caching policy (AUTH-8, adopted verbatim)
31//!
32//! | Condition | Behavior |
33//! |---|---|
34//! | JWKS fetch succeeds | cache keys; TTL = min(`Cache-Control: max-age`, 3600 s); default 3600 s |
35//! | JWKS `max-age` below 60 s | TTL floored at 60 s (IDENTITY-27) — `max-age=0` cannot make every validation a fetch |
36//! | Token `kid` not in cache | one refresh, then reject (`UnknownKeyId`) — at most one such refresh per 60 s per validator, and concurrent refreshes coalesce into one (IDENTITY-27) |
37//! | IdP unreachable, cache present | keep validating with cached keys (degraded) — usable only for tokens whose `exp` is in the future, because `exp` is enforced with **zero grace** regardless |
38//! | IdP unreachable, no cache | reject (`JwksUnavailable` / `Discovery`) |
39//! | Discovery names a `jwks_uri` | trusted only if `https`, or on the issuer's own origin (IDENTITY-27) |
40//! | Fetched documents | at most 1 MiB, no redirects followed (`ReqwestJwksFetcher`, IDENTITY-27) |
41//! | Degradation transitions | `auth_provider_degraded` / `auth_provider_restored` events under `target = "plexus::auth"` |
42//!
43//! # Algorithm posture
44//!
45//! RS256-only for now (maximum Auth0 / off-the-shelf-middleware
46//! compatibility — UT-S01 open question 4). The design is
47//! EdDSA-extensible: key admission lives in one match in
48//! `jwks::admit_key`, and the per-token algorithm gate lives in one check
49//! in `validator.rs` — adding `EdDSA` is one arm in each.
50//!
51//! # No-network testing
52//!
53//! [`JwksFetcher`] is the injection seam: tests supply a fixture fetcher
54//! serving a canned discovery document and JWKS (see
55//! `tests/oidc_validator.rs`). The production fetcher
56//! (`ReqwestJwksFetcher`) is feature-gated behind `oidc-reqwest`.
57
58pub mod config;
59pub mod fetch;
60pub(crate) mod jwks;
61pub mod session;
62pub mod validator;
63
64pub use config::{Audience, AudienceClaim, AudienceError, OidcConfig};
65pub use fetch::{FetchError, FetchedDocument, JwksFetcher};
66#[cfg(feature = "oidc-reqwest")]
67pub use fetch::ReqwestJwksFetcher;
68pub use session::OidcSessionValidator;
69pub use validator::{OidcError, OidcValidator, VerifiedToken};