authn_resolver_sdk/
plugin_api.rs

1//! Plugin API trait for `AuthN` resolver implementations.
2//!
3//! Plugins implement this trait to provide token validation.
4//! The gateway discovers plugins via GTS types-registry and delegates
5//! API calls to the selected plugin.
6
7use async_trait::async_trait;
8
9use crate::error::AuthNResolverError;
10use crate::models::{AuthenticationResult, ClientCredentialsRequest};
11
12/// Plugin API trait for `AuthN` resolver implementations.
13///
14/// Each plugin registers this trait with a scoped `ClientHub` entry
15/// using its GTS instance ID as the scope.
16///
17/// The gateway delegates to this method. Cross-cutting concerns (logging,
18/// metrics) may be added at the gateway level in the future.
19#[async_trait]
20pub trait AuthNResolverPluginClient: Send + Sync {
21    /// Authenticate a bearer token and return the validated identity.
22    ///
23    /// # Arguments
24    ///
25    /// * `bearer_token` - The raw bearer token string
26    ///
27    /// # Errors
28    ///
29    /// - `Unauthorized` if the token is invalid, expired, or malformed
30    /// - `Internal` for unexpected errors
31    async fn authenticate(
32        &self,
33        bearer_token: &str,
34    ) -> Result<AuthenticationResult, AuthNResolverError>;
35
36    /// Exchange client credentials for an `AuthenticationResult`.
37    ///
38    /// The plugin performs the actual `OAuth2` `client_credentials` flow
39    /// (or static credential lookup) and returns an `AuthenticationResult`
40    /// containing the validated `SecurityContext`.
41    ///
42    /// # Scopes
43    ///
44    /// Production plugins forward `scopes` to the `IdP` as-is in the
45    /// `OAuth2` `scope` parameter. Plugins that do not interact with an
46    /// `IdP` (e.g., static dev plugins) may ignore this field.
47    ///
48    /// # Errors
49    ///
50    /// - `TokenAcquisitionFailed` if credentials are invalid or `IdP` is unreachable
51    /// - `Internal` for unexpected errors
52    async fn exchange_client_credentials(
53        &self,
54        request: &ClientCredentialsRequest,
55    ) -> Result<AuthenticationResult, AuthNResolverError>;
56}
authn_resolver_sdk/plugin_api.rs

authn_resolver_sdk/
plugin_api.rs
