Skip to content

The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.

16.9 KB
Raw Blame
//! Named HTTP credentials for `http_request` flow nodes.
//!
//! A flow's `http_request` node can carry a `connection_ref` of the shape
//! `"http_cred:<name>"`. This module is the host-side store those names resolve
//! against: each record is an **injection template** (bearer token, HTTP basic
//! user:pass, or a raw custom header) whose secret material is encrypted at
//! rest with the same [`SecretStore`](crate::security::secret_storage::SecretStore)
//! (ChaCha20-Poly1305) the auth-profile store uses.
//!
//! **Security contract:** the secret value NEVER leaves this module except as
//! the header it is injected into, server-side, inside
//! `flows::caps_host::OpenHumanHttp::request`. It is never returned to the UI,
//! handed to the flow engine/graph, or logged. List/summary shapes carry only
//! the name + scheme + non-secret template fields ([`HttpCredentialSummary`]).

use std::collections::BTreeMap;
use std::fs;
use std::path::{Path, PathBuf};

use anyhow::{Context, Result};
use base64::engine::Engine as _;
use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};

use crate::config::Config;
use crate::security::secret_storage::SecretStore;

pub(crate) const STORE_FILENAME: &str = "http-credentials.json";
/// The HTTP credentials file a store over `state_dir` keeps.
pub(crate) fn store_file(state_dir: &Path) -> PathBuf {
    state_dir.join(STORE_FILENAME)
}
const CURRENT_SCHEMA_VERSION: u32 = 1;

/// How a credential is presented on the outbound request.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum HttpCredentialScheme {
    /// `Authorization: Bearer <secret>`.
    Bearer,
    /// `Authorization: Basic base64(<username>:<secret>)`.
    Basic,
    /// A raw custom header: `<header_name>: <secret>` (e.g. `X-API-Key`).
    Header,
}

impl HttpCredentialScheme {
    pub fn as_str(self) -> &'static str {
        match self {
            HttpCredentialScheme::Bearer => "bearer",
            HttpCredentialScheme::Basic => "basic",
            HttpCredentialScheme::Header => "header",
        }
    }
}

/// A resolved HTTP credential, secret in the clear in memory. Produced only by
/// [`HttpCredentialsStore::get`] and consumed only by the server-side injector.
#[derive(Debug, Clone)]
pub struct HttpCredential {
    pub name: String,
    pub scheme: HttpCredentialScheme,
    /// Header name for the [`HttpCredentialScheme::Header`] scheme (e.g.
    /// `X-API-Key`). Ignored for bearer/basic.
    pub header_name: Option<String>,
    /// Username for the [`HttpCredentialScheme::Basic`] scheme. Ignored
    /// otherwise. Not itself a secret, but stored alongside the secret.
    pub username: Option<String>,
    /// The secret material: bearer token, basic password, or raw header value.
    pub secret: String,
    pub created_at: DateTime<Utc>,
    pub updated_at: DateTime<Utc>,
}

impl HttpCredential {
    pub fn bearer(name: impl Into<String>, token: impl Into<String>) -> Self {
        let now = Utc::now();
        Self {
            name: name.into(),
            scheme: HttpCredentialScheme::Bearer,
            header_name: None,
            username: None,
            secret: token.into(),
            created_at: now,
            updated_at: now,
        }
    }

    pub fn basic(
        name: impl Into<String>,
        username: impl Into<String>,
        password: impl Into<String>,
    ) -> Self {
        let now = Utc::now();
        Self {
            name: name.into(),
            scheme: HttpCredentialScheme::Basic,
            header_name: None,
            username: Some(username.into()),
            secret: password.into(),
            created_at: now,
            updated_at: now,
        }
    }

    pub fn header(
        name: impl Into<String>,
        header_name: impl Into<String>,
        value: impl Into<String>,
    ) -> Self {
        let now = Utc::now();
        Self {
            name: name.into(),
            scheme: HttpCredentialScheme::Header,
            header_name: Some(header_name.into()),
            username: None,
            secret: value.into(),
            created_at: now,
            updated_at: now,
        }
    }

