graphrt-llm 0.2.0

Model providers (OpenAI-compatible, Anthropic, Gemini, AWS Bedrock, TypeSafe Jev) and LLM, classifier, extractor and agent nodes for the graphrt workflow runtime.
Documentation
//! Dynamic credentials for model providers.
//!
//! A static API key is fine on a server, but an app running on a user's device
//! must not ship a provider key inside its binary. Providers therefore accept a
//! [`CredentialSource`], asked for a credential right before each request:
//!
//! - bring-your-own-key: the host app reads the user's key from the platform
//!   keychain / keystore;
//! - token broker: a backend issues short-lived, per-user tokens;
//! - static keys for servers and tests ([`StaticCredential`]).
//!
//! Sources are consulted per request. Wrap slow or rate-limited sources in
//! [`CachedCredentials`], which caches until shortly before expiry and shares
//! one refresh between concurrent requests.
//!
//! | Source | Use |
//! | --- | --- |
//! | [`StaticCredential`] | Servers, tests. |
//! | [`EnvCredentials`] | Servers: read the key from an environment variable at request time. |
//! | [`FnCredentials`] | Hosts: any async closure (keychain lookup, custom auth). |
//! | [`TokenBroker`] (feature `http`) | Apps: short-lived tokens from your backend. |
//!
//! See `docs/credentials.md` for the threat model and the proxy pattern.

#[cfg(feature = "http")]
mod broker;
mod cached;
mod sources;

#[cfg(feature = "http")]
pub use broker::{BrokerAuth, TokenBroker, TokenBrokerConfig};
pub use cached::{CachedCredentials, DEFAULT_REFRESH_SKEW_MS};
pub use sources::{EnvCredentials, FnCredentials};

use std::fmt;

use futures::future::BoxFuture;

use crate::error::LlmError;

/// A credential to authenticate one request.
#[derive(Clone, PartialEq, Eq)]
pub struct Credential {
    /// The secret sent to the provider (API key or bearer token).
    pub secret: String,
    /// Absolute expiry in Unix milliseconds, when known.
    pub expires_at_ms: Option<u64>,
    /// Extra headers to attach (e.g. a tenant or session header issued with a token).
    pub headers: Vec<(String, String)>,
    /// Endpoint override issued with the credential (e.g. a regional proxy). Applied
    /// in place of the provider's configured base URL when set.
    pub base_url: Option<String>,
}

impl Credential {
    pub fn new(secret: impl Into<String>) -> Self {
        Self { secret: secret.into(), expires_at_ms: None, headers: Vec::new(), base_url: None }
    }

    pub fn expires_at(mut self, unix_ms: u64) -> Self {
        self.expires_at_ms = Some(unix_ms);
        self
    }

    pub fn header(mut self, name: impl Into<String>, value: impl Into<String>) -> Self {
        self.headers.push((name.into(), value.into()));
        self
    }

    pub fn base_url(mut self, base_url: impl Into<String>) -> Self {
        self.base_url = Some(base_url.into());
        self
    }

    /// Whether the credential is expired (or within `skew_ms` of expiring) at `now_ms`.
    pub fn is_expired_at(&self, now_ms: u64, skew_ms: u64) -> bool {
        self.expires_at_ms.is_some_and(|exp| now_ms.saturating_add(skew_ms) >= exp)
    }
}

/// Current Unix time in milliseconds. On `wasm32-unknown-unknown`, where there is
/// no system clock, returns 0: credentials then never expire by time and are
/// refreshed only through [`CredentialSource::invalidate`].
pub fn unix_now_ms() -> u64 {
    #[cfg(all(target_arch = "wasm32", target_os = "unknown"))]
    {
        0
    }
    #[cfg(not(all(target_arch = "wasm32", target_os = "unknown")))]
    {
        std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .map(|d| u64::try_from(d.as_millis()).unwrap_or(u64::MAX))
            .unwrap_or(0)
    }
}

impl fmt::Debug for Credential {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("Credential")
            .field("secret", &"<redacted>")
            .field("expires_at_ms", &self.expires_at_ms)
            .field("headers", &self.headers.iter().map(|(k, _)| k).collect::<Vec<_>>())
            .field("base_url", &self.base_url)
            .finish()
    }
}

/// Whether `url` may receive credentials: `https://`, or `http://` to a loopback /
/// Android-emulator-host address (local development and tests only).
pub fn is_secure_endpoint(url: &str) -> bool {
    if url.starts_with("https://") {
        return true;
    }
    let Some(rest) = url.strip_prefix("http://") else {
        return false;
    };
    let authority = rest.split(['/', '?', '#']).next().unwrap_or_default();
    let authority = authority.rsplit_once('@').map_or(authority, |(_, host)| host);
    let host = match authority.strip_prefix('[') {
        Some(v6) => v6.split(']').next().unwrap_or_default(),
        None => authority.rsplit_once(':').map_or(authority, |(h, _)| h),
    };
    matches!(host, "localhost" | "::1" | "10.0.2.2")
        || host.parse::<std::net::Ipv4Addr>().is_ok_and(|ip| ip.is_loopback())
}

/// Validate an endpoint that will receive credentials.
pub fn require_secure_endpoint(url: &str, what: &str) -> Result<(), LlmError> {
    if is_secure_endpoint(url) {
        Ok(())
    } else {
        Err(LlmError::Config(format!(
            "{what} must use https:// (plain http is only allowed for localhost / 127.0.0.1 / 10.0.2.2)"
        )))
    }
}

/// Supplies credentials on demand.
pub trait CredentialSource: Send + Sync + fmt::Debug {
    /// Credential for `provider` (the registry name, e.g. `openai`).
    fn credential<'a>(&'a self, provider: &'a str) -> BoxFuture<'a, Result<Credential, LlmError>>;

    /// Called when the provider rejected the last credential (HTTP 401/403), so
    /// cached values can be dropped before one retry.
    fn invalidate(&self, provider: &str) {
        let _ = provider;
    }

    /// A counter that changes whenever credentials this source would return for
    /// any provider may have changed outside of [`CredentialSource::invalidate`]
    /// (e.g. the host app signed a user out or registered a new key source).
    /// [`CachedCredentials`] drops cached values when it changes. Default: never changes.
    fn generation(&self) -> u64 {
        0
    }
}

/// A fixed secret.
#[derive(Clone)]
pub struct StaticCredential(Credential);

impl StaticCredential {
    pub fn new(secret: impl Into<String>) -> Self {
        Self(Credential::new(secret))
    }

    /// A fixed, fully specified credential (headers, base URL, expiry).
    pub fn from_credential(credential: Credential) -> Self {
        Self(credential)
    }
}

impl fmt::Debug for StaticCredential {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str("StaticCredential(<redacted>)")
    }
}

impl CredentialSource for StaticCredential {
    fn credential<'a>(&'a self, _provider: &'a str) -> BoxFuture<'a, Result<Credential, LlmError>> {
        Box::pin(futures::future::ready(Ok(self.0.clone())))
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn debug_never_shows_secrets() {
        let c = Credential::new("sk-secret").header("x-tenant", "t-secret");
        let text = format!("{c:?} {:?}", StaticCredential::new("sk-secret"));
        assert!(!text.contains("sk-secret"));
        assert!(!text.contains("t-secret"));
    }
}