Skip to main content

FederationKeySource

Trait FederationKeySource 

Source
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§

Source

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).

Source

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_trusted returns false), or
  • the JWKS endpoint is unreachable or returns no usable Ed25519 key, or
  • kid is Some and no candidate with that kid exists after refetch.

Implementors§