//! The ACP provider agreement: where an agent's inference-provider API key
//! lives in the store, and what the object at that path holds.
//!
//! The operator writes it by hand; the agent reads it under its own
//! certificate when it spawns its ACP agent (`hive_runtime`).

use serde::{Deserialize, Serialize};

use crate::{
    Error,
    path::{Kind, principal_prefix},
};

/// The path holding `agent`'s ACP provider API key.
///
/// A flat leaf under the agent's prefix, like [`crate::forge::agent_token_path`],
/// so the agent's own read stanza ([`crate::policy::render_agent`]) already
/// covers it.
///
/// # Errors
/// [`Error::PathSegment`] when `agent` contains anything but `[A-Za-z0-9_-]`,
/// which is what keeps one agent's name from addressing another agent's secret.
pub fn provider_key_path(agent: &str) -> Result<String, Error> {
    let prefix = principal_prefix(Kind::Agent, agent)?;
    Ok(format!("{prefix}/acp-provider"))
}

/// What an agent's ACP provider path holds.
///
/// No `Debug`: `api_key` is a live provider credential.
#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ProviderKey {
    /// The key itself. The operator enters this field name in the store's UI.
    pub api_key: String,
}

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

    #[test]
    fn the_key_lands_under_the_agent_prefix() {
        // Spelled out: the operator types this path into the store's UI.
        assert_eq!(
            provider_key_path("atlas").expect("a plain name is legal"),
            "swarm/agents/atlas/acp-provider"
        );
    }

    #[test]
    fn a_traversal_in_the_agent_name_is_refused() {
        for bad in ["../argus", "a/b", "a.b", ""] {
            let e = provider_key_path(bad).expect_err("a traversal is not legal");
            assert!(matches!(e, Error::PathSegment { kind: "agent", .. }), "{e}");
        }
    }

    #[test]
    fn the_stored_field_is_api_key() {
        let stored: ProviderKey =
            serde_json::from_str(r#"{"api_key":"k"}"#).expect("the documented shape decodes");
        assert_eq!(stored.api_key, "k");
    }
}