lean-ctx-engine 3.12.2

//! HTTP client with pluggable authentication for config-based providers.
//!
//! Builds and executes authenticated HTTP requests using ureq based on
//! the `AuthConfig` from the provider's TOML/JSON definition.

use std::collections::HashMap;

use super::schema::{AuthConfig, ResourceConfig};

/// Resolved auth credentials (env vars already read).
#[derive(Debug, Clone)]
pub enum ResolvedAuth {
    Bearer(String),
    ApiKeyHeader { header: String, value: String },
    ApiKeyQuery { param: String, value: String },
    Basic { username: String, password: String },
    CustomHeader { header: String, value: String },
    None,
}

impl ResolvedAuth {
    /// Bind a source to the resolved credential without making credentials
    /// serializable. Length framing separates fields and authentication kinds.
    pub(super) fn binding_digest(&self) -> String {
        let fields: Vec<&str> = match self {
            Self::Bearer(token) => vec!["bearer", token],
            Self::ApiKeyHeader { header, value } => vec!["api-key-header", header, value],
            Self::ApiKeyQuery { param, value } => vec!["api-key-query", param, value],
            Self::Basic { username, password } => vec!["basic", username, password],
            Self::CustomHeader { header, value } => vec!["custom-header", header, value],
            Self::None => vec!["none"],
        };
        let mut hash = blake3::Hasher::new_derive_key("leanctx.provider.credential-binding.v1");
        for field in fields {
            hash.update(&(field.len() as u64).to_le_bytes());
            hash.update(field.as_bytes());
        }
        hash.finalize().to_hex().to_string()
    }

    /// Resolve auth credentials from environment variables.
    pub fn from_config(auth: &AuthConfig) -> Result<Self, String> {
        match auth {
            AuthConfig::Bearer { token_env } => {
                let token = read_env(token_env)?;
                Ok(Self::Bearer(token))
            }
            AuthConfig::ApiKey {
                key_env,
                header_name,
                query_param,
            } => {
                let key = read_env(key_env)?;
                if let Some(header) = header_name {
                    Ok(Self::ApiKeyHeader {
                        header: header.clone(),
                        value: key,
                    })
                } else if let Some(param) = query_param {
                    Ok(Self::ApiKeyQuery {
                        param: param.clone(),
                        value: key,
                    })
                } else {
                    Ok(Self::ApiKeyHeader {
                        header: "X-Api-Key".into(),
                        value: key,
                    })
                }
            }
            AuthConfig::Basic {
                username_env,
                password_env,
            } => {
                let username = read_env(username_env)?;
                let password = read_env(password_env)?;
                Ok(Self::Basic { username, password })
            }
            AuthConfig::Header {
                header_name,
                value_env,
            } => {
                let value = read_env(value_env)?;
                Ok(Self::CustomHeader {
                    header: header_name.clone(),
                    value,
                })
            }
            AuthConfig::None => Ok(Self::None),
        }
    }

    /// Whether auth credentials could be resolved (provider is usable).
    pub fn is_available(auth: &AuthConfig) -> bool {
        match auth {
            AuthConfig::Bearer { token_env } => std::env::var(token_env).is_ok(),
            AuthConfig::ApiKey { key_env, .. } => std::env::var(key_env).is_ok(),
            AuthConfig::Basic {
                username_env,
                password_env,
            } => std::env::var(username_env).is_ok() && std::env::var(password_env).is_ok(),
            AuthConfig::Header { value_env, .. } => std::env::var(value_env).is_ok(),
            AuthConfig::None => true,
        }
    }
}

fn read_env(var: &str) -> Result<String, String> {
    std::env::var(var).map_err(|_| format!("Environment variable '{var}' not set"))
}

/// Interpolate `{param}` placeholders in a string with actual values.
pub fn interpolate(template: &str, params: &HashMap<String, String>) -> String {
    let mut result = template.to_string();
    for (key, value) in params {
        result = result.replace(&format!("{{{key}}}"), value);
    }
    // Remove unresolved placeholders (optional params not provided)
    let re = regex::Regex::new(r"\{[a-zA-Z_][a-zA-Z0-9_]*\}").expect("valid placeholder regex");
    re.replace_all(&result, "").to_string()
}