    /// The `(header_name, header_value)` pair to inject onto the outbound
    /// request. **The returned value contains the secret** — callers must merge
    /// it into the request server-side and must never log or echo it.
    pub fn to_header(&self) -> Result<(String, String)> {
        match self.scheme {
            HttpCredentialScheme::Bearer => {
                anyhow::ensure!(
                    !self.secret.trim().is_empty(),
                    "http_cred '{}': bearer token is empty",
                    self.name
                );
                Ok((
                    "Authorization".to_string(),
                    format!("Bearer {}", self.secret),
                ))
            }
            HttpCredentialScheme::Basic => {
                let username = self.username.as_deref().unwrap_or_default();
                let encoded = base64::engine::general_purpose::STANDARD
                    .encode(format!("{username}:{}", self.secret));
                Ok(("Authorization".to_string(), format!("Basic {encoded}")))
            }
            HttpCredentialScheme::Header => {
                let header_name = self
                    .header_name
                    .as_deref()
                    .map(str::trim)
                    .filter(|h| !h.is_empty())
                    .with_context(|| {
                        format!(
                            "http_cred '{}': header scheme requires a non-empty header_name",
                            self.name
                        )
                    })?;
                anyhow::ensure!(
                    !self.secret.trim().is_empty(),
                    "http_cred '{}': header value is empty",
                    self.name
                );
                Ok((header_name.to_string(), self.secret.clone()))
            }
        }
    }
}

/// Secret-free description of a stored credential — safe to return to the UI /
/// list surfaces (e.g. a future `flows_list_connections`).
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
pub struct HttpCredentialSummary {
    pub name: String,
    pub scheme: String,
    pub header_name: Option<String>,
    pub username: Option<String>,
    pub updated_at: String,
}

/// On-disk record. `secret` is stored as `enc2:<hex>` ciphertext (or plaintext
/// when `secrets.encrypt = false`, matching the auth-profile store's behavior).
#[derive(Debug, Clone, Serialize, Deserialize)]
struct PersistedHttpCredential {
    scheme: String,
    #[serde(default)]
    header_name: Option<String>,
    #[serde(default)]
    username: Option<String>,
    /// Encrypted secret material.
    secret: String,
    created_at: String,
    updated_at: String,
}

/// Whether `bytes` parse as the persisted HTTP-credentials document.
pub(crate) fn is_persisted_document(bytes: &[u8]) -> bool {
    serde_json::from_slice::<PersistedHttpCredentials>(bytes).is_ok()
}

#[derive(Debug, Clone, Serialize, Deserialize)]
struct PersistedHttpCredentials {
    schema_version: u32,
    updated_at: String,
    credentials: BTreeMap<String, PersistedHttpCredential>,
}

impl Default for PersistedHttpCredentials {
    fn default() -> Self {
        Self {
            schema_version: CURRENT_SCHEMA_VERSION,
            updated_at: Utc::now().to_rfc3339(),
            credentials: BTreeMap::new(),
        }
    }
}

/// Encrypted-at-rest store of named HTTP credentials.
#[derive(Debug, Clone)]
pub struct HttpCredentialsStore {
    path: PathBuf,
    secret_store: SecretStore,
}

impl HttpCredentialsStore {
    pub fn from_config(config: &Config) -> Self {
        let state_dir = super::state_dir_from_config(config);
        Self::new(&state_dir, config.secrets.encrypt)
    }

    pub fn new(state_dir: &Path, encrypt_secrets: bool) -> Self {
        Self {
            path: store_file(state_dir),
            secret_store: SecretStore::new(state_dir, encrypt_secrets),
        }
    }

    /// Normalize a credential name into the stable storage key. Names are
    /// case-insensitive and trimmed so `http_cred:Stripe ` and `stripe` resolve
    /// to the same record.
    fn normalize_name(name: &str) -> String {
        name.trim().to_ascii_lowercase()
    }

