pub trait FederationKeySource:
Send
+ Sync
+ 'static {
// Required methods
fn is_trusted(&self, issuer: &str) -> bool;
fn get_keys<'life0, 'life1, 'life2, 'async_trait>(
&'life0 self,
issuer: &'life1 str,
kid: Option<&'life2 str>,
) -> Pin<Box<dyn Future<Output = Result<Vec<FederationKey>>> + Send + 'async_trait>>
where Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait;
}Expand description
Resolves external JWT issuer URLs to Ed25519 verifying keys.
Implemented by hyprstream::auth::FederationKeyResolver. Services that
serve external traffic return Some(Arc<dyn FederationKeySource>) from
RequestService::federation_key_source() so the default verify_claims()
can perform real key resolution instead of rejecting federated JWTs.
§Key-set semantics (rotation-aware, #1185)
A published JWKS is a named set, never an ordered singleton. get_keys
returns every usable named Ed25519 entry from the issuer’s current JWKS so
a token without a kid can try each candidate. When the JWT carries a
kid, it returns only entries with that exact kid; a named token must
never verify with another co-published key.
The resolver MUST NOT collapse the set to a positional singleton: returning
the “first” Ed25519 key forecloses rotation (#1183). An empty result is an
Err.
§Note on Send bounds
get_keys uses the default (Send) flavour of #[async_trait] because
FederationKeyResolver performs real async I/O (HTTPS JWKS fetch) whose
future must be Send. Call sites inside #[async_trait(?Send)] contexts
(e.g. RequestService::verify_claims) may .await this future directly:
it is valid in Rust to await a Send future from within a !Send
async function — the ?Send bound constrains the outer function’s
future, not the futures it polls. RequestService::verify_claims does
exactly this and compiles correctly.
Required Methods§
Sourcefn is_trusted(&self, issuer: &str) -> bool
fn is_trusted(&self, issuer: &str) -> bool
Return true if issuer is in the configured trusted-issuer list.
Callers should check this before calling get_keys to distinguish an
untrusted issuer (policy reject → 401) from a transient fetch error
(retry eligible → 503).
Sourcefn get_keys<'life0, 'life1, 'life2, 'async_trait>(
&'life0 self,
issuer: &'life1 str,
kid: Option<&'life2 str>,
) -> Pin<Box<dyn Future<Output = Result<Vec<FederationKey>>> + Send + 'async_trait>>where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
fn get_keys<'life0, 'life1, 'life2, 'async_trait>(
&'life0 self,
issuer: &'life1 str,
kid: Option<&'life2 str>,
) -> Pin<Box<dyn Future<Output = Result<Vec<FederationKey>>> + Send + 'async_trait>>where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
Fetch (or return from cache) the Ed25519 candidate verifying keys for
issuer.
Returns every usable named Ed25519 key from the issuer’s JWKS. When
kid is Some, every returned entry has that exact kid; when it is
None, the caller may try each candidate against the JWT.
On a cache miss for the requested kid, the resolver refetches the
JWKS once and re-checks. A kid that is still absent after a fresh
fetch fails closed (Err); the resolver MUST NOT silently substitute
another key for a named kid.
§Errors
Returns Err if:
- the issuer is not in the trusted list (
is_trustedreturnsfalse), or - the JWKS endpoint is unreachable or returns no usable Ed25519 key, or
kidisSomeand no candidate with thatkidexists after refetch.