/// Build the full URL with query parameters.
fn build_url(
    base_url: &str,
    resource: &ResourceConfig,
    interp_params: &HashMap<String, String>,
    auth: &ResolvedAuth,
) -> String {
    let path = interpolate(&resource.path, interp_params);
    let base = base_url.trim_end_matches('/');
    let mut url = format!("{base}{path}");

    let mut query_parts: Vec<String> = Vec::new();
    for (key, val_template) in &resource.query_params {
        let val = interpolate(val_template, interp_params);
        if !val.is_empty() {
            query_parts.push(format!(
                "{}={}",
                urlencoding::encode(key),
                urlencoding::encode(&val)
            ));
        }
    }

    if let ResolvedAuth::ApiKeyQuery { param, value } = auth {
        query_parts.push(format!(
            "{}={}",
            urlencoding::encode(param),
            urlencoding::encode(value)
        ));
    }

    if !query_parts.is_empty() {
        url.push('?');
        url.push_str(&query_parts.join("&"));
    }

    url
}

/// Collect all headers (auth + resource-specific + Accept).
fn collect_headers(
    auth: &ResolvedAuth,
    resource_headers: &HashMap<String, String>,
) -> Vec<(String, String)> {
    let mut headers = Vec::new();

    match auth {
        ResolvedAuth::Bearer(token) => {
            headers.push(("Authorization".into(), format!("Bearer {token}")));
        }
        ResolvedAuth::ApiKeyHeader { header, value }
        | ResolvedAuth::CustomHeader { header, value } => {
            headers.push((header.clone(), value.clone()));
        }
        ResolvedAuth::Basic { username, password } => {
            let encoded = crate::core::providers::config_provider::base64_encode(
                format!("{username}:{password}").as_bytes(),
            );
            headers.push(("Authorization".into(), format!("Basic {encoded}")));
        }
        ResolvedAuth::ApiKeyQuery { .. } | ResolvedAuth::None => {}
    }

    for (key, value) in resource_headers {
        headers.push((key.clone(), value.clone()));
    }

    headers.push(("Accept".into(), "application/json".into()));
    headers
}

/// Parse the response body into JSON, checking status first.
fn parse_response(status: u16, body: &str, url: &str) -> Result<serde_json::Value, String> {
    if !(200..300).contains(&status) {
        return Err(format!(
            "API returned status {status} for {}",
            url.split('?').next().unwrap_or(url)
        ));
    }
    serde_json::from_str(body).map_err(|e| format!("Invalid JSON response: {e}"))
}

fn status_to_u16(status: ureq::http::StatusCode) -> u16 {
    status.as_u16()
}