    /// List all stored credentials as secret-free summaries.
    pub fn list(&self) -> Result<Vec<HttpCredentialSummary>> {
        let persisted = self.read_persisted()?;
        Ok(persisted
            .credentials
            .into_iter()
            .map(|(name, rec)| HttpCredentialSummary {
                name,
                scheme: rec.scheme,
                header_name: rec.header_name,
                username: rec.username,
                updated_at: rec.updated_at,
            })
            .collect())
    }

    /// Resolve a credential name to its secret-bearing record, decrypting the
    /// secret. Returns `Ok(None)` when no such credential exists.
    pub fn get(&self, name: &str) -> Result<Option<HttpCredential>> {
        let key = Self::normalize_name(name);
        let persisted = self.read_persisted()?;
        let Some(rec) = persisted.credentials.get(&key) else {
            log::debug!(target: "credentials", "[credentials] http_cred get miss name={key}");
            return Ok(None);
        };

        let scheme = parse_scheme(&rec.scheme).with_context(|| {
            format!("http_cred '{key}' has unrecognized scheme {:?}", rec.scheme)
        })?;
        let secret = self
            .secret_store
            .decrypt(&rec.secret)
            .with_context(|| format!("failed to decrypt http_cred '{key}' secret"))?;

        log::debug!(
            target: "credentials",
            "[credentials] http_cred get hit name={key} scheme={}",
            scheme.as_str()
        );
        Ok(Some(HttpCredential {
            name: key,
            scheme,
            header_name: rec.header_name.clone(),
            username: rec.username.clone(),
            secret,
            created_at: parse_dt(&rec.created_at),
            updated_at: parse_dt(&rec.updated_at),
        }))
    }

    /// Insert or replace a credential, encrypting its secret at rest.
    pub fn upsert(&self, cred: &HttpCredential) -> Result<()> {
        let key = Self::normalize_name(&cred.name);
        anyhow::ensure!(!key.is_empty(), "http_cred name cannot be empty");

        let mut persisted = self.read_persisted()?;
        let encrypted = self
            .secret_store
            .encrypt(&cred.secret)
            .context("failed to encrypt http_cred secret")?;

        let created_at = persisted
            .credentials
            .get(&key)
            .map(|r| r.created_at.clone())
            .unwrap_or_else(|| cred.created_at.to_rfc3339());

        persisted.credentials.insert(
            key.clone(),
            PersistedHttpCredential {
                scheme: cred.scheme.as_str().to_string(),
                header_name: cred.header_name.clone(),
                username: cred.username.clone(),
                secret: encrypted,
                created_at,
                updated_at: Utc::now().to_rfc3339(),
            },
        );
        persisted.updated_at = Utc::now().to_rfc3339();
        self.write_persisted(&persisted)?;
        log::info!(
            target: "credentials",
            "[credentials] http_cred upserted name={key} scheme={} (secret redacted)",
            cred.scheme.as_str()
        );
        Ok(())
    }

    /// Remove a credential by name. Returns whether a record was removed.
    pub fn remove(&self, name: &str) -> Result<bool> {
        let key = Self::normalize_name(name);
        let mut persisted = self.read_persisted()?;
        let removed = persisted.credentials.remove(&key).is_some();
        if removed {
            persisted.updated_at = Utc::now().to_rfc3339();
            self.write_persisted(&persisted)?;
            log::info!(target: "credentials", "[credentials] http_cred removed name={key}");
        }
        Ok(removed)
    }