/// Execute an HTTP request to the external API.
///
/// Only the read methods of [`super::schema::READ_METHODS`] are sent: GET, and
/// POST with an empty body (ureq 3 uses different types for body vs bodyless
/// requests). Any other method is refused before a request exists, even if
/// validation was bypassed.
pub fn execute_request(
    base_url: &str,
    resource: &ResourceConfig,
    auth: &ResolvedAuth,
    interp_params: &HashMap<String, String>,
) -> Result<serde_json::Value, String> {
    let method = resource.method.to_uppercase();
    if !super::schema::READ_METHODS.contains(&method.as_str()) {
        return Err(format!(
            "method '{}' is not a read method; connectors are read-only",
            resource.method
        ));
    }
    let url = build_url(base_url, resource, interp_params, auth);
    let headers = collect_headers(auth, &resource.headers);
    let agent = crate::core::providers::hardened_http::hardened_agent();

    let res = if method == "POST" {
        let mut req = agent.post(&url);
        for (k, v) in &headers {
            req = req.header(k, v);
        }
        req.send_empty()
    } else {
        let mut req = agent.get(&url);
        for (k, v) in &headers {
            req = req.header(k, v);
        }
        req.call()
    }
    .map_err(|e| format!("HTTP request failed: {e}"))?;
    let status = status_to_u16(res.status());
    if !(200..300).contains(&status) {
        return Err(format!("API returned status {status}"));
    }
    let body = res
        .into_body()
        .read_to_string()
        .map_err(|e| format!("Failed to read response body: {e}"))?;

    parse_response(status, &body, &url)
}

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

    #[test]
    fn interpolate_replaces_known_params() {
        let mut params = HashMap::new();
        params.insert("limit".into(), "10".into());
        params.insert("state".into(), "open".into());
        params.insert("owner".into(), "acme".into());
        assert_eq!(
            interpolate("/repos/{owner}/issues?limit={limit}&state={state}", &params),
            "/repos/acme/issues?limit=10&state=open"
        );
    }

    #[test]
    fn interpolate_removes_unresolved_placeholders() {
        let params = HashMap::new();
        assert_eq!(
            interpolate("/items?filter={filter}", &params),
            "/items?filter="
        );
    }

    #[test]
    fn build_url_with_query_params() {
        let resource = ResourceConfig {
            method: "GET".into(),
            path: "/issues".into(),
            query_params: {
                let mut m = HashMap::new();
                m.insert("state".into(), "{state}".into());
                m.insert("per_page".into(), "{limit}".into());
                m
            },
            headers: HashMap::new(),
            response: super::super::schema::ResponseConfig {
                root: None,
                mapping: super::super::schema::FieldMapping {
                    id: "id".into(),
                    title: "title".into(),
                    body: None,
                    state: None,
                    author: None,
                    url: None,
                    labels: None,
                    created_at: None,
                    updated_at: None,
                },
            },
        };
        let mut params = HashMap::new();
        params.insert("state".into(), "open".into());
        params.insert("limit".into(), "25".into());

        let url = build_url(
            "https://api.example.com",
            &resource,
            &params,
            &ResolvedAuth::None,
        );
        assert!(url.starts_with("https://api.example.com/issues?"));
        assert!(url.contains("state=open"));
        assert!(url.contains("per_page=25"));
    }

    /// A write method never becomes a request, even on a config that skipped
    /// validation: the refusal comes before any URL is built or sent (the
    /// unroutable host would otherwise give a transport error).
    #[test]
    fn write_methods_are_refused_before_any_request() {
        for method in ["PUT", "PATCH", "DELETE", "delete"] {
            let resource = ResourceConfig {
                method: method.into(),
                path: "/items".into(),
                query_params: HashMap::new(),
                headers: HashMap::new(),
                response: super::super::schema::ResponseConfig {
                    root: None,
                    mapping: super::super::schema::FieldMapping {
                        id: "id".into(),
                        title: "title".into(),
                        body: None,
                        state: None,
                        author: None,
                        url: None,
                        labels: None,
                        created_at: None,
                        updated_at: None,
                    },
                },
            };
            let err = execute_request(
                "https://unroutable.invalid",
                &resource,
                &ResolvedAuth::None,
                &HashMap::new(),
            )
            .unwrap_err();
            assert!(err.contains("connectors are read-only"), "{method}: {err}");
        }
    }

    #[test]
    fn build_url_with_api_key_query() {
        let resource = ResourceConfig {
            method: "GET".into(),
            path: "/data".into(),
            query_params: HashMap::new(),
            headers: HashMap::new(),
            response: super::super::schema::ResponseConfig {
                root: None,
                mapping: super::super::schema::FieldMapping {
                    id: "id".into(),
                    title: "name".into(),
                    body: None,
                    state: None,
                    author: None,
                    url: None,
                    labels: None,
                    created_at: None,
                    updated_at: None,
                },
            },
        };
        let auth = ResolvedAuth::ApiKeyQuery {
            param: "api_key".into(),
            value: "secret123".into(),
        };
        let url = build_url("https://api.example.com", &resource, &HashMap::new(), &auth);
        assert!(url.contains("api_key=secret123"));
    }

    #[test]
    fn resolved_auth_none_always_available() {
        assert!(ResolvedAuth::is_available(&AuthConfig::None));
    }

    #[test]
    fn resolved_auth_bearer_unavailable_without_env() {
        let auth = AuthConfig::Bearer {
            token_env: "LEAN_CTX_TEST_NONEXISTENT_TOKEN_12345".into(),
        };
        assert!(!ResolvedAuth::is_available(&auth));
    }
}