    fn read_persisted(&self) -> Result<PersistedHttpCredentials> {
        if let Some(secrets) = crate::storage::secrets::current()? {
            return match crate::storage::secrets::get_blocking(&secrets, STORAGE_SECRET_NAME)? {
                Some(bytes) => serde_json::from_slice(&bytes)
                    .context("http-credentials record on the storage backend is not valid JSON"),
                None => {
                    // First use of the backend: adopt the on-disk store so
                    // existing credentials stay visible and the next upsert
                    // cannot replace them. The file is left in place.
                    let legacy = self.read_file()?;
                    if self.path.exists() && !legacy.credentials.is_empty() {
                        let json = serde_json::to_vec(&legacy)
                            .context("failed to serialize migrated http-credentials store")?;
                        // A failed adoption keeps the legacy credentials
                        // readable; the next read retries it.
                        match crate::storage::secrets::set_blocking(
                            &secrets,
                            STORAGE_SECRET_NAME,
                            &json,
                        ) {
                            Ok(()) => log::info!(
                                target: "credentials",
                                "[credentials] migrated http-credentials file to storage secret"
                            ),
                            Err(_) => log::warn!(
                                target: "credentials",
                                "[credentials] http-credentials migration to storage failed; will retry"
                            ),
                        }
                    }
                    Ok(legacy)
                }
            };
        }
        self.read_file()
    }

    /// Reads the on-disk `http-credentials.json` store (empty when absent).
    fn read_file(&self) -> Result<PersistedHttpCredentials> {
        if !self.path.exists() {
            return Ok(PersistedHttpCredentials::default());
        }
        let bytes = fs::read(&self.path).with_context(|| {
            format!(
                "failed to read http-credentials store at {}",
                self.path.display()
            )
        })?;
        if bytes.is_empty() {
            return Ok(PersistedHttpCredentials::default());
        }
        serde_json::from_slice(&bytes).with_context(|| {
            format!(
                "http-credentials store at {} is not valid JSON",
                self.path.display()
            )
        })
    }

    fn write_persisted(&self, persisted: &PersistedHttpCredentials) -> Result<()> {
        if let Some(secrets) = crate::storage::secrets::current()? {
            let json = serde_json::to_vec(persisted)
                .context("failed to serialize http-credentials store")?;
            crate::storage::secrets::set_blocking(&secrets, STORAGE_SECRET_NAME, &json)?;
            return Ok(());
        }
        if let Some(parent) = self.path.parent() {
            fs::create_dir_all(parent).with_context(|| {
                format!(
                    "failed to create http-credentials dir at {}",
                    parent.display()
                )
            })?;
        }
        let json = serde_json::to_vec_pretty(persisted)
            .context("failed to serialize http-credentials store")?;
        // Atomic publish: write to a unique tmp then rename over the store so a
        // concurrent reader never observes a torn file.
        let tmp_name = format!(
            "{STORE_FILENAME}.tmp.{}.{}",
            std::process::id(),
            Utc::now().timestamp_nanos_opt().unwrap_or_default()
        );
        let tmp_path = self.path.with_file_name(tmp_name);
        fs::write(&tmp_path, &json)
            .with_context(|| format!("failed to write {}", tmp_path.display()))?;
        if let Err(e) = fs::rename(&tmp_path, &self.path) {
            let _ = fs::remove_file(&tmp_path);
            return Err(e).with_context(|| {
                format!(
                    "failed to replace http-credentials store at {}",
                    self.path.display()
                )
            });
        }
        Ok(())
    }
}

/// The secret the store lives in on a storage backend
/// ([`crate::storage::secrets`]): the same JSON as the file, encrypted as one
/// secret in the acting agent's scope.
pub(crate) const STORAGE_SECRET_NAME: &str = "file:http-credentials.json";

fn parse_scheme(raw: &str) -> Option<HttpCredentialScheme> {
    match raw.trim().to_ascii_lowercase().as_str() {
        "bearer" => Some(HttpCredentialScheme::Bearer),
        "basic" => Some(HttpCredentialScheme::Basic),
        "header" => Some(HttpCredentialScheme::Header),
        _ => None,
    }
}

fn parse_dt(raw: &str) -> DateTime<Utc> {
    DateTime::parse_from_rfc3339(raw)
        .map(|dt| dt.with_timezone(&Utc))
        .unwrap_or_else(|_| Utc::now())
}

#[cfg(test)]
#[path = "http_creds_tests.rs"]
mod tests;